[diberry]

Summary

Adds automated testing and CI guardrails for init/upgrade parity, plus improved doctor UX for global installs.

What's included

• FR-2: Parity test suite - 8 new tests that catch init/upgrade drift. Includes parametric tests for every ENSURE_DIRECTORIES entry, casting/sessions recreation, pre-casting repo simulation, and doctor-after-upgrade validation.
• FR-3: CI gate - upgrade-doctor-check job runs init, upgrade, doctor validation on PRs touching init/upgrade/doctor code.
• FR-7: Doctor UX - global installs show info instead of warn for ESM checks, with clearer messaging.
• Changeset included for doctor.ts changes.

What's handled elsewhere

• FR-1 (casting dir fix): Already merged via PR fix(cli): squad doctor — add casting dir to upgrade, improve global install warnings #823
• FR-4/5/6 (SDK compat): Handled in feat: @github/copilot-sdk Compatibility Testing & Breaking Change Detection — PRD #818

NFR-1: agents/ is user data

The parity tests document that .squad/agents/ IS in ENSURE_DIRECTORIES (the directory itself is infrastructure), but agent contents (charter.md, history.md) are user data - never overwritten by upgrade.

Test results

• 26/26 doctor tests pass (3 new)
• 21/21 parity tests pass (8 new)

Closes #817

[github-actions]

🟡 Impact Analysis — PR #912

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	6
Files added	1
Files modified	5
Files deleted	0
Modules touched	4

🎯 Risk Factors

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

📦 Modules Affected

ci-workflows (1 file)

• .github/workflows/squad-ci.yml

root (1 file)

• .changeset/init-upgrade-parity.md

squad-cli (2 files)

• packages/squad-cli/src/cli/commands/doctor.ts
• packages/squad-cli/src/cli/core/upgrade.ts

tests (2 files)

• test/cli/doctor.test.ts
• test/cli/init-upgrade-parity.test.ts

---

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

[github-actions]

🏗️ Architectural Review

⚠️ Architectural review: 1 warning(s), 1 info.

Severity	Category	Finding	Files
🟡 warning	bootstrap-area	1 file(s) in the bootstrap area (packages/squad-cli/src/cli/core/) were modified. These files must maintain zero external dependencies. Review carefully.	packages/squad-cli/src/cli/core/upgrade.ts
ℹ️ info	template-sync	Template files changed in .github/workflows/ but not in other template locations. If these templates should stay in sync, consider updating the others too.	Changed: .github/workflows/, Unchanged: templates/, .squad-templates/, packages/squad-cli/templates/

---

Automated architectural review — informational only.

[diberry]

🔍 Squad Review — Kaylee (Engineering)

#	Check	Status	Notes
1	Changelog entry	✅	.changeset/init-upgrade-parity.md present
2	Squashed to 1 commit	✅	1 commit
3	CI green	✅	All 12 checks passed (incl. upgrade-doctor-check)
4	Copilot comments resolved	✅	0 unresolved threads
5	No .squad/ files	✅	Clean
6	No unrelated files	✅	6 files — doctor.ts, upgrade.ts, CI yml, tests, changeset
7	Tests for changes	✅	doctor.test.ts (3 new) + init-upgrade-parity.test.ts (8 new)
8	Not a duplicate/reversal	✅	Unique parity work for #817

Verdict: ✅ Ready to merge

---

Review by Squad AI team (Kaylee — Engineering) · requested by Dina Berry

[diberry]

🔒 RETRO — Security Review

Verdict: ✅ APPROVE

Security Findings

• No injection vectors. The CI job uses inline node --input-type=module with a hardcoded script — no dynamic user input.
• runInit(), runUpgrade(), runDoctor() are called on a temp directory created with crypto.randomBytes() — good isolation.
• Temp directory is cleaned up in a finally block — no persistent artifacts.
• ENSURE_DIRECTORIES export is a constant array of directory paths — no security impact.

Credential / PII Check

• No secrets or PII.

Workflow Permissions

• Job inherits from parent workflow (squad-ci.yml), uses standard actions/checkout@v4 + actions/setup-node@v4.

Recommendation

Clean merge. Test-only and UX changes with no security surface.

[diberry]

🏗️ Flight — Architecture Review

Verdict: ✅ APPROVE

Findings

1. New exports are intentional and well-scoped. looksLikeGlobalInstall() from doctor.ts and ENSURE_DIRECTORIES from upgrade.ts are exported specifically for test consumption and the CI validation job. Both are stable, non-internal APIs.
2. Doctor logic refactor is correct. The global-install detection was inverted — the old code checked hasNodeModules and returned the wrong message for each branch. The new code cleanly separates the global-install case (info severity) from the local-install-with-missing-packages case (warn severity). Tests verify both branches.
3. CI gate (upgrade-doctor-check) is properly gated. Only runs on PRs with relevant file changes (doctor.ts, init.ts, upgrade.ts, templates.ts). Uses node --input-type=module for ESM compat. Cleans up temp directory in finally block.
4. Changeset included ✅ — required since doctor.ts and upgrade.ts are under packages/squad-cli/src/.
5. Parity tests are thorough. Parametric tests for every ENSURE_DIRECTORIES entry, casting recreation, sessions creation, and the critical end-to-end: init → upgrade → doctor with zero failures.

Module Boundary Check

• All changes within squad-cli package. No cross-package imports. doctor.ts and upgrade.ts are post-SDK files (not in protected bootstrap list), so the exports are safe.

Recommendation

Merge. This closes a real gap — init/upgrade drift has caused production issues before, and the CI gate prevents regression.

[diberry]

🧪 FIDO — Quality Review

Verdict: ✅ APPROVE

Test Coverage

• 14 new parity tests covering init→upgrade→doctor pipeline, parametric directory recreation, casting defaults, session directory creation, and global install detection. ✓
• 3 new doctor tests for looksLikeGlobalInstall() (true/false/warn-when-missing). ✓
• CI gate (upgrade-doctor-check job) exercises the full init→upgrade→doctor pipeline on every PR touching relevant files. ✓
• Changeset included. ✓

Edge Cases / Risks

• CI gate inline script. The upgrade-doctor-check job uses node --input-type=module -e "..." with a 90-line inline script. If this fails, the error context will be minimal. Consider extracting to a test script file for better stack traces.
• ENSURE_DIRECTORIES export. Exporting this constant is a minor API surface increase for squad-cli. Acceptable for testing purposes, but document that it's an internal export.
• Logic inversion verified. The looksLikeGlobalInstall refactor preserves original behavior — global installs (no node_modules) get info-severity, local installs (missing packages) get warn. Tests confirm both paths. ✓

CI Impact

• New upgrade-doctor-check job in CI. Only runs on PRs changing init/upgrade/doctor/templates files (good scoping). 5-minute timeout. ✓

Recommendation

Approve. Strong parity test coverage. The init→upgrade→doctor pipeline is now CI-gated — drift will be caught early.