@event4u/agent-config 10.2.0 → 10.4.0

package/src/scripts/check_suppression_hygiene.ts

@@ -227,9 +227,20 @@ export const SUPPRESSION_INVENTORY: readonly SuppressionSpec[] = [
         file: 'src/config/rule-enforcement-baseline.json',
         listKey: null,
         tier: 'string_list',
-        newInThisChange: true,
         what: 'rules predating the enforced_by-declaration ratchet',
     },
+    {
+        // Two committed prompt→verdict bindings that do not re-derive. Both
+        // sit inside round records § 2.7 declares immutable, so neither may be
+        // repaired by editing the record — the entry pins BOTH hashes, so a
+        // later repair or a further corruption reds instead of passing.
+        file: 'src/config/review-prompt-binding-baseline.json',
+        listKey: 'entries',
+        tier: 'object',
+        keyFields: ['slug'],
+        newInThisChange: true,
+        what: 'review prompts whose recorded prompt_hash does not re-derive',
+    },
 ];
 
 export interface SuppressionFinding {
@@ -391,6 +402,12 @@ export function main(): number {
         const entries = loadEntries(spec);
         const reasonField = spec.reasonField ?? 'reason';
 
+        // Declared BEFORE the stale-flag branch below, which is a file-level
+        // finding: it must feed the single terminal resolution at the end of
+        // this iteration rather than resolve the target itself. Resolving twice
+        // is a `LedgerUsageError` that aborts the whole gate.
+        let fileFindings = 0;
+
         let comparison: RatchetComparison;
         try {
             comparison = compareToBaseRef({
@@ -413,8 +430,8 @@ export function main(): number {
                     `\`newInThisChange\` is still set, but the baseline now resolves at ${baseRef} — ` +
                     'the flag has served its purpose and must be removed from SUPPRESSION_INVENTORY. ' +
                     'Leaving it set makes a future mistyped path pass as a new baseline forever.';
-                ledger.fail(spec.file, detail);
                 findings.push({ file: spec.file, entry: '(whole file)', kind: 'uninventoried', detail });
+                fileFindings += 1;
             }
         } catch (exc) {
             if (exc instanceof BaseRefUnavailableError) {
@@ -426,7 +443,6 @@ export function main(): number {
         }
 
         const added = new Set(comparison.added);
-        let fileFindings = 0;
 
         for (const entry of entries) {
             if (spec.tier === 'object' && entry.reason.length < MIN_REASON_CHARS) {

package/src/scripts/design_slop_rules.test.ts

@@ -100,16 +100,11 @@ const FIXTURES: Record<string, { ext: string; positive: string; negative: string
     negative:
       '<h1>Get Started</h1><p>Deploys are marked ✅ when healthy.</p><td>✅</td><button>Track progress</button>',
   },
-  "slop-lock-shape": {
+  "slop-v8-lock-shape": {
     ext: "css",
     positive: ".a{border-radius:4px}.b{border-radius:8px}.c{border-radius:12px}.d{border-radius:20px}",
     negative: ".a{border-radius:8px}.b{border-radius:12px}",
   },
-  "slop-lock-colour": {
-    ext: "css",
-    positive: ".a{color:#e11d48}.b{background:#2563eb}.c{border-color:#16a34a}",
-    negative: ".a{color:#111827}.b{background:#6b7280}.c{border-color:#2563eb}",
-  },
   "slop-l9-section-monotony": {
     ext: "html",
     // 8 identical media+text sections → 1 distinct layout family (< 4)
@@ -129,6 +124,42 @@ const FIXTURES: Record<string, { ext: string; positive: string; negative: string
     // only 2 consecutive → within cap
     negative: '<section><div class="grid"><img src="x"><h2>A</h2><p>t</p></div></section>'.repeat(2),
   },
+  "slop-v4-over-rounded": {
+    ext: "css",
+    // 24px radius on an 80px chip — mid-range rounding on a small surface
+    positive: ".chip{width:80px;border-radius:24px;background:#1f5f9c}",
+    // a deliberate pill is a shape decision, not over-rounding
+    negative: ".chip{width:80px;border-radius:9999px;background:#1f5f9c}",
+  },
+  "slop-c3-dark-glow": {
+    ext: "css",
+    // zero-offset saturated glow inside a declared dark surface
+    positive: ".dark .btn{background:#0b0f14;box-shadow:0 0 18px #22d3ee}",
+    // same dark surface, ordinary offset depth — not a glow
+    negative: ".dark .btn{background:#0b0f14;box-shadow:0 2px 8px #22d3ee}",
+  },
+  "slop-t9-uppercase-body": {
+    ext: "css",
+    positive: "article p{text-transform:uppercase;font-size:16px}",
+    // a short field label is the legitimate home of uppercase
+    negative: ".field-label{text-transform:uppercase;font-size:12px}",
+  },
+  "slop-t10-wide-tracking-body": {
+    ext: "css",
+    positive: "article p{letter-spacing:0.12em;font-size:16px}",
+    negative: "article p{letter-spacing:0.01em;font-size:16px}",
+  },
+  "slop-m1-bounce-easing": {
+    ext: "css",
+    // y1 = 1.56 overshoots the target and returns — the bounce signature
+    positive: ".card{transition:transform .3s cubic-bezier(.34,1.56,.64,1)}",
+    negative: ".card{transition:transform .3s cubic-bezier(.4,0,.2,1)}",
+  },
+  "slop-m3-img-hover-transform": {
+    ext: "css",
+    positive: ".tile:hover img{transform:scale(1.05)}",
+    negative: ".tile:hover .tile__title{color:#16202b}",
+  },
 };
 
 function findingsFor(ruleId: string, content: string, ext: string, ctx = NO_CTX) {

package/src/scripts/design_slop_rules.ts

@@ -17,6 +17,14 @@
  * dependency-free approach. Council 2026-06-28 assumed those libs were present;
  * for THIS package, pattern-based is the correct, frugal adaptation.
  *
+ * WHAT THE NEGATIVE FIXTURES ARE NOT: each rule ships one positive and one
+ * negative fixture, and the suite asserts both exist. That is a PRESENCE guard —
+ * "this regex stays quiet on one clean snippet crafted for it" — and it is NOT a
+ * false-positive RATE. Nineteen green negatives say nothing about how often a
+ * rule fires on clean UI it has never seen. Reading them as an FP measurement is
+ * the mistake that makes the registry look better-evidenced than it is; the rate
+ * is measured against the clean corpus under `internal/bench/corpora/`, not here.
+ *
  * Severity is a REBUTTABLE PRESUMPTION, never a hard block:
  *   P0 — objective failure (none here; those live in lint_design_quality)
  *   P1 — high-confidence tell (e.g. the side-stripe signature)
@@ -437,7 +445,7 @@ export const SLOP_RULES: SlopRule[] = [
     },
   },
   {
-    id: "slop-lock-shape",
+    id: "slop-v8-lock-shape",
     catalogId: "V8",
     severity: "P2",
     engines: ["css"],
@@ -464,27 +472,6 @@ export const SLOP_RULES: SlopRule[] = [
       return [];
     },
   },
-  {
-    id: "slop-lock-colour",
-    catalogId: "C6",
-    severity: "P3",
-    engines: ["css"],
-    description: "Colour Lock — multiple saturated accent hue families",
-    message: "Several accent hue families read as no single accent identity; lock one (C6 / Colour Lock).",
-    gated: (ctx) => ctx.has("colour lock", "color lock"),
-    detect: ({ content }) => {
-      const buckets = new Set<number>();
-      for (const pm of content.matchAll(/#([0-9a-f]{3}|[0-9a-f]{6})\b/gi)) {
-        const b = hueBucket("#" + (pm[1] ?? ""));
-        if (b !== null) buckets.add(b);
-      }
-      if (buckets.size >= 3) {
-        const idx = content.search(/#[0-9a-f]{3,6}\b/i);
-        return [{ line: lineOf(content, Math.max(0, idx)), snippet: `${buckets.size} distinct accent hue families` }];
-      }
-      return [];
-    },
-  },
   {
     id: "slop-l9-section-monotony",
     catalogId: "L9",
@@ -527,4 +514,145 @@ export const SLOP_RULES: SlopRule[] = [
       return [];
     },
   },
+  // -------------------------------------------------------------------------
+  // Catalog thresholds promoted to rules (road-to-design-detector-evidence
+  // Phase 3). Each entry below already published its number in
+  // docs/guidelines/design-antipatterns.md — the prose is the specification,
+  // nothing here is invented, and each was graded per rule against the clean
+  // corpus rather than as a batch.
+  // -------------------------------------------------------------------------
+  {
+    id: "slop-v4-over-rounded",
+    catalogId: "V4",
+    severity: "P3",
+    engines: ["css"],
+    description: "border-radius > 16px on an element declared under 200px wide",
+    message: "Heavy rounding on a small surface reads as scaffold-default; scale the radius to the element (V4).",
+    gated: (ctx) => ctx.has("pill", "fully rounded", "soft ui", "claymorphism"),
+    detect: ({ content }) =>
+      cssBlocks(content)
+        .filter((b) => {
+          // A pill (9999px / 50% / 999px) and a circle are deliberate shapes,
+          // not over-rounding — the tell is a mid-range radius on a small box.
+          const r = /border-radius\s*:\s*(\d+)px/i.exec(b.body);
+          if (!r?.[1]) return false;
+          const radius = parseInt(r[1], 10);
+          if (radius <= 16 || radius >= 100) return false;
+          // "small" must be declared in the same block; nothing here infers
+          // layout, because inferring it would need a cascade.
+          const size = /(?:^|[;{\s])(?:max-)?(?:width|height)\s*:\s*(\d+)px/i.exec(b.body);
+          return size?.[1] !== undefined && parseInt(size[1], 10) < 200;
+        })
+        .map((b) => ({ line: b.line, snippet: b.selector.slice(0, 80) })),
+  },
+  {
+    id: "slop-c3-dark-glow",
+    catalogId: "C3",
+    severity: "P2",
+    engines: ["css"],
+    description: "Saturated zero-offset glow (box-shadow / text-shadow) in a dark context",
+    message: "A neon glow on dark reads as gaming-UI default rather than a considered accent (C3).",
+    gated: (ctx) => ctx.has("glow", "neon", "cyberpunk", "gaming"),
+    detect: ({ content, lines }) => {
+      // The tell is dark-context-specific, so a file with no dark surface at all
+      // is out of scope — a glow on a light page is a different question.
+      const darkContext =
+        /prefers-color-scheme\s*:\s*dark/i.test(content) ||
+        /\.dark\b|\[data-theme=["']?dark/i.test(content) ||
+        /background(?:-color)?\s*:\s*#(?:0[0-9a-f]{5}|1[0-9a-f]{5}|000|111)\b/i.test(content);
+      if (!darkContext) return [];
+      const out: RawHit[] = [];
+      for (let i = 0; i < lines.length; i++) {
+        const l = lines[i] ?? "";
+        // zero-offset + real blur is the glow signature; an offset shadow is depth.
+        const m = /(?:box|text)-shadow\s*:\s*0\s+0\s+(\d+)px[^;]*?(#[0-9a-f]{3,8})/i.exec(l);
+        if (!m?.[1] || !m[2]) continue;
+        if (parseInt(m[1], 10) < 8) continue;
+        if (hueBucket(m[2]) === null) continue; // a neutral halo is not a neon accent
+        out.push({ line: i + 1, snippet: l.trim().slice(0, 80) });
+      }
+      return out;
+    },
+  },
+  {
+    id: "slop-t9-uppercase-body",
+    catalogId: "T9",
+    severity: "P3",
+    engines: ["css"],
+    description: "text-transform: uppercase applied to body-length text",
+    message: "All-caps destroys word-shape for sustained reading; reserve it for short labels (T9).",
+    gated: (ctx) => ctx.has("all caps", "all-caps", "uppercase display"),
+    detect: ({ content }) =>
+      cssBlocks(content)
+        // Short UI surfaces (labels, buttons, table headers, badges, eyebrows)
+        // are the legitimate home of uppercase and are excluded by selector.
+        .filter((b) => /\b(p|body|article|\.prose|\.body|\.content|\.copy|blockquote|li)\b/i.test(b.selector))
+        .filter((b) => !/label|button|\bth\b|badge|chip|tag|eyebrow|kicker|caption|nav/i.test(b.selector))
+        .filter((b) => /text-transform\s*:\s*uppercase/i.test(b.body))
+        .map((b) => ({ line: b.line, snippet: b.selector.slice(0, 80) })),
+  },
+  {
+    id: "slop-t10-wide-tracking-body",
+    catalogId: "T10",
+    severity: "P3",
+    engines: ["css"],
+    description: "letter-spacing above 0.05em on body-length text",
+    message: "Wide tracking slows sustained reading; it belongs to display type, not body (T10).",
+    gated: (ctx) => ctx.has("wide tracking", "letterspacing", "letter-spacing"),
+    detect: ({ content }) =>
+      cssBlocks(content)
+        .filter((b) => /\b(p|body|article|\.prose|\.body|\.content|\.copy|blockquote|li)\b/i.test(b.selector))
+        .filter((b) => !/label|button|\bth\b|badge|chip|tag|eyebrow|kicker|caption|nav|h[1-6]/i.test(b.selector))
+        .filter((b) => {
+          const em = /letter-spacing\s*:\s*(\d*\.?\d+)(em|rem)/i.exec(b.body);
+          if (em?.[1]) return parseFloat(em[1]) > 0.05;
+          const px = /letter-spacing\s*:\s*(\d*\.?\d+)px/i.exec(b.body);
+          return px?.[1] !== undefined && parseFloat(px[1]) > 0.8;
+        })
+        .map((b) => ({ line: b.line, snippet: b.selector.slice(0, 80) })),
+  },
+  {
+    id: "slop-m1-bounce-easing",
+    catalogId: "M1",
+    severity: "P2",
+    engines: ["css"],
+    description: "Bounce or elastic easing on a UI transition",
+    message: "Overshoot draws attention to the animation instead of the state change (M1).",
+    gated: (ctx) => ctx.has("bounce", "playful motion", "elastic"),
+    detect: ({ lines }) => {
+      const out: RawHit[] = [];
+      for (let i = 0; i < lines.length; i++) {
+        const l = lines[i] ?? "";
+        // Overshoot is decidable from the curve itself: a control point outside
+        // [0,1] on the output axis means the value passes its target and returns.
+        const cb = /cubic-bezier\(\s*[-\d.]+\s*,\s*(-?[\d.]+)\s*,\s*[-\d.]+\s*,\s*(-?[\d.]+)\s*\)/i.exec(l);
+        if (cb?.[1] !== undefined && cb[2] !== undefined) {
+          const y1 = parseFloat(cb[1]);
+          const y2 = parseFloat(cb[2]);
+          if (y1 < 0 || y1 > 1 || y2 < 0 || y2 > 1) {
+            out.push({ line: i + 1, snippet: l.trim().slice(0, 80) });
+            continue;
+          }
+        }
+        if (/(?:transition|animation)[^;]*\b(?:bounce|elastic|back(?:In|Out|InOut))\b/i.test(l)) {
+          out.push({ line: i + 1, snippet: l.trim().slice(0, 80) });
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "slop-m3-img-hover-transform",
+    catalogId: "M3",
+    severity: "P3",
+    engines: ["css"],
+    description: "transform or filter animation on an <img> hover",
+    message: "Hover-scaling an image triggers composite plus decode and often shifts layout (M3).",
+    gated: (ctx) => ctx.has("image hover", "hover zoom", "ken burns"),
+    detect: ({ content }) =>
+      cssBlocks(content)
+        .filter((b) => /\bimg\b/i.test(b.selector) && /:hover|:focus-within/i.test(b.selector))
+        .filter((b) => /(?:^|[;{\s])(?:transform|filter)\s*:/i.test(b.body))
+        .map((b) => ({ line: b.line, snippet: b.selector.slice(0, 80) })),
+  },
 ];

package/src/scripts/design_system_import.ts

@@ -0,0 +1,264 @@
+#!/usr/bin/env tsx
+/**
+ * Import an extracted design system into the `design-system.json` contract.
+ *
+ * Producer-side half of the contract in
+ * `design-system-capture/references/design-system-json.md`
+ * (road-to-design-system-onramp Phase 1). Three input lanes — a native
+ * artifact, a W3C DTCG token file, or an extraction tool's raw JSON — one
+ * output shape.
+ *
+ * **Pure and offline by construction.** It reads a file, transforms it, and
+ * writes to stdout. No network, no browser, no crawl: the package owns the
+ * contract and not the crawler (council 2026-06-28), and a transform that
+ * fetched would quietly become the thing the lock forbids.
+ *
+ * The output is a **proposal**, never an applied change. It is handed to
+ * `design-system-capture`, whose import step confirms it per field against
+ * `DESIGN.md` and flags — never auto-applies — anything that conflicts with a
+ * registered brand token.
+ *
+ * CLI:
+ *
+ *   ./scripts-run src/scripts/design_system_import <file> [options]
+ *
+ *   --lane {native,dtcg,dembrandt}  Force a lane instead of detecting it.
+ *   --source-kind {url,repo,dir}    Provenance for formats that carry none.
+ *   --source-ref REF                Provenance ref (the URL / repo / path).
+ *   --captured-at ISO               Capture time; omitted records "unknown".
+ *   --format {json,summary}         json (default) or a human-readable summary.
+ *
+ * Exit codes:
+ *
+ *   0 — imported; the artifact is on stdout (or its summary).
+ *   1 — the input was rejected (no lane matched, or no provenance).
+ *   2 — argument error.
+ *   3 — internal error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    type ImportOutcome,
+    type Lane,
+    type ProvenanceOverride,
+    importDesignSystem,
+} from './_lib/design_system_import.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+const LANES = new Set(['native', 'dtcg', 'dembrandt']);
+const SOURCE_KINDS = new Set(['url', 'repo', 'dir']);
+const FORMATS = new Set(['json', 'summary']);
+
+const USAGE =
+    'usage: design_system_import <file> [--lane {native,dtcg,dembrandt}] ' +
+    '[--source-kind {url,repo,dir}] [--source-ref REF] [--captured-at ISO] ' +
+    '[--format {json,summary}]';
+
+interface Args {
+    file: string;
+    lane: Lane | null;
+    sourceKind: 'url' | 'repo' | 'dir' | null;
+    sourceRef: string | null;
+    capturedAt: string | null;
+    format: 'json' | 'summary';
+}
+
+function argError(message: string): never {
+    process.stderr.write(`${USAGE}\ndesign_system_import: error: ${message}\n`);
+    process.exit(2);
+}
+
+export function parse_args(argv: readonly string[]): Args {
+    const args: Args = {
+        file: '',
+        lane: null,
+        sourceKind: null,
+        sourceRef: null,
+        capturedAt: null,
+        format: 'json',
+    };
+    const positional: string[] = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        const eq = a.indexOf('=');
+        const flag = a.startsWith('--') && eq > 0 ? a.slice(0, eq) : a;
+        const inline = a.startsWith('--') && eq > 0 ? a.slice(eq + 1) : null;
+        const take = (): string => {
+            if (inline !== null) return inline;
+            const next = argv[++i];
+            if (next === undefined) argError(`argument ${flag}: expected one argument`);
+            return next;
+        };
+        switch (flag) {
+            case '-h':
+            case '--help':
+                process.stdout.write(`${USAGE}\n`);
+                process.exit(0);
+                break;
+            case '--lane': {
+                const v = take();
+                if (!LANES.has(v)) {
+                    argError(`argument --lane: invalid choice: '${v}' (choose from 'native', 'dtcg', 'dembrandt')`);
+                }
+                args.lane = v as Lane;
+                break;
+            }
+            case '--source-kind': {
+                const v = take();
+                if (!SOURCE_KINDS.has(v)) {
+                    argError(`argument --source-kind: invalid choice: '${v}' (choose from 'url', 'repo', 'dir')`);
+                }
+                args.sourceKind = v as 'url' | 'repo' | 'dir';
+                break;
+            }
+            case '--source-ref':
+                args.sourceRef = take();
+                break;
+            case '--captured-at':
+                args.capturedAt = take();
+                break;
+            case '--format': {
+                const v = take();
+                if (!FORMATS.has(v)) {
+                    argError(`argument --format: invalid choice: '${v}' (choose from 'json', 'summary')`);
+                }
+                args.format = v as 'json' | 'summary';
+                break;
+            }
+            default:
+                if (a.startsWith('-')) argError(`unrecognized arguments: ${a}`);
+                positional.push(a);
+        }
+    }
+    if (positional.length === 0) argError('the following arguments are required: file');
+    if (positional.length > 1) argError(`unrecognized arguments: ${positional.slice(1).join(' ')}`);
+    args.file = positional[0] as string;
+    // Half a provenance is worse than none: it reads as complete in the output
+    // while naming nothing traceable, and the contract's whole point is that a
+    // reader can go back to the source.
+    if ((args.sourceKind === null) !== (args.sourceRef === null)) {
+        argError('--source-kind and --source-ref must be given together');
+    }
+    // `--captured-at` alone was accepted and then ignored: the override object
+    // is only built when the kind/ref pair is present. Silently discarding a
+    // flag the user typed is worse than refusing it.
+    if (args.capturedAt !== null && args.sourceKind === null) {
+        argError('--captured-at requires --source-kind and --source-ref');
+    }
+    return args;
+}
+
+/** One line per fact, so a human can see what was mapped without reading JSON. */
+export function render_summary(outcome: ImportOutcome): string {
+    if (!outcome.ok) {
+        return `REJECTED (${outcome.lane ?? 'no lane'})\n  ${outcome.reason}`;
+    }
+    const ds = outcome.design_system;
+    const lines: string[] = [];
+    lines.push(`lane: ${outcome.lane}`);
+    lines.push(`source: ${ds.source.kind} ${ds.source.ref} @ ${ds.source.captured_at} (provenance from ${ds.source._meta?.provenance_origin ?? 'input'})`);
+    const counts: string[] = [];
+    const light = Object.keys(ds.colors?.light ?? {}).length;
+    const dark = Object.keys(ds.colors?.dark ?? {}).length;
+    if (light + dark > 0) counts.push(`colors: ${light} light / ${dark} dark`);
+    if (ds.typography?.families?.length) counts.push(`font families: ${ds.typography.families.length}`);
+    if (ds.typography?.scale?.length) counts.push(`type steps: ${ds.typography.scale.length}`);
+    if (ds.spacing?.scale?.length) counts.push(`spacing steps: ${ds.spacing.scale.length}`);
+    if (ds.radius) counts.push(`radius roles: ${Object.keys(ds.radius).length}`);
+    if (ds.shadow) counts.push(`shadow roles: ${Object.keys(ds.shadow).length}`);
+    if (ds.motion?.durations) counts.push(`motion durations: ${Object.keys(ds.motion.durations).length}`);
+    if (ds.motion?.easings) counts.push(`motion easings: ${Object.keys(ds.motion.easings).length}`);
+    if (ds.components?.length) counts.push(`components: ${ds.components.length}`);
+    lines.push(counts.length > 0 ? `mapped — ${counts.join(', ')}` : 'mapped — nothing (observation only)');
+    for (const note of outcome.notes) lines.push(`note: ${note}`);
+    lines.push('');
+    lines.push('This artifact is observed, not authoritative. Hand it to design-system-capture,');
+    lines.push('which confirms it per field; a value conflicting with a registered brand token is');
+    lines.push('flagged, never auto-applied.');
+    return lines.join('\n');
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const args = parse_args(argv);
+
+    let raw: string;
+    try {
+        raw = fs.readFileSync(args.file, 'utf-8');
+    } catch (exc) {
+        const msg = exc instanceof Error ? exc.message : String(exc);
+        process.stderr.write(`design_system_import: cannot read ${args.file}: ${msg}\n`);
+        return 1;
+    }
+
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (exc) {
+        const msg = exc instanceof Error ? exc.message : String(exc);
+        process.stderr.write(`design_system_import: ${args.file} is not valid JSON: ${msg}\n`);
+        return 1;
+    }
+
+    const provenance: ProvenanceOverride | undefined =
+        args.sourceKind !== null && args.sourceRef !== null
+            ? {
+                  kind: args.sourceKind,
+                  ref: args.sourceRef,
+                  ...(args.capturedAt !== null ? { captured_at: args.capturedAt } : {}),
+              }
+            : undefined;
+
+    const outcome = importDesignSystem(parsed, provenance, args.lane ?? undefined);
+
+    // The input's own provenance wins over a caller override — defensible, and
+    // previously invisible: a user who typed --source-ref was never told the
+    // flag had no effect on this file.
+    if (
+        outcome.ok &&
+        provenance !== undefined &&
+        outcome.design_system.source._meta?.provenance_origin === 'input'
+    ) {
+        outcome.notes.push(
+            `the file carries its own source block, so it wins over --source-ref "${provenance.ref}" — the supplied provenance was not used`,
+        );
+    }
+
+    if (!outcome.ok) {
+        process.stderr.write(`${render_summary(outcome)}\n`);
+        return 1;
+    }
+    if (args.format === 'summary') {
+        process.stdout.write(`${render_summary(outcome)}\n`);
+    } else {
+        process.stdout.write(`${JSON.stringify(outcome.design_system, null, 2)}\n`);
+        for (const note of outcome.notes) process.stderr.write(`note: ${note}\n`);
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    try {
+        process.exit(main());
+    } catch (exc) {
+        const msg = exc instanceof Error ? exc.message : String(exc);
+        process.stderr.write(`design_system_import: internal error: ${msg}\n`);
+        process.exit(3);
+    }
+}

package/src/scripts/dispatch_r2_reviewer.ts

@@ -642,7 +642,21 @@ function reviewerPrompt(args: {
  * Writing the hash of the prompt THIS dispatcher built makes the channel
  * attributable: the artefact now records which prompt produced it, so a review
  * run against a different prompt is distinguishable from one run against the
- * dispatcher's. `--verify` re-derives it from the same inputs and compares.
+ * dispatcher's.
+ *
+ * `--verify` / `--verify-current` do NOT re-derive it. {@link runVerify}
+ * re-derives `scope_hash`, `roadmap_hash` and `ac_hash` only — it re-computes
+ * the review's INPUTS from the current repo state, and the prompt is not one of
+ * them (it is not reconstructible from the repo; it is an artefact this
+ * dispatcher wrote). An earlier revision of this comment claimed otherwise for
+ * roughly a year, which is how the field came to be written, parsed, and
+ * compared to nothing.
+ *
+ * What compares it is `check_review_prompt_binding`, against the prompt package
+ * this dispatcher commits beside the artefact (`<slug>.review-input/prompt.md`,
+ * written below) — a different check with a different scope: corpus-wide rather
+ * than current-branch, because a committed prompt and its recorded hash are both
+ * immutable.
  *
  * It does not CLOSE the residual and is not sold as doing so: the same host that
  * authors a steered prompt could hash the steered text. The gain is an