@am_shork/attest 0.4.3 → 0.6.0

package/README.md

@@ -8,18 +8,26 @@ by a stable ID and continuously detects drift.
 - **Result** — is every test green? (from the test runner)
 - **Drift** — do intent and assertions still agree? (static + runtime cross-check)
 
-The killer move against drift: values that change (timeouts, limits) live **once**
-in a requirement's `params`, and tests read them from there — so a number is
-physically impossible to drift between the spec and the assertion. A param may be
-a scalar or an array of scalars, so list-shaped constants (vendor blacklists, id
-sets) get the same single source as a lone number.
+The killer move against drift: values a requirement **promises** (timeouts,
+limits, budgets) live **once** in its `params`, and tests read them from there —
+so a number is physically impossible to drift between the spec and the assertion.
+Values that merely tune behaviour stay ordinary constants; nothing is owed to
+anyone when a tuning knob changes. A param may be a scalar or an array of
+scalars, so list-shaped constants (vendor blacklists, id sets) get the same
+single source as a lone number.
 
 What that does not buy is a warning when you change the value. `check` runs
 nothing, so editing a param leaves it at `✓ No issues` — nothing became unbound,
 nothing became uncovered. The value cannot *diverge* from the assertion, which is
 the stronger property; noticing that it *moved* is `verify`'s job, and only when
-a scenario asserts on the value it read from `params`. Read the param inside the
-assertion, not beside it.
+a scenario asserts on the value it read from `params`.
+
+Reading the param is necessary and **not sufficient**, which is worth knowing
+before you rely on it: an assertion that recomputes its expectation from the same
+param the code under test just read has no independent term, so both sides move
+together and the test 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.
 
 ## Prerequisites
 
@@ -149,7 +157,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.4.3/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.6.0/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/cli/index.js

@@ -11,12 +11,17 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { resolve } from 'node:path';
 import { writeAtomic } from '../core/write.js';
-import { runCheck, runVerify, runCover, runArchive, runInit, runRender, runRenderCheck, runStatus, DEFAULT_TARGET, TARGET_NAMES, } from '../core/pipeline.js';
+import { runCheck, runVerify, runCover, runArchive, runArchiveApply, runInit, runRender, runRenderCheck, runStatus, DEFAULT_TARGET, TARGET_NAMES, } from '../core/pipeline.js';
 import { hasError } from '../core/types.js';
 import { formatCrash, formatIssues, formatScope, summarize, formatCoverage, formatStatus, } from './report.js';
 import { archiveReport, checkReport, coverReport, errorReport, initReport, renderJson, renderReport, statusReport, verifyReport, } from './json.js';
 import { packageVersion } from '../core/version.js';
 const VERSION = packageVersion();
+/** `runArchive` in the shape `--apply` returns, so the two share one call site. */
+const gateOnly = async (dir, change, options) => ({
+    issues: await runArchive(dir, change, options),
+    written: [],
+});
 const program = new Command();
 program
     .name('attest')
@@ -267,14 +272,27 @@ program
     .argument('[dir]', 'project root', undefined)
     .option(JSON_FLAG, JSON_HELP)
     .option(VITEST_CONFIG_FLAG, VITEST_CONFIG_HELP)
+    .option('--apply', 'if the gate passes, merge the change: splice its ADDED requirements into the registry, rename its proposed specs, and move the change folder to archive/')
     .description('Run the archive gate; merge only if it passes.')
     .action((change, dir, opts) => runAction('archive', opts, async () => {
-    const blocking = await runArchive(root(dir), change, { vitestConfig: vitestConfig(opts) });
+    const run = opts.apply ? runArchiveApply : gateOnly;
+    const { issues: blocking, written } = await run(root(dir), change, {
+        vitestConfig: vitestConfig(opts),
+    });
     return {
         report: archiveReport(VERSION, change, blocking),
         human: () => {
             if (blocking.length === 0) {
-                console.log(chalk.green(`✓ Gate passed: change "${change}" can be archived.`));
+                console.log(chalk.green(opts.apply
+                    ? `✓ Gate passed and merged: change "${change}".`
+                    : `✓ Gate passed: change "${change}" can be archived.`));
+                // Every path the merge touched, because this is the command that
+                // edits files the user cannot regenerate and they need to know which
+                // ones to read before committing. It is also what a working-tree
+                // check would only have approximated, and it works for someone not
+                // using version control at all.
+                for (const path of written)
+                    console.log(chalk.dim(`  ${path}`));
             }
             else {
                 console.log(chalk.red(`✗ Gate failed: change "${change}"`));

package/dist/core/apply.d.ts

@@ -12,6 +12,21 @@ export interface ApplyResult {
  * than off `delta.added`, so the two can never be scoped differently.
  */
 export declare function addedIds(d: RegistryDelta): string[];
+/**
+ * The ids a delta **claims**: what it adds, renames to, or modifies.
+ *
+ * This is how a proposed spec is attributed to a change (design §7). A spec
+ * sitting at its merged location carries no change name, so the delta names its
+ * specs the only way that cannot drift from them — by the requirements they
+ * declare a scenario for. Wider than `addedIds` on purpose: a delta that
+ * retunes a param or renames an id may need a scenario of its own, and one that
+ * could not be claimed would be a spec the gate never ran.
+ *
+ * REMOVED ids are absent. A scenario for a requirement the change deletes is
+ * not proposed behaviour, and claiming it would put a spec into the gate run
+ * whose requirement the same delta has just taken away.
+ */
+export declare function claimedIds(d: RegistryDelta): string[];
 /**
  * Apply a change delta to a base registry, returning the merged registry plus
  * any apply-level issues (conflicts, missing targets, invalid results). The

package/dist/core/apply.js

@@ -14,6 +14,27 @@ import { byCodeUnit } from './order.js';
 export function addedIds(d) {
     return Object.keys(d.added ?? {});
 }
+/**
+ * The ids a delta **claims**: what it adds, renames to, or modifies.
+ *
+ * This is how a proposed spec is attributed to a change (design §7). A spec
+ * sitting at its merged location carries no change name, so the delta names its
+ * specs the only way that cannot drift from them — by the requirements they
+ * declare a scenario for. Wider than `addedIds` on purpose: a delta that
+ * retunes a param or renames an id may need a scenario of its own, and one that
+ * could not be claimed would be a spec the gate never ran.
+ *
+ * REMOVED ids are absent. A scenario for a requirement the change deletes is
+ * not proposed behaviour, and claiming it would put a spec into the gate run
+ * whose requirement the same delta has just taken away.
+ */
+export function claimedIds(d) {
+    return [
+        ...Object.keys(d.added ?? {}),
+        ...(d.renamed ?? []).map((r) => r.to),
+        ...Object.keys(d.modified ?? {}),
+    ].sort(byCodeUnit);
+}
 /**
  * Apply a change delta to a base registry, returning the merged registry plus
  * any apply-level issues (conflicts, missing targets, invalid results). The
@@ -132,8 +153,29 @@ function introducedIdIssue(id, code, prefix) {
 function err(code, message, reqId) {
     return { level: 'ERROR', code, ...(reqId ? { reqId } : {}), message };
 }
+/**
+ * The first schema failure, as `path: message`.
+ *
+ * The path is the half that was being dropped. A requirement carries a record —
+ * `params` — so "invalid" on its own does not say *which* param, and the value
+ * that most often fails is one the author has to find by reading the schema's
+ * `.d.ts`. `RegistryValidationError` has spelled a path `a.b.c` since the
+ * registry shipped, and `troubleshooting.md` has been quoting `rationale:
+ * Required` for `add-invalid` the whole time — a form this function could not
+ * produce. So this is the spelling matching what is already documented, not a
+ * new one.
+ *
+ * Omitted rather than rendered as `(root)` when the path is empty, because the
+ * one caller that gets an empty path is `introducedIdIssue`, whose prefix has
+ * already named the thing: `Added requirement "auth-7" is invalid: id must look
+ * like AUTH-3` reads correctly and `(root): id must look like AUTH-3` does not.
+ */
 function firstMessage(error) {
-    return error.issues[0]?.message ?? 'unknown error';
+    const first = error.issues[0];
+    if (!first)
+        return 'unknown error';
+    const path = first.path.map(String).join('.');
+    return path ? `${path}: ${first.message}` : first.message;
 }
 /** Content equality via canonical JSON (params key order does not matter). */
 function sameRequirement(a, b) {

package/dist/core/compiler.d.ts

@@ -0,0 +1,40 @@
+import type { Issue } from './types.js';
+/**
+ * The range the readers are written against.
+ *
+ * Stated here rather than read from the manifest at runtime, because the
+ * manifest is not on disk beside a bundled build and a diagnostic that cannot
+ * name the range is most of the diagnostic gone. `ATX-56` keeps the two honest:
+ * its `params` carry this string, and its scenario compares them with
+ * `package.json`, so the constant cannot drift from the dependency it describes.
+ */
+export declare const SUPPORTED_TYPESCRIPT = "^5.5.0 || ^6.0.0";
+/**
+ * The part of the compiler surface every AST reader in this project touches.
+ *
+ * Deliberately the two members that are reached *first* rather than an
+ * exhaustive list: `createSourceFile` and `ScriptTarget` are what
+ * `parser.ts`, `static-registry.ts` and `splice.ts` all open with, so a compiler
+ * that has them has the shape this check is about, and one that lacks either
+ * cannot get far enough for a longer list to matter.
+ */
+interface CompilerSurface {
+    version?: unknown;
+    createSourceFile?: unknown;
+    ScriptTarget?: unknown;
+}
+/**
+ * An ERROR when the resolved compiler has no AST API, or `undefined` when it
+ * does.
+ *
+ * Takes the compiler rather than reaching for the import directly, so the
+ * refusal can be attested against a stand-in: the condition only exists on a
+ * compiler this repository cannot install alongside the one it builds with, and
+ * a check nothing can make fail is the shape `never-red` exists to catch.
+ *
+ * No `reqId` and no `file`: the finding is about the toolchain, and every
+ * requirement and every file in the project is equally unreadable because of it.
+ */
+export declare function compilerIssue(compiler?: CompilerSurface): Issue | undefined;
+export {};
+//# sourceMappingURL=compiler.d.ts.map

package/dist/core/compiler.js

@@ -0,0 +1,64 @@
+// Whether the resolved TypeScript can be read from at all (design §5.1).
+//
+// Both registry readers and the spec parser walk the AST with the compiler API,
+// which makes `typescript` the one dependency this tool cannot survive the
+// absence of — and "absent" is not the shape it arrives in. `typescript@7` is
+// the native port: its package resolves, imports cleanly, and answers `version`
+// and `versionMajorMinor`, while `createSourceFile` and every `ts.isX` guard
+// moved behind `typescript/unstable/ast*`. So the members are `undefined` rather
+// than missing, and the first thing to touch one throws.
+//
+// Measured: `attest check` on it died with
+// `TypeError: Cannot read properties of undefined (reading 'Latest')` and a raw
+// stack — no issue code, no fix hint, and nothing saying which compiler it
+// wanted, on the crash path `[0.4.2]` had just finished sanitising.
+//
+// **The declared range excludes 7, and that is not the same as being safe from
+// it.** A caret is a request, not a constraint the adopter cannot override:
+// `pnpm.overrides` and Yarn `resolutions` both pin a transitive dependency
+// across a whole tree, and a repo standardising on one compiler is exactly the
+// repo that uses them — this one has an `overrides` block of its own. So the
+// reachable case is a deliberate, reasonable act by an adopter, answered with a
+// stack trace.
+//
+// What this cannot do is make Attest work on TypeScript 7. That is a migration
+// to `typescript/unstable/ast`, against an API whose own name says not to depend
+// on it yet. The honest answer for now is that the supported range has a ceiling
+// and says so.
+import ts from 'typescript';
+/**
+ * The range the readers are written against.
+ *
+ * Stated here rather than read from the manifest at runtime, because the
+ * manifest is not on disk beside a bundled build and a diagnostic that cannot
+ * name the range is most of the diagnostic gone. `ATX-56` keeps the two honest:
+ * its `params` carry this string, and its scenario compares them with
+ * `package.json`, so the constant cannot drift from the dependency it describes.
+ */
+export const SUPPORTED_TYPESCRIPT = '^5.5.0 || ^6.0.0';
+/**
+ * An ERROR when the resolved compiler has no AST API, or `undefined` when it
+ * does.
+ *
+ * Takes the compiler rather than reaching for the import directly, so the
+ * refusal can be attested against a stand-in: the condition only exists on a
+ * compiler this repository cannot install alongside the one it builds with, and
+ * a check nothing can make fail is the shape `never-red` exists to catch.
+ *
+ * No `reqId` and no `file`: the finding is about the toolchain, and every
+ * requirement and every file in the project is equally unreadable because of it.
+ */
+export function compilerIssue(compiler = ts) {
+    if (typeof compiler.createSourceFile === 'function' && compiler.ScriptTarget !== undefined) {
+        return undefined;
+    }
+    const version = typeof compiler.version === 'string' ? compiler.version : 'unknown';
+    return {
+        level: 'ERROR',
+        code: 'compiler-unsupported',
+        message: `The resolved TypeScript (${version}) does not expose the AST API Attest reads registries and specs with. ` +
+            `Attest supports ${SUPPORTED_TYPESCRIPT}. ` +
+            `If a resolution or override pins the compiler for the whole tree, exclude Attest from it or move that pin back into the supported range.`,
+    };
+}
+//# sourceMappingURL=compiler.js.map

package/dist/core/docs.d.ts

@@ -8,7 +8,7 @@
  * and the `##` headings of both language documents, so landing here cannot
  * produce a dead link.
  */
-export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "change-not-found", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "orphan-test", "possible-drift", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target"];
+export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "added-id-unmerged", "apply-no-prefix-owner", "apply-unsupported-delta", "change-not-found", "compiler-unsupported", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "orphan-test", "possible-drift", "proposed-spec-name-taken", "proposed-spec-unclaimed", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "spec-in-change-dir", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target"];
 export type IssueCode = (typeof ISSUE_CODES)[number];
 /**
  * The page explaining `code`, or `undefined` when nothing explains it.

package/dist/core/docs.js

@@ -21,7 +21,11 @@ import { packageVersion } from './version.js';
 export const ISSUE_CODES = [
     'add-conflict',
     'add-invalid',
+    'added-id-unmerged',
+    'apply-no-prefix-owner',
+    'apply-unsupported-delta',
     'change-not-found',
+    'compiler-unsupported',
     'declared-not-run',
     'duplicate-prefix',
     'duplicate-requirement',
@@ -34,6 +38,8 @@ export const ISSUE_CODES = [
     'never-red',
     'orphan-test',
     'possible-drift',
+    'proposed-spec-name-taken',
+    'proposed-spec-unclaimed',
     'rationale-placeholder',
     'registry-invalid',
     'registry-no-default',
@@ -41,6 +47,7 @@ export const ISSUE_CODES = [
     'rename-source-missing',
     'rename-target-exists',
     'rename-target-invalid',
+    'spec-in-change-dir',
     'stale-spec-doc',
     'tests-red',
     'unbound-param',

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. */
@@ -75,11 +98,28 @@ export declare function staticReader(): RegistryReader;
  * prefix a duplicate-prefix ERROR.
  *
  * Pass `files` to reuse a {@link scanProject} result instead of re-walking.
+ *
+ * `prefixOwners` comes back with the registry because the rule deciding it —
+ * first claim wins, in sorted file order — must have exactly one spelling. It is
+ * what `duplicate-prefix` is computed from here, and what tells `--apply` which
+ * file an ADDED id belongs in (design §7); a second walk arriving at its own
+ * answer would be a second rule the moment either was edited.
  */
 export declare function loadRegistry(root: string, reader: RegistryReader, files?: string[]): Promise<{
     registry: Registry;
     issues: Issue[];
+    prefixOwners: Record<string, string>;
 }>;
+/**
+ * The part of an id that names the space it lives in — `AUTH` of `AUTH-3`.
+ *
+ * The prefix is the only unit above the requirement (design §11) and two things
+ * now depend on agreeing about it: `duplicate-prefix`, and which file `--apply`
+ * writes an ADDED requirement into. An id with no dash is its own prefix, which
+ * cannot arise from `RequirementIdSchema` and is handled anyway because this
+ * also runs over ids a delta proposed.
+ */
+export declare function idPrefix(id: string): string;
 /**
  * Parse the given spec files into one merged plan (paths shown relative to
  * `displayRoot`). Files are read concurrently; the merge follows the input
@@ -92,8 +132,26 @@ 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>;
+/**
+ * Spec-shaped files sitting under `root/changes` — the location a change's
+ * specs used to live at, and which nothing walks any more (design §7).
+ *
+ * Two correct decisions compose into a blind spot. `changes` is in `SKIP_DIRS`,
+ * so `scanProject` cannot reach these; and the explicit include `attest archive`
+ * once applied to `changes/<name>/specs/` went away with `changeExcludeGlobs`
+ * when specs moved to their merged location. A spec left here therefore executes
+ * in no suite and no gate, and the only command that says anything is the gate,
+ * blaming coverage for a file it cannot see.
+ *
+ * Walks through `findFiles` rather than a second walker: `SKIP_DIRS` is consulted
+ * for *sub*directories only, so starting the walk at `changes` itself both
+ * reaches these files and keeps skipping `node_modules` beneath them.
+ *
+ * Both spellings are wrong here and both are returned. A `*.spec.ts` is the
+ * pre-move layout; a `*.proposed.spec.ts` is the right marker at the wrong path,
+ * which is the half-done migration and no more visible than the other.
+ */
+export declare function findChangeDirSpecs(root: string): Promise<string[]>;
 /** List the names of proposed changes under `root/changes`. */
 export declare function listChangeNames(root: string): Promise<string[]>;
 //# sourceMappingURL=locate.d.ts.map