@event4u/agent-config 9.27.0 → 9.28.0

package/src/scripts/_lib/carrier_divergence.ts

@@ -0,0 +1,135 @@
+/**
+ * One definition of "these two carriers deliver the same rule" — shared by the
+ * C-3 reachability harness and the advisory divergence report.
+ *
+ * WHY THIS IS A LIBRARY AND NOT TWO COPIES. Two surfaces need the comparison
+ * and they ask different questions of it. `measure_scope_dedup` asks *how many*
+ * installed twins a byte-identity dedup could skip, anchored on the projection
+ * source. `report_carrier_divergence` asks *which* rules a reader must look at,
+ * anchored on the union of both carriers. The directory walks are legitimately
+ * different; the comparison is not, and a second copy of it is how "differs only
+ * in the ownership stamp" and "differs in body" drift into meaning two things.
+ *
+ * The comparison itself is the load-bearing part, so it is stated once:
+ *
+ *   1. bytes equal                     → `identical`
+ *   2. equal after removing the two
+ *      installer ownership keys        → `provenance-only`
+ *   3. otherwise                       → `body-diff`
+ *
+ * Class 2 exists because `install.ts` stamps `package:` and `source_path:` into
+ * every rule it installs while the in-repo projection stamps nothing, so a
+ * provenance-only difference survives even a perfect version alignment. Keeping
+ * it apart from class 3 is what turns a bare "0 identical twins" into an answer:
+ * `provenanceOnly == shared` means aligning versions would buy nothing, and
+ * `bodyDiff > 0` means the two carriers are delivering different text — the only
+ * class where a reader has to act.
+ *
+ * NOT A LICENCE TO DEDUP. Classifying a pair `provenance-only` says the bodies
+ * match; it does NOT say the rule is safe to drop from one carrier. Byte-identity
+ * remains the dedup predicate, deliberately — see
+ * `agents/settings/contexts/dedup-reachability-refusal.md`, which records that
+ * decision and its five reopen conditions. Nothing here relaxes it.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * The keys `install.ts` adds to every installed rule (`_set_key(fm_lines,
+ * 'package', …)` and `source_path` at install.ts:2733). Removing them is what
+ * separates an installer stamp from a content change.
+ */
+export const OWNERSHIP_KEYS = ['package', 'source_path'] as const;
+
+export type PairVerdict = 'identical' | 'provenance-only' | 'body-diff';
+
+/**
+ * Drop the ownership stamp lines, wherever they appear in the FILE.
+ *
+ * Not scoped to the frontmatter, and the docstring says so because the scope is
+ * wider than the intent. Two reasons it stays this way: `install.ts` writes the
+ * keys without any guarantee about fence position, and `scope_dedup.test.ts`
+ * deliberately pins the fence-less shape (a stamp with no `---` around it) as the
+ * install condition. Residual risk, stated rather than hidden: a rule body that
+ * contains a line literally starting `package:` or `source_path:` — a YAML
+ * example, an indent-free config snippet — has that line removed from both sides,
+ * so a genuine difference confined to such a line would read `provenance-only`
+ * instead of `body-diff`. Measured over the shipped corpus: no rule body carries
+ * one. Re-check that before treating the class as impossible rather than absent.
+ */
+export function stripOwnershipKeys(text: string): string {
+    return text
+        .split('\n')
+        .filter((line) => !OWNERSHIP_KEYS.some((k) => line.startsWith(`${k}:`)))
+        .join('\n');
+}
+
+/**
+ * Compare one rule's two copies.
+ *
+ * Takes buffers rather than paths: the callers already hold them, and a pure
+ * function is what lets both surfaces pin the same three-way split in tests
+ * without a filesystem.
+ */
+export function comparePair(a: Buffer, b: Buffer): PairVerdict {
+    if (a.equals(b)) {
+        return 'identical';
+    }
+    if (stripOwnershipKeys(a.toString('utf-8')) === stripOwnershipKeys(b.toString('utf-8'))) {
+        return 'provenance-only';
+    }
+    return 'body-diff';
+}
+
+export interface RuleDirCensus {
+    files: number;
+    /**
+     * BYTES, not characters — `statSync().size`. The name is kept because every
+     * consumer of this figure (`preamble_byte_census`, `measure_scope_dedup`, the
+     * conformance scan) already divides it by 4 under that name, and one honest
+     * docstring beats a rename that would silently move three published baselines.
+     *
+     * The gap is measured, not assumed: over the 110-rule project tree, 406 502
+     * bytes against 402 823 characters — **0.91 %** overhead from the em-dashes,
+     * arrows and status glyphs the prose uses. So the published token estimate
+     * reads 101 626 where a character basis gives 100 706. Under 1 % and in the
+     * conservative direction for a payload figure, which is why it is documented
+     * rather than repaired; re-measure before quoting it as negligible on a corpus
+     * with more non-ASCII than this one.
+     */
+    chars: number;
+}
+
+/**
+ * How much rule text one carrier delivers.
+ *
+ * `statSync`, not `lstatSync`, on purpose: a project-scope entry is a symlink
+ * into `dist/`, and the bytes the HOST reads are the target's. Measuring the link
+ * would report ~50 bytes per rule and make the whole payload vanish.
+ *
+ * Moved here from `preamble_byte_census` when `conformance_scan` needed it:
+ * that module pulls `yaml` and the cold-start report, and importing a dependency
+ * chain into a bundled CLI path to reach fifteen lines of `statSync` is the wrong
+ * trade. `preamble_byte_census` re-exports this so its own callers are unchanged
+ * and there is still exactly one definition.
+ */
+export function censusRuleDir(dir: string): RuleDirCensus {
+    let files = 0;
+    let chars = 0;
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir);
+    } catch {
+        return { files: 0, chars: 0 };
+    }
+    for (const name of entries) {
+        if (!name.endsWith('.md')) continue;
+        try {
+            chars += fs.statSync(path.join(dir, name)).size;
+            files += 1;
+        } catch {
+            // Unreadable entry — skip rather than fail the whole census.
+        }
+    }
+    return { files, chars };
+}

package/src/scripts/_lib/host_capability.ts

@@ -1,5 +1,5 @@
 /**
- * Host-capability manifest normalizer.
+ * Host-capability manifest normalizer + committed capability registry.
  *
  * Pure, no-I/O helper that takes a partial / unknown object (typically the
  * `subagents.host_capabilities` override from `.agent-settings.yml`, or the
@@ -11,6 +11,18 @@
  *   have no subagent primitive.
  * - A missing or non-boolean field resolves to `false`, never `true`.
  * - `schema_version` is always forced to `1`.
+ *
+ * `resolveHostCapabilities` (F5, road-to-orchestrator-discipline-carriers)
+ * adds a resolution order in front of the safe default so a fresh install on
+ * a KNOWN host does not ship delegation dead by default:
+ *
+ *   explicit `subagents.host_capabilities` override (wins, whole-object,
+ *   unchanged semantics) → committed registry row for the detected host
+ *   (`HOST_CAPABILITY_REGISTRY`) → `SAFE_DEFAULT` (all false).
+ *
+ * The registry lists only OBSERVED capabilities for a host this repo has
+ * actually measured (see the roadmap's transcript evidence) — never a
+ * speculative entry for a host nobody has verified.
  */
 
 /** Resolved host-capability manifest. All booleans, `schema_version` fixed at 1. */
@@ -57,3 +69,74 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
         separate_quota_pool: asBool(src.separate_quota_pool),
     };
 }
+
+/**
+ * Committed registry — known host identifiers → OBSERVED capability sets.
+ *
+ * Keyed by the platform identifier this repo already uses for the same host
+ * across the hook/dispatch layer (`--platform claude`, `platforms['claude']`
+ * in `claude_settings_hooks.ts`, `TOOL_IDS` in `probe_skill_registration.ts`)
+ * — NOT the separate `toolDetection.ts` binary-detection id (`'claude-code'`),
+ * which names a different namespace (installed-CLI presence, not the running
+ * host identity a hook/dispatch envelope carries).
+ *
+ * Each row is partial: an omitted field stays at the `SAFE_DEFAULT` `false`
+ * when the row is applied. Claude Code is the one host this roadmap's
+ * transcript evidence measured spawning and running subagents concurrently
+ * (`Agent` tool dispatch, parallel tool-use blocks); polling and a separate
+ * quota pool were never observed, so they stay `false` — add a field only
+ * once it is itself observed, never by inference.
+ */
+const HOST_CAPABILITY_REGISTRY: Readonly<Record<string, Partial<HostCapabilityManifest>>> = {
+    claude: { subagent_spawn: true, parallel_spawn: true },
+};
+
+/**
+ * Resolve the effective host-capability manifest for `hostId`.
+ *
+ * Resolution order (highest wins), per
+ * `host-capability-manifest.md § Resolution`:
+ *
+ * 1. `override` — the `subagents.host_capabilities` settings value, when
+ *    present as a non-null object. Normalized exactly as {@link normalizeHostManifest}
+ *    always has: a WHOLE-OBJECT override, each field independently coerced,
+ *    a field absent from the override object resolves to `false`. This is
+ *    the pre-existing, unchanged behavior — a present override still wins
+ *    outright over the registry row, it does not merge field-by-field with it.
+ * 2. The committed {@link HOST_CAPABILITY_REGISTRY} row for `hostId`, when no
+ *    override is present and the host is known.
+ * 3. `SAFE_DEFAULT` — unknown `hostId`, or no override and no registry row.
+ *
+ * `hostId` is a caller-supplied identifier (e.g. the same string a hook
+ * envelope's `platform` field carries) — this function does no environment
+ * probing of its own; see `host-capability-manifest.md` for why resolution
+ * stays a per-session, agent/caller-supplied fact rather than a live probe.
+ *
+ * An array override does NOT count as present (F8, review): `typeof [] ===
+ * 'object'` in JS, so a bare `typeof override === 'object'` check let a
+ * stray array reach `normalizeHostManifest`, which reads named properties
+ * off it (`.subagent_spawn`, …) that an array never has — every field
+ * silently coerces to `false`, exactly like an explicit empty-object
+ * override, even though nobody supplied one. An array is not a manifest
+ * shape at all, so it is treated the same as `null`/non-object: fall
+ * through to the registry row.
+ */
+export function resolveHostCapabilities(
+    hostId: string | null | undefined,
+    override?: unknown,
+): HostCapabilityManifest {
+    if (
+        override !== undefined &&
+        override !== null &&
+        typeof override === 'object' &&
+        !Array.isArray(override)
+    ) {
+        return normalizeHostManifest(override);
+    }
+    const row =
+        hostId !== null && hostId !== undefined ? HOST_CAPABILITY_REGISTRY[hostId] : undefined;
+    if (row === undefined) {
+        return { ...SAFE_DEFAULT };
+    }
+    return { ...SAFE_DEFAULT, ...row, schema_version: 1 };
+}

package/src/scripts/_lib/prompt_shape.ts

@@ -0,0 +1,88 @@
+/**
+ * What a "prompt" actually is — shared by the language hook and the conformance
+ * scanner so the two cannot classify the same entry differently.
+ *
+ * They did. Round 6 measured it: `isSyntheticPrompt` lived in
+ * `language_mirror_hook` and was never referenced from `conformance_scan`, whose
+ * only general net was `length > 2500 && english`. So the hook skipped
+ * harness-generated turns and the scanner counted them, and every era split
+ * argued about two different populations without knowing it.
+ *
+ * The asymmetry ran the other way too, and that half had no net on either side:
+ * a prompt whose bulk is pasted content in another language pinned to the paste.
+ * That fired on the very session that received the round-6 review — the pin read
+ * English because an English draft was pasted below German prose.
+ *
+ * Nothing here is language-specific. A rule that names a language cannot answer
+ * a bidirectional question.
+ */
+
+/**
+ * Is this "prompt" a harness-generated turn rather than something a human typed?
+ *
+ * MEASURED, IN THE LANGUAGE HOOK'S OWN AUDIT (round 5, 2026-08-07). The state
+ * file read mid-session:
+ *
+ *   { "language": "en", "source": "prompt", "prompt_chars": 6627,
+ *     "de_markers": 0, "en_markers": 63 }
+ *
+ * No human wrote those 6,627 characters. They were a background-task completion
+ * notification, injected as a user turn, which `user_prompt_submit` sees and the
+ * hook classified as the trigger — flipping a German session to `en` for every
+ * later turn, and recording `source: "prompt"`, a false provenance claim.
+ *
+ * The markers are structural, not linguistic: the harness stamps these turns
+ * with fixed envelope tags. Matching prose would misfire on a human quoting a
+ * notification; matching the tags cannot, because a human typing
+ * `<task-notification>` is quoting, and a quote does not open at character zero.
+ *
+ * Deliberately conservative: an unrecognised synthetic shape falls through and
+ * is treated as a chat message. Under-filtering keeps prior behaviour;
+ * over-filtering would silently stop pinning real prompts, which is worse.
+ * Measured across 1 540 user-role entries: 509 open at character zero with a
+ * marker, and in 0 of them does human text survive wrapper removal.
+ */
+export function isSyntheticPrompt(prompt: string): boolean {
+  const head = prompt.trimStart().slice(0, 400);
+  return (
+    head.startsWith("[SYSTEM NOTIFICATION - NOT USER INPUT]") ||
+    head.startsWith("<task-notification>") ||
+    head.startsWith("<system-reminder>") ||
+    head.startsWith("<local-command-caveat>") ||
+    /^\[SYSTEM NOTIFICATION\b/.test(head)
+  );
+}
+
+/**
+ * A line that starts pasted DOCUMENT content rather than typed instruction.
+ *
+ * Distinct from the output-shaped heads `instructionText` already removes (stack
+ * traces, diffs, `remote:` lines). Those look like machine output. This catches
+ * the other paste shape, which looks like prose: a roadmap, a review, a spec —
+ * pasted whole, under its own headings, below one typed sentence.
+ *
+ * The markers are structural for the same reason as above: a heading, a
+ * frontmatter fence, or a bare tag line is document furniture. A typed chat turn
+ * rarely carries one; a pasted document essentially always does.
+ */
+const DOCUMENT_HEAD = /^\s*(#{1,6}\s|-{3,}\s*$|={3,}\s*$|<[A-Za-z][\w-]*>\s*$)/;
+
+/**
+ * The part of a prompt a human plausibly typed: everything before the first
+ * pasted document begins.
+ *
+ * Callers pass text that has already had output-shaped pastes removed. Returning
+ * the LEAD rather than a filtered whole is deliberate — a paste can be
+ * interleaved, and reassembling the human fragments would invent a text nobody
+ * wrote. The lead is the one span whose authorship is not in question.
+ */
+export function humanAuthoredLead(text: string): string {
+  const kept: string[] = [];
+  for (const line of text.split("\n")) {
+    if (DOCUMENT_HEAD.test(line)) {
+      break;
+    }
+    kept.push(line);
+  }
+  return kept.join("\n");
+}

package/src/scripts/_lib/review_skipped_record.ts

@@ -0,0 +1,102 @@
+/**
+ * `review_skipped` telemetry line builder (pure, no I/O).
+ *
+ * Purpose-built, MINIMAL extension of the audit-log-v1 envelope
+ * (`docs/contracts/audit-log-v1.md`) for the F4-lite end-review-nudge concern
+ * (road-to-orchestrator-discipline-carriers Phase 5). It reuses the same
+ * envelope shape and the same file location
+ * (`agents/runtime/state/audit/<YYYY-MM>.jsonl`) as
+ * `_lib/orchestration_record.ts`'s `orchestration` object, but does not
+ * import that module: `buildOrchestrationLine` requires `spawn_count`, which
+ * has no meaning for a review-skip event, and its enum-constant tables are
+ * private to that file. Adding a second additive top-level object
+ * (`review_skipped`) is exactly the pattern the contract already uses for
+ * `orchestration` — "Unknown trailing fields are forward-compat extensions;
+ * readers MUST NOT raise on them."
+ *
+ * PRIVACY BY CONSTRUCTION: the `review_skipped` object carries `diff_lines`
+ * (a non-negative integer count) and `mutation_measure` (a closed 2-value
+ * enum — never free text). There is no field capable of holding a file
+ * path, a prompt, or any free-form content — never add one (mirrors
+ * `domain-safety-pii` § Surface 2 / the `artifact-engagement` event shape).
+ */
+
+/**
+ * Whether `diff_lines` is an exact sum or a guaranteed-over-threshold
+ * approximation (`end_review_nudge_hook.ts`'s `UNTRACKED_FILE_CAP` path —
+ * past that many untracked non-doc files, the hook refuses to spawn one
+ * `git diff --no-index` subprocess per file and reports a value merely
+ * guaranteed to exceed the fire threshold, not an exact count). Mixing
+ * exact and approximated counts in this telemetry stream, unlabeled, would
+ * corrupt any future blocking-threshold calibration that reads it — hence
+ * this field, rather than folding the approximation silently into
+ * `diff_lines`.
+ */
+export type MutationMeasure = 'exact' | 'capped_approximation';
+
+export interface ReviewSkippedInput {
+    /** Non-doc tracked-file mutation size that triggered the nudge (count only). */
+    diff_lines: number;
+    /** Whether `diff_lines` is exact or a capped approximation — see above. */
+    mutation_measure: MutationMeasure;
+    /** ISO-8601 UTC timestamp; caller supplies (keeps this fn pure/deterministic). */
+    ts: string;
+    /** Stable id (ULID, UUID, or content hash); caller supplies. */
+    id: string;
+    work_id?: string | undefined;
+}
+
+export interface BuiltReviewSkippedLine {
+    line: Record<string, unknown> | null;
+    errors: string[];
+}
+
+function isNonNegInt(n: unknown): n is number {
+    return typeof n === 'number' && Number.isFinite(n) && Number.isInteger(n) && n >= 0;
+}
+
+/**
+ * High-risk threshold for the line's own `risk_class` (audit-log-v1 field,
+ * not the hook's fire threshold): a skipped review over a large diff carries
+ * more residual risk than one just past the fire threshold.
+ */
+const HIGH_RISK_DIFF_LINES = 200;
+
+/**
+ * Build + validate ONE audit-log-v1 line carrying a `review_skipped` object.
+ * Returns `{line, errors}`; when `errors` is non-empty, `line` is null and
+ * the caller must NOT write.
+ */
+export function buildReviewSkippedLine(input: ReviewSkippedInput): BuiltReviewSkippedLine {
+    const errors: string[] = [];
+    if (!isNonNegInt(input.diff_lines)) {
+        errors.push('diff_lines must be a non-negative integer');
+    }
+    if (input.mutation_measure !== 'exact' && input.mutation_measure !== 'capped_approximation') {
+        errors.push('mutation_measure must be "exact" or "capped_approximation"');
+    }
+    if (!input.ts) errors.push('ts (ISO-8601 UTC) is required');
+    if (!input.id) errors.push('id (ULID, UUID, or content hash) is required');
+
+    if (errors.length) return { line: null, errors };
+
+    const line: Record<string, unknown> = {
+        schema_version: 1,
+        id: input.id,
+        ts: input.ts,
+        work_id: input.work_id ?? `review-skipped-${input.ts}`,
+        phase: 'report',
+        outcome: 'skipped',
+        confidence_band: 'medium',
+        risk_class: input.diff_lines >= HIGH_RISK_DIFF_LINES ? 'high' : 'medium',
+        memory: { asks: 0, hits: 0 },
+        verify: { claims: 0, first_try_passes: 0 },
+        rules_applied: ['delegation-policy'],
+        persona: null,
+        input_kind: 'prompt',
+        type: 'note',
+        review_skipped: { diff_lines: input.diff_lines, mutation_measure: input.mutation_measure },
+    };
+
+    return { line, errors: [] };
+}

package/src/scripts/_lib/rule_layer_overlap.ts

@@ -0,0 +1,254 @@
+/**
+ * Rule-layer overlap detection — is the corpus about to be delivered twice?
+ *
+ * Claude Code loads `~/.claude/rules/` and `<project>/.claude/rules/` **both**,
+ * user layer first, with no dedup between them: a rule present in both is in
+ * standing context twice. Measured on a maintainer machine 2026-08-08 — 112
+ * global entries + 92 project entries, 91 shared basenames, 176,354 exact-BPE
+ * tokens of which 74,137 (42%) redundant. Evidence:
+ * `agents/evidence/analysis/standing-rule-delivery-topologies.md`; the host's
+ * loading contract: `agents/evidence/analysis/claude-code-rules-dir-contract.md`.
+ *
+ * This module answers three questions and nothing else:
+ *
+ * 1. **Do two layers overlap, and by how much?** ({@link compareLayers})
+ * 2. **Is the overlap a pure duplicate, or a content skew?** — the difference
+ *    decides whether suppression is enough or a refresh is also needed.
+ * 3. **How is a layer suppressed without deleting it?** — the host's own
+ *    `claudeMdExcludes` settings key ({@link claudeMdExcludesGlob},
+ *    {@link mergeClaudeMdExcludes}).
+ *
+ * The comparison half is pure so it is testable from fixtures; only
+ * {@link readRuleLayer} touches the filesystem, and nothing here ever writes or
+ * unlinks. Deleting a user's `~/.claude/rules/` would be a Hard-Floor action
+ * (`non-destructive-by-default`), so no function in this module can reach one.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Frontmatter keys the installer stamps onto its OWN copies, and which therefore
+ * differ between a global (installed) copy and a project (projected) copy of the
+ * same rule without either being stale.
+ *
+ * Kept in lockstep with `install.ts`'s `_set_key(fm_lines, 'package', …)` /
+ * `_set_key(fm_lines, 'source_path', …)` pair. Adding a third stamped key there
+ * without adding it here makes every rule read as divergent.
+ */
+export const INSTALLER_PROVENANCE_KEYS: readonly string[] = ['package', 'source_path'];
+
+/** One rule layer: its directory and `basename → text` for every `.md` in it. */
+export interface RuleLayer {
+    readonly dir: string;
+    readonly files: ReadonlyMap<string, string>;
+}
+
+/** What {@link compareLayers} found. Counts are chars; token conversion is the caller's. */
+export interface OverlapReport {
+    readonly schema_version: 1;
+    /** Basenames present in both layers. */
+    readonly overlap: readonly string[];
+    /** Of {@link overlap}: bodies equal once the provenance keys are stripped — pure duplicates. */
+    readonly duplicate: readonly string[];
+    /** Of {@link overlap}: bodies genuinely differ — a content skew. Suppression alone is NOT enough. */
+    readonly divergent: readonly string[];
+    /** Basenames only in the first (global) layer. */
+    readonly global_only: readonly string[];
+    /** Basenames only in the second (project) layer. */
+    readonly project_only: readonly string[];
+    /** Chars the SECOND layer contributes redundantly — what suppressing it recovers. */
+    readonly redundant_chars: number;
+}
+
+/** The three answers a user may give when an overlap is detected. */
+export type LayerChoice = 'global' | 'project' | 'both-acknowledged';
+
+/**
+ * Strip the installer's provenance keys from a rule's frontmatter block.
+ *
+ * Only lines inside the leading `---` … `---` fence are considered, and only
+ * those whose key is in {@link INSTALLER_PROVENANCE_KEYS}. A body line that
+ * happens to start with `package:` survives — stripping it would make two
+ * genuinely different rules compare equal, which is the failure direction that
+ * matters here.
+ *
+ * A file with no frontmatter fence is returned unchanged.
+ */
+export function stripProvenance(text: string): string {
+    const lines = text.split('\n');
+    if (lines[0]?.trim() !== '---') return text;
+    let close = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i]?.trim() === '---') {
+            close = i;
+            break;
+        }
+    }
+    if (close === -1) return text;
+    const kept: string[] = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (i > 0 && i < close) {
+            const key = /^([A-Za-z_][A-Za-z0-9_-]*):/.exec(lines[i] ?? '')?.[1];
+            if (key !== undefined && INSTALLER_PROVENANCE_KEYS.includes(key)) continue;
+        }
+        kept.push(lines[i] ?? '');
+    }
+    return kept.join('\n');
+}
+
+/** Sorted basenames of `a` that are absent from `b`. */
+function only_in(a: ReadonlyMap<string, string>, b: ReadonlyMap<string, string>): string[] {
+    return [...a.keys()].filter((k) => !b.has(k)).sort();
+}
+
+/**
+ * Compare two rule layers. Pure — no filesystem, no clock, no environment.
+ *
+ * `global_layer` is the user-level layer and `project_layer` the project one,
+ * because {@link OverlapReport.redundant_chars} is measured on the SECOND
+ * argument: it answers "what does suppressing the project layer recover", which
+ * is the direction the installer offers first (the project layer is the one it
+ * is usually about to write).
+ */
+export function compareLayers(
+    global_layer: ReadonlyMap<string, string>,
+    project_layer: ReadonlyMap<string, string>,
+): OverlapReport {
+    const overlap = [...global_layer.keys()].filter((k) => project_layer.has(k)).sort();
+    const duplicate: string[] = [];
+    const divergent: string[] = [];
+    let redundant_chars = 0;
+    for (const name of overlap) {
+        const g = stripProvenance(global_layer.get(name) ?? '');
+        const p = stripProvenance(project_layer.get(name) ?? '');
+        if (g === p) {
+            duplicate.push(name);
+            redundant_chars += (project_layer.get(name) ?? '').length;
+        } else {
+            divergent.push(name);
+        }
+    }
+    return {
+        schema_version: 1,
+        overlap,
+        duplicate,
+        divergent,
+        global_only: only_in(global_layer, project_layer),
+        project_only: only_in(project_layer, global_layer),
+        redundant_chars,
+    };
+}
+
+/**
+ * Read every `.md` in `dir` into a {@link RuleLayer}, or `null` when the
+ * directory does not exist.
+ *
+ * Symlinks are followed, because the project layer is a symlink projection into
+ * `dist/agent-src/rules/` and its CONTENT is what lands in context. An entry
+ * whose target is unreadable (a dangling symlink) is skipped rather than
+ * throwing — a broken link contributes no bytes to the session either.
+ */
+export function readRuleLayer(dir: string): RuleLayer | null {
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir);
+    } catch {
+        return null;
+    }
+    const files = new Map<string, string>();
+    for (const name of names.filter((n) => n.endsWith('.md')).sort()) {
+        try {
+            files.set(name, fs.readFileSync(path.join(dir, name), 'utf-8'));
+        } catch {
+            continue;
+        }
+    }
+    return { dir, files };
+}
+
+/**
+ * The `claudeMdExcludes` glob that suppresses one rules directory.
+ *
+ * The host matches this key against ABSOLUTE paths, so the directory is
+ * resolved before the `/**` suffix is appended. Documented example from the
+ * host's own docs: `"/home/user/monorepo/other-team/.claude/rules/**"`.
+ */
+export function claudeMdExcludesGlob(dir: string): string {
+    return `${path.resolve(dir).replace(/\/+$/, '')}/**`;
+}
+
+/**
+ * Append `entry` to an existing `claudeMdExcludes` value, preserving everything
+ * already there.
+ *
+ * `claudeMdExcludes` arrays MERGE across settings layers, so an install that
+ * replaced the array would silently drop another layer's exclusions — a
+ * different defect from the one being fixed. Non-string members of a
+ * hand-edited array are preserved in order; an absent or non-array value starts
+ * a fresh single-entry array. Already present → returned unchanged, so the
+ * operation is idempotent across re-installs.
+ */
+export function mergeClaudeMdExcludes(existing: unknown, entry: string): unknown[] {
+    if (!Array.isArray(existing)) return [entry];
+    if (existing.includes(entry)) return [...existing];
+    return [...existing, entry];
+}
+
+/** What the installer should do, given an overlap report and the user's choice. */
+export interface LayerAction {
+    /** Which layer this install writes. */
+    readonly write: 'global' | 'project' | 'both';
+    /** Directory to suppress via `claudeMdExcludes`, or `null` when nothing is suppressed. */
+    readonly suppress_dir: string | null;
+    /** True when the overlap contains divergent bodies — suppression alone loses obligations. */
+    readonly refresh_required: boolean;
+    /** One-line human summary; the installer prints it verbatim. */
+    readonly note: string;
+}
+
+/**
+ * Turn a report plus a {@link LayerChoice} into the action to take. Pure.
+ *
+ * `both-acknowledged` writes both and suppresses nothing — a deliberate
+ * two-layer setup is legitimate and the flag exists so the installer does not
+ * have to guess. The other two choices name the layer to KEEP and suppress the
+ * other; suppression never deletes.
+ *
+ * `refresh_required` fires on any divergent body: suppressing a layer whose
+ * copies differ would drop whichever obligations only the suppressed copy
+ * carried, so the caller must refresh before suppressing. This is the guard
+ * against the version-skew case, which the 2026-08-08 measurement found absent
+ * but nothing prevents later.
+ */
+export function decideLayerAction(
+    report: OverlapReport,
+    choice: LayerChoice,
+    global_dir: string,
+    project_dir: string,
+): LayerAction {
+    const refresh_required = report.divergent.length > 0;
+    const skew = refresh_required
+        ? ` ${report.divergent.length} shared rule(s) differ in body — refresh before suppressing, or obligations only the suppressed copy carries are lost.`
+        : '';
+    if (choice === 'both-acknowledged') {
+        return {
+            write: 'both',
+            suppress_dir: null,
+            refresh_required,
+            note:
+                `Keeping both rule layers by request: ${report.overlap.length} shared rule(s), `
+                + `${report.redundant_chars} chars delivered twice per session. Nothing suppressed, nothing deleted.${skew}`,
+        };
+    }
+    const keep = choice === 'global' ? global_dir : project_dir;
+    const drop = choice === 'global' ? project_dir : global_dir;
+    return {
+        write: choice,
+        suppress_dir: drop,
+        refresh_required,
+        note:
+            `Keeping ${choice} rule layer (${keep}); suppressing ${drop} via claudeMdExcludes — `
+            + `recovers ${report.redundant_chars} chars per session. No file is deleted or rewritten.${skew}`,
+    };
+}