docs: state-backends upgrade flow misses pre-commit hook, file reappearance, and recovery #1226

Summary

The published state-backends documentation says "no manual steps needed" after squad upgrade --state-backend two-layer, but the reality has three significant gaps when users hit the steady-state safety net. The behavior is correct in code — the docs just don't cover it.

Discrepancies between docs and code

1. Hook list is incomplete (4 listed, 6 installed)

docs/src/content/docs/features/state-backends.md:56-59 lists:

Git hooks (pre-push, post-merge, post-checkout, post-rewrite) are installed in .git/hooks/

But packages/squad-cli/src/cli/commands/install-hooks.ts:286 installs 6 hooks:

const requiredHooks = ['pre-push', 'post-merge', 'post-rewrite', 'post-checkout', 'pre-commit', 'post-commit'];

The two undocumented hooks are critical to the steady-state behavior:

• pre-commit (install-hooks.ts:110-127) — refuses commits that stage .squad/decisions.md, .squad/agents/*/history.md, .squad/casting/, or .squad/routing/. Emits ⚠ squad pre-commit: refusing to commit two-layer state into the working tree.
• post-commit (install-hooks.ts:128-142) — calls squad sync --quiet after every commit to push pending state onto the squad-state branch.

2. "Files remain as read-only reference" is incorrect

state-backends.md:409 says:

Existing .squad/ files remain on disk as a read-only reference. New decisions and state writes go to the orphan branch...

Actual code at packages/squad-cli/src/cli/commands/migrate-backend.ts:206-235 deletes the working-tree copies via fs.unlinkSync after migrating them onto the orphan branch (and at lines 236-247 cleans up newly-empty agent directories). The intended behavior is correct ("F1 fix (Round 5, P1.1): the working-tree copies are now stale — the orphan branch is the source of truth"), but the doc still claims the opposite.

3. No recovery flow documented

If anything writes back to .squad/decisions.md or .squad/agents/*/history.md after upgrade (an agent code path that bypasses StateBackend, an editor save, a tool that uses fs.writeFile directly), the pre-commit hook fires and refuses the next commit. The hook output suggests git restore --staged <path> or SQUAD_SYNC_ACTIVE=1 to bypass — but no published doc explains:

• Why the files might reappear in the first place
• The recommended recovery flow (unstage, verify orphan branch has the content, remove from working tree, commit — let post-commit hook sync)
• When (if ever) SQUAD_SYNC_ACTIVE=1 is the right escape hatch, and the cost of using it routinely (it commits state into the working tree, undoing the clean-PR promise of two-layer)
• How to know whether the working-tree copies are stale vs. contain new content worth preserving (and how to lift new content via squad memory write before deleting)

docs/src/content/docs/scenarios/troubleshooting.md and docs/src/content/docs/scenarios/upgrading.md have zero hits for pre-commit, refusing to commit, two-layer, or state-backend.

Repro

1. Take a project on local backend with active state in .squad/decisions.md and a few .squad/agents/*/history.md files.
2. Run squad upgrade --state-backend two-layer.
3. Run any squad agent operation that touches those files (or just touch them).
4. git commit -am "anything" — pre-commit hook refuses the commit.
5. Search the published docs for the message "refusing to commit two-layer state" — zero hits.

Proposed fix

A PR will follow this issue with:

1. docs/src/content/docs/features/state-backends.md — correct the hook list (4 to 6), correct the post-migration file-fate claim (files are removed, not "read-only reference"), add a "Steady-state safety net" section covering the pre-commit + post-commit hooks.
2. docs/src/content/docs/scenarios/troubleshooting.md — add a "I got warning: squad pre-commit: refusing to commit two-layer state" entry with the recovery flow.
3. docs/src/content/docs/scenarios/upgrading.md — add a brief "After the upgrade" verification checklist.

Code references

• packages/squad-cli/src/cli/commands/install-hooks.ts:110-142 — pre-commit + post-commit hook templates
• packages/squad-cli/src/cli/commands/install-hooks.ts:286 — full required hooks list
• packages/squad-cli/src/cli/commands/migrate-backend.ts:206-247 — working-tree file removal after orphan migration

Acceptance criteria

• Hook list in state-backends.md matches the code (6 hooks)
• "Files remain as read-only reference" claim corrected to reflect deletion
• Steady-state safety net (pre-commit + post-commit) documented in state-backends.md
• Recovery flow documented in troubleshooting.md (with the exact hook message)
• After-upgrade verification documented in upgrading.md
• SQUAD_SYNC_ACTIVE=1 bypass mentioned with appropriate caveat