@event4u/agent-config 2.19.0 → 2.20.0

package/docs/architecture/current-onboard-baseline.md

@@ -0,0 +1,126 @@
+# Current `/onboard` Baseline (pre-step-15)
+
+> **Status:** descriptive baseline · **Owner:** package maintainer ·
+> **Last reviewed:** 2026-05-16
+>
+> Documents the **current** `/onboard` flow so the Phase 1 Guided
+> Setup Wizard (step-15 item 2) has a baseline to extend. Council v3
+> unique finding (cannot "extend" an undocumented surface). This file
+> describes what ships today; it is **not** a proposal.
+
+## Surface
+
+`/onboard` lives at [`.agent-src.uncompressed/commands/onboard.md`](../../.agent-src.uncompressed/commands/onboard.md)
+(canonical source) and is triggered by the
+[`onboarding-gate`](../../.agent-src/rules/onboarding-gate.md) rule on
+the first turn when `onboarding.onboarded == false` in
+`.agent-settings.yml`. Cloud surfaces (Claude.ai Web, Skills API): fully
+inert — no settings file, no flow.
+
+## The 12 steps today
+
+| # | Step | Captures | Asked if |
+|---|---|---|---|
+| 1 | Greet + set expectations | — | always |
+| 2 | Offer user-global cross-project defaults | intent flag for step 9 | first-time-setup heuristic only |
+| 3 | `personal.user_name` | first name | unset |
+| 4 | `personal.ide` (+ auto-detect via `ps aux`) and `personal.open_edited_files` | IDE id, auto-open flag | unset |
+| 5 | `personal.pr_comment_bot_icon` | bool | always (no detection possible) |
+| 6 | `personal.rtk_installed` (via `which rtk`) | bool + install action | rtk not found |
+| 7 | `cost_profile` and `pipelines.skill_improvement` | profile id, learning bool | always (one summary screen) |
+| 8 | Mark `onboarding.onboarded: true` | — | always |
+| 9 | Write user-global `~/.event4u/agent-config/agent-settings.yml` | six whitelisted keys | step 2 captured "yes" |
+| 10 | Summary block | — | always |
+| 11 | Quickstart pointer (`/work` and `/implement-ticket`) | — | local only |
+| 12 | Maintainer telemetry hint (opt-in) | — | local only |
+
+## What `/onboard` does **not** capture today
+
+Step-15 Phase 1 item 2 introduces a new role-selection step ("8 options
+covering Software / Content / Founder / Consulting / Marketing / Finance
+/ Handwerk / Self-configure") that produces a `user_type`. Today, no
+`user_type` is captured. Specifically:
+
+- **No audience/role question.** `/onboard` knows the developer's name,
+  IDE, and rtk install status — never the audience taxonomy.
+- **No `profile.id`.** `profile.id` does not exist as a key in
+  `.agent-settings.yml`. Per
+  [ADR-010](../decisions/ADR-010-profile-pack-preset-boundary.md), it
+  is owned by the Phase 1 item 1 profile loader.
+- **No `preset.id`.** Same status — `preset.id` arrives with Phase 1
+  item 4.
+- **No `pack.id`.** Arrives with Phase 2 item 7.
+- **No risk-appetite question.** The current flow defers risk posture
+  to `personal.autonomy`, which is itself not part of the onboard
+  questions (it inherits the template default).
+- **No stack question.** Stack is inferred at runtime by detectors
+  (`scripts/detect/*`), not asked here.
+
+## Settings keys written today
+
+```yaml
+personal:
+  user_name: "<first-name>"        # step 3
+  ide: "code|phpstorm|cursor"       # step 4
+  open_edited_files: true|false     # step 4
+  pr_comment_bot_icon: true|false   # step 5
+  rtk_installed: true|false         # step 6
+cost_profile: "balanced"             # step 7 (default unchanged)
+pipelines:
+  skill_improvement: true            # step 7 (default unchanged)
+onboarding:
+  onboarded: true                    # step 8
+```
+
+User-global file (step 9, opt-in): the six whitelisted keys in
+[`scripts/_lib/agent_settings.py`](../../scripts/_lib/agent_settings.py)
+— `name`, `ide`, `cost_profile`, `personal.bot_icon`,
+`personal.autonomy`, `caveman.speak_scope`.
+
+## Iron Laws today
+
+- **One question per turn** ([`ask-when-uncertain`](../../.agent-src/rules/ask-when-uncertain.md)).
+- **Re-runnable** — invoking `/onboard` when `onboarded: true` walks the
+  flow again, never silently rewrites a value (asks before overwriting
+  `user_name` / `ide`).
+- **Never commits** — `.agent-settings.yml` is git-ignored.
+- **User-global write is opt-in + one-shot + never silent** — step 2
+  captures intent, step 9 re-confirms.
+
+## Gaps the wizard (Phase 1 item 2) must close
+
+1. **Add role-selection step** producing a `user_type` (later mapped to
+   `profile.id`). Eight options covering Software / Content / Founder /
+   Consulting / Marketing / Finance / Handwerk / Self-configure.
+   Inserted **before** step 8 (mark onboarded) so the profile loader
+   has a value to read on the next session start.
+2. **Add stack-detection confirmation step.** Run the existing
+   `scripts/detect/*` detectors, present the result, allow the user
+   to override. Without confirmation, profile-aware presets cannot
+   resolve.
+3. **Add risk-appetite question.** Maps to `preset.id` from
+   [`config-presets.md`](../contracts/config-presets.md). Three
+   options: `fast` / `balanced` / `strict`.
+4. **Write the new keys.** `profile.id`, `preset.id`, optionally
+   `pack.id`, plus the user-typed `user_type` as a stable audit field.
+
+## Wizard contract (Phase 1 item 2 acceptance)
+
+The wizard MUST:
+
+- Preserve every existing step semantically (no silent removal).
+- Insert role + stack + risk-appetite questions **before** step 8.
+- Honor the one-question-per-turn Iron Law.
+- Write `profile.id`, `preset.id`, and `user_type` to
+  `.agent-settings.yml` using the section-aware merge rules.
+- Be re-runnable (idempotent for unchanged answers).
+- Work offline (no network call required for any question).
+- Skip itself on cloud surfaces (inherit current cloud-noop behavior).
+
+## See also
+
+- [`/onboard` command](../../.agent-src.uncompressed/commands/onboard.md) — canonical source.
+- [`onboarding-gate`](../../.agent-src/rules/onboarding-gate.md) — trigger rule.
+- [`ADR-010`](../decisions/ADR-010-profile-pack-preset-boundary.md) — boundary the wizard must respect.
+- [`config-presets.md`](../contracts/config-presets.md) — preset axis the wizard writes.
+- [`agents/roadmaps/step-15-product-refinement.md`](../../agents/roadmaps/step-15-product-refinement.md) — Phase 1 item 2.

package/docs/architecture/current-safety-behavior.md

@@ -0,0 +1,137 @@
+# Current Safety Behavior — Baseline (pre-step-15)
+
+> **Status:** descriptive baseline · **Owner:** package maintainer ·
+> **Last reviewed:** 2026-05-16
+>
+> Documents the **current** safety / autonomy surface so the Phase 2
+> Universal Safety Model ADR (step-15 item 9) has a baseline to diff
+> against. Council v3 action #4 prerequisite. This file describes what
+> ships today; it is **not** a proposal for what should ship next.
+
+## Scope
+
+The current package has **one autonomy switch** plus **four
+non-overridable floors**. The Phase 2 ADR will replace the single switch
+with per-profile, per-domain `deny / ask / allow` declarations. Before
+that ADR can specify "replace X", X has to be written down.
+
+## The one switch — `personal.autonomy`
+
+**Where defined:** `.agent-settings.yml` under `personal.autonomy`.
+Template: `config/agent-settings.template.yml`.
+
+**Values:** `on` · `off` · `auto`.
+
+**Read site:** [`.agent-src/rules/autonomous-execution.md`](../../.agent-src/rules/autonomous-execution.md)
+(Iron-Law rule, kernel-loaded in every profile). Cached on the first
+turn; missing key treated as `on`.
+
+**What it gates:** trivial workflow questions (suppression). Examples:
+"Should I run the tests now?", "Should I create the branch?", "Continue
+with the next phase?". These are suppressed when `autonomy` resolves to
+`on`.
+
+**What it does NOT gate:** any of the four floors below, any
+[`scope-control`](../../.agent-src/rules/scope-control.md) git operation,
+or any [`commit-policy`](../../.agent-src/rules/commit-policy.md) commit
+default. The switch only narrows the **trivial-question** surface.
+
+### State table
+
+| State | Behavior on trivial workflow questions | Blocking / Hard-Floor / Commit gates |
+|---|---|---|
+| `on` | **Suppress** — agent acts, surfaces what it did | Unchanged — still apply |
+| `off` | **Ask** — numbered options, single question | Unchanged — still apply |
+| `auto` | Same as `off` until the user opts in via a standing autonomy directive ("just work", "arbeite eigenständig"). Then sticky-flip to `on` for the rest of the conversation. Mirror opt-out flips back. | Unchanged — still apply |
+
+### Opt-in detection
+
+Intent-matched, not literal-string-matched. Speech-act-checked: the
+phrase must be a meta-instruction, not content / quote / code. Detail:
+[`autonomy-detection`](../../.agent-src/contexts/execution/autonomy-detection.md),
+[`autonomy-mechanics`](../../.agent-src/contexts/execution/autonomy-mechanics.md).
+
+### Task scope vs conversation scope
+
+Two distinct autonomy shapes:
+
+| Shape | Trigger | Scope |
+|---|---|---|
+| **Conversation-wide trivial-question suppression** | "stop asking on trivial steps" — no deliverable named | Sticky for the rest of the conversation. Suppresses trivial workflow questions only. |
+| **Task-scoped autonomous execution** | "work autonomously on X", "arbeite die Roadmap Y komplett ab" — deliverable named | Bound to that task. Ends when the task ends. Does NOT authorize a different later deliverable. |
+
+Per [`autonomous-execution § task-scope`](../../.agent-src/rules/autonomous-execution.md#task-scope--autonomy-is-bound-to-the-named-task).
+
+## The four non-overridable floors
+
+No value of `personal.autonomy` lifts any of these. Standing
+autonomy directives, roadmap authorizations, or "just keep going"
+phrases never reach them.
+
+### 1. Hard Floor — `non-destructive-by-default`
+
+[`.agent-src/rules/non-destructive-by-default.md`](../../.agent-src/rules/non-destructive-by-default.md).
+Stops on: production-branch merges; deploy / release; push to remote;
+production data / infra writes; whimsical bulk deletions; commits
+containing bulk deletions or infra changes. **Always confirm this turn.**
+
+### 2. Git-ops Permission Gate — `scope-control`
+
+[`.agent-src/rules/scope-control.md § Git operations`](../../.agent-src/rules/scope-control.md#git-operations--permission-gated).
+Stops on: commit · push · merge · rebase · force-push · branch create /
+switch / delete · PR create / close / retarget · tag / release / pin.
+Permission must be **this turn or a standing instruction not yet
+revoked**.
+
+### 3. Commit Default — `commit-policy`
+
+[`.agent-src/rules/commit-policy.md`](../../.agent-src/rules/commit-policy.md).
+**Never commit, never ask about committing.** Four exceptions: user
+says so this turn · standing instruction · `/commit` invoked · roadmap
+authorization. Anything else → no commit.
+
+### 4. Security-sensitive STOP — `security-sensitive-stop`
+
+[`.agent-src/rules/security-sensitive-stop.md`](../../.agent-src/rules/security-sensitive-stop.md).
+Stops on: auth, billing, tenant boundaries, secrets, uploads,
+integrations, webhooks, public endpoints. Threat-model **before**
+editing.
+
+## Coverage map
+
+| Surface | What governs it |
+|---|---|
+| Trivial workflow question | `personal.autonomy` (the switch) |
+| Blocking architectural / scope question | [`ask-when-uncertain`](../../.agent-src/rules/ask-when-uncertain.md) (always) |
+| Tool / MCP call cost | None today — Phase 1 item 4 introduces preset-loader Hard Enforcement |
+| Skill / command allowlist per audience | None today — Phase 2 item 7 introduces packs |
+| Per-domain `deny / ask / allow` | None today — Phase 2 item 9 introduces this |
+| Hard Floor (prod, deploy, push, bulk-destructive) | Universal — not switchable |
+| Git ops | Universal permission gate — not switchable |
+| Commit | Universal default-deny — not switchable |
+
+## Gaps the Phase 2 ADR will address
+
+1. **One switch, one granularity.** Today, `autonomy: on` suppresses
+   *every* trivial question identically. A founder running the
+   `content-engine` pack may want autonomy for content, ask-mode for
+   spend; the current model cannot express that.
+2. **No per-domain policy.** Domain-safety rules
+   (`.agent-src/rules/domain-safety-*.md`) act as output floors but do
+   not declare `deny / ask / allow` per profile. The Phase 2 model
+   centralizes this.
+3. **No machine-readable safety schema.** The current behavior is
+   distributed across four rules. A consuming tool (the wizard, the
+   explain command) cannot ask "what is this install's safety posture?"
+   without reading rule prose.
+
+The Phase 2 ADR (`docs/contracts/safety-model.md`) inherits this
+baseline and adds: per-profile policy table, machine-readable schema,
+explain-trace integration. It MUST NOT silently relax any of the four
+floors above.
+
+## See also
+
+- [`autonomous-execution`](../../.agent-src/rules/autonomous-execution.md) · [`non-destructive-by-default`](../../.agent-src/rules/non-destructive-by-default.md) · [`scope-control`](../../.agent-src/rules/scope-control.md) · [`commit-policy`](../../.agent-src/rules/commit-policy.md) · [`security-sensitive-stop`](../../.agent-src/rules/security-sensitive-stop.md).
+- [`docs/safety.md`](../safety.md) — domain-safety output floors.
+- [`agents/roadmaps/step-15-product-refinement.md`](../../agents/roadmaps/step-15-product-refinement.md) — Phase 1 item 2a (this doc) and Phase 2 item 9 (Universal Safety Model ADR).

package/docs/archive/CHANGELOG-pre-2.16.0.md

@@ -0,0 +1,48 @@
+# Changelog Archive — pre-2.16.0
+
+> Frozen snapshot of `event4u/agent-config` changelog entries from
+> `2.15.0`, split out of the main
+> [`CHANGELOG.md`](../../CHANGELOG.md) on 2026-05-16 once the active
+> era's body crossed the 200-line drift cap enforced by
+> `tests/test_changelog_eras.py`.
+>
+> **Read-only.** New entries land in `CHANGELOG.md` § "Era: 2.16.x".
+> Entries here are not amended — git tag `2.15.0` remains the
+> canonical source for what shipped.
+>
+> Entry shape follows the conventions documented in
+> [`docs/contracts/CHANGELOG-conventions.md`](../contracts/CHANGELOG-conventions.md).
+> Earlier eras live in
+> [`CHANGELOG-pre-2.15.0.md`](CHANGELOG-pre-2.15.0.md),
+> [`CHANGELOG-pre-2.11.0.md`](CHANGELOG-pre-2.11.0.md),
+> [`CHANGELOG-pre-2.7.0.md`](CHANGELOG-pre-2.7.0.md), and
+> [`CHANGELOG-pre-2.2.0.md`](CHANGELOG-pre-2.2.0.md).
+
+## [2.15.0](https://github.com/event4u-app/agent-config/compare/2.14.0...2.15.0) (2026-05-15)
+
+### Features
+
+* **agent-user:** add /agents user command cluster (init, show, review, accept, update) ([15d53d8](https://github.com/event4u-app/agent-config/commit/15d53d8d9a2365b044831cd42127e247a70d7e20))
+* **agent-user:** add v1 schema contract for .agent-user.md persona file ([64f4eab](https://github.com/event4u-app/agent-config/commit/64f4eab62ccf6a2606fbca0c56d398372c05a7a0))
+
+### Bug Fixes
+
+* **agent-user:** inline council-reference summary per no-roadmap-references ([ee4d3ce](https://github.com/event4u-app/agent-config/commit/ee4d3cedf9f4429450d21ca5badc2ae5c2ecaaed))
+* **agent-user:** drop roadmap references per no-roadmap-references rule ([c8ade8d](https://github.com/event4u-app/agent-config/commit/c8ade8d7c5b495e0e4295aa0cb801e59076ee0b0))
+* **agent-user:** adjust keep-beta-until to fit 90-day window ([801b365](https://github.com/event4u-app/agent-config/commit/801b365117a2d1efb4505e504bdd730e4cbbc217))
+
+### Documentation
+
+* **persona:** README section + agent-settings legacy-fallback note ([4da7629](https://github.com/event4u-app/agent-config/commit/4da7629f1f0b5a35a64d0a861040ad8639a66ebe))
+* **roadmap:** mark step-3-agent-user-persona phases as in-progress ([f29d3bc](https://github.com/event4u-app/agent-config/commit/f29d3bce2380c0ea9c67e6094540b88d920ed9ff))
+
+### Chores
+
+* **roadmap:** close out + archive step-3-agent-user-persona ([09c0229](https://github.com/event4u-app/agent-config/commit/09c0229efd67af9cad7b2ca8202f4caa351d028d))
+* **ownership:** regenerate file-ownership-matrix for /agents user ([128890d](https://github.com/event4u-app/agent-config/commit/128890d880584704b4842a398555dd979ae54462))
+* **docs:** bump command count from 109 to 115 ([f8c61b1](https://github.com/event4u-app/agent-config/commit/f8c61b1d0ec48034e0d66e8d32534056ca4aa1f0))
+* **template:** bump agent_config_version pin to 2.14.0 ([fcb885f](https://github.com/event4u-app/agent-config/commit/fcb885fd19bdbca46ef91ec4d5e723cc6c186c6d))
+* **index:** regenerate agents/index.md + docs/catalog.md for /agents user ([56b281d](https://github.com/event4u-app/agent-config/commit/56b281d69960d3e57adbd24b9ec6fd24fc1a5aff))
+* **agent-user:** regenerate compressed sources + claude tool stubs ([f79b6d1](https://github.com/event4u-app/agent-config/commit/f79b6d1cfcf1caccde4a723ad779c65d9ed87198))
+
+Tests: 4352 (+12 since 2.14.0)

package/docs/contracts/adr-layout.md

@@ -0,0 +1,108 @@
+---
+stability: stable
+---
+
+# ADR Layout — Per-area Directories
+
+> Status: accepted · 2026-05-16 · Roadmap: `step-11-ruflo-parity` Phase 4
+
+## Scope
+
+Two ADR surfaces coexist in this repo. **Both are canonical** — neither supersedes the other.
+
+| Surface | Path | Use for |
+|---|---|---|
+| **Flat (legacy)** | `docs/decisions/ADR-NNN-<slug>.md` | Cross-cutting governance decisions: kernel composition, rule taxonomy, package-wide architecture. Numbering is global, sequential, gap-free. |
+| **Per-area** | `docs/adrs/<area>/NNNN-<slug>.md` | Sub-area decisions whose blast radius is one plugin / one subsystem. Numbering is per-area, starts at `0001`, padded to 4 digits. |
+
+Choice rule — does the decision constrain code **inside one area folder** (one runtime module, one contract group, one CLI surface)? → per-area. Does it constrain **the package's contract with consumers**? → flat. In doubt → per-area (cheaper to surface, easier to relocate).
+
+## Per-area layout
+
+```
+docs/adrs/
+  <area>/
+    README.md          # one-paragraph area scope + table of all ADRs in this area
+    0001-<slug>.md     # first ADR, retrospective or prospective
+    0002-<slug>.md
+    ...
+```
+
+`<area>` is a kebab-case stem matching one of:
+
+- An entry in the canonical area inventory (see [`scripts/audit_adr_coverage.py`](../../scripts/audit_adr_coverage.py) `AREAS`).
+- A new area added to that inventory in the same PR.
+
+Reserved areas (bootstrap pass — step-11 Phase 4 Step 3):
+
+| Area | Scope | Owner contract |
+|---|---|---|
+| `cost` | Budget ladder, hard-stop hook, cost reporting | [`cost-enforcement.md`](cost-enforcement.md) |
+| `caveman` | Caveman-speak compression, decompression, reversibility | [`compression-default-kill-criterion.md`](compression-default-kill-criterion.md) |
+| `schema` | Frontmatter schemas, v2 rigor, lint behaviour | [`schema-versioning.md`](schema-versioning.md) (when published) |
+| `router` | `router.json` shape, tier semantics, dispatch precedence | [`rule-router.md`](rule-router.md) |
+| `smoke` | Per-tier smoke contracts, baseline locks | [`smoke-contracts.md`](smoke-contracts.md) |
+| `memory` | Memory MCP, propose / promote / poison flow | [`agent-memory-contract.md`](agent-memory-contract.md) |
+
+## Frontmatter
+
+Identical across both surfaces:
+
+```yaml
+---
+adr: NNN              # zero-padded; per-area uses 4-digit (0001), flat uses 3-digit (010)
+area: <area> | flat   # 'flat' for docs/decisions/, otherwise the area slug
+status: proposed | accepted | superseded | deprecated
+date: YYYY-MM-DD
+decision: <slug>
+supersedes: — | ADR-<area>-NNNN | ADR-MMM
+superseded_by: — | ADR-<area>-NNNN | ADR-MMM
+phase: <roadmap-stem> · <phase-id>     # optional but recommended
+type: retrospective | prospective
+---
+```
+
+Supersession links cross surfaces: a per-area ADR may supersede a flat ADR and vice versa. The numeric prefix in `supersedes:` makes the target unambiguous (`ADR-007` = flat, `ADR-cost-0001` = per-area).
+
+## Per-area README contract
+
+Every `<area>/` directory carries a `README.md` with:
+
+1. One-paragraph area scope (≤ 4 sentences).
+2. Single contract pointer — the `docs/contracts/<X>.md` this area implements (or "no published contract" if pre-Phase 5).
+3. Numbered table of ADRs in the area: `| # | Title | Status | Date | Supersedes |`. Generated by `scripts/audit_adr_coverage.py --regen-area-readme <area>`.
+
+## Coverage gate
+
+`scripts/audit_adr_coverage.py --check` (wired to `task lint-adr-coverage`):
+
+- Warns when a `docs/contracts/<X>.md` exists without a matching `docs/adrs/<X>/0001-*.md`.
+- Hard-fails on number gaps within an area (e.g. `0001`, `0003` without `0002`).
+- Hard-fails on missing `README.md` in any non-empty area directory.
+- Warns on dangling `supersedes:` or `superseded_by:` references.
+
+Default mode is **warn** at the consumer surface; **fail** under `task ci`. Rationale: a new contract dropped without an ADR is a documentation gap, not a bug. CI enforces it for this package; consumer projects opt in by adding the task to their own pipeline.
+
+## Numbering & gaps
+
+- Per-area: 4-digit, gap-free, starts at `0001`. Re-use of numbers is a hard failure in the index regenerator.
+- Flat: 3-digit, gap-free, starts at `001`. Existing ADRs in `docs/decisions/` set the precedent.
+- A deleted ADR is **never** removed from history — supersede it. The lint surfaces broken supersession chains.
+
+## Relationship to `adr-create` skill
+
+[`adr-create`](../../.agent-src.uncompressed/skills/adr-create/SKILL.md) accepts an optional `<area>` argument (added in step-11 Phase 4 Step 4):
+
+- No `<area>` → flat surface, `docs/decisions/`.
+- `<area>` matches inventory → per-area surface, `docs/adrs/<area>/`.
+- `<area>` does **not** match inventory → skill refuses with a hint to update the inventory first.
+
+The skill's template, numbering logic, and validation hooks are identical for both surfaces; only the target directory and number padding differ.
+
+## References
+
+- [`docs/adrs/cost/0001-hard-stop-hook.md`](../adrs/cost/0001-hard-stop-hook.md) — first per-area ADR (bootstrap).
+- [`docs/decisions/INDEX.md`](../decisions/INDEX.md) — flat surface index.
+- [`scripts/audit_adr_coverage.py`](../../scripts/audit_adr_coverage.py) — coverage gate.
+- [`scripts/adr/regenerate_index.py`](../../scripts/adr/regenerate_index.py) — index regenerator (works on both surfaces; pass `--dir`).
+- `step-11-ruflo-parity` Phase 4 — origin.

package/docs/contracts/benchmark-corpus-spec.md

@@ -0,0 +1,97 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# Benchmark Corpus Spec — step-4 Phase 1
+
+Parser-visible contract for the golden corpus consumed by
+[`scripts/bench_runner.py`](../../scripts/bench_runner.py) and the
+upcoming `scripts/lint_bench_corpus.py`. Defines composition, schema,
+and validation invariants.
+
+## Path decision
+
+Roadmap `step-4-measurement-and-benchmark.md`
+Phase 1 Step 2 names `bench/corpus.yaml`. The existing benchmark
+infrastructure (runner + non-dev corpus + `task bench`) lives under
+`tests/eval/` and `scripts/bench_runner.py` hardcodes that directory.
+**Canonical location:** `tests/eval/corpus-<id>.yaml`. The `bench/`
+directory is reserved for **reports + pricing** (Phase 2 deliverables).
+Migration to `bench/corpus.yaml` is a no-op rename if downstream Phase
+2 work proves the consolidation is worth the diff cost.
+
+## Composition (25 prompts)
+
+| Bucket | Count | Purpose |
+|---|---|---|
+| **Routing-canonical** | 10 | One prompt per major skill cluster — exact-match scoring |
+| **Ambiguous** | 8 | Multiple plausible skills — set-intersection ≥ 0.7 scoring |
+| **Destructive / security carve-out** | 5 | Triggers a safety floor — selection must surface the floor skill |
+| **Long-context** | 2 | ≥ 4 k input tokens — exercises retrieval under context pressure |
+
+The 10 routing-canonical prompts MUST cover the kernel + tier-1 skill
+clusters used by the dev profile (`developer.yml`). The 8 ambiguous
+prompts MUST each declare ≥ 2 acceptable skills in `expected_skills`.
+The 5 destructive / security prompts MUST declare an
+`expected_carve_outs` value (e.g. `security-sensitive-stop`,
+`non-destructive-by-default`).
+
+## Schema
+
+```yaml
+version: 1                              # corpus format version (int)
+corpus_id: <id>                         # short kebab-case identifier
+selection_accuracy_target: 0.60         # 0.0–1.0; runner exits non-zero below
+prompts:
+  - id: <bucket>-<NN>                   # e.g. canonical-01, ambiguous-03
+    category: <bucket>                  # canonical | ambiguous | destructive | long-context
+    user_type_candidates: [<slug>, ...] # optional; informational
+    language: en                        # en | de — per language-and-tone
+    prompt: "<text>"                    # the agent-facing prompt
+    expected_skills: [<slug>, ...]      # ≥ 1 entry; non-empty
+    expected_carve_outs: [<slug>, ...]  # required when category == destructive
+    rubric:                             # optional structural assertion
+      must_include: ["<phrase>", ...]   # all phrases must appear in output
+      must_not_include: ["<phrase>", ...]
+      length_words: { min: 0, max: 0 }
+    quality_assertion: "<regex>"        # optional regex over agent output
+```
+
+### Invariants (lint-bench gate)
+
+| Drift | `reason` | Example |
+|---|---|---|
+| Missing top-level `version` / `corpus_id` / `prompts` | `missing_top_level` | — |
+| `version` not in `{1}` | `unsupported_version` | `version: 2` |
+| `selection_accuracy_target` outside `[0.0, 1.0]` | `target_out_of_range` | `1.5` |
+| Duplicate `id` across prompts | `duplicate_id` | two `canonical-01` |
+| `id` does not match `^[a-z][a-z0-9-]*-\d{2}$` | `bad_id_format` | `Canonical_1` |
+| `category` not in `{canonical, ambiguous, destructive, long-context}` | `bad_category` | `category: misc` |
+| `language` not in `{en, de}` | `bad_language` | `language: fr` |
+| `expected_skills` empty / missing | `empty_expected` | `expected_skills: []` |
+| `expected_skills` references an unknown skill slug | `unknown_skill` | `expected_skills: [imaginary]` |
+| `category == destructive` without `expected_carve_outs` | `missing_carve_out` | — |
+| Prompt text empty / whitespace-only | `empty_prompt` | — |
+
+The linter MUST run with `--quiet` honour per the script-output
+convention and emit one violation per line in non-quiet mode.
+
+## Composition gates (25-prompt-complete state)
+
+Once `corpus-dev.yaml` reaches the 25-prompt target, the linter
+additionally enforces the per-bucket counts above. Until then, the
+linter only enforces per-prompt invariants — partial corpora are
+valid during Phase 1 build-out.
+
+The composition gate is opt-in via `--require-full` to keep the
+reduced 10-prompt suite (Phase 1 Step 4) usable during development
+without tripping CI.
+
+## Cross-references
+
+- Runner — [`scripts/bench_runner.py`](../../scripts/bench_runner.py)
+- Linter — `scripts/lint_bench_corpus.py` (Phase 1 Step 3)
+- Existing non-dev corpus — [`tests/eval/corpus-non-dev.yaml`](../../tests/eval/corpus-non-dev.yaml)
+- Language gate — [`language-and-tone`](../../.agent-src.uncompressed/rules/language-and-tone.md)
+- Report schema — `docs/contracts/benchmark-report-schema.md` (Phase 2 Step 4)

package/docs/contracts/benchmark-report-schema.md

@@ -0,0 +1,111 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# Benchmark Report Schema — step-4 Phase 2
+
+Parser-visible contract for the JSON + Markdown reports emitted by
+[`scripts/bench_run.py`](../../scripts/bench_run.py). Every `task bench`
+run writes one `bench/reports/<ts>-<corpus_id>.json` + matching `.md`.
+
+## File layout
+
+```
+bench/
+├── pricing.yaml                       # per-1M model rates + sourced_on dates
+└── reports/
+    ├── 2026-05-16T10-30-00Z-dev.json  # machine-readable
+    ├── 2026-05-16T10-30-00Z-dev.md    # human-readable
+    └── ...
+```
+
+Filename format: `<UTC ISO-8601 with `:` → `-`>-<corpus_id>.{json,md}`.
+Sortable lexicographically.
+
+## JSON schema (v1)
+
+```yaml
+schema_version: 1
+generated_at: <ISO-8601 UTC>
+corpus:
+  id: <corpus_id>
+  path: tests/eval/corpus-<id>.yaml
+  prompt_count: <int>
+runner:
+  bench_run_version: <semver>
+  baseline_collector: scripts/bench_runner.py     # selection-accuracy floor
+  baseline_collector_sha: <git-sha-or-mtime>
+selection:
+  top_k: 3
+  prompts_hit: <int>
+  prompts_total: <int>
+  selection_accuracy: <float 0.0-1.0>             # hits / total
+  target: <float>                                 # from corpus
+  passed: <bool>                                  # accuracy >= target
+  per_prompt:                                     # one entry per corpus prompt
+    - id: canonical-01
+      expected_skills: [...]
+      top_k_ranked: [...]
+      hit: <bool>
+cost:
+  source: agents/cost-tracking/sessions.jsonl     # or "unavailable"
+  sessions_scanned: <int>
+  totals:
+    input_tokens: <int>
+    output_tokens: <int>
+    cache_read_input_tokens: <int>
+    cache_creation_input_tokens: <int>
+    total_cost_usd: <float>
+  per_tier:                                        # haiku / sonnet / opus / unknown
+    sonnet: { messages: <int>, cost_usd: <float> }
+    ...
+  pricing_sourced_on: <ISO date from bench/pricing.yaml>
+quality:
+  source: <path-or-"not_collected">
+  prompts_with_assertion: <int>
+  prompts_passing: <int>
+  quality_score: <float 0.0-1.0>                  # passing / total OR 0.0 if not_collected
+  per_prompt:
+    - id: canonical-01
+      assertion: <regex-string>
+      assertion_kind: rubric.must_include | quality_assertion
+      passed: <bool | "not_collected">
+verdict:
+  selection: pass | fail
+  quality: pass | fail | not_collected
+  overall: pass | fail | partial                   # partial = quality not_collected
+```
+
+## Markdown shape
+
+Headers in order:
+
+1. `# Benchmark Report — <corpus_id> · <generated_at>`
+2. `## Headline` — three-line summary (selection · cost · quality).
+3. `## Selection accuracy` — table per prompt with hit/miss + expected/got.
+4. `## Cost capture` — per-tier table + total; "unavailable" block if no
+   session jsonl was found.
+5. `## Quality probe` — per-prompt assertion pass/fail; `not_collected`
+   block when no agent-output path was passed.
+6. `## Notes` — pointer to `pricing.yaml`, `corpus path`, and the
+   versioned filename for citation.
+
+## Invariants
+
+- **No silent drops.** Missing cost source → emit `source: unavailable`
+  and `total_cost_usd: 0.0` with a marker; never omit the section.
+- **Quality stub honesty.** When agent outputs are not provided, set
+  `quality.source: not_collected` and `verdict.overall: partial`. Score
+  stays `0.0`; never inflate by assuming pass.
+- **Pricing dated.** Every cost row reads `sourced_on` from
+  `bench/pricing.yaml`. Stale price (> 90 days) → warning line in the
+  Markdown footer.
+
+## Cross-references
+
+- Runner — [`scripts/bench_run.py`](../../scripts/bench_run.py)
+- Baseline collector — [`scripts/bench_runner.py`](../../scripts/bench_runner.py)
+- Corpus contract — [`benchmark-corpus-spec.md`](benchmark-corpus-spec.md)
+- Pricing source — [`bench/pricing.yaml`](../../bench/pricing.yaml)
+- Cost session reader (live sessions) — [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs)

package/docs/contracts/command-clusters.md

@@ -297,4 +297,5 @@ A command that fails either floor drops to **Tier-1** at the next minor release;
 - [`docs/migrations/commands-1.15.0.md`](../migrations/commands-1.15.0.md) — user-facing migration notes.
 - [`docs/contracts/STABILITY.md`](STABILITY.md) — `beta` level rules apply.
 - [`docs/contracts/command-surface-tiers.md`](command-surface-tiers.md) — what each tier means and what `--help` surfaces.
+- [`docs/contracts/command-taxonomy.md`](command-taxonomy.md) — profile axis (discoverability) layered on top of this verb axis (invocation).
 - [`.agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md`](../../.agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md) — sibling telemetry surface; same privacy floor and four-layer enforcement model.