@event4u/agent-config 2.18.0 → 2.20.0

package/docs/contracts/adr-user-types-axis.md

@@ -0,0 +1,127 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# ADR — Runtime user-types axis (review lens, parallel to personas)
+
+> **Status:** Decided · 2026-05-15
+> **Source:** user-authored brief (no council session — direct user spec)
+> **Sibling axis (distinct layer):** [`adr-install-user-type-axis`](adr-install-user-type-axis.md) — install-time `personal.user_type` filter; same vocabulary, different layer
+
+## Context
+
+The persona axis (`personas/`) was overloaded with two semantics:
+
+1. **Methodology lenses** — `qa`, `senior-engineer`, `critical-challenger`,
+   `developer`, `product-owner`. These voices answer: *how* we review.
+2. **End-user simulations** — proposals like `galabau-field-crew`,
+   `truck-driver`, `metalworking-shop`. These voices answer: *who*
+   experiences the software.
+
+Mixing the two collapses the taxonomy. A `qa` reviewer applies QA
+methodology regardless of which end-user the software serves. A
+`galabau-field-crew` is not a review methodology — it is the end-user
+viewpoint a methodology reviewer should adopt while reviewing.
+
+The composition the system needs is orthogonal:
+
+```
+/refine-ticket --personas=qa --user-type=truck-driver PROJ-123
+```
+
+QA methodology applied through a truck-driver end-user lens. Two
+axes, one orthogonal product.
+
+## Decision
+
+Split into a parallel axis. Add `.agent-src.uncompressed/user-types/`
+as a first-class directory mirroring the persona pipeline:
+
+- Source dir: `.agent-src.uncompressed/user-types/`
+- Schema doc: [`user-type-schema`](user-type-schema.md) — 7-section spine, ≤ 120 lines
+- JSON schema: [`scripts/schemas/user-type.schema.json`](../../scripts/schemas/user-type.schema.json)
+- Linter: `scripts/skill_linter.py § lint_usertype`
+- CLI surface: `/refine-ticket --user-type=<id>` (single id in v1)
+- Composition: `--user-type=` and `--personas=` compose orthogonally
+
+Persona surface is **byte-identical** after this work. No persona
+moves, no schema change to `persona-schema.md` or `persona.schema.json`,
+no behaviour change to `--personas=`. The three seed user-types
+(`galabau-field-crew`, `metalworking-shop`, `truck-driver`) are born
+as user-types — existing personas stay as personas.
+
+## Consequences
+
+**Additive surface:**
+
+- One new CLI flag (`--user-type=`)
+- One new schema doc + JSON schema
+- One new linter hook (`lint_usertype` + classifier branch)
+- One new directory (`user-types/`) projected the same way `personas/`
+  is
+- Three seed files at merge time; consumer projects add their own
+  domain-specific user-types under `.agent-src/user-types/`
+
+**Locked v1 boundaries:**
+
+- CLI-only. Skills do NOT declare a default `user-types:` frontmatter
+  key in v1. Migration path to v2: if usage patterns show > 3 skills
+  citing the same user-type default, add the key and the audit script
+  to mirror `recommended_for_user_types` discipline (smaller surface
+  now, additive later).
+- Single user-type per invocation (`--user-type=<id>`, not a list).
+  Multi-user-type composition deferred to v2 with a one-line note —
+  it requires synthesis logic that does not exist yet and would block
+  v1 on a non-load-bearing nice-to-have.
+- **Review lens only.** User-types never provide trade execution
+  instructions. Guardrails encoded in every file's `Anti-Patterns`
+  section per [`user-type-schema § 5`](user-type-schema.md#-5--guardrails-encoded-in-every-anti-patterns-block).
+- **Anti-Generic Quality Bar.** Every user-type encodes ≥ 5 concrete,
+  domain-specific review points and ≥ 3 Unique Questions no other
+  persona asks verbatim. Generic prose is rejected at lint or review
+  time.
+
+## Alternatives considered
+
+**Alt-1 — Extend persona schema with a `subtype: end-user` discriminator.**
+Rejected. Same physical file, two semantics, two enforcement paths
+inside one linter hook. Scales worse: every persona-consuming surface
+(`--personas=`, `lint_persona`, `audit_persona_coverage.py`) would
+need a branch on `subtype` to know whether the artefact is a
+methodology lens or an end-user lens. The clean axis split is a
+single fork-point at the classifier; the subtype fork-point recurs at
+every consumption site.
+
+**Alt-2 — Reuse the existing `user-types/` (install-time) directory
+for runtime lenses.** Rejected. The install-time axis stores YAML
+configs filtering *which skills load*; the runtime axis stores
+Markdown lenses filtering *whose viewpoint a review adopts*. Same
+vocabulary, completely different content shape (YAML key-value vs.
+Markdown prose + frontmatter), completely different consumer
+(`scripts/install.sh` vs. `refine-ticket`). Co-locating them would
+force a single `kind:` discriminator on a directory whose two halves
+do not share a schema. The separation is in different physical paths
+(`user-types/` root vs. `.agent-src.uncompressed/user-types/`) and
+the vocabulary overlap is deliberate per [`adr-install-user-type-axis`](adr-install-user-type-axis.md).
+
+**Alt-3 — Defer the axis until end-user lenses prove themselves in
+the field.** Rejected. The methodology / end-user overload is already
+producing taxonomy drift in the persona README (review-lens vs
+end-user examples mixing). Splitting now is cheaper than splitting
+after three more end-user "personas" land.
+
+## Migration
+
+No migration. v1 ships with three seed user-types born under the new
+axis. Existing personas (`qa`, `developer`, `senior-engineer`,
+`product-owner`, `stakeholder`, `critical-challenger`, `ai-agent`,
+plus specialists) stay put. The `personas/README.md` gains one
+cross-link sentence pointing readers at the parallel axis when their
+intent is end-user simulation rather than methodology review.
+
+## See also
+
+- [`user-type-schema`](user-type-schema.md) — locked shape, 7-section spine, size budget, quality bar
+- [`persona-schema`](persona-schema.md) — sister axis (untouched by this ADR)
+- [`adr-install-user-type-axis`](adr-install-user-type-axis.md) — install-time `personal.user_type` filter (distinct layer)

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.