@asrunjs/asrun 0.11.0 → 0.12.0

package/dist/lib/records.js

@@ -1,9 +1,39 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { DEFAULT_TEST_DATA_PREFIX, testDataPrefix } from './config.js';
 import { ROOT } from './paths.js';
-/** Every piece of data a test creates carries this prefix, so it can never be mistaken for real data. */
-export const TEST_DATA_PREFIX = '[asrun]';
+/**
+ * The default prefix of data a test creates. The project's `package.json` may set another one
+ * (`"asrun": { "testDataPrefix": "[autotest]" }`); always read the effective value with `testDataPrefix()`.
+ */
+export const TEST_DATA_PREFIX = DEFAULT_TEST_DATA_PREFIX;
 export const RECORDS_DIR = path.join(ROOT, '.tmp', 'records');
+/** The run stamp appended to every name a test creates: the run id's UTC time (`2026-11-09 12-34-56`). */
+export function testDataStamp(now = new Date()) {
+    const match = /^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})/.exec(process.env.ASRUN_RUN_ID ?? '');
+    if (match !== null)
+        return `${match[1]} ${match[2]}-${match[3]}-${match[4]}`;
+    return now.toISOString().slice(0, 19).replace('T', ' ').replaceAll(':', '-');
+}
+let stamp = null;
+/**
+ * The name of one piece of test data: `<base> (<run stamp>)`, for example
+ * `[autotest] Draft CMA (2026-11-09 12-34-56)`.
+ *
+ * The stamp is the run id's UTC time, so it matches the report folder and the ledger entry, and two runs never
+ * share a name: a person can search the product for the run's own data, edit it or delete it by hand. The base is
+ * the case's literal from `## Values`; it must start with the project's prefix. Calling this twice with the same base
+ * (a title before and after an edit, a retry) returns the same name.
+ */
+export function testDataName(base) {
+    const prefix = testDataPrefix();
+    if (!base.startsWith(prefix)) {
+        throw new Error(`Test data must start with the project's prefix "${prefix}" (got "${base}"). ` +
+            `Set "asrun.testDataPrefix" in package.json when the project uses another marker.`);
+    }
+    const suffix = ` (${(stamp ??= testDataStamp())})`;
+    return base.endsWith(suffix) ? base : `${base}${suffix}`;
+}
 /** The ledger of one test: `.tmp/records/<runId>/<file>.json`. One file per test, so parallel workers never share a file. */
 export const ledgerFile = (runId, testId) => path.join(RECORDS_DIR, runId, `${testId.replace(/[^\w-]/g, '_')}.json`);
 export function writeLedger(file, entries) {

package/dist/lib/rules.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The rule layers a project may change, and how they combine. Read by `pnpm asrun doctor` (validation) and by
+ * `pnpm asrun rules` (the digest an AI step reads before it applies them): one parser, so the two never disagree.
+ *
+ * `AGENTS.md` §2 is a table:
+ *
+ * ```
+ * | Rule | Project rule | Effect |
+ * |---|---|---|
+ * | F10 | Case prose in Simplified Chinese. | replaces |
+ * | P1  | Test data is prefixed "[autotest]". | adds |
+ * ```
+ *
+ * A rule id names a baseline rule the row `narrows` (stricter) or `replaces` (a different default). A rule with no
+ * baseline counterpart uses a project id (`P1`, `P2`, ...) and `adds`. Rows outside the table, and rows whose first
+ * cell is not a rule id, are documentation and are ignored.
+ */
+export interface BaselineRule {
+    id: string;
+    /** The rule's own sentence, joined from the lines that follow the id. */
+    text: string;
+    /** `[non-negotiable]`: no project rule may change it. */
+    locked: boolean;
+}
+export interface ProjectRule {
+    id: string;
+    text: string;
+    effect: string;
+    /** 1-based line in `AGENTS.md`. */
+    line: number;
+}
+export interface ProjectRulesCheck {
+    rules: ProjectRule[];
+    errors: string[];
+    warnings: string[];
+}
+/** Every rule the framework baseline defines, in document order. */
+export declare function baselineRules(): BaselineRule[];
+/** The §2 table rows of a project's `AGENTS.md`, with what the enclosing text says about each. */
+export declare function parseProjectRules(agentsText: string): ProjectRule[];
+/** Validates §2 against the baseline. The messages are the ones `doctor` and `rules` print. */
+export declare function checkProjectRules(rules: ProjectRule[], baseline?: BaselineRule[]): ProjectRulesCheck;
+/** Shorthand for the common call: read `AGENTS.md` and validate its §2. */
+export declare function readProjectRules(agentsPath: string): ProjectRulesCheck & {
+    missing: boolean;
+};
+/** The project's §2 rows as one-line entries, for a report or the `rules` command. */
+export declare function describeProjectRule(rule: ProjectRule): string;
+/**
+ * Bracketed words an `AGENTS.md` line names as the test-data prefix (a line that talks about a prefix or test data).
+ * The runtime can only read `package.json` `"asrun.testDataPrefix"`, so a document that names a different one must be
+ * reported: a generated spec would otherwise use one prefix and the document assert another.
+ */
+export declare function mentionedTestDataPrefixes(agentsText: string): Array<{
+    token: string;
+    line: number;
+}>;

package/dist/lib/rules.js

@@ -0,0 +1,140 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { FRAMEWORK_ROOT } from './paths.js';
+const RULE_ID = /^[A-Z]\d+$/;
+const PROJECT_ID = /^P\d+$/;
+const EFFECTS = new Set(['narrows', 'replaces', 'adds']);
+function read(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** Every rule the framework baseline defines, in document order. */
+export function baselineRules() {
+    const text = read(path.join(FRAMEWORK_ROOT, 'AGENTS.md')) ?? '';
+    const rules = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const match = /^- \*\*([A-Z]\d+)\s+—\s*(.*)$/.exec(lines[i].trim());
+        if (match === null)
+            continue;
+        const body = [match[2]];
+        for (let j = i + 1; j < lines.length; j++) {
+            const line = lines[j];
+            if (line.trim() === '' || /^- /.test(line.trim()))
+                break;
+            body.push(line.trim());
+        }
+        rules.push({ id: match[1], text: body.join(' ').replace(/\s+/g, ' ').trim(), locked: lines[i].includes('[non-negotiable]') });
+    }
+    return rules;
+}
+/** The §2 table rows of a project's `AGENTS.md`, with what the enclosing text says about each. */
+export function parseProjectRules(agentsText) {
+    const rules = [];
+    let fenced = false;
+    agentsText.split('\n').forEach((line, index) => {
+        if (line.trim().startsWith('```')) {
+            fenced = !fenced;
+            return;
+        }
+        if (fenced || !line.trim().startsWith('|'))
+            return;
+        const cells = line
+            .trim()
+            .replace(/^\|/, '')
+            .replace(/\|$/, '')
+            .split('|')
+            .map((cell) => cell.trim());
+        if (!RULE_ID.test(cells[0]))
+            return;
+        rules.push({ id: cells[0], text: cells[1] ?? '', effect: (cells[2] ?? '').toLowerCase(), line: index + 1 });
+    });
+    return rules;
+}
+/** Validates §2 against the baseline. The messages are the ones `doctor` and `rules` print. */
+export function checkProjectRules(rules, baseline = baselineRules()) {
+    const errors = [];
+    const warnings = [];
+    const known = new Map(baseline.map((rule) => [rule.id, rule]));
+    const seen = new Set();
+    for (const rule of rules) {
+        const where = `AGENTS.md:${rule.line}`;
+        if (seen.has(rule.id))
+            errors.push(`${where}: rule ${rule.id} appears more than once in §2.`);
+        seen.add(rule.id);
+        if (rule.text === '')
+            errors.push(`${where}: rule ${rule.id} has no text.`);
+        if (PROJECT_ID.test(rule.id)) {
+            if (rule.effect === '')
+                warnings.push(`${where}: project rule ${rule.id} has no Effect column: add "adds".`);
+            else if (rule.effect !== 'adds') {
+                errors.push(`${where}: project rule ${rule.id} has Effect "${rule.effect}"; use "adds" (there is no baseline rule ${rule.id}).`);
+            }
+            continue;
+        }
+        const base = known.get(rule.id);
+        if (base === undefined) {
+            errors.push(`${where}: ${rule.id} is not a rule of the framework baseline. Use a project id (P1, P2, ...) with "adds" ` +
+                'for a rule the baseline does not have.');
+        }
+        else if (base.locked)
+            errors.push(`${where}: ${rule.id} is [non-negotiable]; a project rule cannot change it.`);
+        else if (rule.effect === '')
+            warnings.push(`${where}: rule ${rule.id} has no Effect column: add "narrows" or "replaces".`);
+        else if (!EFFECTS.has(rule.effect)) {
+            errors.push(`${where}: rule ${rule.id} has Effect "${rule.effect}"; use "narrows", "replaces" or "adds".`);
+        }
+        else if (rule.effect === 'adds') {
+            errors.push(`${where}: rule ${rule.id} exists in the baseline; use "narrows" or "replaces", or a project id ` +
+                '(P1, P2, ...) with "adds".');
+        }
+    }
+    return { rules, errors, warnings };
+}
+/** Shorthand for the common call: read `AGENTS.md` and validate its §2. */
+export function readProjectRules(agentsPath) {
+    const text = read(agentsPath);
+    if (text === null)
+        return { rules: [], errors: [], warnings: [], missing: true };
+    const rules = parseProjectRules(text);
+    return { ...checkProjectRules(rules), missing: false };
+}
+/** The project's §2 rows as one-line entries, for a report or the `rules` command. */
+export function describeProjectRule(rule) {
+    return `${rule.id.padEnd(4)} ${rule.effect.padEnd(9)} ${rule.text}`;
+}
+/** Structural tokens that look like a prefix but are not test-data names. */
+const STRUCTURAL = new Set(['input', 'writes', 'email']);
+/**
+ * Bracketed words an `AGENTS.md` line names as the test-data prefix (a line that talks about a prefix or test data).
+ * The runtime can only read `package.json` `"asrun.testDataPrefix"`, so a document that names a different one must be
+ * reported: a generated spec would otherwise use one prefix and the document assert another.
+ */
+export function mentionedTestDataPrefixes(agentsText) {
+    const mentions = [];
+    let fenced = false;
+    agentsText.split('\n').forEach((line, index) => {
+        if (line.trim().startsWith('```')) {
+            fenced = !fenced;
+            return;
+        }
+        if (fenced)
+            return;
+        if (!/\b(prefix|prefixed|test[ -]data)\b/i.test(line))
+            return;
+        // Documentation and examples name the default or an illustration, not the project's own prefix.
+        if (/\b(package\.json|e\.g\.|for example|such as|example)\b/i.test(line))
+            return;
+        for (const match of line.matchAll(/`?\[([a-z0-9][a-z0-9_-]*)\]`?/gi)) {
+            const inner = match[1].toLowerCase();
+            if (STRUCTURAL.has(inner))
+                continue;
+            mentions.push({ token: `[${match[1]}]`, line: index + 1 });
+        }
+    });
+    return mentions;
+}

package/dist/scripts/cleanup.js

@@ -1,4 +1,5 @@
 import { listEnvs } from '../lib/profiles.js';
+import { testDataPrefix } from '../lib/config.js';
 import { describeLeftovers, findLeftovers, forgetLedgers } from '../lib/records.js';
 const args = process.argv.slice(2);
 const envArg = args.find((arg) => arg.startsWith('--env='))?.slice('--env='.length) ?? args[args.indexOf('--env') + 1];
@@ -15,7 +16,15 @@ if (leftovers.length === 0) {
     console.log(`No test data left behind in ${envArg.toUpperCase()}.`);
     process.exit(0);
 }
-console.log(`Test data left behind in ${envArg.toUpperCase()} (named "[asrun] ..."):\n${describeLeftovers(leftovers)}`);
+let prefix;
+try {
+    prefix = testDataPrefix();
+}
+catch (error) {
+    console.error(error.message);
+    process.exit(1);
+}
+console.log(`Test data left behind in ${envArg.toUpperCase()} (named "${prefix} ..."):\n${describeLeftovers(leftovers)}`);
 if (forget) {
     console.log(`\nForgot ${forgetLedgers(envArg)} ledger file(s). Only do this after the data is deleted.`);
 }

package/dist/scripts/cli.js

@@ -32,6 +32,12 @@ async function main() {
         process.exitCode = await migrate(rest);
         return;
     }
+    if (command === 'rules') {
+        // The script reads `process.argv` itself; drop the subcommand so it sees only its own arguments.
+        process.argv.splice(2, 1);
+        await import('./rules.js');
+        return;
+    }
     if (command === 'explore:notes') {
         // The script reads `process.argv` itself; drop the subcommand so it sees only its own arguments.
         process.argv.splice(2, 1);
@@ -44,13 +50,15 @@ async function main() {
     }
     await import('./run.js');
 }
-const USAGE = `Usage: pnpm asrun [init|doctor|reset|upgrade|migrate|explore:notes] [options]
+const USAGE = `Usage: pnpm asrun [init|doctor|rules|reset|upgrade|migrate|explore:notes] [options]
 
   (no subcommand)  Run the tests of one environment. See "pnpm asrun --help".
   init             Create the files a workspace needs (never overwrites; --update refreshes generated files,
                    --root <dir> targets another folder, --force overwrites every file init writes,
                    --force <path> overwrites one file).
   doctor           Check the workspace: profiles, tsconfig alias, generated files, skill overrides, migrations.
+  rules            Print the effective rules: the framework baseline, the project's AGENTS.md §2 and the project
+                   settings (test-data prefix). An AI step reads it before it applies them (--json for machines).
   reset            Remove node_modules and the files init writes, for a clean reinstall (keeps cases, specs,
                    profiles.yaml, package.json and edited scaffold files; see "pnpm asrun reset --help").
   upgrade          Install the newest asrun, refresh the workspace files and apply its migrations, after checking the

package/dist/scripts/doctor.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 import { loadProfiles, listEnvs, PROFILES_FILE } from '../lib/profiles.js';
 import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR } from '../lib/paths.js';
+import { readWorkspaceConfig } from '../lib/config.js';
+import { readProjectRules, mentionedTestDataPrefixes } from '../lib/rules.js';
 import { spawnTarget } from '../lib/command.js';
 import { migrationState, pendingMigrations } from '../lib/migrations.js';
 import { MIGRATIONS } from '../migrations/index.js';
@@ -22,29 +24,6 @@ function read(file) {
         return null;
     }
 }
-/** The ids of the framework rules that a project may not narrow, parsed from the framework's AGENTS.md. */
-function nonNegotiableRules() {
-    const ids = new Set();
-    for (const line of (read(path.join(FRAMEWORK_ROOT, 'AGENTS.md')) ?? '').split('\n')) {
-        const match = /^- \*\*([A-Z]\d+)\b/.exec(line.trim());
-        if (match && line.includes('[non-negotiable]'))
-            ids.add(match[1]);
-    }
-    return ids;
-}
-/**
- * Every rule id the framework baseline defines (`F1`..`F10`, `B1`..`B4`, `A1`..`A6`, `R1`..`R4`), so a project cannot
- * name one that does not exist.
- */
-function frameworkRuleIds() {
-    const ids = new Set();
-    for (const line of (read(path.join(FRAMEWORK_ROOT, 'AGENTS.md')) ?? '').split('\n')) {
-        const match = /^- \*\*([A-Z]\d+)\b/.exec(line.trim());
-        if (match)
-            ids.add(match[1]);
-    }
-    return ids;
-}
 /**
  * The framework sources that `pnpm build` compiles into `dist/` and are older than it, or missing from it. Only the
  * framework repository has those sources; an installed package ships `dist/` alone, so the list is empty there.
@@ -253,8 +232,8 @@ export async function main(args) {
             warnings.push(`.claude/skills/${name} is a copy of the framework skill; delete it, or it will never see an update.`);
         }
     }
-    // Project rules: a project may narrow or replace a baseline rule, never one of F1–F6. Rows are
-    // `| <id> | <the project's rule> | <narrows|replaces> |`.
+    // Project rules: a project may narrow or replace a baseline rule, never one of F1–F6/R2, and may add its own rule
+    // under a project id. Rows are `| <id> | <the project's rule> | <narrows|replaces|adds> |`.
     const agents = read(path.join(ROOT, 'AGENTS.md'));
     if (agents === null) {
         warnings.push('AGENTS.md is missing: run "pnpm asrun init" and fill in the project facts.');
@@ -263,30 +242,30 @@ export async function main(args) {
         if (!agents.includes(`${framework}/AGENTS.md`)) {
             errors.push(`AGENTS.md does not point at the framework baseline (${framework}/AGENTS.md).`);
         }
-        const locked = nonNegotiableRules();
-        const known = frameworkRuleIds();
-        let fenced = false;
-        for (const line of agents.split('\n')) {
-            // A fenced block is documentation (an example table), not the project's rules.
-            if (line.trim().startsWith('```')) {
-                fenced = !fenced;
-                continue;
+        const project = readProjectRules(path.join(ROOT, 'AGENTS.md'));
+        errors.push(...project.errors);
+        warnings.push(...project.warnings);
+        if (project.rules.length > 0) {
+            facts.push(`project rules: ${project.rules.map((rule) => `${rule.id} (${rule.effect || '?'})`).join(', ')}`);
+        }
+    }
+    // The project's own settings (`package.json` "asrun"): a bad prefix makes every write case fail, so it is an error.
+    let prefix = null;
+    try {
+        prefix = readWorkspaceConfig().testDataPrefix;
+        facts.push(`test data: ${prefix} <base> (<run stamp>)`);
+    }
+    catch (error) {
+        errors.push(error.message);
+    }
+    // A document that names another test-data prefix cannot change the runtime: report it instead of letting a generated
+    // spec use one prefix while the case document says another.
+    if (agents !== null && prefix !== null) {
+        for (const mention of mentionedTestDataPrefixes(agents)) {
+            if (mention.token !== prefix) {
+                errors.push(`AGENTS.md:${mention.line} names ${mention.token} as the test-data prefix, but package.json has ` +
+                    `"asrun.testDataPrefix": "${prefix}". Set it to "${mention.token}" (the runtime reads package.json, not prose).`);
             }
-            if (fenced)
-                continue;
-            const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((cell) => cell.trim());
-            if (!/^F\d+$/.test(cells[0]))
-                continue;
-            const id = cells[0];
-            const effect = (cells[2] ?? '').toLowerCase();
-            if (!known.has(id))
-                errors.push(`AGENTS.md names ${id}, which is not a rule of the framework baseline.`);
-            else if (locked.has(id))
-                errors.push(`AGENTS.md changes ${id}, which the framework marks [non-negotiable].`);
-            else if (effect === '')
-                warnings.push(`AGENTS.md rule ${id} has no Effect column: add "narrows" or "replaces" (a table written before 0.3.0 predates it).`);
-            else if (effect !== 'narrows' && effect !== 'replaces')
-                errors.push(`AGENTS.md rule ${id} has Effect "${cells[2]}"; use "narrows" or "replaces".`);
         }
     }
     // The install and the commands the docs use.

package/dist/scripts/lint-specs.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { listCaseFileIds } from '../lib/cases.js';
+import { caseWrites, hasCaseFile, listCaseFileIds, readCaseMeta } from '../lib/cases.js';
 import { TESTS_DIR } from '../lib/paths.js';
 import { parseTargets, readCaseText, TARGET_REF } from '../lib/targets.js';
 const specFiles = (dir) => fs.existsSync(dir)
@@ -125,6 +125,28 @@ function lint(file) {
                 add('fail', i, 'blocking-target', `${match[1]} still has an open [blocking] question in the case; do not build a check on it (use test.fixme).`);
         }
     });
+    // Test data names must be unique per run (F11): a writes case names what it creates with testDataName().
+    // Old specs predate the rule, so this is a warning: regenerate or heal them to clear it.
+    if (caseId !== undefined && hasCaseFile(caseId) && caseWrites(readCaseMeta(caseId))) {
+        const text = lines.join('\n');
+        const composed = new Set([...text.matchAll(/(?:const|let)\s+(\w+)\s*=\s*(?:await\s+)?testDataName\s*\(/g)].map((match) => match[1]));
+        lines.forEach((line, i) => {
+            if (!/\brecords\.track\s*\(/.test(line))
+                return;
+            for (let end = i; end < Math.min(lines.length, i + 15); end++) {
+                const match = /^\s*name:\s*(.*?),?\s*$/.exec(lines[end]);
+                if (match === null)
+                    continue;
+                const expression = match[1].trim();
+                if (/testDataName\s*\(/.test(expression))
+                    return;
+                if (/^[A-Za-z_$][\w$]*$/.test(expression) && composed.has(expression))
+                    return;
+                add('warn', end, 'test-data-name', `records.track() names the data "${expression}"; build it with testDataName() so the run's name carries its timestamp (F11).`);
+                return;
+            }
+        });
+    }
     TARGET_REF.lastIndex = 0;
     return findings;
 }

package/dist/scripts/rules.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/rules.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { caseSectionText } from '../lib/case-doc.js';
+import { readWorkspaceConfig } from '../lib/config.js';
+import { ROOT } from '../lib/paths.js';
+import { baselineRules, checkProjectRules, describeProjectRule, mentionedTestDataPrefixes, parseProjectRules, } from '../lib/rules.js';
+import { testDataStamp } from '../lib/records.js';
+/**
+ * `pnpm asrun rules`: the effective rules of this workspace, as one digest. An AI step reads this before it applies
+ * anything, so "§2 wins over the baseline" is a fact it was told rather than a layer it has to reason about. It never
+ * writes anything. `--json` is the machine-readable form; `--case <id>` adds that case's `## Rules`.
+ */
+const USAGE = `Usage: pnpm asrun rules [--json] [--case <case-id>]
+
+Prints the framework baseline, the project's AGENTS.md §2 rules and the project settings
+(test-data prefix, name format). --case <id> adds the case's own "## Rules".
+Exit code 1 when §2 or a setting is invalid (the same errors "pnpm asrun doctor" shows).`;
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+    console.log(USAGE);
+    process.exit(0);
+}
+const json = args.includes('--json');
+const caseIndex = args.findIndex((arg) => arg === '--case' || arg.startsWith('--case='));
+const caseId = caseIndex === -1 ? null : (args[caseIndex].includes('=') ? args[caseIndex].split('=')[1] : args[caseIndex + 1]);
+if (caseIndex !== -1 && !caseId) {
+    console.error('Usage: pnpm asrun rules [--json] [--case <case-id>]\n  --case needs a case id.');
+    process.exit(1);
+}
+const agentsFile = path.join(ROOT, 'AGENTS.md');
+let agentsText;
+try {
+    agentsText = fs.readFileSync(agentsFile, 'utf8');
+}
+catch {
+    console.error(`No AGENTS.md in ${ROOT}: run "pnpm asrun init" first.`);
+    process.exit(1);
+}
+const baseline = baselineRules();
+const project = checkProjectRules(parseProjectRules(agentsText), baseline);
+let config = null;
+let configError = null;
+try {
+    config = readWorkspaceConfig();
+}
+catch (error) {
+    configError = error.message;
+}
+let caseRules = [];
+if (caseId !== null) {
+    const caseFile = path.join(ROOT, 'cases', `${caseId}.md`);
+    try {
+        const text = fs.readFileSync(caseFile, 'utf8');
+        const section = caseSectionText(text, 'Rules');
+        let current = null;
+        const flush = () => {
+            if (current !== null && current.length > 0)
+                caseRules.push({ text: current.join(' ') });
+            current = null;
+        };
+        for (const raw of section.split('\n')) {
+            if (/^-\s+\S/.test(raw.trim())) {
+                flush();
+                current = [raw.trim()];
+            }
+            else if (current !== null && /^\s+\S/.test(raw)) {
+                current.push(raw.trim());
+            }
+            else if (raw.trim() === '') {
+                flush();
+            }
+        }
+        flush();
+    }
+    catch {
+        console.error(`Case "${caseId}" not found (expected cases/${caseId}.md).`);
+        process.exit(1);
+    }
+}
+const prefix = config?.testDataPrefix ?? '';
+const stamp = testDataStamp();
+const errors = [...project.errors, ...(configError === null ? [] : [configError])];
+const prefixMentions = mentionedTestDataPrefixes(agentsText);
+if (config !== null) {
+    for (const mention of prefixMentions) {
+        if (mention.token !== config.testDataPrefix) {
+            errors.push(`AGENTS.md:${mention.line} names ${mention.token} as the test-data prefix, but package.json has ` +
+                `"asrun.testDataPrefix": "${config.testDataPrefix}". Set it to "${mention.token}" (the runtime reads package.json, not prose).`);
+        }
+    }
+}
+if (json) {
+    console.log(JSON.stringify({
+        workspace: ROOT,
+        baseline: baseline.map((rule) => ({ id: rule.id, locked: rule.locked, text: rule.text })),
+        projectRules: project.rules,
+        projectWarnings: project.warnings,
+        settings: { testDataPrefix: config?.testDataPrefix ?? null, testDataNameExample: `${prefix} <base> (${stamp})` },
+        prefixMentions,
+        ...(caseId !== null && { case: { id: caseId, rules: caseRules } }),
+        errors,
+    }, null, 2));
+}
+else {
+    const byLetter = new Map();
+    for (const rule of baseline) {
+        const letter = rule.id[0];
+        byLetter.set(letter, [...(byLetter.get(letter) ?? []), rule.id]);
+    }
+    console.log(`AsRun rules for ${ROOT}\n`);
+    console.log('Framework baseline:');
+    for (const [letter, ids] of byLetter) {
+        console.log(`  ${letter}: ${ids[0]}–${ids[ids.length - 1]}`);
+    }
+    const locked = baseline.filter((rule) => rule.locked).map((rule) => rule.id);
+    console.log(`  [non-negotiable]: ${locked.join(', ')}`);
+    console.log('\nProject rules (AGENTS.md §2):');
+    if (project.rules.length === 0)
+        console.log('  (none: the baseline defaults apply unchanged)');
+    else
+        for (const rule of project.rules)
+            console.log(`  ${describeProjectRule(rule)}`);
+    console.log('\nProject settings:');
+    console.log(`  testDataPrefix: ${config?.testDataPrefix ?? '(invalid)'}   ` +
+        `(package.json "asrun.testDataPrefix"; default [asrun])`);
+    console.log(`  test data name: ${prefix || '[asrun]'} <base> (${stamp})   (UTC, from the run id)`);
+    if (caseId !== null) {
+        console.log(`\nCase rules (cases/${caseId}.md §Rules):`);
+        if (caseRules.length === 0)
+            console.log('  (none)');
+        else
+            for (const rule of caseRules)
+                console.log(`  - ${rule.text.replace(/^-\s+/, '')}`);
+    }
+    if (project.warnings.length > 0) {
+        console.log('');
+        for (const warning of project.warnings)
+            console.log(`! ${warning}`);
+    }
+    if (errors.length > 0) {
+        console.log('');
+        for (const error of errors)
+            console.log(`x ${error}`);
+        console.log('\nFix the errors above; the rules are not applied until they are valid.');
+    }
+    console.log('\nA project rule is applied as written: a difference from the baseline is never a conflict and never a question.');
+}
+process.exit(errors.length > 0 ? 1 : 0);

package/docs/agents/case-format.md

@@ -89,7 +89,7 @@ Wrong: `- Create a draft named ... and delete it at the end.` (a write → a tag
 - `- Ready when:` is a sub-line of the step: the positive signal that what the step loads is there. The spec waits
   for it before reading; it is not an assertion.
 - `- Recipe (phase):` is a sub-line of an `[input]`/`[writes]` step: what a person did in the browser during an
-  attended exploration (positions, `[asrun]` names, control labels; no selectors). A tagged step with no recipe is a
+  attended exploration (positions, created names, control labels; no selectors). A tagged step with no recipe is a
   `needs-input` stop for `/gen-spec`.
 - A question block is indented under the sentence it belongs to: 4 spaces under a numbered step, 2 under a bullet.
   The parent line is the suggestion, written as a finished sentence; the `TODO` line holds one question and optional
@@ -121,7 +121,8 @@ example-staging:
 - A profile with no entry and no `default` fails with "Missing values ...". An empty value or one that starts with
   `TODO` fails with "Incomplete values ...". Fill them before running; never make a spec read the YAML itself.
 - Values hold literals only: names, labels, options, test-data names. The checks themselves stay in `## Steps` and
-  `## Expected`, and selectors come from `## Targets`.
+  `## Expected`, and selectors come from `## Targets`. A name the case creates is stored here **without** its run
+  stamp: the literal is the base, and the spec composes `<base> (<run stamp>)` with `testDataName()` (F11).
 - No marker or question inside the yaml: it would become part of the expected value. Put it on the prose line above
   the block and name the key there.
 
@@ -201,9 +202,11 @@ test.describe('<Case title>', {tag: caseTags('<id>')}, () => {
   a case limited to some environments is skipped elsewhere; a case that writes elsewhere only is skipped with a
   notice; a write in a non-staging environment needs the confirmation the CLI sets, never an environment variable
   that was merely present.
-- Write cases: name everything `[asrun] ...`, register it with `records.track` right after creating it, remove it
-  newest first (also after a failure), turn retries off with `configureCase`, and keep email steps behind
-  `emailStepAllowed(profile, '<step title>')`.
+- Write cases: name everything `<prefix> <base> (<run stamp>)` through `testDataName(base)`
+  (`@asrunjs/asrun/records`), where the prefix is `asrun.testDataPrefix` in `package.json` (default `[asrun]`, printed
+  by `pnpm asrun rules`) and the stamp is the run's UTC time; register it with `records.track` right after creating
+  it, remove it newest first (also after a failure), turn retries off with `configureCase`, and keep email steps
+  behind `emailStepAllowed(profile, '<step title>')`.
 
 ## Checks to run before reporting