@event4u/agent-config 9.14.0 → 9.16.0

package/src/install/rule_scope.ts

@@ -32,6 +32,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { resolve_rule_pack_scope } from '../scripts/_lib/scoped_projection.js';
 import { rule_in_scope } from './ruleInScope.js';
 
 /**
@@ -67,19 +68,43 @@ function _list(value: unknown): readonly string[] | null {
  * already-parsed settings object (same key contract as condense's
  * `_read_projection_list` — absent / empty = legacy-all).
  */
-export function ruleScopeFromSettings(settings: Record<string, unknown>): RuleScope {
+export function ruleScopeFromSettings(
+    settings: Record<string, unknown>,
+    packageRoot?: string,
+): RuleScope {
     const proj = settings['projection'];
     if (typeof proj !== 'object' || proj === null || Array.isArray(proj)) {
         return LEGACY_ALL;
     }
     const p = proj as Record<string, unknown>;
+    // `rule_packs: auto` derives the active-pack set — the SAME set the
+    // skill/command prune uses — so the rule axis cannot drift from the
+    // artefact axis. Resolving it needs the package root (packs.yml lives
+    // there); without one the sentinel degrades to the inactive axis rather
+    // than to an empty set, which would prune every pack-tagged rule.
+    const packs =
+        packageRoot === undefined
+            ? _list(p['rule_packs'])
+            : resolve_rule_pack_scope(
+                  p['rule_packs'],
+                  packageRoot,
+                  _list(_runtimeActivePacks(settings)) ?? [],
+              );
     return {
         workspaces: _list(p['rule_workspaces']),
-        packs: _list(p['rule_packs']),
+        packs,
         roles: _list(p['rule_roles']),
     };
 }
 
+/** `runtime.active_packs` overlay from an already-parsed settings object. */
+function _runtimeActivePacks(settings: Record<string, unknown>): unknown {
+    const rt = settings['runtime'];
+    return typeof rt === 'object' && rt !== null && !Array.isArray(rt)
+        ? (rt as Record<string, unknown>)['active_packs']
+        : null;
+}
+
 /**
  * Whether a rule FILE (path into the shipped `dist/agent-src/rules` tree)
  * arrives in a consumer install under `scope`.

package/src/scripts/_cli/cmd_conformance.ts

@@ -38,6 +38,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 { routeTargetPathsPosix } from '../router_target_paths.mjs';
 import {
     _classify,
     _collect_manifest_entries,
@@ -146,32 +147,20 @@ export function _check_txlog_clean(logPath: string = installLogPath()): Dict {
  * Map one `routes_to` target (`<kind>:<id>`) to its candidate
  * package-relative paths. The FIRST existing candidate wins.
  *
- * `contract:` has two legitimate homes in the shipped tree: the public
- * contract pages under `docs/contracts/` (per the rule-router contract)
- * and the agent-facing contract contexts under
- * `dist/agent-src/contexts/contracts/` (e.g. artifact-engagement-flow).
+ * The kind→path table itself lives in `../router_target_paths.mjs` and is
+ * SHARED with `prepack-check.mjs` gate 4, which asserts every one of these
+ * targets lands inside the `files[]` whitelist at pack time. A second copy of
+ * the table would let the pack gate and this runtime resolver disagree about
+ * where a pointer lives — the packaging↔runtime gap Phase 4 of
+ * `road-to-gates-that-can-fail` closes. `contract:`'s two legitimate homes
+ * (public `docs/contracts/` pages and agent-facing
+ * `dist/agent-src/contexts/contracts/` contexts) are documented there.
  */
 export function routeTargetPaths(target: string): string[] {
-    const sep = target.indexOf(':');
-    if (sep <= 0) return [];
-    const kind = target.slice(0, sep);
-    const id = target.slice(sep + 1);
-    if (!id) return [];
-    switch (kind) {
-        case 'skill':
-            return [path.join('dist', 'agent-src', 'skills', id, 'SKILL.md')];
-        case 'command':
-            return [path.join('dist', 'agent-src', 'commands', `${id}.md`)];
-        case 'guideline':
-            return [path.join('docs', 'guidelines', `${id}.md`)];
-        case 'contract':
-            return [
-                path.join('docs', 'contracts', `${id}.md`),
-                path.join('dist', 'agent-src', 'contexts', 'contracts', `${id}.md`),
-            ];
-        default:
-            return [];
-    }
+    // POSIX templates → platform paths. `path.join` over the split segments
+    // reproduces the previous per-kind `path.join(...)` calls exactly,
+    // including a slash-bearing id such as `guideline:a/b`.
+    return routeTargetPathsPosix(target).map((rel) => path.join(...rel.split('/')));
 }
 
 export function _check_router_pointers(packageRoot: string = PACKAGE_ROOT): Dict {

package/src/scripts/_dispatch.bash

@@ -203,6 +203,11 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              last dispatcher feedback per concern, missing trampolines.
                              Wraps hooks:status. Read-only.
                              Flags: --format json|table, --strict (CI), --project-root <path>
+  routing:doctor             Live routing diagnosis: per-gate ACTIVE/INACTIVE with the
+                             concern's own reason (read-only probes), session_start chain,
+                             router + projection freshness, host bridge status.
+                             Flags: --platform <p>, --workspace <path>, --json, --strict,
+                             --no-freshness
   hooks:replay               Replay a fixture through the universal dispatcher with
                              AGENT_CONFIG_REPLAY=1 (no writes under agents/runtime/state/).
                              Usage: hooks:replay --platform <name> --event <event>
@@ -755,6 +760,10 @@ cmd_hooks_doctor() {
   exec_hook "src/scripts/hooks_doctor" "$@"
 }
 
+cmd_routing_doctor() {
+  exec_hook "src/scripts/routing_doctor" "$@"
+}
+
 cmd_hooks_replay() {
   exec_hook "src/scripts/hooks/replay_hook" "$@"
 }
@@ -1217,6 +1226,7 @@ main() {
     dispatch:hook)           cmd_dispatch_hook "$@" ;;
     hooks:status)            cmd_hooks_status "$@" ;;
     hooks:doctor)            cmd_hooks_doctor "$@" ;;
+    routing:doctor)          cmd_routing_doctor "$@" ;;
     hooks:replay)            cmd_hooks_replay "$@" ;;
     reach:doctor)            cmd_reach_doctor "$@" ;;
     telemetry:record)        cmd_telemetry_record "$@" ;;

package/src/scripts/_lib/claude_settings_hooks.ts

@@ -108,19 +108,45 @@ export function build_claude_hook_matrix(manifest_path: string): ClaudeHookMatri
         if (!concerns || (Array.isArray(concerns) && concerns.length === 0)) continue;
         const native = ac_to_native[ac_event];
         if (native === undefined) continue;
-        // Hook-resilience shim (road-to-opt-subagent-harvest P1.4):
+        // 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
+        // container; bench_hook_latency --via-cli pins it). Candidates:
+        //   1. project npm install (node_modules/@event4u/agent-config/…)
+        //   2. a source checkout — guarded by hook_manifest.yaml existing
+        //      next to it, so an UNRELATED consumer file that happens to sit
+        //      at dist/hooks/dispatch.js can never be executed as a hook
+        //      (council 2026-08-03).
+        // `exec node` replaces the shell; stdin/exit codes flow through
+        // unchanged (a fail_closed concern still denies). Global installs
+        // have no project-relative bundle path and take the CLI fallback
+        // below, which boots the same bundle in-process via the launcher
+        // fast path (src/cli/agent-config.ts).
+        //
+        // Hook-resilience fallback (road-to-opt-subagent-harvest P1.4):
         // local binary → PATH fallback → SILENT exit 0 when neither exists
         // (a hook must never error-spam the loop on an uninstalled repo).
         // The dispatcher's own exit code PROPAGATES when it runs — a
         // fail_closed concern (e.g. block-no-verify) still denies; only the
         // missing-binary case degrades open, which is the honest degrade
         // (an absent dispatcher cannot evaluate anything).
+        // NOTE: the CLI fallback carries MANAGED_SIGNATURE — keep it, or
+        // previously installed managed entries orphan on refresh.
+        const dispatchArgs =
+            `--platform claude --event ${ac_event} --native-event ${native} ` +
+            `--project-dir "$CLAUDE_PROJECT_DIR" --min-version ${String(hook_spec)}`;
         matrix[native] =
+            'B=""; ' +
+            '[ -f "$CLAUDE_PROJECT_DIR/node_modules/@event4u/agent-config/dist/hooks/dispatch.js" ] && ' +
+            'B="$CLAUDE_PROJECT_DIR/node_modules/@event4u/agent-config/dist/hooks/dispatch.js"; ' +
+            '[ -z "$B" ] && [ -f "$CLAUDE_PROJECT_DIR/dist/hooks/dispatch.js" ] && ' +
+            '[ -f "$CLAUDE_PROJECT_DIR/src/scripts/hook_manifest.yaml" ] && ' +
+            'B="$CLAUDE_PROJECT_DIR/dist/hooks/dispatch.js"; ' +
+            'if [ -n "$B" ] && command -v node >/dev/null 2>&1; then ' +
+            `exec node "$B" ${dispatchArgs}; fi; ` +
             'BIN="$CLAUDE_PROJECT_DIR/agent-config"; [ -x "$BIN" ] || BIN=agent-config; ' +
             'command -v "$BIN" >/dev/null 2>&1 || exit 0; ' +
-            `"$BIN" dispatch:hook --platform claude --event ${ac_event} ` +
-            `--native-event ${native} --project-dir "$CLAUDE_PROJECT_DIR" ` +
-            `--min-version ${String(hook_spec)}`;
+            `"$BIN" dispatch:hook ${dispatchArgs}`;
     }
     return matrix;
 }

package/src/scripts/_lib/gate_baseline.ts

@@ -0,0 +1,213 @@
+/**
+ * Violation ratchet for gates whose scan root was repaired.
+ *
+ * WHY THIS EXISTS (council 2026-08-02, roadmap `road-to-gates-that-can-fail`
+ * blocker `dead-gate-finding-triage`): repairing a dead scan root does not
+ * create violations, it REVEALS violations that were invisible while the gate
+ * scanned nothing. Landing the repair with a hard fail would turn `main` red on
+ * debt the repairing change did not cause, blocking every unrelated merge
+ * behind unrelated copy-editing. Suppressing the findings would be the same
+ * green-on-nothing failure the repair exists to end.
+ *
+ * The adopted shape is a ratchet:
+ *
+ *   The repair records the revealed count as a per-gate baseline in
+ *   `src/config/gate-violation-baselines.json`. The gate fails only when its
+ *   count rises ABOVE the baseline. Lowering a baseline is a normal commit;
+ *   raising one is a defect.
+ *
+ * This is not an allowlist: no individual violation is named or excused, the
+ * number is committed, and every change to it shows as a delta in the diff.
+ *
+ * ## The anti-fossilization clause — why entries expire
+ *
+ * The council's own strongest objection to the ratchet was that a baseline
+ * which never moves hardens from "debt" into "configuration", at which point it
+ * IS suppression with extra steps. So an entry is not permanent: it carries the
+ * date its repair landed, and after {@link STALE_AFTER_DAYS} days a baseline
+ * that has not been lowered fails the gate with an escalation message. Clearing
+ * it means one of three visible acts — fix the findings, lower the count, or
+ * write a `reaffirmed` block whose non-empty reason lands in the diff.
+ *
+ * Dates are plain `YYYY-MM-DD`; ages are whole days in UTC, so the verdict does
+ * not depend on the machine's timezone.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Days a baseline may sit unchanged before it must be fixed or reaffirmed. */
+export const STALE_AFTER_DAYS = 56;
+
+/** Repo-relative location of the committed baseline file. */
+export const BASELINE_REL = 'src/config/gate-violation-baselines.json';
+
+/** A single gate's recorded debt. */
+export interface BaselineEntry {
+    /** Violation count revealed when the scan root was repaired. */
+    count: number;
+    /** `YYYY-MM-DD` the repair (or the last lowering) landed. */
+    landed: string;
+    /** What the counted violations are, so a reader need not re-derive them. */
+    note: string;
+    /** Optional clock reset — requires a reason, and the reason lands in the diff. */
+    reaffirmed?: { date: string; reason: string };
+}
+
+export interface BaselineFile {
+    /** Human-facing pointer back to the rule that governs this file. */
+    $comment?: string;
+    gates: Record<string, BaselineEntry>;
+}
+
+export type BaselineStatus =
+    /** Count is at or under the baseline and the entry is still fresh. */
+    | 'within'
+    /** Count is below the baseline — the ratchet should be tightened. */
+    | 'improved'
+    /** Count rose above the baseline. This is the defect the ratchet catches. */
+    | 'regressed'
+    /** Count is within, but the entry has sat unchanged past the expiry. */
+    | 'stale'
+    /** No baseline recorded — zero violations is the only passing state. */
+    | 'unbaselined';
+
+export interface BaselineVerdict {
+    status: BaselineStatus;
+    /** True when the gate may exit 0. */
+    ok: boolean;
+    /** The effective baseline (0 when no entry exists). */
+    baseline: number;
+    actual: number;
+    /** Whole days since `landed` (or since `reaffirmed.date` when present). */
+    ageDays: number | null;
+    /** One line, ready for stdout (ok) or stderr (not ok). */
+    message: string;
+}
+
+function parseIsoDate(value: string): number | null {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return null;
+    }
+    const ms = Date.parse(`${value}T00:00:00Z`);
+    return Number.isNaN(ms) ? null : ms;
+}
+
+function wholeDaysBetween(fromMs: number, toMs: number): number {
+    return Math.floor((toMs - fromMs) / 86_400_000);
+}
+
+/** Read the committed baseline file. A missing file is an empty ratchet, not an error. */
+export function loadBaselines(repoRoot: string, relPath: string = BASELINE_REL): BaselineFile {
+    const abs = path.join(repoRoot, relPath);
+    let raw: string;
+    try {
+        raw = fs.readFileSync(abs, 'utf8');
+    } catch {
+        return { gates: {} };
+    }
+    const parsed = JSON.parse(raw) as Partial<BaselineFile>;
+    const out: BaselineFile = { gates: parsed.gates ?? {} };
+    if (parsed.$comment !== undefined) out.$comment = parsed.$comment;
+    return out;
+}
+
+export interface RatchetOptions {
+    /** Gate name — the key in the baseline file. */
+    gate: string;
+    /** How many violations this run found. */
+    actual: number;
+    /** Absolute repo root. */
+    repoRoot: string;
+    /** Override the baseline file location (tests). */
+    baselineRel?: string;
+    /** Override "now" as `YYYY-MM-DD` (tests); defaults to the current UTC date. */
+    today?: string;
+}
+
+/**
+ * Judge a violation count against its recorded baseline.
+ *
+ * Callers keep their own reporting and exit codes — this returns a verdict, it
+ * does not print or exit. A gate with no entry behaves exactly as it did before
+ * the ratchet existed: any violation fails.
+ */
+export function checkRatchet(opts: RatchetOptions): BaselineVerdict {
+    const { gate, actual } = opts;
+    const file = loadBaselines(opts.repoRoot, opts.baselineRel ?? BASELINE_REL);
+    const entry = file.gates[gate];
+
+    if (entry === undefined) {
+        return {
+            status: 'unbaselined',
+            ok: actual === 0,
+            baseline: 0,
+            actual,
+            ageDays: null,
+            message:
+                actual === 0
+                    ? `${gate}: 0 violation(s), no baseline needed.`
+                    : `${gate}: ${actual} violation(s) and no recorded baseline — fix them, or ` +
+                      `record the count in ${BASELINE_REL} if this is a scan-root repair ` +
+                      'revealing pre-existing debt.',
+        };
+    }
+
+    const anchor = entry.reaffirmed?.date ?? entry.landed;
+    const anchorMs = parseIsoDate(anchor);
+    const todayMs = parseIsoDate(opts.today ?? new Date().toISOString().slice(0, 10));
+    const ageDays = anchorMs !== null && todayMs !== null ? wholeDaysBetween(anchorMs, todayMs) : null;
+
+    if (actual > entry.count) {
+        return {
+            status: 'regressed',
+            ok: false,
+            baseline: entry.count,
+            actual,
+            ageDays,
+            message:
+                `${gate}: ${actual} violation(s) against a baseline of ${entry.count} — ` +
+                `${actual - entry.count} new. A ratchet only turns one way: fix the new ` +
+                `violation(s). Raising the baseline in ${BASELINE_REL} is a defect, not a fix.`,
+        };
+    }
+
+    if (actual < entry.count) {
+        return {
+            status: 'improved',
+            ok: true,
+            baseline: entry.count,
+            actual,
+            ageDays,
+            message:
+                `${gate}: ${actual} violation(s), baseline ${entry.count} — ratchet is loose. ` +
+                `Lower it to ${actual} in ${BASELINE_REL} (and refresh \`landed\`) so the ` +
+                'gain cannot be silently given back.',
+        };
+    }
+
+    if (ageDays !== null && ageDays > STALE_AFTER_DAYS) {
+        return {
+            status: 'stale',
+            ok: false,
+            baseline: entry.count,
+            actual,
+            ageDays,
+            message:
+                `${gate}: baseline of ${entry.count} has not moved in ${ageDays} days ` +
+                `(limit ${STALE_AFTER_DAYS}). A baseline that never drops is suppression with ` +
+                'extra steps. Fix the findings, lower the count, or add a `reaffirmed` block ' +
+                `with a reason in ${BASELINE_REL}. Debt: ${entry.note}`,
+        };
+    }
+
+    return {
+        status: 'within',
+        ok: true,
+        baseline: entry.count,
+        actual,
+        ageDays,
+        message:
+            `${gate}: ${actual} violation(s) at baseline${ageDays === null ? '' : `, age ${ageDays}d`} ` +
+            `— known debt, not new breakage. ${entry.note}`,
+    };
+}

package/src/scripts/_lib/scoped_projection.ts

@@ -160,6 +160,56 @@ export function is_pruned_under_scoped(md_path: string, active_ids: ReadonlySet<
     return true;
 }
 
+/**
+ * Sentinel value for `projection.rule_packs`: derive the pack scope from the
+ * active-pack set instead of listing ids by hand.
+ *
+ * The rule layer's pack axis was wired end-to-end but shipped inactive
+ * (`rule_packs: []`), so a rule whose own body says "auto-activates when
+ * pack-X is installed" projected into installs that do not have pack-X,
+ * where it guards nothing. Listing the active ids by hand is not a fix — the
+ * list would need re-typing whenever a pack is added, which is the
+ * two-counting-paths failure this module exists to prevent. `auto` reuses
+ * `compute_active_pack_ids`, the SAME set the skill/command prune uses, so
+ * the rule axis cannot drift from the artefact axis.
+ */
+export const RULE_PACKS_AUTO = 'auto';
+
+/**
+ * Resolve a raw `projection.rule_packs` setting into the pack scope
+ * `rule_in_scope` consumes.
+ *
+ * - `'auto'` (scalar or single-element list) → the derived active-pack set.
+ * - a non-empty list → that list, verbatim.
+ * - anything else (absent, `[]`, wrong type) → `null`, axis inactive.
+ *
+ * A derivation failure (unreadable / malformed `packs.yml`) returns `null`,
+ * not an empty set: an empty set would prune every pack-tagged rule, the
+ * opposite of the fail-safe contract `rule_in_scope` documents.
+ */
+export function resolve_rule_pack_scope(
+    raw: unknown,
+    package_root: string,
+    runtime_active_packs: readonly string[] = [],
+): string[] | null {
+    const is_auto =
+        raw === RULE_PACKS_AUTO ||
+        (Array.isArray(raw) && raw.length === 1 && raw[0] === RULE_PACKS_AUTO);
+    if (is_auto) {
+        try {
+            return [
+                ...compute_active_pack_ids(load_packs_registry(package_root), runtime_active_packs),
+            ].sort();
+        } catch {
+            return null;
+        }
+    }
+    if (Array.isArray(raw) && raw.length > 0) {
+        return raw.map((v) => String(v));
+    }
+    return null;
+}
+
 export interface ScopedProjectionStats {
     /** Skills a default `projection.mode: scoped` install deploys. */
     projected: number;