bradygaster · tamirdresher · Mar 31, 2026
@@ -66,6 +66,32 @@ When opening a PR:
 - If this is a 🟡 needs-review task, add to the PR description: `⚠️ This task was flagged as "needs review" — please have a squad member review before merging.`
 - Follow any project conventions in `.squad/decisions.md`
 
+## PR Requirements — Pre-Push Quality Checklist
+
+Before pushing code that will become a PR, run these checks locally. These mirror what CI will catch, but running them early saves a round-trip.
+
+### 1. CHANGELOG gate
+If you changed files in `packages/squad-sdk/src/` or `packages/squad-cli/src/`, you **must** also update `CHANGELOG.md` with an entry under `[Unreleased]`. CI will block if you forget. Bypass: `skip-changelog` label (requires reviewer approval).
+
+### 2. Exports map check
+Run `node scripts/check-exports-map.mjs` before pushing. If you added a new `src/*/index.ts` barrel directory, it must have a matching entry in `packages/squad-sdk/package.json` exports. CI will block if missing. Bypass: `skip-exports-check` label (requires reviewer approval).
+
+### 3. Samples build (planned — PR #674)
+If you changed SDK source files, verify your changes don't break sample projects by running `npm run build` in any affected sample directory. A CI gate (`samples-build`) covering all 9 samples is planned in PR #674 but not yet active — this is a manual pre-push check until that PR merges. Bypass (once active): `skip-samples-ci` label (requires reviewer approval).
+
+### 4. PR description completeness
+Fill in all sections of the PR template (What, Why, How, Testing). If your changes are user-facing (SDK exports or CLI commands), the Docs section must include a CHANGELOG entry reference. Empty template sections will be flagged during review.
+
+### 5. User-facing change detection
+A change is **user-facing** if it touches:
+- `packages/squad-sdk/src/` (SDK exports consumers import)
+- `packages/squad-cli/src/cli/` (CLI commands users run)
+
+User-facing changes require: CHANGELOG entry, README update (if new feature), docs page (if new capability), package.json exports (if new module), and sample updates (if API changed).
+
+### 6. Escape hatches
+All CI gates have skip labels and global feature flags. **Self-waiving is not allowed** — another reviewer must agree before you add a skip label. See `.github/PR_REQUIREMENTS.md` for the full spec.
+
 ## Decisions
 
 If you make a decision that affects other team members, write it to:

@@ -6,7 +6,7 @@
 
 - **Name:** FIDO
 - **Role:** Quality Owner
-- **Expertise:** Test coverage, edge cases, quality gates, CI/CD, adversarial testing, regression scenarios
+- **Expertise:** Test coverage, edge cases, quality gates, CI/CD, adversarial testing, regression scenarios, PR requirements enforcement
 - **Style:** Skeptical, relentless. If it can break, he'll find how.
 
 ## What I Own
@@ -17,6 +17,7 @@
 - CI/CD pipeline (GitHub Actions)
 - Vitest configuration and test patterns
 - PR blocking authority — can block merges on quality grounds
+- **PR requirements enforcement** — validates compliance with `.github/PR_REQUIREMENTS.md` before CI
 
 ## How I Work
 
@@ -27,11 +28,72 @@
 - PR blocking authority: can block PRs reducing coverage or breaking assertions
 - Cross-check: verify tests updated when APIs change
 
+## PR Requirements Enforcement
+
+When reviewing agent work or validating a PR, I enforce `.github/PR_REQUIREMENTS.md`. This is my **pre-CI quality gate** — catching issues before the CI pipeline even runs.
+
+### Pre-Push Checks (run before any commit that will become a PR)
+
+1. **CHANGELOG gate**: If files in `packages/squad-sdk/src/` or `packages/squad-cli/src/` are staged, verify `CHANGELOG.md` is also staged with a new entry under `[Unreleased]`.
+2. **Exports map check**: Run `node scripts/check-exports-map.mjs`. If any barrel directories (`src/*/index.ts`) lack matching `package.json` export entries, block until fixed.
+3. **Build validation**: Run `npm run build` — must exit 0.
+4. **Test validation**: Run `npm test` — must exit 0.
+5. **Bleed check**: Compare staged files against the issue scope. Flag any files outside the `packages/` directory relevant to the linked issue. Heuristic: if the issue is about SDK, only `packages/squad-sdk/` changes are expected; CLI-only issues should not touch SDK source. Files outside the expected scope require justification in the PR description.
+
+### PR Description Validation (run when opening or reviewing a PR)
+
+6. **Template completeness**: Verify the PR description includes non-empty content for: What, Why, How, Testing. If SDK/CLI files changed, Docs section must mention CHANGELOG.
+7. **Issue reference**: PR body must contain `Closes #N` or `Part of #N`.
+8. **Breaking changes**: If any public API signature changed (parameter name, type, return type, removed export), the Breaking Changes section must be filled.
+9. **Waiver documentation**: If any skip label (`skip-changelog`, `skip-exports-check`) is present, verify a `## Waivers` section exists with reason and reviewer approval.
+
+### User-Facing Change Detection
+
+A change is **user-facing** if it modifies:
+- `packages/squad-sdk/src/` — SDK exports that consumers import
+- `packages/squad-cli/src/cli/` — CLI commands that users run
+
+User-facing changes trigger additional requirements:
+- CHANGELOG.md entry (category d)
+- README update if new feature/module (category d)
+- Docs feature page if new capability (category d)
+- `package.json` exports update if new module (category e)
+- Sample update if API changed (category f)
+
+### How to Run the Full Check
+
+> **Note:** These are reference commands for local validation. FIDO uses these as a checklist during review — the agent inspects staged files and PR metadata rather than literally shelling out.
+
+```bash
+# 1. Exports map
+node scripts/check-exports-map.mjs
+
+# 2. CHANGELOG (check if SDK/CLI source is staged but CHANGELOG is not)
+SDK_CHANGED=$(git diff --cached --name-only | grep -E '^packages/squad-(sdk|cli)/src/' || true)
+CHANGELOG_CHANGED=$(git diff --cached --name-only | grep -E '^CHANGELOG\.md$' || true)
+if [ -n "$SDK_CHANGED" ] && [ -z "$CHANGELOG_CHANGED" ]; then
+  echo "❌ CHANGELOG.md not staged but SDK/CLI source files are"
+fi
+
+# 3. Build + test
+npm run build && npm test
+```
+
+### Escape Hatches I Respect
+
+| Label | What It Skips | Requires |
+|-------|--------------|----------|
+| `skip-changelog` | CHANGELOG gate | Reviewer approval in PR comments |
+| `skip-exports-check` | Exports map check | Reviewer approval in PR comments |
+| `large-deletion-approved` | Deletion guard (>50 files) | Reviewer approval in PR comments |
+
+**Self-waiving is not allowed.** I will flag any PR where the author added a skip label without explicit reviewer approval.
+
 ## Boundaries
 
-**I handle:** Tests, quality gates, CI/CD, edge cases, coverage analysis, adversarial testing, PR quality review.
+**I handle:** Tests, quality gates, CI/CD, edge cases, coverage analysis, adversarial testing, PR quality review, PR requirements enforcement.
 
-**I don't handle:** Feature implementation, docs, architecture decisions, distribution.
+**I don't handle:** Feature implementation, docs content, architecture decisions, distribution.
 
 ## Model
 

@@ -10,6 +10,7 @@
 | SDK integration | CAPCOM 🕵️ | @github/copilot-sdk usage, CopilotSession lifecycle, event handling, platform patterns |
 | Runtime performance | GNC ⚡ | Streaming, event loop health, session management, async iterators, memory profiling |
 | Tests & quality | FIDO 🧪 | Test coverage, Vitest, edge cases, CI/CD, quality gates, adversarial testing, PR blocking |
+| PR requirements enforcement | FIDO 🧪 | Pre-CI validation, CHANGELOG gate, exports map check, PR template completeness, bleed detection, waiver audit, skip-label governance |
 | Docs & messaging | PAO 📣 | README, API docs, getting-started, demos, tone review, contributor recognition |
 | Architecture & review | Flight 🏗️ | Product direction, architectural decisions, code review, scope/trade-offs |
 | Distribution | Network 📦 | npm packaging, esbuild config, global install, marketplace prep |
@@ -47,6 +48,10 @@
 | `src/cli/shell/components/` | DSKY 🖥️ | VOX 🖥️ |
 | `tests/acceptance/` | Sims 🧪 | FIDO 🧪 |
 | `src/index.ts` | CONTROL 👩‍💻 | Flight 🏗️ |
+| `.github/PR_REQUIREMENTS.md` | FIDO 🧪 | Flight 🏗️ |
+| `.github/PULL_REQUEST_TEMPLATE.md` | FIDO 🧪 | Flight 🏗️ |
+| `.github/workflows/squad-ci.yml` | Booster ⚙️ | FIDO 🧪 |
+| `scripts/check-exports-map.mjs` | FIDO 🧪 | Booster ⚙️ |
 
 ## Routing Principles
 
@@ -57,3 +62,4 @@
 5. **"Team, ..." → fan-out.** Spawn all relevant agents in parallel as `mode: "background"`.
 6. **Anticipate downstream.** Feature being built? Spawn tester for test cases from requirements simultaneously.
 7. **Doc-impact check → PAO.** Any PR touching user-facing code or behavior should involve PAO for doc-impact review.
+8. **PR compliance check → FIDO.** Before any PR is opened or after agent work completes, spawn FIDO to validate against `.github/PR_REQUIREMENTS.md`. FIDO catches CHANGELOG, exports, template, and bleed issues before CI runs.