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

package/dist/ask.js

@@ -9,6 +9,9 @@ import { PANEL_KEY } from "./regenerate/job-panel.js";
 export const OTHER_OPTION = "Something else…";
 export const CHAT_OPTION = "Chat about this";
 export const DONE_OPTION = "Done — that's all of them";
+/** An option's box in a question of several, ticked and not. */
+export const TICKED = "☑";
+export const UNTICKED = "☐";
 export const DISMISSED = "The user dismissed the question without answering.";
 /** How an answer that is no answer starts: the person chose to talk about the question first. */
 export const CHAT_PREFIX = "The user has not answered this question yet: they chose to talk about it first.";
@@ -107,32 +110,48 @@ export async function runAsk(asked, io) {
             return choice;
         }
     }
-    // Pick several: keep offering what is left until they say they are done.
-    const chosen = [];
-    let remaining = [...options];
-    while (remaining.length > 0) {
-        const title = chosen.length === 0 ? request.question : `${request.question}  [so far: ${chosen.join(", ")}]`;
-        const choice = await io.select(title, [...remaining, ...extras, DONE_OPTION], context);
-        if (choice === undefined)
-            break;
-        if (choice === DONE_OPTION)
+    // Pick several: every option a box, ticked and unticked as it is chosen, until they say they are done. What they type
+    // is one more box, ticked - and can be unticked too. Something else, Chat about this and Done are no boxes.
+    const listed = [...options];
+    const ticked = new Set();
+    const picked = () => listed.filter((option) => ticked.has(option));
+    let at = 0;
+    for (;;) {
+        const rows = listed.map((option) => `${ticked.has(option) ? TICKED : UNTICKED} ${option}`);
+        const choice = await io.select(request.question, [...rows, ...extras, DONE_OPTION], context, at);
+        if (choice === undefined || choice === DONE_OPTION)
             break;
         if (choice === OTHER_OPTION) {
+            at = listed.length;
             const typed = await typeInstead();
-            if (!typedNothing(typed))
-                chosen.push(typed.trim());
+            if (typedNothing(typed))
+                continue;
+            const option = typed.trim();
+            if (!listed.includes(option))
+                listed.push(option);
+            ticked.add(option);
+            at = listed.indexOf(option);
             continue;
         }
         if (choice === CHAT_OPTION) {
+            at = listed.length + extras.indexOf(CHAT_OPTION);
             const said = await chatAbout();
             if (typedNothing(said))
                 continue;
-            return chatAnswer(said, chosen);
+            return chatAnswer(said, picked());
         }
-        chosen.push(choice);
-        remaining = remaining.filter((option) => option !== choice);
+        // A row, or - where the answer is typed, on the command line - an option by its text, or one more of their own.
+        const row = rows.indexOf(choice);
+        const option = row !== -1 ? listed[row] : choice.trim();
+        if (!listed.includes(option))
+            listed.push(option);
+        if (ticked.has(option))
+            ticked.delete(option);
+        else
+            ticked.add(option);
+        at = listed.indexOf(option);
     }
-    return chosen.length > 0 ? chosen.join(", ") : DISMISSED;
+    return ticked.size > 0 ? picked().join(", ") : DISMISSED;
 }
 /**
  * While a question is open, what catches ctrl+h on the terminal's input: pi gives an extension's shortcut only the keys

package/dist/extension.js

@@ -16,7 +16,7 @@ import { readScript, scriptAgainstMachine, stackOnMachine, toolchainsBlock } fro
 import { sandboxAvailable, sandboxSummary } from "./regenerate/os-sandbox.js";
 import { findTestScripts } from "./regenerate/test-scripts.js";
 import { createAskUserTool } from "./tools.js";
-import { asksFromScratch, driftTool, fromWorkingDir, haltTool, loopReply, MODEL_PARAM, regenerateTool, stopJob, WAIT_PARAM, WORKING_DIR_PARAM } from "./loop-tools.js";
+import { asksFromScratch, asksWholeChain, driftTool, fromWorkingDir, haltTool, loopReply, MODEL_PARAM, regenerateTool, stopJob, WAIT_PARAM, WORKING_DIR_PARAM } from "./loop-tools.js";
 import { createWebTools } from "./regenerate/web.js";
 import { describeGates, interruptedRun, runSkill } from "./genome.js";
 import { skillStatus } from "./skill.js";
@@ -90,11 +90,12 @@ 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) => {
+            const dialog = (question, context, options, selected) => ctx.ui.custom((tui, theme, _keybindings, done) => {
                 const shown = new QuestionDialog({
                     question,
                     ...(context !== undefined ? { context } : {}),
                     ...(options !== undefined ? { options } : {}),
+                    ...(selected !== undefined ? { selected } : {}),
                     rows: () => tui.terminal.rows,
                     style: { accent: (text) => theme.fg("accent", text), muted: (text) => theme.fg("muted", text), bold: (text) => theme.bold(text) },
                     done: (answer) => {
@@ -108,7 +109,7 @@ aside) {
                 return shown;
             });
             const asking = (asked) => runAsk(asked, {
-                select: (title, options, context) => dialog(title, context, options),
+                select: (title, options, context, at) => dialog(title, context, options, at),
                 input: (title, context) => dialog(title, context),
             });
             const bare = { ...request, said: undefined };
@@ -610,7 +611,7 @@ function registerRegenerate(pi, cwd, jobs) {
     // by the planner: one functional spec at a time, a few together or the whole module in one, as it judges. What
     // follows the module is guidance for that plan, in the person's words.
     pi.registerCommand("regenerate", {
-        description: "Regenerate a module from its spec as it is now, in pulses the planner cuts - named functionalities though they did not change, or all of it from scratch: /regenerate [module | file.plain] [functionality ...] [from scratch] [how to cut the work]",
+        description: "Regenerate a module from its spec as it is now, in pulses the planner cuts - named functionalities though they did not change, or all of it from scratch, its whole chain too when asked: /regenerate [module | file.plain] [functionality ...] [from scratch [whole chain]] [how to cut the work]",
         handler: async (args, ctx) => {
             const command = `/regenerate ${args.trim()}`.trim();
             await echoCommand(pi, command);
@@ -652,13 +653,17 @@ function registerRegenerate(pi, cwd, jobs) {
             }
             // From scratch - started over, its code deleted - asked in the person's words: confirmed first, as it deletes.
             const scratch = asksFromScratch(guidance);
+            // The whole chain with it - "from scratch, the whole chain" - every module it requires built again from the bottom.
+            const chain = scratch && asksWholeChain(guidance);
             const module = basename(plainFile).replace(/\.plain$/, "");
             if (scratch && again.length > 0) {
                 say("Name functionalities or ask for it from scratch, not both: from scratch regenerates every one of them.", "warning");
                 return;
             }
             if (scratch && ctx.hasUI) {
-                const agreed = await ctx.ui.confirm(`Regenerate ${module} from scratch?`, `Its code and conformance tests are deleted - committed first, so /lineage ${module} keeps them - and the whole module is regenerated from its spec.`);
+                const agreed = await ctx.ui.confirm(chain ? `Regenerate ${module} and its whole chain from scratch?` : `Regenerate ${module} from scratch?`, chain
+                    ? `The code and conformance tests of ${module} and of every module it requires are deleted - committed first, so /lineage keeps them - and the whole chain is regenerated from its spec, from the bottom.`
+                    : `Its code and conformance tests are deleted - committed first, so /lineage ${module} keeps them - and the whole module is regenerated from its spec.`);
                 if (!agreed)
                     return;
             }
@@ -668,14 +673,14 @@ function registerRegenerate(pi, cwd, jobs) {
             // Said at once, and kept in the chat: what follows takes a while - the planner is an agent - and the person sees it
             // began, not a chat that stays empty until the first pulse starts. The plan is said under it once it is made.
             say(scratch
-                ? `Deleting ${module}'s code, then planning all of it again…`
+                ? `Deleting ${module}'s code${chain ? " and its whole chain's" : ""}, then planning all of it again…`
                 : again.length > 0
                     ? `Planning ${module}'s functionalit${again.length === 1 ? "y" : "ies"} ${again.join(", ")} again…`
                     : `Planning ${module}'s pulses…`, "info");
             await nextFrame();
             try {
                 const statuses = scratch
-                    ? await loop.fromScratch(plainFile, request)
+                    ? await loop.fromScratch(plainFile, { ...request, chain })
                     : again.length > 0
                         ? await loop.regenerateAgain(plainFile, again, request)
                         : await loop.bringUp(plainFile, request);

package/dist/loop-cli.js

@@ -85,6 +85,10 @@ async function runLoopReporting(options) {
             console.log(`${mark} ${job.id} ${pulseName(job)} - ${job.status}`);
             if (job.status !== "succeeded")
                 console.log(c.dim((job.announce ?? job.report ?? job.error ?? "").trim()));
+            // Its report is not printed when it succeeds, and nobody is asked here: the spec gaps its agents met are said.
+            else
+                for (const gap of job.details?.specGaps ?? [])
+                    console.log(c.yellow(`  spec gap: ${gap.question}`), c.dim(`Meanwhile: ${gap.assumption}`));
             report?.write();
         },
     });

package/dist/loop-tools.js

@@ -110,6 +110,10 @@ function plainFileOf(cwd, given, what) {
 export function asksFromScratch(words) {
     return FROM_SCRATCH.test(words);
 }
+/** Whether a /regenerate asking for its module from scratch asks for its whole requires chain with it. */
+export function asksWholeChain(words) {
+    return /\bchain\b|\bevery module\b|\ball (the )?modules\b/i.test(words);
+}
 const FROM_SCRATCH = /\b(from (scratch|nothing|zero|the (start|beginning|ground up))|start(ing)? (it )?(over|afresh)|afresh|anew|clean slate|(delete|wipe|remove|drop|throw away)\b.{0,30}\b(module|code|codebase|everything|all of it))/i;
 /** regenerate: regenerate a module's code up to its spec as it is now. */
 export function regenerateTool(options) {
@@ -131,6 +135,7 @@ export function regenerateTool(options) {
             "A change to a file the spec links - an API surface, a mapping document - is a change to the spec: regenerate sees it by itself, and regenerates every functional spec that uses what links it.",
             "Never stop pulses and start them again yourself to follow a spec change: regenerate does it.",
             "Set from_scratch only when the user asks for the module to be regenerated from scratch - started over, its code deleted - in this conversation, or agrees to it when a module's status says it has to start over: never to fix a pulse that did not land.",
+            'from_scratch "module" takes out the code where the module is built; the modules below keep theirs, and the module starts from a copy of the code below it. "chain" takes out every codebase of its requires chain, the base\'s too, and builds all of it again from the bottom: use it after modules were split, merged or moved (refactor-module), or when the user asks for the whole chain.',
         ],
         parameters: Type.Object({
             plain_file: Type.Optional(Type.String({ description: "Path to the .plain file. Omitted: the module the project's config.turri.yaml names" })),
@@ -139,8 +144,9 @@ export function regenerateTool(options) {
             functionalities: Type.Optional(Type.Array(Type.String(), {
                 description: "Functional specs already built, by id, to regenerate though their spec did not change. Omitted: what the spec now differs from the code in",
             })),
-            from_scratch: Type.Optional(Type.Boolean({
-                description: "Only when the user asks for it: the module's code and conformance tests deleted - committed first, so its lineage keeps them - and the whole module regenerated from its spec",
+            from_scratch: Type.Optional(Type.Union([Type.Literal("module"), Type.Literal("chain")], {
+                description: "Only when the user asks for it: the module's code and conformance tests deleted - committed first, so its lineage keeps them - and the whole module regenerated from its spec. " +
+                    '"chain": every module of its requires chain too, built again from the bottom',
             })),
             model: MODEL_PARAM,
             wait: WAIT_PARAM,
@@ -151,15 +157,15 @@ export function regenerateTool(options) {
             if (!check.ok)
                 throw new Error(`${relative(options.cwd, plainFile) || plainFile} does not parse, so nothing can be regenerated from it yet: ${check.error}`);
             const again = given.functionalities ?? [];
-            if (again.length > 0 && given.from_scratch === true)
+            if (again.length > 0 && given.from_scratch !== undefined)
                 throw new Error("Name functionalities or set from_scratch, not both: from scratch regenerates every one of them.");
             // Named functionalities are work on functionalities, as engine chooses a model for it; the rest, spec changes.
             const work = again.length > 0 ? "functionalities" : "spec_changes";
             const model = options.model !== undefined ? options.model(ctx, plainFile, given.model, work) : given.model;
             const loop = options.loop(ctx);
             const request = { ...(model !== undefined ? { model } : {}), ...(given.guidance !== undefined ? { guidance: given.guidance } : {}) };
-            const statuses = given.from_scratch === true
-                ? await loop.fromScratch(plainFile, request)
+            const statuses = given.from_scratch !== undefined
+                ? await loop.fromScratch(plainFile, { ...request, chain: given.from_scratch === "chain" })
                 : again.length > 0
                     ? await loop.regenerateAgain(plainFile, again, request)
                     : await loop.bringUp(plainFile, request);

package/dist/question-dialog.js

@@ -25,6 +25,7 @@ export class QuestionDialog {
         }
         else {
             this.input = undefined;
+            this.selected = Math.min(Math.max(0, options.selected ?? 0), options.options.length - 1);
         }
     }
     get focused() {

package/dist/regenerate/loop.js

@@ -597,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 } : {}),
+                    },
                 };
             },
         });
@@ -1240,17 +1247,21 @@ 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) {
@@ -1511,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
@@ -1565,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) => {
@@ -1581,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/spec-map-view.js

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

package/dist/regenerate-cli.js

@@ -19,6 +19,8 @@ its conformance tests too when they are on.
   --start-over             start over, without asking, a codebase regenerated without a module it now requires -
                            with no terminal to ask and without it, the run stops there
   --from-scratch           delete the module's code and conformance tests (its lineage keeps them) and regenerate all of it
+  --from-scratch-chain     the same for every module of its requires chain, built again from the bottom - after
+                           modules were split or moved
   --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner and the conformance chooser
   --coding-model <p/id>    its coding-model, --model too: the agents that build; p/id:level for how hard a model thinks
   --judge-model <p/id>     its judge-model: the judge and the test review
@@ -31,7 +33,7 @@ its conformance tests too when they are on.
                            as it starts, as each pulse ends and as it exits (docs/headless.md)
 
   PLAIN_TEMPLATE_DIRS      colon-separated template directories`;
-const { positional, options } = parseArgs(process.argv.slice(2), ["--dry-run", "--start-over", "--from-scratch"], USAGE, ["--build-dir", "--report", "--conformance-tests", "--harness-model", "--judge-model", "--review"]);
+const { positional, options } = parseArgs(process.argv.slice(2), ["--dry-run", "--start-over", "--from-scratch", "--from-scratch-chain"], USAGE, ["--build-dir", "--report", "--conformance-tests", "--harness-model", "--judge-model", "--review"]);
 const { report, buildDir } = headlessOptions(options, true);
 const named = positional[0] ?? readProjectConfig(process.cwd()).module;
 // Functional specs named after the file: regenerated again though their spec did not change.
@@ -40,9 +42,10 @@ if (!named) {
     console.error(`${USAGE}\n\nNo file given, and ${CONFIG_FILE} names no module.`);
     process.exit(1);
 }
+const scratch = options["from-scratch-chain"] !== undefined ? "chain" : options["from-scratch"] !== undefined ? "module" : undefined;
 // A dry run starts nothing, and from scratch deletes before it plans: the two do not go together.
-if (options["from-scratch"] !== undefined && options["dry-run"] !== undefined) {
-    console.error("--from-scratch deletes the module's code before anything is planned: it cannot be a dry run.");
+if (scratch !== undefined && options["dry-run"] !== undefined) {
+    console.error(`--from-scratch${scratch === "chain" ? "-chain" : ""} deletes the code before anything is planned: it cannot be a dry run.`);
     process.exit(1);
 }
 runLoop({
@@ -54,8 +57,8 @@ runLoop({
     startOver: options["start-over"] !== undefined,
     ask: (loop) => again.length > 0
         ? loop.regenerateAgain(named, again)
-        : options["from-scratch"] !== undefined
-            ? loop.fromScratch(named)
+        : scratch !== undefined
+            ? loop.fromScratch(named, { chain: scratch === "chain" })
             : loop.bringUp(named),
 }).catch((error) => {
     console.error(error instanceof Error ? error.message : error);

package/dist/run-report.js

@@ -181,6 +181,18 @@ export function startRunReport(options) {
             list,
         };
     };
+    /** The spec gaps the pulses' agents met, in the order the pulses started: questions a person would want to decide. */
+    const specGapsOf = (jobs) => jobs.flatMap((job) => {
+        const details = job.details;
+        return (details?.specGaps ?? []).map((gap) => ({
+            module: job.module ?? null,
+            pulse: job.pulse ?? null,
+            pulse_id: job.id,
+            landed: job.status === "succeeded" && details?.landed === true,
+            question: gap.question,
+            assumption: gap.assumption,
+        }));
+    });
     const functionalitiesOf = (counts) => {
         if (counts === undefined)
             return null;
@@ -245,6 +257,7 @@ export function startRunReport(options) {
             usage: usageOf(jobs),
             pulses: pulsesOf(jobs, now),
             functionalities: functionalitiesOf(attempt(sources.completion)),
+            spec_gaps: specGapsOf(jobs),
             ...(exitParts ?? {}),
             logs: {
                 jobs_dir: fromProject(join(projectRoot, ".turri", "jobs")),

package/docs/headless.md

@@ -87,6 +87,8 @@ Useful options - `turri regenerate --help` lists all of them:
 | `--conformance-tests <all\|chosen\|module\|false>` | `conformance-tests`, with its values (`true` is `all`) |
 | `--review <true\|false>` | `review`: whether the code and its tests are reviewed once they pass |
 | `--stack <name>` | build with the stack's `config.turri.<name>.yaml` over `config.turri.yaml`; default, `TURRI_STACK`, else none |
+| `--from-scratch` | delete the module's code and conformance tests (its lineage keeps them) and regenerate all of it |
+| `--from-scratch-chain` | the same for every module of its requires chain, the base's included, built again from the bottom |
 | `--start-over` | start over, unasked, a codebase built without a module it now requires - without a terminal, a run that needs it and lacks it stops |
 | `--build-dir <dir>` | as the run ends, export the code there - see below |
 | `--report <file.json>` | write [the run report](#the-run-report) there |
@@ -104,7 +106,8 @@ Conformance tests follow `conformance-tests:` in `config.turri.yaml`, or `--conf
 The command exits `0` only when every module is complete: its code regenerated from the spec as it is
 now, and its conformance tests written for what is built when they are on - no pulse failed, nothing
 halted, nothing waiting for a start over. Anything else exits `1`, and the last lines say which
-module is not complete, and why. The log says, per functionality, what was built and whether its
+module is not complete, and why. A behaviour the spec leaves open that an agent had to decide is printed
+as a `spec gap` under its pulse, with what was decided meanwhile. The log says, per functionality, what was built and whether its
 tests passed.
 
 | | |
@@ -191,6 +194,11 @@ changes meaning or goes; new fields may appear in the same version. Paths in `pu
     ],
     "codebases": ["plain_modules/app/code"]
   },
+  "spec_gaps": [{                                       // [] when no agent met one
+    "module": "app", "pulse": 3, "pulse_id": "2a058729", "landed": true,
+    "question": "What happens to a contact archived in HubSpot after it was synced?",
+    "assumption": "An archived contact is left as synced - asserted in sync.test.ts, archived contacts"
+  }],
   "build_dir_export": { "exported": true, "dir": "/work/out", "module": "app", "commit": "8036b3b", "files": 23 },
   "logs": { "jobs_dir": ".turri/jobs", "debug_dir": ".turri/debug", "sessions_dir": ".turri/sessions" }
 }
@@ -209,6 +217,13 @@ calls; a role or model turri could not tell is `unknown`.
 stopped, or did not pass - and everything it wrote was undone. A pulse that failed is tried once more
 before it counts as failed; both tries are the one pulse.
 
+**Spec gaps.** A behaviour the spec leaves open that an agent met and decided on its own - reported with
+`report_spec_gap` (see [regenerating](regenerating.md)). In the chat they are put to you as the pulse ends; a
+headless run has no one to ask, so they are listed here, in the order the pulses started, and printed under the
+pulse that met them. `assumption` is what the agent decided meanwhile, also in the codebase's notes'
+assumptions while its pulse is `landed`; a pulse rolled back takes it out of the notes, but the question still
+stands. Settle the ones you care about in the spec and run again.
+
 **Completed functional specs** - the pass rate, the figure to compare runs by.
 A functional spec is completed when the code record of the codebase the run delivers - the
 furthest-built of the chain, the one `--build-dir` exports - as last committed, holds it as the spec has
@@ -227,7 +242,7 @@ and modules that are complete are skipped, so it picks up where it stopped - aft
 provider outage, or a machine that went to sleep anyway. Whatever the stopped run left
 half-written is undone first: each step starts from the module's last commit. A functionality whose spec has changed
 since counts as not built, so editing the spec and re-running rebuilds what changed. `--from-scratch`
-rebuilds everything.
+rebuilds the module; `--from-scratch-chain` rebuilds every module of its chain.
 
 ## Rebuilding one functionality
 

package/docs/regenerating.md

@@ -718,7 +718,7 @@ with no agent and no testing script. Moving specs into a module the code was not
 change to the code brings that module's code in, so the codebase stops: it has to be started over - its code
 and conformance tests taken out, committed so its history keeps them, and the chain built again from the
 bottom. That is never done unasked. In the chat the model asks the person, saying why, and calls
-`regenerate` with `from_scratch` once they agree; `turri regenerate` and `spec-diff` ask at the terminal, and
+`regenerate` with `from_scratch: "module"` once they agree; `turri regenerate` and `spec-diff` ask at the terminal, and
 `--start-over` agrees in advance - with no terminal and no flag, the run stops there, exit 1, saying so.
 
 ## Conformance tests
@@ -1111,7 +1111,9 @@ are the next agent's, and a gap is yours. An agent reports one with `report_spec
 and the assumption it made meanwhile; turri writes that assumption into the notes' assumptions, so the code built on
 it is known for what it is. The gaps a pulse's agents report are said in its report - "Spec gaps its agents met ... Put
 each to the user", each with its assumption - so the conversation asks you, and writes the ones you decide into the
-spec; the pulse that builds the answer finds the assumption it replaces in the notes, and the tests it names. However many gaps a pulse's agents report, they
+spec; the pulse that builds the answer finds the assumption it replaces in the notes, and the tests it names.
+A headless run has no one to ask: it prints each gap under its pulse, and lists them in its run report's
+`spec_gaps` ([running unattended](headless.md#the-run-report)). However many gaps a pulse's agents report, they
 are put to you - never a reason to stop the pulse; the tool is guarded like any other. A notes
 file from before keeps no spec gaps section: its lines are dropped as it is read.
 

package/docs/skills-and-gates.md

@@ -133,7 +133,9 @@ change the step makes and puts its findings on the executor's next tool result.
 - **Interview the user.** `ask_user` puts one question to the person. In the TUI it is a dialog;
   from the CLI the options are numbered. Offering choices is required, not optional - a call with
   neither `options` nor `free_form: true` is refused - and every list carries "Something else…".
-  `multi_select: true` keeps offering what is left until they are done. The skill's agent talks in a
+  `multi_select: true` gives every option a box, ticked and unticked as it is chosen - a pick made by mistake is
+  undone by choosing it again - until they choose Done; what they type is one more box, ticked. "Something
+  else…", "Chat about this" and Done are no boxes. The skill's agent talks in a
   session of its own that the person never sees, so what the person must read to answer - the brief
   to confirm, the plan to approve - it passes as `ask_user`'s `context`, shown above the question in
   the dialog; `brood`, `spawn` and `bud` pass their briefs so. The agents are told to keep it to what can be taken in at

package/docs/using.md

@@ -50,7 +50,7 @@ where it stopped. A project can have skills of its own, in `.turri/skills/` or `
 
 | tool | |
 | --- | --- |
-| `regenerate` | regenerate a module and its chain from the spec as it is now - after any change to it, by any means: what is left to regenerate is planned into pulses of one to three functional specs, each with the definitions and reqs it uses, and a pulse regenerating what the spec no longer wants is stopped. With functionalities named, those are regenerated though their spec did not change - rewritten or started over, planned into pulses as any change is; with `from_scratch`, the whole module, its code deleted first - only when you ask, or agree |
+| `regenerate` | regenerate a module and its chain from the spec as it is now - after any change to it, by any means: what is left to regenerate is planned into pulses of one to three functional specs, each with the definitions and reqs it uses, and a pulse regenerating what the spec no longer wants is stopped. With functionalities named, those are regenerated though their spec did not change - rewritten or started over, planned into pulses as any change is; with `from_scratch`, the whole module, its code deleted first - `"chain"` for every module of its requires chain too, built again from the bottom - only when you ask, or agree |
 | `drift` | what is left to regenerate: how far the code and its conformance tests have drifted from the spec, starting nothing |
 | `glimpse` | the pulse a module's codebases would start next, and the whole prompt its coding agent would get - starting nothing |
 | `steer` | say how the work is planned - which functional specs go together, what first - for the project or one module, for the session; the next plan follows it, beside what AGENTS.md says under a heading naming the queue |
@@ -63,7 +63,7 @@ where it stopped. A project can have skills of its own, in `.turri/skills/` or `
 | `lineage` | a module's lineage: what each regeneration and conformance run changed in it, and what it was regenerated from |
 | `cultivate` | run a gated skill, its steps and review gates enforced |
 | `release`, `activate` | try what is regenerated: release it to `dist/<module>` and activate it on this machine, installing what it needs - see [deploy](deploy.md) |
-| `ask_user` | put a question to you as a dialog to pick from - several at once, "Something else…" to type, or "Chat about this" to talk it over first; Esc in either goes back to the options |
+| `ask_user` | put a question to you as a dialog to pick from - several at once, each a box you tick and untick, "Something else…" to type, or "Chat about this" to talk it over first; Esc in either goes back to the options |
 | `web_search`, `web_fetch` | search the web and read a page as text - documentation, an API, an error; `curl` and the like run in its `bash` |
 
 What each render does, in order, is in [regenerating the code](regenerating.md).
@@ -174,8 +174,7 @@ come waits for a free slot, and says so.
   regenerates. Pulses are numbered as they start in a module, from 1 each session.
 
   A changed item shows what changed in it: its first line word by word - what is gone struck through in red,
-  what is new in green, what is kept highlighted as it reads now - and, under it, only the sub-bullets that changed. A new
-  item - not in the code yet - is green, all of it, so a new functional spec stands apart from one changed. A spec never built that is taken
+  what is new in green, what is kept highlighted as it reads now - and, under it, only the sub-bullets that changed. A spec never built that is taken
   out is simply gone. The top line has a strip of the module's functional specs - built, regenerating, planned,
   waiting - and how many are built, then what is happening: `pulse 3 of 8 regenerating`, or why nothing is -
   `not asked to build - regenerate plans it` (turri was just opened, or nothing has asked for the module: the
@@ -239,7 +238,7 @@ come waits for a free slot, and says so.
   is laid over `config.turri.yaml` - its testing scripts, toolchains, models - for the session; a pulse already
   running keeps the stack it started with. The chat model switches it too when you ask. See
   [stacks](config.md#stacks).
-- **`/regenerate [module | file.plain] [functionality ...] [from scratch] [how to cut the work]`** regenerates a module from its spec as it is now, as
+- **`/regenerate [module | file.plain] [functionality ...] [from scratch [whole chain]] [how to cut the work]`** regenerates a module from its spec as it is now, as
   the `regenerate` tool does: what is left to regenerate is planned into pulses - one functional spec at a time, a few
   together or the whole module in one, as the planner judges - and the first starts. Words after the module are
   guidance for that plan (`/regenerate app models first`). A module's name typed with spaces for its underscores is
@@ -247,8 +246,13 @@ come waits for a free slot, and says so.
   `config.turri.yaml` names, else the folder's top modules, to pick from. Asked for from scratch - `from scratch`,
   `start over`, `delete the module` - it asks first, then deletes the module's code and conformance tests in every
   codebase where they live, committed so `/lineage` keeps them, and regenerates the whole module from its spec,
-  built though nothing in it changed: `/regenerate shorty from scratch`. The chat's `regenerate` does the same with
-  `from_scratch`, when you ask for it; `turri regenerate --from-scratch` on the command line, not with `--dry-run`.
+  built though nothing in it changed: `/regenerate shorty from scratch`. The modules below it keep their code, and
+  the module starts again from a copy of the code below it. Asked for its chain too - `/regenerate shorty from scratch,
+  the whole chain` - the code of every module of its requires chain is deleted, the base's included, and the whole
+  chain is regenerated from the bottom: what to do after modules were split, merged or moved, when the code below was
+  laid out for modules that are no more. The chat's `regenerate` does the same with `from_scratch: "module"` or
+  `"chain"`, when you ask for it; `turri regenerate --from-scratch` or `--from-scratch-chain` on the command line, not
+  with `--dry-run`.
   Functionalities named after the module - `/regenerate shorty 3 5` - are regenerated though their spec did not
   change, on the model chosen for functionalities: as `turri regenerate shorty.plain 3 5` does, and the chat's
   `regenerate` with `functionalities`.
@@ -454,6 +458,7 @@ turri regenerate <file.plain>              # regenerate what the code is not bui
 turri glimpse <file.plain>             # plan it, and print the first job's prompt - starts nothing
 turri regenerate <file.plain> 2            # regenerate functionality 2 again, changed or not
 turri regenerate <file.plain> --from-scratch   # delete the module's code and tests (its lineage keeps them), regenerate all of it
+turri regenerate <file.plain> --from-scratch-chain   # the same for every module of its requires chain, from the bottom
 turri spec-diff <file.plain> <diff>    # apply a spec diff, and regenerate it
 turri conform <file.plain> 1           # black-box tests for functionality 1
 turri lineage <module>                 # what each regeneration changed in a module, and when

package/genome/skills/refactor-module/SKILL.md

@@ -21,6 +21,8 @@ allowed-tools: [read, write, edit, bash, ls, grep, find]
 
 The refactoring is purely structural. The **combined behavior** of the resulting modules must be **identical** to the original module. No functional spec is added, removed, or weakened. The split is semantic — grouping related specs together — not behavioral.
 
+The spec is structural; the code is not. Once modules are split and specs move between them, the code already built no longer matches the module layout: specs move into modules the code was never built on, and no change to that code brings them in. **After a refactor, the whole requires chain is regenerated from scratch** — the existing code and conformance tests are taken out (their lineage keeps them) and every module is built again from the base of the chain upward. Say so up front: it is part of what the user agrees to (Phase 2e), and it is the last step of the skill (Phase 5).
+
 ## Input
 
 The `.plain` file to refactor, plus guidance from the user on the desired grouping (or ask the user to confirm your proposed grouping).
@@ -90,8 +92,9 @@ Summarize for the user:
 - Any new import module being created
 - Which concepts are exported from each module
 - Confirmation that all original specs are accounted for (none lost)
+- That the whole chain will be **regenerated from scratch** once the split is done: the code and conformance tests built so far are taken out (kept in the lineage) and everything is built again from the base module up — this takes as long and costs as much as building the original module did
 
-Get explicit user confirmation before proceeding.
+Get explicit user confirmation before proceeding — of the split and of regenerating from scratch.
 
 ## Phase 3 — Execute the Split
 
@@ -162,6 +165,19 @@ For each new module:
 
 Read each new `.plain` file in full and present the final structure to the user for approval. If the user requests changes, apply them and re-verify.
 
+Validate each new module with `turri validate <module>.plain` (or the `validate` tool) before going on: a module that does not parse cannot be regenerated.
+
+## Phase 5 — Regenerate the Chain from Scratch
+
+The split moves specs between modules, so the code built from the original module cannot be patched into the new layout: the chain is regenerated from scratch. Do not try to keep or reuse the existing code, and do not regenerate only what looks changed — modules have moved, and a codebase built without a module it now requires has to be started over anyway.
+
+1. **Remind the user** what regenerating from scratch does — the code and conformance tests built so far are taken out, committed so the lineage keeps them, and the whole chain is built again from the base up — and that they already agreed to it in Phase 2e. Proceed only on that agreement.
+2. **Regenerate the tip of the chain from scratch, with its whole chain** — the last module, the one everything else is required by. From scratch for the tip alone is not enough: the modules below keep their code, and the tip starts from a copy of it, laid out for the old modules. With the whole chain, every module's code is taken out, the base's included, and the chain is built again from the bottom:
+   - in the chat: the `regenerate` tool on the tip's `.plain` file with `from_scratch: "chain"`, or `/regenerate <tip> from scratch, the whole chain`;
+   - on the command line: `turri regenerate <tip>.plain --from-scratch-chain`.
+3. **Modules that require the chain** (updated in 3d) are regenerated after it, from scratch too (`from_scratch: "module"`): the modules they require are not the ones their code was built on. When the tip's whole chain is regenerated, a module built on top of it is a chain of its own — regenerating it from scratch with its whole chain instead covers the tip's chain too, in one go.
+4. **The original module's codebase** (`plain_modules/<original-module>/`), when the original module was deleted or renamed, is no longer built from anything. Tell the user it is there; it is theirs to delete. Do not delete it unasked.
+
 ## Common Pitfalls
 
 ### Splitting too aggressively
@@ -179,9 +195,12 @@ This is a refactoring, not a rewrite. Spec text must be copied verbatim. If a sp
 ### Losing acceptance tests
 Acceptance tests are nested under their parent functional spec. When moving a spec to a new module, its acceptance tests must move with it.
 
+### Regenerating only what changed
+After a split the existing code was built for a module layout that no longer exists. Regenerating incrementally either stops at a codebase that has to be started over or builds on code laid out for the old modules. Regenerate the whole chain from scratch.
+
 ## Validation Checklist
 
-- [ ] User confirmed the split plan before execution
+- [ ] User confirmed the split plan before execution, including regenerating the whole chain from scratch
 - [ ] All original functional specs are present in exactly one new module — none lost
 - [ ] Spec text is identical to the original — no rewording
 - [ ] Acceptance tests moved with their parent specs
@@ -194,3 +213,6 @@ Acceptance tests are nested under their parent functional spec. When moving a sp
 - [ ] Original module removed or updated
 - [ ] Downstream modules (if any) updated to require the chain tip, plus any earlier chain modules whose exported concepts they reference
 - [ ] User approved the final result
+- [ ] Every new module validates
+- [ ] The tip of the chain regenerated from scratch with its whole chain, then any module that requires it
+- [ ] User told about the original module's leftover codebase, if there is one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.4-next.246fd84",
+  "version": "0.1.4-next.eb3e006",
   "license": "MIT",
   "type": "module",
   "repository": {