@turri-dev/cli 0.1.7-next.f0d55df → 0.1.8-next.bcca62a

package/dist/regenerate/loop.js

@@ -5,11 +5,11 @@ import { STDLIB_ROOT } from "../plain/stdlib.js";
 import { ACCEPTANCE_TESTS, FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS, TEST_REQUIREMENTS } from "../plain/spec.js";
 import { reportActivity, reportStage } from "./activity.js";
 import { llmChunkAgents, MAX_LINES_PER_JOB, MAX_SPECS_PER_JOB, planChunks, stepsOf } from "./chunk-plan.js";
-import { commitNotes, recordHistory, resetToLastCommit } from "./lineage.js";
+import { commitNotes, landWork, recordHistory, resetToLastCommit } from "./lineage.js";
 import { NOTES_FILE, recordPulse } from "./notes.js";
 import { createJobRegistry, formatDuration } from "./jobs.js";
 import { moduleLanes } from "./lanes.js";
-import { adoptDigests, chainTree, codeTree, conformanceTarget, REGENERATE_AGAIN, inheritedRecord, notBuilt, readRecord, RECORD_FILE, withResourceDigests, writeCodeRecord, writeTestsRecord, } from "./records.js";
+import { adoptDigests, chainTree, codeTree, conformanceTarget, marksRegenerateAgain, REGENERATE_AGAIN, inheritedRecord, notBuilt, readRecord, RECORD_FILE, withResourceDigests, writeCodeRecord, writeTestsRecord, } from "./records.js";
 import { describeSpecDiffConformance, renderSpecDiffConformance } from "./conform.js";
 import { conformanceDirFor } from "./conformance.js";
 import { modulesRoot } from "./paths.js";
@@ -153,7 +153,8 @@ export function functionalityCompletion(plainFile) {
         codebase.forEach((entry, index) => {
             const count = counts[index];
             const completed = entry.frids.filter((frid) => !touched.has(`${entry.moduleName}:${frid}`));
-            const tested = (readRecord(conformanceDirFor(entry.moduleName, modulesRoot(projectDirOf(entry.plainFile))))?.[FUNCTIONAL_REQUIREMENTS] ?? []).filter((item) => item.frid !== undefined && item.markdown.trim() === specText(entry.moduleName, item.frid));
+            // Tests marked to regenerate again were written against code since replaced: not conformance tested until rewritten.
+            const tested = (readRecord(conformanceDirFor(entry.moduleName, modulesRoot(projectDirOf(entry.plainFile))))?.[FUNCTIONAL_REQUIREMENTS] ?? []).filter((item) => item.frid !== undefined && !marksRegenerateAgain(item) && item.markdown.trim() === specText(entry.moduleName, item.frid));
             count.completed = completed.length;
             count.tested = completed.filter((frid) => tested.some((item) => item.frid === frid));
             count.conformanceTested = count.tested.length;
@@ -521,7 +522,7 @@ export function createWorkLoop(options) {
             run: async (onDelta) => {
                 // The guardrail: a conformance job tests only code that is built - the code record, read as the job starts, has every functional spec it tests as it tests it.
                 if (conformance) {
-                    const testing = [...planned.cases.add, ...planned.cases.patch].map((touched) => touched.frid);
+                    const testing = [...planned.cases.add, ...planned.cases.patch, ...planned.cases.again].map((touched) => touched.frid);
                     const missing = notBuilt(readRecord(tip.buildDir), planned.step.tree, testing);
                     if (missing.length > 0) {
                         const record = relative(options.cwd, join(tip.buildDir, RECORD_FILE));
@@ -1109,6 +1110,17 @@ export function createWorkLoop(options) {
                     found.add(frid);
                 const marked = items.map((item, index) => (frids.includes(named(item, index)) ? { ...item, [REGENERATE_AGAIN]: true } : item));
                 writeCodeRecord(tip.buildDir, { ...record, [section]: marked });
+                // Its conformance tests were written against the code being replaced: marked with it, they are written again -
+                // checked against the new code, and rewritten where they relied on what the old code chose - once it lands.
+                if (section === FUNCTIONAL_REQUIREMENTS) {
+                    const testsDir = conformanceDirFor(tip.moduleName, modulesRoot(projectDirOf(tip.plainFile)));
+                    const tests = readRecord(testsDir);
+                    const tested = tests?.[FUNCTIONAL_REQUIREMENTS] ?? [];
+                    if (tested.some((item) => item.frid !== undefined && taken.includes(item.frid))) {
+                        const again = tested.map((item) => (item.frid !== undefined && taken.includes(item.frid) ? { ...item, [REGENERATE_AGAIN]: true } : item));
+                        writeTestsRecord(testsDir, { ...tests, [FUNCTIONAL_REQUIREMENTS]: again });
+                    }
+                }
                 recordHistory(tip.buildDir, `${module} functional spec${taken.length === 1 ? "" : "s"} ${taken.join(", ")} to regenerate again`);
             }
             const missing = frids.filter((frid) => !found.has(frid));
@@ -1596,10 +1608,18 @@ const defaultConformanceRunner = async (job, onDelta) => {
     });
     if (result.passed) {
         writeTestsRecord(result.conformanceDir, job.planned.step.tree);
-        recordHistory(job.buildDir, `conformance tests: ${job.planned.title}`);
+        landWork(job.buildDir, `conformance tests: ${job.planned.title}`);
     }
     return { landed: result.passed, report: describeSpecDiffConformance(result), ...(result.specGaps !== undefined ? { specGaps: result.specGaps } : {}) };
 };
+/**
+ * A module's first pulse when it builds one functional spec - the project set up and the smallest thing that runs: it lands on its
+ * unit tests alone, with no review. A reviewer, and an arbiter after it, on a scaffold is time spent before anything can
+ * be tried.
+ */
+export function skipsReview(cases) {
+    return cases.fresh && cases.add.length <= 1 && cases.patch.length === 0 && cases.again.length === 0 && cases.delete.length === 0;
+}
 /** A job as a spec diff render, landed on its unit tests: conformance is a track of its own. */
 const defaultRunner = async (job, onDelta) => {
     const result = await renderSpecDiff({
@@ -1609,6 +1629,7 @@ const defaultRunner = async (job, onDelta) => {
         applied: "already applied",
         spec: job.spec,
         cases: job.planned.cases,
+        ...(skipsReview(job.planned.cases) ? { unitReview: false } : {}),
         ...(job.model !== undefined ? { model: job.model } : {}),
         ...(job.steering !== undefined ? { steering: job.steering } : {}),
         onDelta,

package/dist/regenerate/records.d.ts

@@ -63,9 +63,11 @@ export type Chosen = (frid: string) => boolean;
  * definitions and implementation reqs, with the test reqs as the spec has them now.
  *
  * Conformance follows the code, never goes ahead of it: a functional spec whose code is not caught up
- * with the spec - its text in the code record is not the spec's, or the code record does not have it at
- * all, as while it is regenerated again - stays as the tests record has it, until the code lands. Its tests are
- * taken out only once the spec and the code have both dropped it.
+ * with the spec - its text in the code record is not the spec's, the code record does not have it at
+ * all, or has it marked to regenerate again - stays as the tests record has it, until the code lands. Its tests are
+ * taken out only once the spec and the code have both dropped it. Tests marked to regenerate again with their code
+ * (`regenerateAgain`) differ from the target once the code lands: written against the code it replaced, they are
+ * conformance work again, though the spec's text never changed.
  */
 export declare function conformanceTarget(code: MarshalledPlainSource | null, tests: MarshalledPlainSource | null, spec: MarshalledPlainSource, chosen?: Chosen): MarshalledPlainSource;
 /**

package/dist/regenerate/records.js

@@ -155,9 +155,11 @@ export function inheritedRecord(source, sourceModule) {
  * definitions and implementation reqs, with the test reqs as the spec has them now.
  *
  * Conformance follows the code, never goes ahead of it: a functional spec whose code is not caught up
- * with the spec - its text in the code record is not the spec's, or the code record does not have it at
- * all, as while it is regenerated again - stays as the tests record has it, until the code lands. Its tests are
- * taken out only once the spec and the code have both dropped it.
+ * with the spec - its text in the code record is not the spec's, the code record does not have it at
+ * all, or has it marked to regenerate again - stays as the tests record has it, until the code lands. Its tests are
+ * taken out only once the spec and the code have both dropped it. Tests marked to regenerate again with their code
+ * (`regenerateAgain`) differ from the target once the code lands: written against the code it replaced, they are
+ * conformance work again, though the spec's text never changed.
  */
 export function conformanceTarget(code, tests, spec, chosen = () => true) {
     const built = itemsOf(code, FUNCTIONAL_REQUIREMENTS);
@@ -168,7 +170,7 @@ export function conformanceTarget(code, tests, spec, chosen = () => true) {
     for (let index = 0; index < Math.max(built.length, now.length); index += 1) {
         const frid = String(index + 1);
         const current = now[index];
-        if (current !== undefined && built[index]?.markdown.trim() === current.markdown.trim()) {
+        if (current !== undefined && built[index]?.markdown.trim() === current.markdown.trim() && !marksRegenerateAgain(built[index])) {
             if (chosen(frid))
                 specs.push({ ...current, frid });
             continue;

package/dist/regenerate/regenerate.js

@@ -11,7 +11,7 @@ import { debugFailure, diagnosisText } from "./debugger.js";
 import { codebaseMap, diffFiles, digestFiles, wroteNothing } from "./codebase.js";
 import { confinedTools } from "./confine.js";
 import { buildSpecDiffPrompt, describeSpecChange, reviewedSpec, sectionModules } from "./prompt.js";
-import { abandonWork, recordHistory, startWork } from "./lineage.js";
+import { abandonWork, landWork, startWork } from "./lineage.js";
 import { createWorkLedger, SUBMIT_WORK_NOTE } from "./submit-work.js";
 import { CODER_COMPACTION } from "./compaction.js";
 import { gapMark, gapsSince, NOTES_TURN, notesForSession, passedOutcome, recordNote, withNotes } from "./notes.js";
@@ -193,7 +193,7 @@ export async function renderSpecDiff(options) {
     if (builtBefore !== null && sameSpec(builtBefore, tree) && !dryRun) {
         stage("the specs were only restructured - nothing to render; recording the spec as it is now laid out");
         writeCodeRecord(tip.buildDir, tree);
-        recordHistory(tip.buildDir, `spec restructured: ${summarizeDiff(options.diff)}`, options.diff);
+        landWork(tip.buildDir, `spec restructured: ${summarizeDiff(options.diff)}`, options.diff);
         return {
             moduleName,
             buildDir: tip.buildDir,
@@ -554,7 +554,7 @@ export async function renderSpecDiff(options) {
         stage("recording what the code is built from, and committing it");
         // Steered, it is built from the spec as it was steered to - the record the loop moved with it.
         writeCodeRecord(buildDir, steering?.target ?? tree);
-        recordHistory(buildDir, `spec diff: ${summarizeDiff(options.diff)}`, options.diff);
+        landWork(buildDir, `spec diff: ${summarizeDiff(options.diff)}`, options.diff);
     };
     if (!unitPassed) {
         stage(unitReviewStopped ? "the unit tests pass but still leave the change untested - undoing the change" : "unit tests NOT passing - undoing the change");

package/dist/regenerate/regression.js

@@ -6,7 +6,7 @@ import { reportActivity, reportStage, unitOf } from "./activity.js";
 import { confinedTools } from "./confine.js";
 import { projectRootOf } from "./paths.js";
 import { buildRegressionFixPrompt, sectionModules } from "./prompt.js";
-import { abandonWork, markWork, recordHistory } from "./lineage.js";
+import { abandonWork, landWork, markWork } from "./lineage.js";
 import { missingToolchainError } from "./environment-error.js";
 import { workspaceBlock } from "./workspace.js";
 import { CODER_COMPACTION } from "./compaction.js";
@@ -154,7 +154,7 @@ export async function ensureRegressionPasses(input) {
         if (passing) {
             reportStage(`${unitOf(input.moduleName)}: the whole conformance suite passes, and the unit tests with it${repairs.length > 0 ? ` after ${repairs.length} repair${repairs.length === 1 ? "" : "s"}` : ""}`);
             if (repairs.length > 0) {
-                recordHistory(input.buildDir, `regression ${input.moduleName} (pass after ${repairs.length} repair(s))`);
+                landWork(input.buildDir, `regression ${input.moduleName} (pass after ${repairs.length} repair(s))`);
             }
             return { passed: true, runs, repairs, command };
         }

package/dist/regenerate/spec-map.js

@@ -8,7 +8,7 @@ import { conformanceDirFor } from "./conformance.js";
 import { chainSpec } from "./loop.js";
 import { modulesRoot, projectDirOf } from "./paths.js";
 import { HISTORY_DIR } from "./lineage.js";
-import { codeTree, readRecord, RECORD_FILE } from "./records.js";
+import { codeTree, marksRegenerateAgain, readRecord, RECORD_FILE } from "./records.js";
 import { specFilesOf } from "./regenerate.js";
 import { builtTips, resolveRequiresChain } from "./requires.js";
 import { changesBetween, layoutOf, serializeTree } from "./spec-steps.js";
@@ -115,17 +115,20 @@ export function pageItems(input) {
         }
     }
     // Conformance tests: of the functional specs, those the tests record has as they read now, as they read before, or taken out.
-    const tested = new Set(itemsOf(input.tested ?? null, FUNCTIONAL_REQUIREMENTS).map((item) => item.markdown.trim()));
+    // Tests marked to regenerate again were written against code since replaced: written for an earlier build, not now.
+    const testedItems = itemsOf(input.tested ?? null, FUNCTIONAL_REQUIREMENTS);
+    const tested = new Set(testedItems.filter((item) => !marksRegenerateAgain(item)).map((item) => item.markdown.trim()));
+    const replaced = new Set(testedItems.filter((item) => marksRegenerateAgain(item)).map((item) => item.markdown.trim()));
     for (const item of items) {
-        if (item.section !== FUNCTIONAL_REQUIREMENTS || tested.size === 0)
+        if (item.section !== FUNCTIONAL_REQUIREMENTS || testedItems.length === 0)
             continue;
         if (item.state === "removed") {
-            if (tested.has(item.text.trim()))
+            if (tested.has(item.text.trim()) || replaced.has(item.text.trim()))
                 item.tests = "removed";
         }
         else if (tested.has(item.text.trim()))
             item.tests = "now";
-        else if (item.was !== undefined && tested.has(item.was.trim()))
+        else if (replaced.has(item.text.trim()) || (item.was !== undefined && (tested.has(item.was.trim()) || replaced.has(item.was.trim()))))
             item.tests = "older";
     }
     return keyed(items);

package/dist/run-report.d.ts

@@ -1,4 +1,4 @@
-import type { Job } from "./regenerate/jobs.ts";
+import { type Job } from "./regenerate/jobs.ts";
 /**
  * A headless run's report: one JSON file, `turri regenerate --report <file>`, saying what the run did - how it ended,
  * what it spent, which pulses landed, how many functional specs are completed - for a benchmark or CI to read rather

package/dist/run-report.js

@@ -2,6 +2,7 @@ import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { turriIdentity } from "./environment.js";
 import { onModelEvent } from "./regenerate/activity.js";
+import { firstRegeneration } from "./regenerate/jobs.js";
 /**
  * A headless run's report: one JSON file, `turri regenerate --report <file>`, saying what the run did - how it ended,
  * what it spent, which pulses landed, how many functional specs are completed - for a benchmark or CI to read rather
@@ -177,7 +178,12 @@ export function startRunReport(options) {
             };
         });
         const ran = list.filter((pulse) => pulse.status !== "queued");
+        const first = firstRegeneration(jobs, startedAt);
+        const seconds = (ms) => (ms !== undefined ? Math.round(ms / 100) / 10 : null);
         return {
+            // The time to first regeneration - the first code pulse started - and to the first one landed, from the run's start.
+            first_started_seconds: seconds(first.started),
+            first_landed_seconds: seconds(first.landed),
             counts: {
                 total: ran.length,
                 landed: ran.filter((pulse) => pulse.landed).length,

package/dist/self-invocation.d.ts

@@ -20,6 +20,6 @@ export declare function selfInvocation(command: string): string | undefined;
  */
 export declare function askedForCommandLine(message: string): boolean;
 /** What the agent is told when the call is refused. */
-export declare function refusal(what: string): string;
+export declare function refusal(what: string, surface?: string): string;
 /** The instruction that goes into the conversation's system prompt. */
 export declare const TOOLS_NOT_CLI: string;

package/dist/self-invocation.js

@@ -88,12 +88,13 @@ export function askedForCommandLine(message) {
         /(^|\s)pi\s+-p\b/.test(text));
 }
 /** What the agent is told when the call is refused. */
-export function refusal(what) {
+export function refusal(what, surface) {
     const instead = what === "pi"
         ? "Do not start another agent: do the work here, with this conversation's tools."
         : `Use ${TOOL_FOR[what] ?? "the matching turri tool"} instead.`;
     return (`Not run: that starts turri${what === "pi" ? "'s agent" : ` ${what}`} again from the shell - a separate, headless ` +
-        "run outside this conversation, its jobs, the panel and /halt. " +
+        // In a host there is no panel: the person watches the pulses where its surface says.
+        (surface !== undefined ? "run outside this conversation and its pulses, where the person can neither watch it nor halt it. " : "run outside this conversation, its jobs, the panel and /halt. ") +
         `${instead} Run turri from the command line only when the user asks for that.`);
 }
 /** The instruction that goes into the conversation's system prompt. */

package/dist/skill-progress.d.ts

@@ -6,7 +6,7 @@
  *   brood       ✓ intent ━━━━ ⠋ stack ──── ○ testing ──── ○ product       phase 2 of 4
  *                 stack - the language, frameworks, storage and architecture
  *
- * The second line says what the phase it is in does: a phase's name alone - `groundwork` - says little to someone
+ * The second line says what the phase it is in does: a phase's name alone - `skeleton` - says little to someone
  * who has not read the skill.
  *
  * A skill of one phase, or none, has nothing to be partway through: its line is the spinner and its name alone.

package/dist/skill.d.ts

@@ -85,6 +85,11 @@ export interface Skill {
      * last answer is written with `write_spec_diff`, and changes the agent decides itself need no answer before them.
      */
     diffPerAnswer: string[];
+    /**
+     * Started only by the person, with its slash command - `/brood` - never by the model on its own
+     * (`metadata.command-only: true`): cultivate runs it only when the person has just typed its command.
+     */
+    commandOnly: boolean;
 }
 export declare function loadSkill(skillDir: string): Skill;
 export declare function readRubric(skill: Skill, review: {

package/dist/skill.js

@@ -131,6 +131,7 @@ export function loadSkill(skillDir) {
         paced: data.metadata?.paced !== false,
         questioning: capped,
         diffPerAnswer,
+        commandOnly: data.metadata?.["command-only"] === true,
     };
 }
 export function readRubric(skill, review) {

package/dist/skills.d.ts

@@ -28,3 +28,17 @@ export declare function discoverSkills(packageRoot: string, projectDir: string |
 export declare function catalogueLine(skill: FoundSkill): string;
 /** What is said under the list about the skills it leaves out. */
 export declare function leftOutNote(catalogue: SkillCatalogue): string;
+/**
+ * Which skills cultivate may start now. A skill marked command-only (`/brood`) waits for the person to type its command:
+ * the command lets it start once, and the run starting uses that up - the model cannot start it again later on its own.
+ */
+export declare function createCommandGate(): {
+    /** The person typed the skill's command. */
+    typed(name: string): void;
+    /** Whether cultivate may start it now. */
+    mayStart(skill: Pick<FoundSkill, "name" | "commandOnly">): boolean;
+    /** Its run started: the command is used up. */
+    started(name: string): void;
+};
+/** What cultivate says of a command-only skill the person did not start. */
+export declare function startedByCommandOnly(name: string): string;

package/dist/skills.js

@@ -61,7 +61,9 @@ export function discoverSkills(packageRoot, projectDir) {
 /** A skill's line in cultivate's list: a project's says so, and where it is. */
 export function catalogueLine(skill) {
     const whose = skill.origin === "turri" ? "" : ` (this project's, ${skill.origin.project})`;
-    return `- ${skill.name}${whose}: ${skill.description}`;
+    // One the person starts themselves: the model points them to its command rather than running it.
+    const byCommand = skill.commandOnly ? ` Started only by the person, with /${skill.name}: never run it unasked - when it fits, tell them to type /${skill.name}.` : "";
+    return `- ${skill.name}${whose}: ${skill.description}${byCommand}`;
 }
 /** What is said under the list about the skills it leaves out. */
 export function leftOutNote(catalogue) {
@@ -72,3 +74,19 @@ export function leftOutNote(catalogue) {
         .map((line) => `\n\n${line}`)
         .join("");
 }
+/**
+ * Which skills cultivate may start now. A skill marked command-only (`/brood`) waits for the person to type its command:
+ * the command lets it start once, and the run starting uses that up - the model cannot start it again later on its own.
+ */
+export function createCommandGate() {
+    const typed = new Set();
+    return {
+        typed: (name) => void typed.add(name),
+        mayStart: (skill) => !skill.commandOnly || typed.has(skill.name),
+        started: (name) => void typed.delete(name),
+    };
+}
+/** What cultivate says of a command-only skill the person did not start. */
+export function startedByCommandOnly(name) {
+    return `Not started: ${name} is started only by the person, with /${name}. If it fits what they want, tell them to type /${name} - with what they want after it, if they like.`;
+}

package/dist/surface.d.ts

@@ -0,0 +1,5 @@
+import type { JobRegistry } from "./regenerate/jobs.ts";
+/** The host's surface for the conversation these jobs are: blank or undefined is the terminal. */
+export declare function setSurface(jobs: JobRegistry, surface: string | undefined): void;
+/** The host's surface, in its own words - undefined in the terminal. */
+export declare function surfaceOf(jobs: JobRegistry | undefined): string | undefined;

package/dist/surface.js

@@ -0,0 +1,18 @@
+/**
+ * Where the person sees turri's work: the terminal - regen, its keys, /pulses - unless a host that runs the conversation
+ * itself describes its own (TurriHost.surface). Kept with the conversation's job registry, so what is told the model
+ * deep in a tool - a pulse not found - says the host's words and not the terminal's.
+ */
+const surfaces = new WeakMap();
+/** The host's surface for the conversation these jobs are: blank or undefined is the terminal. */
+export function setSurface(jobs, surface) {
+    const text = surface?.trim() ?? "";
+    if (text !== "")
+        surfaces.set(jobs, text);
+    else
+        surfaces.delete(jobs);
+}
+/** The host's surface, in its own words - undefined in the terminal. */
+export function surfaceOf(jobs) {
+    return jobs !== undefined ? surfaces.get(jobs) : undefined;
+}

package/docs/authoring-plain.md

@@ -122,12 +122,12 @@ The ones that shape a spec most:
 
 ## Writing specs with turri
 
-In a conversation (`turri`), say what you want and the matching skill runs. 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, asks only what you want to build and which stack - or leaves the stack to it - and writes the rest on its own:
+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 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 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` | intent → groundwork → product | only the intent and the stack are asked - the stack one question, `You choose` first, skipped when the user named one; the stack and the unit tests are written as files, with conformance tests off unless the user asks for them; then one spec change per feature, in build order, as a git diff with `write_spec_diff`, one after another with no answer between them. Changes after it are asked for in the conversation, as spec diffs, and what is left to build is worked out again from the spec |
+| `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 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.
 

package/docs/config.md

@@ -82,7 +82,7 @@ models:                              # each agent role's model, thinking and tur
 | `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` |
 | `conformance-budget` | under `conformance-tests: chosen` or `module`: how many of a module's functional specs may be chosen for conformance tests, beside those with acceptance tests - a count (`2`) or a share of its functional specs (`30%`, rounded up, at least one). Every choice for the module counts, whenever it was made; the chooser is told what is left, and can choose no more. Your own `conform` is not limited. A stack's `config.turri.<stack>.yaml` can set its own | no limit |
-| `review` | `true` or `false`: whether the code and its unit tests - and the conformance tests - are reviewed once they pass: two reviews at most, the second weighed by the arbiter; off, a job lands once its tests pass - see [regenerating the code](regenerating.md#the-code-and-its-unit-tests-are-reviewed) | `false` |
+| `review` | `true` or `false`: whether the code and its unit tests - and the conformance tests - are reviewed once they pass: two reviews at most, the second weighed by the arbiter; off, a job lands once its tests pass. A module's first pulse of one functional spec - the project set up and the smallest thing that runs - lands on its unit tests with no review - see [regenerating the code](regenerating.md#the-code-and-its-unit-tests-are-reviewed) | `false` |
 | `mutation-testing` | `true` or `false`: whether the coding agent and the reviewer have `can_it_fail` - one change put in the code for one run of the unit testing script, to see that a test catches it; on a copy of the code, or in place and put back after the run (see [regenerating the code](regenerating.md#checking-its-own-work)). `turri regenerate --mutation-testing false` for one run | `true` |
 | `rules-off` | a list of rule names - `integrations`, `concise-specs`, the files of `genome/rules/` without `.md` - left out of the conversation's prompt and every spec-writing agent's: a rule this project's own skills or AGENTS.md replace, such as one that says to probe a live API before any spec is written. The project's alone | none |
 | `allow-to-stop-jobs` | `true` or `false`: whether turri stops a running job the spec has moved on from - a functional spec it regenerates changed, or a file one links was edited - rolls it back and regenerates the spec as it now is. `false`: the job runs to its end and lands, and what changed since is regenerated on top of it by the next job - see [regenerating the code](regenerating.md). Your own `halt` stops a job either way | `true` |

package/docs/headless.md

@@ -134,6 +134,8 @@ A module that `requires` others is built in its own codebase on top of theirs: t
     "by_pulse_kind": { "code": { }, "conformance": { } }
   },
   "pulses": {
+    "first_started_seconds": 41.2,   // the time to first regeneration: the first code pulse started - null before
+    "first_landed_seconds": 233.9,   // the first code pulse landed: something to try - null before
     "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": "…",
@@ -170,6 +172,8 @@ A module that `requires` others is built in its own codebase on top of theirs: t
 
 **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.
 
+**Time to first regeneration.** `pulses.first_started_seconds` is how long after the run started its first code pulse started - planning the work, and any wait for a free slot, before it - and `first_landed_seconds` how long until the first one landed, when there is first something to try. Both are `null` until it happens. In the chat, `spawn` and the other skills that write spec diffs say the same in their result, counted from when the skill began.
+
 **Spec gaps.** A behaviour the spec leaves open that an agent met and decided on its own - reported with `report_spec_gap` (see [regenerating](regenerating.md)). In the chat they are put to you as the pulse ends; a headless run has no one to ask, so they are listed here, in the order the pulses started, and printed under the pulse that met them. `assumption` is what the agent decided meanwhile, also in the codebase's notes' assumptions while its pulse is `landed`; a pulse rolled back takes it out of the notes, but the question still stands. Settle the ones you care about in the spec and run again.
 
 **Turn incidents.** Each time the model provider failed for a moment and pi or turri waited it out before trying the request again, each time the provider sent nothing back on a request for two minutes, and each turn turri stopped itself - an agent going round in a circle, its calls failing again and again, its time up - after which the run carried on. The provider failing or stalling is printed as it happens, in orange, under the pulse; a stop is the work's normal course and is only listed. They are counted in the usage as `provider_retries`, `provider_stalls` and `turns_stopped`. Many of any point at the model, not the spec: a provider at its limits, or a model too small for the role it was given.

package/docs/hosting.md

@@ -35,6 +35,8 @@ const loader = new pi.DefaultResourceLoader({
       onJobChange: (job) => {},    // a job started, moved on, did something, or ended
       onPlanChange: () => {},      // what is planned changed with no job
       dialogs: { select, input },  // ask_user's questions, put in the host's own dialogs
+      surface: SURFACE,            // the host's UI, in its own words, told to the model in place of the terminal's
+      systemPrompt: (prompt) => prompt, // the last word on the whole system prompt, each turn
     }),
   ],
 });
@@ -45,8 +47,23 @@ await session.bindExtensions({ uiContext, mode: "tui" });
 
 - **The jobs.** The pulses the conversation starts - its tools, `/regenerate`, a spec change - run in its own job registry and work loop, the project's one. The host is handed both as they are made, and told of each job as it changes, so it shows the very jobs the conversation runs. Its buttons are best the conversation's commands - `session.prompt("/regenerate app.plain")` - so there is never a second loop on the same project.
 - **The questions.** `dialogs` is `ask_user`'s two dialogs: `select(title, options, context, at)` and `input(title, context)`, each resolving with the answer, or undefined when the person dismissed it. Given, the conversation's questions and a skill's interview are put in them; without it, in the terminal's own dialog.
+- **The surface.** What turri tells the model of where the person watches the work is the terminal's by default: regen, the side panel on `ctrl+h`, `/pulses`. In a host none of that is there, and the model would send the person to keys and panels that do not exist. `surface` is the host's own description of its UI - the views it has in place of the terminal's, what its marks and buttons mean, where questions appear - in its own words. Given, turri leaves every terminal instruction out of what the model is told and puts the surface in turri's identity, as a `<surface>` block, where the identity speaks of regen. It reaches the side questions and the tools' own words too: a pulse not found says the `pulses` tool lists them, not `/pulses`. Text only the person sees in the terminal - the job panel, the side panel - is the terminal's and stays as it is. Without `surface`, the prompt is the terminal's, byte for byte.
+- **The system prompt.** `systemPrompt(prompt)` gets the whole system prompt for the turn - pi's, turri's identity and blocks, the rules - after turri's own `before_agent_start` work, and returns what is sent. It is for what `surface` does not cover; to describe the UI, use `surface`, rather than words appended after turri's that contradict them.
 - **The mode.** `mode: "tui"` runs the work in the background and keeps the conversation free, as the terminal does; `rpc`, `json` and `print` wait for each job. The extension's other UI calls - its notices, its working line, a confirm - come to the host's `uiContext`, as pi's [SDK](https://github.com/earendil-works/pi) describes it.
 
+A surface for a desktop app might read:
+
+```js
+const SURFACE = `The person uses turri's desktop app, not a terminal: there are no keys to press. Slash commands are typed in
+the chat, and the toolbar's buttons send them too.
+- The Specs view shows each .plain file, every functional spec marked: a green dot is built, a pulsing ring regenerating,
+  a hollow ring planned, grey waiting.
+- The Pulses view lists every pulse - running, planned and finished. A row opens what its agents did and its log; its
+  Halt button stops it.
+- Your questions appear as cards above the message box: the person picks an option or types an answer there.
+- The Run button releases what is built and opens it.`;
+```
+
 ## Running it
 
 The host entry is compiled JavaScript, so any Node from 22.19 runs it - Electron's own included; nothing strips types. It finds turri's own folders - `genome/`, `stdlib/`, `.pi/` - beside `dist/` in the package, wherever npm installed it.

package/docs/regenerating.md

@@ -123,7 +123,7 @@ The reviewer has `can_it_fail` too, three runs a review session: a test it doubt
 
 ### The code and its unit tests are reviewed
 
-Passing unit tests prove only what they check, and a coding agent is quick to write tests that check next to nothing - that a function exists, that a result is not empty, that a status is 200 - or code that no test reaches. So, with `review: true` in the [config](config.md), once the unit testing script passes a reviewer on the judge model reads what the work wrote, beside the spec, and changes nothing. It reviews both halves, with the unit testing script word for word in its prompt: a test the script never reaches is not run, and checks nothing. The review is off by default - `review: false`, or the key left out - and so is the conformance tests' review: the work goes on once its tests pass.
+Passing unit tests prove only what they check, and a coding agent is quick to write tests that check next to nothing - that a function exists, that a result is not empty, that a status is 200 - or code that no test reaches. So, with `review: true` in the [config](config.md), once the unit testing script passes a reviewer on the judge model reads what the work wrote, beside the spec, and changes nothing. It reviews both halves, with the unit testing script word for word in its prompt: a test the script never reaches is not run, and checks nothing. The review is off by default - `review: false`, or the key left out - and so is the conformance tests' review: the work goes on once its tests pass. Even on, a module's first pulse is not reviewed when it builds one functional spec - the project set up and the smallest thing that runs, as `spawn` starts one: a review of a scaffold is time spent before anything can be tried.
 
 - **The code.** Every behaviour, edge case, validation rule and error the spec states for this work is implemented as the spec says it, with nothing left as a stub, a placeholder or a hard-coded answer. The code keeps to the implementation reqs and does not break what was already built. A behaviour with no code for it is raised as not implemented. Such a problem is of kind `wrong`.
 - **The unit tests.** Every behaviour, edge case and error the spec states for this work has a test asserting the exact outcome the spec says, that fails when it breaks; that no test only checks something exists, asserts nothing, is skipped or swallows a failure; that the unit under test is never mocked - only what is outside it; and that the tests are deterministic. A test that is not there is `missing`, a weak one is `bad`.
@@ -281,11 +281,11 @@ It is told, too, what to do with each functional spec the job touches, by its ca
 | fresh | the module requires none and nothing is built | set up the project and its unit tests where the unit testing script runs them, then build | set up `tests/` so the conformance testing script, which brings the tests together with `code/`, runs them, then write |
 | add | a functional spec is new | build it and write its unit tests | write its tests |
 | patch | its text changed, or a concept it uses did | change the existing code and tests to match - never build it again from scratch | rewrite its existing tests to match |
-| again | `regenerate` named it: it is built, and marked in the code record to be regenerated again | replace its implementation - rewrite it or start it over, doing what the spec says now; no second implementation beside the old, nothing of it left unused; its unit tests may be rewritten | none: its tests stay as they are |
+| again | `regenerate` named it: it is built, and marked in the code record to be regenerated again | replace its implementation - rewrite it or start it over, doing what the spec says now; no second implementation beside the old, nothing of it left unused; its unit tests may be rewritten | its tests were written against the code it replaced: run against the new code, what they check that the spec says stays checked, and what they check that the spec leaves open - a path, a field, a message the old code chose - is rewritten to what the new code does, or taken out |
 | delete | a functional spec is gone | take out its code and the tests only it had | take out its tests |
 | mechanical | no functional spec is touched - only reqs, or definitions none uses | adapt the code; write no new test; an existing one may change only mechanically - an import, a fixture, its setup - never what it asserts | the same, for test reqs, definitions or implementation reqs alone |
 
-**Regenerating again.** `regenerate` with functionalities named regenerates them again though their spec did not change - made better, on another model, after many patches. Each is marked in the code record of every codebase it is built in (`regenerate_again`, committed), and nothing else changes: the record now differs from the spec at that item, so the work loop plans it as it plans any change. A functional spec of a module below is regenerated again where its code lives - the codebase at the tip of each chain built on it, never the module's own codebase left behind - marked among that codebase's required functional specs. The planner groups the ones regenerated again as it groups new ones - up to three a job, only those next to each other in one module together - and the job is given the definitions and implementation reqs as every job is; `<spec change>` lists each under "To regenerate again", with its text as it is now. The job that regenerates it records it as the spec has it, without the mark. Its conformance tests compare its text, which did not change: they stay as they are, and are not rewritten.
+**Regenerating again.** `regenerate` with functionalities named regenerates them again though their spec did not change - made better, on another model, after many patches. Each is marked in the code record of every codebase it is built in (`regenerate_again`, committed), and nothing else changes: the record now differs from the spec at that item, so the work loop plans it as it plans any change. A functional spec of a module below is regenerated again where its code lives - the codebase at the tip of each chain built on it, never the module's own codebase left behind - marked among that codebase's required functional specs. The planner groups the ones regenerated again as it groups new ones - up to three a job, only those next to each other in one module together - and the job is given the definitions and implementation reqs as every job is; `<spec change>` lists each under "To regenerate again", with its text as it is now. The job that regenerates it records it as the spec has it, without the mark. Its conformance tests are marked with it, in the tests record of the codebase whose own functional spec it is: they were written against the code being replaced, and may hold the new code to what only the old code chose - `/healthcheck` where the spec says only that there is a health check, and the new code answers `/health`. While the code regenerates they stay as they are; once it lands, the mark is conformance work like any change, and a conformance job writes them again, in the again case above, and runs the whole suite. Until it lands, regen shows its tests as written for an earlier build, and they are not counted as conformance tested.
 
 A functional spec is patched when a concept it uses changed as well as when its own text did: the harness follows each functional spec's concepts through the definitions. Fresh is only where nothing exists: a module that requires another starts from what it inherits, and its first job adds or patches.
 
@@ -469,7 +469,7 @@ What goes into them:
 - **A code job landed:** the code record becomes the spec the job ends on.
 - **A conformance job landed:** the tests record becomes what its tests are written for.
 - **A module started from another's code:** that code's record, as a lower module's - see [where things go](#where-things-go) - and an empty tests record: the tests it inherits are the module below's.
-- **A functional spec named to `regenerate`:** it is marked to be regenerated again in the code record, so the next job regenerates it again; that job's record drops the mark.
+- **A functional spec named to `regenerate`:** it is marked to be regenerated again in the code record, so the next job regenerates it again; that job's record drops the mark. Its conformance tests, when it has them, are marked in the tests record too, and the conformance job that writes them again for the new code drops that mark.
 
 A unit of work - a code job, a conformance job - lands whole or is undone whole. It starts from the module's last commit, putting back whatever an interrupted run left; a module with no commit yet is given one first. When it does not pass, the module goes back to that commit: its changes, the files it added and any commit it made on the way are gone, with the record they came with. Installed dependencies and caches stay. So the code, its tests and the records of what they were built from never disagree.
 

package/docs/skills-and-gates.md

@@ -37,6 +37,8 @@ metadata:
 
 A skill declares its steps with a `## Steps` section whose `###` headings are the steps; without it the whole skill is one step, which is what most skills are. Steps are never inferred from `###` headings elsewhere in the body - prose skills are full of those. Each gate becomes a conditional edge after its step; a single-step skill is gated by naming the skill itself. None of the skills turri ships declares a gate today - `brood`'s phases end on the person's confirmation alone - but a project's own skill can.
 
+`command-only: true` under `metadata:` keeps a skill from the model: it is started only by the person, with its slash command - `/brood`, `/spawn` and `/bud` are. turri registers the command for every such skill, the project's own too. Typed, the command puts what was typed in the chat as the person's message, and lets `cultivate` start the skill once; the run starting uses that up, so the model cannot start it again later on its own. Without the command, `cultivate` refuses it and the model is told to name the command to the person instead - the skill's line in `cultivate`'s list says so too.
+
 `paced: false` under `metadata:` lets a skill write spec changes one after another on its own: `write_spec_diff` otherwise refuses a new change until the user has answered a question since the last one - one answer, one change, as an interview writes them. `spawn` is unpaced: the tool tells it so, and after each change to write the next at once, not to carry on with an interview it does not have.
 
 `questioning:` under `metadata:` names the steps the questioning level caps (`src/questioning.ts`) - `brood`'s `[stack, product]`, `bud`'s `[product]`. When there are any and someone to ask, the harness itself asks the first question of the first step: how many questions those steps may ask - light (3), medium (5), thorough (10) or best judgement - and tells the agent the answer beside each step's instructions, with how broad each question is to be: broad at light, a whole area at once, narrow at thorough, an edge case at a time. Every level covers the same ground, in less or more depth. In a capped step `ask_user` refuses a question past the cap; the step's closing confirmation, asked with `confirms_phase: true`, is never counted. `end_questions` ends the step's questions sooner - best judgement's only end. What the questions leave open, the agent decides itself and says what it chose. The level, and how many questions each step has asked, are kept in the run's `run.json`, so a resumed run keeps them. A step it does not name, or a run with nobody to ask, is not capped.
@@ -45,7 +47,7 @@ A skill declares its steps with a `## Steps` section whose `###` headings are th
 
 A step ends when its agent's turn does. A turn that ends on a question in the reply would end the step there, half done, on a question no one reads - the person sees only what `ask_user` asks. So such a step is sent back, twice at most: to ask with `ask_user` if the question is truly the person's, or, in an unpaced skill, to decide it itself - then to carry on until the step is done.
 
-`phases:` under `metadata:` says what each step does, in a short line a step by its name - for the person, not the agent: while the skill runs, the line above the input shows its phases, and under them the one it is in with its line (`groundwork - the language, frameworks, storage and architecture`). A phase's name alone says little to someone who has not read the skill. Every skill with more than one step describes each; a line for a step the skill does not have is an error, as a gate after one is.
+`phases:` under `metadata:` says what each step does, in a short line a step by its name - for the person, not the agent: while the skill runs, the line above the input shows its phases, and under them the one it is in with its line (`skeleton - sets up the project and writes the smallest spec that runs, so the first build can start`). A phase's name alone says little to someone who has not read the skill. Every skill with more than one step describes each; a line for a step the skill does not have is an error, as a gate after one is.
 
 A skill gets the tools its `allowed-tools` names, and nothing else: one that names none has none. So every skill here names its own - the file tools (`read`, `write`, `edit`, `bash`, `ls`, `grep`, `find`) for the ones that write specs, resources or scripts, only the reading ones for those that analyse and report, and turri's own (`write_spec_diff` and the ones below) where a skill uses them.
 

package/docs/using.md

@@ -7,14 +7,14 @@ cd ~/my-project
 turri
 ```
 
-That is pi, with turri's tools, skills and themes loaded - `turri` alone, or with pi's options (`turri -c`, `turri --harness-model <m>`). It opens with turri's own banner - the jellyfish it is named after, regenerating until the conversation fills the screen: a pixel polyp on the sea floor grows into the jellyfish - a bell from pink down to indigo, an orange gut, neon tentacles - which swims a while, sinks back to the floor, and the polyp grows again, round and round: a picture in a terminal that shows images (Kitty, Ghostty, WezTerm, Warp, iTerm2), and drawn at a third of the size in half blocks in any other, tmux included (`src/jellyfish.ts` draws it, ported from the design system's pixel kit, `scripts/jellyfish-frames.mjs` writes the pictures) - turri's version (and, run from a clone, the commit it is on, and whether the clone has changes) and where its settings are changed - and only when something is wrong, skills that failed to load or agents' commands less fenced than they should be - rather than pi's startup header and resource list; `turri --verbose` shows those too. pi's "Update Available" notice is left out - turri's pi is a pinned dependency `pi update` never touches - and the terminal's tab reads `🪼 turri - <folder>`, not pi's `π`. Talk to it: ask it to start a project, add a feature, render a module, fix a spec. It decides which skill or tool applies - but not *how* a skill runs: `cultivate` hands the work to the gated runner, which owns the steps, the gates and the judges (see [skills and gates](skills-and-gates.md)).
+That is pi, with turri's tools, skills and themes loaded - `turri` alone, or with pi's options (`turri -c`, `turri --harness-model <m>`). It opens with turri's own banner - the jellyfish it is named after, regenerating until the conversation fills the screen: a pixel polyp on the sea floor grows into the jellyfish - a bell from pink down to indigo, an orange gut, neon tentacles - which swims a while, sinks back to the floor, and the polyp grows again, round and round: a picture in a terminal that shows images (Kitty, Ghostty, WezTerm, Warp, iTerm2), and drawn at a third of the size in half blocks in any other, tmux included (`src/jellyfish.ts` draws it, ported from the design system's pixel kit, `scripts/jellyfish-frames.mjs` writes the pictures) - turri's version (and, run from a clone, the commit it is on, and whether the clone has changes) and where its settings are changed - and only when something is wrong, skills that failed to load or agents' commands less fenced than they should be - rather than pi's startup header and resource list; `turri --verbose` shows those too. pi's "Update Available" notice is left out - turri's pi is a pinned dependency `pi update` never touches - and the terminal's tab reads `🪼 turri - <folder>`, not pi's `π`. Talk to it: ask it to add a feature to a spec, render a module, fix a spec. It decides which skill or tool applies - but not *how* a skill runs: `cultivate` hands the work to the gated runner, which owns the steps, the gates and the judges (see [skills and gates](skills-and-gates.md)).
 
-The skills that build from scratch:
+Three skills you start yourself, by their commands - turri never starts them on its own, and says which to type when one fits: `/brood`, `/spawn` and `/bud`, each with what you want after it - `/spawn a URL shortener in Go`. The skills that build from scratch:
 
 | skill | how it works |
 | --- | --- |
 | `brood` | first, how many questions the stack and product phases may ask - light (3), medium (5), thorough (10) or best judgement, broader with fewer, turri deciding what they leave open; then intent, stack, then testing - conformance tests on or off (into `config.turri.yaml`), their `***test reqs***` and the conformance testing script, which build nothing - then the product feature by feature, where every answer becomes one spec change - a git diff of the `.plain` files, written with `write_spec_diff` and rendered as a render spec diff pulse the moment it is written, with its conformance tests when they are on |
-| `spawn` | its quick twin: asks only what you want to build and which stack - one of the standard library's, your own, or `You choose` - and confirms a five-line brief, then writes the stack and the unit tests itself - conformance tests off, unless you ask for them - and writes the product feature by feature on its own, each feature a spec diff queued as it is written - after which you keep talking, and every change you ask for is a spec diff, and what is left to build is worked out again from the spec |
+| `spawn` | its quick twin, for something running in minutes: asks what you want to build only when your message does not say, and chooses the stack itself unless you named one - conformance tests off, unless you ask for them - then writes the smallest thing that runs, which starts the first build at once, and the main slice of what you described and one more on their happy path, each a spec diff queued as it is written - nothing you did not describe: named only the kind of software, you get it running, and say what it does. You try each as it lands, and say `go on` for the next slice it proposed, or what to change instead - every change is a spec diff, and what is left to build is worked out again from the spec |
 | `mature` | for a spec you already have, rough or hand-written: on its own until it is fully rendered - renders what is not built, watches the agents building it, and when one struggles on something the spec leaves open, settles it in the spec as a spec diff, stops that build and renders it again; decides open choices itself and marks them in its report |
 
 Peeking is safe while a question is open - a skill's or the chat's: `ctrl+h` opens the side panel over the question, which waits under it as it was - the panel says `your question is waiting`, and `ctrl+h` or `esc` takes you back to answer it. (The question has the keys, so turri catches `ctrl+h` itself while one is open.) The dialog holds the question alone - no hint and no invitation; the `ctrl+h` under the job panel breathes until it is first pressed.
@@ -151,7 +151,9 @@ A provider failure - no credits, bad key, rate limit - is raised with the provid
 
 Each `plain_modules/<module>` is a git repository whose git directory is `.plaingit` rather than `.git`, so it stays plain files to your own repository. A commit is made after every step that changes the module - a render, a functionality regenerated, a conformance run, a regression repair, a spec change. `/lineage [module]` and `lineage` show it.
 
-The last commit is also the last known good state. Every render, functionality regenerated, spec change and conformance run starts by putting the codebase it works in back to it, so if turri was stopped or restarted mid-pulse, whatever that pulse left half-written is undone first - and one that does not pass is undone the same way when it ends, commits and all. Only work that passed is committed. Installed dependencies and caches are not in the history and stay. With git directly:
+The last commit is also the last known good state. Every render, functionality regenerated, spec change and conformance run starts by putting the codebase it works in back to it, so if turri was stopped or restarted mid-pulse, whatever that pulse left half-written is undone first - and one that does not pass is undone the same way when it ends, commits and all. Only work that passed is committed. Installed dependencies and caches are not in the history and stay.
+
+The history is turri's own: the hooks your git config names (`core.hooksPath` - gitleaks, husky) do not run on its commits. When work that passed cannot be committed all the same - a `.plaingit/index.lock` a git stopped mid-commit left, a full disk - the pulse does not land: the next start would undo it while turri took it as built. It is rolled back, and the stop says what git said and how to fix it. Any other step's commit failing leaves only a gap in the history. With git directly:
 
 ```bash
 git --git-dir=plain_modules/<module>/.plaingit --work-tree=plain_modules/<module> log

package/genome/rules/func-specs.md

@@ -58,6 +58,7 @@ GOOD — statements of fact with concrete subjects:
 - The first spec must still imply a testable outcome; setup alone is not a functional spec
 - Prefer one minimal entry point or public operation with a deterministic result that can be invoked and verified
 - Defer persistence, integrations, multiple interfaces, branching workflows, and cross-cutting behavior until later specs can build on the generated baseline
+- A spec may start on its happy path and be hardened later - validation, edge cases and errors added to it by changing it - once the software has been tried; it must still say exactly what it does for the input it covers
 - This extra bootstrap cost applies when no previous implementation baseline exists; a module that continues from a `requires` module may already inherit the necessary scaffold
 
 ## Chronological ordering