@event4u/agent-config 9.36.0 → 10.0.0

package/src/scripts/_lib/environment_detector.ts

@@ -220,6 +220,50 @@ export interface DetectEnvironmentOptions {
      * hardened env and a 2s timeout; pass `() => null` to skip probing.
      */
     readonly probeVersion?: VersionProbe;
+    /**
+     * macOS Keychain presence probe for the Claude Code subscription
+     * credential. Omit to shell out to `security find-generic-password`;
+     * pass `() => false` to skip it entirely — every test that is not
+     * specifically about this probe should, so a developer machine's real
+     * Keychain never decides a test outcome.
+     */
+    readonly probeKeychain?: KeychainProbe;
+}
+
+/** `(service) => present?` — never returns the secret, only whether it exists. */
+export type KeychainProbe = (service: string) => boolean;
+
+/** Keychain service name Claude Code writes its subscription credential under. */
+export const CLAUDE_KEYCHAIN_SERVICE = 'Claude Code-credentials';
+
+/**
+ * Is the Claude Code subscription credential in the macOS login Keychain?
+ *
+ * Claude Code stores its OAuth credential in the Keychain on macOS and only
+ * falls back to `~/.claude/.credentials.json` elsewhere. Looking for the file
+ * alone therefore reports "no subscription" on the platform where the
+ * subscription is most likely to exist — which sent every macOS anthropic
+ * member down the metered `api` rung while a paid Claude subscription sat
+ * unused on the same machine. That is the defect this probe closes.
+ *
+ * `-w` is deliberately NOT passed: without it `security` prints attributes and
+ * never the password, so the secret cannot reach a log, a report, or a crash
+ * dump. Presence is read from the exit code alone.
+ */
+function defaultProbeKeychain(service: string): boolean {
+    if (process.platform !== 'darwin') return false;
+    try {
+        const res = spawnSync('security', ['find-generic-password', '-s', service], {
+            timeout: VERSION_PROBE_TIMEOUT_MS,
+            encoding: 'utf-8',
+            windowsHide: true,
+            env: hardenedSpawnEnv(),
+        });
+        if (res.error !== undefined || res.signal !== null) return false;
+        return res.status === 0;
+    } catch {
+        return false;
+    }
 }
 
 /**
@@ -298,6 +342,7 @@ function cliSubscriptionEvidence(
     home: string,
     env: EnvMap,
     claudeConfigDir: string,
+    probeKeychain: KeychainProbe,
 ): { source: AuthSource; evidence: string } | null {
     if (provider === 'anthropic') {
         const configDir = claudeConfigDir;
@@ -305,6 +350,11 @@ function cliSubscriptionEvidence(
             const p = path.join(configDir, rel);
             if (isFile(p)) return { source: 'cli-subscription', evidence: p };
         }
+        // macOS keeps the credential in the Keychain instead of the file above.
+        // The evidence string is a locator, never the secret.
+        if (probeKeychain(CLAUDE_KEYCHAIN_SERVICE)) {
+            return { source: 'cli-subscription', evidence: `keychain:${CLAUDE_KEYCHAIN_SERVICE}` };
+        }
         return null;
     }
     if (provider === 'openai') {
@@ -359,11 +409,12 @@ function detectAuth(opts: DetectEnvironmentOptions): {
         opts.home === undefined && opts.env === undefined
             ? claude_config_dir()
             : ((env['CLAUDE_CONFIG_DIR'] ?? '').trim() || path.join(home, '.claude'));
+    const probeKeychain = opts.probeKeychain ?? defaultProbeKeychain;
     const auth: DetectedAuth[] = [];
     const keys: DetectedKey[] = [];
 
     for (const provider of knownProviders()) {
-        const cli = cliSubscriptionEvidence(provider, home, env, claudeConfigDir);
+        const cli = cliSubscriptionEvidence(provider, home, env, claudeConfigDir, probeKeychain);
         if (cli !== null) {
             auth.push({ provider, source: cli.source, evidence: cli.evidence });
         }

package/src/scripts/ai_council/config.ts

@@ -639,6 +639,20 @@ export interface CouncilConfig {
     readonly low_impact: LowImpactConfig;
     readonly lens_overrides: LensOverridesConfig;
     readonly source_path: PathLike | null;
+    /**
+     * Transport keys the config file still carries and the loader deliberately
+     * IGNORED — dotted paths, e.g. `defaults.mode`, `members.anthropic.mode`.
+     *
+     * Transport is resolved per machine per invocation, never configured: the
+     * chain is `cli → api → unavailable`, and an airgapped host forces the
+     * `api` rung. Deleting the keys from the schema outright would have made
+     * every pre-existing installation fail to load, so a stale key is
+     * accepted, ignored, and reported once — the migration IS the ignore.
+     *
+     * Empty on a config that never carried one, which is the shape the current
+     * template ships.
+     */
+    readonly ignored_transport_keys: readonly string[];
 }
 
 // ── default factories (dataclass defaults) ─────────────────────────
@@ -796,7 +810,11 @@ export function _build_config(raw: Dict, source_path: PathLike): CouncilConfig {
         throw new CouncilConfigError('`enabled` must be a bool.');
     }
 
-    const defaults = _build_defaults(_asDict(_getOr(raw, 'defaults', {})));
+    const ignored_transport_keys: string[] = [];
+    const defaults = _build_defaults(
+        _asDict(_getOr(raw, 'defaults', {})),
+        ignored_transport_keys,
+    );
     const cost_budget = _build_cost_budget(
         _asDict(_getOr(raw, 'cost_budget', {})),
     );
@@ -809,7 +827,12 @@ export function _build_config(raw: Dict, source_path: PathLike): CouncilConfig {
     for (const [name, cfg] of Object.entries(members_raw)) {
         members.set(
             name,
-            _build_member(name, _asDict(_orEmpty(cfg)), defaults.mode),
+            _build_member(
+                name,
+                _asDict(_orEmpty(cfg)),
+                defaults.mode,
+                ignored_transport_keys,
+            ),
         );
     }
 
@@ -920,6 +943,7 @@ export function _build_config(raw: Dict, source_path: PathLike): CouncilConfig {
         low_impact,
         lens_overrides,
         source_path,
+        ignored_transport_keys,
     };
 }
 
@@ -1508,23 +1532,36 @@ function _build_consensus_scoring(d: Dict): ConsensusScoringConfig {
 
 const _VALID_MEMBER_MODES: ReadonlySet<string> = new Set(['cli', 'api']);
 
-function _build_defaults(d: Dict): DefaultsConfig {
+function _build_defaults(d: Dict, ignored: string[] = []): DefaultsConfig {
     if (!_isDict(d)) {
         throw new CouncilConfigError('`defaults` must be a mapping.');
     }
-    // road-to-always-on-orchestration Phase 3.1: CLI-first is the shipped
-    // default (was `api`) — see the module docstring rule 2. `manual` and a
-    // pinned `api`/`cli` remain valid overrides at every layer resolve_mode
-    // checks; this only changes what a config that never sets `mode` gets.
-    const mode = _get(d, 'mode', 'auto');
-    if (!(_isStr(mode) && _VALID_MODES.has(mode))) {
-        throw new CouncilConfigError(
-            `defaults.mode=${_pyRepr(mode)} not in ${_sortedListRepr(_VALID_MODES)}.`,
-        );
-    }
+    // Transport is RESOLVED, never configured.
+    //
+    // The CLI-first flip (road-to-always-on-orchestration Phase 3.1) changed
+    // only what a config that OMITS `mode` receives. Every installation that
+    // spelled the key out — which the wizard did, and which every pre-flip
+    // template shipped — kept its old `api` value forever, silently, and went
+    // on paying per token while a subscription CLI sat unused on the same
+    // machine. A default that only fires on an absent key does not migrate
+    // anybody; it just makes the docs read better than the behaviour.
+    //
+    // So the key is no longer read. `auto` is the only value this loader
+    // produces, and `transport_resolver` picks the concrete rung per machine
+    // per invocation (`cli → api → unavailable`, airgap forcing `api`). A file
+    // still carrying `mode:` loads fine and is reported via
+    // `ignored_transport_keys` — see `CouncilConfig`.
+    // `null` as the sentinel, not `undefined`: `_get`'s default parameter is
+    // typed `Json`, which excludes `undefined`. A config spelling `mode: null`
+    // is indistinguishable from an absent key here, and that is correct — a
+    // null transport is not a pin worth reporting.
+    if (_get(d, 'mode', null) !== null) {
+        ignored.push('defaults.mode');
+    }
+    const mode = 'auto';
     // `member_mode` (step-9 P8 · U1) — global preference for solo /
-    // CLI-mode invocations. Narrower set than `defaults.mode` because
-    // `manual` makes no sense as a per-member dispatch default.
+    // CLI-mode invocations. Narrower set than the retired `defaults.mode`
+    // because `manual` makes no sense as a per-member dispatch default.
     const member_mode = _get(d, 'member_mode', 'cli');
     if (!(_isStr(member_mode) && _VALID_MEMBER_MODES.has(member_mode))) {
         throw new CouncilConfigError(
@@ -1726,6 +1763,7 @@ function _build_member(
     // a future caller that omits the third argument observes the same
     // doctrine rather than silently reverting to the retired `api` default.
     default_mode = 'auto',
+    ignored: string[] = [],
 ): MemberConfig {
     if (!_VALID_PROVIDERS.has(name)) {
         throw new CouncilConfigError(
@@ -1738,15 +1776,15 @@ function _build_member(
     const model = _pyTruthy(modelVal) ? (modelVal as string) : '';
     const api_key_ref_raw = _get(cfg, 'api_key_ref', null);
     const api_key_ref = api_key_ref_raw === undefined ? null : api_key_ref_raw;
-    const member_mode_raw = _get(cfg, 'mode', null);
-    const member_mode = member_mode_raw === undefined ? null : member_mode_raw;
-    if (member_mode !== null && !(_isStr(member_mode) && _VALID_MODES.has(member_mode))) {
-        throw new CouncilConfigError(
-            `members.${name}.mode=${_pyRepr(member_mode)} not in ` +
-                `${_sortedListRepr(_VALID_MODES)}.`,
-        );
-    }
-    const effective_mode = member_mode !== null ? (member_mode as string) : default_mode;
+    // Per-member transport is no longer configurable either — same reasoning
+    // as `_build_defaults`. A member that pinned `mode: api` would reintroduce
+    // exactly the silent-spend path the global key was removed for, one
+    // provider at a time. Recorded as ignored, never read.
+    if (_get(cfg, 'mode', null) !== null) {
+        ignored.push(`members.${name}.mode`);
+    }
+    const member_mode: string | null = null;
+    const effective_mode = default_mode;
     const binary_raw = _get(cfg, 'binary', null);
     const binary = binary_raw === undefined ? null : binary_raw;
     if (binary !== null) {

package/src/scripts/before_complete_hook.ts

@@ -113,6 +113,14 @@ function _empty_state(): StateDict {
     verified_this_turn: false,
     ci_saw_pending: false,
     nonevidence_this_turn: 0,
+    // Round 7 § Phase 1 — the last CI read, SESSION-scoped on purpose. Every
+    // other counter here is turn-scoped because a stale POSITIVE would wrongly
+    // vouch ("I verified"). This one is a NEGATIVE ("CI was not settled"), and a
+    // stale negative only ever refuses more often — so surviving the turn
+    // boundary preserves the freshness invariant rather than bypassing it. It
+    // has to survive it: the measured failure is a completion claim in a LATER
+    // turn than the poll it rests on.
+    ci_last: null,
     checked_at: _now(),
   };
 }
@@ -303,6 +311,16 @@ function _update(state: StateDict, event: string, envelope: StateDict): StateDic
     // Session boundary — reset session-scoped counters.
     state["session_id"] = session_id;
     state["verifications_this_session"] = 0;
+    // R2 finding 1 (high). `ci_last` is SESSION-scoped, and until this line
+    // nothing cleared it: `_reset_turn` clears the turn-scoped witness,
+    // `_empty_state` sets it null only for a state file that does not exist yet,
+    // and `_load_state` merges the persisted value over that default. So session
+    // A polled CI, saw pending, and ended; session B — a doc-only session that
+    // never touched CI — said "Fertig" and was REFUSED, contradicting both the
+    // consumer's own comment ("a session that never polled CI must never be
+    // refused for it") and the negative case the roadmap pinned. Session-scoped
+    // has to mean cleared at the boundary, or it means never cleared.
+    state["ci_last"] = null;
     state = _reset_turn(state, session_id);
   }
 
@@ -338,6 +356,27 @@ function _update(state: StateDict, event: string, envelope: StateDict): StateDic
         } else {
           counts = false; // unrecognised or unreadable — never read as settled
         }
+        // Round 7 § 1.1 — the session-scoped negative the turn-end consumer reads.
+        //
+        // R2 finding 3 (medium), and it was the sharpest one: this said `settled:
+        // pending === 0` and CLAIMED "the same discrimination `counts` makes
+        // above". It was not. `counts` requires `!vacuous && ci_saw_pending`;
+        // `pending === 0` alone drops both. A post-push poll that reads a stale
+        // all-pass table returns pending 0 — verbatim the FC-3b failure documented
+        // twenty lines up — and recorded `settled: true`, so the completion
+        // detector went SILENT in exactly the premature-claim case it exists for.
+        // A detector defeated by the false settle it was built to catch is worse
+        // than no detector, because it reports coverage.
+        //
+        // Now it reuses `counts` itself, which is that discrimination rather than
+        // a paraphrase of it. `pending === null` (unreadable, and "no checks
+        // reported") stays not-a-settle by construction.
+        state["ci_last"] = {
+          at: _now(),
+          command: cmd.slice(0, 512),
+          pending,
+          settled: pending === 0 && counts === true,
+        };
       }
 
       state["last_verification"] = {

package/src/scripts/check_bridge_derivation.ts

@@ -16,6 +16,11 @@
  *      changed entry means the tree on disk did not derive from the current
  *      source (hand-edit, stale generation, or a nondeterministic generator).
  *
+ * Both legs are scoped to the roots this checkout's generator actually writes:
+ * a root whose owning tool is deactivated in `agents/.agent-tools.yml` has no
+ * regeneration path, so nothing found there is drift it could repair. Skipped
+ * roots are named on stderr, never dropped silently.
+ *
  * Run AFTER `task generate-tools` (CI: the sync-consistency job). Exit 1 on
  * the first drifted artefact, naming it.
  */
@@ -26,6 +31,7 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { active_tools_at } from './condense.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.join(path.dirname(_HERE), '..', '..');
@@ -50,6 +56,59 @@ export const BRIDGE_ROOTS: readonly string[] = [
 /** Repo-relative prefixes a bridge symlink may resolve into. */
 const DERIVATION_SOURCES = ['dist/agent-src', 'src', 'AGENTS.md'] as const;
 
+/**
+ * Bridge root → the tool id whose activation makes the generator maintain it.
+ *
+ * A root ABSENT from this map is maintained unconditionally, and `.augment` is
+ * the one that matters: `project_to_augment()` carries no tool gate, so mapping
+ * it to `augment` would silence the audit on a tree that is regenerated on
+ * every run — a strict weakening. Absent-means-unconditional keeps that the
+ * default, so a future bridge root has to opt IN to being skippable.
+ */
+const ROOT_TOOL_ID: Readonly<Record<string, string>> = {
+    '.claude/rules': 'claude-code',
+    '.claude/skills': 'claude-code',
+    '.claude/agents': 'claude-code',
+    '.claude/personas': 'claude-code',
+    '.claude/user-types': 'claude-code',
+    '.cursor/rules': 'cursor',
+    '.cursor/commands': 'cursor',
+    '.windsurf/rules': 'windsurf',
+    '.windsurf/workflows': 'windsurf',
+    '.windsurfrules': 'windsurf',
+    '.clinerules': 'cline',
+    'GEMINI.md': 'gemini',
+};
+
+/**
+ * Split `roots` into the ones this checkout's generator maintains and the ones
+ * it does not, given the active tool set (`null` = all tools active).
+ *
+ * Auditing a root whose owning tool is inactive is not a drift check: the
+ * generator never writes it, so whatever sits there is an unmaintained fossil
+ * with no regeneration path. Reporting it leaves hand-deletion as the only
+ * compliant action, which is exactly what `check_rule_projection_integrity`
+ * rejected as "not a gate" after the same masked-config shape broke the 9.27.0
+ * release. This one broke 9.36.0 the same way: `agents/.agent-tools.yml` is
+ * committed with all eight tools but carries `skip-worktree` locally and reads
+ * `tools: []`, so `.claude/skills/` had not been regenerated since 2026-07-05
+ * and still held symlinks to a directory renamed since.
+ */
+export function partition_roots(
+    roots: readonly string[],
+    active: ReadonlySet<string> | null,
+): { audited: string[]; skipped: string[] } {
+    if (active === null) return { audited: [...roots], skipped: [] };
+    const audited: string[] = [];
+    const skipped: string[] = [];
+    for (const r of roots) {
+        const tool = ROOT_TOOL_ID[r];
+        if (tool === undefined || active.has(tool)) audited.push(r);
+        else skipped.push(r);
+    }
+    return { audited, skipped };
+}
+
 function _walk(p: string, out: string[]): void {
     const st = fs.lstatSync(p);
     if (st.isSymbolicLink() || st.isFile()) {
@@ -132,7 +191,22 @@ export function validate_symlinks(root: string, repoRoot: string): string[] {
 
 export function run(repoRoot: string): string[] {
     const errors: string[] = [];
-    const roots = BRIDGE_ROOTS.map((r) => path.join(repoRoot, r));
+    const { audited, skipped } = partition_roots(BRIDGE_ROOTS, active_tools_at(repoRoot));
+
+    // LOUD, never a silent narrowing: the audited surface just shrank, and a
+    // reader who cannot see which roots dropped out cannot distinguish this run
+    // from a full one — that indistinguishability is the false green
+    // `_lib/scan_scope.ts` exists to prevent.
+    if (skipped.length > 0) {
+        process.stderr.write(
+            `⚠️  check_bridge_derivation: ${skipped.length} bridge root(s) NOT audited — ` +
+                `agents/.agent-tools.yml deactivates the owning tool, so the generator does ` +
+                `not write them in this checkout and their contents cannot be attributed as ` +
+                `drift: ${skipped.join(', ')}. CI activates all eight tools.\n`,
+        );
+    }
+
+    const roots = audited.map((r) => path.join(repoRoot, r));
 
     const before: Record<string, Record<string, string>> = {};
     for (const r of roots) before[r] = snapshot_tree(r);
@@ -141,11 +215,17 @@ export function run(repoRoot: string): string[] {
     // there is nothing to diff and nothing to validate, and the check reports a
     // fixpoint it never tested. Thrown, not returned — `errors` is the drift
     // channel, and a dead scope is not drift.
+    //
+    // No `allowEmpty` twin of the sibling gate's is needed here, and that is a
+    // property of the map rather than an omission: `.augment` is maintained
+    // unconditionally, so `audited` is never empty and zero entries always means
+    // a genuinely dead surface (no `dist/agent-src/` at all), not a deactivated
+    // tool. Map `.augment` to a tool and this reasoning stops holding.
     assertScanned({
         gate: 'check_bridge_derivation',
         scanned: Object.values(before).reduce((n, snap) => n + Object.keys(snap).length, 0),
         units: 'bridge entries',
-        roots: BRIDGE_ROOTS,
+        roots: audited,
     });
 
     // Regenerate in a child process so MODULE_STATE resolves exactly as the
@@ -188,6 +268,12 @@ if (isMain) {
         for (const e of errors) process.stderr.write(`❌  ${e}\n`);
         process.exit(1);
     }
-    process.stdout.write('✅  bridge trees derive from src/ (symlink targets valid, regeneration is a fixpoint)\n');
+    // Name the count rather than "bridge trees": with a tool deactivated the
+    // green covers fewer roots than the reader would assume from a bare tick.
+    const n = partition_roots(BRIDGE_ROOTS, active_tools_at(root)).audited.length;
+    process.stdout.write(
+        `✅  ${n}/${BRIDGE_ROOTS.length} bridge roots derive from src/ ` +
+            '(symlink targets valid, regeneration is a fixpoint)\n',
+    );
     process.exit(0);
 }

package/src/scripts/check_ci_local_parity.ts

@@ -38,6 +38,27 @@ const HOOK = path.join(REPO, 'src', 'scripts', 'install-hooks.sh');
 /** Roots of the local closure. `ci` is the local mirror; the hook is what a push runs. */
 const LOCAL_ROOTS = ['ci', 'consistency'] as const;
 
+/**
+ * Round 7 § Phase 3 — the third dimension, and why two were not enough.
+ *
+ * `task ci` INCLUDES `preflight` (`Taskfile.yml:87`), so the two roots above
+ * answer "does the local MIRROR match CI". The pass an agent is actually told to
+ * run before pushing is `task preflight`, a deliberate subset of `ci` — its own
+ * docstring excludes `check_enforcement_coverage` at a measured 30.7 s because
+ * "a pre-push gate that doubles the hook teaches people to skip it".
+ *
+ * That makes `CI ∩ ci \ preflight` invisible to this gate by construction, and it
+ * is exactly where round 7's measured "green locally, red remotely" cycles came
+ * from: the Thin-Root char cap, the ratchet living in the Node-Tests shard, and
+ * the derived-page freshness check.
+ *
+ * Reported, not gated. The subset is intentional, so failing on it would demand
+ * that `preflight` grow into `ci` — the opposite of what its author decided. What
+ * this dimension removes is the IMPLICATION that a green preflight means CI will
+ * be green.
+ */
+const PREFLIGHT_ROOTS = ['preflight'] as const;
+
 export interface Declared {
     id: string;
     class: string;
@@ -197,6 +218,19 @@ export interface ParityReport {
     undeclared_ci_only: string[];
     undeclared_local_only: string[];
     stale_declarations: string[];
+    /** Round 7 § Phase 3 — `task preflight`'s own closure. */
+    preflight_gates: string[];
+    /**
+     * `CI ∩ local \ (preflight ∪ pre-push hook)` — gates a push's remote run
+     * enforces, the local mirror covers, and NOTHING a push runs locally reaches.
+     * Report-only: the measured size of "green locally, red remotely", not a
+     * failure.
+     *
+     * The hook's own closure is in the subtrahend per R2 finding 4: subtracting
+     * preflight alone counted gates the pre-push hook already runs, which cannot
+     * fail after a push. That read 221; the honest figure is 209.
+     */
+    ci_not_in_preflight: string[];
 }
 
 export function analyse(repo = REPO, manifest?: Manifest): ParityReport {
@@ -231,12 +265,38 @@ export function analyse(repo = REPO, manifest?: Manifest): ParityReport {
         ...[...declaredLocal].filter((g) => localGates.has(g) && ciGates.has(g)),
     ].sort();
 
+    // Round 7 § 3.1 — the third dimension. Derived the same way as the other two,
+    // so it cannot drift from them by construction.
+    //
+    // R2 finding 4 (medium): the first version subtracted only the `preflight`
+    // closure from `localGates`, and `localGates` includes every gate reachable
+    // from `install-hooks.sh` — which the PRE-PUSH hook runs. A gate that runs
+    // before the push lands cannot produce a "green locally, red remotely" cycle,
+    // so counting it inflated the number and mislabelled it, in a step whose own
+    // text calls the number "the deliverable, not an adjective". The subtrahend is
+    // therefore everything a push already runs: preflight PLUS the hook's own
+    // closure.
+    const preflightGates = local_closure(PREFLIGHT_ROOTS, tasks);
+    const prePush = new Set(preflightGates);
+    if (fs.existsSync(HOOK)) {
+        const hook = fs.readFileSync(HOOK, 'utf-8');
+        for (const g of extract_gates(hook)) prePush.add(g);
+        for (const t of extract_tasks(hook)) {
+            for (const g of local_closure([t], tasks)) prePush.add(g);
+        }
+    }
+    const ci_not_in_preflight = [...ciGates]
+        .filter((g) => localGates.has(g) && !prePush.has(g))
+        .sort();
+
     return {
         ci_gates: [...ciGates].sort(),
         local_gates: [...localGates].sort(),
         undeclared_ci_only,
         undeclared_local_only,
         stale_declarations,
+        preflight_gates: [...preflightGates].sort(),
+        ci_not_in_preflight,
     };
 }
 
@@ -292,6 +352,20 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         for (const g of r.stale_declarations) process.stdout.write(`  - ${g}\n`);
     }
 
+    // Round 7 § 3.2 — printed on EVERY path, pass or fail, because the number is
+    // the deliverable. A green parity verdict above says the local MIRROR matches
+    // CI; it says nothing about the pass a contributor is told to run, and reading
+    // the green line as if it did is the implication this block removes.
+    process.stdout.write(
+        `ℹ️   preflight: ${String(r.preflight_gates.length)} gate(s) of the ${String(r.local_gates.length)} local ones; ` +
+            `${String(r.ci_not_in_preflight.length)} CI-enforced gate(s) run NEITHER in \`task preflight\` NOR\n` +
+            '    anywhere else the pre-push hook reaches — i.e. the set that can only fail after\n' +
+            '    a push. `task ci` INCLUDES preflight, so the parity verdict above cannot see it.\n' +
+            '    Report-only: the subset is deliberate (see the preflight docstring). A green\n' +
+            '    preflight is therefore not a prediction that CI will be green.\n',
+    );
+    for (const g of r.ci_not_in_preflight) process.stdout.write(`      · ${g}\n`);
+
     if (!failed) {
         process.stdout.write(
             `✅  CI ↔ local parity: ${String(r.ci_gates.length)} CI gate(s), ${String(r.local_gates.length)} local, ` +

package/src/scripts/check_references.ts

@@ -57,7 +57,21 @@ function makeBrokenRef(
 
 const SCAN_DIRS = ['dist/agent-src', 'agents'];
 const SKIP_DIRS = [
-    'agents/roadmaps/archive', // archived roadmaps have historical refs
+    // Archived roadmaps have historical refs — a link to a file that existed when
+    // the plan was written is not drift, so the exclusion is right on the merits.
+    //
+    // ROUND 7, DOWNGRADE (2026-08-12): it also means this checker is the ONLY thing
+    // that would see a class of real rot, and cannot. Measured: **530 dead relative
+    // links across 147 of 466 archived roadmaps**. The cause is not history — it is
+    // that `archive_completed_roadmaps` moves a file one directory deeper and never
+    // re-depths its outgoing relative links, so a link that resolved before the move
+    // is broken BY the move. Two tools, one silence: the writer does not rewrite, and
+    // the only checker that would notice is scoped away from where it lands.
+    //
+    // Not repaired here: the fix is a bulk edit across 147 files plus a re-depth pass
+    // in the sweep, which is its own change. Recorded so the exclusion is read as a
+    // known gap with a number rather than as coverage.
+    'agents/roadmaps/archive',
     'agents/runtime/council/sessions', // per-user audit trail (gitignored), captured provider output
     'agents/runtime/council/responses', // paired council output (gitignored), captured provider output
     'agents/runtime/council/questions', // design Q&A trail — forward-refs to planned artifacts

package/src/scripts/condense.ts

@@ -359,8 +359,18 @@ const _ALL_TOOLS: ReadonlySet<string> = new Set([
 ]);
 void _ALL_TOOLS;
 
-function _active_tools(): ReadonlySet<string> | null {
-    const tools_file = path.join(MODULE_STATE.PROJECT_ROOT, 'agents', '.agent-tools.yml');
+/**
+ * Tool ids selected by `agents/.agent-tools.yml` under `root`, or `null` when
+ * the file is absent / malformed / carries no `tools:` list — `null` means
+ * "all tools active", never "none".
+ *
+ * Root-parameterised and exported so a consumer auditing a checkout other than
+ * `MODULE_STATE.PROJECT_ROOT` (a gate run with `--root`) reads the selection
+ * this generator actually honours, instead of re-implementing these four
+ * fallbacks and drifting from them.
+ */
+export function active_tools_at(root: string): ReadonlySet<string> | null {
+    const tools_file = path.join(root, 'agents', '.agent-tools.yml');
     if (!_exists(tools_file)) {
         return null;
     }
@@ -380,6 +390,10 @@ function _active_tools(): ReadonlySet<string> | null {
     return new Set(tools.filter((t): t is string => typeof t === 'string'));
 }
 
+function _active_tools(): ReadonlySet<string> | null {
+    return active_tools_at(MODULE_STATE.PROJECT_ROOT);
+}
+
 function _tool_active(tool_id: string): boolean {
     const active = _active_tools();
     return active === null ? true : active.has(tool_id);