@event4u/agent-config 16.1.0 → 16.3.0

package/src/install/installedRuleLinks.ts

@@ -0,0 +1,220 @@
+/**
+ * Do the links inside an installed rule file resolve from where the install
+ * puts it?
+ *
+ * A rule body is authored in `src/rules/` and projected to
+ * `dist/agent-src/rules/`, where `](../guidelines/x.md)` resolves because the
+ * sibling directory is right there. The installer then copies a SUBSET of
+ * those sibling directories into the host's rule directory, so the same link
+ * resolves or does not depending on a list in `install.ts` that the rule
+ * author never sees. Nothing checked the two against each other.
+ *
+ * This module answers one question per link — resolved, or why not — against a
+ * deploy plan rather than against a materialised tree, so the audit costs a
+ * `statSync` per distinct target instead of a copy of 299 skills.
+ *
+ * Side-effect-free, no CLI entry, no `process.exit`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Why a link does not resolve from the installed file's own directory. */
+export type LinkVerdict =
+    /** The target file is present in the installed tree. */
+    | 'resolved'
+    /** The link climbs above the install root — a repo-tree path, never shipped. */
+    | 'outside-install-root'
+    /** The first segment names a directory the deploy plan does not write. */
+    | 'directory-not-deployed'
+    /** The directory IS deployed, but the file is not in it. */
+    | 'file-missing';
+
+export interface LinkAudit {
+    /** Rule file the link was written in, as a bare id (no directory, no `.md`). */
+    rule: string;
+    /** The link target exactly as the markdown carries it, anchor included. */
+    target: string;
+    /** Install-root-relative path the target resolves to, or null when it escapes. */
+    resolved_to: string | null;
+    verdict: LinkVerdict;
+}
+
+export interface LinkAuditReport {
+    audits: LinkAudit[];
+    /** Count per verdict, every verdict present even at zero. */
+    counts: Record<LinkVerdict, number>;
+    /** Unresolved links grouped by the first path segment, highest first. */
+    by_directory: { directory: string; count: number; verdict: LinkVerdict }[];
+}
+
+/**
+ * A deploy plan: installed directory name -> the package directory copied into
+ * it. Exactly the shape of one `GLOBAL_DEPLOY_SOURCES` entry, inverted, so a
+ * caller can hand this module the real plan rather than a restatement of it.
+ */
+export type DeployPlan = Map<string, string>;
+
+/**
+ * Build a plan from `GLOBAL_DEPLOY_SOURCES`-shaped pairs.
+ *
+ * The empty destination (`cline` maps rules to the root) is deliberately kept:
+ * a rule installed at the root resolves `../x` differently, and silently
+ * dropping the entry would make this module answer a question about a layout
+ * that is not the one being installed.
+ */
+export function deployPlanFrom(pairs: ReadonlyArray<readonly [string, string]>): DeployPlan {
+    const plan: DeployPlan = new Map();
+    for (const [source, dest] of pairs) plan.set(dest, source);
+    return plan;
+}
+
+/** Markdown inline links, minus the ones that are not a path into the tree. */
+export function relativeLinkTargets(markdown: string): string[] {
+    const out: string[] = [];
+    for (const m of markdown.matchAll(/\]\(([^)\s]+)\)/g)) {
+        const target = m[1] as string;
+        if (/^[a-z][a-z0-9+.-]*:/i.test(target)) continue; // http:, mailto:, etc.
+        if (target.startsWith('#')) continue; // same-file anchor
+        if (target.startsWith('/')) continue; // absolute — not ours to resolve
+        out.push(target);
+    }
+    return out;
+}
+
+/** Strip a trailing `#anchor`; a bare directory link keeps its trailing slash. */
+function withoutAnchor(target: string): string {
+    const hash = target.indexOf('#');
+    return hash === -1 ? target : target.slice(0, hash);
+}
+
+/**
+ * Audit one link written in a rule that the install places at
+ * `<install-root>/<rulesDest>/<rule>.md`.
+ */
+export function auditLink(
+    rule: string,
+    target: string,
+    rulesDest: string,
+    plan: DeployPlan,
+    packageRoot: string,
+): LinkAudit {
+    const bare = withoutAnchor(target);
+    // Resolve the link the way a reader does: from the installed file's own
+    // DIRECTORY — `rulesDest` is that directory, not the file — as a POSIX
+    // path relative to the install root. A sibling link (`[x](other.md)`, no
+    // `../`) therefore stays inside the rules directory, which is where the
+    // installer puts its sibling.
+    const fromDir = rulesDest === '' ? '.' : rulesDest;
+    const resolved = path.posix.normalize(path.posix.join(fromDir, bare));
+
+    if (resolved.startsWith('..')) {
+        return { rule, target, resolved_to: null, verdict: 'outside-install-root' };
+    }
+
+    const segments = resolved.split('/');
+    // Which deployed directory does this land in? Normally the first segment
+    // names it. When rules install at the install ROOT (`cline` maps them to
+    // `''`), there is no such segment: a sibling link like `](scope-control.md)`
+    // resolves to `scope-control.md`, whose first segment is a FILE NAME. Read
+    // literally that is `directory-not-deployed` for a file the install writes
+    // right beside the rule — 275 of cline's 523 links, every one of them fine.
+    // The `''` key exists in the plan precisely for this and could never be
+    // reached by a first-segment lookup.
+    const rootSource = plan.get('');
+    // The root entry answers for a BARE filename only. A link with a directory
+    // segment the plan does not carry is `directory-not-deployed`, the same as
+    // anywhere else — resolving it against the rules source would probe a path
+    // the install never writes and report `file-missing`, whose documented
+    // meaning ("the directory IS deployed") would then be false.
+    const useRoot = rootSource !== undefined && segments.length === 1;
+    const source = useRoot ? rootSource : plan.get(segments[0] as string);
+    const rest = useRoot ? segments : segments.slice(1);
+    if (source === undefined) {
+        return { rule, target, resolved_to: resolved, verdict: 'directory-not-deployed' };
+    }
+
+    // An empty `rest` means the link points at the deployed directory itself.
+    const onDisk = path.join(packageRoot, source, ...rest);
+    const exists = fs.existsSync(onDisk);
+    return {
+        rule,
+        target,
+        resolved_to: resolved,
+        verdict: exists ? 'resolved' : 'file-missing',
+    };
+}
+
+const EMPTY_COUNTS = (): Record<LinkVerdict, number> => ({
+    resolved: 0,
+    'outside-install-root': 0,
+    'directory-not-deployed': 0,
+    'file-missing': 0,
+});
+
+/**
+ * Audit every link in every rule the plan installs.
+ *
+ * `packageRoot` is the package checkout the installer copies FROM; the rule
+ * bodies are read from the plan's own rules source, so the audit cannot drift
+ * from what is shipped.
+ */
+export function auditInstalledRuleLinks(plan: DeployPlan, packageRoot: string): LinkAuditReport {
+    const audits: LinkAudit[] = [];
+    for (const [dest, source] of plan) {
+        if (!source.endsWith('/rules')) continue;
+        const dir = path.join(packageRoot, source);
+        if (!fs.existsSync(dir)) continue;
+        const files = fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => !e.isDirectory() && e.name.endsWith('.md'))
+            .map((e) => e.name)
+            .sort();
+        for (const file of files) {
+            const rule = file.replace(/\.md$/, '');
+            const body = fs.readFileSync(path.join(dir, file), 'utf8');
+            for (const target of relativeLinkTargets(body)) {
+                audits.push(auditLink(rule, target, dest, plan, packageRoot));
+            }
+        }
+    }
+
+    const counts = EMPTY_COUNTS();
+    for (const a of audits) counts[a.verdict] += 1;
+
+    const grouped = new Map<string, { count: number; verdict: LinkVerdict }>();
+    for (const a of audits) {
+        if (a.verdict === 'resolved') continue;
+        const key = a.resolved_to === null ? a.target.replace(/[^/]*$/, '') : (a.resolved_to.split('/')[0] as string);
+        const row = grouped.get(key);
+        if (row) row.count += 1;
+        else grouped.set(key, { count: 1, verdict: a.verdict });
+    }
+    const by_directory = [...grouped.entries()]
+        .map(([directory, v]) => ({ directory, count: v.count, verdict: v.verdict }))
+        .sort((a, b) => b.count - a.count || a.directory.localeCompare(b.directory));
+
+    return { audits, counts, by_directory };
+}
+
+/**
+ * Standing-text cost of the rewrite option, in characters.
+ *
+ * Option A of this roadmap's step 1.2: leave the install plan alone and
+ * rewrite every link to an absolute package path. Each unresolved link then
+ * grows by the absolute prefix minus the `../` it replaces — and it grows
+ * INSIDE a rule body, which is the text the host loads as instructions.
+ *
+ * `prefixChars` is the installed package root's own length, which is a
+ * property of the machine, so the caller supplies it and the report says which
+ * value it used.
+ */
+export function rewriteOptionCost(report: LinkAuditReport, prefixChars: number): number {
+    const unresolved = report.audits.filter((a) => a.verdict !== 'resolved');
+    let total = 0;
+    for (const a of unresolved) {
+        // `../x` and `../../x` both become `<abs>/x`: the climb is replaced.
+        const climb = (a.target.match(/\.\.\//g) ?? []).length * 3;
+        total += prefixChars + 1 - climb;
+    }
+    return total;
+}

package/src/install/wizard-plan.ts

@@ -64,6 +64,30 @@ export const USER_SCOPE_PATHS: Readonly<Record<string, string>> = {
 /**
  * Universal Anthropic-shaped skill bundle deployed to markdown-skills
  * tools. Mirrors `_CLAUDE_SKILL_BUNDLE` in the retired Python installer (ADR-200).
+ *
+ * NOT deploying `contexts/` and `guidelines/` here is a held decision, not an
+ * oversight — see the `rule-link-targets-change-the-frozen-install-abi` blocker
+ * on `road-to-rule-triggers-and-links-that-hold`.
+ *
+ * A rule is authored against the package tree and projected verbatim, so
+ * `](../guidelines/x.md)` resolves in `dist/agent-src/rules/` and then does
+ * not resolve in the install, because this table does not carry those two
+ * directories. Measured by `report_installed_rule_links` on 2026-10-03: 136 of
+ * 523 links in an installed Claude rule directory point nowhere, 112 of them
+ * into exactly those two. Adding them is the cheaper of the two repairs on the
+ * budget that is scarce — 0 standing characters against **5,152** for rewriting
+ * those same 112 links to absolute package paths, at a 48-character install
+ * prefix (the report prints the prefix it used; the figure scales with it).
+ *
+ * The totals were 160 of 550 when this was first measured and 158 of 545 on
+ * 2026-10-02; what fell since is the OTHER population — repo-tree link forms no
+ * install ever held — so the 112 this paragraph is about has not moved.
+ *
+ * It is held because this table is part of the FROZEN install ABI
+ * (`docs/contracts/install-layout.md`), and any change to it owes an
+ * `install_layout_version` bump plus a deprecation window: old and new shape
+ * side by side for a minor cycle, with in-place migration. That is a release
+ * commitment, not an implementation detail, so it is the owner's to make.
  */
 const CLAUDE_SKILL_BUNDLE: ReadonlyArray<readonly [string, string]> = [
     ['dist/agent-src/rules',    'rules'],

package/src/scripts/_cli/cmd_doctor.ts

@@ -114,7 +114,8 @@ import {
     resolve_project_root,
     type TraceRecord,
 } from '../_lib/agent_settings.js';
-import { executionJson, forgeProtectionJson, UNREAD_FORGE } from './doctor_execution.js';
+import { executionJson, forgeProtectionJsonFor } from './doctor_execution.js';
+import { checkOfflineReadiness, trafficEnvironmentJson } from './doctor_network_posture.js';
 import * as ai_council_clients from '../ai_council/clients.js';
 import * as ai_council_config from '../ai_council/config.js';
 import {
@@ -133,6 +134,8 @@ import {
 } from './detection_report.js';
 import { review_gate_doctor_signal } from '../ai_team/review_gate.js';
 import { resolvePackageRoot } from '../_lib/package_root.js';
+import { rglob as _rglob_raw, scanForeign } from '../_lib/foreign_scan.js';
+import { runCensus, summaryLine } from './cmd_doctor_neighbours.js';
 import {
     LEGACY_ALL,
     excludedRuleBasenames,
@@ -616,77 +619,17 @@ function _collect_manifest_entries(
     return [records, known];
 }
 
-/**
- * Walk every declared deploy root and surface unclaimed files. Only regular
- * files under `deploy_roots` count; bookkeeping is on the resolved final path.
- */
-function _scan_foreign(
-    project_root: string,
-    manifest: Dict,
-    known: Set<string>,
-): string[] {
-    const roots =
-        (manifest['deploy_roots'] as unknown[] | undefined) ||
-        Array.from(installed_tools.DEFAULT_DEPLOY_ROOTS);
-    const foreign: string[] = [];
-    const seen = new Set<string>();
-    for (const root_rel of roots) {
-        const root = _resolve_path(project_root, String(root_rel));
-        if (!pathExists(root) || !isDir(root)) {
-            continue;
-        }
-        for (const child of rglob(root)) {
-            if (!isFile(child)) {
-                continue;
-            }
-            let resolved: string;
-            try {
-                resolved = 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;
-}
-
-/**
- * `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.
- */
-function rglob(root: 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 = path.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;
-}
+const rglob = (root: string): string[] => _rglob_raw(root, isDir, path.join);
+const _scan_foreign = (project_root: string, manifest: Dict, known: Set<string>): string[] =>
+    scanForeign(project_root, manifest, known, {
+        pathExists,
+        isDir,
+        isFile,
+        resolvePath,
+        join: path.join,
+        resolveRoot: _resolve_path,
+        defaultRoots: installed_tools.DEFAULT_DEPLOY_ROOTS,
+    });
 
 /**
  * Split manifest records into missing / modified / tag-drift lists.
@@ -1450,23 +1393,7 @@ function _check_mcp_mode(project_root: string): Dict {
     };
 }
 
-function _check_offline_readiness(): Dict {
-    const script = path.join(_package_root(), 'src', 'scripts', 'hermetic-install.sh');
-    if (!pathExists(script)) {
-        return {
-            id: 'offline-readiness',
-            status: 'warn',
-            message: 'src/scripts/hermetic-install.sh not found in package',
-            remedy: 'reinstall @event4u/agent-config or pull missing files',
-        };
-    }
-    return {
-        id: 'offline-readiness',
-        status: 'ok',
-        message: 'verified-offline install entrypoint present',
-        remedy: '',
-    };
-}
+const _check_offline_readiness = (): Dict => checkOfflineReadiness(_package_root());
 
 function _check_stale_orphans(): Dict {
     const gdi = global_deploy_inventory;
@@ -3043,6 +2970,11 @@ function _run_no_manifest(
         _emit_checks_text(checks);
         _emit_detection_text(project_root, checks);
     }
+    // Also on the no-manifest branch: a consumer with no project lockfile
+    // still has neighbours, and a census that appeared only once a lockfile
+    // existed would be missing on exactly the install shape most likely to
+    // have other packages in it.
+    if (opts.check === null && !opts.json) print(summaryLine(runCensus(project_root, _package_root())));
 
     if (opts.check !== null) {
         if (skipped_requested) {
@@ -3077,7 +3009,8 @@ function _emit_json(
     };
     if (origin !== null) payload['project_root_origin'] = origin;
     payload['execution'] = executionJson(() => iter_setting_overrides({ cwd: project_root }));
-    payload['forge_protection'] = forgeProtectionJson(UNREAD_FORGE); // 3.2
+    payload['forge_protection'] = forgeProtectionJsonFor(String(project_root)); // 3.2 · AC-5
+    payload['traffic_environment'] = trafficEnvironmentJson(process.env);
     if (checks !== null) {
         payload['checks'] = checks;
         const drift = missing.length + modified.length + foreign.length + tag_drift.length;
@@ -3466,6 +3399,11 @@ function main(argv: string[] | null = null): number {
         _emit_detection_text(project_root, checks);
         if (opts.check === null) {
             _emit_text(project_root, missing, modified, foreign, tag_drift);
+            // One line, counts only — the `foreign` listing above stays as it
+            // is and nothing is removed from it. That listing walks THIS
+            // package's deploy roots; the census walks where the hosts keep
+            // things, which is a strictly larger question with its own verb.
+            print(summaryLine(runCensus(project_root, _package_root())));
         }
     }