stop the handoff outranking the log, and gate the pointers into it

A session picked up work from .scratch/continue.md and offered the human a doc
trim that was already in HEAD. The handoff was written at 01:06 saying the trim
awaited a yes; the commit containing the trim was amended at 01:12, underneath
it. Five defects made that possible, and four of them are the harness's.

The read order inverted trust: docs/README.md sent the next session to the
handoff "if present, otherwise git log" — consulting the one ungated file
instead of the record that cannot lie, which is backwards from every other rule
here, where the code beats state.md and generated surface.md beats memory. The
handoff is now step 4 of CLAUDE.md's read order, explicitly after the harness
and never instead of it, and anything it calls pending is checked with
git log -- <path> first.

The tick fired too early. "A planned item completed → tick it in continue.md"
sat in the Document step, so it recorded the plan's version of events while the
commit could still move; an amend, a squash or a late fix moves it. Reconciling
now happens after the commit exists, and a completed item is deleted rather than
ticked, because a ticked item still reads as an item.

HARNESS.md authorised the drift outright — it said the file holds "what is
done", which is exactly what continue.md's own header promises it never records.
It is now described as what it is: a temporary handoff, uncommitted, ungated,
discardable, holding the continuation point and the carried findings.

state.md still pointed at .scratch/build-queue.md, replaced two commits earlier.
The dangling-path gate missed it because .scratch was absent from its
alternation, so no pointer into the handoff directory was ever checked. It is
included now, guarded on the directory existing — a fresh clone has no handoff
and must stay green. Both directions were run: present with a stale pointer
fails, absent with docs naming it passes. The gate then flagged its own
explanatory comment, which is why that one path is written without backticks.

No gate can compare an uncommitted file against anything, so the file's job is
narrowed instead of enforced, and HARNESS.md now says which mechanism stands in
for the missing gate rather than implying one exists.

6 files, +47/-9. No rule, threshold or counter moved. CLAUDE.md 138 → 142 of 150.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-02 16:53:58 +06:00
co-authored by Claude Opus 5
parent 1510a5ff7a
commit 8f5d479f06
6 changed files with 47 additions and 9 deletions
+13
View File
@@ -29,6 +29,12 @@ a layout or markup decision dressed as an engine feature. |
## 1. Clarify
Read `docs/state.md`, then `docs/README.md` — the map, always, before deciding what else to open.
**A handoff is not evidence.** If `.scratch/continue.md` says something is pending, waiting, or unfinished,
run `git log --oneline -- <the path it names>` before planning from it. The file is uncommitted, so no gate
compares it to anything, and it is written *during* a change whose commit can still move underneath it. The
log is the only record of what landed. Offering the human work that is already in `HEAD` wastes the turn
they asked the question in.
For code, read the compressed form before the source: `docs/surface.md` locates every declaration,
`go doc` gives a package's surface, a test states its contract. Disciplines: `docs/context-economy.md`.
Use its topic-ownership table to list the docs owning anything this change asserts a rule about,
@@ -174,6 +180,11 @@ before this change. "Which of these would I want to undo alone?" answers it fast
- Never `git push`. Publishing is the human's; committing is bookkeeping.
- Scratch files, `ideas/`, `reference/` and anything under the scratchpad stay out.
**Then reconcile the handoff — once the commit exists, never before.** If `.scratch/continue.md` carried a
planned item this change completed, delete that item now and note anything learned that changes a later
one. Doing it during Document records the plan's version of events instead of the result: an amend, a
squash or a late fix moves the commit under a handoff that already claims what it contains.
## 7. Report
Short — one line each, no prose unless a conflict or a stop condition needs explaining. Drop the lines
@@ -212,6 +223,8 @@ Swept: the old form you grepped for after a rename, or "n/a"
| Treated a one-sentence request as a narrow change | Articulation size is not blast radius | Walk the propagation table |
| Splitting the difference between request and policy | A compromise nobody chose | Surface it; the human picks |
| Ending a turn with the work only in the working tree | The one copy is the one that gets lost | Commit before reporting |
| Offering work a handoff calls pending | The file states intent; only the log states what landed | `git log -- <path>` before trusting it |
| Ticking the handoff during Document | The commit can still move under it | Reconcile it after the commit exists |
| Opening a file to find out what is in it | The generated surface already answers it | `docs/surface.md`, then read the range |
| Grepping for callers before changing a signature | The compiler enumerates them exactly | Change it, then `go build ./...` |
| A shorter report that dropped a caveat, case or number | Truncation wearing compression's clothes | Restore it; cut words, never findings |