docs(state-backends): document pre-commit hook, post-upgrade flow, and recovery#1227
Open
tamirdresher wants to merge 1 commit into
Open
docs(state-backends): document pre-commit hook, post-upgrade flow, and recovery#1227tamirdresher wants to merge 1 commit into
tamirdresher wants to merge 1 commit into
Conversation
…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>
Contributor
🟢 Impact Analysis — PR #1227Risk tier: 🟢 LOW 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (3 files)
This report is generated automatically for every PR. See #733 for details. |
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| 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 | No Copilot review threads |
| ❌ | CI passing | 7 check(s) still running |
Files Changed (3 files, +121 −2)
| File | +/− |
|---|---|
docs/src/content/docs/features/state-backends.md |
+37 −2 |
docs/src/content/docs/scenarios/troubleshooting.md |
+47 −0 |
docs/src/content/docs/scenarios/upgrading.md |
+37 −0 |
Total: +121 −2
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
There was a problem hiding this comment.
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-commitandpost-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=1caveat).
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). |
Comment on lines
+184
to
+185
| 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 |
This was referenced Jun 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1226
Summary
Fixes three documentation gaps in the two-layer / orphan state-backend upgrade flow:
state-backends.mdlisted 4 hooks; the code installs 6 (pre-commitandpost-commitwere missing from the docs).state-backends.md:409claimed.squad/files remain on disk as a read-only reference. The migration code atmigrate-backend.ts:218-235actually removes them. Updated the doc to match.troubleshooting.mdentry for thewarning squad pre-commit: refusing to commit two-layer statemessage, an "After upgrading" verification checklist toupgrading.md, and a "Steady-state safety net" section instate-backends.mdexplaining thepre-commit+post-commithooks and theSQUAD_SYNC_ACTIVE=1bypass.Files changed
docs/src/content/docs/features/state-backends.md— hook list, post-migration claim, steady-state safety net sectiondocs/src/content/docs/scenarios/troubleshooting.md— pre-commit recovery entrydocs/src/content/docs/scenarios/upgrading.md— post-upgrade verificationOut of scope
docs/, nopackages/*/src/).Test plan
npm run buildpasses locally