stop the harness deferring to a marker system it deleted

/refresh-docs step 4 told the agent to check content-model.md's `[spec]` versus
`[live]` markers. The `[spec]`/`[arc1]` system was deleted in 1510a5f, and
`[live]` never existed at all — so the step was unperformable in both halves
while reading as a check. It now says what the doc actually is: no markers, every
sentence a claim to test, with the failure that has really shipped named
explicitly — a subcommand or gate described in the present tense that no code
dispatches. That is exactly what the previous commit found five of.

The feature-loop conflict table was worse than stale. Its Soft row treated "an
unbuilt `[spec]` section's suggested shape" as a convention to deviate from, and
its None row said a request matching a `[spec]` section should proceed with
nothing said about it. Those sections now live in ideas/exploration.md, whose own
header reads "Presence in this list is not permission to build" — so the skill
authorised building from parked ideas that the storage forbids. Both rows now
point at what a doc describes as built.

HARNESS.md gains the fact that explains the asymmetry, since it is now the only
place both marker systems are visible at once: architecture.md's STATUS markers
stayed and content-model.md's went, because a primitive's endgame is load-bearing
for the next decision while an unbuilt disk format is not. A marker inside a doc
the agent already has open still gets read, which is why the second system was
deleted rather than given a stricter rule.

3 files, +12/-6. No gate, threshold or counter moved.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-02 17:00:01 +06:00
co-authored by Claude Opus 5
parent be92b4b957
commit 4fff6fcd43
3 changed files with 13 additions and 6 deletions
+6 -3
View File
@@ -10,9 +10,12 @@ Reconcile documentation with reality. The code is the truth; the docs are the su
output formats, extensions — rather than trusting the recorded numbers.
3. Check `docs/architecture.md` STATUS lines: has a primitive become real, or is one described
as live when it is not built?
4. Check `docs/content-model.md` `[spec]` versus `[live]` markers against what the parser
actually accepts. Frontmatter fields the code reads but the doc omits are drift; fields the
doc promises but the code ignores are worse drift.
4. Check `docs/content-model.md` against what the parser actually accepts. It describes today's
behaviour and carries no markers, so every sentence in it is a claim to test. Frontmatter fields
the code reads but the doc omits are drift; fields the doc promises but the code ignores are worse
drift. Worst, and the kind that has actually shipped: a subcommand, flag or gate the doc describes
in the present tense that no code dispatches. The frontmatter table is the exception — it is the
accepted format, and `state.md` names which of its keys the parser lifts.
5. Check `scripts/allowed-deps.txt` against `go.mod`.
6. Look for facts stated in two docs. Delete one, link to the other.
7. Run `./scripts/verify.sh --list` and check every doc sentence claiming a gate against it. A doc that
+2 -2
View File
@@ -49,9 +49,9 @@ act; do not average two positions into a compromise nobody chose.
| Kind | Examples | What to do |
|---|---|---|
| **Hard** — reverses a deliberate decision | an ADR, an architecture invariant, the permalink shape, the untrusted boundary, a `_MAX` budget, a frozen contract, the dependency policy | **Stop.** Quote the line, name the file, give both paths: comply, or change the decision (new ADR, or supersede the old one). Wait. Never pick for them. |
| **Soft** — exceeds a convention or a `[spec]` shape | a `_WARN` threshold, a style-floor preference, an unbuilt `[spec]` section's suggested shape, a latent item's trigger | State it in one line, proceed with the request, record the deviation where the convention lives. Conventions are a floor, not a decision. |
| **Soft** — exceeds a convention | a `_WARN` threshold, a style-floor preference, a latent item's trigger, a shape sketched in `ideas/` | State it in one line, proceed with the request, record the deviation where the convention lives. Conventions are a floor, not a decision. |
| **Stale** — a doc contradicts the code | `state.md` inventory, a STATUS line, an out-of-date example | Auto-resolve: the code wins. Fix the doc in Document, mention it in the report. No question needed. |
| **None** — the request refines or extends what is written | asking for something a `[spec]` section already describes | Proceed. Say nothing about it. |
| **None** — the request refines or extends what is written | asking for more of something a doc already describes as built | Proceed. Say nothing about it. |
Resolve intelligently where the answer is genuinely unambiguous — a stale doc, or a request that is a
superset of what is written. Surface anything where a reasonable person could have meant either
+5 -1
View File
@@ -218,7 +218,11 @@ and `any` in an **exported** signature — only exported, because ADR-0002 manda
so unexported code reading frontmatter takes `any` legitimately and forever.
**STATUS markers in `docs/architecture.md`** give the target shape *and* what is legal today, so
the agent can read the endgame without building toward it.
the agent can read the endgame without building toward it. They are the only markers of that kind left:
`content-model.md`'s `[spec]` sections were deleted rather than given a stricter "do not build from this"
rule, because a marker inside a doc the agent already has open still gets read. Those shapes moved to
`ideas/`, which nothing sweeps. The asymmetry is deliberate — a primitive's endgame is load-bearing for the
next decision, an unbuilt disk format is not — so one belongs in a doc that loads and the other in storage.
**Six primitives, and everything reduces to one.** `Effect` (ADR-0012) covers work off the request
path — derivatives, indexes, feed files, outbound syndication — on content change, on a schedule, or on