@event4u/agent-config 9.8.0 → 9.10.0

package/docs/contracts/adr-forecast-construction-shape.md

@@ -1,90 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# ADR — `forecast-construction-shape`: the O2 ↔ H10 interface
-
-> **Status:** Decided · 2026-05-13
-> **Builds on:** [`cross-wing-handoff.md`](cross-wing-handoff.md) § 5 W4 chain;
-> [`wing4-handoff.md`](../guidelines/wing4-handoff.md) § Chain 4;
-> [`gtm-handoff.md`](../guidelines/gtm-handoff.md) § Chain 2 (H10 side).
-
-## Decision
-
-`forecasting` (O2, Wing-4, finance-partner) and `forecast-accuracy`
-(H10, Wing-3, RevOps) compose through a **typed interface**, not a
-shared implementation. O2 owns the cognition of *how a forecast is
-constructed*; H10 owns the cognition of *which deals belong in
-commit*. The interface is the only contract that crosses the wing.
-
-Interface payload (the `forecast-band.json` artifact):
-
-| Field | Type | Meaning |
-|---|---|---|
-| `construction_shape` | enum `top-down` · `bottom-up` · `hybrid` | Which construction shape the forecast was built from. Top-down anchors against TAM × penetration × motion; bottom-up sums deal-level conviction; hybrid is the explicit two-call reconciliation. |
-| `commit_value` | money | Sum of commit-categorised deals × in-window close-rate, or top-down commit-band lower bound. |
-| `best_case_value` | money | Commit + best-case-tagged, or top-down best-case-band upper bound. |
-| `pipeline_value` | money | Population from which commit / best-case are drawn. Not a forecast category, included for ratio reasoning. |
-| `confidence_band` | `{plus_pct: float, minus_pct: float}` | Historical-deviation-derived band around commit. **MUST** be present; a forecast without a band has no honesty about its prior miss-rate. |
-| `retro_signature` | `{horizon: enum, last_two_actual_vs_predicted: [pct, pct]}` | The accuracy retro this band was calibrated against. Horizon = `quarterly` · `monthly` · `annual`. |
-| `segment_scope` | string list | Customer-segment slots the forecast covers (from spine). Empty list = blended; explicit list = per-segment. |
-| `fiscal_period` | string | Reporting cadence slot from `fiscal-period` spine: `monthly` · `quarterly` · `annual` · `multi-year-plan`. |
-| `construction_inputs` | object | Shape-specific inputs: top-down → `{tam, penetration_band, motion_band}`; bottom-up → `{commit_count, best_case_count, evidence_floor}`; hybrid → both. |
-
-## Why this was a real question
-
-Three options were on the table:
-
-1. **Shared implementation in one wing.** Forecasting lives entirely
-   in Wing-3 (RevOps) or Wing-4 (Finance). Rejected: forecasting is
-   constructed from finance fundamentals and consumed from deal-level
-   evidence — collapsing it into one wing forces the other to
-   re-derive cognition.
-2. **Free-form text handoff.** O2 emits prose; H10 reads prose.
-   Rejected: prose drifts every quarter, the linter cannot catch
-   contract breaks, and the retro loop loses the comparison shape.
-3. **Typed interface, owned by O2.** Accepted: O2 owns the shape so
-   that drift is a producer-side fix. H10 consumes against the
-   contract and never re-derives forecasting cognition.
-
-## Citation-evidence gating
-
-This ADR is the gating artefact. O2 cites the ADR in its frontmatter
-and procedure. H10 cites the ADR in its `Related Skills` carve-out
-and validates its `commit-list.md` against the `forecast-band.json`
-shape. `task lint-handoffs` (Phase 3.2) walks the cross-wing graph
-and rejects a contract break.
-
-## Parallel-development rule
-
-O2 ships an **interface-first stub** (this ADR + a stub procedure
-that emits the typed artifact from a single bottom-up case). The
-stub counts as ≥ 100 % of `O2-interface`. H10 starts after the
-interface lands, parallel to O2 implementation. O2 cannot break the
-contract without an ADR revision and a co-ordinated H10 update.
-
-## Counter-evidence the agent should listen for
-
-Three signals that this ADR is wrong and needs revisiting:
-
-1. **H10 re-derives forecasting cognition.** If `forecast-accuracy`
-   starts shipping top-down vs bottom-up reasoning, the interface
-   leaked and one of the two skills is mis-scoped. Re-cut the
-   boundary.
-2. **A third consumer reads `forecast-band.json`.** A new skill
-   composing the interface means the contract is load-bearing for
-   the broader spine and should graduate from beta to stable.
-3. **The confidence-band is consistently absent.** Forecasts that
-   ship without a band are using the interface as a shape but
-   skipping the calibration; the field should become required-on-
-   parse, not required-on-cognition.
-
-## See also
-
-- [`wing4-handoff.md`](../guidelines/wing4-handoff.md) § Chain 4 —
-  finance → GTM prose around this contract.
-- [`gtm-handoff.md`](../guidelines/gtm-handoff.md) § Chain 2 — H10
-  side prose; identical contract, opposite consumer.
-- [`cross-wing-handoff.md`](cross-wing-handoff.md) § 5 — wing-scoped
-  contract policy this ADR follows.

package/docs/contracts/adr-gtm-context-spine.md

@@ -1,116 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# ADR — GTM context-spine: Wing-3 slot extension
-
-> **Status:** Decided · 2026-05-13
-> **Roadmap origin:** `agents/roadmaps/` (Block G — G1, archived after merge)
-> **Builds on:** [`context-spine.md`](context-spine.md) — tri-slot
-> contract (`product`, `team`, `repo`) locked at 3 by council Q1
-> (2026-05-05 KEEP-3, unified-senior-roles iter 1).
-> **Defers to:** [`cross-wing-handoff.md`](cross-wing-handoff.md) — typed
-> handoff contract; orthogonal to slot membership.
-
-## Decision
-
-The context-spine adds **three Wing-3-specific slots** under
-`agents/context-spine/`: `channel-stage`, `funnel-stage`,
-`customer-segment`. The schema enum in
-[`scripts/schemas/skill.schema.json`](../../src/scripts/schemas/skill.schema.json)
-extends from `{product, team, repo}` to
-`{product, team, repo, channel-stage, funnel-stage, customer-segment}`.
-
-The KEEP-3 lock from council Q1 applies to **cross-wing slots** —
-slabs every senior wing might read. The Wing-3 slots are
-**wing-scoped**: they exist for the GTM cluster (Block H, 16 skills)
-and the GTM personas (Block I, 7 personas). Engineering, Foundation,
-and Money / Strategy / Ops wings do not opt into them.
-
-| Slot | Path | Typical content |
-|---|---|---|
-| `channel-stage` | `agents/context-spine/channel-stage.md` | Which channels the GTM motion uses (awareness · consideration · decision · retention · expansion), per-channel maturity, channel-cost band. Read by H1 (`positioning-strategy`), H2 (`messaging-architecture`), H3 (`gtm-launch`), H6 (`editorial-calendar`). |
-| `funnel-stage` | `agents/context-spine/funnel-stage.md` | Funnel topology (top / mid / bottom / activation / retention), per-stage definition, exit-criteria for each. Read by H8 (`pipeline-strategy`), R1 (`funnel-analysis`), R2 (`activation-design`), R3 (`onboarding-design`). |
-| `customer-segment` | `agents/context-spine/customer-segment.md` | ICP, persona-by-segment, ARR-band-by-segment. Read by H7 (`ICP`), H8 (`pipeline-strategy`), H9 (`MEDDIC`), R4 (`retention-loops`). |
-
-## Why this was a real question
-
-Three options were on the table:
-
-1. **Force-fit into existing slots.** Stuff GTM context into the
-   `product` slab. Rejected: `product` is owned by the discovery wing
-   and a Wing-3 reader gets fuzzy semantics (channel maturity is not
-   product scope), Council Q1 explicitly fences `product` against
-   sprawl.
-2. **Wing-3-only frontmatter key.** Add `gtm_spine: [...]` as a
-   parallel field. Rejected: duplicates the read-discipline
-   mechanism, the lint gate, and the skill-author cognitive load.
-   Two spines is the slot-sprawl failure mode at a different layer.
-3. **Extend the spine, scope the slots.** Accepted: same mechanism,
-   same lint gate, same opt-in discipline; slot names carry the wing
-   scope (`channel-stage`, `funnel-stage`, `customer-segment` are
-   visibly GTM-shaped).
-
-## Citation-evidence gating — prospective
-
-The existing § 5 policy requires ≥ 2 shipped skills citing the new
-slot **before** the slot is added. For Wing-3 the citation chain is
-**prospective**: the roadmap (G1 → H → I) ships citing skills in the
-same iteration, ordered so G1 lands first to unblock H authoring.
-
-The ADR is the gating artefact (not the citations). The Block-H
-authoring procedure MUST cite ≥ 1 of the three new slots per skill
-or carry a one-line ADR-opt-out comment in the skill body. The G2
-linter (council Q7 boundary tests) enforces channel-agnosticism,
-which is orthogonal — a skill can cite `channel-stage` for context
-without prescribing channel-specific tactics.
-
-This relaxation is **wing-bounded**: future wings adding their own
-slots must either accumulate ≥ 2 citations from already-shipped
-skills, **or** write a per-wing ADR that names the citing-skill
-chain in the same iteration (the pattern this ADR establishes).
-
-## Migration plan for the existing senior catalog
-
-- **No retrofitting required.** Existing senior skills
-  (`customer-research`, `funnel-analysis`, `po-discovery`,
-  `refine-ticket`, `rice-prioritization`, etc.) keep their current
-  `context_spine` declarations. They MAY add a Wing-3 slot if their
-  cognition genuinely reads it; they MUST NOT be retrofitted
-  mechanically.
-- **Opt-out for off-wing skills.** Engineering / Foundation / Ops
-  senior skills do not need to mention the Wing-3 slots in any way.
-  The schema accepts subsets — declaring only `[product, team]`
-  remains valid.
-- **Slot-file authoring is consumer-side.** The package ships the
-  contract; consumer projects fill `agents/context-spine/channel-stage.md`
-  etc. when adopting Wing-3 skills. Missing slot file is graceful
-  per § 4 of the contract.
-
-## Counter-evidence the agent should listen for
-
-Three signals that this decision is wrong and the ADR needs revisiting:
-
-1. **Off-wing skills start declaring Wing-3 slots.** If an
-   Engineering skill cites `channel-stage`, the slot is misnamed or
-   the wing boundary is leaking. Re-scope the slot or rename it.
-2. **Wing-3 skills consistently ignore the slot they declared.** If
-   Block H skills declare `funnel-stage` but never quote it in their
-   procedure, the slot is decorative and should be deleted.
-3. **A fourth Wing-3 slot is proposed within the same iteration.**
-   That is slot-sprawl on the same wing — Block G2 boundary tests
-   should reject the addition until a follow-up ADR documents why
-   three slots are insufficient.
-
-## See also
-
-- [`context-spine.md`](context-spine.md) § 2 (slot table — extended),
-  § 5 (slot-add policy — wing-bounded extension clause).
-- [`scripts/schemas/skill.schema.json`](../../src/scripts/schemas/skill.schema.json)
-  — `context_spine.items.enum` extended in this ADR.
-- `agents/roadmaps/` § Block G — the authorising roadmap (archived
-  after merge; this ADR is the durable record).
-- [`.agent-src.uncondensed/rules/skill-quality.md`](../../.agent-src.uncondensed/rules/skill-quality.md)
-  § Senior-Tier Required Structure — the four blocks every senior
-  skill ships independently of spine opt-in.

package/docs/contracts/adr-implement-ticket-runtime.md

@@ -1,121 +0,0 @@
----
-stability: stable
----
-
-# ADR — `/implement-ticket` runtime: Python
-
-> **Status:** Decided · Phase 0 spike closed · 2026-04-22
-> **Context:** [`implement-ticket-flow.md`](implement-ticket-flow.md)
-> **Supersedes:** the `Runtime: TBD` placeholder in `implement-ticket-flow.md`.
-
-## Decision
-
-The `/implement-ticket` orchestrator ships on **Python 3.10+** (stdlib + `pyyaml`).
-
-Bash is rejected as the runtime. It stays only where it already lives —
-the install driver, condensation helper, and test runner — not the
-delivery flow.
-
-## Why this was a real question
-
-The repo already ships a Bash install + condensation toolchain. A
-shell-native dispatcher would have reused the existing muscle memory and
-avoided adding Python as a delivery-runtime dependency. The spike
-existed to verify whether Bash could still carry the 8-step linear flow
-once real orchestration needs showed up (structured state, blocked/partial
-outcomes, metrics, tests). Result: not well.
-
-## Spike scope
-
-Both prototypes implement the same shape from
-`implement-ticket-flow.md`:
-
-- 8 linear steps (refine → memory → analyze → plan → implement → test →
-  verify → report)
-- `DeliveryState` as the only thing shared between steps
-- Three terminal outcomes: `success`, `blocked`, `partial`
-- Metrics JSON line per run (Q38 decision)
-- Identical fixtures: one clean ticket, one ambiguous ticket that must
-  block at `refine` with three numbered questions
-
-Sources: Phase-0 spike (`spike/implement-ticket/{bash,python}/`) — deleted after Phase 1 shipped; the evidence inlined below is the only surviving record.
-
-## Evidence (measured, not asserted)
-
-### Wall-clock mean (20 runs, 3 warmup, macOS ARM)
-
-| Scenario | Bash | Python | Winner |
-|---|---|---|---|
-| Clean, all 8 steps | 104 ms | 36 ms | **Python 2.9×** |
-| Blocked at step 1  |  60 ms | 35 ms | **Python 1.7×** |
-
-Harness was `spike/implement-ticket/bench.sh` (20 runs, 3 warmup, macOS ARM);
-raw numbers preserved in this ADR after the spike directory was deleted.
-
-Bash cost is dominated by per-step fork/exec (`yq`, `jq`, `perl`, step
-script). Every step added extends the Bash gap. Python keeps the whole
-dispatch in-process; step count is effectively free.
-
-### Test-writability
-
-| | pytest (Python) | shell asserts (Bash) |
-|---|---|---|
-| Lines to cover 3 scenarios | 59 | 72 |
-| Assert target | typed `state.outcomes`, `state.questions` | stdout string-contains |
-| Suite runtime | 0.01 s | ~2.5 s (15 subprocess launches) |
-| Test isolation | in-process `dispatch(state)` | fork per assertion |
-| IDE affordances | autocomplete, types, stack traces | grep only |
-
-### Error-propagation ergonomics
-
-- **Python:** outcomes flow through typed `StepResult`/`Outcome`
-  enums. One `dispatch()` return tuple covers success/blocked/partial.
-  Zero string parsing.
-- **Bash:** outcomes are encoded in exit codes (0/10/20), propagated
-  through `set +e` dances per step, mirrored into a JSON file with
-  `jq --arg` round-trips. Every step handler re-reads/rewrites the
-  state file. Brittle.
-
-### Source size
-
-Roughly equal (Bash 203 / Python 207 lines), but the Bash total is spread
-across 9 files with per-file shebang + `set -euo pipefail` boilerplate;
-Python is 3 files with shared types.
-
-## Tradeoffs we accept
-
-- **New hard dependency on Python 3.10+ and `pyyaml`.** Mitigated: Python 3
-  is already a build/test dependency of this repo (linters, condensation,
-  `update_counts.py`). `pyyaml` is already pinned in `pyproject.toml` /
-  `requirements-*.txt`. Zero new install surface for contributors.
-- **We lose the "just-shell" story.** The install script stays Bash. The
-  delivery runtime being Python is a deliberate split: install is
-  side-effecting system work, delivery is structured data transformation.
-- **Python per-invocation boot is ~35 ms.** Accepted — it's flat, not
-  proportional to step count, and well below the user-perception floor.
-
-## Non-goals of this decision
-
-- Does not bless Python for every future spike — each flow decides
-  on its own evidence.
-- Does not commit to a specific framework (click, typer, bare argparse);
-  that is chosen during Phase 1 and kept minimal.
-- Does not move the condensation/install scripts off Bash.
-
-## Consequences — unblocks
-
-- Phase 1 of `road-to-implement-ticket.md` can start: wire real step
-  handlers onto the dispatcher shape spiked here.
-- `implement-ticket-flow.md` will have its `Runtime: TBD` line replaced
-  with `Runtime: Python 3.10+` when Phase 1 lands.
-- Metrics contract (Q38, JSON lines under `agents/runtime/logs/implement-ticket/`)
-  is already demonstrated by both prototypes.
-
-## Follow-ups (not part of this ADR)
-
-- If later optimisation is needed, port the numbers above into a
-  `task bench-implement-ticket` target against the real handlers — the
-  original `bench.sh` lives only in this repo's git history now (see
-  commit `79f30e7`).
-- Decide CLI framework during Phase 1 (defer — argparse is enough for
-  the orchestrator skeleton).

package/docs/contracts/adr-install-user-type-axis.md

@@ -1,107 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-13
----
-
-# ADR — Install-time user-type axis
-
-> **Status:** Decided · 2026-05-15
-> **Source:** AI Council session 2026-05-15-step12-closure-run2 (Reviewer-A, Reviewer-B, Reviewer-C) D1 verdict — ACCEPT with amendments: seed all 7 user-types, cap roadmap at ≤5 phases, cap deliverables per phase.
-> **Sibling axis (distinct layer):** the runtime `personas/` ladder. The
-> install-time `user_type` axis filters *which skills load*; personas filter
-> *which voice reviews*. The two compose orthogonally.
-
-## Decision
-
-Install-time skill filtering uses a dedicated axis seeded under
-`user-types/` (package root, not `.agent-src.uncondensed/`). The
-selection lands in the consumer's `.agent-settings.yml` under
-`personal.user_type: <id>` via `agent-config install --user-type=<id>`.
-Runtime skill discovery intersects each skill's
-`recommended_for_user_types` frontmatter against
-`personal.user_type`; unset → "show all skills" (legacy behavior).
-
-The `user-types/` directory holds **seven** YAML configs — `consultant`,
-`creator`, `developer`, `finance`, `founder`, `gtm`, `ops` — matching
-every value already in active use across 32 skills' frontmatter. Adding
-an eighth value requires a new YAML plus a frontmatter audit (Phase 4).
-Schema: [`scripts/schemas/user-type-axis.schema.json`](../../src/scripts/schemas/user-type-axis.schema.json).
-
-## Why this is distinct from the review-lens axis
-
-Same vocabulary, different layer:
-
-| Axis | Layer | Owner roadmap | Where it bites |
-|---|---|---|---|
-| **Install filter** (this ADR) | onboarding / `.agent-settings.yml` | `step-9-user-types-axis.md` | Which skills surface first at discovery |
-| **Review lens** | runtime / `refine-ticket` | `step-6-user-types-axis.md` | Whose viewpoint a review adopts |
-
-The two never collide because they live in different files and
-different config keys. Install filter narrows *which skills load by
-default*; review lens narrows *whose voice a refine-ticket review
-adopts*. Authors can use both, neither, or one — independently.
-
-The naming overlap is preserved deliberately. Consumers think in terms
-of "I am a consultant" once; both axes consume that fact in their own
-layer. Renaming one would force consumers to learn a second vocabulary
-for the same self-identification.
-
-## Why install-time and not runtime-only
-
-Three options were considered:
-
-1. **Runtime-only filter** — read `personal.user_type` on every
-   session start, no install-time wiring. Rejected: needs the value
-   to exist before any skill loads; bootstrapping into an empty
-   `.agent-settings.yml` is fragile and undocumented.
-2. **Install-time flag, no runtime filter** — `--user-type` writes the
-   key, but skill discovery ignores it. Rejected: the value is dead
-   metadata without the discovery hook (Phase 3). Already the state of
-   the codebase before this roadmap; the whole point of step-9 is to
-   wire it.
-3. **Install-time flag + runtime filter** *(chosen)* — `--user-type`
-   writes the key; the discovery hook intersects frontmatter against
-   it. Legacy "no flag" path is preserved by treating an unset value
-   as "match all". Additive, opt-in, no breaking change.
-
-## Consequences
-
-- `scripts/install.sh`, `scripts/install.py`, `scripts/install` each
-  accept `--user-type=<id>`. Validation against `user-types/*.yml`
-  stems happens in one place (`install.py`) and the bash entry-point
-  delegates. Invalid values fail fast with a non-zero exit.
-- `src/config/agent-settings.template.yml` keeps a commented
-  `personal.user_type:` stub documenting the seven valid values.
-- The existing `--interactive` flag (legacy `.agent-config.local.json`
-  stub) is preserved for backward compat; the new flag is the
-  first-class path going forward. A future ADR can deprecate the JSON
-  stub once consumers migrate.
-- Frontmatter audit (Phase 4) catches drift: every value used in
-  `recommended_for_user_types` MUST have a corresponding YAML, and
-  every YAML SHOULD be consumed by at least one skill. The audit ships
-  as a CI gate (`task lint-user-type-axis` →
-  [`scripts/audit_user_type_axis.py`](../../src/scripts/audit_user_type_axis.py)).
-  Initial sweep at Phase 4 close: 7 declared / 7 used / 0 orphans / 0
-  unused — coverage is clean, no rename or backfill needed. Report:
-  [`agents/runtime/reports/user-type-axis-audit.md`](../../agents/runtime/reports/user-type-axis-audit.md).
-- Adding an 8th value is non-trivial by design — it requires a YAML, a
-  schema-compatible frontmatter rollout, and a roadmap entry. The
-  friction is the feature: a sprawling axis defeats the purpose of
-  filtering.
-
-## Open questions deferred
-
-- Skill-loader hook location is left to Phase 3 — likely
-  `scripts/skill_linter.py`'s discovery pass plus a runtime helper for
-  agent hosts that read the axis directly.
-- Whether to surface a "show outside `<id>` filter" affordance in
-  agent hosts is left to host-side UX, not enforced by this ADR.
-- The `default_skill_priority` field is informational in v1 (no
-  loader consumes it yet). Phase 3 may promote it to a sort key.
-
-## See also
-
-- [`user-types/README.md`](../../user-types/README.md) — schema + seed table
-- [`docs/contracts/universal-skills.md`](universal-skills.md) — always-loaded floor
-- [`docs/contracts/rule-router.md`](rule-router.md) — kernel + router
-  architecture (sibling but orthogonal axis)

package/docs/contracts/adr-layout.md

@@ -1,107 +0,0 @@
----
-stability: stable
----
-
-# ADR Layout — Per-area Directories
-
-> Status: accepted · 2026-05-16 · Roadmap: an internal parity roadmap (local-only) 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`](../../src/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) |
-| `telegraph` | Telegraph-speak condensation, decondensation, reversibility | [`condensation-default-kill-criterion.md`](condensation-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) |
-
-## 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.uncondensed/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`](../../src/scripts/audit_adr_coverage.py) — coverage gate.
-- [`scripts/adr/regenerate_index.py`](../../src/scripts/adr/regenerate_index.py) — index regenerator (works on both surfaces; pass `--dir`).
-- an internal parity roadmap (local-only) Phase 4 — origin.