diff --git a/CLAUDE.md b/CLAUDE.md index 2a5cbe1..32c9188 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -86,10 +86,12 @@ the test: `docs/architecture.md`. ## 4. The loop (every request, no exceptions) `Clarify → Plan → Implement → Verify → Document → Commit → Report`. -Procedure: `.claude/skills/feature-loop/SKILL.md`. The three gates people skip: +Procedure: `.claude/skills/feature-loop/SKILL.md`. The gates people skip: -**Clarify.** Only questions whose answer changes the code or the bytes on disk. Max three, -batched, up front, each with a **bold** default so silence answers. Never about naming, formatting, +**Clarify.** Only questions whose answer changes the code or the bytes on disk — but ask every one of +those. Batched, up front, each with a **bold** default so silence answers. There is no cap: a request +carrying six real forks gets six questions, and splitting them across turns to look brisk wastes more of +the human's time than asking once. Never about naming, formatting, or anything `docs/conventions.md` decides. None to ask? State assumptions in one line and move on. **Verify.** `./scripts/verify.sh --quiet` green, plus one piece of feature-specific evidence you actually diff --git a/HARNESS.md b/HARNESS.md index 8708b02..6683583 100644 --- a/HARNESS.md +++ b/HARNESS.md @@ -7,7 +7,7 @@ before code, docs that stay true. constitution (always loaded). `docs/` is what the agent needs to build the engine — anything in it may be pulled into context on demand. `ideas/` and `reference/` sit outside `docs/` deliberately: storage, opened only when you name a file, swept by nothing. -`.claude/` holds the feature-loop skill (`skills/feature-loop/`), six commands, and `launch.json`. +`.claude/` holds the feature-loop skill (`skills/feature-loop/`), the commands, and `launch.json`. `scripts/` holds the gate. ## How you use it @@ -23,7 +23,8 @@ contradicts every doc calling it required. The agent walks every surface — cod need to run there rather than pretending to have done it. 1. **You:** "Add tag pages." -2. **Agent:** up to three clarifying questions, each with a default. Answer or ignore. +2. **Agent:** the clarifying questions whose answers change the code — as many as there are, batched into + one turn, each with a default. Answer or ignore. 3. **Agent:** a short plan — goal, primitive, success criteria, files, ±LOC, deps, earn-it check, and what it is deliberately *not* doing. 4. **You:** "go", or edit the plan. "Just do it" skips the gate on small changes. @@ -68,34 +69,23 @@ into an author's prose. It worked and it had tests; `text-wrap: pretty` does it content, so the feature was deleted (ADR-0045). If a feature only rearranges how something looks, expect the agent to push back toward CSS or a template. -**The ceilings have moved three times, all on purpose, and the third is a different kind.** The first two -were measurements — a number costed before any code existed, then eight lines of contract that would not fit. -The third (ADR-0074) is a budget: core 2850 → 3000, ext 2000 → 3500, modules 6 → 9, signed off ahead of a -list of features rather than in response to one. `ext` was genuinely blocking at 1975 of 2000; the rest is -headroom bought deliberately. Invariant 9 is measured by a number that has now moved three times, and says -something only because ext rose 75% against core's 7%. +**The ceilings have moved three times, and the third is a different kind.** The first two were +measurements — a figure costed before any code existed, then a contract that would not fit. The third +(ADR-0074) is a budget, signed off ahead of a list of features rather than in response to one. The values +themselves live in `scripts/budgets.env` and nowhere else, including here: each ADR records the old and new +figures, and prose that repeats them is a copy waiting to go stale. Invariant 9 — "core stops growing after +Arc 2" — is measured by a number that has now moved three times, and still says something only because `ext` +has risen far faster than core. -**The core ceiling has moved twice before that, both on purpose.** `CORE_LOC_MAX` went 2000 → 2800 (ADR-0041) because the -original figure was costed before any code existed and never budgeted what `cmd/` would hold — `check`, `new`, -`-dev`, change detection. It went 2800 → 2850 (ADR-0065) for eight lines of theme contract, and ADR-0041's own -test — read a second raise as evidence something belongs in `internal/ext/` — was applied rather than waived: -`feed.go` and `discover.go` are the features that should leave, and they cannot, because an `ext` feature -cannot own a **route** until the extension registry exists. When it does, they leave and this ceiling should -come back down rather than stay as headroom. The two ceilings exist so that "core stops growing, ext rises" is -observable, and that stops being true the moment leaves are allowed into core. - -**The binary grew for syntax highlighting.** chroma is larger than khosra and takes it from ~15MB to -~20MB (ADR-0075). That was a deliberate trade for a site that shows code constantly, and it is the one place -where "one small binary" got less true. - -**Context is a budget, and three pieces of it are mechanical.** The limit on this project is how much +**Context is a budget, and parts of it are mechanical.** The limit on this project is how much work fits in a session, so `docs/context-economy.md` holds the reading, searching and reporting disciplines — read the compressed form first, batch calls, script anything repeatable, never pay twice -for the same bytes (ADR-0053). Three parts are enforced rather than trusted: `docs/surface.md` is +for the same bytes (ADR-0053). These are enforced rather than trusted: `docs/surface.md` is regenerated and staged by the pre-commit hook and independently compared by `verify.sh`, so the map of -the code cannot mislead (261 lines standing for 3,757 of source) and no one has to remember to run it; +the code cannot mislead — an order of magnitude smaller than the source it stands for — and no one has to +remember to run it; `CLAUDE_LOC_MAX` bounds the one file re-sent on every turn; -and `./scripts/verify.sh --quiet` prints a verdict instead of forty-three lines, which is what the +and `./scripts/verify.sh --quiet` prints a verdict instead of a line per gate, which is what the pre-commit hook now runs. The doc leads with a floor rather than the savings, because every cheap failure mode is also a token saving — not opening the owning doc, guessing a signature, reporting from a diff — and each of those has already cost this repo a defect. diff --git a/docs/README.md b/docs/README.md index 7239050..3524c12 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,7 +17,7 @@ Read the one you need. Do not read them all. | `context-economy.md` | How the agent spends context: what to read, in what form, and the floor no saving may cross | When a technique or a gate for one changes | | `surface.md` | **Generated.** Every top-level declaration with its line — read before opening source | Never by hand; `make surface` | -Two sibling folders sit **outside** `docs/` because they are storage, not working material: +Sibling folders sit **outside** `docs/` because they are storage, not working material: `../ideas/` (parked ideas, any topic) and `../reference/` (durable facts from conversation). Write there when asked to park something; open a file only when the human names it. Nothing sweeps them. diff --git a/docs/context-economy.md b/docs/context-economy.md index fb548f7..53b99fb 100644 --- a/docs/context-economy.md +++ b/docs/context-economy.md @@ -49,7 +49,7 @@ Discovery by mechanism beats discovery by reading. Filtering inside the call is free. Filtering after it lands is impossible. -- `./scripts/verify.sh --quiet` — two lines on green instead of forty-three. The pre-commit hook uses +- `./scripts/verify.sh --quiet` — two lines on green instead of one per gate. The pre-commit hook uses it. Use the loud form when a gate fails or you are auditing the gates themselves. - Quiet and fail-fast flags by default: `-q`, `--porcelain`, `--short`, `--oneline`, `-failfast`, `--stat` before `-p`, and `2>/dev/null` for known noise. diff --git a/docs/conventions.md b/docs/conventions.md index e0f86c7..9f4c8fc 100644 --- a/docs/conventions.md +++ b/docs/conventions.md @@ -117,7 +117,7 @@ change is knowable only after committing it, now that currency is compared rathe removed, a wording fixed, a line they decided against — is amended into it while it is still unpushed. History records units of work, not the order in which someone noticed things. -**Authorship names who wrote the bytes, not who asked for them.** Three cases, no fourth: +**Authorship names who wrote the bytes, not who asked for them.** | Who wrote the change | `Author` | Trailer | |---|---|---|