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:
Claude Opus 5
2026-08-02 00:56:41 +06:00
committed by bdeshi
parent b8c62d38fd
commit 25d7045133
5 changed files with 23 additions and 31 deletions
+5 -3
View File
@@ -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
View File
@@ -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
View File
@@ -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.
+1 -1
View File
@@ -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
View File
@@ -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 |
|---|---|---|