@event4u/agent-config 14.7.0 → 14.8.0

package/src/config/rule-stub-ceilings.json

@@ -1,12 +1,12 @@
 {
     "_comment": "Per-rule stub ceilings (road-to-rule-stub-projection Phase 2). One exact-BPE token ceiling per rule carrying a migration pointer. SHRINK-ONLY: a rule may fall below its ceiling freely, and may not rise above it. Raising a ceiling to clear a failing check is the config-weakening move this repo blocks by construction \u2014 every raise needs a `history` entry whose `reason` is a real sentence. The ceilings are a floor-plus-residue SNAPSHOT taken at adoption, not a target: a rule at its ceiling is not thereby correct, only not worse. Regenerate with `check_rule_stub_ceiling --write-baseline`; never hand-edit the counts.",
-    "measured_at_commit": "955378e83",
+    "measured_at_commit": "05eeb5ca3",
     "tokens_exact": true,
     "ceilings": {
         "active-remediation": 1601,
         "analysis-skill-routing": 76,
         "architecture": 955,
-        "artifact-drafting-protocol": 611,
+        "artifact-drafting-protocol": 680,
         "augment-edit-discipline": 137,
         "autonomous-execution": 1633,
         "brand-consistency": 133,
@@ -37,7 +37,7 @@
         "provider-lifecycle-discipline": 472,
         "reviewer-awareness": 131,
         "roadmap-ci-steps-policy": 564,
-        "roadmap-progress-sync": 2185,
+        "roadmap-progress-sync": 2479,
         "rule-type-governance": 87,
         "skill-improvement-trigger": 81,
         "skill-quality": 78,
@@ -68,6 +68,20 @@
             "from": 2117,
             "to": 2185,
             "reason": "One sentence in Iron Law 1, +68 tokens, and it is obligation surface rather than explanation: `roadmap:progress` now passes `--archive`, so the law's operational meaning changed \u2014 a complete roadmap is moved by the same run instead of reported to a human, and the two exclusions a reader must know before trusting that (`--check` never archives, the PostToolUse hook never archives) are exactly the part that cannot be deferred to a pointer. The prose was NOT moved to docs/guidelines/agent-infra/roadmap-progress-mechanics.md, which is where this rule's migration note sends its mechanics, because that file has roughly a hundred characters of headroom under the 16,000-char depth ceiling and check_depth_budget is shrink-only with four files already over it \u2014 a FIFTH over-ceiling file reds, so moving 400 characters there would have traded this gate for that one. The full contract, the council record and its recorded dissent live with the code in src/agent-src/scripts/archival_sweep.ts, which is the third home and the one with room."
+        },
+        {
+            "date": "2026-08-20",
+            "rule": "artifact-drafting-protocol",
+            "from": 611,
+            "to": 680,
+            "reason": "Three lines plus a pointer extension, +69 tokens, for a new contract field that governs what a run may author without asking: an artifact discovered AFTER an accepted execution contract halts by default, and `late_artifacts: auto-research` is the only declared value that continues, capped at three per run. The five-step auto-research procedure, the reasoning for the default and its reversibility argument all went to the pointer target (artifact-drafting-protocol-mechanics gains a Late artifacts section) rather than here, which is what held the growth to a bullet. The residue is obligation surface and cannot live in the guideline: this rule's own batch-mode bullet already tells the reader that a mid-run artifact triggers the full interactive protocol, so a reader who never opens the guideline would conclude that a declared value cannot change it. Named default rather than described behaviour, because the default direction is the decision -- AI council 2/2 (anthropic + openai) chose `halt` over `auto-research` on the autonomy-defaults-sheet fork of road-to-user-out-of-the-loop, record agents/evidence/council/drain-blocker-dispositions-a.md."
+        },
+        {
+            "date": "2026-08-20",
+            "rule": "roadmap-progress-sync",
+            "from": 2185,
+            "to": 2479,
+            "reason": "One subsection, +294 tokens, for the `deferred_policy` contract field: a declared policy removes the synchronous options ROUND at closure without moving any row of the preservation test's routing table. It is obligation surface and it cannot live anywhere else. Not in the pointer target -- roadmap-progress-mechanics.md sits at 16,039 chars against check_depth_budget's 16,000-char ceiling, and that gate is a count ratchet whose next failure is a FIFTH over-ceiling file, so prose pushed there is the one move that turns a warn into a red. Not in the contract context either: Iron Law 3 is the gate being amended, and a reader who learns from roadmap-execution-contract that a field exists but never reads this rule would not know that `cancel-with-memo` still stops for the user. The three-row table is the delta in full; the reasoning, both alternatives and the reversibility argument went to the contract context's own decision comment. Condensed once before this raise (2509 -> 2411) by cutting a paragraph that restated the preservation test. AI council 2/2 (anthropic + openai) on the autonomy-defaults-sheet fork of road-to-user-out-of-the-loop, record agents/evidence/council/drain-blocker-dispositions-a.md. RE-BASED on merge with origin/main, 2026-08-20: this entry was authored against a base of 2117 and raised to 2411. main had independently raised the same ceiling 2117 -> 2185 for its own reason, so the merged tree measures 2479 and the honest arithmetic for THIS raise is 2185 -> 2479 -- the same +294 for the same subsection, re-based rather than re-argued. Recorded rather than silently regenerated because the gate's own failure text names a history-versus-ceilings disagreement as the signature of a hand-edited count, and a merge that quietly adopted one side's numbers would produce exactly that signature with nothing saying why."
         }
     ]
 }

package/src/install/globalRuleLayers.ts

@@ -0,0 +1,197 @@
+/**
+ * Where each host's GLOBAL rule layer lives on disk, and whether it carries a
+ * given set of rules.
+ *
+ * ## Why this module exists
+ *
+ * ADR-236 partitions rules between the global and the project layer: an artefact
+ * scoped to this package alone stays project-local, everything else is delivered
+ * globally and withheld from the project tree. `partitionEligibility.ts` decides
+ * WHETHER the partition is on, by verifying the claude host layer against
+ * `installed.lock`. Its own docstring then draws the only conclusion that
+ * evidence supports — it "says nothing about `~/.cursor`", so withholding a
+ * cursor artefact on the strength of a claude fingerprint "would deliver it
+ * nowhere".
+ *
+ * That reasoning is right and its scope was too narrow for rules. The rule
+ * filter sits in `condense.ts::_scoped_rule_basenames()`, which is per-RUN and
+ * not per-DIRECTORY, so it already withholds from `.clinerules` on a claude
+ * fingerprint — the exact extrapolation the docstring refuses. Measured
+ * 2026-08-22 in a freshly generated worktree with the partition active:
+ *
+ * ```
+ * .claude/rules      13 files, 13 package-only,   0 global-only
+ * .clinerules        14 files, 13 package-only,   0 global-only
+ * .cursor/rules     126 files, 26 package-only, 100 global-only
+ * .windsurf/rules   113 files, 13 package-only, 100 global-only
+ * .augment/rules    118 files, 15 package-only, 103 global-only
+ * ```
+ *
+ * Two hosts partition on borrowed evidence; three do not partition at all. This
+ * module supplies the evidence per host so neither case has to be guessed:
+ * {@link globalRuleLayerNames} reads the host's own global directory, and
+ * {@link hostLayerCarries} answers the one question a withhold depends on.
+ *
+ * ## Why the paths are written out rather than imported
+ *
+ * `USER_SCOPE_PATHS` in `src/scripts/install.ts` is the authority for a host's
+ * global scope ROOT, and it is the right authority. It is not imported here for
+ * two reasons: `install.ts` is a multi-thousand-line CLI entry point that pulls
+ * in the whole installer graph, and a scope root is not a rules path — cline's
+ * root already IS its rules directory (`~/Documents/Cline/Rules/`) while every
+ * other host appends a subdirectory. So the mapping is stated once here and
+ * PINNED against `USER_SCOPE_PATHS` by `tests/install/global_rule_layers.test.ts`,
+ * which fails if a root moves. A pinned restatement drifts loudly; an import
+ * would have cost the bundle.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+/**
+ * Tool id → its global rule directory, relative to the user's home.
+ *
+ * Keys are the ids `USER_SCOPE_PATHS` and `TOOL_SIGNALS` use, so a row here is
+ * traceable to the installer's own scope table rather than invented.
+ *
+ * The five hosts below are the ones that receive a projected rule TREE. A host
+ * whose rules arrive as a single concatenated file (`.windsurfrules`,
+ * `GEMINI.md`, copilot instructions) has no directory to compare and is
+ * deliberately absent: {@link globalRuleLayerPath} returns null for it, which
+ * reads as "no evidence" and keeps the full projection.
+ */
+export const GLOBAL_RULE_DIRS: Readonly<Record<string, string>> = {
+    'claude-code': '.claude/rules',
+    cursor: '.cursor/rules',
+    augment: '.augment/rules',
+    // Windsurf's scope root is `~/.codeium/windsurf/`, not `~/.windsurf/`.
+    windsurf: '.codeium/windsurf/rules',
+    // Cline's scope root IS the rules directory — no `rules/` suffix.
+    cline: 'Documents/Cline/Rules',
+};
+
+/**
+ * Project rule directory → the tool id whose global layer covers it.
+ *
+ * Five entries, because five directories receive a projected rule TREE. Two are
+ * symlink trees (`condense.ts::TOOL_DIRS`); three are written by their own
+ * emitters — `generate_cursor_mdc_rules`, `generate_windsurf_modern_rules`, and
+ * `project_to_augment`. The `.cursor/rules` row covers both the `.mdc` files and
+ * the legacy `.md` symlinks that share that directory.
+ *
+ * It lives here rather than in either consumer so the gate that reports a
+ * duplicate and the emitters that must stop creating one read the same list. A
+ * sixth host directory added to one and not the other is exactly how a gate goes
+ * green over a tree nobody checks.
+ */
+export const PROJECT_RULE_DIRS: Readonly<Record<string, string>> = {
+    '.claude/rules': 'claude-code',
+    '.cursor/rules': 'cursor',
+    '.clinerules': 'cline',
+    '.windsurf/rules': 'windsurf',
+    '.augment/rules': 'augment',
+};
+
+/** The tool id whose global layer covers a project rule directory, or null. */
+export function toolIdForProjectRuleDir(dir: string): string | null {
+    return PROJECT_RULE_DIRS[dir] ?? null;
+}
+
+/** Every tool id that has a global rule directory this module can read. */
+export function hostsWithGlobalRuleLayer(): readonly string[] {
+    return Object.keys(GLOBAL_RULE_DIRS).sort();
+}
+
+/**
+ * Absolute path to a host's global rule directory, or null when the host has no
+ * directory-shaped global layer.
+ *
+ * Null is a real answer and not an error: it means this module cannot supply
+ * evidence for that host, and every caller must read that as "do not withhold".
+ */
+export function globalRuleLayerPath(
+    toolId: string,
+    home: string = process.env['HOME'] ?? os.homedir(),
+): string | null {
+    const rel = GLOBAL_RULE_DIRS[toolId];
+    return rel === undefined ? null : path.join(home, rel);
+}
+
+/**
+ * The rule basenames a host's global layer actually holds, normalised to `.md`.
+ *
+ * Returns null when the directory does not exist or cannot be read — the
+ * absent-tolerant contract Phase 1.1 requires. Normalisation matters because
+ * Cursor's tree is `.mdc`: comparing raw filenames would report every rule as
+ * missing there and turn the partition off for the one host whose duplication is
+ * largest.
+ */
+export function globalRuleLayerNames(
+    toolId: string,
+    home: string = process.env['HOME'] ?? os.homedir(),
+): readonly string[] | null {
+    const dir = globalRuleLayerPath(toolId, home);
+    if (dir === null) {
+        return null;
+    }
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir);
+    } catch {
+        return null;
+    }
+    return entries
+        .filter((f) => f.endsWith('.md') || f.endsWith('.mdc'))
+        .map((f) => (f.endsWith('.mdc') ? `${f.slice(0, -4)}.md` : f))
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/** What {@link hostLayerCarries} concluded, and on what evidence. */
+export interface CarriesVerdict {
+    /** True only when every requested name is present in the host's layer. */
+    readonly carries: boolean;
+    /** Absolute path read, or null when the host has no directory layer. */
+    readonly layerPath: string | null;
+    /** Names asked for that the layer does not hold. Empty when `carries`. */
+    readonly missing: readonly string[];
+    /** Why the verdict is what it is — for the caller's own reporting. */
+    readonly reason: 'carries' | 'no-layer-for-host' | 'layer-absent' | 'missing-names';
+}
+
+/**
+ * Does this host's global layer carry every rule that would be withheld from its
+ * project directory?
+ *
+ * This is the property `personaPartition`'s docstring states as the precondition
+ * for any withhold — "withholding is only safe once the surviving layer is known
+ * to carry what is withheld" — asked per host instead of inferred from claude.
+ *
+ * Fails safe in all three negative directions: a host with no directory layer, a
+ * directory that is absent, and a directory missing even one name all return
+ * `carries: false`, so the caller keeps the full projection. An empty
+ * `ruleNames` is vacuously carried, which is correct — withholding nothing needs
+ * no evidence.
+ */
+export function hostLayerCarries(
+    toolId: string,
+    ruleNames: readonly string[],
+    home: string = process.env['HOME'] ?? os.homedir(),
+): CarriesVerdict {
+    const layerPath = globalRuleLayerPath(toolId, home);
+    if (layerPath === null) {
+        return { carries: false, layerPath: null, missing: [...ruleNames], reason: 'no-layer-for-host' };
+    }
+    const have = globalRuleLayerNames(toolId, home);
+    if (have === null) {
+        return { carries: false, layerPath, missing: [...ruleNames], reason: 'layer-absent' };
+    }
+    const present = new Set(have);
+    const missing = ruleNames.filter((n) => !present.has(n));
+    return {
+        carries: missing.length === 0,
+        layerPath,
+        missing,
+        reason: missing.length === 0 ? 'carries' : 'missing-names',
+    };
+}

package/src/install/partitionEligibility.ts

@@ -166,6 +166,31 @@ export function partitionVerdict(inputs: PartitionInputs): PartitionVerdict {
  * artefact is NOT package-only, so it is delivered globally and withheld from
  * the project layer. Both defaults resolve toward "the artefact is generally
  * useful"; only one of them is about withholding.
+ *
+ * ## The state space, MEASURED rather than enumerated defensively (2026-08-21)
+ *
+ * Three of this function's branches — unreadable file, absent `workspaces:`,
+ * empty list — all resolve to `false`, and the closure review asked whether one
+ * of them was resolving by accident. Counted over all 119 files in `src/rules/`:
+ *
+ *     absent=0 · empty=0 · maintainer-only=16 · mixed=103 · scalar-or-other=0
+ *
+ * So exactly TWO states occur today, both deliberate, and the 16 is the figure
+ * ADR-236 partitions on.
+ *
+ * **The other three branches are CURRENTLY ABSENT from the generated tree, not
+ * unreachable** — an earlier revision of this note said "the state space is
+ * closed by that count", and a neutral review was right to refuse it. A file can
+ * become unreadable at runtime (permissions, a partial write, a truncated
+ * checkout) and a rule can acquire a malformed `workspaces:` on any commit. The
+ * count is a current inventory, never a proof of impossibility.
+ *
+ * What the count DOES buy is a bound on the defensive work worth doing now:
+ * fixtures for the absent and malformed cases would pin behaviour on inputs no
+ * committed rule produces, so they were not written. All three branches already
+ * resolve to `false` — deliver globally, withhold from the project layer — which
+ * is the over-delivery direction rather than the losing one, so the untested
+ * branches fail safe. Should that count move, this note is the thing that dates.
  */
 export function isExclusivelyPackageOnly(source_path: string): boolean {
     let meta: Record<string, unknown>;
@@ -323,3 +348,155 @@ export function stampHostLayerFingerprint(
         return null;
     }
 }
+
+/**
+ * Per-tool-directory persona list under the partition — ADR-236's closure for the
+ * one family it never reached.
+ *
+ * The partition shipped for rules and skills and stopped there, so
+ * `<repo>/.claude/personas` kept being written while `~/.claude/personas` was
+ * installed from `_CLAUDE_SKILL_BUNDLE` (`install.ts:1916-1921`). Measured
+ * 2026-08-21 on a freshly regenerated tree with the partition ACTIVE: **29 shared
+ * names**, and neither `check_single_delivery` nor `_lib/layer_overlap_notice`
+ * looked, because `personas` was in neither's `TYPES`.
+ *
+ * ## Two properties the caller depends on
+ *
+ * **Scoped to `.claude/` only.** {@link partitionActive} verifies the CLAUDE host
+ * layer against `installed.lock`. It says nothing about `~/.cursor`, so
+ * withholding a cursor persona on the strength of a claude fingerprint would
+ * deliver it nowhere — the one failure the fail-safe design exists to prevent.
+ * Every other tool directory keeps the full projection.
+ *
+ * **Reconciliation is the empty list, not a second code path.** The caller's
+ * stale-symlink sweep removes any link whose name is absent from the list it was
+ * given for that directory, so returning `[]` empties a directory an earlier
+ * version populated. A gate that only declined to WRITE would leave the existing
+ * duplicate standing — a partition that stops new duplication and keeps the old
+ * is not a partition.
+ *
+ * Verified before shipping: every one of the 29 project personas is present in
+ * the global layer (32 there, a strict superset). The partition is a removal and
+ * has no repair path, so withholding is only safe once the surviving layer is
+ * known to carry what is withheld.
+ */
+export function personaPartition(
+    projectRoot: string,
+    all: readonly string[],
+): {
+    readonly all: readonly string[];
+    listFor: (toolDir: string) => readonly string[];
+    readonly note: string;
+    /**
+     * Per-directory count, for the caller's success line.
+     *
+     * Added after a neutral review (2026-08-21) caught the message claiming
+     * `N personas each` across every tool directory while `.claude/` had
+     * received zero. The suffix said "withheld" and the count contradicted it in
+     * the same sentence — a reader trusting the number is misled by a line that
+     * also carries its own correction.
+     */
+    countFor: (toolDir: string) => number;
+} {
+    const active = partitionActive(projectRoot);
+    return {
+        all,
+        listFor: (toolDir) => (personaWithheldFor(toolDir, active) ? [] : all),
+        note: active ? ' — .claude/ withheld: ADR-236 partition, personas arrive from ~/.claude' : '',
+        countFor: (toolDir) => (personaWithheldFor(toolDir, active) ? 0 : all.length),
+    };
+}
+
+/**
+ * The pure half of {@link personaPartition}: withhold iff the partition is active
+ * AND this is a Claude tool directory.
+ *
+ * Split out so the decision is testable in BOTH directions. `personaPartition`
+ * reads `installed.lock` through a memoized `partitionActive`, so a test over it
+ * can only assert whatever this machine happens to be — which is a test that
+ * passes either way and therefore proves nothing. The two properties worth
+ * pinning are exactly the two this signature exposes: `.claude/` is withheld when
+ * active, and NOTHING else ever is.
+ */
+export function personaWithheldFor(toolDir: string, active: boolean): boolean {
+    return active && toolDir.startsWith('.claude/');
+}
+
+/**
+ * Does the project layer withhold the colon-form `/cluster:sub` commands?
+ *
+ * ## The claim this replaces, and the measurement that revised it
+ *
+ * `generate_claude_project_commands` was written on the reasoning that "Claude
+ * Code dedupes project and user scope by name, so the two copies of
+ * `/cluster:sub` collapse" — a host-behaviour claim with no first-party
+ * observation behind it. Its sibling claim about skills WAS probed under
+ * ADR-236's roadmap (Phase 5.2, `claudeMdExcludes`) and came back negative, so
+ * an unprobed host assumption in the same area was not a safe default.
+ *
+ * **MEASURED 2026-08-21, Claude Code 2.1.238.** Fixture: `/analyze:inbox`
+ * present in BOTH `~/.claude/commands/analyze/` and a temp project's
+ * `.claude/commands/analyze/`. The session reports `COUNT=1`. A control second
+ * entry (`/analyze:inboxctl`, project-only) makes the same probe report
+ * `COUNT=2` — so the 1 is an observation, not a probe that can only say one.
+ *
+ * **The half nobody had checked: the surviving copy is the GLOBAL one.** Asked
+ * for the command's description, the session returned the global body, not the
+ * project fixture's. So the dedup claim holds and its unstated corollary
+ * inverts the value of the project-layer copy: where a verified global layer
+ * exists, those 40 symlinks are written, deduped away, and LOSE. They are dead
+ * weight there — not a second listing, and not a reachability guarantee either.
+ *
+ * ## Why `partitionActive` is the right predicate rather than a new one
+ *
+ * It is true exactly when a global layer is present and verified against
+ * `installed.lock`, which is exactly the case where the project copy loses; and
+ * false on a fresh checkout, an unverified install, or a version mismatch —
+ * every case where the project copy is the only reachable one. So the
+ * fail-safe direction the whole module is built around already matches the
+ * measurement, and withholding needs no separate switch.
+ *
+ * ## Honest limits
+ *
+ * Self-report, n=1 per condition, one host version, one machine. What is NOT
+ * claimed: that older or newer hosts dedupe the same way, or that precedence is
+ * stable across them.
+ *
+ * **And a claim that WAS made here has been withdrawn as false** (neutral review,
+ * 2026-08-21). It read: *"A host that stopped deduping would show up as a
+ * double-listing, and `check_single_delivery` reports the overlap either way."*
+ * It cannot. When this predicate returns true the project copy is never written,
+ * so there is no second copy for the host to double-list or for the gate to
+ * count — it would report zero overlap while the assumption underneath had
+ * failed. Worse, `partitionActive` verifies the INSTALL (version + content
+ * fingerprint), never the HOST version whose behaviour was measured, so a host
+ * upgrade changes the premise and moves nothing this code reads.
+ *
+ * What actually holds: reachability survives a dedup change either way, because
+ * the global copy is delivered regardless. What is lost is only the project
+ * copy's redundancy, and nothing detects that. A real detector would have to
+ * pin the host version this measurement was taken against and re-probe when it
+ * moves — not built here, and named as absent rather than implied away.
+ */
+export function commandsWithheld(projectRoot: string): boolean {
+    return partitionActive(projectRoot);
+}
+
+/**
+ * ## The caller's early return, flagged by review and kept
+ *
+ * `generate_claude_project_commands` applies this predicate and then returns
+ * early when `src/domains/` is absent — BEFORE its stale-link sweep. So a tree
+ * with no `src/domains` keeps whatever `.claude/commands` it already had, even
+ * when the commands are now withheld.
+ *
+ * Invariant rather than oversight: this package always ships `src/domains/`, the
+ * generator only runs from a checkout that has it, and a consumer never reaches
+ * this path. Documented rather than reordered, because hoisting the sweep above
+ * the guard would make a non-package tree lose a directory this code did not
+ * write — a worse failure than the one being avoided, and on a tree we do not own.
+ *
+ * The transition that DOES occur is covered: `partition_delivery_topology.test.ts`
+ * runs inactive→active over a fixture that has `src/domains`, and asserts both
+ * the links and the empty cluster directories are gone after one run.
+ */

package/src/install/ruleLayerPartition.ts

@@ -0,0 +1,212 @@
+/**
+ * The ADR-236 rule partition, decided per HOST directory on that host's own
+ * evidence.
+ *
+ * ## Why the decision moved from per-run to per-directory
+ *
+ * The filter used to sit in `condense.ts::_scoped_rule_basenames()`, which runs
+ * once per generation, so `partitionActive` — a claude-only fingerprint against
+ * `installed.lock` — decided for every host at once. That contradicted
+ * `partitionEligibility.ts`'s own fail-safe reasoning, which refuses to withhold a
+ * cursor artefact on claude's evidence because it "would deliver it nowhere", and
+ * it was measurably wrong in both directions on 2026-08-22 (partition ACTIVE,
+ * freshly generated worktree):
+ *
+ * ```
+ *   .claude/rules      13 files, 13 package-only,   0 global-only
+ *   .clinerules        14 files, 13 package-only,   0 global-only   ← narrowed on
+ *                                                                     borrowed evidence
+ *   .cursor/rules     126 files, 26 package-only, 100 global-only   ← never narrowed
+ *   .windsurf/rules   113 files, 13 package-only, 100 global-only   ← never narrowed
+ *   .augment/rules    118 files, 15 package-only, 103 global-only   ← never narrowed
+ * ```
+ *
+ * So the narrowing is per directory and gated on real evidence:
+ * {@link hostLayerCarries} reads that host's global directory and answers whether
+ * every name about to be withheld is actually there. No layer, an unreadable layer,
+ * or one missing a single name → the full projection is returned. A withhold now
+ * costs a directory read; the alternative cost a rule.
+ *
+ * ## Why it lives here rather than in condense.ts
+ *
+ * Four call sites consume it — the symlink emit plan, the cursor `.mdc` emitter,
+ * the windsurf emitter, the augment projector — and four sites deciding this
+ * separately is exactly how three of them came to disagree. It is in `src/install/`
+ * beside {@link partitionActive} and {@link hostLayerCarries}, the two predicates
+ * it composes, rather than in the 2,700-line generator that calls it.
+ *
+ * ## The classification source is the PROJECTION, not the authored tree
+ *
+ * `rulesSource` is `dist/agent-src/rules` at every call site, deliberately. A rule
+ * absent from `dist/` is compile-disabled and never projected, so it can be neither
+ * withheld nor duplicated — classifying from `src/rules` would count
+ * `telegraph-speak.md` (compile-disabled: 119 rules / 16 package-only in `src/`,
+ * 118 / 15 in `dist/`) and disagree with the emitter by exactly one file.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { isExclusivelyPackageOnly, partitionActive } from './partitionEligibility.js';
+import { hostLayerCarries, toolIdForProjectRuleDir } from './globalRuleLayers.js';
+
+export interface PartitionRulesOptions {
+    /** Project-relative host directory, e.g. `.cursor/rules`. */
+    readonly toolDir: string;
+    /** Candidate rule basenames, already scope- and manual-filtered. */
+    readonly rules: readonly string[];
+    /** Absolute project root — what `partitionActive` verifies against. */
+    readonly projectRoot: string;
+    /** Absolute directory the basenames resolve against for classification. */
+    readonly rulesSource: string;
+    readonly userHome?: string;
+    /** Where the kept-full notice goes. Silent when omitted. */
+    readonly announce?: (message: string) => void;
+    /**
+     * Override the partition-active decision instead of reading `installed.lock`.
+     *
+     * Split out for the reason `partitionEligibility.ts` states about its own
+     * `personaWithheldFor`: "so the decision is testable in BOTH directions". A
+     * test over the un-injected path can only assert whatever the machine happens
+     * to be — and this one bit differs between a maintainer checkout (installed,
+     * so active) and CI (nothing installed, so inactive), which made the first
+     * version of `rule_partition_per_host.test.ts` green locally and red on every
+     * CI shard. That is the environment-dependent gate this whole change exists to
+     * remove, reproduced in its own test suite.
+     *
+     * Production callers omit it.
+     */
+    readonly active?: boolean;
+}
+
+/**
+ * Narrow one directory's rule list to the package-only set — but only when THIS
+ * host's global layer is verified to carry what would be withheld.
+ *
+ * Returns a copy of `rules` unchanged in every uncertain case. That direction is
+ * the whole design: an unnecessary duplicate costs context, a wrong withhold costs
+ * the rule.
+ */
+export function partitionRulesForDir(opts: PartitionRulesOptions): string[] {
+    const { toolDir, rules, projectRoot, rulesSource } = opts;
+    const active = opts.active ?? partitionActive(projectRoot);
+    if (!active) {
+        return [...rules];
+    }
+    const toolId = toolIdForProjectRuleDir(toolDir);
+    if (toolId === null) {
+        // An unmapped directory has no global layer this code can point at, so
+        // there is no evidence to withhold on.
+        return [...rules];
+    }
+    const packageOnly = rules.filter((r) => isExclusivelyPackageOnly(path.join(rulesSource, r)));
+    const keep = new Set(packageOnly);
+    const withheld = rules.filter((r) => !keep.has(r));
+    const home = opts.userHome ?? process.env['HOME'] ?? os.homedir();
+    const verdict = hostLayerCarries(toolId, withheld, home);
+    if (!verdict.carries) {
+        opts.announce?.(
+            `  ⚠️  ${toolDir}: full projection kept — ${toolId}'s global layer ${verdict.reason}` +
+                (verdict.missing.length > 0
+                    ? ` (${String(verdict.missing.length)} rule(s) not there, e.g. ` +
+                      `${verdict.missing.slice(0, 3).join(', ')})`
+                    : ''),
+        );
+        return [...rules];
+    }
+    return packageOnly;
+}
+
+// ── The older, weaker duplicate-avoidance mechanism ──────────────────────────
+//
+// `projection.scope_dedup` (default OFF) predates the partition and solves the
+// same problem with a narrower method: skip a project copy only when its
+// user-scope twin is BYTE-IDENTICAL. It moved here from condense.ts alongside the
+// partition because the two are one subject — a reader deciding how a duplicate is
+// avoided should find both in one file rather than one here and one in a
+// 2,700-line generator. Behaviour is unchanged; only `MODULE_STATE` reads became
+// parameters.
+
+/** `fs.statSync(p).isFile()`, false on any error — condense.ts's `_isFile`. */
+function isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Per-tool user-scope rule directory, for the scope-dedup below. Only tools
+ * whose host reads a user-scope rules directory can have a redundant twin;
+ * everything else has nothing to de-duplicate against.
+ */
+const USER_SCOPE_RULE_DIRS: Readonly<Record<string, string>> = {
+    '.claude/rules': path.join('.claude', 'rules'),
+};
+
+/**
+ * Rules whose user-scope twin is BYTE-IDENTICAL to the source, i.e. safe to
+ * skip at project scope: the host still loads the same text, once instead of
+ * twice, so nothing the model sees changes.
+ *
+ * Byte-identity is the whole safety argument and is not negotiable. Keying on
+ * the filename alone would silently let a stale globally-installed copy win
+ * whenever the two scopes hold different versions — which is the NORMAL state
+ * while developing the package (measured: 110/110 shared filenames differing in
+ * bytes). This is deliberately not the thin-projection mechanism: no rule
+ * becomes trigger-gated, so the quality floor that disabled thin projection
+ * does not apply here.
+ */
+export interface DedupOptions {
+    readonly toolDir: string;
+    readonly rules: readonly string[];
+    readonly userHome: string;
+    /** Absolute directory the basenames resolve against, for the byte compare. */
+    readonly rulesSource: string;
+    readonly announce?: (message: string) => void;
+}
+
+export function dedupableRules(opts: DedupOptions): Set<string> {
+    const { toolDir: tool_dir, rules, userHome, rulesSource } = opts;
+    const relative = USER_SCOPE_RULE_DIRS[tool_dir];
+    if (relative === undefined) {
+        return new Set();
+    }
+    // A hostile or simply absent $HOME must make the dedup inert, not
+    // adventurous. In a container `$HOME` is often unset (so `homedir()` can
+    // resolve to `/`) or world-writable, and this function decides which rules
+    // to STOP emitting — reading an unexpected tree there is how a projection
+    // silently loses a rule. Council review of PR #1055 raised exactly this.
+    let userDirStat: fs.Stats;
+    const userDir = path.join(userHome, relative);
+    try {
+        userDirStat = fs.statSync(userDir);
+    } catch {
+        return new Set();
+    }
+    if (!userDirStat.isDirectory()) {
+        return new Set();
+    }
+    // World-writable user scope: anyone on the box could plant a byte-identical
+    // twin and thereby delete a rule from the project projection. Refuse.
+    if ((userDirStat.mode & 0o002) !== 0) {
+        opts.announce?.(`  ⚠️  ${tool_dir}: user-scope rules dir is world-writable — scope-dedup skipped`);
+        return new Set();
+    }
+    const skip = new Set<string>();
+    for (const rule of rules) {
+        const twin = path.join(userDir, rule);
+        const source = path.join(rulesSource, rule);
+        try {
+            if (!isFile(twin) || !isFile(source)) continue;
+            if (fs.readFileSync(twin).equals(fs.readFileSync(source))) {
+                skip.add(rule);
+            }
+        } catch {
+            // An unreadable twin is simply not de-duplicable — emit the project copy.
+        }
+    }
+    return skip;
+}