@event4u/agent-config 14.22.0 → 15.0.0

package/src/scripts/_lib/continuity_slot.ts

@@ -0,0 +1,295 @@
+/**
+ * The continuity-record slot — capacity policy and state machine.
+ *
+ * `road-to-continuity-writer-activation` step 1.1. Until this module existed
+ * the slot had a producer (`session:recycle`), a consumer
+ * (`handoff_context_hook`) and no documented conflict ownership: the write was
+ * an unguarded `atomic_write_json`, so a second publish replaced whatever sat
+ * there and nobody had decided whether that was correct. With a MANUAL producer
+ * the question was theoretical — a human ran the verb once. Automatic
+ * production makes it routine, which is why the policy is settled here BEFORE
+ * any automatic writer exists.
+ *
+ * The full contract, including why the two rejected alternatives are rejected
+ * on tree evidence rather than on preference, is
+ * `docs/contracts/continuity-record-slot.md`. This module is that document in
+ * code; neither is the source of truth for the other's reasoning, and both are
+ * checked by `tests/scripts/_lib_continuity_slot.test.ts`.
+ *
+ * The policy in one line:
+ *
+ *   SUPERSEDE OWN · REFUSE FOREIGN · QUARANTINE UNUSABLE · NEVER GO BACKWARDS.
+ *
+ * Why not create-if-absent.
+ *
+ * Create-if-absent is the policy the roadmap's own Risk 2 describes as a silent
+ * data loss: "the successor resumes from something plausible and older". It is
+ * rejected. Within one session the resident and the incoming record share a
+ * key, a workspace and a predecessor — the incoming one is the same lineage at
+ * a later moment, so keeping the older is a pure loss with no compensating
+ * safety.
+ *
+ * Why not a bounded multi-record queue.
+ *
+ * Because the reader forbids the resolution such a queue would need. Picking
+ * one of several records requires recency, and `recycle_envelope_paths.ts`
+ * carries a recorded decision against exactly that ("No `latest` index, by
+ * decision" — a pointer to the newest "would restore the shared write target
+ * one layer up"). `resolveContinuityRecord` implements it: several candidates
+ * and no session id START CLEAN rather than pick. A queue would either
+ * contradict that lock or be unreadable.
+ *
+ * Where `consuming` lives.
+ *
+ * Nowhere on disk, and that is the answer rather than a gap. Consumption is a
+ * single `fs.renameSync` from the authoritative name to the consumed name
+ * (`handoff_context_hook.ts:199`), and publication is a single `fs.renameSync`
+ * from a pid-suffixed temp name to the authoritative name
+ * (`state_io.ts:_publish_text_locked`). A rename within one directory is
+ * atomic on every filesystem this package supports, so an interruption lands
+ * strictly before or strictly after it: the authoritative name holds either the
+ * previous complete record or the new complete record, never a partial one.
+ * `consuming` is therefore a transition, not a state, and no reader has to
+ * tolerate a half-written record.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    recycle_consumed_rel,
+    recycle_envelope_rel,
+    recycle_quarantine_rel,
+    RECYCLE_ENVELOPE_MAX_BYTES,
+    RECYCLE_MAX_AGE_HOURS,
+} from './recycle_envelope_paths.js';
+import { validateRecycleEnvelope } from './subagent_capsule.js';
+import { update_json_under_lock } from '../hooks/state_io.js';
+
+/**
+ * The slot's states.
+ *
+ * Five are observable on disk. `consuming` is declared because the roadmap step
+ * names it and a reader looking for it deserves to find the reason it is not a
+ * disk state rather than to conclude it was forgotten — see the module header.
+ */
+export const SLOT_STATES = [
+    'absent',
+    'published',
+    'consuming',
+    'consumed',
+    'quarantined',
+    'conflicting',
+] as const;
+export type SlotState = (typeof SLOT_STATES)[number];
+
+/** What a publish attempt did, and why. The reason is always present. */
+export interface PublishOutcome {
+    /** `published` on a write; otherwise the state that refused it. */
+    state: SlotState;
+    /** Did the authoritative record change as a result of this call? */
+    wrote: boolean;
+    /** One line, always present — emitted by callers, never dropped. */
+    reason: string;
+    /** Absolute path of the record moved aside, when one was. */
+    quarantined?: string;
+}
+
+/** What {@link inspectSlot} found, without changing anything. */
+export interface SlotInspection {
+    state: SlotState;
+    reason: string;
+    /** The authoritative path this session's records live at. */
+    target: string;
+    /** Parsed resident record, when one is present AND parseable. */
+    resident?: Record<string, unknown>;
+}
+
+/** Hours a record stays usable — the reader's own bound, not a second one. */
+const MAX_AGE_MS = RECYCLE_MAX_AGE_HOURS * 3600 * 1000;
+
+function _parse(file: string): Record<string, unknown> | null {
+    try {
+        const decoded: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (typeof decoded === 'object' && decoded !== null && !Array.isArray(decoded)) {
+            return decoded as Record<string, unknown>;
+        }
+        return null;
+    } catch {
+        return null;
+    }
+}
+
+/** Milliseconds since a record's `written_at`, or `null` when it has none. */
+function _ageMs(record: Record<string, unknown>, now: Date): number | null {
+    const raw = record['written_at'];
+    if (typeof raw !== 'string') return null;
+    const at = Date.parse(raw);
+    if (Number.isNaN(at)) return null;
+    return now.getTime() - at;
+}
+
+/**
+ * Read the slot for `session_id` without touching it.
+ *
+ * `conflicting` here is a statement about the RESIDENT relative to the caller's
+ * identity, which is why the session id is required rather than optional: a
+ * record is foreign only with respect to somebody.
+ */
+export function inspectSlot(
+    workspace_root: string,
+    session_id: string | null | undefined,
+    now: Date = new Date(),
+): SlotInspection {
+    const target = path.join(workspace_root, recycle_envelope_rel(session_id));
+    if (!fs.existsSync(target)) {
+        const consumed = path.join(workspace_root, recycle_consumed_rel(session_id));
+        if (fs.existsSync(consumed)) {
+            return { state: 'consumed', reason: 'the record for this session was consumed', target };
+        }
+        const quarantined = path.join(workspace_root, recycle_quarantine_rel(session_id));
+        if (fs.existsSync(quarantined)) {
+            return {
+                state: 'quarantined',
+                reason: 'the slot is free; an unusable record sits in quarantine',
+                target,
+            };
+        }
+        return { state: 'absent', reason: 'no record in this slot', target };
+    }
+    const resident = _parse(target);
+    if (resident === null) {
+        return { state: 'quarantined', reason: 'the resident record does not parse as an object', target };
+    }
+    const violations = validateRecycleEnvelope(resident);
+    if (violations.length > 0) {
+        return {
+            state: 'quarantined',
+            reason: `the resident record fails validation (${violations.length} violation(s))`,
+            target,
+            resident,
+        };
+    }
+    const age = _ageMs(resident, now);
+    if (age === null || age > MAX_AGE_MS) {
+        return {
+            state: 'quarantined',
+            reason:
+                age === null
+                    ? 'the resident record carries no parseable written_at'
+                    : `the resident record is older than ${RECYCLE_MAX_AGE_HOURS} h`,
+            target,
+            resident,
+        };
+    }
+    const owner = String(resident['session_id'] ?? '').trim();
+    const mine = String(session_id ?? '').trim();
+    if (owner !== '' && mine !== '' && owner !== mine) {
+        return {
+            state: 'conflicting',
+            reason: `the slot holds an unconsumed record belonging to session ${owner}`,
+            target,
+            resident,
+        };
+    }
+    return { state: 'published', reason: 'this session has an unconsumed record', target, resident };
+}
+
+/**
+ * Publish `record` into this session's slot under the capacity policy.
+ *
+ * Never throws for a policy reason: a refusal is a return value, because this
+ * runs on the Stop path where an exception is a worse outcome than a missed
+ * record. A genuine I/O failure is reported as `wrote: false` with the reason,
+ * for the same reason.
+ *
+ * The write itself goes through {@link update_json_under_lock} rather than
+ * `atomic_write_json`, and the difference is the whole point: the locked form
+ * gives a read-modify-write, so the resident is inspected and the decision
+ * taken INSIDE the exclusion that stops a peer from publishing between the
+ * inspection and the write. `atomic_write_json` — the path
+ * `session:recycle` still uses — has no such window and cannot express a
+ * refusal.
+ */
+export function publishContinuityRecord(
+    workspace_root: string,
+    session_id: string | null | undefined,
+    record: Record<string, unknown>,
+    now: Date = new Date(),
+): PublishOutcome {
+    const violations = validateRecycleEnvelope(record);
+    if (violations.length > 0) {
+        return {
+            state: 'absent',
+            wrote: false,
+            reason: `refused — the record to publish fails validation: ${violations[0] as string}`,
+        };
+    }
+    const bytes = Buffer.byteLength(JSON.stringify(record, null, 2), 'utf-8');
+    if (bytes > RECYCLE_ENVELOPE_MAX_BYTES) {
+        return {
+            state: 'absent',
+            wrote: false,
+            reason: `refused — ${bytes} bytes exceeds the ${RECYCLE_ENVELOPE_MAX_BYTES} byte slot cap`,
+        };
+    }
+
+    const target = path.join(workspace_root, recycle_envelope_rel(session_id));
+    const before = inspectSlot(workspace_root, session_id, now);
+
+    // A foreign, still-usable record is not this session's to move or replace.
+    // Refusing costs this session's resume; superseding costs another session's,
+    // and that one has no way to find out.
+    if (before.state === 'conflicting') {
+        return { state: 'conflicting', wrote: false, reason: `refused — ${before.reason}` };
+    }
+
+    // Monotonicity. A delayed or retried publisher must not roll the slot back
+    // to an earlier moment of the same session.
+    if (before.state === 'published' && before.resident !== undefined) {
+        const residentAt = Date.parse(String(before.resident['written_at'] ?? ''));
+        const incomingAt = Date.parse(String(record['written_at'] ?? ''));
+        if (!Number.isNaN(residentAt) && !Number.isNaN(incomingAt) && incomingAt < residentAt) {
+            return {
+                state: 'published',
+                wrote: false,
+                reason: 'refused — the resident record is newer than the one offered',
+            };
+        }
+    }
+
+    let quarantined: string | undefined;
+    if (before.state === 'quarantined' && fs.existsSync(target)) {
+        // Move aside, never delete. See `recycle_quarantine_rel`.
+        const dest = path.join(workspace_root, recycle_quarantine_rel(session_id));
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.renameSync(target, dest);
+            quarantined = dest;
+        } catch (exc) {
+            return {
+                state: 'quarantined',
+                wrote: false,
+                reason: `refused — could not quarantine the unusable resident: ${String(exc)}`,
+            };
+        }
+    }
+
+    const result = update_json_under_lock<Record<string, unknown>>(target, () => record);
+    if (result !== 'written') {
+        return {
+            state: before.state,
+            wrote: false,
+            reason: `refused — the slot write did not complete (${result})`,
+            ...(quarantined !== undefined ? { quarantined } : {}),
+        };
+    }
+    return {
+        state: 'published',
+        wrote: true,
+        reason:
+            before.state === 'published'
+                ? 'superseded this session’s earlier record'
+                : `published into a ${before.state} slot`,
+        ...(quarantined !== undefined ? { quarantined } : {}),
+    };
+}

package/src/scripts/_lib/continuity_writer.ts

@@ -0,0 +1,312 @@
+/**
+ * The deterministic continuity-record writer.
+ *
+ * `road-to-continuity-writer-activation` step 1.2. Until this module existed
+ * `agent-config session:recycle` was the ONLY writer of the continuity record
+ * in the tree, which is why `verb:session:recycle` counts on the
+ * `public_continuity_commands` axis and why an advisory had to tell a human to
+ * run it before `/clear`: continuity did not happen unless somebody
+ * remembered. Since step 3.2 (2026-09-10) this module is armed by default and
+ * that advisory is gone; the verb is retained as an explicit affordance, not
+ * as the normal path.
+ *
+ * Every field here is computed from on-disk state and nothing is asked of a
+ * model. That is not a cost optimisation, it is what makes the record a
+ * `continuity_record` rather than a `main_session` one: the judgement fields
+ * (`decisions`, `failed_approaches`, `successful_approaches`, …) are FORBIDDEN
+ * on the variant precisely so a deterministic writer cannot fill one with a
+ * guess and a reader cannot be left unable to tell a derived record from a
+ * judged one.
+ *
+ * Two gates, and both are needed:
+ *
+ *   1. `continuity.auto_record` must be `on`. It ships `on` since 2026-09-10
+ *      (step 3.2, AI council under the owner's written delegation); before
+ *      that it shipped `off` and this module was never reached on a default
+ *      install. The switch still exists and still fails CLOSED, so an
+ *      unreadable settings cascade disarms the producer rather than arming it.
+ *   2. The session must be SUBSTANTIVE by the committed floor
+ *      (`is_substantive`) and must have a resolvable task. Both come from the
+ *      concern's own counters and claim state, never from file presence.
+ *
+ * The task gate is the sharper of the two, and its bound is stated rather than
+ * hidden: a record needs at least one `acceptance_criteria` entry, and the only
+ * deterministic source of one in this tree is the roadmap a session has
+ * claimed. A session with no claim therefore leaves no record — and the
+ * alternative, writing a placeholder acceptance criterion, would assert a
+ * definition of "done" nobody set, which is the exact failure the variant's
+ * forbidden-key set exists to prevent.
+ */
+import * as fs from 'node:fs';
+
+import { load_agent_settings, settings_layer_states } from './agent_settings.js';
+import { resolvePredecessor } from './recycle_envelope_paths.js';
+import { CHECKBOX_LINE, phaseLines } from './roadmap_checkboxes.js';
+import { readHead, roadmapPath } from './run_checkpoint.js';
+import { is_substantive, type StoredEolCounters } from './session_eol.js';
+import { CAPSULE_SCHEMA_VERSION, MAX_ENTRIES, MAX_LINE_CHARS } from './subagent_capsule.js';
+
+/** Settings key that arms this writer. Ships `on` since 2026-09-10 (step 3.2). */
+export const AUTO_RECORD_KEY = 'continuity.auto_record';
+
+/**
+ * Read `continuity.auto_record` from the merged settings cascade.
+ *
+ * The cascade merges the shipped template, so a workspace with no settings file
+ * resolves the TEMPLATE's value. That is what the 2026-09-10 flip acts on:
+ * changing the template to `on` arms a default install.
+ *
+ * FAIL-CLOSED, AND IT IS NOW CARRIED BY CODE RATHER THAN BY THE DEFAULT.
+ *
+ * This function is documented — here, in `docs/contracts/continuity-rollback.md`
+ * and in step 1.4 of its roadmap — as failing closed: a settings cascade the
+ * user has broken must leave the producer disarmed. Until 2026-09-10 that
+ * property was carried by the TEMPLATE saying `off`, not by the `catch` below:
+ * measured, `load_agent_settings` does not throw on a malformed
+ * `.agent-settings.yml`; it skips the layer and returns the template's value.
+ * So the catch never ran for that case, and the flip to `on` removed the
+ * property outright — found by the fixture that was written to pin it.
+ *
+ * The repair is the property, not the wording. An AI council of 2026-09-10
+ * (2 seats, convergent, under the owner's written delegation) ruled option (A):
+ * openai — *"The defective implementation is grounds to repair the protection,
+ * not authority to repeal it."* Both seats classified the alternative (flipping
+ * the documented polarity to fail-open, matching `run_checkpoints_enabled`) as
+ * a WEAKENING of a class-C `consent` protection and therefore owner-reserved,
+ * not council-decidable, even done openly.
+ *
+ * So the malformed case is now decided by `settings_layer_states`, which
+ * reports per-layer validity instead of letting a resolved value stand in for
+ * it. The `catch` stays as the last resort for a genuine throw, and it is no
+ * longer the thing the claim rests on.
+ *
+ * The diagnostic is a required ATTEMPT with non-guaranteed delivery, which is
+ * the strongest promise this path can honestly make: the Stop slot never blocks
+ * and the dispatcher does not forward a concern's stderr on every host, so a
+ * line written here may reach nobody. Saying "warns you" would be the same
+ * class of claim this whole comment exists to correct.
+ */
+export function auto_record_enabled(root: string): boolean {
+    try {
+        // Fail-closed on a layer the USER can break, before the value is read.
+        // Order matters: reading first and checking second would let a valid
+        // template value decide a case in which the user's own file is broken.
+        const broken = settings_layer_states({ cwd: root }).filter((l) => l.state === 'malformed');
+        if (broken.length > 0) {
+            try {
+                process.stderr.write(
+                    `continuity: ${AUTO_RECORD_KEY} disabled for this invocation — ` +
+                        `unreadable or malformed settings layer(s): ` +
+                        `${broken.map((l) => l.path).join(', ')}. ` +
+                        `Validate the file; the shipped default cannot be trusted while a layer above it is broken.\n`,
+                );
+            } catch {
+                // a diagnostic that cannot be written must not change the verdict
+            }
+            return false;
+        }
+        const settings = load_agent_settings({ cwd: root });
+        const section = settings['continuity'];
+        if (section && typeof section === 'object' && !Array.isArray(section)) {
+            const v = (section as Record<string, unknown>)['auto_record'];
+            // YAML 1.1 parses a bare `on` as boolean true — accept both.
+            return v === 'on' || v === true;
+        }
+    } catch {
+        // last resort: a genuine throw leaves the writer disarmed
+    }
+    return false;
+}
+
+/** Settings key that governs run-checkpoint production. Ships `on`. */
+export const RUN_CHECKPOINTS_KEY = 'continuity.run_checkpoints';
+
+/**
+ * Read `continuity.run_checkpoints` from the merged settings cascade.
+ *
+ * Fails OPEN, unlike its sibling above, and the asymmetry is the point: this
+ * switch governs behaviour the tree already had, so an unreadable cascade must
+ * leave it running. Its sibling arms something new, so an unreadable cascade
+ * must leave that disarmed. A single helper with one polarity would have been
+ * wrong for one of the two.
+ *
+ * ONE HONEST QUALIFICATION, from the 2026-09-10 audit of its sibling. This
+ * function's `catch` is unreachable for a malformed settings file too — the
+ * loader skips a broken layer instead of throwing. Its fail-OPEN claim is true
+ * anyway, because the template says `on` and a malformed layer therefore
+ * resolves to `on`. So the polarity holds while the shipped default happens to
+ * agree with it, which is exactly the accident that broke the sibling when its
+ * default flipped. It is left as it is deliberately: the behaviour is correct
+ * today, and hardening a reader whose claim is currently true is a change with
+ * no observable effect. If this key's default ever moves to `off`, this comment
+ * is the notice that the claim moves with it.
+ */
+export function run_checkpoints_enabled(root: string): boolean {
+    try {
+        const settings = load_agent_settings({ cwd: root });
+        const section = settings['continuity'];
+        if (section && typeof section === 'object' && !Array.isArray(section)) {
+            const v = (section as Record<string, unknown>)['run_checkpoints'];
+            if (v === 'off' || v === false) return false;
+        }
+    } catch {
+        // fail-open: an unreadable cascade never silently removes a recovery aid
+    }
+    return true;
+}
+
+/** Why no record was built, when none was. Always a stated reason. */
+export interface WriterDecision {
+    record: Record<string, unknown> | null;
+    reason: string;
+}
+
+/** How many `remaining` / `acceptance_criteria` lines a record carries. */
+const LIST_CAP = 12;
+
+function _clip(line: string): string {
+    const one = line.replace(/\s+/g, ' ').trim();
+    return one.length <= MAX_LINE_CHARS ? one : `${one.slice(0, MAX_LINE_CHARS - 1)}…`;
+}
+
+/**
+ * Open, closed and parked step counts plus the open step bodies.
+ *
+ * Deliberately reuses `phaseLines` + `CHECKBOX_LINE` rather than a fourth
+ * regex: a writer that disagreed with the dashboard about whether a roadmap is
+ * finished would put that disagreement into the record a successor resumes
+ * from.
+ */
+export function roadmapShape(text: string): { done: number; total: number; open: string[] } {
+    let done = 0;
+    let total = 0;
+    const open: string[] = [];
+    for (const raw of phaseLines(text)) {
+        const m = CHECKBOX_LINE.exec(raw);
+        if (m === null) continue;
+        total += 1;
+        const mark = m[1];
+        if (mark === 'x' || mark === 'X') {
+            done += 1;
+            continue;
+        }
+        if (mark === '~' || mark === '-') continue;
+        if (open.length < LIST_CAP) {
+            open.push(_clip((m[2] ?? '').replace(/\*\*/g, '')));
+        }
+    }
+    return { done, total, open };
+}
+
+/**
+ * Checkbox bodies under an `## Acceptance Criteria` heading.
+ *
+ * `phaseLines` deliberately excludes this section — an autonomous run must not
+ * mistake an acceptance criterion for its next step — so it is read separately
+ * here, which is the one place the two readings legitimately differ.
+ */
+export function acceptanceCriteria(text: string): string[] {
+    const lines = text.split('\n');
+    const out: string[] = [];
+    let inside = false;
+    for (const raw of lines) {
+        const heading = /^(#{2,3})[ \t]+(.*?)[ \t]*$/.exec(raw);
+        if (heading !== null) {
+            inside = /^Acceptance[ \t]+Criteria\b/i.test(heading[2] ?? '');
+            continue;
+        }
+        if (!inside) continue;
+        const m = CHECKBOX_LINE.exec(raw);
+        if (m === null) continue;
+        if (out.length < LIST_CAP) {
+            out.push(_clip((m[2] ?? '').replace(/\*\*/g, '')));
+        }
+    }
+    return out;
+}
+
+export interface BuildInput {
+    /** Workspace root — the record's `workspace`, and the root every read is relative to. */
+    root: string;
+    /** Raw session id, as the record paths and the claim state key on it. */
+    sessionId: string;
+    /** The roadmap slug this session claimed, or `null` when it claimed none. */
+    slug: string | null;
+    /** The concern's own counters for this session. */
+    counters: StoredEolCounters | null;
+    /** Injected for determinism in tests. */
+    now?: Date;
+}
+
+/**
+ * Build the record, or say why there is none.
+ *
+ * Never throws and never shells out: this runs on the Stop path, where a
+ * subprocess is a latency cost paid on every turn's end and an exception is
+ * worse than a missing record. `head` is read from `.git` directly (worktree
+ * aware) rather than through `git`, and the richer anchor fields
+ * `session:recycle` collects with `git status` are deliberately omitted — the
+ * trade is one drift line for a Stop path that spawns nothing, and it is stated
+ * in `docs/contracts/continuity-record-slot.md` rather than left for a reader
+ * to discover by diffing two producers.
+ */
+export function buildContinuityRecord(input: BuildInput): WriterDecision {
+    const { root, sessionId, slug, counters } = input;
+    const now = input.now ?? new Date();
+
+    if (!is_substantive(counters)) {
+        return {
+            record: null,
+            reason: 'no record — the session is not substantive by the committed floor',
+        };
+    }
+    if (slug === null || slug.trim() === '') {
+        return {
+            record: null,
+            reason: 'no record — no claimed roadmap, so no deterministic acceptance criterion exists',
+        };
+    }
+
+    let text: string;
+    try {
+        text = fs.readFileSync(roadmapPath(root, slug), 'utf-8');
+    } catch {
+        return { record: null, reason: `no record — the claimed roadmap ${slug} is not readable` };
+    }
+
+    const shape = roadmapShape(text);
+    if (shape.total === 0) {
+        return { record: null, reason: `no record — ${slug} carries no phase checkboxes to count` };
+    }
+
+    const declared = acceptanceCriteria(text);
+    const criteria =
+        declared.length > 0
+            ? declared
+            : // A roadmap with no declared criteria still has one definitional
+              // completion condition, and it is derived from the artefact class
+              // rather than judged: every step closed. Anything richer would be
+              // a definition of done nobody wrote.
+              [`every phase step in agents/roadmaps/${slug}.md is closed`];
+
+    const record: Record<string, unknown> = {
+        capsule_version: CAPSULE_SCHEMA_VERSION,
+        variant: 'continuity_record',
+        summary: _clip(`${slug}: ${shape.done} of ${shape.total} steps closed`),
+        task: _clip(slug),
+        workspace: root,
+        written_at: now.toISOString(),
+        acceptance_criteria: criteria.slice(0, MAX_ENTRIES),
+        remaining: shape.open.slice(0, MAX_ENTRIES),
+        predecessor: resolvePredecessor(root, sessionId),
+        artifact_paths: [`agents/roadmaps/${slug}.md`],
+    };
+    if (sessionId.trim() !== '') {
+        record['session_id'] = sessionId.trim();
+    }
+    const head = readHead(root);
+    if (head !== null) {
+        record['head'] = head;
+    }
+    return { record, reason: `record built for ${slug} (${shape.done}/${shape.total} closed)` };
+}

package/src/scripts/_lib/design_system_import.ts

@@ -77,8 +77,21 @@ export interface ComponentObservation {
 }
 
 /** The contract shape. Only `source` is mandatory; every other key is optional. */
+/**
+ * The artefact-maturity block. Two-valued on the axis `design-fidelity`
+ * branches on, with the rung that decided it and the concrete signal — never a
+ * restatement of the verdict. Resolved by `_lib/artifact_maturity.ts`; OPTIONAL
+ * in the file, because absent resolves `finished` by the same rule.
+ */
+export interface SpecBlock {
+    maturity?: string;
+    maturity_source?: string;
+    maturity_signal?: string;
+}
+
 export interface DesignSystem {
     source: SourceBlock;
+    spec?: SpecBlock;
     colors?: { light?: Record<string, string>; dark?: Record<string, string> };
     typography?: { families?: FontFamily[]; scale?: ScaleStep[] };
     spacing?: { base?: string; scale?: string[] };
@@ -259,6 +272,13 @@ const NATIVE_KEY_SHAPE: Record<string, 'object' | 'array'> = {
     shadow: 'object',
     motion: 'object',
     components: 'array',
+    // The artefact-maturity block (`road-to-design-intent-conformance` 3.1,
+    // resolved by `_lib/artifact_maturity.ts`). Added here in the same change
+    // that documented it: without a row the native lane routes it to
+    // `_meta.unmapped` with an "unknown top-level key" note, so the contract
+    // would say the field exists while the importer said it did not. Caught by
+    // a blind review, which read the two surfaces against each other.
+    spec: 'object',
     _meta: 'object',
 };