Squad product: PR completeness gates -- prevent merging without docs, CHANGELOG, exports, and samples CI #104
Description
Scope: This is a Squad product issue. PRs can currently be submitted and merged without documentation, CHANGELOG entries, samples CI, or export map updates. The CI and review process needs gates to prevent incomplete PRs from landing.
Problem
PR bradygaster#640 (StorageProvider) passed all existing CI checks and got a clean bleed check, but an ecosystem audit revealed 6 missing items that should have been caught before the PR was mergeable:
| Missing item | Why it matters | How it was caught |
|---|---|---|
| CHANGELOG entry | Users don't know the feature exists | Manual audit |
| SDK README section | No discoverability for new API | Manual audit |
| Docs feature page | Not in docs site at all | Manual audit |
| package.json /storage export | Can't deep-import the module | Manual audit |
| Runtime config selection | Hardcoded FSStorageProvider in 40+ files | Manual audit |
| Samples CI coverage | Samples can silently break (#103) | Manual audit |
None of these are checked by squad-ci.yml. None are flagged by Copilot review. None are in any PR template checklist.
Current CI checks (from squad-ci.yml)
What CI checks today:
- npm run build (TypeScript compilation)
- npm test (vitest suite)
- Source tree canary (hardcoded file list)
- Deletion guard (protects critical files)
- Publish policy check
What CI does NOT check:
- CHANGELOG has an entry for the PR
- README/docs updated for new public API
- package.json exports map includes new modules
- Samples still build after SDK changes
- New features have a docs page
Proposed: PR Completeness Gates
Gate 1: CHANGELOG check (CI)
If PR adds/modifies files in packages/squad-sdk/src/ or packages/squad-cli/src/, require CHANGELOG.md to have changes too.
- name: CHANGELOG required for SDK/CLI changes
run: |
SDK_CHANGED=$(git diff --name-only origin/dev...HEAD | grep -c 'packages/squad-sdk/src\|packages/squad-cli/src' || true)
CHANGELOG_CHANGED=$(git diff --name-only origin/dev...HEAD | grep -c 'CHANGELOG.md' || true)
if [ "$SDK_CHANGED" -gt 0 ] && [ "$CHANGELOG_CHANGED" -eq 0 ]; then
echo "ERROR: SDK/CLI changes detected but CHANGELOG.md not updated"
echo "Add an entry under [Unreleased] describing your changes"
exit 1
fiGate 2: Exports map check (CI)
If PR adds new files to packages/squad-sdk/src/*/index.ts, check that package.json exports map includes the new subpath.
- name: Exports map completeness
run: |
node scripts/check-exports-map.jsScript reads all src/*/index.ts barrel files and verifies each has a corresponding entry in package.json exports.
Gate 3: Samples build check (CI)
Already tracked in #103. If PR modifies packages/squad-sdk/src/, build all samples to catch breakage.
Gate 4: PR template checklist (GitHub)
Create .github/PULL_REQUEST_TEMPLATE.md with a completeness checklist:
## PR Checklist
### Required for all PRs
- [ ] Tests pass (`npm test`)
- [ ] Build succeeds (`npm run build`)
- [ ] No unintended file changes (bleed check)
### Required for SDK/CLI changes
- [ ] CHANGELOG.md updated under [Unreleased]
- [ ] package.json exports map updated (if new module)
- [ ] Existing samples still build
### Required for new features
- [ ] SDK README updated with new API section
- [ ] Docs feature page created (docs/src/content/docs/features/)
- [ ] At least one sample demonstrates the feature
- [ ] JSDoc/TSDoc on all public interfaces
### Required for bug fixes
- [ ] Test reproducing the bug added
- [ ] Troubleshooting guide updated (if user-facing)Gate 5: Review checklist enforcement (Squad team)
Already tracked in #100. Flight and FIDO should check docs/CI coverage as part of their review. The review-completeness skill should include these gates.
Gate 6: Required status checks (GitHub Settings)
Once CI gates exist, configure them as required status checks on bradygaster/squad:
changelog-check-- required for SDK/CLI PRsexports-map-check-- required for SDK PRssamples-build-- required for SDK PRs (from Squad product: samples/ directory has zero CI coverage -- SDK changes silently break samples #103)squad-ci / test-- already required
These can be feature-flagged per #98 approach (repo variables to enable/disable).
What this prevents
| Scenario | Before (current) | After (with gates) |
|---|---|---|
| Ship feature without CHANGELOG | Silently lands | CI blocks |
| Add new module without export | Users can't import it | CI blocks |
| Break samples with SDK change | Nobody notices | CI blocks |
| Submit PR without docs | Lands, creates debt | Checklist reminds, review catches |
| Merge without JSDoc | API undocumented | Review checklist flags |
Implementation phases
Phase 1 (P0): PR template
- Create
.github/PULL_REQUEST_TEMPLATE.mdwith checklist - Zero CI changes needed -- just a reminder
- Brady can merge this immediately
Phase 2 (P1): CHANGELOG gate
- Add CHANGELOG check to squad-ci.yml
- Feature-flagged via
vars.SQUAD_CHANGELOG_CHECK(default: true) - Skip label:
skip-changelog
Phase 3 (P1): Exports map check
- Write
scripts/check-exports-map.js - Add to squad-ci.yml
- Feature-flagged via
vars.SQUAD_EXPORTS_CHECK
Phase 4 (P1): Samples build (from #103)
- Separate workflow or job in squad-ci.yml
- Triggers on SDK source changes
- Feature-flagged via
vars.SQUAD_SAMPLES_CI
Phase 5 (P2): Required status checks
- Configure on GitHub Settings after gates are stable
- Start advisory (check runs but doesn't block), promote to required after 1 sprint
Acceptance criteria
- PR template exists with completeness checklist
- CHANGELOG gate runs in CI for SDK/CLI PRs
- Exports map check runs in CI for SDK PRs
- Samples build check runs in CI (from Squad product: samples/ directory has zero CI coverage -- SDK changes silently break samples #103)
- All new gates are feature-flagged (repo variables)
- All new gates have skip labels (per-PR override)
- Review completeness skill (Squad product: Expand team review to include doc coverage and CI improvements #100) references these gates
Related
- Squad product: Default workflows burn too many Actions minutes for multi-repo customers #98 -- Minutes optimization PRD (feature flag approach, CI architecture)
- Squad product: Expand team review to include doc coverage and CI improvements #100 -- Review completeness (docs + CI in review checklist)
- Squad product: samples/ directory has zero CI coverage -- SDK changes silently break samples #103 -- Samples CI coverage (Gate 3)
- feat(sdk): StorageProvider abstraction — complete migration + example providers bradygaster/squad#640 -- StorageProvider PR (the PR that exposed all these gaps)