docs(state-backends): document pre-commit hook, post-upgrade flow, and recovery by tamirdresher · Pull Request #1227 · bradygaster/squad

tamirdresher · 2026-06-08T10:25:46Z

Closes #1226

Summary

Fixes three documentation gaps in the two-layer / orphan state-backend upgrade flow:

Hook list corrected — state-backends.md listed 4 hooks; the code installs 6 (pre-commit and post-commit were missing from the docs).
Post-migration file fate corrected — state-backends.md:409 claimed .squad/ files remain on disk as a read-only reference. The migration code at migrate-backend.ts:218-235 actually removes them. Updated the doc to match.
Recovery flow documented — added a troubleshooting.md entry for the warning squad pre-commit: refusing to commit two-layer state message, an "After upgrading" verification checklist to upgrading.md, and a "Steady-state safety net" section in state-backends.md explaining the pre-commit + post-commit hooks and the SQUAD_SYNC_ACTIVE=1 bypass.

Files changed

docs/src/content/docs/features/state-backends.md — hook list, post-migration claim, steady-state safety net section
docs/src/content/docs/scenarios/troubleshooting.md — pre-commit recovery entry
docs/src/content/docs/scenarios/upgrading.md — post-upgrade verification

Out of scope

No code changes. The hooks and migration behavior are correct — the docs just did not describe them accurately.
No changeset (PR touches only docs/, no packages/*/src/).

Test plan

npm run build passes locally
Manual review of rendered Markdown structure
CI passes

github-actions · 2026-06-08T10:25:59Z

🟢 Impact Analysis — PR #1227

Risk tier: 🟢 LOW

📊 Summary

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

🎯 Risk Factors

3 files changed (≤5 → LOW)
1 module(s) touched (≤1 → LOW)

📦 Modules Affected

docs (3 files)

docs/src/content/docs/features/state-backends.md
docs/src/content/docs/scenarios/troubleshooting.md
docs/src/content/docs/scenarios/upgrading.md

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

github-actions · 2026-06-08T10:25:59Z

🛫 PR Readiness Check

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

PR Scope: 🔧 Infrastructure

⚠️ 2 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	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 unresolved Copilot thread(s) — fix and resolve before merging
✅	CI passing	All checks passing

Files Changed (3 files, +119 −0)

File	+/−
`docs/src/content/docs/features/state-backends.md`	+35 −0
`docs/src/content/docs/scenarios/troubleshooting.md`	+47 −0
`docs/src/content/docs/scenarios/upgrading.md`	+37 −0

Total: +119 −0

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

Copilot

Pull request overview

Updates the documentation around the orphan / two-layer state backends to match current CLI behavior, including the full installed hook set, the post-migration fate of .squad/ state files, and a recovery/verification flow for the pre-commit “state leak guard”.

Changes:

Corrects the documented git hook list to include pre-commit and post-commit.
Updates the migration narrative to reflect that migrated working-tree state files are removed after being copied to squad-state.
Adds post-upgrade verification steps and a troubleshooting entry for the pre-commit refusal message (including the SQUAD_SYNC_ACTIVE=1 caveat).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
docs/src/content/docs/features/state-backends.md	Documents the full hook set, corrects migration file-fate, and adds a “steady-state safety net” explanation.
docs/src/content/docs/scenarios/troubleshooting.md	Adds a recovery guide for the pre-commit “refusing to commit two-layer state” message.
docs/src/content/docs/scenarios/upgrading.md	Adds an “After upgrading” verification checklist for `two-layer` / `orphan`.


 When you choose `orphan` or `two-layer`:
- **Git hooks** (pre-push, post-merge, post-checkout, post-rewrite) are installed in `.git/hooks/`
+- **Git hooks** (pre-push, post-merge, post-rewrite, post-checkout, pre-commit, post-commit) are installed in `.git/hooks/`


 4. Preserve all existing state

-**What happens:** Existing `.squad/` files remain on disk as a read-only reference. New decisions and state writes go to the orphan branch (and git notes for two-layer). Over time, the on-disk state files become stale (they're the snapshot from before migration), while the orphan branch and notes contain the latest state.
+**What happens:** After migration, Squad copies your existing `.squad/` state files onto the orphan branch, then **removes** them from the working tree (via `fs.unlinkSync`). Empty agent directories are also cleaned up. Your working tree is clean immediately after — `git status` shows no changes. The orphan branch is the source of truth from this point on. If anything later writes those paths back into the working tree (a tool, an editor save, or an agent code path that bypasses `StateBackend`), the pre-commit hook will block the next commit. See [Steady-state safety net](#steady-state-safety-net) and the [troubleshooting entry](#squad-pre-commit-refusing-to-commit-two-layer-state-into-the-working-tree) below.


+
+**Why files might reappear:** A tool, editor save, or agent code path that writes directly via `fs.writeFile` (bypassing `StateBackend`) will recreate the file on disk. Staging it and attempting a commit triggers this hook.
+
+For the full recovery flow see [troubleshooting](#squad-pre-commit-refusing-to-commit-two-layer-state-into-the-working-tree).


+git push origin squad-state
+git push origin 'refs/notes/squad*:refs/notes/squad*'


+
+3. **If the working-tree copy contains new content not yet on the orphan branch**, lift it through Squad before deleting:
+   ```bash
+   squad memory write --file .squad/decisions.md


bradygaster

I can't approve this yet: the new links in docs/src/content/docs/features/state-backends.md use same-page anchors like #squad-pre-commit-refusing-to-commit-two-layer-state-into-the-working-tree, but that heading is added in scenarios/troubleshooting.md, not this page. Please switch those to a cross-page link (for example ./troubleshooting#...) and recheck the new recovery references.

bradygaster

✅ Flight approves. Cross-page anchor links noted in comments — Tamir can fix in a follow-up. The pre-commit hook and recovery docs are solid and needed.

…d recovery - Correct hook list (4 -> 6) in state-backends.md - Correct misleading claim that working-tree files remain as read-only reference (they're deleted after migration per migrate-backend.ts:218-235) - Add Steady-state safety net section explaining pre-commit + post-commit hooks - Add troubleshooting entry for refusing to commit two-layer state with recovery flow - Add post-upgrade verification checklist to upgrading.md Closes #1226 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 8, 2026 10:25

Copilot started reviewing on behalf of tamirdresher June 8, 2026 10:25 View session

Copilot AI reviewed Jun 8, 2026

View reviewed changes

bradygaster reviewed Jun 13, 2026

View reviewed changes

bradygaster approved these changes Jun 13, 2026

View reviewed changes

tamirdresher force-pushed the squad/1226-state-backend-upgrade-docs branch from 91cf9e2 to a8d90f6 Compare June 14, 2026 04:07

tamirdresher merged commit caef438 into dev Jun 14, 2026
15 checks passed

tamirdresher deleted the squad/1226-state-backend-upgrade-docs branch June 14, 2026 04:23

tamirdresher mentioned this pull request Jun 14, 2026

chore: promote v0.10.1 dev → main + v0.10 stabilisation blog post #1313

Merged

4 tasks

Navigation Menu

docs(state-backends): document pre-commit hook, post-upgrade flow, and recovery - #1227

docs(state-backends): document pre-commit hook, post-upgrade flow, and recovery#1227
tamirdresher merged 1 commit into
devfrom
squad/1226-state-backend-upgrade-docs

tamirdresher commented Jun 8, 2026

Uh oh!

github-actions Bot commented Jun 8, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

bradygaster left a comment

Uh oh!

bradygaster left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		Why files might reappear: A tool, editor save, or agent code path that writes directly via `fs.writeFile` (bypassing `StateBackend`) will recreate the file on disk. Staging it and attempting a commit triggers this hook.

		For the full recovery flow see [troubleshooting](#squad-pre-commit-refusing-to-commit-two-layer-state-into-the-working-tree).

		git push origin squad-state
		git push origin 'refs/notes/squad:refs/notes/squad'

Conversation

tamirdresher commented Jun 8, 2026

Summary

Files changed

Out of scope

Test plan

Uh oh!

github-actions Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟢 Impact Analysis — PR #1227

📊 Summary

🎯 Risk Factors

📦 Modules Affected

Uh oh!

github-actions Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛫 PR Readiness Check

⚠️ 2 item(s) to address before review

Files Changed (3 files, +119 −0)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

bradygaster left a comment

Choose a reason for hiding this comment

Uh oh!

bradygaster left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions Bot commented Jun 8, 2026 •

edited

Loading

github-actions Bot commented Jun 8, 2026 •

edited

Loading