@event4u/agent-config 16.2.0 → 16.3.0

package/src/scripts/_dispatch.bash

@@ -238,7 +238,11 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   roadmap:set-step           Flip ONE checkbox glyph safely (lock + line anchor +
                              live invariant + survival check)
   roadmap:archive            Archive completed roadmaps (branch-touched by default;
-                             --all for every complete one; --dry-run to preview)
+                             --all for every complete one; --dry-run to preview;
+                             bare [~] steps are carried to a follow-up first,
+                             --no-carry to leave them blocking; owner-blocked
+                             steps ask first; --owner-decision later --only <x>
+                             parks that one roadmap)
   stubs:due                  Read-only: roadmap stubs past their `review_by:`
                              date, plus the decisions routed to the owner.
                              Writes nothing. Flags: --json, --counts,
@@ -342,7 +346,9 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   memory:check-proposal      Run the admission gate on a memory proposal
   memory:learn               Aggregate memory intake signals into the local learning
                              sidecar (read-only; --write to emit). Usage: memory:learn [--intake-dir DIR]
-                             [--out-dir DIR] [--now ISO] [--write] [--format text|json]
+                             [--out-dir DIR] [--now ISO] [--write] [--format text|json|status]
+                             --format status prints the one-screen human view (verdict counts,
+                             top preferred lessons, the hand-off); it refuses --write.
   analytics                  Local-only workspace analytics (emit|show|prune|migrate).
                              Usage: analytics show [--window 30d|7d|24h] · analytics prune
   knowledge                  Global knowledge-card store (list|show|trace|forget|promote|
@@ -1456,7 +1462,15 @@ cmd_prune() {
 # `agent-config doctor` — read-only drift report against the manifest.
 # Surfaces missing / modified / foreign files. Exit 0 clean, 1 drift,
 # 2 manifest-absent. See scripts/_cli/cmd_doctor.ts.
+# `doctor neighbours` routes to its own entry point rather than a branch inside
+# cmd_doctor.ts, which is 2,000 lines over the source-size ceiling and cannot
+# grow. Routed here because the dispatcher is where verbs are already resolved.
 cmd_doctor() {
+  if [[ "${1:-}" == "neighbours" ]]; then
+    shift
+    exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_doctor_neighbours.ts" "$@"
+    return
+  fi
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_doctor.ts" "$@"
 }
 

package/src/scripts/_lib/agent_settings.ts

@@ -305,6 +305,17 @@ export const MERGEABLE_KEYS: readonly string[] = [
     // GUI; whitelisting decides only whether the value SURVIVES the merge
     // (ADR-271, road-to-design-intent-conformance 2.3).
     'design.fidelity_mode',
+    // `lean_projection.*` is a per-MACHINE setting and the install it governs is
+    // a user-scope one: the layer being thinned is `~/.claude/rules`, which
+    // belongs to the machine and not to any checkout. Without these two rows a
+    // consumer who wrote the opt-in into the user-global file got no error, no
+    // warning and no effect — the same silent-filter defect the two entries
+    // above repair, reaching a third key, and unsatisfiable-by-construction on
+    // an ADR-020 global-only install, where no project layer exists to carry it.
+    // Whitelisting decides only whether a value SURVIVES the merge: it sets
+    // nothing, and `installerThinsHost` still refuses a template-only value.
+    'lean_projection.mode',
+    'lean_projection.hosts',
 ];
 
 /** The shipped template, relative to the package root. */

package/src/scripts/_lib/claude_settings_hooks.ts

@@ -98,16 +98,18 @@ export function build_claude_hook_matrix(manifest_path: string): ClaudeHookMatri
     const aliasesAll = (manifest['native_event_aliases'] ?? {}) as Record<string, unknown>;
     const aliases = ((aliasesAll['claude'] ?? {}) as Record<string, unknown>) || {};
 
-    const ac_to_native: Record<string, string> = {};
-    for (const [native, ac] of Object.entries(aliases)) {
-        ac_to_native[String(ac)] = native;
-    }
-
+    // Iterating the ALIAS map, not the event map, because the relation is
+    // many-natives-to-one-event and the inversion this replaced silently lost
+    // every native but the last. `PostToolUse` and `PostToolUseFailure` both
+    // lower to `post_tool_use`; building `ac_to_native` would have kept one of
+    // them and UNBOUND the other, turning a routing fix into a routing
+    // regression that no existing test could see. Pinned by
+    // `before_complete_failure_envelope.test.ts` ("both natives stay bound").
     const matrix: ClaudeHookMatrix = {};
-    for (const [ac_event, concerns] of Object.entries(claude_events)) {
+    for (const [native, ac_raw] of Object.entries(aliases)) {
+        const ac_event = String(ac_raw);
+        const concerns = claude_events[ac_event];
         if (!concerns || (Array.isArray(concerns) && concerns.length === 0)) continue;
-        const native = ac_to_native[ac_event];
-        if (native === undefined) continue;
         // Bundle fast path (road-to-hook-latency-repair Phase 2): invoke the
         // precompiled dispatcher bundle directly — no bash shim, no CLI boot
         // (measured ~450-500 ms CLI vs ~110 ms bundle per event on a 1-vCPU

package/src/scripts/_lib/estate_offsets.ts

@@ -0,0 +1,241 @@
+/**
+ * How a CHANGE touches the roadmap estate — the diff half, read once.
+ *
+ * `check_estate_count` answers two different questions with two different
+ * inputs. The count half reads the TREE and ratchets it against the base ref's
+ * tree. This module is the other half: it reads the DIFF and says what the
+ * change did — which roadmaps entered the active top level, which left it, which
+ * of the arrivals declared an exemption, and what that exemption says.
+ *
+ * WHY IT LIVES HERE AND NOT IN THE GATE. `check_source_size_budget` scores
+ * `Σ max(0, lines(f) − 1500)` over `src/**` and the gate crossed the ceiling
+ * when the exemption-shape work landed. That gate does not object to new code;
+ * it objects to new code in the file that is already too big to read, and the
+ * ratchet was right about which file that was. The seam it forced is the one a
+ * reader would draw anyway — tree-reading on one side of it, diff-reading on the
+ * other — so the extraction is a correction rather than a concession.
+ *
+ * `exemptionReason` sits here rather than beside the vocabulary it feeds
+ * (`exemption_shape.ts`) because this is the module that READS a change; that
+ * one is the module that JUDGES a reason. The split is read-then-judge, and
+ * keeping it means the vocabulary module imports no filesystem and no git.
+ */
+import * as path from 'node:path';
+
+import {
+    is_roadmap_candidate as isRoadmapCandidate,
+    parse_frontmatter as parseFrontmatter,
+} from '../../agent-src/scripts/update_roadmap_progress.js';
+
+/** How a change touched the active roadmap tree, as git reports it. */
+export interface OffsetLedger {
+    /** Files that entered the active top level: new files, and un-parked ones. */
+    added: string[];
+    /** Files that left it: deleted, archived, parked or merged away. */
+    offsets: string[];
+    /** Added files carrying an `estate_offset_exempt:` reason, with the reason. */
+    exempt: Array<{ file: string; reason: string }>;
+    /**
+     * The subset of `offsets` that went to `later/`.
+     *
+     * Tracked separately because parking is the one offset that RAISES another
+     * gated count: active falls by one and later rises by one, which under an
+     * exact floor is growth in `later_roadmaps` unless this allowance exists.
+     * Kept out of a general "any offset raises any allowance" rule on purpose —
+     * an archived roadmap must not buy a new `later/` file.
+     */
+    parked: string[];
+}
+
+/** An `estate_growth_exempt:` reason ADDED to a roadmap in this change. */
+export interface GrowthClaim {
+    /** The roadmap the claim was added to, as git reports the path. */
+    file: string;
+    reason: string;
+}
+
+/** `agents/roadmaps/<name>.md` — the active top level. code-comment-allow provenance-comment -- operand, not provenance */
+function isActiveTopLevel(rel: string): boolean {
+    const norm = rel.split(path.sep).join('/');
+    if (!norm.startsWith('agents/roadmaps/') || !norm.endsWith('.md')) {
+        return false;
+    }
+    const tail = norm.slice('agents/roadmaps/'.length);
+    return !tail.includes('/') && isRoadmapCandidate(norm);
+}
+
+/**
+ * A disposition directory — where an offset sends a roadmap.
+ *
+ * `stubs/` is in the set, and it was missing from the first version. Un-stubbing
+ * is the documented promotion path, so a stub moved to the top level is an
+ * ADDITION that T3 must charge, and a roadmap demoted to a stub is an offset.
+ * With `stubs/` unrecognised, a promotion was classified as neither and the lint
+ * could never charge it — the one hole that let an active roadmap arrive for free.
+ */
+function isDisposed(rel: string): boolean {
+    const norm = rel.split(path.sep).join('/');
+    return /^agents\/roadmaps\/(archive|later|skipped|stubs)\//.test(norm);
+}
+
+/** A roadmap parked for later — the one disposition that grows another count. */
+function isParked(rel: string): boolean {
+    return rel.split(path.sep).join('/').startsWith('agents/roadmaps/later/');
+}
+
+/**
+ * Read the exemption reason a newly added roadmap declares, if any.
+ *
+ * The key lives in the file's own frontmatter rather than in a config or a
+ * commit trailer, for the reason `RATCHET_RESET_KEY` gives for living inside the
+ * baseline JSON: the claim then shows up in the diff of the change that makes
+ * it, and a reviewer sees it without being told to look.
+ *
+ * THE BLOCK SCALAR IS READ HERE AND NOT BY `parseFrontmatter`, which is a flat
+ * line parser with no YAML block support: it returns the value as everything
+ * after the first colon. Measured 2026-10-01 across the three roadmap trees,
+ * **38 of 221 exemptions are written `estate_offset_exempt: >-` with the reason
+ * indented beneath**, and for every one of them this function used to return
+ * the literal two-character string `>-`. That is non-empty, so the gate
+ * accepted it — a key whose whole purpose is that a reviewer sees the claim was
+ * being checked against a YAML punctuation mark on one file in six. The fix
+ * belongs here rather than in the shared parser because every other caller of
+ * that parser reads single-token values (`status`, `complexity`) where block
+ * support buys nothing and a rewrite risks the dashboard.
+ */
+export function exemptionReason(text: string): string | null {
+    const block = blockScalar(text, 'estate_offset_exempt');
+    if (block !== null) return block === '' ? null : block;
+    const fm = parseFrontmatter(text);
+    const raw = (fm as Record<string, unknown>)['estate_offset_exempt'];
+    if (typeof raw !== 'string') {
+        return null;
+    }
+    const reason = raw.trim().replace(/^["']|["']$/g, '').trim();
+    return reason === '' ? null : reason;
+}
+
+/**
+ * The folded body of `<key>: >-` / `<key>: |`, or `null` when not that form.
+ *
+ * Returns `''` — not `null` — for a block header with no body, so the caller can
+ * tell "declared and empty" from "not a block scalar". An empty block is the
+ * blank-reason case the key already refuses, and collapsing it into `null` here
+ * would send it back to the flat parser, which would hand back `>-` and accept it.
+ */
+function blockScalar(text: string, key: string): string | null {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (m === null) return null;
+    const lines = (m[1] as string).split(/\r?\n/);
+    const head = new RegExp(`^${key}:[ \\t]*(.*)$`);
+    for (let i = 0; i < lines.length; i += 1) {
+        const hm = head.exec(lines[i] as string);
+        if (hm === null) continue;
+        // Only the block indicators. A quoted or bare value is the flat form and
+        // stays with the flat parser, which already handles it.
+        //
+        // THE TRAILING COMMENT IS PART OF THE HEADER, and omitting it was a
+        // BYPASS rather than a parse gap. `estate_offset_exempt: >- # offset`
+        // failed this test, fell through to the flat parser, and came back as
+        // the string `">- # offset"` — which the shape rule then searched for a
+        // disposition word and found one, IN THE COMMENT, over a body it never
+        // read. The indicator may also be written `>2-` as well as `>-2`, so
+        // both orders are accepted; an indentation indicator is never `0`.
+        if (!/^[>|](?:[1-9][-+]?|[-+]?[1-9]?)(?:[ \t]+#.*)?$/.test((hm[1] as string).trim())) return null;
+        const body: string[] = [];
+        for (let j = i + 1; j < lines.length; j += 1) {
+            const line = lines[j] as string;
+            if (line.trim() === '') continue;
+            // The first unindented line ends the block — the next key.
+            if (!/^[ \t]/.test(line)) break;
+            body.push(line.trim());
+        }
+        return body.join(' ').replace(/\s+/g, ' ').trim();
+    }
+    return null;
+}
+
+/**
+ * Classify the change's effect on the active roadmap tree.
+ *
+ * Renames carry information a name-only diff loses: `road-to-x.md` →
+ * `archive/road-to-x.md` is the wanted direction and counts as an offset, while
+ * `later/road-to-x.md` → `road-to-x.md` is an un-parking and counts as an
+ * addition. A top-level-to-top-level rename is neither.
+ */
+export function classifyDiff(
+    nameStatus: string,
+    readFile: (rel: string) => string | null,
+): OffsetLedger {
+    const added: string[] = [];
+    const offsets: string[] = [];
+    const exempt: Array<{ file: string; reason: string }> = [];
+    const parked: string[] = [];
+    for (const line of nameStatus.split('\n')) {
+        if (line.trim() === '') continue;
+        const cols = line.split('\t');
+        const status = (cols[0] ?? '').trim();
+        if (status.startsWith('R') || status.startsWith('C')) {
+            const from = cols[1] ?? '';
+            const to = cols[2] ?? '';
+            if (isActiveTopLevel(from) && isDisposed(to)) {
+                offsets.push(from);
+                if (isParked(to)) parked.push(to);
+            } else if (isDisposed(from) && isActiveTopLevel(to)) {
+                added.push(to);
+            }
+            continue;
+        }
+        const file = cols[1] ?? '';
+        if (!isActiveTopLevel(file)) continue;
+        if (status === 'A') {
+            added.push(file);
+        } else if (status === 'D') {
+            offsets.push(file);
+        }
+    }
+    for (const file of added) {
+        const text = readFile(file);
+        if (text === null) continue;
+        const reason = exemptionReason(text);
+        if (reason !== null) {
+            exempt.push({ file, reason });
+        }
+    }
+    return { added, offsets, exempt, parked };
+}
+
+/**
+ * The `estate_growth_exempt:` reasons this change ADDS, read from the patch.
+ *
+ * Read from the diff rather than from the file, and that is the point: a claim
+ * sitting in a roadmap authorises nothing on a later change, so an exemption
+ * cannot be banked the way surplus in a stored baseline could. It also means a
+ * newly added roadmap and an edited one need no separate handling — in a
+ * `base...HEAD` patch both arrive as `+` lines.
+ *
+ * `--unified=0` keeps context lines out, so a claim that merely sits NEAR an
+ * edited line is not read as added. Deliberately tolerant of leading whitespace
+ * and of quoted values, matching `exemptionReason`; deliberately NOT tolerant of
+ * an empty reason, because an exemption whose reason is blank is the silent
+ * exception the key exists to replace.
+ */
+export function growthClaims(patch: string): GrowthClaim[] {
+    const out: GrowthClaim[] = [];
+    let file = '';
+    for (const line of patch.split('\n')) {
+        // `+++ b/<path>` names the file the following `+` lines belong to. The
+        // `/dev/null` form is a deletion, which cannot carry a claim.
+        const head = /^\+\+\+ b\/(.+)$/.exec(line);
+        if (head !== null) {
+            file = (head[1] ?? '').trim();
+            continue;
+        }
+        if (!line.startsWith('+') || line.startsWith('+++')) continue;
+        const m = /^\+\s*estate_growth_exempt:\s*(.+?)\s*$/.exec(line);
+        if (m === null) continue;
+        const reason = (m[1] ?? '').trim().replace(/^["']|["']$/g, '').trim();
+        if (reason !== '') out.push({ file, reason });
+    }
+    return out;
+}

package/src/scripts/_lib/exemption_shape.ts

@@ -0,0 +1,143 @@
+/**
+ * What an `estate_offset_exempt` reason has to SAY — one vocabulary, two readers.
+ *
+ * THE DEFECT THIS EXISTS TO NAME. The one-in-one-out rule charges every added
+ * active roadmap against a disposed one, and `estate_offset_exempt: <reason>`
+ * is the escape hatch that costs "one reviewable line instead of a silent
+ * exception". `exemptionReason` accepted any non-empty string, so the line was
+ * reviewable in the sense that it existed. Measured 2026-10-01 over the active,
+ * `later/` and `archive/` trees: 221 files carry the key, and 43 of them name
+ * no alternative disposition at all under the three-lemma set the roadmap named
+ * from memory, and 6 under the measured one below — including three that say only
+ * `lane N of <parent>`. The escape hatch was free.
+ *
+ * WHAT A SHAPED REASON SAYS. It names at least one disposition the author
+ * considered instead of adding a file: archiving something, parking it in
+ * `later/`, merging into an existing roadmap, or any of the words this tree
+ * actually uses for those three. The requirement is deliberately NOT "explain
+ * yourself well" — that is unjudgeable — but "name what you rejected", which is
+ * a word that is either present or absent.
+ *
+ * WHY THE VOCABULARY IS MEASURED AND NOT CHOSEN. The commissioning roadmap
+ * named three lemmas, archive / park / merge, from memory. Over the real
+ * population those three cover 178 of 221; the measured ten below cover 215.
+ * The 37-file gap is not boilerplate — "Offsetting it individually is not
+ * possible without splitting the set" and "no completed roadmap to retire
+ * against this addition" both name a rejected alternative in words the
+ * three-lemma set does not carry. A refusal vocabulary that reds one added
+ * roadmap in five on the house style gets weakened until it finds nothing, so
+ * the set here is the one the tree writes. Every number above carries its
+ * producing command: `./scripts-run src/scripts/estate_exemption_shape`.
+ *
+ * `close` is excluded on purpose, and it is the most common verb in these
+ * reasons: it almost always refers to closing WORK, not to disposing of a file,
+ * so accepting it would make the check pass on a sentence that named nothing.
+ *
+ * WHAT THIS DOES NOT DO, stated because a reviewer called it HIGH and the
+ * disagreement is worth recording rather than resolving silently. The cheapest
+ * string that passes is the single word `park`, and `park 1` / `park 2` are two
+ * distinct reasons to the duplicate rule. So this verifies that a disposition
+ * word APPEARS; it does not verify that the author thought about one, and no
+ * check can. The claim the gate's message makes is therefore "name what you
+ * rejected", which is what a word either does or does not do — not "explain
+ * yourself well", which is unjudgeable. A reason gamed down to one word is
+ * visible to a human reviewer in the diff, which is where the key's own stated
+ * purpose puts the real control; what this removes is the case where there was
+ * nothing to look at because the reason was free text nobody had read.
+ *
+ * WHY ONE MODULE. Two readers consume this — the estate gate, which refuses,
+ * and the measurement script, which reports. A second copy of the lemma list is
+ * how a gate and its own evidence drift apart, and a drifted vocabulary fails
+ * silently: the report says the tree conforms while the gate refuses it.
+ */
+
+/**
+ * The dispositions a reason may name, as source strings.
+ *
+ * Exported individually rather than as one baked regex so the measurement
+ * script can report per-lemma counts against the same list the gate refuses on.
+ */
+export const DISPOSITION_LEMMAS: readonly { readonly name: string; readonly source: string }[] = [
+    { name: 'archive', source: String.raw`archiv\w*` },
+    // `park` is the one stem with a common false friend, and a reviewer named
+    // it: `park\w*` matches `parkour` at a word boundary, so a reason saying
+    // nothing about dispositions passes on a word that is not one. Enumerated
+    // instead of stemmed — the inflections this tree writes, and no more. Every
+    // other lemma keeps its stem; none of them has a false friend in English
+    // that could plausibly appear in a sentence about roadmap dispositions.
+    { name: 'park', source: String.raw`unpark(?:ed|ing|s)?\b|park(?:ed|ing|s)?\b` },
+    { name: 'merge', source: String.raw`merg\w*` },
+    { name: 'later', source: String.raw`later\/` },
+    { name: 'offset', source: String.raw`offset\w*` },
+    { name: 'defer', source: String.raw`defer\w*` },
+    { name: 'fold', source: String.raw`fold\w*` },
+    { name: 'consolidate', source: String.raw`consolidat\w*` },
+    { name: 'absorb', source: String.raw`absorb\w*` },
+    { name: 'retire', source: String.raw`retir\w*` },
+];
+
+/** The whole vocabulary as one alternation — the gate's own test. */
+export const DISPOSITION_SOURCE = `\\b(?:${DISPOSITION_LEMMAS.map((l) => l.source).join('|')})`;
+
+const DISPOSITION_RE = new RegExp(DISPOSITION_SOURCE, 'i');
+
+/** Does this reason name at least one rejected alternative? */
+export function namesDisposition(reason: string): boolean {
+    return DISPOSITION_RE.test(reason);
+}
+
+/** Which lemmas a reason names, for the reader's per-file column. */
+export function lemmasNamed(reason: string): string[] {
+    return DISPOSITION_LEMMAS.filter((l) => new RegExp(`\\b(?:${l.source})`, 'i').test(reason)).map((l) => l.name);
+}
+
+/**
+ * The comparison key for "two added files say the same thing".
+ *
+ * Case and whitespace are folded because a reason pasted into a second file and
+ * re-wrapped by an editor is the same reason. Nothing else is folded: a reason
+ * that differs by one clause is a different reason, and a normaliser clever
+ * enough to call those equal would start refusing reasons that genuinely differ.
+ */
+export function reasonKey(reason: string): string {
+    return reason.toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+/** One added file whose exemption reason does not hold up. */
+export interface ExemptionFinding {
+    readonly file: string;
+    readonly kind: 'shapeless' | 'duplicate';
+    /** For `duplicate`, the other added file carrying the same reason. */
+    readonly twin: string | null;
+    readonly reason: string;
+}
+
+/**
+ * Judge the exemptions a single change ADDS — never the ones already in the tree.
+ *
+ * Grandfathering is load-bearing rather than polite. 43 of the 221 existing
+ * reasons name no disposition; re-reading them would land this check red on a
+ * fifth of the corpus, which is a backlog wearing a control's clothes. The
+ * input is `classifyDiff`'s exempt ledger, which by construction lists only the
+ * files this change added.
+ */
+export function exemptionFindings(
+    exempt: readonly { readonly file: string; readonly reason: string }[],
+): ExemptionFinding[] {
+    const out: ExemptionFinding[] = [];
+    const seen = new Map<string, string>();
+    for (const e of exempt) {
+        if (!namesDisposition(e.reason)) {
+            out.push({ file: e.file, kind: 'shapeless', twin: null, reason: e.reason });
+            continue;
+        }
+        const key = reasonKey(e.reason);
+        const twin = seen.get(key);
+        if (twin === undefined) {
+            seen.set(key, e.file);
+            continue;
+        }
+        out.push({ file: e.file, kind: 'duplicate', twin, reason: e.reason });
+    }
+    return out;
+}

package/src/scripts/_lib/fnv.ts

@@ -0,0 +1,23 @@
+/**
+ * FNV-1a, 32-bit — the one definition in this tree.
+ *
+ * Extracted from `rule_trigger_eval.ts`, which still re-exports it under its
+ * own name so its suite keeps importing the symbol it always did. The reason
+ * for the extraction is the reason this file carries a doc block at all: a
+ * second consumer arrived (`measure_skill_ranker_baseline`'s held-out
+ * partition), and two copies of a hash that decides which rows a measurement
+ * reads is the shape in which a partition quietly stops being the same
+ * partition. One definition, two callers.
+ *
+ * Pure — no imports, no I/O, no clock.
+ */
+
+/** FNV-1a over UTF-16 code units, returned as an unsigned 32-bit integer. */
+export function fnv1a(s: string): number {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i += 1) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h >>> 0;
+}

package/src/scripts/_lib/foreign_scan.ts

@@ -0,0 +1,106 @@
+/**
+ * The unclaimed-file scan under this package's own deploy roots.
+ *
+ * Moved verbatim out of `src/scripts/_cli/cmd_doctor.ts`
+ * (road-to-a-tree-that-keeps-its-neighbours Phase 2.6). The behaviour is
+ * unchanged — this is a module boundary, not a rewrite.
+ *
+ * Two reasons it earns its own file. `cmd_doctor.ts` is 2,100 lines above the
+ * `check_source_size_budget` ceiling, so the census line that now links this
+ * listing is paid for by a MOVE rather than by raising the tree-wide excess.
+ * And the neighbour census answers a strictly larger question than this scan
+ * does — this one lists FILES under paths this package deploys to, the census
+ * lists ARTEFACTS wherever a host keeps them — so the two belong beside each
+ * other rather than nested inside a doctor renderer.
+ *
+ * What this scan does NOT do, stated because the two listings look alike: it
+ * never leaves a deploy root, so a neighbour's skill in `~/.claude/skills` or
+ * hook entry in `.cursor/hooks.json` is invisible to it. That gap is the
+ * census's subject, and the census links back here rather than repeating the
+ * paths this one already prints.
+ */
+
+import * as fs from 'node:fs';
+
+/**
+ * `Path.rglob("*")` — every descendant path (dirs + files), recursively.
+ *
+ * Order is not relied upon by callers (they sort the matched set), but the
+ * walk is deterministic (sorted per directory) to keep behaviour stable.
+ */
+export function rglob(root: string, isDir: (p: string) => boolean, join: (a: string, b: string) => string): string[] {
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const ent of entries) {
+            const full = join(dir, ent.name);
+            out.push(full);
+            let dirLike = ent.isDirectory();
+            if (ent.isSymbolicLink()) {
+                // pathlib rglob follows into symlinked dirs.
+                dirLike = isDir(full);
+            }
+            if (dirLike) {
+                walk(full);
+            }
+        }
+    };
+    walk(root);
+    return out;
+}
+
+export interface ForeignScanDeps {
+    pathExists: (p: string) => boolean;
+    isDir: (p: string) => boolean;
+    isFile: (p: string) => boolean;
+    resolvePath: (p: string) => string;
+    join: (a: string, b: string) => string;
+    /** Resolve one declared deploy root against the consumer root. */
+    resolveRoot: (projectRoot: string, rel: string) => string;
+    defaultRoots: readonly string[];
+}
+
+/**
+ * Walk every declared deploy root and surface unclaimed files. Only regular
+ * files under `deploy_roots` count; bookkeeping is on the resolved final path.
+ */
+export function scanForeign(
+    projectRoot: string,
+    manifest: Record<string, unknown>,
+    known: Set<string>,
+    deps: ForeignScanDeps,
+): string[] {
+    const roots = (manifest['deploy_roots'] as unknown[] | undefined) || Array.from(deps.defaultRoots);
+    const foreign: string[] = [];
+    const seen = new Set<string>();
+    for (const root_rel of roots) {
+        const root = deps.resolveRoot(projectRoot, String(root_rel));
+        if (!deps.pathExists(root) || !deps.isDir(root)) {
+            continue;
+        }
+        for (const child of rglob(root, deps.isDir, deps.join)) {
+            if (!deps.isFile(child)) {
+                continue;
+            }
+            let resolved: string;
+            try {
+                resolved = deps.resolvePath(child);
+            } catch {
+                resolved = child;
+            }
+            if (known.has(resolved) || seen.has(resolved)) {
+                continue;
+            }
+            seen.add(resolved);
+            foreign.push(child);
+        }
+    }
+    foreign.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return foreign;
+}