@event4u/agent-config 10.4.0 → 12.0.0

package/src/scripts/check_branch_freshness.ts

@@ -31,6 +31,33 @@
  * 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 AS THE SERVER REPORTS IT (`ls-remote --symref`), then the local
+ * `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.
+ *
+ * The server symref matters for the same reason `remoteHead` exists: the local
+ * `refs/remotes/origin/HEAD` is written at clone time and never refreshed, so
+ * taking the base NAME from it would reintroduce the stale-local-state failure
+ * this module argues against everywhere else. It is kept only as the labelled
+ * fallback for when the server cannot be reached.
+ *
+ * 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,18 +70,254 @@ 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 network round trip on the push path — long enough for a cold `gh`, short
+ * enough that the worst case stays under budget.
+ *
+ * It bounds `git` as well as `gh`, and that is the point rather than tidiness:
+ * with a timeout on `gh` only, the two `ls-remote` calls could hang unbounded
+ * against an unresponsive SSH remote, so the stated worst case was not one. The
+ * slowest path makes three calls (forge, symref, base head), so the arithmetic
+ * that keeps this under the 25s `pre_push_budget_seconds` ceiling is 3 x 8s.
+ */
+const NETWORK_TIMEOUT_MS = 8_000;
 
 function git(args: string[]): string | null {
   try {
-    return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    return execFileSync("git", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: NETWORK_TIMEOUT_MS,
+    }).trim();
   } catch {
     return 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-symref"
+  | "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: NETWORK_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 ${NETWORK_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" };
+  }
+  // The number is cosmetic — it names the PR in the verdict line — while the
+  // base is the answer the gate exists to get. An unusable number therefore
+  // does NOT discard the base: doing that made the gate check the repo default
+  // instead and warn "could not ask the forge" when it had asked and been
+  // answered, trading a correct verdict for a tidier message. `describeBase`
+  // omits the number rather than rendering the impossible `#0`.
+  const usable =
+    typeof row.number === "number" && Number.isInteger(row.number) && row.number > 0;
+  return usable ? { kind: "pr", base, number: row.number as number } : { kind: "pr", base };
+}
+
+/**
+ * The default branch as the LOCAL clone believes it — no network.
+ *
+ * `refs/remotes/origin/HEAD` is written at clone time and never refreshed
+ * without `git remote set-head`, so this is exactly the class of stale local
+ * state this module argues against everywhere else. It has exactly one caller,
+ * `serverDefaultBase`, and is reached only when the server could not be asked —
+ * where `describeBase` labels it as possibly stale. It decides no verdict on
+ * its own; a short-circuit that let it do so is the regression documented in
+ * `resolveBase`.
+ */
+export function localDefaultBase(): { 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" };
+}
+
+/**
+ * The default branch as the SERVER reports it right now.
+ *
+ * Same discipline as `remoteHead`: a gate whose thesis is "ask the remote"
+ * must not take the branch NAME from a tracking ref either. Costs one
+ * `ls-remote`, the round trip this gate already pays, and degrades to the
+ * local ref (labelled as such) when the server cannot be reached.
+ */
+export function serverDefaultBase(): {
+  base: string;
+  source: "origin-symref" | "origin-head" | "fallback";
+} {
+  const out = git(["ls-remote", "--symref", "origin", "HEAD"]);
+  if (out !== null) {
+    for (const line of out.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("ref:")) {
+        const name = trimmed.slice("ref:".length).trim().split(/\s+/)[0] ?? "";
+        if (name.startsWith("refs/heads/")) {
+          const short = name.slice("refs/heads/".length).trim();
+          if (short !== "") {
+            return { base: short, source: "origin-symref" };
+          }
+        }
+      }
+    }
+  }
+  return localDefaultBase();
+}
+
+/**
+ * The base requested on the command line, or null when none was.
+ *
+ * Both spellings are accepted. `--base=develop` used to be dropped silently by
+ * an `indexOf("--base")` lookup, and a dropped request is worse than a rejected
+ * one here: the gate then auto-resolves some OTHER base and reports a green
+ * about a base the caller never asked about.
+ */
+export function explicitBase(argv: readonly string[]): string | null {
+  const joined = argv.find((a) => a.startsWith("--base="));
+  if (joined !== undefined) {
+    const value = joined.slice("--base=".length);
+    return value === "" ? null : value;
+  }
+  const flag = argv.indexOf("--base");
+  if (flag < 0) {
+    return null;
+  }
+  const explicit = argv[flag + 1];
+  // A bare trailing `--base`, or one followed by another flag, is a typo rather
+  // than a base name. Accepting it produced `remoteHead("--quiet")`, which fails
+  // and lands on the exit-0 NOT-VERIFIED path — a typo reading as a pass.
+  if (explicit === undefined || explicit === "" || explicit.startsWith("-")) {
+    return null;
+  }
+  return explicit;
+}
+
+/** `--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 explicit = explicitBase(argv);
+  if (explicit !== null) {
+    return { base: explicit, source: "flag" };
+  }
+  // There is deliberately no cheap short-circuit for "the branch looks like the
+  // default". It was tried and reverted: it decided a VERDICT from
+  // `localDefaultBase`, the stale clone-time ref this module argues against, so
+  // a branch whose name collided with a stale or fallback local default was
+  // skipped without any check at all. The premise it rested on — that
+  // `gh pr list --head main` can never usefully answer — is false: a PR from the
+  // default branch into a release line or a parent PR is exactly that answer,
+  // and it is the case this gate exists for. Standing on the real base is
+  // short-circuited one layer up, in `main`, AFTER the base is known.
+  const answer = forge(branch);
+  if (answer.kind === "pr") {
+    return answer.number === undefined
+      ? { base: answer.base, source: "pull-request" }
+      : { base: answer.base, source: "pull-request", pr: answer.number };
+  }
+  const fallback = serverDefaultBase();
+  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 r.pr === undefined
+        ? "base of the open PR for this branch"
+        : `base of open PR #${r.pr}`;
+    case "origin-symref":
+      return "repo default branch, as the server reports it";
+    case "origin-head":
+      return "repo default branch from the LOCAL origin/HEAD ref, which may be stale";
+    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]);
@@ -93,7 +356,15 @@ export function containsCommit(sha: string): boolean | null {
  * gate reading the tracking ref would pass it — which is exactly the false green
  * this gate exists to remove.
  */
-function buildFixture(root: string, opts: { advanceRemote: boolean }): string {
+interface Scaffold {
+  origin: string;
+  work: string;
+  g: (args: string[], at: string) => void;
+  write: (at: string, name: string, body: string) => void;
+}
+
+/** The bare origin + working clone every fixture below starts from. */
+function scaffold(root: string): Scaffold {
   const origin = path.join(root, "origin.git");
   const work = path.join(root, "work");
   fs.mkdirSync(origin, { recursive: true });
@@ -110,6 +381,11 @@ function buildFixture(root: string, opts: { advanceRemote: boolean }): string {
   g(["remote", "add", "origin", origin], work);
   write(work, "a.txt", "one");
   g(["push", "-u", "origin", DEFAULT_BASE], work);
+  return { origin, work, g, write };
+}
+
+function buildFixture(root: string, opts: { advanceRemote: boolean }): string {
+  const { origin, work, g, write } = scaffold(root);
   g(["checkout", "-b", "feat/x"], work);
   write(work, "b.txt", "two");
   if (opts.advanceRemote) {
@@ -121,6 +397,58 @@ function buildFixture(root: string, opts: { advanceRemote: boolean }): string {
   return work;
 }
 
+/**
+ * A repo where the branch's real base is NOT `main`: `feat/x` is cut from
+ * `develop`, `develop` then advances on the remote, and `main` never moves.
+ * The SERVER's `HEAD` is pointed at `serverDefault`.
+ *
+ * The base is left for the gate to resolve — no `--base`. That is the whole
+ * point of the fixture, and the first version got it wrong: it passed
+ * `--base` on both cases, which exercises the flag branch that existed before
+ * this change. Deleting the entire forge/symref resolution would have left both
+ * cases green, so the pair proved nothing about the new behaviour and the raised
+ * self-test floors rested on coverage that did not exist. (R2 finding 2.)
+ *
+ * With `serverDefault = "develop"` the gate must refuse: that is the base this
+ * branch is actually behind. With `serverDefault = "main"` the same tree passes.
+ * A regression that reinstates a hardcoded `main` flips the first case, because
+ * nothing but the resolution decides which base is asked about.
+ */
+function buildTwoBaseFixture(root: string, serverDefault: string): string {
+  const { origin, work, g, write } = scaffold(root);
+  g(["checkout", "-b", "develop"], work);
+  g(["push", "-u", "origin", "develop"], work);
+  g(["checkout", "-b", "feat/x"], work);
+  write(work, "b.txt", "two");
+  // The bare repo's own HEAD is what `ls-remote --symref origin HEAD` reports,
+  // so this is the server-side default branch, not a local tracking ref.
+  g(["symbolic-ref", "HEAD", `refs/heads/${serverDefault}`], origin);
+  // 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;
+}
+
+/**
+ * Strip everything that could point the child's `gh` at a real forge.
+ *
+ * `runGateCli` spawns with the full inherited environment, and since the
+ * two-base cases dropped `--base` the resolution itself is what they assert on.
+ * An ambient `GH_REPO` can make `gh pr list --head feat/x` answer about a real
+ * PR in someone else's repository and silently move the base under test — the
+ * same ambient-credential hazard the `forge` seam closed for the unit tests,
+ * which would otherwise have stayed live in the only coverage of the new
+ * symref resolution. `CI` would no-op every case green.
+ */
+function isolateChildEnv(): void {
+  for (const key of ["CI", "GITHUB_ACTIONS", "GH_REPO", "GH_TOKEN", "GITHUB_TOKEN", "GH_HOST", "GH_CONFIG_DIR"]) {
+    delete process.env[key];
+  }
+}
+
 export function selfTest(repoRoot: string): number {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "cbf-selftest-"));
   const run = (advanceRemote: boolean, onBase: boolean): number => {
@@ -129,9 +457,14 @@ export function selfTest(repoRoot: string): number {
     if (onBase) {
       execFileSync("git", ["checkout", DEFAULT_BASE], { cwd: work, stdio: "ignore" });
     }
-    // The child must not inherit a CI flag, or every case would no-op green.
-    delete process.env["CI"];
-    delete process.env["GITHUB_ACTIONS"];
+    isolateChildEnv();
+    return runGateCli(repoRoot, SCRIPT_REL, ["--quiet"], work);
+  };
+  const runTwoBase = (serverDefault: string): number => {
+    const dir = fs.mkdtempSync(path.join(root, "twobase-"));
+    const work = buildTwoBaseFixture(dir, serverDefault);
+    isolateChildEnv();
+    // No `--base`: the gate resolves it, which is the behaviour under test.
     return runGateCli(repoRoot, SCRIPT_REL, ["--quiet"], work);
   };
   const cases: SelfTestCase[] = [
@@ -140,6 +473,16 @@ export function selfTest(repoRoot: string): number {
       expect: "reject",
       run: () => run(true, false),
     },
+    {
+      name: "the RESOLVED base decides: server default develop, branch behind it, REFUSED",
+      expect: "reject",
+      run: () => runTwoBase("develop"),
+    },
+    {
+      name: "same tree, server default main — passes, so the resolution is what moved the verdict",
+      expect: "accept",
+      run: () => runTwoBase(DEFAULT_BASE),
+    },
     {
       name: "a branch containing the remote base passes",
       expect: "accept",
@@ -181,13 +524,23 @@ function scanReport(scanned: number, allowEmpty?: string): void {
   });
 }
 
-export function main(argv: string[] = process.argv.slice(2)): number {
+/**
+ * @param forge Seam for the forge lookup. Production passes nothing and gets the
+ * real `gh`. Tests MUST pass a stub: without this parameter the only way to
+ * reach the forge-unavailable branch was to not have `gh` installed, so the test
+ * for it could only assert conditionally — i.e. it passed whether or not the
+ * warning was emitted. It also stopped every fixture test from spawning `gh`
+ * against ambient credentials, where a `GH_REPO` override could return a real
+ * PR base for a same-named branch and silently change the base under test.
+ */
+export function main(
+  argv: string[] = process.argv.slice(2),
+  forge?: (b: string) => ForgeAnswer,
+): number {
   if (argv.includes("--self-test")) {
     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 +553,29 @@ 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.
+  // `resolveBase`'s third parameter has a default, so passing `undefined`
+  // positionally already selects the real `gh` — no branch needed here.
+  const resolved = resolveBase(argv, branch, forge);
+  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 +592,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.",

package/src/scripts/gen_discovery_baseline.ts

@@ -247,19 +247,19 @@ export function main(): number {
     out.push('');
 
     out.push('## Sample commands (first 10)\n');
-    out.push('| File | name | tier | cluster |');
+    out.push('| File | name | visibility | cluster |');
     out.push('|---|---|---|---|');
     for (const c of commands.slice(0, 10)) {
         const fm = _frontmatter(c);
         const rel = _relativeTo(c, SRC);
-        out.push(`| \`${rel}\` | ${fm.name ?? ''} | ${fm.tier ?? ''} | ${fm.cluster ?? ''} |`);
+        out.push(`| \`${rel}\` | ${fm.name ?? ''} | ${fm.visibility ?? ''} | ${fm.cluster ?? ''} |`);
     }
     out.push('');
 
     out.push('## Notes\n');
     out.push('- Every skill carries `domain:` today — Phase 4 mapping uses it as primary signal.');
     out.push('- Rules use `type` (always | auto) + `tier` (safety-floor | kernel | …); no `domain:` today.');
-    out.push('- Commands use `tier` + `cluster`; no `domain:` today.');
+    out.push('- Commands use `visibility` + `cluster`; no `domain:` today.');
     out.push('- Templates have no consistent frontmatter; Phase 4 quarantines them in `unassigned-artefacts.yml`.');
     out.push('');
 

package/src/scripts/hook_manifest.yaml

@@ -590,6 +590,26 @@ concerns:
 # blocker: in-process Agent-tool subagents inherit the host process env and
 # cannot be marked per-spawn; the axis binds where the suite launches a CLI
 # session itself.
+#
+# Superseded in part, 2026-08-14 (road-to-subagent-lifecycle-integrity Phase 4
+# Step 2). The env half above still stands — nothing marks an in-process spawn
+# per-process. What has changed is that env is no longer the only candidate
+# channel: `subagent_start` / `subagent_stop` are bound on this host
+# (2.1.229, Phase 0 Step 1) and their payload carries `agent_id`, which
+# `subagent-ledger` correlates on today. So a payload-bound role axis —
+# `agent_id` present ⇒ role `worker` — is a live proposal (Phase 4 Step 1),
+# not a closed question.
+# It is NOT implemented, and the reason is a missing measurement rather than a
+# missing decision: whether `agent_id` reaches a `PreToolUse` / `PostToolUse`
+# payload inside a subagent is unverified on this host. That is Phase 0 Step 4,
+# blocked on `raw-capture-needs-host-env` (the capture itself is already
+# shipped — `dispatch_hook._maybe_capture_payload`). A neighbouring assertion
+# from the same spike already came back negative: `agent_type` does NOT arrive
+# on `SubagentStop` (18 of 25 stop records null), so the documented-field
+# presence is not assumed for `agent_id` either.
+# Until that spike lands the env path is the only one wired, and the
+# pre_tool_use exemption above is unaffected either way — a payload-resolved
+# `worker` still cannot drop a pre_tool_use concern.
 roles:
   worker:
     # Orchestrator-only concerns (Phase 2.3): a worker never talks to the

package/src/scripts/hooks/subagent_ledger_hook.ts

@@ -73,8 +73,9 @@
  * a `subagent_reaped` line is written for it. That line is not bookkeeping —
  * it is the closest thing this instrument has to a direct observation of a
  * never-returning dispatch, which is why the leak is reported rather than
- * quietly swept. `session_id` rides on the record so a future sweep can scope
- * by session; nothing reads it yet and it is not claimed to.
+ * quietly swept. `session_id` rides on the open record AND on both dispatch
+ * lines so a rate can be scoped by session; nothing reads it yet and it is not
+ * claimed to.
  *
  * ── Depth and concurrency (Step 3) ────────────────────────────────────────
  *
@@ -598,6 +599,13 @@ function handleStart(root: string, payload: JsonObject, nowIso: string, sessionI
         event: 'subagent_start',
         ts: nowIso,
         ref,
+        // Phase 1 Step 4 correction (b): without this the dispatch denominator
+        // is not per-session. Three sessions share one ledger file, so a rate
+        // computed over the file aggregates strangers — the measured window
+        // held 7 starts against 25 stops, one of them an agent type this
+        // session never dispatched. The open record already carried it; the
+        // appended line did not, and the line is what a rate is computed from.
+        session_id: sessionId,
         agent_type: rec.agent_type,
         parent_ref: parentRef,
         depth,
@@ -606,7 +614,7 @@ function handleStart(root: string, payload: JsonObject, nowIso: string, sessionI
     });
 }
 
-function handleStop(root: string, payload: JsonObject, nowIso: string): void {
+function handleStop(root: string, payload: JsonObject, nowIso: string, sessionId: string | null): void {
     const agentId = str(payload, 'agent_id', 'agentId');
     if (agentId === null) {
         appendUnidentified(root, 'subagent_stop', nowIso, payload);
@@ -631,6 +639,11 @@ function handleStop(root: string, payload: JsonObject, nowIso: string): void {
         event: 'subagent_stop',
         ts: nowIso,
         ref,
+        // The session this stop was OBSERVED in, read from the same envelope
+        // position as the start's — never back-filled from `rec`, which would
+        // relabel a cross-session stop as belonging to the dispatching session
+        // and hide exactly the mismatch this field exists to expose.
+        session_id: sessionId,
         agent_type: rec?.agent_type ?? str(payload, 'agent_type', 'agentType', 'subagent_type', 'subagentType'),
         depth: rec?.depth ?? null,
         depth_basis: rec?.depth_basis ?? null,
@@ -661,7 +674,7 @@ export function processEnvelope(envelope: JsonValue, consumerRoot: string): numb
         reapStaleOpenRecords(consumerRoot, nowIso);
 
         if (event === 'subagent_start') handleStart(consumerRoot, payload, nowIso, sessionId);
-        else handleStop(consumerRoot, payload, nowIso);
+        else handleStop(consumerRoot, payload, nowIso, sessionId);
     } catch {
         // Malformed payload, unreadable disk, anything — never disturb the run.
         return EXIT_ALLOW;