uncap the clarifying questions, and stop the harness asserting numbers
The cap was arbitrary and the wrong lever: what matters is that a question's answer changes the code, not how many such questions a request happens to carry. A request with six real forks now gets six, batched into one turn — splitting them to look brisk costs the human more than asking once. The instruction to ask is unchanged and still gated by "each with a default so silence answers". The rest is numbers the harness had no business holding. Three kinds, swept across every harness doc, and none of them wanted machinery. Restated values were the real fault: HARNESS.md carried the ceiling figures, which docs/README.md's single-source table says live in scripts/budgets.env and nowhere else. Prose repeating a value is a copy waiting to go stale, which is exactly the rule I was quoting at everything else. The ADRs keep old and new, as an append-only log should; the harness names the concept and points. Illustrative figures — how long verify.sh prints, surface.md against the source, how much the binary grew — drift every commit and carry no decision, so they now say "a line per gate", "an order of magnitude smaller", "roughly a third". Counts that restate their own list are the same fault in miniature: "the three gates people skip", "six commands", "three pieces of it are mechanical", "two sibling folders", "three cases, no fourth". Each is a number that goes wrong the day the list beneath it changes, and none of them was doing any work. Left alone deliberately: values with no other home — the ~50% overrun, the 72-character subject, 40 lines of stdlib over a dependency, toolchain versions. Those are the source, not a copy of one. No gate for this. It would have to guess which four-digit number is a budget rather than a year, an ADR, an HTTP status or a Go version, and a gate that fires on correct prose is a defect.
This commit is contained in:
@@ -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
|
||||
|
||||
+15
-25
@@ -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.
|
||||
|
||||
+1
-1
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
+1
-1
@@ -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 |
|
||||
|---|---|---|
|
||||
|
||||
Reference in New Issue
Block a user