diff --git a/.changeset/dedicated-review-app.md b/.changeset/dedicated-review-app.md new file mode 100644 index 000000000..30e809777 --- /dev/null +++ b/.changeset/dedicated-review-app.md @@ -0,0 +1,6 @@ +--- +"@bradygaster/squad-cli": patch +"@bradygaster/squad-sdk": patch +--- + +Require a dedicated, branch-restricted GitHub App identity for authoritative Squad review checks. diff --git a/.github/agents.md b/.github/agents.md index e08e50acf..44593c3ab 100644 --- a/.github/agents.md +++ b/.github/agents.md @@ -33,6 +33,14 @@ GitHub Agentic Workflows (`gh-aw`) are composable AI workflows triggered by slas > Stop at the bootstrap PR; the human merges it. > `/squad` slash commands become active only after that merge reaches > the repository's default branch. +> The installation PR is a manual trust boundary: its PR-controlled workflow +> cannot mint a trusted Squad verdict. After merge, require the automatically +> opened Cast PR to pass the exact-head `Squad Review / review` attestation from +> the base-controlled `pull_request_target` authority before treating bootstrap +> or lifecycle automation as trusted. That check must be published by a +> dedicated GitHub App token minted only inside the exact-default-branch +> `squad-review-authority` environment. Missing or misconfigured reviewer +> credentials fail closed; the workflow never falls back to `github.token`. The quick start installs this workflow set: diff --git a/.github/workflows/squad-ci.yml b/.github/workflows/squad-ci.yml index 25521afb9..a26578d1b 100644 --- a/.github/workflows/squad-ci.yml +++ b/.github/workflows/squad-ci.yml @@ -173,7 +173,7 @@ jobs: # than skipping — a skipped gate is indistinguishable from no gate. This # includes the shell input security contract gate (#1834) and the compile # contract (#1732). - run: gh extension install --pin v0.87.10 github/gh-aw + run: gh extension install --pin v0.89.21 github/gh-aw env: GH_TOKEN: ${{ github.token }} - name: Build @@ -778,7 +778,12 @@ jobs: git -C "$CONSUMER_DIR" remote add origin https://github.com/example/squad-consumer.git ( cd "$CONSUMER_DIR" - gh aw add "$GITHUB_WORKSPACE/workflows" + mkdir -p .github/workflows + for workflow in squad squad-implement-worker squad-review squad-deps-worker squad-retro squad-improvement-worker squad-bootstrap squad-command-router; do + cp "$GITHUB_WORKSPACE/workflows/package/${workflow}.md" \ + ".github/workflows/${workflow}.md" + done + gh aw add --force "$GITHUB_WORKSPACE/workflows" node .github/workflows/shared/squad-install-verifier.mjs \ --write-local-test-ownership \ --source-revision "$SQUAD_SOURCE_REVISION" diff --git a/.squad-templates/skills/gh-aw-enlistment/SKILL.md b/.squad-templates/skills/gh-aw-enlistment/SKILL.md index bd6c10e53..9005f105e 100644 --- a/.squad-templates/skills/gh-aw-enlistment/SKILL.md +++ b/.squad-templates/skills/gh-aw-enlistment/SKILL.md @@ -182,17 +182,17 @@ uses a moving branch reference. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, + **`SQUAD_GITHUB_TOKEN`**, and **`SQUAD_REVIEW_APP_PRIVATE_KEY`** - Action: **`bradygaster/squad/.github/actions/squad-init`** -> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets -> the workflows *reference* so you can approve that surface — it is not asking you -> to supply them. Both secrets are optional, they need not exist, and neither is -> required to enlist a repository. Single-repo activation runs on the built-in -> `github.token`. Configure them only for cross-repo access or elevated -> permissions. Auth precedence: GitHub App token, then the PAT, then -> `github.token`. Never block an enlistment waiting for a credential. +> **Compilation approval is not credential provisioning.** `gh aw add` lists +> referenced names so you can approve the surface. `SQUAD_GITHUB_APP_PRIVATE_KEY` +> and `SQUAD_GITHUB_TOKEN` remain optional activation credentials. +> `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: trusted check publication requires +> it in the exact-default-branch `squad-review-authority` environment. Never put +> reviewer credentials at repository scope and never fall back to `github.token`. If — and only if — the report contains exactly those documented entries, complete the one-time approval: @@ -284,7 +284,27 @@ gh pr checks --watch `main`. - Request Copilot review, address feedback, and wait for required checks. -### 9. Never auto-merge — and explain what comes next +### 9. Verify the external review-authority prerequisite when API access permits + +Before claiming trusted review is ready, query the repository environment. It +must be named `squad-review-authority`, use custom deployment branch policies, +allow exactly the captured `${default_branch}`, contain the environment secret +`SQUAD_REVIEW_APP_PRIVATE_KEY`, and define environment variables +`SQUAD_REVIEW_APP_ID`, `SQUAD_REVIEW_APP_SLUG`, and +`SQUAD_REVIEW_APP_OWNER`. The App ID/slug must differ from +`15368`/`github-actions`. All four reviewer-specific names must also be absent +from repository-level Actions secrets and variables; repository fallback does +not satisfy this gate. + +If the authenticated account cannot read environment configuration, or any +requirement is absent, report the exact external prerequisite and do not claim +the required check is trusted. The installation PR remains a human boundary; +after it merges, the Cast canary intentionally fails closed until an +administrator provisions the environment and reruns the base-controlled +review. Configure a ruleset only from the canary check's observed App +integration ID, never from user input or a guessed value. + +### 10. Never auto-merge — and explain what comes next - **Never** merge the bootstrap PR yourself. Merge happens **only** after human approval. @@ -346,8 +366,9 @@ gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT mer ### ✓ Correct: STOP on an undocumented safe-update entry ```text -gh aw add reports a third secret: `ACME_DEPLOY_KEY`. -→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) +gh aw add reports an additional secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, + SQUAD_REVIEW_APP_PRIVATE_KEY) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -381,7 +402,8 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path. - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, - `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything + `SQUAD_GITHUB_TOKEN`, `SQUAD_REVIEW_APP_PRIVATE_KEY`, and + `bradygaster/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain `gh aw compile --strict` (no `--approve`). diff --git a/docs/src/content/docs/guide/gh-aw.md b/docs/src/content/docs/guide/gh-aw.md index 56d5bbf60..0c9cfabe7 100644 --- a/docs/src/content/docs/guide/gh-aw.md +++ b/docs/src/content/docs/guide/gh-aw.md @@ -103,6 +103,23 @@ skill as one update unit. For an upgrade, resolve or select one reviewed commit and reinstall that same package as described in [Upgrading the workflows](#upgrading-the-workflows). +The bootstrap installation PR is an explicit human trust boundary. Because its +base branch does not yet contain the Squad review guard and manifest, no job, +check name, review comment, or workflow code introduced by that PR is accepted +as a trusted Squad verdict. The canonical workflow reports +`First-install manual boundary`, emits no `Squad-Review-Verdict:` record, and +requires a human to review the verifier/compile evidence before merging. + +After merge, the default-branch bootstrap workflow opens the draft Cast PR. +That PR is the activation canary: `Squad Review / review` must succeed using the +base-controlled `pull_request_target` workflow plus the guard and manifest +checked out from the Cast PR's exact base commit. The guard +also requires matching exact-head provenance in the PR body and a durable +GitHub Actions bot comment, so editable PR prose cannot rebind an old bootstrap +run to a changed branch head. Only after that base-controlled canary succeeds +should the Cast/bootstrap lifecycle be treated as trusted. Do not enable the +required check in a ruleset before this post-install canary has been observed. + Step 2 deliberately checks Issues before creating the bootstrap branch or installing any workflow. Squad commands are issue comments, and the merged bootstrap creates a research/proposals issue; without Issues, the installation @@ -281,17 +298,21 @@ source/lock pairs, and one coherent 40-character revision. On a clean repository, `gh aw add` reports these expected safe-update changes: -- Restricted secrets: `SQUAD_GITHUB_APP_PRIVATE_KEY` and `SQUAD_GITHUB_TOKEN` +- Restricted secrets: `SQUAD_GITHUB_APP_PRIVATE_KEY`, `SQUAD_GITHUB_TOKEN`, and + `SQUAD_REVIEW_APP_PRIVATE_KEY` - Action: `bradygaster/squad/.github/actions/squad-init` > **These are referenced names, not prerequisites.** `gh aw add` lists the secrets > the workflows *reference* so you can approve that surface — it is not asking you -> to supply them. Both secrets are optional, they need not exist, and you do not -> need to create either one to enlist a repository. Single-repo activation runs on -> the built-in `github.token`. Configure these only for cross-repo access or +> to supply them during compilation. `SQUAD_GITHUB_APP_PRIVATE_KEY` and +> `SQUAD_GITHUB_TOKEN` remain optional activation credentials; single-repo +> activation can use the built-in `github.token`. Configure those only for cross-repo access or > elevated permissions — see [enhanced permissions with a GitHub > App](#optional-enhanced-permissions-with-a-github-app) and [PAT -> fallback](#optional-pat-fallback). +> fallback](#optional-pat-fallback). `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: +> it belongs only in the branch-restricted `squad-review-authority` environment +> described below. Trusted required-check publication intentionally fails closed +> until that external prerequisite is provisioned. Review the report before approving it. If it contains only those documented entries, complete the first-install approval with: @@ -415,6 +436,47 @@ a Personal Access Token: **Auth precedence:** GitHub App token → `SQUAD_GITHUB_TOKEN` → `github.token`. +### Required: dedicated review authority App + +The required `Squad Review / review` check must not use `github.token`. +`github.token` checks are owned by the shared GitHub Actions App +(`id: 15368`, slug: `github-actions`), which is also available to ordinary +same-repository PR workflows. The reviewer instead mints a short-lived token +for a dedicated GitHub App inside a protected environment and has no fallback. + +Before expecting the post-install Cast canary to pass: + +1. Create a dedicated GitHub App with repository **Checks: read and write** and + read access to Actions, contents, metadata, and pull requests. Install it + only on the consumer repository. +2. Create the Actions environment **`squad-review-authority`**. +3. Configure a custom deployment branch policy containing exactly the + repository default branch. Do not allow wildcard, feature, release, tag, or + additional branch policies; a PR workflow must not be able to request this + environment from its own ref. +4. Store these reviewer-specific values in that environment, not as + repository-level Actions secrets or variables: + + | Setting | Type | Purpose | + |---------|------|---------| + | `SQUAD_REVIEW_APP_ID` | Variable | Dedicated App numeric ID; must not be `15368` | + | `SQUAD_REVIEW_APP_SLUG` | Variable | Dedicated App slug; must not be `github-actions` | + | `SQUAD_REVIEW_APP_OWNER` | Variable | Repository owner where the App is installed | + | `SQUAD_REVIEW_APP_PRIVATE_KEY` | Secret | Dedicated App private key | + +The publisher validates the configured ID and slug, mints an installation token +inside the environment, publishes with that token, and validates the App +identity returned by the Checks API. Missing environment protection, missing +credentials, token-mint failure, Actions App identity, or any ID/slug mismatch +fails closed. An ordinary `github.token` may create a same-named check owned by +the Actions App, but it cannot update the dedicated App's check and cannot +satisfy an integration-bound ruleset. + +Before rollout, verify the four reviewer-specific names are absent from +repository-level Actions secrets and variables. GitHub expression contexts can +otherwise fall back to a repository-scoped value with the same name. The hosted +controller treats that overlap as a hard configuration error. + --- ## Supported-path validation checklist @@ -426,12 +488,13 @@ Use this checklist for the initial bootstrap and after any workflow update: | Repository readiness | Confirm `.has_issues` is `true`; if it is `false`, enable it before installing workflows | GitHub Issues are available for `/squad` comments and the bootstrap research/proposals issue; insufficient administration permission stops the install before a bootstrap PR is created | | Install | Run the eight-workflow `gh aw add` command on a bootstrap branch | All eight `.md`/`.lock.yml` pairs exist, with shared imports, `.github/aw/`, installed skills, and `.gitattributes` included in the diff | | Compile | Review any first-install safe-update report, approve only the documented entries, then run `gh aw compile --strict` without approval | All eight workflows succeed, only documented warnings remain, and all sixteen source/lock files exist | -| Bootstrap review | Open the PR, request `@copilot`, wait for checks, and merge only after human approval | The default branch receives the complete generated install as one human-reviewable change | -| Automatic bootstrap | Merge the workflow-installation PR | The dedicated workflow creates one draft Cast PR and one linked research-proposals issue from the same validated payload | +| Bootstrap review | Open the installation PR, request `@copilot`, inspect verifier/compile evidence, and merge only after human approval | The run reports the explicit first-install manual boundary; no `Squad-Review-Verdict:` record or PR-controlled check is treated as trusted | +| Activation canary | Merge the workflow-installation PR and inspect the automatically opened draft Cast PR | `Squad Review / review` succeeds with reserved bootstrap roles only after loading the guard and manifest from the exact base commit and validating the default-branch bootstrap run | +| Automatic bootstrap | Continue only after the Cast PR activation canary succeeds | The dedicated workflow's draft Cast PR and linked research-proposals issue share the same validated base-controlled provenance | | Cast persistence | Review the Cast PR before merging | The PR contains `.squad/casting/policy.json`, `registry.json`, and `history.json`, plus the team, routing, charters, Copilot agent, and `meet-the-squad.md` | | Research backlog | Follow the proposal issue through research, triage, plan, and activate | The journey ends with assignable implementation issues; `/squad implement` is used only on those generated tasks | | Cast checks | Open the linked Cast PR and inspect its checks; if application CI is `action_required`, approve that workflow run and wait for it to finish | Copilot review and the repository's normal build, test, lint, and security checks complete before merge | -| Handoffs | Run `/squad implement` on a ready issue, then review its PR | The dispatcher starts the appropriate isolated worker; automatic PR review supplies the independent current-head verdict; manual `/squad review` is diagnostic | +| Handoffs | Run `/squad implement` on a ready issue, then review its PR | The dispatcher starts the appropriate isolated worker; automatic PR review supplies the independent current-head verdict; `/squad review` explains how to rerun that exact automatic check | | Rerun | Repeat the same command after a cancellation or uncertain result | Existing Cast and implementation PRs are detected instead of duplicated; an unchanged reviewed head is not reviewed twice | | Recovery | Fix the named failing activation step, then use **Re-run failed jobs**; for an interrupted command, rerun the identical `/squad` command | Activation uploads no partial state artifact, and command-specific idempotency resumes from GitHub's committed PR, issue, comment, and review state | @@ -480,7 +543,7 @@ wins: `/squad plan accept scope` is not treated as `/squad plan`. | Activation | `/squad plan activate` | Create GitHub issues from an accepted plan | Terminal step; creates real GitHub issues | | Activation | `/squad plan activate phase {N}` | Create GitHub issues for only Phase N | Use when accept didn't auto-activate | | Implementation | `/squad implement` | Implement an issue, or start the next ready wave of an epic | Dispatches an isolated implementation worker | -| Review | `/squad review` | Independently review the current pull request | Advisory `COMMENT` or `REQUEST_CHANGES`; human approval remains mandatory | +| Review | `/squad review` | Show how to rerun the current pull request's automatic independent review | Does not dispatch branch-selected code; human approval remains mandatory | | Retrospective | `/squad retro` | Run the shared retrospective immediately | Authorized manual run; weekly and evidence-driven wakeups use the same durable gate | | Governance | `/squad approve-improvement` | Request implementation of an exact retrospective proposal revision | Human write/maintain/admin permission, `Approved-Revision:` hash and exact `Approved-Path:` lines; dispatcher relays nested `issue_number` and `approval_comment_id`, never approval authority | | Governance | `/squad revoke-improvement` | Withdraw a prior `/squad approve-improvement` | Reserved, read-only command available to any actor; emits no output of any kind — the comment itself is the record that later runs re-check | @@ -1429,14 +1492,14 @@ The implementation worker performs an internal self-review before opening a PR: 5. **Protected-file guard** — changes to protected paths trigger a review request on the PR rather than a direct commit After the PR is opened, `squad-review` provides an independent review. -You can start it in either of these ways: - -- **Manual:** Comment `/squad review` on a same-repository pull request. The main - Squad router relays the pull request number, current head SHA, and manual - origin to the isolated reviewer workflow. -- **Automatic:** Every same-repository pull request triggers review on `opened`, - `reopened`, `ready_for_review` and `synchronize`. Fork pull requests are - refused. Only a PR-triggered run can publish the required check. +Every same-repository pull request triggers review on `opened`, `reopened`, +`ready_for_review` and `synchronize`; fork pull requests are refused. The +workflow runs as `pull_request_target` from immutable default-branch context, +sets `checkout: false`, and has no `workflow_dispatch` trigger. It never checks +out or executes pull request files, actions, scripts, guards, or manifests; the +agent reads the diff through GitHub APIs. Comment `/squad review` to receive +instructions for opening the existing base-controlled run and using GitHub's +**Re-run all jobs** action. The reviewer classifies provenance in this priority order: @@ -1470,9 +1533,11 @@ labels, and GitHub logins do not establish independent logical agent identity. This is auditable logical attribution, not proof of a separate account or model. Registry migration and legitimate attribution changes require human review. -The trusted guard reads attribution from the exact PR head commit, never the -agent's working tree. A `Squad-Review-Verdict:` JSON record binds repository, PR, -head SHA, both agent IDs, verdict, UTC timestamp, and workflow run/attempt. +The trusted guard reads attribution from the exact PR head commit through the +GitHub API, never by checking out or executing the PR. A +`Squad-Review-Verdict:` JSON record binds repository, PR, base SHA, head SHA, +immutable workflow SHA, both agent IDs, verdict, UTC timestamp, and the +`pull_request_target` workflow run/attempt. Exactly one current-head record is required. The legacy `Squad-Review-Head: ` marker remains human-readable but is not authorization. Per-PR concurrency cancels stale runs; both output and final gate re-fetch the @@ -1491,8 +1556,13 @@ exactly one pull request review. It returns: The trusted writer publishes these logical verdicts in a native `COMMENT` review: GitHub does not permit an account to approve or request changes on its -own PR. The separate status check enforces `REQUEST_CHANGES`; no additional bot -accounts or Apps are needed. +own PR. The native `Squad Review Authority / attest` job proves that the base-controlled +workflow executed. Its publisher creates `Squad Review / review` on the exact +PR head with a `squad-review-check/v1` attestation linked to that run. A +PR-controlled workflow may create advisory output with the same display name, +but it cannot satisfy the relay without the successful native authority job and +exact event/base/head/run/App binding. The status check enforces +`REQUEST_CHANGES`; no additional bot accounts or Apps are needed. The reviewer has no file-editing, issue-creation, pull-request-creation, remediation, merge, or `APPROVE` authority. Its verdict @@ -1506,31 +1576,45 @@ The lifecycle is: ``` The epic relay repeats the guard before running the agent and before processing -any outputs. It requires a clearing verdict and the successful required job -from that PR review run, completed **before merge**, for the merged PR's -**head SHA**, not the merge commit. Bypassing a missing Squad review at merge +any outputs. It requires a clearing verdict, the successful native authority +job from the base-controlled run, and the exact-head published check completed +**before merge** for the merged PR's **head SHA**, not the merge commit. +Bypassing a missing Squad review at merge cannot silently advance the epic. Missing evidence stops the run with an explicit error; it never dispatches the next wave. ### Required check rollout (repository administrator) The stable literal check name is **`Squad Review / review`**. -`inlined-imports: true` makes the compiled job directly addressable. -Manual `/squad review` runs use `Squad Review / manual`; they cannot satisfy -the PR check or clear relay evidence. +There is no manual reviewer run. `/squad review` only explains how to rerun the +existing automatic `pull_request_target` run, and only that exact base-controlled +run ID, attempt, native authority job, and exact-head attestation can satisfy +its emitted verdict and check. Brady (or the consumer repository administrator) must install/merge the complete -generated bundle and observe a successful PR-triggered check before changing -rulesets. Record its actual check name and GitHub App ID from the check-runs -API. Enable the required context with that observed App ID on `dev` **only after -advisory soak** has met the evidence gate in #1734; promote to `main` after the -agreed soak. This change does not modify repository rulesets and does not claim -live soak evidence. Keep native human approving-review requirements enabled -independently, with stale approvals dismissed. The bot's `COMMENT` is not a -human approval. Do not use an unobserved guessed App ID or require the manual job. +generated bundle through the explicit human installation boundary, then observe +a successful base-controlled `pull_request_target` check on the post-install +draft Cast PR before +changing rulesets. The installation PR itself is not evidence: its workflow and +check name are controlled by that PR. The Cast canary remains intentionally red +until the [dedicated review authority App](#required-dedicated-review-authority-app) +and exact-default-branch environment policy are provisioned. Record the +activation canary's actual +check name, external ID, details URL, attestation summary, and GitHub App ID +and slug from the check-runs API. The attestation's `publisher_app_id` and +`publisher_app_slug` must equal the check's returned App identity and must not +be `15368`/`github-actions`. Enable the required context with that observed App ID +on `dev` **only after advisory soak** has met the +evidence gate in #1734; promote to `main` after the agreed soak. This change +does not modify repository rulesets and does not claim live soak evidence. Keep +native human approving-review requirements enabled independently, with stale +approvals dismissed. The bot's `COMMENT` is not a human approval. Do not use an +unobserved guessed App ID, a user-supplied integration ID, an Actions-owned +same-name check, or the manual job. Because rulesets apply to all PRs, existing human/Copilot PRs must add committed -attribution before enabling the requirement. Fork review is not supported by -this workflow; do not relax it with `pull_request_target`. +attribution before enabling the requirement. Fork review remains unsupported; +the workflow rejects foreign head repositories even though its base-controlled +trigger is `pull_request_target`. ### Auditable human override @@ -1543,7 +1627,8 @@ native review ID, and a meaningful reason): Squad-Review-Override: {"schema":"squad-review-override/v1","repository":"owner/repo","pull_request":456,"head_sha":"0123456789abcdef0123456789abcdef01234567","review_id":789,"reason":"False positive: explanation and evidence for accepting this risk."} ``` -Then rerun the original **PR-triggered workflow**, not the manual dispatcher. +Then rerun the original base-controlled **`pull_request_target` workflow**, not +the manual dispatcher. The gate checks the human account type and live administrator permission, record shape, exact SHA/review binding, creation time after the verdict and before merge, and absence of edits or duplicate override records. Do not edit diff --git a/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md b/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md index bd6c10e53..9005f105e 100644 --- a/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md +++ b/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md @@ -182,17 +182,17 @@ uses a moving branch reference. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, + **`SQUAD_GITHUB_TOKEN`**, and **`SQUAD_REVIEW_APP_PRIVATE_KEY`** - Action: **`bradygaster/squad/.github/actions/squad-init`** -> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets -> the workflows *reference* so you can approve that surface — it is not asking you -> to supply them. Both secrets are optional, they need not exist, and neither is -> required to enlist a repository. Single-repo activation runs on the built-in -> `github.token`. Configure them only for cross-repo access or elevated -> permissions. Auth precedence: GitHub App token, then the PAT, then -> `github.token`. Never block an enlistment waiting for a credential. +> **Compilation approval is not credential provisioning.** `gh aw add` lists +> referenced names so you can approve the surface. `SQUAD_GITHUB_APP_PRIVATE_KEY` +> and `SQUAD_GITHUB_TOKEN` remain optional activation credentials. +> `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: trusted check publication requires +> it in the exact-default-branch `squad-review-authority` environment. Never put +> reviewer credentials at repository scope and never fall back to `github.token`. If — and only if — the report contains exactly those documented entries, complete the one-time approval: @@ -284,7 +284,27 @@ gh pr checks --watch `main`. - Request Copilot review, address feedback, and wait for required checks. -### 9. Never auto-merge — and explain what comes next +### 9. Verify the external review-authority prerequisite when API access permits + +Before claiming trusted review is ready, query the repository environment. It +must be named `squad-review-authority`, use custom deployment branch policies, +allow exactly the captured `${default_branch}`, contain the environment secret +`SQUAD_REVIEW_APP_PRIVATE_KEY`, and define environment variables +`SQUAD_REVIEW_APP_ID`, `SQUAD_REVIEW_APP_SLUG`, and +`SQUAD_REVIEW_APP_OWNER`. The App ID/slug must differ from +`15368`/`github-actions`. All four reviewer-specific names must also be absent +from repository-level Actions secrets and variables; repository fallback does +not satisfy this gate. + +If the authenticated account cannot read environment configuration, or any +requirement is absent, report the exact external prerequisite and do not claim +the required check is trusted. The installation PR remains a human boundary; +after it merges, the Cast canary intentionally fails closed until an +administrator provisions the environment and reruns the base-controlled +review. Configure a ruleset only from the canary check's observed App +integration ID, never from user input or a guessed value. + +### 10. Never auto-merge — and explain what comes next - **Never** merge the bootstrap PR yourself. Merge happens **only** after human approval. @@ -346,8 +366,9 @@ gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT mer ### ✓ Correct: STOP on an undocumented safe-update entry ```text -gh aw add reports a third secret: `ACME_DEPLOY_KEY`. -→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) +gh aw add reports an additional secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, + SQUAD_REVIEW_APP_PRIVATE_KEY) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -381,7 +402,8 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path. - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, - `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything + `SQUAD_GITHUB_TOKEN`, `SQUAD_REVIEW_APP_PRIVATE_KEY`, and + `bradygaster/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain `gh aw compile --strict` (no `--approve`). diff --git a/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md b/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md index bd6c10e53..9005f105e 100644 --- a/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md +++ b/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md @@ -182,17 +182,17 @@ uses a moving branch reference. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, + **`SQUAD_GITHUB_TOKEN`**, and **`SQUAD_REVIEW_APP_PRIVATE_KEY`** - Action: **`bradygaster/squad/.github/actions/squad-init`** -> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets -> the workflows *reference* so you can approve that surface — it is not asking you -> to supply them. Both secrets are optional, they need not exist, and neither is -> required to enlist a repository. Single-repo activation runs on the built-in -> `github.token`. Configure them only for cross-repo access or elevated -> permissions. Auth precedence: GitHub App token, then the PAT, then -> `github.token`. Never block an enlistment waiting for a credential. +> **Compilation approval is not credential provisioning.** `gh aw add` lists +> referenced names so you can approve the surface. `SQUAD_GITHUB_APP_PRIVATE_KEY` +> and `SQUAD_GITHUB_TOKEN` remain optional activation credentials. +> `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: trusted check publication requires +> it in the exact-default-branch `squad-review-authority` environment. Never put +> reviewer credentials at repository scope and never fall back to `github.token`. If — and only if — the report contains exactly those documented entries, complete the one-time approval: @@ -284,7 +284,27 @@ gh pr checks --watch `main`. - Request Copilot review, address feedback, and wait for required checks. -### 9. Never auto-merge — and explain what comes next +### 9. Verify the external review-authority prerequisite when API access permits + +Before claiming trusted review is ready, query the repository environment. It +must be named `squad-review-authority`, use custom deployment branch policies, +allow exactly the captured `${default_branch}`, contain the environment secret +`SQUAD_REVIEW_APP_PRIVATE_KEY`, and define environment variables +`SQUAD_REVIEW_APP_ID`, `SQUAD_REVIEW_APP_SLUG`, and +`SQUAD_REVIEW_APP_OWNER`. The App ID/slug must differ from +`15368`/`github-actions`. All four reviewer-specific names must also be absent +from repository-level Actions secrets and variables; repository fallback does +not satisfy this gate. + +If the authenticated account cannot read environment configuration, or any +requirement is absent, report the exact external prerequisite and do not claim +the required check is trusted. The installation PR remains a human boundary; +after it merges, the Cast canary intentionally fails closed until an +administrator provisions the environment and reruns the base-controlled +review. Configure a ruleset only from the canary check's observed App +integration ID, never from user input or a guessed value. + +### 10. Never auto-merge — and explain what comes next - **Never** merge the bootstrap PR yourself. Merge happens **only** after human approval. @@ -346,8 +366,9 @@ gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT mer ### ✓ Correct: STOP on an undocumented safe-update entry ```text -gh aw add reports a third secret: `ACME_DEPLOY_KEY`. -→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) +gh aw add reports an additional secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, + SQUAD_REVIEW_APP_PRIVATE_KEY) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -381,7 +402,8 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path. - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, - `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything + `SQUAD_GITHUB_TOKEN`, `SQUAD_REVIEW_APP_PRIVATE_KEY`, and + `bradygaster/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain `gh aw compile --strict` (no `--approve`). diff --git a/scripts/gh-aw-hosted-e2e.mjs b/scripts/gh-aw-hosted-e2e.mjs index ecc3e24d7..e58960d0f 100644 --- a/scripts/gh-aw-hosted-e2e.mjs +++ b/scripts/gh-aw-hosted-e2e.mjs @@ -38,6 +38,10 @@ const RESEARCH_ISSUE_TITLE = '[Research Proposals] Agent-discovered repo opportu const RESEARCH_MARKER = ''; const PROVENANCE_MARKER_PATTERN = /^$/gm; const ACTIONS_BOT_LOGIN = 'github-actions[bot]'; +const ACTIONS_BOT_ID = 41898282; +const ACTIONS_APP_ID = 15368; +const ACTIONS_APP_SLUG = 'github-actions'; +const REVIEW_AUTHORITY_ENVIRONMENT = 'squad-review-authority'; const SAFE_CHILD_ENV = Object.freeze([ 'CI', 'GH_CONFIG_DIR', @@ -366,6 +370,113 @@ export function guardedTargetMutation({ return mutate(); } +export function validateReviewAuthorityEnvironment( + environment, + branchPolicies, + secretNames, + variables, + repositorySecretNames, + repositoryVariableNames, + defaultBranch, + targetOwner, +) { + if (environment?.name !== REVIEW_AUTHORITY_ENVIRONMENT + || environment.deployment_branch_policy?.custom_branch_policies !== true + || environment.deployment_branch_policy?.protected_branches !== false) { + throw new Error( + 'Dedicated review authority environment must use an exact custom default-branch policy.', + ); + } + if (!Array.isArray(branchPolicies) + || branchPolicies.length !== 1 + || branchPolicies[0]?.type !== 'branch' + || branchPolicies[0]?.name !== defaultBranch) { + throw new Error( + 'Dedicated review authority environment must allow only the repository default branch.', + ); + } + if (!secretNames.includes('SQUAD_REVIEW_APP_PRIVATE_KEY')) { + throw new Error('Dedicated review authority environment is missing its reviewer App private key.'); + } + const reviewerNames = new Set([ + 'SQUAD_REVIEW_APP_ID', + 'SQUAD_REVIEW_APP_SLUG', + 'SQUAD_REVIEW_APP_OWNER', + 'SQUAD_REVIEW_APP_PRIVATE_KEY', + ]); + if (repositorySecretNames.some((name) => reviewerNames.has(name)) + || repositoryVariableNames.some((name) => reviewerNames.has(name))) { + throw new Error('Reviewer App credentials must not exist at repository scope.'); + } + const values = Object.fromEntries(variables.map(({ name, value }) => [name, value])); + const appId = Number(values.SQUAD_REVIEW_APP_ID); + const appSlug = values.SQUAD_REVIEW_APP_SLUG; + const appOwner = values.SQUAD_REVIEW_APP_OWNER; + if (!Number.isSafeInteger(appId) || appId < 1 || appId === ACTIONS_APP_ID + || typeof appSlug !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(appSlug) + || appSlug === ACTIONS_APP_SLUG || appOwner !== targetOwner) { + throw new Error('Dedicated review authority App variables are missing or misconfigured.'); + } + return { id: appId, slug: appSlug, owner: appOwner }; +} + +function reviewAuthorityEnvironment(target, defaultBranch) { + const [targetOwner] = target.split('/'); + const environment = ghJson([ + 'api', `repos/${target}/environments/${REVIEW_AUTHORITY_ENVIRONMENT}`, + ]); + const branchPolicies = ghJson([ + 'api', '--paginate', '--slurp', + `repos/${target}/environments/${REVIEW_AUTHORITY_ENVIRONMENT}/deployment-branch-policies?per_page=100`, + ]).flat().flatMap((page) => page.branch_policies ?? []); + const secretNames = ghJson([ + 'api', + `repos/${target}/environments/${REVIEW_AUTHORITY_ENVIRONMENT}/secrets?per_page=100`, + '--jq', '[.secrets[].name]', + ]); + const variables = ghJson([ + 'api', + `repos/${target}/environments/${REVIEW_AUTHORITY_ENVIRONMENT}/variables?per_page=100`, + '--jq', '[.variables[] | {name,value}]', + ]); + const repositorySecretNames = ghJson([ + 'api', `repos/${target}/actions/secrets?per_page=100`, + '--jq', '[.secrets[].name]', + ]); + const repositoryVariableNames = ghJson([ + 'api', `repos/${target}/actions/variables?per_page=100`, + '--jq', '[.variables[].name]', + ]); + return validateReviewAuthorityEnvironment( + environment, + branchPolicies, + secretNames, + variables, + repositorySecretNames, + repositoryVariableNames, + defaultBranch, + targetOwner, + ); +} + +export function observedRequiredCheck(check, attestation) { + if (check?.name !== 'Squad Review / review' + || !Number.isSafeInteger(check.app?.id) + || check.app.id < 1 + || check.app.id === ACTIONS_APP_ID + || typeof check.app?.slug !== 'string' + || check.app.slug === ACTIONS_APP_SLUG + || attestation?.publisher_app_id !== check.app.id + || attestation?.publisher_app_slug !== check.app.slug) { + throw new Error('Required-check rollout must use the observed dedicated App identity.'); + } + return { + context: check.name, + integration_id: check.app.id, + integration_slug: check.app.slug, + }; +} + export function authorizeTarget(args, sourceInfo, contract, github = githubAdapter) { const target = requireArg(args, 'target'); const expectedRepositoryId = Number(requireArg(args, 'target_repository_id')); @@ -403,8 +514,9 @@ export function authorizeTarget(args, sourceInfo, contract, github = githubAdapt || workflowPermissions.can_approve_pull_request_reviews !== true) { throw new Error('Target Actions permissions do not match the supported secure configuration.'); } + const reviewApp = reviewAuthorityEnvironment(target, info.default_branch); const baseline = assertPristineTarget(target, info.default_branch, contract, github); - return { target, info, workflowPermissions, actor, baseline }; + return { target, info, workflowPermissions, actor, reviewApp, baseline }; } function waitForBootstrapRun(target, headSha, startedAt, evidence) { @@ -564,6 +676,96 @@ export function waitForBootstrapOutputs( throw new Error('Timed out waiting for the draft Cast PR and bootstrap research issue.'); } +function waitForBaseControlledReviewCanary(target, castPr, expectedApp, evidence) { + const deadline = Date.now() + 20 * 60 * 1000; + while (Date.now() < deadline) { + const checks = ghJson([ + 'api', + '-H', 'Accept: application/vnd.github+json', + `repos/${target}/commits/${castPr.headSha}/check-runs`, + '--jq', '{check_runs:[.check_runs[] | {id,name,status,conclusion,head_sha,external_id,details_url,completed_at,output:{summary:.output.summary},app:{id:.app.id,slug:.app.slug}}]}', + ]).check_runs; + const externalId = + `squad-review-authority/v1:${target}:${castPr.number}:${castPr.baseSha}:${castPr.headSha}`; + const trustedChecks = checks.filter((check) => + check.name === 'Squad Review / review' && + check.external_id === externalId && + check.head_sha === castPr.headSha && + check.app?.id === expectedApp.id && + check.app?.slug === expectedApp.slug); + if (trustedChecks.length > 1) { + throw new Error(`Expected one base-controlled Squad Review canary check; found ${trustedChecks.length}.`); + } + const reviews = ghJson([ + 'api', + `repos/${target}/pulls/${castPr.number}/reviews?per_page=100`, + ]); + const verdicts = reviews.filter((review) => + review.user?.login === ACTIONS_BOT_LOGIN && + review.user?.id === ACTIONS_BOT_ID && + review.user?.type === 'Bot' && + review.commit_id === castPr.headSha && + String(review.body ?? '').includes('Squad-Review-Verdict:')); + if (verdicts.length > 1) { + throw new Error(`Expected one base-controlled Squad Review canary verdict; found ${verdicts.length}.`); + } + if (trustedChecks.length === 1 && trustedChecks[0].status === 'completed') { + const check = trustedChecks[0]; + if (check.conclusion !== 'success') { + throw new Error(`Base-controlled Squad Review canary failed for ${castPr.url}.`); + } + if (verdicts.length !== 1) { + throw new Error('Successful Squad Review canary check is missing its exact-head verdict.'); + } + const marker = String(verdicts[0].body).match(/^Squad-Review-Verdict: (\{[^\r\n]+\})$/m); + if (!marker) throw new Error('Squad Review canary verdict marker is malformed.'); + const verdict = JSON.parse(marker[1]); + if (verdict.schema !== 'squad-review-verdict/v1' + || verdict.repository !== target + || verdict.pull_request !== castPr.number + || verdict.base_sha !== castPr.baseSha + || verdict.head_sha !== castPr.headSha + || verdict.author_agent !== '@squad/base-controlled-bootstrap' + || verdict.reviewer_agent !== '@squad/base-controlled-review' + || verdict.result !== 'COMMENT' + || verdict.event !== 'pull_request_target' + || verdict.workflow_sha !== castPr.baseSha + || verdict.workflow_path !== '.github/workflows/squad-review.lock.yml') { + throw new Error('Squad Review canary verdict is not bound to the base-controlled bootstrap activation.'); + } + const attestation = JSON.parse(check.output?.summary ?? ''); + if (attestation.schema !== 'squad-review-check/v1' + || attestation.repository !== target + || attestation.pull_request !== castPr.number + || attestation.base_sha !== castPr.baseSha + || attestation.head_sha !== castPr.headSha + || attestation.workflow_sha !== castPr.baseSha + || attestation.run_id !== verdict.run_id + || attestation.event !== 'pull_request_target' + || attestation.workflow_path !== '.github/workflows/squad-review.lock.yml' + || attestation.authority_job !== 'Squad Review Authority / attest' + || attestation.publisher_app_id !== expectedApp.id + || attestation.publisher_app_slug !== expectedApp.slug + || check.app?.id === ACTIONS_APP_ID + || check.app?.slug === ACTIONS_APP_SLUG + || check.details_url !== `https://github.com/${target}/actions/runs/${verdict.run_id}`) { + throw new Error('Squad Review canary check is not bound to the base-controlled authority run.'); + } + writeJson(resolve(evidence, 'base-controlled-review-canary.json'), { + pull_request: castPr, + observed_required_check: observedRequiredCheck(check, attestation), + check, + review: verdicts[0], + verdict, + attestation, + }); + return { check, verdict }; + } + sleep(10_000); + } + throw new Error('Timed out waiting for the base-controlled Squad Review activation canary.'); +} + function createAndMergePr({ cwd, target, @@ -732,6 +934,12 @@ function hosted(args, repositoryRoot) { installation, installRun, ); + const reviewCanary = waitForBaseControlledReviewCanary( + targetState.target, + outputs.castPr, + targetState.reviewApp, + evidence, + ); runChild('git', ['fetch', 'origin', targetState.info.default_branch], { cwd: checkout }); const probeBranch = `squad-e2e/probe-${process.env.GITHUB_RUN_ID ?? sourceSha.slice(0, 12)}`; @@ -785,6 +993,8 @@ function hosted(args, repositoryRoot) { source_sha: sourceSha, installation_pr: installation.number, installation_run: installRun.url, + review_canary_pr: outputs.castPr.number, + review_canary_check: reviewCanary.check.id, probe_pr: probeMerge.number, probe_run: probeRun.url, generated_cast_pr: outputs.castPr.url, diff --git a/templates/skills/gh-aw-enlistment/SKILL.md b/templates/skills/gh-aw-enlistment/SKILL.md index bd6c10e53..9005f105e 100644 --- a/templates/skills/gh-aw-enlistment/SKILL.md +++ b/templates/skills/gh-aw-enlistment/SKILL.md @@ -182,17 +182,17 @@ uses a moving branch reference. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, + **`SQUAD_GITHUB_TOKEN`**, and **`SQUAD_REVIEW_APP_PRIVATE_KEY`** - Action: **`bradygaster/squad/.github/actions/squad-init`** -> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets -> the workflows *reference* so you can approve that surface — it is not asking you -> to supply them. Both secrets are optional, they need not exist, and neither is -> required to enlist a repository. Single-repo activation runs on the built-in -> `github.token`. Configure them only for cross-repo access or elevated -> permissions. Auth precedence: GitHub App token, then the PAT, then -> `github.token`. Never block an enlistment waiting for a credential. +> **Compilation approval is not credential provisioning.** `gh aw add` lists +> referenced names so you can approve the surface. `SQUAD_GITHUB_APP_PRIVATE_KEY` +> and `SQUAD_GITHUB_TOKEN` remain optional activation credentials. +> `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: trusted check publication requires +> it in the exact-default-branch `squad-review-authority` environment. Never put +> reviewer credentials at repository scope and never fall back to `github.token`. If — and only if — the report contains exactly those documented entries, complete the one-time approval: @@ -284,7 +284,27 @@ gh pr checks --watch `main`. - Request Copilot review, address feedback, and wait for required checks. -### 9. Never auto-merge — and explain what comes next +### 9. Verify the external review-authority prerequisite when API access permits + +Before claiming trusted review is ready, query the repository environment. It +must be named `squad-review-authority`, use custom deployment branch policies, +allow exactly the captured `${default_branch}`, contain the environment secret +`SQUAD_REVIEW_APP_PRIVATE_KEY`, and define environment variables +`SQUAD_REVIEW_APP_ID`, `SQUAD_REVIEW_APP_SLUG`, and +`SQUAD_REVIEW_APP_OWNER`. The App ID/slug must differ from +`15368`/`github-actions`. All four reviewer-specific names must also be absent +from repository-level Actions secrets and variables; repository fallback does +not satisfy this gate. + +If the authenticated account cannot read environment configuration, or any +requirement is absent, report the exact external prerequisite and do not claim +the required check is trusted. The installation PR remains a human boundary; +after it merges, the Cast canary intentionally fails closed until an +administrator provisions the environment and reruns the base-controlled +review. Configure a ruleset only from the canary check's observed App +integration ID, never from user input or a guessed value. + +### 10. Never auto-merge — and explain what comes next - **Never** merge the bootstrap PR yourself. Merge happens **only** after human approval. @@ -346,8 +366,9 @@ gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT mer ### ✓ Correct: STOP on an undocumented safe-update entry ```text -gh aw add reports a third secret: `ACME_DEPLOY_KEY`. -→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) +gh aw add reports an additional secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, + SQUAD_REVIEW_APP_PRIVATE_KEY) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -381,7 +402,8 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path. - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, - `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything + `SQUAD_GITHUB_TOKEN`, `SQUAD_REVIEW_APP_PRIVATE_KEY`, and + `bradygaster/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain `gh aw compile --strict` (no `--approve`). diff --git a/test/gh-aw-bootstrap-workflow.test.ts b/test/gh-aw-bootstrap-workflow.test.ts index 73781f0d6..4ef39ee80 100644 --- a/test/gh-aw-bootstrap-workflow.test.ts +++ b/test/gh-aw-bootstrap-workflow.test.ts @@ -742,6 +742,9 @@ describe('automatic Squad bootstrap workflow', () => { expect(lock).toContain('SQUAD_BOOTSTRAP_REPOSITORY: ${{ github.repository }}'); expect(lock).toContain('SQUAD_BOOTSTRAP_RUN_ID: ${{ github.run_id }}'); expect(lock).toContain('squad:bootstrap-provenance'); + expect(lock).toContain('Base-controlled bootstrap provenance. Do not edit this comment.'); + expect(lock).toContain('github.rest.issues.createComment'); + expect(lock).toContain('github.rest.issues.updateComment'); expect(lock).toContain('pullRequestDetails.head.repo?.full_name !== provenance.repository'); expect(lock).toContain('body: `${provenanceMarker}\\n${prBodyWithoutProvenance}`'); expect(lock).toContain('body: markedIssueBody'); diff --git a/test/gh-aw-enlistment-skill.test.ts b/test/gh-aw-enlistment-skill.test.ts index fdcaf5c1d..5d400576e 100644 --- a/test/gh-aw-enlistment-skill.test.ts +++ b/test/gh-aw-enlistment-skill.test.ts @@ -115,10 +115,11 @@ describe('gh-aw-enlistment skill', () => { // Every backtick-delimited token in the region — order-independent exact set. const tokens = [...region.matchAll(/`([^`]+)`/g)].map(m => m[1]); - expect(tokens.slice().sort(), 'allowlist tokens must be exactly the three documented entries').toEqual( + expect(tokens.slice().sort(), 'allowlist tokens must be exactly the four documented entries').toEqual( [ 'SQUAD_GITHUB_APP_PRIVATE_KEY', 'SQUAD_GITHUB_TOKEN', + 'SQUAD_REVIEW_APP_PRIVATE_KEY', 'bradygaster/squad/.github/actions/squad-init', ].sort() ); diff --git a/test/gh-aw-hosted-e2e.test.ts b/test/gh-aw-hosted-e2e.test.ts index 387e583c4..9728a0bf7 100644 --- a/test/gh-aw-hosted-e2e.test.ts +++ b/test/gh-aw-hosted-e2e.test.ts @@ -6,8 +6,10 @@ import { parse } from 'yaml'; import { assertPristineTarget, guardedTargetMutation, + observedRequiredCheck, sanitizedEnvironment, selectBootstrapOutputs, + validateReviewAuthorityEnvironment, waitForBootstrapOutputs, } from '../scripts/gh-aw-hosted-e2e.mjs'; import { @@ -189,9 +191,20 @@ describe('Squad gh-aw hosted E2E controller', () => { expect(BOOTSTRAP_WORKFLOW).toContain('SQUAD_BOOTSTRAP_INSTALL_SHA: ${{ github.sha }}'); expect(BOOTSTRAP_WORKFLOW).toContain('SQUAD_BOOTSTRAP_REPOSITORY: ${{ github.repository }}'); expect(BOOTSTRAP_WORKFLOW).toContain('SQUAD_BOOTSTRAP_RUN_ID: ${{ github.run_id }}'); - expect(BOOTSTRAP_WORKFLOW).toContain(''); + expect(BOOTSTRAP_WORKFLOW).toContain( + "const provenancePrefix = '<' + '!-- squad:bootstrap-provenance ';", + ); + expect(BOOTSTRAP_WORKFLOW).toContain( + 'const provenanceMarker = `${provenancePrefix}${JSON.stringify(provenance)} -->`;', + ); + expect(BOOTSTRAP_WORKFLOW).not.toContain( + '', + ); expect(BOOTSTRAP_WORKFLOW).toContain('pullRequestDetails.head.repo?.full_name !== provenance.repository'); expect(BOOTSTRAP_WORKFLOW).toContain('body: `${provenanceMarker}\\n${prBodyWithoutProvenance}`'); + expect(BOOTSTRAP_WORKFLOW).toContain( + 'Base-controlled bootstrap provenance. Do not edit this comment.', + ); expect(BOOTSTRAP_WORKFLOW).toContain('body: markedIssueBody'); }); @@ -204,6 +217,107 @@ describe('Squad gh-aw hosted E2E controller', () => { expect(SCRIPT).toContain('rmSync(checkout, { recursive: true, force: true })'); }); + it('requires a base-controlled review canary after the manual installation boundary', () => { + expect(SCRIPT).toContain('waitForBaseControlledReviewCanary'); + expect(SCRIPT).toContain("check.name === 'Squad Review / review'"); + expect(SCRIPT).toContain('check.app?.id === expectedApp.id'); + expect(SCRIPT).toContain('check.app?.slug === expectedApp.slug'); + expect(SCRIPT).toContain('observed_required_check'); + expect(SCRIPT).toContain('integration_id: check.app.id'); + expect(SCRIPT).toContain("'@squad/base-controlled-bootstrap'"); + expect(SCRIPT).toContain("'@squad/base-controlled-review'"); + expect(SCRIPT).toContain("verdict.result !== 'COMMENT'"); + expect(SCRIPT.indexOf('waitForBaseControlledReviewCanary')).toBeLessThan( + SCRIPT.indexOf("kind: 'squad-bootstrap-trigger-probe'"), + ); + }); + + it('requires a branch-restricted environment with reviewer-only App credentials', () => { + const environment = { + name: 'squad-review-authority', + deployment_branch_policy: { + custom_branch_policies: true, + protected_branches: false, + }, + }; + const policies = [{ type: 'branch', name: 'main' }]; + const secrets = ['SQUAD_REVIEW_APP_PRIVATE_KEY']; + const variables = [ + { name: 'SQUAD_REVIEW_APP_ID', value: '424242' }, + { name: 'SQUAD_REVIEW_APP_SLUG', value: 'squad-review-authority' }, + { name: 'SQUAD_REVIEW_APP_OWNER', value: 'owner' }, + ]; + expect(validateReviewAuthorityEnvironment( + environment, + policies, + secrets, + variables, + [], + [], + 'main', + 'owner', + )).toEqual({ id: 424242, slug: 'squad-review-authority', owner: 'owner' }); + + const invalid = [ + [undefined, policies, secrets, variables, [], []], + [{ ...environment, deployment_branch_policy: null }, policies, secrets, variables, [], []], + [environment, [], secrets, variables, [], []], + [environment, [{ type: 'branch', name: '*' }], secrets, variables, [], []], + [environment, [...policies, { type: 'branch', name: 'release' }], secrets, variables, [], []], + [environment, policies, [], variables, [], []], + [environment, policies, secrets, + variables.filter(({ name }) => name !== 'SQUAD_REVIEW_APP_ID'), [], []], + [environment, policies, secrets, variables.map(variable => + variable.name === 'SQUAD_REVIEW_APP_ID' ? { ...variable, value: '15368' } : variable), [], []], + [environment, policies, secrets, variables.map(variable => + variable.name === 'SQUAD_REVIEW_APP_SLUG' + ? { ...variable, value: 'github-actions' } + : variable), [], []], + [environment, policies, secrets, variables.map(variable => + variable.name === 'SQUAD_REVIEW_APP_OWNER' + ? { ...variable, value: 'attacker' } + : variable), [], []], + [environment, policies, secrets, variables, ['SQUAD_REVIEW_APP_PRIVATE_KEY'], []], + [environment, policies, secrets, variables, [], ['SQUAD_REVIEW_APP_ID']], + ] as const; + for (const args of invalid) { + expect(() => validateReviewAuthorityEnvironment( + args[0], + args[1], + args[2], + args[3], + args[4], + args[5], + 'main', + 'owner', + )).toThrow(); + } + }); + + it('derives ruleset integration only from the observed dedicated canary check', () => { + const check = { + name: 'Squad Review / review', + app: { id: 424242, slug: 'squad-review-authority' }, + }; + const attestation = { + publisher_app_id: 424242, + publisher_app_slug: 'squad-review-authority', + }; + expect(observedRequiredCheck(check, attestation)).toEqual({ + context: 'Squad Review / review', + integration_id: 424242, + integration_slug: 'squad-review-authority', + }); + expect(() => observedRequiredCheck( + { ...check, app: { id: 15368, slug: 'github-actions' } }, + { publisher_app_id: 15368, publisher_app_slug: 'github-actions' }, + )).toThrow(); + expect(() => observedRequiredCheck(check, { + ...attestation, + publisher_app_id: 1, + })).toThrow(); + }); + it('never executes candidate package or installed verifier with inherited credentials', () => { expect(SCRIPT).toContain( 'env: sanitizedEnvironment(options.env, { allowGitHubToken: options.allowGitHubToken === true })', diff --git a/test/gh-aw-quality.test.ts b/test/gh-aw-quality.test.ts index 59cd432da..5830eb496 100644 --- a/test/gh-aw-quality.test.ts +++ b/test/gh-aw-quality.test.ts @@ -15,7 +15,9 @@ import { tmpdir } from 'node:os'; import { execFileSync, execSync, spawnSync } from 'node:child_process'; import { createHash } from 'node:crypto'; import { minimatch } from 'minimatch'; +import { isMap, isSeq, parseDocument, type YAMLMap } from 'yaml'; import { POSIX_SHELL, NO_POSIX_SHELL_MESSAGE, requirePosixShell } from './posix-shell'; +import { createFirstInstallFixture } from './helpers/gh-aw-install-fixture.js'; import { extractRunBlocks, scanRunBlocks, @@ -26,6 +28,7 @@ import { import { CONTRACT_DESTINATION, CONTRACT_SOURCE, + MIN_GH_AW_VERSION, OWNERSHIP_ENTRY_COUNT, PACKAGE_NAME, RUNTIME_TUPLES, @@ -35,6 +38,7 @@ import { WORKFLOW_NAMES, checkSource, materializeRuntime, + normalizeCompiledLock, validateContract, verifyInstall, } from '../workflows/shared/squad-install-verifier.mjs'; @@ -3512,6 +3516,260 @@ describe('gh-aw: activation roster guard counts only data rows (#1605)', () => { }); }); +describe('gh-aw: CI compiler pin contract', () => { + const ci = readText(join(process.cwd(), '.github/workflows/squad-ci.yml')); + const installs = [ + { + job: 'test', + name: 'Install gh-aw extension', + commands: [`gh extension install --pin ${MIN_GH_AW_VERSION} github/gh-aw`], + }, + { + job: 'gh-aw-compile', + name: `Install gh-aw ${MIN_GH_AW_VERSION} (pinned)`, + commands: [ + `gh extension install --force --pin ${MIN_GH_AW_VERSION} github/gh-aw`, + `test "$(gh aw --version 2>&1 | awk '{print $NF}')" = ${MIN_GH_AW_VERSION}`, + ], + }, + ] as const; + + // This is a deliberately bounded recognizer, not a general shell parser. + // Unsupported here-documents fail closed; only literal cat-to-stdout is inert. + function shellCommands(run: string): string[] { + const commands: string[] = []; + let command = ''; + let quote = ''; + let wordStart = true; + for (let i = 0; i < run.length; i++) { + const char = run[i]; + if (char === '\\' && quote !== "'") { + const next = run[++i]; + if (next === undefined) throw new Error('Dangling shell escape'); + if (next !== '\n' || quote) { + command += char + next; + wordStart = false; + } + } else if (char === quote) { + quote = ''; + command += char; + } else if (!quote && (char === "'" || char === '"')) { + quote = char; + command += char; + wordStart = false; + } else if (!quote && char === '#' && wordStart) { + while (i + 1 < run.length && run[i + 1] !== '\n') i++; + } else if (!quote && char === '\n') { + const heredoc = command.match(/^cat <<(['"])([A-Za-z_][A-Za-z0-9_]*)\1$/); + if (heredoc) { + const end = run.indexOf(`\n${heredoc[2]}\n`, i); + if (end === -1) throw new Error('Unterminated literal heredoc'); + command += run.slice(i, end + heredoc[2].length + 1); + i = end + heredoc[2].length + 1; + } + if (command.trim()) commands.push(command.trim()); + command = ''; + wordStart = true; + } else { + command += char; + if (!quote) wordStart = /[\s;|&()<>]/.test(char); + } + } + if (quote) throw new Error('Unterminated shell quote'); + if (command.trim()) commands.push(command.trim()); + return commands; + } + + function isInstallerOrAmbiguous(command: string): boolean { + if (/^cat <<(['"])([A-Za-z_][A-Za-z0-9_]*)\1\n[\s\S]*\n\2$/.test(command)) return false; + if (/^(?:echo|printf)(?:\s+(?:'[^']*'|"(?:\\[\s\S]|[^"\\$`])*"))+$/.test(command)) return false; + // Remove word-splicing quotes/escapes for detection only, never for approval. + // A repository operand alone is enough: dynamic command/argument construction + // must not evade detection merely by hiding "gh extension install". + const visible = command.replace(/['"\\]/g, ''); + const syntax = command.replace(/'[^']*'|"(?:\\[\s\S]|[^"\\])*"|\\[\s\S]/g, + token => token.startsWith('"') && /[$`]/.test(token) ? '$' : 'literal'); + const dynamicCommand = '(?![A-Za-z_]\\w*=)[^\\s;&|()]*[$`]'; + return /github\/gh-aw|\bgh\s+(?:extension|ext)\b/.test(visible) || + /\bgh\s+[^\s]*[$`]/.test(visible) || + new RegExp(`(?:^|[;&|(){}\\n])\\s*(?:(?:if|then|else|do|!|command|exec|env|sudo|--?[\\w-]+|[A-Za-z_]\\w*=[^()\\s]+)\\s+)*${dynamicCommand}`).test(syntax) || + new RegExp(`(?:\\$\\(|\`)\\s*${dynamicCommand}`).test(visible) || + /\b(?:command|exec|env|sudo)\s[^;\n]*[$`]/.test(syntax) || + /(?:^|[;&|()\n])\s*(?:eval|source|\.)\s/.test(syntax) || + /\b(?:bash|sh|zsh|ksh)\s+.*(?:-[a-z]*c\b|[$`])/.test(visible) || + /< = []; + for (const { key, value } of jobs.items) { + if (!isMap(value)) throw new Error('CI job must be a mapping'); + const steps = value.get('steps'); + if (steps === undefined) continue; // Reusable workflow jobs have no steps. + if (!isSeq(steps)) throw new Error('CI steps must be a sequence'); + for (const step of steps.items) { + if (!isMap(step)) throw new Error('CI step must be a mapping'); + const run = step.get('run'); + if (run === undefined) continue; + if (typeof run !== 'string') throw new Error('CI run must be a string'); + const commands = shellCommands(`${run}\n`); + const name = step.get('name'); + // Include named slots even if their install was removed or replaced by output. + // Unexpected install-like scripts fail closed; never accept a shell wrapper + // merely because it contains the pinned command as a substring. + if (installs.some(install => install.name === name) || commands.some(isInstallerOrAmbiguous)) { + installSteps.push({ job: String(key), name, commands }); + } + } + } + expect(installSteps).toEqual(installs); + } + + function mutateInstall(job: string, change: (step: YAMLMap) => void): string { + const workflow = parseDocument(ci); + const steps = workflow.getIn(['jobs', job, 'steps']); + if (!isSeq(steps)) throw new Error(`Missing steps for ${job}`); + const name = installs.find(install => install.job === job)?.name; + const step = steps.items.find(step => isMap(step) && step.get('name') === name); + if (!isMap(step)) throw new Error(`Missing install step for ${job}`); + change(step); + return workflow.toString(); + } + + it('pins every CI compiler install to the package minimum gh-aw version', () => { + assertCompilerPins(ci); + }); + + it('ignores YAML comments, shell comment lines, and non-run strings', () => { + const workflow = parseDocument(ci); + workflow.setIn(['env', 'INSTALL_EXAMPLE'], 'gh extension install github/gh-aw'); + workflow.addIn(['jobs', 'changes', 'steps'], { + name: installs[0].commands[0], + run: `echo '${installs[0].commands[0]}'\nprintf "%s" "gh extension install github/gh-aw"`, + }); + const source = mutateInstall('test', step => { + step.set('run', `# gh extension install github/gh-aw\n\n${installs[0].commands[0]} # pinned\n`); + step.setIn(['env', 'PIN_EXAMPLE'], installs[1].commands[0]); + }); + assertCompilerPins(`# gh extension install github/gh-aw\n${source}`); + assertCompilerPins(workflow.toString()); + }); + + it.each([ + ['continued comment', '# gh extension \\\necho "install github/gh-aw"'], + ['single-quoted backslash', "printf '%s' 'gh extension \\\ninstall github/gh-aw'"], + ['double-quoted backslash', 'echo "gh extension \\\ninstall github/gh-aw"'], + ['escaped backslash', String.raw`echo "gh extension \\"`], + ['literal heredoc', "cat <<'INSTALL'\ngh extension \\\ninstall github/gh-aw\nINSTALL"], + ['heredoc quote and comment text', "cat <<'INSTALL'\n' \" # \\\n$(gh extension install github/gh-aw)\nINSTALL"], + ])('ignores inert %s without folding literal text', (_label, run) => { + const workflow = parseDocument(ci); + workflow.addIn(['jobs', 'changes', 'steps'], { name: 'Literal example', run }); + assertCompilerPins(workflow.toString()); + if (!run.startsWith('#')) expect(shellCommands(`${run}\n`)).toEqual([run]); + }); + + it('accepts an unquoted continuation of the standalone approved command', () => { + assertCompilerPins(mutateInstall('test', step => { + step.set('run', installs[0].commands[0].replace('extension ', 'extension \\\n')); + })); + }); + + describe.each(installs)('$job install step', ({ job, commands }) => { + it.each([ + ['unpinned', 'gh extension install github/gh-aw'], + ['wrong version', commands[0].replace(MIN_GH_AW_VERSION, 'v0.0.0')], + ['duplicate command', `${commands[0]}\n${commands[0]}`], + ['comment-only pin', `# ${commands[0]}\ngh extension install github/gh-aw`], + ['inline comment pin', `gh extension install github/gh-aw # ${commands[0]}`], + ['echoed pin', `echo "${commands[0]}"`], + ['shell wrapper', `bash -c '${commands[0]}'`], + ['conditional command', `false && ${commands[0]}`], + ['preceding command', `echo preparing\n${commands[0]}`], + ['appended command', `${commands[0]}; gh extension install github/gh-aw`], + ['heredoc text', `cat <<'INSTALL'\n${commands[0]}\nINSTALL`], + ['quoted continuation', `'${commands[0].replace('extension ', 'extension \\\n')}'`], + ['escaped backslash is not continuation', commands[0].replace('extension ', 'extension \\\\\n')], + ['comment backslash is not continuation', commands[0].replace('extension ', 'extension # comment \\\n')], + ['space after backslash is not continuation', commands[0].replace('extension ', 'extension \\ \n')], + ])('rejects %s', (_label, command) => { + const source = mutateInstall(job, step => { + step.set('run', [command, ...commands.slice(1)].join('\n')); + }); + expect(() => assertCompilerPins(source)).toThrow(); + }); + + it('rejects an install moved to an unexpected step', () => { + const source = mutateInstall(job, step => step.set('name', 'Unexpected install')); + expect(() => assertCompilerPins(source)).toThrow(); + }); + + it('rejects an install moved to an unexpected job', () => { + const workflow = parseDocument(ci); + const original = workflow.getIn(['jobs', job]); + workflow.deleteIn(['jobs', job]); + workflow.setIn(['jobs', 'unexpected-job'], original); + expect(() => assertCompilerPins(workflow.toString())).toThrow(); + }); + + it('rejects a missing install step', () => { + const source = mutateInstall(job, step => step.delete('run')); + expect(() => assertCompilerPins(source)).toThrow(); + }); + + it.each([ + ['duplicate step', job, commands[0]], + ['extra pinned install', 'changes', commands[0]], + ['extra unpinned install', 'changes', 'gh extension install github/gh-aw'], + ['extra wrapped install', 'changes', `bash -c '${commands[0]}'`], + ['extra install after quoted hash', 'changes', `echo "#"; ${commands[0]}`], + ['extra install in output substitution', 'changes', `echo "$(${commands[0]})"`], + ['continued installer', 'changes', 'gh extension \\\ninstall github/gh-aw'], + ['continued command word', 'changes', 'g\\\nh ext\\\nension install github/gh-aw'], + ['continued repository', 'changes', 'gh extension install github/gh-\\\naw'], + ['continued wrapper', 'changes', 'command gh extension \\\ninstall github/gh-aw'], + ['continued conditional', 'changes', 'if true; then gh extension \\\ninstall github/gh-aw; fi'], + ['continued substitution', 'changes', 'echo "$(gh extension \\\ninstall github/gh-aw)"'], + ['backtick substitution', 'changes', 'echo "`gh extension install github/gh-aw`"'], + ['quoted word splicing', 'changes', `g'h' exten"sion" install github/gh-"aw"`], + ['dynamic command', 'changes', 'cli=gh\n"$cli" extension install github/gh-aw'], + ['dynamic arguments', 'changes', 'gh "$verb" "$action" "$repository"'], + ['partly dynamic subcommand', 'changes', 'gh exten"$suffix" "$action" "$repository"'], + ['partly dynamic executable', 'changes', 'g"$suffix" "$verb" "$action" "$repository"'], + ['fully dynamic command', 'changes', '"$INSTALLER"'], + ['dynamic command in group', 'changes', '{ "$INSTALLER"; }'], + ['dynamic command in substitution', 'changes', 'echo "$("$INSTALLER")"'], + ['dynamic command in backticks', 'changes', 'echo "`$INSTALLER`"'], + ['dynamic command after assignment', 'changes', 'ENV=value "$INSTALLER"'], + ['dynamic env wrapper', 'changes', 'env -i "$INSTALLER"'], + ['dynamic wrapper with option operand', 'changes', 'env -u PATH "$INSTALLER"'], + ['dynamic shell wrapper', 'changes', 'bash -c "$INSTALLER"'], + ['eval wrapper', 'changes', 'eval "$INSTALLER"'], + ['unquoted heredoc substitution', 'changes', 'cat < { + const workflow = parseDocument(ci); + workflow.addIn(['jobs', targetJob, 'steps'], { + name: 'Extra install', + run: command, + }); + expect(() => assertCompilerPins(workflow.toString())).toThrow(); + }); + }); +}); + describe('gh-aw: canonical package integrity contract', () => { const revisionA = 'a'.repeat(40); const revisionB = 'b'.repeat(40); @@ -3524,13 +3782,16 @@ describe('gh-aw: canonical package integrity contract', () => { function makeConsumer(revision = revisionA, materialize = true): string { const root = createTestWorkspace('gh-aw-package-contract-'); + const install = createFirstInstallFixture(revision); copyInto(root, CONTRACT_SOURCE, CONTRACT_DESTINATION); const contract = JSON.parse(readFileSync(join(process.cwd(), CONTRACT_SOURCE), 'utf8')); for (const workflow of contract.workflows) { - copyInto(root, workflow.source, workflow.destination); + const destination = join(root, workflow.destination); + mkdirSync(dirname(destination), { recursive: true }); + writeFileSync(destination, install.consumerFiles.get(workflow.destination)!); const lock = join(root, workflow.lock); mkdirSync(dirname(lock), { recursive: true }); - writeFileSync(lock, `# test lock for ${workflow.name}\n`); + writeFileSync(lock, install.consumerFiles.get(workflow.lock)!); } for (const resource of contract.shared_runtime) { copyInto(root, resource.source, resource.package_destination); @@ -3580,11 +3841,23 @@ describe('gh-aw: canonical package integrity contract', () => { const ciRuntimeCount = readText(join(process.cwd(), '.github/workflows/squad-ci.yml')).match( /find \.github\/workflows\/shared -type f ! -name 'squad-bootstrap-trigger-probe\.json' \| wc -l \| tr -d ' '\)" = (\d+)/, ); + const ci = readText(join(process.cwd(), '.github/workflows/squad-ci.yml')); expect(contract.workflows.map((entry: { name: string }) => entry.name)).toEqual(WORKFLOW_NAMES); expect(contract.shared_runtime).toHaveLength(RUNTIME_TUPLES.length); expect(contract.shared_runtime).toHaveLength(17); expect(ciRuntimeCount?.[1], 'strict compile CI runtime cardinality must match the package manifest') .toBe(String(contract.shared_runtime.length)); + const seedStart = ci.indexOf('mkdir -p .github/workflows'); + const addStart = ci.indexOf('gh aw add --force "$GITHUB_WORKSPACE/workflows"'); + expect(seedStart, 'clean-consumer CI must seed all dispatched peers before gh aw add compiles') + .toBeGreaterThan(-1); + expect(addStart).toBeGreaterThan(seedStart); + expect(ci.slice(seedStart, addStart)).toContain( + `for workflow in ${WORKFLOW_NAMES.join(' ')}; do`, + ); + expect(ci.slice(seedStart, addStart)).toContain( + '"$GITHUB_WORKSPACE/workflows/package/${workflow}.md"', + ); expect(contract.shared_runtime).toContainEqual(expect.objectContaining({ path: 'shared/squad-review-guard.mjs', destination: '.github/workflows/shared/squad-review-guard.mjs', @@ -3612,6 +3885,23 @@ describe('gh-aw: canonical package integrity contract', () => { expect(record.files).toHaveLength(OWNERSHIP_ENTRY_COUNT); }); + it('normalizes only compiler-declared repository-scattered schedules', () => { + const metadata = `# gh-aw-metadata: {"frontmatter_hash":"${'a'.repeat(64)}"}`; + const lock = [ + metadata, + `source_revision: ${revisionA}`, + ' - cron: "17 4 * * 2" # Friendly format: weekly on Tuesday at 04:00 (scattered)', + ' - cron: "0 4 * * 2" # Fixed schedule', + ].join('\n'); + const normalized = normalizeCompiledLock(lock, revisionA); + + expect(normalized).toContain( + ' - cron: "" # Friendly format: weekly on Tuesday at 04:00 (scattered)', + ); + expect(normalized).toContain(' - cron: "0 4 * * 2" # Fixed schedule'); + expect(normalized).not.toContain(revisionA); + }); + it('accepts only the deterministic retained bootstrap trigger sentinel', () => { const root = makeConsumer(); const probePath = join(root, TRIGGER_PROBE_DESTINATION); diff --git a/test/gh-aw-review-guard.test.ts b/test/gh-aw-review-guard.test.ts index 5de59d7bd..42cddf84a 100644 --- a/test/gh-aw-review-guard.test.ts +++ b/test/gh-aw-review-guard.test.ts @@ -16,6 +16,8 @@ const SUBMITTED = '2026-09-28T12:01:01Z'; const FINISHED = '2026-09-28T12:02:00Z'; const MERGED = '2026-09-28T12:03:00Z'; const NOW = Date.parse('2026-09-28T12:04:00Z'); +const REVIEW_APP_ID = 424242; +const REVIEW_APP_SLUG = 'squad-review-authority'; const workspaces: string[] = []; afterEach(() => { @@ -27,9 +29,11 @@ afterEach(() => { function fixture(relay = false) { vi.spyOn(Date, 'now').mockReturnValue(NOW); const env = { - GITHUB_EVENT_NAME: 'pull_request', GITHUB_REPOSITORY: REPOSITORY, + GITHUB_EVENT_NAME: 'pull_request_target', GITHUB_REPOSITORY: REPOSITORY, + GITHUB_SERVER_URL: 'https://github.com', GITHUB_RUN_ID: '17', GITHUB_RUN_ATTEMPT: '1', - SQUAD_REVIEW_PR: '42', SQUAD_REVIEW_HEAD: HEAD, SQUAD_REVIEW_DEFAULT_BRANCH: 'dev', + SQUAD_REVIEW_PR: '42', SQUAD_REVIEW_HEAD: HEAD, + SQUAD_REVIEW_WORKFLOW_SHA: BASE, SQUAD_REVIEW_DEFAULT_BRANCH: 'dev', }; const attribution = { schema: 'squad-review-author/v1', repository: REPOSITORY, issue: 9, @@ -44,28 +48,69 @@ function fixture(relay = false) { }; const pr = { number: 42, state: relay ? 'closed' : 'open', merged: relay, merged_at: MERGED, + title: 'Implementation', body: '', + user: { login: 'human', type: 'User' }, head: { sha: HEAD, ref: 'squad/implement-9-fix', repo: { full_name: REPOSITORY, name: 'example' } }, base: { sha: BASE, ref: 'dev', repo: { full_name: REPOSITORY, name: 'example' } }, }; const verdict = { schema: 'squad-review-verdict/v1', repository: REPOSITORY, pull_request: 42, - head_sha: HEAD, author_agent: 'implementer', reviewer_agent: 'reviewer', - result: 'COMMENT', timestamp: ISSUED, run_id: 17, run_attempt: 1, event: 'pull_request', + base_sha: BASE, head_sha: HEAD, author_agent: 'implementer', reviewer_agent: 'reviewer', + result: 'COMMENT', timestamp: ISSUED, run_id: 17, run_attempt: 1, + event: 'pull_request_target', workflow_path: '.github/workflows/squad-review.lock.yml', + workflow_sha: BASE, }; const review = { - id: 123, user: { login: 'github-actions[bot]' }, commit_id: HEAD, + id: 123, user: { login: 'github-actions[bot]', id: 41898282, type: 'Bot' }, commit_id: HEAD, state: 'COMMENTED', submitted_at: SUBMITTED, body: '', }; const run = { - event: 'pull_request', path: '.github/workflows/squad-review.lock.yml', + event: 'pull_request_target', path: '.github/workflows/squad-review.lock.yml', display_title: 'Squad review \u2014 PR #42', - repository: { full_name: REPOSITORY }, head_sha: HEAD, run_attempt: 1, + repository: { full_name: REPOSITORY }, head_sha: BASE, run_attempt: 1, pull_requests: [{ number: 42, head: { sha: HEAD }, base: { repo: { name: 'example' } } }], run_started_at: START, updated_at: FINISHED, status: 'completed', conclusion: 'success', }; - const jobs = [{ name: CHECK_NAME, conclusion: 'success', completed_at: FINISHED }]; + const jobs = [{ + name: 'Squad Review Authority / attest', + conclusion: 'success', + completed_at: FINISHED, + }]; + const checkRuns = [{ + id: 88, + name: CHECK_NAME, + external_id: `squad-review-authority/v1:${REPOSITORY}:42:${BASE}:${HEAD}`, + head_sha: HEAD, + status: 'completed', + conclusion: 'success', + completed_at: FINISHED, + details_url: `https://github.com/${REPOSITORY}/actions/runs/17`, + app: { id: REVIEW_APP_ID, slug: REVIEW_APP_SLUG }, + output: { + summary: JSON.stringify({ + schema: 'squad-review-check/v1', + repository: REPOSITORY, + pull_request: 42, + base_sha: BASE, + head_sha: HEAD, + workflow_sha: BASE, + run_id: 17, + run_attempt: 1, + event: 'pull_request_target', + workflow_path: '.github/workflows/squad-review.lock.yml', + authority_job: 'Squad Review Authority / attest', + publisher_app_id: REVIEW_APP_ID, + publisher_app_slug: REVIEW_APP_SLUG, + }), + }, + }]; + const bootstrapRun = { + event: 'push', path: '.github/workflows/squad-bootstrap.lock.yml', + repository: { full_name: REPOSITORY }, head_sha: BASE, head_branch: 'dev', + status: 'completed', conclusion: 'success', + }; const override = { schema: 'squad-review-override/v1', repository: REPOSITORY, pull_request: 42, head_sha: HEAD, review_id: 123, reason: 'Accepted false positive; linked human decision.', @@ -78,10 +123,13 @@ function fixture(relay = false) { reviews: [review], comments: [] as typeof comment[], permission: 'admin', missingManifest: false, calls: [] as string[], prReads: 0, changeAfterFirstRead: false, }; - const encode = (value: unknown) => ({ - type: 'file', encoding: 'base64', size: 1000, - content: Buffer.from(JSON.stringify(value)).toString('base64'), - }); + const encode = (value: unknown) => { + const content = Buffer.from(JSON.stringify(value)); + return { + type: 'file', encoding: 'base64', size: content.length, + content: content.toString('base64'), + }; + }; const get = async (route: string, fields?: Record) => { state.calls.push(route); if (route.endsWith('/pulls/42')) { @@ -89,9 +137,14 @@ function fixture(relay = false) { if (state.changeAfterFirstRead && state.prReads > 1) pr.head.sha = BASE; return structuredClone(pr); } + if (route === `repos/${REPOSITORY}`) { + return { full_name: REPOSITORY, default_branch: 'dev' }; + } if (route.endsWith('/contents/.squad-review.json')) { expect(fields?.ref).toBe(HEAD); - if (state.missingManifest) throw new Error('404 missing committed attribution'); + if (state.missingManifest) { + throw Object.assign(new Error('Not Found'), { status: 404 }); + } return encode(attribution); } if (route.endsWith('/contents/.squad/casting/registry.json')) { @@ -100,8 +153,10 @@ function fixture(relay = false) { } if (route.endsWith('/reviews')) return state.reviews; if (route.endsWith('/actions/runs/17')) return run; + if (route.endsWith('/actions/runs/29')) return bootstrapRun; if (route.endsWith('/attempts/1')) return { ...run, run_attempt: 1, run_started_at: START }; if (/\/attempts\/[12]\/jobs$/.test(route)) return { jobs }; + if (route.endsWith(`/commits/${HEAD}/check-runs`)) return { check_runs: checkRuns }; if (route.endsWith('/comments')) return state.comments; if (route.endsWith('/permission')) return { permission: state.permission }; throw new Error(`Unexpected API route: ${route}`); @@ -111,10 +166,117 @@ function fixture(relay = false) { comment.body = `${OVERRIDE_PREFIX}${JSON.stringify(override)}`; }; sync(); - return { env, attribution, registry, pr, verdict, review, run, jobs, override, comment, state, get, sync }; + return { + env, attribution, registry, pr, verdict, review, run, bootstrapRun, jobs, checkRuns, + override, comment, + state, encode, get, sync, + }; +} + +function makeBootstrap(f: ReturnType) { + f.state.missingManifest = true; + f.pr.title = '[squad] Cast your Squad'; + f.pr.user = { login: 'github-actions[bot]', type: 'Bot' }; + f.pr.head.ref = 'squad/bootstrap-cast'; + f.pr.body = ``; + f.state.comments.push({ + user: { login: 'github-actions[bot]', type: 'Bot' }, + created_at: START, + updated_at: START, + body: `${f.pr.body}\nBase-controlled bootstrap provenance. Do not edit this comment.`, + }); + f.verdict.author_agent = '@squad/base-controlled-bootstrap'; + f.verdict.reviewer_agent = '@squad/base-controlled-review'; + f.sync(); } describe('independent Squad review guard', () => { + it('uses reserved workflow roles only for the base-controlled post-install bootstrap PR', async () => { + const f = fixture(); + makeBootstrap(f); + f.state.reviews = []; + await expect(reviewTarget(f.env, f.get)).resolves.toMatchObject({ + author_agent: '@squad/base-controlled-bootstrap', + reviewer_agent: '@squad/base-controlled-review', + }); + + const workspace = mkdtempSync(join(tmpdir(), 'squad-review-bootstrap-')); + workspaces.push(workspace); + const path = join(workspace, 'output.json'); + writeFileSync(path, JSON.stringify({ items: [{ + type: 'submit_pull_request_review', event: 'COMMENT', body: 'Bootstrap Cast reviewed.', + }] })); + await enforceReviewOutputs({ ...f.env, GH_AW_AGENT_OUTPUT: path }, f.get); + const output = JSON.parse(readFileSync(path, 'utf8')); + expect(output.items[0].body).toContain('"author_agent":"@squad/base-controlled-bootstrap"'); + expect(output.items[0].body).toContain( + '"reviewer_agent":"@squad/base-controlled-review"', + ); + }); + + it('refuses arbitrary first-install PRs even when they contain package-shaped claims', async () => { + const f = fixture(); + f.state.missingManifest = true; + f.pr.title = 'ci: add Squad agentic workflow'; + f.pr.body = `Package: bradygaster/squad/workflows@${HEAD}`; + await expect(reviewTarget(f.env, f.get)) + .rejects.toThrow('missing or duplicate base-controlled bootstrap PR provenance'); + }); + + it.each([ + ['branch', (f: ReturnType) => { f.pr.head.ref = 'attacker/bootstrap'; }], + ['title', (f: ReturnType) => { f.pr.title = 'Trusted bootstrap'; }], + ['author', (f: ReturnType) => { f.pr.user.login = 'attacker'; }], + ['head', (f: ReturnType) => { + f.pr.body = f.pr.body.replace(HEAD, BASE); + }], + ['base run', (f: ReturnType) => { f.bootstrapRun.head_sha = HEAD; }], + ['workflow', (f: ReturnType) => { + f.bootstrapRun.path = '.github/workflows/attacker.yml'; + }], + ['comment', (f: ReturnType) => { + f.state.comments[0].body = f.state.comments[0].body.replace(HEAD, BASE); + }], + ['comment author', (f: ReturnType) => { + f.state.comments[0].user.login = 'attacker'; + }], + ])('refuses a bootstrap activation with mutated %s provenance', async (_label, mutate) => { + const f = fixture(); + makeBootstrap(f); + mutate(f); + await expect(reviewTarget(f.env, f.get)).rejects.toThrow(); + }); + + it('requires successful base-controlled bootstrap completion at the clearing gate', async () => { + const f = fixture(); + makeBootstrap(f); + f.bootstrapRun.status = 'in_progress'; + f.bootstrapRun.conclusion = null; + await expect(reviewTarget(f.env, f.get)).resolves.toMatchObject({ + author_agent: '@squad/base-controlled-bootstrap', + }); + await expect(assertClearingReview(f.env, f.get)) + .rejects.toThrow('base-controlled bootstrap run did not complete successfully'); + }); + + it('does not rescue malformed attribution or non-404 reads', async () => { + const f = fixture(); + f.attribution.schema = 'wrong'; + await expect(reviewTarget(f.env, f.get)).rejects.toThrow('malformed committed'); + await expect(reviewTarget(f.env, async (route, fields) => { + if (route.endsWith('/contents/.squad-review.json')) { + throw Object.assign(new Error('Forbidden'), { status: 403 }); + } + return f.get(route, fields); + })).rejects.toThrow('Forbidden'); + }); + it('accepts a distinct, committed, current-head verdict and merged-head relay', async () => { for (const relay of [false, true]) { const f = fixture(relay); @@ -124,6 +286,43 @@ describe('independent Squad review guard', () => { } }); + it('ignores an ordinary-token forged check and accepts only the dedicated App check', async () => { + const f = fixture(true); + f.checkRuns.unshift({ + ...structuredClone(f.checkRuns[0]), + id: 87, + app: { id: 15368, slug: 'github-actions' }, + output: { + summary: JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + publisher_app_id: 15368, + publisher_app_slug: 'github-actions', + }), + }, + }); + await expect(assertClearingReview(f.env, f.get, { relay: true })) + .resolves.toEqual(f.verdict); + f.checkRuns.splice(1); + await expect(assertClearingReview(f.env, f.get, { relay: true })) + .rejects.toThrow('missing or duplicate exact-head authority check'); + }); + + it('refuses PR-controlled shaped review, job, check, and artifact evidence', async () => { + const f = fixture(true); + f.run.event = 'pull_request'; + f.run.head_sha = HEAD; + f.jobs[0].name = CHECK_NAME; + f.checkRuns[0].external_id = + `squad-review-authority/v1:${REPOSITORY}:42:${BASE}:${HEAD}`; + f.checkRuns[0].output.summary = JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + event: 'pull_request', + workflow_sha: HEAD, + }); + await expect(assertClearingReview(f.env, f.get, { relay: true })) + .rejects.toThrow('not bound to this PR workflow run'); + }); + it.each([ ['schema', 'other'], ['repository', 'other/repo'], ['issue', 10], ['issue', '9'], ['author_agent', 'missing'], ['reviewer_agent', 'missing'], @@ -151,11 +350,13 @@ describe('independent Squad review guard', () => { it.each([ ['schema', 'other'], ['repository', 'other/repo'], ['pull_request', 41], - ['head_sha', BASE], ['author_agent', 'reviewer'], ['reviewer_agent', 'implementer'], + ['base_sha', HEAD], ['head_sha', BASE], ['author_agent', 'reviewer'], + ['reviewer_agent', 'implementer'], ['result', 'APPROVE'], ['result', ''], ['timestamp', 'bad'], ['timestamp', '2026-09-28T12:05:00Z'], ['timestamp', '2026-09-28T11:00:00Z'], ['timestamp', '2026-02-30T12:01:00Z'], ['run_id', 0], ['run_id', '17'], ['run_attempt', 0], ['event', 'workflow_dispatch'], + ['workflow_path', '.github/workflows/attacker.yml'], ['workflow_sha', HEAD], ])('refuses verdict mutation %s=%s at the real relay', async (key, value) => { const f = fixture(true); Object.assign(f.verdict, { [key]: value }); @@ -179,8 +380,11 @@ describe('independent Squad review guard', () => { 'wrong-branch', 'duplicate-marker', 'stale-head', 'foreign-head', 'foreign-base', 'head-race', 'not-merged', 'wrong-base', 'merge-before-review', 'merge-before-check', 'failed-run', 'failed-check', 'missing-check', 'duplicate-check', 'wrong-check', + 'forged-check', 'actions-app-check', 'wrong-check-app', 'wrong-check-app-slug', + 'wrong-check-attestation', 'wrong-attested-app-id', 'wrong-attested-app-slug', 'manual-run', 'wrong-workflow', 'wrong-run-repo', 'wrong-run-sha', 'wrong-run-pr', 'wrong-run-attempt', 'wrong-run-title', 'verdict-before-run', + 'wrong-bot-id', 'wrong-bot-type', ])('fails closed for %s', async mutation => { const f = fixture(true); switch (mutation) { @@ -213,11 +417,36 @@ describe('independent Squad review guard', () => { case 'manual-run': f.run.event = 'workflow_dispatch'; break; case 'wrong-workflow': f.run.path = '.github/workflows/other.yml'; break; case 'wrong-run-repo': f.run.repository.full_name = 'other/repo'; break; - case 'wrong-run-sha': f.run.head_sha = BASE; break; + case 'wrong-run-sha': f.run.head_sha = HEAD; break; case 'wrong-run-pr': f.run.pull_requests[0].number = 43; break; case 'wrong-run-attempt': f.run.run_attempt = 0; break; case 'wrong-run-title': f.run.display_title = 'Squad review \u2014 PR #43'; break; case 'verdict-before-run': f.run.run_started_at = FINISHED; break; + case 'wrong-bot-id': f.review.user.id = 1; break; + case 'wrong-bot-type': f.review.user.type = 'User'; break; + case 'forged-check': f.checkRuns[0].external_id = 'forged'; break; + case 'actions-app-check': + f.checkRuns[0].app = { id: 15368, slug: 'github-actions' }; + f.checkRuns[0].output.summary = JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + publisher_app_id: 15368, + publisher_app_slug: 'github-actions', + }); + break; + case 'wrong-check-app': f.checkRuns[0].app.id = 1; break; + case 'wrong-check-app-slug': f.checkRuns[0].app.slug = 'other-review-app'; break; + case 'wrong-attested-app-id': f.checkRuns[0].output.summary = JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + publisher_app_id: 1, + }); break; + case 'wrong-attested-app-slug': f.checkRuns[0].output.summary = JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + publisher_app_slug: 'other-review-app', + }); break; + case 'wrong-check-attestation': f.checkRuns[0].output.summary = JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + event: 'pull_request', + }); break; } await expect(assertClearingReview(f.env, f.get, { relay: true })).rejects.toThrow(); }); @@ -225,7 +454,7 @@ describe('independent Squad review guard', () => { it('does not accept a manual gate or the merge commit as the reviewed head', async () => { const f = fixture(true); await expect(assertClearingReview({ ...f.env, GITHUB_EVENT_NAME: 'workflow_dispatch' }, f.get, { relay: true })) - .rejects.toThrow('only PR runs'); + .rejects.toThrow('only base-controlled PR target runs'); await expect(reviewTarget({ ...f.env, SQUAD_REVIEW_HEAD: BASE }, f.get, { relay: true })) .rejects.toThrow('head changed'); }); @@ -246,6 +475,10 @@ describe('independent Squad review guard', () => { f.state.comments = [f.comment]; f.state.comments.push({ ...f.comment, body: `${OVERRIDE_PREFIX}${JSON.stringify({ ...f.override, head_sha: BASE })}` }); f.run.run_attempt = 2; + f.checkRuns[0].output.summary = JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + run_attempt: 2, + }); await expect(assertClearingReview(f.env, f.get, { relay: true })).resolves.toEqual(f.verdict); expect(f.state.calls.some(route => route.endsWith('/attempts/2/jobs'))).toBe(true); }); @@ -325,7 +558,7 @@ describe('independent Squad review guard', () => { expect(output.items[0].body).toContain('"result":"REQUEST_CHANGES"'); }); - it('never mints clearing evidence on a manual run', async () => { + it('refuses manual runs before reading or writing review output', async () => { const f = fixture(); f.state.reviews = []; const workspace = mkdtempSync(join(tmpdir(), 'squad-review-manual-')); @@ -334,16 +567,13 @@ describe('independent Squad review guard', () => { writeFileSync(path, JSON.stringify({ items: [{ type: 'submit_pull_request_review', event: 'REQUEST_CHANGES', body: 'Diagnostic.', }] })); - await enforceReviewOutputs({ + await expect(enforceReviewOutputs({ ...f.env, GITHUB_EVENT_NAME: 'workflow_dispatch', GH_AW_AGENT_OUTPUT: path, - }, f.get); - const output = JSON.parse(readFileSync(path, 'utf8')); - expect(output.items[0].event).toBe('COMMENT'); - expect(output.items[0].body).not.toContain(VERDICT_PREFIX); - expect(output.items[0].body).toContain('diagnostic only'); + }, f.get)).rejects.toThrow('only base-controlled PR target runs'); + expect(JSON.parse(readFileSync(path, 'utf8')).items[0].body).toBe('Diagnostic.'); }); - it('deduplicates only a validated existing verdict, never a marker-shaped claim', async () => { + it('deduplicates only evidence from the exact run attempt', async () => { const f = fixture(); const workspace = mkdtempSync(join(tmpdir(), 'squad-review-dedup-')); workspaces.push(workspace); @@ -355,6 +585,13 @@ describe('independent Squad review guard', () => { type: 'submit_pull_request_review', event: 'COMMENT', body: 'Duplicate.', }] })); await expect(enforceReviewOutputs(env, f.get)).rejects.toThrow('already has a verdict'); + f.verdict.run_attempt = 2; + f.sync(); + writeFileSync(path, JSON.stringify({ items: [{ + type: 'submit_pull_request_review', event: 'COMMENT', body: 'New attempt.', + }] })); + await expect(enforceReviewOutputs(env, f.get)).resolves.toBeUndefined(); + expect(readFileSync(path, 'utf8')).toContain('\\"run_attempt\\":1'); f.review.body = `${VERDICT_PREFIX}{broken`; writeFileSync(path, JSON.stringify({ items: [{ type: 'noop' }] })); await expect(enforceReviewOutputs(env, f.get)).rejects.toThrow(); diff --git a/test/gh-aw-review-workflow.test.ts b/test/gh-aw-review-workflow.test.ts index bbccd9b61..ee6bc7700 100644 --- a/test/gh-aw-review-workflow.test.ts +++ b/test/gh-aw-review-workflow.test.ts @@ -91,7 +91,16 @@ function assertReviewerContract(workflow: string): void { expect(submitReview).not.toContain('APPROVE'); expect(concurrency).toContain('cancel-in-progress: true'); expect(trigger).not.toMatch(/^\s+forks:/m); + expect(trigger).not.toContain('workflow_dispatch:'); + expect(trigger).toMatch(/pull_request_target:/); + expect(trigger).not.toMatch(/^\s+pull_request:/m); + expect(yaml).toContain('checkout: false'); + expect(yaml).toContain('strict: false'); expect(yaml).toContain('github.event.pull_request.head.repo.full_name == github.repository'); + expect(yaml).toContain('SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }}'); + expect(yaml).toContain('ref: ${{ github.event.pull_request.base.sha }}'); + expect(yaml).not.toContain('ref: ${{ github.workflow_sha }}'); + expect(yaml).not.toContain('github.event.inputs'); expect(workflow).toContain('Squad-Review-Head: {40-character lowercase head SHA}'); expect(rows).toEqual([ '1:One validated durable worker marker:Squad-authored', @@ -104,6 +113,11 @@ function assertReviewerContract(workflow: string): void { expect(workflow).toContain('inlined-imports: true'); expect(workflow).toContain('await guard.enforceReviewOutputs'); expect(workflow).toContain('await guard.assertClearingReview'); + expect(workflow).toContain('Squad Review Authority / attest'); + expect(workflow).toContain('Publish exact-head required check'); + expect(workflow).toContain("run.event !== 'pull_request_target'"); + expect(workflow).toContain('The workflow-installation PR is an explicit human trust boundary.'); + expect(workflow).toContain('Trusted review starts on the automatic post-merge Cast PR.'); expect(workflow).toContain('Human approval remains mandatory.'); } @@ -112,6 +126,84 @@ interface CompiledContract { safeOutputs: Record>; } +async function executePublisher( + script: string, + { + publishedApp, + existing = [], + updateError, + }: { + publishedApp: { id: number; slug: string }; + existing?: Array>; + updateError?: Error; + }, +): Promise<{ failures: string[]; created: number; updated: number; deleted: number }> { + const failures: string[] = []; + let created = 0; + let updated = 0; + let deleted = 0; + const listJobs = async () => undefined; + const listChecks = async () => undefined; + const github = { + paginate: async (method: unknown) => method === listJobs + ? [{ name: 'Squad Review Authority / attest', conclusion: 'success' }] + : existing, + rest: { + actions: { + getWorkflowRun: async () => ({ data: { + event: 'pull_request_target', + path: '.github/workflows/squad-review.lock.yml', + head_sha: 'b'.repeat(40), + repository: { full_name: 'squad/example' }, + } }), + listJobsForWorkflowRunAttempt: listJobs, + }, + checks: { + listForRef: listChecks, + create: async () => { + created++; + return { data: { id: 88, app: publishedApp } }; + }, + update: async () => { + updated++; + if (updateError) throw updateError; + return { data: { id: 88, app: publishedApp } }; + }, + delete: async () => { + deleted++; + return { data: {} }; + }, + }, + }, + }; + const core = { setFailed: (message: string) => failures.push(message) }; + const previous = { ...process.env }; + Object.assign(process.env, { + AUTHORITY_RESULT: 'success', + GITHUB_REPOSITORY: 'squad/example', + GITHUB_RUN_ID: '17', + GITHUB_RUN_ATTEMPT: '1', + GITHUB_SERVER_URL: 'https://github.com', + SQUAD_REVIEW_APP_ID: '424242', + SQUAD_REVIEW_APP_SLUG: 'squad-review-authority', + SQUAD_REVIEW_PR: '42', + SQUAD_REVIEW_BASE: 'b'.repeat(40), + SQUAD_REVIEW_HEAD: 'a'.repeat(40), + SQUAD_REVIEW_WORKFLOW_SHA: 'b'.repeat(40), + }); + try { + const run = new Function( + 'github', + 'core', + `return (async () => {\n${script}\n})();`, + ) as (github: unknown, core: unknown) => Promise; + await run(github, core); + } finally { + process.env = previous; + } + return { failures, created, updated, deleted }; +} + function compileReviewer(workflow = REVIEWER): CompiledContract { const workspace = mkdtempSync(resolve(ROOT, '.squad-review-contract-')); compileWorkspaces.push(workspace); @@ -145,9 +237,11 @@ afterAll(() => { function assertCompiledGate(lock: string): void { const workflow = parse(lock); const { jobs } = workflow; - expect(workflow['run-name']).toBe('Squad review — PR #${{ github.event.inputs.issue_number || github.event.pull_request.number }}'); + expect(workflow.on).toHaveProperty('pull_request_target'); + expect(workflow.on).not.toHaveProperty('pull_request'); + expect(workflow['run-name']).toBe('Squad review — PR #${{ github.event.pull_request.number }}'); const review = jobs.review; - expect(review.name).toBe("${{ github.event_name == 'pull_request' && 'Squad Review / review' || 'Squad Review / manual' }}"); + expect(review.name).toBe('Squad Review Authority / attest'); expect(review.if).toBe('always()'); expect(review.needs).toEqual(expect.arrayContaining(['agent', 'safe_outputs'])); const execution = review.steps.find((step: { name: string }) => step.name === 'Require successful PR review execution'); @@ -155,6 +249,7 @@ function assertCompiledGate(lock: string): void { expect(execution.run).toContain('test "$OUTPUT_RESULT" = success'); expect(review.steps.at(-1).with.script).toContain('await guard.assertClearingReview'); expect(review.steps.at(-1).env.SQUAD_REVIEW_HEAD).toBe('${{ github.event.pull_request.head.sha }}'); + expect(review.steps.at(-1).env.SQUAD_REVIEW_WORKFLOW_SHA).toBe('${{ github.workflow_sha }}'); const steps = jobs.safe_outputs.steps; const guard = steps.findIndex((step: { name: string }) => step.name === 'Bind review output to committed agent identities and current head'); const process = steps.findIndex((step: { name: string }) => step.name === 'Process Safe Outputs'); @@ -165,20 +260,65 @@ function assertCompiledGate(lock: string): void { expect(steps[guard]['continue-on-error']).toBeUndefined(); const baseCheckout = steps.find((step: { name: string }) => step.name === 'Checkout base commit for review guard'); - const workflowCheckout = steps.find((step: { name: string }) => - step.name === 'Checkout workflow commit for first-install review guard'); - expect(baseCheckout.with.ref).toBe('${{ github.event.pull_request.base.sha || github.workflow_sha }}'); - expect(workflowCheckout.with.ref).toBe('${{ github.workflow_sha }}'); - expect(steps[guard].with.script).toContain('if (existsSync(baseGuard))'); - expect(steps[guard].with.script).toContain('else if (!existsSync(baseManifest))'); - expect(steps[guard].with.script).toContain('missing from an established base installation'); + expect(baseCheckout.with.ref).toBe('${{ github.event.pull_request.base.sha }}'); + expect(steps.some((step: { name: string }) => + step.name.includes('workflow commit'))).toBe(false); + expect(steps[guard].with.script).toContain('!existsSync(baseGuard) || !existsSync(baseManifest)'); + expect(steps[guard].with.script).toContain('First-install manual boundary'); + expect(steps[guard].with.script).toContain('pathToFileURL(baseGuard)'); + expect(steps[guard].with.script).not.toContain('github.workflow_sha'); + expect(steps[guard].with.script).not.toContain('.squad-review-workflow'); + expect(steps[guard].with.script).not.toContain('Squad-Review-Verdict:'); const finalGate = review.steps.find((step: { name: string }) => step.name === 'Enforce independent current-head verdict'); - expect(finalGate.with.script).toContain('if (existsSync(baseGuard))'); - expect(finalGate.with.script).toContain('else if (!existsSync(baseManifest))'); - expect(finalGate.with.script).toContain('missing from an established base installation'); + expect(finalGate.with.script).toContain('!existsSync(baseGuard) || !existsSync(baseManifest)'); + expect(finalGate.with.script).toContain('First-install manual boundary'); + expect(finalGate.with.script).toContain('pathToFileURL(baseGuard)'); + expect(finalGate.with.script).not.toContain('github.workflow_sha'); + expect(finalGate.with.script).not.toContain('.squad-review-workflow'); + expect(finalGate.with.script).not.toContain('Squad-Review-Verdict:'); for (const step of review.steps) expect(step['continue-on-error']).toBeUndefined(); expect(review['continue-on-error']).toBeUndefined(); + const publish = jobs.publish; + expect(publish.name).toBe('Publish Squad Review required check'); + expect(publish.if).toBe('always()'); + expect(publish.needs).toEqual(expect.arrayContaining(['agent', 'safe_outputs', 'review'])); + expect(publish.environment).toBe('squad-review-authority'); + expect(publish.permissions).toMatchObject({ + actions: 'read', + contents: 'read', + 'pull-requests': 'read', + }); + expect(publish.permissions.checks).toBeUndefined(); + const validateStep = publish.steps.find((step: { name: string }) => + step.name === 'Validate dedicated reviewer App configuration'); + expect(validateStep.env.SQUAD_REVIEW_APP_ID).toBe('${{ vars.SQUAD_REVIEW_APP_ID }}'); + expect(validateStep.env.SQUAD_REVIEW_APP_SLUG).toBe('${{ vars.SQUAD_REVIEW_APP_SLUG }}'); + expect(validateStep.env.SQUAD_REVIEW_APP_OWNER).toBe('${{ vars.SQUAD_REVIEW_APP_OWNER }}'); + expect(validateStep.env.SQUAD_REVIEW_APP_PRIVATE_KEY) + .toBe('${{ secrets.SQUAD_REVIEW_APP_PRIVATE_KEY }}'); + expect(validateStep.run).toContain('test "${SQUAD_REVIEW_APP_ID}" != "15368"'); + expect(validateStep.run).toContain('test "${SQUAD_REVIEW_APP_SLUG}" != "github-actions"'); + const mintStep = publish.steps.find((step: { name: string }) => + step.name === 'Mint dedicated reviewer App token'); + expect(mintStep.uses).toMatch(/^actions\/create-github-app-token@[0-9a-f]{40}$/); + expect(mintStep['continue-on-error']).toBeUndefined(); + const publishStep = publish.steps.find((step: { name: string }) => + step.name === 'Publish exact-head required check'); + expect(publishStep.with['github-token']) + .toBe('${{ steps.squad-review-app-token.outputs.token }}'); + expect(publishStep.with.script).toContain("const checkName = 'Squad Review / review'"); + expect(publishStep.with.script).toContain("run.event !== 'pull_request_target'"); + expect(publishStep.with.script).toContain('run.head_sha !== workflowSha'); + expect(publishStep.with.script).toContain('authorityJobs.length !== 1'); + expect(publishStep.with.script).toContain("external_id: externalId"); + expect(publishStep.with.script).toContain("head_sha: headSha"); + expect(publishStep.with.script).toContain('published.data.app?.id !== expectedAppId'); + expect(publishStep.with.script).toContain('publisher_app_id: expectedAppId'); + expect(publishStep.with.script).toContain('publisher_app_slug: expectedAppSlug'); + expect(publishStep.with.script).not.toContain('github.event.pull_request.head.ref'); + expect(lock).not.toContain('Checkout PR branch'); + expect(lock).not.toMatch(/uses:\s+\.\/\.github\/actions\//); } function compiledGuardScripts(lock: string): Array<{ name: string; script: string }> { @@ -200,9 +340,9 @@ async function executeCompiledGuardLoader( { baseGuard, baseManifest = false, - workflowGuard, + dispatchGuard, head = 'a'.repeat(40), - }: { baseGuard?: string; baseManifest?: boolean; workflowGuard: string; head?: string }, + }: { baseGuard?: string; baseManifest?: boolean; dispatchGuard?: string; head?: string }, ): Promise { const workspace = mkdtempSync(resolve(ROOT, '.squad-review-loader-')); compileWorkspaces.push(workspace); @@ -222,10 +362,17 @@ async function executeCompiledGuardLoader( mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, '{}\n'); } - const workflowPath = resolve(workspace, '.squad-review-workflow', guardPath); - mkdirSync(dirname(workflowPath), { recursive: true }); - writeFileSync(workflowPath, workflowGuard); - + if (dispatchGuard !== undefined) { + const path = resolve( + workspace, + '.github', + 'workflows', + 'shared', + 'squad-review-guard.mjs', + ); + mkdirSync(dirname(path), { recursive: true }); + writeFileSync(path, dispatchGuard); + } const previousWorkspace = process.env.GITHUB_WORKSPACE; const previousOutput = process.env.SQUAD_TEST_GUARD_OUTPUT; const previousHead = process.env.SQUAD_REVIEW_HEAD; @@ -253,32 +400,59 @@ async function executeCompiledGuardLoader( } describe('gh-aw enforcing Squad reviewer', () => { - it('routes /squad review to the isolated workflow and supports automatic PR events', () => { + it('rejects ordinary-token publication and accepts the dedicated App identity', async () => { + const { lock } = compileReviewer(); + const workflow = parse(lock); + const publishStep = workflow.jobs.publish.steps.find((step: { name: string }) => + step.name === 'Publish exact-head required check'); + const ordinary = await executePublisher(publishStep.with.script, { + publishedApp: { id: 15368, slug: 'github-actions' }, + }); + expect(ordinary).toEqual({ + failures: ['Squad review check was not published by the configured dedicated GitHub App.'], + created: 1, + updated: 0, + deleted: 1, + }); + const dedicated = await executePublisher(publishStep.with.script, { + publishedApp: { id: 424242, slug: 'squad-review-authority' }, + }); + expect(dedicated).toEqual({ failures: [], created: 1, updated: 0, deleted: 0 }); + }); + + it('cannot update the dedicated App check with an ordinary workflow token', async () => { + const { lock } = compileReviewer(); + const workflow = parse(lock); + const publishStep = workflow.jobs.publish.steps.find((step: { name: string }) => + step.name === 'Publish exact-head required check'); + await expect(executePublisher(publishStep.with.script, { + publishedApp: { id: 15368, slug: 'github-actions' }, + existing: [{ + id: 88, + external_id: `squad-review-authority/v1:squad/example:42:${'b'.repeat(40)}:${'a'.repeat(40)}`, + app: { id: 424242, slug: 'squad-review-authority' }, + }], + updateError: Object.assign(new Error('Resource not accessible by integration'), { status: 403 }), + })).rejects.toMatchObject({ status: 403 }); + }); + + it('keeps review automatic and makes /squad review a non-dispatching rerun guide', () => { const routerDispatch = yamlBlock(ROUTER_FRONTMATTER, 'dispatch-workflow'); const reviewTrigger = yamlBlock(REVIEWER_FRONTMATTER, 'on'); const relay = ROUTER.match(/## skill: `squad-review-relay`([\s\S]*?)(?=\n## skill:)/)?.[1] ?? ''; - const relayPayload = JSON.parse(relay.match(/```json\n([\s\S]*?)\n```/)?.[1] ?? '{}') as { - workflow_name?: string; - inputs?: Record; - issue_number?: string; - }; - expect(listInBlock(routerDispatch, 'workflows')).toContain('squad-review'); + expect(listInBlock(routerDispatch, 'workflows')).not.toContain('squad-review'); + expect(ROUTER_FRONTMATTER).toContain('actions: read'); expect(ROUTER).toContain('| `/squad review` | Review Relay |'); expect(REVIEWER).not.toContain('slash_command:'); - expect(reviewTrigger).toMatch(/workflow_dispatch:\n\s+inputs:/); - expect(reviewTrigger).toMatch(/pull_request:\n\s+types: \[opened, reopened, ready_for_review, synchronize\]/); - expect(relayPayload).toEqual({ - workflow_name: 'squad-review', - inputs: { - issue_number: '{pull-request-number}', - expected_head_sha: '{current-head-sha}', - request_origin: 'manual', - }, - }); - expect(relayPayload.issue_number).toBeUndefined(); - expect(relay).not.toContain('"pr_number"'); - expect(relay).toContain('Never call the generic'); + expect(reviewTrigger).toMatch(/pull_request_target:\n\s+types: \[opened, reopened, ready_for_review, synchronize\]/); + expect(reviewTrigger).not.toContain('workflow_dispatch:'); + expect(relay).toContain('.github/workflows/squad-review.lock.yml'); + expect(relay).toContain('exact current PR head'); + expect(relay).toMatch(/require\s+exactly one job named `Squad Review Authority \/ attest`/); + expect(relay).toMatch(/command did not rerun it\./); + expect(relay).toMatch(/no base-controlled automatic review run exists for\s+the exact head/); + expect(relay).not.toContain('dispatch-workflow'); }); it('limits slash commands to issue and pull request conversation surfaces', () => { @@ -390,13 +564,13 @@ describe('gh-aw enforcing Squad reviewer', () => { const concurrency = yamlBlock(REVIEWER_FRONTMATTER, 'concurrency'); expect(concurrency).toContain( - 'group: "squad-review-${{ github.event.inputs.issue_number || github.event.pull_request.number || github.run_id }}"', + 'group: "squad-review-${{ github.event.pull_request.number }}"', ); expect(concurrency).toContain('cancel-in-progress: true'); expect(REVIEWER_FRONTMATTER).not.toMatch(/^\s+forks:/m); expect(REVIEWER).toContain('If an existing bot review contains a `Squad-Review-Verdict:` record'); - expect(REVIEWER).toContain('Never re-review an unchanged head'); - expect(REVIEWER).toContain('Re-fetch the pull request immediately before emitting'); + expect(REVIEWER).toContain('Evidence from a different run or attempt cannot deduplicate'); + expect(REVIEWER).toMatch(/Re-fetch the pull request\s+immediately before emitting/); }); it('covers acceptance, routing, protected files, tests, and changesets', () => { @@ -429,25 +603,29 @@ describe('gh-aw enforcing Squad reviewer', () => { expect(safeOutputs.submit_pull_request_review).toMatchObject({ max: 1, allowed_events: ['COMMENT', 'REQUEST_CHANGES'], - commit_id: '${{ github.event.pull_request.head.sha || github.event.inputs.expected_head_sha }}', + commit_id: '${{ github.event.pull_request.head.sha }}', }); expect(safeOutputs).not.toHaveProperty('dispatch_workflow'); expect(safeOutputs).not.toHaveProperty('create_issue'); expect(safeOutputs).not.toHaveProperty('create_pull_request'); expect(lock).toContain('GH_AW_HEAD_SHA: ${{ github.event.pull_request.head.sha }}'); + expect(lock).toContain('pull_request_target:'); + expect(lock).not.toContain('Checkout PR branch'); }, 30000); - it('executes the compiled first-install fallback without weakening established base control', async () => { + it('loads review authority only from the base and makes first install a manual boundary', async () => { const { lock } = compileReviewer(); const stub = (source: string) => ` import { writeFileSync } from 'node:fs'; export async function enforceReviewOutputs(env) { writeFileSync(process.env.SQUAD_TEST_GUARD_OUTPUT, - JSON.stringify({ source: ${JSON.stringify(source)}, operation: 'safe outputs', head: env.SQUAD_REVIEW_HEAD })); + JSON.stringify({ source: ${JSON.stringify(source)}, operation: 'safe outputs', + head: env.SQUAD_REVIEW_HEAD })); } export async function assertClearingReview(env) { writeFileSync(process.env.SQUAD_TEST_GUARD_OUTPUT, - JSON.stringify({ source: ${JSON.stringify(source)}, operation: 'final verdict', head: env.SQUAD_REVIEW_HEAD })); + JSON.stringify({ source: ${JSON.stringify(source)}, operation: 'final verdict', + head: env.SQUAD_REVIEW_HEAD })); } `; @@ -456,37 +634,69 @@ describe('gh-aw enforcing Squad reviewer', () => { ? 'edd6fbf0f84334ff086ed2bc8bbfed5503fdd56f' : '9a898b5182ca432b62bef26dbf1f9022dd1d256b'; await expect(executeCompiledGuardLoader(script, { - workflowGuard: stub('workflow'), + dispatchGuard: stub('dispatch-ref'), head, - })).resolves.toBe(JSON.stringify({ source: 'workflow', operation: name, head })); + })).rejects.toThrow('First-install manual boundary'); await expect(executeCompiledGuardLoader(script, { baseGuard: stub('base'), baseManifest: true, - workflowGuard: stub('workflow'), + dispatchGuard: stub('dispatch-ref'), head, - })).resolves.toBe(JSON.stringify({ source: 'base', operation: name, head })); + })).resolves.toBe(JSON.stringify({ + source: 'base', + operation: name, + head, + })); await expect(executeCompiledGuardLoader(script, { baseManifest: true, - workflowGuard: stub('workflow'), head, - })).rejects.toThrow( - 'Squad Review guard is missing from an established base installation. Refusing workflow-source fallback.', - ); + })).rejects.toThrow('First-install manual boundary'); await expect(executeCompiledGuardLoader(script, { baseGuard: 'this is not valid JavaScript', baseManifest: true, - workflowGuard: stub('workflow'), head, })).rejects.toThrow(); } }, 30000); + it('does not embed a PR-controlled guard, verdict, or trusted fallback in emitted loaders', () => { + const { lock } = compileReviewer(); + for (const { script } of compiledGuardScripts(lock)) { + expect(script).toContain('pathToFileURL(baseGuard)'); + expect(script).not.toContain('.squad-review-workflow'); + expect(script).not.toContain('workflowGuard'); + expect(script).not.toContain('Squad-Review-Verdict:'); + expect(script).not.toContain('@squad/bootstrap-installation'); + } + }, 30000); + + it('rejects compiled PR-head checkout, local action, and PR-trigger authority mutations', () => { + const mutations = [ + REVIEWER.replace( + 'ref: ${{ github.event.pull_request.base.sha }}', + 'ref: ${{ github.event.pull_request.head.sha }}', + ), + REVIEWER.replace( + "uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0", + 'uses: ./.github/actions/pr-controlled', + ), + REVIEWER.replace('pull_request_target:', 'pull_request:'), + ]; + for (const [index, mutation] of mutations.entries()) { + expect(mutation, `compiled adversarial mutation ${index} must change the source`) + .not.toBe(REVIEWER); + const { lock } = compileReviewer(mutation); + expect(() => assertCompiledGate(lock), `compiled adversarial mutation ${index}`) + .toThrow(); + } + }, 60000); + it('kills mutations of every important authority and provenance gate', () => { const mutations = [ - REVIEWER.replace('tools:\n bash:', 'tools:\n edit:\n bash:'), + REVIEWER.replace('tools:\n github:', 'tools:\n edit:\n github:'), REVIEWER.replace( 'safe-outputs:\n', 'safe-outputs:\n dispatch-workflow:\n workflows: [squad-retro]\n max: 1\n', @@ -504,11 +714,21 @@ describe('gh-aw enforcing Squad reviewer', () => { REVIEWER.replace('invalid provenance. Fail closed with', 'invalid provenance. Continue with'), REVIEWER.replace('Every same-repository PR (including', 'Some PRs (including'), REVIEWER.replace('inlined-imports: true', 'inlined-imports: false'), + REVIEWER.replace( + 'on:\n pull_request_target:', + 'on:\n workflow_dispatch:\n pull_request_target:', + ), + REVIEWER.replace( + 'ref: ${{ github.event.pull_request.base.sha }}', + 'ref: ${{ github.workflow_sha }}', + ), + REVIEWER.replace('checkout: false', 'checkout: true'), + REVIEWER.replace('pull_request_target:', 'pull_request:'), REVIEWER.replaceAll('Squad-Review-Head: {40-character lowercase head SHA}', 'Reviewed head SHA'), ]; - for (const mutation of mutations) { - expect(() => assertReviewerContract(mutation)).toThrow(); + for (const [index, mutation] of mutations.entries()) { + expect(() => assertReviewerContract(mutation), `source mutation ${index}`).toThrow(); } }); @@ -517,9 +737,19 @@ describe('gh-aw enforcing Squad reviewer', () => { const mutations = [ REVIEWER.replace('await guard.enforceReviewOutputs', 'void guard.enforceReviewOutputs'), REVIEWER.replace('await guard.assertClearingReview', 'void guard.assertClearingReview'), - REVIEWER.replace("&& 'Squad Review / review'", "&& 'Other check'"), + REVIEWER.replace(' name: Squad Review Authority / attest', ' name: Other check'), + REVIEWER.replace('pathToFileURL(baseGuard)', "pathToFileURL('.squad-review-workflow/guard.mjs')"), + REVIEWER.replace('No trusted Squad verdict was emitted.', 'Squad-Review-Verdict: trusted'), REVIEWER.replace(' if: always()\n', ' if: success()\n'), REVIEWER.replace(' needs: [agent, safe_outputs]', ' needs: [agent]'), + REVIEWER.replace( + "run.event !== 'pull_request_target'", + "run.event !== 'pull_request'", + ), + REVIEWER.replace( + "uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0", + "uses: ./.github/actions/pr-controlled", + ), ]; for (const mutation of mutations) { expect(mutation).not.toBe(REVIEWER); diff --git a/test/helpers/gh-aw-install-fixture.ts b/test/helpers/gh-aw-install-fixture.ts new file mode 100644 index 000000000..ba993bd7a --- /dev/null +++ b/test/helpers/gh-aw-install-fixture.ts @@ -0,0 +1,177 @@ +import { + cpSync, + mkdirSync, + mkdtempSync, + readFileSync, + rmSync, + writeFileSync, +} from 'node:fs'; +import { createHash } from 'node:crypto'; +import { execFileSync } from 'node:child_process'; +import { dirname, resolve } from 'node:path'; +import { + CONTRACT_DESTINATION, + CONTRACT_SOURCE, + PACKAGE_NAME, +} from '../../workflows/shared/squad-install-verifier.mjs'; + +interface ContractEntry { + source: string; + destination: string; + sha256: string; +} + +interface WorkflowEntry extends ContractEntry { + name: string; + lock: string; + source_sha256: string; + lock_sha256: string; +} + +interface RuntimeEntry extends ContractEntry { + path: string; + package_destination: string; + ownership: string; +} + +interface SkillEntry extends ContractEntry { + name: string; +} + +export interface InstallFixture { + manifest: { + workflows: WorkflowEntry[]; + shared_runtime: RuntimeEntry[]; + skills: SkillEntry[]; + }; + provenance: { + schemaVersion: number; + package: string; + source: string; + resolvedCommit: string; + installer: string; + files: ContractEntry[]; + }; + consumerFiles: Map; + canonicalFiles: Map; +} + +const fixtureCache = new Map(); + +function cloneFixture(fixture: InstallFixture): InstallFixture { + return { + manifest: structuredClone(fixture.manifest), + provenance: structuredClone(fixture.provenance), + consumerFiles: new Map([...fixture.consumerFiles].map( + ([path, content]) => [path, Buffer.from(content)], + )), + canonicalFiles: new Map([...fixture.canonicalFiles].map( + ([path, content]) => [path, Buffer.from(content)], + )), + }; +} + +function sha256(content: Buffer): string { + return createHash('sha256').update(content).digest('hex'); +} + +function withSource(content: Buffer, source: string, revision: string): Buffer { + const text = content.toString('utf8'); + const marker = '\n---\n'; + const end = text.indexOf(marker, 4); + if (!text.startsWith('---\n') || end < 0) throw new Error(`Invalid workflow source: ${source}`); + return Buffer.from( + `${text.slice(0, end)}\nsource: bradygaster/squad/${source}@${revision}${text.slice(end)}`, + ); +} + +export function githubFile(content: Buffer): { + type: string; + encoding: string; + size: number; + content: string; +} { + return { + type: 'file', + encoding: 'base64', + size: content.length, + content: content.toString('base64'), + }; +} + +export function createFirstInstallFixture(revision: string): InstallFixture { + const cached = fixtureCache.get(revision); + if (cached) return cloneFixture(cached); + const root = process.cwd(); + const manifestBytes = readFileSync(resolve(root, CONTRACT_SOURCE)); + const manifest = JSON.parse(manifestBytes.toString('utf8')); + const consumerFiles = new Map([[CONTRACT_DESTINATION, manifestBytes]]); + const canonicalFiles = new Map([[CONTRACT_SOURCE, manifestBytes]]); + const scratch = mkdtempSync(resolve(root, '.squad-install-fixture-')); + try { + const workflowRoot = resolve(scratch, '.github/workflows'); + mkdirSync(workflowRoot, { recursive: true }); + cpSync(resolve(root, 'workflows/shared'), resolve(workflowRoot, 'shared'), { recursive: true }); + + for (const entry of manifest.workflows as WorkflowEntry[]) { + const canonical = readFileSync(resolve(root, entry.source)); + canonicalFiles.set(entry.source, canonical); + const installed = withSource(canonical, entry.source, revision); + consumerFiles.set(entry.destination, installed); + const path = resolve(scratch, entry.destination); + mkdirSync(dirname(path), { recursive: true }); + writeFileSync(path, installed); + } + execFileSync('git', ['init', '--quiet'], { cwd: scratch }); + execFileSync('gh', ['aw', 'compile', '--strict', '--no-check-update'], { + cwd: scratch, + stdio: 'pipe', + timeout: 120_000, + }); + for (const entry of manifest.workflows as WorkflowEntry[]) { + consumerFiles.set(entry.lock, readFileSync(resolve(scratch, entry.lock))); + } + + for (const entry of manifest.shared_runtime as RuntimeEntry[]) { + const canonical = readFileSync(resolve(root, entry.source)); + canonicalFiles.set(entry.source, canonical); + consumerFiles.set(entry.package_destination, canonical); + } + for (const entry of manifest.skills as SkillEntry[]) { + const canonical = readFileSync(resolve(root, entry.source)); + canonicalFiles.set(entry.source, canonical); + consumerFiles.set(entry.destination, canonical); + } + + const owned = [ + ...(manifest.workflows as WorkflowEntry[]).map( + ({ source, destination }) => ({ source, destination }), + ), + ...(manifest.shared_runtime as RuntimeEntry[]).map( + ({ source, package_destination: destination }) => ({ source, destination }), + ), + { source: CONTRACT_SOURCE, destination: CONTRACT_DESTINATION }, + ].sort((left, right) => left.destination.localeCompare(right.destination)); + const files = owned.map(entry => ({ + ...entry, + sha256: sha256(consumerFiles.get(entry.destination)!), + })); + const fixture = { + manifest, + provenance: { + schemaVersion: 1, + package: PACKAGE_NAME, + source: `${PACKAGE_NAME}@${revision}`, + resolvedCommit: revision, + installer: 'gh-aw v0.89.21 test', + files, + }, + consumerFiles, + canonicalFiles, + }; + fixtureCache.set(revision, fixture); + return cloneFixture(fixture); + } finally { + rmSync(scratch, { recursive: true, force: true }); + } +} diff --git a/test/standalone-release-workflow.test.ts b/test/standalone-release-workflow.test.ts index cd0f44125..68f7eb2cf 100644 --- a/test/standalone-release-workflow.test.ts +++ b/test/standalone-release-workflow.test.ts @@ -707,6 +707,8 @@ describe('automated package publication', () => { expect(ghAwGuide).toContain('`.vscode/settings.json`'); expect(ghAwGuide).toContain('SQUAD_GITHUB_APP_PRIVATE_KEY'); expect(ghAwGuide).toContain('SQUAD_GITHUB_TOKEN'); + expect(ghAwGuide).toContain('SQUAD_REVIEW_APP_PRIVATE_KEY'); + expect(ghAwGuide).toContain('squad-review-authority'); expect(ghAwGuide).toContain('both slash-command and `github-actions[bot]`'); expect(ghAwGuide).toContain('The completion comment links the created Cast PR'); expect(ghAwGuide).toContain('application CI is `action_required`'); diff --git a/workflows/package/squad-bootstrap.md b/workflows/package/squad-bootstrap.md index ef2a0cb15..216ffc9a8 100644 --- a/workflows/package/squad-bootstrap.md +++ b/workflows/package/squad-bootstrap.md @@ -151,7 +151,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "a8206bd6f8605915bd284b219a66db623eb2ee09a44a0ac51dd4304aed9d8b57" + check_hash "$install_verifier" "4f385df488cc65165e398e499663c015ce63851cb9c938f4c3dd0af38d25f991" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS @@ -474,14 +474,46 @@ safe-outputs: || pullRequestDetails.head.repo?.full_name !== provenance.repository) { throw new Error('Trusted bootstrap provenance inputs or Cast PR head identity are invalid.'); } - const provenanceMarker = ``; + const provenancePrefix = '<' + '!-- squad:bootstrap-provenance '; + const provenanceMarker = `${provenancePrefix}${JSON.stringify(provenance)} -->`; const prBodyWithoutProvenance = String(pullRequestDetails.body || payload.pr_body) - .replace(/^\r?\n?/gm, ''); + .replace(new RegExp(`^${provenancePrefix}.* -->\\r?\\n?`, 'gm'), ''); await github.rest.pulls.update({ ...context.repo, pull_number: pullRequest.number, body: `${provenanceMarker}\n${prBodyWithoutProvenance}`, }); + const provenanceComments = (await github.paginate( + github.rest.issues.listComments, + { + ...context.repo, + issue_number: pullRequest.number, + per_page: 100, + }, + )).filter((comment) => + String(comment.body || '').startsWith(provenancePrefix), + ); + if (provenanceComments.length > 1) { + throw new Error('Ambiguous bot-authenticated bootstrap provenance comments.'); + } + const provenanceCommentBody = + `${provenanceMarker}\nBase-controlled bootstrap provenance. Do not edit this comment.`; + if (provenanceComments.length === 1) { + if (provenanceComments[0].user?.login !== 'github-actions[bot]') { + throw new Error('Bootstrap provenance comment is not owned by GitHub Actions.'); + } + await github.rest.issues.updateComment({ + ...context.repo, + comment_id: provenanceComments[0].id, + body: provenanceCommentBody, + }); + } else { + await github.rest.issues.createComment({ + ...context.repo, + issue_number: pullRequest.number, + body: provenanceCommentBody, + }); + } const finalPayload = { ...payload, issue_body: payload.issue_body.replace('{{CAST_PR_URL}}', pullRequest.url), diff --git a/workflows/package/squad-review.md b/workflows/package/squad-review.md index 4abbe4c70..7ad1673bf 100644 --- a/workflows/package/squad-review.md +++ b/workflows/package/squad-review.md @@ -1,31 +1,19 @@ --- name: Squad Review -run-name: "Squad review — PR #${{ github.event.inputs.issue_number || github.event.pull_request.number }}" +run-name: "Squad review — PR #${{ github.event.pull_request.number }}" description: Independently reviews agent-authored pull requests without editing or remediating private: false inlined-imports: true +strict: false on: - workflow_dispatch: - inputs: - issue_number: - description: Pull request number to review - required: true - type: string - expected_head_sha: - description: Pull request head SHA observed by the /squad review relay - required: true - type: string - request_origin: - description: Review request origin - required: true - type: string - pull_request: + pull_request_target: types: - opened - reopened - ready_for_review - synchronize -if: github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) +if: github.event.pull_request.head.repo.full_name == github.repository +checkout: false permissions: contents: read copilot-requests: write @@ -33,14 +21,12 @@ permissions: pull-requests: read actions: read concurrency: - group: squad-review-${{ github.event.inputs.issue_number || github.event.pull_request.number || github.run_id }} + group: squad-review-${{ github.event.pull_request.number }} cancel-in-progress: true - job-discriminator: ${{ github.run_id }} network: allowed: - defaults tools: - bash: true github: min-integrity: approved mode: gh-proxy @@ -53,21 +39,16 @@ safe-outputs: - name: Checkout base commit for review guard uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: - ref: ${{ github.event.pull_request.base.sha || github.workflow_sha }} + ref: ${{ github.event.pull_request.base.sha }} persist-credentials: false path: .squad-review-base - - name: Checkout workflow commit for first-install review guard - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 - with: - ref: ${{ github.workflow_sha }} - persist-credentials: false - path: .squad-review-workflow - name: Bind review output to committed agent identities and current head uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 env: GH_AW_AGENT_OUTPUT: ${{ steps.setup-agent-output-env.outputs.GH_AW_AGENT_OUTPUT }} - SQUAD_REVIEW_PR: ${{ github.event.pull_request.number || github.event.inputs.issue_number }} - SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha || github.event.inputs.expected_head_sha }} + SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} + SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} + SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} with: script: | const { existsSync } = require('node:fs'); @@ -76,37 +57,30 @@ safe-outputs: `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/workflows/shared/squad-review-guard.mjs`; const baseManifest = `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/aw/squad-workflows.manifest.json`; - const workflowGuard = - `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/shared/squad-review-guard.mjs`; - let guardPath; - if (existsSync(baseGuard)) { - guardPath = baseGuard; - } else if (!existsSync(baseManifest)) { - guardPath = workflowGuard; - } else { + if (!existsSync(baseGuard) || !existsSync(baseManifest)) { throw new Error( - 'Squad Review guard is missing from an established base installation. Refusing workflow-source fallback.' + 'First-install manual boundary: the PR base does not contain the trusted Squad review guard and manifest. No trusted Squad verdict was emitted. Merge only with explicit human approval; trusted review begins on the post-merge bootstrap PR.' ); } - const guard = await import(pathToFileURL(guardPath).href); + const guard = await import(pathToFileURL(baseGuard).href); await guard.enforceReviewOutputs(process.env, async (route, fields) => (await github.request(`GET /${route}`, fields)).data); add-comment: max: 1 - target: ${{ github.event.inputs.issue_number || github.event.pull_request.number }} + target: ${{ github.event.pull_request.number }} create-pull-request-review-comment: max: 10 - target: ${{ github.event.inputs.issue_number || github.event.pull_request.number }} + target: ${{ github.event.pull_request.number }} submit-pull-request-review: max: 1 - target: ${{ github.event.inputs.issue_number || github.event.pull_request.number }} + target: ${{ github.event.pull_request.number }} allowed-events: - COMMENT - REQUEST_CHANGES - commit-id: ${{ github.event.pull_request.head.sha || github.event.inputs.expected_head_sha }} + commit-id: ${{ github.event.pull_request.head.sha }} jobs: review: - name: ${{ github.event_name == 'pull_request' && 'Squad Review / review' || 'Squad Review / manual' }} + name: Squad Review Authority / attest if: always() needs: - agent @@ -120,34 +94,24 @@ jobs: steps: - name: Require successful PR review execution env: - EVENT_NAME: ${{ github.event_name }} AGENT_RESULT: ${{ needs.agent.result }} OUTPUT_RESULT: ${{ needs.safe_outputs.result }} run: | set -euo pipefail - if [ "$EVENT_NAME" != pull_request ]; then exit 0; fi test "$AGENT_RESULT" = success test "$OUTPUT_RESULT" = success - name: Checkout base commit for final verdict gate - if: github.event_name == 'pull_request' uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: ref: ${{ github.event.pull_request.base.sha }} persist-credentials: false path: .squad-review-base - - name: Checkout workflow commit for first-install final verdict gate - if: github.event_name == 'pull_request' - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 - with: - ref: ${{ github.workflow_sha }} - persist-credentials: false - path: .squad-review-workflow - name: Enforce independent current-head verdict - if: github.event_name == 'pull_request' uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 env: SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} + SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} with: script: | const { existsSync } = require('node:fs'); @@ -156,21 +120,170 @@ jobs: `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/workflows/shared/squad-review-guard.mjs`; const baseManifest = `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/aw/squad-workflows.manifest.json`; - const workflowGuard = - `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/shared/squad-review-guard.mjs`; - let guardPath; - if (existsSync(baseGuard)) { - guardPath = baseGuard; - } else if (!existsSync(baseManifest)) { - guardPath = workflowGuard; - } else { + if (!existsSync(baseGuard) || !existsSync(baseManifest)) { throw new Error( - 'Squad Review guard is missing from an established base installation. Refusing workflow-source fallback.' + 'First-install manual boundary: the PR base does not contain the trusted Squad review guard and manifest. No trusted Squad verdict was emitted. Merge only with explicit human approval; trusted review begins on the post-merge bootstrap PR.' ); } - const guard = await import(pathToFileURL(guardPath).href); + const guard = await import(pathToFileURL(baseGuard).href); await guard.assertClearingReview(process.env, async (route, fields) => (await github.request(`GET /${route}`, fields)).data); + publish: + name: Publish Squad Review required check + if: always() + needs: + - agent + - safe_outputs + - review + runs-on: ubuntu-latest + environment: squad-review-authority + permissions: + actions: read + contents: read + pull-requests: read + steps: + - name: Validate dedicated reviewer App configuration + env: + SQUAD_REVIEW_APP_ID: ${{ vars.SQUAD_REVIEW_APP_ID }} + SQUAD_REVIEW_APP_SLUG: ${{ vars.SQUAD_REVIEW_APP_SLUG }} + SQUAD_REVIEW_APP_OWNER: ${{ vars.SQUAD_REVIEW_APP_OWNER }} + SQUAD_REVIEW_APP_PRIVATE_KEY: ${{ secrets.SQUAD_REVIEW_APP_PRIVATE_KEY }} + run: | + set -euo pipefail + test "${SQUAD_REVIEW_APP_ID}" != "15368" + test "${SQUAD_REVIEW_APP_SLUG}" != "github-actions" + [[ "${SQUAD_REVIEW_APP_ID}" =~ ^[1-9][0-9]*$ ]] + [[ "${SQUAD_REVIEW_APP_SLUG}" =~ ^[a-z0-9][a-z0-9-]*$ ]] + [[ "${SQUAD_REVIEW_APP_OWNER}" =~ ^[A-Za-z0-9_.-]+$ ]] + test -n "${SQUAD_REVIEW_APP_PRIVATE_KEY}" + - name: Mint dedicated reviewer App token + id: squad-review-app-token + uses: actions/create-github-app-token@v3.2.0 + with: + app-id: ${{ vars.SQUAD_REVIEW_APP_ID }} + private-key: ${{ secrets.SQUAD_REVIEW_APP_PRIVATE_KEY }} + owner: ${{ vars.SQUAD_REVIEW_APP_OWNER }} + - name: Publish exact-head required check + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 + env: + AUTHORITY_RESULT: ${{ needs.review.result }} + SQUAD_REVIEW_APP_ID: ${{ vars.SQUAD_REVIEW_APP_ID }} + SQUAD_REVIEW_APP_SLUG: ${{ vars.SQUAD_REVIEW_APP_SLUG }} + SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} + SQUAD_REVIEW_BASE: ${{ github.event.pull_request.base.sha }} + SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} + SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} + with: + github-token: ${{ steps.squad-review-app-token.outputs.token }} + script: | + const checkName = 'Squad Review / review'; + const authorityJob = 'Squad Review Authority / attest'; + const repository = process.env.GITHUB_REPOSITORY; + const [owner, repo] = repository.split('/'); + const expectedAppId = Number(process.env.SQUAD_REVIEW_APP_ID); + const expectedAppSlug = process.env.SQUAD_REVIEW_APP_SLUG; + const pullRequest = Number(process.env.SQUAD_REVIEW_PR); + const baseSha = process.env.SQUAD_REVIEW_BASE; + const headSha = process.env.SQUAD_REVIEW_HEAD; + const workflowSha = process.env.SQUAD_REVIEW_WORKFLOW_SHA; + const runId = Number(process.env.GITHUB_RUN_ID); + const runAttempt = Number(process.env.GITHUB_RUN_ATTEMPT); + if (!Number.isSafeInteger(expectedAppId) || expectedAppId < 1 || + expectedAppId === 15368 || + !/^[a-z0-9][a-z0-9-]*$/.test(expectedAppSlug) || + expectedAppSlug === 'github-actions' || + !Number.isSafeInteger(pullRequest) || pullRequest < 1 || + !/^[0-9a-f]{40}$/.test(baseSha) || !/^[0-9a-f]{40}$/.test(headSha) || + workflowSha !== baseSha || !Number.isSafeInteger(runId) || runId < 1 || + !Number.isSafeInteger(runAttempt) || runAttempt < 1) { + core.setFailed('Invalid base-controlled Squad review check context.'); + return; + } + const run = (await github.rest.actions.getWorkflowRun({ + owner, repo, run_id: runId, + })).data; + if (run.event !== 'pull_request_target' || + run.path !== '.github/workflows/squad-review.lock.yml' || + run.head_sha !== workflowSha || + run.repository.full_name !== repository) { + core.setFailed('Squad review check is not bound to the base-controlled workflow run.'); + return; + } + const jobs = await github.paginate(github.rest.actions.listJobsForWorkflowRunAttempt, { + owner, repo, run_id: runId, attempt_number: runAttempt, per_page: 100, + }); + const authorityJobs = jobs.filter(job => job.name === authorityJob); + if (authorityJobs.length !== 1) { + core.setFailed('Missing or duplicate base-controlled Squad review authority job.'); + return; + } + const succeeded = process.env.AUTHORITY_RESULT === 'success' && + authorityJobs[0].conclusion === 'success'; + const externalId = + `squad-review-authority/v1:${repository}:${pullRequest}:${baseSha}:${headSha}`; + const existing = await github.paginate(github.rest.checks.listForRef, { + owner, repo, ref: headSha, check_name: checkName, per_page: 100, + }); + const owned = existing.filter(check => + check.external_id === externalId && + check.app?.id === expectedAppId && + check.app?.slug === expectedAppSlug); + if (owned.length > 1) { + core.setFailed('Duplicate exact-head Squad review authority checks.'); + return; + } + const detailsUrl = + `${process.env.GITHUB_SERVER_URL}/${repository}/actions/runs/${runId}`; + const output = { + title: succeeded + ? 'Base-controlled Squad review passed' + : 'Base-controlled Squad review did not pass', + summary: JSON.stringify({ + schema: 'squad-review-check/v1', + repository, + pull_request: pullRequest, + base_sha: baseSha, + head_sha: headSha, + workflow_sha: workflowSha, + run_id: runId, + run_attempt: runAttempt, + event: 'pull_request_target', + workflow_path: '.github/workflows/squad-review.lock.yml', + authority_job: authorityJob, + publisher_app_id: expectedAppId, + publisher_app_slug: expectedAppSlug, + }), + }; + const request = { + owner, repo, name: checkName, head_sha: headSha, + status: 'completed', + conclusion: succeeded ? 'success' : 'failure', + details_url: detailsUrl, + external_id: externalId, + output, + }; + const published = owned.length === 1 + ? await github.rest.checks.update({ + ...request, + check_run_id: owned[0].id, + }) + : await github.rest.checks.create(request); + if (published.data.app?.id !== expectedAppId || + published.data.app?.slug !== expectedAppSlug) { + try { + await github.rest.checks.delete({ + owner, repo, check_run_id: published.data.id, + }); + } finally { + core.setFailed( + 'Squad review check was not published by the configured dedicated GitHub App.' + ); + } + return; + } + if (!succeeded) { + core.setFailed('Base-controlled Squad review authority did not succeed.'); + } --- @@ -187,19 +300,22 @@ this workflow. ## Trigger and target gate 1. Resolve the pull request number from - `${{ github.event.inputs.issue_number || github.event.pull_request.number }}`. + `${{ github.event.pull_request.number }}`. If it is absent or not a positive integer, call `noop` and stop. 2. Fetch the pull request from `${{ github.repository }}` and record its current 40-character lowercase head SHA. -3. For `workflow_dispatch`, require `request_origin` to equal `manual` and - `expected_head_sha` to equal the current head SHA. A missing, malformed, or - stale value, or a head repository other than `${{ github.repository }}`, is a - refusal: call `noop` and stop. This is the `/squad review` path relayed by - `workflows/squad.md`. -4. For `pull_request`, require the head repository to equal +3. Require the head repository to equal `${{ github.repository }}`. Forks and any event other than `opened`, `reopened`, `ready_for_review` or `synchronize` are refused with `noop`. +This base-controlled `pull_request_target` workflow has no `workflow_dispatch` +trigger and never checks out or executes pull request content. The agent reads +the pull request diff and repository evidence only through GitHub APIs. +`/squad review` is an operator +aid that points to GitHub's **Re-run jobs** action for the existing automatic +run. Never execute reviewer code, guards, manifests, or safe-output handlers +from a manually selected ref. + Read `.squad-review.json` at the exact PR head SHA and the committed `.squad/casting/registry.json` at the PR base SHA. The attribution schema is `squad-review-author/v1` with `repository`, positive integer `issue`, @@ -207,9 +323,29 @@ Read `.squad-review.json` at the exact PR head SHA and the committed `persistent_name` entries in that registry, and must differ. Act as that `reviewer_agent`, reading its base-commit charter. Missing or malformed attribution is a refusal, never a fallback to a display name or GitHub login. -The deterministic output guard and final job repeat these checks. A refusal, -missing verdict, stale head, or malformed provenance cannot clear the required -`Squad Review / review` check. +The deterministic output guard and authority job repeat these checks. The +publisher creates `Squad Review / review` on the exact PR head only after the +native `Squad Review Authority / attest` job in the same base-controlled run +succeeds. A refusal, missing verdict, stale head, malformed provenance, or +same-named PR-controlled check cannot clear the authority contract. + +The workflow-installation PR is an explicit human trust boundary. Its base does +not contain this workflow, guard, or manifest, so no trusted automatic Squad +review runs. No code, job name, check result, or review record emitted by that +PR is a trusted Squad verdict. Merge the installation only through explicit +human review of the generated package. + +Trusted review starts on the automatic post-merge Cast PR. The guard is then +loaded only from the exact PR base commit, where the installed manifest also +exists. That base-controlled guard permits missing `.squad-review.json` only +for the exact `squad/bootstrap-cast` PR created by the base-controlled bootstrap +workflow. It verifies the GitHub Actions bot author, canonical title and branch, +matching provenance in the PR body and a durable bot-authored PR comment, exact +base/head SHAs, and the referenced default-branch `squad-bootstrap.lock.yml` +push run. It binds the reserved roles +`@squad/base-controlled-bootstrap` and `@squad/base-controlled-review`; the +clearing gate additionally requires that bootstrap run to finish successfully. +All other missing, malformed, or non-404 attribution evidence is refused. ## Provenance decision tree @@ -249,11 +385,15 @@ machine-readable review marker is a standalone final line: `Squad-Review-Head: {40-character lowercase head SHA}` If an existing bot review contains a `Squad-Review-Verdict:` record for the -current head SHA, call `noop` and stop. The deterministic gate validates it; -an arbitrary comment or the legacy head marker is not clearing evidence. -Never re-review an unchanged head, including duplicate -`synchronize` deliveries. Re-fetch the pull request immediately before emitting -outputs; if its head SHA changed, call `noop` and let the newer run review it. +current head SHA and this exact workflow run ID and attempt, call `noop` and +stop. Evidence from a different run or attempt cannot deduplicate or clear this +run. The deterministic gate validates the `pull_request_target` event, immutable +workflow SHA, workflow path, PR, base, head, run, attempt, native authority job, +exact-head published check, and GitHub Actions App/bot identity; an arbitrary +comment, PR-controlled workflow, same-named check, or legacy head marker is not +clearing evidence. Re-fetch the pull request +immediately before emitting outputs; if its head SHA changed, call `noop` and +let the newer run review it. ## Review procedure @@ -288,12 +428,11 @@ Submit exactly one review: Do not emit `Squad-Review-Verdict:` or `Squad-Review-Override:` yourself. The trusted safe-output guard adds the repository, PR, head SHA, stable -author/reviewer IDs, result, timestamp and workflow-run binding. Only -`pull_request` runs mint this evidence; manual `/squad review` is diagnostic -and does not satisfy the required check. A valid `REQUEST_CHANGES` keeps the -check red unless an administrator posts the documented SHA- and review-scoped -override and reruns the PR workflow. Overrides cannot repair invalid identity -or missing evidence. Never approve or merge on behalf of a human. +author/reviewer IDs, result, timestamp and exact automatic workflow-run binding. +Manual dispatch does not exist. A valid `REQUEST_CHANGES` keeps the check red +unless an administrator posts the documented SHA- and review-scoped override +and reruns the same PR workflow. Overrides cannot repair invalid identity or +missing evidence. Never approve or merge on behalf of a human. Keep the body concise. State the provenance classification, linked issue scope, and blocking themes. End with these two standalone lines, substituting the diff --git a/workflows/package/squad.md b/workflows/package/squad.md index 67cbe1ac1..411000183 100644 --- a/workflows/package/squad.md +++ b/workflows/package/squad.md @@ -472,7 +472,6 @@ safe-outputs: workflows: - squad-implement-worker - squad-deps-worker - - squad-review - squad-retro - squad-improvement-worker max: 3 @@ -740,6 +739,7 @@ on: type: string if: github.event_name != 'issues' || github.actor != 'github-actions[bot]' || github.event.issue.title != '[Research Proposals] Agent-discovered repo opportunities' || !contains(github.event.issue.body, '') permissions: + actions: read contents: read copilot-requests: write issues: read @@ -2228,32 +2228,44 @@ and includes the verified PR number, URL, and CI-approval guidance. ## skill: `squad-review-relay` --- -description: Relay `/squad review` on a pull request to the independent reviewer. +description: Guide an operator to rerun the automatic independent review. --- This mode is only valid from a pull request comment or pull request review comment. Resolve the pull request number and current 40-character lowercase head SHA from GitHub's API, not from user text. If either cannot be established, post one `add-comment` explaining that `/squad review` must target a pull -request, then stop without dispatching. - -Use only the typed `dispatch-workflow` safe-output. Never call the generic -`dispatch_workflow` tool. Emit exactly one dispatch: - -```json -{ - "workflow_name": "squad-review", - "inputs": { - "issue_number": "{pull-request-number}", - "expected_head_sha": "{current-head-sha}", - "request_origin": "manual" - } -} -``` +request, then stop. + +List workflow runs for `.github/workflows/squad-review.lock.yml`. Keep only +`pull_request_target` runs associated with this pull request whose workflow +head SHA equals the pull request's exact base SHA. Select the newest run by +creation time, breaking ties by numeric run ID, then fetch its jobs and require +exactly one job named `Squad Review Authority / attest`. Also fetch check runs +for the exact current PR head and require exactly one `Squad Review / review` +check whose external ID, details URL, GitHub Actions App identity, and +`squad-review-check/v1` summary bind that base-controlled run, PR, base SHA, +head SHA, run ID, and attempt. A same-named check without that binding is +advisory only. If no matching run or authority check exists, emit exactly one +`add-comment` stating that no base-controlled automatic review run exists for +the exact head and that a new PR event +(`synchronize`, reopen, or ready-for-review) is required. Stop without implying +that a rerun occurred. + +Otherwise emit exactly one `add-comment` on the pull request that includes the +selected run URL, run ID, attempt, status, conclusion, exact head SHA, and this +instruction: + +> Squad Review is automatic and cannot be dispatched from a branch. In the +> selected base-controlled automatic run, choose **Re-run all jobs**. This +> command did not rerun it. Only the new attempt of that exact +> `pull_request_target` run can publish verdict evidence and the exact-head +> `Squad Review / review` check for PR #{pull-request-number} +> at head `{current-head-sha}`. Do not review the diff in this router, emit a verdict, edit files, create an -issue, or dispatch any other workflow. The independent reviewer owns all -provenance, deduplication, and review decisions. +issue, or dispatch a workflow. The independent reviewer owns all provenance, +deduplication, and review decisions. ## skill: `squad-retro-relay` --- diff --git a/workflows/shared/squad-install-verifier.mjs b/workflows/shared/squad-install-verifier.mjs index cf2e6ec43..6b7ad970e 100644 --- a/workflows/shared/squad-install-verifier.mjs +++ b/workflows/shared/squad-install-verifier.mjs @@ -32,6 +32,7 @@ export const TRIGGER_PROBE_DESTINATION = const SHA256_PATTERN = /^[0-9a-f]{64}$/; const REVISION_PATTERN = /^[0-9a-f]{40}$/; +const LOCK_REVISION_PLACEHOLDER = 'f'.repeat(40); function deepFreeze(value) { if (value && typeof value === 'object' && !Object.isFrozen(value)) { @@ -158,13 +159,18 @@ export function validateContract(contract) { assertArray(contract.workflows, WORKFLOW_TUPLES.length, 'Integrity contract workflows'); contract.workflows.forEach((entry, index) => { - assertKeys(entry, ['name', 'source', 'destination', 'lock', 'source_sha256'], `Workflow entry ${index}`); + assertKeys( + entry, + ['name', 'source', 'destination', 'lock', 'source_sha256', 'lock_sha256'], + `Workflow entry ${index}`, + ); const [name, source, destination, lock] = WORKFLOW_TUPLES[index]; if (entry.name !== name) throw new Error(`Workflow entry ${index} name must be ${name}.`); validatePathSyntax(entry.source, source, `Workflow ${name} source`); validatePathSyntax(entry.destination, destination, `Workflow ${name} destination`); validatePathSyntax(entry.lock, lock, `Workflow ${name} lock`); assertDigest(entry.source_sha256, `Workflow ${name} source_sha256`); + assertDigest(entry.lock_sha256, `Workflow ${name} lock_sha256`); }); assertArray(contract.shared_runtime, RUNTIME_TUPLES.length, 'Integrity contract shared_runtime'); @@ -320,7 +326,77 @@ function packageWorkflowSource(_root, name) { return `workflows/package/${name}.md`; } +function workflowWithSource(content, name, revision) { + const marker = '\n---\n'; + const end = content.indexOf(marker, 4); + if (!content.startsWith('---\n') || end < 0) { + throw new Error(`Generated package workflow has invalid frontmatter: ${name}`); + } + return `${content.slice(0, end)} +source: ${PACKAGE_NAME}/package/${name}.md@${revision}${content.slice(end)}`; +} + +export function normalizeCompiledLock(content, revision) { + if (!REVISION_PATTERN.test(revision)) { + throw new Error('Compiled lock revision must be a lowercase 40-character SHA.'); + } + const text = Buffer.isBuffer(content) ? content.toString('utf8') : String(content); + if (!text.includes(revision)) { + throw new Error('Compiled lock is not bound to the expected package revision.'); + } + const metadata = text.match( + /^(# gh-aw-metadata: \{[^\n]*"frontmatter_hash":")([0-9a-f]{64})("[^\n]*\})$/m, + ); + if (!metadata) throw new Error('Compiled lock has missing or malformed gh-aw metadata.'); + return text + .replace(metadata[0], `${metadata[1]}${'0'.repeat(64)}${metadata[3]}`) + .replace( + /^(\s*-\s+cron:\s+)"[^"]+"(\s+# Friendly format: .+ \(scattered\))$/gm, + '$1""$2', + ) + .replaceAll(revision, LOCK_REVISION_PLACEHOLDER); +} + +function buildLockDigests(root, renderedWorkflows) { + const scratch = mkdtempSync(join(resolve(root), '.squad-gh-aw-lock-digests-')); + try { + const workflowRoot = resolve(scratch, '.github/workflows'); + mkdirSync(workflowRoot, { recursive: true }); + cpSync(resolve(root, 'workflows/shared'), resolve(workflowRoot, 'shared'), { recursive: true }); + for (const [name, content] of renderedWorkflows) { + writeFileSync( + resolve(workflowRoot, `${name}.md`), + workflowWithSource(content, name, LOCK_REVISION_PLACEHOLDER), + ); + } + spawnChecked('git', ['init', '--quiet'], scratch); + const ghAwBin = process.env.SQUAD_GH_AW_BIN; + const command = ghAwBin || 'gh'; + const args = ghAwBin + ? ['compile', '--strict', '--no-check-update'] + : ['aw', 'compile', '--strict', '--no-check-update']; + const result = spawnSync(command, args, { + cwd: scratch, + encoding: 'utf8', + env: process.env, + }); + if (result.error || result.status !== 0) { + throw result.error ?? new Error(`${command} failed:\n${result.stdout}${result.stderr}`); + } + return new Map(WORKFLOW_NAMES.map((name) => { + const lock = readRequired(scratch, `.github/workflows/${name}.lock.yml`); + return [name, sha256(normalizeCompiledLock(lock, LOCK_REVISION_PLACEHOLDER))]; + })); + } finally { + rmSync(scratch, { recursive: true, force: true }); + } +} + export function buildContract(root) { + const renderedWorkflows = new Map(WORKFLOW_NAMES.map( + name => [name, readFileSync(resolve(root, `workflows/package/${name}.md`), 'utf8')], + )); + const lockDigests = buildLockDigests(root, renderedWorkflows); return validateContract({ schema_version: 1, package: PACKAGE_NAME, @@ -329,10 +405,15 @@ export function buildContract(root) { revision_policy: { ...REVISION_POLICY }, workflows: WORKFLOW_TUPLES.map(([name, , destination, lock]) => { const source = packageWorkflowSource(root, name); - const content = source.startsWith('workflows/package/') - ? renderPackageWorkflow(root, name) - : readFileSync(resolve(root, source)); - return { name, source, destination, lock, source_sha256: sha256(content) }; + const content = renderedWorkflows.get(name); + return { + name, + source, + destination, + lock, + source_sha256: sha256(content), + lock_sha256: lockDigests.get(name), + }; }), shared_runtime: RUNTIME_TUPLES.map( ([path, source, package_destination, destination, ownership]) => ({ @@ -420,10 +501,13 @@ function updateEmbeddedDigests(root) { export function writeSource(root) { updateEmbeddedDigests(root); - for (const [path, content] of generatedFiles(root)) { + for (const name of WORKFLOW_NAMES) { + const path = resolve(root, `workflows/package/${name}.md`); mkdirSync(dirname(path), { recursive: true }); - writeFileSync(path, content); + writeFileSync(path, renderPackageWorkflow(root, name)); } + writeFileSync(resolve(root, PACKAGE_MANIFEST), renderManifest(root)); + writeFileSync(resolve(root, CONTRACT_SOURCE), stableJson(buildContract(root))); } export function checkSource(root) { @@ -432,6 +516,7 @@ export function checkSource(root) { const digests = expectedEmbeddedDigests(root); const dispatcher = readFileSync(resolve(root, 'workflows/squad.md'), 'utf8'); const bootstrap = readFileSync(resolve(root, 'workflows/squad-bootstrap.md'), 'utf8'); + const reviewer = readFileSync(resolve(root, 'workflows/squad-review.md'), 'utf8'); if (!dispatcher.includes(`validator_expected_sha256="${digests.cast}"`)) { failures.push('Generated Cast validator digest is stale in workflows/squad.md.'); } @@ -450,6 +535,22 @@ export function checkSource(root) { failures.push(`Generated package file is stale: ${relative(root, path)} (run: npm run gh-aw:integrity:write)`); } } + for (const required of [ + 'environment: squad-review-authority', + 'SQUAD_REVIEW_APP_PRIVATE_KEY: ${{ secrets.SQUAD_REVIEW_APP_PRIVATE_KEY }}', + 'github-token: ${{ steps.squad-review-app-token.outputs.token }}', + 'published.data.app?.id !== expectedAppId', + "expectedAppId === 15368", + "expectedAppSlug === 'github-actions'", + ]) { + if (!reviewer.includes(required)) { + failures.push(`Dedicated review authority contract is missing: ${required}`); + } + } + const publishJob = reviewer.match(/\n publish:\n([\s\S]*?)\n---\n/)?.[1] ?? ''; + if (publishJob.includes('checks: write')) { + failures.push('Dedicated review publisher must not grant checks:write to github.token.'); + } } catch (error) { failures.push(error instanceof Error ? error.message : String(error)); } @@ -565,6 +666,15 @@ function verifyInstalledBytes(root, contract, revision) { } } for (const entry of contract.workflows) readRequired(root, entry.lock); + for (const entry of contract.workflows) { + const normalized = normalizeCompiledLock(readRequired(root, entry.lock), revision); + const observedDigest = sha256(normalized); + if (observedDigest !== entry.lock_sha256) { + throw new Error( + `Installed digest mismatch for ${entry.lock}: expected ${entry.lock_sha256}, observed ${observedDigest}.`, + ); + } + } } function verifyTriggerNamespace(root) { @@ -725,6 +835,20 @@ export function materializeRuntime(root) { export function writeLocalTestOwnership(root, revision) { if (!REVISION_PATTERN.test(revision)) throw new Error('Local test revision must be a lowercase 40-character SHA.'); const { contract } = parseInstalledContract(root); + for (const entry of contract.workflows) { + const path = safePath(root, entry.destination); + const content = readRequired(root, entry.destination).toString('utf8'); + const end = content.indexOf('\n---\n', 4); + if (!content.startsWith('---\n') || end < 0) { + throw new Error(`Installed workflow has invalid frontmatter: ${entry.destination}`); + } + const frontmatter = content.slice(0, end); + const source = `source: bradygaster/squad/${entry.source}@${revision}`; + const rebound = /^source:\s*.+$/m.test(frontmatter) + ? `${frontmatter.replace(/^source:\s*.+$/m, source)}${content.slice(end)}` + : `${frontmatter}\n${source}${content.slice(end)}`; + writeFileSync(path, rebound); + } const files = expectedOwnership(contract).map((entry) => ({ ...entry, sha256: fileDigest(root, entry.destination), diff --git a/workflows/shared/squad-review-guard.mjs b/workflows/shared/squad-review-guard.mjs index c8386cd4b..e7a11cbc1 100644 --- a/workflows/shared/squad-review-guard.mjs +++ b/workflows/shared/squad-review-guard.mjs @@ -5,9 +5,22 @@ export const CHECK_NAME = 'Squad Review / review'; export const VERDICT_PREFIX = 'Squad-Review-Verdict: '; export const OVERRIDE_PREFIX = 'Squad-Review-Override: '; const WORKFLOW = '.github/workflows/squad-review.lock.yml'; +const AUTHORITY_JOB = 'Squad Review Authority / attest'; +const CHECK_SCHEMA = 'squad-review-check/v1'; +const CHECK_EXTERNAL_ID = 'squad-review-authority/v1'; +const BOOTSTRAP_WORKFLOW = '.github/workflows/squad-bootstrap.lock.yml'; const SHA = /^[0-9a-f]{40}$/; const ID = /^[a-z][a-z0-9-]*$/; const BOT = 'github-actions[bot]'; +const BOT_ID = 41898282; +const ACTIONS_APP_ID = 15368; +const ACTIONS_APP_SLUG = 'github-actions'; +const APP_SLUG = /^[a-z0-9][a-z0-9-]*$/; +const BOOTSTRAP_BRANCH = 'squad/bootstrap-cast'; +const BOOTSTRAP_TITLE = '[squad] Cast your Squad'; +const BOOTSTRAP_AUTHOR = '@squad/base-controlled-bootstrap'; +const BOOTSTRAP_REVIEWER = '@squad/base-controlled-review'; +const BOOTSTRAP_PREFIX = '<' + '!-- squad:bootstrap-provenance '; function requireThat(condition, message) { if (!condition) throw new Error(`Squad review refused: ${message}`); @@ -55,18 +68,26 @@ export function validateAttribution(value, registry, repository, issue) { export function validateVerdict(value, expected, review, now = Date.now()) { requireThat(exactKeys(value, [ - 'schema', 'repository', 'pull_request', 'head_sha', 'author_agent', 'reviewer_agent', - 'result', 'timestamp', 'run_id', 'run_attempt', 'event', + 'schema', 'repository', 'pull_request', 'base_sha', 'head_sha', 'author_agent', + 'reviewer_agent', 'result', 'timestamp', 'run_id', 'run_attempt', 'event', + 'workflow_path', 'workflow_sha', ]) && value.schema === 'squad-review-verdict/v1', 'invalid verdict shape'); - for (const key of ['repository', 'pull_request', 'head_sha', 'author_agent', 'reviewer_agent']) { + for (const key of [ + 'repository', 'pull_request', 'base_sha', 'head_sha', 'author_agent', 'reviewer_agent', + ]) { requireThat(value[key] === expected[key], `verdict ${key} mismatch`); } - requireThat(SHA.test(value.head_sha) && value.author_agent !== value.reviewer_agent, + requireThat(SHA.test(value.base_sha) && SHA.test(value.head_sha) && + value.author_agent !== value.reviewer_agent, 'invalid SHA or self review'); requireThat(['COMMENT', 'REQUEST_CHANGES'].includes(value.result) && - value.event === 'pull_request' && Number.isSafeInteger(value.run_id) && value.run_id > 0 && - Number.isSafeInteger(value.run_attempt) && value.run_attempt > 0, 'invalid verdict result or run'); - requireThat(review.user?.login === BOT && review.commit_id === value.head_sha && + value.event === 'pull_request_target' && + Number.isSafeInteger(value.run_id) && value.run_id > 0 && + Number.isSafeInteger(value.run_attempt) && value.run_attempt > 0 && + value.workflow_path === WORKFLOW && value.workflow_sha === expected.workflow_sha, + 'invalid verdict result or run'); + requireThat(review.user?.login === BOT && review.user?.id === BOT_ID && + review.user?.type === 'Bot' && review.commit_id === value.head_sha && review.state === 'COMMENTED', 'review author, commit, or native result mismatch'); const issued = timestamp(value.timestamp); @@ -88,25 +109,128 @@ async function list(get, route, field) { throw new Error('Squad review refused: evidence pagination exceeded bound'); } -async function committedJson(get, repository, path, ref) { +async function committedFileEvidence( + get, + repository, + path, + ref, + { allowMissing = false, maximumSize = 2_000_000 } = {}, +) { requireThat(SHA.test(ref), 'invalid committed evidence ref'); - const file = await get(`repos/${repository}/contents/${path}`, { ref }); + let file; + try { + file = await get(`repos/${repository}/contents/${path}`, { ref }); + } catch (error) { + if (allowMissing && error?.status === 404) return undefined; + throw error; + } requireThat(file?.type === 'file' && file.encoding === 'base64' && - typeof file.content === 'string' && file.size <= 65536, `unreadable committed ${path}`); - return JSON.parse(Buffer.from(file.content, 'base64').toString('utf8')); + typeof file.content === 'string' && Number.isSafeInteger(file.size) && + file.size >= 0 && file.size <= maximumSize, `unreadable committed ${path}`); + const content = Buffer.from(file.content, 'base64'); + requireThat(content.length === file.size, `truncated committed ${path}`); + return { + content, + }; +} + +async function committedJsonEvidence(get, repository, path, ref, options) { + const evidence = await committedFileEvidence(get, repository, path, ref, options); + if (evidence === undefined) return undefined; + return { + ...evidence, + value: JSON.parse(evidence.content.toString('utf8')), + }; } -export async function reviewTarget(env, get, { relay = false } = {}) { +async function committedJson(get, repository, path, ref, options) { + return (await committedJsonEvidence(get, repository, path, ref, options))?.value; +} + +function bootstrapRecord(body, label = 'bootstrap provenance') { + const lines = String(body ?? '').replace(/\r\n/g, '\n') + .split('\n').filter(line => line.startsWith(BOOTSTRAP_PREFIX)); + requireThat(lines.length === 1 && lines[0].endsWith(' -->'), + `missing or duplicate base-controlled ${label}`); + const value = JSON.parse(lines[0].slice(BOOTSTRAP_PREFIX.length, -4)); + requireThat(exactKeys( + value, + ['schema', 'repository', 'run_id', 'install_sha', 'cast_sha'], + ) && value.schema === 1, `malformed base-controlled ${label}`); + return value; +} + +async function validateBootstrapAttribution(get, repository, pr, requireRunSuccess) { + const provenance = bootstrapRecord(pr.body, 'bootstrap PR provenance'); + const comments = await list(get, `repos/${repository}/issues/${pr.number}/comments`); + const provenanceComments = comments.filter(comment => + comment.user?.login === BOT && + comment.user?.type === 'Bot' && + String(comment.body ?? '').startsWith(BOOTSTRAP_PREFIX)); + requireThat(provenanceComments.length === 1, + 'missing or duplicate bot-authenticated bootstrap provenance comment'); + const commentProvenance = bootstrapRecord( + provenanceComments[0].body, + 'bootstrap comment provenance', + ); + requireThat(JSON.stringify(commentProvenance) === JSON.stringify(provenance), + 'bootstrap PR and bot-authenticated comment provenance differ'); + requireThat( + pr.title === BOOTSTRAP_TITLE && + pr.head.ref === BOOTSTRAP_BRANCH && + pr.user?.login === BOT && + pr.user?.type === 'Bot' && + provenance.repository === repository && + /^[1-9]\d*$/.test(provenance.run_id ?? '') && + provenance.install_sha === pr.base.sha && + provenance.cast_sha === pr.head.sha, + 'invalid base-controlled bootstrap pull request', + ); + const run = await get(`repos/${repository}/actions/runs/${provenance.run_id}`); + requireThat( + run.event === 'push' && + run.path === BOOTSTRAP_WORKFLOW && + run.repository?.full_name === repository && + run.head_sha === pr.base.sha && + run.head_branch === pr.base.ref && + (!requireRunSuccess || (run.status === 'completed' && run.conclusion === 'success')), + requireRunSuccess + ? 'base-controlled bootstrap run did not complete successfully' + : 'bootstrap provenance is not bound to the base-controlled workflow run', + ); + return { + schema: 'squad-review-author/v1', + repository, + issue: pr.number, + author_agent: BOOTSTRAP_AUTHOR, + reviewer_agent: BOOTSTRAP_REVIEWER, + }; +} + +export async function reviewTarget( + env, + get, + { + relay = false, + requireBootstrapRunSuccess = false, + } = {}, +) { const repository = env.GITHUB_REPOSITORY; const number = Number(env.SQUAD_REVIEW_PR); requireThat(typeof repository === 'string' && /^[\w.-]+\/[\w.-]+$/.test(repository) && /^[1-9]\d*$/.test(env.SQUAD_REVIEW_PR ?? '') && Number.isSafeInteger(number), 'invalid target'); const pr = await get(`repos/${repository}/pulls/${number}`); + const repo = await get(`repos/${repository}`); requireThat(pr.number === number && pr.head?.repo?.full_name === repository && pr.base?.repo?.full_name === repository && SHA.test(pr.head.sha) && SHA.test(pr.base.sha), 'foreign repository or invalid PR'); + requireThat(repo?.full_name === repository && typeof repo.default_branch === 'string' && + pr.base.ref === repo.default_branch, 'review target must use the repository default branch'); requireThat(SHA.test(env.SQUAD_REVIEW_HEAD ?? '') && pr.head.sha === env.SQUAD_REVIEW_HEAD, 'PR head changed or expected SHA missing'); + requireThat(SHA.test(env.SQUAD_REVIEW_WORKFLOW_SHA ?? '') && + env.SQUAD_REVIEW_WORKFLOW_SHA === pr.base.sha, + 'workflow source is not the exact PR base commit'); requireThat(relay ? pr.merged === true && pr.state === 'closed' && pr.base.ref === env.SQUAD_REVIEW_DEFAULT_BRANCH @@ -120,11 +244,35 @@ export async function reviewTarget(env, get, { relay = false } = {}) { requireThat(provenance.ok, 'malformed or duplicate implementation provenance'); issue = provenance.issue_number; } - const value = await committedJson(get, repository, '.squad-review.json', pr.head.sha); - const registry = await committedJson(get, repository, '.squad/casting/registry.json', pr.base.sha); - const attribution = validateAttribution(value, registry, repository, issue ?? value?.issue); + const value = await committedJson( + get, + repository, + '.squad-review.json', + pr.head.sha, + { allowMissing: true }, + ); + let attribution; + if (value === undefined) { + requireThat(relay === false && env.GITHUB_EVENT_NAME === 'pull_request_target', + 'missing committed attribution outside base-controlled bootstrap activation'); + attribution = await validateBootstrapAttribution( + get, + repository, + pr, + requireBootstrapRunSuccess, + ); + } else { + const registry = await committedJson( + get, + repository, + '.squad/casting/registry.json', + pr.base.sha, + ); + attribution = validateAttribution(value, registry, repository, issue ?? value?.issue); + } return { - repository, pull_request: number, head_sha: pr.head.sha, + repository, pull_request: number, base_sha: pr.base.sha, head_sha: pr.head.sha, + workflow_sha: env.SQUAD_REVIEW_WORKFLOW_SHA, author_agent: attribution.author_agent, reviewer_agent: attribution.reviewer_agent, pr, }; } @@ -138,16 +286,21 @@ async function currentEvidence(target, get) { String(review.body ?? '').includes(VERDICT_PREFIX.trim())); } -export async function enforceReviewOutputs(env, get) { - requireThat(['pull_request', 'workflow_dispatch'].includes(env.GITHUB_EVENT_NAME), 'invalid event'); - const target = await reviewTarget(env, get); +export async function enforceReviewOutputs(env, get, options = {}) { + requireThat(env.GITHUB_EVENT_NAME === 'pull_request_target', + 'only base-controlled PR target runs can emit review output'); + const target = await reviewTarget(env, get, options); const output = JSON.parse(readFileSync(env.GH_AW_AGENT_OUTPUT, 'utf8')); requireThat(Array.isArray(output.items), 'missing safe-output items'); const verdicts = output.items.filter(item => item.type === 'submit_pull_request_review'); const existing = await currentEvidence(target, get); - requireThat(existing.length <= 1, 'duplicate verdict evidence'); - if (existing.length === 1) { - validateVerdict(record(existing[0].body, VERDICT_PREFIX), target, existing[0]); + const currentRun = existing.filter(review => { + const verdict = validateVerdict(record(review.body, VERDICT_PREFIX), target, review); + return String(verdict.run_id) === env.GITHUB_RUN_ID && + String(verdict.run_attempt) === env.GITHUB_RUN_ATTEMPT; + }); + requireThat(currentRun.length <= 1, 'duplicate verdict evidence for this run'); + if (currentRun.length === 1) { requireThat(verdicts.length === 0, 'unchanged head already has a verdict'); return; } @@ -156,17 +309,11 @@ export async function enforceReviewOutputs(env, get) { requireThat(['COMMENT', 'REQUEST_CHANGES'].includes(item.event) && typeof item.body === 'string' && !item.body.includes('Squad-Review-Verdict') && !item.body.includes('Squad-Review-Override'), 'invalid review output'); - // Manual runs remain useful review diagnostics, but never mint clearing evidence. - if (env.GITHUB_EVENT_NAME === 'workflow_dispatch') { - item.body += `\n\nManual Squad verdict: ${item.event} (diagnostic only).`; - item.event = 'COMMENT'; - writeFileSync(env.GH_AW_AGENT_OUTPUT, JSON.stringify(output)); - return; - } const value = { schema: 'squad-review-verdict/v1', repository: target.repository, pull_request: target.pull_request, + base_sha: target.base_sha, head_sha: target.head_sha, author_agent: target.author_agent, reviewer_agent: target.reviewer_agent, @@ -174,7 +321,9 @@ export async function enforceReviewOutputs(env, get) { timestamp: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'), run_id: Number(env.GITHUB_RUN_ID), run_attempt: Number(env.GITHUB_RUN_ATTEMPT), - event: 'pull_request', + event: 'pull_request_target', + workflow_path: WORKFLOW, + workflow_sha: target.workflow_sha, }; requireThat(Number.isSafeInteger(value.run_id) && value.run_id > 0 && Number.isSafeInteger(value.run_attempt) && value.run_attempt > 0, 'invalid workflow identity'); @@ -183,33 +332,48 @@ export async function enforceReviewOutputs(env, get) { // not a native bot approval/rejection, drives the independent status check. item.event = 'COMMENT'; // Native review commit binding and a final live read prevent stale agent output passing. - await reviewTarget(env, get); + await reviewTarget(env, get, options); writeFileSync(env.GH_AW_AGENT_OUTPUT, JSON.stringify(output)); } -export async function assertClearingReview(env, get, { relay = false } = {}) { - requireThat(env.GITHUB_EVENT_NAME === 'pull_request', 'only PR runs can clear review'); - const target = await reviewTarget(env, get, { relay }); - const candidates = await currentEvidence(target, get); - requireThat(candidates.length === 1, 'missing or duplicate verdict evidence'); - const review = candidates[0]; +export async function assertClearingReview(env, get, options = {}) { + const { relay = false } = options; + requireThat(env.GITHUB_EVENT_NAME === 'pull_request_target', + 'only base-controlled PR target runs can clear review'); + const target = await reviewTarget(env, get, { + ...options, + requireBootstrapRunSuccess: true, + }); + const candidates = (await currentEvidence(target, get)).map(review => ({ + review, + verdict: validateVerdict( + record(review.body, VERDICT_PREFIX), + target, + review, + relay ? timestamp(target.pr.merged_at) : Date.now(), + ), + })); + const bound = relay ? candidates : candidates.filter(({ verdict }) => + String(verdict.run_id) === env.GITHUB_RUN_ID && + String(verdict.run_attempt) === env.GITHUB_RUN_ATTEMPT); + requireThat(bound.length === 1, 'missing or duplicate verdict evidence for this run'); + const { review, verdict } = bound[0]; const cutoff = relay ? timestamp(target.pr.merged_at) : Date.now(); - const verdict = validateVerdict(record(review.body, VERDICT_PREFIX), target, review, cutoff); const run = await get(`repos/${target.repository}/actions/runs/${verdict.run_id}`); - requireThat(run.event === 'pull_request' && run.path === WORKFLOW && - run.repository?.full_name === target.repository && run.head_sha === target.head_sha && + requireThat(run.event === 'pull_request_target' && run.path === WORKFLOW && + run.repository?.full_name === target.repository && run.head_sha === target.workflow_sha && run.run_attempt >= verdict.run_attempt && run.display_title === `Squad review \u2014 PR #${target.pull_request}` && Array.isArray(run.pull_requests) && (run.pull_requests.length === 0 || run.pull_requests.some(pr => pr.number === target.pull_request && pr.head?.sha === target.head_sha && pr.base?.repo?.name === target.pr.base.repo.name)), 'verdict is not bound to this PR workflow run'); - requireThat(relay || String(verdict.run_id) === env.GITHUB_RUN_ID || - (run.status === 'completed' && run.conclusion === 'success'), - 'rerun the original PR review workflow to clear its failed verdict'); const attempt = run.run_attempt === verdict.run_attempt ? run : await get(`repos/${target.repository}/actions/runs/${verdict.run_id}/attempts/${verdict.run_attempt}`); - requireThat(attempt.run_attempt === verdict.run_attempt && + requireThat(attempt.event === 'pull_request_target' && attempt.path === WORKFLOW && + attempt.repository?.full_name === target.repository && + attempt.head_sha === target.workflow_sha && + attempt.run_attempt === verdict.run_attempt && timestamp(attempt.run_started_at) <= timestamp(verdict.timestamp) && (attempt.status !== 'completed' || timestamp(review.submitted_at) <= timestamp(attempt.updated_at)), 'verdict outside workflow run'); @@ -217,9 +381,44 @@ export async function assertClearingReview(env, get, { relay = false } = {}) { requireThat(run.status === 'completed' && run.conclusion === 'success', 'review run did not succeed'); const jobs = await list(get, `repos/${target.repository}/actions/runs/${verdict.run_id}/attempts/${run.run_attempt}/jobs`, 'jobs'); - const checks = jobs.filter(job => job.name === CHECK_NAME); - requireThat(checks.length === 1 && checks[0].conclusion === 'success' && - timestamp(checks[0].completed_at) <= cutoff, 'required review check did not pass before merge'); + const authorityJobs = jobs.filter(job => job.name === AUTHORITY_JOB); + requireThat(authorityJobs.length === 1 && authorityJobs[0].conclusion === 'success' && + timestamp(authorityJobs[0].completed_at) <= cutoff, + 'base-controlled review authority job did not pass before merge'); + const checkRuns = await list(get, + `repos/${target.repository}/commits/${target.head_sha}/check-runs`, 'check_runs'); + const externalId = + `${CHECK_EXTERNAL_ID}:${target.repository}:${target.pull_request}:${target.base_sha}:${target.head_sha}`; + const checks = checkRuns.filter(check => check.name === CHECK_NAME && + check.external_id === externalId && + Number.isSafeInteger(check.app?.id) && + check.app.id > 0 && + check.app.id !== ACTIONS_APP_ID && + typeof check.app?.slug === 'string' && + APP_SLUG.test(check.app.slug) && + check.app.slug !== ACTIONS_APP_SLUG); + requireThat(checks.length === 1, 'missing or duplicate exact-head authority check'); + const check = checks[0]; + requireThat(check.head_sha === target.head_sha && check.status === 'completed' && + check.conclusion === 'success' && + check.details_url === + `${env.GITHUB_SERVER_URL ?? 'https://github.com'}/${target.repository}/actions/runs/${verdict.run_id}`, + 'required review check is not attributable to the dedicated GitHub App'); + const summary = JSON.parse(check.output?.summary ?? ''); + requireThat(exactKeys(summary, [ + 'schema', 'repository', 'pull_request', 'base_sha', 'head_sha', 'workflow_sha', + 'run_id', 'run_attempt', 'event', 'workflow_path', 'authority_job', + 'publisher_app_id', 'publisher_app_slug', + ]) && summary.schema === CHECK_SCHEMA && summary.repository === target.repository && + summary.pull_request === target.pull_request && summary.base_sha === target.base_sha && + summary.head_sha === target.head_sha && summary.workflow_sha === target.workflow_sha && + summary.run_id === verdict.run_id && summary.run_attempt === run.run_attempt && + summary.event === 'pull_request_target' && summary.workflow_path === WORKFLOW && + summary.authority_job === AUTHORITY_JOB && + summary.publisher_app_id === check.app.id && + summary.publisher_app_slug === check.app.slug && + timestamp(check.completed_at) <= cutoff, + 'required review check attestation or dedicated App identity is invalid'); } if (verdict.result === 'REQUEST_CHANGES') { const comments = await list(get, `repos/${target.repository}/issues/${target.pull_request}/comments`); @@ -248,6 +447,9 @@ export async function assertClearingReview(env, get, { relay = false } = {}) { `repos/${target.repository}/collaborators/${comment.user.login}/permission`); requireThat(permission.permission === 'admin', 'override requires repository administrator'); } - await reviewTarget(env, get, { relay }); + await reviewTarget(env, get, { + ...options, + requireBootstrapRunSuccess: true, + }); return verdict; } diff --git a/workflows/skills/gh-aw-enlistment/SKILL.md b/workflows/skills/gh-aw-enlistment/SKILL.md index 54707c13a..a2bf36c08 100644 --- a/workflows/skills/gh-aw-enlistment/SKILL.md +++ b/workflows/skills/gh-aw-enlistment/SKILL.md @@ -182,17 +182,17 @@ uses a moving branch reference. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, + **`SQUAD_GITHUB_TOKEN`**, and **`SQUAD_REVIEW_APP_PRIVATE_KEY`** - Action: **`bradygaster/squad/.github/actions/squad-init`** -> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets -> the workflows *reference* so you can approve that surface — it is not asking you -> to supply them. Both secrets are optional, they need not exist, and neither is -> required to enlist a repository. Single-repo activation runs on the built-in -> `github.token`. Configure them only for cross-repo access or elevated -> permissions. Auth precedence: GitHub App token, then the PAT, then -> `github.token`. Never block an enlistment waiting for a credential. +> **Compilation approval is not credential provisioning.** `gh aw add` lists +> referenced names so you can approve the surface. `SQUAD_GITHUB_APP_PRIVATE_KEY` +> and `SQUAD_GITHUB_TOKEN` remain optional activation credentials. +> `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: trusted check publication requires +> it in the exact-default-branch `squad-review-authority` environment. Never put +> reviewer credentials at repository scope and never fall back to `github.token`. If — and only if — the report contains exactly those documented entries, complete the one-time approval: @@ -284,7 +284,27 @@ gh pr checks --watch `main`. - Request Copilot review, address feedback, and wait for required checks. -### 9. Never auto-merge — and explain what comes next +### 9. Verify the external review-authority prerequisite when API access permits + +Before claiming trusted review is ready, query the repository environment. It +must be named `squad-review-authority`, use custom deployment branch policies, +allow exactly the captured `${default_branch}`, contain the environment secret +`SQUAD_REVIEW_APP_PRIVATE_KEY`, and define environment variables +`SQUAD_REVIEW_APP_ID`, `SQUAD_REVIEW_APP_SLUG`, and +`SQUAD_REVIEW_APP_OWNER`. The App ID/slug must differ from +`15368`/`github-actions`. All four reviewer-specific names must also be absent +from repository-level Actions secrets and variables; repository fallback does +not satisfy this gate. + +If the authenticated account cannot read environment configuration, or any +requirement is absent, report the exact external prerequisite and do not claim +the required check is trusted. The installation PR remains a human boundary; +after it merges, the Cast canary intentionally fails closed until an +administrator provisions the environment and reruns the base-controlled +review. Configure a ruleset only from the canary check's observed App +integration ID, never from user input or a guessed value. + +### 10. Never auto-merge — and explain what comes next - **Never** merge the bootstrap PR yourself. Merge happens **only** after human approval. @@ -346,8 +366,9 @@ gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT mer ### ✓ Correct: STOP on an undocumented safe-update entry ```text -gh aw add reports a third secret: `ACME_DEPLOY_KEY`. -→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) +gh aw add reports an additional secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, + SQUAD_REVIEW_APP_PRIVATE_KEY) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -381,7 +402,8 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path. - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, - `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything + `SQUAD_GITHUB_TOKEN`, `SQUAD_REVIEW_APP_PRIVATE_KEY`, and + `bradygaster/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain `gh aw compile --strict` (no `--approve`). diff --git a/workflows/squad-bootstrap.md b/workflows/squad-bootstrap.md index 130efe8f8..ca9ee3058 100644 --- a/workflows/squad-bootstrap.md +++ b/workflows/squad-bootstrap.md @@ -158,7 +158,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "a8206bd6f8605915bd284b219a66db623eb2ee09a44a0ac51dd4304aed9d8b57" + check_hash "$install_verifier" "4f385df488cc65165e398e499663c015ce63851cb9c938f4c3dd0af38d25f991" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS @@ -465,14 +465,46 @@ safe-outputs: || pullRequestDetails.head.repo?.full_name !== provenance.repository) { throw new Error('Trusted bootstrap provenance inputs or Cast PR head identity are invalid.'); } - const provenanceMarker = ``; + const provenancePrefix = '<' + '!-- squad:bootstrap-provenance '; + const provenanceMarker = `${provenancePrefix}${JSON.stringify(provenance)} -->`; const prBodyWithoutProvenance = String(pullRequestDetails.body || payload.pr_body) - .replace(/^\r?\n?/gm, ''); + .replace(new RegExp(`^${provenancePrefix}.* -->\\r?\\n?`, 'gm'), ''); await github.rest.pulls.update({ ...context.repo, pull_number: pullRequest.number, body: `${provenanceMarker}\n${prBodyWithoutProvenance}`, }); + const provenanceComments = (await github.paginate( + github.rest.issues.listComments, + { + ...context.repo, + issue_number: pullRequest.number, + per_page: 100, + }, + )).filter((comment) => + String(comment.body || '').startsWith(provenancePrefix), + ); + if (provenanceComments.length > 1) { + throw new Error('Ambiguous bot-authenticated bootstrap provenance comments.'); + } + const provenanceCommentBody = + `${provenanceMarker}\nBase-controlled bootstrap provenance. Do not edit this comment.`; + if (provenanceComments.length === 1) { + if (provenanceComments[0].user?.login !== 'github-actions[bot]') { + throw new Error('Bootstrap provenance comment is not owned by GitHub Actions.'); + } + await github.rest.issues.updateComment({ + ...context.repo, + comment_id: provenanceComments[0].id, + body: provenanceCommentBody, + }); + } else { + await github.rest.issues.createComment({ + ...context.repo, + issue_number: pullRequest.number, + body: provenanceCommentBody, + }); + } const finalPayload = { ...payload, issue_body: payload.issue_body.replace('{{CAST_PR_URL}}', pullRequest.url), diff --git a/workflows/squad-review.md b/workflows/squad-review.md index a9ce2e8ee..84e34a0a3 100644 --- a/workflows/squad-review.md +++ b/workflows/squad-review.md @@ -1,30 +1,15 @@ --- name: Squad Review -run-name: "Squad review — PR #${{ github.event.inputs.issue_number || github.event.pull_request.number }}" +run-name: "Squad review — PR #${{ github.event.pull_request.number }}" description: Independently reviews agent-authored pull requests without editing or remediating private: false inlined-imports: true +strict: false on: - workflow_dispatch: - inputs: - issue_number: - description: Pull request number to review - required: true - type: string - expected_head_sha: - description: Pull request head SHA observed by the /squad review relay - required: true - type: string - request_origin: - description: Review request origin - required: true - type: string - pull_request: + pull_request_target: types: [opened, reopened, ready_for_review, synchronize] -if: >- - github.event_name == 'workflow_dispatch' || - (github.event_name == 'pull_request' && - github.event.pull_request.head.repo.full_name == github.repository) +if: github.event.pull_request.head.repo.full_name == github.repository +checkout: false permissions: contents: read copilot-requests: write @@ -32,14 +17,12 @@ permissions: pull-requests: read actions: read concurrency: - group: "squad-review-${{ github.event.inputs.issue_number || github.event.pull_request.number || github.run_id }}" + group: "squad-review-${{ github.event.pull_request.number }}" cancel-in-progress: true - job-discriminator: ${{ github.run_id }} network: allowed: - defaults tools: - bash: true github: min-integrity: approved mode: gh-proxy @@ -51,21 +34,16 @@ safe-outputs: - name: Checkout base commit for review guard uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: - ref: ${{ github.event.pull_request.base.sha || github.workflow_sha }} + ref: ${{ github.event.pull_request.base.sha }} persist-credentials: false path: .squad-review-base - - name: Checkout workflow commit for first-install review guard - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - ref: ${{ github.workflow_sha }} - persist-credentials: false - path: .squad-review-workflow - name: Bind review output to committed agent identities and current head uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 env: GH_AW_AGENT_OUTPUT: ${{ steps.setup-agent-output-env.outputs.GH_AW_AGENT_OUTPUT }} - SQUAD_REVIEW_PR: ${{ github.event.pull_request.number || github.event.inputs.issue_number }} - SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha || github.event.inputs.expected_head_sha }} + SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} + SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} + SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} with: script: | const { existsSync } = require('node:fs'); @@ -74,36 +52,28 @@ safe-outputs: `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/workflows/shared/squad-review-guard.mjs`; const baseManifest = `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/aw/squad-workflows.manifest.json`; - const workflowGuard = - `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/shared/squad-review-guard.mjs`; - let guardPath; - if (existsSync(baseGuard)) { - guardPath = baseGuard; - } else if (!existsSync(baseManifest)) { - guardPath = workflowGuard; - } else { + if (!existsSync(baseGuard) || !existsSync(baseManifest)) { throw new Error( - 'Squad Review guard is missing from an established base installation. Refusing workflow-source fallback.' + 'First-install manual boundary: the PR base does not contain the trusted Squad review guard and manifest. No trusted Squad verdict was emitted. Merge only with explicit human approval; trusted review begins on the post-merge bootstrap PR.' ); } - const guard = await import(pathToFileURL(guardPath).href); + const guard = await import(pathToFileURL(baseGuard).href); await guard.enforceReviewOutputs(process.env, async (route, fields) => (await github.request(`GET /${route}`, fields)).data); add-comment: max: 1 - target: "${{ github.event.inputs.issue_number || github.event.pull_request.number }}" + target: "${{ github.event.pull_request.number }}" create-pull-request-review-comment: max: 10 - target: "${{ github.event.inputs.issue_number || github.event.pull_request.number }}" + target: "${{ github.event.pull_request.number }}" submit-pull-request-review: max: 1 - target: "${{ github.event.inputs.issue_number || github.event.pull_request.number }}" + target: "${{ github.event.pull_request.number }}" allowed-events: [COMMENT, REQUEST_CHANGES] - commit-id: "${{ github.event.pull_request.head.sha || github.event.inputs.expected_head_sha }}" + commit-id: "${{ github.event.pull_request.head.sha }}" jobs: review: - # A manual run must never publish the required context, including a skipped one. - name: "${{ github.event_name == 'pull_request' && 'Squad Review / review' || 'Squad Review / manual' }}" + name: Squad Review Authority / attest if: always() needs: [agent, safe_outputs] runs-on: ubuntu-latest @@ -115,34 +85,24 @@ jobs: steps: - name: Require successful PR review execution env: - EVENT_NAME: ${{ github.event_name }} AGENT_RESULT: ${{ needs.agent.result }} OUTPUT_RESULT: ${{ needs.safe_outputs.result }} run: | set -euo pipefail - if [ "$EVENT_NAME" != pull_request ]; then exit 0; fi test "$AGENT_RESULT" = success test "$OUTPUT_RESULT" = success - name: Checkout base commit for final verdict gate - if: github.event_name == 'pull_request' uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: ${{ github.event.pull_request.base.sha }} persist-credentials: false path: .squad-review-base - - name: Checkout workflow commit for first-install final verdict gate - if: github.event_name == 'pull_request' - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - ref: ${{ github.workflow_sha }} - persist-credentials: false - path: .squad-review-workflow - name: Enforce independent current-head verdict - if: github.event_name == 'pull_request' uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 env: SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} + SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} with: script: | const { existsSync } = require('node:fs'); @@ -151,21 +111,167 @@ jobs: `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/workflows/shared/squad-review-guard.mjs`; const baseManifest = `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/aw/squad-workflows.manifest.json`; - const workflowGuard = - `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/shared/squad-review-guard.mjs`; - let guardPath; - if (existsSync(baseGuard)) { - guardPath = baseGuard; - } else if (!existsSync(baseManifest)) { - guardPath = workflowGuard; - } else { + if (!existsSync(baseGuard) || !existsSync(baseManifest)) { throw new Error( - 'Squad Review guard is missing from an established base installation. Refusing workflow-source fallback.' + 'First-install manual boundary: the PR base does not contain the trusted Squad review guard and manifest. No trusted Squad verdict was emitted. Merge only with explicit human approval; trusted review begins on the post-merge bootstrap PR.' ); } - const guard = await import(pathToFileURL(guardPath).href); + const guard = await import(pathToFileURL(baseGuard).href); await guard.assertClearingReview(process.env, async (route, fields) => (await github.request(`GET /${route}`, fields)).data); + publish: + name: Publish Squad Review required check + if: always() + needs: [agent, safe_outputs, review] + runs-on: ubuntu-latest + environment: squad-review-authority + permissions: + actions: read + contents: read + pull-requests: read + steps: + - name: Validate dedicated reviewer App configuration + env: + SQUAD_REVIEW_APP_ID: ${{ vars.SQUAD_REVIEW_APP_ID }} + SQUAD_REVIEW_APP_SLUG: ${{ vars.SQUAD_REVIEW_APP_SLUG }} + SQUAD_REVIEW_APP_OWNER: ${{ vars.SQUAD_REVIEW_APP_OWNER }} + SQUAD_REVIEW_APP_PRIVATE_KEY: ${{ secrets.SQUAD_REVIEW_APP_PRIVATE_KEY }} + run: | + set -euo pipefail + test "${SQUAD_REVIEW_APP_ID}" != "15368" + test "${SQUAD_REVIEW_APP_SLUG}" != "github-actions" + [[ "${SQUAD_REVIEW_APP_ID}" =~ ^[1-9][0-9]*$ ]] + [[ "${SQUAD_REVIEW_APP_SLUG}" =~ ^[a-z0-9][a-z0-9-]*$ ]] + [[ "${SQUAD_REVIEW_APP_OWNER}" =~ ^[A-Za-z0-9_.-]+$ ]] + test -n "${SQUAD_REVIEW_APP_PRIVATE_KEY}" + - name: Mint dedicated reviewer App token + id: squad-review-app-token + uses: actions/create-github-app-token@v3.2.0 + with: + app-id: ${{ vars.SQUAD_REVIEW_APP_ID }} + private-key: ${{ secrets.SQUAD_REVIEW_APP_PRIVATE_KEY }} + owner: ${{ vars.SQUAD_REVIEW_APP_OWNER }} + - name: Publish exact-head required check + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + env: + AUTHORITY_RESULT: ${{ needs.review.result }} + SQUAD_REVIEW_APP_ID: ${{ vars.SQUAD_REVIEW_APP_ID }} + SQUAD_REVIEW_APP_SLUG: ${{ vars.SQUAD_REVIEW_APP_SLUG }} + SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} + SQUAD_REVIEW_BASE: ${{ github.event.pull_request.base.sha }} + SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} + SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} + with: + github-token: ${{ steps.squad-review-app-token.outputs.token }} + script: | + const checkName = 'Squad Review / review'; + const authorityJob = 'Squad Review Authority / attest'; + const repository = process.env.GITHUB_REPOSITORY; + const [owner, repo] = repository.split('/'); + const expectedAppId = Number(process.env.SQUAD_REVIEW_APP_ID); + const expectedAppSlug = process.env.SQUAD_REVIEW_APP_SLUG; + const pullRequest = Number(process.env.SQUAD_REVIEW_PR); + const baseSha = process.env.SQUAD_REVIEW_BASE; + const headSha = process.env.SQUAD_REVIEW_HEAD; + const workflowSha = process.env.SQUAD_REVIEW_WORKFLOW_SHA; + const runId = Number(process.env.GITHUB_RUN_ID); + const runAttempt = Number(process.env.GITHUB_RUN_ATTEMPT); + if (!Number.isSafeInteger(expectedAppId) || expectedAppId < 1 || + expectedAppId === 15368 || + !/^[a-z0-9][a-z0-9-]*$/.test(expectedAppSlug) || + expectedAppSlug === 'github-actions' || + !Number.isSafeInteger(pullRequest) || pullRequest < 1 || + !/^[0-9a-f]{40}$/.test(baseSha) || !/^[0-9a-f]{40}$/.test(headSha) || + workflowSha !== baseSha || !Number.isSafeInteger(runId) || runId < 1 || + !Number.isSafeInteger(runAttempt) || runAttempt < 1) { + core.setFailed('Invalid base-controlled Squad review check context.'); + return; + } + const run = (await github.rest.actions.getWorkflowRun({ + owner, repo, run_id: runId, + })).data; + if (run.event !== 'pull_request_target' || + run.path !== '.github/workflows/squad-review.lock.yml' || + run.head_sha !== workflowSha || + run.repository.full_name !== repository) { + core.setFailed('Squad review check is not bound to the base-controlled workflow run.'); + return; + } + const jobs = await github.paginate(github.rest.actions.listJobsForWorkflowRunAttempt, { + owner, repo, run_id: runId, attempt_number: runAttempt, per_page: 100, + }); + const authorityJobs = jobs.filter(job => job.name === authorityJob); + if (authorityJobs.length !== 1) { + core.setFailed('Missing or duplicate base-controlled Squad review authority job.'); + return; + } + const succeeded = process.env.AUTHORITY_RESULT === 'success' && + authorityJobs[0].conclusion === 'success'; + const externalId = + `squad-review-authority/v1:${repository}:${pullRequest}:${baseSha}:${headSha}`; + const existing = await github.paginate(github.rest.checks.listForRef, { + owner, repo, ref: headSha, check_name: checkName, per_page: 100, + }); + const owned = existing.filter(check => + check.external_id === externalId && + check.app?.id === expectedAppId && + check.app?.slug === expectedAppSlug); + if (owned.length > 1) { + core.setFailed('Duplicate exact-head Squad review authority checks.'); + return; + } + const detailsUrl = + `${process.env.GITHUB_SERVER_URL}/${repository}/actions/runs/${runId}`; + const output = { + title: succeeded + ? 'Base-controlled Squad review passed' + : 'Base-controlled Squad review did not pass', + summary: JSON.stringify({ + schema: 'squad-review-check/v1', + repository, + pull_request: pullRequest, + base_sha: baseSha, + head_sha: headSha, + workflow_sha: workflowSha, + run_id: runId, + run_attempt: runAttempt, + event: 'pull_request_target', + workflow_path: '.github/workflows/squad-review.lock.yml', + authority_job: authorityJob, + publisher_app_id: expectedAppId, + publisher_app_slug: expectedAppSlug, + }), + }; + const request = { + owner, repo, name: checkName, head_sha: headSha, + status: 'completed', + conclusion: succeeded ? 'success' : 'failure', + details_url: detailsUrl, + external_id: externalId, + output, + }; + const published = owned.length === 1 + ? await github.rest.checks.update({ + ...request, + check_run_id: owned[0].id, + }) + : await github.rest.checks.create(request); + if (published.data.app?.id !== expectedAppId || + published.data.app?.slug !== expectedAppSlug) { + try { + await github.rest.checks.delete({ + owner, repo, check_run_id: published.data.id, + }); + } finally { + core.setFailed( + 'Squad review check was not published by the configured dedicated GitHub App.' + ); + } + return; + } + if (!succeeded) { + core.setFailed('Base-controlled Squad review authority did not succeed.'); + } --- # Squad Review @@ -181,19 +287,22 @@ this workflow. ## Trigger and target gate 1. Resolve the pull request number from - `${{ github.event.inputs.issue_number || github.event.pull_request.number }}`. + `${{ github.event.pull_request.number }}`. If it is absent or not a positive integer, call `noop` and stop. 2. Fetch the pull request from `${{ github.repository }}` and record its current 40-character lowercase head SHA. -3. For `workflow_dispatch`, require `request_origin` to equal `manual` and - `expected_head_sha` to equal the current head SHA. A missing, malformed, or - stale value, or a head repository other than `${{ github.repository }}`, is a - refusal: call `noop` and stop. This is the `/squad review` path relayed by - `workflows/squad.md`. -4. For `pull_request`, require the head repository to equal +3. Require the head repository to equal `${{ github.repository }}`. Forks and any event other than `opened`, `reopened`, `ready_for_review` or `synchronize` are refused with `noop`. +This base-controlled `pull_request_target` workflow has no `workflow_dispatch` +trigger and never checks out or executes pull request content. The agent reads +the pull request diff and repository evidence only through GitHub APIs. +`/squad review` is an operator +aid that points to GitHub's **Re-run jobs** action for the existing automatic +run. Never execute reviewer code, guards, manifests, or safe-output handlers +from a manually selected ref. + Read `.squad-review.json` at the exact PR head SHA and the committed `.squad/casting/registry.json` at the PR base SHA. The attribution schema is `squad-review-author/v1` with `repository`, positive integer `issue`, @@ -201,9 +310,29 @@ Read `.squad-review.json` at the exact PR head SHA and the committed `persistent_name` entries in that registry, and must differ. Act as that `reviewer_agent`, reading its base-commit charter. Missing or malformed attribution is a refusal, never a fallback to a display name or GitHub login. -The deterministic output guard and final job repeat these checks. A refusal, -missing verdict, stale head, or malformed provenance cannot clear the required -`Squad Review / review` check. +The deterministic output guard and authority job repeat these checks. The +publisher creates `Squad Review / review` on the exact PR head only after the +native `Squad Review Authority / attest` job in the same base-controlled run +succeeds. A refusal, missing verdict, stale head, malformed provenance, or +same-named PR-controlled check cannot clear the authority contract. + +The workflow-installation PR is an explicit human trust boundary. Its base does +not contain this workflow, guard, or manifest, so no trusted automatic Squad +review runs. No code, job name, check result, or review record emitted by that +PR is a trusted Squad verdict. Merge the installation only through explicit +human review of the generated package. + +Trusted review starts on the automatic post-merge Cast PR. The guard is then +loaded only from the exact PR base commit, where the installed manifest also +exists. That base-controlled guard permits missing `.squad-review.json` only +for the exact `squad/bootstrap-cast` PR created by the base-controlled bootstrap +workflow. It verifies the GitHub Actions bot author, canonical title and branch, +matching provenance in the PR body and a durable bot-authored PR comment, exact +base/head SHAs, and the referenced default-branch `squad-bootstrap.lock.yml` +push run. It binds the reserved roles +`@squad/base-controlled-bootstrap` and `@squad/base-controlled-review`; the +clearing gate additionally requires that bootstrap run to finish successfully. +All other missing, malformed, or non-404 attribution evidence is refused. ## Provenance decision tree @@ -243,11 +372,15 @@ machine-readable review marker is a standalone final line: `Squad-Review-Head: {40-character lowercase head SHA}` If an existing bot review contains a `Squad-Review-Verdict:` record for the -current head SHA, call `noop` and stop. The deterministic gate validates it; -an arbitrary comment or the legacy head marker is not clearing evidence. -Never re-review an unchanged head, including duplicate -`synchronize` deliveries. Re-fetch the pull request immediately before emitting -outputs; if its head SHA changed, call `noop` and let the newer run review it. +current head SHA and this exact workflow run ID and attempt, call `noop` and +stop. Evidence from a different run or attempt cannot deduplicate or clear this +run. The deterministic gate validates the `pull_request_target` event, immutable +workflow SHA, workflow path, PR, base, head, run, attempt, native authority job, +exact-head published check, and GitHub Actions App/bot identity; an arbitrary +comment, PR-controlled workflow, same-named check, or legacy head marker is not +clearing evidence. Re-fetch the pull request +immediately before emitting outputs; if its head SHA changed, call `noop` and +let the newer run review it. ## Review procedure @@ -282,12 +415,11 @@ Submit exactly one review: Do not emit `Squad-Review-Verdict:` or `Squad-Review-Override:` yourself. The trusted safe-output guard adds the repository, PR, head SHA, stable -author/reviewer IDs, result, timestamp and workflow-run binding. Only -`pull_request` runs mint this evidence; manual `/squad review` is diagnostic -and does not satisfy the required check. A valid `REQUEST_CHANGES` keeps the -check red unless an administrator posts the documented SHA- and review-scoped -override and reruns the PR workflow. Overrides cannot repair invalid identity -or missing evidence. Never approve or merge on behalf of a human. +author/reviewer IDs, result, timestamp and exact automatic workflow-run binding. +Manual dispatch does not exist. A valid `REQUEST_CHANGES` keeps the check red +unless an administrator posts the documented SHA- and review-scoped override +and reruns the same PR workflow. Overrides cannot repair invalid identity or +missing evidence. Never approve or merge on behalf of a human. Keep the body concise. State the provenance classification, linked issue scope, and blocking themes. End with these two standalone lines, substituting the diff --git a/workflows/squad-workflows.manifest.json b/workflows/squad-workflows.manifest.json index 2bb0c4e5d..7c6ab32ba 100644 --- a/workflows/squad-workflows.manifest.json +++ b/workflows/squad-workflows.manifest.json @@ -14,56 +14,64 @@ "source": "workflows/package/squad.md", "destination": ".github/workflows/squad.md", "lock": ".github/workflows/squad.lock.yml", - "source_sha256": "17d7b124e5d3f06d8c1ea67a7330366b40f3e69d2209e8477fe4fa38a1ae38b0" + "source_sha256": "bb7f231c852dfb73c5d1a6ba5e9f23f9f7c9fc5af9e1f1021c4c5213fd9389f9", + "lock_sha256": "f2e62f0ded2b937c99dcdab321f1ea2f886ff2f0537a324af4342908466a2bcf" }, { "name": "squad-implement-worker", "source": "workflows/package/squad-implement-worker.md", "destination": ".github/workflows/squad-implement-worker.md", "lock": ".github/workflows/squad-implement-worker.lock.yml", - "source_sha256": "ae710dd5c89360af540576dac378a0d0df129cce5a9bbf16f0615dfd86d0b21c" + "source_sha256": "ae710dd5c89360af540576dac378a0d0df129cce5a9bbf16f0615dfd86d0b21c", + "lock_sha256": "d6d2fa7f2bac5845c414cf42a9ea565d3663dba23d9208942fe142fca6b23bc3" }, { "name": "squad-review", "source": "workflows/package/squad-review.md", "destination": ".github/workflows/squad-review.md", "lock": ".github/workflows/squad-review.lock.yml", - "source_sha256": "cae3f9ca8a32ca76cfd873941fafe38319fa53b35fb3478c2338732b8b9f63fd" + "source_sha256": "27adf384cbe16c11ec89f4ecd76c9087a409c911ab9760575a3254b1d21dfb56", + "lock_sha256": "c3ed91988744077da65cbbc8a77a6d262bf4dca3bbfc593ab520283c3e9ced6b" }, { "name": "squad-deps-worker", "source": "workflows/package/squad-deps-worker.md", "destination": ".github/workflows/squad-deps-worker.md", "lock": ".github/workflows/squad-deps-worker.lock.yml", - "source_sha256": "37c4ba60b85c5fc07bef322bbfd0f713472924d55cff9481ae76af7ec0c91fac" + "source_sha256": "37c4ba60b85c5fc07bef322bbfd0f713472924d55cff9481ae76af7ec0c91fac", + "lock_sha256": "d5a8c0b1eb7933bb4bb74499fd9de872b6d55045665f918c831658f8baa20f71" }, { "name": "squad-retro", "source": "workflows/package/squad-retro.md", "destination": ".github/workflows/squad-retro.md", "lock": ".github/workflows/squad-retro.lock.yml", - "source_sha256": "92bcfa39cc5fd3087b11612125e314959237c5b79460825453d1e493727a2562" + "source_sha256": "92bcfa39cc5fd3087b11612125e314959237c5b79460825453d1e493727a2562", + "lock_sha256": "00771decb93b93d04ea9c9e6173c2338eef615e49df0a8ca12729680fa15fc52" }, { "name": "squad-improvement-worker", "source": "workflows/package/squad-improvement-worker.md", "destination": ".github/workflows/squad-improvement-worker.md", "lock": ".github/workflows/squad-improvement-worker.lock.yml", - "source_sha256": "01c89f8890f02c0ca884513aa10225787feaf3606ab604d5c0e85fbbccdb6c95" + "source_sha256": "01c89f8890f02c0ca884513aa10225787feaf3606ab604d5c0e85fbbccdb6c95", + "lock_sha256": "880b7673b022d6155870d87b70e6d6a2489eb7eefec64fcf3515041d5ca5c42e" }, { "name": "squad-bootstrap", "source": "workflows/package/squad-bootstrap.md", "destination": ".github/workflows/squad-bootstrap.md", "lock": ".github/workflows/squad-bootstrap.lock.yml", - "source_sha256": "a7d9d072d4a626c1d35677fa323f3b7af7a66efe0eca4b3b94042eb1c656d3a7" + "source_sha256": "9df28d8e4094b66e7ddf4aed1ff3626efaa65c1dcd3815984d70573b40af640d", + "lock_sha256": "9a23ee0bd51cd7dd69b91538872a3fce0fb2376423ce8ac56c7c9f6f5b7f4b1b" }, { "name": "squad-command-router", "source": "workflows/package/squad-command-router.md", "destination": ".github/workflows/squad-command-router.md", "lock": ".github/workflows/squad-command-router.lock.yml", - "source_sha256": "cbce466a6cfe64c194b17672ea3363fe7c22cb6b4258c195cc93a2d294d0bf88" + "source_sha256": "cbce466a6cfe64c194b17672ea3363fe7c22cb6b4258c195cc93a2d294d0bf88", + "lock_sha256": "9c5bf2b28dc82a575c528ce73a75c38b54129d512341e10cdce2a6e12ceecb4b" } ], "shared_runtime": [ @@ -73,7 +81,7 @@ "package_destination": ".github/workflows/shared/squad-review-guard.mjs", "destination": ".github/workflows/shared/squad-review-guard.mjs", "ownership": "manifest", - "sha256": "82ba4b8bc7262d53c0d849acd4468a0495827c60ed0f0715449aa4b8365c30b4" + "sha256": "6685f7e16b4ee13958bcdddf2a868a287f76b26913b0c17c4a943b398bbb4938" }, { "path": "shared/squad-install-verifier.mjs", @@ -81,7 +89,7 @@ "package_destination": ".github/workflows/shared/squad-install-verifier.mjs", "destination": ".github/workflows/shared/squad-install-verifier.mjs", "ownership": "manifest", - "sha256": "a8206bd6f8605915bd284b219a66db623eb2ee09a44a0ac51dd4304aed9d8b57" + "sha256": "4f385df488cc65165e398e499663c015ce63851cb9c938f4c3dd0af38d25f991" }, { "path": "shared/squad-command-contract.mjs", @@ -209,7 +217,7 @@ "name": "gh-aw-enlistment", "source": "workflows/skills/gh-aw-enlistment/SKILL.md", "destination": ".github/skills/gh-aw-enlistment/SKILL.md", - "sha256": "697f16b5dd4dab722e39c631511b9ba274143b4ec676dbe6d5304f2835f62bfd" + "sha256": "2123f535c9fa5863d85fbed89ec5820579222eb39d279ffe1dea9a79a13fbadb" } ], "bootstrap": { diff --git a/workflows/squad.md b/workflows/squad.md index a2ea0d56c..f5c43b20d 100644 --- a/workflows/squad.md +++ b/workflows/squad.md @@ -32,6 +32,7 @@ if: >- github.event.issue.title != '[Research Proposals] Agent-discovered repo opportunities' || !contains(github.event.issue.body, '') permissions: + actions: read contents: read copilot-requests: write issues: read @@ -423,7 +424,7 @@ safe-outputs: max: 20 target: "*" dispatch-workflow: - workflows: [squad-implement-worker, squad-deps-worker, squad-review, squad-retro, squad-improvement-worker] + workflows: [squad-implement-worker, squad-deps-worker, squad-retro, squad-improvement-worker] max: 3 --- @@ -1124,32 +1125,44 @@ and includes the verified PR number, URL, and CI-approval guidance. ## skill: `squad-review-relay` --- -description: Relay `/squad review` on a pull request to the independent reviewer. +description: Guide an operator to rerun the automatic independent review. --- This mode is only valid from a pull request comment or pull request review comment. Resolve the pull request number and current 40-character lowercase head SHA from GitHub's API, not from user text. If either cannot be established, post one `add-comment` explaining that `/squad review` must target a pull -request, then stop without dispatching. - -Use only the typed `dispatch-workflow` safe-output. Never call the generic -`dispatch_workflow` tool. Emit exactly one dispatch: - -```json -{ - "workflow_name": "squad-review", - "inputs": { - "issue_number": "{pull-request-number}", - "expected_head_sha": "{current-head-sha}", - "request_origin": "manual" - } -} -``` +request, then stop. + +List workflow runs for `.github/workflows/squad-review.lock.yml`. Keep only +`pull_request_target` runs associated with this pull request whose workflow +head SHA equals the pull request's exact base SHA. Select the newest run by +creation time, breaking ties by numeric run ID, then fetch its jobs and require +exactly one job named `Squad Review Authority / attest`. Also fetch check runs +for the exact current PR head and require exactly one `Squad Review / review` +check whose external ID, details URL, GitHub Actions App identity, and +`squad-review-check/v1` summary bind that base-controlled run, PR, base SHA, +head SHA, run ID, and attempt. A same-named check without that binding is +advisory only. If no matching run or authority check exists, emit exactly one +`add-comment` stating that no base-controlled automatic review run exists for +the exact head and that a new PR event +(`synchronize`, reopen, or ready-for-review) is required. Stop without implying +that a rerun occurred. + +Otherwise emit exactly one `add-comment` on the pull request that includes the +selected run URL, run ID, attempt, status, conclusion, exact head SHA, and this +instruction: + +> Squad Review is automatic and cannot be dispatched from a branch. In the +> selected base-controlled automatic run, choose **Re-run all jobs**. This +> command did not rerun it. Only the new attempt of that exact +> `pull_request_target` run can publish verdict evidence and the exact-head +> `Squad Review / review` check for PR #{pull-request-number} +> at head `{current-head-sha}`. Do not review the diff in this router, emit a verdict, edit files, create an -issue, or dispatch any other workflow. The independent reviewer owns all -provenance, deduplication, and review decisions. +issue, or dispatch a workflow. The independent reviewer owns all provenance, +deduplication, and review decisions. ## skill: `squad-retro-relay` ---