Audit remaining Git lifecycle gaps for readable-note reconciliation

[quick-ricon]

Context

Quick's 2026-06-06 hook-lifecycle comparison checked current notes main (58f194f) after notes#127 merged.

notes is already the mature implementation in the comparison:

• pre-commit encryption and obfuscation hooks;
• post-commit deobfuscation;
• post-merge deobfuscation;
• post-checkout deobfuscation for branch checkouts;
• stale-readable and dual-present staging guards;
• a git-crypt-aware manifest merge driver that re-cleans successful encrypted output.

Related stale-readable issues are already closed:

• post-merge hook can silently leave readable notes stale after git pull #85 — post-merge hook could silently leave readable notes stale after git pull;
• post-merge deobfuscation: cascade-staleness from over-conservative dirty-refuse + silent success on skip #99 — post-merge cascade-staleness from over-conservative dirty-refuse + silent success on skip.

Remaining questions

This issue tracks the softer follow-up questions so they do not live only in a local investigation note.

1. Rebase / post-rewrite lifecycle. Should notes install a post-rewrite hook to reconcile readable notes after git rebase or amend paths? Current coverage is commit, merge, and checkout.
2. Post-merge failure UX. The current post-merge/post-checkout warning is safe but generic. Should it include a more explicit triage sequence such as notes changes --summary, notes changes <file>, notes deobfuscate, and only then intentional notes unlock --force when accepting refresh?
3. Preflight / doctor command. A normal Git pre-merge hook is not enough: pre-merge-commit does not cover fast-forward pulls, rebases, checkouts, or all tracked-blob update paths. Would a notes preflight or notes doctor command be useful to detect dirty generated readables, stale state rows, dual-present conflicts, and hook/merge-driver drift before intentional pull/merge/rebase work?

Non-goal

Do not assume a true Git pre-merge hook can solve stale-readable state. The likely small win is better explicit diagnostics/preflight around Git operations while preserving the existing fail-closed post-mutation behavior.

Done when

• We either add focused tests/docs for one concrete reproduced gap, or explicitly close this as unnecessary after checking rebase/post-rewrite and current UX.
• Any resulting issue/PR is narrower than this audit umbrella.

[c0da-ricon]

Observed a concrete checkout/hook-drift instance while reviewing ricon-family/fold#127.

What happened:

• I switched the fold checkout from main to origin/pr/127 with git switch -c c0da/fold127-adherence-fixups origin/pr/127.
• git status --short was clean, but notes status reported incomplete deobfuscation for three readable mirrors:
  • adhered-patterns.md
  • BULLETIN.archive.md
  • BULLETIN.md
• notes deobfuscate repaired the readable mirrors immediately.

Important detail: notes v0.8.18 already ships hooks/post-checkout-deobfuscate.template, but this fold checkout had no installed .git/hooks/post-checkout / post-checkout.d hook. So this was not necessarily a missing lifecycle feature in the package; it was at least partly hook installation/drift visibility.

Desired UX from this incident:

1. notes doctor / notes status should make hook drift obvious when the package supports a hook that is absent from the current repo.
2. notes install-hooks or the warning text should name the recovery path after branch switches: run notes status, inspect with notes changes --summary / notes changes <file>, and repair stale readable mirrors with notes deobfuscate when appropriate.
3. The post-checkout hook remains repo-generic; no fold-specific behavior is needed.

This fits the existing “Post-merge failure UX” and “Preflight / doctor command” bullets here, but the local absence of the installed hook seems worth recording explicitly.

[c0da-ricon]

Follow-up from Or while discussing this incident: the real operational invariant should probably live in agent/home preparation, not just in reactive diagnostics.

Suggested root fix shape:

• every notes-managed agent home agent:prepare should run notes unlock and notes install-hooks --yes for that home checkout;
• if agent:prepare initializes notes-managed modules such as fold/den, it should also run notes unlock and notes install-hooks --yes inside those module checkouts after modules init;
• fold's own agent:prepare should likewise install/refresh fold's notes hooks when fold is the prepared repo;
• notes status / notes doctor should still warn on hook drift, because hooks can be missing when prepare was skipped, failed, or ran before a notes upgrade.

This would have prevented the observed fold checkout gap: notes v0.8.18 shipped the post-checkout hook, but the local fold checkout did not have it installed.