Session Close Protocol — shared

One protocol, every project. This skill holds the drift-prevention discipline that is identical across projects. The values that differ per project — which files are Bucket A, the size caps, which drift script exists, whether the repo may be pushed — live in that project's _handoff/close_config.md. This skill reads that config and runs the generic steps.

Project-specific safeguards belong in the per-project config, never forked into a second copy of these steps. Divergent copies drift — the exact failure this protocol exists to prevent.

STEP 0 — Load this project's config FIRST

Read _handoff/close_config.md. It declares:

• push_policy: push or local-only (commit but NEVER push — e.g. a repo holding private documents; there may be no remote at all).
• bucket_a: the files rewritten at EVERY close (the session record).
• drift_check: the command that enforces the staleness ledger (or none — then Bucket B is tracked by hand in explicit lists in the handoff).
• ledger: path to the Bucket-B ledger (or none).
• review_refresh, size_bill: optional per-project commands (or none).
• size_caps: the per-artifact caps for this project.

If _handoff/close_config.md is absent, STOP and tell the user the project needs a close config (offer to draft one from the template at the end of this skill). Do not guess a size cap or a push policy — a wrong value is a real hazard.

Why this exists

Prevent DRIFT — the gap between what is true about the project now and what a future session believes is true at startup. It accumulates when (a) the user edits a file outside a session, (b) a session silently skips updating a tracked file, or (c) the context file describes a world later work has changed but the close didn't rewrite. Enough drift and a future session operates on false beliefs. Secondary goal: keep the always-loaded context small by skipping UNCHANGED Bucket B files at startup.

Bucket A vs Bucket B

• Bucket A — ALWAYS rewrite at close: the context file (CLAUDE.md) + the handoff files. Every field reflects today's reality even if the answer is "no change." Exact list = bucket_a.
• Bucket B — CONDITIONAL (touch only if the file's own state changed). Tracked in the project's ledger; without one, track it via explicit UPDATED:/UNCHANGED: lists.

The ledger date means "KNOWN-REVIEWED THROUGH"

The date is the date someone last confirmed the file's contents. It moves forward for exactly two reasons: the file changed, or it was genuinely reviewed. Carry it forward on UNCHANGED — never reset to today for a file you did not look at. Advancing a date without a change is allowed only by acknowledging a valve trip AFTER really reviewing the file (drift_check --ack <path> --note "<what you verified>"). Acking without looking is a FALSE PASS — the one failure mode this gate may never have.

The two staleness valves (when the project has a drift_check)

1. mtime: if an UNCHANGED file's mtime is newer than its ledger date + 1 day, re-read it once, then --ack.
2. calendar: any UNCHANGED file older than its interval gets re-read once, then --acked — the re-read IS the review that earns the new date.

Do NOT "re-read once and leave the stamp" — that re-fires the alert every startup forever and trains you to ignore it. Both valves are enforced by the drift_check script, fail-closed.

THE CLOSE STEPS

1. Name in one sentence what changed (engine / product / docs / cleanup / ops).
2. Identify what files changed — use BOTH git status AND a scan of the session, not memory.
3. For each Bucket B file: decide AFFECTED or UNCHANGED.
4. Update EVERY Bucket A file IN FULL — partial updates are an anti-pattern.
5. Update ONLY the AFFECTED Bucket B files.
6. List both buckets explicitly in the session record (UPDATED: / UNCHANGED:). A silent skip is indistinguishable from a forgotten file.
7. Update the ledger (if any): AFFECTED → today's date (add a :scope for very large files); UNCHANGED → carry the prior date forward. Run drift_check and confirm it does not hard-error.
8. SIZE GATE — check each capped artifact; over cap, prune (move procedures to skills, rules to rules files, history to an archive; trim the handoff to only what the next session must ACT on). Never defer a size check to "protect the close under budget" — that's how a context file reaches 5× its cap over a few deferrals.
9. Refresh the review folder (if review_refresh != none) — never hand-copy files there.
10. COMMIT, and PUSH only if push_policy: push. If local-only, STOP after the commit — do NOT push. Then VERIFY: git status --short must be clean, or every remaining entry is deliberately gitignored. A commit that ran is not the same as a clean tree.

Anti-patterns

• Bumping a date stamp for a file whose content didn't change.
• Skipping a Bucket B file without naming it in the UNCHANGED list.
• Updating Bucket A only partially.
• Resetting date stamps to today for files you did NOT review (the most subtle, damaging error).
• Leaving a valve trip un-acked once it IS reviewed (a permanently-red gate trains you to ignore red).
• Hooking SessionStart to mandate any Bucket B file by name (defeats the conditional mechanism).
• Letting the context file grow back past its cap.
• Pushing a local-only repo.

APPENDIX — _handoff/close_config.md template

# Close config — <PROJECT NAME>
push_policy:     push            # or: local-only
bucket_a:        CLAUDE.md, _handoff/Next_Session_Handoff.txt, _handoff/Session_Block_Latest.txt
drift_check:     python "$HOME/.claude/ops/startup_read_check.py"   # or: none
ledger:          _handoff/bucket_b_ledger.txt                        # or: none
review_refresh:  none
size_bill:       none
size_caps:
  - CLAUDE.md: 30000 chars
  - _handoff/Next_Session_Handoff.txt: 8000 chars
  - gitStatus: tree clean
notes: <anything project-specific>