@am_shork/attest 0.9.2 → 0.9.4

package/README.md

@@ -167,7 +167,7 @@ Every diagnostic carries a `code`, and every code has a section in
 ```
 ERROR   registry-not-static (requirements/upload.reqs.ts:5)
     Value is not a literal.
-    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.2/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.4/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

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.d.ts

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

package/dist/core/archive.js

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

package/dist/core/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/red-record.d.ts

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

package/dist/core/red-record.js

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

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