@event4u/agent-config 10.4.0 → 11.0.0

package/dist/ui/index.html

@@ -27,7 +27,7 @@
                 document.documentElement.setAttribute('data-theme', theme);
             })();
         </script>
-      <script type="module" crossorigin src="/assets/index-5fXOHoVh.js"></script>
+      <script type="module" crossorigin src="/assets/index-B0aMJnuz.js"></script>
       <link rel="stylesheet" crossorigin href="/assets/index-jSfMW8_t.css">
     </head>
     <body>

package/docs/contracts/settings-classes.md

@@ -39,9 +39,10 @@ surface without a consumer.
 **It governs writes, not reads.** Every class is readable by everything. A C
 class does not hide a value; it refuses to let a non-human change it.
 
-**It governs writes, not asks.** Four settings ship an `ask` value in their own
-enum (`tokens.rich_skills`, `subagents.adversarial_council`, `worktrees.mode`,
-`decision_engine.on_block`).
+**It governs writes, not asks.** Three settings ship an `ask` value in their own
+enum (`tokens.rich_skills`, `subagents.adversarial_council`,
+`decision_engine.on_block`). It was four until ADR-229 deleted
+`worktrees.mode`.
 Those are C-class here, and that is not a contradiction: the class says who may
 *persist* a new value; the `ask` value says what happens *at runtime* when the
 setting is already set to `ask`. A C-class key set to `ask` still produces a
@@ -189,12 +190,15 @@ dispatch runs, not WHETHER the layer exists, so they keep their own C rows.
 |---|---|
 | A — preference | 26 |
 | B — consent | 3 |
-| C — guarded | 106 |
-| **Total** | **135** |
+| C — guarded | 105 |
+| **Total** | **134** |
 
 The total was 140 until 2026-08-12, when five of the six keys no code path read were
 deleted, minus the one held open (§ The six unread keys, below): one A
-(`telegraph.speak_scope`) and four C.
+(`telegraph.speak_scope`) and four C. It dropped to 134 on 2026-08-13 when
+ADR-229 deleted `worktrees.mode` — a fifth C, and the first deletion in this
+series of a key that WAS read: the doctrine there is that the decision was never
+the agent's to make, not that nothing consulted it.
 
 The total is every leaf in the template, where *leaf* means anything that is not
 a **non-empty** map. An empty map (like the former `subagents.host_capabilities: {}`) is a real
@@ -244,9 +248,9 @@ the template, which is the drift this contract exists to prevent.
 |---|---|
 | derivable | 83 |
 | un-inferrable | 9 |
-| consent | 38 |
+| consent | 37 |
 | policy | 5 |
-| **Total** | **135** |
+| **Total** | **134** |
 
 First measured 2026-08-12 at 140 leaves (derivable 88 · consent 38 ·
 un-inferrable 9 · policy 5), from the table below rather than predicted — the
@@ -421,7 +425,6 @@ Rows follow template order, so a diff against the template reads straight down.
 | `subagents.model_ceiling` | C | `""` | session-wide subagent model cap (exported as `CLAUDE_CODE_SUBAGENT_MODEL` by suite-owned CLI spawn wrappers), which is spend and quality | consent |
 | `subagents.max_parallel` | C | `3` | parallelism cap, and therefore a spend rate | consent |
 | `subagents.adversarial_council` | C | `"off"` | governs a paid verification step | consent |
-| `worktrees.mode` | C | `ask` | standing permission for autonomous worktree creation | consent |
 | `ai_team.model` | C | `auto` | names an external model | un-inferrable |
 | `ai_team.allow_delegate` | C | `false` | grants an external tool write access to the repository | consent |
 | `ai_team.max_calls_per_day` | C | `50` | quota cap on a shared budget | consent |

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "10.4.0",
+    "version": "11.0.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,

package/src/config/agent-settings.template.yml

@@ -815,24 +815,21 @@ subagents:
 
 # --- Git worktrees ---
 #
-# Controls how the `using-git-worktrees` skill and `subagent-orchestration`
-# mode 6 (`do-in-worktrees`) behave. Mechanical layer on top of the
-# existing `scope-control` permission gate — narrows, never widens.
-worktrees:
-  # off | on | ask  (default: ask)
-  #
-  # ask = status quo. Skill asks before creating any worktree; mode 6 is
-  #       selectable when the chain shape warrants it. Matches the
-  #       behaviour required by `scope-control` and `autonomous-execution`.
-  # off = no autonomous worktree creation. Skill refuses; mode 6 falls
-  #       back to mode 3 (do-in-steps). Explicit user request in the
-  #       chat ("do this in a worktree", "use mode 6") overrides for
-  #       that single task — the setting suppresses *unprompted* usage,
-  #       not the tool itself.
-  # on  = standing permission. Skill skips the per-creation permission
-  #       ask; mode 6 may be picked without prompting. Iron-Law gates
-  #       (ignore-check, clean baseline) still apply.
-  mode: ask
+# There is no setting. Worktree creation is INSTRUCTION-ONLY (ADR-229):
+# `using-git-worktrees` and `subagent-orchestration` mode 6 (`do-in-worktrees`)
+# create a worktree ONLY when the user asks for one in the chat ("do this in a
+# worktree", "use mode 6"). Unprompted, mode 6 is not selectable and the chain
+# falls back to mode 3 (`do-in-steps`).
+#
+# `worktrees.mode` was DELETED. It offered `ask`/`on`/`off` over a decision that
+# was never the agent's to make: `ask` spent a round trip on every spawn, `on`
+# let the agent start parallel work on its own, and `off` was the behaviour
+# everyone actually wanted — so the setting's only real value was hardcoded and
+# the other two values removed. A leftover key from an older install is ignored
+# with one deprecation line (see `REMOVED_KEYS` in `_lib/agent_settings.ts`).
+#
+# The Iron-Law gates on creation (ignore-safety check, clean baseline) are
+# unchanged and still run on every explicitly-requested worktree.
 
 # --- AI Council (external second-opinion network) ---
 #

package/src/config/gate-coverage.yml

@@ -335,9 +335,19 @@ gates:
       Why 340 and not 360, the measured value: gate-authoring.md § registration
       requires a floor BELOW the live count, because a floor pinned at today's
       number reds on the very change that legitimately retires one unit. 340
-      leaves ~20 units (~5.5%) of headroom while still catching the collapse this
-      floor exists for — a re-broken extractor would drop the count by 164, not
-      by 20.
+      leaves ~20 units (~5.5%) of headroom.
+      What this floor can and cannot catch, corrected after the R2 review caught
+      the first version arguing from a break that cannot fire it. The extraction
+      bug INFLATED the count — phantom gate names entering the CI set — so a
+      re-break raises the population to roughly 527 and a min_scanned floor never
+      triggers on a rise. The floor guards the opposite direction: an extractor
+      that stops finding taskfiles or workflows at all, a parse error zeroing one
+      side, a scan root that moves. Those are collapses of 100+ units and 340
+      catches every one of them. The realistic PARTIAL break — one taskfile
+      failing to parse, say ~14 units — passes 340 and would have failed 380,
+      which is the honest cost of the headroom and is accepted here rather than
+      hidden: a floor tight enough to catch that is also tight enough to red on
+      the next legitimate retirement.
 
   - id: check_site_links
     argv: []

package/src/config/gate-violation-baselines.json

@@ -4,7 +4,7 @@
     "ci-parity:local-only": {
       "count": 166,
       "landed": "2026-08-13",
-      "note": "Gates that `task ci` runs and no workflow does — the direction this manifest's own header calls the one that let real defects merge (16 stale index rows reached the trunk behind a local-only check-index). Revealed, not created, by repairing the checker's extraction: check_ci_local_parity built its CI-side set by regexing RAW workflow text for `task <name>` and expanding each closure, comments included. Several workflow comments contain the literal string `task ci` while stating that no workflow invokes it, so `ci` was read as an invocation and its full 247-gate closure entered the 'runs in CI' set. The count was therefore 0 BY CONSTRUCTION, and the prose documenting the gap was what suppressed it. Measured at the repair: CI-side 273 → 106, undeclared_local_only 0 → 167 of 247 local gates (68%). Baselined rather than hard-failed because 167 findings nobody can clear in the change that reveals them is the gate-that-lands-as-N-instant-blockers failure this repository has refused before; shrink-only keeps the property that matters, namely that a NEW gate registered in `task ci` with no workflow reds immediately. Lowering happens by wiring gates into workflows or declaring them under `local_only:` with a reason. Note the punchline, because it bounds the risk of this entry: check_ci_local_parity ITSELF runs in no workflow, so it is its own finding and this ratchet has no remote reach either — clearing the backlog is what gives it teeth. DRAINED BY ONE, 2026-08-13: check_ci_local_parity itself was wired into consistency.yml, so it left the set it exists to report. That is the whole shape of a legitimate drain here — the gate stops being local-only because a workflow now runs it, not because the declaration list grew. The floor in gate-coverage.yml moved in the same change and for the same reason: wiring two gates raised the parsed population 357 -> 359.",
+      "note": "Gates that `task ci` runs and no workflow does — the direction this manifest's own header calls the one that let real defects merge (16 stale index rows reached the trunk behind a local-only check-index). Revealed, not created, by repairing the checker's extraction: check_ci_local_parity built its CI-side set by regexing RAW workflow text for `task <name>` and expanding each closure, comments included. Several workflow comments contain the literal string `task ci` while stating that no workflow invokes it, so `ci` was read as an invocation and its full 247-gate closure entered the 'runs in CI' set. The count was therefore 0 BY CONSTRUCTION, and the prose documenting the gap was what suppressed it. Measured at the repair: CI-side 273 → 106, undeclared_local_only 0 → 167 of 247 local gates (68%). Baselined rather than hard-failed because 167 findings nobody can clear in the change that reveals them is the gate-that-lands-as-N-instant-blockers failure this repository has refused before; shrink-only keeps the property that matters, namely that a NEW gate registered in `task ci` with no workflow reds immediately. Lowering happens by wiring gates into workflows or declaring them under `local_only:` with a reason. Note the punchline, because it bounds the risk of this entry: check_ci_local_parity ITSELF runs in no workflow, so it is its own finding and this ratchet has no remote reach either — clearing the backlog is what gives it teeth. DRAINED BY ONE, 2026-08-13: check_ci_local_parity itself was wired into consistency.yml, so it left the set it exists to report. That is the whole shape of a legitimate drain here — the gate stops being local-only because a workflow now runs it, not because the declaration list grew. The floor in gate-coverage.yml moved in the same change and for the same reason: wiring two gates raised the parsed population 357 -> 360 (109 CI + 251 local). The intermediate 359 was the reading after the CI-side wiring alone and before check_gate_coverage joined the local `ci` chain; it was committed here by mistake and is corrected rather than left as a second number for the same measurement.",
       "falsifier": "./scripts-run src/scripts/check_ci_local_parity"
     },
     "check_no_new_legacy_path:hardcoded-scan-roots": {

package/src/config/pack-size-budget.json

@@ -20,9 +20,10 @@
         "rationale": "Measured 2026-07-31: the largest non-excepted skill is corpus-grounding at 2.33%, so a 5% cap is green with better than 2x headroom and red for any skill that doubles. It is a falsifiable gate, not a ritual one.",
         "exceptions": {
             "design-intelligence": {
-                "max_pct": 23.0,
+                "max_pct": 23.5,
                 "measured_pct": 22.63,
-                "reason": "771 KB of BM25 corpus (27 CSVs + 16 design-language prose specs + manifest.json) consumed at runtime by corpus-grounding's retriever, and referenced by 6 further skills. Moving it behind a lazy fetch would add a network dependency to a skill that works offline today — the same trade-off ADR-061 §8 already REJECTED for a 745 KB font index. The exception is visible debt, not an endorsement: raising max_pct requires a reason in the same commit."
+                "reason": "771 KB of BM25 corpus (27 CSVs + 16 design-language prose specs + manifest.json) consumed at runtime by corpus-grounding's retriever, and referenced by 6 further skills. Moving it behind a lazy fetch would add a network dependency to a skill that works offline today — the same trade-off ADR-061 §8 already REJECTED for a 745 KB font index. The exception is visible debt, not an endorsement: raising max_pct requires a reason in the same commit.",
+                "baseline_note_2026_08_13": "23.0 → 23.5 on 2026-08-13, and the reason belongs in this file per the sentence above. WHAT WAS ADOPTED: data/motion.csv, 10.5 KB, 16 rows. WHY IT IS NOT DISCRETIONARY: the roadmap's three design dials were all in its original scope, and two of the three (variance, density) were already portable — variance's keywords resolve against the local styles.csv (2/3/3 hits) and density is three pure range maps. The motion dial is not: upstream filters its corpus rows by `Intensity Tier == <dial tier>`, and that column exists only in motion.csv, so shipping the dial without the file means shipping a flag that silently does nothing. Two of three dials plus an inert third is a worse surface than three working ones. WHAT WAS DECLINED IN THE SAME PASS, so this is not a ratchet slipping: google-fonts.csv (743 KB — ADR-061 §8 rejects it by name and by size; the 2026-06-16 amendment authorises a slim top-N slice from a different mirror, not this file), typography.csv (our curated font-pairings-reference.csv is the ADR's working substitution), six desktop-UI stacks outside frontend-design's scope, and eleven content-drifted files nobody has reviewed. The base pin in ATTRIBUTION.md is deliberately NOT bumped for the same reason. HONEST LIMIT ON THE NUMBER: 22.63 is the committed measurement, not a fresh one — check_pack_size cannot be re-measured from a built worktree (it reads 9.096 against the 7.8 packed cap before any change, the trap the packed_size_mb note above documents), so the post-adoption share is arithmetic (~22.87 %) and the new cap carries ~0.6 pp over it rather than clearing by a hair. DECIDED BY: AI council, 2026-08-13, on a maintainer delegation — and honestly, by ONE member over two rounds, not by convergence: the second seat returned exit_1 (the codex CLI refuses a git worktree as an untrusted directory). Recorded as a single-member review in agents/evidence/analysis/design-system-blockers-council.md."
             }
         }
     }

package/src/scripts/_lib/agent_settings.ts

@@ -922,6 +922,13 @@ export function load_agent_settings(
  * whether the repair is to build its missing reader or to delete a promise a
  * Hard Floor can never honour. See `settings-classes.md` § The six unread keys.
  *
+ * `worktrees.mode` (2026-08-13, ADR-229) is a third doctrine again: not
+ * always-on, not unread. It WAS read, and the reader honoured all three values —
+ * the deletion says the decision was never the agent's to make. `ask` bought a
+ * round trip per spawn, `on` let the agent start parallel work unprompted, and
+ * `off` described the wanted behaviour, so `off` became the hardcoded rule and
+ * the switch went. What decides instead is the user's own sentence in the chat.
+ *
  * Every reason string must name what decides INSTEAD, never just "removed".
  * Exported so `lint_settings_classes` can check the deletion side of the
  * surface: a reason that names no replacement, or an entry whose key is live in
@@ -942,6 +949,7 @@ export const REMOVED_KEYS: ReadonlyMap<string, string> = new Map([
     ['chat_history.on_overflow', 'the overflow mode comes from the rotate command --mode argv'],
     ['quality.wait_for_remote_ci', 'whether to poll follows from the push plus a detectable remote pipeline'],
     ['legal_review_prep.consented_at', 'the provenance sidecar settings:set writes and consentVerdict reads'],
+    ['worktrees.mode', 'the user asking for a worktree in the chat; creation is instruction-only and hardcoded'],
 ]);
 
 /** Keys already warned about in THIS process — the "once per run" dedupe. */

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/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.",