feat: implement issue #375 — Compliance audit — 2026-05-29

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,213 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# SOURCE OF TRUTH: petry-projects/.github/standards/workflows/copilot-setup-steps.yml
+# Standard:        petry-projects/.github/standards/ci-standards.md#11-copilot-cloud-agent-setup
+#
+# ADOPTING THIS WORKFLOW:
+#   1. Copy this file to .github/workflows/copilot-setup-steps.yml in your repo.
+#   2. Keep every REQUIRED section — do NOT remove the checkout or verify steps.
+#   3. Uncomment and adapt the stack blocks that match your repo's tech stack.
+#   4. Delete (not just comment out) stacks that do not apply after initial setup.
+#   5. Merge to the default branch — the workflow only triggers from the default branch.
+#   6. Run manually from Actions → "Copilot Setup Steps" → "Run workflow" to verify.
+#
+# WHAT THIS FILE DOES:
+#   Bootstraps Copilot cloud agent's ephemeral environment BEFORE the agent starts
+#   working on your repo. Pre-installing dependencies deterministically:
+#     • Speeds up every agent session (no trial-and-error dependency discovery)
+#     • Makes private/internal packages available (impossible for the agent alone)
+#     • Ensures exact tool versions that match your CI pipeline
+#   Without this file the agent installs dependencies itself — slower, non-deterministic,
+#   and unreliable for repos with private packages or complex build graphs.
+#
+# SEE ALSO:
+#   AGENTS.md                         — authoritative development standards for this repo
+#   .github/copilot-instructions.md   — always-on Copilot instructions (summary of AGENTS.md)
+#   .github/instructions/             — path-scoped instruction files per language
+#
+# CONSTRAINTS (enforced by GitHub, documented at docs.github.com):
+#   • Job MUST be named `copilot-setup-steps` to be recognized by Copilot cloud agent
+#   • timeout-minutes maximum: 59 (hard limit)
+#   • Customizable fields: steps, permissions, runs-on, services, snapshot, timeout-minutes
+#   • All other job-level settings are silently ignored by GitHub
+#   • fetch-depth on checkout is always overridden by the agent — do not rely on it here
+#   • This file MUST be present on the default branch to take effect
+#
+# AGENTS — READ BEFORE EDITING:
+#   This file is a PER-REPO TEMPLATE (Tier 2). There is no central reusable workflow
+#   because setup steps are inherently tech-stack-specific. Each repo owns its copy.
+#   Stay within the patterns documented in ci-standards.md §11. Do not change:
+#     • the job name (`copilot-setup-steps`)
+#     • the fork guard condition
+#     • the trigger events
+#     • the verify-environment step
+#   For changes to the org-wide pattern, open a PR against this file in
+#   petry-projects/.github and propagate to the fleet.
+# ─────────────────────────────────────────────────────────────────────────────
+
+name: "Copilot Setup Steps"
+
+# Run automatically when this file changes (validates the setup steps work),
+# and allow manual runs from the Actions tab at any time.
+# NOT a standard CI trigger — this file should NOT be added to push: branches: [main].
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+# Defense-in-depth: reset top-level permissions; set exact grants per-job.
+# Pattern from envoyproxy/envoy and the org Permissions Policy (ci-standards.md).
+permissions: {}
+
+jobs:
+  # ── REQUIRED: Job name must be exactly `copilot-setup-steps` ────────────────
+  copilot-setup-steps:
+    # Skip on fork-origin pull requests — forks cannot access org secrets required for private packages.
+    # `github.event.repository.fork` reflects the base repo (always false for org repos); the
+    # correct guard is on the PR head repo so that external fork PRs are skipped while direct
+    # pushes and manual runs always proceed.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false
+
+    runs-on: ubuntu-latest
+
+    # Adjust upward only if your build or download steps genuinely need more time.
+    # Hard maximum enforced by GitHub is 59 minutes.
+    timeout-minutes: 30
+
+    # Minimum permissions — Copilot receives its own separate token for its operations.
+    # Add `packages: read` if pulling from GitHub Packages (GHCR or npm private registry).
+    permissions:
+      contents: read
+
+    steps:
+      # ── REQUIRED ──────────────────────────────────────────────────────────────
+      # Checkout the repository so dependency manifests (package.json, go.mod, etc.)
+      # are available for the install steps below.
+      # Note: fetch-depth is always overridden by the agent — set it here only if
+      # your install steps need history (rare).
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      # ── NODE.JS / NPM ──────────────────────────────────────────────────────────
+      # Uncomment for repos using npm (TypeScript, React, Electron, Google Apps Script).
+      # Use node-version-file: .nvmrc if the repo maintains a .nvmrc; otherwise pin
+      # the version to match the CI pipeline and the org standard (Node.js 22 LTS).
+      #
+      # - name: Set up Node.js
+      #   uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      #   with:
+      #     node-version: "22"           # or: node-version-file: .nvmrc
+      #     cache: "npm"
+      #
+      # - name: Install Node.js dependencies
+      #   run: npm ci --ignore-scripts
+
+      # ── NODE.JS / PNPM ────────────────────────────────────────────────────────
+      # Uncomment for repos using pnpm (e.g., broodly TypeScript layer).
+      # pnpm must be set up before setup-node when using pnpm cache.
+      #
+      # - name: Set up pnpm
+      #   uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4
+      #
+      # - name: Set up Node.js (pnpm)
+      #   uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      #   with:
+      #     node-version: "22"
+      #     cache: "pnpm"
+      #
+      # - name: Install Node.js dependencies (pnpm)
+      #   run: pnpm install --frozen-lockfile --ignore-scripts
+
+      # ── GO ────────────────────────────────────────────────────────────────────
+      # Uncomment for repos with Go code (e.g., broodly API layer).
+      # Pin go-version to match go.mod to avoid silent toolchain upgrades.
+      # For monorepos, set cache-dependency-path to the correct go.sum path.
+      #
+      # - name: Set up Go
+      #   uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+      #   with:
+      #     go-version: "stable"         # or: go-version-file: go.mod
+      #     cache-dependency-path: go.sum
+      #
+      # - name: Download Go dependencies
+      #   run: go mod download
+
+      # ── PYTHON ────────────────────────────────────────────────────────────────
+      # Uncomment for repos with Python code.
+      # Pin python-version to a specific minor version for reproducibility.
+      #
+      # - name: Set up Python
+      #   uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+      #   with:
+      #     python-version: "3.12"       # pin to match your runtime
+      #     cache: "pip"
+      #
+      # - name: Install Python dependencies
+      #   run: pip install -r requirements.txt
+
+      # ── OPTIONAL: Additional build artifacts ──────────────────────────────────
+      # If the agent needs pre-built artifacts to run tests (e.g., a Next.js build,
+      # a compiled binary, or generated types), add a build step here.
+      # Keep it minimal — the agent will run its own build steps when needed.
+      #
+      # - name: Build
+      #   run: npm run build
+
+      # ── OPTIONAL: gh-aw MCP extension ────────────────────────────────────────
+      # Installs GitHub Advanced Workflows (gh-aw), a GitHub-developed MCP server
+      # that gives Copilot cloud agent extended GitHub API access (web search,
+      # enhanced PR tools, and more). Used by github/copilot-sdk, TryGhost/Ghost,
+      # and github/awesome-copilot. Recommended for any repo doing heavy GitHub
+      # platform work (issue triage, PR automation, release management).
+      # Pin the version to a specific SHA for supply-chain safety.
+      #
+      # - name: Install gh-aw MCP extension
+      #   uses: github/gh-aw/actions/setup-cli@ce1794953e0ec42adc41b6fca05e02ab49ee21c3
+      #   with:
+      #     version: v0.49.3
+
+      # ── REQUIRED ──────────────────────────────────────────────────────────────
+      # Environment verification — always runs last. Fails loud if something is
+      # missing so the problem is caught here rather than mid-agent-session.
+      # Also surfaces the agent instruction files so session logs confirm they
+      # were found before the agent began working.
+      - name: Verify environment
+        run: |
+          echo "=== petry-projects Copilot cloud agent environment ==="
+          echo "Repository : ${{ github.repository }}"
+          echo "Ref        : ${{ github.ref }}"
+          echo "Runner     : ${{ runner.os }} / ${{ runner.arch }}"
+          echo ""
+          echo "--- Installed tool versions ---"
+          git   --version
+          gh    --version 2>/dev/null | head -1 || echo "gh: not installed"
+          node  --version 2>/dev/null            || echo "node: not installed"
+          npm   --version 2>/dev/null            || echo "npm: not installed"
+          go    version   2>/dev/null            || echo "go: not installed"
+          python --version 2>/dev/null           || echo "python: not installed"
+          echo ""
+          echo "--- Agent instruction files ---"
+          if [ -f "AGENTS.md" ]; then
+            echo "✅ AGENTS.md ($(wc -l < AGENTS.md) lines)"
+          else
+            echo "❌ AGENTS.md — MISSING. Add this file per agent-standards.md."
+            exit 1
+          fi
+          if [ -f ".github/copilot-instructions.md" ]; then
+            echo "✅ .github/copilot-instructions.md"
+          else
+            echo "ℹ️  .github/copilot-instructions.md — not present (optional but recommended)"
+          fi
+          # Count path-scoped instruction files (guard against missing directory)
+          INSTR_COUNT=0
+          if [ -d ".github/instructions" ]; then
+            INSTR_COUNT=$(find .github/instructions -name "*.instructions.md" | wc -l)
+          fi
+          echo "ℹ️  .github/instructions/: ${INSTR_COUNT} file(s)"
+          echo ""
+          echo "✅ Setup complete — Copilot cloud agent is ready to work"

.gitignore

@@ -385,8 +385,8 @@ private.yml
 # be committed accidentally.
 .claude/worktrees/
 .worktrees/
+.dev-lead/
 
 # ============================================================================
 # End of petry-projects secrets baseline
 # ============================================================================
-.dev-lead/

standards/workflows/copilot-setup-steps.yml

@@ -90,6 +90,8 @@ jobs:
       # your install steps need history (rare).
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
 
       # ── NODE.JS / NPM ──────────────────────────────────────────────────────────
       # Uncomment for repos using npm (TypeScript, React, Electron, Google Apps Script).