@turri-dev/cli 0.1.3-next.f74e98a → 0.1.4-next.18d69fb

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");

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.