@turri-dev/cli 0.1.3-next.f74e98a → 0.1.3

package/dist/extension.js

@@ -90,15 +90,23 @@ aside) {
             // The question, with what the asker gives to read for it - a brief to confirm - above it; what it said of its work
             // before asking is kept in its record, never put in the dialog.
             // A dialog of turri's own: a long brief scrolls above the question, and the options always show (question-dialog.ts).
-            const dialog = (question, context, options) => ctx.ui.custom((tui, theme, _keybindings, done) => new QuestionDialog({
-                question,
-                ...(context !== undefined ? { context } : {}),
-                ...(options !== undefined ? { options } : {}),
-                rows: () => tui.terminal.rows,
-                style: { accent: (text) => theme.fg("accent", text), muted: (text) => theme.fg("muted", text), bold: (text) => theme.bold(text) },
-                done,
-                requestRender: () => tui.requestRender(),
-            }));
+            const dialog = (question, context, options) => ctx.ui.custom((tui, theme, _keybindings, done) => {
+                const shown = new QuestionDialog({
+                    question,
+                    ...(context !== undefined ? { context } : {}),
+                    ...(options !== undefined ? { options } : {}),
+                    rows: () => tui.terminal.rows,
+                    style: { accent: (text) => theme.fg("accent", text), muted: (text) => theme.fg("muted", text), bold: (text) => theme.bold(text) },
+                    done: (answer) => {
+                        if (questionShown === shown)
+                            questionShown = undefined;
+                        done(answer);
+                    },
+                    requestRender: () => tui.requestRender(),
+                });
+                questionShown = shown;
+                return shown;
+            });
             const asking = (asked) => runAsk(asked, {
                 select: (title, options, context) => dialog(title, context, options),
                 input: (title, context) => dialog(title, context),
@@ -117,6 +125,12 @@ aside) {
 }
 /** The side panel, as a question open in the chat reaches it: set once the extension has its panel. */
 let questionPeek;
+/**
+ * The question open in the chat now, if any. The side panel gives the keys back to it: pi would give them to what had the
+ * focus when the panel first opened, and a panel kept beside the chat outlives that question - the keys would go to a
+ * dialog already answered, and nothing would take them.
+ */
+let questionShown;
 /** A widget with nothing to draw: below the editor, it takes no line. */
 const PEEK_KEY_WIDGET = "turri-peek-key";
 /**
@@ -1508,6 +1522,7 @@ function registerJobTools(pi, jobs, cwd) {
         }
         needsLooking.delete(jobs);
         if (panel !== undefined) {
+            panel.keepChatFocus();
             panel.handle?.setHidden(false);
             panel.keys = true;
             panel.handle?.focus();
@@ -1515,7 +1530,21 @@ function registerJobTools(pi, jobs, cwd) {
         }
         // Not awaited: the panel lives on while the jobs it shows run.
         void ctx.ui.custom((tui, theme, _keybindings, done) => {
-            const close = () => done(undefined);
+            // What the chat shows when the panel takes the keys - its editor, or a pi dialog - for when it gives them back.
+            const focusedNow = () => tui.getFocusedComponent?.() ?? null;
+            let chatFocus = focusedNow();
+            const keepChatFocus = () => {
+                const focused = focusedNow();
+                if (focused !== null && focused !== component && !(focused instanceof QuestionDialog))
+                    chatFocus = focused;
+            };
+            // The keys back to the chat: to the question open there now, else to what it showed - never to a question answered
+            // while the panel was open.
+            const giveBack = () => entry.handle?.unfocus({ target: questionShown ?? chatFocus });
+            const close = () => {
+                giveBack();
+                done(undefined);
+            };
             panelTerminal = tui.terminal;
             let component;
             // Beside the chat: the chat drawn narrower, on the left, and a click on either side giving it the keys - undone
@@ -1548,10 +1577,11 @@ function registerJobTools(pi, jobs, cwd) {
             // Beside the chat, back to it: the chat has the keys, the panel stays.
             const toChat = () => {
                 entry.keys = false;
-                entry.handle?.unfocus();
+                giveBack();
                 tui.requestRender();
             };
             const toPanel = () => {
+                keepChatFocus();
                 entry.keys = true;
                 entry.handle?.focus();
                 tui.requestRender();
@@ -1604,7 +1634,7 @@ function registerJobTools(pi, jobs, cwd) {
                     return focused !== null && focused !== component;
                 },
             });
-            const entry = { view, close, keys: true };
+            const entry = { view, close, keepChatFocus, keys: true };
             panel = entry;
             layOut();
             // Every key goes to the panel while it shows, whatever has the focus: a question the chat model asks in the

package/dist/pi-launch.js

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

package/dist/question-dialog.js

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

package/dist/questioning.js

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

package/dist/regenerate/activity.js

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

package/dist/regenerate/conform.js

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

package/dist/regenerate/conformance-agents.js

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

package/dist/regenerate/conformance.js

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

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;
@@ -989,9 +1006,10 @@ export function createWorkLoop(options) {
     };
     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))));
+            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.
             for (const state of states)
                 state.halted = undefined;

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