@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/condense.ts

@@ -1,17 +1,18 @@
 #!/usr/bin/env tsx
 /**
- * Agent-config sync — condense .agent-src.uncondensed/ → dist/agent-src/
+ * Agent-config sync — project the artefact roots under src/ → dist/agent-src/
  * and project dist/agent-src/ → .augment/ (copies for rules by default,
  * symlinks for the rest; opt into rule symlinks via
  * augment.rules_use_symlinks in .agent-settings.yml).
  *
  * Ported from the retired Python `src/scripts/condense.py` (ADR-200 — Python→TS
- * migration, Phase 5). Mirrors the Python CLI surface EXACTLY — every
- * subcommand (`--sync`, `--list`, `--changed`, `--check`, `--check-hashes`,
- * `--clean-hashes`, `--mark-done <path>`, `--mark-all-done`,
- * `--generate-tools`, `--clean-tools`, `--project-augment`) — same flags,
- * exit codes, stdout/stderr split, byte-identical messages. No behaviour
- * changes; historical quirks preserved and flagged.
+ * migration, Phase 5), which mirrored the Python CLI surface exactly.
+ * ADR-201 then narrowed it: `.md` is copied verbatim + path-rewritten instead of
+ * rewritten by an agent, so the condensation-hash cache and its subcommands
+ * (`--check-hashes`, `--clean-hashes`, `--mark-done`, `--mark-all-done`) are gone —
+ * staleness is read off the projection itself. Remaining surface: `--sync`,
+ * `--list`, `--changed`, `--check`, `--generate-tools`, `--clean-tools`,
+ * `--project-augment`.
  *
  * Path handling note: the retired Python implementation uses `pathlib.Path` objects.
  * This twin uses absolute path strings (the host filesystem on the
@@ -22,12 +23,12 @@
  * multi-root helper functions (iter_all_sources, resolve_logical,
  * artefact_roots) are exposed through a mutable module-state object so the
  * pytest suite's monkeypatch pattern — reassigning `condense.PROJECT_ROOT`,
- * `condense.HASH_FILE`, `condense.iter_all_sources`, … — has a faithful TS
+ * `condense.TARGET_DIR`, `condense.iter_all_sources`, … — has a faithful TS
  * equivalent. Tests mutate `MODULE_STATE` via the exported setters.
  */
 
-import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -42,6 +43,7 @@ import {
 import { build_claude_hook_matrix } from './_lib/claude_settings_hooks.js';
 import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import { project_settings_path, load_agent_settings } from './_lib/agent_settings.js';
+import { rule_is_compile_enabled } from './_lib/compile_time_toggles.js';
 import { info, success, flush_summary, resolve_level } from './_lib/script_output.js';
 import {
     TIER_TO_CLAUDE_MODEL as _TIER_TO_CLAUDE_MODEL,
@@ -223,7 +225,7 @@ function _stripChars(s: string, chars: string): string {
 // =============================================================================
 // Module state — mutable mirror of the Python module-level constants & hooks.
 //
-// The pytest suite reassigns `condense.PROJECT_ROOT`, `condense.HASH_FILE`,
+// The pytest suite reassigns `condense.PROJECT_ROOT`, `condense.TARGET_DIR`,
 // `condense.TARGET_DIR`, `condense.SOURCE_DIR`, `condense.RULES_SOURCE`,
 // `condense.SKILLS_SOURCE`, `condense.COMMANDS_SOURCE`,
 // `condense.CLAUDE_SKILLS_DIR`, `condense.AUGMENT_DIR`, `condense.SETTINGS_FILE`,
@@ -244,7 +246,6 @@ interface ModuleState {
     SOURCE_DIR: string;
     TARGET_DIR: string;
     AUGMENT_DIR: string;
-    HASH_FILE: string;
     SETTINGS_FILE: string;
     RULES_SOURCE: string;
     SKILLS_SOURCE: string;
@@ -267,7 +268,6 @@ function _deriveState(root: string): ModuleState {
         SOURCE_DIR: path.join(root, '.agent-src.uncondensed'),
         TARGET_DIR: path.join(root, 'dist/agent-src'),
         AUGMENT_DIR: path.join(root, '.augment'),
-        HASH_FILE: path.join(root, 'internal', '.condensation-hashes.json'),
         SETTINGS_FILE: project_settings_path(root),
         RULES_SOURCE: path.join(root, 'dist/agent-src', 'rules'),
         SKILLS_SOURCE: path.join(root, 'dist/agent-src', 'skills'),
@@ -396,130 +396,105 @@ function _read_augment_rules_use_symlinks(): boolean {
     return false;
 }
 
-function _lean_projection_mode(): string {
+/**
+ * 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'),
+};
+
+function _read_projection_scope_dedup(): boolean {
     const data = load_agent_settings({ project_path: MODULE_STATE.SETTINGS_FILE });
-    const lean = data['lean_projection'];
-    if (
-        typeof lean === 'object' &&
-        lean !== null &&
-        !Array.isArray(lean) &&
-        String((lean as Record<string, unknown>)['mode'] ?? '')
-            .trim()
-            .toLowerCase() === 'thin'
-    ) {
-        return 'thin';
+    const projection = data['projection'];
+    if (typeof projection !== 'object' || projection === null || Array.isArray(projection)) {
+        return false;
     }
-    return 'eager-all';
-}
-
-// --- hashing -----------------------------------------------------------------
-
-export function file_hash(filepath: string): string {
-    const h = crypto.createHash('sha256');
-    h.update(fs.readFileSync(filepath));
-    return h.digest('hex');
-}
-
-const _DEP_FRONTMATTER_KEYS = ['skills', 'rules'] as const;
-
-function _slug_to_logical(slug: string): string | null {
-    for (const cand of [`skills/${slug}/SKILL.md`, `rules/${slug}.md`]) {
-        if (_resolve_source(cand) !== null) {
-            return cand;
-        }
+    const value = (projection as Record<string, unknown>)['scope_dedup'];
+    if (typeof value === 'boolean') {
+        return value;
     }
-    return null;
+    if (typeof value === 'string') {
+        return ['true', 'yes', 'on', '1'].includes(value.trim().toLowerCase());
+    }
+    return false;
 }
 
-function _direct_includes(relative: string): string[] {
-    const source = _resolve_source(relative);
-    if (source === null) {
-        return [];
-    }
-    let meta: Record<string, unknown>;
+/**
+ * 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.
+ */
+function _dedupable_rules(tool_dir: string, rules: readonly string[], userHome: string): Set<string> {
+    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 {
-        [meta] = _parse_frontmatter(_readText(source));
+        userDirStat = fs.statSync(userDir);
     } catch {
-        return [];
+        return new Set();
     }
-    const deps: string[] = [];
-    for (const key of _DEP_FRONTMATTER_KEYS) {
-        const value = meta[key];
-        if (!Array.isArray(value)) {
-            continue;
-        }
-        for (const item of value) {
-            if (typeof item !== 'string') {
-                continue;
-            }
-            const logical = _slug_to_logical(item.trim());
-            if (logical !== null && logical !== relative) {
-                deps.push(logical);
-            }
-        }
+    if (!userDirStat.isDirectory()) {
+        return new Set();
     }
-    return deps;
-}
-
-export function effective_hash(relative: string, _seen: ReadonlySet<string> | null = null): string {
-    const source = _resolve_source(relative);
-    if (source === null) {
-        return '';
-    }
-    const own = file_hash(source);
-    if (_seen !== null && _seen.has(relative)) {
-        return own; // cycle — fold own content only
+    // 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) {
+        _print(`  ⚠️  ${tool_dir}: user-scope rules dir is world-writable — scope-dedup skipped`);
+        return new Set();
     }
-    const deps = [...new Set(_direct_includes(relative))].sort((a, b) =>
-        a < b ? -1 : a > b ? 1 : 0,
-    );
-    if (deps.length === 0) {
-        return own; // leaf — identical to plain file_hash
-    }
-    const seenNext = new Set(_seen ?? []);
-    seenNext.add(relative);
-    const parts = [own, ...deps.map((dep) => effective_hash(dep, seenNext))];
-    return crypto.createHash('sha256').update(parts.join('\n'), 'utf-8').digest('hex');
-}
-
-export function load_hashes(): Record<string, string> {
-    if (_exists(MODULE_STATE.HASH_FILE)) {
+    const skip = new Set<string>();
+    for (const rule of rules) {
+        const twin = path.join(userDir, rule);
+        const source = path.join(MODULE_STATE.RULES_SOURCE, rule);
         try {
-            return JSON.parse(_readText(MODULE_STATE.HASH_FILE)) as Record<string, string>;
+            if (!_isFile(twin) || !_isFile(source)) continue;
+            if (fs.readFileSync(twin).equals(fs.readFileSync(source))) {
+                skip.add(rule);
+            }
         } catch {
-            return {};
+            // An unreadable twin is simply not de-duplicable — emit the project copy.
         }
     }
-    return {};
+    return skip;
 }
 
-export function save_hashes(hashes: Record<string, string>): void {
-    _mkdirp(path.dirname(MODULE_STATE.HASH_FILE));
-    _writeText(MODULE_STATE.HASH_FILE, _jsonDumpsSorted(hashes) + '\n');
-}
-
-/** Mirror json.dumps(obj, indent=2, sort_keys=True) for a flat string map. */
-function _jsonDumpsSorted(obj: Record<string, string>): string {
-    const keys = Object.keys(obj).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-    if (keys.length === 0) {
-        return '{}';
+function _lean_projection_mode(): string {
+    const data = load_agent_settings({ project_path: MODULE_STATE.SETTINGS_FILE });
+    const lean = data['lean_projection'];
+    if (
+        typeof lean === 'object' &&
+        lean !== null &&
+        !Array.isArray(lean) &&
+        String((lean as Record<string, unknown>)['mode'] ?? '')
+            .trim()
+            .toLowerCase() === 'thin'
+    ) {
+        return 'thin';
     }
-    const lines = keys.map((k) => `  ${JSON.stringify(k)}: ${JSON.stringify(obj[k])}`);
-    return `{\n${lines.join(',\n')}\n}`;
+    return 'eager-all';
 }
 
-export function mark_done(relative_path: string): void {
-    const source_file = _resolve_source(relative_path);
-    if (source_file === null || !_exists(source_file)) {
-        _print(`❌  Source file not found: ${relative_path}`);
-        process.exit(1);
-    }
-    apply_path_rewriter(relative_path);
-    const hashes = load_hashes();
-    hashes[relative_path] = effective_hash(relative_path);
-    save_hashes(hashes);
-    _print(`✅  Marked as condensed: ${relative_path}`);
-}
+// --- hashing -----------------------------------------------------------------
+
+
 
 export function apply_path_rewriter(relative_path: string): boolean {
     const target = path.join(MODULE_STATE.TARGET_DIR, relative_path);
@@ -535,60 +510,66 @@ export function apply_path_rewriter(relative_path: string): boolean {
     return true;
 }
 
-export function mark_all_done(): void {
-    const hashes = load_hashes();
-    let count = 0;
-    for (const [source_file, relative] of _iter_sources()) {
-        if (!should_condense(source_file)) {
-            continue;
-        }
-        hashes[relative] = effective_hash(relative);
-        count += 1;
+
+/**
+ * Whether the projection of `relative` is out of date.
+ *
+ * Post-ADR-201 the projection IS `rewrite(source)` — a pure function of the
+ * source's own bytes and its own relative path. So staleness is *observable in
+ * the output* rather than inferred from a stored source hash, which is both
+ * simpler and strictly stronger: the old hash cache could only tell you the
+ * source had moved since someone last claimed to have condensed it. It never
+ * looked at dist, so a hand-edited or half-written projection read as current.
+ *
+ * The dropped dependency-folding (`effective_hash` mixed in the hashes of
+ * `skills:` / `rules:` frontmatter deps) has no counterpart here, and needs
+ * none: an LLM rewrite could be influenced by a dependency's content, a pure
+ * rewrite cannot. Probed rather than assumed — the whole rewriter chain
+ * (`_depth_prefix`, `_split_frontmatter`, `_rewrite_body_links`,
+ * `_rewrite_frontmatter_lines`, `_parse_trust_and_owner`,
+ * `_inject_hrr_banner`) touches no file but its own input.
+ */
+export function is_projection_stale(relative: string): boolean {
+    const source = _resolve_source(relative);
+    if (source === null) {
+        // No source at all — a leftover in dist. `check_sync` owns that verdict.
+        return false;
     }
-    save_hashes(hashes);
-    _print(`✅  Marked ${count} files as condensed`);
+    if (skip_compile_disabled_rule(relative)) {
+        // Deliberately absent from the projection, not out of date.
+        return false;
+    }
+    const target = path.join(MODULE_STATE.TARGET_DIR, relative);
+    if (!_exists(target)) {
+        return true; // never projected
+    }
+    return _readText(target) !== _rewrite_paths(_readText(source), relative);
 }
 
 export function list_changed_md(_source_dir?: string): string[] {
     // _source_dir retained for signature compatibility but ignored (multi-root).
-    const hashes = load_hashes();
     const changed: string[] = [];
-    for (const [source_file, relative] of _iter_sources()) {
-        if (!should_condense(source_file)) {
+    const seen = new Set<string>();
+    for (const [, relative] of _iter_sources()) {
+        if (seen.has(relative)) {
+            continue;
+        }
+        seen.add(relative);
+        // Resolve through `_resolve_source` rather than trusting the iterator's
+        // physical hit: `src/` and `src/agent-src/` are both artefact roots, so
+        // one relative path can name two unrelated files and only the resolver
+        // knows which one wins.
+        const source = _resolve_source(relative);
+        if (source === null || !should_condense(source)) {
             continue;
         }
-        const current_hash = effective_hash(relative);
-        const stored_hash = hashes[relative];
-        if (stored_hash !== current_hash) {
+        if (is_projection_stale(relative)) {
             changed.push(relative);
         }
     }
     return changed;
 }
 
-export function find_stale_hashes(_source_dir?: string): string[] {
-    const hashes = load_hashes();
-    const stale: string[] = [];
-    for (const relative of Object.keys(hashes).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))) {
-        if (_resolve_source(relative) === null) {
-            stale.push(relative);
-        }
-    }
-    return stale;
-}
-
-export function clean_stale_hashes(_source_dir?: string): number {
-    const stale = find_stale_hashes(_source_dir);
-    if (stale.length === 0) {
-        return 0;
-    }
-    const hashes = load_hashes();
-    for (const relative of stale) {
-        delete hashes[relative];
-    }
-    save_hashes(hashes);
-    return stale.length;
-}
 
 export function should_condense(filepath: string): boolean {
     if (path.extname(filepath) !== '.md') {
@@ -660,19 +641,66 @@ export function cleanup_stale(_source_dir: string, target_dir: string): number {
     return deleted;
 }
 
+/** ADR-201 (accepted 2026-07-29): `.md` is COPIED + path-rewritten, never rewritten
+ * by an LLM. Set false to restore the pre-ADR-201 behaviour, where `.md` was skipped
+ * here and an agent wrote the condensed body into `dist/` by hand.
+ *
+ * Measured basis for the removal: 0/429 artifacts saved ≥500 tok, aggregate 0.86%,
+ * 267/429 byte-identical, and −36 tok on the always-loaded kernel (condensation made
+ * the per-request surface *worse*). Determinism failed by construction: the hash
+ * covered the source, never the output, so drift was undetectable — observed live.
+ *
+ * Council verdict A: `dist/agent-src/` STAYS as a deterministically-produced,
+ * git-diffable artifact. Only the *manner* of derivation changes. */
+export const COPY_MD_VERBATIM = true;
+
+/** True when `relative` is a rule whose compile-time toggle is off, so the projector
+ * must not emit it. Exported for the coupling test — without a pinned test the
+ * second half of "dormancy" would be asserted rather than enforced, which is the
+ * exact failure ADR telegraph/0002 § part 1 records. */
+export function skip_compile_disabled_rule(relative: string): boolean {
+    const posix = relative.split(path.sep).join('/');
+    if (!posix.startsWith('rules/') || !posix.endsWith('.md')) {
+        return false;
+    }
+    const rule_id = path.basename(posix, '.md');
+    const settings = load_agent_settings({ project_path: MODULE_STATE.SETTINGS_FILE }) as Record<
+        string,
+        unknown
+    >;
+    return !rule_is_compile_enabled(rule_id, settings);
+}
+
 export function sync_non_md(_source_dir: string, target_dir: string): number {
     let copied = 0;
     const seen = new Set<string>();
     for (const [source_file, relative] of _iter_sources()) {
-        if (should_condense(source_file)) {
-            continue; // .md files are condensed by the agent, not copied here
+        if (!COPY_MD_VERBATIM && should_condense(source_file)) {
+            continue; // pre-ADR-201: .md was condensed by the agent, not copied here
         }
         if (seen.has(relative)) {
             continue;
         }
+        // ADR telegraph/0002 § part 1: a compile-time-disabled RULE must not be
+        // emitted at all. Router membership alone was never zero-cost — the host
+        // reads the projected FILE, so a rule dropped from router.json while its
+        // body still shipped kept costing its full token price. One switch, both
+        // surfaces. Unknown ids are always emitted (the map gates, it does not
+        // allowlist), so this is a no-op for every rule but the gated ones.
+        if (skip_compile_disabled_rule(relative)) {
+            continue;
+        }
         seen.add(relative);
         const target_file = path.join(target_dir, relative);
         copy_file(source_file, target_file);
+        // ADR-201: a copied `.md` still needs the ONE deterministic transform the
+        // removal deliberately preserves — `apply_path_rewriter` fixes relative
+        // links so they resolve from the DELIVERED location (`../../docs/…` →
+        // `../docs/…`, ~38 artifacts). Without this the projection's links break.
+        // Idempotent: it returns false when nothing changed.
+        if (COPY_MD_VERBATIM && relative.endsWith('.md')) {
+            apply_path_rewriter(relative);
+        }
         _print(`  Copied: ${relative}`);
         copied += 1;
     }
@@ -704,6 +732,12 @@ export function check_sync(_source_dir: string, target_dir: string): [string[],
             continue;
         }
         seen.add(relative);
+        // A compile-disabled rule is deliberately absent from the projection,
+        // so demanding a counterpart would report the intended state as a defect.
+        // Same predicate the projector and the router compiler use.
+        if (skip_compile_disabled_rule(relative)) {
+            continue;
+        }
         if (!_exists(path.join(target_dir, relative))) {
             missing.push(relative);
         }
@@ -714,7 +748,10 @@ export function check_sync(_source_dir: string, target_dir: string): [string[],
                 continue;
             }
             const relative = _relativeToPosix(target_file, target_dir);
-            if (_resolve_source(relative) === null) {
+            // Two ways a projected file is stale: no source at all, or a source
+            // that is compile-disabled — the second is how a re-enabled-then-
+            // disabled rule leaves weight behind.
+            if (_resolve_source(relative) === null || skip_compile_disabled_rule(relative)) {
                 stale.push(relative);
             }
         }
@@ -965,17 +1002,25 @@ function _read_rule_packs(): string[] | null {
 }
 
 /**
- * Whether a rule source file projects under the given workspace + pack
- * scopes. Both scopes are independent constraints: when configured, the
- * rule's frontmatter list must intersect (installed workspaces AND
- * installed packs). Kernel always projects; untagged axes fail safe.
+ * Whether a rule source file projects under the given workspace + pack +
+ * role scopes. Each configured scope is an independent constraint: the
+ * rule's frontmatter list must intersect it. Kernel always projects;
+ * untagged axes fail safe.
+ *
+ * `role_scope` is the subagent-role axis (road-to-lean-agent-init Phase 4):
+ * a `roles:` frontmatter list, parallel to `workspaces:`/`packs:`, so a
+ * review-worker subagent's rule projection can be scoped to review-shaped
+ * rules instead of the full set. Additive — the new param defaults to
+ * `null` (no role filtering), so every existing 2- and 3-arg call site
+ * compiles and behaves unchanged.
  */
 export function rule_in_scope(
     source_path: string,
     scope: readonly string[] | null,
     pack_scope: readonly string[] | null = null,
+    role_scope: readonly string[] | null = null,
 ): boolean {
-    if (scope === null && pack_scope === null) {
+    if (scope === null && pack_scope === null && role_scope === null) {
         return true;
     }
     const [meta] = _parse_frontmatter(_readText(source_path));
@@ -994,7 +1039,7 @@ export function rule_in_scope(
         }
         return values.some((v) => configured.includes(v));
     };
-    return axis('workspaces', scope) && axis('packs', pack_scope);
+    return axis('workspaces', scope) && axis('packs', pack_scope) && axis('roles', role_scope);
 }
 
 /** List rule basenames under RULES_SOURCE, workspace/pack scope applied. */
@@ -1004,6 +1049,12 @@ function _scoped_rule_basenames(): string[] {
     return _iterdirSorted(MODULE_STATE.RULES_SOURCE)
         .filter((p) => p.endsWith('.md') && _isFile(p))
         .filter((p) => rule_in_scope(p, scope, pack_scope))
+        // A compile-disabled rule has no dist/agent-src/ counterpart, so a per-tool
+        // symlink to it would dangle. The source file still exists, which is why the
+        // scope filters alone let it through — the toggle is a separate axis and this
+        // is its fourth consumer, after the router compiler, the dist writer, and
+        // check_sync. Same predicate in all four; that is the point.
+        .filter((p) => !skip_compile_disabled_rule(`rules/${path.basename(p)}`))
         .map((p) => path.basename(p))
         .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 }
@@ -1022,18 +1073,28 @@ export function generate_rule_symlinks(): number {
         );
     }
 
+    const dedup_on = _read_projection_scope_dedup();
+    const user_home = process.env['HOME'] ?? os.homedir();
+    const skipped_per_tool: Record<string, Set<string>> = {};
+
     let total = 0;
     for (const [tool_dir, rel_prefix] of Object.entries(tool_dirs)) {
         const target_dir = path.join(MODULE_STATE.PROJECT_ROOT, tool_dir);
+        const skip = dedup_on ? _dedupable_rules(tool_dir, rules, user_home) : new Set<string>();
+        skipped_per_tool[tool_dir] = skip;
         _mkdirp(target_dir);
-        // Clean stale symlinks
+        // Clean stale symlinks — a rule that became de-duplicable this run is
+        // stale at project scope too, so it has to go with the rest.
         for (const item of _iterdirSorted(target_dir)) {
             const name = path.basename(item);
-            if (_isSymlink(item) && !rules.includes(name) && name !== 'README.md') {
+            if (_isSymlink(item) && (!rules.includes(name) || skip.has(name)) && name !== 'README.md') {
                 fs.unlinkSync(item);
             }
         }
         for (const rule of rules) {
+            if (skip.has(rule)) {
+                continue;
+            }
             const link = path.join(target_dir, rule);
             if (_existsOrSymlink(link)) {
                 fs.unlinkSync(link);
@@ -1050,9 +1111,25 @@ export function generate_rule_symlinks(): number {
     const source_count = rules.length;
     for (const tool_dir of Object.keys(tool_dirs)) {
         const target_dir = path.join(MODULE_STATE.PROJECT_ROOT, tool_dir);
-        const tool_count = _iterdirSorted(target_dir).filter((f) => f.endsWith('.md')).length;
-        if (tool_count !== source_count) {
-            _print(`  ⚠️  ${tool_dir}: ${tool_count} rules (expected ${source_count})`);
+        // Count only the RULES this run emitted, not every `.md` in the tree.
+        // Some tool trees legitimately receive other artefact classes — the cline
+        // tree also carries `*.subagent.md` — and counting those produced a
+        // permanent "111 rules (expected 110)" warning that was pure noise. A
+        // warning that is always on is a warning nobody reads.
+        const emitted = new Set(rules);
+        const tool_count = _iterdirSorted(target_dir).filter((f) => emitted.has(path.basename(f))).length;
+        // Expect the de-duplicated count, not the source count: a skipped rule is
+        // an intended absence, so warning on it would train the reader to ignore
+        // this line — which is how a real drift gets missed.
+        const skipped = (skipped_per_tool[tool_dir] ?? new Set()).size;
+        const expected = source_count - skipped;
+        if (tool_count !== expected) {
+            _print(`  ⚠️  ${tool_dir}: ${tool_count} rules (expected ${expected})`);
+        }
+        if (skipped > 0) {
+            _print(
+                `  ℹ️  ${tool_dir}: ${skipped} rule(s) skipped — byte-identical twin already installed at user scope`,
+            );
         }
     }
 
@@ -2276,7 +2353,7 @@ function _print(line: string): void {
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
     if (!_exists(MODULE_STATE.SOURCE_DIR) && !_any_source_root_exists()) {
         _print(
-            `❌  No source directory found (looked at ${MODULE_STATE.SOURCE_DIR} and packages/*/.agent-src.uncondensed)`,
+            `❌  No source directory found (looked at the artefact roots under src/ and ${MODULE_STATE.SOURCE_DIR})`,
         );
         return 1;
     }
@@ -2292,25 +2369,17 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     } else if (arg === '--changed') {
         const changed = list_changed_md(MODULE_STATE.SOURCE_DIR);
         if (changed.length === 0) {
-            _print('✅  No .md files changed since last condensation');
+            _print('✅  Every .md projection matches its source');
             return 0;
         }
-        _print(`📝  ${changed.length} .md files changed since last condensation:\n`);
+        _print(`📝  ${changed.length} .md projection(s) out of date — run 'task sync':\n`);
         for (const f of changed) {
             _print(`  ${f}`);
         }
-    } else if (arg === '--mark-done') {
-        if (argv.length < 2) {
-            _print('Usage: python scripts/condense.py --mark-done <relative-path>');
-            return 1;
-        }
-        mark_done(argv[1] as string);
-    } else if (arg === '--mark-all-done') {
-        mark_all_done();
     } else if (arg === '--check') {
         const [missing, stale] = check_sync(MODULE_STATE.SOURCE_DIR, MODULE_STATE.TARGET_DIR);
         if (missing.length === 0 && stale.length === 0) {
-            _print('✅  dist/agent-src/ is in sync with .agent-src.uncondensed/');
+            _print('✅  dist/agent-src/ is in sync with the artefact roots under src/');
             return 0;
         }
         if (missing.length > 0) {
@@ -2325,70 +2394,28 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
                 _print(`  ${f}`);
             }
         }
-        _print(`\nRun 'task sync' to fix non-.md files, then ask the agent to condense .md files.`);
+        _print(`\nRun 'task sync' — the projection is a deterministic copy, so it needs no agent step.`);
         return 1;
     } else if (arg === '--sync') {
-        _print(`Source: ${MODULE_STATE.SOURCE_DIR}`);
+        // SOURCE_DIR is the pre-ADR-051 single root, kept only as a fallback probe;
+        // the real inputs are the artefact roots the multi-root iterator walks.
+        _print(`Source: the artefact roots under src/`);
         _print(`Target: ${MODULE_STATE.TARGET_DIR}\n`);
         _print('--- Syncing non-.md files ---');
         const copied = sync_non_md(MODULE_STATE.SOURCE_DIR, MODULE_STATE.TARGET_DIR);
         _print(`\n--- Cleanup stale files ---`);
         const deleted = cleanup_stale(MODULE_STATE.SOURCE_DIR, MODULE_STATE.TARGET_DIR);
-        const hashes = load_hashes();
-        const stale_keys = Object.keys(hashes).filter((k) => _resolve_source(k) === null);
-        for (const k of stale_keys) {
-            delete hashes[k];
-        }
-        if (stale_keys.length > 0) {
-            save_hashes(hashes);
-            _print(`  Cleaned ${stale_keys.length} stale hash entries`);
-        }
         const changed = list_changed_md(MODULE_STATE.SOURCE_DIR);
         _print(`\n✅  Done: ${copied} copied, ${deleted} stale deleted`);
         if (changed.length > 0) {
-            _print(`📝  ${changed.length} .md files need condensation (run --changed to see them)`);
+            // --sync writes .md itself, so anything still stale here is a bug in
+            // the projector, not work left for a follow-up step.
+            _print(`❌  ${changed.length} .md projection(s) still out of date after sync (run --changed)`);
         } else {
-            _print(`✅  All .md files are up to date`);
+            _print(`✅  Every .md projection matches its source`);
         }
         _print(`\n--- Projecting dist/agent-src/ → .augment/ ---`);
         project_to_augment();
-    } else if (arg === '--check-hashes') {
-        let has_issues = false;
-        const changed = list_changed_md(MODULE_STATE.SOURCE_DIR);
-        const stale = find_stale_hashes(MODULE_STATE.SOURCE_DIR);
-
-        if (stale.length > 0) {
-            has_issues = true;
-            _print(`⚠️  ${stale.length} stale hash(es) for deleted source files:\n`);
-            for (const f of stale) {
-                _print(`  ${f}`);
-            }
-            _print(`\nRun 'task sync-clean-hashes' to remove them.\n`);
-        }
-
-        if (changed.length > 0) {
-            has_issues = true;
-            _print(`❌  ${changed.length} .md file(s) need recondensation:\n`);
-            for (const f of changed) {
-                const stored = load_hashes()[f];
-                const reason = stored === undefined ? 'no hash stored' : 'hash mismatch';
-                _print(`  ${f}  (${reason})`);
-            }
-            _print(`\nRun '/condense' command to recondense these files.`);
-        }
-
-        if (!has_issues) {
-            _print('✅  All condensation hashes are clean (no stale, no mismatches)');
-            return 0;
-        }
-        return 1;
-    } else if (arg === '--clean-hashes') {
-        const count = clean_stale_hashes(MODULE_STATE.SOURCE_DIR);
-        if (count) {
-            _print(`✅  Removed ${count} stale hash(es)`);
-        } else {
-            _print('✅  No stale hashes found');
-        }
     } else if (arg === '--generate-tools') {
         generate_tools();
     } else if (arg === '--clean-tools') {
@@ -2397,7 +2424,7 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         project_to_augment();
     } else {
         _print(
-            'Usage: python scripts/condense.py [--sync|--list|--changed|--check|--check-hashes|--clean-hashes|--mark-done <path>|--mark-all-done|--generate-tools|--clean-tools|--project-augment]',
+            'Usage: condense [--sync|--list|--changed|--check|--generate-tools|--clean-tools|--project-augment]',
         );
         return 1;
     }