HANDOFF — derived orientation page

Run the deterministic generator (never hand-write this page):

(${CLAUDE_PLUGIN_ROOT} is the plugin directory, set by Claude Code. Without it, the same scripts sit in the plugin checkout's root scripts/ directory (a Codex install keeps the whole checkout), in scripts/ beside this SKILL.md (a skills-CLI install), or in your clone of github.com/arbelh/perdure.)

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/handoff.py" .

With --check as the argument, run integrity-check mode instead — it regenerates the page in memory and compares it to the committed one, with or without git, so it catches a stale page, a hand-edited one, and one left with merge-conflict markers. The stamp names the moment of the newest record update, not the commit or the clock, so it is compared like any other line. One fragment is normalized before comparing and is therefore NOT covered: the advisory ⚠ staleness annotations, whose commit counts move on their own. A page in the 4.2.0 format, with its commit-and-minute stamp and old footer, still passes when its content is current. Everything else must match the records exactly:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/handoff.py" . --check

Then:

1. Report the generator's summary line (N records, M withheld for reconciliation).
2. If records were withheld, list them and offer to reconcile: those records contradict themselves or git, and the page deliberately carries none of their claims. Fix them per the convention's Correcting a record rules (correct headers in place with a dated note; paraphrase retractions, never re-quote), then regenerate.
3. Show the user the page path (perdure/HANDOFF.md) and, on first generation in a repo, a one-line explanation: derived, regenerated, never edited; every status is a claim as of the newest record update the stamp names.

On a merge conflict in the page, never resolve it by hand: regenerate it from the merged records (the command above) and commit the result. Its second line says the same, so any tool that opens the file sees it.

Why the lint gate is non-negotiable

A naive derived summary strips the context that lets a reader catch a stale claim, then presents the stale claim with the summary's authority. The generator therefore withholds all state claims from any record the rot lint flags. Do not paste record content into the page by hand around that gate; reconcile the record instead.

What the page does NOT claim

A lint-clean record can still be semantically stale, and external systems (experiments, deployments, tickets) are never checked. The page says this in its own header and footer — leave those disclaimers intact.

When to regenerate

• At workflow close (after the record goes terminal and lint-clean) — the close creates the page if the project has none, and the close-gate hook regenerates a generator-stamped page on its own (opt-out for both: handoff-regen-at-close: false)
• Before a handoff, a long pause, or archiving a session
• Whenever --check reports the page no longer matches the records