@event4u/agent-config 2.19.0 → 2.20.1

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.

package/docs/contracts/command-taxonomy.md

@@ -0,0 +1,137 @@
+---
+stability: beta
+keep-beta-until: 2026-08-12
+---
+
+# Command taxonomy
+
+> **Status:** beta — first draft 2026-05-16 (Phase 2 Item 6 of
+> `step-15-product-refinement`).
+
+The taxonomy answers **"how is the command surface organized so each
+profile finds their three first commands in under 30 seconds?"** It is
+a **catalog-organization contract**, not an invocation-rename. Existing
+slash invocations (`/work`, `/fix ci`, `/research deep`) are preserved
+by the locked verb-cluster contract at
+[`command-clusters`](command-clusters.md). This file adds a **profile
+axis** on top of the verb axis without breaking either.
+
+## The two axes
+
+| Axis | Owner | Surface |
+|---|---|---|
+| **Verb-cluster** (existing) | [`command-clusters`](command-clusters.md) | Defines the invocation tree (`/fix ci` dispatches to the `ci` sub-command of the `fix` cluster). Linter-enforced. **Source of truth for invocation.** |
+| **Profile** (this contract) | [`profile-system`](profile-system.md) | Defines which verb-clusters and sub-commands are surfaced first for each profile (developer · content_creator · founder · agency · finance · ops). **Source of truth for discoverability.** |
+
+A command can be discoverable under multiple profiles. `/work` is
+universal — it appears in `commands_hint` for every profile. `/dcf-modeling`
+is finance-only. Discoverability is many-to-many; invocation stays
+single-source.
+
+## Membership rules
+
+### Profile membership
+
+A command appears in a profile's `commands_hint` (in
+`.agent-src.uncompressed/profiles/<id>.yml`) iff **all** hold:
+
+1. **First-week reach.** A user of that profile will reach for this
+   command within their first five sessions without being told.
+2. **Profile-coherent.** The command's domain matches the profile's
+   primary work surface (engineering for `developer`, content for
+   `content_creator`, etc.).
+3. **Verb-cluster owned.** The command exists in `command-clusters` —
+   no profile may declare a command that has not gone through the
+   verb-cluster linter.
+4. **Cap of five.** A profile's `commands_hint` is capped at five
+   entries. The cap is what makes "three first commands" possible.
+
+### Top-10 most-used (for alias / deprecation policy)
+
+The top-10 list is the **union of all six profiles' `commands_hint`
+lists, ranked by per-profile membership count**. As of 2026-05-16
+that union is, in rank order:
+
+1. `work` (6/6 profiles)
+2. `implement-ticket` (2/6 — developer, agency)
+3. `feature` (2/6 — founder, agency)
+4. `council` (2/6 — founder, finance)
+5. `challenge-me` (2/6 — founder, finance)
+6. `review-changes` (2/6 — developer, ops)
+7. `fix` (2/6 — developer, ops)
+8. `refine-ticket` (1/6 — agency)
+9. `commit` (1/6 — developer)
+10. `roadmap` (1/6 — agency)
+
+The top-10 is regenerated automatically from the profile YAMLs by
+`scripts/regen_top10.py` (Phase 2 deliverable — not yet shipped). Until
+the regen script lands, the list above is the locked snapshot.
+
+## Backward-compat policy
+
+The top-10 commands carry a **two-release backward-compat guarantee**:
+
+- A rename of any top-10 command (whether by verb-cluster restructure
+  or profile-axis reorganization) ships with an alias for **at least
+  two minor releases**.
+- The alias is recorded in the verb-cluster's `Replaces` column in
+  [`command-clusters`](command-clusters.md) and re-emits a one-line
+  deprecation notice to stderr on every invocation.
+- Removing the alias requires the `bundled-always-rules-acknowledged`
+  PR label and an entry in the CHANGELOG `Removed` section naming the
+  end-of-deprecation release.
+
+Commands outside the top-10 follow the existing verb-cluster
+deprecation rules (one release as a shim, then disappear).
+
+## Discoverability surfaces
+
+Three surfaces consume this contract:
+
+| Surface | Path | What it shows |
+|---|---|---|
+| **README** | `README.md` § "Six entry paths" | Per-profile `commands_hint` (max 5) rendered as the first-commands list per profile block |
+| **Catalog** | `docs/catalog.md` | All commands grouped by verb-cluster (primary axis), with a per-command `profiles:` line listing which profiles surface it |
+| **Wizard** | `.agent-src.uncompressed/commands/onboard.md` | After role selection, prints the five-command starter list from the selected profile's `commands_hint` |
+
+The README and wizard surfaces are already wired. The catalog `profiles:`
+line is a Phase 2 deliverable.
+
+## What this contract does **not** do
+
+- **Does not** rename any command. Invocation stays flat (`/work`, not
+  `/dev/work`). The `/dev/...` / `/ops/...` strawman in the Item 6
+  roadmap entry is **rejected** — adding a profile prefix to invocation
+  would dual-namespace the surface, conflict with verb-cluster cluster
+  heads, and require a 124-command migration with no measurable
+  discoverability gain over the README + wizard surfaces above.
+- **Does not** modify the verb-cluster contract. `command-clusters`
+  remains the locked source of truth for invocation. This contract is
+  additive.
+- **Does not** ship telemetry. The top-10 is derived from declared
+  profile membership, not observed usage. A usage-based top-10
+  recomputation is deferred to Item 10 (Cost Governance Dashboard),
+  which already collects per-command call counts.
+
+## Open questions (post-beta)
+
+1. **Profile evolution.** When a seventh profile lands (e.g.
+   `researcher`), what is the membership review process for the
+   top-10? Proposal: any new profile triggers a `regen_top10.py` run
+   and a CHANGELOG entry; no manual review unless the top-10 order
+   changes.
+2. **Profile-prefix invocation.** If the no-rename verdict is
+   revisited (e.g. user research shows discoverability still fails
+   even with the README + wizard surfaces), a separate ADR records
+   the decision; this contract does not pre-authorize it.
+3. **Catalog generator.** `docs/catalog.md` is currently
+   handwritten. The `profiles:` line proposed in the discoverability
+   table requires `scripts/regen_catalog.py` to consume profile YAMLs
+   — deferred to its own roadmap step.
+
+## See also
+
+- [`command-clusters`](command-clusters.md) — verb-axis (invocation)
+- [`profile-system`](profile-system.md) — profile-axis (discoverability)
+- [`command-surface-tiers`](command-surface-tiers.md) — tier-axis (`./agent-config --help` visibility)
+- `step-15-product-refinement` § Phase 2 Item 6

package/docs/contracts/compression-default-kill-criterion.md

@@ -0,0 +1,69 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# Compression default — kill-criterion
+
+> **Status:** parked, criterion-deferred · **Owner:** `step-4-measurement-and-benchmark.md`
+> closeout phase · **Source:** [`council-synthesis.md` § 7](../../agents/audit-2026-05-14-north-star/council-synthesis.md)
+
+## Rule
+
+```
+DEFAULT STAYS OFF UNTIL `task bench` PRODUCES A NUMBER.
+DECISION OWNED BY step-4 CLOSEOUT, NOT BY THIS DOC OR BY step-99.
+```
+
+1. **Current state.** `caveman.speak_scope` defaults `off`. Carve-outs
+   (security · destructive · multi-step · code blocks · paths · numbered
+   options · Iron-Law markers) are documented in
+   [`caveman-speak`](../../.agent-src.uncompressed/rules/caveman-speak.md)
+   but the feature is non-promoted: no skill recommends turning it on,
+   no preset enables it, no profile depends on it.
+2. **Baseline window.** 60 days from the first green run of
+   `task bench` against the locked 25-prompt corpus
+   (`step-4-measurement-and-benchmark.md`
+   Phase 2). The corpus, the model, and the cost-tracker are frozen
+   for the window; mid-window changes restart the clock.
+3. **Decision points.** After the window closes, `step-4` closeout
+   reads `docs/parity/bench.json` and applies exactly one of:
+
+   | Measured tokens saved | Quality regression on corpus | Verdict |
+   |---|---|---|
+   | < 30 % | any | **Deprecate** — remove `caveman-speak` rule, archive `caveman-compress` script, retire `caveman.*` settings keys with a one-release deprecation window |
+   | ≥ 30 % | < 5 % | **Flip default on** — `caveman.speak_scope` defaults to a non-`off` value, carve-outs stay, statusline surfaces lifetime tokens saved |
+   | ≥ 30 % | ≥ 5 % | **Hold** — repeat the window once with tuned intensity ladder; second hold → deprecate |
+
+   "Quality regression" = host-side rubric on the corpus per
+   `step-4-measurement-and-benchmark.md` Phase 3. Numbers checked into
+   `docs/parity/bench.json` as the decision artefact.
+4. **No interim flip.** The default does not move on anecdote,
+   gut feeling, or a single benchmark snapshot. The 60-day window and
+   the table above are the only path to a default change.
+
+## Why this is parked, not decided
+
+The council split (Opus = remove now, o1 = measure-then-decide) is
+real. Either branch is wrong-shaped without numbers. The kill-criterion
+gives the audit a deterministic resolution path and stops every
+downstream roadmap from re-litigating compression on every PR.
+
+## Cross-references
+
+- ``step-99-north-star-restructure.md` § Phase 4`
+  — parks this criterion, does not decide.
+- `step-4-measurement-and-benchmark.md`
+  — owns `task bench`, the corpus, and the closeout that applies the
+  table above.
+- `step-10-caveman-parity.md`
+  — implements the carve-outs and the statusline integration the
+  "flip default on" branch depends on; blocks the default flip until
+  acceptance is green.
+- [`caveman-speak`](../../.agent-src.uncompressed/rules/caveman-speak.md)
+  — runtime rule; reads `caveman.speak_scope` from settings.
+
+## Done
+
+This doc exists to keep the decision visible. It is **not** an action
+item. `step-4` closeout closes the loop.

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).