@event4u/agent-config 14.23.0 → 16.0.0

package/src/scripts/_lib/conformance_report.ts

@@ -0,0 +1,403 @@
+/**
+ * Per-dimension conformance of a port against the artifact it was ported from.
+ *
+ * WHY A DIMENSION REPORT AND NOT A SCORE. `internal/bench/ui` already scores a
+ * port on pixel / dom / tokens / interactions and produces one weighted number.
+ * A number answers "how close", which is the right question for a benchmark and
+ * the wrong one for a fidelity gate: a port can be pixel-identical and still
+ * have dropped a keyboard interaction, inlined every value the project has a
+ * token for, or lost a breakpoint. Averaged into a weighted score those
+ * disappear, because the axis that carries them is small and the axis that
+ * hides them is large.
+ *
+ * A GREEN PIXEL DIFF ALONE CANNOT PRODUCE A PASS, and that is enforced by
+ * construction rather than by policy: pixel similarity is not one of the
+ * dimensions below. It is evidence a human may read; it is never an input to
+ * `overall`.
+ *
+ * WHAT EACH ROW OWES. Every finding cites BOTH sides — what the artifact has
+ * and what the implementation has. A finding that names only the implementation
+ * is unactionable: the reader cannot tell whether the port dropped something or
+ * whether the artifact never had it.
+ *
+ * SCOPE, stated because the honest version is narrower than the obvious one.
+ * These are static checks over two documents' text. They catch the deviations
+ * that leave a textual trace — a value gone, a handler gone, a breakpoint gone.
+ * They do NOT catch a deviation that is only visible when rendered, and they do
+ * not claim to. Where a rendered comparison is available it belongs beside this
+ * report, not inside it.
+ */
+import { type TokenCandidate, type ValueKind, type ValueRow, reconcileValue } from './design_tolerance.js';
+import { recordToleranceShadow } from './tolerance_shadow.js';
+
+export type Dimension = 'structure' | 'values' | 'behaviour' | 'responsive' | 'icons' | 'carrier';
+
+export const DIMENSIONS: readonly Dimension[] = [
+    'structure',
+    'values',
+    'behaviour',
+    'responsive',
+    'icons',
+    'carrier',
+];
+
+export interface Finding {
+    dimension: Dimension;
+    /** What the artifact carries. Never omitted — see the header. */
+    artifact: string;
+    /** What the implementation carries in its place. */
+    implementation: string;
+    detail: string;
+}
+
+export interface DimensionVerdict {
+    dimension: Dimension;
+    verdict: 'conforms' | 'deviates';
+    findings: Finding[];
+}
+
+export interface ConformanceReport {
+    dimensions: DimensionVerdict[];
+    /** Value rows with their distance, reported whether or not they deviate. */
+    values: ValueRow[];
+    overall: 'conforms' | 'deviates';
+    /** Dimensions that deviated, in `DIMENSIONS` order. */
+    deviating: Dimension[];
+}
+
+// ------------------------------------------------------------- extraction
+
+const HEX_RE = /#[0-9a-fA-F]{3}\b|#[0-9a-fA-F]{6}\b/g;
+const LENGTH_RE = /\b\d*\.?\d+(?:px|rem)\b/g;
+const TAG_RE = /<([a-zA-Z][a-zA-Z0-9-]*)\b/g;
+// EVERY width bound in a query, not the first. `@media (min-width: 48rem) and
+// (max-width: 80rem)` has two, and capturing one left `80rem` counted as a
+// VALUE — which reds two dimensions for one corruption and breaks the
+// one-dimension property 4.1's verify clause rests on. Found by a blind review.
+const MEDIA_QUERY_RE = /@media[^{]+/g;
+const MEDIA_BOUND_RE = /\(\s*(?:min|max)-width\s*:\s*([^)]+)\)/g;
+// Case-insensitive on the listener name: the first version required an
+// all-lowercase quoted name, so `addEventListener('DOMContentLoaded', …)` and
+// any camelCase custom event were invisible to the behavior dimension that
+// exists to catch a dropped interaction. Blind-review finding.
+const LISTENER_RE = /addEventListener\(\s*['"]([A-Za-z][A-Za-z0-9_:.-]*)['"]/g;
+
+/**
+ * `on*` ATTRIBUTES, matched against a closed set rather than by shape.
+ *
+ * A word boundary does not separate `onclick` from `onboarding` — both begin
+ * with `on` and both are followed by `=`, so a shape rule reads the second as a
+ * hook named `boarding`. It is the inline-handler namespace that is closed, so
+ * the set is what discriminates. A custom event never appears as an attribute
+ * anyway; it appears in `addEventListener`, which the regex above reads openly.
+ */
+const INLINE_EVENTS = new Set([
+    'click', 'dblclick', 'mousedown', 'mouseup', 'mouseenter', 'mouseleave',
+    'mousemove', 'mouseover', 'mouseout', 'keydown', 'keyup', 'keypress',
+    'input', 'change', 'submit', 'reset', 'focus', 'blur', 'focusin',
+    'focusout', 'scroll', 'wheel', 'load', 'error', 'resize', 'toggle',
+    'select', 'drag', 'dragstart', 'dragend', 'dragover', 'drop', 'touchstart',
+    'touchend', 'touchmove', 'pointerdown', 'pointerup', 'pointermove',
+    'animationend', 'transitionend', 'contextmenu', 'copy', 'cut', 'paste',
+    'invalid', 'play', 'pause', 'ended',
+]);
+const ON_ATTR_RE = /(?:^|[\s"'`<])on([a-z]+)\s*=/g;
+// Attribute-bounded and quote-agnostic. Unbounded, it false-positived on any
+// attribute ENDING in `style` (`data-style=`, `hover-style=`); double-quote-only,
+// it missed `style='…'` entirely. Blind-review finding.
+const INLINE_STYLE_RE = /(?:^|[\s"'`<])style\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+
+/** Landmark and control tags — the structural skeleton, not every `<div>`. */
+const STRUCTURAL_TAGS = new Set([
+    'main',
+    'header',
+    'footer',
+    'nav',
+    'aside',
+    'section',
+    'article',
+    'form',
+    'table',
+    'dialog',
+    'button',
+    'input',
+    'select',
+    'textarea',
+    'a',
+    'label',
+    'svg',
+]);
+
+function setMinus(a: Set<string>, b: Set<string>): Set<string> {
+    const out = new Set<string>();
+    for (const v of a) if (!b.has(v)) out.add(v);
+    return out;
+}
+
+function matchSet(text: string, re: RegExp, group = 0): Set<string> {
+    const out = new Set<string>();
+    for (const m of text.matchAll(re)) {
+        const v = m[group];
+        if (typeof v === 'string' && v !== '') out.add(v.toLowerCase().trim());
+    }
+    return out;
+}
+
+/** Counts per structural tag; a dropped control is a count change, not absence. */
+export function structuralCounts(html: string): Map<string, number> {
+    const counts = new Map<string, number>();
+    for (const m of html.matchAll(TAG_RE)) {
+        const tag = (m[1] as string).toLowerCase();
+        if (!STRUCTURAL_TAGS.has(tag)) continue;
+        counts.set(tag, (counts.get(tag) ?? 0) + 1);
+    }
+    return counts;
+}
+
+/** Event names the document wires, from listeners and from `on*` attributes. */
+export function behaviourHooks(html: string): Set<string> {
+    const out = new Set<string>();
+    for (const m of html.matchAll(LISTENER_RE)) {
+        out.add((m[1] as string).toLowerCase());
+    }
+    for (const m of html.matchAll(ON_ATTR_RE)) {
+        const name = (m[1] as string).toLowerCase();
+        if (INLINE_EVENTS.has(name)) out.add(name);
+    }
+    return out;
+}
+
+/** Breakpoints, normalised so `48rem` and `48 rem` are one value. */
+export function breakpoints(html: string): Set<string> {
+    const out = new Set<string>();
+    for (const q of html.matchAll(MEDIA_QUERY_RE)) {
+        for (const b of (q[0] as string).matchAll(MEDIA_BOUND_RE)) {
+            const v = (b[1] as string).toLowerCase().trim();
+            if (v !== '') out.add(v);
+        }
+    }
+    return out;
+}
+
+/**
+ * Static declarations sitting in a `style=` attribute.
+ *
+ * The carrier axis: static presentation belongs in CSS or classes, and `style=`
+ * is for what only the runtime knows. A port that moves the artifact's inline
+ * styles into classes is CONFORMING as long as the resolved value is identical
+ * — which is why this counts declarations the IMPLEMENTATION added, never ones
+ * it removed.
+ */
+export function inlineStaticDeclarations(html: string): string[] {
+    const out: string[] = [];
+    for (const m of html.matchAll(INLINE_STYLE_RE)) {
+        for (const decl of ((m[1] ?? m[2] ?? '') as string).split(';')) {
+            const trimmed = decl.trim();
+            if (trimmed === '') continue;
+            // A custom property or a `var()` is plausibly runtime-driven.
+            if (trimmed.startsWith('--') || trimmed.includes('var(')) continue;
+            out.push(trimmed.toLowerCase());
+        }
+    }
+    return out;
+}
+
+/** Inline `<svg>` occurrences — the icon carrier a port reproduces. */
+export function inlineSvgCount(html: string): number {
+    return (html.match(/<svg\b/gi) ?? []).length;
+}
+
+// ------------------------------------------------------------------ report
+
+function verdictFor(dimension: Dimension, findings: Finding[]): DimensionVerdict {
+    return { dimension, verdict: findings.length > 0 ? 'deviates' : 'conforms', findings };
+}
+
+export interface ReportInput {
+    artifact: string;
+    implementation: string;
+    /** Project tokens, so a value row can carry its distance. */
+    tokens?: readonly TokenCandidate[];
+    /**
+     * Repo root. When given, every measurable value row is appended to the
+     * shadow log as a `tolerance_shadow` record.
+     *
+     * OPT-IN, and that is the whole design: a report is also built by tests and
+     * by a reader inspecting a port, and a window that recorded those would be
+     * measuring its own test fixtures. The caller that wants the window says so.
+     */
+    shadowRoot?: string;
+}
+
+/**
+ * Build the report. Pure over two strings, so a test can corrupt exactly one
+ * dimension and assert that exactly one reds.
+ */
+export function buildConformanceReport(input: ReportInput): ConformanceReport {
+    const { artifact, implementation } = input;
+    const tokens = input.tokens ?? [];
+
+    // --- structure
+    const structureFindings: Finding[] = [];
+    const aCounts = structuralCounts(artifact);
+    const iCounts = structuralCounts(implementation);
+    for (const tag of new Set([...aCounts.keys(), ...iCounts.keys()])) {
+        const a = aCounts.get(tag) ?? 0;
+        const i = iCounts.get(tag) ?? 0;
+        // `svg` is the icons dimension's subject; counting it here too would
+        // red two dimensions for one corruption and break the step's verify.
+        if (tag === 'svg' || a === i) continue;
+        structureFindings.push({
+            dimension: 'structure',
+            artifact: `${String(a)} × <${tag}>`,
+            implementation: `${String(i)} × <${tag}>`,
+            detail: `structural element count differs for <${tag}>`,
+        });
+    }
+
+    // --- values, and their distances
+    const aHex = matchSet(artifact, HEX_RE);
+    const iHex = matchSet(implementation, HEX_RE);
+    // A breakpoint's own length belongs to `responsive`, not to `values`.
+    // Without this both axes red on one corruption — measured: dropping
+    // `@media (min-width: 48rem)` also dropped `48rem` from the value set, so
+    // the responsive case reported `['values', 'responsive']` and the step's
+    // "and no other" clause could not hold. Same shape as the `svg` exclusion
+    // in the structure loop above.
+    const aLen = setMinus(matchSet(artifact, LENGTH_RE), breakpoints(artifact));
+    const iLen = setMinus(matchSet(implementation, LENGTH_RE), breakpoints(implementation));
+    const valueFindings: Finding[] = [];
+    const valueRows: ValueRow[] = [];
+    // Parallel to `valueRows`: a row does not carry its own kind, and the
+    // shadow record needs it to pick the right candidate-threshold spread.
+    const valueKinds: ValueKind[] = [];
+
+    for (const hex of aHex) {
+        // Reported on every value, present or missing — the distance is the
+        // point, not the verdict (`design_tolerance.ts` header).
+        valueRows.push(reconcileValue('color', hex, tokens));
+        valueKinds.push('color');
+        if (!iHex.has(hex)) {
+            valueFindings.push({
+                dimension: 'values',
+                artifact: hex,
+                implementation: iHex.size > 0 ? `absent (port uses ${[...iHex].join(', ')})` : 'absent',
+                detail: 'a colour the artifact states does not appear in the port',
+            });
+        }
+    }
+    for (const len of aLen) {
+        valueRows.push(reconcileValue('length', len, tokens));
+        valueKinds.push('length');
+        if (!iLen.has(len)) {
+            valueFindings.push({
+                dimension: 'values',
+                artifact: len,
+                implementation: 'absent',
+                detail: 'a length the artifact states does not appear in the port',
+            });
+        }
+    }
+
+    // --- behaviour
+    const aHooks = behaviourHooks(artifact);
+    const iHooks = behaviourHooks(implementation);
+    const behaviourFindings: Finding[] = [];
+    for (const hook of aHooks) {
+        if (iHooks.has(hook)) continue;
+        behaviourFindings.push({
+            dimension: 'behaviour',
+            artifact: `wires \`${hook}\``,
+            implementation: 'not wired',
+            detail: `an interaction the artifact wires is missing from the port`,
+        });
+    }
+
+    // --- responsive
+    const aBp = breakpoints(artifact);
+    const iBp = breakpoints(implementation);
+    const responsiveFindings: Finding[] = [];
+    for (const bp of aBp) {
+        if (iBp.has(bp)) continue;
+        responsiveFindings.push({
+            dimension: 'responsive',
+            artifact: `breakpoint ${bp}`,
+            implementation: iBp.size > 0 ? `only ${[...iBp].join(', ')}` : 'no breakpoints',
+            detail: 'a breakpoint the artifact declares is missing from the port',
+        });
+    }
+
+    // --- icons
+    const aSvg = inlineSvgCount(artifact);
+    const iSvg = inlineSvgCount(implementation);
+    const iconFindings: Finding[] = [];
+    if (aSvg !== iSvg) {
+        iconFindings.push({
+            dimension: 'icons',
+            artifact: `${String(aSvg)} inline <svg>`,
+            implementation: `${String(iSvg)} inline <svg>`,
+            detail: 'the port does not carry the artifact’s icon count',
+        });
+    }
+
+    // --- carrier
+    const aInline = new Set(inlineStaticDeclarations(artifact));
+    const carrierFindings: Finding[] = [];
+    for (const decl of inlineStaticDeclarations(implementation)) {
+        if (aInline.has(decl)) continue;
+        carrierFindings.push({
+            dimension: 'carrier',
+            artifact: 'not inline in the artifact',
+            implementation: `style="${decl}"`,
+            detail: 'a static declaration the port put inline; static presentation belongs in a class',
+        });
+    }
+
+    const dimensions: DimensionVerdict[] = [
+        verdictFor('structure', structureFindings),
+        verdictFor('values', valueFindings),
+        verdictFor('behaviour', behaviourFindings),
+        verdictFor('responsive', responsiveFindings),
+        verdictFor('icons', iconFindings),
+        verdictFor('carrier', carrierFindings),
+    ];
+    const deviating = dimensions.filter((d) => d.verdict === 'deviates').map((d) => d.dimension);
+
+    // The one place the shadow window is fed. Without this the records the
+    // flip criterion is meant to read never exist, and its reverse trigger is
+    // satisfied by construction — the defect a blind review caught on the
+    // branch that introduced the module.
+    if (input.shadowRoot !== undefined) {
+        recordToleranceShadow(
+            input.shadowRoot,
+            valueRows.map((row, i) => ({ kind: valueKinds[i] as ValueKind, row })),
+        );
+    }
+
+    return {
+        dimensions,
+        values: valueRows,
+        overall: deviating.length > 0 ? 'deviates' : 'conforms',
+        deviating,
+    };
+}
+
+/** One line per dimension, then the value rows with their distances. */
+export function formatConformanceReport(report: ConformanceReport): string {
+    const lines: string[] = [];
+    for (const d of report.dimensions) {
+        const mark = d.verdict === 'conforms' ? '✅' : '❌';
+        lines.push(`${mark} ${d.dimension}: ${d.verdict} (${String(d.findings.length)} finding(s))`);
+        for (const f of d.findings) {
+            lines.push(`     artifact: ${f.artifact}  ·  port: ${f.implementation}  —  ${f.detail}`);
+        }
+    }
+    lines.push(
+        `\noverall: ${report.overall}` +
+            (report.deviating.length > 0 ? ` (${report.deviating.join(', ')})` : ''),
+    );
+    // Stated on every report, not only on a failing one: a reader who sees a
+    // pass has to know what it did NOT measure.
+    lines.push('pixel similarity is not a dimension here and cannot produce a pass on its own.');
+    return lines.join('\n');
+}

package/src/scripts/_lib/continuity_writer.ts

@@ -4,9 +4,11 @@
  * `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 has to tell a human to
+ * `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.
+ * 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
@@ -18,9 +20,11 @@
  *
  * Two gates, and both are needed:
  *
- *   1. `continuity.auto_record` must be `on`. It ships `off`, so with the
- *      shipped default this module is never reached and the tree behaves
- *      exactly as it does today.
+ *   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.
@@ -35,28 +39,72 @@
  */
 import * as fs from 'node:fs';
 
-import { load_agent_settings } from './agent_settings.js';
+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 `off`. */
+/** 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 `off` through the template rather than through the trailing
- * `return false` — which is why that line is defence against an unreadable
- * cascade and not the path a default install takes. Both directions are pinned
- * by fixtures, because "absent" and "off" arriving by different routes is
- * exactly the kind of thing a reader assumes and a test has to establish.
+ * 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)) {
@@ -65,7 +113,7 @@ export function auto_record_enabled(root: string): boolean {
             return v === 'on' || v === true;
         }
     } catch {
-        // fail-closed: unreadable settings leave the writer disarmed
+        // last resort: a genuine throw leaves the writer disarmed
     }
     return false;
 }
@@ -81,6 +129,17 @@ export const RUN_CHECKPOINTS_KEY = 'continuity.run_checkpoints';
  * 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 {

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',
 };