@event4u/agent-config 16.2.0 → 16.4.0

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_analyze_session.ts

@@ -12,10 +12,10 @@
  *        - `changes`  — files touched (array of {kind, stack, file, summary}).
  *        - `outcomes` — directive → "success" / "blocked" / … .
  *        - `halts`    — array of recorded halts.
- *   2. `agents/runtime/state/context-hygiene.json` — fields read:
+ *   2. the context-hygiene hook's state file (`STATE_FILE`, imported from
+ *      `context_hygiene_hook.ts` rather than spelled here — two independent
+ *      spellings of this path drifted apart before). Fields read:
  *        - `tool_calls`           (int)
- *        - `consecutive_same_tool`(int)
- *        - `loop_detected`        (bool)
  *
  * There is NO general token/cost data source in this package (only
  * video-specific telemetry), so the report deliberately does NOT report
@@ -33,18 +33,16 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { ProjectRootError, resolve_project_root } from '../_lib/agent_settings.js';
+import { STATE_FILE as HYGIENE_STATE_FILE } from '../context_hygiene_hook.js';
 import { StateLoadError, load_state } from './explain_last/state_loader.js';
 
 type Dict = Record<string, unknown>;
 
 const _HERE = fileURLToPath(import.meta.url);
 
-const CONTEXT_HYGIENE_RELATIVE = path.join(
-    'agents',
-    'runtime',
-    'state',
-    'context-hygiene.json',
-);
+// Imported from the hook rather than spelled here — the hook is the writer,
+// so it is the single source of truth for the path it writes to.
+const CONTEXT_HYGIENE_RELATIVE = HYGIENE_STATE_FILE;
 
 /** Python `raise SystemExit(code)` analogue — propagates an explicit code. */
 class SystemExitError extends Error {
@@ -196,11 +194,7 @@ export function render_report(state: Dict, hygiene: Dict | null): string {
         lines.push('_Context-hygiene snapshot not available._');
     } else {
         const toolCalls = intOrUnknown(hygiene['tool_calls']);
-        const consecutive = intOrUnknown(hygiene['consecutive_same_tool']);
-        const loop = hygiene['loop_detected'] === true;
         lines.push(`- Tool calls: ${toolCalls}`);
-        lines.push(`- Consecutive same-tool calls: ${consecutive}`);
-        lines.push(`- Loop detected: ${loop ? 'yes' : 'no'}`);
     }
     lines.push('');
 
@@ -253,8 +247,8 @@ Sources read:
     · changes  — files touched
     · outcomes — per-directive success / blocked
     · halts    — recorded halts
-  agents/runtime/state/context-hygiene.json
-    · tool_calls · consecutive_same_tool · loop_detected
+  agents/state/context-hygiene.json
+    · tool_calls
 
 Token/cost is NOT reported — this package has no per-session token
 source (only video-specific telemetry).

package/src/scripts/_cli/cmd_conformance.ts

@@ -42,6 +42,7 @@ import { atomicAppendLine } from '../../install/atomic.js';
 import { readRecentEntries } from '../../install/txlog.js';
 import { detectToolPresence } from '../../install/detect.js';
 import { resolvePackageRoot } from '../_lib/package_root.js';
+import { THIN_ENTRY_MARKER } from '../_lib/thin_rules.js';
 import { routeTargetPathsPosix } from '../router_target_paths.mjs';
 import { buildFunnel, render as renderFunnel } from '../report_conformance_funnel.js';
 import {
@@ -74,8 +75,18 @@ export const CONFORMANCE_CHECK_IDS = [
     'host-manifest',
 ] as const;
 
-/** Marker emitted by `project_thin_rules.thin_entry()` — the thin-stub signature. */
-export const THIN_STUB_MARKER = 'Routed rule — load the body on trigger-match';
+/**
+ * Marker emitted by `project_thin_rules.thin_entry()` — the thin-stub signature.
+ *
+ * RE-EXPORTED, NEVER RE-SPELLED — step 2.1 of
+ * `road-to-a-thinned-layer-measured-in-one-unit`. This was its own literal, a
+ * substring of the writer's constant without the blockquote prefix and the full
+ * stop, which is exactly the drift `THIN_ENTRY_MARKER`'s own docstring warns
+ * about: shorten the writer and this detector keeps matching the old sentence,
+ * silently, in the direction where a stub it fails to recognise reads as a
+ * complete rule body. The name stays so existing callers are unchanged.
+ */
+export const THIN_STUB_MARKER = THIN_ENTRY_MARKER;
 
 /**
  * Rendering symbols for this verb's rows — doctor's table plus `unknown`.

package/src/scripts/_cli/cmd_doctor.ts

@@ -114,7 +114,7 @@ import {
     resolve_project_root,
     type TraceRecord,
 } from '../_lib/agent_settings.js';
-import { executionJson, forgeProtectionJsonFor } from './doctor_execution.js';
+import { executionJson, forgeDepsFor, forgeProtectionJsonFor, type ForgeDeps } 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';
@@ -134,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,
@@ -617,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.
@@ -3003,7 +2945,7 @@ function _run_no_manifest(
         checks.some((c) => c['id'] === opts.check && c['status'] === 'skipped');
 
     if (opts.json) {
-        _emit_json(project_root, [], [], [], [], checks, origin);
+        _emit_json(project_root, [], [], [], [], checks, origin, forgeDepsFor(opts));
     } else if (opts.check === null) {
         print(`  📍  project_root: ${project_root} (origin: ${origin})`);
         if (bridge_present) {
@@ -3028,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) {
@@ -3051,7 +2998,7 @@ function _emit_json(
     foreign: Dict[],
     tag_drift: Dict[],
     checks: Dict[] | null = null,
-    origin: string | null = null,
+    origin: string | null = null, forge: ForgeDeps = {},
 ): void {
     const payload: Dict = {
         project_root: String(project_root),
@@ -3062,7 +3009,7 @@ function _emit_json(
     };
     if (origin !== null) payload['project_root_origin'] = origin;
     payload['execution'] = executionJson(() => iter_setting_overrides({ cwd: project_root }));
-    payload['forge_protection'] = forgeProtectionJsonFor(String(project_root)); // 3.2 · AC-5
+    payload['forge_protection'] = forgeProtectionJsonFor(String(project_root), forge); // 3.2 · AC-5
     payload['traffic_environment'] = trafficEnvironmentJson(process.env);
     if (checks !== null) {
         payload['checks'] = checks;
@@ -3119,7 +3066,7 @@ interface Options {
     ci: boolean;
     strict: boolean; strict_level: string; // see `_doctor_strict.ts`
     check: string | null;
-    trace_root: boolean;
+    trace_root: boolean; no_forge: boolean; online: boolean; // opt-out / opt-in; `forgeDepsFor`
     context: boolean;
     anatomy: boolean;
     repair: string | null;
@@ -3133,14 +3080,14 @@ const PROG = 'agent-config doctor';
 const USAGE =
     `usage: ${PROG} [-h] [--project PROJECT] [--json] [--ci] [--check ID]\n` +
     STRICT_USAGE +
-    '                           [--trace-root] [--context] [--anatomy]\n' +
-    '                           [--repair ID]\n';
+    '                           [--trace-root] [--context] [--anatomy] [--no-forge]\n' +
+    '                           [--online] [--repair ID]\n';
 
 const _STORE_TRUE_FLAGS: Record<string, keyof Options> = {
     '--json': 'json',
     '--ci': 'ci',
     ...STRICT_STORE_TRUE,
-    '--trace-root': 'trace_root',
+    '--trace-root': 'trace_root', '--no-forge': 'no_forge', '--offline': 'no_forge', '--online': 'online',
     '--context': 'context',
     '--anatomy': 'anatomy',
 };
@@ -3165,7 +3112,7 @@ function _parse(argv: string[]): Options {
         ci: false,
         ...STRICT_DEFAULTS,
         check: null,
-        trace_root: false,
+        trace_root: false, no_forge: false, online: false,
         context: false,
         anatomy: false,
         repair: null,
@@ -3443,7 +3390,7 @@ function main(argv: string[] | null = null): number {
     const fail_check = checks.some((c) => c['status'] === 'fail');
 
     if (opts.json) {
-        _emit_json(project_root, missing, modified, foreign, tag_drift, checks, origin);
+        _emit_json(project_root, missing, modified, foreign, tag_drift, checks, origin, forgeDepsFor(opts));
     } else {
         if (opts.check === null) {
             print(`  📍  project_root: ${project_root} (origin: ${origin})`);
@@ -3452,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())));
         }
     }