fable-ship

The report is part of the work, not an afterthought. Ship a calibrated claim and the docs that let a stranger redo it.

The report

• Answer first, then the support. Lead with the verdict (done / not done / exact / blocked) in the first line; put evidence underneath, never above.
• Scale the report to the tier. T1 = the verdict, its Verified: line(s), and the tier line — a few lines, not a document. The full shape here is for T2+.
• Separate verified from assumed, out loud — as the method's ledger (canonical shapes: the method skill's ledger section; same tokens every report, and the Stop-hook gate greps for them). Never let an Assumed: line read like a Verified: one.
• Cite specifics: paths, counts, file:line, the command you ran, the number you saw, before→after deltas.
• Report what you observed, not what you intended. If a step was skipped or a test failed, say so with the output.
• Calibrate "done" with a use-boundary. Stamp unproven results PROVISIONAL ("do not quote these yet") and lift it explicitly only when the check passed. Scope the claim to exactly what you measured; put the rest in a visible residual list.
• State the tier and its gates. One line: Tier: Tn — gates run: <verify / review lenses / human gate>. A skipped gate that leaves no trace is invisible exactly when it matters.
• Never soften a real problem — including your own. Flag anything the human must decide (⚠️), state it plainly with the evidence, and repeat the flag into every downstream artifact (PR body, log, memory), not just the chat.
• End with what the reader still owns. Even a perfect report leaves a short list: every Assumed: line, plus any T3 (outward/production) action gated to the human. Say it explicitly — worry-less means a short, honest residual list, not an empty one.
• Close in the reader's language: where we are, what's next. After the ledger, two plain-language lines — the state of the work, and the single next move with whose it is. No session-jargon: a label coined mid-work (a codename, a phase number, an internal shorthand) gets one plain-word gloss or stays out of the report. The reader is catching up, not replaying your process — findings go above; the ending is orientation.

Docs-as-done

A change isn't done until someone else could redo it from the record it leaves. In the same change that ships the work, update the record it affects — runbook, config/topology doc, implementation log. Scope it to impact: when a change is fully self-evident in code + tests + commit message, that is the record — never write prose that restates a diff (point-don't-copy applies to your own work too). Convert relative references to absolute (dates, versions). Keep one canonical source for a fact; have other docs point to it rather than restating.

Curate the project overlay

If .fable/project.md exists, fold in what this task confirmed — durable facts and gotchas (Gotcha: <trap> → Cause → Rule) — and announce what changed. Log gotchas liberally — over-capture beats missing one. Compact on trigger, not ritual: when the overlay is pushing past ~a page or entries are visibly stale, dedup, retire the obsolete, promote the recurring; skip the pass when it isn't needed. And never compact in place. The overlay is git-ignored, so it has no history and no prior revision: a bad or interrupted rewrite of the one file holding the acceptance oracle and the standing human rulings is unrecoverable — nothing else keeps a copy. Write the new page beside it, confirm the anchors survived (every oracle row, every ack'd: human ruling), then replace, keeping the previous version as .fable/project.md.bak. Note the asymmetry the method already relies on: expiry demotes entries (non-destructive, correct); compaction retires them (destructive) — and compaction is the one operation that can silently move an anchor. Check .fable/gate-log too: each line is a turn the calibration gate had to bounce; a recurring bounce is a gotcha about working habits — log it like any other trap.

Keep the calibration record — durable writes first, the destructive one last. These steps have exactly one safe order, and it is not the order they occur to you in:

1. Append every Verified: line from the final report to .fable/claims-log (date · claim · command) — this is what fable-debug falsifies against when a vouched-for behavior later breaks.
2. Route undischarged Assumed:/PROVISIONAL lines to .fable/residuals.md (the SessionStart hook surfaces the open count until they're discharged).
3. Fold what this task confirmed into the overlay.
4. Only then, retire the task file (.fable/tasks/<slug>.md) — promote surviving decisions into the project's committed decision records (docs/decisions/, if the project keeps them) or the overlay, and durable facts into the overlay or the project's own docs, then delete it. An in-flight pointer that outlives the work is a lie the next session inherits.

The task file is the transaction's commit record: while it exists, an interrupt is recoverable — you re-read it and redo the steps. Delete it first and an interrupt destroys the Assumed: list with no trace, SessionStart reports nothing open, and the run reads as a clean finish. A silent false-clean is the worst state this record can reach, and step order is the whole defence.

Never trim residuals.md. An open residual is an obligation, not a log line — trimming by length discharges the oldest unverified assumptions, which are precisely the ones most likely to have rotted, and silences the only counter that nags about them. If it is pushing a page, that is a finding to report, not a file to shorten. claims-log: archive, never truncate — move aged lines to .fable/claims-log.<year> (fable-status and fable-debug read the archives too). A deleted Verified: is a claim that can never be falsified, and the record of your own bounces is not yours to prune. gate-log needs nothing from you: it rotates itself in the hook, because expiry belongs in the deterministic half rather than in a habit.

Before you call it shipped

Run fable-verify on the central claim. Don't state as fact anything you haven't verified this session.