[bradygaster]

What

Add an explicit maintainer-controlled fresh-bootstrap generation without deleting historical PRs, issues, or branches. Working as agentic-workflows-dev (Agentic Workflows Engineer).

Why

Closes #2188. Closing a stale Cast PR intentionally records opt-out; deleting its branch or changing its title cannot restart bootstrap safely. Maintainers need a supported fresh attempt without removing that default protection.

How

A reviewed default-branch .squad/bootstrap-reset.json names a stable ID and exact closed artifacts. It only arms the generation. Initial creation additionally requires default-branch workflow_dispatch, matching fresh_start, and authenticated human write/maintain/admin actors. Preflight and writer independently validate the record/history. Generation-specific branch and titles prevent historical artifact reuse. Installed teams, merged/open/foreign archive PRs, duplicate/ambiguous state, changed reset records, and divergent branches fail closed. The writer checks the live default-branch SHA before initial reset writes. Existing closed-current-generation opt-out, partial recovery, bounded payload validation, package integrity, and provenance remain enforced. Manual bot/fallback review authorization is limited to the committed generation and verified run actors.

11 files are all workflow sources/shared runtime, generated package/manifest, documentation, and tests. No SDK/CLI source or runtime team state changed; no consumer mutations.

---

⚠️ Quick Check

• If SDK/CLI source files changed: completed the applicable Changeset step below (npx changeset add / .changeset/*.md, direct CHANGELOG.md entry for maintainers, or skip-changelog label for no user-facing changes)

N/A: no SDK/CLI source changes.

PR Readiness Checklist

The PR readiness bot will validate these automatically after push.
Check each item before requesting review. See CONTRIBUTING.md for full details.

Branch & Commit

• Branch created from dev (not main)
• Branch is up to date with dev (git fetch upstream && git rebase upstream/dev)
• Verified diff contains only intended changes (git diff --cached --stat)
• PR is not in draft mode (mark ready when checks pass)
• Commit history is clean (squash fixups before review)

Verified with git fetch origin dev --quiet && git merge-base --is-ancestor origin/dev HEAD (passed); app-managed isolated branch, no main checkout operations.

Build & Test

• npm run build passes
• npm test passes (all tests green)
• npm run lint passes (type check clean)
• npm run lint:eslint passes
• For migration PRs (>20 files): include test output summary in PR description

Validation evidence:

• npm run build — passed; generated version stamps restored, not committed.
• npm run lint — passed.
• npm run lint:eslint — passed, zero errors; 2246 existing repository warnings.
• node_modules/.bin/eslint test/gh-aw-bootstrap-workflow.test.ts test/gh-aw-review-guard.test.ts test/gh-aw-install-staging.test.ts — passed without warnings.
• npm test -- test/gh-aw-bootstrap-workflow.test.ts test/gh-aw-review-guard.test.ts test/gh-aw-review-workflow.test.ts test/gh-aw-install-staging.test.ts test/gh-aw-verify-resource.test.ts — passed, 291 tests. Includes executable compiled writer with historical Cast [TEST] API capability test — will be deleted #3, repeated run without duplicate artifacts, compiled authorization-removal mutation, and coherent eight-workflow package installation with committed reset state.
• npm run gh-aw:integrity:write then npm run gh-aw:integrity:check — passed.
• Required gh-aw MCP compiler tool, strict mode, for workflows/squad-bootstrap.md, workflows/package/squad-bootstrap.md, workflows/squad-review.md, workflows/package/squad-review.md — all four valid, no errors/warnings. Compiled artifact inspected for input, trusted SHA checkout, preflight/writer authorization, and repository-wide concurrency. Generated ephemeral locks are not tracked by this source package.
• npm test — failed locally: 10,639 passed, 6 failed, 19 skipped, 47 todo. Two existing acceptance tests assume a non-worktree checkout; four existing CLI external-state tests fail on this macOS host. No affected CLI/acceptance source changed. npm test -- test/cli/cast.test.ts test/cli/copilot.test.ts test/cli/rc.test.ts reproduced those same four failures in isolation (55 passed). No full-suite green claim; require hosted CI before normal merge.
• Independent bounded security-reviewer gate — APPROVE, no vulnerabilities found in the reset boundary.
• git diff --check — passed.

Changeset

• Changeset added via npx changeset add (if packages/squad-sdk/src/ or packages/squad-cli/src/ changed)
• Or direct CHANGELOG.md entry (maintainers only — write-protected for external contributors)
• Or skip-changelog label applied (if no user-facing changes)

N/A: workflow infrastructure only; no escape-hatch label requested.

Docs

• README section updated (if new feature/module)
• Docs feature page (if new user-facing capability)

Existing gh-aw guide documents exact reset record, manual field, fallback/recovery, safety gates, and preserved history. No new SDK/CLI module.

Exports

• package.json subpath exports updated (if new module)

N/A: no SDK exports.

---

Breaking Changes

None. Legacy opt-out and push-only legacy provenance remain unchanged. Reset generations are opt-in.

Waivers

None requested. Hosted required checks must be green; local macOS/worktree full-suite limitations are recorded above.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 983bdec

PR Scope: 🔧 Infrastructure

⚠️ 2 item(s) to address before review

Status	Check	Details
❌	Single commit	3 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	No source files changed — changeset not required
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	3 active Copilot thread(s) resolved (1 outdated skipped)
✅	CI passing	All checks passing

Files Changed (11 files, +988 −92)

File	+/−
docs/src/content/docs/guide/gh-aw.md	+58 −0
test/gh-aw-bootstrap-workflow.test.ts	+353 −21
test/gh-aw-install-staging.test.ts	+38 −0
test/gh-aw-review-guard.test.ts	+90 −0
workflows/package/squad-bootstrap.md	+86 −19
workflows/package/squad-review.md	+6 −1
workflows/shared/squad-bootstrap-validator.mjs	+210 −12
workflows/shared/squad-review-guard.mjs	+48 −12
workflows/squad-bootstrap.md	+85 −18
workflows/squad-review.md	+6 −1
workflows/squad-workflows.manifest.json	+8 −8

Total: +988 −92

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[github-actions]

🟡 Impact Analysis — PR #2189

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	11
Files added	0
Files modified	11
Files deleted	0
Modules touched	3

🎯 Risk Factors

• 11 files changed (6-20 → MEDIUM)
• 3 modules touched (2-4 → MEDIUM)

📦 Modules Affected

docs (1 file)

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

root (7 files)

• workflows/package/squad-bootstrap.md
• workflows/package/squad-review.md
• workflows/shared/squad-bootstrap-validator.mjs
• workflows/shared/squad-review-guard.mjs
• workflows/squad-bootstrap.md
• workflows/squad-review.md
• workflows/squad-workflows.manifest.json

tests (3 files)

• test/gh-aw-bootstrap-workflow.test.ts
• test/gh-aw-install-staging.test.ts
• test/gh-aw-review-guard.test.ts

---

This report is generated automatically for every PR. See #733 for details.

[Copilot]

🟡 Changes recommended

Archived PR authorization, actor-type validation, and a default-branch race must be addressed.

3 open findings

• Bot rerun actor type is not validated before reset writes · New
• Archived PR bypasses reset protection via legacy branch · New
• Fresh-reset SHA check has a mutable-ref race · New

What changed in this PR

Adds a maintainer-authorized fresh-bootstrap generation while preserving historical artifacts and existing opt-out behavior.

Changes:

• Introduces committed reset records and generation-specific bootstrap identities.
• Extends workflow authorization, provenance validation, packaging, and documentation.
• Adds reset, compiled-writer, review-guard, and installation tests.

File	Description
workflows/​squad-workflows.manifest.json	Updates workflow and runtime integrity hashes.
workflows/​squad-review.md	Documents reset-generation review authorization.
workflows/​squad-bootstrap.md	Implements reset dispatch and materialization.
workflows/​shared/​squad-review-guard.mjs	Validates generation-bound provenance.
workflows/​shared/​squad-bootstrap-validator.mjs	Parses, authorizes, and classifies resets.
workflows/​package/​squad-review.md	Regenerates packaged review workflow.
workflows/​package/​squad-bootstrap.md	Regenerates packaged bootstrap workflow.
test/​gh-aw-review-guard.test.ts	Tests reset-generation review provenance.
test/​gh-aw-install-staging.test.ts	Tests coherent package installation.
test/​gh-aw-bootstrap-workflow.test.ts	Tests reset state and compiled writer behavior.
docs/​src/​content/​docs/​guide/​gh-aw.md	Documents the maintainer reset procedure.

🧠 Review effort: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[bradygaster]

Revision evidence for 4b35b12: all three Copilot findings are addressed with executable regressions (bot rerun actor, reopened archived bot/fallback PR, mutable default-ref race). npm test -- test/gh-aw-bootstrap-workflow.test.ts test/gh-aw-review-guard.test.ts test/gh-aw-review-workflow.test.ts test/gh-aw-install-staging.test.ts test/gh-aw-verify-resource.test.ts passed: 295 tests. SKIP_BUILD_BUMP=1 npm run build, npm run lint, changed-test ESLint, and npm run gh-aw:integrity:check passed. Required strict compiler tool recompiled both changed Bootstrap markdown sources with no warnings/errors. Independent bounded security delta review: APPROVE, no vulnerabilities found. First hosted CI at 7f1b216 was entirely green, including the full test job; awaiting new-head CI and Copilot rereview. No bypass or waiver requested.

[Copilot]

🟡 Changes recommended

Push recovery can replace authenticated reset-dispatch provenance and bypass the fresh-start authorization boundary.

1 open finding

• Push recovery bypasses required fresh_start authorization · New

3 resolved since last review

• Archived PR bypasses reset protection via legacy branch
• Bot rerun actor type is not validated before reset writes
• Fresh-reset SHA check has a mutable-ref race

🧠 Review effort: Balanced

[bradygaster]

Final origin-preserving revision 983bdec: npm test -- test/gh-aw-bootstrap-workflow.test.ts test/gh-aw-review-guard.test.ts test/gh-aw-review-workflow.test.ts test/gh-aw-install-staging.test.ts test/gh-aw-verify-resource.test.ts passed (299 tests). SKIP_BUILD_BUMP=1 npm run build, npm run lint, changed-test ESLint, package generation/integrity, and strict required-tool compilation passed. Independent final security delta gate APPROVE. Added executable compiled recovery proving push keeps the original dispatch trust root, plus signed-fallback recovery, same-origin rerun, and unauthenticated-generation rejection. Actual bradygaster/eShop read-only snapshots validated proposed archive record against closed bot Cast #3 and closed signed fallback issue #2; unrelated retrospective #4 excluded. Consumer workflow remains disabled and no consumer writes were made. Awaiting latest-head hosted CI and Copilot rereview.

[Copilot]

🔵 Needs a closer look

The security-sensitive workflow authorization changes require final human review and successful hosted CI.

0 open findings

1 resolved since last review

• Push recovery bypasses required fresh_start authorization

🧠 Review effort: Balanced