@turri-dev/cli 0.1.27 → 0.2.0

package/dist/run-report.js

@@ -13,7 +13,7 @@ import { firstRegeneration } from "./regenerate/jobs.js";
  * pulse failed, a crash, a signal. A process killed outright (SIGKILL) leaves the one written as the last pulse ended.
  * Each write is atomic: the file is written beside it and renamed over it, so a reader never sees half of one.
  */
-export const REPORT_SCHEMA_VERSION = 1;
+export const REPORT_SCHEMA_VERSION = 2;
 const SIGNALS = { 129: "SIGHUP", 130: "SIGINT", 143: "SIGTERM" };
 const emptyTotals = () => ({
     input_tokens: 0,
@@ -229,13 +229,15 @@ export function startRunReport(options) {
         const modules = counts.flatMap((chain) => chain.modules.map((module) => ({
             module: module.module,
             specified: module.specified,
+            with_scenarios: module.withScenarios,
             completed: module.completed,
             conformance_tested: module.conformanceTested,
-            incomplete_frids: module.incomplete,
+            incomplete_func_ids: module.incomplete,
         })));
         return {
             total: {
                 specified: modules.reduce((sum, module) => sum + module.specified, 0),
+                with_scenarios: modules.reduce((sum, module) => sum + module.with_scenarios, 0),
                 completed: modules.reduce((sum, module) => sum + module.completed, 0),
                 conformance_tested: modules.reduce((sum, module) => sum + module.conformance_tested, 0),
             },
@@ -268,7 +270,6 @@ export function startRunReport(options) {
             spec_file: resolve(options.specFile),
             project_dir: projectRoot,
             build_dir: options.buildDir !== undefined ? resolve(options.buildDir) : null,
-            conformance_tests: options.conformanceTests,
             review: options.review ?? null,
             mutation_testing: options.mutationTesting ?? null,
             models: {

package/dist/self-invocation.d.ts

@@ -10,7 +10,7 @@
  */
 /**
  * What a shell command would run of turri or pi itself, if anything: the subcommand,
- * or "pi" for another pi. `turri validate`, `drift` and `lineage` are not in it - they start no
+ * or "pi" for another pi. `turri parse`, `drift` and `lineage` are not in it - they start no
  * agent - and neither are setup and doctor.
  */
 export declare function selfInvocation(command: string): string | undefined;

package/dist/self-invocation.js

@@ -39,7 +39,7 @@ const ENTRY = {
 const AT_COMMAND = String.raw `(?:^|[\s;&|()\x60$])`;
 /**
  * What a shell command would run of turri or pi itself, if anything: the subcommand,
- * or "pi" for another pi. `turri validate`, `drift` and `lineage` are not in it - they start no
+ * or "pi" for another pi. `turri parse`, `drift` and `lineage` are not in it - they start no
  * agent - and neither are setup and doctor.
  */
 export function selfInvocation(command) {

package/dist/sentinel.js

@@ -244,7 +244,7 @@ export function sentinelBrief(job, context) {
 // ---------------------------------------------------------------------------------------------
 // Its tools.
 /** The tools the sentinel's agent may call: what reads, its notices and its guidance - and what a host gives it. */
-export const SENTINEL_TOOLS = ["read", "ls", "grep", "find", "bash", "read_output", "ledger", "pulses", "diagnose", "validate", "doctor", "web_search", "web_fetch", "notify_person", "conclude", "keep_guidance"];
+export const SENTINEL_TOOLS = ["read", "ls", "grep", "find", "bash", "read_output", "ledger", "pulses", "diagnose", "parse", "doctor", "web_search", "web_fetch", "notify_person", "conclude", "keep_guidance"];
 /**
  * Its file tools and shell: the whole project to read and nothing to write - the shell behind the command check, the OS
  * sandbox where one is up, and the audit, with the network open. Its home and temporary folder are its own, in the

package/dist/setup.d.ts

@@ -55,6 +55,16 @@ export interface DoctorOptions {
  * nothing, so a host can show them in its own way; `turri doctor` prints the same.
  */
 export declare function doctor(options?: DoctorOptions): Promise<Check[]>;
+/**
+ * The base folders the project's config names - its own, and each stack's - each there with its files, or not: a codebase
+ * that requires nothing starts from one, and its first pulse stops when it is not there. Nothing when none is named.
+ */
+export declare function checkBaseFolders(project: string): Check[];
+/**
+ * The AWS region a project's Bedrock models are called in, when it uses any: turri's, the person's or the profile's - and
+ * what is wrong with it, when the models need two, or the person's is not in their geography. Nothing when it uses none.
+ */
+export declare function checkBedrockRegion(project: string, env?: NodeJS.ProcessEnv): Check[];
 /** What the checks add up to: whether turri can run here, and a line saying so - with its marks, uncoloured. */
 export declare function verdictOf(checks: Check[]): {
     ready: boolean;

package/dist/setup.js

@@ -1,14 +1,16 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, rmSync } from "node:fs";
-import { join, relative } from "node:path";
+import { existsSync, rmSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { ModelRegistry, ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { globalExtensionFile, MIN_NODE, nodeVersionOk, PACKAGE_ROOT, turriOnPath } from "./environment.js";
 import { sandboxAvailable, sandboxWith } from "./regenerate/os-sandbox.js";
 import { findTestScripts, onThisMachine } from "./regenerate/test-scripts.js";
 import { configKeyOptions, parseArgs } from "./cli-options.js";
-import { hasProjectConfig, readProjectConfig, stackOf } from "./config.js";
+import { CONFIG_FILE, hasProjectConfig, readProjectConfig, stackConfigFile, stackOf, stacksOf } from "./config.js";
 import { checkModels, modelsInUse, piModelAccess } from "./model-check.js";
+import { bedrockRegionFor, describeBedrockRegion, regionInGeography } from "./bedrock-region.js";
+import { baseFiles } from "./regenerate/base-folder.js";
 import { brand } from "./brand.js";
 import { readScript, scriptAgainstMachine, stackOnMachine } from "./stack.js";
 const MARK = { ok: "✓", missing: "✗", limited: "!", info: "·" };
@@ -156,7 +158,8 @@ export async function checkProjectModels(project, access) {
     }
     let verdicts;
     try {
-        verdicts = await checkModels(used, access ?? (await piModelAccess()));
+        const region = describeBedrockRegion(bedrockRegionFor(project));
+        verdicts = await checkModels(used, access ?? (await piModelAccess()), region !== undefined ? { bedrockRegion: region } : {});
     }
     catch (error) {
         return [{ level: "missing", name: "Models", detail: `pi's models could not be read: ${error instanceof Error ? error.message : String(error)}` }];
@@ -194,10 +197,55 @@ async function allChecks(options) {
         return checks;
     if (hasProjectConfig(project) || existsSync(join(project, "plain_modules")))
         checks.push(...checkProject(project, { has: (command) => onThisMachine(command, env) !== undefined }));
+    if (hasProjectConfig(project))
+        checks.push(...checkBedrockRegion(project, env), ...checkBaseFolders(project));
     if (asksModels(options))
         checks.push(...(await checkProjectModels(project)));
     return checks;
 }
+/**
+ * The base folders the project's config names - its own, and each stack's - each there with its files, or not: a codebase
+ * that requires nothing starts from one, and its first pulse stops when it is not there. Nothing when none is named.
+ */
+export function checkBaseFolders(project) {
+    const named = new Map();
+    for (const [stack, config] of [[undefined, readProjectConfig(project)], ...stacksOf(project).map((stack) => [stack, readProjectConfig(project, stack)])]) {
+        if (config.baseFolder === undefined)
+            continue;
+        named.set(config.baseFolder, [...(named.get(config.baseFolder) ?? []), stack === undefined ? CONFIG_FILE : stackConfigFile(stack)]);
+    }
+    return [...named].map(([folder, files]) => {
+        const path = resolve(project, folder);
+        const name = `base folder ${folder}`;
+        if (!existsSync(path) || !statSync(path).isDirectory()) {
+            return { level: "missing", name, detail: `${existsSync(path) ? "not a folder" : "not there"} - named in ${files.join(", ")}`, fix: "make the folder, or name the right one in base-folder:, by path from the project's folder" };
+        }
+        const count = baseFiles(path).length;
+        return { level: "ok", name, detail: `${count} file${count === 1 ? "" : "s"} to start a codebase from - named in ${files.join(", ")}` };
+    });
+}
+/**
+ * The AWS region a project's Bedrock models are called in, when it uses any: turri's, the person's or the profile's - and
+ * what is wrong with it, when the models need two, or the person's is not in their geography. Nothing when it uses none.
+ */
+export function checkBedrockRegion(project, env = process.env) {
+    let decided;
+    try {
+        decided = bedrockRegionFor(project, { env });
+    }
+    catch {
+        return [];
+    }
+    const line = describeBedrockRegion(decided);
+    if (decided.models.length === 0 || line === undefined)
+        return [];
+    const outside = decided.source === "set" && decided.needs !== undefined && decided.region !== undefined && !regionInGeography(decided.region, decided.needs.geography);
+    if (decided.conflict !== undefined)
+        return [{ level: "missing", name: "AWS region", detail: "the Bedrock models need two regions", more: [line] }];
+    if (outside)
+        return [{ level: "missing", name: "AWS region", detail: `${decided.region}, which does not serve ${decided.needs.geography}'s models`, more: [line] }];
+    return [{ level: "ok", name: "AWS region", detail: line }];
+}
 /** What the checks add up to: whether turri can run here, and a line saying so - with its marks, uncoloured. */
 export function verdictOf(checks) {
     const missing = checks.filter((check) => check.level === "missing").length;

package/dist/skill.d.ts

@@ -90,6 +90,16 @@ export interface Skill {
      * (`metadata.command-only: true`): cultivate runs it only when the person has just typed its command.
      */
     commandOnly: boolean;
+    /**
+     * Run in the background (`metadata.background: true`): in the chat, cultivate starts it and returns at once, and what
+     * it did comes back to the chat once the chat is idle. Nobody is asked anything while it runs.
+     */
+    background: boolean;
+    /**
+     * The model it runs on (`metadata.model`): `coding`, the coding model of the module it is for. Omitted: the chat's
+     * model, or `harness-model` from the command line.
+     */
+    model?: "coding";
 }
 export declare function loadSkill(skillDir: string): Skill;
 export declare function readRubric(skill: Skill, review: {

package/dist/skill.js

@@ -121,6 +121,10 @@ export function loadSkill(skillDir) {
             throw new Error(`${name}: gate references unknown step '${stepName}'`);
         }
     }
+    const rawModel = data.metadata?.model;
+    if (rawModel !== undefined && rawModel !== "coding")
+        throw new Error(`${name}: 'metadata.model' is coding, or left out for the chat's model`);
+    const model = rawModel === "coding" ? "coding" : undefined;
     return {
         name,
         description,
@@ -132,6 +136,8 @@ export function loadSkill(skillDir) {
         questioning: capped,
         diffPerAnswer,
         commandOnly: data.metadata?.["command-only"] === true,
+        background: data.metadata?.background === true,
+        ...(model !== undefined ? { model } : {}),
     };
 }
 export function readRubric(skill, review) {

package/dist/skills.js

@@ -63,7 +63,9 @@ export function catalogueLine(skill) {
     const whose = skill.origin === "turri" ? "" : ` (this project's, ${skill.origin.project})`;
     // One the person starts themselves - typed, or picked among the options the model offers: never run unasked.
     const byCommand = skill.commandOnly ? ` Started only by the person, with /${skill.name} or by picking it when you offer it with ask_user: never run it unasked.` : "";
-    return `- ${skill.name}${whose}: ${skill.description}${byCommand}`;
+    // One that runs in the background: the chat goes on, and its end comes back to it.
+    const background = skill.background ? " Runs in the background: cultivate returns at once, and its end comes back to this chat - pass plainFile, the module it is for." : "";
+    return `- ${skill.name}${whose}: ${skill.description}${byCommand}${background}`;
 }
 /** What is said under the list about the skills it leaves out. */
 export function leftOutNote(catalogue) {

package/dist/spec-tools.js

@@ -1,11 +1,10 @@
-import { basename, relative, resolve } from "node:path";
+import { resolve } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { plainFileParser } from "./plain/parser.js";
-import { importingModules, isImportModule } from "./regenerate/requires.js";
-import { resolveTemplateDirs } from "./regenerate/paths.js";
+import { advisingNote } from "./advisor-chat.js";
+import { checkTouchedPlain, formatCheckResults } from "./plain/check.js";
 import { applySpecDiff, plainFilesOf, revertSpecDiff } from "./regenerate/regenerate.js";
-import { MissingFunctionalitiesError } from "./plain/errors.js";
+import { refuseTestPlainFile } from "./test-plain-files.js";
 import { describeModules } from "./regenerate/loop.js";
 import { reviewNote } from "./tools.js";
 import { STACK_PARAM, stacklessBuild, withCallStack } from "./loop-tools.js";
@@ -33,10 +32,13 @@ export function createSpecDiffTools(options) {
         description: "Apply a change to the ***plain specs, given as a git diff of the .plain files, and start building it in " +
             "the background. The diff is applied with git; if the specs no longer parse, it is undone and nothing is " +
             "built. Any section may change - definitions, implementation reqs, functional specs, added, changed or removed - and " +
-            "every change is built, whatever it touches.",
+            "every change is built, whatever it touches. A diff may touch test plain files too - tests/<module>/<func-id>.plain, " +
+            "a functional spec's conformance and acceptance scenarios. A functional spec with none has no test plain file: " +
+            "write one only to give it scenarios.",
         promptSnippet: "apply a git diff of the .plain specs and start building it",
         promptGuidelines: [
             "Every change to a .plain file in the product phase goes through change_plain, as a git diff with paths relative to the project root. It writes the change and starts its build in one step.",
+            "A functional spec is a `# <func-id>` heading and its text. One with scenarios has a test plain file, tests/<module>/<func-id>.plain: its `module:` and `func_id:`, then `***conformance tests***` and `***acceptance tests***`, each scenario a `# <scenario-id>` heading and its text - a section only when it has a scenario, an empty one being a syntax error. One with no scenarios has no test plain file. plain_file stays the module's .plain file when the diff touches only its test plain files.",
             skillPaced
                 ? "One change per answer, and a new one only after the user has answered a question about it. Set fixes_earlier to correct something already written."
                 : "Write the changes one after another, on your own: no answer is needed between them, and none is asked for. Set fixes_earlier to correct something already written.",
@@ -62,31 +64,17 @@ export function createSpecDiffTools(options) {
             const touched = plainFilesOf(params.diff);
             if (touched.length === 0)
                 throw new Error("The diff changes no .plain file. Nothing was written.");
+            refuseTestPlainFile(resolve(cwd, params.plain_file));
             const result = applySpecDiff(params.diff, cwd);
-            // A change that breaks a spec is not written at all, so nothing is ever built from a
-            // file that cannot be parsed. A module with no functional specs yet is not broken. An import
-            // module - definitions only, say - is not a module of its own: it is parsed as the modules
-            // that import it read it, the one the change is built for among them.
-            const toParse = [
-                ...new Set([params.plain_file, ...touched].flatMap((file) => {
-                    const path = resolve(cwd, file);
-                    const importing = isImportModule(path) ? importingModules(path) : [];
-                    return importing.length > 0 ? importing : [path];
-                })),
-            ];
-            for (const path of toParse) {
-                const file = relative(cwd, path);
-                try {
-                    plainFileParser(basename(path), resolveTemplateDirs(path), { allowNoFunctionalities: true });
-                }
-                catch (error) {
-                    if (error instanceof MissingFunctionalitiesError)
-                        continue;
-                    if (result === "applied")
-                        revertSpecDiff(params.diff, cwd);
-                    const reason = error instanceof Error ? error.message : String(error);
-                    throw new Error(`Nothing was written: with this change ${file} no longer parses. ${reason}`);
-                }
+            // A change that breaks a spec is not written at all, so nothing is ever built from a file that cannot be parsed:
+            // each module it touched is parsed with its test plain files - an import module as the modules that import it
+            // read it, a test plain file as its module - as parse reads them. A module with no functional specs yet is
+            // not broken.
+            const failed = checkTouchedPlain([params.plain_file, ...touched].map((file) => resolve(cwd, file))).filter((check) => !check.ok);
+            if (failed.length > 0) {
+                if (result === "applied")
+                    revertSpecDiff(params.diff, cwd);
+                throw new Error(`Nothing was written: with this change the ***plain no longer checks.\n${formatCheckResults(failed)}`);
             }
             if (params.fixes_earlier !== true)
                 answeredSinceLastDiff = false;
@@ -118,8 +106,10 @@ export function createSpecDiffTools(options) {
                         ? "Carry on: write the next change you decided yourself, or ask the next question - every answer is written as a change before the question after it."
                         : "Write the next change now, without stopping to ask: this skill goes on until everything it is to write is written.",
             ];
+            // The functional specs the test advisor took up, for the agent to say so rather than offer their scenarios.
+            const advising = advisingNote(loop, building);
             return {
-                content: [{ type: "text", text: lines.join(" ") + reviewNote(liveReview) }],
+                content: [{ type: "text", text: lines.join(" ") + reviewNote(liveReview) + (advising !== "" ? `\n\n${advising}` : "") }],
                 details: { jobIds: statuses.flatMap((status) => (status.running !== undefined ? [status.running.jobId] : [])), files: touched },
             };
         },

package/dist/test-plain-files.d.ts

@@ -0,0 +1,41 @@
+/** A module's test plain files: every .plain file under `<test-dir>/<module>/`, sorted, as absolute paths. */
+export declare function testPlainFilesOf(plainFile: string): string[];
+/** The modules of a project, by name: the .plain files in its folder and its `template/` folder. */
+export declare function projectModules(projectDir: string): Map<string, string>;
+/** What a path under a project's test folder is: the test folder itself, or a module's folder or file in it. */
+export interface TestPlace {
+    projectDir: string;
+    testDir: string;
+    /** The module whose folder it is in - `tests/<module>/...` - when it is in one. */
+    folderModule?: string;
+    /** For a file: the `module:` and `func_id:` it names. */
+    module?: string;
+    funcId?: string;
+    directory: boolean;
+}
+/**
+ * Where a path is, when it is a test plain file - under the project's test folder, or a .plain file whose frontmatter
+ * binds it with `module:` and `func_id:` - or the test folder, or a folder in it. Undefined for anything else.
+ */
+export declare function testPlaceOf(path: string): TestPlace | undefined;
+/**
+ * Why a tool refuses a path in place of a module: it is a test plain file - naming its module and the functional
+ * spec it binds to - or a test folder. Undefined for a path that is not one.
+ */
+export declare function testPlainFileRefusal(path: string): string | undefined;
+/** Refuse a path that is a test plain file or a test folder, as every tool that takes a module does. */
+export declare function refuseTestPlainFile(path: string): void;
+/**
+ * The test plain files of a project that are not where they belong, each with where it does: a file outside any
+ * module's folder, in the folder of a module there is not, or in a module's folder its `module:` does not name. Strays
+ * are not read when a module is parsed; this is where they are found.
+ */
+export declare function strayTestPlainFiles(projectDir: string): Array<{
+    file: string;
+    problem: string;
+}>;
+/** The module a test plain file belongs to, by its folder, and that module's .plain file when the project has one. */
+export declare function moduleOfTestPlainFile(path: string): {
+    module: string;
+    plainFile: string | undefined;
+} | undefined;

package/dist/test-plain-files.js

@@ -0,0 +1,177 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { DEFAULT_TEST_DIR, testDirOf } from "./config.js";
+import { PLAIN_SOURCE_FILE_EXTENSION } from "./plain/parser.js";
+import { FUNC_ID_KEY, loadFrontmatter, MODULE_KEY } from "./plain/test-plain-file.js";
+import { isProjectDir, projectDirOf } from "./regenerate/paths.js";
+/**
+ * Where a project's test plain files are, and what each belongs to: `<test-dir>/<module>/`, every `.plain` file in it
+ * a test plain file of that module - its functional specs' conformance and acceptance scenarios. turri finds modules
+ * only in the project's folder and its `template/` folder, so a test plain file is never taken for a module; and no
+ * tool takes one in place of its module.
+ */
+/** Every .plain file under a folder, at any depth, sorted by path; none when it is not there. */
+function plainFilesUnder(dir) {
+    let names;
+    try {
+        names = readdirSync(dir).sort();
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names) {
+        const path = join(dir, name);
+        let directory = false;
+        try {
+            directory = statSync(path).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (directory)
+            found.push(...plainFilesUnder(path));
+        else if (name.endsWith(PLAIN_SOURCE_FILE_EXTENSION))
+            found.push(path);
+    }
+    return found;
+}
+/** A module's test plain files: every .plain file under `<test-dir>/<module>/`, sorted, as absolute paths. */
+export function testPlainFilesOf(plainFile) {
+    return plainFilesUnder(join(testDirOf(plainFile), basename(plainFile, PLAIN_SOURCE_FILE_EXTENSION)));
+}
+/** Whether a path is a folder, or below one. */
+function within(path, folder) {
+    const from = relative(folder, path);
+    return from === "" || (!from.startsWith("..") && !from.startsWith(sep) && from !== "..");
+}
+/** The frontmatter of a .plain file, as a test plain file's is read; empty when it cannot be read. */
+function frontmatterOf(path) {
+    try {
+        return loadFrontmatter(readFileSync(path, "utf8").split("\r\n").join("\n")).metadata;
+    }
+    catch {
+        return {};
+    }
+}
+/** The modules of a project, by name: the .plain files in its folder and its `template/` folder. */
+export function projectModules(projectDir) {
+    const modules = new Map();
+    for (const dir of [join(projectDir, "template"), projectDir]) {
+        let names = [];
+        try {
+            names = readdirSync(dir).filter((name) => name.endsWith(PLAIN_SOURCE_FILE_EXTENSION));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names)
+            modules.set(basename(name, PLAIN_SOURCE_FILE_EXTENSION), join(dir, name));
+    }
+    return modules;
+}
+/**
+ * Where a path is, when it is a test plain file - under the project's test folder, or a .plain file whose frontmatter
+ * binds it with `module:` and `func_id:` - or the test folder, or a folder in it. Undefined for anything else.
+ */
+export function testPlaceOf(path) {
+    const absolute = resolve(path);
+    const directory = existsSync(absolute) && statSync(absolute).isDirectory();
+    const projectDir = projectOfTestPath(absolute, directory);
+    const testDir = testDirOf(join(projectDir, "x.plain"));
+    const metadata = directory || !existsSync(absolute) ? {} : frontmatterOf(absolute);
+    const bound = typeof metadata[MODULE_KEY] === "string" && typeof metadata[FUNC_ID_KEY] === "string";
+    if (!within(absolute, testDir) && !bound)
+        return undefined;
+    const parts = within(absolute, testDir) ? relative(testDir, absolute).split(sep).filter(Boolean) : [];
+    const folderModule = directory ? parts[0] : parts.length > 1 ? parts[0] : undefined;
+    return {
+        projectDir,
+        testDir,
+        directory,
+        ...(folderModule !== undefined ? { folderModule } : {}),
+        ...(bound ? { module: metadata[MODULE_KEY], funcId: metadata[FUNC_ID_KEY] } : {}),
+    };
+}
+/**
+ * The project a path in a test folder belongs to. One with no config yet has nothing above the path to say so: its
+ * test folder is `tests`, and the project the folder that holds it.
+ */
+function projectOfTestPath(absolute, directory) {
+    const found = projectDirOf(directory ? join(absolute, "x.plain") : absolute);
+    if (isProjectDir(found))
+        return found;
+    for (let dir = directory ? absolute : dirname(absolute); dirname(dir) !== dir; dir = dirname(dir)) {
+        if (basename(dir) === DEFAULT_TEST_DIR)
+            return dirname(dir);
+    }
+    return found;
+}
+/** A path as a person reads it in the project: from its folder. */
+function shown(path, projectDir) {
+    return relative(projectDir, resolve(path)).split(sep).join("/");
+}
+/**
+ * Why a tool refuses a path in place of a module: it is a test plain file - naming its module and the functional
+ * spec it binds to - or a test folder. Undefined for a path that is not one.
+ */
+export function testPlainFileRefusal(path) {
+    const place = testPlaceOf(path);
+    if (place === undefined)
+        return undefined;
+    const given = shown(path, place.projectDir) + (place.directory ? "/" : "");
+    const module = place.module ?? place.folderModule;
+    if (place.directory) {
+        return module === undefined
+            ? `\`${given}\` is the test folder of the project, which holds the test plain files; name a module's .plain file.`
+            : `\`${given}\` is the test folder of \`${module}\`; name \`${module}.plain\`.`;
+    }
+    if (module === undefined)
+        return `\`${given}\` is in the test folder, where test plain files are; name a module's .plain file.`;
+    const funcId = place.funcId ?? basename(path, PLAIN_SOURCE_FILE_EXTENSION);
+    return `\`${given}\` is a test plain file of \`${module}\`; name \`${module}.plain\`, or \`${module}:${funcId}\` for that one functional spec.`;
+}
+/** Refuse a path that is a test plain file or a test folder, as every tool that takes a module does. */
+export function refuseTestPlainFile(path) {
+    const refusal = testPlainFileRefusal(path);
+    if (refusal !== undefined)
+        throw new Error(refusal);
+}
+/**
+ * The test plain files of a project that are not where they belong, each with where it does: a file outside any
+ * module's folder, in the folder of a module there is not, or in a module's folder its `module:` does not name. Strays
+ * are not read when a module is parsed; this is where they are found.
+ */
+export function strayTestPlainFiles(projectDir) {
+    const testDir = testDirOf(join(projectDir, "x.plain"));
+    const modules = projectModules(projectDir);
+    const strays = [];
+    for (const path of plainFilesUnder(testDir)) {
+        const file = shown(path, projectDir);
+        const folder = relative(testDir, dirname(path)).split(sep).filter(Boolean)[0];
+        const metadata = frontmatterOf(path);
+        const named = typeof metadata[MODULE_KEY] === "string" ? metadata[MODULE_KEY] : undefined;
+        const home = (module) => `${shown(join(testDir, module), projectDir)}/`;
+        if (folder === undefined) {
+            strays.push({ file, problem: named === undefined ? "move it to the folder of its module, in the test folder" : `move it to ${home(named)} (its module: ${named})` });
+        }
+        else if (!modules.has(folder)) {
+            strays.push({
+                file,
+                problem: named === undefined ? `no module ${folder}` : `no module ${folder}; module: ${named} is in ${home(named)}`,
+            });
+        }
+        else if (named !== undefined && named !== folder) {
+            strays.push({ file, problem: `its module: is ${named}, not ${folder}; move it to ${home(named)}` });
+        }
+    }
+    return strays;
+}
+/** The module a test plain file belongs to, by its folder, and that module's .plain file when the project has one. */
+export function moduleOfTestPlainFile(path) {
+    const place = testPlaceOf(path);
+    const module = place?.folderModule;
+    if (place === undefined || module === undefined)
+        return undefined;
+    return { module, plainFile: projectModules(place.projectDir).get(module) };
+}

package/docs/README.md

@@ -18,6 +18,7 @@ turri is the first coding agent with the power of regenerative software: [\*\*\*
 | how to start a project, or add a feature, in a conversation | [using](using.md#in-a-conversation) |
 | how to have several chats open at once, and reopen them | [chats](chats.md) |
 | what checks each pulse as it finishes, and tells me what needs me | [the sentinel](sentinel.md) |
+| why the chat wrote scenarios I did not ask for, and how to turn that off | [the test advisor](test-advisor.md) |
 | which model codes, and how to change it | [using](using.md#choosing-a-model), [the project config](config.md#models) |
 | what `config.turri.yaml` can set, and what happens without it | [the project config](config.md) |
 | how a backend and a frontend on different stacks share one project | [the project config](config.md#stacks) |
@@ -44,6 +45,7 @@ turri is the first coding agent with the power of regenerative software: [\*\*\*
 | [Using turri](using.md) | the conversation, the tools, background jobs, choosing a model, module history, the command line |
 | [Chats](chats.md) | several chats in one session: what each keeps and what they share, `/chat` and its keys, `turri --continue` and `.turri/chats.json` |
 | [The sentinel](sentinel.md) | the chat every finished pulse goes to: what it checks and tests, its notices and how to answer them, what it may do, closing it, its model, in a host |
+| [The test advisor](test-advisor.md) | turri's background check of new and changed functional specs: when it runs, how it decides, what you see, its records, model and setting |
 | [The project config](config.md) | `config.turri.yaml` and each stack's `config.turri.<stack>.yaml`: where they are read from, every key, models and their inheritance, conformance, the testing scripts, stacks and choosing one, the old `config.yaml` |
 | [Deploy](deploy.md) | trying what is built: dist/<module>, the last commit, starting it on your machine, `turri release` |
 | [Running unattended](headless.md) | regenerating overnight or in CI: before you leave it, the command, the results, resuming, rebuilding one functionality |
@@ -51,7 +53,7 @@ turri is the first coding agent with the power of regenerative software: [\*\*\*
 | [Regenerating](regenerating.md) | where things go, one job, a whole module and how its work is cut into jobs, each job's cases, \*\*\*plain changes, conformance tests, the two records of what is built |
 | [The sandbox](sandbox.md) | what an agent can reach, the file-tool fence, the command check, the OS sandbox, the audit |
 | [Skills and gates](skills-and-gates.md) | the gate syntax, what the harness enforces, what a step can do, the rules, trying the gates |
-| [The \*\*\*plain parser](parser.md) | the TypeScript port, `turri validate`, inheritance, the iterator, fidelity |
+| [The \*\*\*plain parser](parser.md) | the TypeScript port, `turri parse`, inheritance, the iterator, fidelity |
 | [Theming](theming.md) | the turri themes, contrast, backgrounds, the font |
 | [Running turri in a host](hosting.md) | `@turri-dev/cli/host`: the session and its chats in a host's own windows - their jobs, their questions - and what a host shows beside them |
 | [Development](development.md) | tests, the source layout, known edges |