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