@am_shork/attest 0.4.2 → 0.5.0

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

package/dist/core/runner.js

@@ -4,6 +4,8 @@
 // never crosses the process boundary; the serialized task tree does.
 import { startVitest } from 'vitest/node';
 import { configDefaults } from 'vitest/config';
+import { relativePath } from './paths.js';
+import { byCodeUnit } from './order.js';
 /** requirement() names each describe block `[reqId]`; recover the id from that. */
 const REQ_SUITE = /^\[(.+)\]$/;
 /**
@@ -17,8 +19,21 @@ const REQ_SUITE = /^\[(.+)\]$/;
  * command goes through — the boundary the gate exists to hold.
  */
 export const BASE_EXCLUDE = configDefaults.exclude;
-/** Proposed / archived changes are excluded from a normal run (design §7, §8). */
-const DEFAULT_EXCLUDE = [...BASE_EXCLUDE, '**/changes/**', '**/archive/**'];
+/**
+ * Proposed / archived changes are excluded from a normal run (design §7, §8).
+ *
+ * The `.proposed.spec.ts` glob is the one carrying the weight now: a proposal's
+ * specs sit at their merged location, next to the code they attest, so nothing
+ * about *where* they are keeps them out of a run. They are red by construction
+ * until their change is implemented, and a default run that swept them up would
+ * report a project as broken for the whole life of every change in flight.
+ */
+const DEFAULT_EXCLUDE = [
+    ...BASE_EXCLUDE,
+    '**/*.proposed.spec.ts',
+    '**/changes/**',
+    '**/archive/**',
+];
 /**
  * Build the child-run options. Attest owns the run *scope* — include/exclude/
  * root/watch always come from here, so the caller can neither widen the spec
@@ -88,20 +103,42 @@ export async function runAndCollect(options = {}) {
         // that notices if the task tree ever stops having a `type`, a `name` or a
         // `result.state`. An `as unknown as` here bought nothing and blinded it to
         // exactly the change that would silently empty the runtime coverage.
-        for (const file of vitest.state.getFiles())
+        const unloadedFiles = [];
+        for (const file of vitest.state.getFiles()) {
             walk(file);
+            // Relative and POSIX for the reason everything derived from the root is
+            // (`paths.ts`): this becomes an `Issue.file`, which a `--json` consumer
+            // diffs across two CI runs that may not share an operating system.
+            if (failedToLoad(file)) {
+                unloadedFiles.push(relativePath(options.root ?? process.cwd(), file.filepath));
+            }
+        }
+        unloadedFiles.sort(byCodeUnit);
         // No optional call and no `?? 0` default: `getCountOfFailedTests` is a
         // required method on Vitest's state, so the guard was dead at the type
         // level — and had it ever become live it defaulted the wrong way, reading a
         // missing API as zero failures and turning a red suite green. This is the
         // one boolean in the engine that must never fail open.
         const passed = vitest.state.getCountOfFailedTests() === 0;
-        return { passed, runtimeCoverage, outcomes };
+        return { passed, runtimeCoverage, outcomes, unloadedFiles };
     }
     finally {
         await vitest.close();
     }
 }
+/**
+ * Did this file fail before any of its tests could exist?
+ *
+ * Errors recorded on the *file* rather than on a test are collection errors —
+ * the module threw while being imported. Measured rather than assumed: a spec
+ * whose assertion fails carries `errors: 0` at the file level and one failing
+ * test task, while a spec whose import throws carries `errors: 1` and no tasks
+ * at all. Both leave `result.state` at `fail`, which is why the state alone
+ * cannot tell them apart.
+ */
+function failedToLoad(file) {
+    return (file.result?.errors?.length ?? 0) > 0;
+}
 /** The outcome of a task that ran, or `undefined` when it did not run at all. */
 function executedOutcome(task) {
     const state = task.result?.state;

package/dist/core/schema.js

@@ -14,10 +14,18 @@ export const RequirementSchema = z.object({
     // blacklists, id sets) are the most drift-prone constants, so keeping them out
     // of params left the highest-risk values unguarded; an array still has exactly
     // one owner (the spec) read by exactly one place (the scenario).
+    // The union carries its own message because a union's default one is the
+    // word "Invalid input", which names neither what was given nor what is
+    // accepted. A nested object is the value that reaches it — a table of
+    // kind -> weight is the natural thing to try — and the constraint that
+    // refuses it is stated nowhere the author is looking, so the message is
+    // where they find it.
     params: z
         .record(z.string(), (() => {
         const scalar = z.union([z.number(), z.string(), z.boolean()]);
-        return z.union([scalar, z.array(scalar)]);
+        return z.union([scalar, z.array(scalar)], {
+            errorMap: () => ({ message: 'expected a string, number, boolean, or an array of those' }),
+        });
     })())
         .default({}),
     outOfScope: z.array(z.string()).default([]),

package/dist/core/skill.js

@@ -74,12 +74,22 @@ promises is a two-stage workflow, and the stages are separate on purpose.
   a limit, a list of names — is written **once**, in the requirement's \`params\`,
   and the scenario reads it from there. The number then cannot drift between the
   spec and the assertion, because there is only one of it.
+- **What earns a param: promises, not tuning.** A value belongs in \`params\` when
+  the requirement promises it — a timeout the user is owed, a budget someone would
+  file a bug about. A value that only tunes behaviour (a search depth, a cache
+  size) stays an ordinary constant: nothing is owed if it changes, and a registry
+  that accumulates every knob in the project is one of the ways intent bloats.
 - **What that does not buy.** \`attest check\` executes nothing, so editing a
   param value leaves it at \`✓ No issues\` — nothing became unbound or uncovered.
   The single source makes a value impossible to *diverge*; it does not announce
   that it *moved*. Only \`verify\` goes red, and only when a scenario asserts on
-  the value it read from params. That is the reason to read params **inside** the
-  assertion rather than beside it.
+  the value it read from params.
+- **Reading the param is necessary, not sufficient.** An assertion that
+  recomputes its expectation from the same param the code under test just read
+  has no independent term: both sides move together, and the scenario stays green
+  through any edit. Pin the expectation to something that does not move with the
+  param — a fixture, a literal in the test, or a second independently derived
+  value.
 
 ## Rules the engine enforces
 
@@ -128,10 +138,31 @@ Then write the change folder. \`<name>\` is one directory name inside
 \`\`\`
 changes/<name>/
 ├── proposal.md              # why, and what is out of scope. Prose, for humans.
-├── requirements.delta.ts    # the intent change
-└── specs/*.spec.ts          # the scenarios that must pass for it to be done
+└── requirements.delta.ts    # the intent change
 \`\`\`
 
+**The change's scenarios do not live in that folder.** Each goes where it will
+live once the change is merged — beside the code it attests, in the same
+directory as the specs already there — under the name \`*.proposed.spec.ts\`:
+
+\`\`\`
+lib/game/specs/
+├── board.spec.ts            # already merged
+└── fog.proposed.spec.ts     # this change's, and ../fog already resolves
+\`\`\`
+
+That name is the whole mechanism. It keeps the file out of \`attest verify\` and
+out of a plain \`vitest run\` while the change is in flight — the scenarios are
+red by construction — and \`attest archive <name>\` pulls it in by the requirement
+ids it covers: a change claims the proposed specs that declare a scenario for an
+id it ADDs, renames to, or MODIFIEs. Nothing lists paths anywhere, so nothing can
+fall out of step. A proposed spec no change claims is a \`proposed-spec-unclaimed\`
+ERROR from \`attest check\`, because it would otherwise run nowhere at all.
+
+Writing it at its merged location is what makes merging it a rename. Its relative
+imports resolve now exactly as they will afterwards, so \`../fog\` never becomes
+\`../../../lib/game/fog\` and back again.
+
 \`\`\`ts
 // changes/add-2fa/requirements.delta.ts
 import { delta } from '@am_shork/attest/define';
@@ -156,8 +187,22 @@ The delta applies \`RENAMED → REMOVED → MODIFIED → ADDED\`, idempotently:
 ADDED id that already exists with identical content is a no-op, with different
 content it is a conflict.
 
+**A delta also reads as the registry of what it adds**, so a scenario written now
+reads a proposed param exactly as it will after the merge:
+
+\`\`\`ts
+import reqs from '../../changes/add-2fa/requirements.delta.ts';   // ← only this line changes at merge
+const window = reqs['AUTH-7'].params.totpWindowSec;               // typed at 30, no cast
+\`\`\`
+
+Never hand-write an accessor for a proposed param, and never copy the literal
+into the assertion: both are a second place the value lives, opened during the
+one stage where the assertion is being authored against a value nobody has
+implemented yet. MODIFIED ids are deliberately not readable this way — the end
+state is the base entry with the patch applied, and the base is not in that file.
+
 **The scenarios must be red.** Every added requirement needs at least one
-scenario under \`changes/<name>/specs/\`, and at this stage they must fail —
+scenario in a \`*.proposed.spec.ts\`, and at this stage they must fail —
 they describe behaviour that does not exist yet. Prove it:
 
 \`\`\`
@@ -227,6 +272,8 @@ once. Branch on \`issues[].code\`, never on \`message\`:
 | \`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\`?) |
+| \`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 |
 | \`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 |
@@ -247,6 +294,12 @@ failure this framework exists to make visible:
    is the drift the single source exists to prevent, and the param is typed at
    the value written in the registry, so a stale expectation stops compiling
    rather than silently passing.
+   *One thing to know before implementation code reads a param this change
+   ADDs:* the suite imports your \`*.reqs.ts\` from disk, while the gate applies
+   the delta in memory — so that read throws at import and the gate answers
+   \`added-id-unmerged\`. Merge the added requirement into the registry and run
+   again; the \`added:\` entry stays, because applying it a second time with
+   identical content is a no-op.
 4. **Do not write or edit \`first-run.json\`.** It is the one file here the gate
    trusts without being able to check it, so a hand-written \`"fail"\` clears
    \`never-red\` while proving nothing at all. Run the gate before implementing;
@@ -256,8 +309,10 @@ failure this framework exists to make visible:
 
 Then, and not before:
 
-1. Merge \`requirements.delta.ts\` into the main registry, and the change's specs
-   into the main suite.
+1. Merge \`requirements.delta.ts\` into the main registry, and rename each of the
+   change's \`*.proposed.spec.ts\` to \`*.spec.ts\` **in place**. Nothing moves and
+   no import changes; if you find yourself editing a specifier, the spec was not
+   written at its merged location and stage 1 was the place to fix that.
 2. Move \`changes/<name>/\` to \`archive/<date>-<name>/\`.
 3. If the project commits a rendering, regenerate it: \`attest render --out
    <file>\`. A committed document that no longer matches the registry is a

package/dist/core/static-registry.js

@@ -20,7 +20,7 @@
 // value is fixed by the source text — a second walker would be a second answer
 // to "is this a literal", and those two answers must not be able to disagree.
 import ts from 'typescript';
-import { RegistryValidationError } from './registry.js';
+import { RegistryValidationError, withProposedRequirements } from './registry.js';
 import { RegistrySchema } from './schema.js';
 /** The authoring function a registry file must default-export the result of. */
 const DEFINE = 'defineRequirements';
@@ -142,7 +142,11 @@ export function readDeltaSource(file, source) {
     // function deliberately does not make (see the note above on why a delta is
     // not schema-validated here), which is the worst thing an assertion can do —
     // look like verification.
-    return { ok: true, delta: value };
+    // Augmented exactly as `delta()` augments the evaluated one, through the same
+    // function: a delta reads as the registry of what it adds (design §7), and the
+    // two readers must not disagree about that — the differential suite is the
+    // thing that would notice, and it should have nothing to notice.
+    return { ok: true, delta: withProposedRequirements(value) };
 }
 /**
  * The expression a file default-exports, following one level of local binding.

package/dist/core/types.d.ts

@@ -40,6 +40,16 @@ export interface RunResult {
      * it, which is what §6's mechanism 2 records.
      */
     outcomes: Map<string, Map<string, Outcome>>;
+    /**
+     * Spec files that failed to *load*, as project-relative POSIX paths.
+     *
+     * A file whose module threw at import has no tasks at all, so every other
+     * signal it produces is an absence: no coverage, no outcomes, and scenarios
+     * the static plan declared but the runtime never saw. Those absences are
+     * indistinguishable from a `skip` unless the load failure is carried
+     * separately, which is what this is.
+     */
+    unloadedFiles: string[];
 }
 /** Severity levels for graded reporting (design §5.3). */
 export type Level = 'ERROR' | 'WARNING' | 'INFO';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
   "type": "module",
   "engines": {