@am_shork/attest 0.4.3 → 0.5.0

package/dist/core/gate.d.ts

@@ -9,6 +9,15 @@ export interface GateInputs {
     run: RunResult;
     /** Ids this change ADDs — the scenarios that carry a first-red obligation. */
     addedIds?: readonly string[];
+    /**
+     * Of those, the ids the registry **on disk** does not have yet.
+     *
+     * Computed against the base registry rather than the applied one, because
+     * that is the registry the child run imports: the gate applies the delta in
+     * memory, and the suite is a separate process reading `*.reqs.ts` off the
+     * filesystem. The two disagreeing is the whole content of `added-id-unmerged`.
+     */
+    unmergedAddedIds?: readonly string[];
     /** First observed outcome per scenario, already merged with this run. */
     firstRun?: RedRecord;
 }
@@ -21,6 +30,32 @@ export interface GateInputs {
  * this framework is that agreement should be structural, not clerical.
  */
 export declare function declaredNotRunIssues(plan: AttestPlan, run: RunResult): Issue[];
+/**
+ * A spec file that failed to load, while the change adds ids the registry on
+ * disk does not have yet (design §8).
+ *
+ * The gate applies the delta in memory and hands the result to itself; the
+ * suite is a child process that imports `*.reqs.ts` from the filesystem. So
+ * implementation code doing exactly what the workflow requires —
+ * `reqs['FOG-4'].params.modestRisk` for an id the change *adds* — throws at
+ * import, every spec file transitively importing that module fails to load, and
+ * what the gate could see was `tests-red` plus a `declared-not-run` per
+ * scenario, whose message sends the reader to look for a `skip` or an `.only`
+ * that is not there. The change could not be made green by the documented
+ * workflow, and the verdict pointed away from the reason.
+ *
+ * This names the reason instead. It is a diagnosis, not a fix: the run still
+ * fails, and the way forward is still to merge the added requirement into the
+ * registry before running the gate. What it buys is that the reader is told
+ * that, rather than sent to audit their own spec files for a skip.
+ *
+ * The conjunction is the whole test, and it is deliberately a heuristic: a
+ * module can fail to import for reasons that have nothing to do with a
+ * requirement id. Naming an unmerged id when one exists is more useful than
+ * silence, so the message states the two facts and the inference between them
+ * rather than asserting a cause.
+ */
+export declare function unmergedIdIssues(run: RunResult, unmergedAddedIds: readonly string[]): Issue[];
 /**
  * Never-red: a scenario attesting a requirement this change ADDs, whose first
  * observed run did not fail (design §6, mechanism 2).
@@ -48,10 +83,12 @@ export declare function neverRedIssues(plan: AttestPlan, addedIds: readonly stri
  *      the registry+plan here are already the applied result, so one pass
  *      validates the end state.
  *   2. Executable: all tests green.
- *   3. Static coverage vs runtime coverage: every declared scenario actually
+ *   3. A spec file that failed to load while the change adds an id the registry
+ *      on disk lacks — the reason, named before the absences it causes.
+ *   4. Static coverage vs runtime coverage: every declared scenario actually
  *      ran (catches skip/only false coverage).
- *   4. Never-red: every scenario of an ADDED requirement failed on its first
+ *   5. Never-red: every scenario of an ADDED requirement failed on its first
  *      recorded run (design §6, mechanism 2).
  */
-export declare function evaluateGate({ registry, plan, run, addedIds, firstRun }: GateInputs): Issue[];
+export declare function evaluateGate({ registry, plan, run, addedIds, unmergedAddedIds, firstRun, }: GateInputs): Issue[];
 //# sourceMappingURL=gate.d.ts.map

package/dist/core/gate.js

@@ -29,6 +29,43 @@ export function declaredNotRunIssues(plan, run) {
     }
     return issues;
 }
+/**
+ * A spec file that failed to load, while the change adds ids the registry on
+ * disk does not have yet (design §8).
+ *
+ * The gate applies the delta in memory and hands the result to itself; the
+ * suite is a child process that imports `*.reqs.ts` from the filesystem. So
+ * implementation code doing exactly what the workflow requires —
+ * `reqs['FOG-4'].params.modestRisk` for an id the change *adds* — throws at
+ * import, every spec file transitively importing that module fails to load, and
+ * what the gate could see was `tests-red` plus a `declared-not-run` per
+ * scenario, whose message sends the reader to look for a `skip` or an `.only`
+ * that is not there. The change could not be made green by the documented
+ * workflow, and the verdict pointed away from the reason.
+ *
+ * This names the reason instead. It is a diagnosis, not a fix: the run still
+ * fails, and the way forward is still to merge the added requirement into the
+ * registry before running the gate. What it buys is that the reader is told
+ * that, rather than sent to audit their own spec files for a skip.
+ *
+ * The conjunction is the whole test, and it is deliberately a heuristic: a
+ * module can fail to import for reasons that have nothing to do with a
+ * requirement id. Naming an unmerged id when one exists is more useful than
+ * silence, so the message states the two facts and the inference between them
+ * rather than asserting a cause.
+ */
+export function unmergedIdIssues(run, unmergedAddedIds) {
+    if (unmergedAddedIds.length === 0)
+        return [];
+    return run.unloadedFiles.map((file) => ({
+        level: 'ERROR',
+        code: 'added-id-unmerged',
+        file,
+        message: `${file} failed to load, and this change adds ${unmergedAddedIds.join(', ')}, which the registry on disk does not have yet. ` +
+            `The suite runs against the registry files, not the applied registry the gate computed, so code reading a requirement this change adds throws at import. ` +
+            `Merge the added requirement into the registry and run the gate again: applying a delta whose ADDED entry already exists with identical content is a no-op, so the change still documents the intent.`,
+    }));
+}
 /**
  * Never-red: a scenario attesting a requirement this change ADDs, whose first
  * observed run did not fail (design §6, mechanism 2).
@@ -77,12 +114,14 @@ export function neverRedIssues(plan, addedIds, firstRun) {
  *      the registry+plan here are already the applied result, so one pass
  *      validates the end state.
  *   2. Executable: all tests green.
- *   3. Static coverage vs runtime coverage: every declared scenario actually
+ *   3. A spec file that failed to load while the change adds an id the registry
+ *      on disk lacks — the reason, named before the absences it causes.
+ *   4. Static coverage vs runtime coverage: every declared scenario actually
  *      ran (catches skip/only false coverage).
- *   4. Never-red: every scenario of an ADDED requirement failed on its first
+ *   5. Never-red: every scenario of an ADDED requirement failed on its first
  *      recorded run (design §6, mechanism 2).
  */
-export function evaluateGate({ registry, plan, run, addedIds, firstRun }) {
+export function evaluateGate({ registry, plan, run, addedIds, unmergedAddedIds, firstRun, }) {
     const blocking = [];
     // 1) Structure (end-state re-validation).
     blocking.push(...validateStructure(registry, plan).filter((i) => i.level === 'ERROR'));
@@ -94,9 +133,20 @@ export function evaluateGate({ registry, plan, run, addedIds, firstRun }) {
             message: 'Some tests are failing; the change cannot be archived.',
         });
     }
-    // 3) Declared-not-run: static coverage claimed, runtime never executed it.
-    blocking.push(...declaredNotRunIssues(plan, run));
-    // 4) Never-red: the added scenarios have to have discriminated once.
+    // 3) A file that failed to load, named before the absences it produces.
+    const unmerged = unmergedIdIssues(run, unmergedAddedIds ?? []);
+    blocking.push(...unmerged);
+    // 4) Declared-not-run: static coverage claimed, runtime never executed it.
+    //
+    // Scenarios in a file diagnosed just above are left out. Not because they
+    // ran — they could not have — but because "declared but never executed
+    // (skipped, or excluded by an .only?)" is one fact restated as a guess about
+    // a cause the line above has already established. Only when that line was
+    // emitted: with no diagnosis to replace it, a wrong message still beats
+    // silence, which is why `verify` keeps reporting them.
+    const diagnosed = new Set(unmerged.map((i) => i.file));
+    blocking.push(...declaredNotRunIssues(plan, run).filter((i) => !diagnosed.has(i.file)));
+    // 5) Never-red: the added scenarios have to have discriminated once.
     if (addedIds && addedIds.length > 0) {
         blocking.push(...neverRedIssues(plan, addedIds, firstRun ?? {}));
     }

package/dist/core/locate.d.ts

@@ -1,6 +1,24 @@
 import type { Loader } from './loader.js';
 import type { AttestPlan, Issue, Registry } from './types.js';
 export declare const isReqsFile: (name: string) => boolean;
+/**
+ * A spec belonging to a change that has not been agreed yet (design §7).
+ *
+ * The marker is in the **name** rather than the directory because the file
+ * already sits where it will live once the change is merged: a proposal's spec
+ * is written next to the code it attests, so its relative imports resolve
+ * identically before and after the merge, and merging renames it in place
+ * instead of moving it up a tree and rewriting every specifier.
+ */
+export declare const isProposedSpecFile: (name: string) => boolean;
+/**
+ * A spec belonging to the merged suite.
+ *
+ * Proposed specs are excluded here rather than at each call site, so the base
+ * scan, the base run and every reporting command are wrong together or not at
+ * all: a red scenario for behaviour nobody has implemented must not reach any
+ * of them until its gate passes.
+ */
 export declare const isSpecFile: (name: string) => boolean;
 /**
  * Recursively find files under root whose basename matches `match`.
@@ -11,16 +29,21 @@ export declare const isSpecFile: (name: string) => boolean;
  * order never depends on which `readdir` happened to resolve first.
  */
 export declare function findFiles(root: string, match: (name: string) => boolean): Promise<string[]>;
-/** The two file sets every command needs, collected in one pass. */
+/** The file sets every command needs, collected in one pass. */
 export interface ProjectScan {
     reqsFiles: string[];
     specFiles: string[];
+    /** Specs of changes still under review; never part of the base suite. */
+    proposedSpecFiles: string[];
 }
 /**
  * Find the registry and spec files under root in a **single** traversal.
  *
  * Calling findFiles once per pattern meant `check` walked the tree twice and
- * `archive` four times, over a tree that cannot change in between.
+ * `archive` four times, over a tree that cannot change in between. Proposed
+ * specs are collected in the same pass for that reason and kept in their own
+ * list: they are found everywhere the merged ones are, and no caller may reach
+ * them by accident.
  */
 export declare function scanProject(root: string): Promise<ProjectScan>;
 /** One file's worth of registry, or the single issue that stopped it. */
@@ -92,8 +115,6 @@ export declare function loadRegistry(root: string, reader: RegistryReader, files
 export declare function parseSpecs(files: string[], displayRoot: string): Promise<AttestPlan>;
 /** Parse every `*.spec.ts` under root into one merged plan (file paths shown relative to root). */
 export declare function parseAllSpecFiles(root: string): Promise<AttestPlan>;
-/** Parse the spec files belonging to a single proposed change (design §8). */
-export declare function parseChangeSpecs(root: string, changeName: string): Promise<AttestPlan>;
 /** List the names of proposed changes under `root/changes`. */
 export declare function listChangeNames(root: string): Promise<string[]>;
 //# sourceMappingURL=locate.d.ts.map

package/dist/core/locate.js

@@ -20,7 +20,25 @@ const SKIP_DIRS = new Set([
     'archive',
 ]);
 export const isReqsFile = (name) => name.endsWith('.reqs.ts');
-export const isSpecFile = (name) => name.endsWith('.spec.ts');
+/**
+ * A spec belonging to a change that has not been agreed yet (design §7).
+ *
+ * The marker is in the **name** rather than the directory because the file
+ * already sits where it will live once the change is merged: a proposal's spec
+ * is written next to the code it attests, so its relative imports resolve
+ * identically before and after the merge, and merging renames it in place
+ * instead of moving it up a tree and rewriting every specifier.
+ */
+export const isProposedSpecFile = (name) => name.endsWith('.proposed.spec.ts');
+/**
+ * A spec belonging to the merged suite.
+ *
+ * Proposed specs are excluded here rather than at each call site, so the base
+ * scan, the base run and every reporting command are wrong together or not at
+ * all: a red scenario for behaviour nobody has implemented must not reach any
+ * of them until its gate passes.
+ */
+export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpecFile(name);
 /**
  * Recursively find files under root whose basename matches `match`.
  *
@@ -53,19 +71,29 @@ export async function findFiles(root, match) {
  * Find the registry and spec files under root in a **single** traversal.
  *
  * Calling findFiles once per pattern meant `check` walked the tree twice and
- * `archive` four times, over a tree that cannot change in between.
+ * `archive` four times, over a tree that cannot change in between. Proposed
+ * specs are collected in the same pass for that reason and kept in their own
+ * list: they are found everywhere the merged ones are, and no caller may reach
+ * them by accident.
  */
 export async function scanProject(root) {
-    const files = await findFiles(root, (n) => isReqsFile(n) || isSpecFile(n));
+    const files = await findFiles(root, (n) => isReqsFile(n) || isSpecFile(n) || isProposedSpecFile(n));
     const reqsFiles = [];
     const specFiles = [];
+    const proposedSpecFiles = [];
     for (const f of files) {
-        if (isReqsFile(basename(f)))
+        const name = basename(f);
+        // Sorted by `isSpecFile` rather than by `isProposedSpecFile`, so what makes
+        // a spec part of the merged suite is decided in exactly one place: the two
+        // predicates would otherwise both have to be right about the same file.
+        if (isReqsFile(name))
             reqsFiles.push(f);
-        else
+        else if (isSpecFile(name))
             specFiles.push(f);
+        else
+            proposedSpecFiles.push(f);
     }
-    return { reqsFiles, specFiles };
+    return { reqsFiles, specFiles, proposedSpecFiles };
 }
 /**
  * Read registries by **executing** the module through the Vite loader.
@@ -251,11 +279,6 @@ export async function parseSpecs(files, displayRoot) {
 export async function parseAllSpecFiles(root) {
     return parseSpecs(await findFiles(root, isSpecFile), root);
 }
-/** Parse the spec files belonging to a single proposed change (design §8). */
-export async function parseChangeSpecs(root, changeName) {
-    const dir = join(root, 'changes', changeName);
-    return parseSpecs(await findFiles(dir, isSpecFile), root);
-}
 /** List the names of proposed changes under `root/changes`. */
 export async function listChangeNames(root) {
     try {

package/dist/core/pipeline.d.ts

@@ -120,15 +120,6 @@ export declare function runInit(root: string, names: readonly string[]): Promise
     files: string[];
     issues: Issue[];
 }>;
-/**
- * The globs that keep *other* proposals out of a change's gate run.
- *
- * Sibling names come from `readdir`, not from the guard above, so they are
- * escaped: a directory called `feat(auth)` pasted in raw is a *pattern*, it
- * matches nothing, and that sibling's specs silently join the run — quietly
- * widening the scope of the one check that decides "done".
- */
-export declare function changeExcludeGlobs(others: string[]): string[];
 export interface StatusResult {
     change: string;
     /** One row per added id, in id order. */

package/dist/core/pipeline.js

@@ -1,11 +1,11 @@
 // 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, loadRegistry, parseSpecs, parseChangeSpecs, listChangeNames, scanProject, staticReader, } from './locate.js';
+import { evalReader, 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 } from './apply.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';
@@ -41,8 +41,61 @@ export async function runCheck(root, options = {}) {
         ...issues,
         ...validateStructure(registry, plan),
         ...detectPotentialDrift(registry, plan, plan.paramRefs),
+        ...(await unclaimedProposedSpecIssues(root, scan, options)),
     ];
 }
+/**
+ * A `*.proposed.spec.ts` no change's delta claims (design §7).
+ *
+ * A proposed spec is kept out of every normal run by its name and pulled into a
+ * gate run by its requirement ids, so one whose ids no delta mentions is a file
+ * that never executes anywhere — the silent drop this marker would otherwise
+ * cost. The base suite cannot catch it (the file is excluded there by design)
+ * and neither can the gate (it is scoped to what its own delta claims), which
+ * leaves `check` as the only command positioned to see it at all.
+ *
+ * A delta that cannot be read is reported as itself rather than turned into
+ * accusations against its specs: not knowing what a change claims is a different
+ * finding from knowing it claims nothing, and `check` already owes the first one
+ * — a change delta is intent, and the commands that only report read it from
+ * source (design §5.1).
+ */
+async function unclaimedProposedSpecIssues(root, scan, options) {
+    if (scan.proposedSpecFiles.length === 0)
+        return [];
+    const claimed = new Set();
+    const issues = [];
+    for (const name of await listChangeNames(root)) {
+        const read = await readDelta(root, name, options);
+        if ('issue' in read)
+            issues.push(read.issue);
+        else
+            for (const id of claimedIds(read.delta))
+                claimed.add(id);
+    }
+    const proposed = await parseSpecs(scan.proposedSpecFiles, root);
+    const claimedFiles = new Set(proposed.scenarios.filter((s) => claimed.has(s.reqId)).map((s) => s.file));
+    // Reported per file, not per scenario: the file is the unit a run includes,
+    // so it is the unit that did or did not execute, and one line per scenario
+    // would say the same thing several times about one unread file. Driven off
+    // the scanned files rather than off the parsed scenarios, so a proposed spec
+    // that declares no scenario at all is reported too — that one is claimed by
+    // nothing for a second reason, and reading the plan alone cannot see it.
+    for (const abs of scan.proposedSpecFiles) {
+        const file = relativePath(root, abs);
+        if (claimedFiles.has(file))
+            continue;
+        issues.push({
+            level: 'ERROR',
+            code: 'proposed-spec-unclaimed',
+            file,
+            message: `${file} is a proposed spec, but no change under changes/ declares a requirement it covers, ` +
+                `so no gate run will ever include it. Add its requirement ids to that change's ` +
+                `${CHANGE_DELTA_FILE}, or rename the file to *.spec.ts if the behaviour has already merged.`,
+        });
+    }
+    return issues;
+}
 /**
  * The spec files a run should execute: the ones that declare a `requirement()`.
  *
@@ -103,6 +156,7 @@ export async function runVerify(root, options = {}) {
             passed: true,
             runtimeCoverage: new Map(),
             outcomes: new Map(),
+            unloadedFiles: [],
         }
         : await runAndCollect({
             root,
@@ -215,10 +269,9 @@ export async function runInit(root, names) {
  * MR title.
  *
  * The test is path safety, not a character whitelist: the name never reaches a
- * glob (only *sibling* names do, and changeExcludeGlobs escapes those), so
- * `feat(auth)` or a name with a space is a perfectly good directory and there
- * is no reason for the gate to refuse it. Rejecting only what can escape the
- * directory keeps the guard exactly as wide as the danger.
+ * glob, so `feat(auth)` or a name with a space is a perfectly good directory
+ * and there is no reason for the gate to refuse it. Rejecting only what can
+ * escape the directory keeps the guard exactly as wide as the danger.
  */
 function isSafeChangeName(name) {
     return (name !== '' &&
@@ -229,29 +282,21 @@ function isSafeChangeName(name) {
         !name.includes('\0'));
 }
 /**
- * The globs that keep *other* proposals out of a change's gate run.
+ * Escape a path so a run's `include` matches that file and nothing else.
  *
- * Sibling names come from `readdir`, not from the guard above, so they are
- * escaped: a directory called `feat(auth)` pasted in raw is a *pattern*, it
- * matches nothing, and that sibling's specs silently join the run — quietly
- * widening the scope of the one check that decides "done".
+ * The backslash comes first, and it is the one that matters most: it is glob's
+ * own escape character, so a path containing one is not merely unescaped, it
+ * silently rewrites the pattern around it — `a\b` reads as an escaped `b` and
+ * matches `ab`, never the file itself. These paths come from the tree, not from
+ * the change-name guard above, so they are escaped rather than refused: a file
+ * that exists is not ours to reject.
+ *
+ * This used to escape *sibling change names* too, for the exclude globs that
+ * kept other proposals out of a gate run. Those globs are gone with the
+ * directory that made them possible; the include list is now the plan's own
+ * files, which is a set rather than a pattern.
  */
-export function changeExcludeGlobs(others) {
-    return others.map((n) => `**/changes/${escapeGlob(n)}/**`);
-}
 function escapeGlob(name) {
-    // The backslash comes first, and it is the one that matters most: it is
-    // glob's own escape character, so a name containing one is not merely
-    // unescaped, it silently rewrites the pattern around it. On POSIX a
-    // backslash is a legal filename character, so `changes/a\b` produced the
-    // exclude glob `**/changes/a\b/**`, which globbing reads as an escaped `b` —
-    // matching `ab`, never the directory itself. That sibling's specs then
-    // joined the gate run, quietly widening the scope of the one check that
-    // decides whether a change is done.
-    //
-    // Escaped rather than rejected, because these names are not the change name
-    // the guard above screens: they come from `readdir`, and a directory that
-    // exists is not ours to refuse.
     return name.replace(/[\\*?[\]{}()!+@|^$]/g, '\\$&');
 }
 /** The delta a change is declared in (design §7). */
@@ -325,14 +370,35 @@ async function readDelta(root, changeName, options) {
         },
     };
 }
+/** Split a plan over the proposed specs into the part one delta claims. */
+function claimedByDelta(proposed, delta) {
+    const claimed = new Set(claimedIds(delta));
+    // A file is claimed whole or not at all. Scenarios in one file can name
+    // several requirements, and running half a file is not something Vitest can
+    // be asked for — the run scope is a set of files — so a per-scenario split
+    // would make the static plan describe a run that cannot happen.
+    const files = new Set(proposed.scenarios.filter((s) => claimed.has(s.reqId)).map((s) => s.file));
+    const scenarios = proposed.scenarios.filter((s) => files.has(s.file));
+    // A `ParamRef` records a requirement and a scenario name, not a file, so it
+    // is carried by the scenario it was seen in rather than filtered on its own.
+    // Dropping the pair down to `reqId` would let a param read in a *merged*
+    // scenario silence the drift heuristic for a proposed one, and vice versa.
+    const key = (reqId, scenario) => JSON.stringify([reqId, scenario]);
+    const kept = new Set(scenarios.map((s) => key(s.reqId, s.name)));
+    return {
+        scenarios,
+        paramRefs: proposed.paramRefs.filter((p) => kept.has(key(p.reqId, p.scenario))),
+    };
+}
 /**
  * The static plan a change is gated and reported against: the base suite plus
- * the change's own specs (design §8). Takes the spec files rather than finding
- * them, so a caller that already scanned the tree does not walk it twice.
+ * the specs this change's delta claims (design §8). Takes the scan rather than
+ * walking the tree again, so a caller that already scanned does not repeat it.
  */
-async function changeMergedPlan(root, changeName, specFiles) {
-    const basePlan = await parseSpecs(specFiles, root);
-    const changePlan = await parseChangeSpecs(root, changeName);
+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);
     return {
         scenarios: [...basePlan.scenarios, ...changePlan.scenarios],
         paramRefs: [...basePlan.paramRefs, ...changePlan.paramRefs],
@@ -354,7 +420,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, changeName, scan.specFiles);
+    const 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: [] };
@@ -395,14 +461,14 @@ export async function runArchive(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, changeName, scan.specFiles);
-        // Run base specs + this change's specs; exclude other proposals and archive.
-        const others = (await listChangeNames(root)).filter((n) => n !== changeName);
-        const exclude = [
-            ...BASE_EXCLUDE,
-            '**/archive/**',
-            ...changeExcludeGlobs(others),
-        ];
+        const plan = 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 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
         // under the same root as the change being archived.
@@ -429,7 +495,17 @@ export async function runArchive(root, changeName, options = {}) {
                 await writeAtomic(redRecordPath(root, changeName), serialiseRedRecord(changeName, merged.record));
             }
         }
-        return evaluateGate({ registry: applied.registry, plan, run, addedIds: added, firstRun });
+        // Against `base`, not `applied`: the child run imported the registry from
+        // disk, so what matters is what that file has, not what the gate computed.
+        const unmergedAddedIds = added.filter((id) => !Object.hasOwn(base, id));
+        return evaluateGate({
+            registry: applied.registry,
+            plan,
+            run,
+            addedIds: added,
+            unmergedAddedIds,
+            firstRun,
+        });
     }
     finally {
         await loader.close();

package/dist/core/registry.d.ts

@@ -75,10 +75,69 @@ export interface RegistryDelta {
     }[];
 }
 /**
- * Declare a registry delta for a change. This is an identity pass-through that
- * fixes the authoring surface; ordered idempotent application
- * (RENAMED -> REMOVED -> MODIFIED -> ADDED) lives in applyDelta (design §7).
+ * The requirements a delta ADDs, keyed by id and typed at the params written —
+ * the same shape {@link defineRequirements} returns, over the half of a change
+ * that introduces requirements.
+ *
+ * MODIFIED ids are deliberately absent. A modified requirement's end state is
+ * the base entry with the patch applied, and the base is not in this file; a
+ * view that showed the patch alone would answer `params.x` with the proposed
+ * value and `params.y` with `undefined` for a key the requirement has. That is
+ * a shape that reads as the merged requirement and is not one, which is worse
+ * than not offering it.
+ */
+type ProposedRequirements<T extends RegistryDelta> = T extends {
+    added: infer A;
+} ? {
+    [K in keyof A]: Omit<Requirement, 'params'> & {
+        params: DefinedParams<A[K]>;
+    };
+} : unknown;
+/**
+ * What `delta()` returns: the delta itself, also readable as the registry of
+ * what it proposes.
+ *
+ * The union is safe by grammar rather than by convention — a requirement id
+ * matches `/^[A-Z]+-\d+$/` (`RequirementIdSchema`), so no id can ever be spelled
+ * `added`, `modified`, `removed` or `renamed`. That is what lets one value carry
+ * both surfaces without either shadowing the other.
+ *
+ * There is no index signature, unlike {@link DefinedRegistry}. That one keeps
+ * its because `reqs[id]` with an `id: string` is a real pattern in a shared test
+ * helper over a whole registry; the ids a single change adds are few and known
+ * at the call site, so the stricter shape costs nothing and rejects a mistyped
+ * id outright instead of leaving it to `check`.
+ */
+export type DefinedDelta<T extends RegistryDelta> = T & ProposedRequirements<T>;
+/**
+ * Declare a registry delta for a change (design §7). Ordered idempotent
+ * application (RENAMED -> REMOVED -> MODIFIED -> ADDED) lives in applyDelta.
+ *
+ * The returned value is the delta *and* the registry of the requirements it
+ * adds, so a stage-1 scenario reads a proposed param with the expression a
+ * merged one uses — `reqs['AUTH-7'].params.totpWindowSec`, not
+ * `d.added!['AUTH-7']!.params!.totpWindowSec as number`. Stage 1 is where the
+ * scenario must be written and must go red, which made it the one stage where
+ * the workflow pushed the author off `params`, the single source the whole tool
+ * exists to reward — and then billed them the rewrite at merge for having
+ * complied. Now merging a spec changes its import and nothing else.
+ *
+ * Still no validation, deliberately. A delta carrying an id the registry would
+ * refuse is an `add-invalid` / `rename-target-invalid` ERROR from the gate
+ * (ATX-41), which is where a reviewer sees it; throwing here would move that
+ * verdict into whichever command happened to evaluate the file first.
+ */
+export declare function delta<const T extends RegistryDelta>(d: T): DefinedDelta<T>;
+/**
+ * A delta, also keyed by the ids it ADDs. The one place that shape is built.
+ *
+ * Both readers go through this — `delta()` on the evaluated path, and
+ * `readDeltaSource` on the static one — because the differential suite asserts
+ * the two agree about what a delta *is*, and a second copy of this three-line
+ * spread is exactly the kind of agreement that holds by transcription until it
+ * does not. A new object rather than a mutated argument, so the literal a
+ * caller wrote is still the literal they hold.
  */
-export declare function delta(d: RegistryDelta): RegistryDelta;
+export declare function withProposedRequirements<T extends RegistryDelta>(d: T): T;
 export {};
 //# sourceMappingURL=registry.d.ts.map

package/dist/core/registry.js

@@ -34,11 +34,37 @@ export function defineRequirements(input) {
     return result.data;
 }
 /**
- * Declare a registry delta for a change. This is an identity pass-through that
- * fixes the authoring surface; ordered idempotent application
- * (RENAMED -> REMOVED -> MODIFIED -> ADDED) lives in applyDelta (design §7).
+ * Declare a registry delta for a change (design §7). Ordered idempotent
+ * application (RENAMED -> REMOVED -> MODIFIED -> ADDED) lives in applyDelta.
+ *
+ * The returned value is the delta *and* the registry of the requirements it
+ * adds, so a stage-1 scenario reads a proposed param with the expression a
+ * merged one uses — `reqs['AUTH-7'].params.totpWindowSec`, not
+ * `d.added!['AUTH-7']!.params!.totpWindowSec as number`. Stage 1 is where the
+ * scenario must be written and must go red, which made it the one stage where
+ * the workflow pushed the author off `params`, the single source the whole tool
+ * exists to reward — and then billed them the rewrite at merge for having
+ * complied. Now merging a spec changes its import and nothing else.
+ *
+ * Still no validation, deliberately. A delta carrying an id the registry would
+ * refuse is an `add-invalid` / `rename-target-invalid` ERROR from the gate
+ * (ATX-41), which is where a reviewer sees it; throwing here would move that
+ * verdict into whichever command happened to evaluate the file first.
  */
 export function delta(d) {
-    return d;
+    return withProposedRequirements(d);
+}
+/**
+ * A delta, also keyed by the ids it ADDs. The one place that shape is built.
+ *
+ * Both readers go through this — `delta()` on the evaluated path, and
+ * `readDeltaSource` on the static one — because the differential suite asserts
+ * the two agree about what a delta *is*, and a second copy of this three-line
+ * spread is exactly the kind of agreement that holds by transcription until it
+ * does not. A new object rather than a mutated argument, so the literal a
+ * caller wrote is still the literal they hold.
+ */
+export function withProposedRequirements(d) {
+    return { ...d, ...(d.added ?? {}) };
 }
 //# sourceMappingURL=registry.js.map