@event4u/agent-config 2.19.0 → 2.20.1

package/docs/featured-commands.md

@@ -0,0 +1,27 @@
+# Featured Commands
+
+A curated subset of the 124 active commands. Full set lives in
+[`.agent-src/commands/`](../.agent-src/commands/) — see also
+[`docs/catalog.md`](catalog.md) for the complete index.
+
+## For developers
+
+| Command | What it does |
+|---|---|
+| [`/implement-ticket`](../.agent-src/commands/implement-ticket.md) | Drive a Jira / Linear ticket end-to-end through refine → plan → implement → test → verify |
+| [`/work`](../.agent-src/commands/work.md) | Same end-to-end loop for a free-form prompt — confidence-band gated |
+| [`/fix ci`](../.agent-src/commands/fix.md) | Fetch CI failures from GitHub Actions and fix them |
+| [`/review-changes`](../.agent-src/commands/review-changes.md) | Self-review local changes before creating a PR (five judges) |
+| [`/create-pr`](../.agent-src/commands/create-pr.md) | Create a GitHub PR with Jira-linked description |
+
+## For everyone
+
+| Command | What it does |
+|---|---|
+| [`/research`](../.agent-src/commands/research.md) | Survey / benchmark / competitive scan scaffolder — picks objects, defines fields |
+| [`po-discovery`](../.agent-src/skills/po-discovery/SKILL.md) | Shape a fuzzy product ask into a refined backlog item — problem framing, AC tightening |
+| [`/ghostwriter:write`](../.agent-src/commands/ghostwriter/write.md) | Draft in a public-figure voice profile (mandatory disclosure footer) |
+| [`/challenge-me`](../.agent-src/commands/challenge-me.md) | Interactive grill-style interview that sharpens a fuzzy plan into a copyable pitch |
+| [`/fundraising-narrative`](../.agent-src/skills/fundraising-narrative/SKILL.md) | Shape a capital-raise pitch — why-now / why-us / why-this framing |
+
+→ [Browse all 124 active commands](../.agent-src/commands/)

package/docs/parity/bench-ruflo.json

@@ -0,0 +1,58 @@
+{
+  "schema": "parity-bench-ruflo-v1",
+  "status": "infrastructure_ready_awaiting_corpus_run",
+  "owner_roadmap": "agents/roadmaps/step-11-ruflo-parity.md",
+  "parity_doc": "docs/parity/ruflo.md",
+  "parent_bench": "docs/parity/bench.json",
+  "claim_under_test": {
+    "source": "agents/audit-2026-05-14-north-star/external-findings.md § 2",
+    "headline": "Average dollar cost per 25-prompt corpus run, separated by model tier (Haiku / Sonnet / Opus) and by token class (input / output / cache-read / cache-write).",
+    "comparison_target": "ruflo cost-tracker README (claimed upstream, not yet pulled into this repo)",
+    "type": "claimed_upstream_not_verified_in_repo"
+  },
+  "measurement_protocol": {
+    "corpus": "bench/corpus/* (25-prompt corpus owned by step-4-measurement-and-benchmark.md)",
+    "tracker": "scripts/cost/track.mjs",
+    "pricing": "bench/pricing.yaml",
+    "session_source": "~/.claude/projects/*/sessions/*.jsonl (Claude Code-native, no manual tracking)",
+    "tokens_to_dollars": "track.mjs multiplies input/output/cache-read/cache-write tokens by per-1M pricing from bench/pricing.yaml, separated by model id",
+    "headline_output": "average dollar cost per 25-prompt run, with min / max / p50 / p90 across N reports"
+  },
+  "current_window": {
+    "report_count": 0,
+    "verdict": "awaiting_first_corpus_run",
+    "notes": "Phase 1-5 of step-11 delivered the cost-tracking and bench infrastructure. Phase 6 Step 2 awaits the first end-to-end 25-prompt corpus run against the live tracker. Until then this file exists as a methodology contract, not a verdict surface."
+  },
+  "soak_inheritance": {
+    "follows": "docs/parity/bench.json",
+    "min_days": 60,
+    "min_reports": 30,
+    "earliest_flip": "2026-07-15",
+    "arbiter_command": "task bench:baseline-ready",
+    "notes": "bench-ruflo.json flips status to 'baseline_ready' only after the parent bench.json flips. No independent soak window — same corpus, same arbiter."
+  },
+  "redundancy_verdict": {
+    "status": "pending",
+    "criterion": "Once bench.json soak completes, this verdict is set by comparing the dollar cost in current_window vs ruflo's published table.",
+    "outcome_branches": {
+      "redundant": "Our cost-per-25-prompt-run sits within Ruflo's published range (or beats it). G5 redundancy gate row for cost surface flips green.",
+      "behind": "Our cost-per-run > Ruflo's. Follow-up issue filed; G5 stays open."
+    }
+  },
+  "fields_pending_first_run": [
+    "current_window.avg_cost_per_run_usd",
+    "current_window.cost_by_model.haiku_usd",
+    "current_window.cost_by_model.sonnet_usd",
+    "current_window.cost_by_model.opus_usd",
+    "current_window.cost_by_class.input_usd",
+    "current_window.cost_by_class.output_usd",
+    "current_window.cost_by_class.cache_read_usd",
+    "current_window.cost_by_class.cache_write_usd"
+  ],
+  "decisions_pending": {},
+  "_meta": {
+    "created": "2026-05-16",
+    "created_by": "step-11-ruflo-parity.md Phase 6 Step 2",
+    "spec": "scripts/cost/track.mjs --bench-ruflo (planned wiring); for now the file is a methodology contract"
+  }
+}

package/docs/parity/bench.json

@@ -0,0 +1,41 @@
+{
+  "schema": "parity-bench-v1",
+  "status": "soak_in_progress",
+  "owner_roadmap": "agents/roadmaps/step-4-measurement-and-benchmark.md",
+  "contract": "docs/contracts/measurement-baseline.md",
+  "soak": {
+    "start_date": "2026-05-16",
+    "min_days": 60,
+    "min_reports": 30,
+    "earliest_flip": "2026-07-15",
+    "arbiter_command": "task bench:baseline-ready"
+  },
+  "current_window": {
+    "report_count": 1,
+    "days_elapsed": 0,
+    "verdict": "warmup",
+    "notes": "First infrastructure-shakedown run only. Numbers below are not the baseline."
+  },
+  "shakedown_run": {
+    "report": "bench/reports/2026-05-16T06-13-07Z-dev-projection.md",
+    "corpus": "dev",
+    "selection_accuracy_augment": 0.5,
+    "selection_accuracy_claude": 0.5,
+    "projection_fidelity_claude": 1.0,
+    "projection_fidelity_cursor": "not_applicable",
+    "projection_fidelity_cline": "not_applicable",
+    "projection_fidelity_windsurf": "not_applicable"
+  },
+  "decisions_pending": {
+    "compression_default": {
+      "kill_criterion": "docs/contracts/compression-default-kill-criterion.md",
+      "verdict": "deferred_until_baseline_closes",
+      "decision_owner": "step-4 closeout phase"
+    }
+  },
+  "downstream_consumers": [
+    "agents/roadmaps/step-99-north-star-restructure.md#G1",
+    "agents/roadmaps/step-2-skill-inventory-rationalization.md#G0",
+    "docs/contracts/compression-default-kill-criterion.md"
+  ]
+}

package/docs/parity/ruflo.md

@@ -0,0 +1,46 @@
+# Parity verdict — Ruflo
+
+> Per-row verdict against the eight Ruflo measurement-governance patterns
+> catalogued in
+> [`external-findings.md § 2`](../../agents/audit-2026-05-14-north-star/external-findings.md).
+> Owner roadmap: [`step-11-ruflo-parity.md`](../../agents/roadmaps/step-11-ruflo-parity.md)
+> (Phase 6 Step 1). Cross-index lives at
+> [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md)
+> Phase 5 Step 2.
+>
+> **Verdict legend:** `[x] covered by <file:line>` · `[~] superseded by <approach>` · `[!] gap`.
+> **Acceptance:** zero `[!]` rows. Closure flips the corresponding cell in the
+> [composite scorecard](../../agents/audit-2026-05-14-north-star/external-findings.md#5-composite-scorecard--agent-config-vs-the-field)
+> `vs Ruflo` column from `–` to `=` or `+`.
+
+**Measured-vs-claimed disclaimer:** Each row cites the **mechanism** that
+covers Ruflo's pattern. Numbers attached to those mechanisms (cost figures,
+smoke baselines, ADR count) are claimed until the 25-prompt bench corpus
+soak in [`bench.json`](bench.json) flips from `warmup` to `baseline_ready`
+(min 60 days, ≥ 30 reports — earliest 2026-07-15).
+
+## Verdict table
+
+| # | Ruflo pattern | Verdict | Evidence |
+|---|---|---|---|
+| 1 | **Cost-tracker plugin** — real model pricing, per-1M, separated input/output/cache | `[x] covered by` | [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs) + [`bench/pricing.yaml`](../../bench/pricing.yaml) (Haiku/Sonnet/Opus per-1M, input/output/cache-read/cache-write split). Step-11 Phase 1. |
+| 2 | **Auto-capture from session jsonl** — reads Claude Code log, no manual tracking | `[x] covered by` | [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs) reads `~/.claude/projects/*/sessions/*.jsonl` automatically. Step-11 Phase 1 Step 1. |
+| 3 | **50/75/90/100 % budget ladder with hard stop** | `[x] covered by` | [`scripts/cost/budget.mjs`](../../scripts/cost/budget.mjs) — exit codes 0/1/2/3 per tier; opt-in fail-closed via `cost.enforcement` setting. Fixtures: `tests/fixtures/cost/budget/{under-50,at-100,over-100}/`. Step-11 Phase 2. |
+| 4 | **Measured-vs-claimed disclaimer** — every percentage tagged "claimed upstream" | `[x] covered by` | One-line `**Measured-vs-claimed disclaimer:**` header block on all 9 active roadmaps in `agents/roadmaps/`. Verified 2026-05-16. Step-11 Phase 5 Step 4. |
+| 5 | **Smoke test as contract** — `bash scripts/smoke.sh` with declared baseline | `[x] covered by` | Four per-tier smoke scripts: [`scripts/smoke/kernel.sh`](../../scripts/smoke/kernel.sh), [`router.sh`](../../scripts/smoke/router.sh), [`schema.sh`](../../scripts/smoke/schema.sh), [`skills.sh`](../../scripts/smoke/skills.sh). Declared baselines in [`docs/contracts/smoke-contracts.md`](../contracts/smoke-contracts.md). CI gate: [`.github/workflows/smoke.yml`](../../.github/workflows/smoke.yml). Step-11 Phase 3. |
+| 6 | **Per-plugin ADR directory** — `docs/adrs/0001-*.md` co-located with subsystem | `[x] covered by` | Six bootstrap ADRs under [`docs/adrs/{cost,memory,router,schema,smoke,caveman}/`](../adrs/). Coverage gate: [`scripts/audit_adr_coverage.py`](../../scripts/audit_adr_coverage.py) (`task lint-adr-coverage`). Contract: [`docs/contracts/adr-layout.md`](../contracts/adr-layout.md). Step-11 Phase 4. |
+| 7 | **Namespace contract** — `<stem>-<intent>` kebab-case, reserved-names list | `[x] covered by` | [`scripts/lint_namespace.py`](../../scripts/lint_namespace.py) enforces shape + length floors + reserved-names + skill-dir-matches-name across 430 names · 0 issues. Contract: [`docs/contracts/namespace.md`](../contracts/namespace.md). CI gate: `task lint-namespace`. Step-11 Phase 5 Step 1. |
+| 8 | **Topology choices in swarm** — `hierarchical / mesh / star / adaptive` with anti-drift defaults | `[x] covered by` | [`.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md`](../../.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md) `Topology hints` subsection — 7-row table mapping each mode to topology + Ruflo anti-drift default (`hierarchical, 6–8 agents, raft consensus`). Step-11 Phase 5 Step 2. |
+| 9 | **MCP-tool count + source-line refs** — every tool with `<file>:<line>` citation | `[x] covered by` | [`docs/contracts/mcp-tool-inventory.md`](../contracts/mcp-tool-inventory.md) — 20 tools (9 stdio-implemented · 11 discovery stubs) each with catalog `<file>:<line>` + handler `<file>:<line>`. Generator: [`scripts/audit_mcp_tools.py`](../../scripts/audit_mcp_tools.py). CI drift gate: `task lint-mcp-inventory`. Step-11 Phase 5 Step 3. |
+
+## Open `[!]` rows
+
+**Zero.** Every Ruflo pattern is mechanism-covered. Numbers behind those
+mechanisms remain claimed until [`bench.json`](bench.json) soak completes
+(see disclaimer above).
+
+## Cross-references
+
+- Composite scorecard refresh: owned by [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md) Phase 5 Step 4 (replaces [`external-findings.md § 5`](../../agents/audit-2026-05-14-north-star/external-findings.md)).
+- Bench-ruflo redundancy verdict: [`bench-ruflo.json`](bench-ruflo.json) (step-11 Phase 6 Step 2).
+- G5 redundancy gate cite: step-99 Acceptance Criteria row "G5 — external redundancy (Domination Mandate)".

package/docs/profiles.md

@@ -0,0 +1,91 @@
+# Six entry paths — by `profile.id`
+
+Each block below is the first-screen for one shipped profile. The
+`profile.id` written by `/onboard` selects the anchor; the block names
+the audience, the first three things the agent does for that role,
+and the exact commands and skills wired into the profile YAML at
+[`.agent-src.uncompressed/profiles/<id>.yml`](../.agent-src.uncompressed/profiles/).
+
+The summary table at the top of [`README.md`](../README.md) is the
+one-page index; the prose below is the deep version.
+
+<a id="profile-developer"></a>
+## 👩‍💻 `developer` — IC engineer
+
+Implement a ticket end-to-end, fix CI red, run a self-review before
+the PR. `/implement-ticket` refines the ticket, plans, edits, tests,
+and verifies; `/work` is the free-form sibling; `/review-changes`
+dispatches five judges (bug, security, tests, quality, architecture)
+on the local diff. Stack-aware skills cover Laravel · Symfony ·
+Next.js · React · Node. **Preset default: `balanced`.**
+[Profile YAML](../.agent-src.uncompressed/profiles/developer.yml) ·
+[Role guide](getting-started-by-role.md#developer-the-original-audience).
+
+<a id="profile-content_creator"></a>
+## ✍️ `content_creator` — writers, ghostwriters, marketers
+
+Draft in someone else's voice, plan a quarter of content, ship a
+launch announcement. `/ghostwriter` fetches and writes against a
+public-figure voice profile; `/post-as` is the same primitive for
+your own voice (`.agent-user.md`); `voice-and-tone-design` and
+`messaging-architecture` lock the brand frame before any copy ships.
+**Preset default: `balanced`.**
+[Profile YAML](../.agent-src.uncompressed/profiles/content_creator.yml) ·
+[Role guide](getting-started-by-role.md#creator-writer-marketer-indie-content-shop).
+
+<a id="profile-founder"></a>
+## 🚀 `founder` — solo / early-stage founder
+
+Sharpen a fuzzy idea, rank what to build, write the why-now slide.
+`/challenge-me` runs a grill-style interview that turns a vague plan
+into a copyable pitch; `/council` polls external AIs for a neutral
+second opinion; `rice-prioritization` ranks the backlog;
+`vision-articulation` and `fundraising-narrative` shape the
+internal-vs-external story. **Preset default: `fast`.**
+[Profile YAML](../.agent-src.uncompressed/profiles/founder.yml) ·
+[Role guide](getting-started-by-role.md#founder-early-stage-operator-wearing-every-hat).
+
+<a id="profile-agency"></a>
+## 🏛 `agency` — multi-client delivery shop
+
+Refine a fuzzy client ask into an estimated, AC-tight ticket; turn a
+phase into a roadmap; ship per client without losing decision
+provenance. `/refine-ticket` rewrites the ticket and surfaces top-5
+risks; `estimate-ticket` sizes and splits; `decision-record` anchors
+the trade-off in an ADR before code starts. **Preset default:
+`strict`.**
+[Profile YAML](../.agent-src.uncompressed/profiles/agency.yml) ·
+[Role guide](getting-started-by-role.md#consultant-advisory-freelance-fractional).
+
+<a id="profile-finance"></a>
+## 💼 `finance` — CFO / fractional finance / FP&A
+
+Build a DCF, stress-test the plan, frame the runway call. `dcf-modeling`
+walks the WACC / terminal-value / 5-year-hold reasoning; `forecasting`
+reconciles top-down vs bottom-up; `scenario-modeling` produces the
+base / upside / downside cuts; `runway-cognition` frames the
+fundraise-vs-cut-vs-grow decision. **Preset default: `strict`.**
+[Profile YAML](../.agent-src.uncompressed/profiles/finance.yml) ·
+[Role guide](getting-started-by-role.md#finance--ops-cfo-controller-ops-lead-founder-finance).
+
+<a id="profile-ops"></a>
+## 🛡 `ops` — RevOps, support, SRE-adjacent
+
+Threat-model a change before it ships, command the incident when it
+breaks, build the dashboard that catches it next time.
+`/threat-model` enumerates abuse cases and trust boundaries before
+the first line of code; `incident-commander` frames severity and
+post-mortem; `dashboard-design` chooses the right RED / USE / Golden
+Signal panel. **Preset default: `strict`.**
+[Profile YAML](../.agent-src.uncompressed/profiles/ops.yml) ·
+[Role guide](getting-started-by-role.md#finance--ops-cfo-controller-ops-lead-founder-finance).
+
+> **Universal AI Agent OS, not "for developers only".** The same
+> orchestration core also drives non-software trades. Worked-example
+> user types ship for [galabau](../.agent-src.uncompressed/user-types/galabau-field-crew.md),
+> [metalworking](../.agent-src.uncompressed/user-types/metalworking-shop.md),
+> [truck driving](../.agent-src.uncompressed/user-types/truck-driver.md) —
+> with a [scaffold](../.agent-src.uncompressed/user-types/_template/) for
+> contributing your own.
+
+→ [Public catalog](catalog.md) (all rules, skills, commands, guidelines) · [Skills only](skills-catalog.md) · [llms.txt](../llms.txt)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.19.0",
+    "version": "2.20.1",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_cli/cmd_explain.py

@@ -0,0 +1,250 @@
+"""``agent-config explain`` — print the decision chain behind an outcome.
+
+Step-15 Phase 1 item 3. Answers the silent "why did the agent do that?"
+question by showing which inputs the loader / router consulted, in what
+order, and which one won. Read-only; never edits state, never dispatches
+network calls. Three subjects in the v1 surface:
+
+* ``config``           — full resolution chain for the active profile +
+                         preset. Uses :mod:`scripts.config.profiles` and
+                         :mod:`scripts.config.presets`; surfaces source
+                         (pack / profile / user / env / runtime / default)
+                         and per-knob overrides.
+* ``rule <name>``      — kernel vs tier-1 vs tier-2 placement plus the
+                         declared trigger list from ``router.json``.
+* ``route <text>``     — given prompt text, returns every tier-1 rule
+                         whose trigger list matches plus kernel rules
+                         (always active).
+
+Exit codes: ``0`` clean, ``1`` not found / no match, ``2`` invocation
+error (bad project root, malformed ``router.json``).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from scripts._lib.agent_settings import (
+    DEFAULT_PROJECT_FILE,
+    ProjectRootError,
+    load_agent_settings,
+    resolve_project_root,
+)
+from scripts.config import presets, profiles
+
+ROUTER_FILENAME = "router.json"
+
+
+def _resolve_root(arg: str | None) -> tuple[Path, str]:
+    try:
+        return resolve_project_root(arg, cwd=Path.cwd())
+    except ProjectRootError as exc:
+        print(f"❌  explain: {exc}", file=sys.stderr)
+        raise SystemExit(2) from exc
+
+
+def _load_user_settings(project_root: Path) -> dict[str, Any]:
+    path = project_root / DEFAULT_PROJECT_FILE
+    if not path.exists():
+        return {}
+    return load_agent_settings(project_path=path) or {}
+
+
+def _load_router(project_root: Path) -> dict[str, Any]:
+    path = project_root / ROUTER_FILENAME
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"❌  explain: cannot read {path}: {exc}", file=sys.stderr)
+        raise SystemExit(2) from exc
+
+
+def _explain_config(project_root: Path, *, as_json: bool) -> int:
+    settings = _load_user_settings(project_root)
+    resolved_profile = profiles.resolve_profile(
+        project_root=project_root,
+        user_settings=settings,
+    )
+    resolved_preset = presets.resolve_preset(
+        project_root=project_root,
+        user_settings=settings,
+        profile_preset_id=resolved_profile.preset_id,
+    )
+    payload = {
+        "project_root": str(project_root),
+        "profile": {
+            "id": resolved_profile.id,
+            "source": resolved_profile.source,
+            "preset_id": resolved_profile.preset_id,
+            "warning": resolved_profile.warning,
+        },
+        "preset": {
+            "id": resolved_preset.id,
+            "source": resolved_preset.source,
+            "overrides": list(resolved_preset.overrides),
+            "knobs": resolved_preset.knobs,
+        },
+        "env": {
+            profiles.PROFILE_ID_ENV: os.environ.get(profiles.PROFILE_ID_ENV),
+            presets.PRESET_ID_ENV: os.environ.get(presets.PRESET_ID_ENV),
+        },
+    }
+    if as_json:
+        json.dump(payload, sys.stdout, indent=2, sort_keys=True)
+        sys.stdout.write("\n")
+        return 0
+    print(f"  📍  project_root: {project_root}")
+    print()
+    print(f"  profile.id:   {resolved_profile.id}  (source: {resolved_profile.source})")
+    if resolved_profile.warning:
+        print(f"  ⚠️   {resolved_profile.warning}")
+    print(f"  preset.id:    {resolved_preset.id}  (source: {resolved_preset.source})")
+    if resolved_preset.overrides:
+        print(f"  overrides:    {', '.join(resolved_preset.overrides)}")
+    cost = resolved_preset.knobs.get("cost", {})
+    if cost:
+        print(
+            f"  cost caps:    daily ${cost.get('daily_max_usd')} · "
+            f"weekly ${cost.get('weekly_max_usd')} · "
+            f"monthly ${cost.get('monthly_max_usd')}",
+        )
+    autonomy = resolved_preset.knobs.get("autonomy", {})
+    if autonomy:
+        print(f"  autonomy:     default={autonomy.get('default')}")
+    return 0
+
+
+def _find_rule(router: dict[str, Any], name: str) -> tuple[str, dict[str, Any]] | None:
+    if name in router.get("kernel", []):
+        return "kernel", {"id": name, "triggers": [{"always": True}]}
+    for tier in ("tier_1", "tier_2"):
+        for entry in router.get(tier, []):
+            if entry.get("id") == name:
+                return tier, entry
+    return None
+
+
+def _explain_rule(project_root: Path, name: str, *, as_json: bool) -> int:
+    router = _load_router(project_root)
+    found = _find_rule(router, name)
+    if found is None:
+        print(f"❌  explain: rule {name!r} not found in router", file=sys.stderr)
+        return 1
+    tier, entry = found
+    payload = {"rule": name, "tier": tier, "entry": entry}
+    if as_json:
+        json.dump(payload, sys.stdout, indent=2, sort_keys=True)
+        sys.stdout.write("\n")
+        return 0
+    print(f"  rule:    {name}")
+    print(f"  tier:    {tier}")
+    triggers = entry.get("triggers") or []
+    print(f"  triggers ({len(triggers)}):")
+    for trig in triggers:
+        print(f"    · {trig}")
+    routes = entry.get("routes_to") or []
+    if routes:
+        print(f"  routes_to: {', '.join(routes)}")
+    return 0
+
+
+def _matches_trigger(trigger: dict[str, Any], text: str, lowered: str) -> str | None:
+    """Return a human-readable match reason, or ``None`` for no match."""
+    if "keyword" in trigger:
+        kw = str(trigger["keyword"]).lower()
+        if kw and kw in lowered:
+            return f"keyword: {kw}"
+    if "phrase" in trigger:
+        ph = str(trigger["phrase"]).lower()
+        if ph and ph in lowered:
+            return f"phrase: {ph}"
+    if "path_prefix" in trigger:
+        prefix = str(trigger["path_prefix"])
+        if prefix and prefix in text:
+            return f"path_prefix: {prefix}"
+    return None
+
+
+def _explain_route(project_root: Path, text: str, *, as_json: bool) -> int:
+    router = _load_router(project_root)
+    lowered = text.lower()
+    matches: list[dict[str, Any]] = []
+    for entry in router.get("tier_1", []):
+        for trig in entry.get("triggers", []) or []:
+            reason = _matches_trigger(trig, text, lowered)
+            if reason is not None:
+                matches.append({
+                    "id": entry["id"], "tier": "tier_1", "reason": reason,
+                })
+                break
+    payload = {
+        "input": text,
+        "kernel_always": list(router.get("kernel", [])),
+        "tier_1_matches": matches,
+    }
+    if as_json:
+        json.dump(payload, sys.stdout, indent=2, sort_keys=True)
+        sys.stdout.write("\n")
+        return 0
+    print(f"  input: {text!r}")
+    print()
+    print(f"  kernel (always active, {len(payload['kernel_always'])}):")
+    for kid in payload["kernel_always"]:
+        print(f"    · {kid}")
+    print()
+    print(f"  tier-1 matches ({len(matches)}):")
+    if not matches:
+        print("    · (no trigger matched — only kernel rules active)")
+        return 1
+    for match in matches:
+        print(f"    · {match['id']}  ({match['reason']})")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agent-config explain",
+        description=(
+            "Print the decision chain behind a configuration or routing "
+            "outcome. Read-only; no network calls."
+        ),
+    )
+    parser.add_argument(
+        "subject", choices=("config", "rule", "route"),
+        help="what to explain",
+    )
+    parser.add_argument(
+        "target", nargs="?", default=None,
+        help="rule name (for 'rule') or prompt text (for 'route')",
+    )
+    parser.add_argument(
+        "--project", default=None,
+        help="project root (defaults to anchor walk from cwd)",
+    )
+    parser.add_argument(
+        "--json", action="store_true", dest="as_json",
+        help="emit JSON instead of human-readable text",
+    )
+    opts = parser.parse_args(argv)
+    project_root, _origin = _resolve_root(opts.project)
+    if opts.subject == "config":
+        return _explain_config(project_root, as_json=opts.as_json)
+    if opts.target is None:
+        print(
+            f"❌  explain: '{opts.subject}' requires a target argument",
+            file=sys.stderr,
+        )
+        return 2
+    if opts.subject == "rule":
+        return _explain_rule(project_root, opts.target, as_json=opts.as_json)
+    return _explain_route(project_root, opts.target, as_json=opts.as_json)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

package/scripts/_lib/bench_cost.py

@@ -0,0 +1,138 @@
+# Cost capture for `scripts/bench_run.py` — step-4 Phase 2 Step 2.
+#
+# Reads Claude Code session jsonl summaries (one summary line per session)
+# from agents/cost-tracking/sessions.jsonl — produced by scripts/cost/track.mjs
+# — and aggregates totals using model rates from bench/pricing.yaml.
+#
+# Returns the dict shape declared in docs/contracts/benchmark-report-schema.md
+# § JSON schema (v1) `cost`. When the source jsonl is missing, returns the
+# `unavailable` sentinel block (NEVER silently drops, per schema invariant).
+"""Cost capture helper for the bench runner."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover — bench_run handles the same import
+    yaml = None  # type: ignore[assignment]
+
+UNKNOWN_TIER = "unknown"
+TIER_KEYS = ("haiku", "sonnet", "opus", UNKNOWN_TIER)
+
+
+def load_pricing(pricing_path: Path) -> tuple[dict[str, dict[str, float]], str | None]:
+    """Return ({tier: rates}, oldest_sourced_on) from bench/pricing.yaml."""
+    if yaml is None or not pricing_path.is_file():
+        return {}, None
+    data = yaml.safe_load(pricing_path.read_text(encoding="utf-8")) or {}
+    rates: dict[str, dict[str, float]] = {}
+    oldest: str | None = None
+    for row in data.get("models", []):
+        tier = row.get("tier")
+        if not tier:
+            continue
+        rates[tier] = {
+            "input": float(row.get("input", 0.0)),
+            "output": float(row.get("output", 0.0)),
+            "cache_write": float(row.get("cache_write", 0.0)),
+            "cache_read": float(row.get("cache_read", 0.0)),
+        }
+        sourced = row.get("sourced_on")
+        # YAML 1.1 parses ISO dates to datetime.date; coerce to ISO string.
+        if sourced is not None and not isinstance(sourced, str):
+            sourced = sourced.isoformat() if hasattr(sourced, "isoformat") else str(sourced)
+        if isinstance(sourced, str) and (oldest is None or sourced < oldest):
+            oldest = sourced
+    return rates, oldest
+
+
+def _empty_totals() -> dict[str, int | float]:
+    return {
+        "input_tokens": 0,
+        "output_tokens": 0,
+        "cache_read_input_tokens": 0,
+        "cache_creation_input_tokens": 0,
+        "total_cost_usd": 0.0,
+    }
+
+
+def _empty_per_tier() -> dict[str, dict[str, int | float]]:
+    return {t: {"messages": 0, "cost_usd": 0.0} for t in TIER_KEYS}
+
+
+def unavailable_block(reason: str, source: str, pricing_sourced_on: str | None) -> dict[str, Any]:
+    """Schema-compliant `cost` block when no session jsonl is readable."""
+    return {
+        "source": "unavailable",
+        "reason": reason,
+        "scanned_path": source,
+        "sessions_scanned": 0,
+        "totals": _empty_totals(),
+        "per_tier": _empty_per_tier(),
+        "pricing_sourced_on": pricing_sourced_on,
+    }
+
+
+def aggregate_sessions(
+    sessions_jsonl: Path,
+    pricing_path: Path,
+) -> dict[str, Any]:
+    """Read agents/cost-tracking/sessions.jsonl and aggregate per-tier totals."""
+    rates, pricing_sourced_on = load_pricing(pricing_path)
+    if not sessions_jsonl.is_file():
+        return unavailable_block(
+            reason="sessions_jsonl_missing",
+            source=str(sessions_jsonl),
+            pricing_sourced_on=pricing_sourced_on,
+        )
+
+    totals = _empty_totals()
+    per_tier = _empty_per_tier()
+    sessions_scanned = 0
+
+    for line in sessions_jsonl.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            summary = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        sessions_scanned += 1
+        for _model, slot in (summary.get("byModel") or {}).items():
+            tier = slot.get("tier", UNKNOWN_TIER)
+            if tier not in per_tier:
+                tier = UNKNOWN_TIER
+            totals["input_tokens"] += int(slot.get("input_tokens", 0))
+            totals["output_tokens"] += int(slot.get("output_tokens", 0))
+            totals["cache_read_input_tokens"] += int(slot.get("cache_read_input_tokens", 0))
+            totals["cache_creation_input_tokens"] += int(slot.get("cache_creation_input_tokens", 0))
+            cost = float(slot.get("cost_usd", 0.0))
+            # Recompute from rates if upstream cost is zero AND we have rates;
+            # otherwise trust the upstream attribution (it priced at capture time).
+            if cost == 0.0 and tier in rates:
+                r = rates[tier]
+                cost = (
+                    int(slot.get("input_tokens", 0)) / 1e6 * r["input"]
+                    + int(slot.get("output_tokens", 0)) / 1e6 * r["output"]
+                    + int(slot.get("cache_creation_input_tokens", 0)) / 1e6 * r["cache_write"]
+                    + int(slot.get("cache_read_input_tokens", 0)) / 1e6 * r["cache_read"]
+                )
+            per_tier[tier]["messages"] += int(slot.get("messages", 0))
+            per_tier[tier]["cost_usd"] += cost
+            totals["total_cost_usd"] += cost
+
+    # Round currency to 6 decimals for stable diffs.
+    totals["total_cost_usd"] = round(float(totals["total_cost_usd"]), 6)
+    for t in per_tier.values():
+        t["cost_usd"] = round(float(t["cost_usd"]), 6)
+
+    return {
+        "source": str(sessions_jsonl),
+        "sessions_scanned": sessions_scanned,
+        "totals": totals,
+        "per_tier": per_tier,
+        "pricing_sourced_on": pricing_sourced_on,
+    }