@turri-dev/cli 0.1.3-next.f74e98a → 0.1.4-next.172be6f

package/docs/installation.md

@@ -40,6 +40,9 @@ on npm runs JavaScript compiled from them instead (`npm run build`, into `dist/`
 before they pack), as Node runs no `.ts` file inside a `node_modules`. `bin/turri.mjs` runs `src/` where there is one,
 and `dist/` otherwise.
 
+To update, `git pull` and `npm install` - the second picks up a dependency that changed, pi's say. `npm link` needs
+running only once. A **turri** already running keeps the code it started with: start it again to run what you pulled.
+
 ## In Docker
 
 `docker/Dockerfile` builds an image with Node, git, bash, bubblewrap and **turri** linked; the agents' commands and the

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`.
 
@@ -119,7 +123,21 @@ An agent that goes round in a circle - the same tool called with the same argume
 nothing in between, or a look (read, grep, find, ls) made again with nothing changed since, however
 many other looks came between, so the same answer comes back - is let through three times; the next
 such call is refused with what is happening, and past six its turn is stopped, and the harness goes on
-from there as after any turn. The arguments are compared whatever order they come in.
+from there as after any turn. The arguments are compared whatever order they come in. So too an agent whose
+calls to one tool fail ten times in a row, nothing going through - a call its arguments do not fit never reaches
+any guard on the tools.
+
+A turn turri stops itself - for any of these, or for its time, below - ends as any turn ends: what the agent said
+stands, `[the turn was stopped: ...]` after it, and the caller does what it does when the agent handed nothing over
+(the explorer's fallback, a nudge, a failed round). The abort that ended it is never taken for the provider
+failing; an abort turri did not make still is. Each stop is said as it happens - a notification in the chat, a
+line in a headless run - and listed in the run report's `turn_incidents`.
+
+A tool argument that is a list of objects - the explorer's `interfaces` and `plan`, a reviewer's `problems` - is
+what small models get wrong most. Before a call's arguments are checked, a list sent as JSON text, entries sent as
+JSON text, one object for the list, or a list written inside another argument's text
+(`...</tests_reach_it><plan>[...]</plan>`) are taken as the list; what still is not one is refused saying which
+argument, what was sent, each entry's fields and an example (`list-arguments.ts`).
 
 The agents with one thing to decide have a budget of tool calls: the judge 30, the test review and the
 explorer 40. Past it every tool but the one that hands the decision over refuses, telling it to decide
@@ -241,12 +259,18 @@ use each:
 - **`my_diff`**: the diff of the code folder from the commit the job started from, new files whole - exactly
   what the reviewer is shown. Read before handing the work in: every part of the change in it, and nothing else.
 - **`can_it_fail`**: whether the unit tests catch a bug. The agent gives one change to a code file - a
-  condition turned round, a value changed - and the unit testing script runs on a fresh copy of the code with
-  it; the code itself is never touched. If every test still passes, no test catches that bug. Six
+  condition turned round, a value changed - and the unit testing script runs with it. Where the testing scripts
+  run on a copy (`testing-scripts-run-on: copy`), the change is made to a fresh copy and the code itself is never
+  touched. In place, the default, it is made to the code itself, so a script that finds the code from its own path
+  sees it; the file is put back as it was once the run ends - passed, failed, hung, the script failing to start, the
+  script rewriting the file, turri exiting. Killed outright, the next unit of work starts from the last commit anyway.
+  It never runs beside another call of the agent's, so no edit lands while the bug is in. What the script does
+  beyond the code - a package copied into a host codebase - it does with the bug in, until the next test run puts the
+  real code there. If every test still passes, no test catches that bug. Six
   runs a job. A bug often makes the code hang instead - a loop that never ends - so a run may take three times
   as long as the last passing run of the unit tests, within 15 and 60 seconds, and one that does not finish is
-  reported as a hang, not as a test that caught it. Only where the testing scripts run on a copy
-  (`testing-scripts-run-on: copy`): in place, the default, there is no copy to change.
+  reported as a hang, not as a test that caught it. `mutation-testing: false` in the [config](config.md) - or
+  `turri regenerate --mutation-testing false` - takes it away, from the reviewer too.
 - **`start_service`**, **`service_logs`**, **`stop_service`**: a server or a worker it built, started in the
   background on this machine, behind the same walls as its shell - the command check, the module's environment, the
   OS sandbox, the audit while it comes up - to try from outside with `curl` as a client would. Whatever the stack: the
@@ -266,7 +290,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
@@ -375,6 +400,18 @@ halts its codebase: nothing more runs there until the spec changes or the module
 the command line, `turri regenerate` runs until nothing more can start, one line as each job starts and
 ends, and exits 1 when any failed.
 
+The person halts a module's planned work too: `halt` (and `/halt`) given a planned row - `planned-<module>-2`,
+`planned-<module>-waiting` - or the module's name. A module's pulses are planned again from its spec at every look, so
+one planned pulse cannot be taken out alone: the module is halted - its running pulse stopped and rolled back, none of
+its planned pulses started, the modules built on it waiting for it - and what landed stays. A halt the person asked for
+holds through spec changes - `write_spec_diff` brings the spec in without starting the module - until the module is
+asked for again (`regenerate`, `conform`). To build some of it later, or cut it differently, there is `steer`; to drop
+work, the spec.
+
+A module the loop looked after whose `.plain` file is gone is forgotten - no rows, nothing waited for - and a codebase
+left behind, or whose spec no longer parses, shows nothing planned: its plan, and what it waited for, were the spec's
+before.
+
 ### How the work is cut into jobs
 
 A job that renders the whole of a new spec is too big to build well, and a render per functional spec,
@@ -503,8 +540,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,
@@ -543,7 +581,8 @@ does not find them:
 testing-scripts-run-on: copy
 ```
 
-`can_it_fail` needs a copy to change, so an agent has it only where the scripts run on one.
+`can_it_fail` works either way: on a copy it changes the copy; in place it changes the code for the one run and puts
+it back.
 
 ### When the environment lacks something
 
@@ -700,7 +739,7 @@ with no agent and no testing script. Moving specs into a module the code was not
 change to the code brings that module's code in, so the codebase stops: it has to be started over - its code
 and conformance tests taken out, committed so its history keeps them, and the chain built again from the
 bottom. That is never done unasked. In the chat the model asks the person, saying why, and calls
-`regenerate` with `from_scratch` once they agree; `turri regenerate` and `spec-diff` ask at the terminal, and
+`regenerate` with `from_scratch: "module"` once they agree; `turri regenerate` and `spec-diff` ask at the terminal, and
 `--start-over` agrees in advance - with no terminal and no flag, the run stops there, exit 1, saying so.
 
 ## Conformance tests
@@ -836,7 +875,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
@@ -919,7 +959,8 @@ culprit: what it does with the tests, the tests fit; what it needs of the build,
 - **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. 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;
+  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:
@@ -961,7 +1002,9 @@ 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
@@ -1067,8 +1110,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 |
 
@@ -1085,9 +1127,16 @@ 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.
+A headless run has no one to ask: it prints each gap under its pulse, and lists them in its run report's
+`spec_gaps` ([running unattended](headless.md#the-run-report)). 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
@@ -1110,8 +1159,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.
@@ -133,7 +133,9 @@ change the step makes and puts its findings on the executor's next tool result.
 - **Interview the user.** `ask_user` puts one question to the person. In the TUI it is a dialog;
   from the CLI the options are numbered. Offering choices is required, not optional - a call with
   neither `options` nor `free_form: true` is refused - and every list carries "Something else…".
-  `multi_select: true` keeps offering what is left until they are done. The skill's agent talks in a
+  `multi_select: true` gives every option a box, ticked and unticked as it is chosen - a pick made by mistake is
+  undone by choosing it again - until they choose Done; what they type is one more box, ticked. "Something
+  else…", "Chat about this" and Done are no boxes. The skill's agent talks in a
   session of its own that the person never sees, so what the person must read to answer - the brief
   to confirm, the plan to approve - it passes as `ask_user`'s `context`, shown above the question in
   the dialog; `brood`, `spawn` and `bud` pass their briefs so. The agents are told to keep it to what can be taken in at

package/docs/using.md

@@ -50,7 +50,7 @@ where it stopped. A project can have skills of its own, in `.turri/skills/` or `
 
 | tool | |
 | --- | --- |
-| `regenerate` | regenerate a module and its chain from the spec as it is now - after any change to it, by any means: what is left to regenerate is planned into pulses of one to three functional specs, each with the definitions and reqs it uses, and a pulse regenerating what the spec no longer wants is stopped. With functionalities named, those are regenerated though their spec did not change - rewritten or started over, planned into pulses as any change is; with `from_scratch`, the whole module, its code deleted first - only when you ask, or agree |
+| `regenerate` | regenerate a module and its chain from the spec as it is now - after any change to it, by any means: what is left to regenerate is planned into pulses of one to three functional specs, each with the definitions and reqs it uses, and a pulse regenerating what the spec no longer wants is stopped. With functionalities named, those are regenerated though their spec did not change - rewritten or started over, planned into pulses as any change is; with `from_scratch`, the whole module, its code deleted first - `"chain"` for every module of its requires chain too, built again from the bottom - only when you ask, or agree |
 | `drift` | what is left to regenerate: how far the code and its conformance tests have drifted from the spec, starting nothing |
 | `glimpse` | the pulse a module's codebases would start next, and the whole prompt its coding agent would get - starting nothing |
 | `steer` | say how the work is planned - which functional specs go together, what first - for the project or one module, for the session; the next plan follows it, beside what AGENTS.md says under a heading naming the queue |
@@ -58,12 +58,12 @@ where it stopped. A project can have skills of its own, in `.turri/skills/` or `
 | `validate` | validate a spec, regenerating nothing |
 | `engine` | show or choose the model the code is regenerated on - see [below](#choosing-a-model) |
 | `pulses` | the pulses - running, planned and finished - or one of them |
-| `halt` | halt a pulse, or what `activate` started |
+| `halt` | halt a pulse, a module's planned pulses, or what `activate` started |
 | `diagnose` | why a pulse did not land, from its transcript: how it ended, the stages that went wrong, the last failing test run, the last review, the tool calls that failed |
 | `lineage` | a module's lineage: what each regeneration and conformance run changed in it, and what it was regenerated from |
 | `cultivate` | run a gated skill, its steps and review gates enforced |
 | `release`, `activate` | try what is regenerated: release it to `dist/<module>` and activate it on this machine, installing what it needs - see [deploy](deploy.md) |
-| `ask_user` | put a question to you as a dialog to pick from - several at once, "Something else…" to type, or "Chat about this" to talk it over first; Esc in either goes back to the options |
+| `ask_user` | put a question to you as a dialog to pick from - several at once, each a box you tick and untick, "Something else…" to type, or "Chat about this" to talk it over first; Esc in either goes back to the options |
 | `web_search`, `web_fetch` | search the web and read a page as text - documentation, an API, an error; `curl` and the like run in its `bash` |
 
 What each render does, in order, is in [regenerating the code](regenerating.md).
@@ -238,7 +238,7 @@ come waits for a free slot, and says so.
   is laid over `config.turri.yaml` - its testing scripts, toolchains, models - for the session; a pulse already
   running keeps the stack it started with. The chat model switches it too when you ask. See
   [stacks](config.md#stacks).
-- **`/regenerate [module | file.plain] [functionality ...] [from scratch] [how to cut the work]`** regenerates a module from its spec as it is now, as
+- **`/regenerate [module | file.plain] [functionality ...] [from scratch [whole chain]] [how to cut the work]`** regenerates a module from its spec as it is now, as
   the `regenerate` tool does: what is left to regenerate is planned into pulses - one functional spec at a time, a few
   together or the whole module in one, as the planner judges - and the first starts. Words after the module are
   guidance for that plan (`/regenerate app models first`). A module's name typed with spaces for its underscores is
@@ -246,13 +246,19 @@ come waits for a free slot, and says so.
   `config.turri.yaml` names, else the folder's top modules, to pick from. Asked for from scratch - `from scratch`,
   `start over`, `delete the module` - it asks first, then deletes the module's code and conformance tests in every
   codebase where they live, committed so `/lineage` keeps them, and regenerates the whole module from its spec,
-  built though nothing in it changed: `/regenerate shorty from scratch`. The chat's `regenerate` does the same with
-  `from_scratch`, when you ask for it; `turri regenerate --from-scratch` on the command line, not with `--dry-run`.
+  built though nothing in it changed: `/regenerate shorty from scratch`. The modules below it keep their code, and
+  the module starts again from a copy of the code below it. Asked for its chain too - `/regenerate shorty from scratch,
+  the whole chain` - the code of every module of its requires chain is deleted, the base's included, and the whole
+  chain is regenerated from the bottom: what to do after modules were split, merged or moved, when the code below was
+  laid out for modules that are no more. The chat's `regenerate` does the same with `from_scratch: "module"` or
+  `"chain"`, when you ask for it; `turri regenerate --from-scratch` or `--from-scratch-chain` on the command line, not
+  with `--dry-run`.
   Functionalities named after the module - `/regenerate shorty 3 5` - are regenerated though their spec did not
   change, on the model chosen for functionalities: as `turri regenerate shorty.plain 3 5` does, and the chat's
   `regenerate` with `functionalities`.
-- **`/halt <id>`** halts a pulse - a queued one never starts - and **`/halt activated <name>`** halts a
-  server `activate` started; it lists both when no id is given.
+- **`/halt <id>`** halts a pulse - a queued one never starts - **`/halt <module>`** (or a planned row's id) halts a
+  module's planned pulses until you ask for it again, a spec change not starting it, and **`/halt activated <name>`**
+  halts a server `activate` started; it lists all three when no id is given.
 - **What these commands show you, the chat knows.** What `/regenerate` and `/halt activated` tell you - a spec that
   does not parse, the pulses planned, a server halted - stays in the chat under the command, and since a slash command
   runs outside the conversation, it is put in the conversation as well: say "fix it" next and turri knows what you are
@@ -389,7 +395,11 @@ To change pi's own default, in `~/.pi/agent/settings.json`:
 ```
 
 A provider failure - no credits, bad key, rate limit - is raised with the provider's own message,
-rather than surfacing as an agent that said nothing.
+rather than surfacing as an agent that said nothing. One that passes - overloaded, rate limited, unreachable,
+timed out - is waited out first, after pi's own retries: six more tries, the wait doubled each time from 15
+seconds up to five minutes (15s, 30s, 1m, 2m, 4m, 5m, a tenth either way so parallel jobs do not all come back
+at once), the agent carrying on where it was. Each wait is shown as it happens - a notification in the chat and
+the job panel's status, a yellow line in a headless run - and listed in the run report's `turn_incidents`.
 
 ## Module history
 
@@ -452,6 +462,7 @@ turri regenerate <file.plain>              # regenerate what the code is not bui
 turri glimpse <file.plain>             # plan it, and print the first job's prompt - starts nothing
 turri regenerate <file.plain> 2            # regenerate functionality 2 again, changed or not
 turri regenerate <file.plain> --from-scratch   # delete the module's code and tests (its lineage keeps them), regenerate all of it
+turri regenerate <file.plain> --from-scratch-chain   # the same for every module of its requires chain, from the bottom
 turri spec-diff <file.plain> <diff>    # apply a spec diff, and regenerate it
 turri conform <file.plain> 1           # black-box tests for functionality 1
 turri lineage <module>                 # what each regeneration changed in a module, and when

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/genome/skills/refactor-module/SKILL.md

@@ -21,6 +21,8 @@ allowed-tools: [read, write, edit, bash, ls, grep, find]
 
 The refactoring is purely structural. The **combined behavior** of the resulting modules must be **identical** to the original module. No functional spec is added, removed, or weakened. The split is semantic — grouping related specs together — not behavioral.
 
+The spec is structural; the code is not. Once modules are split and specs move between them, the code already built no longer matches the module layout: specs move into modules the code was never built on, and no change to that code brings them in. **After a refactor, the whole requires chain is regenerated from scratch** — the existing code and conformance tests are taken out (their lineage keeps them) and every module is built again from the base of the chain upward. Say so up front: it is part of what the user agrees to (Phase 2e), and it is the last step of the skill (Phase 5).
+
 ## Input
 
 The `.plain` file to refactor, plus guidance from the user on the desired grouping (or ask the user to confirm your proposed grouping).
@@ -90,8 +92,9 @@ Summarize for the user:
 - Any new import module being created
 - Which concepts are exported from each module
 - Confirmation that all original specs are accounted for (none lost)
+- That the whole chain will be **regenerated from scratch** once the split is done: the code and conformance tests built so far are taken out (kept in the lineage) and everything is built again from the base module up — this takes as long and costs as much as building the original module did
 
-Get explicit user confirmation before proceeding.
+Get explicit user confirmation before proceeding — of the split and of regenerating from scratch.
 
 ## Phase 3 — Execute the Split
 
@@ -162,6 +165,19 @@ For each new module:
 
 Read each new `.plain` file in full and present the final structure to the user for approval. If the user requests changes, apply them and re-verify.
 
+Validate each new module with `turri validate <module>.plain` (or the `validate` tool) before going on: a module that does not parse cannot be regenerated.
+
+## Phase 5 — Regenerate the Chain from Scratch
+
+The split moves specs between modules, so the code built from the original module cannot be patched into the new layout: the chain is regenerated from scratch. Do not try to keep or reuse the existing code, and do not regenerate only what looks changed — modules have moved, and a codebase built without a module it now requires has to be started over anyway.
+
+1. **Remind the user** what regenerating from scratch does — the code and conformance tests built so far are taken out, committed so the lineage keeps them, and the whole chain is built again from the base up — and that they already agreed to it in Phase 2e. Proceed only on that agreement.
+2. **Regenerate the tip of the chain from scratch, with its whole chain** — the last module, the one everything else is required by. From scratch for the tip alone is not enough: the modules below keep their code, and the tip starts from a copy of it, laid out for the old modules. With the whole chain, every module's code is taken out, the base's included, and the chain is built again from the bottom:
+   - in the chat: the `regenerate` tool on the tip's `.plain` file with `from_scratch: "chain"`, or `/regenerate <tip> from scratch, the whole chain`;
+   - on the command line: `turri regenerate <tip>.plain --from-scratch-chain`.
+3. **Modules that require the chain** (updated in 3d) are regenerated after it, from scratch too (`from_scratch: "module"`): the modules they require are not the ones their code was built on. When the tip's whole chain is regenerated, a module built on top of it is a chain of its own — regenerating it from scratch with its whole chain instead covers the tip's chain too, in one go.
+4. **The original module's codebase** (`plain_modules/<original-module>/`), when the original module was deleted or renamed, is no longer built from anything. Tell the user it is there; it is theirs to delete. Do not delete it unasked.
+
 ## Common Pitfalls
 
 ### Splitting too aggressively
@@ -179,9 +195,12 @@ This is a refactoring, not a rewrite. Spec text must be copied verbatim. If a sp
 ### Losing acceptance tests
 Acceptance tests are nested under their parent functional spec. When moving a spec to a new module, its acceptance tests must move with it.
 
+### Regenerating only what changed
+After a split the existing code was built for a module layout that no longer exists. Regenerating incrementally either stops at a codebase that has to be started over or builds on code laid out for the old modules. Regenerate the whole chain from scratch.
+
 ## Validation Checklist
 
-- [ ] User confirmed the split plan before execution
+- [ ] User confirmed the split plan before execution, including regenerating the whole chain from scratch
 - [ ] All original functional specs are present in exactly one new module — none lost
 - [ ] Spec text is identical to the original — no rewording
 - [ ] Acceptance tests moved with their parent specs
@@ -194,3 +213,6 @@ Acceptance tests are nested under their parent functional spec. When moving a sp
 - [ ] Original module removed or updated
 - [ ] Downstream modules (if any) updated to require the chain tip, plus any earlier chain modules whose exported concepts they reference
 - [ ] User approved the final result
+- [ ] Every new module validates
+- [ ] The tip of the chain regenerated from scratch with its whole chain, then any module that requires it
+- [ ] User told about the original module's leftover codebase, if there is one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.3-next.f74e98a",
+  "version": "0.1.4-next.172be6f",
   "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.