@event4u/agent-config 14.11.0 → 14.13.0

package/src/install/detect_php_shape.ts

@@ -0,0 +1,191 @@
+/**
+ * Which PHP application shape is in play — decided from the entry point and the
+ * router, never from the dependency list.
+ *
+ * `road-to-consumer-repo-reality` Phase 3. A dependency proves a library is
+ * AVAILABLE. Only the entry point and the routing mechanism prove which
+ * application shape is actually running.
+ *
+ * THE THIRD STATE IS THE POINT. Component-based distribution is a published
+ * model: a framework family ships its ORM, container, collections and HTTP
+ * layer as independently installable packages, usable with no framework
+ * present. PHP has at least two families distributed exactly this way, so the
+ * shape is a property of the DISTRIBUTION MODEL and not of any one consumer.
+ *
+ * Dependency-presence routing sends such an application to the framework's
+ * skill, which then offers a CLI that does not exist, a request-validation
+ * primitive that is not wired, and a routes file that was never there. Every
+ * suggestion is confidently wrong, and the reason is visible only from the
+ * entry point.
+ *
+ * COST IS THE OTHER HALF OF THE DESIGN. Risk-register rank 7: "the third
+ * framework state is added but never fires, because the discriminator is
+ * expensive to evaluate". So the discriminator is a FIXED SET of at most
+ * `PROBE_COUNT` filesystem existence checks plus one manifest read — no
+ * directory walk, no content scan, no per-session re-derivation. The probe set
+ * is exported so a caller can state the cost rather than estimate it.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * The verdict. `unknown` is a real answer, returned when the tree carries no
+ * `composer.json` — guessing a shape from an absent manifest would be the
+ * dependency-list reasoning this module exists to replace.
+ */
+export type PhpShape = 'laravel' | 'symfony' | 'components-without-framework' | 'plain-php' | 'unknown';
+
+/**
+ * Skeleton markers — the files a framework's own installer writes and a
+ * component consumer never has. Presence of ANY marker for a family is what
+ * makes the framework real rather than merely available.
+ *
+ * These are the framework's console entry point and its bootstrap config, both
+ * generated by the official skeleton and both absent when a developer wires the
+ * components by hand.
+ */
+export const SKELETON_MARKERS: Readonly<Record<'laravel' | 'symfony', readonly string[]>> = {
+    laravel: ['artisan', path.join('config', 'app.php'), path.join('bootstrap', 'app.php')],
+    symfony: [path.join('bin', 'console'), path.join('config', 'bundles.php'), path.join('config', 'services.yaml')],
+};
+
+/**
+ * Composer package prefixes that prove a family's COMPONENTS are available.
+ * Availability only — this is deliberately never sufficient for a verdict.
+ */
+export const COMPONENT_PREFIXES: Readonly<Record<'laravel' | 'symfony', readonly string[]>> = {
+    laravel: ['illuminate/'],
+    symfony: ['symfony/'],
+};
+
+/** The whole framework, as opposed to its parts. */
+const FRAMEWORK_PACKAGES: Readonly<Record<'laravel' | 'symfony', readonly string[]>> = {
+    laravel: ['laravel/framework'],
+    symfony: ['symfony/framework-bundle'],
+};
+
+/** Every path this module may stat. The cost, stated rather than estimated. */
+export const PROBE_PATHS: readonly string[] = [
+    'composer.json',
+    ...SKELETON_MARKERS.laravel,
+    ...SKELETON_MARKERS.symfony,
+];
+
+/** Upper bound on filesystem probes for one verdict. */
+export const PROBE_COUNT = PROBE_PATHS.length;
+
+export interface PhpShapeVerdict {
+    shape: PhpShape;
+    /** Which family's components are present, if any. Availability, not shape. */
+    componentsOf: 'laravel' | 'symfony' | null;
+    /** The skeleton markers actually found, repo-relative. */
+    markersFound: string[];
+    /** One sentence a caller can print. Never empty. */
+    reason: string;
+    /** How many filesystem probes this verdict cost. */
+    probes: number;
+}
+
+function _requireKeys(root: string): string[] {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(root, 'composer.json'), 'utf8')) as {
+            require?: Record<string, string>;
+            'require-dev'?: Record<string, string>;
+        };
+        return [...Object.keys(raw.require ?? {}), ...Object.keys(raw['require-dev'] ?? {})];
+    } catch {
+        return [];
+    }
+}
+
+function _markers(root: string, family: 'laravel' | 'symfony'): string[] {
+    return SKELETON_MARKERS[family].filter((rel) => fs.existsSync(path.join(root, rel)));
+}
+
+/**
+ * The verdict, in one pass.
+ *
+ * Order matters and is the whole discriminator: a family is only `laravel` or
+ * `symfony` when a **skeleton marker exists**. Components present with no
+ * marker is the third state, and it is checked before falling through to
+ * `plain-php` so a component consumer is never described as a project with no
+ * framework libraries at all.
+ */
+export function detectPhpShape(root: string): PhpShapeVerdict {
+    let probes = 1;
+    const requires = _requireKeys(root);
+    if (requires.length === 0 && !fs.existsSync(path.join(root, 'composer.json'))) {
+        return {
+            shape: 'unknown',
+            componentsOf: null,
+            markersFound: [],
+            reason: 'no composer.json — no PHP application shape to decide',
+            probes: probes + 1,
+        };
+    }
+
+    // TWO PASSES, and the order between them is the fix for a real defect.
+    //
+    // A single pass that returned on the first family with ANY component present
+    // reported a genuine Symfony application as components-without-framework the
+    // moment its composer.json also required `illuminate/collections` — because
+    // `laravel` is examined first, has a component, has no Laravel skeleton, and
+    // returned before Symfony's three markers were ever looked at. Both
+    // `illuminate/collections` and `illuminate/support` are widely used
+    // standalone, so a mixed manifest is ordinary rather than exotic.
+    //
+    // PASS 1 — a real skeleton anywhere wins. A framework whose own installer
+    // wrote its console entry point and bootstrap config is running, whatever
+    // else the manifest happens to carry.
+    const present: ('laravel' | 'symfony')[] = [];
+    for (const family of ['laravel', 'symfony'] as const) {
+        const hasFramework = FRAMEWORK_PACKAGES[family].some((p) => requires.includes(p));
+        const hasComponents = requires.some((r) => COMPONENT_PREFIXES[family].some((p) => r.startsWith(p)));
+        if (!hasFramework && !hasComponents) continue;
+        present.push(family);
+        const markersFound = _markers(root, family);
+        probes += SKELETON_MARKERS[family].length;
+        if (markersFound.length > 0) {
+            return {
+                shape: family,
+                componentsOf: family,
+                markersFound,
+                reason: `${family} skeleton present (${markersFound.join(', ')}) — the framework is real, not merely available`,
+                probes,
+            };
+        }
+    }
+
+    // PASS 2 — components present, no skeleton for ANY of them. Only now is the
+    // third state the right answer, and it names every family whose components
+    // are available rather than only the first one examined.
+    const first = present[0];
+    if (first !== undefined) {
+        const missing = present.flatMap((f) => SKELETON_MARKERS[f]);
+        const families = present.join(' and ');
+        return {
+            shape: 'components-without-framework',
+            componentsOf: first,
+            markersFound: [],
+            reason:
+                `${families} component(s) are required in composer.json but NO skeleton marker exists ` +
+                `(none of ${missing.join(', ')}). The entry point and router are the ` +
+                `application's own, so the framework CLI, its request-validation primitive and its routes ` +
+                'file are not there. Routing to a framework skill would offer all three.',
+            probes,
+        };
+    }
+
+    return {
+        shape: 'plain-php',
+        componentsOf: null,
+        markersFound: [],
+        reason: 'composer.json requires no component of either framework family',
+        probes,
+    };
+}
+
+/** True when a framework-routing rule must NOT claim this tree. */
+export function frameworkRoutingIsWrong(v: PhpShapeVerdict): boolean {
+    return v.shape === 'components-without-framework';
+}

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 };
+}