[omercangumus]

What changed

• Add a squad doctor check for history archive references in .squad Markdown files.
• Fail with the source history and archive path when the target is missing, untracked, or differs from its staged Git blob.
• Add regression tests for dangling, untracked, modified, and valid archives.

Closes #1836

[github-actions]

🟡 Impact Analysis — PR #2325

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	3
Files added	1
Files modified	2
Files deleted	0
Modules touched	3

🎯 Risk Factors

• 3 files changed (≤5 → LOW)
• 3 modules touched (2-4 → MEDIUM)

📦 Modules Affected

root (1 file)

• .changeset/archive-pointers-are-validated.md

squad-cli (1 file)

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

tests (1 file)

• test/cli/doctor.test.ts

---

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

[github-actions]

🛫 PR Readiness Check

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

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 3 item(s) to address before review

Status	Check	Details
❌	Single commit	2 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	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	No Copilot review threads
❌	CI passing	15 check(s) still running

Files Changed (3 files, +307 −1)

File	+/−
.changeset/archive-pointers-are-validated.md	+5 −0
packages/squad-cli/src/cli/commands/doctor.ts	+197 −1
test/cli/doctor.test.ts	+105 −0

Total: +307 −1

---

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

[tamirdresher]

Thanks Omer! The pointer scan and tracked file check for #1836 look good, and I verified it merges cleanly with dev. Two adjustments we need before merging after the 2.0.0-preview.2 freeze:

1. In packages/squad-cli/src/cli/commands/doctor.ts:996, checkHistoryArchiveIntegrity returns status: 'fail' whenever worktreeBlob !== indexBlob. When someone runs squad nap, compressHistory in packages/squad-cli/src/cli/core/nap.ts:245 appends to history-archive.md in the working tree without staging it, so running squad doctor before git add hard fails on a valid tracked archive. Could you make the worktreeBlob !== indexBlob case a warn (while keeping missing or untracked archives as ail)?
2. In packages/squad-cli/src/cli/commands/doctor.ts:1087, checkHistoryArchiveIntegrity(stateDir) runs unconditionally without checking configuredStateBackend(squadDir) or whether stateDir is externalized outside the git worktree (compare checkDecisionsMd at doctor.ts:352). Please add guards for orphan / wo-layer backends and externalized stateDir so doctor does not run working tree git ls-files checks against non-local state.

[omercangumus]

Thanks for catching both issues. A tracked archive changed by squad nap should not be a hard failure, and the integrity check should not run Git tracking checks against two-layer, orphan, or externalized state. I will make those adjustments and push an update.

[omercangumus]

Thanks again for the catches. I pushed an update: tracked archive changes now warn instead of fail, and the Git checks are skipped for orphan/two-layer backends and state outside the worktree. I added regression coverage for those cases; CI is running now.