Merge pull request #2197 from bradygaster/bradygaster-align-squad-gh-aw-compiler

fix(gh-aw): repair signed Cast review evidence and generation guidance

Author: bradygaster

.changeset/native-review-bootstrap-provenance.md

@@ -0,0 +1,9 @@
+---
+"@bradygaster/squad-cli": patch
+"@bradygaster/squad-sdk": patch
+---
+
+Give the native review safe-output guard read access to same-repository workflow
+run evidence needed for signed Bootstrap provenance. Correct Cast generation
+guidance for Scribe's decision-only role and native specialist assignment.
+Document reviewed fresh generation rather than amending a signed Cast head.

docs/src/content/docs/guide/gh-aw.md

@@ -262,6 +262,14 @@ permissions.
 
 ### Explicit fresh bootstrap after a failed attempt
 
+Signed Cast provenance binds the exact generated head commit (`cast_sha`).
+Do not amend that branch or rewrite provenance to fix review findings. Correct
+the generation guidance in the trusted package, then use the reviewed fresh
+generation procedure below. The replacement Cast receives new provenance and
+still requires independent review and human approval. An automatic review
+infrastructure failure does not authorize bypassing the guard or merging the
+original Cast.
+
 Closing an unmerged Cast PR still means **opt out**. Ordinary pushes, blank
 manual runs, renaming that PR, or deleting its branch do not undo that decision.
 To intentionally start over without deleting history, a maintainer can prepare

test/gh-aw-bootstrap-workflow.test.ts

@@ -614,6 +614,21 @@ afterAll(() => {
 });
 
 describe('automatic Squad bootstrap workflow', () => {
+  it('keeps generated support and routing guidance consistent with native contracts', () => {
+    const dispatcher = readFileSync(resolve(ROOT, 'workflows/squad.md'), 'utf8');
+    for (const source of [WORKFLOW, dispatcher]) {
+      const normalized = source.replace(/\s+/g, ' ');
+      expect(normalized).toContain('accepted durable decisions only, never session or orchestration logs');
+      expect(normalized).toContain('`squad:{member}` labels as specialist assignment');
+      expect(normalized).toContain('bare `squad` label is a tracking marker');
+      expect(normalized).toContain('A name mention alone does not dispatch a native workflow');
+      expect(source).not.toContain('Scribe logs sessions');
+    }
+    const guide = readFileSync(resolve(ROOT, 'docs/src/content/docs/guide/gh-aw.md'), 'utf8');
+    expect(guide).toContain('Do not amend that branch or rewrite provenance');
+    expect(guide.replace(/\s+/g, ' ')).toContain('reviewed fresh generation procedure');
+  });
+
   it('pins the canonical bootstrap validator digest in the authenticated runner', () => {
     const canonical = readFileSync(VALIDATOR);
     const commandDigest = WORKFLOW.match(

test/gh-aw-review-guard.test.ts

@@ -420,6 +420,27 @@ describe('independent Squad review guard', () => {
       .rejects.toThrow('missing or duplicate base-controlled bootstrap PR provenance');
   });
 
+  it('preserves review output when signed bootstrap run evidence is inaccessible', async () => {
+    const f = fixture();
+    makeBootstrap(f);
+    const workspace = mkdtempSync(join(tmpdir(), 'squad-review-run-permission-'));
+    workspaces.push(workspace);
+    const path = join(workspace, 'output.json');
+    const original = JSON.stringify({ items: [{
+      type: 'submit_pull_request_review', event: 'COMMENT', body: 'Bootstrap Cast reviewed.',
+    }] });
+    writeFileSync(path, original);
+    const get = async (route: string, fields?: Record<string, unknown>) => {
+      if (route === `repos/${REPOSITORY}/actions/runs/29`) {
+        throw Object.assign(new Error('Resource not accessible by integration'), { status: 403 });
+      }
+      return f.get(route, fields);
+    };
+    await expect(enforceReviewOutputs({ ...f.env, GH_AW_AGENT_OUTPUT: path }, get))
+      .rejects.toThrow('Resource not accessible by integration');
+    expect(readFileSync(path, 'utf8')).toBe(original);
+  });
+
   it.each([
     ['branch', (f: ReturnType<typeof fixture>) => { f.pr.head.ref = 'attacker/bootstrap'; }],
     ['title', (f: ReturnType<typeof fixture>) => { f.pr.title = 'Trusted bootstrap'; }],

test/gh-aw-review-workflow.test.ts

@@ -513,7 +513,8 @@ describe('gh-aw enforcing Squad reviewer', () => {
     expect(permissionBlock).toContain('pull-requests: read');
     expect(permissionBlock).toContain('copilot-requests: write');
     expect(permissionBlock).not.toMatch(/^\s+(contents|issues|pull-requests): write$/m);
-    expect(safeOutputPermissions).toMatchObject({
+    expect(safeOutputPermissions).toEqual({
+      actions: 'read',
       contents: 'read',
       issues: 'write',
       'pull-requests': 'write',

workflows/package/squad-bootstrap.md

@@ -802,6 +802,14 @@ sections. The coordinator has concrete Cast-source paths and one synchronized,
 nonzero Team Capabilities block. Remove bootstrap specialist directories not
 selected by this Cast, but never remove or rewrite the four built-ins.
 
+In the coordinator and team introduction, describe Scribe as silently merging
+accepted durable decisions only, never session or orchestration logs. The
+canonical support charters govern when support agents run.
+Document `squad:{member}` labels as specialist assignment, using exact active
+registry names and `.squad/routing.md`. The bare `squad` label is a tracking marker,
+not specialist assignment. A name mention alone does not dispatch a native
+workflow; use documented `/squad` commands with their prerequisites.
+
 ## Shared payload
 
 Write `.github/workflows/squad-bootstrap-payload.json` with this exact shape:

workflows/package/squad-review.md

@@ -79,6 +79,9 @@ safe-outputs:
       - REQUEST_CHANGES
     commit-id: ${{ github.event.pull_request.head.sha }}
 jobs:
+  safe_outputs:
+    permissions:
+      actions: read
   review:
     name: review
     if: always()

workflows/package/squad.md

@@ -2109,7 +2109,7 @@ Create/replace:
    - `# Squad Coordinator` plus one short paragraph establishing that the coordinator routes work and does not replace specialist judgment.
    - `## Cast sources` listing only the concrete final Cast paths for the team, routing, registry, history, policy, meet-the-squad, every active specialist member charter, and the four built-in charter paths (`.squad/agents/scribe/charter.md`, `.squad/agents/ralph/charter.md`, `.squad/agents/rai/charter.md`, `.squad/agents/fact-checker/charter.md`). Do not use path globs or dynamic paths.
    - `## Routing work` with this behavior: read the routing table, select only active registry members, load only the selected member's charter, delegate through the platform's available agent mechanism, and synthesize the result for the user. If no route matches, choose the active Lead; if no active Lead exists, ask the user rather than inventing a member.
-   - `## Built-in Support Agents` — concise operational instructions establishing that Scribe, Ralph, Rai, and Fact Checker are mandatory always-on support agents with a fixed lifecycle role (Scribe logs sessions and merges decisions silently in the background; Ralph monitors the work queue on request; Rai reviews for RAI/content-safety concerns and can gate on 🔴 Critical findings; Fact Checker verifies claims and offers Devil's-Advocate review before risky work ships). Never present them as selectable domain specialists, never list them as routing-table destinations, and never count them toward `specialists`, `taskTypes`, or `hints`.
+   - `## Built-in Support Agents` — concise operational instructions establishing that Scribe, Ralph, Rai, and Fact Checker are mandatory support agents with a fixed lifecycle role (Scribe silently merges accepted durable decisions only, never session or orchestration logs; Ralph monitors the work queue on request; Rai reviews for RAI/content-safety concerns and can gate on 🔴 Critical findings; Fact Checker verifies claims and offers Devil's-Advocate review before risky work ships). Their canonical charters govern when they run. Never present them as selectable domain specialists, never list them as routing-table destinations, and never count them toward `specialists`, `taskTypes`, or `hints`.
    - One complete generated Team Capabilities block delimited by `<!-- SQUAD:TEAM-CAPABILITIES:BEGIN -->` and `<!-- SQUAD:TEAM-CAPABILITIES:END -->`. Preserve the stable heading, metadata, specialist table, supported task types, routing hints, and capability boundaries format. Set `specialists` to the active registry count and set both `taskTypes` and `hints` to the routing-row count; all three counts must be nonzero and must never include the four built-ins. Generate every value from the final team, routing, registry, and active specialist charters.
 
    The coordinator must be self-contained for the final Cast tree. It must not mention standalone lifecycle behavior, templates, configuration, decisions, plugins, logs, non-GH-AW clients, internal Squad source paths, or sample labels/names that are not active registry members. The four built-in charter references and the `## Built-in Support Agents` section are the one permitted exception to "no inactive/support roles" content — they are mandatory, not inactive, and must never be phrased as selectable specialists or routing destinations.
@@ -2119,6 +2119,7 @@ Keep naming consistent across generated team state and the Cast PR summary. In d
 ##### Step 5: Generate meet-the-squad.md
 
 Create `meet-the-squad.md` at repo root with: title, naming mode (`Descriptive` in descriptive mode; otherwise the exact universe name), active team table (Name|Role|Specialty|How to talk), How to Work With Your Squad (label-based assignment with `9B8FCC` color, iteration commands, routing reference), "What Happened Here" block with analysis rationale (languages, structure, CI/CD, rationale), footer with cast date. Do not advertise the four built-ins or any other inactive/support role as a selectable specialist.
+Document `squad:{member}` labels as specialist assignment, using exact active registry names and `.squad/routing.md`. The bare `squad` label is a tracking marker, not specialist assignment. A name mention alone does not dispatch a native workflow; use documented `/squad` commands with their prerequisites.
 
 ##### Step 6: Build the Safe-Output Payload
 

workflows/squad-bootstrap.md

@@ -792,6 +792,14 @@ sections. The coordinator has concrete Cast-source paths and one synchronized,
 nonzero Team Capabilities block. Remove bootstrap specialist directories not
 selected by this Cast, but never remove or rewrite the four built-ins.
 
+In the coordinator and team introduction, describe Scribe as silently merging
+accepted durable decisions only, never session or orchestration logs. The
+canonical support charters govern when support agents run.
+Document `squad:{member}` labels as specialist assignment, using exact active
+registry names and `.squad/routing.md`. The bare `squad` label is a tracking marker,
+not specialist assignment. A name mention alone does not dispatch a native
+workflow; use documented `/squad` commands with their prerequisites.
+
 ## Shared payload
 
 Write `.github/workflows/squad-bootstrap-payload.json` with this exact shape:

workflows/squad-review.md

@@ -72,6 +72,9 @@ safe-outputs:
     allowed-events: [COMMENT, REQUEST_CHANGES]
     commit-id: "${{ github.event.pull_request.head.sha }}"
 jobs:
+  safe_outputs:
+    permissions:
+      actions: read
   review:
     name: review
     if: always()