@am_shork/attest 0.9.3 → 0.10.0

package/README.md

@@ -16,28 +16,6 @@ anyone when a tuning knob changes. A param may be any JSON value, so a
 composite constant — a vendor blacklist, a `kind -> payload` table — gets the
 same single source as a lone number, which is where drift is worst.
 
-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`.
-
-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.
-
-A composite param has a second failure of its own, and it runs the other way. When
-a test **loops over** a list it read from `params`, that list is the set of cases
-the run covers: drop a member and every assertion inside the loop still passes
-over what is left, so the suite quietly tests less with nothing to show for it.
-Pin the extent beside the loop — the members against a literal when their identity
-is the promise, the length when the size is. That literal is not the copy the
-single source exists to prevent: it is not what the system is measured against,
-it is what the intent claimed to cover.
-
 ## Prerequisites
 
 - Node ≥ 20.19
@@ -134,7 +112,14 @@ for exactly one machine-readable document on stdout. Flags, per-command
 behaviour and the JSON shape are in the
 [CLI reference](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md).
 
-### Working with an agent
+Reading a param is necessary and **not sufficient** — an assertion that
+recomputes its expectation from the same param the code just read has no
+independent term, and a scenario that loops over a list param covers exactly
+that list. Both have a known shape and a known repair, and both are in
+[Judging your own intent layer](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/intent-quality.md#writing-a-param-that-pins-something),
+along with the decision table — the shape a composite param is best at.
+
+## Working with an agent
 
 The engine above is only half the framework. The other half is the workflow —
 agree on intent, write the delta, drive the scenarios red, then implement to
@@ -159,7 +144,7 @@ found or pasted. See
 [`attest init`](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md#attest-init)
 for the targets and what `init` deliberately does not write.
 
-### When something goes wrong
+## When something goes wrong
 
 Every diagnostic carries a `code`, and every code has a section in
 **Troubleshooting** — which the diagnostic itself links to:
@@ -167,7 +152,7 @@ Every diagnostic carries a `code`, and every code has a section in
 ```
 ERROR   registry-not-static (requirements/upload.reqs.ts:5)
     Value is not a literal.
-    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.3/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.10.0/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/cli/action.js

@@ -73,10 +73,14 @@ export async function runAction(command, opts, action) {
     }
     catch (err) {
         if (opts.json) {
-            // Unsanitised on purpose: `JSON.stringify` escapes every C0 character,
-            // so these bytes cannot carry one out (see report.ts). That is a claim
-            // about what this line writes and nothing wider — what the project under
-            // test writes is the divert's business, above.
+            // Sanitised, though not on this line: `renderJson` strips every string in
+            // the document as it serialises it (ATX-74), so the crash path is covered
+            // by going through the same function every other report goes through.
+            //
+            // Not by `JSON.stringify`, which is what this comment used to claim. That
+            // escapes C0 and nothing else — DEL and the C1 range survive it — so the
+            // replacer in `renderJson` is load-bearing rather than belt and braces.
+            // What the project under test writes is still the divert's business, above.
             console.log(renderJson(errorReport(VERSION, command, err)));
         }
         else {

package/dist/cli/index.js

@@ -261,10 +261,15 @@ program
     const { issues: blocking, written } = await run(root(dir), change, {
         vitestConfig: vitestConfig(opts),
     });
+    // Built once and handed to both renderings, rather than each being told
+    // separately what the merge did. Two renderings of one result agreeing by
+    // transcription is what let the verdict disagree with itself (ATX-60),
+    // and the paths are the other thing this command has to say.
+    const merge = { applied: opts.apply === true, written };
     return {
-        report: archiveReport(VERSION, change, blocking),
+        report: archiveReport(VERSION, change, blocking, merge),
         human: () => {
-            console.log(formatArchiveVerdict(change, blocking, { applied: opts.apply === true, written }));
+            console.log(formatArchiveVerdict(change, blocking, merge));
         },
     };
 }));

package/dist/cli/json.d.ts

@@ -33,6 +33,22 @@ export interface JsonReport {
     };
     /** `archive` and `status`: the change being gated or reported on. */
     change?: string;
+    /**
+     * `archive --apply` only: every path the merge touched, relative to the
+     * project root, in the order it touched them.
+     *
+     * Additive, so no SCHEMA_VERSION bump. **Absent** when `--apply` was not
+     * asked for — no merge was attempted, and there is nothing to report — while
+     * an **empty array** means the merge ran and had nothing left to write, which
+     * is the ordinary state of a re-run after a completed one. Folding the two
+     * into `[]` would make the field unable to say which happened.
+     *
+     * The human rendering has printed these since `--apply` shipped, on the
+     * grounds that this is the command that edits files the user cannot
+     * regenerate and they need to know which ones to read before committing. That
+     * argument does not stop at the reader with a terminal.
+     */
+    written?: string[];
     /** `status` only: one row per requirement the change adds. */
     progress?: StatusRow[];
     /** `status` only: roll-up of the rows by obligation state. */
@@ -83,7 +99,18 @@ export declare function renderReport(version: string, issues: Issue[], outFile?:
  * was added for, to say something the array already says.
  */
 export declare function initReport(version: string, issues: Issue[], outFiles: string[]): JsonReport;
-export declare function archiveReport(version: string, change: string, blocking: Issue[]): JsonReport;
+/**
+ * `archive`, and — when `--apply` was asked for — what the merge wrote.
+ *
+ * `merge` is the same bundle `formatArchiveVerdict` takes, passed to both from
+ * one place in the shell. The two renderings of one result had already grown
+ * apart once over the verdict (ATX-60); handing them the same object is what
+ * stops the paths from being the second thing they disagree about.
+ */
+export declare function archiveReport(version: string, change: string, blocking: Issue[], merge?: {
+    applied: boolean;
+    written: readonly string[];
+}): JsonReport;
 /**
  * `status`. The progress rows never touch the verdict: `ok` comes from the same
  * `hasError` predicate as everywhere else, over an `issues` array that carries

package/dist/cli/json.js

@@ -109,7 +109,15 @@ export function initReport(version, issues, outFiles) {
     const [only] = outFiles;
     return outFiles.length === 1 && only !== undefined ? { ...report, outFile: only } : report;
 }
-export function archiveReport(version, change, blocking) {
+/**
+ * `archive`, and — when `--apply` was asked for — what the merge wrote.
+ *
+ * `merge` is the same bundle `formatArchiveVerdict` takes, passed to both from
+ * one place in the shell. The two renderings of one result had already grown
+ * apart once over the verdict (ATX-60); handing them the same object is what
+ * stops the paths from being the second thing they disagree about.
+ */
+export function archiveReport(version, change, blocking, merge) {
     return {
         ...envelope({
             version,
@@ -123,6 +131,7 @@ export function archiveReport(version, change, blocking) {
             issues: blocking,
         }),
         change,
+        ...(merge?.applied ? { written: [...merge.written] } : {}),
     };
 }
 /**

package/dist/core/apply.js

@@ -97,6 +97,10 @@ export function applyDelta(base, d) {
             ...patch,
             params: { ...existing.params, ...(patch.params ?? {}) },
             outOfScope: patch.outOfScope ?? existing.outOfScope,
+            // Replaced wholesale rather than merged, exactly as `outOfScope` is: a
+            // patch that closes a question says so by writing the list that remains,
+            // and a union would make closing the last one impossible to express.
+            open: patch.open ?? existing.open,
         };
         const parsed = RequirementSchema.safeParse(merged);
         if (!parsed.success) {
@@ -209,6 +213,7 @@ function canonical(req) {
         // against itself. Code-unit order throughout, and `sortDeep` says why.
         params: sortDeep(req.params),
         outOfScope: [...req.outOfScope],
+        open: [...req.open],
     });
 }
 //# sourceMappingURL=apply.js.map

package/dist/core/archive.js

@@ -35,11 +35,26 @@
 // present without a given scenario is one that did and then drifted.
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { forEachBounded } from './locate.js';
 import { byCodeUnit } from './order.js';
 import { relativePath } from './paths.js';
 import { keepOutcome, readRedRecordIn } from './red-record.js';
 /** The directory archived changes are moved into, under the project root. */
 const ARCHIVE_DIR = 'archive';
+/**
+ * How many archived first-run records are read at once. Its own constant for
+ * the reason `WALK_CONCURRENCY` gives, and a fourth resource: what this bounds
+ * is the *parsed records held at once*, not descriptors. `readFile` does
+ * open-read-close inside one libuv threadpool work item, so concurrent
+ * descriptors track the threadpool and never the fan-out — measured, 3,000
+ * unbounded reads peaked at 53 open handles. Heap is what tracks the input, and
+ * a project's archive grows by one folder per change merged, forever, so the
+ * list is as much the project's shape as a spec tree is.
+ * `Promise.all(names.map(...))` put every record in flight at once: measured at
+ * the `fs` seam, 64 changes peaked at 64 concurrent reads, and 2,000 records of
+ * 45 KB peaked at 352 MB of heap against 177 MB bounded.
+ */
+const ARCHIVE_CONCURRENCY = 32;
 /**
  * Read every archived change folder under `root`.
  *
@@ -67,10 +82,18 @@ export async function readArchivedChanges(root) {
         .filter((e) => e.isDirectory())
         .map((e) => e.name)
         .sort(byCodeUnit);
-    return Promise.all(names.map(async (name) => {
+    // Preallocated and written by `index`, which is how a `forEachBounded` caller
+    // keeps a stable result: the pool calls in input order but completes in
+    // whatever order the disk answers, and `names` is already sorted above.
+    const changes = new Array(names.length);
+    await forEachBounded(names, ARCHIVE_CONCURRENCY, async (name, i) => {
+        // `readRedRecordIn` catches its own read and parse, so nothing here can
+        // throw and abandon the rest — the same thing `readGuarded` is for on the
+        // registry pool, and what keeps every slot of the array above filled.
         const path = join(dir, name);
-        return { name, path: relativePath(root, path), firstRun: await readRedRecordIn(path) };
-    }));
+        changes[i] = { name, path: relativePath(root, path), firstRun: await readRedRecordIn(path) };
+    });
+    return changes;
 }
 /**
  * The archive's first-run evidence, merged across every archived change.

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", "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", "non-scalar-interpolation", "orphan-from-failed-registry", "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", "spec-load-failed", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target", "unreadable-file", "unsafe-target-path"];
+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", "non-scalar-interpolation", "open-unresolved", "orphan-from-failed-registry", "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", "requirement-open", "spec-in-change-dir", "spec-load-failed", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target", "unreadable-file", "unsafe-target-path"];
 export type IssueCode = (typeof ISSUE_CODES)[number];
 /**
  * The page explaining `code`, or `undefined` when nothing explains it.

package/dist/core/docs.js

@@ -37,6 +37,7 @@ export const ISSUE_CODES = [
     'modify-missing',
     'never-red',
     'non-scalar-interpolation',
+    'open-unresolved',
     'orphan-from-failed-registry',
     'orphan-test',
     'possible-drift',
@@ -49,6 +50,7 @@ export const ISSUE_CODES = [
     'rename-source-missing',
     'rename-target-exists',
     'rename-target-invalid',
+    'requirement-open',
     'spec-in-change-dir',
     'spec-load-failed',
     'stale-spec-doc',

package/dist/core/gate.d.ts

@@ -120,6 +120,14 @@ export declare function notRunIssues(plan: AttestPlan, run: RunResult, specific?
  * never a moment when its scenario was supposed to fail.
  */
 export declare function neverRedIssues(plan: AttestPlan, addedIds: readonly string[], firstRun: RedRecord): Issue[];
+/**
+ * Every requirement that still declares an open question.
+ *
+ * Exported for the same reason `neverRedIssues` is: it is one of the gate's
+ * obligations, and a caller projecting the gate's verdict has to reach the same
+ * answer from the same function rather than re-deriving it.
+ */
+export declare function openIssues(registry: Registry): Issue[];
 /**
  * Decide whether a change may be archived. Returns the blocking issues; an
  * empty array means the gate passes (design §8). Checks, in order:

package/dist/core/gate.js

@@ -171,6 +171,27 @@ export function neverRedIssues(plan, addedIds, firstRun) {
     }
     return issues;
 }
+/**
+ * Every requirement that still declares an open question.
+ *
+ * Exported for the same reason `neverRedIssues` is: it is one of the gate's
+ * obligations, and a caller projecting the gate's verdict has to reach the same
+ * answer from the same function rather than re-deriving it.
+ */
+export function openIssues(registry) {
+    const out = [];
+    for (const [id, req] of Object.entries(registry)) {
+        for (const question of req.open) {
+            out.push({
+                level: 'ERROR',
+                code: 'open-unresolved',
+                reqId: id,
+                message: `Requirement "${id}" still declares an open question, so the registry is not done: ${question} Answer it and remove the entry from open, then run the gate again.`,
+            });
+        }
+    }
+    return out;
+}
 /**
  * Decide whether a change may be archived. Returns the blocking issues; an
  * empty array means the gate passes (design §8). Checks, in order:
@@ -209,6 +230,23 @@ export function evaluateGate({ registry, plan, run, addedIds, unmergedAddedIds,
     if (addedIds && addedIds.length > 0) {
         blocking.push(...neverRedIssues(plan, addedIds, firstRun ?? {}));
     }
+    // 6) Open questions: nothing in the end-state registry may still be undecided.
+    //
+    // **Over the whole registry rather than the ids this change adds**, which is
+    // where it parts company with step 5 above. `never-red` is scoped to added ids
+    // because "was ever observed failing" is a fact about history and cannot be
+    // demanded retroactively of a requirement written straight into the base
+    // registry. An open field is not a historical fact; it is a claim that is true
+    // right now, so step 1's whole-registry re-validation is the precedent this
+    // belongs to. The scoping is also what closes the path the narrow form would
+    // open: `applyDelta` merges a MODIFIED patch field-wise, so an id that
+    // archived long ago can acquire `open` from a later change, and an
+    // added-ids-only gate would never look at it.
+    //
+    // The cost is deliberate: one unresolved question anywhere blocks every
+    // unrelated change from archiving. That is the intended reading of a registry
+    // that is not done, and it is recoverable by answering the question.
+    blocking.push(...openIssues(registry));
     return blocking;
 }
 //# sourceMappingURL=gate.js.map

package/dist/core/locate.d.ts

@@ -20,6 +20,33 @@ export declare const isProposedSpecFile: (name: string) => boolean;
  * of them until its gate passes.
  */
 export declare const isSpecFile: (name: string) => boolean;
+/**
+ * Run `fn` over every item with at most `limit` of them in flight.
+ *
+ * Extracted at the second call site rather than the first, because a shape
+ * written N times is one a later fix reaches only some copies of.
+ *
+ * **There are three, and the third is the one to look for.** `findFiles` and
+ * `parseSpecs` are named for what they fan out over; `loadRegistry` is named for
+ * merging, and its concurrency sits under a comment about *ordering* that
+ * answers a different question convincingly. Anything here that reads a list the
+ * project's tree decides the length of belongs in this pool, whatever the
+ * function around it is called.
+ *
+ * The order `fn` is *called* in is the input order; the order it *completes* in
+ * is not, so a caller that needs a stable result either indexes into a
+ * preallocated array by `index` or sorts afterwards. All three callers here do
+ * one of those, deliberately — as does `readArchivedChanges`, the caller
+ * outside this file, which preallocates and writes by `index`.
+ *
+ * No result is collected and none is needed — every caller writes into something
+ * it already owns, and a version returning `T[]` would have to choose an
+ * ordering on their behalf. A throw from `fn` propagates and abandons the rest,
+ * which is the existing behaviour at all three sites: `parseSpecs` and
+ * `loadRegistry` catch per file so that one hostile source scraps only itself
+ * (ATX-65), and a failed `readdir` really does end the walk.
+ */
+export declare function forEachBounded<T>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<void>): Promise<void>;
 /**
  * Recursively find files under root whose basename matches `match`.
  *

package/dist/core/locate.js

@@ -56,7 +56,8 @@ export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpec
  * The order `fn` is *called* in is the input order; the order it *completes* in
  * is not, so a caller that needs a stable result either indexes into a
  * preallocated array by `index` or sorts afterwards. All three callers here do
- * one of those, deliberately.
+ * one of those, deliberately — as does `readArchivedChanges`, the caller
+ * outside this file, which preallocates and writes by `index`.
  *
  * No result is collected and none is needed — every caller writes into something
  * it already owns, and a version returning `T[]` would have to choose an
@@ -65,7 +66,7 @@ export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpec
  * `loadRegistry` catch per file so that one hostile source scraps only itself
  * (ATX-65), and a failed `readdir` really does end the walk.
  */
-async function forEachBounded(items, limit, fn) {
+export async function forEachBounded(items, limit, fn) {
     let cursor = 0;
     const worker = async () => {
         for (let i = cursor++; i < items.length; i = cursor++) {

package/dist/core/merge.js

@@ -319,6 +319,7 @@ function modifyRefusal(root, file, refusal) {
     const where = refusal.field ? `${refusal.reqId}.${refusal.field}` : refusal.reqId;
     const why = {
         comment: `a comment sits inside the value it would replace, and which side of that edit the comment belongs to is not something --apply can decide`,
+        'duplicate-key': `that name is written more than once in the file, so the span --apply located is not the one the registry's readers evaluate`,
         'entry-not-found': `the registry file that owns its prefix holds no entry for it`,
         'not-a-literal': `the value it would replace is not written as a literal`,
         'param-dropped': `the proved end state does not carry that param, and a delta has no way to say one was removed`,

package/dist/core/red-record.js

@@ -320,20 +320,30 @@ export function mergeRedRecord(existing, plan, run, addedIds) {
         forFile[s.name] = kept;
         changed = true;
     }
-    // Sort within each requirement, and within each file, for the same
-    // byte-stability reason.
-    for (const id of Object.keys(record)) {
+    // Sort at every level, for the same byte-stability reason — the ids included.
+    //
+    // The rebuild above sorts only the ids the record already held; the loop after
+    // it *appends* the ones this run is the first to observe, in plan order. So
+    // the ids are unsorted by the time this runs, and this is the level that has
+    // to put them in order.
+    //
+    // A rebuild rather than an in-place sort, which is the trap: reassigning
+    // `record[id]` writes a value and does not move a key, so a version of this
+    // that sorted the two inner levels while walking the ids as they came would
+    // leave the outer order exactly as it found it.
+    const sorted = emptyMap();
+    for (const id of Object.keys(record).sort(byCodeUnit)) {
         const sortedFiles = emptyMap();
         for (const file of Object.keys(record[id]).sort(byCodeUnit)) {
-            const sorted = emptyMap();
+            const names = emptyMap();
             for (const name of Object.keys(record[id][file]).sort(byCodeUnit)) {
-                sorted[name] = record[id][file][name];
+                names[name] = record[id][file][name];
             }
-            sortedFiles[file] = sorted;
+            sortedFiles[file] = names;
         }
-        record[id] = sortedFiles;
+        sorted[id] = sortedFiles;
     }
-    return { record, changed };
+    return { record: sorted, changed };
 }
 /** Serialise the record. A trailing newline, so the file is a well-formed text file. */
 export function serialiseRedRecord(changeName, record) {

package/dist/core/render.js

@@ -83,6 +83,7 @@ function sanitised(registry) {
             rationale: control(req.rationale),
             params: Object.fromEntries(Object.entries(req.params).map(([k, v]) => [control(k), sanitisedValue(v)])),
             outOfScope: req.outOfScope.map(control),
+            open: req.open.map(control),
         };
     }
     return out;
@@ -231,6 +232,13 @@ function section(id, req) {
     if (req.outOfScope.length > 0) {
         out.push('', '**Out of scope**', '', ...req.outOfScope.map((s) => `- ${prose(s)}`));
     }
+    // Last, and rendered at all because this document is the only human review
+    // surface a requirement has: a reader who is told what a requirement promises
+    // without being told what about it is still undecided has been told the
+    // stronger half of a claim on its own.
+    if (req.open.length > 0) {
+        out.push('', '**Open**', '', ...req.open.map((s) => `- ${prose(s)}`));
+    }
     return out;
 }
 /** The statement as the document says it, with its params in place. */

package/dist/core/schema.d.ts

@@ -11,6 +11,7 @@ export declare const RequirementSchema: z.ZodObject<{
     rationale: z.ZodString;
     params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<ParamValue, unknown, z.core.$ZodTypeInternals<ParamValue, unknown>>>>;
     outOfScope: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    open: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 /**
  * The id grammar, on its own.
@@ -45,16 +46,19 @@ export declare const RegistrySchema: z.ZodPipe<z.ZodCustom<Record<string, {
     rationale: string;
     params?: Record<string, unknown> | undefined;
     outOfScope?: string[] | undefined;
+    open?: string[] | undefined;
 }>, Record<string, {
     statement: string;
     rationale: string;
     params?: Record<string, unknown> | undefined;
     outOfScope?: string[] | undefined;
+    open?: string[] | undefined;
 }>>, z.ZodRecord<z.ZodString, z.ZodObject<{
     statement: z.ZodString;
     rationale: z.ZodString;
     params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<ParamValue, unknown, z.core.$ZodTypeInternals<ParamValue, unknown>>>>;
     outOfScope: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    open: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>>>;
 /** Parsed (output) shapes — defaults applied. */
 export type Requirement = z.infer<typeof RequirementSchema>;

package/dist/core/schema.js

@@ -63,6 +63,17 @@ export const RequirementSchema = z.object({
     // instance.
     params: z.record(z.string(), paramValue).default({}),
     outOfScope: z.array(z.string()).default([]),
+    // What is still undecided about this requirement, in free text, one entry per
+    // question. Shaped as `outOfScope` rather than as a new kind of thing: every
+    // place that has to learn about it — the patch merge, both splice writers, the
+    // renderer — already carries that field's branch to copy, and a defaulted
+    // array means an empty list and an absent field are the same state, so no
+    // caller has to distinguish "closed" from "never opened".
+    //
+    // No grammar is imposed on an entry. A greppable free-text line is what
+    // spec-kit's `[NEEDS CLARIFICATION: …]` is, and constraining it here would be
+    // deciding for every adopter what counts as a question.
+    open: z.array(z.string()).default([]),
 });
 /**
  * The id grammar, on its own.

package/dist/core/skill.js

@@ -132,6 +132,30 @@ promises is a two-stage workflow, and the stages are separate on purpose.
   or it is an \`unbound-param\` ERROR. A \`{placeholder}\` written into a
   *rationale* is a \`rationale-placeholder\` WARNING — rationales are not
   interpolated, so it would reach the rendered document with its braces intact.
+- **If you cannot determine a value, say so — do not pick one.** \`open\` is a
+  list of what is still undecided about the requirement, in free text, one entry
+  per question. Each is a \`requirement-open\` WARNING from the static commands,
+  which does not fail them, so a proposal may be legitimately half-finished
+  while you are still writing it. The archive gate is where it stops: it blocks
+  with \`open-unresolved\` while any requirement in the merged registry still
+  carries one, so "done" is never diluted.
+
+  \`\`\`ts
+  'AUTH-7': {
+    statement: 'The system MUST require a TOTP code within {totpWindowSec} seconds.',
+    rationale: 'A password alone no longer meets the account-takeover risk we accept.',
+    params: { totpWindowSec: 30 },
+    open: ['is 30 seconds right, or does the authenticator app dictate it?'],
+  },
+  \`\`\`
+
+  This matters more for you than for a human author, and the reason is worth
+  stating plainly: the schema will not let you leave the field out, so an agent
+  that cannot determine a number picks one. A scenario is then written against
+  the invented value, and the result is a single source that is perfectly
+  consistent and describes a promise nobody made — the exact drift this workflow
+  exists to prevent, arriving through the mechanism meant to stop it. Writing
+  the question down costs nothing and blocks nothing until archive time.
 - **A registry is a literal, and so is a delta.** Every value is written in the
   file: no imported constant (\`params: { maxMb: MAX_MB }\`), no computed value,
   no \`Date.now()\`. \`check\`, \`cover\` and \`render\` read \`*.reqs.ts\` with the
@@ -348,6 +372,7 @@ once. Branch on \`issues[].code\`, never on \`message\`:
 | --- | --- |
 | \`tests-red\` | a test is failing — the normal state until you are finished |
 | \`never-red\` | an added requirement's scenario has no recorded failing run |
+| \`open-unresolved\` | a requirement anywhere in the merged registry still declares an \`open\` question |
 | \`uncovered-requirement\` | a requirement in the applied registry has no scenario |
 | \`declared-not-run\` | a scenario was declared but never executed (\`skip\` / \`only\`?) — withdrawn when one of the two rows below already explains its file, so it never stands in for a load failure |
 | \`spec-load-failed\` | a spec file could not be imported, so nothing in it ran. The run output carries the import error itself; this names which file it stopped |

package/dist/core/splice.d.ts

@@ -18,11 +18,11 @@ export declare class UnwritableValue extends Error {
  * body needs one after, and putting that decision here would mean this function
  * had to be told which case it was in anyway.
  *
- * `params` and `outOfScope` are omitted when empty rather than written as `{}`
- * and `[]`. The schema defaults both, so the two spellings mean the same thing,
- * and the shorter one is what a person writing this entry by hand would have
- * produced — which is the standard for a file `--apply` is merging into rather
- * than generating.
+ * `params`, `outOfScope` and `open` are omitted when empty rather than written
+ * as `{}` and `[]`. The schema defaults all three, so the two spellings mean the
+ * same thing, and the shorter one is what a person writing this entry by hand
+ * would have produced — which is the standard for a file `--apply` is merging
+ * into rather than generating.
  */
 export declare function requirementSource(id: string, req: Requirement, indent: string): string;
 /**
@@ -65,7 +65,7 @@ export interface Modification {
 export interface ModifyRefusal {
     reqId: string;
     field?: string;
-    reason: 'comment' | 'entry-not-found' | 'not-a-literal' | 'param-dropped';
+    reason: 'comment' | 'duplicate-key' | 'entry-not-found' | 'not-a-literal' | 'param-dropped';
 }
 export type ModifyResult = {
     ok: true;