From 4fff6fcd4324820761850f05f4603bdda3e0c63c Mon Sep 17 00:00:00 2001 From: bdeshi Date: Sun, 2 Aug 2026 17:00:01 +0600 Subject: [PATCH] stop the harness deferring to a marker system it deleted MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /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 --- .claude/commands/refresh-docs.md | 9 ++++++--- .claude/skills/feature-loop/SKILL.md | 4 ++-- HARNESS.md | 6 +++++- 3 files changed, 13 insertions(+), 6 deletions(-) diff --git a/.claude/commands/refresh-docs.md b/.claude/commands/refresh-docs.md index 2c3ec02..14a7558 100644 --- a/.claude/commands/refresh-docs.md +++ b/.claude/commands/refresh-docs.md @@ -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 diff --git a/.claude/skills/feature-loop/SKILL.md b/.claude/skills/feature-loop/SKILL.md index d1ad89a..3992adf 100644 --- a/.claude/skills/feature-loop/SKILL.md +++ b/.claude/skills/feature-loop/SKILL.md @@ -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 diff --git a/HARNESS.md b/HARNESS.md index b07a859..8f1d063 100644 --- a/HARNESS.md +++ b/HARNESS.md @@ -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