bdeshiandClaude Opus 5
ec6e9838f0
docs/content-model.md opens with "Engine specification". It is also where the rule lives that a leading underscore makes a file unaddressable — and the human who owns this site did not know that rule, because nothing in this repository is addressed to an author. Twelve documents named docs/ while being exclusively about building the parser is a signpost pointing at the wrong room. Naming the directory for its audience makes the gap visible instead of hiding it. docs/ is now reserved and deliberately absent: an empty docs/ is an honest statement that end-user documentation does not exist, where docs/ full of parser specs was a claim that it did. HARNESS.md stays at the root. Root holds the three entry points — README.md for a human, CLAUDE.md for an agent, HARNESS.md for whoever maintains the machine — and harness/README.md is the map of the directory, so moving the guide inside would have collided with it for nothing. Mechanical and wide: 100 path references across 24 files. Every verify.sh gate that names a doc by path, the directory lists the dangling-path and ADR-number gates scan, surface.sh's output target, the Makefile, CLAUDE.md's read order, the skill, four commands, and two Go package comments. A first pass with a shell loop silently edited only four files and the rest still said docs/; the fix was to write the file list out and check the remaining count was zero rather than trust the loop's exit status. No rule, threshold, gate or obligation moved — this is a rename, and the gates demonstrated it twice: they stayed green on the new paths, and the ADR-number gate caught ADR-0082 before the entry existed. Deferred, both on the human's call: the end-user documentation site itself, which wants its own decision about where it lives and whether its claims are gated; and moving examples/ under docs/, since demo-site is a live site root that verify.sh, the coverage test and make demo all point at, and moving it would couple a rename to a design nobody has made. 31 files, +146/-106. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
22 lines
1.1 KiB
Markdown
22 lines
1.1 KiB
Markdown
---
|
|
description: Record an architectural decision in six lines
|
|
---
|
|
|
|
Append an ADR to `harness/decisions.md` using the exact format at the top of that file.
|
|
|
|
First, before writing anything: find the doc that owns this topic via the ownership table in
|
|
`harness/README.md` and read it. If it already carries the rule, do not write an ADR — amend that doc
|
|
and say that is what you did. An ADR that restates an existing doc is a duplicate, not a decision.
|
|
|
|
Rules:
|
|
- Next sequential number. Never renumber, never rewrite an existing entry.
|
|
- To reverse a decision, add a new ADR and mark the old one `superseded by ADR-NNNN`.
|
|
- Six lines. If the reasoning needs more, the decision is not yet made.
|
|
- `Revisit if:` must name a specific observable event, not "if requirements change".
|
|
- If the decision adds a dependency, update `scripts/allowed-deps.txt` in the same change.
|
|
- If the decision raises a budget, update `scripts/budgets.env` in the same change and state
|
|
the old and new values in the ADR.
|
|
|
|
If the argument for `$ARGUMENTS` is thin — no forcing reason, or no consequence you can name —
|
|
say so and ask one question rather than writing a hollow entry.
|