Repository navigation
feat: durable close-out receipt (HANDOFFS.md) — prevent silently-skipped close-out reports - #52
Merged
Merged
Conversation
New starter-kit/HANDOFFS.md: a per-session `handoff`-block receipt ledger, a SEED-disposition twin of the action ledger, so the close-out handoff becomes a durable, machine-checkable artifact instead of a transient note. Wired into bin/_manifest.py (DISTRIBUTION SEED + SEED_FORMAT_MARKERS "Handoff Receipts"). sync seeds it, status reports present / present (stale format), sync never clobbers it. Layer 1 of the pre-declared close-out-receipt vertical slice (plan on fork main: docs/planning/close-out-receipt-durable-artifact-plan.md). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
New canonical-only bin/check-handoff (python3 stdlib): isolates the newest ```handoff receipt block (CommonMark fence-nesting aware, so the template's own 4-backtick-wrapped example is never misparsed) and asserts presence + structural completeness — required non-empty keys, integer 1..10 scores (self/predecessor distinct), path:line in key_files, sha-or-`pending` in what_was_done, status complete/reconciled/pending — plus anti-pattern lints (pick-next-from-backlog, need-to-verify, bare placeholders). Never checks semantic quality (that stays the Phase 3A scoring loop). Tests 21-22 cover pass + every field/lint defect + block isolation + Session-1 exemption + fresh-seed. Built by Sonnet 5; Opus review accepted `status: reconciled` (P4's backfill status) and made the HANDOFFS.md template checker-safe (dropped inline # comments — # is a literal value char, cf. `PR KJ5HST#52`). Suite 81/82 (the 1 = expected github-source 404 on the not-yet-pushed HANDOFFS.md). Layer 2 of the close-out-receipt vertical slice. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…+ IM Core protocol wiring for the close-out receipt: - SESSION_RUNNER.md: 1B opens a `status: pending` receipt stub (committed with the claim, a fresh-clone-durable crash breadcrumb); 3D gains "Write the six as a durable receipt" (complete the HANDOFFS.md block, bin/check-handoff asserts structure not quality); Planning-session checklist + vertical-slice revert both now owe the receipt. - ITERATIVE_METHODOLOGY.md: Phase 1B stub step, Phase 6 step 7 (handoff), and the Review/Audit, Planning, and Debugging session types all name the receipt. Learning KJ5HST#8 meta-gate: every close-out restatement in these two files reconciled; the 3 campaign checklists follow in P3b. check-links clean; no numbered-set drift (the receipt encodes the same six minimum handoff requirements, adds no 7th). Layer 3a of the close-out-receipt vertical slice. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…KJ5HST#8) Adds the HANDOFFS.md receipt item alongside every CHANGELOG ledger item in the three campaign per-session + consolidation close-out checklists (TEMPLATE, INHERITED_CODEBASE_FAMILIARIZATION, RESEARCH_EXHAUSTIVE_VERIFICATION). Completes the Learning KJ5HST#8 meta-gate: every checklist that restates close-out now names the receipt, so no session type silently exempts it. check-links clean. Layer 3b of the close-out-receipt vertical slice. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Extends Phase 0 reconcile-on-read to backstop the receipt (the case CI/hooks can never see: a session that committed work but skipped or only stubbed its receipt, or crashed). SESSION_RUNNER.md step 6 + the mechanics note, and IM Pre-Flight, now also reconcile HANDOFFS.md: compute its frontier, and a missing receipt for a committed session or a frontier block still `status: pending` is reconstructed best-effort as `status: reconciled` at the next Orient — folded into the one write Phase 0 already permits, not a second write. Honest limit kept: catches only sessions that left a commit or a 1B stub. Built by Sonnet 5; Opus review verified the CHANGELOG-reconcile text is untouched and the false-positive scoping (one receipt per session, keyed to the already- computed undocumented set, not per commit), and documented `status: reconciled` in the HANDOFFS.md seed (the gap the review surfaced). check-links clean; 81/82. Layer 4 of the close-out-receipt vertical slice. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…p-hook rec) - FM #6 (skip close-out) countermeasure now names the durable HANDOFFS.md receipt: close-out is not done until it's written; a spoken report leaves no trace, a missing/pending receipt is caught at the next Orient. No new FM — count stays 27. - New Degradation Detection row: commits landed but the receipt was never completed (still status: pending) -> FM #6 active. - Learning KJ5HST#9: a handoff is dependable only as a durable, machine-checkable artifact — gate-on-write (receipt + bin/check-handoff) AND reconcile-on-read (Phase 0), neither alone; same honest ceiling (structure not quality; no-commit escapes). - SAFEGUARDS "Close-Out Completeness Hook" + BOOTSTRAP Step 10 pointer: a RECOMMENDED (never shipped) agent-harness session-end hook for the in-session catch — soft- remind, agent-specific. Notes bin/check-handoff is canonical-only/copyable; the adopter discipline itself is the synced write-step + reconcile. check-links clean; 81/82; no FM/learnings count drift. Layer 5 of the close-out-receipt vertical slice. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Creates the canonical repo's own root HANDOFFS.md and writes this very slice's close-out receipt (S1) into it — the session that built the receipt mechanism closes itself out with a receipt. bin/check-handoff validates it green (the first non-fixture run), proving the write -> check path end to end. Final verification: bin/tests.sh 81/82 (the 1 = expected github-404 that clears on merge), bin/check-links clean, bin/check-handoff green on the real receipt. Version event (D4) deferred to merge per the ratified plan; CLAUDE.md §Versioning untouched. Authored by Opus (P6's deliverable is the session's own handoff, not a delegable mechanical phase). Layer 6 — final — of the close-out-receipt vertical slice. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ha (final-review C1/C2/C7)
Adversarial final review (wf_91880f5f-35c) confirmed two holes in the checks that
enforce the load-bearing Minimum Handoff Requirements:
- C1 key_files false-positive: `\S+:\d+` accepted any incidental colon-digit in
prose (John 3:16, 10:30, 3:1, auth:2fa). Now the pre-colon token must be
path-like (contain / or .). Tradeoff documented: ./Makefile:12 for ext-less files.
- C2 what_was_done false-negative: `[0-9a-f]{7,40}` accepted bare 7+ digit decimals
(counts, unix timestamps). Now requires at least one hex letter.
- C7: docstring caveat that an unwrapped ```handoff example shadows the real receipt.
Regression tests added for C1 + C2 (suite 81 -> 83; the 1 fail stays the expected
github-source 404). good_handoff + the real root receipt still pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…final-review C4/C5/C6) - C4/C5: the mandatory-procedure references to bin/check-handoff (SESSION_RUNNER 3D, IM Phase 6 step 7, the HANDOFFS.md seed) now carry the "canonical-only — copy it in; the dependable backstop is Phase 0 reconcile" caveat that only the optional-hook subsections (SAFEGUARDS/BOOTSTRAP) previously had. An adopter grepping for the tool no longer finds a bare reference to something not synced into their project. - C6: the receipt-to-requirements mapping no longer double-counts self_score (requirement #6 IS self_score) — now "the six requirements (the sixth is self_score) plus predecessor_score." Applied to all three twinned sites. check-links clean; suite 83/84; root receipt green; "six" claim still accurate. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…inal-review C3/C4/C5) - C3: HANDOFFS.md added to BOOTSTRAP's seed enumerations (repo tree, root-files table, the "seeded" sync sentence, the "seeded-once" update note) so the guide no longer lists the seed set as three files. Deliberately NOT added to the named three-file BACKLOG/CHANGELOG/ROADMAP task-tracking split (HANDOFFS is a close-out record, not part of that concept; keeps the "three" count accurate). - C4/C5 (campaign part): the campaign per-session checklists drop the bare bin/check-handoff mention (canonical-only tool an adopter may not have); the caveated reference stays in SESSION_RUNNER §3D. Now consistent with the consolidation checklist lines. Final review fully discharged: all 7 confirmed findings fixed across commits 28cecc8 (A), ac97722 (B), this (C). check-links clean; suite 83/84. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
rmsharp
added a commit
that referenced
this pull request
Jul 9, 2026
Version bump v3.2 -> v3.3 (tenths / minor): - CLAUDE.md "Current version" line + a new §Versioning "v3.3" narrated entry - README.md "What's New in v3.3" - root CHANGELOG.md: a release-pointer entry (cite-don't-restate) + finalize the close-out-receipt feature entry (merged as PR #52, e5638af) Covers the close-out-receipt slice merged in PR #52. No principle, phase, gate, workstream, or FM change; failure-mode count stays 27. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
rmsharp
added a commit
to rmsharp/methodology
that referenced
this pull request
Jul 9, 2026
…it sha HANDOFFS.md had one receipt (S1, the close-out-receipt slice itself) but three more sessions landed commits since with no receipt written: the v3.3 release (dd2c84b/4ec1f47), the doc-completeness follow-up (67581fd/768631e), and the issue KJ5HST#55 filing (6591faa). Reconstructed status: reconciled blocks for S2-S4 from git log + the CHANGELOG entries each session wrote for itself, per SESSION_RUNNER.md Phase 0 step 6. Also backfilled S1's commit: pending to the real merge sha (e5638af) now that PR KJ5HST#52 has landed, per HANDOFFS.md's own documented reconcile mechanic. CHANGELOG.md co-staged per the repo's own pre-commit gate (FM KJ5HST#27). bin/check-handoff clean on the newest receipt; bin/tests.sh 84/84; bin/check-links clean.
2 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Closes a structural gap in close-out enforcement: the mandatory close-out report / handoff was the one close-out artifact with no durable form. Of the seven Phase 3 sub-steps, only 3F (the
CHANGELOG.mdledger) produced a git-tracked file — the 3A/3B/3C/3D handoff lived only in the transient, wholesale-overwrittenSESSION_NOTES.md, and the 3G spoken report left no file at all. So a session could commit its work with a clean ledger line and then simply go silent, and every existing mechanism passed: the pre-commit hook saw its co-staged CHANGELOG, and Phase 0 reconcile foundfrontier == HEAD. The skipped handoff was invisible.This makes the handoff a durable, machine-checkable artifact whose absence is detectable — mirroring v3.1's ledger architecture exactly: gate-on-write AND reconcile-on-read.
The mechanism (four layers)
HANDOFFS.mdreceipt — a per-session```handoffblock (a structural twin of the action ledger; SEED-seeded to adopters), carrying the six Phase 3D minimum-handoff fields + the two 1–10 scores as machine-checkable keys. Writtenstatus: pendingat the Phase 1B claim (a committed, fresh-clone-durable crash breadcrumb) and completedstatus: completeat Phase 3D.bin/check-handoff(python3 stdlib, canonical-only) — asserts a receipt's presence and structural completeness (block-isolated, integer scores,path:lineinkey_files, sha-or-pendinginwhat_was_done) plus anti-pattern lints ("pick next from backlog", "need to verify", bare placeholders). Wired intobin/tests.sh.pendingreceipt for a session that left commits is reconstructedstatus: reconciledat the next Orient, folded into the one write Phase 0 already permits.SAFEGUARDS.md/BOOTSTRAP.mdfor the in-session catch.The honest ceiling (stated throughout the docs)
This makes a skipped report durable + auto-detected, not prevented.
bin/check-handoffverifies structure, never quality — a green check is not a good handoff (that stays the next session's 3A score). A session that makes no commit and no 1B stub still escapes; true dependability rests on reconcile-on-read running at the next Orient — the same instruction-class ceiling as the ledger. The only in-session catch is the agent-specific stop-hook, which the methodology can only recommend.What adopters receive
The receipt discipline (the synced Phase 3D write-step + Phase 0 reconcile) and the
HANDOFFS.mdseed ship to adopters.bin/check-handoffand the stop-hook are canonical-only / recommended — adopters copy the checker if they want the structural check; the dependable backstop is reconcile, which needs no tooling. No new hard gate; a project that ignores the recommendation layer operates the methodology unchanged.Verification
bin/tests.sh83/84;bin/check-linksclean; the repo dogfoods its own change — a real rootHANDOFFS.mdreceipt (S1) thatbin/check-handoffvalidates green.sync --source=github) 404ing onstarter-kit/HANDOFFS.md, which is not yet on the default branch — it clears on merge.key_files/what_was_done).Not in this PR
docs/planning/(the ratified plan) is fork-only by convention. The version event is deliberately deferred to merge —CLAUDE.md§Versioning (v3.3 minor vs none) is the maintainer's call, not presumed here.