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