@turri-dev/cli 0.1.3-next.f74e98a → 0.1.4-next.246fd84

package/dist/regenerate/loop.js

@@ -16,7 +16,7 @@ import { modulesRoot } from "./paths.js";
 import { budgetFor, choosingWhen, configForSpec, conformanceSwitchedOn } from "../config.js";
 import { describeSpecChange } from "./prompt.js";
 import { resolveTemplateDirs } from "./paths.js";
-import { builtTips, copyRequiredCode, newlyRequired, resolveRequiresChain, startFromScratch } from "./requires.js";
+import { builtTips, copyRequiredCode, importingModules, isImportModule, newlyRequired, resolveRequiresChain, startFromScratch } from "./requires.js";
 import { withTryItLine } from "./delivery.js";
 import { describeSpecDiff, renderSpecDiff, specFilesOf } from "./regenerate.js";
 import { locateDiffLines } from "./diff-view.js";
@@ -85,6 +85,23 @@ function chainsFor(plainFile) {
     const tips = builtTips(plainFile);
     return tips.length > 0 ? tips : [resolveRequiresChain(plainFile, [], undefined, { allowNoFunctionalities: true })];
 }
+/**
+ * The modules a .plain file is built as: itself - or, an import module, the modules importing it whose code is started.
+ * An import module is no codebase; one no started module imports has nothing to build yet - its reqs are built with the
+ * first module that imports it.
+ */
+function codebasesOf(plainFile) {
+    if (!isImportModule(plainFile))
+        return [plainFile];
+    return importingModules(plainFile).filter((file) => {
+        try {
+            return builtTips(file).length > 0 || started(resolveRequiresChain(file, [], undefined, { allowNoFunctionalities: true }).at(-1));
+        }
+        catch {
+            return false;
+        }
+    });
+}
 /** How many functional specs of its own a codebase has built - none when it was only started from the code below it. */
 function ownBuilt(entry) {
     return (readRecord(entry.buildDir)?.[FUNCTIONAL_REQUIREMENTS] ?? []).length;
@@ -361,6 +378,8 @@ export function createWorkLoop(options) {
             const waiting = (why) => ({ module: entry.moduleName, why: `waiting for ${entry.moduleName}: ${why}` });
             if (below.running !== undefined)
                 return waiting(below.running.planned.track === "conformance" ? "its conformance tests are being written" : "the code it is built on is not built yet");
+            if (below.held !== undefined)
+                return waiting("you halted it - nothing is built on it until it is asked for again");
             const spec = chainSpec(below.chain);
             if (codeWork(builtOf(below), spec.tree).length > 0)
                 return waiting("the code it is built on is not built yet");
@@ -469,6 +488,11 @@ export function createWorkLoop(options) {
     /** A dry run's first jobs, by codebase: what each would start. */
     const firsts = new Map();
     const startJob = (state, spec, from, planned) => {
+        // Halted while it was being planned: the plan is made, nothing starts.
+        if (state.held !== undefined) {
+            state.why = state.held.why;
+            return;
+        }
         const tip = tipEntry(state);
         if (options.dryRun === true) {
             firsts.set(tip.buildDir, { spec: planned.track === "conformance" ? spec : { ...spec, tree: planned.step.tree }, planned });
@@ -756,16 +780,37 @@ export function createWorkLoop(options) {
         }
         return states;
     };
+    /** A codebase the loop no longer looks after: nothing of it is shown, planned or waited for. */
+    const forget = (state) => {
+        const key = tipEntry(state).buildDir;
+        modules.delete(key);
+        order.splice(order.indexOf(key), 1);
+    };
     const lookAll = async () => {
+        // A .plain file taken out of the project is asked for no more, and a codebase whose module's file is gone is
+        // forgotten - nothing running there - rather than shown waiting for a plan it will never have.
+        for (const file of [...asked.keys()])
+            if (!existsSync(file))
+                asked.delete(file);
+        for (const key of [...order]) {
+            const state = modules.get(key);
+            if (state.running === undefined && !existsSync(tipEntry(state).plainFile))
+                forget(state);
+        }
         const now = active();
         looking = now;
         for (const key of order) {
             const state = modules.get(key);
-            // A codebase left behind - built on since - is not looked at, unless a job of it is still running.
+            // A codebase left behind - built on since - is not looked at, unless a job of it is still running; what it had
+            // planned, or waited for, is no longer shown.
             if (now.has(state) || state.running !== undefined)
                 await look(state);
-            else
+            else {
                 state.why = "left behind: the code is built on further up the chain, where changes to it are made";
+                state.waitsFor = undefined;
+                state.plan = undefined;
+                state.conformancePlan = undefined;
+            }
         }
     };
     const look = async (state) => {
@@ -776,6 +821,12 @@ export function createWorkLoop(options) {
         }
         catch (error) {
             state.why = `its spec does not parse: ${error instanceof Error ? error.message : String(error)}`;
+            // Not planned from a spec that does not parse: what it waited for, and the plan, were the spec's before.
+            state.waitsFor = undefined;
+            if (state.running === undefined) {
+                state.plan = undefined;
+                state.conformancePlan = undefined;
+            }
             return;
         }
         const specKey = keyOf(spec);
@@ -828,6 +879,11 @@ export function createWorkLoop(options) {
             return;
         }
         hashResources(state, spec);
+        if (state.held !== undefined) {
+            state.why = state.held.why;
+            state.waitsFor = undefined;
+            return;
+        }
         if (state.halted !== undefined) {
             if (state.halted.specKey === specKey) {
                 state.why = state.halted.why;
@@ -988,13 +1044,18 @@ export function createWorkLoop(options) {
         return state;
     };
     const loop = {
-        async bringUp(plainFile, request = {}) {
-            const file = resolve(options.cwd, plainFile);
-            asked.set(file, { ...asked.get(file), ...request });
-            const states = withParseCache(() => chainsFor(file).flatMap((chain) => toBuild(chain).map((entry) => track(chain.slice(0, chain.indexOf(entry) + 1), file, request))));
-            // Asked again, a halted codebase is tried again.
-            for (const state of states)
+        async bringUp(plainFile, given = {}) {
+            const { specChange, ...request } = given;
+            const files = codebasesOf(resolve(options.cwd, plainFile));
+            for (const file of files)
+                asked.set(file, { ...asked.get(file), ...request });
+            const states = withParseCache(() => files.flatMap((file) => chainsFor(file).flatMap((chain) => toBuild(chain).map((entry) => track(chain.slice(0, chain.indexOf(entry) + 1), file, request)))));
+            // Asked again, a halted codebase is tried again - one the person halted too, unless only its spec changed.
+            for (const state of states) {
                 state.halted = undefined;
+                if (specChange !== true)
+                    state.held = undefined;
+            }
             await tick();
             return [...new Set(states)].map(statusOf);
         },
@@ -1062,7 +1123,7 @@ export function createWorkLoop(options) {
                 report.scheduled = (state.scheduled ?? []).map((group) => ({ frids: group.specs.map((touched) => touched.frid), unbuilt: group.unbuilt }));
                 if (state.running !== undefined)
                     report.running = { jobId: state.running.jobId, title: state.running.planned.title };
-                const halted = state.halted?.why ?? state.conformanceHalted?.why;
+                const halted = state.held?.why ?? state.halted?.why ?? state.conformanceHalted?.why;
                 if (halted !== undefined)
                     report.why = halted;
                 if (state.startOver !== undefined)
@@ -1149,6 +1210,7 @@ export function createWorkLoop(options) {
                 }
                 state.conformanceHalted = undefined;
                 state.halted = undefined;
+                state.held = undefined;
             }
             await tick();
             return [...new Set(states)].map((state) => {
@@ -1191,6 +1253,50 @@ export function createWorkLoop(options) {
                     startAgain(entry, "asked to be regenerated from scratch");
             return loop.bringUp(plainFile, request);
         },
+        halt(target, reason) {
+            const named = target.trim();
+            // A planned row's module - the longest name its id starts with, as a name may hold a hyphen - or a module by its name.
+            const state = order
+                .map((key) => modules.get(key))
+                .filter((candidate) => {
+                const name = tipEntry(candidate).moduleName;
+                return named === name || named.startsWith(`planned-${name}-`);
+            })
+                .sort((a, b) => tipEntry(b).moduleName.length - tipEntry(a).moduleName.length)[0];
+            if (state === undefined)
+                return undefined;
+            const tip = tipEntry(state);
+            if (state.running === undefined && !existsSync(tip.plainFile)) {
+                forget(state);
+                asked.delete(tip.plainFile);
+                return `${tip.moduleName} is no longer in the project - ${basename(tip.plainFile)} is gone - so nothing was to be built there: it is dropped from the regeneration.`;
+            }
+            const planned = statusOf(state).planned.length;
+            const said = reason !== undefined && reason.trim() !== "" ? ` (${reason.trim()})` : "";
+            state.held = { why: `you halted it${said} - nothing runs here until it is asked for again` };
+            state.why = state.held.why;
+            state.waitsFor = undefined;
+            state.plan = undefined;
+            state.conformancePlan = undefined;
+            const running = state.running;
+            if (running !== undefined && running.stopping !== true) {
+                running.stopping = true;
+                options.registry.stop(running.jobId, `Halted by you${said}: what it had done is rolled back, and nothing more runs in ${tip.moduleName} until it is asked for again.`);
+            }
+            const above = order
+                .map((key) => modules.get(key))
+                .filter((other) => other !== state && looking.has(other) && other.chain.some((entry) => entry.buildDir === tip.buildDir))
+                .map((other) => tipEntry(other).moduleName);
+            void tick();
+            return [
+                `Halted ${tip.moduleName}${said}:`,
+                running !== undefined ? ` its running pulse ${running.jobId} is being stopped, and what it had done rolled back;` : "",
+                planned > 0 ? ` its ${planned} planned pulse${planned === 1 ? "" : "s"} will not start.` : " nothing more is planned there.",
+                " Pulses that landed stay.",
+                above.length > 0 ? ` ${above.join(", ")} ${above.length === 1 ? "waits" : "wait"} for it.` : "",
+                ` It runs again only when asked for - regenerate ${basename(tip.plainFile)} - a spec change does not start it.`,
+            ].join("");
+        },
         status() {
             return order.map((key) => statusOf(modules.get(key)));
         },

package/dist/regenerate/notes.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { reportActivity } from "./activity.js";
@@ -40,7 +40,6 @@ export const SECTIONS = {
     where: "Where things are",
     run: "How to build, run and test",
     assumptions: "Assumptions",
-    gaps: "Spec gaps",
     pitfalls: "Pitfalls",
     pulses: "Pulses",
 };
@@ -53,8 +52,13 @@ export function notesPath(buildDir) {
     return join(buildDir, NOTES_FILE);
 }
 function empty() {
-    return { where: [], run: [], assumptions: [], gaps: [], pitfalls: [], pulses: [] };
+    return { where: [], run: [], assumptions: [], pitfalls: [], pulses: [] };
 }
+/**
+ * Sections the notes no longer have, their lines dropped as they are read: the spec gaps are the person's, reported
+ * with report_spec_gap - the choice made meanwhile is an assumption, which stays.
+ */
+const DROPPED = new Set(["spec gaps"]);
 /** The notes, as lines per section. Lines under no known heading go to pitfalls, not lost. */
 export function parseNotes(text) {
     const notes = empty();
@@ -63,11 +67,12 @@ export function parseNotes(text) {
         const line = raw.trim();
         const heading = /^##\s+(.+)$/.exec(line);
         if (heading) {
-            section = ORDER.find((key) => SECTIONS[key].toLowerCase() === heading[1].trim().toLowerCase()) ?? section;
+            const named = heading[1].trim().toLowerCase();
+            section = DROPPED.has(named) ? undefined : (ORDER.find((key) => SECTIONS[key].toLowerCase() === named) ?? section ?? "pitfalls");
             continue;
         }
         const item = /^[-*]\s+(.+)$/.exec(line);
-        if (item)
+        if (item && section !== undefined)
             notes[section].push(item[1].trim());
     }
     return notes;
@@ -93,14 +98,14 @@ const GUIDANCE = [
     `- ${SECTIONS.where}: entry points, layout, where each functionality and its tests live.`,
     `- ${SECTIONS.run}: the commands that build, run and test it, and what had to be installed for them.`,
     `- ${SECTIONS.assumptions}: what you assumed where the specification is silent - a format, a default, a`,
-    "  choice it leaves open. Build on the assumptions already there; change or remove one the moment the code",
-    "  or the specification shows it wrong.",
-    `- ${SECTIONS.gaps}: what the specification should say and does not - a behaviour you had to decide that the`,
-    "  person would want to decide, not a detail of how. Each is put to the person, to be written into the",
-    "  specification. One a line, as the question it leaves: \"What happens to a contact archived in HubSpot after it",
-    "  was synced?\"",
+    "  choice it leaves open - and the tests that assert it, when any do: \"A Dash drains Pulses at 1/s - asserted in",
+    "  predators.test.ts, The Dash\". One no test asserts is written down all the same. Build on the assumptions",
+    "  already there; change or remove one the moment the code or the specification shows it wrong - and the tests",
+    "  it names with it.",
     `- ${SECTIONS.pitfalls}: what went wrong and what fixed it, approaches that did not work.`,
     `- ${SECTIONS.pulses}: written by turri as each pulse ends - read them, never write them.`,
+    "A behaviour you had to decide that the person would want to decide - not a detail of how - is not a note: report",
+    "it with report_spec_gap, with the assumption you made meanwhile.",
     "Each line stands on its own, for someone who never saw your work. When and where it came from is added",
     "to it for you - do not write it. Where two lines disagree, the later one is right: change the older one",
     'rather than add a contradicting line. Leave a section with nothing new alone: "none" is not a note.',
@@ -232,7 +237,7 @@ export function createNotesTool(buildDir, onWrite, before = () => { }, source) {
         label: "Update notes",
         description: "Update the working notes on this codebase for the next agent - add a line, change one that is no longer " +
             "true, remove one that is wrong - in its sections: where things are, how to build, run and test, " +
-            "assumptions made where the specification is silent, spec gaps the person should decide, and pitfalls. Never " +
+            "assumptions made where the specification is silent, and pitfalls. Never " +
             "requirements: the specification is never an assumption.",
         promptSnippet: "leave the next agent what you learned and assumed about this codebase",
         parameters: Type.Object({
@@ -283,7 +288,7 @@ export function sectionNamed(name) {
 /** How many times an agent that finishes without update_notes is asked to call it. */
 export const NOTES_ASKS = 3;
 /** The turn that asks for the notes: update_notes is the only tool it may use - the work it follows is done. */
-export const NOTES_TURN = { onlyTools: ["update_notes"] };
+export const NOTES_TURN = { onlyTools: ["update_notes", "report_spec_gap"] };
 /** What the notes turn says first, once the harness's own run of `script` has passed on the work. */
 export function passedOutcome(script) {
     return (`The harness ran the project's ${script} on your work itself, and it passed: your work is done and accepted. ` +
@@ -327,10 +332,53 @@ export function recordPulse(buildDir, text, source) {
         // The notes are a help, not the work.
     }
 }
-/** The lines of a section added since `before` - a pulse's new spec gaps, say - without when and where they came from. */
-export function linesAddedSince(before, buildDir, section) {
-    const known = new Set(before[section]);
-    return readNotes(buildDir)[section].filter((line) => !known.has(line)).map((line) => line.replace(/^\[[^\]]*\]\s*/, ""));
+/** Every spec gap reported in this process, with the codebase it was met in: a pulse reads those since it started. */
+const reportedGaps = [];
+/** Where the spec gaps stand now: what `gapsSince` reads from. */
+export function gapMark() {
+    return reportedGaps.length;
+}
+/** The spec gaps reported in these codebases since `mark`. */
+export function gapsSince(mark, dirs) {
+    const wanted = new Set(dirs.map((dir) => resolve(dir)));
+    return reportedGaps.slice(mark).filter((entry) => wanted.has(entry.dir)).map((entry) => entry.gap);
+}
+/**
+ * `report_spec_gap`: a behaviour the specification leaves open that the person would want to decide, put to them as
+ * the pulse ends - never into the notes, which are the next agent's. What the agent decided meanwhile goes into the
+ * notes' assumptions, so the code built on it is known for what it is until the specification settles it.
+ */
+export function createSpecGapTool(buildDir, source) {
+    return defineTool({
+        name: "report_spec_gap",
+        label: "Report a spec gap",
+        description: "Report a spec gap: a behaviour the specification leaves open that the person would want to decide - not a detail " +
+            "of how. Decide it meanwhile and carry on: the person is asked once the work ends, and what they decide is " +
+            "written into the specification. The assumption you made is added to the notes' assumptions for you.",
+        promptSnippet: "tell the person about a behaviour the specification leaves open, and what you decided meanwhile",
+        parameters: Type.Object({
+            question: Type.String({ description: 'The question it leaves the person, one line: "What happens to a contact archived in HubSpot after it was synced?"' }),
+            assumption: Type.String({
+                description: "What you decided meanwhile, as its line in the notes' assumptions - with the tests that assert it, when any do: " +
+                    '"An archived contact is left as synced - asserted in sync.test.ts, archived contacts".',
+            }),
+        }),
+        async execute(_id, params) {
+            const question = params.question.replace(/\s+/g, " ").trim();
+            const assumption = params.assumption.replace(/\s+/g, " ").trim();
+            if (question === "" || assumption === "")
+                throw new Error("Nothing reported - a spec gap needs both the question it leaves and the assumption you made meanwhile.");
+            // However many there are, spec gaps are put to the person - never a reason to stop the pulse.
+            reportedGaps.push({ dir: resolve(buildDir), gap: { question, assumption } });
+            const known = readNotes(buildDir).assumptions.some((line) => body(line) === assumption);
+            if (!known)
+                recordNote(buildDir, "assumptions", assumption, source ?? "spec gap");
+            return {
+                content: [{ type: "text", text: `Reported. The assumption is in the notes' assumptions${known ? " already" : " now"} - do not add it again.` }],
+                details: { question, assumption },
+            };
+        },
+    });
 }
 /** The notes, for an agent that reads them but leaves none - a judge. Empty when there are none. */
 export function notesToRead(buildDir) {
@@ -367,6 +415,7 @@ export function notesForSession(buildDir, source) {
         return true;
     };
     return {
+        gapTool: createSpecGapTool(buildDir, source),
         tool: createNotesTool(buildDir, (text) => {
             written = true;
             knownNotes.set(file, text);

package/dist/regenerate/prompt.js

@@ -278,8 +278,10 @@ function itemText(serialized) {
         return item;
     const { markdown, [ACCEPTANCE_TESTS]: tests } = (item ?? {});
     const lines = [markdown ?? JSON.stringify(item)];
+    // Each test is an item of the tree, its text in its markdown - as spec-steps.ts `itemText` reads it.
+    const testText = (test) => (typeof test === "string" ? test : (test?.markdown ?? JSON.stringify(test)));
     if (Array.isArray(tests) && tests.length > 0)
-        lines.push("  <acceptance tests>", ...tests.map((test) => `  ${String(test)}`), "  </acceptance tests>");
+        lines.push("  <acceptance tests>", ...tests.map((test) => `  ${testText(test).replace(/\n/g, "\n  ")}`), "  </acceptance tests>");
     return lines.join("\n");
 }
 const indent = (text, by) => text.split("\n").map((line) => `${by}${line}`).join("\n");

package/dist/regenerate/regenerate.js

@@ -14,7 +14,7 @@ import { buildSpecDiffPrompt, describeSpecChange, reviewedSpec, sectionModules }
 import { abandonWork, recordHistory, startWork } from "./lineage.js";
 import { createWorkLedger, SUBMIT_WORK_NOTE } from "./submit-work.js";
 import { CODER_COMPACTION } from "./compaction.js";
-import { linesAddedSince, NOTES_TURN, notesForSession, passedOutcome, readNotes, recordNote, withNotes } from "./notes.js";
+import { gapMark, gapsSince, NOTES_TURN, notesForSession, passedOutcome, recordNote, withNotes } from "./notes.js";
 import { createLoopWatch, createScriptTool, failureSignature, findTestScripts, projectRootFor, requireTestScripts, runUnitScript, STUCK_ROUNDS, withoutConformance, withTestingScripts, } from "./test-scripts.js";
 import { createWebTools, WEB_TOOLS } from "./web.js";
 import { createCanItFailTool, createMyDiffTool, selfCheckNote } from "./self-check.js";
@@ -268,8 +268,8 @@ export async function renderSpecDiff(options) {
         ...(options.cases !== undefined ? { cases: options.cases } : {}),
     });
     const digestsBefore = digestFiles(buildDir);
-    // The notes as the agent finds them: what it adds - a spec gap above all - is told with the result.
-    const notesBefore = readNotes(buildDir);
+    // The spec gaps its agents report from here on are told with the result.
+    const gapsFrom = gapMark();
     /** What the debugger found, each time it was asked: the pulse's line in the notes says it. */
     const diagnosed = [];
     const runs = [];
@@ -305,6 +305,7 @@ export async function renderSpecDiff(options) {
         cwd: buildDir,
         customTools: [
             notes.tool,
+            notes.gapTool,
             work.tool,
             ...createWebTools(),
             createScriptTool({ kind: "unit", script: scripts.unit, run: () => runUnitScript(buildDir, scripts.unit), runs, watch: loop }),
@@ -313,7 +314,7 @@ export async function renderSpecDiff(options) {
             ...fence.tools,
             createCopyResourceTool({ resources: linkedResources, dir: buildDir }),
         ],
-        tools: [...fence.names, "run_unit_tests", ...selfChecks.map((tool) => tool.name), ...services.names, "update_notes", "submit_work", "copy_resource", ...WEB_TOOLS],
+        tools: [...fence.names, "run_unit_tests", ...selfChecks.map((tool) => tool.name), ...services.names, "update_notes", "report_spec_gap", "submit_work", "copy_resource", ...WEB_TOOLS],
         model: options.model,
         label: `${moduleName} spec change coding agent`,
         role: "coding",
@@ -499,6 +500,7 @@ export async function renderSpecDiff(options) {
                 ...(options.cases !== undefined ? { cases: options.cases } : {}),
                 label: `${moduleName} spec change`,
                 ...(scripts.runOn === "copy" ? { unitScript: scripts.unit } : {}),
+                testingScript: { path: relative(root, scripts.unit), content: readFileSync(scripts.unit, "utf8") },
                 model: options.judgeModel ?? modelSpec(inheritModel(configForSpec(tip.plainFile).judgeModel, modelOnly(options.model))),
                 send: async (next) => {
                     response = await ask(executor, next, options.onDelta);
@@ -541,8 +543,8 @@ export async function renderSpecDiff(options) {
         testRemovals,
         files,
         ...(steering !== undefined && steering.steers > 0 ? { steered: [...steering.notes] } : {}),
-        // Read before a rollback takes the notes back: a gap the agent met is the person's to decide, whether it landed or not.
-        specGaps: linesAddedSince(notesBefore, buildDir, "gaps"),
+        // A gap the agent met is the person's to decide, whether it landed or not.
+        specGaps: gapsSince(gapsFrom, [buildDir]),
         diagnosed,
     };
     /** The change landed: what the code is built from is now the spec with the change in, committed with it. */
@@ -579,8 +581,10 @@ export function specGapsText(gaps) {
         return [];
     return [
         "",
-        "Spec gaps its agents met - the spec does not say, so they decided. Put each to the user, and write the ones they decide into the spec:",
-        ...gaps.map((gap) => `- ${gap}`),
+        "Spec gaps its agents met - the spec does not say, so they decided, each as an assumption in the codebase's notes. Put " +
+            "each to the user, and write the ones they decide into the spec - the pulse that builds it is told the assumption " +
+            "it replaces:",
+        ...gaps.map((gap) => `- ${gap.question} Meanwhile: ${gap.assumption}`),
     ];
 }
 /** What a rendered spec change did, for the agent and the person. */

package/dist/regenerate/regression.js

@@ -21,7 +21,7 @@ import { keepingTestsUnchanged, listFiles } from "./testing.js";
  * job ends on it: tests that pass on their own are not done until the whole suite passes with them.
  */
 /** On top of the file tools, which are fenced to the build directory by `confine.ts`. */
-const FIX_TOOLS = ["run_unit_tests", "run_conformance_tests", "update_notes"];
+const FIX_TOOLS = ["run_unit_tests", "run_conformance_tests", "update_notes", "report_spec_gap"];
 const DEFAULT_MAX_REGRESSION_ROUNDS = ATTEMPTS.regression;
 /** The module's conformance tests, when there are any: the chain's, copied up, and its own. */
 function conformanceDirs(conformanceRoot, moduleName) {
@@ -39,6 +39,7 @@ async function repairRegression(input) {
         cwd: input.buildDir,
         customTools: [
             notes.tool,
+            notes.gapTool,
             ...createWebTools(),
             ...fence.tools,
             createScriptTool({ kind: "unit", script: input.scripts.unit, run: () => runUnitScript(input.buildDir, input.scripts.unit), runs }),

package/dist/regenerate/requires.js

@@ -1,6 +1,6 @@
-import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, withParseCache } from "../plain/parser.js";
+import { IMPORT_DIRECTIVE, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata, withParseCache } from "../plain/parser.js";
 import { getFrids, getInheritedFunctionalSpecs } from "../plain/spec.js";
 import { buildDirUnder, modulesRoot, projectDirOf } from "./paths.js";
 import { notesPath } from "./notes.js";
@@ -54,6 +54,59 @@ options = {}) {
     visit(resolve(plainFile), []);
     return chain;
 }
+/** The .plain files that import `plainFile` - read from beside it, and, kept in a `template/` folder, from the folder it is in. */
+function importersOf(plainFile) {
+    const file = resolve(plainFile);
+    const dir = dirname(file);
+    const name = basename(file, PLAIN_SOURCE_FILE_EXTENSION);
+    const dirs = [dir, ...(basename(dir) === "template" ? [dirname(dir)] : [])];
+    return dirs.flatMap((at) => {
+        let names;
+        try {
+            names = readdirSync(at).filter((entry) => entry.endsWith(PLAIN_SOURCE_FILE_EXTENSION));
+        }
+        catch {
+            return [];
+        }
+        return names
+            .map((entry) => join(at, entry))
+            .filter((path) => {
+            if (path === file || !resolveTemplateDirs(path).includes(dir))
+                return false;
+            try {
+                return (readPlainSourceMetadata(readFileSync(path, "utf8")).metadata[IMPORT_DIRECTIVE] ?? []).includes(name);
+            }
+            catch {
+                return false;
+            }
+        });
+    });
+}
+/**
+ * Whether a .plain file is an import module - one a .plain file imports, or one kept in a `template/` folder - rather than
+ * a module of its own. It is no codebase: its reqs and definitions are built in the modules that import it.
+ */
+export function isImportModule(plainFile) {
+    return basename(dirname(resolve(plainFile))) === "template" || importersOf(plainFile).length > 0;
+}
+/** The modules of their own that import an import module, through any import modules between. */
+export function importingModules(plainFile) {
+    const found = new Set();
+    const seen = new Set();
+    const walk = (file) => {
+        if (seen.has(file))
+            return;
+        seen.add(file);
+        for (const importer of importersOf(file)) {
+            if (isImportModule(importer))
+                walk(importer);
+            else
+                found.add(importer);
+        }
+    };
+    walk(resolve(plainFile));
+    return [...found];
+}
 /**
  * The codebase a change to `plainFile`'s module lands in: the furthest-built module whose
  * requires chain includes it, with that chain.

package/dist/regenerate/spec-map-view.js

@@ -329,7 +329,7 @@ function detailLines(item, width, style) {
     // The rest of its text - its first line is the row - against the record's, for a change.
     const rest = item.state === "changed" ? lineDiff(item.was ?? "", item.text).slice(1) : item.text.split("\n").slice(1).map((line) => ({ was: line, now: line }));
     for (const line of rest) {
-        const drawn = item.state === "removed" ? style.removed(strike(line.now ?? "")) : item.state === "changed" ? diffLine(line, style) : highlighted(line.now ?? "", style);
+        const drawn = item.state === "removed" ? style.removed(strike(line.now ?? "")) : item.state === "changed" ? diffLine(line, style) : item.state === "new" ? style.added(line.now ?? "") : highlighted(line.now ?? "", style);
         lines.push(...wrapped(drawn, width));
     }
     if (item.acceptance.length > 0) {
@@ -476,7 +476,9 @@ export function specMapLines(pages, state, width, style, _jobs = [], now = Date.
             ? style.removed(strike(first))
             : item.state === "changed" && wasFirst !== first
                 ? wordDiff(wasFirst, first, style)
-                : highlighted(first, style);
+                : item.state === "new"
+                    ? style.added(first)
+                    : highlighted(first, style);
         // Wrapped, never cut short: what follows a `…` is what a person came to read. The lines after the first hang
         // under the item's text, past its bullet.
         const [head = "", ...rest] = hanging(drawn, first, room);

package/dist/regenerate/unit-review.js

@@ -63,6 +63,17 @@ export function unitReviewTask(options) {
         options.spec.trim(),
         "</specification>",
         "",
+        ...(options.testingScript !== undefined
+            ? [
+                "The harness runs the unit tests with this script, and it decides whether they pass. Read it for which tests it",
+                "runs and how: a test it never reaches - a file it does not pick up, a folder it does not look in - is not run, and",
+                "checks nothing.",
+                `<unit testing script path="${options.testingScript.path}">`,
+                options.testingScript.content.trimEnd(),
+                "</unit testing script>",
+                "",
+            ]
+            : []),
         ...(options.cases !== undefined ? [...codeReviewCasesBlock(options.cases), ""] : []),
         // A job that touches no functional spec is held only to that: the checks of behaviour are not its.
         ...(mechanical ? [] : ["Check that the code does what the specification states for this work:"]),

package/dist/release-tools.js

@@ -142,7 +142,7 @@ export function createDeployTools(options) {
         },
     });
     // The one halt: with the pulses in the conversation, and without them for the release agent.
-    const stopTool = haltTool(options.jobs !== undefined ? { jobs: options.jobs } : {});
+    const stopTool = haltTool(options.jobs !== undefined ? { jobs: options.jobs, ...(options.workLoop !== undefined ? { workLoop: options.workLoop } : {}) } : {});
     return [deploy, startTool, stopTool];
 }
 export const DEPLOY_TOOLS = ["release", "activate", "halt"];

package/dist/resume-line.js

@@ -0,0 +1,4 @@
+/** pi's line on the way out that says how to resume the session, with turri in place of pi as the command to run. */
+export function resumeLine(text) {
+    return text.replace(/^((?:\x1b\[[0-9;]*m)*To resume this session:(?:\x1b\[[0-9;]*m)*\s+)pi(?= )/m, "$1turri");
+}