@event4u/agent-config 9.11.0 → 9.13.0

package/src/scripts/hooks/block_kernel_rule_writes.ts

@@ -40,6 +40,7 @@ import * as path from 'node:path';
 
 import { is_kernel_rule } from '../_lib/kernel_rules.js';
 import { EDIT_TOOLS } from '../minimal_safe_diff_hook.js';
+import { COMMAND_TOOLS } from '../verify_before_complete_hook.js';
 import { readHookStdin } from './hook_stdin.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -122,25 +123,159 @@ export function targets_kernel_rule(filePath: string): string | null {
     return basename.replace(/\.md$/, '');
 }
 
-/** Return (blocked, reason) for one PreToolUse envelope. Pure — no I/O beyond the arg. */
+/** In-place mutators that name their target as a plain argument. */
+const _MUTATOR_VERBS: ReadonlySet<string> = new Set([
+    'sed',
+    'tee',
+    'truncate',
+    'rm',
+    'shred',
+]);
+/** Verbs whose LAST positional argument is the destination. */
+const _DEST_LAST_VERBS: ReadonlySet<string> = new Set(['mv', 'cp', 'install', 'rsync']);
+
+/**
+ * Shell tokens that, in a command naming a kernel rule path, mean the path is
+ * being WRITTEN rather than read. Reads (`cat`, `grep`, `head`, `diff`,
+ * `git show`) carry none of these and stay allowed — a kernel rule is
+ * immutable, not secret.
+ */
+function _bash_targets_kernel_rule(command: string): string | null {
+    // Cheap reject first: no kernel-rule path in the string at all.
+    const tokens = command.split(/\s+/).filter((t) => t.length > 0);
+    const stripped = tokens.map((t) => t.replace(/^['"]|['"]$/g, ''));
+    const ruleOf = (t: string): string | null => targets_kernel_rule(t);
+    if (!stripped.some((t) => ruleOf(t) !== null)) {
+        return null;
+    }
+
+    // 1. Redirection into the path: `> p`, `>> p`, `>p`, `>>p`.
+    for (let i = 0; i < stripped.length; i += 1) {
+        const tok = stripped[i] as string;
+        const inline = /^>{1,2}(.+)$/.exec(tok);
+        if (inline) {
+            const r = ruleOf(inline[1] as string);
+            if (r !== null) {
+                return r;
+            }
+        }
+        if (tok === '>' || tok === '>>') {
+            const next = stripped[i + 1];
+            if (typeof next === 'string') {
+                const r = ruleOf(next);
+                if (r !== null) {
+                    return r;
+                }
+            }
+        }
+    }
+
+    // 2. A mutator verb anywhere in the pipeline, with the path as an argument.
+    //    `sed` only counts in its in-place form — `sed 's/x/y/' file` prints.
+    const verbs = new Set<string>();
+    let prevWasSeparator = true;
+    for (const tok of stripped) {
+        if (['&&', '||', ';', '|'].includes(tok)) {
+            prevWasSeparator = true;
+            continue;
+        }
+        if (prevWasSeparator && !tok.startsWith('-')) {
+            verbs.add(path.basename(tok));
+            prevWasSeparator = false;
+        }
+    }
+    const sedInPlace = verbs.has('sed') && stripped.some((t) => /^-i/.test(t));
+    for (const verb of verbs) {
+        if (verb === 'sed' && !sedInPlace) {
+            continue;
+        }
+        if (_MUTATOR_VERBS.has(verb)) {
+            const hit = stripped.map(ruleOf).find((r) => r !== null);
+            if (hit !== undefined && hit !== null) {
+                return hit;
+            }
+        }
+        if (_DEST_LAST_VERBS.has(verb)) {
+            const last = stripped[stripped.length - 1] as string;
+            const r = ruleOf(last);
+            if (r !== null) {
+                return r;
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * Return (blocked, reason) for one PreToolUse envelope. Pure — no I/O beyond
+ * the arg.
+ *
+ * Two surfaces, one effect. The Write/Edit branch is the original Layer-1
+ * guard. The Bash branch was added by road-to-governance-invariants Phase 1
+ * after the S0.2 spike measured the gap: this gate keyed on the TOOL NAME, so
+ * `Bash sed -i … src/rules/commit-policy.md` reached the immutable-rule
+ * outcome the Write branch refuses, and a two-step
+ * `Write docs/staging/<kernel>.md` → `Bash mv … src/rules/<kernel>.md`
+ * sequence did the same with every step individually allowed.
+ *
+ * The Bash branch is deliberately narrow (2026-08-02 council cut, option ii):
+ * only redirection into the path, an in-place `sed`, a `tee`/`truncate`/`rm`
+ * naming it, or a `mv`/`cp` whose DESTINATION it is. Reads stay allowed — a
+ * kernel rule is immutable, not secret — and no attempt is made to understand
+ * arbitrary shell. Recognising every conceivable write verb would make this a
+ * shell sandbox, which is the failure mode the council named.
+ */
 export function check_envelope(envelope: JsonObject): [boolean, string] {
     const { tool, paths } = _extract(envelope);
-    if (!tool || !EDIT_TOOLS.has(tool)) {
+    if (!tool) {
         return [false, ''];
     }
-    for (const p of paths) {
-        const ruleName = targets_kernel_rule(p);
-        if (ruleName !== null) {
-            return [
-                true,
-                `kernel rule ${ruleName} is immutable — tighten-only via the override ` +
-                    'exception registry; see docs/contracts/kernel-membership.md',
-            ];
+    const deny = (ruleName: string): [boolean, string] => [
+        true,
+        `kernel rule ${ruleName} is immutable — tighten-only via the override ` +
+            'exception registry; see docs/contracts/kernel-membership.md',
+    ];
+    if (EDIT_TOOLS.has(tool)) {
+        for (const p of paths) {
+            const ruleName = targets_kernel_rule(p);
+            if (ruleName !== null) {
+                return deny(ruleName);
+            }
+        }
+        return [false, ''];
+    }
+    if (COMMAND_TOOLS.has(tool)) {
+        const cmd = _extract_command(envelope);
+        if (cmd !== null) {
+            const ruleName = _bash_targets_kernel_rule(cmd);
+            if (ruleName !== null) {
+                return deny(ruleName);
+            }
         }
     }
     return [false, ''];
 }
 
+/** Best-effort read of a shell command off a PreToolUse envelope. */
+function _extract_command(envelope: JsonObject): string | null {
+    const payload = _isObject(envelope['payload']) ? envelope['payload'] : envelope;
+    const ti = _isObject(payload['tool_input'])
+        ? payload['tool_input']
+        : _isObject(envelope['tool_input'])
+          ? envelope['tool_input']
+          : null;
+    for (const src of [ti, payload]) {
+        if (src === null) {
+            continue;
+        }
+        const v = src['command'];
+        if (typeof v === 'string' && v) {
+            return v;
+        }
+    }
+    return null;
+}
+
 function _asObject(v: JsonValue | undefined): JsonObject | null {
     return _isObject(v) ? v : null;
 }

package/src/scripts/hooks/block_no_verify.ts

@@ -33,6 +33,34 @@ const _SHELL_SEPARATORS: ReadonlySet<string> = new Set(['&&', '||', ';', '|']);
 const _NO_VERIFY_FLAGS: ReadonlySet<string> = new Set(['--no-verify']);
 const _NO_VERIFY_SHORT: ReadonlySet<string> = new Set(['-n']);
 const _HOOKS_PATH_RE = /^core\.hooksPath\s*=/i;
+/** Bare key form, as `git config core.hooksPath <value>` spells it. */
+const _HOOKS_PATH_KEY_RE = /^core\.hooksPath$/i;
+/**
+ * `git config` flags that make the invocation a READ or a RESTORE rather than
+ * a write. `--unset` removes the override — the opposite of disabling hooks —
+ * so it stays allowed, or the gate would block its own remediation.
+ */
+/** Global `git` options that consume the following token as their value. */
+const _GIT_GLOBAL_OPTS_WITH_VALUE: ReadonlySet<string> = new Set([
+    '-C',
+    '-c',
+    '--config',
+    '--git-dir',
+    '--work-tree',
+    '--namespace',
+    '--exec-path',
+    '--super-prefix',
+]);
+const _CONFIG_READ_OR_RESTORE: ReadonlySet<string> = new Set([
+    '--get',
+    '--get-all',
+    '--get-regexp',
+    '--get-urlmatch',
+    '--list',
+    '-l',
+    '--unset',
+    '--unset-all',
+]);
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };
@@ -178,7 +206,80 @@ function _git_base(tokens: string[]): string[] | null {
     return null;
 }
 
+/**
+ * `git config … core.hooksPath <value>` — the subcommand form of the hooksPath
+ * override, distinct from the `-c` / `--config` global-option form handled in
+ * `_is_blocked`.
+ *
+ * Closed by road-to-governance-invariants Phase 1 after the S0.2 spike measured
+ * it: `git-history-discipline` already claimed `core.hooksPath` overrides were
+ * "deterministically blocked", and only the inline `-c` form was. That made
+ * `git config core.hooksPath /dev/null` → `git commit` a two-step sequence
+ * whose every step this gate allowed and whose composition is exactly the
+ * outcome the gate exists to prevent.
+ *
+ * Deliberately narrow, per the 2026-08-02 council cut (option ii — widen only
+ * the exact shapes with no plausible legitimate use):
+ *   - a READ (`--get`, `--list`, or the key with no value) is allowed;
+ *   - `--unset` is allowed — it restores hooks, it does not disable them;
+ *   - non-git ways of disabling a hook (`mv`/`chmod`/`rm` on `.git/hooks/*`)
+ *     are NOT matched here. Recognising them would turn this guard into a
+ *     shell sandbox and those verbs have ordinary legitimate uses. That gap
+ *     is published rather than papered over — see the S0.2 spike.
+ */
+function _is_config_hookspath_write(git_tokens: string[]): [boolean, string] {
+    const rest = git_tokens.slice(1);
+    // The subcommand is the first token that is neither a global option nor
+    // the VALUE of one — `git -C /repo config …` must still resolve to
+    // `config`, not to `/repo`.
+    let subIdx = -1;
+    for (let k = 0; k < rest.length; k += 1) {
+        const tok = rest[k] as string;
+        if (!tok.startsWith('-')) {
+            subIdx = k;
+            break;
+        }
+        if (_GIT_GLOBAL_OPTS_WITH_VALUE.has(tok)) {
+            k += 1; // consume its value
+        }
+    }
+    if (subIdx === -1 || rest[subIdx] !== 'config') {
+        return [false, ''];
+    }
+    const args = rest.slice(subIdx + 1);
+    if (args.some((t) => _CONFIG_READ_OR_RESTORE.has(t))) {
+        return [false, ''];
+    }
+    for (let k = 0; k < args.length; k += 1) {
+        const tok = args[k] as string;
+        // `core.hooksPath=<value>` — one token, always a write.
+        if (_HOOKS_PATH_RE.test(tok)) {
+            return [
+                true,
+                `'git config ${tok}' disables git hooks via hooksPath (git-history-discipline)`,
+            ];
+        }
+        if (!_HOOKS_PATH_KEY_RE.test(tok)) {
+            continue;
+        }
+        // Bare key: a write only when a value follows.
+        const next = args.slice(k + 1).find((t) => !t.startsWith('-'));
+        if (next !== undefined) {
+            return [
+                true,
+                `'git config ${tok} ${next}' disables git hooks via hooksPath (git-history-discipline)`,
+            ];
+        }
+        return [false, ''];
+    }
+    return [false, ''];
+}
+
 function _is_blocked(git_tokens: string[]): [boolean, string] {
+    const [cfgBlocked, cfgReason] = _is_config_hookspath_write(git_tokens);
+    if (cfgBlocked) {
+        return [cfgBlocked, cfgReason];
+    }
     let i = 1; // skip 'git'
     while (i < git_tokens.length) {
         const tok = git_tokens[i] as string;

package/src/scripts/install-hooks.sh

@@ -51,6 +51,27 @@ else
     fi
 fi
 
+# road-to-local-ci-trust Phase 2: the CI-only repo-content gates, as one task.
+# Deliberately placed AFTER the consistency block above — `task consistency`
+# runs `task sync`, which generates the `.augment/` projection. Several
+# preflight gates read that tree, so on a FRESH worktree (this repo's standard
+# workflow) running preflight first would fail with "produced by regeneration
+# but absent before" — red for a reason the contributor did not cause, which is
+# exactly the anti-pattern this gate set exists to avoid. Measured 15s against
+# the 25s `pre_push_budget_seconds` ceiling in src/config/ci-local-parity.yml.
+# `check_enforcement_coverage` (30.7s) stays out of preflight by design.
+echo "🔍 Preflight — the CI-only repo-content gates..."
+if [ "${AGENT_CONFIG_SKIP_PREPUSH_PREFLIGHT:-}" = "1" ]; then
+    echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_PREFLIGHT=1"
+elif ! command -v task >/dev/null 2>&1; then
+    echo "⚠️  'task' not found — skipping preflight for this push."
+elif ! task preflight; then
+    echo "❌  Preflight failed. These gates run in CI too, so pushing now buys a"
+    echo "    red run and a fixup re-push. Fix the failures above, or"
+    echo "    AGENT_CONFIG_SKIP_PREPUSH_PREFLIGHT=1 for a genuine WIP push."
+    exit 1
+fi
+
 echo "🔍 Checking for leftover conflict markers / unmerged paths..."
 if ! ./scripts-run src/scripts/check_no_conflict_markers --quiet; then
     echo "❌  Conflict markers or unmerged paths present. Resolve them (e.g. 'git checkout HEAD -- <file>' or finish the merge), then re-push."
@@ -127,11 +148,22 @@ if git diff --cached --name-only | grep -qE '^agents/roadmaps(-progress\.md|/)';
     ./scripts-run .augment/scripts/update_roadmap_progress --check
     rstatus=$?
     if [ $rstatus -ne 0 ]; then
+        # The check fails for THREE distinct reasons and prints the real one
+        # above: a stale dashboard, an unresolved `[~]` deferred item (Iron
+        # Law 3), or a completed-but-unarchived roadmap. Naming only the first
+        # sent a maintainer chasing a regeneration that was already correct —
+        # and a safety gate whose text points at the wrong cause trains people
+        # to distrust the gate, which costs more than the wrong message.
         echo ""
-        echo "❌  Commit blocked — agents/roadmaps-progress.md is stale."
-        echo "   Run './agent-config roadmap:progress' (or"
-        echo "   './scripts-run .augment/scripts/update_roadmap_progress'),"
-        echo "   stage agents/roadmaps-progress.md, then re-commit."
+        echo "❌  Commit blocked — the roadmap dashboard gate failed."
+        echo "   The cause is printed above. The three it reports:"
+        echo "     · dashboard stale      → './agent-config roadmap:progress',"
+        echo "                               then stage agents/roadmaps-progress.md"
+        echo "     · Iron Law 3           → unresolved '[~]' deferred items. Surface"
+        echo "                               them and ask the user; NOT the agent's"
+        echo "                               to clear (roadmap-management § 4b)"
+        echo "     · completed roadmap    → 'git mv' it into agents/roadmaps/archive/,"
+        echo "                               then regenerate"
         echo "   To bypass for an unrelated WIP commit: git commit --no-verify"
         exit 1
     fi

package/src/scripts/install.ts

@@ -82,6 +82,13 @@ import * as user_global_paths from './_lib/user_global_paths.js';
 import * as claude_desktop_bundler from './_lib/claude_desktop_bundler.js';
 import * as claude_settings_hooks from './_lib/claude_settings_hooks.js';
 import { find_project_root_with_anchor, load_agent_settings } from './_lib/agent_settings.js';
+import {
+    LEGACY_ALL,
+    ruleFileArrives,
+    ruleScopeFromSettings,
+    type RuleScope,
+} from '../install/rule_scope.js';
+import { RULE_SOURCE_REL } from '../install/wizard-plan.js';
 import { flattenSurface, computeSurfaceDelta, type SettingsSurface } from '../shared/settingsSurface.js';
 import { settingsSchema } from '../server/schemas/settings.js';
 import { zodToJsonSchema } from 'zod-to-json-schema';
@@ -2730,17 +2737,71 @@ function _inject_package_tag(
     }
 }
 
+/**
+ * Would dereferencing `entry` escape the package root?
+ *
+ * `_copy_dir_dereferencing_symlinks` copies the REALPATH of every entry, so a
+ * symlink in the shipped tree pointing outside the package would copy an
+ * arbitrary readable file into the deploy destination — and those destinations
+ * are agent-readable instruction dirs (`~/.claude/rules/`, `~/.codeium/…`). A
+ * tampered tarball carrying `rules/x.md -> ~/.ssh/id_rsa` would land that file
+ * where an agent reads rules.
+ *
+ * Defence-in-depth for `docs/threat-model.md` row b (supply-chain compromise):
+ * the package is the install-time trust anchor, so this is not the primary
+ * control — but the check is one comparison and `package_root` was already
+ * threaded through, so there is no reason to ship without it.
+ *
+ * Both sides are realpath'd before comparing, so a macOS `/var` → `/private/var`
+ * root does not read as an escape. A `null` package_root means the caller did
+ * not scope the copy (several do) — unchanged, permissive behaviour there.
+ */
+function _escapes_package_root(resolved: string, package_root: string | null): boolean {
+    if (package_root === null) return false;
+    let root: string;
+    try {
+        root = fs.realpathSync(package_root);
+    } catch {
+        // Unresolvable root — cannot judge containment, so do not block the copy.
+        return false;
+    }
+    return !global_deploy_inventory.is_ancestor(root, resolved);
+}
+
+/**
+ * Copy `src` → `dest`, dereferencing symlinks, returning
+ * `[written, skipped, written_paths]`.
+ *
+ * `file_filter` is an optional predicate over the SOURCE path; `false` means the
+ * file is not part of this install and is neither copied nor counted. It MUST be
+ * the same predicate handed to `global_deploy_inventory.expected_deploy_files`
+ * for the same source — that function computes what the reaper considers
+ * "should exist", so filtering one side only either leaves excluded files behind
+ * forever or deletes files the copy just wrote.
+ */
 function _copy_dir_dereferencing_symlinks(
     src: string,
     dest: string,
     force: boolean,
     package_root: string | null = null,
+    file_filter: global_deploy_inventory.FileFilter | null = null,
 ): [number, number, string[]] {
     let written = 0;
     let skipped = 0;
     const written_paths: string[] = [];
     if (!pathExists(src)) return [0, 0, written_paths];
     if (!isDir(src)) {
+        if (file_filter !== null && !file_filter(src)) return [0, 0, written_paths];
+        let resolved_src = src;
+        try {
+            resolved_src = fs.realpathSync(src);
+        } catch {
+            resolved_src = src;
+        }
+        if (_escapes_package_root(resolved_src, package_root)) {
+            warn(`refused: ${src} dereferences outside the package root — not copied`);
+            return [0, 0, written_paths];
+        }
         mkdirp(path.dirname(dest));
         const decision = _resolve_file_conflict(dest, force);
         if (decision === 'skip') return [0, 1, written_paths];
@@ -2784,6 +2845,13 @@ function _copy_dir_dereferencing_symlinks(
         } catch {
             resolvedIsDir = false;
         }
+        // Containment is checked on the RESOLVED path, before either the
+        // recursion or the copy — a symlinked directory escaping the root would
+        // otherwise pull its whole subtree in.
+        if (_escapes_package_root(resolved, package_root)) {
+            warn(`refused: ${entry} dereferences outside the package root — not copied`);
+            continue;
+        }
         if (resolvedIsDir) {
             mkdirp(target);
             const [sub_w, sub_s, sub_p] = _copy_dir_dereferencing_symlinks(
@@ -2791,12 +2859,20 @@ function _copy_dir_dereferencing_symlinks(
                 target,
                 force,
                 package_root,
+                file_filter,
             );
             written += sub_w;
             skipped += sub_s;
             written_paths.push(...sub_p);
             continue;
         }
+        // The predicate sees the SOURCE path (the rule-scope predicate reads the
+        // file's own frontmatter tags). Skipped files are counted as neither
+        // written nor skipped-as-identical: they are not part of this install,
+        // so the inventory twin must omit them too or the reaper drifts.
+        if (file_filter !== null && !file_filter(entry)) {
+            continue;
+        }
         const decision = _resolve_file_conflict(target, force);
         if (decision === 'skip') {
             skipped += 1;
@@ -2949,6 +3025,10 @@ function _deploy_global_content(
     lockfile_path: string,
 ): Record<string, DeployResult> {
     const results: Record<string, DeployResult> = {};
+    // Resolved ONCE per deploy, not per tool: every tool installs the same rule
+    // tree, and re-reading settings per tool could yield different answers
+    // mid-run if the file changed underneath.
+    const rule_scope = _resolve_global_rule_scope(package_root);
     for (const tool_id of [...tools].sort()) {
         if (tool_id === 'claude-desktop') {
             results[tool_id] = _deploy_claude_desktop(force, package_root, lockfile_path);
@@ -2975,13 +3055,30 @@ function _deploy_global_content(
         for (const [src_rel, dest_sub] of plan) {
             const src = path.join(package_root, src_rel);
             const dest = dest_sub ? path.join(anchor, dest_sub) : anchor;
-            const [w, s, paths] = _copy_dir_dereferencing_symlinks(src, dest, force, package_root);
+            // ONE filter instance, handed to BOTH the copy and the inventory.
+            // `expected_deploy_files` is what the reaper treats as "should
+            // exist": filtering only the copy would leave previously-installed
+            // maintainer rules on disk forever, and filtering only the
+            // inventory would delete rules the copy just wrote. Both, or
+            // neither — never one.
+            const rule_filter = _rule_filter_for_source(src_rel, rule_scope);
+            const [w, s, paths] = _copy_dir_dereferencing_symlinks(
+                src,
+                dest,
+                force,
+                package_root,
+                rule_filter,
+            );
             written_total += w;
             skipped_total += s;
             written_paths.push(...paths);
             current_files = setUnion(
                 current_files,
-                global_deploy_inventory.expected_deploy_files(src, dest_sub ? dest_sub : ''),
+                global_deploy_inventory.expected_deploy_files(
+                    src,
+                    dest_sub ? dest_sub : '',
+                    rule_filter,
+                ),
             );
         }
         // Flat-command → skill-wrapper re-projection for Claude Code
@@ -3091,6 +3188,9 @@ function _preview_global_reap(
 ): Record<string, string[]> {
     const inventory = global_deploy_inventory.load_inventory();
     const preview: Record<string, string[]> = {};
+    // The preview must compute the SAME expected set the real deploy will, or
+    // `--dry-run` under-reports the rules a scoped upgrade is about to reap.
+    const rule_scope = _resolve_global_rule_scope(package_root);
     for (const tool_id of [...tools].sort()) {
         const plan = GLOBAL_DEPLOY_SOURCES[tool_id];
         if (plan === undefined) continue;
@@ -3102,7 +3202,11 @@ function _preview_global_reap(
             const src = path.join(package_root, src_rel);
             current_files = setUnion(
                 current_files,
-                global_deploy_inventory.expected_deploy_files(src, dest_sub ? dest_sub : ''),
+                global_deploy_inventory.expected_deploy_files(
+                    src,
+                    dest_sub ? dest_sub : '',
+                    _rule_filter_for_source(src_rel, rule_scope),
+                ),
             );
         }
         let would_reap: string[] = [];
@@ -3334,11 +3438,25 @@ function _compute_active_pack_ids(
  * artefact of any kind.
  */
 function _resolve_global_settings_doc(): Record<string, unknown> | null {
+    const p = _resolve_global_settings_path();
+    return p === null ? null : _load_yaml_doc(p);
+}
+
+/**
+ * The path `_resolve_global_settings_doc` would read, or `null` when no global
+ * settings artefact exists at all.
+ *
+ * Split out because "absent" and "present but unparseable" are different facts
+ * and one caller must tell them apart: `_load_yaml_doc` maps BOTH to `{}`, which
+ * silently turns a YAML typo into legacy-all rule scoping — defeating a scoping
+ * decision the user made, with no signal. See `_resolve_global_rule_scope`.
+ */
+function _resolve_global_settings_path(): string | null {
     const root = user_global_paths.event4u_root();
     const canonical = path.join(root, 'settings', SETTINGS_FILE);
-    if (pathExists(canonical)) return _load_yaml_doc(canonical);
+    if (pathExists(canonical)) return canonical;
     const legacy = path.join(root, SETTINGS_FILE);
-    if (pathExists(legacy)) return _load_yaml_doc(legacy);
+    if (pathExists(legacy)) return legacy;
     return null;
 }
 
@@ -3369,6 +3487,84 @@ function _resolve_scoped_projection(
     return { mode, active_packs };
 }
 
+/**
+ * Resolve the rule scope governing THIS global deploy — the same way the wizard
+ * does (`src/server/routes/install.ts::_resolveRuleScope`), so the two global
+ * paths cannot ship different rule sets for the same settings.
+ *
+ * Settings resolution mirrors `_resolve_scoped_projection` above: an existing
+ * global settings doc is authoritative, and only a genuinely fresh machine falls
+ * through to the packaged template. Any read or parse failure resolves to
+ * `LEGACY_ALL` — over-shipping is the safe direction, and the compat exclusion
+ * (`source-of-truth.md`) still applies even then.
+ */
+function _resolve_global_rule_scope(package_root: string): RuleScope {
+    const settings_path = _resolve_global_settings_path();
+
+    // No global settings artefact at all — a genuinely fresh machine. Fall
+    // through to the packaged template silently: there is no user decision to
+    // contradict, and this is the documented upgrade-compat path.
+    if (settings_path === null) {
+        try {
+            return ruleScopeFromSettings(_load_default_settings(package_root));
+        } catch {
+            return LEGACY_ALL;
+        }
+    }
+
+    // A doc EXISTS, so the user has expressed a configuration. Failing to read
+    // it is not the same as not having one: falling back to legacy-all here
+    // ships the maintainer-only rules the user may have deliberately scoped out,
+    // and `_load_yaml_doc` would report that as an indistinguishable `{}`. So
+    // parse it explicitly and be LOUD when it does not parse — over-shipping
+    // stays the safe direction, but it must not be a silent one.
+    let text: string;
+    try {
+        text = readText(settings_path);
+    } catch (e) {
+        warn(
+            `could not read ${settings_path} (${String(e)}) — rule scoping falls back ` +
+                'to legacy-all, so ALL rules including maintainer-only ones will be ' +
+                'installed. Fix the file to restore scoping.',
+        );
+        return LEGACY_ALL;
+    }
+    const parsed = yamlSafeLoad(text);
+    if (!_isPlainObject(parsed)) {
+        warn(
+            `${settings_path} is not a YAML mapping — rule scoping falls back to ` +
+                'legacy-all, so ALL rules including maintainer-only ones will be ' +
+                'installed. Fix the file to restore scoping.',
+        );
+        return LEGACY_ALL;
+    }
+    try {
+        return ruleScopeFromSettings(parsed as Record<string, unknown>);
+    } catch (e) {
+        warn(
+            `could not derive rule scope from ${settings_path} (${String(e)}) — ` +
+                'falling back to legacy-all; ALL rules will be installed.',
+        );
+        return LEGACY_ALL;
+    }
+}
+
+/**
+ * The rule-scope filter for one `GLOBAL_DEPLOY_SOURCES` row, or `null` when the
+ * row is not the rules tree.
+ *
+ * Keyed on `src_rel === RULE_SOURCE_REL` exactly as `expandWizardSources` keys
+ * it — the two must agree on WHICH source gets filtered, not only on the
+ * predicate.
+ */
+function _rule_filter_for_source(
+    src_rel: string,
+    scope: RuleScope,
+): global_deploy_inventory.FileFilter | null {
+    if (src_rel !== RULE_SOURCE_REL) return null;
+    return (srcFile: string): boolean => ruleFileArrives(srcFile, scope);
+}
+
 /**
  * Prune every skill/command artefact whose `packs:` frontmatter is
  * non-empty AND has no intersection with `active_ids`. Untagged artefacts
@@ -5035,5 +5231,14 @@ export {
     _compute_active_pack_ids,
     _resolve_global_settings_doc,
     _resolve_scoped_projection,
+    // road-to-consistent-rule-scoping Phase 2: the CLI global deploy path had
+    // no direct test — the existing rule-scoping suite covers the PLAN path
+    // (`expandWizardSources`) only, which is why the two diverged unnoticed.
+    _deploy_global_content,
+    // road-to-local-ci-trust: exported for the symlink-confinement tests
+    // (PR #1076 review-gate finding).
+    _copy_dir_dereferencing_symlinks,
+    _preview_global_reap,
+    _resolve_global_rule_scope,
 };
 export type { Options, PackRecord, DeployResult };