@asrunjs/asrun 0.10.0 → 0.12.0

package/dist/lib/explore-notes.js

@@ -0,0 +1,242 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { isValidCaseId } from './case-id.js';
+import { CASES_DIR, EXPLORE_DIR } from './paths.js';
+/**
+ * The local exploration note: what `/explore-case` saw on the page, in a form `/gen-spec` can read.
+ *
+ * It lives under `.explore/notes/<case-id>/<profile-id>.json`, one file per profile, so a run with `--profiles` never
+ * has to merge with an earlier one. `.explore/` is git-ignored local state: a note is optional, may be deleted at any
+ * time, and a fresh checkout simply has none (generation then replays the case as before).
+ *
+ * A note holds only what the case does not: locators the agent confirmed on the page, the data-call paths of the
+ * actions that load something, and the match count of a target card's element. Expected values stay in the case's
+ * `## Values`, ready signals in the case's `Ready when:` lines, and assertions nowhere near this file.
+ */
+export const NOTES_VERSION = 1;
+const HASH = /^[a-f0-9]{64}$/;
+const PROFILE_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const STEP_KEY = /^[1-9]\d*$/;
+const TARGET_KEY = /^T[1-9]\d*$/;
+// A request pattern is a path, never a URL with a host or a query string that could carry a token.
+const UNSAFE_REQUEST = /[?#]|:\/\//;
+const SECRET_PARAM = /(?:^|[/&])(?:token|cookie|password|authorization|secret|signature|sig|session)=/i;
+const MAX_LOCATOR = 400;
+const MAX_PURPOSE = 200;
+const MAX_REQUEST = 200;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isOneLine = (value) => !/[\r\n]/.test(value);
+/** The folder that holds one case's notes; `<case-id>` may contain its group folder (`documents/landing-page`). */
+export function exploreNotesDir(caseId) {
+    if (!isValidCaseId(caseId))
+        throw new Error(`"${caseId}" is not a valid case id`);
+    return path.join(EXPLORE_DIR, 'notes', ...caseId.split('/'));
+}
+/** The note of one profile: `.explore/notes/<case-id>/<profile-id>.json`. */
+export function exploreNotesFile(caseId, profileId) {
+    if (!PROFILE_FILE.test(profileId))
+        throw new Error(`"${profileId}" is not a valid profile id`);
+    return path.join(exploreNotesDir(caseId), `${profileId}.json`);
+}
+/** sha256 of the case document, or null when it does not exist. */
+export function caseSha256(caseId) {
+    if (!isValidCaseId(caseId))
+        return null;
+    try {
+        return crypto.createHash('sha256').update(fs.readFileSync(path.join(CASES_DIR, `${caseId}.md`))).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a note still describes the case. A stale note is not an error: `/gen-spec` replays the case and ignores it.
+ */
+export function noteFreshness(note) {
+    const current = caseSha256(note.caseId);
+    if (current === null)
+        return { state: 'no-case', reason: 'the case file does not exist' };
+    if (current !== note.caseSha256)
+        return { state: 'stale', reason: 'the case file changed after the note was written' };
+    return { state: 'fresh' };
+}
+function checkLocator(value, where, problems) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        problems.push(`${where} must be a locator string`);
+        return;
+    }
+    if (!isOneLine(value))
+        problems.push(`${where} must be one line`);
+    if (value.length > MAX_LOCATOR)
+        problems.push(`${where} is longer than ${MAX_LOCATOR} characters`);
+    if (!value.startsWith('page.'))
+        problems.push(`${where} must start with "page." (use browser_generate_locator)`);
+    if (value.includes('=>'))
+        problems.push(`${where} must be a locator, not code`);
+}
+function checkRequest(value, where, problems) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        problems.push(`${where} must be a request path`);
+        return;
+    }
+    if (!isOneLine(value))
+        problems.push(`${where} must be one line`);
+    if (value.length > MAX_REQUEST)
+        problems.push(`${where} is longer than ${MAX_REQUEST} characters`);
+    if (!value.startsWith('/') || value.startsWith('//'))
+        problems.push(`${where} must start with "/" (a path, not a URL)`);
+    if (UNSAFE_REQUEST.test(value))
+        problems.push(`${where} must have no host, query string or fragment`);
+    if (SECRET_PARAM.test(value))
+        problems.push(`${where} must not carry a token, cookie or session`);
+}
+function checkPurpose(value, where, problems) {
+    if (typeof value !== 'string' || value.trim() === '')
+        problems.push(`${where} must be a short description`);
+    else if (!isOneLine(value))
+        problems.push(`${where} must be one line`);
+    else if (value.length > MAX_PURPOSE)
+        problems.push(`${where} is longer than ${MAX_PURPOSE} characters`);
+}
+function checkSteps(value, problems) {
+    if (!isRecord(value)) {
+        problems.push('steps must be an object keyed by step number');
+        return;
+    }
+    for (const [step, body] of Object.entries(value)) {
+        const where = `steps["${step}"]`;
+        if (!STEP_KEY.test(step))
+            problems.push(`${where}: the key must be a positive step number`);
+        if (!isRecord(body)) {
+            problems.push(`${where} must be an object`);
+            continue;
+        }
+        if (body.url !== undefined) {
+            const url = body.url;
+            if (typeof url !== 'string' || !url.startsWith('/'))
+                problems.push(`${where}.url must start with "/"`);
+            else if (UNSAFE_REQUEST.test(url))
+                problems.push(`${where}.url must have no host, query string or fragment`);
+        }
+        if (body.locators !== undefined) {
+            if (!Array.isArray(body.locators))
+                problems.push(`${where}.locators must be a list`);
+            else {
+                for (const [index, locator] of body.locators.entries()) {
+                    const item = `${where}.locators[${index}]`;
+                    if (!isRecord(locator)) {
+                        problems.push(`${item} must be an object with "purpose" and "locator"`);
+                        continue;
+                    }
+                    checkPurpose(locator.purpose, `${item}.purpose`, problems);
+                    checkLocator(locator.locator, `${item}.locator`, problems);
+                }
+            }
+        }
+        if (body.requests !== undefined) {
+            if (!Array.isArray(body.requests))
+                problems.push(`${where}.requests must be a list`);
+            else
+                body.requests.forEach((request, index) => checkRequest(request, `${where}.requests[${index}]`, problems));
+        }
+        const known = new Set(['url', 'locators', 'requests']);
+        for (const key of Object.keys(body))
+            if (!known.has(key))
+                problems.push(`${where}.${key} is not a known field`);
+    }
+}
+function checkTargets(value, problems) {
+    if (!isRecord(value)) {
+        problems.push('targets must be an object keyed by target id');
+        return;
+    }
+    for (const [id, target] of Object.entries(value)) {
+        const where = `targets["${id}"]`;
+        if (!TARGET_KEY.test(id))
+            problems.push(`${where}: the key must be a target id such as "T1"`);
+        if (!isRecord(target)) {
+            problems.push(`${where} must be an object`);
+            continue;
+        }
+        checkLocator(target.locator, `${where}.locator`, problems);
+        if (target.matches !== undefined && (!Number.isInteger(target.matches) || target.matches < 1)) {
+            problems.push(`${where}.matches must be a positive whole number`);
+        }
+        const known = new Set(['locator', 'matches']);
+        for (const key of Object.keys(target))
+            if (!known.has(key))
+                problems.push(`${where}.${key} is not a known field`);
+    }
+}
+/** Every reason the note is not usable, in plain words. An empty list means it is valid. */
+export function validateExploreNote(value, expected) {
+    const problems = [];
+    if (!isRecord(value))
+        return ['the note is not a JSON object'];
+    if (value.version !== NOTES_VERSION)
+        problems.push(`version must be ${NOTES_VERSION}`);
+    if (value.caseId !== expected.caseId)
+        problems.push(`caseId must be "${expected.caseId}"`);
+    if (value.profile !== expected.profile)
+        problems.push(`profile must be "${expected.profile}"`);
+    if (typeof value.profile !== 'string' || !PROFILE_FILE.test(value.profile)) {
+        problems.push('profile must be a profile id (letters, digits, ".", "_" and "-")');
+    }
+    if (typeof value.caseSha256 !== 'string' || !HASH.test(value.caseSha256)) {
+        problems.push('caseSha256 must be the sha256 of the case file (run "explore:notes <case-id> --hash")');
+    }
+    if (typeof value.capturedAt !== 'string' || value.capturedAt.trim() === '') {
+        problems.push('capturedAt must be an ISO date-time');
+    }
+    if (value.updatedAt !== undefined && typeof value.updatedAt !== 'string')
+        problems.push('updatedAt must be a string');
+    if (value.env !== undefined && (typeof value.env !== 'string' || value.env.trim() === '')) {
+        problems.push('env must be a non-empty string when it is present');
+    }
+    checkSteps(value.steps, problems);
+    if (value.targets !== undefined)
+        checkTargets(value.targets, problems);
+    const known = new Set(['version', 'caseId', 'profile', 'env', 'caseSha256', 'capturedAt', 'updatedAt', 'steps', 'targets']);
+    for (const key of Object.keys(value))
+        if (!known.has(key))
+            problems.push(`${key} is not a known field`);
+    return problems;
+}
+/**
+ * Reads every note of a case (or one profile's), parses and validates it. A malformed file is reported, never thrown:
+ * the caller decides whether it matters, and generation treats an unreadable note as a missing one.
+ */
+export function readExploreNotes(caseId, profileId) {
+    const errors = [];
+    const notes = [];
+    if (!isValidCaseId(caseId))
+        return { notes, errors: [{ file: caseId, problems: ['not a valid case id'] }] };
+    let files;
+    try {
+        files = fs.readdirSync(exploreNotesDir(caseId)).filter((file) => file.endsWith('.json'));
+    }
+    catch {
+        return { notes, errors };
+    }
+    for (const file of files.sort()) {
+        const profile = path.basename(file, '.json');
+        if (profileId !== undefined && profile !== profileId)
+            continue;
+        const full = path.join(exploreNotesDir(caseId), file);
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(full, 'utf8'));
+        }
+        catch (error) {
+            errors.push({ file: full, problems: [`not valid JSON: ${error.message}`] });
+            continue;
+        }
+        const problems = validateExploreNote(parsed, { caseId, profile });
+        if (problems.length > 0)
+            errors.push({ file: full, problems });
+        else
+            notes.push(parsed);
+    }
+    return { notes, errors };
+}

package/dist/lib/fixtures.d.ts

@@ -4,7 +4,7 @@ import { type Profile } from './profiles.js';
 export interface TrackedData {
     /** What it is, e.g. "Document draft". */
     kind: string;
-    /** Its name in the product. Must start with `[asrun]`, so cleanup can never touch real data. */
+    /** Its name in the product. Must start with the project's prefix, so cleanup can never touch real data. */
     name: string;
     /** Where a person finds it by hand if the cleanup fails, e.g. "/app/documents". */
     where?: string;

package/dist/lib/fixtures.js

@@ -2,7 +2,8 @@ import { expect, test as base } from '@playwright/test';
 import { getProfile } from './profiles.js';
 import { caseWrites, caseWritesIn, hasCaseFile, readCaseMeta } from './cases.js';
 import { acquireAccountLock } from './account-lock.js';
-import { ledgerFile, TEST_DATA_PREFIX, writeLedger } from './records.js';
+import { testDataPrefix } from './config.js';
+import { ledgerFile, writeLedger } from './records.js';
 import { caseIdFromFile } from './run-summary.js';
 import { ALLOW_WRITES_ENV, isProtectedEnv } from './write-gate.js';
 import { checkSession, isLoggedOutUrl, parseNotLoggedIn, sessionProblemMessage, signinCommand, } from './session.js';
@@ -76,9 +77,11 @@ export const test = base.extend({
         const save = () => writeLedger(file, entries.map((item) => item.entry));
         await use({
             async track(data, remove) {
-                if (!data.name.startsWith(TEST_DATA_PREFIX)) {
-                    throw new Error(`Test data must be named with the prefix "${TEST_DATA_PREFIX}" (got "${data.name}"). ` +
-                        `Only data that is clearly a test's own may be created and removed.`);
+                const prefix = testDataPrefix();
+                if (!data.name.startsWith(prefix)) {
+                    throw new Error(`Test data must be named with the project's prefix "${prefix}" (got "${data.name}"). ` +
+                        `Set "asrun.testDataPrefix" in package.json when the project uses another marker, and build the name ` +
+                        'with testDataName() so two runs never share it.');
                 }
                 entries.push({
                     entry: {

package/dist/lib/paths.d.ts

@@ -25,6 +25,8 @@ export declare const CASES_DIR: string;
 export declare const TESTS_DIR: string;
 export declare const REPORTS_DIR: string;
 export declare const TMP_DIR: string;
+/** Local agent output (reference screenshots, exploration notes), git-ignored and safe to delete. */
+export declare const EXPLORE_DIR: string;
 export declare const TEMPLATES_DIR: string;
 export declare const SKILLS_DIR: string;
 /**

package/dist/lib/paths.js

@@ -82,6 +82,8 @@ export const CASES_DIR = path.join(ROOT, 'cases');
 export const TESTS_DIR = path.join(ROOT, 'tests');
 export const REPORTS_DIR = path.join(ROOT, 'reports');
 export const TMP_DIR = path.join(ROOT, '.tmp');
+/** Local agent output (reference screenshots, exploration notes), git-ignored and safe to delete. */
+export const EXPLORE_DIR = path.join(ROOT, '.explore');
 export const TEMPLATES_DIR = path.join(FRAMEWORK_ROOT, 'templates');
 export const SKILLS_DIR = path.join(FRAMEWORK_ROOT, '.claude', 'skills');
 /**

package/dist/lib/records.d.ts

@@ -1,4 +1,7 @@
-/** Every piece of data a test creates carries this prefix, so it can never be mistaken for real data. */
+/**
+ * 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 declare const TEST_DATA_PREFIX = "[asrun]";
 export type RecordStatus = 'open' | 'cleaned' | 'leftover';
 /** One piece of test data a case created, as written to the ledger. */
@@ -10,7 +13,7 @@ export interface LedgerEntry {
     caseId: string;
     /** What kind of thing it is, e.g. "Document draft". */
     kind: string;
-    /** Its name in the product; always starts with TEST_DATA_PREFIX. */
+    /** Its name in the product; always starts with the project's test-data prefix (`testDataPrefix()`). */
     name: string;
     /** Where a person can find and remove it by hand, e.g. "/app/documents". */
     where: string | null;
@@ -20,6 +23,18 @@ export interface LedgerEntry {
     createdAt: string;
 }
 export declare const RECORDS_DIR: string;
+/** The run stamp appended to every name a test creates: the run id's UTC time (`2026-11-09 12-34-56`). */
+export declare function testDataStamp(now?: Date): string;
+/**
+ * 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 declare function testDataName(base: string): string;
 /** The ledger of one test: `.tmp/records/<runId>/<file>.json`. One file per test, so parallel workers never share a file. */
 export declare const ledgerFile: (runId: string, testId: string) => string;
 export declare function writeLedger(file: string, entries: LedgerEntry[]): void;

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,23 +32,38 @@ 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);
+        await import('./explore-notes.js');
+        return;
+    }
     if (command === 'help' || command === '--help-init') {
         console.log(USAGE);
         return;
     }
     await import('./run.js');
 }
-const USAGE = `Usage: pnpm asrun [init|doctor|reset|upgrade|migrate] [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
                    target release for breaking changes (see "pnpm asrun upgrade --help").
   migrate          Apply the workspace migrations of the installed release, or list them (see "pnpm asrun migrate
-                   --help"). "upgrade" runs it; use it after a manual install.`;
+                   --help"). "upgrade" runs it; use it after a manual install.
+  explore:notes    Print or validate the local exploration note of a case (see "pnpm asrun explore:notes --help").`;
 await main();