@turri-dev/cli 0.1.2 → 0.1.3-next.162a2c3

package/dist/setup.js

@@ -6,6 +6,7 @@ import { ModelRegistry, ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { globalExtensionFile, MIN_NODE, nodeVersionOk, PACKAGE_ROOT, turriOnPath } from "./environment.js";
 import { sandboxAvailable } from "./regenerate/os-sandbox.js";
 import { findTestScripts } from "./regenerate/test-scripts.js";
+import { configKeyOptions, parseArgs } from "./cli-options.js";
 import { hasProjectConfig, readProjectConfig, stackOf } from "./config.js";
 import { checkModels, modelsInUse, piModelAccess } from "./model-check.js";
 import { brand } from "./brand.js";
@@ -33,6 +34,17 @@ export function checkShell(found = spawnSync("bash", ["--version"], { stdio: "ig
         fix: platform === "win32" ? "install Git for Windows (Git Bash), and put its bash on the PATH" : "install bash with your system's package manager",
     };
 }
+/** git: each module's history, which every pulse starts from and lands in, and the spec diffs the work is planned from. */
+export function checkGit(found = spawnSync("git", ["--version"], { stdio: "ignore", windowsHide: true }).status === 0) {
+    if (found)
+        return { level: "ok", name: "git", detail: "on the PATH - each module's history, and the spec diffs" };
+    return {
+        level: "missing",
+        name: "git",
+        detail: "not on the PATH - each module's history is a git repository, and the work is planned from git diffs",
+        fix: "install git with your system's package manager",
+    };
+}
 /** Which wall is up under the agents' commands, and - where none starts - why, and how to give it one. */
 export function checkSandbox(wall = sandboxAvailable(), platform = process.platform) {
     if (wall.kind === "seatbelt")
@@ -140,7 +152,7 @@ function checkGlobal() {
 export async function checkProjectModels(project, access) {
     const used = modelsInUse(readProjectConfig(project, stackOf(project)));
     if (used.length === 0) {
-        return [{ level: "missing", name: "Models", detail: "config.turri.yaml names none", fix: "turri init-config writes the two models" }];
+        return [{ level: "missing", name: "Models", detail: "config.turri.yaml names none", fix: "turri init-config writes the two models - or name them here: --harness-model, --coding-model" }];
     }
     let verdicts;
     try {
@@ -156,16 +168,17 @@ export async function checkProjectModels(project, access) {
             : { level: "missing", name, detail: verdict.spec, more: [verdict.problem], fix: verdict.fix };
     });
 }
+/** `modelsGiven`: models named on the command line - checked wherever doctor runs, a project or not. */
 async function allChecks(options = {}) {
-    const checks = [checkNode(), checkShell(), checkSandbox(), await checkProvider(), checkPath(), ...checkGlobal()];
+    const checks = [checkNode(), checkShell(), checkGit(), checkSandbox(), await checkProvider(), checkPath(), ...checkGlobal()];
     // In a project: what it needs of this machine, and whether its models answer.
     const project = process.cwd();
-    if (hasProjectConfig(project) || existsSync(join(project, "plain_modules"))) {
+    const inProject = hasProjectConfig(project) || existsSync(join(project, "plain_modules"));
+    if (inProject)
         checks.push(...checkProject(project));
-        if (options.models !== false && hasProjectConfig(project)) {
-            console.log(brand.muted("Asking each model the config names for a word..."));
-            checks.push(...(await checkProjectModels(project)));
-        }
+    if (options.models !== false && (hasProjectConfig(project) || options.modelsGiven === true)) {
+        console.log(brand.muted("Asking each model the config names for a word..."));
+        checks.push(...(await checkProjectModels(project)));
     }
     return checks;
 }
@@ -224,21 +237,27 @@ function removeGlobalExtension() {
     rmSync(file, { force: true });
     console.log(`  removed ${file}`);
 }
+const USAGE = [
+    "usage: turri doctor [--harness-model <m>] [--coding-model <m>] [--judge-model <m>] [--no-models] [--yes]",
+    "",
+    "Check everything turri needs - in a project, what its modules need of this machine too, and that",
+    "each model its config names answers with this machine's credentials (one short request a model;",
+    "--no-models skips it). The model options are read as the config's keys, as turri regenerate reads them:",
+    "a headless run's models can be checked before it starts, with no config.turri.yaml.",
+    "It changes nothing but this, asked first: a plain pi that an older turri made load turri too is put back to",
+    "plain pi. --yes answers yes.",
+].join("\n");
 export async function main(args) {
-    if (args.includes("--help") || args.includes("-h")) {
-        console.log("usage: turri doctor [--no-models] [--yes]\n\nCheck everything turri needs - in a project, what its modules need of this machine too, and that\n" +
-            "each model its config names answers with this machine's credentials (one short request a model;\n--no-models skips it).\n" +
-            "It changes nothing but this, asked first: a plain pi that an older turri made load turri too is put back to\n" +
-            "plain pi. --yes answers yes.");
-        return 0;
-    }
+    const { options } = parseArgs(args, ["--no-models", "--yes", "-y"], USAGE, ["--harness-model", "--judge-model"]);
+    configKeyOptions(options);
     console.log(brand.bold(brand.accent("Checking what turri needs.")));
     if (!nodeVersionOk())
         return report([checkNode()]);
-    const code = report(await allChecks({ models: !args.includes("--no-models") }));
+    const modelsGiven = ["harness-model", "model", "judge-model"].some((name) => options[name] !== undefined);
+    const code = report(await allChecks({ models: options["no-models"] === undefined, modelsGiven }));
     // turri and pi are kept apart: a plain pi does not start turri. An older turri's file that made it do so goes, asked.
     const global = globalExtensionFile();
-    if (global !== undefined && (await confirm(`\nA plain \`pi\` loads turri too, through ${global}. Remove it, so pi stays pi?`, true, args.includes("--yes") || args.includes("-y")))) {
+    if (global !== undefined && (await confirm(`\nA plain \`pi\` loads turri too, through ${global}. Remove it, so pi stays pi?`, true, options.yes !== undefined || args.includes("-y")))) {
         removeGlobalExtension();
     }
     return code;

package/dist/spec-diff-cli.js

@@ -2,16 +2,25 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { checkPlainFile } from "./plain/check.js";
 import { applySpecDiff, revertSpecDiff } from "./regenerate/regenerate.js";
-import { parseArgs, runLoop } from "./loop-cli.js";
+import { parseArgs } from "./cli-options.js";
+import { headlessOptions, runLoop } from "./loop-cli.js";
 const USAGE = `usage: turri spec-diff <file.plain> <diff-file> [options]
 
 Applies a change to the specs, given as a git diff of the .plain files, and builds it: the headless
 counterpart of regenerate, given a diff. The diff is applied first, unless it is already in; then, as
 turri regenerate does, what is left to build is planned into jobs and built.
 
-  --model <provider/id>    model for the agents (default: config.turri.yaml's coding-model)
-  --start-over             start over, without asking, a codebase regenerated without a module it now requires`;
-const { positional, options } = parseArgs(process.argv.slice(2), ["--start-over"], USAGE);
+  --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner, the conformance chooser, a diagnosis
+  --coding-model <p/id>    its coding-model, --model too: the agents that build
+  --start-over             start over, without asking, a codebase regenerated without a module it now requires
+  --judge-model <p/id>     its judge-model: the judge and the test review
+  --review <true|false>    its review: whether the code and its tests are reviewed once they pass
+  --conformance-tests <all|chosen|module|false>
+                           its conformance-tests: which conformance tests are written and run
+  --build-dir <dir>        as the run ends, export the code there (see turri regenerate --help)
+  --report <file.json>     write a report of the run there (see turri regenerate --help)`;
+const { positional, options } = parseArgs(process.argv.slice(2), ["--start-over"], USAGE, ["--build-dir", "--report", "--conformance-tests", "--harness-model", "--judge-model", "--review"]);
+const { report, buildDir } = headlessOptions(options, true);
 const [plainFile, diffFile] = positional;
 if (plainFile === undefined || diffFile === undefined) {
     console.error(USAGE);
@@ -28,9 +37,11 @@ if (!check.ok) {
 }
 runLoop({
     plainFile,
-    ...(options.model !== undefined ? { model: options.model } : {}),
     startOver: options["start-over"] !== undefined,
-    ask: (loop) => loop.bringUp(plainFile, options.model !== undefined ? { model: options.model } : {}),
+    ...(buildDir !== undefined ? { buildDir } : {}),
+    ...(report !== undefined ? { report } : {}),
+    command: ["spec-diff", ...process.argv.slice(2)],
+    ask: (loop) => loop.bringUp(plainFile),
 }).catch((error) => {
     console.error(error instanceof Error ? error.message : error);
     process.exit(1);

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);
@@ -129,27 +117,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/config.md

@@ -5,7 +5,7 @@ is optional: with no file at all, turri finds the testing scripts on its own, tu
 tests on wherever a module has test reqs, and runs on pi's configured model. A project whose
 parts are on different stacks - a backend and a frontend - adds a file per stack,
 `config.turri.<stack>.yaml`, beside it, and chooses the stack to build with (see
-[stacks](#stacks)). turri never writes a `config.yaml`: it may be another tool's - codeplain's - and
+[stacks](#stacks)). turri never writes a `config.yaml`: it may be another tool's, and
 is read only by a project that has no file of turri's yet (see [the old config.yaml](#the-old-configyaml)).
 
 `turri init-config` starts one: the two models, a strong one to talk to and a smaller one to write the code. It
@@ -42,7 +42,7 @@ change one by changing it. The optional ones, which have no value of their own -
 skill that writes them), `module`, `conformance-budget`, `judge-model`, `models` - are there commented out, each with an
 example: uncomment one to use it. A key taken out of the file is still read as the table below says.
 
-Beside a `config.yaml` - codeplain's - the new file takes from it the keys turri reads too, each in its place, its
+Beside a `config.yaml` - another tool's, say - the new file takes from it the keys turri reads too, each in its place, its
 testing scripts above all, and says which it left (see [the old config.yaml](#the-old-configyaml)); `config.yaml`
 is left as it is. A `config.turri.yaml` already there keeps everything but its two models, which it sets - `--force` writes the whole
 file again - and a `config.yaml` turri read until then is copied to it first. It takes a folder other than the current
@@ -122,7 +122,7 @@ models:                              # each agent role's model, thinking and tur
 | key | what it sets | left out |
 | --- | --- | --- |
 | `module` | the `.plain` file `turri regenerate` and the chat's `regenerate` build when none is named, from the project root | a file has to be named |
-| `harness-model` | the model `turri` starts on - the one you talk to - the one that diagnoses a job that failed for good, and, in the conversation, the planner that cuts the work into jobs (on whatever model the chat is on when it plans); under `turri regenerate`, the planner too | pi's configured model |
+| `harness-model` | the model `turri` starts on - the one you talk to - and, in the conversation, the planner that cuts the work into jobs (on whatever model the chat is on when it plans); under `turri regenerate`, the planner too | pi's configured model |
 | `coding-model` | every render: functionalities, spec diffs, conformance tests, repairs, planning spec diffs, the explorer | `harness-model` |
 | `judge-model` | the judge and the test review of a conformance run | `coding-model` |
 | `conformance-tests` | `all` (or `true`): conformance tests for every functional spec of every module with test reqs, written once each module's code is built, before anything is built on it. `chosen`: for the functional specs chosen - every one with acceptance tests, and those the chooser picks as each code pulse ends, from what that pulse regenerated. `module`: the same, but the chooser is asked once, when the whole module is regenerated, and plans the conformance pulses too. Under both, the choice is made inside the pulse, before anything is built on the module, and the pulse's report says what was chosen and why; those the person asks for with `conform` are written too; once chosen, a functional spec keeps them, and they are rewritten when it changes - see [who chooses, and when](regenerating.md#conformance-tests-in-the-work-loop). `false`: none written, and none of the existing ones run - until the conversation asks with `conform` | `false` |
@@ -133,7 +133,7 @@ models:                              # each agent role's model, thinking and tur
 | `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` |
 | `unittests-script` | the unit testing script, by path from the project root - it runs the code's static checks too, exiting 80 when only they fail (see [the static checks](regenerating.md#the-static-checks)) | looked for - see below |
 | `conformance-tests-script` | the conformance testing script, by path from the project root | looked for - see below |
-| `prepare-environment-script` | optional, as codeplain has it: run as `<script> <build>` before every run of the conformance testing script, which runs only once it passes - see [the testing scripts](regenerating.md#the-testing-scripts). turri never writes one | the one `prepare_environment*.sh` at the root or in `test_scripts/`, else none |
+| `prepare-environment-script` | optional: run as `<script> <build>` before every run of the conformance testing script, which runs only once it passes - see [the testing scripts](regenerating.md#the-testing-scripts). turri never writes one | the one `prepare_environment*.sh` at the root or in `test_scripts/`, else none |
 | `compact-at` | how many tokens of work - past its instructions - an agent kept through a job holds before the harness compacts it between turns; at least 1000; the project's alone | 100,000 - see [agent sessions](regenerating.md#agent-sessions) |
 | `max-specs-per-pulse` | the most functional specs the planner groups into one pulse - what builds one feature goes together, up to this many; a stack's file wins | 3 |
 | `max-lines-per-pulse` | the most lines of spec in one pulse - its functional specs with the definitions they bring; a group past it is split again, a functional spec a pulse; a stack's file wins | 120 |
@@ -145,7 +145,7 @@ models:                              # each agent role's model, thinking and tur
 | `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` |
 
 Keys are written with dashes; underscores are read the same (`conformance_tests`). A key turri
-does not know is ignored - a codeplain `config.yaml`, read while it is the old file, carries several - and so is a value of the
+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
 wrong type, as if it were not there. `model:`, from before there were separate models, is read as
 `coding-model`.
 
@@ -158,7 +158,8 @@ wrong type, as if it were not there. `model:`, from before there were separate m
 | --- | --- |
 | `default` | every role not named below - but the conversation's side |
 | `chat` | `turri`'s model - the same as `harness-model`, which it wins over |
-| `chooser`, `planner`, `diagnosis` | the conversation's side: the conformance chooser of `turri regenerate`, the planner's agents, the diagnosis of a failed job. Unnamed, the chat's model |
+| `chooser`, `planner` | the conversation's side: the conformance chooser of `turri regenerate`, the planner's agents. Unnamed, the chat's model |
+| `diagnosis` | the diagnosis of a job that failed for good: why it did not land, and what to do. Unnamed, the coding model the job ran on, thinking medium |
 | `release` | `turri release`'s agent and release-after-pulse's: it follows steps - a script, a start command - so it runs on the coding model, thinking low |
 | `coding` | the coding agent, the code fixer of a conformance run and the repair agent - the same as `coding-model`, which it wins over. `--model` on the command line, or a model chosen in the conversation (`engine`), wins over both |
 | `conformance` | the conformance agent |
@@ -218,8 +219,13 @@ They are defaults. What is asked for wins over them:
 | model | wins over the config |
 | --- | --- |
 | harness | `turri --harness-model <m>` (or pi's own `--model`), and pi's `/model` in the conversation |
-| coding | `turri --coding-model <m>`, `engine` in the conversation, and `--model` / `--coding-model` on `turri regenerate`, `conform` and `spec-diff` |
-| judge | `--judge-model` on `turri conform` |
+| coding | `turri --coding-model <m>`, `engine` in the conversation |
+| judge | - |
+
+`turri regenerate`, `conform` and `spec-diff` read `--harness-model`, `--coding-model` (or `--model`),
+`--judge-model`, `--review` and `--conformance-tests` differently: as the keys themselves, as if the file had
+them. Each takes its key's value and its place in the order above - a `models:` entry still wins over it - so a
+headless run is the same as a chat with those keys in the file.
 
 A job keeps the model it was queued with: choosing another holds for what is queued after.
 
@@ -231,8 +237,8 @@ codebase are not run, and no agent is shown the conformance testing script. No k
 `false`: conformance tests are off by default. `all` (or `true`) means on wherever a module has
 `***test reqs***` - a module without them has nothing to write conformance tests from, so it writes
 none, but still keeps the codebase's existing ones passing. Asked in the
-conversation, or with `--conformance` / `--no-conformance` on the command line, a render does
-otherwise.
+conversation (`conform`), or with `--conformance-tests all|chosen|module|false` on `turri regenerate` and
+`spec-diff` - for that run, the file left as it is - a render does otherwise.
 
 `spawn` writes `conformance-tests: false` into a new project unless you ask for tests;
 `brood` asks, whatever the key says, offering what it says first.
@@ -346,8 +352,14 @@ The first time turri itself writes a setting there with `/turri-config`, it copi
 `config.turri.yaml` and each `config.<name>.yaml` to `config.turri.<name>.yaml` first, leaves the old
 files as they are, and from then on reads only the new ones. `turri init-config` copies the stacks'
 files the same way, but writes `config.turri.yaml` as its quick start, taking from `config.yaml` only
-the keys turri reads too - codeplain's `unittests-script`, `conformance-tests-script` and
+the keys turri reads too - `unittests-script`, `conformance-tests-script` and
 `prepare-environment-script`, say - each in its place in the file, and saying which keys it left:
-`template_dir`, `verbose`, `api`, codeplain's alone. The two models are the vendor's, never taken. To change a
+`template_dir`, `verbose`, `api`, the other tool's alone. The two models are the vendor's, never taken. To change a
 setting by hand in such a project, do the same: copy the files to their new names, and edit the
-copies - never `config.yaml`.
+copies - never `config.yaml`. Writing a `config.turri.yaml` of your own beside it is the same move: from then on
+`config.yaml` is not read, its testing scripts with it. For a headless run that only needs conformance tests or
+another judge, or review, those options leave the files alone: `--conformance-tests`, `--judge-model`, `--review true|false`, and the models' too.
+
+Keys turri does not read - another tool's `verbose`, `api-key`, `build-folder`, ... - are ignored without a word, and so
+is a value of the wrong type. A file that does not parse as YAML is read as empty, so its testing scripts are then
+looked for by name.

package/docs/development.md

@@ -18,6 +18,12 @@ which tests reach which mutant (`vitest.stryker.config.ts`, the suite without th
 mutant against those tests. `scripts/mutation.mjs` sets two things in Stryker's vitest runner the suite needs - forked
 workers, and a test-name filter that matches vitest 5's names - again after every `npm install`.
 
+The `mutation` workflow (`.github/workflows/mutation.yml`) runs it on GitHub, started by hand: Actions, mutation, Run
+workflow. It takes the parts to run, space-separated (empty for every part), each a job of its own side by side, on
+four cores (`TURRI_MUTATION_CONCURRENCY`; six here). Each part's `mutation.html` and `mutation.json` are uploaded as an
+artifact, `mutation-<part>`, and summed up on the run's page. Stryker's incremental file is cached from run to run, so
+a run tests again only the mutants whose code or tests changed; tick `fresh` to test every one again.
+
 Working on turri itself, `npm link` points the global `turri` at this clone, so edits
 take effect immediately. `npm run chat` starts pi with the extension loaded from `src/`.
 
@@ -69,6 +75,7 @@ trust `turri-oss/turri`, the workflow `publish.yml` and the environment `npm`. R
 | `src/regenerate/confine.ts`, `src/regenerate/agent-shell.ts`, `src/regenerate/command-check.ts`, `src/regenerate/os-sandbox.ts`, `src/regenerate/audit.ts`, `src/regenerate/agent-env.ts`, `src/regenerate/shell.ts` | the file-tool fence and the walls around every agent command: the check, the OS sandbox, the audit, the module's environment, the host runner - see [sandbox](sandbox.md) |
 | `src/regenerate/engine.ts` | choosing and resolving render models |
 | `src/regenerate/job-panel.ts`, `src/regenerate/transcript-view.ts`, `src/regenerate/diff-view.ts` | the job panel, the side panel's colours, and a spec diff as they show it - highlighted and banded |
+| `src/regenerate/side-panel.ts`, `src/regenerate/panel-dock.ts` | the side panel, and the chat narrowed beside it when it is docked |
 | `src/regenerate/spec-map.ts`, `src/regenerate/spec-map-view.ts` | regen: each item's mark, from the records, the `.plain` files and the work loop's plan (`mapPlan`), and the map drawn |
 | `src/regenerate/debug-log.ts` | each render agent's whole conversation, always streamed to `.turri/debug/` |
 | `genome/` | what turri knows and can do: `genome/skills/`, the skill library, and `genome/rules/`, the \*\*\*plain authoring rules |

package/docs/headless.md

@@ -14,7 +14,8 @@ Everything marked `✗` stops the run, so fix those first. Two more things matte
   a module's implementation reqs name that this machine lacks.
 - **The models.** In a project, `turri doctor` sends each model `config.turri.yaml` names one short request, as turri's
   agents will - so a key the provider refuses, a model pi does not know or an account without access to it shows now,
-  not an hour into the run.
+  not an hour into the run. Models the run is given on the command line are given to doctor the same way -
+  `--harness-model`, `--coding-model`, `--judge-model`, read as the config's keys - and are checked with the config's.
 - **Credentials that do not expire mid-run.** An API key in the environment
   (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, ...) or pi's saved login - whatever
   `doctor` shows as the model provider.
@@ -62,9 +63,14 @@ conformance-tests: true            # write and run conformance tests where there
 ```
 
 The same file names the [testing scripts](regenerating.md#the-testing-scripts); every key is in
-[the project config](config.md). Options on the command
-line win over it; `turri regenerate`, `spec-diff` and `conform` take its
-`coding-model` too, and `--coding-model` means the same as `--model` on every one of them.
+[the project config](config.md). `turri regenerate`, `spec-diff` and `conform` take five of its keys on
+the command line too - `--harness-model`, `--coding-model` (`--model` is the same), `--judge-model`,
+`--review` and, but for `conform`, `--conformance-tests`. Each is read as if the file had it, in its place:
+it takes that key's value, and every key keeps its place in the order the config resolves them in - a
+`models:` entry still wins over `harness-model`, `coding-model` or `judge-model`, the planner and the
+conformance chooser run on the harness model, the judge falls back on the coding model. So a run with
+the options is the same as one, or a chat, with those keys in `config.turri.yaml` - and a `config.yaml`
+the project has is left as it is.
 A project whose parts are on different stacks keeps each stack's settings in
 `config.turri.<stack>.yaml` beside it ([stacks](config.md#stacks)). Choose the one to build with
 `--stack <name>` - on any command: `regenerate`, `conform`, `spec-diff`, `glimpse`, `release`, `cultivate` -
@@ -75,29 +81,39 @@ Useful options - `turri regenerate --help` lists all of them:
 
 | | |
 | --- | --- |
-| `--model <provider/id>` | the model every agent runs on (`--coding-model` too), with `:level` for its thinking (`provider/id:high`); default, `config.turri.yaml`'s `coding-model`, then its `harness-model`, then pi's configured model |
-| `--judge-model <provider/id>` | `conformance`: the model of the judge and the test review; default, `config.turri.yaml`'s `judge-model`, then the coding model |
+| `--harness-model <provider/id>` | `harness-model`: the planner and the conformance chooser |
+| `--coding-model <provider/id>` | `coding-model` (`--model` too): the agents that build - with `:level` for how hard it thinks (`provider/id:high`); not given, the harness model's |
+| `--judge-model <provider/id>` | `judge-model`: the judge and the test review; not given, the coding model |
+| `--conformance-tests <all\|chosen\|module\|false>` | `conformance-tests`, with its values (`true` is `all`) |
+| `--review <true\|false>` | `review`: whether the code and its tests are reviewed once they pass |
 | `--stack <name>` | build with the stack's `config.turri.<name>.yaml` over `config.turri.yaml`; default, `TURRI_STACK`, else none |
-| `--to <frid>` | queue functionalities only up to this one |
-| `--only` | build just this module, not the ones it requires |
-| `--build-dir <dir>` | where the code goes; default `plain_modules/<module>/code` |
+| `--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 |
+
+An option a command does not take is refused, not ignored.
 
 `turri regenerate` queues the jobs the chat's `regenerate` does - a spec diff that brings what
 is built in line, when it no longer matches the spec, then one render functionality job per
 functional spec not built, each with its conformance job - and runs them all to the end, the queue
 master reworking them as in the chat (see [a whole module](regenerating.md#a-whole-module)).
-Conformance tests follow `conformance-tests:` in `config.turri.yaml`.
+Conformance tests follow `conformance-tests:` in `config.turri.yaml`, or `--conformance-tests`.
 
 ## In the morning
 
-The command exits `0` only when every module is complete. The log says, per functionality, what
-was built and whether its tests passed; the last lines summarise each module.
+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
+tests passed.
 
 | | |
 | --- | --- |
 | `plain_modules/<module>/code/` | the code and unit tests |
 | `plain_modules/<module>/tests/` | the conformance tests |
 | `plain_modules/<module>/code/.turri.json` | the marshalled plain tree the code is built from |
+| `.turri/jobs/` | each pulse's log: its agents, its test runs, how it ended |
+| `.turri/debug/` | each agent's whole conversation |
 
 And what happened, step by step, in the module's history:
 
@@ -105,13 +121,112 @@ And what happened, step by step, in the module's history:
 git --git-dir=plain_modules/<module>/.plaingit --work-tree=plain_modules/<module> log --stat
 ```
 
+### Where the code is
+
+A module that `requires` others is built in its own codebase on top of theirs: the code of
+`plain_modules/<module>/code` holds every module below it. `--build-dir <dir>` exports it as the run
+ends, however it ends - done, failed, stopped by a signal: the last commit of the furthest-built
+codebase of the chain, with the harness's own files (`.turri.json`, the notes) left out, so what is in
+it is only what landed, its unit tests passing. The folder's contents are replaced each time; a
+folder that holds the project, or one inside `plain_modules`, is refused. Point an external test
+suite at it.
+
+### The run report
+
+`--report <file.json>` writes one JSON summary of the run, for a benchmark or CI to read rather than
+the log. It is written as the run starts, again as each pulse ends, and last as the process exits -
+whether the run is done, a pulse failed, the provider failed, it crashed, or `SIGTERM` / `SIGINT` /
+`SIGHUP` stopped it. Only a process killed outright (`SIGKILL`) keeps the one written as its last pulse
+ended. Each write replaces the file whole (written beside it, then renamed), so a reader never sees
+half of one. Keys are snake_case, numbers are numbers, and `schema_version` changes only when a field
+changes meaning or goes; new fields may appear in the same version. Paths in `pulses`,
+`functionalities` and `logs` are relative to `project_dir`.
+
+```jsonc
+{
+  "schema_version": 1,
+  "turri": { "version": "0.1.1", "git_commit": "48dacfc…", "git_dirty": false },  // commit: null outside a clone
+  "command": ["regenerate", "app.plain", "--model", "…", "--report", "report.json"],
+  "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,
+  "models": {
+    "harness": { "model": "…", "thinking": "medium" },  // the planner, the chooser
+    "coding":  { "model": "…", "thinking": "low" },
+    "judge":   { "model": "…", "thinking": "medium" },
+    "observed": { "coding": ["provider/id:low"], "planner": ["provider/id:medium"] }  // what each role really ran on
+  },
+  "started_at": "…", "finished_at": "…", "duration_seconds": 4351.4,
+  "outcome": {
+    "status": "completed",  // completed | incomplete | failed | interrupted | crashed | running (written mid-run)
+    "exit_code": 0, "signal": null, "error": null,
+    "modules": [{ "module": "app", "state": "complete" }]  // complete | incomplete | halted | start_over_needed | running, with "why"
+  },
+  "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
+    },
+    "in_pulses": { },       // the pulses' usage added up - the same fields
+    "outside_pulses": { },  // the planner, the conformance chooser, a failed pulse's diagnosis
+    "by_model": { "provider/id:low": { } },
+    "by_role": { "coding": { }, "reviewer": { }, "planner": { } },
+    "by_pulse_kind": { "code": { }, "conformance": { } }
+  },
+  "pulses": {
+    "counts": { "total": 7, "landed": 5, "failed": 1, "stopped": 0, "rolled_back": 2, "running": 0, "not_started": 0 },
+    "list": [{
+      "id": "2a058729", "module": "app", "number": 1, "kind": "code", "title": "…",
+      "status": "succeeded", "landed": true, "failed_for_good": false,
+      "started_at": "…", "duration_seconds": 512.3, "usage": { },
+      "agents": [{ "label": "app 1 coding agent", "model": "…", "turns": 14, "compactions": 0, "input_tokens": 0, "…": 0 }],
+      "log_file": ".turri/jobs/….log", "error": null
+    }]
+  },
+  "functionalities": {
+    "total": { "specified": 12, "completed": 10, "conformance_tested": 8 },
+    "modules": [
+      { "module": "base", "specified": 4, "completed": 4, "conformance_tested": 4, "incomplete_frids": [] },
+      { "module": "app", "specified": 8, "completed": 6, "conformance_tested": 4, "incomplete_frids": ["7", "8"] }
+    ],
+    "codebases": ["plain_modules/app/code"]
+  },
+  "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" }
+}
+```
+
+**Usage.** Every model response an agent gets counts, in a pulse or not. `total` is `in_pulses` plus
+`outside_pulses`, and `in_pulses` is the pulses' own usage added up - the figures their lines in the
+notes and the pulse logs print - so the totals can be checked by hand against them. `llm_calls` counts
+model responses, a compaction's included; `agent_turns` the harness's requests to an agent, each as
+many responses as it takes; `model_seconds` the time from each request to its response's end, added
+up - several agents working at once each count theirs, so it can exceed the run's duration. Tokens and
+cost are as the provider reports them to pi. `by_model`, `by_role` and `by_pulse_kind` split the same
+calls; a role or model turri could not tell is `unknown`.
+
+**Pulses.** `landed`: its work is committed. `rolled_back`: it ended without landing - failed,
+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.
+
+**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
+it now: the same text, every file it links holding the same, no definition it uses changed, and not
+marked to regenerate again. A record moves only when a pulse lands, and a pulse lands only once the
+code's unit tests pass (its conformance tests too, when they are on), so completed means landed and
+passing. Each module counts its own functional specs: a module below the tip counts from what the
+tip's code was built on, and a module above the delivered codebase has none completed.
+`conformance_tested` is those of the completed ones whose conformance tests are recorded as written
+for them as they are now (`plain_modules/<module>/tests/.turri.json`).
+
 ## If it stopped
 
 Run the same command again. Functionalities already built from the current spec are left alone,
 and modules that are complete are skipped, so it picks up where it stopped - after a crash, a
 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. `--force`
+since counts as not built, so editing the spec and re-running rebuilds what changed. `--from-scratch`
 rebuilds everything.
 
 ## Rebuilding one functionality
@@ -125,14 +240,53 @@ it is - without rebuilding the ones before it. To change what it does, change it
 spec is what the code is built from, and a change made there lasts. Then it updates the
 functionality's conformance tests and runs every conformance test in the codebase, since a change can break something built
 later as easily as something built earlier. It works in the codebase the functionality now lives
-in: when later modules are built on top of this one, the furthest-built of them (`--in <module>`
-picks one when there are several). It exits `0` when everything passes, and refuses when there is
-no code yet - build it with `module` first.
+in: when later modules are built on top of this one, the furthest-built of them. It exits `0` when
+everything passes, and refuses when there is no code yet - regenerate the module first.
 
 Several changes do not need one command each: after editing the spec, re-running `turri regenerate`
 brings the code up to it - one spec diff for what changed in what is built, then the functional
 specs not built yet.
 
+## In a container
+
+A benchmark or CI task runs it with no terminal and nothing to ask, so give it everything up front:
+
+```bash
+turri regenerate app.plain --harness-model amazon-bedrock/eu.anthropic.claude-opus-5-5 \
+  --coding-model amazon-bedrock/eu.anthropic.claude-sonnet-5-5 \
+  --conformance-tests all --review false --judge-model amazon-bedrock/eu.anthropic.claude-opus-5-5 \
+  --start-over --build-dir /out/build --report /out/report.json < /dev/null
+```
+
+- **What it needs:** Node 22.19 or newer, `bash`, `git` (each module's history, and the spec diffs
+  the work is planned from), `/bin/sh` with `kill` and `sleep`, a writable `HOME` (pi keeps
+  `~/.pi/agent/auth.json` there, even with no login - or set `PI_CODING_AGENT_DIR`) and `TMPDIR`, and
+  the toolchains the project's testing scripts and implementation reqs name. `turri doctor` in the project, given
+  the run's models, checks them all and that each model answers - at the start of the task's log, not when a pulse
+  fails:
+
+  ```bash
+  turri doctor --harness-model amazon-bedrock/eu.anthropic.claude-opus-5-5 \
+    --coding-model amazon-bedrock/eu.anthropic.claude-sonnet-5-5 --judge-model amazon-bedrock/eu.anthropic.claude-opus-5-5
+  ```
+
+  It exits 1 on anything marked `✗`.
+- **Without bubblewrap:** a container that cannot make user namespaces - no
+  `--security-opt seccomp=unconfined` - has no OS sandbox. turri runs anyway, the command check and the
+  audit holding alone under the agents' commands; `turri doctor` shows it as `!`, not `✗`. Installing
+  the `bubblewrap` package is worth it where it can start.
+- **As another user:** run it as the user who will own `plain_modules/`. git refuses a repository
+  another user made (`dubious ownership`), so do not let root create it first.
+- **Amazon Bedrock:** `AWS_BEARER_TOKEN_BEDROCK` (or the usual AWS credentials) and `AWS_REGION` are
+  enough - no pi login. An `eu.` inference profile needs an EU region. A model id pi does not know
+  stops the first pulse; `turri --list-models bedrock` lists the ones it does.
+- **A project with only a `config.yaml`:** it is read while there is no `config.turri*.yaml` -
+  `unittests-script`, `conformance-tests-script` and `prepare-environment-script` included, relative to
+  the project; the keys turri does not know are ignored. Do not write a `config.turri.yaml` beside it to
+  turn on conformance tests or review: from then on `config.yaml` is not read. The options above do it instead.
+- **Long test suites:** a testing script run is stopped after 120 seconds; set `TURRI_COMMAND_TIMEOUT`
+  (seconds) for more.
+
 ## Asking in words instead
 
 pi's print mode runs one request and exits, with the render tools waiting for their work rather

package/docs/installation.md

@@ -68,7 +68,7 @@ In a project - a folder with `config.turri.yaml` (or the old `config.yaml`) or `
 | --- | --- |
 | each module's toolchains | what its implementation reqs name - Python, Node, Java, Go, Rust, C/C++, Zig, ... - against this machine's PATH: the agents use this machine's toolchains and install none, so a missing one is yours to install |
 | the testing scripts | what in them this machine does not have: a program named by its whole path that is not here (a macOS-only `/usr/libexec/java_home` on Linux), a toolchain they run that is not on the PATH |
-| the models | each model `config.turri.yaml` names - `harness-model`, `coding-model`, `judge-model`, every role under `models:` - sent one short request through pi, with the credentials turri's agents will use, for any provider pi supports. One that answers is ready; for one that does not, it says what the provider said and what to do: the credentials pi reads for that provider (`AWS_PROFILE` and `AWS_REGION` for Amazon Bedrock, `OPENAI_API_KEY`, `/login`, ...), model access in the Bedrock console, the closest model ids pi knows for one it does not. `--no-models` skips it |
+| the models | each model `config.turri.yaml` names - `harness-model`, `coding-model`, `judge-model`, every role under `models:` - sent one short request through pi, with the credentials turri's agents will use, for any provider pi supports. One that answers is ready; for one that does not, it says what the provider said and what to do: the credentials pi reads for that provider (`AWS_PROFILE` and `AWS_REGION` for Amazon Bedrock, `OPENAI_API_KEY`, `/login`, ...), model access in the Bedrock console, the closest model ids pi knows for one it does not. `--harness-model`, `--coding-model` (`--model`) and `--judge-model` name models as the config's keys, as `turri regenerate` reads them - checked in a project or not. `--no-models` skips it |
 
 Removing that file is the one thing `doctor` changes, and it asks first; `turri doctor --yes` says yes. Run without a
 terminal - piped, or in CI - it asks nothing and changes nothing. Run it again whenever something breaks;

package/docs/parser.md

@@ -9,7 +9,7 @@
 | `src/plain/spec.ts` | `plain_spec.py` - functionality ids, the per-functionality context, linked resources, ranges |
 | `src/plain/concepts.ts` | `concept_utils.py` - concept extraction, validation, topological ordering |
 | `src/plain/markdown.ts` | mistletoe's AST + `PlainRenderer` (mdast + a matching serializer) |
-| `src/plain/liquid.ts` | `plain2code_nodes.py` + the two filters in `plain_spec.py` (liquidjs) |
+| `src/plain/liquid.ts` | the reference implementation's Liquid nodes + the two filters in `plain_spec.py` (liquidjs) |
 | `src/plain/files.ts` | `file_utils.open_from` / `get_loaded_templates`, base64 blob detection |
 | `src/plain/stdlib.ts` | nothing - turri's own: `stdlib/` is a reserved import prefix, read from turri's standard library only, and a project module at such a path is an error (see [the standard library](authoring-plain.md#the-standard-library)) |