@event4u/agent-config 2.18.0 → 2.20.0

package/docs/contracts/config-presets.md

@@ -0,0 +1,144 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# Config Presets — Contract
+
+> **Status:** beta · **Owner:** package maintainer · **Last reviewed:** 2026-05-16
+>
+> Schema and semantics for the **Config Preset** axis introduced in
+> step-15 Phase 1 item 4. Records the **Cost Enforcement** model
+> (Council v3 action #3 prerequisite) so the preset loader can ship.
+> Boundary against `profile.id`, `pack.id`, and `cost_profile`:
+> [`ADR-010`](../decisions/ADR-010-profile-pack-preset-boundary.md).
+
+## Decision
+
+A **preset** owns governance knobs that the user wants to tune as a
+bundle, not individually. Three seed presets ship; users can declare
+their own under `.agent-src.uncompressed/presets/<id>.yml`.
+
+| `preset.id` | Stance | Typical user |
+|---|---|---|
+| `fast` | Lowest friction; widest autonomy; loosest cost caps | Solo founder, throw-away prototype, exploration |
+| **`balanced`** *(default)* | Moderate friction; per-task autonomy; sensible cost caps | Day-to-day work; default for any new install |
+| `strict` | Highest friction; ask-by-default; tight cost caps; block-on-risk | Production paths, regulated work, shared trunks |
+
+Profile-aware overlay: `developer + strict` ≠ `founder + strict` — the
+profile selects which knob in the preset is read first (e.g. `developer`
+reads `block_on_risk.code_paths`, `founder` reads `block_on_risk.financial_paths`).
+
+## Preset shape
+
+```yaml
+preset:
+  id: balanced
+  autonomy:
+    default: auto              # on | off | auto (see autonomous-execution rule)
+    trivial_suppress: true
+  confidence:
+    min_band: medium           # low | medium | high — block plan if below
+    require_evidence: false
+  risk:
+    block_on: [security, prod_data]
+    ask_on: [bulk_delete, schema_change]
+  council:
+    auto_consult: false
+    cap_per_consult_usd: 0.50
+  mcp:
+    per_call_max_usd: 0.10
+    per_session_max_usd: 2.00
+  cost:
+    daily_max_usd: 10.00
+    weekly_max_usd: 50.00
+    monthly_max_usd: 150.00
+    enforce: hybrid            # see Cost Enforcement section
+  notifications:
+    threshold_pct: [50, 75, 90, 100]
+```
+
+## Cost Enforcement
+
+*Hybrid model* — recorded as the Phase 1 prerequisite per Council v3
+action #3. Two enforcement surfaces, one decision per call.
+
+### Hard enforcement (preset loader, blocking)
+
+The preset loader **refuses to dispatch** any council or MCP call whose
+*estimated* cost exceeds the active preset's per-call ceiling. The
+estimate is read from the model adapter (`council_cli.py estimate` for
+council; the MCP tool manifest for MCP). The block is raised **before**
+the network call. There is no override flag — the user must change the
+preset, override `cost.per_call_max_usd` in `.agent-settings.yml`, or
+pass `--preset=fast` on the CLI.
+
+```
+PRE-CALL CEILING IS HARD.
+NO RUNTIME OVERRIDE. NO "JUST THIS ONCE" FLAG.
+EXCEED → REFUSE → SURFACE THE CEILING + THE OVERRIDE PATH.
+```
+
+Applies to:
+
+- AI Council consults (`scripts/council_cli.py run`).
+- MCP tool calls dispatched through the universal dispatcher
+  ([`hook-architecture-v1`](hook-architecture-v1.md)).
+- Any future skill that reads `preset.cost.per_call_max_usd`.
+
+### Advisory dashboard (retroactive, non-blocking)
+
+`agent-config cost` (Phase 2 item 10) surfaces daily / weekly / monthly
+spend against the active preset's caps. The dashboard **does not**
+block — it warns at the thresholds in `preset.notifications.threshold_pct`
+(default `50 / 75 / 90 / 100`). At 100 %, the dashboard prints a hard
+warning; the next session start re-checks the cap against the running
+total before dispatching the next paid call.
+
+The advisory layer's role is **awareness**, not enforcement. Enforcement
+is exclusively the per-call ceiling above; retroactive blocking would
+turn a session unrecoverably hostile mid-task.
+
+### What the loader does **not** do
+
+- It does **not** estimate cost for unpaid local model calls
+  (`ollama`, local llama.cpp). These bypass both surfaces.
+- It does **not** estimate cost for non-LLM tool calls (file reads,
+  shell commands, MCP-static-resource fetches). The per-call ceiling
+  targets paid token spend.
+- It does **not** override the Hard Floor in
+  [`non-destructive-by-default`](../../.agent-src/rules/non-destructive-by-default.md)
+  — a preset cannot lift the universal safety floor.
+
+## Resolution chain
+
+Reads happen in this order; last writer wins for any single knob:
+
+1. `pack.preset_id` (if pack active) → set `preset.id`.
+2. `profile.preset_id` → set `preset.id` (if not already set by pack).
+3. `preset.<id>.yml` → fill all knobs.
+4. `.agent-settings.yml` user keys under `preset:` → override per-knob.
+5. Environment variables (`AGENT_CONFIG_PRESET_COST_DAILY_MAX_USD=…`)
+   → override per-knob.
+6. Runtime CLI flags (`--preset-cost-per-call-max-usd=…`) → override
+   per-knob, single session.
+
+Per [`ADR-010`](../decisions/ADR-010-profile-pack-preset-boundary.md),
+no other axis may write preset-owned knobs.
+
+## Drift detection
+
+`task lint-config-schema` (added in Phase 1) hard-fails when:
+
+- A pack YAML or profile YAML names a preset-owned knob.
+- A preset YAML names a knob outside this contract.
+- The three seed presets diverge from the documented stances above.
+
+## Non-goals
+
+- This contract does **not** define profiles, packs, or `cost_profile`.
+  See the corresponding contracts.
+- It does **not** ship a UI. CLI-first (`agent-config cost`,
+  `agent-config preset set <id>`).
+- It does **not** auto-migrate existing installs. Without a preset,
+  the loader falls back to current per-knob defaults (`balanced`-equivalent).

package/docs/contracts/cost-dashboard.md

@@ -0,0 +1,143 @@
+---
+stability: beta
+keep-beta-until: 2026-08-12
+---
+
+# Cost governance dashboard
+
+> **Status:** beta — first draft 2026-05-16 (Phase 2 Item 10 of
+> `step-15-product-refinement`).
+>
+> **Related:** [`config-presets`](config-presets.md) (caps schema) ·
+> [`cost-profile-defaults`](cost-profile-defaults.md) (default
+> selection) · `scripts/cost/budget.mjs` (existing local-store
+> primitive) · `scripts/cost/track.mjs` (session ingest).
+
+The `agent-config cost` subcommand surfaces accumulated spend against
+the active preset's caps. Read-only, CLI-first, no UI. Wraps the
+existing `scripts/cost/*.mjs` primitives behind a single discoverable
+verb so a user can ask "where am I against my budget?" without knowing
+the storage layout.
+
+## Surface
+
+```
+agent-config cost                       # default: status (this period's spend)
+agent-config cost status [--json]       # spend vs caps for daily/weekly/monthly
+agent-config cost ingest                # pull latest session.jsonl → local store
+agent-config cost history [--period=today|week|month] [--limit=N]
+agent-config cost reset --confirm       # truncate sessions.jsonl + budget.json
+```
+
+All subcommands are **read-only by default**. `ingest` writes only to
+`agents/cost-tracking/sessions.jsonl`. `reset` is destructive and
+gated by `--confirm` (Hard-Floor per
+[`non-destructive-by-default`](../../.agent-src/rules/non-destructive-by-default.md)).
+
+## `cost status` — output contract
+
+Human format:
+
+```
+Cost (preset: balanced · profile: developer)
+
+Period       Spent      Cap        Remaining   %   Status
+today        $2.43      $10.00     $7.57       24%  ✅
+week         $14.20     $40.00     $25.80      36%  ✅
+month        $52.10     $150.00    $97.90      35%  ✅
+
+MCP calls:     12 today · 47 this week · 188 this month
+Council calls:  1 today ·  3 this week ·  11 this month
+
+Next threshold notification at 75% (week: $30.00).
+```
+
+`--json` output schema:
+
+```json
+{
+  "preset": "balanced",
+  "profile": "developer",
+  "periods": {
+    "today":   {"spent_usd": 2.43,  "cap_usd": 10.00,  "remaining_usd": 7.57,  "pct": 0.243, "status": "ok"},
+    "week":    {"spent_usd": 14.20, "cap_usd": 40.00,  "remaining_usd": 25.80, "pct": 0.355, "status": "ok"},
+    "month":   {"spent_usd": 52.10, "cap_usd": 150.00, "remaining_usd": 97.90, "pct": 0.347, "status": "ok"}
+  },
+  "calls": {
+    "mcp":     {"today": 12, "week": 47, "month": 188},
+    "council": {"today": 1,  "week": 3,  "month": 11}
+  },
+  "next_threshold": {"period": "week", "pct": 0.75, "trigger_usd": 30.00}
+}
+```
+
+### Status field
+
+| Value | Trigger | Exit code |
+|---|---|---|
+| `ok` | `pct < 0.75` | 0 |
+| `warn` | `0.75 ≤ pct < 1.0` | 0 |
+| `over` | `pct ≥ 1.0` | 1 |
+
+Overall exit = worst-of across the three periods. `--json` always
+emits the full object regardless of exit.
+
+## Data sources
+
+| Field | Source |
+|---|---|
+| `preset` | Active preset id from [`config-presets`](config-presets.md) resolution chain. |
+| `cap_usd` | `preset.cost.{daily,weekly,monthly}_max_usd`. |
+| `spent_usd` | Sum of `cost_usd` field over `agents/cost-tracking/sessions.jsonl` records inside the period window. |
+| `calls.mcp.*` | Sum of `mcp_calls` field in the same records. |
+| `calls.council.*` | Count of records whose `kind` is `council`. |
+| `next_threshold` | Smallest `(period, pct ∈ preset.notifications.threshold_pct)` tuple where `spent_usd < pct × cap_usd`. |
+
+When the active preset declares no `cost.*` cap (legacy installs),
+`cap_usd` is reported as `null` and `status` is `ok`. The tool does
+**not** invent a default cap.
+
+## Enforcement vs surfacing
+
+`agent-config cost` is **read-only**. Enforcement (refuse a council
+or MCP call that would push spend over a cap) lives at the call site
+per the active preset's `cost.enforce` setting (`off`, `advisory`,
+`hybrid`, `hard`). This contract does not change enforcement; it only
+makes the existing local-store data discoverable.
+
+## Refresh model
+
+`sessions.jsonl` is appended to by the Claude Code session hooks
+(see `scripts/cost/track.mjs`). `cost status` reads what's there;
+`cost ingest` triggers a one-shot pull from `~/.claude/projects/`.
+Users running a non-Claude-Code agent surface call `cost ingest`
+manually after a session; users on Claude Code with hooks installed
+never need to.
+
+## Validation
+
+`scripts/lint_cost_dashboard.py` (Phase 2 deliverable — not yet
+shipped) fails CI on:
+
+- Schema drift in `sessions.jsonl` (missing required fields).
+- Preset declaring `cost.*` caps that disagree with this contract's
+  expected period grid.
+- `cost status --json` output diverging from the schema above.
+
+## What this contract does **not** do
+
+- **Does not** ship a UI. CLI-first, by design.
+- **Does not** introduce per-skill or per-command cost attribution
+  beyond `kind` (`council` vs other). Per-skill attribution is a
+  Phase 3 candidate.
+- **Does not** override per-call hard caps from the preset.
+- **Does not** roll up across multiple projects. Each project's
+  `agents/cost-tracking/` is its own scope.
+
+## See also
+
+- [`config-presets`](config-presets.md) — preset caps + `enforce` semantics
+- [`cost-profile-defaults`](cost-profile-defaults.md) — default preset selection
+- [`safety-model`](safety-model.md) — `mcp_call_costly` domain
+- `scripts/cost/budget.mjs`, `scripts/cost/track.mjs` — wrapped primitives
+- `step-15-product-refinement` § Phase 2 Item 10

package/docs/contracts/cost-enforcement.md

@@ -0,0 +1,134 @@
+---
+stability: stable
+---
+
+# Cost Enforcement Contract
+
+> Status: stable · Owner: `step-11-measurement-governance-parity` · Last reviewed: 2026-05-16
+
+How USD budgets read from `.agent-settings.yml` interact with the
+session-cost ledger (`agents/cost-tracking/sessions.jsonl`) and the
+budget evaluator (`scripts/cost/budget.mjs`).
+
+## Surface
+
+Two files. Settings file declares the budget; ledger file accumulates
+spend. The evaluator joins them and emits a tier.
+
+| File | Role |
+|---|---|
+| `.agent-settings.yml § cost` | Declarative: budgets per period + enforcement mode. |
+| `agents/cost-tracking/sessions.jsonl` | Append-only: per-session cost records (model, tokens, USD). |
+| `scripts/cost/budget.mjs` | Evaluator: joins both, emits `{ level, utilization_pct, enforcement, source }`. |
+| `scripts/cost/preflight.mjs` | Hard-stop hook: wraps `budget.mjs check` and exits non-zero at HARD_STOP when `enforcement: hard-stop`. |
+
+## Settings schema
+
+```yaml
+cost:
+  budgets:
+    daily: 0     # USD ceiling for rolling 24h. 0 = unbudgeted.
+    weekly: 0    # USD ceiling for rolling 7d.  0 = unbudgeted.
+    monthly: 0   # USD ceiling for rolling 30d. 0 = unbudgeted.
+  enforcement: advisory   # advisory | hard-stop
+```
+
+- `0` (or absent) on any period = that period is not enforced. The
+  evaluator falls back to a longer-period budget when checking shorter
+  periods, never the other way around.
+- `enforcement: advisory` is the default. Dashboards surface the
+  breach; the agent keeps working.
+- `enforcement: hard-stop` is opt-in. `scripts/cost/preflight.mjs`
+  exits non-zero at the HARD_STOP tier; wrapping shells / CI / `task`
+  bindings must check this before composing a turn.
+
+## Tier ladder (5-stage)
+
+| Utilization | Level | Emoji | Threshold-pct |
+|---:|---|:---:|---:|
+| `< 50 %` | `OK` | 🟢 | 0 |
+| `50–74 %` | `INFO` | 🟡 | 50 |
+| `75–89 %` | `WARNING` | 🟠 | 75 |
+| `90–99 %` | `CRITICAL` | 🔴 | 90 |
+| `≥ 100 %` | `HARD_STOP` | 🛑 | 100 |
+
+The legacy 4-stage draft (`under / 50 / 75 / 90 / 100`) folded `OK`
+into `under`. Parity-doc Phase 6 maps both forms verbatim.
+
+## Hook surface
+
+`scripts/cost/preflight.mjs` is the **single** turn-start surface.
+It wraps `budget.mjs check` and:
+
+1. Reads `cost.enforcement` from `.agent-settings.yml`.
+2. If `advisory` → always exits `0`, prints the tier as advisory text.
+3. If `hard-stop` and level is `HARD_STOP` → prints a refusal block
+   citing this contract and exits `1`.
+4. If no budget is configured at all → exits `0` (fail-open). Never
+   blocks unbudgeted work.
+
+The hook does **not** rewrite or block individual tool calls. It is a
+process-entry gate, intended to be invoked by:
+
+- `task ci`, `task work:*`, `task roadmap:*` wrappers.
+- The `/onboard` boot path (`scripts/install.py`-side guidance only).
+- Manual `node scripts/cost/preflight.mjs` for shell wrappers.
+
+## Bypass
+
+User-facing bypass mechanism (documented for the refusal block):
+
+- Raise the budget: edit `.agent-settings.yml § cost.budgets.<period>`.
+- Reset the ledger (drops historical spend from the calculation):
+  `node scripts/cost/track.mjs reset --confirm`.
+- Disable enforcement: set `cost.enforcement: advisory`.
+
+No environment-variable override. Bypass must be an explicit edit so
+the change is durable and auditable.
+
+## Default behaviour without a budget
+
+When `cost.budgets.{daily,weekly,monthly}` are all `0`:
+
+- `budget.mjs check` reports cumulative spend, no tier (returns the
+  no-budget JSON shape).
+- `preflight.mjs` exits `0`. Never blocks.
+- `agent-status` panel shows **only** the measured-spend USD figure;
+  the tier table is suppressed.
+
+## Source precedence
+
+`budget.mjs` reads budget config in this order:
+
+1. `.agent-settings.yml § cost` (when any value > 0).
+2. `agents/cost-tracking/budget.json` (legacy single-period JSON).
+3. None → no-budget output shape.
+
+The evaluator output carries `source: 'agent-settings.yml' | 'budget.json'`
+so dashboards can show where the figure came from.
+
+## Period mapping
+
+`BUDGET_PERIOD={today|week|month|all}` selects which budget value
+applies:
+
+| `BUDGET_PERIOD` | Settings key |
+|---|---|
+| `today` | `cost.budgets.daily` |
+| `week` | `cost.budgets.weekly` |
+| `month` | `cost.budgets.monthly` |
+| `all` (default) | First non-zero of `monthly → weekly → daily`. |
+
+## Acceptance fixtures
+
+`tests/fixtures/cost/budget/` carries five reference fixtures:
+`under-50`, `mid-75`, `high-90`, `at-100`, `over-100`. Each fixture
+ships a `sessions.jsonl` slice + an expected JSON output. The fixture
+suite is wired to `task test-cost-budget` per `step-11` Phase 2 Step 5.
+
+## See also
+
+- `step-11-ruflo-parity` — Measurement & Governance Parity roadmap.
+- `docs/contracts/cost-dashboard.md` — companion dashboard contract.
+- `scripts/cost/budget.mjs` — evaluator implementation.
+- `bench/pricing.yaml` — per-model USD pricing table.

package/docs/contracts/file-ownership-matrix.json

@@ -6928,13 +6928,6 @@
       "via": "body_link",
       "depth": 1
     },
-    {
-      "source": ".agent-src.uncompressed/rules/no-cheap-questions.md",
-      "target": ".agent-src.uncompressed/contexts/contracts/frugality-charter.md",
-      "type": "READ_ONLY",
-      "via": "body_link",
-      "depth": 1
-    },
     {
       "source": ".agent-src.uncompressed/rules/no-cheap-questions.md",
       "target": ".agent-src.uncompressed/rules/ask-when-uncertain.md",

package/docs/contracts/mcp-tool-inventory.md

@@ -0,0 +1,53 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# MCP tool inventory
+
+> Generated by [`scripts/audit_mcp_tools.py`](../../scripts/audit_mcp_tools.py)
+> from the source-of-truth catalog
+> [`scripts/mcp_server/consumer_tool_catalog.json`](../../scripts/mcp_server/consumer_tool_catalog.json).
+> Do **not** hand-edit; rerun `python3 scripts/audit_mcp_tools.py --write`.
+>
+> Step-11 Phase 5 Step 3 (`step-11-ruflo-parity.md`).
+
+## Summary
+
+- **Total tools:** 20
+- **By transport:** stdio=9
+- **By side-effect:** fs-write=5, ro=12, shell=3
+- **Discovery-only stubs (no implementation):** 11
+
+## Tools
+
+| Tool | Side-effect | Transports | Catalog | Handler |
+|---|---|---|---|---|
+| `lint_skills` | `ro` | stdio | [`consumer_tool_catalog.json:7`](../../scripts/mcp_server/consumer_tool_catalog.json#L7) | [`tools.py:510`](../../scripts/mcp_server/tools.py#L510) |
+| `chat_history_append` | `fs-write` | stdio | [`consumer_tool_catalog.json:24`](../../scripts/mcp_server/consumer_tool_catalog.json#L24) | [`tools.py:535`](../../scripts/mcp_server/tools.py#L535) |
+| `chat_history_read` | `ro` | stdio | [`consumer_tool_catalog.json:43`](../../scripts/mcp_server/consumer_tool_catalog.json#L43) | [`tools.py:571`](../../scripts/mcp_server/tools.py#L571) |
+| `memory_lookup` | `ro` | stdio | [`consumer_tool_catalog.json:59`](../../scripts/mcp_server/consumer_tool_catalog.json#L59) | [`tools.py:590`](../../scripts/mcp_server/tools.py#L590) |
+| `memory_signal` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:75`](../../scripts/mcp_server/consumer_tool_catalog.json#L75) | _stub-only_ |
+| `memory_status` | `ro` | stdio | [`consumer_tool_catalog.json:91`](../../scripts/mcp_server/consumer_tool_catalog.json#L91) | [`tools.py:617`](../../scripts/mcp_server/tools.py#L617) |
+| `skill_trigger_eval` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:98`](../../scripts/mcp_server/consumer_tool_catalog.json#L98) | _stub-only_ |
+| `suggest_command` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:114`](../../scripts/mcp_server/consumer_tool_catalog.json#L114) | _stub-only_ |
+| `suggest_skill_for_task` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:129`](../../scripts/mcp_server/consumer_tool_catalog.json#L129) | _stub-only_ |
+| `mine_session` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:144`](../../scripts/mcp_server/consumer_tool_catalog.json#L144) | _stub-only_ |
+| `update_form_request_messages` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:158`](../../scripts/mcp_server/consumer_tool_catalog.json#L158) | _stub-only_ |
+| `sync_gitignore` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:173`](../../scripts/mcp_server/consumer_tool_catalog.json#L173) | _stub-only_ |
+| `sync_agent_settings` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:186`](../../scripts/mcp_server/consumer_tool_catalog.json#L186) | _stub-only_ |
+| `run_tests` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:200`](../../scripts/mcp_server/consumer_tool_catalog.json#L200) | _stub-only_ |
+| `run_quality_checks` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:214`](../../scripts/mcp_server/consumer_tool_catalog.json#L214) | _stub-only_ |
+| `list_skills` | `ro` | stdio | [`consumer_tool_catalog.json:227`](../../scripts/mcp_server/consumer_tool_catalog.json#L227) | [`tools.py:631`](../../scripts/mcp_server/tools.py#L631) |
+| `list_commands` | `ro` | stdio | [`consumer_tool_catalog.json:234`](../../scripts/mcp_server/consumer_tool_catalog.json#L234) | [`tools.py:644`](../../scripts/mcp_server/tools.py#L644) |
+| `list_rules` | `ro` | stdio | [`consumer_tool_catalog.json:241`](../../scripts/mcp_server/consumer_tool_catalog.json#L241) | [`tools.py:657`](../../scripts/mcp_server/tools.py#L657) |
+| `compile_router` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:248`](../../scripts/mcp_server/consumer_tool_catalog.json#L248) | _stub-only_ |
+| `read_resource_body` | `ro` | stdio | [`consumer_tool_catalog.json:261`](../../scripts/mcp_server/consumer_tool_catalog.json#L261) | [`tools.py:670`](../../scripts/mcp_server/tools.py#L670) |
+
+## Glossary
+
+- **Side-effect** — `ro` (read-only) · `fs-write` (filesystem write) · `shell` (spawns processes).
+- **Transports** — `stdio` (`scripts/mcp_server/`) · `worker` (`workers/mcp/`). A tool may live on both.
+- **Stub** — catalog-listed for discovery; returns the `not_implemented` envelope from
+  [`mcp-tool-stub-envelope.md`](mcp-tool-stub-envelope.md) until promoted.
+

package/docs/contracts/measurement-baseline.md

@@ -0,0 +1,102 @@
+---
+stability: stable
+---
+
+# Measurement baseline — contract
+
+> **Status:** locked 2026-05-16 · **Owner:** `step-4-measurement-and-benchmark.md`
+> · **Cited by:** every P2 enforcement roadmap (skill rationalization G0, north-star G1, compression default decision).
+
+Single source of truth for what `task bench` measures, what counts as
+drift, and what unblocks enforcement. Read this before pinning a number
+to a roadmap or PR description.
+
+## What `task bench` measures
+
+Four axes, all numeric, all reproducible from the same input:
+
+| Axis | Source | Definition | Units |
+|---|---|---|---:|
+| **selection accuracy** | [`scripts/bench_runner.py`](../../scripts/bench_runner.py) | Keyword-overlap ranker hits the expected skill in top-K | % |
+| **cost** | [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs) session jsonl | Token+USD per model, captured live | USD |
+| **quality** | regex / rubric assertions per prompt | `quality_assertion` matches in agent output | % |
+| **projection fidelity** | [`scripts/bench_per_tool.py`](../../scripts/bench_per_tool.py) | `accuracy(tool) / accuracy(augment)` for skill-projecting tools | ratio |
+
+Schemas: [`benchmark-report-schema.md`](benchmark-report-schema.md) ·
+[`benchmark-corpus-spec.md`](benchmark-corpus-spec.md). Reports land at
+`bench/reports/<utc-stamp>-<corpus>[-projection].{json,md}` —
+timestamped, never overwritten, content-addressed by run.
+
+## Corpora — frozen for the soak window
+
+| Corpus | Path | Prompts | Purpose |
+|---|---|---:|---|
+| `dev` | [`tests/eval/corpus-dev.yaml`](../../tests/eval/corpus-dev.yaml) | 10 | Developer task surface (Laravel/Symfony/React/CI/PR) |
+| `non-dev` | [`tests/eval/corpus-non-dev.yaml`](../../tests/eval/corpus-non-dev.yaml) | 16 | Founder / agency / content creator surface (Wing-4) |
+
+Total 26 prompts ≥ Acceptance Criteria floor of 25. Mid-window edits
+to either YAML restart the 60-day clock per
+[`compression-default-kill-criterion.md`](compression-default-kill-criterion.md) § 2.
+
+## What counts as drift
+
+[`scripts/bench_drift_check.py`](../../scripts/bench_drift_check.py)
+compares the latest report against a sliding window of the prior N runs
+(default 5) for the same corpus.
+
+| Axis | Threshold | Note |
+|---|---|---|
+| selection accuracy | latest − baseline_mean ≤ −5 pp | always evaluated |
+| cost | latest / baseline_mean ≥ +20 % | only when both sides have `source: captured` |
+| quality | latest − baseline_mean ≤ −10 pp | skipped when latest is `not_collected` |
+| projection fidelity | tool fidelity < 0.85 | exit 1 from `task bench:projection` |
+
+Drift exits with code 2 from `task bench:drift`. **CI posture during
+soak:** all bench-drift steps `continue-on-error: true` and post a
+sticky PR comment — informational only, not a merge gate. Flip to
+required check happens via a separate PR once
+`task bench:baseline-ready` returns 0 (see below).
+
+## What unblocks enforcement (the G1 gate)
+
+```
+TASK bench:baseline-ready EXIT 0 IS THE ONLY AUTHORITY.
+NO ANECDOTE, NO INDIVIDUAL REPORT, NO ROADMAP-SIDE OVERRIDE.
+```
+
+[`scripts/bench_baseline_ready.py`](../../scripts/bench_baseline_ready.py)
+returns exit 0 iff both:
+
+1. **Wall-clock soak:** `today − bench/baseline-start.txt ≥ --min-days` (default 60)
+2. **Report density:** `bench/reports/*-<corpus>.json` count ≥ `--min-reports` (default 30)
+
+Soak start anchored at [`bench/baseline-start.txt`](../../bench/baseline-start.txt)
+= **2026-05-16**. Earliest possible flip: **2026-07-15**, contingent
+on the 30-report floor.
+
+Downstream consumers:
+
+- ``step-99-north-star-restructure.md` § Acceptance G1` — reads this exit code.
+- [`compression-default-kill-criterion.md` § 3](compression-default-kill-criterion.md) — reads the decision table after baseline closes.
+- ``step-2-skill-inventory-rationalization.md` § G0` — usage-data soak floor.
+
+## What the closeout writes
+
+On baseline closure, the step-4 closeout writes the numeric verdict to
+[`docs/parity/bench.json`](../parity/bench.json) — frozen snapshot with
+the 30+ reports averaged, drift verdict, and the compression-default
+decision per the kill-criterion table. That file is the artefact every
+P2 roadmap reads — not the live `bench/reports/` directory.
+
+## Carve-outs
+
+- **Pricing freshness:** [`bench/pricing.yaml`](../../bench/pricing.yaml) rows must carry `sourced_on: YYYY-MM-DD`. Stale prices = stale numbers = no trust (ruflo "measured-vs-claimed" pattern).
+- **Subjective grading excluded:** quality scoring is mechanical via `quality_assertion`. No vibes.
+- **Cursor / Cline / Windsurf:** rules-only surfaces, no SKILL.md projection. `bench:projection` reports them as `not_applicable` — the gap is acknowledged, not silently dropped.
+
+## Cross-references
+
+- [`benchmark-report-schema.md`](benchmark-report-schema.md) · per-report JSON schema
+- [`benchmark-corpus-spec.md`](benchmark-corpus-spec.md) · corpus YAML schema
+- [`compression-default-kill-criterion.md`](compression-default-kill-criterion.md) · decision table read by step-4 closeout
+- `step-4-measurement-and-benchmark.md` · the owning roadmap