@event4u/agent-config 2.19.0 → 2.20.1

package/docs/adrs/smoke/0001-per-tier-smoke-scripts.md

@@ -0,0 +1,99 @@
+# ADR 0001 — Per-tier smoke scripts (kernel · router · schema · skills)
+
+> Area: `smoke` · Status: accepted · Date: 2026-05-16 · Type: retrospective
+> Roadmap: `agents/roadmaps/step-11-ruflo-parity.md` Phase 4 Step 3
+> Supersedes: —
+
+## Context
+
+The North-Star audit
+([`external-findings.md § 5`](../../../agents/audit-2026-05-14-north-star/external-findings.md))
+flagged "smoke contracts" as an absorbed Ruflo pattern: every
+high-traffic tier needs a fast, deterministic, measurable check that
+runs in CI and surfaces regressions before they reach the rules /
+router / schema / skill linter pipelines.
+
+The full `task ci` run is ≥ 90 s and exercises every linter. That's
+fine for merge gates; it's too slow for path-change feedback on PRs
+that touch one tier in isolation.
+
+## Decision
+
+**One smoke script per tier, each ≤ 30 s, each emitting a baseline
+declaration as its last stdout line.** Scripts live under
+[`scripts/smoke/`](../../../scripts/smoke/):
+
+| Tier | Script | Validates | Path-trigger globs |
+|---|---|---|---|
+| Kernel | [`kernel.sh`](../../../scripts/smoke/kernel.sh) | 9 kernel rules present, char-budget respected | `.agent-src.uncompressed/rules/**`, `docs/contracts/kernel-membership.md` |
+| Router | [`router.sh`](../../../scripts/smoke/router.sh) | `router.json` compiles, all `routes_to:` resolve | `router.json`, `.agent-src.uncompressed/rules/**` |
+| Schema | [`schema.sh`](../../../scripts/smoke/schema.sh) | Random skill / rule sample validates against JSON Schema | `scripts/schemas/**`, `.agent-src.uncompressed/{rules,skills}/**` |
+| Skills | [`skills.sh`](../../../scripts/smoke/skills.sh) | 5 random skills pass frontmatter + `name == dir` | `.agent-src.uncompressed/skills/**` |
+
+### Runtime contract
+
+Per [`smoke-contracts.md`](../../contracts/smoke-contracts.md) § 1:
+
+| Limit | Value |
+|---|---:|
+| Wall time | ≤ 30 s |
+| External I/O | filesystem only — no network, no MCP |
+| Output | last stdout line = baseline declaration |
+| Exit code | non-zero on baseline regression |
+
+### CI wiring
+
+[`.github/workflows/smoke.yml`](../../../.github/workflows/smoke.yml)
+dispatches each smoke independently on path-trigger match. Local
+aggregator: `task smoke` (sub-tasks `task smoke:{kernel,router,schema,skills}`)
+wired in [`taskfiles/engine.yml`](../../../taskfiles/engine.yml).
+
+### Baseline declarations (lock-in 2026-05-16)
+
+- Kernel: `9 rules · 23 / 26 kB used (88 %) · 0 fence breaches`.
+- Router: `tier_1: N · tier_2: M · 0 unresolved routes`.
+- Schema: deterministic seed = epoch day · 10 random files validated.
+- Skills: deterministic seed = epoch day · `210 skills · 5/5 pass`.
+
+## Considered alternatives
+
+### Alt 1 — One monolithic smoke (rejected)
+
+Single `task smoke` running every check.
+
+**Why rejected:** path-change PRs pay the full cost every time;
+flaky tier-X regression masks tier-Y signal; output is harder to
+diff. The per-tier split costs four files and saves CI minutes.
+
+### Alt 2 — Inline-in-`task ci` only (rejected)
+
+Skip the smoke layer; rely on `task ci` for everything.
+
+**Why rejected:** `task ci` is the merge gate, not the feedback
+loop. Smokes are the cheap-and-fast layer between push and review.
+
+### Alt 3 — Per-tier, ≤ 30 s budget, baseline-declaring (accepted)
+
+The chosen path. One script per tier, declared budget, declared
+baseline, CI-dispatched on path-trigger.
+
+## Consequences
+
+- **Positive:** PRs touching one tier get tier-specific feedback in
+  ≤ 30 s; baseline declarations are diff-readable so regressions
+  surface in PR descriptions; the `task ci` merge gate stays the
+  authoritative full-run.
+- **Negative:** four scripts to maintain, one workflow file, one
+  taskfile entry. Mitigated by the runtime contract — a smoke that
+  approaches 30 s gets split, not optimised in place.
+- **Reversal cost:** delete `smoke.yml`; the scripts stay as opt-in
+  local checks (`task smoke:*`). No contract churn.
+
+## References
+
+- [`docs/contracts/smoke-contracts.md`](../../contracts/smoke-contracts.md) — runtime + path-trigger contract.
+- [`scripts/smoke/`](../../../scripts/smoke/) — four scripts.
+- [`.github/workflows/smoke.yml`](../../../.github/workflows/smoke.yml) — CI dispatch.
+- [`taskfiles/engine.yml`](../../../taskfiles/engine.yml) — local aggregator.
+- [`agents/audit-2026-05-14-north-star/external-findings.md`](../../../agents/audit-2026-05-14-north-star/external-findings.md) § 5 — origin pattern.
+- [`agents/roadmaps/step-11-ruflo-parity.md`](../../../agents/roadmaps/step-11-ruflo-parity.md) Phase 3 (delivery) + Phase 4 Step 3 (this ADR).

package/docs/adrs/smoke/README.md

@@ -0,0 +1,9 @@
+# ADRs — `smoke`
+
+> Per-tier smoke contracts, baseline locks, regression gates.
+
+Contract: [`docs/contracts/smoke-contracts.md`](../../../docs/contracts/smoke-contracts.md).
+
+| # | Title | Status | Date | Supersedes |
+|---|---|---|---|---|
+| [0001](0001-per-tier-smoke-scripts.md) | Per Tier Smoke Scripts | — | — | — |

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/archive/CHANGELOG-pre-2.17.0.md

@@ -0,0 +1,63 @@
+# Changelog Archive — pre-2.17.0
+
+> Frozen snapshot of `event4u/agent-config` changelog entries from
+> `2.16.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.17.x".
+> Entries here are not amended — git tag `2.16.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.16.0.md`](CHANGELOG-pre-2.16.0.md),
+> [`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.16.0](https://github.com/event4u-app/agent-config/compare/2.15.0...2.16.0) (2026-05-15)
+
+### Features
+
+* **install:** install-mode marker + minimal-init upgrade hint (Step 8 P3) ([e028468](https://github.com/event4u-app/agent-config/commit/e028468ed2b58428b99bea5a2e6c2a25e12fc113))
+* **cli:** doctor --trace-root + --context diagnostic surface (Step 8 P2) ([387a626](https://github.com/event4u-app/agent-config/commit/387a626b7795fc40e6e2442c1dde272dfc98f9d7))
+* **cli:** --root override flag + fail-loud root validation (Step 8 P1) ([0c8356e](https://github.com/event4u-app/agent-config/commit/0c8356e9034ca474827de89db5386a04c61f560c))
+* **wrapper:** export AGENT_CONFIG_PROJECT_ROOT pin so subdir invocations skip the walk ([e866cef](https://github.com/event4u-app/agent-config/commit/e866cef14d40269786fb0a88b69d9aafcfab1c88))
+* **agent-settings:** add resolve_project_root helper for Phase 3 subdir hardening ([95bac18](https://github.com/event4u-app/agent-config/commit/95bac187132d35d476716cd38d8c619bccaca6e5))
+* **install:** add --minimal / --settings-only init mode ([4c02743](https://github.com/event4u-app/agent-config/commit/4c02743cd7df6d89f7b7fa6188d654ca1eec983c))
+* **agent_settings:** extend find_project_root with agents/ + .agent-settings.yml anchors ([60dcd11](https://github.com/event4u-app/agent-config/commit/60dcd11c498f25f92bb01482943bfb95d4efef37))
+
+### Documentation
+
+* **changelog:** Step 8 discovery polish entry under Unreleased ([eecaf6a](https://github.com/event4u-app/agent-config/commit/eecaf6a9a2248a877d71dbd33e7db096f94dab3b))
+* **installation:** root override + monorepo semantics + diagnostics (Step 8) ([de3081f](https://github.com/event4u-app/agent-config/commit/de3081fe828cb43c628d922c50d25177d43f267e))
+* **roadmap:** archive step-7 (all phases complete) + sync dashboard ([8f2953e](https://github.com/event4u-app/agent-config/commit/8f2953ee5c867ada29c9f32cf45bd2380504bc12))
+* **step-7:** add minimal-init flow, anchor migration guide, changelog entry ([9ace019](https://github.com/event4u-app/agent-config/commit/9ace01945967e67e98e8855a940801db09de8d17))
+* **roadmap:** mark Step 7 Phase 3 complete (subdir invocation hardening) ([518f9dc](https://github.com/event4u-app/agent-config/commit/518f9dcaf6d71a34cf1700bceb1487f1e8e33175))
+* **roadmap:** mark Step 7 Phase 2 + test items complete ([1bb9b71](https://github.com/event4u-app/agent-config/commit/1bb9b712d866dd509124f7d8502f52957e972b20))
+* **roadmap:** mark Step 7 Phase 1 complete; refresh progress dashboard ([2ba8d5b](https://github.com/event4u-app/agent-config/commit/2ba8d5be1b94bbab87da4270d833697c895cc9c6))
+
+### Refactoring
+
+* **cli:** route all cmd_*.py entry points through resolve_project_root ([aa7a01a](https://github.com/event4u-app/agent-config/commit/aa7a01a7f27205919193d54339298c0dbd30c43e))
+
+### Tests
+
+* **cli:** coverage for --root override + doctor trace/context (Step 8) ([9b943aa](https://github.com/event4u-app/agent-config/commit/9b943aa9f002750499738fd36f8a203525fb84da))
+* **subdir:** cover resolve_project_root precedence + wrapper-pinned root ([0693714](https://github.com/event4u-app/agent-config/commit/06937145ac8f4e1160ec9279d3832e4f5397bb1e))
+* **install:** cover --minimal payload + nested-install guard ([5623521](https://github.com/event4u-app/agent-config/commit/56235218624792b487a92f444ff8ee114a5651a3))
+* **agent_settings:** cover anchor extension, kill-switch, perf budget ([37a080c](https://github.com/event4u-app/agent-config/commit/37a080c07ee9238fda45bbda1829764a4232f062))
+
+### Chores
+
+* **template:** bump agent_config_version pin to 2.15.0 ([093367d](https://github.com/event4u-app/agent-config/commit/093367d3e417a11a28295f2efa574e8c3fef6524))
+* **sync:** propagate Step 8 agent_settings.py to .agent-src/ projection ([7ce92e5](https://github.com/event4u-app/agent-config/commit/7ce92e514a8edbd970a4118b91d2f651bf730070))
+* **roadmap:** archive Step 8 discovery polish ([1c21982](https://github.com/event4u-app/agent-config/commit/1c219825dc413cfe45aefc3b12c08d2720583880))
+* **changelog:** split era 2.11.x → pre-2.15.0 ([c79363c](https://github.com/event4u-app/agent-config/commit/c79363c05d775ecfa95ab6fff5b3bbe706f797c9))
+
+Tests: 4405 (+53 since 2.15.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.