@event4u/agent-config 14.10.0 → 14.11.0

package/src/scripts/hooks/rule_inject_hook.ts

@@ -0,0 +1,318 @@
+#!/usr/bin/env tsx
+/**
+ * Rule-inject — the delivery twin of `skill-route`, with the opposite payload
+ * policy (`road-to-trigger-delivered-rule-bodies` Phase 1).
+ *
+ * BODIES, NEVER POINTERS — and the difference from its twin is deliberate
+ * rather than incidental. `skill_route_hook.ts:14` ships "POINTERS, NEVER
+ * BODIES" on this same slot, and it is right to: a skill is a thing the agent
+ * *invokes*, so naming it is enough. A rule is a thing the agent must already
+ * be *under*, and the only datum anyone has on pointer-shaped rule delivery is
+ * the 36.2 %-against-48 % run at `docs/CLAIMS.md:188-189`. Whatever that
+ * instrument's flaws — and ADR-202 closed it — it points one way.
+ *
+ * DEFAULT OFF, AND OFF MEANS ZERO BYTES. The concern registers on two slots but
+ * returns before reading the router unless `lean_projection.mode: delivery` is
+ * set. Under every shipped default it emits nothing, costs no injection budget,
+ * and leaves the standing corpus exactly as it is today. That is why its
+ * `hook-token-budget.json` row is registered against the per-prompt cap rather
+ * than a measured emission: there is no measured emission to register yet.
+ *
+ * ONE MATCHER, SHARED WITH THE OFFLINE MODEL. Everything about selection,
+ * ordering, capping and body loading comes from `_lib/rule_injection.ts`, which
+ * `model_rule_injection.ts` also imports. Step 0.5 states the reason in as many
+ * words: an experiment whose offline pricing and runtime delivery use different
+ * matchers measures nothing.
+ *
+ * ONCE PER SESSION PER RULE, RE-ARMED ON COMPACTION. A rule's body is injected
+ * the first time one of its triggers fires and not again, because the model
+ * already has it. Compaction is exactly the event that makes that false, so
+ * `pre_compact` clears the seen-set — the same pin-lost shape `language-mirror`
+ * uses. State lives under `agents/runtime/state/`, the class
+ * `context-hygiene.json` already occupies; no new state convention is created.
+ *
+ * NEVER BLOCKS. Every failure path returns 0: unreadable stdin, malformed JSON,
+ * missing router, unreadable body, unwritable state. The one non-zero exit is
+ * the host's advisory context channel (exit 2 + `decision: "warn"`), the same
+ * channel `ui-route-nudge` and `code-graph-nudge` already use on `pre_tool_use`
+ * with `severity: advisory` — a warn there is an injection, not a deny.
+ *
+ * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `user_prompt_submit` and
+ * `pre_tool_use` are bound on a subset of hosts, and only `claude` honours a
+ * deny at all. On a host where neither slot is bound this concern cannot run,
+ * which is the whole reason the flip step 2.4 gates on is Claude-only. Run
+ * `agent-config hooks:status` for the host you are actually on.
+ *
+ * SUBAGENTS ARE OUT OF REACH, MEASURED. Neither slot fires inside a spawned
+ * child session and the `subagent_start` payload carries no prompt field — see
+ * `agents/evidence/investigations/subagent-start-payload-probe.md` (2026-08-23,
+ * claude 2.1.241, three verdicts). Delivery is therefore orchestrator-only, and
+ * no third binding is added.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { hookSectionEnabled, leanProjectionModeRaw } from '../_lib/hook_settings.js';
+import { deliversBodies, normalizeLeanProjectionMode } from '../_lib/lean_projection_mode.js';
+import {
+    loadRuleBody,
+    loadRouter,
+    matchTierRules,
+    selectForInjection,
+} from '../_lib/rule_injection.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+
+/**
+ * Per-prompt injection ceiling, in UTF-8 BYTES.
+ *
+ * DERIVED, NOT PICKED: `model_rule_injection --corpus tests/eval/routing-matrix`
+ * measured the matched-body-token distribution over the frozen labelled corpus
+ * at p50 1,728 / p90 4,804 / p99 8,248 / max 12,957 exact-BPE tokens, and step
+ * 1.1 specifies "the p90 from 0.4, rounded to 500" — 4,804 rounds up to 5,000.
+ *
+ * BYTES rather than tokens, and the unit change is the point rather than a
+ * detail. `_lib/token_count.ts` resolves `js-tiktoken` at module load, so a
+ * token-capped concern drags a tokenizer into EVERY hook dispatch on every
+ * slot, for a concern that is default-OFF and emits nothing. Measured: 202 ms
+ * -> 196 ms on the `pre_tool_use` p95 when the concern is unbound entirely, and
+ * the CI latency gate went red on the branch that introduced it while passing
+ * on main. So the runtime cap is the same bound in the unit
+ * `hook-token-budget.json` already enforces — 5,000 tok at the ~4 bytes/token
+ * this corpus measures is 20,480 B, which is exactly this concern's registered
+ * row. Cap and budget row are now one number instead of two units.
+ *
+ * Re-run that command if the corpus or the bodies move; a cap copied from a
+ * stale measurement is worse than no cap, because it looks derived.
+ */
+export const CAP_BYTES = 20480;
+
+/** Tools whose input names a file this concern can match path triggers against. */
+export const FILE_TOOLS = new Set(['Write', 'Edit', 'NotebookEdit', 'Read', 'MultiEdit']);
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function str(o: JsonObject, ...keys: string[]): string | null {
+    for (const k of keys) {
+        const v = o[k];
+        if (typeof v === 'string' && v !== '') return v;
+    }
+    return null;
+}
+
+/** Workspace root the envelope points at, falling back to the process cwd. */
+export function workspaceRoot(env: JsonObject): string {
+    return str(env, 'workspace', 'cwd', 'project_dir') ?? process.cwd();
+}
+
+// ── seen-set state ───────────────────────────────────────────────────────
+
+export interface SeenState {
+    rules: string[];
+}
+
+export function statePath(root: string, session: string): string {
+    const safe = session.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 80) || 'unknown';
+    return path.join(root, 'agents', 'runtime', 'state', 'rule-inject', `${safe}.json`);
+}
+
+export function readSeen(root: string, session: string): Set<string> {
+    try {
+        const raw = fs.readFileSync(statePath(root, session), 'utf-8');
+        const parsed = JSON.parse(raw) as SeenState;
+        return new Set(Array.isArray(parsed.rules) ? parsed.rules.map(String) : []);
+    } catch {
+        return new Set(); // fresh session, or a file nothing can parse
+    }
+}
+
+export function writeSeen(root: string, session: string, seen: Set<string>): void {
+    const p = statePath(root, session);
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        const payload: SeenState = { rules: [...seen].sort() };
+        fs.writeFileSync(`${p}.tmp`, `${JSON.stringify(payload)}\n`, 'utf-8');
+        fs.renameSync(`${p}.tmp`, p);
+    } catch {
+        /* unwritable state must never fail a turn — worst case a re-injection */
+    }
+}
+
+export function clearSeen(root: string, session: string): void {
+    try {
+        fs.rmSync(statePath(root, session), { force: true });
+    } catch {
+        /* ignore */
+    }
+}
+
+// ── payload extraction ───────────────────────────────────────────────────
+
+/** The user's prompt, across the shapes the hosts use. */
+export function extractPrompt(payload: JsonObject): string {
+    return str(payload, 'prompt', 'user_prompt', 'userPrompt', 'message', 'text') ?? '';
+}
+
+/** The file path a file-touching tool call names, or `null`. */
+export function extractFilePath(payload: JsonObject): string | null {
+    const ti = payload['tool_input'] ?? payload['toolInput'] ?? payload['input'];
+    if (!isObject(ti)) return null;
+    return str(ti, 'file_path', 'path', 'filePath', 'notebook_path');
+}
+
+// ── decision ─────────────────────────────────────────────────────────────
+
+export interface Injection {
+    rules: string[];
+    bytes: number;
+    body: string;
+}
+
+/**
+ * Build the injection for one event, or `null` for silence.
+ *
+ * `prompt` drives keyword / phrase / command triggers; `openFiles` drives
+ * `path_prefix` / `file_pattern`. On the tool slot the prompt is deliberately
+ * empty, so a file event can only ever fire a path trigger — a tool call is not
+ * a restatement of the user's request and must not re-fire keyword rules.
+ */
+export function buildInjection(
+    root: string,
+    prompt: string,
+    openFiles: string[] | null,
+    command: string | null,
+    seen: Set<string>,
+): Injection | null {
+    let router;
+    try {
+        router = loadRouter(root);
+    } catch {
+        return null; // no router — nothing to deliver, and never a failure
+    }
+    const matches = matchTierRules(router, prompt, openFiles, command).filter(
+        (m) => !seen.has(m.id),
+    );
+    if (matches.length === 0) return null;
+    const sel = selectForInjection(root, matches, CAP_BYTES);
+    const parts: string[] = [];
+    const ids: string[] = [];
+    for (const m of sel.selected) {
+        const body = loadRuleBody(root, m.id);
+        if (body === null) continue;
+        ids.push(m.id);
+        parts.push(`<rule id="${m.id}" tier="${m.tier}">\n${body.trim()}\n</rule>`);
+    }
+    if (ids.length === 0) return null;
+    return { rules: ids, bytes: sel.bytes, body: parts.join('\n\n') };
+}
+
+// ── main ─────────────────────────────────────────────────────────────────
+
+/**
+ * Whether the settings gate applies.
+ *
+ * Through the dispatcher the gate is absolute: no `lean_projection.mode:
+ * delivery`, no bytes. A DIRECT CLI invocation is a probe by definition — an
+ * operator piping an envelope into this file is asking to see what it would
+ * deliver — so there the mode defaults to on. `AGENT_CONFIG_REPLAY` re-imposes
+ * the gate, which is what keeps `bench_hook_injection` measuring the shipped
+ * default (zero bytes) rather than the probe.
+ */
+export function gateOpen(root: string, cliEntry: boolean): boolean {
+    if (deliversBodies(normalizeLeanProjectionMode(leanProjectionModeRaw(root)))) return true;
+    if (hookSectionEnabled(root, 'rule_inject')) return true;
+    return cliEntry && process.env['AGENT_CONFIG_REPLAY'] !== '1';
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let eventOverride: string | null = null;
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--event') {
+            i += 1;
+            eventOverride = argv[i] ?? null;
+        }
+    }
+
+    let env: JsonObject = {};
+    try {
+        const raw = readHookStdin();
+        const parsed = raw.trim() ? (JSON.parse(raw) as unknown) : {};
+        env = isObject(parsed) ? parsed : {};
+    } catch {
+        return EXIT_ALLOW; // malformed envelope — never block
+    }
+
+    const root = workspaceRoot(env);
+    const payload = isObject(env['payload']) ? (env['payload'] as JsonObject) : env;
+    const slot = eventOverride ?? str(env, 'event') ?? 'user_prompt_submit';
+    const session = str(env, 'session_id', 'sessionId') ?? str(payload, 'session_id', 'sessionId') ?? 'unknown';
+
+    if (slot === 'pre_compact') {
+        clearSeen(root, session);
+        return EXIT_ALLOW; // re-arm is silent; the next turn re-injects
+    }
+    if (slot !== 'user_prompt_submit' && slot !== 'pre_tool_use') return EXIT_ALLOW;
+    if (!gateOpen(root, _isCliEntry())) return EXIT_ALLOW;
+
+    let prompt = '';
+    let openFiles: string[] | null = null;
+    let command: string | null = null;
+    if (slot === 'user_prompt_submit') {
+        prompt = extractPrompt(payload);
+        if (prompt === '') return EXIT_ALLOW;
+        const m = /^\s*(\/[A-Za-z0-9:_-]+)/.exec(prompt);
+        command = m ? (m[1] as string) : null;
+    } else {
+        const tool = str(payload, 'tool_name', 'toolName', 'tool');
+        if (tool === null || !FILE_TOOLS.has(tool)) return EXIT_ALLOW;
+        const fp = extractFilePath(payload);
+        if (fp === null) return EXIT_ALLOW;
+        openFiles = [fp];
+    }
+
+    const seen = readSeen(root, session);
+    const injection = buildInjection(root, prompt, openFiles, command, seen);
+    if (injection === null) return EXIT_ALLOW; // silence is the default
+
+    for (const id of injection.rules) seen.add(id);
+    writeSeen(root, session, seen);
+
+    process.stdout.write(
+        `${JSON.stringify({
+            decision: 'warn',
+            reason: `rule-inject: ${injection.rules.length} rule body/bodies on ${slot} (${injection.bytes} B)`,
+            additional_context: injection.body,
+        })}\n`,
+    );
+    return EXIT_WARN;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/hot_context_hook.ts

@@ -36,6 +36,7 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
 import { hardenedSpawnEnv } from './_lib/spawn_env.js';
+import { computeRereads } from './_lib/transcript_reads.js';
 import { redact_low_impact_entry } from './ai_council/redact_low_impact_entry.js';
 import { readHookStdin } from './hooks/hook_stdin.js';
 
@@ -57,6 +58,7 @@ const MAX_OPEN_VERIFICATIONS = 3;
 const THREAD_SNIPPET_CHARS = 200;
 const CHANGE_SNIPPET_CHARS = 120;
 const KEY_FACTS_CHARS = 600;
+const MAX_REREAD_LINES = 3; // advisory, not an inventory — see _reread_lines
 
 const VERIFICATION_RE = /\b(fail(ing|ed|ure)?|error|exit[= ][1-9]|red\b|broken)\b/i;
 
@@ -161,11 +163,55 @@ function _word_count(text: string): number {
     return text.split(/\s+/).filter((w) => w.length > 0).length;
 }
 
+// ---------------------------------------------------------------------
+// re-read advisory (road-to-role-scoped-spawn-profiles Phase 3 Steps 4-5)
+// ---------------------------------------------------------------------
+
+/**
+ * Files this leg read more than once, as advisory lines for the cache.
+ *
+ * Phase 3 Step 4 of `road-to-role-scoped-spawn-profiles` requires the
+ * suppression to ride THIS surface rather than arrive as a second artefact,
+ * and Step 5 requires it to stay advice: there is no refuse branch anywhere
+ * below, and there is no code path that returns a deny on a re-read condition.
+ * The output is three lines in a markdown cache; the next leg may ignore it.
+ *
+ * **Why the path is relativised, and why an outside path is dropped rather
+ * than shortened.** The privacy floor
+ * ({@link _redact_lines} → `redact_low_impact_entry`) drops any line carrying
+ * a project-rooted absolute path, so emitting `/Users/...` would produce a
+ * silently empty section — the feature would look implemented and do nothing.
+ * Relativising to the workspace root keeps the line inside the floor. A path
+ * OUTSIDE the root cannot be relativised without `../` escapes that re-reveal
+ * the layout, and it is another project's business in any case, so it is
+ * dropped entirely.
+ *
+ * Fail-silent: no transcript path, an unreadable one, or a malformed leg all
+ * yield `[]`. This is a cache, and a cache that throws is worse than a cache
+ * that is short.
+ */
+export function _reread_lines(transcriptPath: string | null, root: string): string[] {
+    if (!transcriptPath) return [];
+    const result = computeRereads([transcriptPath]);
+    const lines: string[] = [];
+    for (const f of result.files) {
+        if (lines.length >= MAX_REREAD_LINES) break;
+        const rel = path.relative(root, f.file_path);
+        if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+        lines.push(`${rel} — read ${f.total_reads}x this leg (${f.duplicate_reads} re-read)`);
+    }
+    return lines;
+}
+
 // ---------------------------------------------------------------------
 // stop — deterministic write
 // ---------------------------------------------------------------------
 
-export function build_hot_context(root: string, now: Date = new Date()): string {
+export function build_hot_context(
+    root: string,
+    now: Date = new Date(),
+    transcriptPath: string | null = null,
+): string {
     const session = _latest_session_entries(_read_history(root));
 
     const userPrompts = session.filter((e) => e.t === 'user_prompt' && e.text);
@@ -188,20 +234,36 @@ export function build_hot_context(root: string, now: Date = new Date()): string
     );
     const lastStop = String(stops[stops.length - 1]?.text ?? '');
     const keyFacts = _redact_lines(lastStop ? [_snippet(lastStop, KEY_FACTS_CHARS)] : []);
+    const rereads = _redact_lines(_reread_lines(transcriptPath, root));
 
     const droppedTotal =
-        activeThreads.dropped + recentChanges.dropped + openVerifications.dropped + keyFacts.dropped;
+        activeThreads.dropped +
+        recentChanges.dropped +
+        openVerifications.dropped +
+        keyFacts.dropped +
+        rereads.dropped;
 
     // Assemble; trim lowest-priority sections first until under the word cap.
     // Priority (highest kept longest): Key Facts > Active Threads >
-    // Open Verifications > Recent Changes.
+    // Open Verifications > Recent Changes > Re-Read Advisory.
+    //
+    // The advisory sits LAST on purpose. It is the only section that is a
+    // suggestion rather than a record of what happened, so when the 400-word
+    // cap bites it is the one whose loss costs nothing.
     const sections: Array<{ title: string; items: string[] }> = [
         { title: 'Key Facts', items: keyFacts.kept },
         { title: 'Active Threads', items: activeThreads.kept },
         { title: 'Open Verifications', items: openVerifications.kept },
         { title: 'Recent Changes', items: recentChanges.kept },
+        { title: 'Re-Read Advisory', items: rereads.kept },
+    ];
+    const trimOrder = [
+        'Re-Read Advisory',
+        'Recent Changes',
+        'Open Verifications',
+        'Active Threads',
+        'Key Facts',
     ];
-    const trimOrder = ['Recent Changes', 'Open Verifications', 'Active Threads', 'Key Facts'];
 
     const render = (): string => {
         const lines: string[] = [
@@ -240,9 +302,9 @@ export function build_hot_context(root: string, now: Date = new Date()): string
     return text;
 }
 
-function _write_hot_context(root: string): void {
+function _write_hot_context(root: string, transcriptPath: string | null = null): void {
     const target = _hot_context_path(root);
-    const text = build_hot_context(root);
+    const text = build_hot_context(root, new Date(), transcriptPath);
     fs.mkdirSync(path.dirname(target), { recursive: true });
     const tmp = `${target}.tmp-${process.pid}`;
     fs.writeFileSync(tmp, text, { encoding: 'utf-8' });
@@ -392,7 +454,12 @@ export function main(): number {
         // one rebuild and can never produce a worse cache than the older one it
         // replaces. It emits nothing — the restore side is unchanged.
         if (event === 'stop' || event === 'session_end' || event === 'pre_compact') {
-            _write_hot_context(root);
+            // Claude Code puts the leg's own transcript on the stop payload;
+            // the camelCase alias is defensive, matching how the subagent
+            // ledger reads `last_assistant_message`. Absent on other hosts,
+            // where the advisory is simply empty.
+            const tp = payload.transcript_path ?? payload.transcriptPath;
+            _write_hot_context(root, typeof tp === 'string' && tp.length > 0 ? tp : null);
         } else if (event === 'session_start') {
             const source = String(payload.source ?? '');
             const decision = restore_hot_context(root, source);

package/src/scripts/install.ts

@@ -74,6 +74,7 @@ import type * as YamlModule from 'yaml';
 import { build_merge_entries } from './_lib/json_pointers.js';
 import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import * as installed_lock from './_lib/installed_lock.js';
+import * as mcp_bridge from './_lib/mcp_bridge.js';
 import * as scoped_projection from './_lib/scoped_projection.js';
 import * as surface_tiers from './_lib/surface_tiers.js';
 import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
@@ -1115,6 +1116,18 @@ function ensure_claude_bridge(project_root: string, force: boolean): Record<stri
     return merge_json_file(target, bridge, force || healed.length > 0, '.claude/settings.json');
 }
 
+// `.mcp.json` registration + the skill-tier projection lever live in
+// `_lib/mcp_bridge.ts`; only the call sites are here (see that module's header
+// for why). Names are forwarded so the export surface is unchanged.
+const ensure_mcp_bridge = mcp_bridge.makeEnsureMcpBridge(merge_json_file);
+const _resolve_tier_b = mcp_bridge.resolveTierB;
+const _tier_b_advisory = mcp_bridge.tierBAdvisory;
+const _prune_tier_b_modules = (
+    dr: Record<string, DeployResult>,
+    tier_b: ReadonlySet<string>,
+): [number, Record<string, DeployResult>] =>
+    _prune_modules_by(dr, mcp_bridge.tierBPrunePredicate(tier_b));
+
 const CURSOR_DISPATCHER_BINDINGS: ReadonlyArray<readonly [string, string]> = [
     ['session_start', 'sessionStart'],
     ['session_end', 'sessionEnd'],
@@ -2472,7 +2485,7 @@ function _file_entry(p: string, kind: string, hash_content: boolean): Record<str
     };
 }
 
-type DeployResult = [number, number, string, string[]];
+type DeployResult = scoped_projection.DeployTuple;
 
 function _files_by_tool_from_deploy(
     deploy_results: Record<string, DeployResult>,
@@ -3397,91 +3410,10 @@ function _verify_deploy_targets(anchor: string, plan: ReadonlyArray<readonly [st
     return missing;
 }
 
-/**
- * Remove skills/commands matching `is_pruned` from a completed deploy.
- *
- * road-to-install-contract-stability Phase 2 Step 2 (generalized in
- * road-to-credible-install Phase 2 to back both the core-only lab prune and
- * the scoped-projection pack prune off the same mechanics). Skills are
- * pruned by whole directory (tier decided by the skill's `SKILL.md`
- * frontmatter); commands by file (own frontmatter). Rules / personas /
- * contexts / templates are core/shared and left intact. Returns
- * `[pruned_count, adjusted_results]` with the pruned paths removed from each
- * tool's `written_paths` so the manifest never records them.
- */
-function _prune_modules_by(
-    deploy_results: Record<string, DeployResult>,
-    is_pruned: (md_path: string) => boolean,
-): [number, Record<string, DeployResult>] {
-    let pruned = 0;
-    const adjusted: Record<string, DeployResult> = {};
-    for (const tool_id of Object.keys(deploy_results)) {
-        const [written, skipped, status, paths] = deploy_results[tool_id] as DeployResult;
-        const pruned_skill_dirs = new Set<string>();
-        for (const p of paths) {
-            const parts = p.split(path.sep);
-            if (parts.includes('skills')) {
-                const i = parts.indexOf('skills');
-                if (i + 1 < parts.length) {
-                    const skill_root = parts.slice(0, i + 2).join(path.sep);
-                    if (!pruned_skill_dirs.has(skill_root)) {
-                        const skillmd = path.join(skill_root, 'SKILL.md');
-                        if (pathExists(skillmd) && is_pruned(skillmd)) {
-                            pruned_skill_dirs.add(skill_root);
-                        }
-                    }
-                }
-            }
-        }
-        const keep: string[] = [];
-        const delete_files: string[] = [];
-        for (const p of paths) {
-            const parts = p.split(path.sep);
-            let is_target = false;
-            if (parts.includes('skills')) {
-                const i = parts.indexOf('skills');
-                if (i + 1 < parts.length && pruned_skill_dirs.has(parts.slice(0, i + 2).join(path.sep))) {
-                    is_target = true;
-                }
-            } else if (
-                parts.includes('commands') &&
-                path.extname(p) === '.md' &&
-                is_pruned(p)
-            ) {
-                is_target = true;
-            }
-            (is_target ? delete_files : keep).push(p);
-        }
-        for (const d of pruned_skill_dirs) {
-            fs.rmSync(d, { recursive: true, force: true });
-        }
-        for (const p of delete_files) {
-            if (p.split(path.sep).includes('commands') && pathExists(p)) {
-                try {
-                    fs.unlinkSync(p);
-                } catch {
-                    // OSError → swallow, mirroring the .py.
-                }
-            }
-        }
-        pruned += delete_files.length;
-        adjusted[tool_id] = [Math.max(0, written - delete_files.length), skipped, status, keep];
-    }
-    return [pruned, adjusted];
-}
-
-/**
- * Remove lab-tier skills/commands from a completed deploy (core-only).
- *
- * road-to-install-contract-stability Phase 2 Step 2. Thin wrapper over
- * `_prune_modules_by` — see that function for the mechanics.
- */
-function _prune_lab_modules(
-    deploy_results: Record<string, DeployResult>,
-    lab_ids: Set<string>,
-): [number, Record<string, DeployResult>] {
-    return _prune_modules_by(deploy_results, (p) => surface_tiers.is_lab_artefact(p, lab_ids));
-}
+// The prune mechanics moved WHOLE into `_lib/scoped_projection.ts` beside the
+// predicate they consume — a pure move, names forwarded, no behaviour change.
+const _prune_modules_by = scoped_projection.prune_modules_by;
+const _prune_lab_modules = scoped_projection.prune_lab_modules;
 
 // --- Scoped-projection prune (road-to-credible-install Phase 2) ----------
 //
@@ -3549,10 +3481,10 @@ function _resolve_global_settings_path(): string | null {
  */
 function _resolve_scoped_projection(
     package_root: string,
-): { mode: 'scoped' | 'legacy-all'; active_packs: string[] } {
+): { mode: mcp_bridge.ProjectionMode; active_packs: string[] } {
     const doc = _resolve_global_settings_doc() ?? _load_default_settings(package_root);
     const projection = _isPlainObject(doc['projection']) ? (doc['projection'] as Record<string, unknown>) : {};
-    const mode: 'scoped' | 'legacy-all' = projection['mode'] === 'scoped' ? 'scoped' : 'legacy-all';
+    const mode = mcp_bridge.projectionModeOf(projection['mode']);
     const runtime = _isPlainObject(doc['runtime']) ? (doc['runtime'] as Record<string, unknown>) : {};
     const active_packs_raw = runtime['active_packs'];
     const active_packs = Array.isArray(active_packs_raw)
@@ -3782,6 +3714,13 @@ function install_global(
     // here and restores the full tree — never a partial or crashed prune.
     try {
         const { mode, active_packs } = _resolve_scoped_projection(package_root);
+        if (mode === 'tiered') {
+            const outcome = mcp_bridge.applyTieredPrune(deploy_results, package_root, _prune_modules_by);
+            deploy_results = outcome.deployResults;
+            if (!state.QUIET && outcome.message !== null) {
+                (outcome.level === 'warn' ? warn : info)(outcome.message);
+            }
+        }
         if (mode === 'scoped') {
             const packs_registry = _load_packs_registry(package_root);
             const active_ids = _compute_active_pack_ids(packs_registry, active_packs);
@@ -5225,7 +5164,10 @@ function _main_project_install(
             ...ensure_augment_bridge(project_root, opts.force),
         ];
         if (_is_tool_enabled(tools, 'claude-code')) {
-            merged_keys_by_tool['claude-code'] = ensure_claude_bridge(project_root, opts.force);
+            merged_keys_by_tool['claude-code'] = [
+                ...ensure_claude_bridge(project_root, opts.force),
+                ...ensure_mcp_bridge(project_root, opts.force),
+            ];
         }
         if (_is_tool_enabled(tools, 'cursor')) {
             merged_keys_by_tool['cursor'] = ensure_cursor_bridge(project_root, opts.force);
@@ -5249,6 +5191,11 @@ function _main_project_install(
         if (_is_tool_enabled(tools, 'kiro')) ensure_kiro_bridge(project_root, opts.force);
     }
 
+    const tier_advisory = _tier_b_advisory(package_root);
+    if (tier_advisory !== null && !state.QUIET) {
+        info(tier_advisory);
+    }
+
     if (opts.augment_user_hooks) {
         (merged_keys_by_tool['augment'] ??= []).push(...ensure_augment_user_hooks(package_root, opts.force));
     }
@@ -5441,6 +5388,10 @@ export {
     GEMINI_DISPATCHER_BINDINGS,
     ensure_cursor_bridge,
     ensure_cline_bridge,
+    ensure_mcp_bridge,
+    _prune_tier_b_modules,
+    _resolve_tier_b,
+    _tier_b_advisory,
     ensure_windsurf_bridge,
     ensure_gemini_bridge,
     // road-to-credible-install Phase 2: exported for the scoped-projection