fix(gh-aw): preserve ownership staging with bounded index verification

.changeset/verified-gh-aw-ownership-staging.md

@@ -0,0 +1,6 @@
+---
+"@bradygaster/squad-cli": patch
+"@bradygaster/squad-sdk": patch
+---
+
+Preserve manifest-allowlisted gh-aw ownership metadata through broad consumer ignore rules by force-staging only the exact required ownership file. Verify every required artifact's staged type and bytes before commit or push, using bounded index queries that exclude unrelated consumer files.

.squad-templates/skills/gh-aw-enlistment/SKILL.md

@@ -11,7 +11,7 @@ tools:
     when: "Every step: preflight identity/auth, requiring Issues, enabling Actions-created PRs, opening and watching the bootstrap PR."
   - name: "gh aw"
     description: "GitHub Agentic Workflows extension (github/gh-aw) — installs and strictly compiles the Squad workflow set."
-    when: "Installing the immutable native Squad package and compiling its seven workflows into deterministic .lock.yml files."
+    when: "Installing the immutable native Squad package and compiling its eight workflows into deterministic .lock.yml files."
 ---
 
 ## Context
@@ -146,7 +146,7 @@ gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
 
 The nested `workflows/aw.yml` is the only supported distribution registration.
 It isolates package auto-discovery from unrelated repository skills and agents,
-and installs exactly seven workflows, fifteen runtime resources, and one
+and installs exactly eight workflows, seventeen runtime resources, and one
 `gh-aw-enlistment` skill at the same resolved revision:
 
 - `squad.md` + `squad.lock.yml`
@@ -156,11 +156,12 @@ and installs exactly seven workflows, fifteen runtime resources, and one
 - `squad-retro.md` + `squad-retro.lock.yml`
 - `squad-improvement-worker.md` + `squad-improvement-worker.lock.yml`
 - `squad-bootstrap.md` + `squad-bootstrap.lock.yml`
+- `squad-command-router.md` + `squad-command-router.lock.yml`
 
 `squad-improvement-worker` is part of the standard, coherent install above —
 not a separate opt-in add-on. It stays dormant until a maintainer approves a
 governance-scoped retrospective proposal (see the gh-aw guide's retrospective
-auto-implementation section); installing it alongside the other six keeps the
+auto-implementation section); installing it alongside the other seven keeps the
 full stack consistent and avoids a second bootstrap pass later.
 
 Report/proposal-only is the default. Ordinary fixes require the explicit
@@ -220,7 +221,7 @@ node .github/workflows/shared/squad-install-verifier.mjs \
 This must run after any first-install approval and before committing. Success
 criteria:
 
-- All seven workflows compile successfully.
+- All eight workflows compile successfully.
 - The **only** permitted warning is the known `squad.md` bot-trigger warning: it
   configures both slash-command and `github-actions[bot]` triggers, and the bot
   trigger is required for controlled worker-continuation dispatches.
@@ -230,7 +231,7 @@ criteria:
 ### 6. Require the verifier to prove the complete consumer contract
 
 - **STOP** if the verifier reports a missing source/lock pair, missing package
-  ownership record, stale source/resource digest, incomplete seven-workflow
+  ownership record, stale source/resource digest, incomplete eight-workflow
   registration, or mixed revision.
 - Use only the recovery commands printed by the verifier. They reinstall the
   complete package at one immutable revision; never repair one workflow or
@@ -258,6 +259,8 @@ Stage **only** the documented generated surfaces, then verify the staged set:
 
 ```bash
 git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
+node .github/workflows/shared/squad-install-verifier.mjs \
+  --verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
 git diff --cached --stat
 # No deletions should be staged:
 test -z "$(git diff --cached --diff-filter=D --name-only)" || { echo "STOP: staged deletions"; exit 1; }
@@ -267,6 +270,15 @@ test -z "$(git diff --cached --diff-filter=D --name-only)" || { echo "STOP: stag
   edits to **unrelated files**, or committed **log/diagnostic output**. Re-scope with
   explicit `git add -- <path>` — never `git add .`, `git add -A`, or `git commit -a`.
 
+Consumer rules such as `packages/` can silently ignore the required ownership
+JSON under `.github/aw/packages/`. The staged verifier force-adds only the exact
+native package ownership JSON when it is ignored and untracked. It then verifies
+every manifest-required source, lock, runtime, skill, manifest and ownership
+file against the validated working-tree bytes in a snapshot of the Git index.
+**STOP before commit/push** on missing metadata, a staging failure, an omitted
+required file or a staged digest mismatch. Never force-add a directory or glob.
+Rerun this gate after changing or restaging any installation file.
+
 ### 8. Commit, push, and open the bootstrap PR to the captured default branch
 
 ```bash
@@ -360,6 +372,8 @@ node .github/workflows/shared/squad-install-verifier.mjs \
   --verify-install --source-revision "${SQUAD_SHA}" --strict-compile
 
 git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
+node .github/workflows/shared/squad-install-verifier.mjs \
+  --verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
 git commit -m "ci: add Squad agentic workflow"
 git push -u origin HEAD
 gh pr create --base "${default_branch}" \

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

@@ -84,6 +84,8 @@ node .github/workflows/shared/squad-install-verifier.mjs \
 
 # 7. Commit the generated files and open the bootstrap PR
 git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
+node .github/workflows/shared/squad-install-verifier.mjs \
+  --verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
 git diff --cached --stat
 test -z "$(git diff --cached --diff-filter=D --name-only)"
 git commit -m "ci: add Squad agentic workflow"
@@ -364,6 +366,8 @@ done
 
 ```bash
 git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
+node .github/workflows/shared/squad-install-verifier.mjs \
+  --verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
 git diff --cached --stat
 test -z "$(git diff --cached --diff-filter=D --name-only)"
 git commit -m "ci: add Squad agentic workflow"
@@ -381,6 +385,16 @@ state under `.github/aw/`, the installed skills, and `.gitattributes`. Review
 the complete generated diff in the bootstrap PR, address Copilot review
 feedback, and wait for required checks. Merge only after human approval.
 
+Consumer ignore rules such as `packages/` can silently omit the required
+`.github/aw/packages/` ownership JSON from directory staging. The staged verifier
+force-adds only the exact native package ownership JSON when ignored and
+untracked, never unrelated ignored files. It checks every manifest-required
+source, lock, runtime, skill, manifest and ownership file in the Git index
+against the verified working-tree bytes. Missing metadata, failed staging,
+omitted required files or staged digest mismatches stop the install before
+commit/push. Never force-add a directory or glob; rerun the gate after edits or
+restaging, including package upgrades.
+
 `gh aw add` may also create `.vscode/settings.json` to enable Copilot for
 Markdown workflow files. The command above intentionally leaves that optional
 editor setting untracked. Delete it if you do not want the local setting, or

packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md

@@ -11,7 +11,7 @@ tools:
     when: "Every step: preflight identity/auth, requiring Issues, enabling Actions-created PRs, opening and watching the bootstrap PR."
   - name: "gh aw"
     description: "GitHub Agentic Workflows extension (github/gh-aw) — installs and strictly compiles the Squad workflow set."
-    when: "Installing the immutable native Squad package and compiling its seven workflows into deterministic .lock.yml files."
+    when: "Installing the immutable native Squad package and compiling its eight workflows into deterministic .lock.yml files."
 ---
 
 ## Context
@@ -146,7 +146,7 @@ gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
 
 The nested `workflows/aw.yml` is the only supported distribution registration.
 It isolates package auto-discovery from unrelated repository skills and agents,
-and installs exactly seven workflows, fifteen runtime resources, and one
+and installs exactly eight workflows, seventeen runtime resources, and one
 `gh-aw-enlistment` skill at the same resolved revision:
 
 - `squad.md` + `squad.lock.yml`
@@ -156,11 +156,12 @@ and installs exactly seven workflows, fifteen runtime resources, and one
 - `squad-retro.md` + `squad-retro.lock.yml`
 - `squad-improvement-worker.md` + `squad-improvement-worker.lock.yml`
 - `squad-bootstrap.md` + `squad-bootstrap.lock.yml`
+- `squad-command-router.md` + `squad-command-router.lock.yml`
 
 `squad-improvement-worker` is part of the standard, coherent install above —
 not a separate opt-in add-on. It stays dormant until a maintainer approves a
 governance-scoped retrospective proposal (see the gh-aw guide's retrospective
-auto-implementation section); installing it alongside the other six keeps the
+auto-implementation section); installing it alongside the other seven keeps the
 full stack consistent and avoids a second bootstrap pass later.
 
 Report/proposal-only is the default. Ordinary fixes require the explicit
@@ -220,7 +221,7 @@ node .github/workflows/shared/squad-install-verifier.mjs \
 This must run after any first-install approval and before committing. Success
 criteria:
 
-- All seven workflows compile successfully.
+- All eight workflows compile successfully.
 - The **only** permitted warning is the known `squad.md` bot-trigger warning: it
   configures both slash-command and `github-actions[bot]` triggers, and the bot
   trigger is required for controlled worker-continuation dispatches.
@@ -230,7 +231,7 @@ criteria:
 ### 6. Require the verifier to prove the complete consumer contract
 
 - **STOP** if the verifier reports a missing source/lock pair, missing package
-  ownership record, stale source/resource digest, incomplete seven-workflow
+  ownership record, stale source/resource digest, incomplete eight-workflow
   registration, or mixed revision.
 - Use only the recovery commands printed by the verifier. They reinstall the
   complete package at one immutable revision; never repair one workflow or
@@ -258,6 +259,8 @@ Stage **only** the documented generated surfaces, then verify the staged set:
 
 ```bash
 git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
+node .github/workflows/shared/squad-install-verifier.mjs \
+  --verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
 git diff --cached --stat
 # No deletions should be staged:
 test -z "$(git diff --cached --diff-filter=D --name-only)" || { echo "STOP: staged deletions"; exit 1; }
@@ -267,6 +270,15 @@ test -z "$(git diff --cached --diff-filter=D --name-only)" || { echo "STOP: stag
   edits to **unrelated files**, or committed **log/diagnostic output**. Re-scope with
   explicit `git add -- <path>` — never `git add .`, `git add -A`, or `git commit -a`.
 
+Consumer rules such as `packages/` can silently ignore the required ownership
+JSON under `.github/aw/packages/`. The staged verifier force-adds only the exact
+native package ownership JSON when it is ignored and untracked. It then verifies
+every manifest-required source, lock, runtime, skill, manifest and ownership
+file against the validated working-tree bytes in a snapshot of the Git index.
+**STOP before commit/push** on missing metadata, a staging failure, an omitted
+required file or a staged digest mismatch. Never force-add a directory or glob.
+Rerun this gate after changing or restaging any installation file.
+
 ### 8. Commit, push, and open the bootstrap PR to the captured default branch
 
 ```bash
@@ -360,6 +372,8 @@ node .github/workflows/shared/squad-install-verifier.mjs \
   --verify-install --source-revision "${SQUAD_SHA}" --strict-compile
 
 git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
+node .github/workflows/shared/squad-install-verifier.mjs \
+  --verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
 git commit -m "ci: add Squad agentic workflow"
 git push -u origin HEAD
 gh pr create --base "${default_branch}" \

packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md

@@ -11,7 +11,7 @@ tools:
     when: "Every step: preflight identity/auth, requiring Issues, enabling Actions-created PRs, opening and watching the bootstrap PR."
   - name: "gh aw"
     description: "GitHub Agentic Workflows extension (github/gh-aw) — installs and strictly compiles the Squad workflow set."
-    when: "Installing the immutable native Squad package and compiling its seven workflows into deterministic .lock.yml files."
+    when: "Installing the immutable native Squad package and compiling its eight workflows into deterministic .lock.yml files."
 ---
 
 ## Context
@@ -146,7 +146,7 @@ gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
 
 The nested `workflows/aw.yml` is the only supported distribution registration.
 It isolates package auto-discovery from unrelated repository skills and agents,
-and installs exactly seven workflows, fifteen runtime resources, and one
+and installs exactly eight workflows, seventeen runtime resources, and one
 `gh-aw-enlistment` skill at the same resolved revision:
 
 - `squad.md` + `squad.lock.yml`
@@ -156,11 +156,12 @@ and installs exactly seven workflows, fifteen runtime resources, and one
 - `squad-retro.md` + `squad-retro.lock.yml`
 - `squad-improvement-worker.md` + `squad-improvement-worker.lock.yml`
 - `squad-bootstrap.md` + `squad-bootstrap.lock.yml`
+- `squad-command-router.md` + `squad-command-router.lock.yml`
 
 `squad-improvement-worker` is part of the standard, coherent install above —
 not a separate opt-in add-on. It stays dormant until a maintainer approves a
 governance-scoped retrospective proposal (see the gh-aw guide's retrospective
-auto-implementation section); installing it alongside the other six keeps the
+auto-implementation section); installing it alongside the other seven keeps the
 full stack consistent and avoids a second bootstrap pass later.
 
 Report/proposal-only is the default. Ordinary fixes require the explicit
@@ -220,7 +221,7 @@ node .github/workflows/shared/squad-install-verifier.mjs \
 This must run after any first-install approval and before committing. Success
 criteria:
 
-- All seven workflows compile successfully.
+- All eight workflows compile successfully.
 - The **only** permitted warning is the known `squad.md` bot-trigger warning: it
   configures both slash-command and `github-actions[bot]` triggers, and the bot
   trigger is required for controlled worker-continuation dispatches.
@@ -230,7 +231,7 @@ criteria:
 ### 6. Require the verifier to prove the complete consumer contract
 
 - **STOP** if the verifier reports a missing source/lock pair, missing package
-  ownership record, stale source/resource digest, incomplete seven-workflow
+  ownership record, stale source/resource digest, incomplete eight-workflow
   registration, or mixed revision.
 - Use only the recovery commands printed by the verifier. They reinstall the
   complete package at one immutable revision; never repair one workflow or
@@ -258,6 +259,8 @@ Stage **only** the documented generated surfaces, then verify the staged set:
 
 ```bash
 git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
+node .github/workflows/shared/squad-install-verifier.mjs \
+  --verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
 git diff --cached --stat
 # No deletions should be staged:
 test -z "$(git diff --cached --diff-filter=D --name-only)" || { echo "STOP: staged deletions"; exit 1; }
@@ -267,6 +270,15 @@ test -z "$(git diff --cached --diff-filter=D --name-only)" || { echo "STOP: stag
   edits to **unrelated files**, or committed **log/diagnostic output**. Re-scope with
   explicit `git add -- <path>` — never `git add .`, `git add -A`, or `git commit -a`.
 
+Consumer rules such as `packages/` can silently ignore the required ownership
+JSON under `.github/aw/packages/`. The staged verifier force-adds only the exact
+native package ownership JSON when it is ignored and untracked. It then verifies
+every manifest-required source, lock, runtime, skill, manifest and ownership
+file against the validated working-tree bytes in a snapshot of the Git index.
+**STOP before commit/push** on missing metadata, a staging failure, an omitted
+required file or a staged digest mismatch. Never force-add a directory or glob.
+Rerun this gate after changing or restaging any installation file.
+
 ### 8. Commit, push, and open the bootstrap PR to the captured default branch
 
 ```bash
@@ -360,6 +372,8 @@ node .github/workflows/shared/squad-install-verifier.mjs \
   --verify-install --source-revision "${SQUAD_SHA}" --strict-compile
 
 git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
+node .github/workflows/shared/squad-install-verifier.mjs \
+  --verify-staged-install --stage-ownership --source-revision "${SQUAD_SHA}" || exit 1
 git commit -m "ci: add Squad agentic workflow"
 git push -u origin HEAD
 gh pr create --base "${default_branch}" \

scripts/gh-aw-hosted-e2e.mjs

@@ -21,6 +21,7 @@ import {
   TRIGGER_PROBE_DESTINATION,
   checkSource,
   verifyInstall,
+  verifyStagedInstall,
 } from '../workflows/shared/squad-install-verifier.mjs';
 
 const TRUSTED_SOURCE = Object.freeze({
@@ -802,6 +803,10 @@ function hosted(args, repositoryRoot) {
     const installPaths = ['.gitattributes', '.github/aw', '.github/workflows', '.github/skills', '.vscode']
       .filter((path) => existsSync(resolve(checkout, path)));
     runChild('git', ['add', '--', ...installPaths], { cwd: checkout });
+    const staged = verifyStagedInstall(checkout, { expectedRevision: sourceSha, stageOwnership: true });
+    if (staged.failures.length > 0) {
+      throw new Error(`STOP: required installation files could not be staged and verified:\n${staged.failures.join('\n')}`);
+    }
     runChild('git', ['commit', '-m', 'ci: install Squad agentic workflows'], { cwd: checkout });
     const installStartedAt = Date.now();
     const installation = createAndMergePr({

scripts/sync-templates.mjs

@@ -117,6 +117,10 @@ for (const relFile of sourceFiles) {
     targets.push(join(AGENT_MD_TARGET, AGENT_MD_FILE));
   }
 
+  if (relFile === 'skills/gh-aw-enlistment/SKILL.md') {
+    targets.push(join(ROOT, 'workflows', relFile));
+  }
+
   if (targets.length === 0) continue;
 
   for (const dest of targets) {