@turri-dev/cli 0.1.3-next.f74e98a → 0.1.4-next.318a98a

package/README.md

@@ -27,7 +27,7 @@ npm install -g @turri-dev/cli # puts `turri` on your PATH
 turri doctor              # checks the machine
 ```
 
-To work on turri itself, run it from a clone instead - see [installation](docs/installation.md#from-a-clone).
+To follow `main` as it moves, or work on turri itself, run it [from a clone](#from-a-clone) instead.
 
 `doctor` checks for Node 22.19+, bash, the OS sandbox and a model provider for pi; in a project, the toolchains its
 modules need, what its testing scripts run against this machine, and that each model `config.turri.yaml` names
@@ -73,6 +73,27 @@ Rather not install Node and the rest? **turri** also runs in Docker, from one im
 
 Choosing models: [models](#models); what to do next: [use](#use).
 
+### From a clone
+
+In place of the npm package - for the latest of `main`, or to change turri itself:
+
+```bash
+git clone git@github.com:turri-oss/turri.git && cd turri
+npm install
+npm link        # puts `turri` on your PATH, pointing at this clone
+turri doctor
+```
+
+The clone runs its TypeScript sources directly, so there is nothing to build. When new commits land:
+
+```bash
+git pull
+npm install     # picks up any dependency that changed
+```
+
+A **turri** already running keeps the code it started with - start it again to run what you pulled. More in
+[installation](docs/installation.md#from-a-clone).
+
 ## Why
 
 In the age of coding agents, writing code is getting easy. The hard and important part is

package/dist/extension.js

@@ -90,15 +90,23 @@ aside) {
             // The question, with what the asker gives to read for it - a brief to confirm - above it; what it said of its work
             // before asking is kept in its record, never put in the dialog.
             // A dialog of turri's own: a long brief scrolls above the question, and the options always show (question-dialog.ts).
-            const dialog = (question, context, options) => ctx.ui.custom((tui, theme, _keybindings, done) => new QuestionDialog({
-                question,
-                ...(context !== undefined ? { context } : {}),
-                ...(options !== undefined ? { options } : {}),
-                rows: () => tui.terminal.rows,
-                style: { accent: (text) => theme.fg("accent", text), muted: (text) => theme.fg("muted", text), bold: (text) => theme.bold(text) },
-                done,
-                requestRender: () => tui.requestRender(),
-            }));
+            const dialog = (question, context, options) => ctx.ui.custom((tui, theme, _keybindings, done) => {
+                const shown = new QuestionDialog({
+                    question,
+                    ...(context !== undefined ? { context } : {}),
+                    ...(options !== undefined ? { options } : {}),
+                    rows: () => tui.terminal.rows,
+                    style: { accent: (text) => theme.fg("accent", text), muted: (text) => theme.fg("muted", text), bold: (text) => theme.bold(text) },
+                    done: (answer) => {
+                        if (questionShown === shown)
+                            questionShown = undefined;
+                        done(answer);
+                    },
+                    requestRender: () => tui.requestRender(),
+                });
+                questionShown = shown;
+                return shown;
+            });
             const asking = (asked) => runAsk(asked, {
                 select: (title, options, context) => dialog(title, context, options),
                 input: (title, context) => dialog(title, context),
@@ -117,6 +125,12 @@ aside) {
 }
 /** The side panel, as a question open in the chat reaches it: set once the extension has its panel. */
 let questionPeek;
+/**
+ * The question open in the chat now, if any. The side panel gives the keys back to it: pi would give them to what had the
+ * focus when the panel first opened, and a panel kept beside the chat outlives that question - the keys would go to a
+ * dialog already answered, and nothing would take them.
+ */
+let questionShown;
 /** A widget with nothing to draw: below the editor, it takes no line. */
 const PEEK_KEY_WIDGET = "turri-peek-key";
 /**
@@ -534,7 +548,7 @@ export default function (pi) {
                 loopTools: [
                     regenerateTool({ cwd, jobs, loop: () => workLoopFor(jobs, cwd, ctx), model: (_skill, plainFile, named, work) => jobModel(ctx, work ?? "spec_changes", named, plainFile), wait: () => false }),
                     driftTool({ cwd, jobs, loop: () => workLoopFor(jobs, cwd, ctx) }),
-                    haltTool({ jobs }),
+                    haltTool({ jobs, workLoop: () => workLoops.get(jobs)?.loop }),
                     conformTool({ cwd, loop: () => workLoopFor(jobs, cwd, ctx), model: (_skill, plainFile, named) => jobModel(ctx, "spec_changes", named, plainFile), wait: () => false }),
                 ],
                 // The escalation becomes a real dialog in the TUI. Without dialog-capable
@@ -1405,25 +1419,37 @@ function registerJobTools(pi, jobs, cwd) {
     // The panel is compact and ctrl+o only lasts as long as the work does. This is the whole
     // list, finished jobs included, put in the transcript where it stays.
     pi.registerCommand("halt", {
-        description: "Halt a queued or running pulse, or what activate started: /halt [pulse id | activated <name>]",
+        description: "Halt a queued or running pulse, a module's planned pulses, or what activate started: /halt [pulse id | module | activated <name>]",
         handler: async (args, ctx) => {
             if (!ctx.hasUI)
                 return;
             const live = jobs.list().filter((job) => job.status === "running" || job.status === "queued");
             const deployed = runningDeployed();
+            const loop = workLoops.get(jobs)?.loop;
+            // A module's planned pulses, one line a module: halting one halts the module.
+            const plannedRows = loop?.planned() ?? [];
+            const planned = [...new Set(plannedRows.map((row) => row.module ?? ""))].filter((module) => module !== "");
             let id = args.trim();
             if (id === "") {
-                if (live.length === 0 && deployed.length === 0)
-                    return ctx.ui.notify("Nothing is regenerating or queued.", "info");
+                if (live.length === 0 && deployed.length === 0 && planned.length === 0)
+                    return ctx.ui.notify("Nothing is regenerating, queued or planned.", "info");
                 const label = (job) => `${job.id}  ${job.status.padEnd(8)} ${pulseName(job)}`;
-                const labels = [...live.map(label), ...deployed.map((item) => deployedLabel(item.name, item.url ?? item.command))];
+                const plannedLabel = (module) => {
+                    const rows = plannedRows.filter((row) => row.module === module);
+                    const waiting = rows.find((row) => row.id.endsWith("-waiting"));
+                    return `${module}  ${waiting !== undefined ? waiting.summary : `${rows.length} planned`} - halts the module`;
+                };
+                const labels = [...live.map(label), ...planned.map(plannedLabel), ...deployed.map((item) => deployedLabel(item.name, item.url ?? item.command))];
                 const picked = await ctx.ui.select("Halt which?", labels);
                 const job = live.find((candidate) => picked !== undefined && label(candidate) === picked);
+                const module = planned.find((name) => picked !== undefined && plannedLabel(name) === picked);
                 const server = deployed.find((item) => picked !== undefined && deployedLabel(item.name, item.url ?? item.command) === picked);
                 if (server !== undefined)
                     id = `activated ${server.name}`;
                 else if (job !== undefined)
                     id = job.id;
+                else if (module !== undefined)
+                    id = module;
                 else
                     return;
             }
@@ -1432,7 +1458,7 @@ function registerJobTools(pi, jobs, cwd) {
                 const stopped = await stopDeployed({ name });
                 return shownAfterCommand(pi, ctx, `/halt ${id}`, stopped.length > 0 ? `Halted ${stopped.join(", ")}.` : `Nothing activate started is running as ${name}.`, "info");
             }
-            ctx.ui.notify(stopJob(jobs, id), "info");
+            ctx.ui.notify(stopJob(jobs, id, undefined, loop), "info");
         },
     });
     // Debug mode, for the render agents started from now on - see debug-log.ts.
@@ -1508,6 +1534,7 @@ function registerJobTools(pi, jobs, cwd) {
         }
         needsLooking.delete(jobs);
         if (panel !== undefined) {
+            panel.keepChatFocus();
             panel.handle?.setHidden(false);
             panel.keys = true;
             panel.handle?.focus();
@@ -1515,7 +1542,21 @@ function registerJobTools(pi, jobs, cwd) {
         }
         // Not awaited: the panel lives on while the jobs it shows run.
         void ctx.ui.custom((tui, theme, _keybindings, done) => {
-            const close = () => done(undefined);
+            // What the chat shows when the panel takes the keys - its editor, or a pi dialog - for when it gives them back.
+            const focusedNow = () => tui.getFocusedComponent?.() ?? null;
+            let chatFocus = focusedNow();
+            const keepChatFocus = () => {
+                const focused = focusedNow();
+                if (focused !== null && focused !== component && !(focused instanceof QuestionDialog))
+                    chatFocus = focused;
+            };
+            // The keys back to the chat: to the question open there now, else to what it showed - never to a question answered
+            // while the panel was open.
+            const giveBack = () => entry.handle?.unfocus({ target: questionShown ?? chatFocus });
+            const close = () => {
+                giveBack();
+                done(undefined);
+            };
             panelTerminal = tui.terminal;
             let component;
             // Beside the chat: the chat drawn narrower, on the left, and a click on either side giving it the keys - undone
@@ -1548,10 +1589,11 @@ function registerJobTools(pi, jobs, cwd) {
             // Beside the chat, back to it: the chat has the keys, the panel stays.
             const toChat = () => {
                 entry.keys = false;
-                entry.handle?.unfocus();
+                giveBack();
                 tui.requestRender();
             };
             const toPanel = () => {
+                keepChatFocus();
                 entry.keys = true;
                 entry.handle?.focus();
                 tui.requestRender();
@@ -1604,7 +1646,7 @@ function registerJobTools(pi, jobs, cwd) {
                     return focused !== null && focused !== component;
                 },
             });
-            const entry = { view, close, keys: true };
+            const entry = { view, close, keepChatFocus, keys: true };
             panel = entry;
             layOut();
             // Every key goes to the panel while it shows, whatever has the focus: a question the chat model asks in the
@@ -2007,6 +2049,7 @@ function registerDeploy(pi, cwd, jobs, state) {
         cwd,
         state,
         jobs,
+        workLoop: () => workLoops.get(jobs)?.loop,
         defaultPlainFile: () => readProjectConfig(cwd).module,
     });
     for (const tool of tools)

package/dist/genome.js

@@ -185,7 +185,7 @@ export async function runSkill(opts) {
     // Built renders were lost with the process; queue what the specs hold that is not built.
     if (resumed !== undefined && opts.renderQueue !== undefined) {
         for (const file of plainFilesIn(opts.cwd))
-            void opts.renderQueue.bringUp(file).catch(() => undefined);
+            void opts.renderQueue.bringUp(file, { specChange: true }).catch(() => undefined);
     }
     if (liveStep !== undefined && liveProxy !== undefined) {
         const continuous = liveStep.gate.continuous;

package/dist/loop-tools.js

@@ -70,7 +70,11 @@ export async function loopReply(loop, statuses, wait) {
     return { content: [{ type: "text", text }], details: { jobIds } };
 }
 /** Halt a pulse by its id, or the start of it: what it was, and what moves up behind it. `reason`: why, kept with it. */
-export function stopJob(jobs, named, reason) {
+export function stopJob(jobs, named, reason, loop) {
+    // A planned row, or a module by its name: the module is halted - its rows are planned again from the spec each look.
+    const module = /^planned-/.test(named.trim()) || !jobs.list().some((job) => job.id.startsWith(named.trim())) ? loop?.halt(named, reason) : undefined;
+    if (module !== undefined)
+        return module;
     const matches = jobs.list().filter((job) => job.id.startsWith(named.trim()));
     if (matches.length === 0)
         return `No pulse ${named}. /pulses shows them.`;
@@ -188,7 +192,7 @@ export function driftTool(options) {
 }
 const ACTIVATED_PARAM = Type.Optional(Type.String({ description: 'What activate started, by name - or "all" for every one' }));
 const HALT_PULSE_PARAMS = Type.Object({
-    job_id: Type.Optional(Type.String({ description: "The pulse's id, or the start of it" })),
+    job_id: Type.Optional(Type.String({ description: "The pulse's id, or the start of it; a planned row's id (planned-<module>-...), or a module's name, halts the module" })),
     reason: Type.Optional(Type.String({ description: "Why it is halted, kept with it - what the spec now says that it did not, say" })),
     activated: ACTIVATED_PARAM,
 });
@@ -201,12 +205,21 @@ export function haltTool(options) {
         name: "halt",
         label: "Halt",
         description: jobs !== undefined
-            ? "Halt a pulse, or what activate started. A pulse: a queued one never starts, a running one has its agent stopped at once, " +
-                "and the pulses queued behind it move up - what a running pulse already changed is rolled back, and what it was regenerating " +
-                "counts as not regenerated. What activate started: the one named, or every one."
+            ? "Halt a pulse, a module's planned pulses, or what activate started. A pulse: a queued one never starts, a running one has its " +
+                "agent stopped at once, and the pulses queued behind it move up - what a running pulse already changed is rolled back, and what " +
+                "it was regenerating counts as not regenerated. A planned row (planned-<module>-...) or a module's name halts the module: its " +
+                "running pulse stopped, none of its planned pulses started, and the modules built on it waiting - until it is asked for again " +
+                "with regenerate; a spec change does not start it. A module whose .plain file is gone is dropped. What activate started: the " +
+                "one named, or every one."
             : "Stop what activate started: the one named, or every one.",
         promptSnippet: jobs !== undefined ? "halt a pulse, or what activate started" : "stop a deployed server, or all of them",
-        promptGuidelines: jobs !== undefined ? ["Halt a pulse only when the user asks, or your instructions say to. Name which one, and say which pulses were queued behind it - they will now run."] : [],
+        promptGuidelines: jobs !== undefined
+            ? [
+                "Halt a pulse only when the user asks, or your instructions say to. Name which one, and say which pulses were queued behind it - they will now run.",
+                "Halting a planned row halts its whole module - one planned pulse cannot be taken out alone, as the plan is made again from the spec. To build some of it later, or cut it differently, use steer; to drop work, change the spec.",
+                "A planned row for a module that is no longer in the project is halted the same way, and dropped.",
+            ]
+            : [],
         parameters: (jobs !== undefined ? HALT_PULSE_PARAMS : HALT_ACTIVATED_PARAMS),
         async execute(_id, params) {
             if (params.job_id === undefined && params.activated === undefined) {
@@ -214,7 +227,7 @@ export function haltTool(options) {
             }
             const lines = [];
             if (params.job_id !== undefined && jobs !== undefined)
-                lines.push(stopJob(jobs, params.job_id, params.reason));
+                lines.push(stopJob(jobs, params.job_id, params.reason, options.workLoop?.()));
             if (params.activated !== undefined) {
                 const stopped = await stopDeployed(params.activated === "all" ? {} : { name: params.activated });
                 lines.push(stopped.length > 0 ? `Halted ${stopped.join(", ")}.` : `Nothing activate started is running${params.activated === "all" ? "" : ` as ${params.activated}`}.`);

package/dist/pi-launch.js

@@ -11,6 +11,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { main, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { ProcessTerminal } from "@earendil-works/pi-tui";
 import "./terminal-images.js";
+import { resumeLine } from "./resume-line.js";
 /**
  * pi, started the way its own CLI starts it, for `turri`.
  *
@@ -31,6 +32,10 @@ const setTitle = ProcessTerminal.prototype.setTitle;
 ProcessTerminal.prototype.setTitle = function (title) {
     setTitle.call(this, title.replace(/^π(?= |$)/, "🪼 turri"));
 };
+// What pi prints on the way out to resume the session names pi - its APP_NAME, a constant - which may not be on the
+// PATH at all: turri takes the same flags, so it is turri the line names.
+const write = process.stdout.write.bind(process.stdout);
+process.stdout.write = ((chunk, ...rest) => write(typeof chunk === "string" ? resumeLine(chunk) : chunk, ...rest));
 // pi's own keys stand: a new line is shift+enter or ctrl+j. turri's side panel is on ctrl+h (job-panel.ts PANEL_KEY).
 // What pi's CLI does before main: the process title, pi's environment markers, the HTTP
 // dispatcher. Not exported, so loaded from the file - beside pi's entry point, wherever npm put it.

package/dist/question-dialog.js

@@ -58,18 +58,23 @@ export class QuestionDialog {
         const choices = this.options.options ?? [];
         const body = this.input !== undefined
             ? this.input.render(inner)
-            : choices.map((choice, index) => (index === this.selected ? style.accent(`› ${choice}`) : `  ${choice}`));
+            : // A long option wraps, its lines under its first, rather than cut off where the person cannot read it.
+                choices.flatMap((choice, index) => wrapTextWithAnsi(choice, Math.max(1, inner - 2)).map((line, at) => {
+                    const shown = `${at === 0 && index === this.selected ? "›" : " "} ${line}`;
+                    return index === this.selected ? style.accent(shown) : shown;
+                }));
         const hint = this.input !== undefined
             ? "enter answers · esc dismisses"
             : "↑↓ choose · enter picks · esc dismisses";
         // The brief gets what the question, the options and the hints leave of the screen.
-        const fixed = question.length + body.length + 4;
+        const fixed = question.length + body.length + 5;
         const room = Math.max(3, this.options.rows() - KEPT_ABOVE - fixed);
         const scrolls = brief.length > room;
         this.window = scrolls ? room - 1 : brief.length;
         this.maxScroll = scrolls ? brief.length - this.window : 0;
         this.scroll = Math.min(this.scroll, this.maxScroll);
-        const lines = [];
+        // Set apart from what is drawn above it - the job panel's hints.
+        const lines = [""];
         if (brief.length > 0) {
             lines.push(...brief.slice(this.scroll, this.scroll + this.window).map(pad));
             if (scrolls) {

package/dist/questioning.js

@@ -43,7 +43,7 @@ export function questioningQuestion(phases) {
     return {
         question: `How many questions should I ask you in ${named}?`,
         options: QUESTIONING_LEVELS.map((level) => level.option),
-        context: `Light, medium and thorough cap each of ${named} at 3, 5 and 10 questions - broader with fewer, so every level ` +
+        context: `Light, medium and thorough cap ${phases.length === 1 ? named : `each of ${named}`} at 3, 5 and 10 questions - broader with fewer, so every level ` +
             "covers the same ground, only in less or more depth. What the questions leave open, turri decides itself and " +
             "says what it chose. With best judgement, turri asks as much as it judges each phase needs. Each phase still " +
             "ends with your confirmation of its summary.",

package/dist/regenerate/activity.js

@@ -183,6 +183,8 @@ export function describeToolCall(name, args) {
             return `± my_diff`;
         case "update_notes":
             return `✐ update_notes`;
+        case "report_spec_gap":
+            return `? spec gap: ${text("question") ?? ""}`.trimEnd();
         case "copy_resource":
             return `⎘ copy_resource ${path ?? text("to") ?? ""}`.trimEnd();
         case "can_it_fail":

package/dist/regenerate/conform.js

@@ -7,7 +7,7 @@ import { abandonWork, startWork } from "./lineage.js";
 import { ensureRegressionPasses } from "./regression.js";
 import { modulesRoot, projectDirOf } from "./paths.js";
 import { applySpecDiff, snapshotSpec, specGapsText } from "./regenerate.js";
-import { linesAddedSince, readNotes } from "./notes.js";
+import { gapMark, gapsSince } from "./notes.js";
 import { sectionsOf } from "./state.js";
 import { describeStop } from "./stop-report.js";
 import { missingTestLabels } from "./test-kinds.js";
@@ -41,8 +41,8 @@ export async function renderSpecDiffConformance(options) {
     // state, not to what an interrupted run left half-written. The tests and the whole suite are
     // one unit, landed whole or undone whole.
     const unit = startWork([buildDir, conformanceDir], moduleName);
-    // The notes as its agents find them: a spec gap they add is told with the result.
-    const notesBefore = { code: readNotes(buildDir), tests: readNotes(conformanceDir) };
+    // The spec gaps its agents report from here on are told with the result.
+    const gapsFrom = gapMark();
     const conformance = await renderConformanceTests({
         plainFile: tip.plainFile,
         frid: lastFrid,
@@ -58,8 +58,8 @@ export async function renderSpecDiffConformance(options) {
     });
     // What the codebase now has conformance tests for, as their labels say.
     const tested = () => frids.filter((frid) => missingTestLabels(conformanceDir, frid, []).length === 0);
-    // Read before a rollback takes the notes back: a gap is the person's to decide, whether the tests passed or not.
-    const base = { moduleName, buildDir, conformanceDir, diff: applied, conformance, specGaps: [...linesAddedSince(notesBefore.code, buildDir, "gaps"), ...linesAddedSince(notesBefore.tests, conformanceDir, "gaps")] };
+    // A gap is the person's to decide, whether the tests passed or not.
+    const base = { moduleName, buildDir, conformanceDir, diff: applied, conformance, specGaps: gapsSince(gapsFrom, [buildDir, conformanceDir]) };
     if (!conformance.passed) {
         abandonWork(unit, moduleName, notLandedWhy("for the spec change", conformance.unlabelled));
         return { ...base, tested: tested(), passed: false, stoppedAt: "conformance" };

package/dist/regenerate/conformance-agents.js

@@ -7,7 +7,7 @@ import { confinedTools } from "./confine.js";
 import { ensureInModulesScratch, modulesScratchDir } from "./paths.js";
 import { workspaceBlock } from "./workspace.js";
 import { reportActivity } from "./activity.js";
-import { runTiming } from "./test-scripts.js";
+import { runTiming, withTestingScripts } from "./test-scripts.js";
 import { createWebTools, WEB_TOOLS } from "./web.js";
 import { diffFiles, digestFiles } from "./codebase.js";
 import { ERROR_CAUSE_RULES, fixMethod, INTEGRITY_RULES, specPrimer } from "./prompt.js";
@@ -378,9 +378,17 @@ export function explorePrompt(buildDir, spec, scope, testingScripts, question, p
         ...(testingScripts !== undefined && testingScripts.length > 0
             ? [
                 "",
-                "This is the project's conformance testing script, which the harness runs to decide whether the",
-                "tests pass - read it for what it builds or installs before the tests run, and so what the tests can depend on:",
-                ...testingScripts.flatMap((script) => ["", `<script path="${script.path}" run-as="${script.runs}">`, script.content.trimEnd(), "</script>"]),
+                ...(testingScripts.some((script) => script.prepare === true)
+                    ? [
+                        "These are the project's prepare script, which the harness runs on the build first, and its conformance testing",
+                        "script, which runs only once the prepare script passes and decides whether the tests pass - read both for what",
+                        "they build or install before the tests run, and so what the tests can depend on:",
+                    ]
+                    : [
+                        "This is the project's conformance testing script, which the harness runs to decide whether the",
+                        "tests pass - read it for what it builds or installs before the tests run, and so what the tests can depend on:",
+                    ]),
+                ...testingScripts.flatMap((script) => ["", `<script${script.prepare === true ? ' kind="prepare environment"' : ""} path="${script.path}" run-as="${script.runs}">`, script.content.trimEnd(), "</script>"]),
             ]
             : []),
         ...(previous !== undefined && question === undefined
@@ -704,7 +712,7 @@ export function unfoundedEvidence(evidence, opened) {
             "opened, the testing script, or the failing run - each with where. What <how to invoke it> says is not evidence: it " +
             "may be wrong, so check it against the testing script and the files.");
     }
-    const inPrompt = (source) => /^(the )?(conformance )?testing script$|^(the )?failing run$/i.test(source.trim());
+    const inPrompt = (source) => /^(the )?(conformance )?testing script$|^(the )?prepare script$|^(the )?failing run$/i.test(source.trim());
     const unread = given.filter((item) => !inPrompt(item.source) && !opened(item.source.trim()));
     if (unread.length > 0) {
         return (`Your evidence cites ${unread.map((item) => item.source.trim()).join(", ")}, which you did not open. Open each file you cite ` +
@@ -735,7 +743,7 @@ export async function judgeFailure(options) {
                 description: "For code: the conformance testing script's own words for what it needs the build to have - the file, entry point or module the run failed on - copied exactly from the script",
             })),
             evidence: Type.Optional(Type.Array(Type.Object({
-                source: Type.String({ description: "Where: the path of a file you opened, `testing script`, or `failing run`" }),
+                source: Type.String({ description: "Where: the path of a file you opened, `testing script`, `prepare script` where there is one, or `failing run`" }),
                 shows: Type.String({ description: "What it shows, e.g. `the script runs node dist/cli.js` or `tsconfig.json emits src/cli.ts as dist/src/cli.js`" }),
             }), { description: "What you found yourself, each with where - never what <how to invoke it> claims unchecked" })),
             functionalities: Type.Optional(Type.Array(Type.Object({
@@ -900,6 +908,12 @@ export function judgePrompt(options) {
                 "what is wrong. What it does with the tests, the tests have to fit; what it needs of the code - a file it runs or",
                 "checks for, a command it builds with - the code has to provide. A verdict that the script is wrong is neither",
                 "code nor tests: say which of the two has to change to get past it.",
+                ...(scripts.some((script) => script.prepare === true)
+                    ? [
+                        "The prepare script below it runs on the build before every run, and the conformance testing script only once it",
+                        "passes: it binds the same way - neither agent can change it, and what it needs of the code the code provides.",
+                    ]
+                    : []),
                 "",
             ]
             : []),
@@ -929,7 +943,10 @@ export function judgePrompt(options) {
         "",
         `<how to invoke it>\n${options.invocation.trim()}\n</how to invoke it>`,
         "",
-        ...scripts.flatMap((script) => [`<conformance testing script path="${script.path}" run-as="${script.runs}">`, script.content.trimEnd(), "</conformance testing script>", ""]),
+        ...scripts.flatMap((script) => {
+            const tag = script.prepare === true ? "prepare script" : "conformance testing script";
+            return [`<${tag} path="${script.path}" run-as="${script.runs}">`, script.content.trimEnd(), `</${tag}>`, ""];
+        }),
         ...(options.run.timedOut === true ? [...timedOutBlock(options.run), ""] : []),
         `<failing run exit="${options.run.exitCode}" command="${options.run.command}">`,
         runTiming(options.run),
@@ -1004,7 +1021,10 @@ export async function createCodeFixer(options) {
         model: options.model,
         label: `${options.label} coding agent`, role: "coding",
         system: `${fence.note}\n\n${workspaceBlock({ dir: options.buildDir, hasMyDiff: options.toolNames.includes("my_diff") })}`,
-        task: codeFixerTask(options),
+        // What the conformance testing script needs of the build, the code provides: the fixer reads it, not only a judge's quote of it.
+        task: options.testingScripts !== undefined
+            ? withTestingScripts(codeFixerTask(options), options.testingScripts.scripts, ["conformance", "unit"], options.testingScripts.root)
+            : codeFixerTask(options),
         compaction: { instructions: CODER_COMPACTION },
         ...(options.checkEnvironment !== undefined ? { checkEnvironment: options.checkEnvironment } : {}),
     });

package/dist/regenerate/conformance.js

@@ -9,7 +9,7 @@ import { abandonWork, diffSinceSnapshot, moduleDirOf, recordHistory, startWork,
 import { createWorkLedger, describeAccounts, SUBMIT_WORK_NOTE, unanswered, unansweredPrompt } from "./submit-work.js";
 import { CONFORMANCE_COMPACTION } from "./compaction.js";
 import { NOTES_TURN, notesForSession, passedOutcome, readNotes, reflectOnReview, withNotes } from "./notes.js";
-import { labelsPrompt, labelsPromptFor, misplacedConformanceTests, misplacedTestsPrompt, missingTestLabels } from "./test-kinds.js";
+import { acceptanceLabel, acceptanceText, labelsPrompt, labelsPromptFor, misplacedConformanceTests, misplacedTestsPrompt, missingTestLabels } from "./test-kinds.js";
 import { createScriptTool, findTestScripts, projectRootFor, requireTestScripts, runConformanceScript, runUnitScript, failureSignature, STUCK_ROUNDS, scriptFailure, staticChecksOnly, withTestingScripts, } from "./test-scripts.js";
 import { createWebTools, WEB_TOOLS } from "./web.js";
 import { createMyDiffTool } from "./self-check.js";
@@ -157,9 +157,11 @@ export async function renderConformanceTests(options) {
     // may read the code but writes only tests. An explorer reads the code first and writes down how the
     // software is invoked, which is what the tests are written against.
     const label = `${moduleName} ${options.diff !== undefined ? "spec change" : frid}`;
-    const specContext = { moduleName, text: specText(specifications, moduleName, frids, required, options.change ?? options.diff, sectionModules(tree, moduleName)) };
     // For a spec change: the functionalities it touches, whose acceptance tests are labelled, checked and reviewed.
     const touched = forChange ? touchedFunctionalities(tree, frids, options.diff) : [];
+    // The acceptance tests the run's tests carry out: every functionality the change touches, or the one under test.
+    const carriedOut = forChange ? touched : [{ frid: frid, acceptanceTests: specifications[ACCEPTANCE_TESTS] ?? [] }];
+    const specContext = { moduleName, text: specText(specifications, moduleName, frids, required, carriedOut, options.change ?? options.diff, sectionModules(tree, moduleName)) };
     // Any functionality of the codebase - this module's, and those of the modules it requires. A
     // functionality's run may raise a spec conflict only with that functionality; a spec diff's, between any two.
     const own = (forChange ? frids : frids.slice(0, frids.indexOf(frid) + 1)).map((id) => ({ module: moduleName, frid: id }));
@@ -223,11 +225,15 @@ export async function renderConformanceTests(options) {
     };
     stage(`exploring the code for how it is invoked${options.model ? ` (${options.model})` : ""}`);
     // The explorer reads the conformance testing script too: it is how the tests are built and run, and so how they reach the software.
+    // The prepare script, where there is one, runs on the build before it - and only once it passes does the suite run.
     const testingScripts = [
+        ...(scripts.prepare !== undefined
+            ? [{ path: relative(root, scripts.prepare), runs: "<script> <copy of the build>, before every run of the conformance testing script", content: readFileSync(scripts.prepare, "utf8"), prepare: true }]
+            : []),
         { path: relative(root, scripts.conformance), runs: "<script> <copy of the build> <copy of the whole conformance suite>", content: readFileSync(scripts.conformance, "utf8") },
     ];
     // The acceptance tests the explorer's plan has to carry out, step by step.
-    const toCarryOut = (forChange ? touched : [{ frid: frid, acceptanceTests: specifications[ACCEPTANCE_TESTS] ?? [] }])
+    const toCarryOut = carriedOut
         .map((item) => ({ module: moduleName, frid: item.frid, count: item.acceptanceTests.length }))
         .filter((item) => item.count > 0);
     let invocation = await exploreInvocation({ buildDir, spec: specContext, scope, testingScripts, acceptance: toCarryOut, label, model: options.model, onDelta: options.onDelta });
@@ -272,6 +278,7 @@ export async function renderConformanceTests(options) {
         cwd: conformanceDir,
         customTools: [
             notes.tool,
+            notes.gapTool,
             work.tool,
             ...createWebTools(),
             ...fence.tools,
@@ -285,7 +292,7 @@ export async function renderConformanceTests(options) {
             }),
             createCopyResourceTool({ resources: linkedResources, dir: conformanceDir }),
         ],
-        tools: [...fence.names, "run_conformance_tests", "my_diff", "ask_explorer", "update_notes", "submit_work", "copy_resource", ...WEB_TOOLS],
+        tools: [...fence.names, "run_conformance_tests", "my_diff", "ask_explorer", "update_notes", "report_spec_gap", "submit_work", "copy_resource", ...WEB_TOOLS],
         model: options.model,
         label: `${label} conformance agent`,
         role: "conformance",
@@ -313,12 +320,14 @@ export async function renderConformanceTests(options) {
             // The unit tests, and the conformance suite - to reproduce the failure and check the fix, seeing only its output.
             tools: [
                 fixerNotes.tool,
+                fixerNotes.gapTool,
                 createScriptTool({ kind: "unit", script: scripts.unit, run: () => runUnitScript(buildDir, scripts.unit), runs: unitRuns }),
                 fixerConformanceRuns.tool,
                 ...fixerServices.tools,
             ],
-            toolNames: ["run_unit_tests", "run_conformance_tests", ...fixerServices.names, "update_notes"],
+            toolNames: ["run_unit_tests", "run_conformance_tests", ...fixerServices.names, "update_notes", "report_spec_gap"],
             checkEnvironment: { run: () => runUnitScript(buildDir, scripts.unit), script: scripts.unit },
+            testingScripts: { scripts, root },
         });
         fixerConformanceRuns.newTurn();
         return ask(fixer, withNotes(text, buildDir), options.onDelta);
@@ -687,7 +696,7 @@ export async function renderConformanceTests(options) {
                     buildDir,
                     conformanceDir,
                     spec: specContext,
-                    functionalities: forChange ? touched : [{ frid: frid, acceptanceTests: specifications[ACCEPTANCE_TESTS] ?? [] }],
+                    functionalities: carriedOut,
                     forChange,
                     invocation,
                     label,
@@ -947,9 +956,10 @@ export function failureLine(run) {
 }
 /**
  * The spec as the explorer, the judge and the coding agent are shown it - its functional specs
- * numbered with their ids, so a spec conflict can name them.
+ * numbered with their ids, so a spec conflict can name them, and the acceptance tests the run carries
+ * out labelled as their tests are, so a verdict can quote them.
  */
-function specText(specifications, moduleName, frids, required, diff, modules) {
+function specText(specifications, moduleName, frids, required, acceptance, diff, modules) {
     // Every functionality in the codebase, each with its module: the required modules' first, then this one's.
     const numbered = (key, items) => key === FUNCTIONAL_REQUIREMENTS
         ? [
@@ -957,10 +967,14 @@ function specText(specifications, moduleName, frids, required, diff, modules) {
         ]
         : items;
     // Each section in its tag, as every agent is shown it (see specPrimer).
-    const sections = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, FUNCTIONAL_REQUIREMENTS, ACCEPTANCE_TESTS]
+    const sections = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, FUNCTIONAL_REQUIREMENTS]
         .map((key) => [key, specifications[key] ?? []])
         .filter(([, items]) => items.length > 0)
-        .map(([key, items]) => (key === FUNCTIONAL_REQUIREMENTS || key === ACCEPTANCE_TESTS ? section(key, numbered(key, items)) : moduleSection(key, items, moduleName, modules)));
+        .map(([key, items]) => (key === FUNCTIONAL_REQUIREMENTS ? section(key, numbered(key, items)) : moduleSection(key, items, moduleName, modules)));
+    // Not only the last functionality's: a spec change's run carries out the acceptance tests of every one it touches.
+    const tests = acceptance.flatMap((item) => item.acceptanceTests.map((test, index) => `${acceptanceLabel(item.frid, index + 1)}: ${acceptanceText(test)}`));
+    if (tests.length > 0)
+        sections.push(section(ACCEPTANCE_TESTS, tests));
     if (diff !== undefined)
         sections.push(specChangeBlock(diff));
     return sections.join("\n\n");