@turri-dev/cli 0.1.3-next.f74e98a → 0.1.4-next.073df25

package/dist/run-report.js

@@ -22,6 +22,9 @@ const emptyTotals = () => ({
     llm_calls: 0,
     agent_turns: 0,
     compactions: 0,
+    provider_retries: 0,
+    provider_stalls: 0,
+    turns_stopped: 0,
     model_seconds: 0,
 });
 function addUsage(totals, usage) {
@@ -43,8 +46,14 @@ function addEvent(totals, event, tokens) {
     }
     else if (event.kind === "turn")
         totals.agent_turns += 1;
-    else
+    else if (event.kind === "compaction")
         totals.compactions += 1;
+    else if (event.kind === "provider_retry")
+        totals.provider_retries += 1;
+    else if (event.kind === "provider_stall")
+        totals.provider_stalls += 1;
+    else
+        totals.turns_stopped += 1;
 }
 function sumTotals(a, b) {
     const sum = emptyTotals();
@@ -181,6 +190,32 @@ export function startRunReport(options) {
             list,
         };
     };
+    /** The spec gaps the pulses' agents met, in the order the pulses started: questions a person would want to decide. */
+    const specGapsOf = (jobs) => jobs.flatMap((job) => {
+        const details = job.details;
+        return (details?.specGaps ?? []).map((gap) => ({
+            module: job.module ?? null,
+            pulse: job.pulse ?? null,
+            pulse_id: job.id,
+            landed: job.status === "succeeded" && details?.landed === true,
+            question: gap.question,
+            assumption: gap.assumption,
+        }));
+    });
+    /** Each request the provider failed and was waited out or stalled on, and each turn turri ended itself: why, and where. */
+    const turnIncidentsOf = () => events
+        .filter((event) => event.kind === "provider_retry" || event.kind === "provider_stall" || event.kind === "stopped")
+        .map((event) => ({
+        kind: event.kind,
+        pulse_id: event.job ?? null,
+        role: event.role ?? null,
+        model: event.model ?? null,
+        ...(event.kind === "stopped"
+            ? { reason: event.reason ?? null }
+            : event.kind === "provider_stall"
+                ? { silent_seconds: Math.round((event.waitMs ?? 0) / 1000) }
+                : { error: event.error ?? null, attempt: event.attempt ?? null, of: event.of ?? null, wait_seconds: Math.round((event.waitMs ?? 0) / 100) / 10 }),
+    }));
     const functionalitiesOf = (counts) => {
         if (counts === undefined)
             return null;
@@ -228,6 +263,7 @@ export function startRunReport(options) {
             build_dir: options.buildDir !== undefined ? resolve(options.buildDir) : null,
             conformance_tests: options.conformanceTests,
             review: options.review ?? null,
+            mutation_testing: options.mutationTesting ?? null,
             models: {
                 ...Object.fromEntries(Object.entries(options.models).map(([role, choice]) => [role, { model: choice.model ?? null, thinking: choice.thinking ?? null }])),
                 observed: Object.fromEntries([...new Set(events.map((event) => event.role ?? "unknown"))].sort().map((role) => [role, [...new Set(events.filter((event) => (event.role ?? "unknown") === role).map((event) => event.model ?? "unknown"))].sort()])),
@@ -245,6 +281,8 @@ export function startRunReport(options) {
             usage: usageOf(jobs),
             pulses: pulsesOf(jobs, now),
             functionalities: functionalitiesOf(attempt(sources.completion)),
+            spec_gaps: specGapsOf(jobs),
+            turn_incidents: turnIncidentsOf(),
             ...(exitParts ?? {}),
             logs: {
                 jobs_dir: fromProject(join(projectRoot, ".turri", "jobs")),

package/dist/spec-tools.js

@@ -1,8 +1,8 @@
-import { readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, relative, resolve } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { IMPORT_DIRECTIVE, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata } from "./plain/parser.js";
+import { plainFileParser } from "./plain/parser.js";
+import { importingModules, isImportModule } from "./regenerate/requires.js";
 import { resolveTemplateDirs } from "./regenerate/paths.js";
 import { applySpecDiff, plainFilesOf, revertSpecDiff } from "./regenerate/regenerate.js";
 import { MissingFunctionalitiesError } from "./plain/errors.js";
@@ -62,24 +62,12 @@ export function createSpecDiffTools(options) {
             // file that cannot be parsed. A module with no functional specs yet is not broken. An import
             // module - definitions only, say - is not a module of its own: it is parsed as the modules
             // that import it read it, the one the change is built for among them.
-            const importers = (file) => {
-                const name = basename(file, ".plain");
-                const dir = dirname(resolve(cwd, file));
-                return readdirSync(dir)
-                    .filter((entry) => entry.endsWith(".plain"))
-                    .map((entry) => join(dir, entry))
-                    .filter((path) => {
-                    try {
-                        return (readPlainSourceMetadata(readFileSync(path, "utf8")).metadata[IMPORT_DIRECTIVE] ?? []).includes(name);
-                    }
-                    catch {
-                        return false;
-                    }
-                });
-            };
-            const imported = importedNames(resolveTemplateDirs(resolve(cwd, params.plain_file)));
             const toParse = [
-                ...new Set([params.plain_file, ...touched].flatMap((file) => imported.has(basename(file, ".plain")) ? importers(file).filter((path) => !imported.has(basename(path, ".plain"))) : [resolve(cwd, file)])),
+                ...new Set([params.plain_file, ...touched].flatMap((file) => {
+                    const path = resolve(cwd, file);
+                    const importing = isImportModule(path) ? importingModules(path) : [];
+                    return importing.length > 0 ? importing : [path];
+                })),
             ];
             for (const path of toParse) {
                 const file = relative(cwd, path);
@@ -100,7 +88,8 @@ export function createSpecDiffTools(options) {
             owed = false;
             liveReview?.notice(`${params.plain_file}, after the change to ${touched.join(", ")}`);
             // In the files, the change is work: the loop works out what is left to build and plans it.
-            const statuses = await loop.bringUp(params.plain_file, params.guidance !== undefined ? { guidance: params.guidance } : {});
+            // A spec change, not a request: a module the person halted stays halted.
+            const statuses = await loop.bringUp(params.plain_file, { specChange: true, ...(params.guidance !== undefined ? { guidance: params.guidance } : {}) });
             const lines = [
                 result === "applied" ? `Applied the change to ${touched.join(", ")}.` : `The change to ${touched.join(", ")} was already applied.`,
                 `Building in the background:\n${describeModules(statuses)}\n`,
@@ -129,27 +118,3 @@ export function createSpecDiffTools(options) {
         },
     };
 }
-/** The module names some .plain file in these folders imports: import modules, not codebases. */
-export function importedNames(dirs) {
-    const names = new Set();
-    for (const dir of dirs) {
-        let entries;
-        try {
-            entries = readdirSync(dir).filter((name) => name.endsWith(PLAIN_SOURCE_FILE_EXTENSION));
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            try {
-                const imports = readPlainSourceMetadata(readFileSync(join(dir, entry), "utf8")).metadata[IMPORT_DIRECTIVE];
-                for (const name of imports ?? [])
-                    names.add(name);
-            }
-            catch {
-                // A file that does not read imports nothing.
-            }
-        }
-    }
-    return names;
-}

package/docs/authoring-plain.md

@@ -158,13 +158,15 @@ an agent has to decide to go and read.
 | `import-modules.md`, `requires-modules.md` | the two ways modules build on each other |
 | `exported-concepts.md`, `required-concepts.md` | which concepts cross module boundaries |
 | `integrations.md` (+ standalone, embedded, embedded testing) | specs for REST API integrations, deployed standalone or embedded in an existing codebase |
+| `turri-regeneration.md` | turri's model of itself: a spec change regenerated as a spec diff, wherever it sits, in the chain's tip; what each kind of change sets off; what a coding agent sees; how bad code is fixed; where the cost is - so a spec is placed by what it means, never to spare regeneration |
 | `stdlib.md` | the standard library: when to import which template, and every template with what it is and where it is, read from `stdlib/` |
 
 The ones that shape a spec most:
 
 - **One functionality is at most ~200 lines of code.** A bigger one is split before it is written
   (`analyze-if-func-spec-too-complex`, `break-down-func-spec`).
-- **Functional specs are in build order.** Each is rendered on top of the ones before it.
+- **Functional specs are in build order.** Each is rendered on top of the ones before it - which is
+  what a spec may assume, not what a change costs: a spec inserted anywhere is regenerated alone.
 - **They state facts, with a concrete subject.** "A :User: can add a :Task:" - not "Implement
   adding tasks", not "The system should…".
 - **Nothing a test cannot check.** No `robust`, `seamless`, `as appropriate`; state the checkable
@@ -196,18 +198,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

@@ -84,7 +84,7 @@ runs:
 | --- | --- |
 | now | `harness-model` and `models.chat` - the conversation switches to it; `parallel-jobs` - a pulse waiting for a slot starts if there is one now; `allow-to-stop-jobs` |
 | your next message | `rules-off` - for the conversation; a skill's agents from the next skill run |
-| the next pulse - one running keeps what it started with | `coding-model`, `judge-model`, every other `models.<role>`, `review`, `turn-limit`, `compact-at`, `agent-env`, `toolchains` |
+| the next pulse - one running keeps what it started with | `coding-model`, `judge-model`, every other `models.<role>`, `review`, `mutation-testing`, `turn-limit`, `compact-at`, `agent-env`, `toolchains` |
 | the next time the work is planned | `conformance-tests`, `conformance-budget`, `max-specs-per-pulse`, `max-lines-per-pulse` |
 | the next test run - the running pulse's too | the testing scripts, `testing-scripts-run-on` |
 | the next pulse that lands - the running one too | `release-after-pulse` |
@@ -128,6 +128,7 @@ models:                              # each agent role's model, thinking and tur
 | `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` |
 | `conformance-budget` | under `conformance-tests: chosen` or `module`: how many of a module's functional specs may be chosen for conformance tests, beside those with acceptance tests - a count (`2`) or a share of its functional specs (`30%`, rounded up, at least one). Every choice for the module counts, whenever it was made; the chooser is told what is left, and can choose no more. Your own `conform` is not limited. A stack's `config.turri.<stack>.yaml` can set its own | no limit |
 | `review` | `true` or `false`: whether the code and its unit tests - and the conformance tests - are reviewed once they pass: two reviews at most, the second weighed by the arbiter; off, a job lands once its tests pass - see [regenerating the code](regenerating.md#the-code-and-its-unit-tests-are-reviewed) | `false` |
+| `mutation-testing` | `true` or `false`: whether the coding agent and the reviewer have `can_it_fail` - one change put in the code for one run of the unit testing script, to see that a test catches it; on a copy of the code, or in place and put back after the run (see [regenerating the code](regenerating.md#checking-its-own-work)). `turri regenerate --mutation-testing false` for one run | `true` |
 | `rules-off` | a list of rule names - `integrations`, `concise-specs`, the files of `genome/rules/` without `.md` - left out of the conversation's prompt and every spec-writing agent's: a rule this project's own skills or AGENTS.md replace, such as one that says to probe a live API before any spec is written. The project's alone | none |
 | `allow-to-stop-jobs` | `true` or `false`: whether turri stops a running job the spec has moved on from - a functional spec it regenerates changed, or a file one links was edited - rolls it back and regenerates the spec as it now is. `false`: the job runs to its end and lands, and what changed since is regenerated on top of it by the next job - see [regenerating the code](regenerating.md). Your own `halt` stops a job either way | `true` |
 | `release-after-pulse` | `true` or `false`: whether every pulse that lands code releases it, in the chat, as its last stage - before the module's next pulse starts, whatever the chat is doing: an agent on the coding model looks for the project's release guidance as the chat does (what was passed to `release` this conversation, AGENTS.md, the project's skills) and, when it says to release after a build, does what it says - see [deploy](deploy.md#after-every-pulse). One release a pulse that lands; a release that fails is said in the pulse's report, and what it landed stays | `false` |
@@ -142,7 +143,7 @@ models:                              # each agent role's model, thinking and tur
 | `toolchains` | folders of this machine an agent's commands may read beside the system's, the `PATH`'s and those the toolchain variables point at - a toolchain installed somewhere unusual (`[/srv/zig]`). A stack's add to the project's. See [the OS sandbox](sandbox.md#the-os-sandbox) | none |
 | `turn-limit` | seconds each turn of an agent a job starts has, for every role without its own (`models:`); `0` for none. The config is the only place it is set. A turn past it ends at its next request to the model - see [regenerating the code](regenerating.md) | 120 |
 | `models` | each agent role's own model, thinking and turn limit - see [models per role](#models-per-role) | every role on `coding-model`, the conversation's side on `harness-model` |
-| `testing-scripts-run-on` | what the testing scripts run on - always on this machine, in your environment. `in-place`: the real build and tests folders, the script at its own path, from the project - so a script that finds a host codebase from its own path finds it. `copy`: a fresh copy of the code, staged in `plain_modules/.turri/scripts/`, with the script copied beside it; it gives the coding agent `can_it_fail` (see [the testing scripts](regenerating.md#the-testing-scripts)) | `in-place` |
+| `testing-scripts-run-on` | what the testing scripts run on - always on this machine, in your environment. `in-place`: the real build and tests folders, the script at its own path, from the project - so a script that finds a host codebase from its own path finds it. `copy`: a fresh copy of the code, staged in `plain_modules/.turri/scripts/`, with the script copied beside it. `can_it_fail` works on either: on a copy it changes the copy, in place the code itself for the one run, put back after it (see [the testing scripts](regenerating.md#the-testing-scripts)) | `in-place` |
 
 Keys are written with dashes; underscores are read the same (`conformance_tests`). A key turri
 does not know is ignored - another tool's `config.yaml`, read while it is the old file, may carry several - and so is a value of the

package/docs/headless.md

@@ -86,7 +86,10 @@ Useful options - `turri regenerate --help` lists all of them:
 | `--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`) |
 | `--review <true\|false>` | `review`: whether the code and its tests are reviewed once they pass |
+| `--mutation-testing <true\|false>` | `mutation-testing`: whether the coding agent and the reviewer have `can_it_fail` |
 | `--stack <name>` | build with the stack's `config.turri.<name>.yaml` over `config.turri.yaml`; default, `TURRI_STACK`, else none |
+| `--from-scratch` | delete the module's code and conformance tests (its lineage keeps them) and regenerate all of it |
+| `--from-scratch-chain` | the same for every module of its requires chain, the base's included, built again from the bottom |
 | `--start-over` | start over, unasked, a codebase built without a module it now requires - without a terminal, a run that needs it and lacks it stops |
 | `--build-dir <dir>` | as the run ends, export the code there - see below |
 | `--report <file.json>` | write [the run report](#the-run-report) there |
@@ -104,7 +107,8 @@ Conformance tests follow `conformance-tests:` in `config.turri.yaml`, or `--conf
 The command exits `0` only when every module is complete: its code regenerated from the spec as it is
 now, and its conformance tests written for what is built when they are on - no pulse failed, nothing
 halted, nothing waiting for a start over. Anything else exits `1`, and the last lines say which
-module is not complete, and why. The log says, per functionality, what was built and whether its
+module is not complete, and why. A behaviour the spec leaves open that an agent had to decide is printed
+as a `spec gap` under its pulse, with what was decided meanwhile. The log says, per functionality, what was built and whether its
 tests passed.
 
 | | |
@@ -150,6 +154,7 @@ changes meaning or goes; new fields may appear in the same version. Paths in `pu
   "spec_file": "/work/app.plain", "project_dir": "/work", "build_dir": "/work/out",  // build_dir: null without one
   "conformance_tests": "all",                                                       // all | chosen | module | false
   "review": false,
+  "mutation_testing": true,
   "models": {
     "harness": { "model": "…", "thinking": "medium" },  // the planner, the chooser
     "coding":  { "model": "…", "thinking": "low" },
@@ -165,7 +170,7 @@ changes meaning or goes; new fields may appear in the same version. Paths in `pu
   "usage": {
     "total": {
       "input_tokens": 0, "output_tokens": 0, "cache_read_tokens": 0, "cache_write_tokens": 0, "cost_usd": 0,
-      "llm_calls": 0, "agent_turns": 0, "compactions": 0, "model_seconds": 0
+      "llm_calls": 0, "agent_turns": 0, "compactions": 0, "provider_retries": 0, "provider_stalls": 0, "turns_stopped": 0, "model_seconds": 0
     },
     "in_pulses": { },       // the pulses' usage added up - the same fields
     "outside_pulses": { },  // the planner, the conformance chooser, a failed pulse's diagnosis
@@ -191,6 +196,16 @@ changes meaning or goes; new fields may appear in the same version. Paths in `pu
     ],
     "codebases": ["plain_modules/app/code"]
   },
+  "spec_gaps": [{                                       // [] when no agent met one
+    "module": "app", "pulse": 3, "pulse_id": "2a058729", "landed": true,
+    "question": "What happens to a contact archived in HubSpot after it was synced?",
+    "assumption": "An archived contact is left as synced - asserted in sync.test.ts, archived contacts"
+  }],
+  "turn_incidents": [                                   // [] when none
+    { "kind": "provider_retry", "pulse_id": "2a058729", "role": "coding", "model": "…", "error": "…: 529 overloaded", "attempt": 1, "of": 6, "wait_seconds": 15.3 },
+    { "kind": "provider_stall", "pulse_id": "2a058729", "role": "coding", "model": "…", "silent_seconds": 120 },
+    { "kind": "stopped", "pulse_id": "5c1e0b2f", "role": "conformance explorer", "model": "…", "reason": "10 submit_exploration calls failed in a row" }
+  ],
   "build_dir_export": { "exported": true, "dir": "/work/out", "module": "app", "commit": "8036b3b", "files": 23 },
   "logs": { "jobs_dir": ".turri/jobs", "debug_dir": ".turri/debug", "sessions_dir": ".turri/sessions" }
 }
@@ -209,6 +224,21 @@ calls; a role or model turri could not tell is `unknown`.
 stopped, or did not pass - and everything it wrote was undone. A pulse that failed is tried once more
 before it counts as failed; both tries are the one pulse.
 
+**Spec gaps.** A behaviour the spec leaves open that an agent met and decided on its own - reported with
+`report_spec_gap` (see [regenerating](regenerating.md)). In the chat they are put to you as the pulse ends; a
+headless run has no one to ask, so they are listed here, in the order the pulses started, and printed under the
+pulse that met them. `assumption` is what the agent decided meanwhile, also in the codebase's notes'
+assumptions while its pulse is `landed`; a pulse rolled back takes it out of the notes, but the question still
+stands. Settle the ones you care about in the spec and run again.
+
+**Turn incidents.** Each time the model provider failed for a moment and pi or turri waited it out before trying
+the request again, each time the provider sent nothing back on a request for two minutes, and each turn turri
+stopped itself - an agent going round in a circle, its calls failing again and again, its time up - after which the
+run carried on. The provider failing or stalling is printed as it happens, in yellow, under the pulse; a stop is
+the work's normal course and is only listed. They are counted in the usage as `provider_retries`,
+`provider_stalls` and `turns_stopped`. Many of any point at the model, not the spec: a provider at its limits, or a
+model too small for the role it was given.
+
 **Completed functional specs** - the pass rate, the figure to compare runs by.
 A functional spec is completed when the code record of the codebase the run delivers - the
 furthest-built of the chain, the one `--build-dir` exports - as last committed, holds it as the spec has
@@ -227,7 +257,7 @@ and modules that are complete are skipped, so it picks up where it stopped - aft
 provider outage, or a machine that went to sleep anyway. Whatever the stopped run left
 half-written is undone first: each step starts from the module's last commit. A functionality whose spec has changed
 since counts as not built, so editing the spec and re-running rebuilds what changed. `--from-scratch`
-rebuilds everything.
+rebuilds the module; `--from-scratch-chain` rebuilds every module of its chain.
 
 ## Rebuilding one functionality
 

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,22 @@ 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. A stop is the work's normal course: it is in the pulse's activity
+and log and the run report's `turn_incidents`, but not said in the chat or a headless run's console - those say
+only the model provider failing or stalling.
+
+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 +260,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 +291,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 +401,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 +541,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 +582,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 +740,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 +876,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 +960,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 +1003,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 +1111,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 +1128,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 +1160,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