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:
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user