@turri-dev/cli 0.1.27 → 0.1.28-next.d5f2680

package/dist/regenerate/spec-steps.js

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
-import { ACCEPTANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS, TEST_REQUIREMENTS, getInheritedFunctionalSpecs, } from "../plain/spec.js";
+import { ACCEPTANCE_TESTS, CONFORMANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS, TEST_REQUIREMENTS, getInheritedFunctionalSpecs, } from "../plain/spec.js";
 import { validateConcepts } from "../plain/concepts.js";
 import { sectionTag } from "./prompt.js";
 /**
@@ -11,9 +11,10 @@ import { sectionTag } from "./prompt.js";
  *
  * Both specs are marshalled trees, written out as text with one JSON value per line - a
  * section's name, then each of its items on a line of its own - and compared with git. So an
- * item is the unit of change: a functional spec with its acceptance tests and linked resources,
+ * item is the unit of change: a functional spec with its scenarios and linked resources,
  * a definition, a req. Git lines them up, so a spec inserted in the middle is one addition and
- * the specs after it are untouched, though their numbers moved.
+ * the specs after it are untouched. A functional spec is known by its func-id: one taken out and
+ * one put in with the same func-id are the same functional spec, changed - or, the same text, moved.
  *
  * The planner (`chunk-plan.ts`) cuts the changes into steps - which go together, which go first. It
  * picks changes by id; it never writes a diff. `makeStep` applies what it picked, and `inconsistencies`
@@ -72,8 +73,9 @@ export function sameSpec(before, after) {
     const had = modulesOf(before);
     if ([...modulesOf(after)].some((module) => !had.has(module)))
         return false;
+    // A functional spec by its func-id and what it says, wherever it is written: moved, it is the same spec.
     const text = (item) => {
-        const { module: _module, frid: _frid, ...rest } = item;
+        const { module: _module, ...rest } = item;
         return JSON.stringify(sortKeys(rest));
     };
     const list = (tree, heading) => (tree[heading] ?? []).map(text);
@@ -84,7 +86,7 @@ export function sameSpec(before, after) {
             .map((key) => [key, sortKeys(tree[key])]);
         return JSON.stringify({
             sections: [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS].map((heading) => list(tree, heading).sort()),
-            specs: [...list(tree, REQUIRED_FUNCTIONAL_SPECS), ...list(tree, FUNCTIONAL_REQUIREMENTS)],
+            specs: [...list(tree, REQUIRED_FUNCTIONAL_SPECS), ...list(tree, FUNCTIONAL_REQUIREMENTS)].sort(),
             others,
         });
     };
@@ -245,7 +247,51 @@ export function changesBetween(before, after) {
             });
         });
     }
-    return changes;
+    return mergeMoves(changes);
+}
+/** The sections whose items are functional specs, each known by its func-id. */
+const FUNCTIONAL_SECTIONS = [FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS];
+/** A functional spec's identity - its func-id, and its module for one a module below has - or undefined for any other line. */
+function identityOfLine(line) {
+    if (line === undefined || headerOf(line) !== undefined)
+        return undefined;
+    try {
+        const item = JSON.parse(line);
+        return typeof item.id === "string" ? `${typeof item.module === "string" ? item.module : ""}:${item.id}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A functional spec taken out in one place and put in at another - the same func-id - is one change, not two: moved,
+ * and changed where its text differs. git lines up a move as a removal and an addition, in hunks of their own; the change
+ * takes the line out where it was and puts it in where it now is.
+ */
+function mergeMoves(changes) {
+    // Paired first, whichever comes first: a spec moved up is added before it is removed.
+    const pairs = new Map();
+    const used = new Set();
+    for (const change of changes) {
+        const identity = change.kind === "remove" && FUNCTIONAL_SECTIONS.includes(change.section) ? identityOfLine(change.before) : undefined;
+        const added = identity === undefined ? undefined : changes.find((other) => !used.has(other) && other.kind === "add" && other.section === change.section && identityOfLine(other.after) === identity);
+        if (added === undefined)
+            continue;
+        used.add(added);
+        pairs.set(change, added);
+    }
+    const merged = [];
+    for (const change of changes) {
+        if (used.has(change))
+            continue;
+        const added = pairs.get(change);
+        merged.push(added === undefined ? change : { ...change, kind: "change", after: added.after, position: added.position, inserts: added.inserts });
+    }
+    return merged.map((change, index) => ({ ...change, id: `c${index + 1}` }));
+}
+/** Whether a change moves a functional spec and leaves what it says as it was. */
+export function isMove(change) {
+    return change.kind === "change" && change.before === change.after;
 }
 /** The words of an item's text, for telling a changed item from a different one. */
 function wordsOf(line) {
@@ -268,12 +314,18 @@ export function similarity(a, b) {
 const SAME_ITEM = 0.5;
 /**
  * Which removed item became which added one, in order on both sides: the pairing that matches
- * the most alike items. Only items at least SAME_ITEM alike are paired.
+ * the most alike items. A functional spec pairs only with the one of its func-id; any other item only with one at
+ * least SAME_ITEM alike.
  */
 function pairItems(removed, added) {
-    const alike = (r, a) => headerOf(removed[r]) === undefined && headerOf(added[a]) === undefined && similarity(removed[r], added[a]) >= SAME_ITEM
-        ? similarity(removed[r], added[a])
-        : 0;
+    const alike = (r, a) => {
+        if (headerOf(removed[r]) !== undefined || headerOf(added[a]) !== undefined)
+            return 0;
+        const identity = identityOfLine(removed[r]);
+        if (identity !== undefined || identityOfLine(added[a]) !== undefined)
+            return identity === identityOfLine(added[a]) ? 1 : 0;
+        return similarity(removed[r], added[a]) >= SAME_ITEM ? similarity(removed[r], added[a]) : 0;
+    };
     // Best total likeness over order-keeping pairings - a longest common subsequence, weighted.
     const best = Array.from({ length: removed.length + 1 }, () => new Array(added.length + 1).fill(0));
     for (let r = removed.length - 1; r >= 0; r -= 1) {
@@ -314,15 +366,82 @@ export function applyChanges(before, changes) {
     }
     return `${out.join("\n")}\n`;
 }
-/** An item as a person reads it: its text, and its acceptance tests under it. */
+/** A functional spec's scenarios of one kind, as a person reads them: each under its scenario-id, in its section's tag. */
+export function scenarioLines(tag, scenarios) {
+    if (scenarios === undefined || scenarios.length === 0)
+        return [];
+    const indent = (text) => text.split("\n").map((line) => (line === "" ? "" : `  ${line}`)).join("\n");
+    return [`  <${tag}>`, ...scenarios.map((scenario) => indent(`# ${scenario.id ?? ""}\n${scenario.text ?? ""}`)), `  </${tag}>`];
+}
+/**
+ * An item as a person reads it: a functional spec under its `# <func-id>` heading, as its module's file writes it,
+ * with its conformance and acceptance scenarios under it where the tree has them; anything else as it reads.
+ */
 function itemText(line) {
     const item = JSON.parse(line);
-    const tests = item[ACCEPTANCE_TESTS] ?? [];
     return [
-        item.markdown ?? line,
-        ...(tests.length > 0 ? ["  <acceptance tests>", ...tests.map((test) => `  ${(test.markdown ?? "").replace(/\n/g, "\n  ")}`), "  </acceptance tests>"] : []),
+        item.id !== undefined ? `# ${item.id}\n${item.markdown ?? ""}` : (item.markdown ?? line),
+        ...scenarioLines("conformance tests", item[CONFORMANCE_TESTS]),
+        ...scenarioLines("acceptance tests", item[ACCEPTANCE_TESTS]),
     ].join("\n");
 }
+/** An item as its module's file writes it: a functional spec under its `# <func-id>` heading - its scenarios are in its test plain file. */
+function fileItemText(line) {
+    const item = JSON.parse(line);
+    return item.id !== undefined ? `# ${item.id}\n${item.markdown ?? ""}` : (item.markdown ?? line);
+}
+/** A functional spec's test plain file, as it would read: its binding, then each section that has scenarios, each scenario under its id. */
+export function testPlainFileText(module, item) {
+    // A section with no scenarios is left out: it is a syntax error.
+    const section = (title, scenarios) => (scenarios ?? []).length === 0 ? [] : [`${title}\n\n${(scenarios ?? []).map((scenario) => `# ${scenario.id ?? ""}\n${(scenario.text ?? "").trim()}`).join("\n\n")}`];
+    const sections = [...section("***conformance tests***", item[CONFORMANCE_TESTS]), ...section("***acceptance tests***", item[ACCEPTANCE_TESTS])];
+    return `---\nmodule: ${module}\nfunc_id: ${item.id ?? ""}\n---\n\n${sections.join("\n\n")}\n`;
+}
+/** One file's two texts as git diffs them, named `path` on both sides: an empty side is the file added or taken out whole. */
+export function diffFileTexts(before, after, path) {
+    return before === after ? "" : gitDiff(before, after, 3, [path, path]);
+}
+/**
+ * The functional specs' test plain files a change between two serialized trees touches, each as a diff of its own,
+ * rebuilt from the trees as the module's file is: only the trees that carry scenarios - the conformance tests' - have
+ * any. A functional spec that had no scenarios has no test plain file before, so its file shows as added whole; one whose
+ * scenarios all went, as deleted whole - an empty one is a syntax error.
+ */
+export function diffTestPlainFiles(before, after, module, pathOf) {
+    const carriers = (serialized) => {
+        const found = new Map();
+        let section;
+        for (const line of serialized.split("\n")) {
+            if (line === "")
+                continue;
+            const header = headerOf(line);
+            if (header !== undefined) {
+                section = header.key;
+                continue;
+            }
+            // A module below's functional specs too, by module and func-id: the tip's conformance suite holds the chain's.
+            if (section === undefined || !FUNCTIONAL_SECTIONS.includes(section))
+                continue;
+            const item = JSON.parse(line);
+            // A functional spec with no scenarios - none listed, or the lists empty - has no test plain file.
+            if (item.id !== undefined && (item[CONFORMANCE_TESTS] ?? []).length + (item[ACCEPTANCE_TESTS] ?? []).length > 0)
+                found.set(`${item.module ?? ""}:${item.id}`, item);
+        }
+        return found;
+    };
+    const was = carriers(before);
+    const now = carriers(after);
+    return [...new Set([...now.keys(), ...was.keys()])]
+        .map((key) => {
+        const item = now.get(key) ?? was.get(key);
+        const owner = item.module ?? module;
+        const text = (found) => (found === undefined ? "" : testPlainFileText(owner, found));
+        const [from, to] = [text(was.get(key)), text(now.get(key))];
+        const path = pathOf(item.id ?? "", owner);
+        return from === to ? "" : gitDiff(from, to, 3, [path, path]);
+    })
+        .join("");
+}
 /** A serialized tree as a person reads it, section by section. */
 export function treeText(serialized) {
     const out = [];
@@ -345,25 +464,52 @@ export function treeText(serialized) {
         out.push(`</${open}>`);
     return out.join("\n").trim();
 }
-/** What of an item a change touches: its text, its acceptance tests, its linked resources. */
+/** What of an item a change touches: its text, its scenarios, its linked resources. */
 function changedParts(before, after) {
     if (headerOf(before) !== undefined || headerOf(after) !== undefined)
         return "the text";
     const x = JSON.parse(before);
     const y = JSON.parse(after);
-    const names = { markdown: "the text", [ACCEPTANCE_TESTS]: "the acceptance tests", linked_resources: "the linked resources", code_variables: "the code variables" };
+    const names = {
+        markdown: "the text",
+        [CONFORMANCE_TESTS]: "the conformance scenarios",
+        [ACCEPTANCE_TESTS]: "the acceptance scenarios",
+        linked_resources: "the linked resources",
+        code_variables: "the code variables",
+    };
     const parts = [...new Set([...Object.keys(x), ...Object.keys(y)])]
         .filter((key) => JSON.stringify(x[key]) !== JSON.stringify(y[key]))
         .map((key) => names[key] ?? key);
     return parts.length === 0 ? "the text" : parts.join(" and ");
 }
+/** A functional spec a change is to, by its func-id - `module:func-id` for one of a module below - or nothing for another item. */
+function funcSpecOf(change) {
+    if (!FUNCTIONAL_SECTIONS.includes(change.section))
+        return undefined;
+    try {
+        const item = JSON.parse(change.after ?? change.before ?? "");
+        if (item.id === undefined)
+            return undefined;
+        return `functional spec \`${item.module !== undefined ? `${item.module}:` : ""}${item.id}\``;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** A change as the planning agent is shown it. */
 export function describeChange(change) {
-    const what = change.kind === "add"
-        ? `add to ${change.section}, as item ${change.position}`
-        : change.kind === "remove"
-            ? `remove item ${change.position} of ${change.section}`
-            : `change ${changedParts(change.before, change.after)} of item ${change.position} of ${change.section}`;
+    const spec = funcSpecOf(change);
+    const what = spec !== undefined
+        ? change.kind === "add"
+            ? `add ${spec} to ${change.section}, as item ${change.position}`
+            : change.kind === "remove"
+                ? `remove ${spec} from ${change.section}`
+                : `change ${changedParts(change.before, change.after)} of ${spec}`
+        : change.kind === "add"
+            ? `add to ${change.section}, as item ${change.position}`
+            : change.kind === "remove"
+                ? `remove item ${change.position} of ${change.section}`
+                : `change ${changedParts(change.before, change.after)} of item ${change.position} of ${change.section}`;
     const header = (line) => (line !== undefined && headerOf(line) !== undefined ? `the section ${headerOf(line).key}` : undefined);
     const body = [
         ...(change.before !== undefined ? ["  before:", `    ${(header(change.before) ?? itemText(change.before)).replace(/\n/g, "\n    ")}`] : []),
@@ -397,7 +543,7 @@ export function layoutOf(text) {
             continue;
         }
         // An item straight after another's last line, with no blank line: the section is written tight.
-        if (section !== undefined && line.startsWith("- ") && previous.trim() !== "" && !SECTION_HEADING.test(previous))
+        if (section !== undefined && section !== FUNCTIONAL_REQUIREMENTS && line.startsWith("- ") && previous.trim() !== "" && !SECTION_HEADING.test(previous))
             tight.add(section);
         previous = line;
         const concept = CONCEPT.exec(line);
@@ -423,7 +569,7 @@ export function plainText(serialized, layout) {
         if (header !== undefined)
             sections.push({ key: header.key, items: [] });
         else
-            sections.at(-1)?.items.push(itemText(line));
+            sections.at(-1)?.items.push(fileItemText(line));
     }
     const own = sections.filter((section) => section.key !== REQUIRED_FUNCTIONAL_SPECS && section.items.length > 0);
     if (layout === undefined)
@@ -450,6 +596,41 @@ export function plainText(serialized, layout) {
 export function diffSpecText(before, after, file = "spec.plain", layout) {
     return gitDiff(`${plainText(before, layout)}\n`, `${plainText(after, layout)}\n`, 3, [file, file]);
 }
+/**
+ * The functional specs of the modules below that a change between two serialized trees touches, each module's as a diff
+ * of its own file's `***functional specs***`: the tip is built with them, but its own file does not hold them.
+ */
+export function diffRequiredSpecs(before, after, file = "spec.plain") {
+    const byModule = (serialized) => {
+        const found = new Map();
+        let section;
+        for (const line of serialized.split("\n")) {
+            if (line === "")
+                continue;
+            const header = headerOf(line);
+            if (header !== undefined) {
+                section = header.key;
+                continue;
+            }
+            if (section !== REQUIRED_FUNCTIONAL_SPECS)
+                continue;
+            const module = JSON.parse(line).module ?? "";
+            found.set(module, [...(found.get(module) ?? []), fileItemText(line)]);
+        }
+        return found;
+    };
+    const was = byModule(before);
+    const now = byModule(after);
+    const folder = dirname(file);
+    return [...new Set([...was.keys(), ...now.keys()])]
+        .map((module) => {
+        const text = (items) => (items === undefined ? "" : `***${FUNCTIONAL_REQUIREMENTS}***\n\n${items.join("\n\n")}\n`);
+        const [from, to] = [text(was.get(module)), text(now.get(module))];
+        const path = folder === "." ? `${module}.plain` : `${folder}/${module}.plain`;
+        return from === to ? "" : gitDiff(from, to, 3, [path, path]);
+    })
+        .join("");
+}
 /** The linked resources of a changed item whose content is different now - each hashed on its own: by their path, with both hashes. */
 export function resourcesChanged(before, after) {
     const resources = (line) => {
@@ -494,7 +675,7 @@ export function resourceDiff(changes, file = "spec.plain") {
     ].join("\n"))
         .join("");
 }
-/** The item a change is to, as the person finds it: its concept or its number, in the spec file it is in - a module below's by its name. */
+/** The item a change is to, as the person finds it: its concept, its func-id or its number, in the spec file it is in - a module below's by its name. */
 function linkedBy(change, file) {
     let item = {};
     try {
@@ -506,12 +687,16 @@ function linkedBy(change, file) {
     const concept = /^-?\s*(:[^:\s]+:)/.exec(item.markdown?.trim() ?? "")?.[1];
     const what = change.section === DEFINITIONS && concept !== undefined
         ? concept
-        : change.section === FUNCTIONAL_REQUIREMENTS
-            ? `functional spec ${change.position}`
+        : FUNCTIONAL_SECTIONS.includes(change.section) && item.id !== undefined
+            ? `functional spec ${item.id}`
             : `${sectionTag(change.section).replace(/s$/, "")} ${change.position}`;
     return `${what} in ${item.module !== undefined ? `${item.module}.plain` : file}`;
 }
-export function makeStep(title, reason, changes, before, after, file, layout) {
+/**
+ * A step of the work. `testPlain`: for the conformance tests' steps, the module and where its functional specs' test plain
+ * files are - a scenario changed shows as a diff of its test plain file, after the module's.
+ */
+export function makeStep(title, reason, changes, before, after, file, layout, testPlain) {
     return {
         title,
         reason,
@@ -521,7 +706,7 @@ export function makeStep(title, reason, changes, before, after, file, layout) {
         tree: parseTree(after),
         diff: diffTrees(before, after),
         // What a linked resource holds changed shows in the step's diff, after the spec's own.
-        textDiff: `${diffSpecText(before, after, file, layout)}${resourceDiff(changes, file)}`,
+        textDiff: `${diffSpecText(before, after, file, layout)}${diffRequiredSpecs(before, after, file)}${testPlain !== undefined ? diffTestPlainFiles(before, after, testPlain.module, testPlain.pathOf) : ""}${resourceDiff(changes, file)}`,
         sections: [...new Set(changes.map((change) => change.section))],
     };
 }

package/dist/regenerate/state.d.ts

@@ -1,4 +1,4 @@
-import { DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, type MarshalledPlainSource } from "../plain/spec.ts";
+import { DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, type MarshalledPlainSource, type ScenarioText } from "../plain/spec.ts";
 /**
  * A module's spec as the prompts read it: the sections every functional spec shares, and a
  * functional spec a module inherits. What the code and the tests are built from is in `records.ts`.
@@ -12,9 +12,10 @@ export interface SharedSections {
 /** A functional spec of a module this one requires: documented, not built here. */
 export interface RequiredSpec {
     module: string;
-    frid: string;
+    funcId: string;
     spec: string;
-    acceptanceTests?: string[];
+    conformanceTests?: ScenarioText[];
+    acceptanceTests?: ScenarioText[];
 }
 /** A module's shared sections as they stand, with or without a functional spec to read them through. */
 export declare function sectionsOf(tree: MarshalledPlainSource): SharedSections;

package/dist/regenerate/stop-report.d.ts

@@ -15,7 +15,7 @@ export declare const ATTEMPTS: Record<StopPoint, number>;
 export interface StopFacts {
     moduleName: string;
     /** The functionality it stopped at; none for a spec change. */
-    frid?: string;
+    funcId?: string;
     at: StopPoint;
     /** The unit test runs, the last of which is the failing one. */
     runs?: TestRun[];

package/dist/regenerate/stop-report.js

@@ -11,7 +11,7 @@ export const ATTEMPTS = {
  * offered here is a change to a `.plain` file, never to code, tests or the machine.
  */
 export function describeStop(facts) {
-    const what = facts.frid !== undefined ? `${facts.moduleName} functionality ${facts.frid}` : `the spec change in ${facts.moduleName}`;
+    const what = facts.funcId !== undefined ? `functional spec ${facts.moduleName}:${facts.funcId}` : `the spec change in ${facts.moduleName}`;
     // What actually happened, not the most it could have been.
     const tries = facts.at === "unit tests" ? (facts.attempts ?? ATTEMPTS[facts.at]) : facts.at === "conformance" ? (facts.conformance?.rounds ?? ATTEMPTS[facts.at]) : ATTEMPTS[facts.at];
     let why;
@@ -50,12 +50,12 @@ export function describeStop(facts) {
     }
     else if (facts.at === "conformance" && facts.conformance?.specConflict !== undefined) {
         const { functionalities, reason } = facts.conformance.specConflict;
-        const [one, two] = functionalities.map((ref) => `${ref.module} ${ref.frid}`);
+        const [one, two] = functionalities.map((ref) => `${ref.module}:${ref.funcId}`);
         why = `its spec contradicts itself: functionalities ${one} and ${two} cannot both hold. ${reason.trim()}`;
         todo = [
             `Compare functional specs ${one} and ${two} (\`analyze-2-func-specs\`, \`resolve-spec-conflict\`) and change whichever is wrong - ` +
                 "or both, so they say the same thing about where they meet.",
-            "If one is meant to change what the other does, say so in the one that changes it, and update its acceptance tests to match.",
+            "If one is meant to change what the other does, say so in the one that changes it, and update its scenarios to match.",
         ];
     }
     else if (facts.at === "conformance" && facts.conformance?.review !== undefined && facts.conformance.stuck === undefined) {
@@ -64,14 +64,14 @@ export function describeStop(facts) {
             `its conformance tests pass, but never passed review in ${tries} round${tries === 1 ? "" : "s"}: they do not yet test what the spec says, ` +
                 `black box. What the review last found:\n${problems.slice(0, 8).map((problem) => `    - ${problem.kind === "missing" ? "missing" : "bad"} · ${problem.file}${problem.test ? ` · ${problem.test}` : ""}: ${problem.what.trim().replace(/\s+/g, " ")}`).join("\n")}`;
         todo = [
-            "If an acceptance test asks for something the tests cannot do - a service they cannot reach, data they cannot set up - say in the test " +
-                "reqs how they do it, or change the acceptance test to what can be checked.",
+            "If a scenario asks for something the tests cannot do - a service they cannot reach, data they cannot set up - say in the test " +
+                "reqs how they do it, or change the scenario to what can be checked.",
             "If the test reqs leave open how the software is reached or what may be mocked, say so exactly.",
         ];
     }
     else if (facts.at === "conformance" && facts.conformance?.unlabelled !== undefined) {
         why =
-            "its conformance tests were never written and labelled as the two kinds - conformance tests and each acceptance test - " +
+            "its conformance tests were never written and labelled as the scenarios they carry out - each conformance and acceptance scenario - " +
                 `though they were sent back for it again and again. Still missing:\n${facts.conformance.unlabelled.map((line) => `    - ${line}`).join("\n")}`;
         todo = ["If the test reqs leave open where the tests go or how they are built, say so exactly - the folder, the files, the build."];
     }
@@ -109,7 +109,7 @@ export function describeStop(facts) {
         why = `after ${tries} round${tries === 1 ? "" : "s"}, its conformance tests and its code still disagree about what the spec means.`;
         todo = [
             "The functional spec can be read more than one way. Say exactly what should happen - the inputs, the outputs, " +
-                "the edge cases - and add acceptance tests that pin down the expected result.",
+                "the edge cases - and add scenarios to its test plain file that pin down the expected result.",
             "If the conformance tests are meant to be written or run differently - framework, command, setup - change the test reqs.",
         ];
     }
@@ -121,7 +121,7 @@ export function describeStop(facts) {
             "This most often means its spec contradicts an earlier one. Compare them (`analyze-func-specs`, " +
                 "`resolve-spec-conflict`) and change whichever is wrong.",
             "If the new behaviour is meant to change what an earlier functionality does, change that earlier spec and its " +
-                "acceptance tests to say so.",
+                "scenarios to say so.",
         ];
     }
     return [
@@ -140,13 +140,13 @@ export function describeStop(facts) {
  * spec is all they work on, and the fix is theirs to choose.
  */
 export function describeSpecConflict(conflict) {
-    const name = (spec) => `functional spec ${spec.frid} of ${spec.module}`;
+    const name = (spec) => `functional spec ${spec.module}:${spec.funcId}`;
     const [one, two] = conflict.specs;
     return [
         `The spec contradicts itself: ${name(one)} and ${name(two)} cannot both hold.`,
         "",
         ...conflict.specs.flatMap((spec) => [
-            `Functional spec ${spec.frid} of ${spec.module} (${basename(spec.plainFile)}):`,
+            `Functional spec ${spec.module}:${spec.funcId} (${basename(spec.plainFile)}):`,
             ...spec.text.trim().split("\n").map((line) => `  ${line}`),
             "",
         ]),

package/dist/regenerate/test-advisor.d.ts

@@ -0,0 +1,101 @@
+import type { AdvisorAnswer, AdvisorInput, AdvisorReport } from "./advisor-records.ts";
+/**
+ * The test advisor's judgement of one functional spec: does it need explicit testing scenarios, and if so, which inputs
+ * should they cover (docs/test-advisor.md). Every step is a plain model call on `models.advisor`, answered through one
+ * tool and checked in code, as the planner's grouping agent is - none is a skill, and none can touch the project.
+ *
+ * - **Classify:** four questions, each yes carrying its evidence - a wrong output that looks right (silent failure), an
+ *   input two reasonable readings answer differently (divergence), what would change (revisited), the consequence of a
+ *   bug (cost). A yes whose evidence is empty or malformed counts as no. Silent failure, divergence or cost make the
+ *   verdict yes; revisited alone does not - the unit tests are the regression protection.
+ * - **On a yes, pick the inputs:** one call writes 1-10 boundary probes (and the divergence's input), readers that
+ *   differ only by their system prompt each predict every probe's output, code compares them, and any disagreement is a
+ *   candidate - the union, never a majority. The third reader is spared when the first two already disagree. One last
+ *   call keeps, of each candidate, the readings a reasonable person could hold.
+ */
+/** The functional spec the advisor looks at, and what it reads it with. */
+export interface AdvisorSubject {
+    module: string;
+    funcId: string;
+    /** The functional spec's text. */
+    text: string;
+    /** The module's .plain file, whole: its definitions, its reqs, the functional specs around it. */
+    moduleText: string;
+    /** The project's own words on what matters: its AGENTS.md, the steering given in the conversation. */
+    context: string[];
+    /** A module below's: the tip its scenarios are tested in - built on it, its own functional specs beside it. */
+    testedIn?: {
+        module: string;
+        text: string;
+    };
+    /** Why the chat asked for the evaluation (evaluate_tests) - "the coding agent failed three times to implement it" - for the classifier, as context. */
+    reason?: string;
+}
+export interface AdvisorCallOptions {
+    /** Where the calls run: the project. */
+    cwd: string;
+    /** The advisor's model (advisorModel) - the `advisor` role's config is laid over it as for any agent. */
+    model?: string;
+}
+/** The classification: the verdict, the questions that were a yes with their evidence, and the divergence's input. */
+export interface Classification {
+    verdict: "yes" | "no";
+    questions: AdvisorAnswer[];
+    divergence?: {
+        input: string;
+        readings: [string, string];
+    };
+}
+/** The fewest and most probes a functional spec is given. */
+export declare const MIN_PROBES = 1;
+export declare const MAX_PROBES = 10;
+/** What a reader answers for an input the functional spec does not settle: a scenario on it would pin a guess. */
+export declare const UNSPECIFIED = "unspecified";
+/** The readers: the same task, decorrelated by their system prompts alone. */
+export declare const READERS: ReadonlyArray<{
+    name: string;
+    system: string;
+}>;
+/** Text compared as the readers' outputs are: whitespace collapsed, case left aside. */
+export declare function normalised(text: string): string;
+type ClassificationAnswer = {
+    silent_failure: {
+        answer: boolean;
+        wrong_output?: string;
+    };
+    divergence: {
+        answer: boolean;
+        input?: string;
+        reading_a?: string;
+        reading_b?: string;
+    };
+    revisited: {
+        answer: boolean;
+        would_change?: string;
+    };
+    cost: {
+        answer: boolean;
+        consequence?: string;
+    };
+};
+/**
+ * The classification, from the call's answer: each yes kept only with its evidence - a yes without it, or with it
+ * malformed (two readings that are the same), is a no. The verdict is yes on silent failure, divergence or cost.
+ */
+export declare function classificationOf(answer: ClassificationAnswer): Classification;
+/** Classify a functional spec: one call, four evidence-backed questions. Throws when the call gives no answer. */
+export declare function classify(subject: AdvisorSubject, options: AdvisorCallOptions): Promise<Classification>;
+/**
+ * The inputs the readers split on - every probe where any two predictions differ once normalised: the union, never a
+ * majority - each with its distinct readings, in the order the readers gave them.
+ */
+export declare function splitInputs(readings: string[][]): Map<number, string[]>;
+/**
+ * Pick the inputs a functional spec's scenarios should cover: the probes, the readers' predictions of them, the
+ * disagreements in code, and the verifier's word on each. An input the readers agree on comes with their output; one
+ * they split on, with every reading the verifier kept - a single reading left is an agreed one, and none left drops it.
+ */
+export declare function pickInputs(subject: AdvisorSubject, classification: Classification, options: AdvisorCallOptions): Promise<AdvisorInput[]>;
+/** The whole judgement: classify, and on a yes pick the inputs. Throws when a call that cannot be done without fails. */
+export declare function advise(subject: AdvisorSubject, options: AdvisorCallOptions): Promise<AdvisorReport>;
+export {};