@turri-dev/cli 0.1.3-next.f74e98a → 0.1.4-next.172be6f

package/dist/regenerate/list-arguments.js

@@ -0,0 +1,121 @@
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** The tool's arguments that take a list of objects. */
+function listArguments(schema) {
+    const required = new Set(schema.required ?? []);
+    return Object.entries(schema.properties ?? {})
+        .filter(([, property]) => property.type === "array" && property.items?.type === "object")
+        .map(([name, property]) => ({ name, required: required.has(name), item: property.items }));
+}
+/** JSON text, fenced or not, as what it holds; anything else as it is. */
+function parsed(value) {
+    if (typeof value !== "string")
+        return value;
+    const text = value
+        .trim()
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/\s*```$/, "");
+    if (!/^[[{]/.test(text))
+        return value;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return value;
+    }
+}
+const escaped = (name) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Arguments the model wrote inside another argument's text - `answer</a>\n<b>[...]</b>\n<c>...` - taken out of it and
+ * given as their own, where they were not given already. Which argument each was found in, for the refusal.
+ */
+function untucked(args, names) {
+    const out = { ...args };
+    const foundIn = new Map();
+    const anyTag = names.map(escaped).join("|");
+    for (const [key, value] of Object.entries(args)) {
+        if (typeof value !== "string")
+            continue;
+        let cut = value.search(new RegExp(`</${escaped(key)}>`));
+        for (const name of names) {
+            if (name === key || (out[name] !== undefined && out[name] !== ""))
+                continue;
+            const match = new RegExp(`<${escaped(name)}>([\\s\\S]*?)(?:</${escaped(name)}>|(?=<(?:${anyTag})>)|$)`).exec(value);
+            if (match === null)
+                continue;
+            out[name] = match[1].trim();
+            foundIn.set(name, key);
+            cut = cut === -1 ? match.index : Math.min(cut, match.index);
+        }
+        if (cut !== -1)
+            out[key] = value.slice(0, cut).trim();
+    }
+    return { args: out, foundIn };
+}
+/** What an entry of the list looks like, as JSON: its fields, the optional ones marked. */
+function shapeOf(item) {
+    const required = new Set(item.required ?? []);
+    const entries = Object.entries(item.properties ?? {});
+    const fields = entries.map(([name, field]) => `"${name}"${required.has(name) ? "" : "?"}: ${field.type ?? "value"}`).join(", ");
+    const sample = (field) => (field.type === "number" || field.type === "integer" ? "1" : field.type === "boolean" ? "true" : field.type === "string" ? '"..."' : "...");
+    const example = entries
+        .filter(([name]) => required.has(name))
+        .map(([name, field]) => `"${name}": ${sample(field)}`)
+        .join(", ");
+    return { fields: `{${fields}}`, example: `{${example}}` };
+}
+/** Why a list argument is not one, said so a model can make the call right next time - or undefined when it is. */
+function problemOf(list, value, foundIn) {
+    if (value === undefined)
+        return list.required ? "you left it out" : undefined;
+    if (!Array.isArray(value)) {
+        if (foundIn !== undefined)
+            return `you wrote it inside \`${foundIn}\``;
+        return typeof value === "string" ? "you sent it as text, not a list" : `you sent ${isObject(value) ? "an object" : `a ${typeof value}`}, not a list`;
+    }
+    const bad = value.findIndex((entry) => !isObject(entry));
+    if (bad === -1)
+        return undefined;
+    return `entry ${bad + 1} is ${typeof value[bad] === "string" ? "text" : `a ${typeof value[bad]}`}, not an object`;
+}
+/** The arguments with their lists made lists where they plainly are; refused, saying what is wanted, where they are not. */
+export function prepareListArguments(toolName, schema, raw) {
+    const lists = listArguments(schema);
+    if (lists.length === 0 || !isObject(raw))
+        return raw;
+    const { args, foundIn } = untucked(raw, Object.keys(schema.properties ?? {}));
+    const problems = [];
+    for (const list of lists) {
+        let value = parsed(args[list.name]);
+        if (isObject(value))
+            value = [value];
+        if (Array.isArray(value))
+            value = value.map(parsed);
+        if (value !== undefined)
+            args[list.name] = value;
+        const problem = problemOf(list, value, foundIn.get(list.name));
+        if (problem === undefined)
+            continue;
+        const { fields, example } = shapeOf(list.item);
+        problems.push(`- \`${list.name}\`: ${problem}. It is a list of objects, each ${fields} - e.g. "${list.name}": [${example}].`);
+    }
+    if (problems.length === 0)
+        return args;
+    throw new Error([
+        `${toolName} was not run - its arguments are not in the shape it takes:`,
+        ...problems,
+        "Each argument is a field of its own in the call, at the top level: a list is a JSON array of objects, never text, and never written inside another argument's text.",
+    ].join("\n"));
+}
+/** The tools, each that takes a list of objects preparing its arguments so before they are checked. */
+export function withListArguments(tools) {
+    return tools.map((tool) => {
+        const schema = tool.parameters;
+        if (listArguments(schema).length === 0)
+            return tool;
+        const before = tool.prepareArguments;
+        return {
+            ...tool,
+            prepareArguments: (args) => prepareListArguments(tool.name, schema, before !== undefined ? before(args) : args),
+        };
+    });
+}

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 });
@@ -573,7 +597,14 @@ export function createWorkLoop(options) {
                 }
                 return {
                     report: released !== undefined ? `${report}\n\n${released}` : report,
-                    details: { passed: result.landed, landed: result.landed, ...(released !== undefined ? { released: true } : {}), ...(result.story !== undefined ? { story: result.story } : {}) },
+                    details: {
+                        passed: result.landed,
+                        landed: result.landed,
+                        ...(released !== undefined ? { released: true } : {}),
+                        ...(result.story !== undefined ? { story: result.story } : {}),
+                        // The spec gaps its agents met, for a headless run to say - in the chat the report puts them to the person.
+                        ...(result.specGaps !== undefined && result.specGaps.length > 0 ? { specGaps: result.specGaps } : {}),
+                    },
                 };
             },
         });
@@ -756,16 +787,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 +828,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 +886,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 +1051,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 +1130,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 +1217,7 @@ export function createWorkLoop(options) {
                 }
                 state.conformanceHalted = undefined;
                 state.halted = undefined;
+                state.held = undefined;
             }
             await tick();
             return [...new Set(states)].map((state) => {
@@ -1178,19 +1247,67 @@ export function createWorkLoop(options) {
                 startAgain(entry, `it now requires ${requires.join(", ")}, which its code was not built on`);
             return loop.bringUp(plainFile, request);
         },
-        async fromScratch(plainFile, request = {}) {
+        async fromScratch(plainFile, { chain, ...request } = {}) {
             const file = resolve(options.cwd, plainFile);
-            // Where its code lives: the tips its module is built in, or - none built yet - its own codebase.
-            const codebases = chainsFor(file).map(tipOf);
+            // Where its code lives: the tips its module is built in, or - none built yet - its own codebase. The whole chain:
+            // every codebase in those chains, bottom first - a tip taken back to nothing is otherwise started from a copy of
+            // the code below it.
+            const chains = chainsFor(file);
+            const codebases = [...new Map((chain === true ? chains.flat() : chains.map(tipOf)).map((entry) => [entry.buildDir, entry])).values()];
             for (const entry of codebases) {
                 if (modules.get(entry.buildDir)?.running !== undefined)
                     throw new Error(`${entry.moduleName} has a pulse running: halt it, or ask again once it is done.`);
             }
+            const why = chain === true ? "asked to be regenerated from scratch, with its whole chain" : "asked to be regenerated from scratch";
             for (const entry of codebases)
                 if (started(entry))
-                    startAgain(entry, "asked to be regenerated from scratch");
+                    startAgain(entry, why);
             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)));
         },
@@ -1405,7 +1522,7 @@ export function describeModules(statuses, options = {}) {
                 `  Ask the user whether to start ${codebases.join(", ")} over, and say why: ${codebases.join(", ")} was built without ` +
                     `${requires.join(", ")}, so no change to its code can bring ${requires.join(", ")} in - its code and conformance ` +
                     "tests are taken out, kept in its history, and built again from the bottom of the chain. Only if they agree, " +
-                    `call regenerate with ${basename(status.plainFile)} and from_scratch.`,
+                    `call regenerate with ${basename(status.plainFile)} and from_scratch: "module".`,
             ];
     };
     return statuses
@@ -1459,7 +1576,7 @@ const defaultConformanceRunner = async (job, onDelta) => {
         writeTestsRecord(result.conformanceDir, job.planned.step.tree);
         recordHistory(job.buildDir, `conformance tests: ${job.planned.title}`);
     }
-    return { landed: result.passed, report: describeSpecDiffConformance(result) };
+    return { landed: result.passed, report: describeSpecDiffConformance(result), ...(result.specGaps !== undefined ? { specGaps: result.specGaps } : {}) };
 };
 /** A job as a spec diff render, landed on its unit tests: conformance is a track of its own. */
 const defaultRunner = async (job, onDelta) => {
@@ -1475,7 +1592,9 @@ const defaultRunner = async (job, onDelta) => {
         onDelta,
     });
     // Landed code can be tried.
-    return { landed: result.passed, report: withTryItLine(describeSpecDiff(result), result.passed && result.restructured !== true), story: codeStory(result) };
+    return { landed: result.passed, report: withTryItLine(describeSpecDiff(result), result.passed && result.restructured !== true), story: codeStory(result),
+        ...(result.specGaps !== undefined ? { specGaps: result.specGaps } : {}),
+    };
 };
 /** How a code pulse went, for its line in the notes: the rounds it took, its test runs, what the debugger found. */
 export function codeStory(result) {

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 = [];
@@ -281,9 +281,11 @@ export async function renderSpecDiff(options) {
     const work = createWorkLedger();
     // What it checks its own work with: the diff its reviewer is shown, and whether a test catches a bug - neither decides anything.
     const gate = createUnitGate(buildDir, scripts.unit);
+    // can_it_fail, for the coding agent and its reviewer: on unless mutation-testing says otherwise.
+    const mutationTesting = scripts.unit !== undefined && configForSpec(tip.plainFile).mutationTesting !== false;
     const selfChecks = [
         createMyDiffTool({ dir: buildDir, what: "code" }),
-        ...(scripts.runOn === "copy" ? [createCanItFailTool({ buildDir, script: scripts.unit })] : []),
+        ...(mutationTesting ? [createCanItFailTool({ buildDir, script: scripts.unit })] : []),
     ];
     // A server it built, it can start and try from outside - stopped when it is done.
     const services = createServiceTools({ dir: buildDir });
@@ -305,6 +307,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 +316,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",
@@ -498,7 +501,8 @@ export async function renderSpecDiff(options) {
                 forChange: true,
                 ...(options.cases !== undefined ? { cases: options.cases } : {}),
                 label: `${moduleName} spec change`,
-                ...(scripts.runOn === "copy" ? { unitScript: scripts.unit } : {}),
+                ...(mutationTesting ? { 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 +545,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 +583,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. */