@event4u/agent-config 14.12.0 → 14.13.0

package/src/scripts/_cli/cmd_doctor.ts

@@ -99,6 +99,9 @@ import * as global_deploy_inventory from '../_lib/global_deploy_inventory.js';
 import { censusDuplicateScope } from '../_lib/duplicate_scope_census.js';
 import * as preamble_byte_census from '../preamble_byte_census.js';
 import * as dispatch_economy_report from '../dispatch_economy_report.js';
+import * as runtime_wiring from '../_lib/runtime_wiring_checks.js';
+import * as install_reach from '../_lib/install_reach_checks.js';
+import * as runtime_checks from '../_lib/doctor_runtime_checks.js';
 import { git_common_dir } from '../_lib/git_common_dir.js';
 import * as sync_gitattributes from '../sync_gitattributes.js';
 import {
@@ -106,6 +109,7 @@ import {
     ROOT_OVERRIDE_ENV,
     ProjectRootError,
     find_project_root_with_trace,
+    iter_setting_overrides,
     project_settings_path,
     resolve_project_root,
     type TraceRecord,
@@ -771,6 +775,8 @@ const CHECK_IDS = [
     'claude-command-wrappers',
     'surface-state',
     'hook-wiring',
+    ...runtime_wiring.WIRING_CHECK_IDS,
+    ...install_reach.REACH_CHECK_IDS,
     'stale-orphans',
     'overrides',
     'rule-scope-drift',
@@ -802,6 +808,8 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'claude-command-wrappers',
     'surface-state',
     'hook-wiring',
+    ...runtime_wiring.WIRING_CHECK_IDS,
+    ...install_reach.REACH_CHECK_IDS,
     'stale-orphans',
     'overrides',
     'rule-scope-drift',
@@ -1361,79 +1369,16 @@ function pathExistsAny(p: string): boolean {
 }
 
 
-/**
- * Managed hook wiring (single-surface model): the deterministic hook matrix
- * must be registered in ~/.claude/settings.json AND the dispatch target
- * (`agent-config` binary) must resolve on PATH. Both halves are required —
- * hooks without a binary silently no-op every session.
- */
+/** Managed hook wiring — moved to `_lib/runtime_wiring_checks.ts` (it IS a runtime-wiring check). */
 function _check_hook_wiring(): Dict {
-    const claude = shutilWhich('claude');
-    if (claude === null) {
-        return {
-            id: 'hook-wiring',
-            status: 'skipped',
-            message: 'Claude Code CLI not on PATH — hook-wiring check not applicable',
-            remedy: '',
-        };
-    }
-    const settings_path = path.join(os.homedir(), '.claude', 'settings.json');
-    let missing: string[];
-    try {
-        const matrix = claude_settings_hooks.build_claude_hook_matrix(
-            path.join(_package_root(), 'src', 'scripts', 'hook_manifest.yaml'),
-        );
-        const settings = pathExists(settings_path)
-            ? (JSON.parse(fs.readFileSync(settings_path, 'utf8')) as Record<string, unknown>)
-            : {};
-        const hooks = ((settings['hooks'] ?? {}) as Record<string, unknown>) || {};
-        missing = Object.keys(matrix).filter((ev) => {
-            const groups = hooks[ev];
-            if (!Array.isArray(groups)) return true;
-            return !JSON.stringify(groups).includes(claude_settings_hooks.MANAGED_SIGNATURE);
-        });
-    } catch (e) {
-        return {
-            id: 'hook-wiring',
-            status: 'fail',
-            message: `cannot evaluate managed hooks: ${String(e)}`,
-            remedy: 'fix ~/.claude/settings.json (invalid JSON?), then agent-config refresh --global',
-        };
-    }
-    const binary_ok = shutilWhich('agent-config') !== null;
-    if (missing.length === 0 && binary_ok) {
-        return {
-            id: 'hook-wiring',
-            status: 'ok',
-            message: 'managed hooks registered in ~/.claude/settings.json; dispatch binary on PATH',
-            remedy: '',
-        };
-    }
-    if (missing.length > 0 && claude_plugin.claude_plugin_installed()) {
-        return {
-            id: 'hook-wiring',
-            status: 'warn',
-            message:
-                `managed hooks missing for: ${missing.join(', ')} — currently carried by the ` +
-                'installed plugin (deprecated surface)',
-            remedy: 'agent-config refresh --global (writes the managed settings.json block)',
-        };
-    }
-    const parts: string[] = [];
-    if (missing.length > 0) parts.push(`managed hooks missing for: ${missing.join(', ')}`);
-    if (!binary_ok) parts.push('`agent-config` not on PATH (hooks would silently no-op)');
-    if (parts.length === 0) {
-        // hooks complete, binary missing was the only issue → covered above.
-        parts.push('`agent-config` not on PATH');
-    }
-    return {
-        id: 'hook-wiring',
-        status: 'fail',
-        message: parts.join('; '),
-        remedy: binary_ok
-            ? 'agent-config refresh --global'
-            : 'npm install -g @event4u/agent-config, then agent-config refresh --global',
-    };
+    return runtime_wiring.checkHookWiring({
+        which: shutilWhich,
+        packageRoot: _package_root(),
+        homeDir: os.homedir(),
+        buildMatrix: (mp) => claude_settings_hooks.build_claude_hook_matrix(mp) as Record<string, unknown>,
+        managedSignature: claude_settings_hooks.MANAGED_SIGNATURE,
+        pluginInstalled: () => claude_plugin.claude_plugin_installed(),
+    }) as unknown as Dict;
 }
 
 function _check_bridge_drift(
@@ -1811,46 +1756,12 @@ function _check_duplicate_scope_rules(project_root: string, userRulesDirOverride
     };
 }
 
-function _check_python_runtime(): Dict {
-    // Post-teardown: the package runtime is TypeScript-on-`tsx`. python3 is no
-    // longer a runtime dependency, so this check no longer probes for an
-    // interpreter (spawning python3 here would be misleading in a python-free
-    // package). The check id is retained for the doctor's stable report shape;
-    // it always reports `ok`.
-    return {
-        id: 'python-runtime',
-        status: 'ok',
-        message: 'python3 is not a runtime dependency (TS runtime via tsx)',
-        remedy: '',
-    };
-}
-
-function _check_humanizer_runtime(): Dict {
-    // Write-engine step 4b (humanize audit) runs `detect_ai_tells.ts` via a
-    // Node/tsx runtime "when available", degrading to a prose-only audit
-    // otherwise. This check surfaces which path a consumer install gets so the
-    // default-on behavior is not a silent surprise. Either state is healthy —
-    // the fallback is graceful by design — so it never fails the run.
-    const node = shutilWhich('node');
-    if (node === null) {
-        return {
-            id: 'humanizer-runtime',
-            status: 'ok',
-            message:
-                'no Node runtime on PATH — write-engine step 4b uses the ' +
-                'prose-only humanize audit (graceful fallback)',
-            remedy:
-                'install Node to enable the mechanical detect_ai_tells.ts pass; ' +
-                'the prose audit runs regardless',
-        };
-    }
-    return {
-        id: 'humanizer-runtime',
-        status: 'ok',
-        message: `Node runtime present (${node}) — step 4b runs the mechanical detect_ai_tells.ts pass`,
-        remedy: '',
-    };
-}
+// Both bodies moved to `_lib/doctor_runtime_checks.ts` to pay for the Phase-1
+// install-reach wiring under `check_source_size_budget`. These wrappers keep the
+// historical names and arity, so the runner map, the export block and the
+// existing fallback test are untouched by the move.
+const _check_python_runtime = (): Dict => runtime_checks.checkPythonRuntime();
+const _check_humanizer_runtime = (): Dict => runtime_checks.checkHumanizerRuntime(shutilWhich);
 
 function _check_mcp_beta_readiness(project_root: string): Dict {
     // Maintainer-scoped gate: the six artefacts live in the agent-config
@@ -2970,6 +2881,8 @@ function _run_checks(
         'claude-command-wrappers': _check_claude_command_wrappers,
         'surface-state': _check_surface_state,
         'hook-wiring': _check_hook_wiring,
+        ...(runtime_wiring.wiringRunners({ packageRoot: _package_root(), iterOverrides: () => iter_setting_overrides({ cwd: project_root }) }) as unknown as Record<string, CheckRunner>),
+        ...(install_reach.reachRunners({ projectRoot: project_root, resolvableVersion: _current_package_version() }) as unknown as Record<string, CheckRunner>),
         'stale-orphans': _check_stale_orphans,
         overrides: () => _check_overrides(project_root),
         'rule-scope-drift': () => _check_rule_scope_drift(project_root),
@@ -3054,6 +2967,8 @@ function _run_checks_no_manifest(
         'claude-command-wrappers': _check_claude_command_wrappers,
         'surface-state': _check_surface_state,
         'hook-wiring': _check_hook_wiring,
+        ...(runtime_wiring.wiringRunners({ packageRoot: _package_root(), iterOverrides: () => iter_setting_overrides({ cwd: project_root }) }) as unknown as Record<string, CheckRunner>),
+        ...(install_reach.reachRunners({ projectRoot: project_root, resolvableVersion: _current_package_version() }) as unknown as Record<string, CheckRunner>),
         'stale-orphans': _check_stale_orphans,
         // BOTH registries need the id. Registering only the first one crashed with
         // `runners[cid] is not a function` on a global-only consumer, which is the

package/src/scripts/_dispatch.bash

@@ -235,8 +235,14 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
                              (archives completed roadmaps; --no-archive to skip)
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
+  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)
+  stubs:due                  Read-only: roadmap stubs past their `review_by:`
+                             date, plus the decisions routed to the owner.
+                             Writes nothing. Flags: --json, --counts,
+                             --today <ISO> (pin "now")
   gates                      Open decisions that need you, rendered as actions —
                              roadmap blockers filtered by owner, most-unblocking
                              first. Flags: --all (include maintainer/external),
@@ -755,6 +761,13 @@ cmd_roadmap_progress() {
   exec_ts "$script" --archive "$@"
 }
 
+# The parked estate's front door — read-only, and deliberately so. It authors
+# nothing under `agents/roadmaps/stubs/`, which is what keeps it clear of the
+# 2026-08-21 council verdict that deleted the hand-maintained index there.
+cmd_stubs_due() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/stubs_due.ts" "$@"
+}
+
 cmd_roadmap_progress_check() {
   local script
   script="$(resolve_script "dist/agent-src/scripts/update_roadmap_progress.ts" ".augment/scripts/update_roadmap_progress.ts")"
@@ -769,6 +782,18 @@ cmd_roadmap_archive() {
   exec_ts "$script" "$@"
 }
 
+cmd_roadmap_set_step() {
+  local script
+  script="$(resolve_script "dist/agent-src/scripts/roadmap_set_step.ts" ".augment/scripts/roadmap_set_step.ts")"
+  exec_ts "$script" "$@"
+}
+
+cmd_stubs_due() {
+  local script
+  script="$(resolve_script "dist/agent-src/scripts/stubs_due.ts" ".augment/scripts/stubs_due.ts")"
+  exec_ts "$script" "$@"
+}
+
 cmd_gates() {
   local script
   script="$(resolve_script "dist/agent-src/scripts/roadmap_gates.ts" ".augment/scripts/roadmap_gates.ts")"
@@ -1481,6 +1506,8 @@ main() {
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     roadmap:archive)         cmd_roadmap_archive "$@" ;;
+    roadmap:set-step)        cmd_roadmap_set_step "$@" ;;
+    stubs:due)               cmd_stubs_due "$@" ;;
     gates)                   cmd_gates "$@" ;;
     capabilities:index)      cmd_capabilities_index "$@" ;;
     adr:effective)           cmd_adr_effective "$@" ;;

package/src/scripts/_lib/activation_ladder.ts

@@ -0,0 +1,211 @@
+/**
+ * The activation ladder, its precedence receipt, and the unknown invariant.
+ *
+ * `road-to-governed-harness-evolution` Phase 1, steps 1.1 and 1.2.
+ *
+ * **E4 + E9 decided 2026-08-30, option B, AI council 2/2** (anthropic +
+ * openai): SIX rungs, twelve cascade stages. The argument that carried it was
+ * not "more is better" — it was that option A requires EDITING Phase 1's exit
+ * criterion in order to fit, and that the distinction A drops is the one the
+ * delivery experiment exists to measure. Two independent roadmaps arriving at
+ * the same distinction (`road-to-experience-loop-broadening` Phase 5 needs five
+ * activation/adherence states of its own) was the strongest evidence available.
+ *
+ * The cost asymmetry is a ratchet and it points the same way: an
+ * under-populated rung can be collapsed later, while a distinction that was
+ * never recorded cannot be added to historical data at all.
+ *
+ * **The openai seat attached a condition, and this module is it.** Before the
+ * enums are persisted, every rung must map to a receipt field and an OBSERVABLE
+ * PREDICATE, with an explicit `unknown`; see {@link LADDER}. Its `revisit-if`:
+ * any rung lacking a distinct observable predicate, or staying `unknown` across
+ * representative Phase 1 evaluations — in which case keep six rungs and
+ * reconsider the nine-stage cascade independently.
+ */
+
+/**
+ * The six rungs, in order. A run climbs them; the first one it fails to reach
+ * is where the receipt points.
+ *
+ * `projected`, `delivered` and `visible` are three rungs and not one because
+ * the shipping substrate already separates them:
+ * `_lib/lean_projection_mode.ts:19` defines `eager-all | thin | delivery`, and
+ * under `thin`/`delivery` an artefact can be projected without being visible in
+ * a given turn. The 4-rung form collapses all three into `injected`.
+ */
+export const LADDER_RUNGS = [
+    'eligible',
+    'selected',
+    'projected',
+    'delivered',
+    'visible',
+    'adhered',
+] as const;
+export type LadderRung = (typeof LADDER_RUNGS)[number];
+
+/**
+ * Which failure family a stall at each rung belongs to.
+ *
+ * This is what step 1.1's exit criterion asks for: a deliberately failing
+ * trigger eval must be classifiable as CONTENT vs ACTIVATION vs ADHERENCE from
+ * the recorded receipt alone.
+ */
+export type FailureFamily = 'content' | 'activation' | 'adherence' | 'unknown';
+
+/** One rung's contract: what it means, what observes it, and what it decides. */
+export interface RungSpec {
+    readonly rung: LadderRung;
+    /** The receipt field whose value decides this rung. */
+    readonly observedBy: string;
+    /** How the value is read — the observable predicate the council required. */
+    readonly predicate: string;
+    /** The family a stall AT this rung belongs to. */
+    readonly family: Exclude<FailureFamily, 'unknown'>;
+}
+
+/**
+ * The evidence matrix — rung → receipt field → predicate → family.
+ *
+ * Required by the E4+E9 verdict before the enum is persisted. Its purpose is to
+ * make "false precision" checkable: a rung whose predicate cannot be evaluated
+ * from a receipt is a rung that will read `unknown` forever, which is the
+ * council's own stated revisit condition.
+ */
+export const LADDER: readonly RungSpec[] = [
+    {
+        rung: 'eligible',
+        observedBy: 'eligible',
+        predicate: 'the artefact matched the request at all — its triggers, packs and workspaces admit it',
+        family: 'content',
+    },
+    {
+        rung: 'selected',
+        observedBy: 'selected',
+        predicate: 'the router chose it over competing artefacts at the same trigger',
+        family: 'activation',
+    },
+    {
+        rung: 'projected',
+        observedBy: 'projected',
+        predicate: 'a host tree carries the artefact — the projection wrote a file for this host',
+        family: 'activation',
+    },
+    {
+        rung: 'delivered',
+        observedBy: 'delivered',
+        predicate: 'the host loaded it for this turn under the active lean_projection_mode',
+        family: 'activation',
+    },
+    {
+        rung: 'visible',
+        observedBy: 'visible',
+        predicate: 'it survived the turn\'s context budget rather than being trimmed',
+        family: 'activation',
+    },
+    {
+        rung: 'adhered',
+        observedBy: 'adhered',
+        predicate: 'the reply shows the obligation was followed, not merely present',
+        family: 'adherence',
+    },
+];
+
+/**
+ * Why a rung was not reached.
+ *
+ * This replaces a flat `rule/skill/hook/router/host/model` attribution, which
+ * names a CATEGORY and not a PLACE — you cannot fix "router" and you can fix
+ * "lost to a higher-priority rule".
+ */
+export const PRECEDENCE_REASONS = [
+    'lost-to-higher-priority-rule',
+    'host-restriction',
+    'pack-filter',
+    'missing-projection',
+    'context-budget',
+    'contradictory-instruction',
+] as const;
+export type PrecedenceReason = (typeof PRECEDENCE_REASONS)[number];
+
+/**
+ * A rung's observed state.
+ *
+ * `'unknown'` is a first-class value and NOT a default that means no: step
+ * 1.2's soundness invariant is that a state which was not observed stays
+ * unknown and is never silently converted to success. Without it every
+ * downstream rate is inflated by exactly the capture gap.
+ */
+export type RungState = 'reached' | 'not-reached' | 'unknown';
+
+export interface ActivationReceipt {
+    readonly artefact: string;
+    /** A rung ABSENT from this map is `unknown` — see {@link rungState}. */
+    readonly rungs: Readonly<Partial<Record<LadderRung, RungState>>>;
+    /** Why the first not-reached rung was not reached. */
+    readonly reason?: PrecedenceReason;
+}
+
+/**
+ * A rung's state, with absence read as `unknown`.
+ *
+ * ABSENT and `not-reached` are different observations and this is where that is
+ * enforced. The audit-log contract already draws the same line for
+ * `skills_applied` (`docs/contracts/audit-log-v1.md:88`): the key omitted means
+ * *not recorded*, `[]` means *recorded, and none*. A reader that folds the two
+ * cannot tell no signal from a negative signal.
+ */
+export function rungState(receipt: ActivationReceipt, rung: LadderRung): RungState {
+    return receipt.rungs[rung] ?? 'unknown';
+}
+
+/**
+ * Which family a receipt's failure belongs to — step 1.1's exit criterion.
+ *
+ * Walks the ladder in order and returns the family of the FIRST rung that was
+ * not reached. A rung whose state is `unknown` short-circuits to `'unknown'`
+ * rather than being skipped: skipping it would silently attribute the failure
+ * to a later rung the run may never have reached, which is the same inflation
+ * step 1.2 forbids, wearing a different shape.
+ *
+ * Every rung reached → `'adherence'` is NOT returned; the receipt did not fail,
+ * and the caller gets `null`.
+ */
+export function classifyFailure(receipt: ActivationReceipt): FailureFamily | null {
+    for (const spec of LADDER) {
+        const state = rungState(receipt, spec.rung);
+        if (state === 'unknown') return 'unknown';
+        if (state === 'not-reached') return spec.family;
+    }
+    return null;
+}
+
+/** A rate with its `unknown` bucket kept OUT of the denominator. */
+export interface LadderRate {
+    readonly reached: number;
+    readonly notReached: number;
+    readonly unknown: number;
+    /** `reached / (reached + notReached)`, or `null` when that is zero. */
+    readonly rate: number | null;
+}
+
+/**
+ * Aggregate one rung across receipts.
+ *
+ * The invariant step 1.2 exists for: **no aggregation folds `unknown` into a
+ * success denominator.** `unknown` is reported beside the rate, never inside
+ * it, and a population that is entirely `unknown` yields `rate: null` rather
+ * than `0` — zero is a measurement, and there was none.
+ */
+export function ladderRate(receipts: readonly ActivationReceipt[], rung: LadderRung): LadderRate {
+    let reached = 0;
+    let notReached = 0;
+    let unknown = 0;
+    for (const r of receipts) {
+        const s = rungState(r, rung);
+        if (s === 'reached') reached += 1;
+        else if (s === 'not-reached') notReached += 1;
+        else unknown += 1;
+    }
+    const denominator = reached + notReached;
+    return { reached, notReached, unknown, rate: denominator === 0 ? null : reached / denominator };
+}

package/src/scripts/_lib/activation_states.ts

@@ -0,0 +1,88 @@
+/**
+ * The five states a per-asset outcome can occupy, and why three would not do.
+ *
+ * A per-asset "win rate" computed over two states — worked / did not work —
+ * is uninterpretable, and the failure is not cosmetic. Take a skill whose
+ * content is excellent and which the router never activates. Its success rate
+ * is low. Every fix that number suggests is a change to the skill, and every
+ * one of them would improve nothing, because the skill was never reached. The
+ * split below is what makes the number point at the right layer.
+ *
+ * Three rungs are observed independently:
+ *
+ *   available -> was the asset present in this install at all?
+ *   activated -> did the router/agent actually load it for this task?
+ *   followed  -> did the work that followed conform to what it said?
+ *
+ * Each rung is `true`, `false`, or `null` for "not observed". `null` is not a
+ * pessimistic `false`: an unobserved rung means the instrument did not see,
+ * which is a statement about the instrument. Collapsing it into either
+ * direction manufactures a signal, so `classify` returns `'unknown'` the moment
+ * any rung it would need is unobserved.
+ */
+
+/** Ordered from least to most engaged. `unknown` is not on that ladder. */
+export const ACTIVATION_STATES = [
+    /** The asset is not present in this install. Nothing about its quality follows. */
+    'not-available',
+    /** Present, and the router never loaded it. A content fix cannot help this case. */
+    'available-not-activated',
+    /** Loaded, and the work did not conform to it. This is the case a content or clarity fix addresses. */
+    'activated-not-followed',
+    /** Loaded and conformed to. The only state that may count toward a win rate. */
+    'activated-followed',
+    /**
+     * At least one rung was not observed. Reported as its own share, never
+     * folded into a success or a failure — a report that hides its own blind
+     * spot is worse than one that has none, because the reader cannot see the
+     * hole.
+     */
+    'unknown',
+] as const;
+
+export type ActivationState = (typeof ACTIVATION_STATES)[number];
+
+export function isActivationState(v: unknown): v is ActivationState {
+    return typeof v === 'string' && (ACTIVATION_STATES as readonly string[]).includes(v);
+}
+
+/** One observation per rung. `null` means "not observed", never "no". */
+export interface ActivationObservation {
+    available: boolean | null;
+    activated: boolean | null;
+    followed: boolean | null;
+}
+
+/**
+ * Classify one observation.
+ *
+ * The short-circuits are deliberate and are the reason this is a function
+ * rather than a lookup table: once `available` is observed `false`, the other
+ * two rungs are IRRELEVANT rather than unknown — an absent asset cannot have
+ * been activated — so an unobserved `followed` must not drag the answer to
+ * `'unknown'`. The same holds one rung down for `activated: false`.
+ *
+ * Everywhere else an unobserved rung wins, because the alternative is to invent
+ * the observation.
+ */
+export function classify(obs: ActivationObservation): ActivationState {
+    if (obs.available === null) return 'unknown';
+    if (obs.available === false) return 'not-available';
+
+    if (obs.activated === null) return 'unknown';
+    if (obs.activated === false) return 'available-not-activated';
+
+    if (obs.followed === null) return 'unknown';
+    return obs.followed ? 'activated-followed' : 'activated-not-followed';
+}
+
+/**
+ * True for the states that may enter a win-rate denominator.
+ *
+ * `unknown` is excluded because it is not an outcome, and `not-available` is
+ * excluded because it is not a fact about the asset's quality. Exported so a
+ * report cannot quietly choose a different denominator per column.
+ */
+export function countsTowardWinRate(state: ActivationState): boolean {
+    return state === 'activated-followed' || state === 'activated-not-followed';
+}