@turri-dev/cli 0.1.11-next.3495500 → 0.1.11-next.450c74d

package/README.md

@@ -179,7 +179,7 @@ turri regenerate app.plain      # regenerate the code from ***plain: planned int
 turri regenerate app.plain 3    # regenerate functionality 3, changed or not
 ```
 
-More: [using **turri**](docs/using.md); to regenerate \*\*\*plain overnight, see [running unattended](docs/headless.md).
+More: [using **turri**](docs/using.md); to render \*\*\*plain overnight, see [running unattended](docs/headless.md).
 
 ## Documentation
 
@@ -192,7 +192,7 @@ Start at the [documentation index](docs/README.md), or go straight to a page:
 | [Using **turri**](docs/using.md) | the conversation, skills, tools, pulses and regen, choosing models, the command line |
 | [The project config](docs/config.md) | `config.turri.yaml` and each stack's `config.turri.<stack>.yaml`: every key, models and their inheritance, conformance, the testing scripts, stacks and choosing one, the old `config.yaml` |
 | [Deploy](docs/deploy.md) | trying what is built: the last commit in `dist/<module>`, started on your machine, nothing installed without asking |
-| [Running unattended](docs/headless.md) | regenerating \*\*\*plain overnight or in CI: the command, keeping it running, the results, resuming, rebuilding one functionality |
+| [Running unattended](docs/headless.md) | rendering \*\*\*plain overnight or in CI: the command, keeping it running, the results, resuming, rebuilding one functionality |
 | [Authoring \*\*\*plain](docs/authoring-plain.md) | what \*\*\*plain is made of, the authoring rules, the skills that write and fix it, checking it |
 | [Regenerating](docs/regenerating.md) | what each build does and in which order: functionalities, modules, regeneration, changes to \*\*\*plain, conformance and acceptance tests, working notes, what the code is built from |
 | [The sandbox](docs/sandbox.md) | what agents can reach, the walls every command passes, time limits, the web tools |

package/dist/cli.js

@@ -78,7 +78,7 @@ const COMMANDS = {
     glimpse: { module: "./regenerate-cli.ts", blurb: "plan the work and print the first job's prompt, starting nothing", args: ["--dry-run"] },
     drift: { module: "./drift-cli.ts", blurb: "what is left to regenerate: how far the code has drifted from its spec" },
     conform: { module: "./conform-cli.ts", blurb: "write and run a module's conformance tests" },
-    "change-plain": { module: "./change-plain-cli.ts", blurb: "apply a change to ***plain, given as a git diff, and regenerate it" },
+    "spec-diff": { module: "./spec-diff-cli.ts", blurb: "apply a change to the specs, given as a git diff, and regenerate it" },
     validate: { module: "./validate-cli.ts", blurb: "validate a ***plain spec, regenerating nothing" },
     lineage: { module: "./lineage-cli.ts", blurb: "a module's lineage: what was regenerated into it, and when" },
     ledger: { module: "./ledger-cli.ts", blurb: "what turri did here: the last runs and their pulses, or one pulse, from the ledger" },

package/dist/extension.js

@@ -669,11 +669,11 @@ function turriExtension(pi, host) {
                 : "It changed no file in the project - whatever it said it wrote is not there. Say so to the user; do not report the work as done.";
             // A skill that edits the specs with the file tools builds nothing: the change is the conversation's to render.
             const specsChanged = changes.filter((path) => path.endsWith(".plain"));
-            const unrendered = specsChanged.length > 0 && !skill.allowedTools.includes("change_plain")
+            const unrendered = specsChanged.length > 0 && !skill.allowedTools.includes("write_spec_diff")
                 ? `${specsChanged.join(", ")} changed, and nothing is regenerated from that yet: call regenerate for it, and the code is brought up to the spec.`
                 : "";
             const gated = skill.steps.some((step) => step.gate !== undefined);
-            const first = skill.allowedTools.includes("change_plain") ? firstRegeneration(jobs.list(), began) : {};
+            const first = skill.allowedTools.includes("write_spec_diff") ? firstRegeneration(jobs.list(), began) : {};
             const ttfr = first.started === undefined
                 ? ""
                 : `Time to first regeneration: ${formatElapsed(first.started)} - its first pulse started that long after ${skill.name} began` +
@@ -1125,7 +1125,7 @@ export function projectConfigBlock(root) {
         return [
             ...settings(readProjectConfig(dir), withStack(undefined, () => findTestScripts(dir)), dir === root ? `${projectConfigFile(dir)}, for the specs here:` : `${relative(root, dir)}/${projectConfigFile(dir)}, for the specs in ${relative(root, dir)}/ - built in ${relative(root, dir)}/plain_modules:`, where, stacks.length > 0 ? "project of stacks" : "project"),
             ...(stacks.length > 0
-                ? ["", `Stacks: ${stacks.join(", ")} - chosen now: ${chosen ?? "none, so the project's file alone"}. Each module is built with the stack of its part, pinned to its pulses whatever is chosen after: a stack named after the module is its own - backend.plain is built with config.turri.backend.yaml - with nothing to choose. For a module whose stack has another name, pass it as stack to regenerate, conform, glimpse and change_plain. Choose one for the whole session with the stack tool only when the user asks.`]
+                ? ["", `Stacks: ${stacks.join(", ")} - chosen now: ${chosen ?? "none, so the project's file alone"}. Each module is built with the stack of its part, pinned to its pulses whatever is chosen after: a stack named after the module is its own - backend.plain is built with config.turri.backend.yaml - with nothing to choose. For a module whose stack has another name, pass it as stack to regenerate, conform, glimpse and write_spec_diff. Choose one for the whole session with the stack tool only when the user asks.`]
                 : []),
             // A stack: its file over the project's, for everything built while it is chosen.
             ...stacks.flatMap((stack) => [
@@ -1298,7 +1298,7 @@ function setRenderModelTool(pi, conversation) {
         label: "Engine",
         description: "The engine: which model the agents that regenerate the code run on. With no model, say which it is. With one, choose it " +
             "for the rest of this session: for spec changes " +
-            "(render spec diff pulses, and the ones change_plain queues), for functionalities (render, module, " +
+            "(render spec diff pulses, and the ones write_spec_diff queues), for functionalities (render, module, " +
             "regenerate with functionalities named, conformance), or for everything. By default " +
             "each runs on the model the project's config.turri.yaml names, or else the conversation's model. The model may be given as provider/model-id or by name as " +
             "the user said it; a name that fits more than one model, or none with credentials, comes back as a " +

package/dist/genome.js

@@ -12,7 +12,7 @@ import { DISMISSED } from "./ask.js";
 import { createQuestioning, levelOf, questioningQuestion } from "./questioning.js";
 import { createSpecDiffTools } from "./spec-tools.js";
 import { createMatureTools, MATURE_TOOLS } from "./mature-tools.js";
-const CHANGE_PLAIN = "change_plain";
+const WRITE_SPEC_DIFF = "write_spec_diff";
 /** The conversation's tools a skill acts on the work loop with - never pi built-ins. */
 const LOOP_TOOLS = ["regenerate", "drift", "halt", "conform"];
 /** How much of what the agent said before a question is shown with it: its end, where the brief is. */
@@ -77,14 +77,14 @@ export async function runSkill(opts) {
     const questions = {
         refusal: (confirmsPhase) => diffPerAnswer() && diffs?.pace.owed() === true
             ? "This question was not asked: the last answer is not in the spec yet. Every answer in this phase is a spec " +
-                "change, built at once - write it with change_plain first, then ask."
+                "change, built at once - write it with write_spec_diff first, then ask."
             : questioning?.refusal(confirmsPhase),
         answered: (confirmsPhase) => questioning?.answered(confirmsPhase),
         end: () => questioning?.end() ?? "No questioning level was chosen: ask what the phase needs.",
     };
-    // A skill whose unit of work is a spec change gets change_plain: the change is applied
+    // A skill whose unit of work is a spec change gets write_spec_diff: the change is applied
     // and its build queued in one step.
-    const diffs = opts.renderQueue !== undefined && skill.allowedTools.includes(CHANGE_PLAIN)
+    const diffs = opts.renderQueue !== undefined && skill.allowedTools.includes(WRITE_SPEC_DIFF)
         ? createSpecDiffTools({
             loop: opts.renderQueue,
             cwd: opts.cwd,
@@ -125,7 +125,7 @@ export async function runSkill(opts) {
     customTools.push(...(opts.sharedTools ?? []));
     const names = customTools.map((tool) => tool.name);
     // Tools this harness provides are never pi built-ins, even when it did not provide them.
-    const builtins = skill.allowedTools.filter((t) => !names.includes(t) && t !== CHANGE_PLAIN && !MATURE_TOOLS.includes(t) && !LOOP_TOOLS.includes(t));
+    const builtins = skill.allowedTools.filter((t) => !names.includes(t) && t !== WRITE_SPEC_DIFF && !MATURE_TOOLS.includes(t) && !LOOP_TOOLS.includes(t));
     const executor = await createExecutor({
         cwd: opts.cwd,
         customTools,

package/dist/identity.js

@@ -27,9 +27,8 @@ export function conversationIdentity(surface) {
 }
 const IDENTITY_BEFORE = [
     "<turri>",
-    "You are turri - always lowercase - the first coding agent with the power of regenerative software. The software is",
-    "its ***plain; the code is regenerated from it. You write the ***plain with the person - they say what the software",
-    "should do, and you write it down as ***plain, shaping it with them - and you regenerate the code from it a",
+    "You are turri - always lowercase - a coding agent with the power of regenerative software. The software is its",
+    "***plain; the code is regenerated from it. You help the person write ***plain, and you regenerate the code from it a",
     "change at a time - with agents that write the code and tests, while you decide what runs next and when the work is",
     "done - record what each piece was regenerated from, and prove it against conformance tests written from the ***plain",
     "alone. When the code goes bad, you regenerate it from the ***plain. You are named after Turritopsis dohrnii, the",
@@ -38,10 +37,9 @@ const IDENTITY_BEFORE = [
     "gone bad is regenerated from it, whole, rather than patched. Say it as that likeness, not as a fact about a",
     "jellyfish.",
     "",
-    "Asked who or what you are, say it in those words: you are turri, the first coding agent with the power of",
-    "regenerative software - you write ***plain with them and regenerate the code from it. Never say they write the",
-    "***plain and you help: you write it, together. Not an assistant, and not a helper with specifications: ***plain is",
-    "the language the software is written in, and naming it is the point. Your replies are Markdown, where",
+    "Asked who or what you are, say it in those words: you are turri, a coding agent with the power of regenerative",
+    "software - you help them write ***plain and regenerate the code from it. Not an assistant, and not a helper with",
+    "specifications: ***plain is the language they write, and naming it is the point. Your replies are Markdown, where",
     "three asterisks start bold italics: write the name escaped, \\*\\*\\*plain, so it shows as ***plain.",
     "",
     "Speak as turri, in the first person - I, my pulses, my agents - to the person, in whole sentences. Never speak of",
@@ -55,7 +53,7 @@ const IDENTITY_BEFORE = [
     "  allow-to-stop-jobs in config.turri.yaml are about pulses. \"Job\" in what you read is a pulse; say pulse.",
 ];
 const IDENTITY_AFTER = [
-    "- mutate, in a skill's activity, is change_plain: a spec change written and regenerated in one step.",
+    "- mutate, in a skill's activity, is write_spec_diff: a spec change written and regenerated in one step.",
     "- Regenerate is the word for what you do to the code: never grow, grew or grown - older text, a tool's description",
     "  or a report may still say it, and means regenerate.",
 ];

package/dist/loop-cli.d.ts

@@ -1,7 +1,7 @@
 import { type DriftReport, type ModuleStatus, type WorkLoop } from "./regenerate/loop.ts";
 import { type ModuleState } from "./run-report.ts";
 /**
- * What every command that builds - `turri regenerate`, `conform`, `change-plain` - does around its own
+ * What every command that builds - `turri regenerate`, `conform`, `spec-diff` - does around its own
  * request of the work loop, as the chat does it: the project's models, a job that fails run once more and, failing again,
  * diagnosed, a line as each job starts and ends; then the loop run until nothing more can start, how each job ended,
  * and exit 1 when any failed or a module is not complete. With `dryRun`, the work is planned and the prompt of the first job each codebase would

package/dist/loop-cli.js

@@ -17,7 +17,7 @@ import { listFiles } from "./regenerate/testing.js";
 import { startRunReport } from "./run-report.js";
 import { configKeyOptions, optionValue } from "./cli-options.js";
 /**
- * What every command that builds - `turri regenerate`, `conform`, `change-plain` - does around its own
+ * What every command that builds - `turri regenerate`, `conform`, `spec-diff` - does around its own
  * request of the work loop, as the chat does it: the project's models, a job that fails run once more and, failing again,
  * diagnosed, a line as each job starts and ends; then the loop run until nothing more can start, how each job ended,
  * and exit 1 when any failed or a module is not complete. With `dryRun`, the work is planned and the prompt of the first job each codebase would

package/dist/regenerate/activity.js

@@ -173,10 +173,10 @@ export function withinModules(text) {
 }
 /**
  * What the person is shown a tool as, where that is not the name its agent calls it by. The agent's name says
- * what the call takes - `change_plain` takes a diff of the spec - and the shown one speaks turri's language.
+ * what the call takes - `write_spec_diff` takes a diff of the spec - and the shown one speaks turri's language.
  */
 const SHOWN_AS = {
-    change_plain: "mutate",
+    write_spec_diff: "mutate",
 };
 /** A tool's name as the person is shown it. */
 export function shownName(name) {

package/dist/self-invocation.js

@@ -15,7 +15,7 @@ const TOOL_FOR = {
     conform: "conform",
     cultivate: "cultivate",
     release: "release",
-    "change-plain": "regenerate",
+    "spec-diff": "regenerate",
     chat: "nothing - you are the conversation already",
     ask: "nothing - you are the conversation already",
 };
@@ -31,7 +31,7 @@ const NPM_SCRIPT = {
 const ENTRY = {
     "regenerate-cli": "regenerate",
     "conform-cli": "conform",
-    "change-plain-cli": "change-plain",
+    "spec-diff-cli": "spec-diff",
     "cultivate-cli": "cultivate",
     "release-cli": "release",
 };
@@ -43,10 +43,10 @@ const AT_COMMAND = String.raw `(?:^|[\s;&|()\x60$])`;
  * agent - and neither are setup and doctor.
  */
 export function selfInvocation(command) {
-    const cli = new RegExp(`${AT_COMMAND}(?:npx\\s+)?turri\\s+(regenerate|glimpse|conform|cultivate|release|change-plain)\\b`).exec(command);
+    const cli = new RegExp(`${AT_COMMAND}(?:npx\\s+)?turri\\s+(regenerate|glimpse|conform|cultivate|release|spec-diff)\\b`).exec(command);
     if (cli)
         return cli[1];
-    const launcher = new RegExp(`(?:bin/turri\\.mjs|src/cli\\.ts)\\s+(regenerate|glimpse|conform|cultivate|release|change-plain)\\b`).exec(command);
+    const launcher = new RegExp(`(?:bin/turri\\.mjs|src/cli\\.ts)\\s+(regenerate|glimpse|conform|cultivate|release|spec-diff)\\b`).exec(command);
     if (launcher)
         return launcher[1];
     // turri alone, or with options, is the conversation - where a command starts, not a word an argument names (`which turri`).
@@ -83,7 +83,7 @@ const PI_CONFIGURES = new Set([
 export function askedForCommandLine(message) {
     const text = message.toLowerCase();
     return (/\b(headless|command[ -]line|cli|terminal|shell|in bash|via bash|through bash|npm run|nohup)\b/.test(text) ||
-        /\bturri\s+(regenerate|glimpse|conform|change-plain|cultivate|release)\b/.test(text) ||
+        /\bturri\s+(regenerate|glimpse|conform|spec-diff|cultivate|release)\b/.test(text) ||
         /(^|\s)turri\s+-p\b/.test(text) ||
         /(^|\s)pi\s+-p\b/.test(text));
 }
@@ -102,7 +102,7 @@ export const TOOLS_NOT_CLI = [
     "<turri-tools>",
     "In this conversation, you do your work with your tools - regenerate, conform, cultivate and the rest - which run as",
     "background jobs the user can watch and halt. To try what is regenerated, release it - never by hand in plain_modules. Never",
-    "run your own command line (turri regenerate, glimpse, conform, change-plain, cultivate, release, turri itself; npm run",
+    "run your own command line (turri regenerate, glimpse, conform, spec-diff, cultivate, release, turri itself; npm run",
     "regenerate and the like) or start another pi through bash:",
     "that is a separate headless run the user cannot see or stop. Only when the user explicitly asks for the",
     "command line, run it. Configuring pi itself - pi install, update, list, config, auth, or its settings files -",

package/dist/skill.d.ts

@@ -70,7 +70,7 @@ export interface Skill {
     allowedTools: string[];
     steps: StepSpec[];
     /**
-     * Whether `change_plain` needs an answer from the user between two new changes - one answer,
+     * Whether `write_spec_diff` needs an answer from the user between two new changes - one answer,
      * one change, as an interview writes them. `metadata.paced: false` turns it off, for a skill that
      * writes the specs on its own.
      */
@@ -81,8 +81,8 @@ export interface Skill {
      */
     questioning: string[];
     /**
-     * The steps where each answer is a spec change (`metadata.change-plain-per-answer`): the next question waits until the
-     * last answer is written with `change_plain`, and changes the agent decides itself need no answer before them.
+     * The steps where each answer is a spec change (`metadata.spec-diff-per-answer`): the next question waits until the
+     * last answer is written with `write_spec_diff`, and changes the agent decides itself need no answer before them.
      */
     diffPerAnswer: string[];
     /**

package/dist/skill.js

@@ -109,11 +109,11 @@ export function loadSkill(skillDir) {
             throw new Error(`${name}: 'metadata.questioning' names unknown step '${stepName}'`);
         }
     }
-    const perAnswer = data.metadata?.["change-plain-per-answer"];
+    const perAnswer = data.metadata?.["spec-diff-per-answer"];
     const diffPerAnswer = Array.isArray(perAnswer) ? perAnswer.map(String) : [];
     for (const stepName of diffPerAnswer) {
         if (!steps.some((s) => s.name === stepName)) {
-            throw new Error(`${name}: 'metadata.change-plain-per-answer' names unknown step '${stepName}'`);
+            throw new Error(`${name}: 'metadata.spec-diff-per-answer' names unknown step '${stepName}'`);
         }
     }
     for (const stepName of gatesByStep.keys()) {

package/dist/{change-plain-cli.js → spec-diff-cli.js}

@@ -4,9 +4,9 @@ import { checkPlainFile } from "./plain/check.js";
 import { applySpecDiff, revertSpecDiff } from "./regenerate/regenerate.js";
 import { parseArgs } from "./cli-options.js";
 import { headlessOptions, runLoop } from "./loop-cli.js";
-const USAGE = `usage: turri change-plain <file.plain> <diff-file> [options]
+const USAGE = `usage: turri spec-diff <file.plain> <diff-file> [options]
 
-Applies a change to ***plain, given as a git diff of the .plain files, and builds it: the headless
+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.
 
@@ -40,7 +40,7 @@ runLoop({
     startOver: options["start-over"] !== undefined,
     ...(buildDir !== undefined ? { buildDir } : {}),
     ...(report !== undefined ? { report } : {}),
-    command: ["change-plain", ...process.argv.slice(2)],
+    command: ["spec-diff", ...process.argv.slice(2)],
     ask: (loop) => loop.bringUp(plainFile),
 }).catch((error) => {
     console.error(error instanceof Error ? error.message : error);

package/dist/spec-tools.js

@@ -28,7 +28,7 @@ export function createSpecDiffTools(options) {
     let owed = false;
     let answeredSinceLastDiff = true;
     const writeDiff = defineTool({
-        name: "change_plain",
+        name: "write_spec_diff",
         label: "Write spec diff",
         description: "Apply a change to the ***plain specs, given as a git diff of the .plain files, and start building it in " +
             "the background. The diff is applied with git; if the specs no longer parse, it is undone and nothing is " +
@@ -36,7 +36,7 @@ export function createSpecDiffTools(options) {
             "every change is built, whatever it touches.",
         promptSnippet: "apply a git diff of the .plain specs and start building it",
         promptGuidelines: [
-            "Every change to a .plain file in the product phase goes through change_plain, as a git diff with paths relative to the project root. It writes the change and starts its build in one step.",
+            "Every change to a .plain file in the product phase goes through write_spec_diff, as a git diff with paths relative to the project root. It writes the change and starts its build in one step.",
             skillPaced
                 ? "One change per answer, and a new one only after the user has answered a question about it. Set fixes_earlier to correct something already written."
                 : "Write the changes one after another, on your own: no answer is needed between them, and none is asked for. Set fixes_earlier to correct something already written.",

package/dist/stacks.js

@@ -77,7 +77,7 @@ export function registerStacks(pi, cwd) {
             "For the session; a pulse already running keeps the stack it started with. Without a name, says the stacks and the one chosen.",
         promptSnippet: "choose the stack - its testing scripts and settings - that everything is built with",
         promptGuidelines: [
-            "Switch the stack only when the user asks for it, and say which you chose. A module is built with the stack named after it by itself; to build one whose stack has another name, pass that stack as stack to regenerate, conform, glimpse or change_plain instead: it is pinned to that module's pulses, and the session's choice stays as it is.",
+            "Switch the stack only when the user asks for it, and say which you chose. A module is built with the stack named after it by itself; to build one whose stack has another name, pass that stack as stack to regenerate, conform, glimpse or write_spec_diff instead: it is pinned to that module's pulses, and the session's choice stays as it is.",
         ],
         parameters: Type.Object({
             name: Type.Optional(Type.String({ description: "The stack to choose, or none. Omitted: the stacks there are, and the one chosen" })),

package/dist/tools.js

@@ -164,7 +164,7 @@ export function createEndQuestionsTool(questioning) {
         label: "End questions",
         description: "End this phase's questions: you have asked what the person must decide, and you decide what is left " +
             "yourself, saying what you chose. Afterwards ask_user asks only the phase's closing confirmation, and " +
-            "change_plain needs no answer between changes.",
+            "write_spec_diff needs no answer between changes.",
         promptSnippet: "end this phase's questions and decide what is left yourself",
         parameters: Type.Object({}),
         async execute() {

package/docs/README.md

@@ -1,31 +1,31 @@
 # turri documentation
 
-turri is the first coding agent with the power of regenerative software: [\*\*\*plain](https://plainlang.org/docs/) captures the durable definition of what a system does, and the code is regenerated from it and validated against. The [project README](../README.md) says why, and how to install and start; these pages go into each part.
+turri implements regenerative software: [\*\*\*plain](https://plainlang.org/docs/) captures the durable definition of what a system does, and the code is regenerated from it and validated against. The [project README](../README.md) says why, and how to install and start; these pages go into each part.
 
 ## Start here
 
 1. [Installation](installation.md) - get a machine ready: `turri doctor`, and what turri needs of this machine.
-2. [Using turri](using.md) - the conversation, the skills and tools, background jobs and their logs, choosing the model that codes, the command line.
-3. [Authoring \*\*\*plain](authoring-plain.md) - writing \*\*\*plain: what is it made out of, the authoring rules, the skills that write and fix it.
-4. [Regenerating](regenerating.md) - turning \*\*\*plain into code: what each build does, in which order, and what has to pass before it moves on.
+2. [Using turri](using.md) - the conversation, the skills and tools, background jobs and their logs, choosing the model that regenerates, the command line.
+3. [Authoring \*\*\*plain](authoring-plain.md) - writing the specs: what a spec is made of, the authoring rules, the skills that write and fix specs.
+4. [Regenerating](regenerating.md) - turning the specs into code: what each build does, in which order, and what has to pass before it moves on.
 
 ## By question
 
 | to find out… | read |
 | --- | --- |
 | what my machine needs, and why a check failed | [installation](installation.md) |
-| what turri needs of this machine, and what `turri doctor` checks | [installation](installation.md#what-turri-doctor-checks) |
+| what turri needs of this machine, and what `turri doctor` checks | [installation](installation.md#what-turri-setup-checks) |
 | how to start a project, or add a feature, in a conversation | [using](using.md#in-a-conversation) |
-| which model codes, and how to change it | [using](using.md#choosing-a-model), [the project config](config.md#models) |
+| which model regenerates, and how to change it | [using](using.md#choosing-a-model), [the project config](config.md#models) |
 | what `config.turri.yaml` can set, and what happens without it | [the project config](config.md) |
 | how a backend and a frontend on different stacks share one project | [the project config](config.md#stacks) |
-| which ready-made stacks \*\*\*plain can import - a FastAPI backend, a React frontend | [the standard library](authoring-plain.md#the-standard-library) |
+| which ready-made stacks a spec can import - a FastAPI backend, a React frontend | [the standard library](authoring-plain.md#the-standard-library) |
 | everything an agent was sent and did, to debug it | [using](using.md#agent-logs) |
-| how to regenerate \*\*\*plain overnight, and resume it | [running unattended](headless.md) |
+| how to regenerate a spec overnight, and resume it | [running unattended](headless.md) |
 | how to rebuild one functionality | [running unattended](headless.md#rebuilding-one-functionality) |
-| what goes in which section of \*\*\*plain | [authoring \*\*\*plain](authoring-plain.md#what-plain-is-made-of) |
+| what goes in which section of a spec | [authoring \*\*\*plain](authoring-plain.md#what-a-spec-is-made-of) |
 | which skill does what | [authoring \*\*\*plain](authoring-plain.md#the-skills) |
-| what happens when \*\*\*plain changes | [regenerating the code](regenerating.md#when-plain-changes) |
+| what happens when a spec changes | [regenerating the code](regenerating.md#when-the-spec-changes) |
 | why a test was not allowed to be deleted | [regenerating the code](regenerating.md#the-tests-must-actually-pass) |
 | how to try what is built, and what deploy may install | [deploy](deploy.md) |
 | what the agents can and cannot reach | [the sandbox](sandbox.md) |
@@ -43,8 +43,8 @@ turri is the first coding agent with the power of regenerative software: [\*\*\*
 | [The project config](config.md) | `config.turri.yaml` and each stack's `config.turri.<stack>.yaml`: where they are read from, every key, models and their inheritance, conformance, the testing scripts, stacks and choosing one, the old `config.yaml` |
 | [Deploy](deploy.md) | trying what is built: dist/<module>, the last commit, starting it on your machine, `turri release` |
 | [Running unattended](headless.md) | regenerating overnight or in CI: before you leave it, the command, the results, resuming, rebuilding one functionality |
-| [Authoring \*\*\*plain](authoring-plain.md) | a \*\*\*plain project, what \*\*\*plain is made of, the rules, writing \*\*\*plain with the agent, the skills, checking \*\*\*plain |
-| [Regenerating](regenerating.md) | where things go, one job, a whole module and how its work is cut into jobs, each job's cases, \*\*\*plain changes, conformance tests, the two records of what is built |
+| [Authoring \*\*\*plain](authoring-plain.md) | a \*\*\*plain project, what a spec is made of, the rules, writing specs with the agent, the skills, checking a spec |
+| [Regenerating](regenerating.md) | where things go, one job, a whole module and how its work is cut into jobs, each job's cases, spec changes, conformance tests, the two records of what is built |
 | [The sandbox](sandbox.md) | what an agent can reach, the file-tool fence, the command check, the OS sandbox, the audit |
 | [Skills and gates](skills-and-gates.md) | the gate syntax, what the harness enforces, what a step can do, the rules, trying the gates |
 | [The \*\*\*plain parser](parser.md) | the TypeScript port, `turri validate`, inheritance, the iterator, fidelity |

package/docs/authoring-plain.md

@@ -1,8 +1,8 @@
 # Authoring \*\*\*plain
 
-turri builds code from [\*\*\*plain](https://plainlang.org/docs/) - its documentation is the language's whole reference. Regenerating turns \*\*\*plain into code; authoring is the half that decides what gets built. The code is only ever as good as the \*\*\*plain description - a fact in the wrong section is silently ignored, a functional spec that is too big comes out half-built, two functional specs that contradict each other break each other's tests. So this repo carries as much for writing \*\*\*plain as for regenerating it: the authoring rules, a library of skills that apply them, and independent review of what they write.
+A spec is written in [\*\*\*plain](https://plainlang.org/docs/) - its documentation is the language's whole reference. Rendering turns a spec into code; authoring is the half that decides what gets built. The code is only ever as good as the spec - a fact in the wrong section is silently ignored, a functional spec that is too big comes out half-built, two specs that contradict each other break each other's tests. So this repo carries as much for writing specs as for rendering them: the authoring rules, a library of skills that apply them, and independent review of what they write.
 
-The rule underneath all of it: **\*\*\*plain is the source of truth**. The generated code in `plain_modules/` is never edited by hand. A bug is fixed in \*\*\*plain, and a change that is wanted goes into \*\*\*plain - that is what persists and what the next regeneration builds from.
+The rule underneath all of it: **the specs are the source of truth**. The generated code in `plain_modules/` is never edited by hand. A bug is fixed in the spec, and a change that is wanted goes into the spec - that is what persists and what the next render builds from.
 
 ## A \*\*\*plain project
 
@@ -16,7 +16,7 @@ my-project/
   plain_modules/       # generated - code, tests, history; never edited by hand
 ```
 
-## What \*\*\*plain is made of
+## What a spec is made of
 
 A `.plain` file is one module: optional YAML frontmatter, then up to four sections, in this order.
 
@@ -39,13 +39,13 @@ The frontmatter connects modules:
 | `exported_concepts` | which concepts a module that `requires` this one may use |
 | `required_concepts` | concepts an import module expects the importing module to define |
 
-Beyond that: \*\*\*plain links to files under `resources/` with markdown link syntax, and the file's contents go to the coding agents with the \*\*\*plain description; lines starting with `>` are comments for people; and files are processed with Liquid first, so a template can be included with parameters.
+Beyond that: a spec links to files under `resources/` with markdown link syntax, and the file's contents go to the renderer with the spec; lines starting with `>` are comments for people; and files are processed with Liquid first, so a template can be included with parameters.
 
-**Section ownership is the rule that bites.** turri reads each kind of fact only from the section that owns it. A tech choice written into a functional spec, or a behaviour written into the implementation reqs, is not flagged - it is simply not read.
+**Section ownership is the rule that bites.** The renderer reads each kind of fact only from the section that owns it. A tech choice written into a functional spec, or a behaviour written into the implementation reqs, is not flagged - it is simply not read.
 
 ## The standard library
 
-turri ships a standard library of import modules in `stdlib/` that settle everything about a generic piece of software on one stack except what it does: its language and framework, layout, configuration, error handling, logging, shutdown, and how it is unit and conformance tested. A module's \*\*\*plain imports one and writes only its own concepts and functional specs:
+turri ships a standard library of import modules in `stdlib/` that settle everything about a generic piece of software on one stack except what it does: its language and framework, layout, configuration, error handling, logging, shutdown, and how it is unit and conformance tested. A spec imports one and writes only its own concepts and functional specs:
 
 ```plain
 ---
@@ -82,19 +82,19 @@ It is built in three layers, and a stack imports the other two:
 
 Each conformance template imports its kind's `conformance/common`: a backend's tests start the built service on a free port and reach it over HTTP only, checking a failure by status and `error.code`; a frontend's run the served build in Chromium through Playwright with the backend stood in; a command-line tool's run the built tool as a process; a library's go through its public entry point.
 
-- **Conformance tests apart.** \*\*\*plain without the conformance template has no test reqs, so no conformance tests are written or run for it. Turning them on later is adding that one import.
-- **A reserved name.** An import that starts with `stdlib/` is always turri's template, never a file of the project's. A project with a module at such a path - `stdlib/backend/python-fastapi.plain` beside the project's \*\*\*plain, in its `template/` folder or in `PLAIN_TEMPLATE_DIRS` - gets an error saying the name is reserved, so which one the project's \*\*\*plain builds on never depends on what is on disk beside it.
-- **No concepts.** Its requirements are on the predefined `:Implementation:`, `:UnitTests:` and `:ConformanceTests:` only, so it never collides with \*\*\*plain's own definitions.
+- **Conformance tests apart.** A spec without the conformance template has no test reqs, so no conformance tests are written or run for it. Turning them on later is adding that one import.
+- **A reserved name.** An import that starts with `stdlib/` is always turri's template, never a file of the project's. A project with a module at such a path - `stdlib/backend/python-fastapi.plain` beside the spec, in its `template/` folder or in `PLAIN_TEMPLATE_DIRS` - gets an error saying the name is reserved, so which one a spec builds on never depends on what is on disk beside it.
+- **No concepts.** Its requirements are on the predefined `:Implementation:`, `:UnitTests:` and `:ConformanceTests:` only, so it never collides with a spec's own definitions.
 - **Pinned to a toolchain.** It names its stack's toolchain - Python 3.12, Node.js 24, Java 21, Go 1.25, Rust - which the agents use from this machine; `turri doctor` says when the machine lacks it.
 - **Not storage, not the testing scripts.** A module with a database says which on top of its stack. It still needs its unit testing script, and a conformance testing script when it has conformance tests.
-- **Known to the agents.** The `stdlib` rule, in the system prompt of every agent that writes \*\*\*plain, says when to import which, and lists every template with what it is and the folder it is in, read from `stdlib/` when the rules load. `spawn` and `brood` import a stack when the one chosen is in it, and its conformance template when conformance tests are on.
-- **Only what this machine can build.** The agents use this machine's toolchains and install none, so a Go stack on a laptop without Go stops at its first build. Every agent that writes \*\*\*plain, and the conversation, are told which of the standard library's languages the machine can build now - Python needs `uv`, TypeScript and every frontend `node` and `npm`, Go `go`, Rust `cargo`, Java a JDK (`src/stack.ts`, `toolchainsBlock`) - and `spawn` and `brood` offer, and choose, only stacks in those. A stack the person names in a language the machine lacks is not refused: they are told what to install first, and that `turri doctor` checks it.
+- **Known to the agents.** The `stdlib` rule, in every spec-writing agent's system prompt, says when to import which, and lists every template with what it is and the folder it is in, read from `stdlib/` when the rules load. `spawn` and `brood` import a stack when the one chosen is in it, and its conformance template when conformance tests are on.
+- **Only what this machine can build.** The agents use this machine's toolchains and install none, so a Go stack on a laptop without Go stops at its first build. Every spec-writing agent and the conversation are told which of the standard library's languages the machine can build now - Python needs `uv`, TypeScript and every frontend `node` and `npm`, Go `go`, Rust `cargo`, Java a JDK (`src/stack.ts`, `toolchainsBlock`) - and `spawn` and `brood` offer, and choose, only stacks in those. A stack the person names in a language the machine lacks is not refused: they are told what to install first, and that `turri doctor` checks it.
 
 A requirement beyond the stack - storage, an outside service - is added on top of it. A module that differs from its stack on something the stack settles - another framework, another layout - writes its own instead: an import cannot be taken back in part.
 
 ## The rules
 
-`genome/rules/` holds the authoring rules. They are in the system prompt of every agent that writes \*\*\*plain - the conversation, the interview skills, the reviewers - so they are not something an agent has to decide to go and read.
+`genome/rules/` holds the authoring rules. They are in the system prompt of every agent that writes specs - the conversation, the interview skills, the reviewers - so they are not something an agent has to decide to go and read.
 
 | rule | covers |
 | --- | --- |
@@ -103,40 +103,40 @@ A requirement beyond the stack - storage, an outside service - is added on top o
 | `func-specs.md` | voice, the complexity limit, chronological order, no conflicts, language agnosticism, testability, acceptance tests |
 | `impl-reqs.md` | HOW not WHAT, unit tests live here, what belongs and what does not |
 | `test-reqs.md` | conformance tests only, what belongs, test types |
-| `concise-specs.md` (+ two example banks) | keeping \*\*\*plain short enough for a person to review: no obvious lines, plain words, no uncheckable adjectives, no hedging |
+| `concise-specs.md` (+ two example banks) | keeping specs short enough for a person to review: no obvious lines, plain words, no uncheckable adjectives, no hedging |
 | `bullet-continuation.md` | bullets and continuation lines in every section |
 | `linked-resources.md` | a linked resource is one text file on disk, or a PNG or JPEG image for a model that reads images; protocol artifacts are linked, never transcribed |
 | `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) | \*\*\*plain for REST API integrations, deployed standalone or embedded in an existing codebase |
-| `turri-regeneration.md` | turri's model of itself: a \*\*\*plain change regenerated as a \*\*\*plain 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 \*\*\*plain is placed by what it means, never to spare regeneration |
+| `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 \*\*\*plain most:
+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 regenerated on top of the ones before it - which is what a functional spec may assume, not what a change costs: a functional spec inserted anywhere is regenerated alone.
+- **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 fact or cut the word.
-- **No two functional specs contradict each other.** A conflict is found and resolved when a functional spec is added, not when its tests fail.
+- **No two specs contradict each other.** A conflict is found and resolved when a spec is added, not when its tests fail.
 
-## Writing \*\*\*plain with turri
+## Writing specs with turri
 
-In a conversation (`turri`), say what you want and the matching skill runs - but the three that start a project or a feature you start yourself, by their commands: `/brood`, `/spawn` or `/bud`, with what you want after it. Two build a project from scratch, and write each \*\*\*plain change as a git diff that is built in the background the moment it is written. `brood` interviews you one question at a time and writes \*\*\*plain as you answer; `spawn`, its quick twin, gets something running as soon as it can - the smallest thing that runs first, then the product a slice at a time - asking only what your message leaves open:
+In a conversation (`turri`), say what you want and the matching skill runs - but the three that start a project or a feature you start yourself, by their commands: `/brood`, `/spawn` or `/bud`, with what you want after it. Two build a project from scratch, and write each spec change as a git diff that is built in the background the moment it is written. `brood` interviews you one question at a time and writes the specs as you answer; `spawn`, its quick twin, gets something running as soon as it can - the smallest thing that runs first, then the product a slice at a time - asking only what your message leaves open:
 
-| skill | phases | how a \*\*\*plain change is written |
+| skill | phases | how a spec change is written |
 | --- | --- | --- |
-| `brood` | intent → stack → testing → product, feature by feature | first, how many questions the stack and product phases may ask - light 3, medium 5, thorough 10 or best judgement, broader with fewer, covering the same ground - and what they leave open turri decides itself, each decision a \*\*\*plain change of its own; every product answer is still a \*\*\*plain change, built before the next question; in testing, whether there are conformance tests, their `***test reqs***` and script - written as files, building nothing; then one \*\*\*plain change per answer, across whatever sections it needs, as a git diff with `change_plain`, regenerated as a \*\*\*plain diff pulse and conformance tested as it is built |
-| `spawn` | start → skeleton → regenerate | built for the time to first regeneration: what to build is asked only when the message does not say, and the stack only when the user named one this machine cannot build - otherwise turri chooses one; the stack and the unit tests are written as files, with conformance tests off unless the user asks for them; then a \*\*\*plain change for the smallest thing that runs starts the first build - a module's first pulse of one functional spec is not reviewed - and the main slice of what the user described and at most one more follow - none when they described no feature, and never one of turri's own - each a functional spec on its happy path, as git diffs with `change_plain`, one after another with no answer between them. The rest - the next slices, then validation and edge cases as changes to those functional specs - is asked for in the conversation once the user has tried what landed: `go on` for the next slice it proposed |
+| `brood` | intent → stack → testing → product, feature by feature | first, how many questions the stack and product phases may ask - light 3, medium 5, thorough 10 or best judgement, broader with fewer, covering the same ground - and what they leave open turri decides itself, each decision a spec change of its own; every product answer is still a spec change, built before the next question; in testing, whether there are conformance tests, their `***test reqs***` and script - written as files, building nothing; then one spec change per answer, across whatever sections it needs, as a git diff with `write_spec_diff`, rendered as a render spec diff job and conformance tested as it is built |
+| `spawn` | start → skeleton → regenerate | built for the time to first regeneration: what to build is asked only when the message does not say, and the stack only when the user named one this machine cannot build - otherwise turri chooses one; the stack and the unit tests are written as files, with conformance tests off unless the user asks for them; then a spec change for the smallest thing that runs starts the first build - a module's first pulse of one functional spec is not reviewed - and the main slice of what the user described and at most one more follow - none when they described no feature, and never one of turri's own - each a functional spec on its happy path, as git diffs with `write_spec_diff`, one after another with no answer between them. The rest - the next slices, then validation and edge cases as changes to those specs - is asked for in the conversation once the user has tried what landed: `go on` for the next slice it proposed |
 
-`mature` starts from \*\*\*plain you already have, rough or hand-written, and runs on its own until it is fully regenerated - every functionality built from \*\*\*plain as it stands, its tests passing. It regenerates what is not built and watches the agents building it; when one struggles on something \*\*\*plain leaves open or unclear - sent back again and again, the judge going back and forth, a \*\*\*plain conflict - it writes what \*\*\*plain should say as a \*\*\*plain diff, stops that build, and regenerates it again. What the builds had to decide themselves - their assumptions, pitfalls, a failed build's diagnosis - goes into \*\*\*plain the same way, when a user, a caller or a test can see it. It never asks: it takes the reading that fits the rest of the \*\*\*plain description, and marks each such decision in its report. It leaves code, environment and turri problems to the builds, and stops when a functionality keeps struggling after its \*\*\*plain was clarified, when two cycles change nothing, or after twenty.
+`mature` starts from a spec you already have, rough or hand-written, and runs on its own until it is fully rendered - every functionality built from the spec as it stands, its tests passing. It renders what is not built and watches the agents building it; when one struggles on something the spec leaves open or unclear - sent back again and again, the judge going back and forth, a spec conflict - it writes what the spec should say as a spec diff, stops that build, and renders it again. What the builds had to decide themselves - their assumptions, pitfalls, a failed build's diagnosis - goes into the spec the same way, when a user, a caller or a test can see it. It never asks: it takes the reading that fits the rest of the spec, and marks each such decision in its report. It leaves 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. 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 \*\*\*plain change, a git diff written with `change_plain` and built the moment it is written, before the next question. What the questions leave open it decides itself, a \*\*\*plain change each. A change to something already specified, built or still to build, is put to the user first and is a \*\*\*plain diff too: what is left to build is worked out again from \*\*\*plain. It ends on the person's confirmation of a short summary of the feature's changes.
+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. 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 \*\*\*plain change.
-- **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 \*\*\*plain change - see [skills and gates](skills-and-gates.md).
+- **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 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.
 
 ## The skills
@@ -146,21 +146,21 @@ Every skill in `genome/skills/` can be run from a conversation; most are also us
 | to… | skills |
 | --- | --- |
 | start a project | `brood`, `spawn`, `init-plain-project` |
-| make rough \*\*\*plain build | `mature` |
-| add to \*\*\*plain | `bud`, `add-functional-spec`, `add-functional-specs`, `add-concept`, `add-implementation-requirement`, `add-test-requirement`, `add-acceptance-test`, `add-resource`, `add-template` |
+| make a rough spec build | `mature` |
+| add to a spec | `bud`, `add-functional-spec`, `add-functional-specs`, `add-concept`, `add-implementation-requirement`, `add-test-requirement`, `add-acceptance-test`, `add-resource`, `add-template` |
 | check what is written | `analyze-if-func-spec-too-complex`, `analyze-2-func-specs`, `analyze-func-specs`, `resolve-section-ownership` |
 | fix what is written | `break-down-func-spec`, `resolve-spec-conflict`, `debug-specs` |
 | restructure modules | `create-import-module`, `create-requires-module`, `refactor-module`, `consolidate-concepts` |
 | set up the project to build | `implement-unit-testing-script`, `implement-conformance-testing-script`, `check-plain-env` |
 
-`debug-specs` is the one for a running application that misbehaves: it reads the generated code to find the cause, traces it back to \*\*\*plain, and fixes only the `.plain` files.
+`debug-specs` is the one for a running application that misbehaves: it reads the generated code to find the cause, traces it back to the spec, and fixes only the `.plain` files.
 
-## Checking \*\*\*plain
+## Checking a spec
 
 ```bash
 turri validate app.plain     # or validate in a conversation
 ```
 
-It parses \*\*\*plain with this repo's own parser, resolves its imports and required modules, and reports every syntax, concept and structure error with its line - no model, no API key. The interview skills run it before a phase ends, and `change_plain` refuses a change that leaves a file that does not parse. Pass the project directory to check every module at once.
+It parses the spec with this repo's own parser, resolves its imports and required modules, and reports every syntax, concept and structure error with its line - no model, no API key. The interview skills run it before a phase ends, and `write_spec_diff` refuses a change that leaves a file that does not parse. Pass the project directory to check every module at once.
 
-What `check` cannot see - a fact in the wrong section, a functional spec that is too big, two that conflict, wording no test can check - is what the rules, the skills and the reviewers are for.
+What `check` cannot see - a fact in the wrong section, a spec that is too big, two that conflict, wording no test can check - is what the rules, the skills and the reviewers are for.