bdeshi/khosra
0
0
Fork 0
Code Issues Pull Requests Releases Activity

rename docs/ to harness/, and reserve docs/ for the reader

Browse Source 
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>
This commit is contained in:
bdeshi
2026-08-02 20:11:06 +06:00
co-authored by Claude Opus 5
parent 9349c54d2e
commit ec6e9838f0
31 changed files with 146 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/feature-loop/SKILL.md
+11 -11
View File
@@ -19,7 +19,7 @@ are the first and the last.
| the site root | Out of reach: it lives in its own repo (ADR-0011). A disk-contract change ships a **written migration step** the author runs, plus a note on whether any bundle key or URL moves. Never claim to have migrated files you cannot see. |
| code | The engine, plus a test for the new behaviour. |
| the theme | Out of reach, like the site root (ADR-0023). This repo ships a **contract extension** in
`docs/theme-contract.md` plus a written note of what a theme must do — never the theme itself, and never
`harness/theme-contract.md` plus a written note of what a theme must do — never the theme itself, and never
a layout or markup decision dressed as an engine feature. |
| fixtures and emitted output | Fixture sites in `testdata/`, the embedded default templates (a reference implementation of the contract), and anything reading a field or path shape you altered. |
| harness docs | Every doc, ADR, marker or example that assumes the old form. An ADR that mandates what you just made optional is not stale, it is **contradicted** — supersede it, do not quietly reword it. |
@@ -28,15 +28,15 @@ a layout or markup decision dressed as an engine feature. |
## 1. Clarify
Read `docs/state.md`, then `docs/README.md` — the map, always, before deciding what else to open.
Read `harness/state.md`, then `harness/README.md` — the map, always, before deciding what else to open.
**A handoff is not evidence.** If `.scratch/continue.md` says something is pending, waiting, or unfinished,
run `git log --oneline -- <the path it names>` before planning from it. The file is uncommitted, so no gate
compares it to anything, and it is written *during* a change whose commit can still move underneath it. The
log is the only record of what landed. Offering the human work that is already in `HEAD` wastes the turn
they asked the question in.
For code, read the compressed form before the source: `docs/surface.md` locates every declaration,
`go doc` gives a package's surface, a test states its contract. Disciplines: `docs/context-economy.md`.
For code, read the compressed form before the source: `harness/surface.md` locates every declaration,
`go doc` gives a package's surface, a test states its contract. Disciplines: `harness/context-economy.md`.
Use its topic-ownership table to list the docs owning anything this change asserts a rule about,
and read those. That list is a floor: skipping it is how a rule gets written twice and the second
copy contradicts the first.
@@ -96,7 +96,7 @@ If the plan reveals a trunk, say so instead of planning and offer the leaf.
- Smallest code satisfying the success criteria. Nothing for the version after next.
- Only the planned files. No renames, reordering, reformatting beyond `gofmt`, or tidying of
neighbouring code.
- Something wrong outside the plan? One line on the Latent list in `docs/state.md`, keep moving.
- Something wrong outside the plan? One line on the Latent list in `harness/state.md`, keep moving.
That is the whole mechanism; use it instead of a drive-by fix.
- Reuse the existing shape before inventing one. Copying eight lines twice beats an abstraction at
use two; the third use is when it becomes a design.
@@ -123,12 +123,12 @@ not run something, say which and why.
## 5. Document
Same change, not later. Triggers: `docs/README.md`. Walk the propagation table above — every surface
Same change, not later. Triggers: `harness/README.md`. Walk the propagation table above — every surface
done or explicitly n/a. Minimum:
- `docs/state.md`: inventory rows, counters, latent items added/removed — in *this* commit, never a
- `harness/state.md`: inventory rows, counters, latent items added/removed — in *this* commit, never a
trailing one, which is what `verify.sh` compares (ADR-0057).
- `docs/decisions.md`: an ADR if the choice is expensive to reverse. Six lines. First open the doc
- `harness/decisions.md`: an ADR if the choice is expensive to reverse. Six lines. First open the doc
that owns the topic — if it already carries the rule, amend it there; an ADR restating an
existing doc is a duplicate, not a decision.
- Any other doc **only if the change made it wrong.** Never state one fact in two docs.
@@ -139,7 +139,7 @@ Doc edits are surgical too. Prefer deleting a stale line to appending a correcte
elsewhere in the old terms:
```
grep -rn '<old form>' docs CLAUDE.md HARNESS.md ideas reference .claude scripts
grep -rn '<old form>' harness CLAUDE.md HARNESS.md ideas reference .claude scripts
```
`verify.sh` fails on dangling file paths, ADR numbers and `CLAUDE.md` section refs. It cannot detect
@@ -216,7 +216,7 @@ Swept: the old form you grepped for after a rename, or "n/a"
| Renaming "for clarity" mid-feature | Drive-by refactor | Latent list |
| Explaining why the boundary can bend here | It cannot (ADR-0003) | Stop and ask |
| Plan grew while implementing | Scope drift | Stop, re-plan, continue |
| Writing a rule without reading its owning doc | Guessing where you could look | `docs/README.md` topic table, then amend that doc |
| Writing a rule without reading its owning doc | Guessing where you could look | `harness/README.md` topic table, then amend that doc |
| Quietly doing what was asked against a recorded decision | The conflict was real and you hid it | Quote the line, give both paths, wait |
| Changed the rule in code, left the docs describing the old one | Propagation stopped at the first surface | Walk all four surfaces |
| Made a field optional, left the ADR mandating it | Contradicted, not stale | Supersede the ADR |
@@ -225,7 +225,7 @@ Swept: the old form you grepped for after a rename, or "n/a"
| Ending a turn with the work only in the working tree | The one copy is the one that gets lost | Commit before reporting |
| Offering work a handoff calls pending | The file states intent; only the log states what landed | `git log -- <path>` before trusting it |
| Ticking the handoff during Document | The commit can still move under it | Reconcile it after the commit exists |
| Opening a file to find out what is in it | The generated surface already answers it | `docs/surface.md`, then read the range |
| Opening a file to find out what is in it | The generated surface already answers it | `harness/surface.md`, then read the range |
| Grepping for callers before changing a signature | The compiler enumerates them exactly | Change it, then `go build ./...` |
| A shorter report that dropped a caveat, case or number | Truncation wearing compression's clothes | Restore it; cut words, never findings |
| One commit per file, or per doc touched | Shredding a single revertible unit | Bundle what would be undone together |