@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/regenerate/agent-shell.js

@@ -0,0 +1,114 @@
+import { dirname, join, resolve, sep } from "node:path";
+import { readProjectConfig, stackOf } from "../config.js";
+import { reportNote } from "./activity.js";
+import { agentEnvironment, DARWIN_TEMP_SUFFIX, packageCacheDir, TOOLCHAIN_VARIABLES } from "./agent-env.js";
+import { afterCommand, auditMessage, beforeCommand } from "./audit.js";
+import { checkCommand, machineReadable } from "./command-check.js";
+import { darwinUserDirs, machineFor, sandboxAvailable, sandboxWrap } from "./os-sandbox.js";
+import { MODULES_DIR, projectRootOf } from "./paths.js";
+import { RECORD_FILE } from "./records.js";
+import { runCommand } from "./shell.js";
+/**
+ * What a module's shell writes beside its roots: its home, its TMPDIR, the package caches - and on macOS its own folder
+ * in the per-user temporary folder, where its JVMs keep the attach sockets Mockito's inline mocks and jcmd go through.
+ */
+export function writableFor(env, moduleDir) {
+    const darwinTemp = darwinUserDirs().temp;
+    const suffix = env[DARWIN_TEMP_SUFFIX];
+    return [env.HOME, env.TMPDIR, packageCacheDir(moduleDir), ...(darwinTemp !== undefined && suffix !== undefined ? [join(darwinTemp, suffix)] : [])];
+}
+/** The module a folder is part of: `plain_modules/<module>`, or - a build folder elsewhere - its parent. */
+function moduleOf(dir) {
+    const parts = resolve(dir).split(sep);
+    const index = parts.lastIndexOf(MODULES_DIR);
+    return index >= 0 && parts.length > index + 1 ? parts.slice(0, index + 2).join(sep) : dirname(resolve(dir));
+}
+export function agentShell(role, options = {}) {
+    const workdir = resolve(role.workdir);
+    const read = (role.read ?? [workdir]).map((dir) => resolve(dir));
+    const write = (role.write ?? [workdir]).map((dir) => resolve(dir));
+    const moduleDir = moduleOf(workdir);
+    const project = projectRootOf(workdir);
+    const { env } = agentEnvironment(moduleDir);
+    const root = projectRootOf(moduleDir);
+    const toolchains = readProjectConfig(root, stackOf(root)).toolchains ?? [];
+    const machine = machineFor(env, TOOLCHAIN_VARIABLES, toolchains);
+    const writable = writableFor(env, moduleDir);
+    const commandFence = {
+        cwd: workdir,
+        read,
+        write,
+        home: env.HOME,
+        tmp: env.TMPDIR,
+        writable,
+        readable: [...machineReadable(), ...machine],
+        platform: process.platform === "win32" ? "win32" : "posix",
+    };
+    const sandboxFence = {
+        cwd: workdir,
+        read: read.filter((dir) => !write.includes(dir)),
+        write,
+        writable,
+        machine,
+        deny: ["code", "tests"].map((part) => join(moduleDir, part, RECORD_FILE)),
+    };
+    const wall = options.wall ?? sandboxAvailable();
+    const wrap = sandboxWrap(wall, sandboxFence);
+    const auditScope = { project, module: moduleDir, write, readOnly: read.filter((dir) => !write.includes(dir)), ...(options.busy !== undefined ? { busy: options.busy } : {}) };
+    const audited = async (work) => {
+        const before = beforeCommand(auditScope);
+        let value;
+        try {
+            value = await work();
+        }
+        catch (error) {
+            // Stopped or failed: what it did is put back all the same.
+            afterCommand(before);
+            throw error;
+        }
+        const result = afterCommand(before);
+        if (result.putBack.length > 0)
+            reportNote(`  an agent's command changed ${result.putBack.join(", ")} - put back`);
+        if (result.left.length > 0)
+            reportNote(`  an agent's command changed ${result.left.join(", ")}, where another pulse is at work - left`);
+        if (result.lost.length > 0)
+            reportNote(`  an agent's command changed ${result.lost.join(", ")}, and it could not be put back`);
+        if (result.conversation.length > 0)
+            reportNote(`  the conversation changed ${result.conversation.join(", ")} while an agent's command ran - left as it is`);
+        const note = auditMessage(result);
+        return { value, ...(note !== undefined ? { note } : {}) };
+    };
+    const description = wall.kind === "none"
+        ? `commands on this machine behind the command check and the audit - no OS sandbox: ${wall.why}`
+        : `commands on this machine behind the command check, ${wall.kind === "seatbelt" ? "Seatbelt" : "bubblewrap"} and the audit`;
+    return {
+        wall,
+        env,
+        description,
+        check: (command) => checkCommand(command, commandFence),
+        wrap,
+        async run(command, runOptions = {}) {
+            const checked = checkCommand(command, commandFence);
+            if (!checked.ok) {
+                reportNote(`  refused an agent's command (${checked.rule}): ${command.length > 120 ? `${command.slice(0, 120)}...` : command}`);
+                const output = `Not run: ${checked.reason}`;
+                runOptions.onData?.(Buffer.from(output));
+                return { exitCode: 126, output };
+            }
+            const { value, note } = await audited(() => runCommand(command, {
+                cwd: workdir,
+                env,
+                wrap,
+                ...(runOptions.timeoutMs !== undefined ? { timeoutMs: runOptions.timeoutMs } : {}),
+                ...(runOptions.signal !== undefined ? { signal: runOptions.signal } : {}),
+                ...(runOptions.onData !== undefined ? { onData: runOptions.onData } : {}),
+                ...(runOptions.timeoutNote !== undefined ? { timeoutNote: runOptions.timeoutNote } : {}),
+            }));
+            if (note === undefined)
+                return value;
+            runOptions.onData?.(Buffer.from(`\n${note}\n`));
+            return { ...value, output: `${value.output}\n${note}\n` };
+        },
+        audited,
+    };
+}

package/dist/regenerate/arbiter.js

@@ -0,0 +1,133 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { ask, BEGIN, createExecutor } from "../pi.js";
+import { confinedTools } from "./confine.js";
+import { REVIEWER_CALLS } from "./conformance-agents.js";
+/**
+ * The arbiter: the third voice in a review. The coding agent writes the tests; the reviewer - exacting,
+ * opinionated, hard to satisfy - sends them back with everything it finds; after the first review that sends
+ * them back, the arbiter weighs what each one found before any of it goes back. It is the distinguished engineer
+ * who balances the trade-offs: the tests have to be good, and time lost chasing perfect ones is lost too. It
+ * upholds a problem when the reviewer is right - a behaviour the spec states is untested, or a test cannot
+ * fail - and dismisses it when it is out of scope or a nitpick. Only what it upholds goes back; when it upholds
+ * nothing, the tests are approved as they are. Read-only, like the reviewer.
+ */
+/**
+ * How many reviews that send the work back go to the agent as they are: every one after them the arbiter weighs
+ * first, and only what it upholds goes back.
+ */
+export const ARBITER_AFTER = 1;
+/**
+ * How many reviews at most. What the last one sends back - weighed by the arbiter - goes to the agent once more, and
+ * then the work goes on without another review, once its tests pass.
+ */
+export const REVIEW_LIMIT = 2;
+export function problemLine(problem) {
+    return `${problem.blocking === true ? "BLOCKING · " : ""}${problem.kind.toUpperCase()} · ${problem.file}${problem.test ? ` · ${problem.test}` : ""}: ${problem.what.trim()}`;
+}
+/** The arbiter's prompt: the spec, the reviews so far, and the latest one's problems, numbered. */
+export function arbiterPrompt(options) {
+    return [
+        `You are the arbiter of ${options.subject}: the distinguished engineer who has the last word on their review.`,
+        `The tests pass. A reviewer - exacting, opinionated, hard to satisfy - has ${options.history.length === 0 ? "sent the work back" : `sent the work back ${options.history.length === 1 ? "once" : `${options.history.length} times`}, and has sent it back again`}. Weigh what it found, as the engineer who balances`,
+        "the trade-offs: the work has to be right and its tests good, and time lost chasing perfect ones is lost too.",
+        "",
+        `The tests and the code are in ${options.read.join(" and ")}.`,
+        "",
+        "For each problem the reviewer raised this time, rule:",
+        ...options.uphold,
+        "- dismiss it when it is out of scope - something the specification does not state for this work, a page or a",
+        "  component only a definition names, how the code works inside rather than what it does - or a nitpick: a",
+        "  test that already tests the behaviour, made a little stronger, another case of one already covered, a",
+        "  matter of style, code written another way than the reviewer would have that does what the specification",
+        "  says. Dismissed, it is let go.",
+        "When you uphold nothing, the work is approved as it is.",
+        "",
+        ...(options.history.length > 0
+            ? [
+                "<the reviews before, oldest first - what each sent back, and the tests were worked on since>",
+                ...options.history.map((problems, index) => `review ${index + 1}:\n${problems.map((problem) => `  - ${problemLine(problem)}`).join("\n")}`),
+                "</the reviews before>",
+                "",
+            ]
+            : []),
+        "<the problems it raised now>",
+        ...options.problems.map((problem, index) => `${index + 1}. ${problemLine(problem)}`),
+        "</the problems it raised now>",
+        "",
+        "<tests added or changed>",
+        options.changed.length > 0 ? options.changed.join("\n") : "(none)",
+        "</tests added or changed>",
+        "",
+        options.spec.trim(),
+        "",
+        ...(options.code !== undefined
+            ? [
+                "<the code this work wrote - a diff from where the work started, new files whole>",
+                options.code.trim() !== "" ? options.code.trim() : "(nothing)",
+                "</the code this work wrote>",
+                "",
+            ]
+            : []),
+        "Then call submit_ruling once, with every problem by its number - upheld, or dismissed - and in a line, why.",
+    ].join("\n");
+}
+/** The arbiter's ruling on the latest review - or nothing, when it gave none: the review then stands. */
+export async function arbitrateReview(options) {
+    let ruling;
+    const submit = defineTool({
+        name: "submit_ruling",
+        label: "Submit the ruling",
+        description: "Rule on every problem the reviewer raised, by its number: upheld, or dismissed, each with why. Call this once.",
+        parameters: Type.Object({
+            rulings: Type.Array(Type.Object({
+                problem: Type.Number({ description: "The problem's number" }),
+                uphold: Type.Boolean({ description: "True: the reviewer is right, the tests are fixed for it. False: dismissed, let go" }),
+                why: Type.String({ description: "In one line, why" }),
+            })),
+        }),
+        async execute(_id, params) {
+            const given = params.rulings;
+            const numbers = new Set(given.map((entry) => entry.problem));
+            const missing = options.problems.map((_, index) => index + 1).filter((number) => !numbers.has(number));
+            if (missing.length > 0) {
+                return { content: [{ type: "text", text: `Rule on every problem: ${missing.join(", ")} ${missing.length === 1 ? "has" : "have"} no ruling.` }], details: {} };
+            }
+            const ruled = given
+                .filter((entry) => options.problems[entry.problem - 1] !== undefined)
+                .map((entry) => ({ problem: options.problems[entry.problem - 1], why: entry.why, uphold: entry.uphold }));
+            ruling = {
+                upheld: ruled.filter((entry) => entry.uphold).map(({ problem, why }) => ({ problem, why })),
+                dismissed: ruled.filter((entry) => !entry.uphold).map(({ problem, why }) => ({ problem, why })),
+            };
+            return { content: [{ type: "text", text: "Recorded." }], details: {}, terminate: true };
+        },
+    });
+    const fence = confinedTools({ workdir: options.workdir, read: options.read, write: [], noBash: true });
+    const session = await createExecutor({
+        cwd: options.workdir,
+        customTools: [submit, ...fence.tools],
+        tools: [...fence.names, "submit_ruling"],
+        model: options.model,
+        label: `${options.label} arbiter`, role: "arbiter",
+        system: fence.note,
+        task: arbiterPrompt(options),
+        budget: { calls: REVIEWER_CALLS, finish: ["submit_ruling"] },
+    });
+    try {
+        await ask(session, BEGIN, options.onDelta);
+        if (ruling === undefined)
+            await ask(session, "You have not called submit_ruling. Call it now, with every problem by its number.", options.onDelta);
+    }
+    finally {
+        session.dispose();
+    }
+    return ruling;
+}
+/** What the arbiter let go, for the working notes' pitfalls. */
+export function dismissedNote(ruling, what) {
+    return `the arbiter let go what the ${what} review raised: ${ruling.dismissed
+        .map((entry) => `${entry.problem.file}${entry.problem.test ? ` ${entry.problem.test}` : ""}: ${entry.problem.what.trim()} - ${entry.why.trim()}`)
+        .join("; ")
+        .slice(0, 600)}`;
+}

package/dist/regenerate/audit.js

@@ -0,0 +1,203 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { writtenByConversation } from "./conversation-writes.js";
+import { isCredentialFile } from "./credentials.js";
+import { RECORD_FILE } from "./records.js";
+/** Folders never looked in: dependencies, build output, caches, histories, turri's scratch. */
+const SKIPPED = new Set([
+    "node_modules", ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".tox", "target", "build",
+    "dist", ".gradle", ".m2", ".cargo", ".next", "coverage", ".git", ".turri", ".plaingit", ".idea", ".vscode",
+]);
+/** A file kept whole before the command - at most this big. */
+const MAX_KEPT = 1024 * 1024;
+function stat(path) {
+    try {
+        const found = statSync(path);
+        return found.isFile() ? { size: found.size, mtimeMs: found.mtimeMs } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every file under `root` that `wanted` takes, skipping the folders that are never looked in. */
+function walk(root, wanted, skip = () => false) {
+    const files = new Map();
+    const visit = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            const path = join(dir, name);
+            let found;
+            try {
+                found = statSync(path);
+            }
+            catch {
+                continue;
+            }
+            if (found.isDirectory()) {
+                if (!SKIPPED.has(name) && !skip(path))
+                    visit(path);
+            }
+            else if (found.isFile() && wanted(path)) {
+                files.set(path, { size: found.size, mtimeMs: found.mtimeMs });
+            }
+        }
+    };
+    if (existsSync(root))
+        visit(root);
+    return files;
+}
+function keep(files) {
+    const kept = new Map();
+    for (const [path, seen] of files) {
+        if (seen.size > MAX_KEPT)
+            continue;
+        try {
+            kept.set(path, readFileSync(path));
+        }
+        catch {
+            /* unreadable: nothing to put back from */
+        }
+    }
+    return kept;
+}
+function within(path, root) {
+    return path === root || path.startsWith(root + sep);
+}
+/** What the project's own files are that no agent changes: specs, config, testing scripts, credentials. */
+function projectFile(project, path) {
+    const name = basename(path);
+    if (isCredentialFile(path))
+        return true;
+    if (name.endsWith(".plain"))
+        return true;
+    if (dirname(path) === project && /^config(\.[^.]+)?\.ya?ml$/.test(name))
+        return true;
+    if (relative(project, path).split(sep)[0] === "test_scripts")
+        return true;
+    return dirname(path) === project && /^(run_|prepare_environment).*\.sh$/.test(name);
+}
+/** Take what the audit compares against, before a command runs. */
+export function beforeCommand(scope) {
+    const at = Date.now();
+    const modulesRoot = join(scope.project, "plain_modules");
+    const trees = [];
+    // The project's own files, outside plain_modules.
+    const own = walk(scope.project, (path) => projectFile(scope.project, path), (dir) => dir === modulesRoot);
+    trees.push({ root: scope.project, files: own, kept: keep(own), from: "copy" });
+    // In what the role writes: only the record and credential files are watched.
+    for (const root of scope.write) {
+        const watched = walk(root, (path) => basename(path) === RECORD_FILE || isCredentialFile(path));
+        trees.push({ root, files: watched, kept: keep(watched), from: "copy", watchOnly: true });
+    }
+    // What the role only reads, and the parts of its own module it does not write at all: all of it, from a copy - they may
+    // hold this pulse's work, not yet committed.
+    const ownParts = ["code", "tests"].map((part) => join(scope.module, part)).filter((part) => existsSync(part) && !scope.write.includes(part) && !scope.readOnly.includes(part));
+    for (const root of [...scope.readOnly, ...ownParts]) {
+        const all = walk(root, () => true);
+        trees.push({ root, files: all, kept: keep(all), from: "copy" });
+    }
+    // The module's lineage: its refs and settings - the objects are only ever added to.
+    const lineage = join(scope.module, ".plaingit");
+    const refs = walk(lineage, (path) => !within(path, join(lineage, "objects")) && !within(path, join(lineage, "logs")));
+    trees.push({ root: lineage, files: refs, kept: keep(refs), from: "copy" });
+    // The other modules, put back from their last commit.
+    if (existsSync(modulesRoot)) {
+        for (const name of readdirSync(modulesRoot)) {
+            const other = join(modulesRoot, name);
+            if (name.startsWith(".") || other === scope.module || !existsSync(join(other, ".plaingit")))
+                continue;
+            const files = walk(other, () => true);
+            trees.push({ root: other, files, from: { lineage: other }, busy: scope.busy?.(other) === true });
+        }
+    }
+    return { scope, trees, at };
+}
+/** The file's last committed content in a module's lineage, or nothing when it was not committed. */
+function committed(moduleDir, path) {
+    const rel = relative(moduleDir, path).split(sep).join("/");
+    const run = spawnSync("git", ["--git-dir", join(moduleDir, ".plaingit"), "show", `HEAD:${rel}`], { maxBuffer: 256 * 1024 * 1024 });
+    return run.status === 0 ? run.stdout : undefined;
+}
+function put(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+}
+/** After the command: put back what it changed that its role may not, and say what. */
+export function afterCommand(snapshot) {
+    const { scope } = snapshot;
+    const result = { putBack: [], left: [], lost: [], conversation: [] };
+    const shown = (path) => relative(scope.project, path).split(sep).join("/");
+    const modulesRoot = join(scope.project, "plain_modules");
+    for (const tree of snapshot.trees) {
+        const isLineage = tree.root === join(scope.module, ".plaingit");
+        const after = tree.root === scope.project
+            ? walk(scope.project, (path) => projectFile(scope.project, path), (dir) => dir === modulesRoot)
+            : tree.watchOnly === true
+                ? walk(tree.root, (path) => basename(path) === RECORD_FILE || isCredentialFile(path))
+                : isLineage
+                    ? walk(tree.root, (path) => !within(path, join(tree.root, "objects")) && !within(path, join(tree.root, "logs")))
+                    : walk(tree.root, () => true);
+        const changed = [];
+        for (const [path, seen] of after) {
+            const was = tree.files.get(path);
+            if (was === undefined)
+                changed.push(path);
+            else if (was.size !== seen.size || was.mtimeMs !== seen.mtimeMs) {
+                const kept = tree.kept?.get(path);
+                // Touched but the same: nothing to put back.
+                if (kept !== undefined && readFileSync(path).equals(kept))
+                    continue;
+                changed.push(path);
+            }
+        }
+        for (const path of tree.files.keys())
+            if (!after.has(path))
+                changed.push(path);
+        // What the conversation wrote meanwhile is its own: left as it is.
+        const mine = changed.filter((path) => writtenByConversation(path, snapshot.at));
+        result.conversation.push(...mine.map(shown));
+        changed.splice(0, changed.length, ...changed.filter((path) => !mine.includes(path)));
+        if (changed.length === 0)
+            continue;
+        if (tree.busy === true) {
+            result.left.push(...changed.map(shown));
+            continue;
+        }
+        for (const path of changed) {
+            const existed = tree.files.has(path);
+            if (!existed) {
+                rmSync(path, { force: true });
+                result.putBack.push(shown(path));
+                continue;
+            }
+            const content = tree.from === "copy" ? tree.kept?.get(path) : committed(tree.from.lineage, path);
+            if (content === undefined) {
+                result.lost.push(shown(path));
+                continue;
+            }
+            put(path, content);
+            result.putBack.push(shown(path));
+        }
+    }
+    return result;
+}
+/** What the agent is told in its command's result, or nothing when the audit put nothing back. */
+export function auditMessage(result) {
+    if (result.putBack.length === 0 && result.lost.length === 0)
+        return undefined;
+    const list = (paths) => (paths.length > 10 ? `${paths.slice(0, 10).join(", ")} and ${paths.length - 10} more` : paths.join(", "));
+    const parts = [];
+    if (result.putBack.length > 0)
+        parts.push(`turri put back ${list(result.putBack)} as it was before this command`);
+    if (result.lost.length > 0)
+        parts.push(`${list(result.lost)} changed and could not be put back`);
+    return (`[${parts.join("; ")}: outside what you may change. Your own work is kept. What you need from there is in your ` +
+        "prompt; leave it as it is.]");
+}

package/dist/regenerate/cases.js

@@ -0,0 +1,83 @@
+/**
+ * What a job's agents are told to do, by its cases - see docs/regenerating.md. A job's functional specs each fall in
+ * one case - fresh, added, changed (patched), regenerated again, taken out - or, with none touched, the job is
+ * mechanical. The coding agent and the conformance agent are each told, case by case, exactly what to do with the
+ * functional specs of that case; their reviewers, what to hold each to. A job holding several cases gets a section
+ * for each.
+ */
+/** Functional specs, each by its number and - each module numbering its own from 1 - the module it belongs to. */
+const named = (specs) => specs.map((spec) => `fs ${spec.frid}${spec.module !== undefined ? ` of module \`${spec.module}\`` : ""} (${spec.text})`).join("; ");
+/** What the coding agent does, case by case. */
+export function codeCasesBlock(cases) {
+    const lines = [];
+    if (cases.fresh) {
+        lines.push("- Nothing is built yet: set the project up first - its layout, its dependency manifest, and its unit tests", "  where the unit testing script runs them - then build what follows, with its unit tests.");
+    }
+    if (cases.add.length > 0)
+        lines.push(`- New - build each, and write its unit tests: ${named(cases.add)}.`);
+    if (cases.patch.length > 0) {
+        lines.push(`- Changed - its text, or a concept it uses: ${named(cases.patch)}.`, "  Its code and unit tests exist: change them to match what it says now. Do not build it again from scratch.");
+    }
+    if (cases.again.length > 0) {
+        lines.push(`- Regenerated again - its code and unit tests are built, and are to be regenerated again: ${named(cases.again)}.`, "  Replace its implementation: rewrite it, or take it out and build it anew - made better, and doing exactly what", "  the specification says now. Take out what the new code replaces: no second implementation beside the old one,", "  nothing of the old left unused. What the rest of the code uses from it keeps working. Its unit tests may be", "  rewritten, to test what the specification says.");
+    }
+    if (cases.delete.length > 0) {
+        lines.push(`- Taken out - remove its code, and the unit tests only it had, where nothing that remains needs them: ${named(cases.delete)}.`);
+    }
+    if (cases.mechanical) {
+        lines.push("- No functional spec is touched: the change is to implementation reqs, or definitions no functional spec uses.", "  Adapt the code to it. Write no new tests. An existing test may change only mechanically - an import, a", "  fixture, its setup - never what it asserts. Every test must still pass.");
+    }
+    return lines;
+}
+/** What the unit reviewer holds the work to, case by case - in place of its checks, when the job is mechanical. */
+export function codeReviewCasesBlock(cases) {
+    if (cases.mechanical) {
+        return [
+            "This work touches no functional spec - only implementation reqs, or definitions none uses. Review only that",
+            "the code keeps to them and still does what it did, and that no test was removed or weakened: an assertion",
+            "loosened or taken out, a case dropped, a test skipped or deleted. A test may change mechanically - an import, a",
+            "fixture, its setup. Raise no missing test: this work adds no behaviour to test.",
+        ];
+    }
+    return [
+        "What this work does, by functional spec - hold each part to its own:",
+        ...(cases.add.length > 0 ? [`- New: ${named(cases.add)} - implemented, and tested as below.`] : []),
+        ...(cases.patch.length > 0 ? [`- Changed: ${named(cases.patch)} - the code and its tests changed to match it now, not left as they were.`] : []),
+        ...(cases.again.length > 0
+            ? [
+                `- Regenerated again: ${named(cases.again)} - its implementation replaced, not patched beside the old one: nothing of what it`,
+                "  replaced left behind or duplicated, it does what the specification says, what the rest of the code uses from it",
+                "  still works, and its unit tests test the specification.",
+            ]
+            : []),
+        ...(cases.delete.length > 0 ? [`- Taken out: ${named(cases.delete)} - its code and the tests only it had removed, and nothing else.`] : []),
+    ];
+}
+/** What the conformance agent does, case by case. */
+export function conformanceCasesBlock(cases) {
+    const lines = [];
+    if (cases.fresh) {
+        lines.push("- There are no conformance tests yet: set the tests folder up first - the tests' own build and layout, so the", "  conformance testing script, which brings the tests together with the code, runs them - then write what follows.");
+    }
+    if (cases.add.length > 0)
+        lines.push(`- New - write its conformance tests: ${named(cases.add)}.`);
+    if (cases.patch.length > 0) {
+        lines.push(`- Changed - its text, its acceptance tests, or a concept it uses: ${named(cases.patch)}.`, "  Its conformance tests exist: rewrite them to what it says now. The tests of everything else stay as they are.");
+    }
+    if (cases.delete.length > 0)
+        lines.push(`- Taken out - remove its conformance tests: ${named(cases.delete)}.`);
+    if (cases.mechanical) {
+        lines.push("- No functional spec is touched: the change is to the test reqs, or to definitions or implementation reqs alone.", "  Adapt the existing tests to it. Write no new tests. A test may change only mechanically - how it is built,", "  started or reaches the software - never what it asserts. Every test must still pass.");
+    }
+    return lines;
+}
+/** What the conformance test reviewer holds the tests to, when the job is mechanical: in place of its checks. */
+export function conformanceReviewCasesBlock(cases) {
+    if (!cases.mechanical)
+        return [];
+    return [
+        "This work touches no functional spec - only the test reqs, or definitions or implementation reqs alone. Review",
+        "only that the tests follow them, and that no test was removed or weakened: an assertion loosened or taken out, a",
+        "case dropped, a test skipped or deleted. A test may change mechanically. Raise no missing test.",
+    ];
+}

package/dist/regenerate/change-view.js

@@ -0,0 +1,102 @@
+import { ACCEPTANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS } from "../plain/spec.js";
+import { resourceDiff } from "./spec-steps.js";
+/**
+ * A job's change as its agent is given it, for the panels: the same items `describeSpecChange` writes into
+ * `<spec change>` - what the job's functional specs use, from the module's own file and from the files it
+ * imports and requires alike - laid out as a diff the panels already show (`diff-view.ts`). Each section is
+ * a block under its header, each item as its file writes it - its markdown, its acceptance tests indented
+ * under it - so placed in the .plain files (`locateDiffLines`) every line is shown in the file it is written
+ * in, with its line there: split by file and by block. A text diff of the module's file would show other
+ * things - the lines around a change, the items no job takes yet - and leave out what an import adds.
+ */
+/** The sections in the order the agent is given them, then any other. */
+const ORDER = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, FUNCTIONAL_REQUIREMENTS];
+/** An item's lines as a .plain file writes them: its markdown, then its acceptance tests indented under it. */
+function itemLines(serialized) {
+    if (serialized === undefined)
+        return [];
+    let item;
+    try {
+        item = JSON.parse(serialized);
+    }
+    catch {
+        return serialized.split("\n");
+    }
+    if (typeof item === "string")
+        return item.split("\n");
+    const { markdown, [ACCEPTANCE_TESTS]: tests } = (item ?? {});
+    const lines = (markdown ?? JSON.stringify(item)).split("\n");
+    if (Array.isArray(tests) && tests.length > 0) {
+        lines.push("", "    ***acceptance tests***", "");
+        for (const test of tests) {
+            const text = typeof test === "string" ? test : (test.markdown ?? JSON.stringify(test));
+            lines.push(...text.split("\n").map((line) => `    ${line}`));
+        }
+    }
+    return lines;
+}
+/**
+ * `changes` as a diff of `file` - the module's .plain file, which the diff names - section by section: a removed
+ * item's lines taken out, an added one's put in, a changed one's both. A change to what a linked file holds
+ * follows, as the step's own diff has it.
+ */
+export function changeDiff(changes, file) {
+    return laidOut(changes, file).diff;
+}
+/**
+ * `changeDiff`, each section's items in the order they are written - by file, then by line - rather than in the
+ * order the spec is read in, which puts a concept after those it uses: placed by `locate`, as the panels place it.
+ */
+export function changeDiffInFiles(changes, file, locate) {
+    const first = laidOut(changes, file);
+    const where = locate(first.diff);
+    const placeOf = (change) => {
+        const at = where[first.starts.get(change) ?? -1];
+        return at === undefined ? undefined : { file: at.file, line: at.line };
+    };
+    const ordered = [...changes].sort((a, b) => {
+        // Each section is laid out on its own: between two, any order that holds will do.
+        if (a.section !== b.section)
+            return a.section < b.section ? -1 : 1;
+        const [x, y] = [placeOf(a), placeOf(b)];
+        if (x === undefined || y === undefined)
+            return a.position - b.position;
+        return x.file === y.file ? x.line - y.line : (x.file === file ? -1 : y.file === file ? 1 : x.file.localeCompare(y.file));
+    });
+    const diff = laidOut(ordered, file, true).diff;
+    return { diff, where: locate(diff) };
+}
+/** The diff, and the line each change starts on in it. `asGiven`: each section's items in the order given. */
+function laidOut(changes, file, asGiven = false) {
+    const starts = new Map();
+    const sections = [...new Set(changes.map((change) => change.section))].sort((a, b) => (ORDER.indexOf(a) === -1 ? ORDER.length : ORDER.indexOf(a)) - (ORDER.indexOf(b) === -1 ? ORDER.length : ORDER.indexOf(b)));
+    const lines = [`diff --git a/${file} b/${file}`, `--- a/${file}`, `+++ b/${file}`];
+    for (const section of sections) {
+        const own = changes.filter((change) => change.section === section);
+        if (!asGiven)
+            own.sort((a, b) => a.position - b.position);
+        const body = [];
+        // Where this section's lines start in the diff: after the lines so far, its hunk header and its section header.
+        const offset = lines.length + 2;
+        for (const change of own) {
+            const before = change.kind === "add" ? [] : itemLines(change.before);
+            const after = change.kind === "remove" ? [] : itemLines(change.after);
+            // Where it is found: its first line now, or - removed - its first line as it was.
+            starts.set(change, offset + body.length + (change.kind === "change" && after.length > 0 ? before.length : 0));
+            // Only what a file it links holds changed: the item as it is, the file's change after the spec's.
+            if (change.kind === "change" && before.join("\n") === after.join("\n")) {
+                body.push(...after.map((line) => ` ${line}`));
+                continue;
+            }
+            body.push(...before.map((line) => `-${line}`), ...after.map((line) => `+${line}`));
+        }
+        if (body.length === 0)
+            continue;
+        lines.push("@@ @@", ` ***${section}***`, ...body);
+    }
+    return { diff: `${lines.join("\n")}\n${resourceDiff(changes, file)}`, starts };
+}
+/** The changes a job's agent works from: a code job's leave out the test reqs, which are the conformance job's. */
+export function agentChanges(changes, track) {
+    return track === "conformance" ? changes : changes.filter((change) => change.section !== TEST_REQUIREMENTS);
+}