@am_shork/attest 0.6.0 → 0.7.0

package/dist/core/pipeline.js

@@ -1,14 +1,12 @@
 // High-level operations composing the core layers (design §9). These are
 // tool-agnostic; the CLI is a thin shell that calls them and renders the result.
-import { createLoader } from './loader.js';
 import { evalReader, findChangeDirSpecs, loadRegistry, listChangeNames, parseSpecs, scanProject, staticReader, } from './locate.js';
 import { validateStructure, detectPotentialDrift, uncoveredIssues } from './validator.js';
 import { byCodeUnit } from './order.js';
-import { runAndCollect, BASE_EXCLUDE } from './runner.js';
 import { applyDelta, addedIds, claimedIds } from './apply.js';
 import { readDeltaSource } from './static-registry.js';
 import { statusRows, statusCounts } from './status.js';
-import { evaluateGate, declaredNotRunIssues } from './gate.js';
+import { evaluateGate, notRunIssues } from './gate.js';
 import { renderMarkdown, staleIssue } from './render.js';
 import { mergeRedRecord, readRedRecord, redRecordPath, serialiseRedRecord, } from './red-record.js';
 import { DEFAULT_TARGET, resolveTargets } from './targets.js';
@@ -19,13 +17,52 @@ import { mkdir, readFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { relativePath } from './paths.js';
 import { hasError } from './types.js';
+// The runner half of the engine, reached only when a command actually needs it.
+//
+// These two are deliberately not top-level imports. `cli/index.ts` imports this
+// module whole, so a static import here resolves and evaluates `vite`,
+// `vitest/node` and `vitest/config` before `commander` has parsed an argument —
+// measured at ~900 ms, paid by `check`, `cover`, `render`, `status` without
+// `--eval` and `init`, none of which can start a run. §11's cost model is a
+// short-lived process where cold start is the whole bill, so a fixed toll on
+// every invocation outweighs anything scaling with requirement count.
+//
+// This is *not* the core/adapter package split §11 defers, and does not
+// substitute for it: `pipeline.ts` still holds both halves, so the reachability
+// `tests/import-boundary.spec.ts` cannot assert is still unassertable. What
+// moves is when the cost is paid. The specifiers stay relative and the gate
+// reads `import(...)` from the AST alongside static imports, so the boundary is
+// checked exactly as before — that is the one property this change could have
+// silently dropped, and the reason that test looks for dynamic imports at all.
+/** {@link import('./loader.js').createLoader}, resolved on first use. */
+async function createLoader() {
+    const { createLoader: create } = await import('./loader.js');
+    return create();
+}
+/**
+ * {@link import('./runner.js').runAndCollect}, resolved on first use.
+ *
+ * `BASE_EXCLUDE` gets no such wrapper: it has one caller, which is inside the
+ * function that starts the run it belongs to, so it is destructured there
+ * alongside nothing.
+ */
+async function runAndCollect(options = {}) {
+    const { runAndCollect: run } = await import('./runner.js');
+    return run(options);
+}
 /**
  * Read every registry under root with the reader `options` asks for, and close
  * whatever that reader needed. Static reading starts no Vite server at all.
+ *
+ * `borrowed` is a loader the caller is already holding open for this command.
+ * See `withLoader` for why a command with more than one thing to evaluate owns
+ * one rather than letting each read start its own.
  */
-async function readRegistry(root, options, files) {
+async function readRegistry(root, options, files, borrowed) {
     if (!options.evaluate)
         return loadRegistry(root, staticReader(), files);
+    if (borrowed)
+        return loadRegistry(root, evalReader(borrowed), files);
     const loader = await createLoader();
     try {
         return await loadRegistry(root, evalReader(loader), files);
@@ -34,22 +71,59 @@ async function readRegistry(root, options, files) {
         await loader.close();
     }
 }
+/**
+ * Run `fn` with one loader for the whole command, or with none when nothing is
+ * to be evaluated.
+ *
+ * A loader is a Vite dev server: starting one is the expensive thing on this
+ * path, and `check --eval` used to start **one per change** — `readDelta`
+ * created and closed its own on every iteration of the loop over
+ * `listChangeNames`, on top of the one `readRegistry` had already opened and
+ * closed for the same command. So the cost was 1 + N servers for a command that
+ * needs one. Ownership sits here rather than in either reader because neither
+ * of them knows how many times it is about to be called.
+ *
+ * Static commands pass `undefined` all the way down and start nothing at all,
+ * which is the property `check` without `--eval` is documented on (design §5.1)
+ * and the reason this returns an optional rather than always creating one.
+ */
+async function withLoader(options, fn) {
+    if (!options.evaluate)
+        return fn(undefined);
+    const loader = await createLoader();
+    try {
+        return await fn(loader);
+    }
+    finally {
+        await loader.close();
+    }
+}
 /** Static structural check (design §9: `attest check`). */
 export async function runCheck(root, options = {}) {
     const unusable = compilerIssue();
     if (unusable)
         return [unusable];
     const scan = await scanProject(root);
-    const { registry, issues } = await readRegistry(root, options, scan.reqsFiles);
-    const plan = await parseSpecs(scan.specFiles, root);
-    return [
-        ...issues,
-        ...validateStructure(registry, plan),
-        ...detectPotentialDrift(registry, plan, plan.paramRefs),
-        ...(await unclaimedProposedSpecIssues(root, scan, options)),
-        ...(await changeDirSpecIssues(root)),
-        ...proposedNameTakenIssues(root, scan),
-    ];
+    // One loader for the command, not one per thing evaluated: this is the only
+    // command that reads both the registry and every change's delta, so it is the
+    // only one where that distinction is worth anything.
+    return withLoader(options, async (loader) => {
+        const { registry, issues, unreadableFiles } = await readRegistry(root, options, scan.reqsFiles, loader);
+        const plan = await parseSpecs(scan.specFiles, root);
+        return [
+            ...issues,
+            // `check` keeps reporting on a registry that only half-loaded,
+            // deliberately: its contract is breadth, and the findings from the files
+            // that *did* load are all still true. What it must not do is advise work
+            // that the load failure makes wrong — see `orphan-test` in
+            // `validateStructure`.
+            ...validateStructure(registry, plan, unreadableFiles.length > 0),
+            ...detectPotentialDrift(registry, plan, plan.paramRefs),
+            ...(await unclaimedProposedSpecIssues(root, scan, options, loader)),
+            ...(await changeDirSpecIssues(root)),
+            ...proposedNameTakenIssues(root, scan),
+        ];
+    });
 }
 /**
  * A proposed spec whose merged name is already taken (design §7).
@@ -131,13 +205,15 @@ async function changeDirSpecIssues(root) {
  * — a change delta is intent, and the commands that only report read it from
  * source (design §5.1).
  */
-async function unclaimedProposedSpecIssues(root, scan, options) {
+async function unclaimedProposedSpecIssues(root, scan, options, loader) {
     if (scan.proposedSpecFiles.length === 0)
         return [];
     const claimed = new Set();
     const issues = [];
+    // The loop `loader` exists for: under `--eval` this used to start and stop a
+    // Vite dev server per change.
     for (const name of await listChangeNames(root)) {
-        const read = await readDelta(root, name, options);
+        const read = await readDelta(root, name, options, loader);
         if ('issue' in read)
             issues.push(read.issue);
         else
@@ -204,17 +280,21 @@ export async function runVerify(root, options = {}) {
     const loader = await createLoader();
     let registry;
     let plan;
+    let unreadableFiles;
     const issues = [];
     try {
         const loaded = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
         registry = loaded.registry;
         issues.push(...loaded.issues);
+        unreadableFiles = loaded.unreadableFiles;
         plan = await parseSpecs(scan.specFiles, root);
     }
     finally {
         await loader.close();
     }
-    issues.push(...validateStructure(registry, plan));
+    // Same as `check`: everything the loaded half supports is still reported, and
+    // only the advice that a load failure would make wrong is withdrawn.
+    issues.push(...validateStructure(registry, plan, unreadableFiles.length > 0));
     issues.push(...detectPotentialDrift(registry, plan, plan.paramRefs));
     const attesting = attestingFiles(plan);
     const counts = {
@@ -257,7 +337,13 @@ export async function runVerify(root, options = {}) {
     if (!run.passed) {
         issues.push({ level: 'ERROR', code: 'tests-red', message: 'Some tests are failing.' });
     }
-    issues.push(...declaredNotRunIssues(plan, run));
+    // The load failures first, then the absences they caused — by the same
+    // function the gate calls, which is the point. `verify` used to ask only for
+    // the absences, so an ordinary broken import surfaced as a `declared-not-run`
+    // per scenario blaming a skip, with nothing anywhere naming the file that did
+    // not load. No more specific diagnosis to pass: `added-id-unmerged` is a
+    // statement about a change's delta, and `verify` has no change.
+    issues.push(...notRunIssues(plan, run));
     return { issues, passed: run.passed, ok: run.passed && !hasError(issues), counts };
 }
 /**
@@ -284,8 +370,12 @@ export async function runCover(root, options = {}) {
     for (const s of plan.scenarios) {
         counts.set(s.reqId, (counts.get(s.reqId) ?? 0) + 1);
     }
+    // `byCodeUnit`, not a bare `.sort()`. The two give an identical result on ids
+    // that match the grammar, and that is exactly why this is worth spelling:
+    // `order.ts` exists so ordering has one spelling across the engine, which is
+    // a property that survives an edit — an identical result is not.
     const rows = Object.keys(registry)
-        .sort()
+        .sort(byCodeUnit)
         .map((reqId) => ({
         reqId,
         covered: (counts.get(reqId) ?? 0) > 0,
@@ -426,10 +516,14 @@ function changeNotFoundIssue(root, deltaPath, changeName, err) {
  * under review. `archive` evaluates unconditionally because it runs the suite
  * anyway, so declining to evaluate one more module would buy it nothing.
  */
-async function readDelta(root, changeName, options) {
+async function readDelta(root, changeName, options, borrowed) {
     const deltaPath = changeDeltaPath(root, changeName);
     if (options.evaluate) {
-        const loader = await createLoader();
+        // Borrow the caller's loader when it has one, own one otherwise. The
+        // difference matters only to the caller that reads several deltas — see
+        // `withLoader` — and a lone reader should not have to build scaffolding to
+        // ask for one delta.
+        const loader = borrowed ?? (await createLoader());
         try {
             const mod = await loader.load(deltaPath);
             if (!mod.default || typeof mod.default !== 'object') {
@@ -443,7 +537,10 @@ async function readDelta(root, changeName, options) {
             return { issue: changeNotFoundIssue(root, deltaPath, changeName, err) };
         }
         finally {
-            await loader.close();
+            // Only what this call created. Closing a borrowed loader would take it
+            // out from under the caller's next iteration.
+            if (!borrowed)
+                await loader.close();
         }
     }
     let source;
@@ -512,10 +609,20 @@ function claimedByDelta(proposed, delta) {
 async function changeMergedPlan(root, delta, scan) {
     const basePlan = await parseSpecs(scan.specFiles, root);
     const proposed = await parseSpecs(scan.proposedSpecFiles, root);
-    const changePlan = claimedByDelta(proposed, delta);
+    const claimed = claimedByDelta(proposed, delta);
     return {
-        scenarios: [...basePlan.scenarios, ...changePlan.scenarios],
-        paramRefs: [...basePlan.paramRefs, ...changePlan.paramRefs],
+        merged: {
+            scenarios: [...basePlan.scenarios, ...claimed.scenarios],
+            paramRefs: [...basePlan.paramRefs, ...claimed.paramRefs],
+        },
+        // Returned rather than recomputed by the caller that needs it. `--apply`
+        // renames exactly the proposed specs this change claims, and deriving that
+        // set a second time — a second `parseSpecs` and a second `claimedByDelta`
+        // over the same files — is agreement by transcription: the two answers
+        // match because the same two functions ran twice, which is the thing this
+        // codebase extracts `declaredNotRunIssues` and `uncoveredIssues` to stop
+        // relying on. One parse, one split, one answer.
+        claimed,
     };
 }
 /** Per-change progress (design §9: `attest status <change>`). */
@@ -537,7 +644,7 @@ export async function runStatus(root, changeName, options = {}) {
     if ('issue' in read)
         return nothing([read.issue]);
     const scan = await scanProject(root);
-    const plan = await changeMergedPlan(root, read.delta, scan);
+    const { merged: plan } = await changeMergedPlan(root, read.delta, scan);
     const firstRun = await readRedRecord(root, changeName);
     const rows = statusRows(addedIds(read.delta), plan, firstRun);
     return { change: changeName, rows, counts: statusCounts(rows), issues: [] };
@@ -557,7 +664,10 @@ export async function runArchive(root, changeName, options = {}) {
  */
 export async function runArchiveApply(root, changeName, options = {}) {
     const { issues, merge } = await archiveRun(root, changeName, options);
-    if (issues.some((i) => i.level === 'ERROR') || !merge)
+    // One predicate for the verdict, everywhere (ATX-60): the gate's WARNINGs
+    // survive `--apply` by design, so `some(level === 'ERROR')` spelled here by
+    // hand was a second definition of failure sitting next to the one that counts.
+    if (hasError(issues) || !merge)
         return { issues, written: [] };
     const result = await applyMerge({ root, changeName, ...merge });
     // The gate's non-blocking output is kept: a WARNING the gate raised is still
@@ -589,7 +699,7 @@ async function archiveRun(root, changeName, options = {}) {
     const loader = await createLoader();
     try {
         const { registry: base, issues, prefixOwners } = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
-        if (issues.some((i) => i.level === 'ERROR'))
+        if (hasError(issues))
             return { issues };
         const deltaPath = changeDeltaPath(root, changeName);
         let delta;
@@ -615,13 +725,14 @@ async function archiveRun(root, changeName, options = {}) {
         // Static plan = merged base suite + this change's specs (design §8), by the
         // same function `status` reports against — a progress report computed over a
         // different spec set than the gate uses would be a report about nothing.
-        const plan = await changeMergedPlan(root, delta, scan);
+        const { merged: plan, claimed } = await changeMergedPlan(root, delta, scan);
         // Other proposals need no exclude glob of their own: the include list below
         // is the plan's own files, and the plan holds only the proposed specs this
         // delta claims. That is what replaced `**/changes/<sibling>/**` — with the
         // specs no longer living under `changes/`, a directory glob could not have
         // told two proposals apart, and one kept alongside the claim check would be
         // a second scoping rule able to disagree with it.
+        const { BASE_EXCLUDE } = await import('./runner.js');
         const exclude = [...BASE_EXCLUDE, '**/archive/**'];
         // Same run scope as `verify`: only the files that declare a requirement().
         // The gate must not go red because a repo's incumbent suite happens to sit
@@ -668,8 +779,9 @@ async function archiveRun(root, changeName, options = {}) {
                 prefixOwners,
                 // The plan's proposed files, not every proposed file on disk: `--apply`
                 // renames what *this* change claims, and a sibling proposal's spec is
-                // not this change's to move.
-                claimedSpecs: claimedSpecsOf(root, claimedByDelta(await parseSpecs(scan.proposedSpecFiles, root), delta)),
+                // not this change's to move. `claimed` is the half of the plan the gate
+                // above ran, handed back by the function that built it.
+                claimedSpecs: claimedSpecsOf(root, claimed),
                 mergedSpecs: scan.specFiles,
             },
         };

package/dist/core/render.js

@@ -6,7 +6,7 @@
 // back, so the direction OpenSpec's pure-Markdown model went (Markdown as
 // truth, and the free-form drift that comes with it) stays closed.
 //
-// Three properties this file must keep:
+// Four properties this file must keep:
 //  - **Intent only.** The document says what the system promises, never what is
 //    proven or green: coverage and results are verdicts, and verdicts belong to
 //    `cover` / `verify`, which recompute them on demand. Putting them here also
@@ -20,7 +20,13 @@
 //  - **Params interpolated into the statement.** The source says
 //    "{idleTimeoutMin} minutes"; a human reader wants "30 minutes". This is the
 //    one thing the projection gives that reading the source does not.
+//  - **None of the registry's control characters survive into it.** The
+//    document is quoted prose from a repository that may not be the reader's,
+//    and it is a *file* — committed, served, and read again long after the run
+//    that wrote it. See `sanitised` for why the defence sits here rather than
+//    at the terminal write.
 import { byCodeUnit } from './order.js';
+import { control } from './terminal.js';
 const BANNER = '<!-- Generated by `attest render` — do not edit. Edit the `*.reqs.ts` registry and regenerate. -->';
 /**
  * Render the registry as a standalone Markdown document.
@@ -31,18 +37,65 @@ const BANNER = '<!-- Generated by `attest render` — do not edit. Edit the `*.r
  * worse than no gate.
  */
 export function renderMarkdown(registry) {
-    const ids = Object.keys(registry).sort(compareIds);
+    const clean = sanitised(registry);
+    const ids = Object.keys(clean).sort(compareIds);
     const out = [BANNER, '', '# Requirements', ''];
     if (ids.length === 0) {
         out.push('_No requirements are defined yet._', '');
         return out.join('\n');
     }
-    out.push(...overviewTable(registry, ids), '');
+    out.push(...overviewTable(clean, ids), '');
     for (const id of ids) {
-        out.push(...section(id, registry[id]), '');
+        out.push(...section(id, clean[id]), '');
     }
     return out.join('\n');
 }
+/**
+ * The registry with every string its author controls stripped of control
+ * characters (ATX-58).
+ *
+ * **At the entry rather than at each emitter**, which is the whole of why this
+ * defect existed. ATX-37 put every byte the *CLI* prints through `control`, and
+ * this document is built by concatenation that never went past it — so a
+ * statement carrying `ESC [2K CR` erased the reviewer's line and repainted a
+ * verdict, from `attest render` with no flag at all. Sanitising here means a
+ * field added to `Requirement` later is covered by having been added, instead of
+ * by someone remembering; four call sites each doing it is the arrangement that
+ * produced the gap in the first place.
+ *
+ * **Over the document, not over stdout.** The obvious fix — sanitise the
+ * terminal write — is wrong, and the loop that found this said so: `--out`
+ * carried the payload into the file too. That file is committed, served, and
+ * read later by `cat`, by `less -R`, or by a site generator, so the artifact
+ * outlives the run and the run is the wrong place to defend. It also keeps
+ * `--check` honest, since both sides of the comparison are built from here.
+ *
+ * Ids are not sanitised and need not be: `RegistrySchema` holds every key to
+ * `^[A-Z]+-\d+$` on **both** reader paths — the static one by construction, the
+ * evaluating one since ATX-38 — so no id can carry a control character to begin
+ * with. The container is still built without a prototype, for the reason
+ * `red-record.ts` builds its own that way: that grammar is held somewhere else,
+ * and a defence that reads an inherited key when the other one lapses is not a
+ * defence. `Object.entries` and the sort below see own keys either way.
+ */
+function sanitised(registry) {
+    const out = Object.create(null);
+    for (const [id, req] of Object.entries(registry)) {
+        out[id] = {
+            statement: control(req.statement),
+            rationale: control(req.rationale),
+            params: Object.fromEntries(Object.entries(req.params).map(([k, v]) => [control(k), sanitisedValue(v)])),
+            outOfScope: req.outOfScope.map(control),
+        };
+    }
+    return out;
+}
+/** A param value with its strings sanitised; numbers and booleans have none. */
+function sanitisedValue(value) {
+    if (Array.isArray(value))
+        return value.map((v) => (typeof v === 'string' ? control(v) : v));
+    return typeof value === 'string' ? control(value) : value;
+}
 /**
  * Line endings are a checkout artifact, not content.
  *
@@ -85,23 +138,56 @@ export function staleIssue(target, current, fresh) {
         message: `${why} Regenerate it with: ${target.command}`,
     };
 }
+/**
+ * `AUTH-3` as its two ordering keys. An id this reader cannot take apart is its
+ * own prefix with no number, which is the reading `locate.ts`'s `idPrefix`
+ * gives — the two used to disagree, and one of them was wrong.
+ *
+ * `lastIndexOf('-')` with no guard was the old spelling, and on an id with no
+ * dash it silently dropped the last character (`AUTH` → prefix `AUT`) and
+ * produced `NaN` for the number. A comparator that answers `NaN` is not merely
+ * imprecise, it is **non-transitive**: measured on
+ * `['AUTH-3','AUTH-abc','AUTH-2']` the result was `AUTH-3, AUTH-abc, AUTH-2`,
+ * which is not a sorted permutation of anything. Both cases are handled here so
+ * the comparator below is total by construction rather than by the input
+ * happening to be well-formed.
+ */
+function orderingKey(id) {
+    const at = id.indexOf('-');
+    const tail = at === -1 ? '' : id.slice(at + 1);
+    if (at === -1 || !/^\d+$/.test(tail))
+        return [id, -1];
+    return [id.slice(0, at), Number(tail)];
+}
 /**
  * Order ids the way a reader expects: prefix alphabetically, then the number
  * numerically. A plain string sort puts ATX-10 between ATX-1 and ATX-2, which
  * scrambles the document as soon as a registry reaches ten requirements.
+ *
+ * Total, and a function of the ids alone. `renderMarkdown` feeds `--check`, so
+ * an order that depends on anything else — the locale, the insertion order, the
+ * engine's tie-breaking — is a freshness gate that can disagree with the run
+ * that generated the file it is checking.
+ *
+ * A malformed id cannot reach here through any command: `RequirementIdSchema`
+ * rejects it and `render` returns early on a registry that failed to load. That
+ * is why this is robustness rather than a fix — the property being bought is
+ * that the function is correct on its own terms instead of correct because
+ * something upstream is.
  */
 function compareIds(a, b) {
-    const split = (id) => {
-        const at = id.lastIndexOf('-');
-        return [id.slice(0, at), Number(id.slice(at + 1))];
-    };
-    const [prefixA, numA] = split(a);
-    const [prefixB, numB] = split(b);
+    const [prefixA, numA] = orderingKey(a);
+    const [prefixB, numB] = orderingKey(b);
     // byCodeUnit, not localeCompare: the ordering has to be identical on every
     // machine, or `--check` would flap with the runner's locale.
     if (prefixA !== prefixB)
         return byCodeUnit(prefixA, prefixB);
-    return numA - numB;
+    if (numA !== numB)
+        return numA - numB;
+    // Same prefix and same number is only reachable for ids this reader could not
+    // take apart. Falling back to the whole id keeps the order total rather than
+    // leaving it to the sort's stability, which is a property of the engine.
+    return byCodeUnit(a, b);
 }
 /**
  * An index of the whole registry: id + the promise itself. Deliberately carries
@@ -166,14 +252,43 @@ function formatValue(value) {
  * at either end needs padding spaces.
  */
 function code(value) {
-    const longest = Math.max(0, ...[...value.matchAll(/`+/g)].map((m) => m[0].length));
+    // Accumulated, never `Math.max(0, ...runs)` (ATX-59). The spread puts one
+    // argument on the stack per backtick run, so a param holding a few hundred
+    // thousand of them exhausted it — `RangeError` out of `attest render` under
+    // the static reader, with the stack naming this function. Not backtracking,
+    // and found only by sweeping for more of it: same reachable path, same
+    // registry-chooses-the-cost shape, different mechanism.
+    let longest = 0;
+    for (const run of value.matchAll(/`+/g))
+        longest = Math.max(longest, run[0].length);
     const fence = '`'.repeat(longest + 1);
     const pad = value.startsWith('`') || value.endsWith('`') ? ' ' : '';
     return `${fence}${pad}${value}${pad}${fence}`;
 }
-/** Make prose safe inside a table cell: no row-breaking pipes, no newlines. */
+/**
+ * Make prose safe inside a table cell: no row-breaking pipes, no newlines.
+ *
+ * Each maximal whitespace run is matched once and inspected, rather than
+ * matched by the old starred-`\s`, `\n`, starred-`\s` pattern (ATX-59). That
+ * spelling puts a required character after a leading quantifier, so a
+ * whitespace run with no newline in it was consumed, failed, and re-tried one
+ * character shorter from every position in the run — quadratic, and 8.6 seconds
+ * of CPU for 120,000 spaces in one statement, reachable through `render
+ * --check` in CI without executing a line of the project.
+ *
+ * The obvious repair does not work and was measured before this one was
+ * written: `[^\S\n]*\n[^\S\n]*`, which stops the class matching the newline,
+ * came out *slower*. The backtracking was never about which characters the
+ * class held — it was about the quantifier having something after it. `\s+`
+ * has nothing after it, so there is no failure to backtrack into, and the
+ * decision moves to the callback. Byte-identical to the old pattern: a
+ * whitespace run containing a newline collapses to one space, and a run
+ * without one is left exactly as it was.
+ */
 function cell(text) {
-    return text.replace(/\s*\n\s*/g, ' ').replace(/\|/g, '\\|');
+    return text
+        .replace(/\s+/g, (ws) => (ws.includes('\n') ? ' ' : ws))
+        .replace(/\|/g, '\\|');
 }
 /** GitHub/GitLab slug for a `## AUTH-3` heading. */
 function anchor(id) {

package/dist/core/req-suite.d.ts

@@ -0,0 +1,5 @@
+/** How `requirement(id)` names its describe block. */
+export declare function requirementSuiteName(id: string): string;
+/** The requirement id a suite name carries, or `undefined` if it carries none. */
+export declare function requirementIdOf(suiteName: string): string | undefined;
+//# sourceMappingURL=req-suite.d.ts.map

package/dist/core/req-suite.js

@@ -0,0 +1,27 @@
+// The one spelling of the suite name that carries a requirement id.
+//
+// `requirement()` writes it, `runner.ts` reads it back out of the serialized
+// task tree, and the runtime's own guard reads it to find the requirement that
+// owns a scenario. That is three readers of one encoding, across a process
+// boundary — the task tree is the only channel that crosses it (design §5.4) —
+// and two spellings of one encoding are two encodings the moment either is
+// edited.
+//
+// Deliberately free of any `vitest` import, so both sides of the engine ↔
+// runner boundary (`tests/import-boundary.spec.ts`) can depend on it.
+/** How `requirement(id)` names its describe block. */
+export function requirementSuiteName(id) {
+    return `[${id}]`;
+}
+/**
+ * `.+` rather than something narrower: a delta may propose an id the registry's
+ * grammar would refuse, and this has to round-trip whatever `requirement()`
+ * wrote so the two readers agree about it (the call `readDeltaSource` makes for
+ * the same reason).
+ */
+const REQ_SUITE = /^\[(.+)\]$/;
+/** The requirement id a suite name carries, or `undefined` if it carries none. */
+export function requirementIdOf(suiteName) {
+    return REQ_SUITE.exec(suiteName)?.[1];
+}
+//# sourceMappingURL=req-suite.js.map

package/dist/core/runner.js

@@ -5,9 +5,8 @@
 import { startVitest } from 'vitest/node';
 import { configDefaults } from 'vitest/config';
 import { relativePath } from './paths.js';
+import { requirementIdOf } from './req-suite.js';
 import { byCodeUnit } from './order.js';
-/** requirement() names each describe block `[reqId]`; recover the id from that. */
-const REQ_SUITE = /^\[(.+)\]$/;
 /**
  * Vitest's own default exclusions, which every Attest run keeps on top of
  * whatever else it excludes.
@@ -73,18 +72,15 @@ export async function runAndCollect(options = {}) {
         // Reconstruct coverage from the task tree (not an in-process singleton).
         const walk = (task) => {
             if (task.type === 'suite') {
-                const m = REQ_SUITE.exec(task.name);
-                if (m) {
-                    const id = m[1];
+                const id = requirementIdOf(task.name);
+                if (id !== undefined) {
                     const set = runtimeCoverage.get(id) ?? new Set();
                     const byName = outcomes.get(id) ?? new Map();
-                    for (const c of task.tasks ?? []) {
+                    for (const c of scenariosUnder(task)) {
                         // A scenario counts as covered only if it actually executed —
                         // skipped/todo scenarios have no run result (enables §8's
                         // declared-not-run check). The same test decides whether there is
                         // an outcome to record: a skip is not a red (design §6).
-                        if (c.type !== 'test')
-                            continue;
                         const outcome = executedOutcome(c);
                         if (!outcome)
                             continue;
@@ -126,6 +122,28 @@ export async function runAndCollect(options = {}) {
         await vitest.close();
     }
 }
+/**
+ * Every scenario belonging to a requirement suite, at any depth beneath it.
+ *
+ * Direct children only was the other half of the nested-`describe` defect: a
+ * scenario grouped under one is a `test` inside a `suite` inside `[reqId]`, so
+ * even once the runtime stopped throwing it would have been invisible here —
+ * `declared-not-run`, for a scenario that ran and passed. The static parser has
+ * always recursed (`parser.ts` walks the whole subtree), and this is the seam
+ * where the two readers of one plan have to agree.
+ *
+ * Descent stops at a nested requirement suite, so a `requirement()` written
+ * inside another one keeps its own scenarios rather than donating them upward.
+ */
+function* scenariosUnder(suite) {
+    for (const child of suite.tasks ?? []) {
+        if (child.type === 'test')
+            yield child;
+        else if (child.type === 'suite' && requirementIdOf(child.name) === undefined) {
+            yield* scenariosUnder(child);
+        }
+    }
+}
 /**
  * Did this file fail before any of its tests could exist?
  *

package/dist/core/skill.js

@@ -34,6 +34,9 @@
 // workflow to an agent that trusts it. The backstop is that every mistake it
 // could cause is a diagnostic with a fix hint — a registry written the old way
 // is `registry-not-static`, and the agent corrects itself from the report.
+// It has happened once, so: read this file when a release adds a diagnostic.
+// Nothing gates that — `ATX-57` catches a code the engine cannot emit, never one
+// it can.
 /**
  * The one sentence that decides whether the workflow is ever loaded.
  *
@@ -283,9 +286,10 @@ once. Branch on \`issues[].code\`, never on \`message\`:
 | \`tests-red\` | a test is failing — the normal state until you are finished |
 | \`never-red\` | an added requirement's scenario has no recorded failing run |
 | \`uncovered-requirement\` | a requirement in the applied registry has no scenario |
-| \`declared-not-run\` | a scenario was declared but never executed (\`skip\` / \`only\`?) |
+| \`declared-not-run\` | a scenario was declared but never executed (\`skip\` / \`only\`?) — withdrawn when one of the two rows below already explains its file, so it never stands in for a load failure |
+| \`spec-load-failed\` | a spec file could not be imported, so nothing in it ran. The run output carries the import error itself; this names which file it stopped |
 | \`proposed-spec-unclaimed\` | a \`*.proposed.spec.ts\` no change's delta claims |
-| \`added-id-unmerged\` | a spec failed to load, and this change adds an id the registry on disk lacks |
+| \`added-id-unmerged\` | the same load failure, when this change also adds an id the registry on disk lacks. The specific case, and the only one reported for that file |
 | \`unbound-param\` | a \`{placeholder}\` has no matching \`params\` key |
 | \`registry-not-static\` | a registry file is not a literal the engine can read |
 | \`add-conflict\` | the delta adds an id that already exists with different content |