@event4u/agent-config 10.3.0 → 11.0.0

package/src/scripts/check_branch_freshness.ts

@@ -31,6 +31,26 @@
  * It never fetches, merges, or rebases for you. Choosing how to catch up is a
  * git-history decision (`git-history-discipline`), and a gate that rewrites
  * history to make itself pass is a worse failure than the one it reports.
+ *
+ * WHICH BASE — asked of the forge, not assumed.
+ *
+ * The first version hardcoded `main`. That is right for most branches here and
+ * wrong for every branch whose PR targets something else: a stacked PR, a
+ * release line, a consumer repo on `master`. On those the gate produced a false
+ * GREEN — "current with origin/main" while the branch sat behind the base it
+ * would actually merge into — which is worse than no gate, because it answers a
+ * question nobody asked in the voice of the one they did.
+ *
+ * So the base is resolved, in order: an explicit `--base`, then the base of the
+ * OPEN PR for this branch as the forge reports it, then the repo's default
+ * branch from `origin/HEAD`, then `main`. Every message names the base AND
+ * where it came from, because "I checked main because that is the PR's base"
+ * and "I checked main because I could not ask" must never print the same.
+ *
+ * When the forge cannot be asked (no `gh`, not authenticated, no GitHub remote)
+ * the run says so out loud even under `--quiet`: it has verified the default
+ * base and has NOT ruled out an open PR against a different one. That is a
+ * partial answer, and partial answers are reported as partial.
  */
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
@@ -43,9 +63,11 @@ import { reportScanned } from "./_lib/scan_scope.js";
 
 // ledger-exempt: single remote-ref probe — the entire scope is ONE ls-remote answer (0 or 1 refs) resolved to one aggregate ancestor verdict, and every empty path already publishes its reason via reportScanned allowEmpty; there is no per-target collection to account.
 const DEFAULT_BASE = "main";
-const SELF_TEST_MIN_CASES = 3;
-const SELF_TEST_MIN_REJECT = 1;
+const SELF_TEST_MIN_CASES = 5;
+const SELF_TEST_MIN_REJECT = 2;
 const SCRIPT_REL = "src/scripts/check_branch_freshness.ts";
+/** One forge round trip on the push path — long enough for a cold `gh`, short enough not to stall a push. */
+const FORGE_TIMEOUT_MS = 10_000;
 
 function git(args: string[]): string | null {
   try {
@@ -55,6 +77,134 @@ function git(args: string[]): string | null {
   }
 }
 
+export type GhResult = { ok: true; stdout: string } | { ok: false; reason: string };
+export type GhRunner = (args: string[]) => GhResult;
+
+/**
+ * What the forge said about an open PR for this branch.
+ *
+ * Three-valued on purpose. `none` (the forge answered: no open PR) and
+ * `unavailable` (the forge could not be asked) lead to the same base and to
+ * DIFFERENT confidence, and collapsing them is exactly how a gate reports a
+ * green it did not earn.
+ */
+export type ForgeAnswer =
+  | { kind: "pr"; base: string; number: number }
+  | { kind: "none" }
+  | { kind: "unavailable"; reason: string };
+
+/** Where the base name came from — printed with every verdict. */
+export type BaseSource = "flag" | "pull-request" | "origin-head" | "fallback";
+
+export interface BaseResolution {
+  readonly base: string;
+  readonly source: BaseSource;
+  readonly pr?: number;
+  /** Present iff an open PR against a different base could not be ruled out. */
+  readonly unverified?: string;
+}
+
+function gh(args: string[]): GhResult {
+  try {
+    const out = execFileSync("gh", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: FORGE_TIMEOUT_MS,
+    });
+    return { ok: true, stdout: out.toString() };
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {
+      return { ok: false, reason: "the gh CLI is not installed" };
+    }
+    if (code === "ETIMEDOUT") {
+      return { ok: false, reason: `gh did not answer within ${FORGE_TIMEOUT_MS / 1000}s` };
+    }
+    return { ok: false, reason: "gh could not answer — not authenticated, or no GitHub remote" };
+  }
+}
+
+/**
+ * The base of the open PR whose head is `branch`.
+ *
+ * `pr list --head` rather than `pr view`: `pr view` will happily resolve a
+ * CLOSED PR for the same branch, and a merged PR's base is not the base the
+ * next push has to be current with.
+ */
+export function askForgeForBase(branch: string, run: GhRunner = gh): ForgeAnswer {
+  const res = run([
+    "pr", "list", "--head", branch, "--state", "open",
+    "--json", "number,baseRefName", "--limit", "1",
+  ]);
+  if (!res.ok) {
+    return { kind: "unavailable", reason: res.reason };
+  }
+  let rows: unknown;
+  try {
+    rows = JSON.parse(res.stdout);
+  } catch {
+    return { kind: "unavailable", reason: "gh returned output that is not JSON" };
+  }
+  if (!Array.isArray(rows) || rows.length === 0) {
+    return { kind: "none" };
+  }
+  const row = rows[0] as { baseRefName?: unknown; number?: unknown };
+  const base = typeof row.baseRefName === "string" ? row.baseRefName.trim() : "";
+  if (base === "") {
+    return { kind: "unavailable", reason: "gh answered without a baseRefName" };
+  }
+  return { kind: "pr", base, number: typeof row.number === "number" ? row.number : 0 };
+}
+
+/** The repo's own default branch, so a consumer on `master` is not told about `main`. */
+export function repoDefaultBase(): { base: string; source: "origin-head" | "fallback" } {
+  const ref = git(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+  if (ref !== null && ref.startsWith("origin/")) {
+    const name = ref.slice("origin/".length).trim();
+    if (name !== "") {
+      return { base: name, source: "origin-head" };
+    }
+  }
+  return { base: DEFAULT_BASE, source: "fallback" };
+}
+
+/** `--base` wins, then the open PR's base, then the repo default. */
+export function resolveBase(
+  argv: readonly string[],
+  branch: string,
+  forge: (b: string) => ForgeAnswer = (b) => askForgeForBase(b),
+): BaseResolution {
+  const flag = argv.indexOf("--base");
+  if (flag >= 0) {
+    const explicit = argv[flag + 1];
+    if (explicit !== undefined && explicit !== "") {
+      return { base: explicit, source: "flag" };
+    }
+  }
+  const answer = forge(branch);
+  if (answer.kind === "pr") {
+    return { base: answer.base, source: "pull-request", pr: answer.number };
+  }
+  const fallback = repoDefaultBase();
+  return answer.kind === "unavailable"
+    ? { base: fallback.base, source: fallback.source, unverified: answer.reason }
+    : { base: fallback.base, source: fallback.source };
+}
+
+/** Human-readable provenance — never omitted, so no verdict is ambiguous about what it checked. */
+export function describeBase(r: BaseResolution): string {
+  switch (r.source) {
+    case "flag":
+      return "base given on the command line";
+    case "pull-request":
+      return `base of open PR #${r.pr ?? 0}`;
+    case "origin-head":
+      return "repo default branch (origin/HEAD)";
+    case "fallback":
+      return `repo default (assumed ${DEFAULT_BASE} — origin/HEAD is not set)`;
+  }
+}
+
 /** The SHA the server reports for `<base>` right now — never a tracking ref. */
 export function remoteHead(base: string, remote = "origin"): string | null {
   const out = git(["ls-remote", "--heads", remote, base]);
@@ -121,6 +271,47 @@ function buildFixture(root: string, opts: { advanceRemote: boolean }): string {
   return work;
 }
 
+/**
+ * A repo where the branch's real base is NOT the default branch: `feat/x` is
+ * cut from `develop`, `develop` then advances on the remote, and `main` never
+ * moves.
+ *
+ * This is the fixture that demonstrates the defect the base resolution exists
+ * to remove. Checked against `main` the branch is perfectly current — a GREEN
+ * that is true and irrelevant. Checked against `develop`, the base it will
+ * actually merge into, it is behind. Both verdicts come from the same tree, so
+ * a regression that reinstates a hardcoded base flips exactly one of them.
+ */
+function buildTwoBaseFixture(root: string): string {
+  const origin = path.join(root, "origin.git");
+  const work = path.join(root, "work");
+  fs.mkdirSync(origin, { recursive: true });
+  const g = (args: string[], at: string): void => {
+    execFileSync("git", args, { cwd: at, stdio: "ignore" });
+  };
+  const write = (at: string, name: string, body: string): void => {
+    fs.writeFileSync(path.join(at, name), body);
+    g(["add", "-A"], at);
+    g(["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-m", name], at);
+  };
+  g(["init", "--bare", "-b", DEFAULT_BASE], origin);
+  g(["init", "-b", DEFAULT_BASE, work], root);
+  g(["remote", "add", "origin", origin], work);
+  write(work, "a.txt", "one");
+  g(["push", "-u", "origin", DEFAULT_BASE], work);
+  g(["checkout", "-b", "develop"], work);
+  g(["push", "-u", "origin", "develop"], work);
+  g(["checkout", "-b", "feat/x"], work);
+  write(work, "b.txt", "two");
+  // A second clone advances `develop` only — `main` stays exactly where it was.
+  const other = path.join(root, "other");
+  g(["clone", origin, other], root);
+  g(["checkout", "develop"], other);
+  write(other, "c.txt", "three");
+  g(["push"], other);
+  return work;
+}
+
 export function selfTest(repoRoot: string): number {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "cbf-selftest-"));
   const run = (advanceRemote: boolean, onBase: boolean): number => {
@@ -134,12 +325,29 @@ export function selfTest(repoRoot: string): number {
     delete process.env["GITHUB_ACTIONS"];
     return runGateCli(repoRoot, SCRIPT_REL, ["--quiet"], work);
   };
+  const runTwoBase = (base: string): number => {
+    const dir = fs.mkdtempSync(path.join(root, "twobase-"));
+    const work = buildTwoBaseFixture(dir);
+    delete process.env["CI"];
+    delete process.env["GITHUB_ACTIONS"];
+    return runGateCli(repoRoot, SCRIPT_REL, ["--quiet", "--base", base], work);
+  };
   const cases: SelfTestCase[] = [
     {
       name: "a branch whose tracking ref is stale while the remote has moved is REFUSED",
       expect: "reject",
       run: () => run(true, false),
     },
+    {
+      name: "a branch behind its REAL base (develop) is refused when that base is checked",
+      expect: "reject",
+      run: () => runTwoBase("develop"),
+    },
+    {
+      name: "the same branch passes against main — the false green a hardcoded base produces",
+      expect: "accept",
+      run: () => runTwoBase(DEFAULT_BASE),
+    },
     {
       name: "a branch containing the remote base passes",
       expect: "accept",
@@ -186,8 +394,6 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     return selfTest(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", ".."));
   }
   const quiet = argv.includes("--quiet");
-  const baseArg = argv.indexOf("--base");
-  const base = baseArg >= 0 ? (argv[baseArg + 1] ?? DEFAULT_BASE) : DEFAULT_BASE;
 
   // CI merges or refuses on the server; a second opinion here would be noise.
   if (process.env["CI"] === "true" || process.env["GITHUB_ACTIONS"] === "true") {
@@ -200,11 +406,27 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     scanReport(0, "detached HEAD — there is no branch whose freshness could be asked");
     return 0;
   }
+
+  // Resolved AFTER the branch is known: the PR's base is a fact about THIS branch.
+  const resolved = resolveBase(argv, branch);
+  const base = resolved.base;
+
   if (branch === base) {
     scanReport(0, `standing on ${base} itself — a branch cannot be behind itself`);
     return 0;
   }
 
+  // Loud even under --quiet: this run verified the default base and did NOT
+  // rule out an open PR against a different one. A partial answer is reported
+  // as partial, never folded into the plain green below.
+  if (resolved.unverified !== undefined) {
+    process.stdout.write(
+      `⚠️  check_branch_freshness: could not ask the forge for this branch's PR base ` +
+        `(${resolved.unverified}) — checking origin/${base}, the ${describeBase(resolved)}. ` +
+        "If an open PR targets a different base, THAT base is NOT verified here.\n",
+    );
+  }
+
   const sha = remoteHead(base);
   if (sha === null) {
     // Loud, not silent. An offline run has not verified the invariant, and a
@@ -221,19 +443,29 @@ export function main(argv: string[] = process.argv.slice(2)): number {
   scanReport(1);
   if (containsCommit(sha) === true) {
     if (!quiet) {
-      process.stdout.write(`✅  branch is current with origin/${base} (${sha.slice(0, 9)})` + "\n");
+      process.stdout.write(
+        `✅  branch is current with origin/${base} (${sha.slice(0, 9)}) — ${describeBase(resolved)}\n`,
+      );
     }
     return 0;
   }
 
-  console.error(`❌  branch is BEHIND origin/${base} — the remote is at ${sha.slice(0, 9)}.`);
+  console.error(
+    `❌  branch is BEHIND origin/${base} — the remote is at ${sha.slice(0, 9)}. ` +
+      `(${describeBase(resolved)})`,
+  );
   console.error("");
   console.error("    Pushing now opens a PR that may conflict, and worse: another branch");
   console.error("    may already have shipped what this one is implementing.");
   console.error("");
   console.error(`    git fetch origin && git merge origin/${base}`);
+  console.error("    ./agent-config roadmap:progress   # regenerate AFTER every merge, not only on conflict");
   console.error("    then re-run the gates before pushing.");
   console.error("");
+  console.error("    The dashboard line is not optional housekeeping: the roadmap dashboard is a");
+  console.error("    GENERATED file, so a merge that lands cleanly still leaves it describing");
+  console.error("    neither side's roadmap set. A clean auto-merge of a generated file is still wrong.");
+  console.error("");
   console.error(
     "    This gate asks the REMOTE, not your tracking ref — a fetch from earlier in",
   );

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/external_sources_denylist.json

@@ -95,7 +95,10 @@
     "agents/roadmaps/archive/road-to-subagent-value-realization.md",
     "agents/roadmap-assets/road-to-image-brand-typography.assets.md",
     "CREDITS.md",
-    "agents/roadmaps/archive/road-to-ecosystem-harvest-index.md"
+    "agents/roadmaps/archive/road-to-ecosystem-harvest-index.md",
+    "provenance/borrows.jsonl",
+    "docs/THIRD-PARTY-NOTICES.md",
+    "agents/evidence/reviews/*.review-input/diff.patch"
   ],
   "skip_reason": {
     "vendored_cluster": "design-intelligence/corpus-grounding/design-tokens/react-shadcn-ui/tailwind-engineer + cost/*.mjs ship vendored Apache/MIT code; their upstream attribution is license-required and must NOT be stripped (ADR-061). CREDITS.md is the repo-level attribution file FOR that same cluster — it names the upstreams because the licenses require it, which is the one case source-confidentiality explicitly exempts. It was missing here, so the gate flagged the very attribution the rule mandates.",
@@ -103,7 +106,9 @@
     "generated_bundles": "content.json* bundle the vendored-cluster skill bodies above.",
     "self": "the linter + its denylist + the source-confidentiality rule necessarily contain the deny tokens as data.",
     "validate_safe_paths": "telegraph-derived (MIT) ported code; upstream attribution is license-required.",
-    "archived_roadmaps_newly_tracked": "Archived roadmaps (and their assets) that predate the source-confidentiality sweep became tracked via the 2026-07 agents-dir gitignore hygiene change. They are frozen historical records; the claudekit mentions are ADR-061 license-attribution work and the remaining names are historical planning references. New roadmaps stay subject to the gate. road-to-ecosystem-harvest-index.md is the sharpest case: the flagged line is its own acceptance criterion, 'No harvest-family artifact names a real external source' — it quotes the names in order to assert their absence, so the gate fires on the sentence that records the cleanup. road-to-opt-retrieval-and-memory.md was REMOVED from this list on 2026-07-28 (road-to-native-code-intelligence Phase 6): its two clear-text mentions named a gitignored borrow-catalogue inbox file, which carries no historical value that a neutral descriptor loses — so the mentions were rewritten and the exception retired rather than kept. Retiring an exception is preferred over holding one whenever the named token is not license-required attribution and not load-bearing for the record."
+    "archived_roadmaps_newly_tracked": "Archived roadmaps (and their assets) that predate the source-confidentiality sweep became tracked via the 2026-07 agents-dir gitignore hygiene change. They are frozen historical records; the claudekit mentions are ADR-061 license-attribution work and the remaining names are historical planning references. New roadmaps stay subject to the gate. road-to-ecosystem-harvest-index.md is the sharpest case: the flagged line is its own acceptance criterion, 'No harvest-family artifact names a real external source' — it quotes the names in order to assert their absence, so the gate fires on the sentence that records the cleanup. road-to-opt-retrieval-and-memory.md was REMOVED from this list on 2026-07-28 (road-to-native-code-intelligence Phase 6): its two clear-text mentions named a gitignored borrow-catalogue inbox file, which carries no historical value that a neutral descriptor loses — so the mentions were rewritten and the exception retired rather than kept. Retiring an exception is preferred over holding one whenever the named token is not license-required attribution and not load-bearing for the record.",
+    "provenance_ledger": "provenance/borrows.jsonl and the docs/THIRD-PARTY-NOTICES.md it generates are the license-attribution surfaces for CODE borrows, and code-provenance REQUIRES the upstream name in them: the ledger's `source_url` is a mandatory field (provenance/README.md), and lint_provenance fails when the notices file drifts from it. That is the same license-required-attribution case source-confidentiality already exempts for the vendored cluster and CREDITS.md — the rule forbids derivation-attribution, not the notice a license obliges. The collision only surfaced on 2026-08-13 because the ledger had been empty until its first record; before that there was no name to flag. Scope is deliberately these two paths and not `provenance/*`: the harvest ledger next door governs KNOWLEDGE claims, where anonymisation is the rule and no license compels a name.",
+    "r2_review_diff_capture": "The R2 completion-review dispatcher writes a verbatim `diff.patch` of the branch under review into a tracked input package. It is a MECHANICAL CAPTURE, not authored text: any source name inside it was already written somewhere else in the same branch, where this gate does see it. A branch that touches the vendored cluster's ATTRIBUTION.md — carved out here precisely because its license requires the name — therefore reproduces that name in the capture and fails the gate for content the gate already allowed at its source. Scope is the capture ONLY: `findings.md` and `prompt.md` are authored prose and stay under the gate, so a reviewer who names a harvest source in their findings is still caught."
   },
   "_excluded_tokens": {
     "agent-os": "collides with our own coined 'Agent-OS primitive' term (universal-skills) — too FP-prone to auto-deny; scrub external 'agent-os' mentions by review.",