@turri-dev/cli 0.1.3-next.2babf06 → 0.1.3-next.420ce7e

package/docs/authoring-plain.md

@@ -196,18 +196,21 @@ the reading that fits the rest of the spec, and marks each such decision in its
 code, environment and turri problems to the builds, and stops when a functionality keeps
 struggling after the spec was clarified, when two cycles change nothing, or after twenty.
 
-For an existing project, `bud` works the same way, scoped to one feature: intent → scope →
-product → review. After a short feature-intent interview it asks product questions one at a time -
-a trigger and its outcome, an edge case, a rule - and every answer is one spec change, a git diff
-written with `write_spec_diff` and built the moment it is written. A change to something already
+For an existing project, `bud` works the same way, scoped to one feature: intent → scope → product.
+It first asks how many questions the product phase may ask - light, medium, thorough or best
+judgement, as `brood` does - then a short feature-intent interview, then product questions - a
+trigger and its outcome, an edge case, a rule - and every answer is a spec change, a git diff
+written with `write_spec_diff` and built the moment it is written, before the next question. What
+the questions leave open it decides itself, a spec change each. A change to something already
 specified, built or still to build, is put to the user first and is a spec diff too: what is left to
-build is worked out again from the spec.
+build is worked out again from the spec. It ends on the person's confirmation of a short summary of
+the feature's changes.
 
 What keeps the interview honest is the harness, not the interviewer:
 
 - **Every question offers choices** (`ask_user` refuses a question without them), and each
   answer maps to one spec change.
-- **Every answer is written before the next question.** In `brood`'s product phase `ask_user` refuses
+- **Every answer is written before the next question.** In the product phase of `brood` and `bud`, `ask_user` refuses
   a new question until the last answer is a spec change - see [skills and gates](skills-and-gates.md).
 - **Each phase ends on the person's confirmation** of a short summary, not on the interviewer's word.
 

package/docs/config.md

@@ -122,7 +122,7 @@ models:                              # each agent role's model, thinking and tur
 | key | what it sets | left out |
 | --- | --- | --- |
 | `module` | the `.plain` file `turri regenerate` and the chat's `regenerate` build when none is named, from the project root | a file has to be named |
-| `harness-model` | the model `turri` starts on - the one you talk to - the one that diagnoses a job that failed for good, and, in the conversation, the planner that cuts the work into jobs (on whatever model the chat is on when it plans); under `turri regenerate`, the planner too | pi's configured model |
+| `harness-model` | the model `turri` starts on - the one you talk to - and, in the conversation, the planner that cuts the work into jobs (on whatever model the chat is on when it plans); under `turri regenerate`, the planner too | pi's configured model |
 | `coding-model` | every render: functionalities, spec diffs, conformance tests, repairs, planning spec diffs, the explorer | `harness-model` |
 | `judge-model` | the judge and the test review of a conformance run | `coding-model` |
 | `conformance-tests` | `all` (or `true`): conformance tests for every functional spec of every module with test reqs, written once each module's code is built, before anything is built on it. `chosen`: for the functional specs chosen - every one with acceptance tests, and those the chooser picks as each code pulse ends, from what that pulse regenerated. `module`: the same, but the chooser is asked once, when the whole module is regenerated, and plans the conformance pulses too. Under both, the choice is made inside the pulse, before anything is built on the module, and the pulse's report says what was chosen and why; those the person asks for with `conform` are written too; once chosen, a functional spec keeps them, and they are rewritten when it changes - see [who chooses, and when](regenerating.md#conformance-tests-in-the-work-loop). `false`: none written, and none of the existing ones run - until the conversation asks with `conform` | `false` |
@@ -158,7 +158,8 @@ wrong type, as if it were not there. `model:`, from before there were separate m
 | --- | --- |
 | `default` | every role not named below - but the conversation's side |
 | `chat` | `turri`'s model - the same as `harness-model`, which it wins over |
-| `chooser`, `planner`, `diagnosis` | the conversation's side: the conformance chooser of `turri regenerate`, the planner's agents, the diagnosis of a failed job. Unnamed, the chat's model |
+| `chooser`, `planner` | the conversation's side: the conformance chooser of `turri regenerate`, the planner's agents. Unnamed, the chat's model |
+| `diagnosis` | the diagnosis of a job that failed for good: why it did not land, and what to do. Unnamed, the coding model the job ran on, thinking medium |
 | `release` | `turri release`'s agent and release-after-pulse's: it follows steps - a script, a start command - so it runs on the coding model, thinking low |
 | `coding` | the coding agent, the code fixer of a conformance run and the repair agent - the same as `coding-model`, which it wins over. `--model` on the command line, or a model chosen in the conversation (`engine`), wins over both |
 | `conformance` | the conformance agent |

package/docs/headless.md

@@ -81,7 +81,7 @@ Useful options - `turri regenerate --help` lists all of them:
 
 | | |
 | --- | --- |
-| `--harness-model <provider/id>` | `harness-model`: the planner, the conformance chooser, the diagnosis of a failed pulse |
+| `--harness-model <provider/id>` | `harness-model`: the planner and the conformance chooser |
 | `--coding-model <provider/id>` | `coding-model` (`--model` too): the agents that build - with `:level` for how hard it thinks (`provider/id:high`); not given, the harness model's |
 | `--judge-model <provider/id>` | `judge-model`: the judge and the test review; not given, the coding model |
 | `--conformance-tests <all\|chosen\|module\|false>` | `conformance-tests`, with its values (`true` is `all`) |
@@ -151,7 +151,7 @@ changes meaning or goes; new fields may appear in the same version. Paths in `pu
   "conformance_tests": "all",                                                       // all | chosen | module | false
   "review": false,
   "models": {
-    "harness": { "model": "…", "thinking": "medium" },  // the planner, the chooser, the diagnosis
+    "harness": { "model": "…", "thinking": "medium" },  // the planner, the chooser
     "coding":  { "model": "…", "thinking": "low" },
     "judge":   { "model": "…", "thinking": "medium" },
     "observed": { "coding": ["provider/id:low"], "planner": ["provider/id:medium"] }  // what each role really ran on

package/docs/regenerating.md

@@ -112,6 +112,10 @@ the planner's, the spec-steps agent's, the conformance agents' - is laid out in
 A module that `requires` another inherits its functional specs; one that `import`s another
 inherits its definitions, implementation reqs and test reqs.
 
+An import module - one a `.plain` file imports, or one kept in a `template/` folder - is no codebase of its own. A
+change to it is built in the modules that import it, through any import modules between, whose code is started; when
+none is, nothing is built, and the change goes in with the first of them built.
+
 Template search order: the plain file's own directory, then a sibling `template/`, then
 `--template-dir`, then `PLAIN_TEMPLATE_DIRS`.
 
@@ -160,6 +164,10 @@ runs the unit testing script itself**, and only that run counts (see
   tried. An agent circles a cause it has not thought of - an in-memory database every connection opens
   empty, a test runner that leaves the code off its path - and this is the way out. The rounds go on as
   before, up to 20; should the same failure come round three times again, the debugger looks again.
+  **A run the time limit stopped** is looked at by the debugger at once, told how long the run had and that the limit
+  stopped it: it finds what hangs - the root cause and the fix, as above - or that nothing does, the run getting on up
+  to the limit and needing more time than a test run may take. Then the pulse stops, rolled back and not retried, and
+  the person is told to raise `TURRI_COMMAND_TIMEOUT` or make the suite faster.
 - **It goes round in circles in its own runs.** An agent stuck on a failure can try the same few changes in
   turn - three signatures of a stand-in function, say - and run the tests after each, dozens of times in one
   turn. Its own `run_unit_tests` runs are watched (`createLoopWatch` in `test-scripts.ts`): the code folder back
@@ -262,7 +270,8 @@ Passing unit tests prove only what they check, and a coding agent is quick to wr
 next to nothing - that a function exists, that a result is not empty, that a status is 200 - or code
 that no test reaches. So, with `review: true` in the [config](config.md), once the unit testing script
 passes a reviewer on the judge model reads what the work wrote, beside the spec, and changes nothing. It
-reviews both halves. The review is off by default - `review: false`, or the key left out - and so is the
+reviews both halves, with the unit testing script word for word in its prompt: a test the script never reaches is
+not run, and checks nothing. The review is off by default - `review: false`, or the key left out - and so is the
 conformance tests' review: the work goes on once its tests pass.
 
 - **The code.** Every behaviour, edge case, validation rule and error the spec states for this work
@@ -499,8 +508,9 @@ testing script, stops before it starts and says which skill adds it.
 `prepare-environment-script:` in the config, else the one `prepare_environment*.sh` at the root, else in
 `test_scripts/` - on the build, before every run of the conformance testing script: the harness's own, and the agents'
 `run_conformance_tests`. Both get the same build folder - the code in place, or the same fresh copy - so what it sets up
-for that build, the conformance testing script finds. With conformance off it is not run. The conformance agents are
-shown it, before the conformance testing script.
+for that build, the conformance testing script finds. With conformance off it is not run. Every agent shown the
+conformance testing script - the explorer, the conformance agent, the judge, the code fixer and the repair agent - is
+shown it too, before the conformance testing script.
 
 **Where they run.** On this machine, as you would run them: unfenced - no sandbox, no command check, no audit - in
 your own environment with this machine's toolchains, turri's model providers' API keys alone left out. They are yours,
@@ -577,10 +587,20 @@ not an install:
 > **lunch stopped: turri's sandbox kept its agents from reading `…/mise/installs/node/24.16.0/lib/node_modules/npm/bin/npm-cli.js` - it is on this machine; nothing is missing.**
 > To fix: let the agents read that toolchain - add its folder to `toolchains:` in config.turri.yaml, keeping what is there: `toolchains: [/Users/…/mise/installs/node/24.16.0]`. Nothing needs installing.
 
+A write the sandbox refused is told apart from a read - a report naming a lock file (`*.lock`, `*.lck`, `lockfile`, even
+one never made), or saying a write, a create or a lock not taken. No setting lets the agents write outside their
+module's folders, their own home and temporary folder and the package caches, and `toolchains:` only lets them read; so
+the stop names the lock and what fixes it instead. In your home - a tool that found it without `$HOME`, as a JVM does for
+`user.home` - it is having the tool use `$HOME` (`-Duser.home=$HOME` where the build starts its JVM); in a toolchain's own
+install, it is a setting of the tool's that keeps the write elsewhere, or a copy of the toolchain that keeps its writes in
+its cache. The agents are told such a refusal is the sandbox's, to report at once - not to work around it for half an
+hour.
+
 **The conversation heals it.** Told of the stop, it never regenerates the module again before the cause is fixed - a pulse
 stopped on its environment stops the same way again - and fixes what it can:
 
-- **hidden by the sandbox**: it adds the folder to `toolchains:` itself, says so in a line, and resumes;
+- **hidden by the sandbox**: it adds the folder to `toolchains:` itself, says so in a line, and resumes - a refused
+  write, which no setting fixes, it fixes in the project's own files when it can, and otherwise tells you what to do;
 - **a toolchain or a tool missing** - a JDK, Maven, Go, uv: it looks first for one installed off the PATH - Homebrew's opt
   folders, `/Library/Java/JavaVirtualMachines`, mise, asdf, sdkman, nvm - then asks you, with the exact command for this
   machine (`brew install openjdk@21`, `mise use -g java@21`), and on your yes runs it in its shell, checks the command is
@@ -822,7 +842,8 @@ coding agent that fixes the code is told the same of the tests: it can read them
 Before the test author starts, an explorer - an agent in
 the code's folder with the file tools alone: it reads the code, runs nothing and changes nothing - hands over everything
 the author needs, in parts: how to build and run it; how the conformance tests reach it as the project's
-conformance testing script runs them - the explorer is given the script, and says what it builds or
+conformance testing script runs them - the explorer is given the script, and the prepare script before it where there
+is one, and says what they build or
 installs and what the tests depend on or start (a package, a module, an entry point, by its exact name);
 how each functionality is reached from outside
 (the command, or the route, method and the request and response fields); what it needs around it; and
@@ -896,10 +917,17 @@ agent is told that a failure of the software itself - it does not build or start
 spec says it must not - is not the tests' to work around. When it fails, a judge - an agent that reads
 the code and the tests, changes neither, and holds both to the spec - decides which is wrong. It has the
 file tools and the web (`web_search`, `web_fetch`), to look up what a service the code calls answers - no shell: it
-judges from the code, the tests, the spec and the failing run's output, and its file tools write nothing:
+judges from the code, the tests, the spec, the conformance testing script word for word and the failing run's output,
+and its file tools write nothing. The explorer's account of how the code is invoked is in its prompt too, marked as
+written before the run and possibly wrong: the judge checks what it uses of it against the script and the files, and
+gives in `evidence` what it found itself. The script is fixed - neither agent can change it - so it is never the
+culprit: what it does with the tests, the tests fit; what it needs of the build, the code provides.
 
 - **the code:** the coding agent - in the code's folder, reading the tests but never changing them - fixes it,
-  and keeps its unit tests passing;
+  and keeps its unit tests passing. The judge quotes the spec's own words the code does not meet, or the testing
+  script's for what it needs of the build (`script_needs`: a build output, an entry point, a module) - each checked
+  by the harness against the text it quotes. The acceptance tests are in that text, labelled as their tests are:
+  for a spec change, those of every functional spec it touches, not only the last one's;
 - **the tests:** the conformance agent corrects them to what the spec says;
 - **the spec:** two functional specs cannot both hold, whatever the code does;
 - **the environment:** neither the code nor the tests can fix it - only the person can, in what the run is given:
@@ -941,16 +969,41 @@ spending the rest of its 20 attempts on it. Two failures are the same once what
 taken out of their lines - numbers, times, paths, colour codes, and the ids a service makes up for each
 response, a UUID or a correlation id. Nothing changes either when the agent sent to fix the code or the tests
 changes no file: two such fixes in a row, and the run stops. The conformance agent has the testing script in its prompt,
-and is told to fit the tests' own build to it.
+and is told to fit the tests' own build to it. The code fixer has the testing scripts its fixes are run by - the
+conformance testing script, the prepare script before it, and the unit testing script - word for word in its task:
+what the conformance testing script needs of the build, it reads there, not only in the judge's quote of it.
+
+**Escalation.** A failure judged the tests' goes to the conformance agent first: it owns the tests. When the run then
+fails the same way - the fix changed nothing, or nothing that mattered - the judge is asked again, now whether the
+failure belongs to the code rather than the tests: the run failing on something the code is meant to produce (a build
+output, an entry point, a module the testing script needs), or the tests running and the behaviour itself being
+wrong. Its verdict, either way, has to rest on evidence it gathered: each piece from a file it opened (the harness
+keeps track of what it read, listed and searched), the testing script or the failing run - and not the run alone.
+A verdict without it is sent back; a verdict of code still without it is taken as the tests'. Judged the tests'
+again, the failure stays with the conformance agent, and a fix that changes nothing counts towards stopping as
+before. Judged the code's, it is escalated to the coding agent, handed the script's error, the conformance tests as
+they stand and the judge's reason and evidence (`the script runs dist/cli.js; the build emits dist/src/cli.js`). Its
+fix has to build and pass the unit tests, then the suite runs again. Should the run still fail the same way - or the
+fix change nothing - the run stops there, with the judge's reasoning and evidence in what the person is told. Each of
+these runs is one of the run's 20 attempts, so a failure neither agent can fix stops in three of them.
 
 Every attempt is written into the working notes' pitfalls by the harness as cause and effect - what
 the run failed with, how it was judged, and which files the agent sent to fix it changed; the next
 attempt's line says what came of it - and each judge reads them first, so it does not send a
 failure the way that already failed. A run that does not pass is undone whole, its notes with it.
 
-Then the suite runs again. A run stopped by its time limit goes back to the conformance agent without a judge: the
-tests' environment is its. So does a run that exits 80 - the tests pass and only their static checks do not (see
-[the static checks](#the-static-checks)): the findings are the tests'. A run whose script cannot find its
+Then the suite runs again. A run that exits 80 goes back to the conformance agent without a judge - the tests pass and
+only their static checks do not (see [the static checks](#the-static-checks)): the findings are the tests'.
+
+**Timing.** Every run is shown to the judge, the debugger and whoever fixes it with how long it ran against its time
+limit (`runTiming` in `test-scripts.ts`): `This run ended on its own - exit 1, after 37.2s of the 120.0s a test run
+may take`, or `The time limit stopped this run: it had run 120.0s of the 120.0s ...` - so none takes a run that
+ended on its own for one the limit stopped, or the other way. A run the time limit stopped is judged like any other,
+and the judge is told what keeps a run from finishing: the code hangs (it waits on input, keeps a server in the
+foreground, never exits) - the code's; a test waits for what never comes - the tests'; or nothing hangs, the output
+showing the run getting on up to the limit, and it needs more time than a test run may take - the environment. That
+verdict stops the pulse at once, rolled back and not retried, and the person is told to raise `TURRI_COMMAND_TIMEOUT`
+or make the suite faster - no agent can give a run more time. A run whose script cannot find its
 toolchain stops the pulse instead - see [when the environment lacks something](#when-the-environment-lacks-something).
 Unit tests failing after the suite passes go to the coding agent. It goes round up to 20 times; still failing, the work is undone.
 
@@ -1024,8 +1077,7 @@ both. Each set goes where its folder goes - copied up the chain, committed, roll
 | --- | --- |
 | Where things are | entry points, layout, where each functionality lives |
 | How to build, run and test | the commands that work, what had to be installed |
-| Assumptions | what an agent assumed where the spec is silent - a format, a default, a choice it leaves open |
-| Spec gaps | what the spec should say and does not - a behaviour the person would want to decide, as the question it leaves |
+| Assumptions | what an agent assumed where the spec is silent - a format, a default, a choice it leaves open - and the tests that assert it, when any do; one no test asserts is written down all the same |
 | Pitfalls | what went wrong and what fixed it - and what the debugger found, filed by turri itself |
 | Pulses | written by turri alone, as each pulse ends: the last ten, a line each |
 
@@ -1042,9 +1094,14 @@ it landed, a commit of its own (`pulse 3 rolled back: …`) when it did not - so
 commit, keeps it. `update_notes` refuses the section. What the debugger finds is filed in the pitfalls the moment it
 finds it, not left to the coding agent to write down.
 
-The spec gaps a pulse's agents add are said in its report - "Spec gaps its agents met ... Put each to the user" - so
-the conversation asks you, and writes the ones you decide into the spec; the gaps stay in the notes, for the agents
-after, until then.
+A spec gap - what the spec should say and does not, a behaviour you would want to decide - is not a note: the notes
+are the next agent's, and a gap is yours. An agent reports one with `report_spec_gap`, giving the question it leaves
+and the assumption it made meanwhile; turri writes that assumption into the notes' assumptions, so the code built on
+it is known for what it is. The gaps a pulse's agents report are said in its report - "Spec gaps its agents met ... Put
+each to the user", each with its assumption - so the conversation asks you, and writes the ones you decide into the
+spec; the pulse that builds the answer finds the assumption it replaces in the notes, and the tests it names. However many gaps a pulse's agents report, they
+are put to you - never a reason to stop the pulse; the tool is guarded like any other. A notes
+file from before keeps no spec gaps section: its lines are dropped as it is read.
 
 Stubborn on the specs, flexible on the assumptions: the spec is never an assumption and never
 copied into the notes, and where the two disagree the spec wins. An agent builds on the assumptions
@@ -1067,8 +1124,8 @@ Leaving notes is required, and only through the `update_notes` tool. The file to
 notes file, and a change made to it any other way - from the shell, by a script - is undone. An agent
 that finishes without calling `update_notes` is asked again, up to three times; if it still has not,
 the activity log says so. The turn that asks is for the notes alone: the work is done - its testing script's run
-passed, and the agent is told so first, so its notes speak of work that succeeded - so every tool but `update_notes` is
-refused, and an agent that keeps calling them has its turn stopped. What
+passed, and the agent is told so first, so its notes speak of work that succeeded - so every tool but `update_notes` and
+`report_spec_gap` is refused, and an agent that keeps calling the refused ones has its turn stopped. What
 landed is what the harness checked; nothing changes after it. Only work that lands is asked: a job whose code or tests do not pass - or whose
 testing script cannot run - is rolled back, notes and all, so its agent is not asked to leave any.
 

package/docs/skills-and-gates.md

@@ -52,7 +52,7 @@ last one - one answer, one change, as an interview writes them. `spawn` is unpac
 each change to write the next at once, not to carry on with an interview it does not have.
 
 `questioning:` under `metadata:` names the steps the questioning level caps (`src/questioning.ts`) - `brood`'s
-`[stack, product]`. When there are any and someone to ask, the harness itself asks the first question of the first
+`[stack, product]`, `bud`'s `[product]`. When there are any and someone to ask, the harness itself asks the first question of the first
 step: how many questions those steps may ask - light (3), medium (5), thorough (10) or best judgement - and tells the
 agent the answer beside each step's instructions, with how broad each question is to be: broad at light, a whole area
 at once, narrow at thorough, an edge case at a time. Every level covers the same ground, in less or more depth. In a
@@ -63,7 +63,7 @@ questions each step has asked, are kept in the run's `run.json`, so a resumed ru
 or a run with nobody to ask, is not capped.
 
 `spec-diff-per-answer:` under `metadata:` names the steps where every answer is a spec change - `brood`'s
-`[product]`, at every questioning level. There `ask_user` refuses the next question until the last answer is written
+and `bud`'s `[product]`, at every questioning level. There `ask_user` refuses the next question until the last answer is written
 with `write_spec_diff` (a confirmation, or a question dismissed, owes nothing), and `write_spec_diff` no longer waits
 for an answer before a change: the agent writes as many as the step needs, those it decides itself included. The
 level limits the questions, never the spec changes.

package/docs/using.md

@@ -127,11 +127,11 @@ come waits for a free slot, and says so.
   as GitHub names a hunk's function: each section is named once.
 - **The side panel** (`ctrl+h`, as it was left - but on the pulse that last failed, stopped or did not pass, when one has
   since it was last opened: the live panel that showed it is gone with the last pulse, and its announcement in the chat
-  says `ctrl+h shows this pulse`; **`/regen`** on regen, **`/pulses`** on the pulses; not `ctrl+j`, which a terminal without the Kitty
+  says `ctrl+h shows this pulse`; **`/pulses`** on the pulses; not `ctrl+j`, which a terminal without the Kitty
   keyboard protocol sends as a line feed, the same as `shift+enter`, and which a dialog takes for
   `enter`; both stay pi's new-line keys. `ctrl+h` is the byte old terminals sent for backspace; a
   terminal set to send `^H` for its Backspace key would open the panel on it) takes the whole screen - the panel or the chat, one at a time -
-  or, `s`, sits beside the chat: the chat on the left, the panel in the right 45% of the screen, and `s` again
+  or, `s`, sits beside the chat: the chat on the left, the panel in the right half of the screen, and `s` again
   over the whole screen. It opens as it was last left, for the conversation; a terminal under 100 columns has
   no room for both and shows the panel over the whole screen.
   It opens on **regen**: the spec itself, in full, with how much of it the code has been regenerated from drawn
@@ -218,7 +218,9 @@ come waits for a free slot, and says so.
   said and did is not shown - it is in each pulse's log (see [Agent logs](#agent-logs)).
 
   `ctrl+h` again, or `esc`, closes it and goes back to the chat. Beside the chat, a click decides which side has
-  the keys - the chat or the panel, the one clicked - and `esc` gives the chat the keys too, the panel staying and
+  the keys - the chat or the panel, the one clicked, or the one `⌥⌘←` / `⌥⌘→` points at (on a
+  terminal that passes ⌘ on, over the Kitty keyboard protocol - Ghostty, kitty, WezTerm, iTerm2; not Apple's Terminal);
+  the other is drawn faint - and `esc` gives the chat the keys too, the panel staying and
   following the pulses; `ctrl+h` gives the panel the keys again, and from the panel closes it. (pi's regular screen,
   `--tui-mode regular`, reads no mouse: there it is the keys alone.)
   While the panel has the keys, every key is the panel's,

package/genome/skills/bud/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: bud
 description: >-
-  Add a feature to an existing ***plain project the way `brood` builds one: a short
-  feature-intent interview, then product questions one at a time - a trigger and its outcome, an
-  edge case, a rule - where every answer becomes one spec change, written as a git diff of the
+  Add a feature to an existing ***plain project the way `brood` builds one: it first asks how many
+  questions the product phase may ask - light, medium, thorough or best judgement, broader with
+  fewer - then a short feature-intent interview, then product questions - a trigger and its outcome,
+  an edge case, a rule - where every answer becomes a spec change, written as a git diff of the
   .plain files and built the moment it is written, so the feature appears while the interview is
-  still going. A change that touches what is already specified or being built is a spec diff too: what
+  still going. What the questions leave open it decides itself, each decision a spec change of its
+  own. A change that touches what is already specified or being built is a spec diff too: what
   is left to build is worked out again from the spec. Use when the user wants to add a
   feature to an existing project. Not for starting a new project (use `brood`, or `spawn`
   to start fast) or for editing generated code (the .plain specs are the source of truth).
@@ -16,7 +18,12 @@ metadata:
     intent: "what the feature is for, who it serves, and what it leaves out"
     scope: "finds where the feature goes in the spec, and what is built already"
     product: "the feature, question by question - each answer starts a regenerate pulse"
-    review: "checks the changed spec holds together, then hands over"
+  # The phase the questioning level caps, asked by the harness as the first question: light 3,
+  # medium 5, thorough 10, best judgement as many as turri judges the phase needs.
+  questioning: [product]
+  # Every answer in the product phase is a spec change: the next question waits until it is
+  # written with write_spec_diff. Changes turri decides itself need no answer before them.
+  spec-diff-per-answer: [product]
 ---
 
 # Bud
@@ -37,10 +44,36 @@ the spec."
 This is `brood`'s product phase, scoped to one feature, on top of what is there: the stack,
 the testing setup and every earlier feature are settled - read them, build on them, restart none.
 
+## How many questions
+
+The first question of the intent phase is the harness's own, not yours: how many questions the
+**product** phase may ask. The level sets how many questions there are and so how broad each is -
+never what they cover:
+
+| level | product questions | each question |
+| --- | --- | --- |
+| light | at most 3 | broad: the whole feature at once - what it does end to end, its main rules - with what fits the brief proposed, for the person to confirm or correct |
+| medium | at most 5 | one part of the feature, with its main rules |
+| thorough | at most 10 | narrow: one trigger, rule or edge case, with follow-ups on the ones that matter |
+| best judgement | as many as you judge the feature needs | as broad or as narrow as each part needs |
+
+The intent phase is not capped. Follow-ups count; the closing confirmation - asked with
+`confirms_phase: true` - does not. Past the cap `ask_user` refuses the question. To stop sooner, or
+under best judgement once the feature is settled enough to build, call `end_questions`.
+
+The level limits the questions, never the spec changes. **Every answer is a spec change**, whatever
+the level: written with `write_spec_diff` and built at once, before the next question - `ask_user`
+refuses the next one until it is. A broad answer that covers several behaviours is several changes,
+and you write them all. What the questions leave open - the details of a light answer, what is left
+once they are over - is yours to decide, as a careful engineer would, in the light of the brief: each
+decision a spec change of its own, written with `write_spec_diff` with no answer needed before it,
+and said in one line. The closing summary names every decision you made yourself, so the
+confirmation is where the person can change it.
+
 ## Question style
 
-- Ask with `ask_user`, one question per call, and pass `options` so the user picks rather than
-  types - concrete choices, plus the free-form catch-all the tool adds. Reserve `free_form: true`
+- Ask with `ask_user`, one question per call, as broad as the level says, and pass `options` so
+  the user picks rather than types - concrete choices, plus the free-form catch-all the tool adds. Reserve `free_form: true`
   for a genuinely open question.
 - Ask about the product - a trigger and its outcome, an edge case, a rule, a permission, a step of
   a flow - never about a spec section ("which concepts?", "what reqs?"). Let the answer decide which
@@ -55,6 +88,9 @@ the testing setup and every earlier feature are settled - read them, build on th
 
 ### intent
 
+The harness has asked how many questions the product phase may ask before this phase starts; its
+note beside these instructions gives the answer. Do not ask it again.
+
 Read `references/intent.md` and ask its five core questions one at a time with `ask_user`. Ask at
 most one focused follow-up when an answer is too vague to summarize. If what the user has already
 said answers a question, confirm it in one line instead of asking.
@@ -81,8 +117,8 @@ Say in one line where the feature goes, and move on. Write nothing to disk.
 
 ### product
 
-The feature, walked question by question. Run this loop until the user says the feature is fully
-covered:
+The feature, walked question by question. Run this loop while the questioning level allows (see
+"How many questions"):
 
 1. **Ask** one product question with `ask_user`.
 2. The user **answers**.
@@ -106,14 +142,17 @@ covered:
    Write it as a git diff: `diff --git a/<file> b/<file>`, `--- a/<file>`, `+++ b/<file>`, then the
    hunks with a few lines of unchanged context, paths from the project root. A new functional spec
    goes where it belongs in build order - after what it builds on, usually at the end.
-4. **Write it with `write_spec_diff`.** It applies the diff and queues a render spec diff job for
-   it; with conformance on, its conformance tests follow it. Say in one line what went into the
-   spec - "added `:Note:` and functional spec 7" - and what became of the build, as the tool says,
-   then ask the next question. Never wait for a build, and never ask the user to approve a change.
-
-**One answer, one change.** A follow-up about the same behavior - an edge case, a validation rule -
-is its own answer and its own change. An answer that describes two behaviors is two: write the
-first, then ask about the second. A change never carries anything the user was not asked about.
+4. **Write it with `write_spec_diff` at once**, before anything else. It applies the diff and starts
+   a render spec diff job for it; with conformance on, its conformance tests follow it. An answer
+   that covers several behaviours is a change for each: write them all. Then the changes for what
+   you decide yourself around it, if any. Say in one line what went into the spec - "added `:Note:`
+   and functional spec 7" - and what became of the build, as the tool says, then ask the next
+   question. Never wait for a build, and never ask the user to approve a change.
+
+**One answer, at least one change.** A follow-up about the same behaviour - an edge case, a
+validation rule - is its own answer and its own change. An answer that describes two behaviours is
+two changes, both written before the next question. A change never carries both an answer and
+something you decided: what you decide is a change of its own.
 
 **What already exists.** When an answer - or the conflict check - means changing something already
 specified: a definition, a req, a functional spec, built or still queued, the next question is
@@ -127,22 +166,14 @@ is taken out, one it touches renders the spec as it now is.
 **Fix your own mistakes in place.** When a later answer refines or contradicts a change you wrote in
 this feature, write the correction as its own diff with `fixes_earlier`, before the next question.
 
-When the loop reaches the end of what the brief covers, ask whether the feature is fully covered.
-Yes: go to the review. No: the next question.
-
-### review
-
-A short consistency pass over what the feature changed, then the handover.
-
-1. Read the modified `.plain` file(s) whole, and check: every new concept defined before use, with
-   no cycles; build order right end to end - no spec depends on one after it; functional specs
-   language-agnostic; every external interface explicit (paths, methods, arguments, formats);
-   acceptance tests consistent with their functional specs.
-2. Run `validate` on every module the feature touched.
-3. Fix what either finds with a spec diff and `fixes_earlier` - never by editing the file. Ask the
-   user only when a fix is a decision the brief and the answers do not settle.
-
-Walk `references/checklist.md` once, as a self-audit. Then hand over in a few lines: the feature's
-spec changes in order, the builds they queued and how they stand (`drift`), and that any
-further change is asked for in the conversation - each one a spec diff, and what is left to build is
-worked out again from the spec. The next feature starts again from the intent.
+Once the questions are over - the cap reached, or `end_questions` called - write what is left of
+the feature the same way: one decision of yours, one spec change, with no answer between. Then run
+`validate` on every module the feature touched, and fix what it finds with a spec diff and
+`fixes_earlier`.
+
+Finish by summarizing the feature's spec changes in build order, marking what you decided without
+asking, saying what is built and what is still queued (`drift`), and getting explicit confirmation
+with `confirms_phase: true`. The summary is for the person to take in at a glance - a line a change,
+each decision you made yourself in a few words, about fifteen lines at most, never the specs'
+wording. Any further change is asked for in the conversation, each one a spec diff; the next
+feature starts again from the intent.

package/genome/skills/bud/references/intent.md

@@ -3,6 +3,10 @@
 Extract the intent of this feature before choosing files or authoring specifications. Ask exactly
 five core questions, one at a time, and do not write to disk.
 
+The harness has already asked the first question of this phase: how many questions the product
+phase may ask - light (3), medium (5), thorough (10) or best judgement. Do not ask it again; this
+phase's own questions are not capped by it.
+
 ## Questions
 
 1. **Motivation** — What problem or limitation should this feature address?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.3-next.2babf06",
+  "version": "0.1.3-next.420ce7e",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -33,8 +33,8 @@
     "grammar:sync": "node scripts/sync-plyn-grammar.mjs"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "^1.1.0",
-    "@earendil-works/pi-tui": "^1.1.0",
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-tui": "^1.2.0",
     "@langchain/langgraph": "1.4.15",
     "gray-matter": "^4.0.3",
     "js-yaml": "^5.4.2",

package/genome/skills/bud/references/checklist.md

@@ -1,44 +0,0 @@
-# Bud Checklist
-
-Use this to verify the workflow was followed - never as a substitute for it. Walk it once in the
-review step, before the handover. A box counts only when the change is in the `.plain` files, not
-merely discussed; an unmet box is completed with a spec diff before finishing.
-
-## Intent
-
-- [ ] Asked the five core questions of `references/intent.md` one at a time - or confirmed in one
-  line what the user had already said - with at most one clarification for a vague answer.
-- [ ] Wrote nothing to disk before the brief was confirmed.
-- [ ] Summarized motivation, affected user, desired outcome, observable success criterion, and
-  boundary with explicit exclusions; got explicit confirmation.
-
-## Scope
-
-- [ ] Read the target `.plain` file(s) whole, with their `import` and `requires` chains, and the
-  config that says whether conformance tests are on.
-- [ ] Asked which module only when it was genuinely ambiguous.
-
-## Every product question
-
-- [ ] Asked exactly one question via `ask_user`, about the product - a trigger and outcome, an edge
-  case, a rule, a permission, a step of a flow - never about a spec section.
-- [ ] Turned the answer into exactly one spec change, across every section it needed, and wrote it
-  with `write_spec_diff` - never with `write` or `edit`.
-- [ ] Concepts defined in the same change as, or before, what first uses them; no cycles.
-- [ ] Every functional spec follows `add-functional-spec`'s rules, passed its complexity and
-  conflict checks, and sits in build order; one too big was split with the user.
-- [ ] Every change to something already specified - built or still queued - was put to the user
-  first (keep / augment / replace) and written as a diff with `fixes_earlier`.
-- [ ] Every correction of this feature's own changes was a diff with `fixes_earlier`, before the
-  next question.
-- [ ] `***test reqs***` and `***acceptance tests***` only with conformance tests on.
-- [ ] Asked whether the feature is fully covered before leaving the loop.
-
-## Review
-
-- [ ] Read the modified `.plain` file(s) whole and checked: concepts defined before use, no cycles,
-  build order right end to end, functional specs language-agnostic, every external interface
-  explicit, acceptance tests consistent with their functional specs.
-- [ ] Ran `validate` on every module touched, and fixed what it reported with spec diffs.
-- [ ] Handed over: the spec changes in order, the builds they queued and how they stand, and that
-  further changes are asked for in the conversation as spec diffs.