@am_shork/attest 0.9.1 → 0.9.3

package/README.md

@@ -167,7 +167,7 @@ Every diagnostic carries a `code`, and every code has a section in
 ```
 ERROR   registry-not-static (requirements/upload.reqs.ts:5)
     Value is not a literal.
-    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.1/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.3/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section
@@ -180,6 +180,7 @@ isn't. In `--json` the same link is on each issue as `docsUrl`.
 | **CLI reference** — every command, flag and JSON field | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/cli-reference.md) |
 | **Troubleshooting** — one section per issue code | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/troubleshooting.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/troubleshooting.md) |
 | **Design** — the authoritative design of the framework | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/attest-design.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/attest-design.md) |
+| **Judging your own intent layer** — what no gate checks, and a method for it | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/intent-quality.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/intent-quality.md) |
 | **Feedback template** — report how adoption actually went | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/feedback.template.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/feedback.template.md) |
 
 The change workflow is not here: it is what `attest init` writes into your

package/dist/core/archive.d.ts

@@ -0,0 +1,59 @@
+import type { RedRecord } from './red-record.js';
+/** One archived change folder, as this module found it. */
+export interface ArchivedChange {
+    /** The folder name, `<YYYY-MM-DD>-<changeName>` as `--apply` spelled it. */
+    readonly name: string;
+    /**
+     * The folder relative to the project root, through `relativePath`.
+     *
+     * Not `join`ed by a caller from {@link ArchivedChange.name}: a value derived
+     * from the root is spelled one way here or it becomes a report field and a
+     * comparison key that depends on the host platform (`paths.ts`).
+     */
+    readonly path: string;
+    /**
+     * What this change's `first-run.json` holds, or an empty record.
+     *
+     * Empty covers both "the folder carries no record" and "the record did not
+     * validate", which `readRedRecordIn` does not distinguish — deliberately, and
+     * the same way round as the gate: an unreadable record is exactly as strict
+     * as a missing one. Kept per change rather than only merged so a caller can
+     * say which folders contributed nothing, which is the difference between a
+     * report and an assertion about an archive nobody counted.
+     */
+    readonly firstRun: RedRecord;
+}
+/** Everything `archive/` says about first runs, and where it said it. */
+export interface ArchivedEvidence {
+    /** Every archived change folder, in folder-name order. */
+    readonly changes: readonly ArchivedChange[];
+    /** Their records merged. See {@link keepOutcome} for the precedence. */
+    readonly firstRun: RedRecord;
+}
+/**
+ * Read every archived change folder under `root`.
+ *
+ * A missing `archive/` is an empty list rather than an error: a project that has
+ * archived nothing is the normal state, and it is the state every project starts
+ * in. Directories only — a symbolic link is not followed, because this walks a
+ * tree to report on it and following one would let a link decide which files a
+ * report describes.
+ *
+ * Ordered by folder name, which is `<date>-<name>` and so is chronological, and
+ * through the same code-unit comparator as everything else this tool commits or
+ * compares — the report is then a function of the input rather than of the order
+ * a filesystem happened to hand back.
+ */
+export declare function readArchivedChanges(root: string): Promise<ArchivedChange[]>;
+/**
+ * The archive's first-run evidence, merged across every archived change.
+ *
+ * One `RedRecord` rather than a list to search, because the three questions a
+ * caller has of it are the three `recordedOutcome` already answers, at the
+ * granularity the gate leaves open: this scenario was observed failing; this
+ * scenario's id never came through the workflow; this id did and this scenario
+ * is not in it. Merging costs nothing else — the reader, the validator and the
+ * accessors are the ones the gate uses, unchanged.
+ */
+export declare function readArchivedEvidence(root: string): Promise<ArchivedEvidence>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/core/archive.js

@@ -0,0 +1,142 @@
+// The read side of `archive/`, which until now had none.
+//
+// `--apply` moves a change folder whole into `archive/<date>-<name>/`
+// (`merge.ts`), carrying `proposal.md`, the delta and `first-run.json` — why the
+// change was agreed, every id it touched, and the recorded failing run behind
+// each one it ADDed. Nothing read any of it back: `archive` is in `locate.ts`'s
+// scan exclusions, in `runner.ts`'s child-run exclusions and in `pipeline.ts`'s.
+//
+// **Those exclusions stay exactly as they are.** They are design §7 and §8 — an
+// archived change's requirements and specs must not re-enter a normal run — and
+// nothing here relaxes them. This module walks `archive/` on its own terms, for
+// facts *about* archived changes rather than to fold their contents back into a
+// registry or a plan.
+//
+// **Only `first-run.json` is read, and that is a selection rather than a first
+// instalment.** It is the typed half: a `RedRecord` in a versioned envelope,
+// schema-validated on read and discarded whole if it does not parse
+// (`red-record.ts`). `proposal.md` is prose, and in this repository it is a
+// pointer — `CLAUDE.md` makes `CHANGELOG.md` the single decision record, so a
+// proposal restating an argument would be a second store of it with nothing
+// comparing the two. There is nothing in the prose half for an index to offer
+// but its path.
+//
+// **What the merged record is for.** Design §11 records that the never-red
+// guarantee is a property of the `changes/` workflow, not of the registry as a
+// whole, so nothing else in the tool can say across a project which scenarios
+// were ever observed failing. Note the granularity: the gate blocks on *every*
+// scenario of an ADDED id (`gate.ts`), so asking this per requirement comes back
+// yes for every archived id and answers nothing. Where the gate genuinely stops
+// is one level down — a scenario grown onto a requirement after it archived
+// carries no obligation, because `never-red` fires only on ids a change is
+// currently ADDing, and MODIFIED carries no such obligation at all. Those are
+// the absences this record makes visible, and a `RedRecord` answers them
+// directly: an id absent from it never came through the workflow, while an id
+// present without a given scenario is one that did and then drifted.
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { byCodeUnit } from './order.js';
+import { relativePath } from './paths.js';
+import { keepOutcome, readRedRecordIn } from './red-record.js';
+/** The directory archived changes are moved into, under the project root. */
+const ARCHIVE_DIR = 'archive';
+/**
+ * Read every archived change folder under `root`.
+ *
+ * A missing `archive/` is an empty list rather than an error: a project that has
+ * archived nothing is the normal state, and it is the state every project starts
+ * in. Directories only — a symbolic link is not followed, because this walks a
+ * tree to report on it and following one would let a link decide which files a
+ * report describes.
+ *
+ * Ordered by folder name, which is `<date>-<name>` and so is chronological, and
+ * through the same code-unit comparator as everything else this tool commits or
+ * compares — the report is then a function of the input rather than of the order
+ * a filesystem happened to hand back.
+ */
+export async function readArchivedChanges(root) {
+    const dir = join(root, ARCHIVE_DIR);
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const names = entries
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort(byCodeUnit);
+    return Promise.all(names.map(async (name) => {
+        const path = join(dir, name);
+        return { name, path: relativePath(root, path), firstRun: await readRedRecordIn(path) };
+    }));
+}
+/**
+ * The archive's first-run evidence, merged across every archived change.
+ *
+ * One `RedRecord` rather than a list to search, because the three questions a
+ * caller has of it are the three `recordedOutcome` already answers, at the
+ * granularity the gate leaves open: this scenario was observed failing; this
+ * scenario's id never came through the workflow; this id did and this scenario
+ * is not in it. Merging costs nothing else — the reader, the validator and the
+ * accessors are the ones the gate uses, unchanged.
+ */
+export async function readArchivedEvidence(root) {
+    const changes = await readArchivedChanges(root);
+    return { changes, firstRun: mergeRecords(changes.map((c) => c.firstRun)) };
+}
+/**
+ * Fold records into one, `fail` winning.
+ *
+ * The precedence is `keepOutcome`'s and is order-independent, so nothing here
+ * depends on the order `readArchivedChanges` returned — which matters because
+ * one id can legitimately appear in two archived changes (removed, then added
+ * again) and neither folder's date makes its observation the truer one.
+ *
+ * Built into prototype-free maps at every level for the reason `red-record.ts`
+ * gives at length: the keys are requirement ids, paths and scenario names read
+ * off disk, and evidence that can be inherited is not evidence. The records
+ * being merged already have no prototype; the container this builds must not
+ * reintroduce one.
+ */
+function mergeRecords(records) {
+    const merged = Object.create(null);
+    for (const record of records) {
+        for (const [reqId, byFile] of Object.entries(record)) {
+            const files = (merged[reqId] ??= Object.create(null));
+            for (const [file, outcomes] of Object.entries(byFile)) {
+                const kept = (files[file] ??= Object.create(null));
+                for (const [name, outcome] of Object.entries(outcomes)) {
+                    kept[name] = keepOutcome(kept[name], outcome);
+                }
+            }
+        }
+    }
+    return sortRecord(merged);
+}
+/**
+ * Rebuild the record in key order at every level.
+ *
+ * The same byte-stability rule `mergeRedRecord` and `render` follow: two
+ * machines reading one archive produce one document, so key order has to be a
+ * function of the data rather than of insertion. `sortDeep` is not used because
+ * it would have to be told these containers must stay prototype-free.
+ */
+function sortRecord(record) {
+    const sorted = Object.create(null);
+    for (const reqId of Object.keys(record).sort(byCodeUnit)) {
+        const byFile = record[reqId];
+        const files = Object.create(null);
+        for (const file of Object.keys(byFile).sort(byCodeUnit)) {
+            const outcomes = byFile[file];
+            const names = Object.create(null);
+            for (const name of Object.keys(outcomes).sort(byCodeUnit))
+                names[name] = outcomes[name];
+            files[file] = names;
+        }
+        sorted[reqId] = files;
+    }
+    return sorted;
+}
+//# sourceMappingURL=archive.js.map

package/dist/core/red-record.d.ts

@@ -1,5 +1,19 @@
 import type { AttestPlan, Outcome, RunResult, ScenarioRef } from './types.js';
-/** Where the record lives, relative to the project root. */
+/**
+ * Where the record lives inside a change folder, wherever that folder is.
+ *
+ * **The unit is the folder, not the project plus a name**, because `--apply`
+ * moves the folder whole into `archive/<date>-<name>/` (`merge.ts`) and this
+ * file travels inside it. An archived record is therefore the same file at a
+ * different path, not a different format — so a reader spelled `root` +
+ * `changeName` could not reach it, and that is exactly where the reading side
+ * stopped: the archive is written and nothing reads it back.
+ *
+ * The two spellings below are the two places a change folder is, and they are
+ * the whole of the difference.
+ */
+export declare function redRecordPathIn(changeDir: string): string;
+/** Where the record lives for a change still in flight, from the project root. */
 export declare function redRecordPath(root: string, changeName: string): string;
 /** The file name, exported so a diagnostic can name it without rebuilding it. */
 export declare const RED_RECORD_FILE = "first-run.json";
@@ -34,6 +48,16 @@ export type RedRecord = Record<string, Record<string, Record<string, Outcome>>>;
  * the whole one.
  */
 export declare function readRedRecord(root: string, changeName: string): Promise<RedRecord>;
+/**
+ * The same read, against a change folder given directly.
+ *
+ * Every rule in the comment above is this function's; `readRedRecord` is the
+ * in-flight spelling of it. Split out rather than parameterised on a directory
+ * name because an archived folder is not a variant of `changes/` — it is the
+ * same folder after `--apply` moved it, and naming the folder says so where a
+ * `'changes' | 'archive'` argument would invite a caller to pick.
+ */
+export declare function readRedRecordIn(changeDir: string): Promise<RedRecord>;
 /**
  * What the record says about one scenario, or undefined if it never saw it.
  *
@@ -54,6 +78,21 @@ export declare function recordedOutcome(record: RedRecord, ref: ScenarioRef): Ou
  * `uncoveredIssues` from the commands that had a copy each.
  */
 export declare function hasRecordedRed(record: RedRecord, ref: ScenarioRef): boolean;
+/**
+ * Which of two observations of one scenario the record keeps.
+ *
+ * **Monotonic toward `fail`**: a recorded fail is final, a recorded pass can
+ * still be corrected by a real one. The reasoning is at the top of this file;
+ * what is here is the one place it is decided, because two callers now decide
+ * on it — a run being folded into a change's record, and two records being
+ * merged. A second spelling of `=== 'fail'` would let them disagree about what
+ * the same pair of observations means, which is the argument that gave
+ * `hasRecordedRed` its single definition.
+ *
+ * Order-independent by construction — `keepOutcome(a, b)` and `keepOutcome(b, a)`
+ * agree — so a caller merging many records owes no sequencing rule.
+ */
+export declare function keepOutcome(existing: Outcome | undefined, incoming: Outcome): Outcome;
 /**
  * Fold this run's outcomes into the record, for the scenarios that carry an
  * obligation — those covering a requirement this change ADDs.

package/dist/core/red-record.js

@@ -97,9 +97,35 @@ function fileKey(file) {
 function emptyMap() {
     return Object.create(null);
 }
-/** Where the record lives, relative to the project root. */
+/**
+ * Where the record lives inside a change folder, wherever that folder is.
+ *
+ * **The unit is the folder, not the project plus a name**, because `--apply`
+ * moves the folder whole into `archive/<date>-<name>/` (`merge.ts`) and this
+ * file travels inside it. An archived record is therefore the same file at a
+ * different path, not a different format — so a reader spelled `root` +
+ * `changeName` could not reach it, and that is exactly where the reading side
+ * stopped: the archive is written and nothing reads it back.
+ *
+ * The two spellings below are the two places a change folder is, and they are
+ * the whole of the difference.
+ */
+export function redRecordPathIn(changeDir) {
+    return join(changeDir, RED_RECORD_FILE);
+}
+/** Where the record lives for a change still in flight, from the project root. */
 export function redRecordPath(root, changeName) {
-    return join(root, 'changes', changeName, RED_RECORD_FILE);
+    return redRecordPathIn(inFlightChangeDir(root, changeName));
+}
+/**
+ * The folder a change occupies before it is archived.
+ *
+ * One spelling, because both public entry points below would otherwise carry a
+ * copy of `'changes'` and they must not be able to disagree about where a
+ * record is read from versus where a diagnostic says it is.
+ */
+function inFlightChangeDir(root, changeName) {
+    return join(root, 'changes', changeName);
 }
 /** The file name, exported so a diagnostic can name it without rebuilding it. */
 export const RED_RECORD_FILE = 'first-run.json';
@@ -132,9 +158,21 @@ const RedRecordSchema = z.record(z.string(), z.record(z.string(), z.record(z.str
  * the whole one.
  */
 export async function readRedRecord(root, changeName) {
+    return readRedRecordIn(inFlightChangeDir(root, changeName));
+}
+/**
+ * The same read, against a change folder given directly.
+ *
+ * Every rule in the comment above is this function's; `readRedRecord` is the
+ * in-flight spelling of it. Split out rather than parameterised on a directory
+ * name because an archived folder is not a variant of `changes/` — it is the
+ * same folder after `--apply` moved it, and naming the folder says so where a
+ * `'changes' | 'archive'` argument would invite a caller to pick.
+ */
+export async function readRedRecordIn(changeDir) {
     let raw;
     try {
-        raw = await readFile(redRecordPath(root, changeName), 'utf8');
+        raw = await readFile(redRecordPathIn(changeDir), 'utf8');
     }
     catch {
         return emptyMap();
@@ -218,6 +256,23 @@ export function recordedOutcome(record, ref) {
 export function hasRecordedRed(record, ref) {
     return recordedOutcome(record, ref) === 'fail';
 }
+/**
+ * Which of two observations of one scenario the record keeps.
+ *
+ * **Monotonic toward `fail`**: a recorded fail is final, a recorded pass can
+ * still be corrected by a real one. The reasoning is at the top of this file;
+ * what is here is the one place it is decided, because two callers now decide
+ * on it — a run being folded into a change's record, and two records being
+ * merged. A second spelling of `=== 'fail'` would let them disagree about what
+ * the same pair of observations means, which is the argument that gave
+ * `hasRecordedRed` its single definition.
+ *
+ * Order-independent by construction — `keepOutcome(a, b)` and `keepOutcome(b, a)`
+ * agree — so a caller merging many records owes no sequencing rule.
+ */
+export function keepOutcome(existing, incoming) {
+    return existing === 'fail' ? 'fail' : incoming;
+}
 /**
  * Fold this run's outcomes into the record, for the scenarios that carry an
  * obligation — those covering a requirement this change ADDs.
@@ -259,11 +314,10 @@ export function mergeRedRecord(existing, plan, run, addedIds) {
             continue;
         const forId = (record[s.reqId] ??= emptyMap());
         const forFile = (forId[fileKey(s.file)] ??= emptyMap());
-        // Monotonic toward `fail`: a recorded fail is final, a recorded pass can
-        // still be corrected by a real one. See the note at the top of this file.
-        if (forFile[s.name] === 'fail' || forFile[s.name] === outcome)
+        const kept = keepOutcome(forFile[s.name], outcome);
+        if (kept === forFile[s.name])
             continue;
-        forFile[s.name] = outcome;
+        forFile[s.name] = kept;
         changed = true;
     }
     // Sort within each requirement, and within each file, for the same

package/dist/core/skill.js

@@ -318,6 +318,14 @@ blocks the gate with the suite fully green; so does a spec file that will not
 import, or a proposed spec no delta claims. A clean table plus green tests is
 still not a verdict — \`attest archive\` is the only thing that decides.
 
+**Three questions before you present it**, each a category no diagnostic reports:
+
+- **What pins each expectation** — a fixture, a literal, an independently
+  derived value; never the param the code under test consumed?
+- **Does each statement carry one obligation**, or several under one SHALL?
+- **Was any of this ever red**, or does part of it already work? \`never-red\`
+  asks for a recorded failing run only on the ids you ADD.
+
 Then present the proposal, the ids, and the red output, and **stop**. Wait for
 agreement before implementing.
 

package/dist/inspect.d.ts

@@ -0,0 +1,146 @@
+import type { Issue, ParsedScenario, Registry } from './core/types.js';
+export type { Issue, ParsedScenario, Registry, Requirement } from './core/types.js';
+/** What a project declares, read without executing any of it. */
+export interface Inspection {
+    /**
+     * Every requirement declared under the root, merged across registry files.
+     *
+     * A registry file that could not be read statically contributes nothing here
+     * and one entry to {@link Inspection.issues} — so an empty result never means
+     * "this project has no requirements" without the issues saying why.
+     */
+    readonly registry: Registry;
+    /**
+     * The scenarios each requirement id has, in declaration order.
+     *
+     * A `Map` rather than a record, and not only for the key type: a record keyed
+     * by ids from a file on disk is the `Object.prototype` hazard ATX-42 exists
+     * for, and a `Map` has no prototype chain to read a requirement out of. The
+     * cost is that `JSON.stringify` renders it as `{}` — a caller serialising
+     * this owes `Object.fromEntries`, and the type is a `Map` so that the
+     * conversion is a decision rather than a surprise.
+     *
+     * An id with no scenarios is absent rather than present-and-empty — the same
+     * distinction `cover` reports, and the one a coverage check is asking about.
+     */
+    readonly scenarios: ReadonlyMap<string, readonly ParsedScenario[]>;
+    /**
+     * Everything that stopped a *file* being read, in the shape every command
+     * reports: one unreadable file scraps itself and nothing else (ATX-65), which
+     * is what lets a caller report on the rest of the project.
+     *
+     * Not a promise that nothing throws. A root that cannot be walked at all is a
+     * caller's mistake rather than a finding about a project, and rejects.
+     */
+    readonly issues: readonly Issue[];
+}
+/**
+ * Read the requirements and scenarios declared under `root`, executing nothing.
+ *
+ * `root` is the project directory, resolved here so a relative one behaves the
+ * same as an absolute one rather than half-working: the walk would find the
+ * files either way, and only the relative paths in the result would be wrong,
+ * which is the shape of bug that survives a demo.
+ *
+ * Every `file` in the result is relative to that root and POSIX-spelled on
+ * every platform (`paths.ts`) — the spelling a caller can compare against and
+ * store, on a value that would otherwise carry the host's separator.
+ *
+ * The registry read and the spec parse are independent, so they run
+ * concurrently — each already bounds its own fan-out over a tree whose size is
+ * not ours to choose.
+ */
+export declare function inspectProject(root: string): Promise<Inspection>;
+/**
+ * What the archived first-run records say about one scenario a spec declares.
+ *
+ * Four values, not two, and the two absences are the reason. `'fail'` and
+ * `'pass'` are the record's own outcomes, spelled the same so a caller
+ * comparing against `'fail'` is comparing against the string the gate compares
+ * against. The other two are both "no observation", and folding them together
+ * would report a design working as intended as if it were a defect:
+ *
+ * - `'unarchived'` — this scenario's requirement appears in no archived change
+ *   at all. It was written straight into the registry, which is how existing
+ *   behaviour is described in a brownfield adoption, and it carries **no**
+ *   obligation to have been red. Nothing is wrong.
+ * - `'unobserved'` — the requirement *is* archived and this scenario is not in
+ *   the record. It was added after the change was archived, and nothing will
+ *   ever require it to have failed first: the gate raises `never-red` only for
+ *   ids a change is currently ADDing, and an archived id is ADDed by nothing
+ *   again. This is the one no gate can see.
+ *
+ * `'pass'` is a state the gate cannot produce — it blocks a change whose
+ * scenario passed on its first run — so an archived `'pass'` means the record
+ * was hand-edited or written by a format that has since moved. Reported rather
+ * than folded into the absences, because the fix is different.
+ *
+ * Attest computes which of the four holds and stops there. Whether an
+ * `'unobserved'` scenario matters is a judgement about that scenario, which is
+ * the caller's (design §0).
+ */
+export type ScenarioEvidence = 'fail' | 'pass' | 'unobserved' | 'unarchived';
+/** One declared scenario, and what the archive records about it. */
+export interface EvidenceRow {
+    readonly reqId: string;
+    /** The spec file, relative to the root and POSIX-spelled, as {@link ParsedScenario} spells it. */
+    readonly file: string;
+    readonly name: string;
+    readonly line: number;
+    readonly evidence: ScenarioEvidence;
+}
+/** An archived change folder the evidence was read from. */
+export interface ArchivedChangeRef {
+    /** The folder name, `<YYYY-MM-DD>-<change>`, as `archive --apply` spelled it. */
+    readonly name: string;
+    /** The folder relative to the root, POSIX-spelled. */
+    readonly path: string;
+}
+/** What {@link inspectRedEvidence} answers. */
+export interface RedEvidenceInspection {
+    /**
+     * One row per scenario declared under the root, in the order
+     * {@link Inspection.scenarios} lists them.
+     *
+     * Rows for *declared* scenarios rather than for recorded ones: the question is
+     * what today's suite can show about itself, so a record naming a scenario no
+     * spec declares any more contributes nothing here. It is not lost — the folder
+     * it came from is in {@link RedEvidenceInspection.archived} — but a row about
+     * a scenario that no longer exists is not something a caller can act on.
+     */
+    readonly scenarios: readonly EvidenceRow[];
+    /**
+     * Every archived change folder that was read, in folder-name order.
+     *
+     * Provenance, and it is load-bearing: an empty list means the project has
+     * archived nothing, in which case every row is `'unarchived'` and the report
+     * says nothing about the project rather than something bad about it.
+     */
+    readonly archived: readonly ArchivedChangeRef[];
+    /** Everything that stopped a file being read, exactly as {@link Inspection.issues}. */
+    readonly issues: readonly Issue[];
+}
+/**
+ * Join what a project declares against what its archive recorded, executing
+ * nothing.
+ *
+ * **Why this is not a field on {@link Inspection}.** It walks `archive/`, which
+ * most callers of {@link inspectProject} have no use for, and a reader should
+ * not pay a second tree walk to be told about requirements.
+ *
+ * **Why it returns rows rather than the records.** The record is a nested map
+ * keyed by requirement ids, paths and scenario names read off disk, and reading
+ * it correctly means never answering from an inherited key — the whole of the
+ * prototype argument `red-record.ts` carries. Handing that container to a caller
+ * would export the hazard along with the data. What is exported is the answer,
+ * at the granularity the question is asked.
+ *
+ * **What the granularity is, and why it is not the requirement.** The gate
+ * blocks a change unless *every* scenario of every id it ADDs was observed
+ * failing, so "did this requirement ever have red evidence" comes back yes for
+ * every archived id and answers nothing. Where the gate stops is one level down:
+ * a scenario grown onto a requirement after it archived, and a requirement whose
+ * statement a later change MODIFIED, which carries no such obligation at all.
+ */
+export declare function inspectRedEvidence(root: string): Promise<RedEvidenceInspection>;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/inspect.js

@@ -0,0 +1,123 @@
+// The static reading layer, as a second public entry point (design §10).
+//
+// Why it exists: everything this repository knows about the quality of its own
+// requirements is a hand-judged table in `tests/intent-rule-candidates.spec.ts`,
+// and the check that keeps such a table from rotting is "the scenario this row
+// names is one a spec really declares". An adopter could not write that check.
+// The package exported the authoring API and nothing else, so the ids, the
+// statements and above all the *scenario names* of their own project were
+// unreachable from outside — not merely undocumented, unreachable. That is what
+// this entry point answers, and the deliberate limit is that it answers only
+// that: it reports what a project declares, and judges none of it (design §0).
+//
+// **One function rather than the four internals it composes**, and the reason is
+// a security property rather than convenience. `loadRegistry` takes a
+// `RegistryReader`, and which reader runs is fixed by the command — never chosen
+// by a caller, never a fallback — because one of the two executes the project's
+// code and the other does not (design §5.1). Exporting the readers would hand
+// that choice to an adopter, which is the one thing the two-adapter seam must
+// never allow. What is exported therefore has the static reader welded in, and
+// there is no parameter that could change it.
+//
+// The same rule decides the import graph: nothing here may reach `vite` or
+// `vitest`, so a consumer that only analyses does not acquire the runner peer.
+// `tests/import-boundary.spec.ts` gates that rather than leaving it to review —
+// this module is on the short list of entry points whose closure is walked.
+import { resolve } from 'node:path';
+import { readArchivedEvidence } from './core/archive.js';
+import { loadRegistry, parseSpecs, scanProject, staticReader } from './core/locate.js';
+import { recordedOutcome } from './core/red-record.js';
+/**
+ * Read the requirements and scenarios declared under `root`, executing nothing.
+ *
+ * `root` is the project directory, resolved here so a relative one behaves the
+ * same as an absolute one rather than half-working: the walk would find the
+ * files either way, and only the relative paths in the result would be wrong,
+ * which is the shape of bug that survives a demo.
+ *
+ * Every `file` in the result is relative to that root and POSIX-spelled on
+ * every platform (`paths.ts`) — the spelling a caller can compare against and
+ * store, on a value that would otherwise carry the host's separator.
+ *
+ * The registry read and the spec parse are independent, so they run
+ * concurrently — each already bounds its own fan-out over a tree whose size is
+ * not ours to choose.
+ */
+export async function inspectProject(root) {
+    const projectRoot = resolve(root);
+    const { reqsFiles, specFiles } = await scanProject(projectRoot);
+    const [loaded, parsed] = await Promise.all([
+        loadRegistry(projectRoot, staticReader(), reqsFiles),
+        parseSpecs(specFiles, projectRoot),
+    ]);
+    const scenarios = new Map();
+    for (const scenario of parsed.plan.scenarios) {
+        const existing = scenarios.get(scenario.reqId);
+        if (existing === undefined)
+            scenarios.set(scenario.reqId, [scenario]);
+        else
+            existing.push(scenario);
+    }
+    return {
+        registry: loaded.registry,
+        scenarios,
+        // Registry issues before spec issues, and each already in sorted file
+        // order: the list is a function of the project rather than of which read
+        // finished first, so two runs over one tree answer identically.
+        issues: [...loaded.issues, ...parsed.issues],
+    };
+}
+/**
+ * Join what a project declares against what its archive recorded, executing
+ * nothing.
+ *
+ * **Why this is not a field on {@link Inspection}.** It walks `archive/`, which
+ * most callers of {@link inspectProject} have no use for, and a reader should
+ * not pay a second tree walk to be told about requirements.
+ *
+ * **Why it returns rows rather than the records.** The record is a nested map
+ * keyed by requirement ids, paths and scenario names read off disk, and reading
+ * it correctly means never answering from an inherited key — the whole of the
+ * prototype argument `red-record.ts` carries. Handing that container to a caller
+ * would export the hazard along with the data. What is exported is the answer,
+ * at the granularity the question is asked.
+ *
+ * **What the granularity is, and why it is not the requirement.** The gate
+ * blocks a change unless *every* scenario of every id it ADDs was observed
+ * failing, so "did this requirement ever have red evidence" comes back yes for
+ * every archived id and answers nothing. Where the gate stops is one level down:
+ * a scenario grown onto a requirement after it archived, and a requirement whose
+ * statement a later change MODIFIED, which carries no such obligation at all.
+ */
+export async function inspectRedEvidence(root) {
+    const projectRoot = resolve(root);
+    // Sequential rather than concurrent, unlike the two reads inside
+    // `inspectProject`: this is one tree walk after another over the same disk,
+    // and the archive holds only the folders of changes already merged — so
+    // overlapping them buys nothing worth a second fan-out.
+    const inspection = await inspectProject(projectRoot);
+    const { changes, firstRun } = await readArchivedEvidence(projectRoot);
+    const scenarios = [];
+    for (const [reqId, declared] of inspection.scenarios) {
+        // Own property only, and the distinction the two absences rest on: an id
+        // the archive never mentions is a different fact from an id it mentions
+        // without this scenario.
+        const archived = Object.hasOwn(firstRun, reqId);
+        for (const s of declared) {
+            const outcome = recordedOutcome(firstRun, { reqId, file: s.file, name: s.name });
+            scenarios.push({
+                reqId,
+                file: s.file,
+                name: s.name,
+                line: s.line,
+                evidence: outcome ?? (archived ? 'unobserved' : 'unarchived'),
+            });
+        }
+    }
+    return {
+        scenarios,
+        archived: changes.map((c) => ({ name: c.name, path: c.path })),
+        issues: inspection.issues,
+    };
+}
+//# sourceMappingURL=inspect.js.map