@turri-dev/cli 0.1.27 → 0.2.0

package/dist/regenerate/chunk-plan.js

@@ -1,7 +1,7 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { DEFAULT_CONCEPTS, extractConceptsFromDefinition, extractConceptsFromSpecText } from "../plain/concepts.js";
-import { ACCEPTANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS, TEST_REQUIREMENTS } from "../plain/spec.js";
+import { ACCEPTANCE_TESTS, CONFORMANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS, TEST_REQUIREMENTS } from "../plain/spec.js";
 import { ask, BEGIN, createExecutor } from "../pi.js";
 import { reportActivity, reportStage } from "./activity.js";
 import { firstLine, record } from "./ledger.js";
@@ -65,7 +65,8 @@ export function stepsOf(input, draft) {
         const changes = job.changes.map((id) => byId.get(id));
         sofar.push(...changes);
         const after = applyChanges(serializeTree(input.base), sofar);
-        const step = makeStep(job.title, job.reason, changes, before, after, input.specFile, layout);
+        const testPlain = input.track === "conformance" && input.testPlainPath !== undefined && input.moduleName !== undefined ? { module: input.moduleName, pathOf: input.testPlainPath } : undefined;
+        const step = makeStep(job.title, job.reason, changes, before, after, input.specFile, layout, testPlain);
         before = after;
         return { ...job, step };
     });
@@ -95,12 +96,16 @@ export function shortTitle(text, chars = TITLE_CHARS, words = TITLE_WORDS) {
 export const MAX_LINES_PER_JOB = 120;
 /** How often an answer that does not hold goes back to its agent before the plan falls back. */
 const RETRIES = 2;
-/** An item's text, from its serialized line: its markdown, and its acceptance tests. */
+/**
+ * An item's text, from its serialized line: its markdown - a functional spec's body, its func-id given beside it - and
+ * its scenarios, each under its scenario-id, where the tree has them: the conformance track's.
+ */
 function textOf(change) {
     const line = change.after ?? change.before ?? "";
     try {
         const item = JSON.parse(line);
-        return [item.markdown ?? "", ...(item[ACCEPTANCE_TESTS] ?? []).map((test) => test.markdown ?? "")].filter(Boolean).join("\n");
+        const scenarios = [...(item[CONFORMANCE_TESTS] ?? []), ...(item[ACCEPTANCE_TESTS] ?? [])].map((scenario) => `# ${scenario.id ?? ""}\n${scenario.text ?? ""}`);
+        return [item.markdown ?? "", ...scenarios].filter(Boolean).join("\n");
     }
     catch {
         return line;
@@ -118,27 +123,60 @@ function namedIn(text) {
 function definedBy(text) {
     return extractConceptsFromDefinition(text)[0];
 }
-/** What is wrong with a grouping: every new functional spec once, in order, next to each other, none too big. */
-export function groupProblems(specs, answer, maxSpecs = MAX_SPECS_PER_JOB) {
+/**
+ * What is wrong with a grouping: every new functional spec once, in order, next to each other, none too big - and
+ * every change to what is built placed once, with a group or first. A functional spec changed counts in its group: it
+ * is built as the new ones are. One taken out builds nothing, and does not.
+ */
+export function groupProblems(specs, answer, maxSpecs = MAX_SPECS_PER_JOB, built = []) {
+    const problems = newSpecProblems(specs, answer, maxSpecs, built);
+    const placed = new Map();
+    for (const entry of answer.built ?? []) {
+        if (!built.some((change) => change.number === entry.change))
+            problems.push(`There is no change ${entry.change} to what is built.`);
+        placed.set(entry.change, (placed.get(entry.change) ?? 0) + 1);
+        const valid = entry.to === "first" || (Number.isInteger(entry.to) && entry.to >= 1 && entry.to <= answer.groups.length);
+        if (!valid)
+            problems.push(`Change ${entry.change} to what is built goes to ${entry.to}, which is no group: a group's number, or "first".`);
+    }
+    for (const change of built) {
+        const times = placed.get(change.number) ?? 0;
+        if (times === 0)
+            problems.push(`change ${change.number} to what is built is not placed: every one goes with a group, or "first".`);
+        if (times > 1)
+            problems.push(`Change ${change.number} to what is built is placed ${times} times: once.`);
+    }
+    return problems;
+}
+/** How many functional specs a group builds: its new ones, and those changed that go with it. */
+function builtIn(group, answer, built) {
+    const changed = new Set(built.filter((change) => change.kind !== "taken out" && change.what === "functional spec").map((change) => change.number));
+    return (answer.built ?? []).filter((entry) => entry.to === group && changed.has(entry.change)).length;
+}
+function newSpecProblems(specs, answer, maxSpecs, built) {
     const problems = [];
     const numbers = specs.map((spec) => spec.number);
     const given = answer.groups.flatMap((group) => group.specs);
     if (given.join(",") !== numbers.join(","))
         problems.push(`The groups must hold every new functional spec once, in the order the spec has them: ${numbers.join(", ")}. They hold ${given.join(", ") || "none"}.`);
-    // Next to each other: in the same module, one numbered after the other there.
+    // Next to each other: in the same module, one in the place after the other there.
     const byNumber = new Map(specs.map((spec) => [spec.number, spec]));
     const nextTo = (a, b) => {
         const first = byNumber.get(a);
         const second = byNumber.get(b);
         if (first === undefined || second === undefined)
             return b === a + 1;
-        return first.module === second.module && Number(second.id ?? second.number) === Number(first.id ?? first.number) + 1;
+        return first.module === second.module && (second.place ?? second.number) === (first.place ?? first.number) + 1;
     };
-    for (const group of answer.groups) {
+    answer.groups.forEach((group, index) => {
         if (group.specs.length === 0)
             problems.push(`"${group.title}" has no functional spec.`);
-        if (group.specs.length > maxSpecs)
-            problems.push(`"${group.title}" has ${group.specs.length} functional specs - at most ${maxSpecs}.`);
+        const changed = builtIn(index + 1, answer, built);
+        if (group.specs.length + changed > maxSpecs) {
+            problems.push(changed === 0
+                ? `"${group.title}" has ${group.specs.length} functional specs - at most ${maxSpecs}.`
+                : `"${group.title}" has ${group.specs.length + changed} functional specs to build - ${group.specs.length} new, ${changed} changed - at most ${maxSpecs}.`);
+        }
         for (let i = 1; i < group.specs.length; i += 1) {
             if (!nextTo(group.specs[i - 1], group.specs[i]))
                 problems.push(`"${group.title}" groups ${group.specs.join(", ")}: only functional specs next to each other in the same module go together.`);
@@ -147,7 +185,7 @@ export function groupProblems(specs, answer, maxSpecs = MAX_SPECS_PER_JOB) {
             problems.push("Every group needs a title.");
         else if (!fitsTitle(group.title))
             problems.push(`"${group.title}" is too long for a title: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.`);
-    }
+    });
     return problems;
 }
 /** What is wrong with a titling: every group titled once, by its number, none empty, none too long. */
@@ -236,7 +274,7 @@ function placeDefinitions(chunks, definitions) {
     const placed = new Set();
     for (const chunk of chunks) {
         chunk.definitions = [];
-        const queue = [...chunk.specs, ...chunk.reqs, ...(chunk.built ?? [])].flatMap((change) => namedIn(textOf(change)));
+        const queue = [...chunk.specs, ...chunk.reqs, ...(chunk.built ?? []), ...(chunk.joined ?? [])].flatMap((change) => namedIn(textOf(change)));
         for (let concept = queue.shift(); concept !== undefined; concept = queue.shift()) {
             const definition = byConcept.get(concept);
             if (definition === undefined || placed.has(definition))
@@ -258,7 +296,7 @@ function movableSize(chunk) {
     return [...chunk.specs, ...chunk.definitions].reduce((total, change) => total + linesOf(change), 0);
 }
 function sizeOf(chunk) {
-    return [...chunk.specs, ...chunk.definitions, ...chunk.reqs, ...(chunk.built ?? [])].reduce((total, change) => total + linesOf(change), 0);
+    return [...chunk.specs, ...chunk.definitions, ...chunk.reqs, ...(chunk.built ?? []), ...(chunk.joined ?? [])].reduce((total, change) => total + linesOf(change), 0);
 }
 /**
  * The draft a chunking is: a job per chunk, its changes in the order the net has them. A job runs as the queued job
@@ -268,7 +306,7 @@ function sizeOf(chunk) {
 function draftOf(chunks, net) {
     return chunks
         .map((chunk) => {
-        const ids = new Set([...chunk.specs, ...chunk.definitions, ...chunk.reqs, ...(chunk.built ?? [])].map((change) => change.id));
+        const ids = new Set([...chunk.specs, ...chunk.definitions, ...chunk.reqs, ...(chunk.built ?? []), ...(chunk.joined ?? [])].map((change) => change.id));
         return { chunk, changes: net.filter((change) => ids.has(change.id)).map((change) => change.id) };
     })
         .filter((entry) => entry.changes.length > 0)
@@ -311,7 +349,7 @@ export async function planChunks(input, agents, notes) {
  */
 function anchored(draft, net) {
     const sectionOf = new Map(net.map((change) => [change.id, change.section]));
-    const testsASpec = (job) => job.changes.some((id) => sectionOf.get(id) === FUNCTIONAL_REQUIREMENTS);
+    const testsASpec = (job) => job.changes.some((id) => sectionOf.get(id) === FUNCTIONAL_REQUIREMENTS || sectionOf.get(id) === REQUIRED_FUNCTIONAL_SPECS);
     if (!draft.some(testsASpec))
         return draft;
     const jobs = [];
@@ -329,22 +367,17 @@ function anchored(draft, net) {
     return jobs;
 }
 /**
- * How the conformance tests are cut, with no agent: every functional spec tested in one job - those of one module
- * together - a new job begun where the next functional spec was asked for in another group (`groups`: conform called for
- * 1-3, then for 4-6), or would take the job's functional specs and the definitions they bring past `maxLines`; or,
- * `separately`, a job a functional spec, as the person asked.
+ * How the conformance tests are cut, with no agent: every functional spec tested in one job - those of the modules below
+ * and the codebase's own alike, the tip's suite holding the chain's - a new job begun where the next functional spec
+ * would take the job's functional specs and the definitions they bring past `maxLines`; or, `separately`, a job a
+ * functional spec, as the person asked.
  * `size`: the movable lines of the last group of a grouping, its definitions placed.
  */
-function conformanceGroups(specs, separately, maxLines, size, titleOfSpec, 
-/** The group a functional spec was asked for in - none, -1: a job never takes two. */
-askedIn = () => -1) {
+function conformanceGroups(specs, separately, maxLines, size, titleOfSpec) {
     const groups = [];
     for (const spec of specs) {
         const last = groups.at(-1);
-        const first = last !== undefined ? specs.find((other) => other.number === last.specs[0]) : undefined;
-        const sameModule = first !== undefined && first.module === spec.module;
-        const sameAsk = first !== undefined && askedIn(first) === askedIn(spec);
-        if (!separately && last !== undefined && sameModule && sameAsk) {
+        if (!separately && last !== undefined) {
             const trial = [...groups.slice(0, -1), { specs: [...last.specs, spec.number] }].map((group) => ({ ...group, title: "" }));
             if (size(trial) <= maxLines) {
                 last.specs.push(spec.number);
@@ -355,15 +388,46 @@ askedIn = () => -1) {
     }
     return groups.map((group) => ({ specs: group.specs, title: group.specs.map(titleOfSpec).join("; ") }));
 }
-/** A functional spec's id, as the tree it is in has it - a conformance item's `frid` - or nothing when it says none. */
-function fridOf(change) {
+/** What an item of a section is, in the words the grouping agent is told it in. */
+const WHAT = {
+    [FUNCTIONAL_REQUIREMENTS]: "functional spec",
+    [REQUIRED_FUNCTIONAL_SPECS]: "functional spec",
+    [DEFINITIONS]: "definition",
+    [NON_FUNCTIONAL_REQUIREMENTS]: "implementation req",
+    [TEST_REQUIREMENTS]: "test req",
+};
+/** A change to what is built as the grouping agent is shown it: what it is, how it changes, and its text as it is now - or was, taken out. */
+function builtChangeOf(change, number, moduleName) {
+    const id = funcIdOf(change);
+    let module;
+    if (change.section === REQUIRED_FUNCTIONAL_SPECS) {
+        try {
+            module = JSON.parse(change.after ?? change.before ?? "{}").module;
+        }
+        catch {
+            // Not an item with a module.
+        }
+    }
+    else if (change.section === FUNCTIONAL_REQUIREMENTS)
+        module = moduleName;
+    return {
+        number,
+        kind: change.kind === "change" ? "changed" : change.kind === "remove" ? "taken out" : "added",
+        what: WHAT[change.section] ?? change.section,
+        text: textOf(change),
+        ...(id !== undefined ? { id } : {}),
+        ...(module !== undefined ? { module } : {}),
+    };
+}
+/** A functional spec's func-id, as the tree it is in has it - or nothing when it says none. */
+function funcIdOf(change) {
     for (const side of [change.after, change.before]) {
         if (side === undefined)
             continue;
         try {
-            const frid = JSON.parse(side).frid;
-            if (typeof frid === "string" && frid !== "")
-                return frid;
+            const id = JSON.parse(side).id;
+            if (typeof id === "string" && id !== "")
+                return id;
         }
         catch {
             // Not an item with an id.
@@ -384,10 +448,14 @@ async function cut(input, agents, notes) {
         return [];
     // What is grouped into jobs: the functional specs regenerated again - the modules' below first, as the codebase is
     // built on them - and the codebase's own, regenerated again or new at the end, in the spec's order.
-    const below = net.filter((change) => regeneratesAgain(change) && change.section === REQUIRED_FUNCTIONAL_SPECS).sort((a, b) => a.position - b.position);
-    // The conformance tests are written on the code as built: every functional spec added or changed is tested alike, wherever it is.
+    // The conformance tests are written on the code as built: every functional spec of the chain whose tests are added,
+    // changed or taken out is tested alike, wherever it is - so one edit, however mixed, is one pulse.
+    const testedIn = (section) => net.filter((change) => change.section === section).sort((a, b) => a.position - b.position);
+    const below = input.track === "conformance"
+        ? testedIn(REQUIRED_FUNCTIONAL_SPECS)
+        : net.filter((change) => regeneratesAgain(change) && change.section === REQUIRED_FUNCTIONAL_SPECS).sort((a, b) => a.position - b.position);
     const own = input.track === "conformance"
-        ? net.filter((change) => change.section === FUNCTIONAL_REQUIREMENTS && change.kind !== "remove").sort((a, b) => a.position - b.position)
+        ? testedIn(FUNCTIONAL_REQUIREMENTS)
         : [...net.filter((change) => regeneratesAgain(change) && change.section === FUNCTIONAL_REQUIREMENTS), ...newSpecsOf(net, input.current)].sort((a, b) => a.position - b.position);
     const specs = [...below, ...own];
     const inSpecs = new Set(specs);
@@ -400,7 +468,10 @@ async function cut(input, agents, notes) {
     const otherAdds = net.filter((change) => change.kind === "add" && !inSpecs.has(change) && !placedByKind.has(change) && change.section !== FUNCTIONAL_REQUIREMENTS);
     // Anything else changes what is built on - an edit, a removal, a functional spec built changed or put in among them.
     const builtChanges = net.filter((change) => !inSpecs.has(change) && !placedByKind.has(change) && !otherAdds.includes(change));
-    const hasBuilt = builtChanges.length > 0;
+    // Shown to the grouping agent, which puts each with the new work it belongs with or first; unplaced, each goes first.
+    const builtShown = builtChanges.map((change, index) => builtChangeOf(change, index + 1, input.moduleName));
+    /** Where each change to what is built goes: with the group holding a new functional spec - by that spec's number - or first. */
+    const builtTo = new Map();
     // Named as the person asks for it: "shorty.plain regenerate".
     const whole = [{ title: "regenerate", reason: "the whole of the work, in one job", changes: net.map((change) => change.id) }];
     if (specs.length === 0)
@@ -408,19 +479,27 @@ async function cut(input, agents, notes) {
     // 1. Which functional specs go together.
     reportStage(`planning the queue: which of the ${specs.length} functional spec${specs.length === 1 ? "" : "s"} to build go together`);
     const numbered = specs.map((change, index) => {
-        const required = change.section === REQUIRED_FUNCTIONAL_SPECS ? JSON.parse(change.after) : undefined;
+        const required = change.section === REQUIRED_FUNCTIONAL_SPECS ? JSON.parse(change.after ?? change.before) : undefined;
         return {
             number: index + 1,
             text: textOf(change),
-            id: required?.frid ?? String(change.position),
+            id: funcIdOf(change) ?? "",
+            place: change.position,
             ...(required?.module !== undefined ? { module: required.module } : input.moduleName !== undefined ? { module: input.moduleName } : {}),
             ...(regeneratesAgain(change) ? { again: true } : {}),
         };
     });
     const bySpec = new Map(specs.map((change, index) => [index + 1, change]));
+    const firstBuilt = () => builtChanges.filter((change) => (builtTo.get(change) ?? "first") === "first");
     const chunksFor = (list) => [
-        ...(hasBuilt ? [{ title: "Changes to what is built", specs: [], definitions: [], reqs: [], built: builtChanges }] : []),
-        ...list.map((group) => ({ title: group.title, specs: group.specs.map((number) => bySpec.get(number)), definitions: [], reqs: [] })),
+        ...(firstBuilt().length > 0 ? [{ title: "Changes to what is built", specs: [], definitions: [], reqs: [], built: firstBuilt() }] : []),
+        ...list.map((group) => ({
+            title: group.title,
+            specs: group.specs.map((number) => bySpec.get(number)),
+            definitions: [],
+            reqs: [],
+            joined: builtChanges.filter((change) => group.specs.includes(builtTo.get(change))),
+        })),
     ];
     const conformance = input.track === "conformance";
     // The conformance tests are grouped and their reqs placed by the harness: their agents are only asked for titles.
@@ -443,17 +522,22 @@ async function cut(input, agents, notes) {
         say(answer === undefined ? "the titles were not given - each pulse titled by its functional specs' first lines" : `the titles did not hold (${problems.join(" ")}) - each pulse titled by its functional specs' first lines`);
         return list;
     };
-    const grouped = conformance ? undefined : ((await agents?.group(numbered, (answer) => groupProblems(numbered, answer, maxSpecs), input.steering, maxSpecs).catch((error) => plannerFailed("group", error))) ?? undefined);
-    const holds = grouped !== undefined && groupProblems(numbered, grouped, maxSpecs).length === 0;
+    const grouped = conformance ? undefined : ((await agents?.group(numbered, (answer) => groupProblems(numbered, answer, maxSpecs, builtShown), input.steering, maxSpecs, builtShown.length > 0 ? builtShown : undefined).catch((error) => plannerFailed("group", error))) ?? undefined);
+    const holds = grouped !== undefined && groupProblems(numbered, grouped, maxSpecs, builtShown).length === 0;
+    // The grouping holds: each change to what is built goes where it was placed.
+    if (holds) {
+        for (const entry of grouped.built ?? []) {
+            const change = builtChanges[entry.change - 1];
+            if (change !== undefined)
+                builtTo.set(change, entry.to === "first" ? "first" : grouped.groups[entry.to - 1].specs[0]);
+        }
+    }
     const made = conformance
         ? conformanceGroups(numbered, input.separately === true, maxLines, (list) => {
             const trial = chunksFor(list);
             placeDefinitions(trial, definitions);
             return movableSize(trial.at(-1));
-        }, (number) => titleOf(bySpec.get(number)), (spec) => {
-            const frid = fridOf(bySpec.get(spec.number));
-            return frid === undefined ? -1 : (input.groups ?? []).findIndex((group) => group.includes(frid));
-        })
+        }, (number) => titleOf(bySpec.get(number)))
         : grouped !== undefined && holds
             ? grouped.groups
             : numbered.map((spec, index) => ({ specs: [spec.number], title: titleOf(specs[index]) }));
@@ -464,9 +548,9 @@ async function cut(input, agents, notes) {
             record({ kind: "planner.fellBack", step: "group", why: "no grouping was given" });
             say("the grouping was not given - a functional spec a pulse");
         }
-        else if (groupProblems(numbered, grouped, maxSpecs).length > 0) {
-            record({ kind: "planner.fellBack", step: "group", why: firstLine(groupProblems(numbered, grouped, maxSpecs).join(" "), 300) });
-            say(`the grouping did not hold (${groupProblems(numbered, grouped, maxSpecs).join(" ")}) - a functional spec a pulse`);
+        else if (groupProblems(numbered, grouped, maxSpecs, builtShown).length > 0) {
+            record({ kind: "planner.fellBack", step: "group", why: firstLine(groupProblems(numbered, grouped, maxSpecs, builtShown).join(" "), 300) });
+            say(`the grouping did not hold (${groupProblems(numbered, grouped, maxSpecs, builtShown).join(" ")}) - a functional spec a pulse`);
         }
     }
     // Titled before the chunks are made of them: a group split for its size keeps its title, numbered.
@@ -483,7 +567,7 @@ async function cut(input, agents, notes) {
         const placeInput = {
             ...(input.steering !== undefined ? { steering: input.steering } : {}),
             groups: newChunks().map((chunk, index) => ({ number: index + 1, title: chunk.title, specs: chunk.specs.map(textOf), definitions: chunk.definitions.map(textOf) })),
-            built: hasBuilt,
+            built: chunks.some((chunk) => chunk.built !== undefined),
             implementationReqs: implementationReqs.map((change, index) => ({ number: index + 1, text: textOf(change) })),
             testReqs: testReqs.map((change, index) => ({ number: index + 1, text: textOf(change) })),
         };
@@ -570,6 +654,7 @@ async function cut(input, agents, notes) {
     // It does not hold together: a functional spec a job, every req with the first.
     say(`the plan did not hold together (${checkDraft(input, draft)[0]?.slice(0, 120)}) - a functional spec a pulse`);
     placement = undefined;
+    builtTo.clear();
     groups.splice(0, groups.length, ...(await titled(numbered.map((spec, index) => ({ specs: [spec.number], title: titleOf(specs[index]) })))));
     chunks = chunksFor(groups);
     place();
@@ -580,11 +665,11 @@ async function cut(input, agents, notes) {
 }
 // ---------------------------------------------------------------------------------------------
 // The agents.
-export function groupPrompt(specs, steering, maxSpecs = MAX_SPECS_PER_JOB) {
+export function groupPrompt(specs, steering, maxSpecs = MAX_SPECS_PER_JOB, built = []) {
     return [
         "You plan how new work on a codebase is built: which of its new functional specs are built together, in one job.",
         "",
-        "Each job is rendered by a coding agent, reviewed and tested, then the next - fewer, fuller jobs: each job costs a",
+        "Each job is regenerated by a coding agent, reviewed and tested, then the next - fewer, fuller jobs: each job costs a",
         "coding session, a test run and a review. So group by default: what builds one feature goes together - the feature,",
         `its edge cases, and the functional specs that build on it - up to ${maxSpecs}: a component and the parts only it uses`,
         "(a timeout handler, a retry handler and the executor that runs a function through both), an endpoint and the one",
@@ -592,12 +677,12 @@ export function groupPrompt(specs, steering, maxSpecs = MAX_SPECS_PER_JOB) {
         "independent - nothing next to it builds on it or is part of the same thing - or when it is very large on its own.",
         "Never group specs only because they are of the same kind.",
         "",
-        "Only functional specs next to each other in the same module go together, and they stay in the order given: the",
+        "Only functional specs next to each other in the same module - one in the place after the other there - go together, and they stay in the order given: the",
         `order is what each is built on. Give each group a title that says what it builds - at most ${TITLE_WORDS} words and ${TITLE_CHARS}`,
         "characters: it heads the group's pulse where the person watches the work, and a longer one is cut short there.",
         "",
-        "The specification is split into modules - a ***plain matter, not how the code is laid out. Each numbers its",
-        "functional specs from 1: each below is given with its module and its id there, and a number of its own to answer with.",
+        "The specification is split into modules - a ***plain matter, not how the code is laid out. A functional spec has a",
+        "func-id, unique in its module: each below is given with its module, its func-id, its place among the module's functional specs, and a number of its own to answer with.",
         "",
         ...steeringBlock(steering),
         ...(specs.some((spec) => spec.again === true)
@@ -609,9 +694,27 @@ export function groupPrompt(specs, steering, maxSpecs = MAX_SPECS_PER_JOB) {
             : []),
         "The functional specs to build:",
         "",
-        ...specs.map((spec) => `<functional spec number="${spec.number}"${spec.module !== undefined ? ` module="${spec.module}"` : ""} id="${spec.id ?? spec.number}"${spec.again === true ? ' again="true"' : ""}>\n${spec.text.trim()}\n</functional spec>`),
+        ...specs.map((spec) => `<functional spec number="${spec.number}"${spec.module !== undefined ? ` module="${spec.module}"` : ""} id="${spec.id ?? spec.number}"${spec.place !== undefined ? ` place="${spec.place}"` : ""}${spec.again === true ? ' again="true"' : ""}>\n${spec.text.trim()}\n</functional spec>`),
         "",
-        "Call submit_groups once, with every one of them in a group.",
+        ...(built.length > 0
+            ? [
+                "The same work changes what is built already - below. Place each change: with the group of new functional specs",
+                'it belongs with, by the group\'s number, or "first" - in a pulse of its own, before the new work.',
+                "",
+                "- With a group, by default, when it is about the same thing as the group's new functional specs: one they build",
+                "  on changed, or one of the same feature changed or taken out. One pulse costs less than two.",
+                '- "first" when it reshapes what the new work is built on - a concept many functional specs use redefined, a',
+                "  functional spec others rely on taken out, a large rewrite - so the new work is built on code already changed and",
+                '  tested. "first" too when it has nothing to do with any group, or is too large to share a pulse.',
+                `- A functional spec changed counts toward its group's ${maxSpecs}; one taken out builds nothing, and does not.`,
+                "",
+                "The changes to what is built:",
+                "",
+                ...built.map((change) => `<change number="${change.number}" kind="${change.kind}" what="${change.what}"${change.module !== undefined ? ` module="${change.module}"` : ""}${change.id !== undefined ? ` id="${change.id}"` : ""}>\n${change.text.trim()}\n</change>`),
+                "",
+            ]
+            : []),
+        `Call submit_groups once, with every one of them in a group${built.length > 0 ? ", and every change to what is built placed" : ""}.`,
     ].join("\n");
 }
 export function placePrompt(input) {
@@ -681,11 +784,11 @@ async function askStep(options) {
 export function llmChunkAgents(options) {
     const label = options.label ?? "queue planner";
     return {
-        group: (specs, check, steering, maxSpecs) => askStep({
+        group: (specs, check, steering, maxSpecs, built) => askStep({
             cwd: options.cwd,
             model: options.model,
             label: `${label} grouping`,
-            task: groupPrompt(specs, steering, maxSpecs),
+            task: groupPrompt(specs, steering, maxSpecs, built),
             check,
             tool: (take) => defineTool({
                 name: "submit_groups",
@@ -693,6 +796,9 @@ export function llmChunkAgents(options) {
                 description: `The new functional specs in groups, in order: each group's spec numbers and a title of at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.`,
                 parameters: Type.Object({
                     groups: Type.Array(Type.Object({ specs: Type.Array(Type.Number()), title: Type.String({ description: `What the group builds: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.` }) })),
+                    built: Type.Optional(Type.Array(Type.Object({ change: Type.Number(), to: Type.Union([Type.Number(), Type.Literal("first")]) }), {
+                        description: 'Where each change to what is built goes: with a group, by its number, or "first" - a pulse of its own, before the new work.',
+                    })),
                     notes: Type.Optional(Type.String({ description: NOTES })),
                 }),
                 async execute(_id, params) {

package/dist/regenerate/conform.d.ts

@@ -1,4 +1,5 @@
 import type { JobCases } from "./drift.ts";
+import { type MarshalledPlainSource } from "../plain/spec.ts";
 import { type RenderConformanceTestsResult } from "./conformance.ts";
 import { type RegressionResult } from "./regression.ts";
 import { type SpecSnapshot } from "./regenerate.ts";
@@ -40,6 +41,8 @@ export interface RenderSpecDiffConformanceOptions {
     applied?: "applied" | "already applied";
     /** The spec as parsed with the diff in. Taken now, after applying it, when not given. */
     spec?: SpecSnapshot;
+    /** What the tests are written for once the job lands - the tests record it writes: its labels are checked against it. */
+    recorded?: MarshalledPlainSource;
     model?: string;
     onDelta?: (delta: string) => void;
 }

package/dist/regenerate/conform.js

@@ -23,8 +23,8 @@ export async function renderSpecDiffConformance(options) {
     stage(`the spec diff is ${applied === "applied" ? "applied to the .plain files" : "already in the .plain files"} - ` +
         `bringing the conformance tests in ${moduleName}'s codebase in line with it`);
     // The change is tested whatever it touches - with or without a functional spec yet.
-    const frids = [...getFrids(tree)];
-    const lastFrid = frids.at(-1);
+    const funcIds = [...getFrids(tree)];
+    const lastFuncId = funcIds.at(-1);
     if ((sectionsOf(tree)[TEST_REQUIREMENTS] ?? []).length === 0) {
         throw new Error(`${moduleName} has no ${TEST_REQUIREMENTS}, so conformance tests cannot be written: they say how conformance tests ` +
             "are written and run. Add them first - a change to them is a spec diff like any other.");
@@ -45,19 +45,20 @@ export async function renderSpecDiffConformance(options) {
     const gapsFrom = gapMark();
     const conformance = await renderConformanceTests({
         plainFile: tip.plainFile,
-        frid: lastFrid,
+        funcId: lastFuncId,
         templateDirs,
         buildDir,
         conformanceDir,
         diff: options.diff,
         ...(options.change !== undefined ? { change: options.change } : {}),
         ...(options.cases !== undefined ? { cases: options.cases } : {}),
+        ...(options.recorded !== undefined ? { recorded: options.recorded } : {}),
         spec: { moduleName, tree },
         model: options.model,
         onDelta: options.onDelta,
     });
     // What the codebase now has conformance tests for, as their labels say.
-    const tested = () => frids.filter((frid) => missingTestLabels(conformanceDir, frid, []).length === 0);
+    const tested = () => funcIds.filter((funcId) => missingTestLabels(conformanceDir, moduleName, { funcId, conformance: [], acceptance: [] }).length === 0);
     // 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) {
@@ -78,7 +79,7 @@ export async function renderSpecDiffConformance(options) {
         buildDir,
         conformanceRoot,
         moduleName,
-        frids,
+        funcIds,
         tree,
         required: getInheritedFunctionalSpecs(tree),
         scripts,

package/dist/regenerate/conformance-agents.d.ts

@@ -1,3 +1,4 @@
+import { type TestedSpec } from "./test-kinds.ts";
 import type { AgentSession, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { type ScriptRun, type TestScripts } from "./test-scripts.ts";
 import type { JobCases } from "./drift.ts";
@@ -18,8 +19,8 @@ export interface SpecContext {
     text: string;
 }
 /**
- * What an explorer hands the author of the conformance tests: how the software is built and run, how each functionality is reached from outside,
- * what it needs around it, and a plan for the tests.
+ * What an explorer hands the author of the conformance tests: how the software is built and run, how each functionality is
+ * reached from outside, and what it needs around it. What to test is the scenarios', never the explorer's.
  */
 export interface Exploration {
     buildAndRun: string;
@@ -31,15 +32,10 @@ export interface Exploration {
     testsReachIt: string;
     interfaces: Array<{
         module: string;
-        frid: string;
+        funcId: string;
         how: string;
     }>;
     environment: string;
-    plan: Array<{
-        module: string;
-        frid: string;
-        tests: string;
-    }>;
     other?: string;
 }
 /** An exploration as the test author, and the judge, read it. */
@@ -47,7 +43,7 @@ export declare function explorationText(exploration: Exploration, replies?: stri
 /**
  * What an exploration lacks for the conformance tests to be written from it alone, or nothing when
  * it is whole: how to build and run it, and - for every functionality the tests are for - how it
- * is reached and what to test.
+ * is reached.
  */
 /**
  * How many tool calls the agents with one thing to decide may make before they are told to decide:
@@ -62,18 +58,11 @@ export declare const JUDGE_CALLS = 30;
 export declare const MAX_EXPLORATION_CHARS = 12000;
 /** How many times the explorer may hand an exploration over: each ends its turn, and is checked. */
 export declare const EXPLORATION_SUBMISSIONS = 3;
-export declare function explorationProblems(exploration: Exploration | undefined, scope: ConflictScope, moduleName: string, 
-/** The functionalities whose acceptance tests the plan has to carry out, and how many each has. */
-acceptance?: Array<{
-    module: string;
-    frid: string;
-    count: number;
-}>): string[];
+export declare function explorationProblems(exploration: Exploration | undefined, scope: ConflictScope, moduleName: string): string[];
 /**
- * How the built software is invoked from outside, and a plan for its conformance tests, as an agent
- * that explored the code writes it - everything the tests' author works
- * from. Checked before it is used: it has to cover every functionality the tests are for, and is sent
- * back until it does. What the explorer wrote in its replies goes with an account it never completed.
+ * How the built software is invoked from outside, as an agent that explored the code writes it - everything of the code
+ * the tests' author works from; what to test is the scenarios'. Checked before it is used: it has to cover every
+ * functionality the tests are for, and is sent back until it does. What the explorer wrote in its replies goes with an account it never completed.
  */
 export declare function exploreInvocation(options: {
     buildDir: string;
@@ -90,12 +79,6 @@ export declare function exploreInvocation(options: {
         failure: string;
         account: string;
     };
-    /** The functionalities whose acceptance tests the plan has to carry out, and how many each has. */
-    acceptance?: Array<{
-        module: string;
-        frid: string;
-        count: number;
-    }>;
     label: string;
     model?: string;
     onDelta?: (delta: string) => void;
@@ -142,7 +125,7 @@ export interface ReviewProblem {
     kind: "missing" | "bad";
     what: string;
     /**
-     * The functionality is not yet tested, black box: a test or an acceptance test missing or cut down,
+     * The functionality is not yet tested, black box: a scenario's test missing or cut down,
      * the software mocked or reached other than from outside, a test that cannot fail or skips what it
      * checks. Never let go. Anything else is a way to make good tests better.
      */
@@ -150,7 +133,7 @@ export interface ReviewProblem {
 }
 /**
  * The review gate, after the conformance suite and the unit tests pass: do the tests this run added
- * or changed test the software black box, and do the acceptance tests do what the spec says - every
+ * or changed test the software black box, and do they carry out the scenarios as they say - every
  * step, every expectation. Passing tests prove nothing when they assert nothing, mock the software
  * they test, or skip what the spec asks for. It reads the tests and the code and changes neither.
  * No verdict is no pass: a gate that cannot say yes stays shut.
@@ -174,11 +157,8 @@ export declare function createTestReviewer(options: {
     buildDir: string;
     conformanceDir: string;
     spec: SpecContext;
-    /** The functionality under test - or, for a spec change, those it touches - with their acceptance tests. */
-    functionalities: Array<{
-        frid: string;
-        acceptanceTests: string[];
-    }>;
+    /** The functionality under test - or, for a spec change, those it touches - with their scenarios. */
+    functionalities: TestedSpec[];
     forChange?: boolean;
     invocation: string;
     label: string;
@@ -192,10 +172,7 @@ export declare function testReviewTask(options: {
     buildDir: string;
     conformanceDir: string;
     spec: SpecContext;
-    functionalities: Array<{
-        frid: string;
-        acceptanceTests: string[];
-    }>;
+    functionalities: TestedSpec[];
     forChange?: boolean;
     invocation: string;
 }): string;
@@ -241,7 +218,7 @@ export interface Escalation {
 /** A functionality, by the module it is in and its id there: a conflict can cross modules. */
 export interface FunctionalityRef {
     module: string;
-    frid: string;
+    funcId: string;
 }
 /** "billing 4": a functionality as the judge and the person read it. */
 export declare function refLabel(ref: FunctionalityRef): string;
@@ -269,12 +246,14 @@ export interface ConflictScope {
     functionalities: FunctionalityRef[];
     /** The functionality under test, which every conflict raised must include. None for a spec diff. */
     tested?: FunctionalityRef;
+    /** For a spec diff: the modules whose functional specs it touches - a module below's, tested in the tip, among them. */
+    touchedModules?: string[];
 }
 /** A conflict's functionalities as the judge gave them, tidied: trimmed, and each once. */
 export declare function conflictRefs(given: Array<{
     module?: string;
     id?: string;
-    frid?: string;
+    funcId?: string;
 }> | undefined): FunctionalityRef[];
 /** Why a spec conflict cannot be raised as given, or nothing when it can. */
 export declare function specConflictProblem(functionalities: FunctionalityRef[] | undefined, scope: ConflictScope): string | undefined;