@event4u/agent-config 9.7.0 → 9.9.0

package/docs/decisions/ADR-033-distribution-identity-npm-primary.md

@@ -1,81 +0,0 @@
----
-adr: 033
-status: accepted
-date: 2026-05-29
-decision: distribution-identity-npm-primary
-supersedes: —
-superseded_by: —
-phase: distribution-identity
-type: structural
-review_date: 2026-08-29
----
-
-# ADR-033 — Distribution identity: npm-primary, Packagist deprecated-in-place
-
-## Status
-
-**Accepted** · 2026-05-29. AI Council (claude-sonnet-4-5 + gpt-4o, analysis lens, 2026-05-29) converged on **npm-primary with Packagist deprecated-in-place**. No maintainer veto surfaced; the de-facto evidence and the operational-honesty argument both point to a single answer. Review date 2026-08-29.
-
-## Context
-
-External feedback rounds 10 / 12 / 13 returned to two recurring symptoms — *"Packagist still shows 1.0.4"* and *"two major bumps in six days with no breaking-change signal"*. A council deliberation (lens: analysis) re-framed both as **one distribution-identity question** the repo has answered in practice but never recorded:
-
-- **`package.json` at `5.1.0`** — the package is past the unified-setup 4.0.0 major and a subsequent 5.0.0 line; semver discipline (per `CONTRIBUTING.md § Versioning policy`) treats installer-layout changes as major, so the cadence is policy-correct.
-- **`scripts/release.py` invokes `npm publish` exclusively** — the only publish surface that ships from a release run.
-- **No `composer.json` exists in this repo** — the file was removed during the npm pivot (pre-3.x era). The Packagist `event4u/agent-config` 1.0.4 listing is a zombie pointing at a repository state that no longer exists.
-- **No automation syncs the Composer surface** — none has existed since the pivot. Pretending the channel is supported is a maintenance lie.
-- **ADR-027** already locks the changelog-machine path (`scripts/release.py` derives `CHANGELOG.md § Breaking` from Conventional Commits). The "no breaking-change signal" symptom is stale against that surface — what is missing is a one-click pointer for consumers.
-
-Council framing — two perspectives surfaced:
-
-**Lens A — Strategic / consumer-positioning.** A consumer who lands on Packagist sees 1.0.4 and installs an artefact the repo cannot support. The honest signal is deprecation; dual-track without resources is worse than a single declared channel.
-
-**Lens B — Technical / operational-honesty.** A channel is "supported" only if a release pipeline publishes to it. Composer/Packagist has had no such pipeline since the npm pivot. The simpler invariant — *one channel, one truth* — wins on every measurable axis: maintenance load, consumer trust, audit clarity.
-
-Both lenses converged.
-
-## Decision
-
-1. **The package is npm-primary.** The canonical install path is `npm install @event4u/agent-config` (and the consumer-facing `npx @event4u/agent-config install` wizard). All release tooling (`scripts/release.py`, `package.json`, `CONTRIBUTING.md § Versioning policy`) already aligns with this surface — this ADR records the policy, no code changes follow from the declaration itself.
-
-2. **Composer / Packagist is deprecated-in-place.** No `composer.json` ships from this repo; no PHP autoload surface is supported; the Packagist `event4u/agent-config` 1.0.4 listing is treated as legacy and gets a deprecation pointer through the only mechanism available to a deleted-composer-json repo: a registry-side claim/archive action by the maintainer. The corresponding human-owner item is surfaced in `docs/distribution/registries.md` (see Phase 2 of the [`road-to-distribution-identity.md`](../../agents/roadmaps/road-to-distribution-identity.md) roadmap).
-
-3. **Breaking-change communication uses `CHANGELOG.md § Breaking`.** ADR-027 locked the auto-generated changelog from Conventional Commits. This ADR adds one consumer-facing affordance — a README / distribution-doc pointer linking that section — so a consumer who sees a major-version bump has a one-click path to *what broke, what to do*. No new `BREAKING_CHANGES.md` file unless the maintainer prefers one.
-
-4. **Commit-subject hygiene is enforced in CI.** Because the changelog generator reads commit subjects verbatim, sloppy subjects (`leftover`, `wip`, `temp`, `fixup`, or sub-10-character one-word entries) leak directly into the public changelog. A CI lint (`task lint-commit-subjects` or sibling) rejects those subjects on PR. This is wired in Phase 3 of the same roadmap and is the one hygiene item that ties directly to distribution identity.
-
-## Consequences
-
-**Positive:**
-
-- The distribution story is **single-channel, single-truth**. Anyone scanning the package — consumer, contributor, auditor, package-registry crawler — gets one consistent answer.
-- The zombie Packagist listing no longer misdirects PHP-shop consumers (once the maintainer files the registry-side archive action).
-- Breaking-change discoverability is two clicks from the README: "release notes" → `CHANGELOG.md § Breaking`. No bespoke `BREAKING_CHANGES.md` to maintain.
-- CI catches sloppy commit subjects before they become public changelog lines — the changelog is as clean as the gate that feeds it.
-
-**Negative / accepted costs:**
-
-- A PHP-shop consumer who depends on the 1.0.4 Packagist release is left behind. Mitigation: clear deprecation notice + npm install pointer in the registry-side archive.
-- The maintainer must perform a one-time login at `packagist.org/packages/event4u/agent-config` to claim or archive the listing — autonomous tooling cannot do that.
-- Future re-entry into the Composer ecosystem would require a new ADR superseding this one. That cost is acceptable: a re-entry would be a strategic redirect, not a quiet re-add.
-
-**Operationally neutral:**
-
-- `scripts/release.py` already does the right thing; no script change follows from this ADR.
-- `CONTRIBUTING.md § Versioning policy` already does the right thing; no policy change follows from this ADR. The major bumps that prompted the feedback (4.0.0 unified-setup, 5.0.0 follow-up) were policy-correct under the existing rule.
-
-## Alternatives considered
-
-- **Dual-track with auto-sync.** Rejected. The repo carries no Composer surface to sync; restoring one would mean re-introducing a `composer.json` + a sync pipeline + a PHP-side autoload story, all to support a consumer base nobody has named. The carrying cost outweighs the demand signal.
-- **Dual-track without auto-sync (status quo).** Rejected. This is the failure mode that produced the external feedback in the first place — a stale 1.0.4 listing pretends a channel is supported when it is not. Operational-honesty argument carries.
-- **Re-introduce composer.json as a stub linking to npm.** Rejected. A stub on Packagist is still a Packagist artifact; consumers may still try to `composer require` it and hit a non-functional package. Registry-side archive is the cleaner signal.
-- **A bespoke `BREAKING_CHANGES.md` file.** Rejected by default; ADR-027 already locks the machine-generated changelog as the breaking-change surface. Maintainer may revisit if the changelog format proves insufficient for end-of-life or migration-guide-shape communication.
-
-## References
-
-- [`agents/roadmaps/road-to-distribution-identity.md`](../../agents/roadmaps/road-to-distribution-identity.md) — the work-item plan this ADR underwrites.
-- [`ADR-027-changelog-machine-vs-manual.md`](ADR-027-changelog-machine-vs-manual.md) — the prior decision locking the auto-generated changelog.
-- [`CONTRIBUTING.md § Versioning policy`](../../CONTRIBUTING.md) — the semver discipline this ADR confirms.
-- [`docs/distribution/registries.md`](../distribution/registries.md) — external-registry submission posture; this ADR adds a distribution-channel-identity section to that file.
-- `scripts/release.py` — the `npm publish` release pipeline.
-- External feedback rounds 10 / 12 / 13 (private session transcripts; convergence summary inlined above to keep this ADR self-contained).

package/docs/decisions/ADR-034-per-skill-model-recommendation-transport.md

@@ -1,63 +0,0 @@
----
-adr: 034
-status: superseded
-date: 2026-05-30
-decision: per-skill-model-recommendation-transport
-supersedes: —
-superseded_by: 035
-phase: per-skill-model-autoswitch
-type: structural
-review_date: 2026-08-30
----
-
-# ADR-034 — Per-skill model recommendation: neutral source field, native projection on Claude
-
-> **Superseded by [ADR-035](ADR-035-model-capability-tiers.md)** (2026-05-30).
-> The concrete-model field (`recommended_model: opus|sonnet|gpt`) recommended a
-> cross-vendor model to Claude users (`gpt`) and was version-brittle. ADR-035
-> replaces it with vendor-neutral capability tiers (`model_tier: lite|medium|high`).
-
-## Status
-
-**Accepted** · 2026-05-30. AI Council (anthropic/claude-sonnet-4-5 + openai/gpt-4o, design lens, 2 rounds, 2026-05-30) was convened on the transport fork and the Claude projection shape. The council leaned toward putting a native `model:` key directly in source (its "Option B"); this ADR **overrides that lean on two package-specific facts the council lacked** and adopts the neutral-field transport (Option A). The council's other challenges (haiku floor, the `/model` trust boundary, measurement-first sequencing) are incorporated below.
-
-## Context
-
-`model-recommendation` (tier-2a, `core`) is a dead shell — it routes to `command:set-cost-profile`, which flips `rule_loading_tier` but never selects a model. The task→model intelligence already exists in `contexts/model-recommendations.md` but has no mechanism to act. Claude Code now honours a native skill `model:` frontmatter key — verified against the official skills docs (`code.claude.com/docs/en/skills.md`): the override applies for the rest of the current turn, reverts to the session model on the next prompt, and accepts the `/model` values plus `inherit`. That makes per-skill model selection structural on Claude; Augment has no per-turn override, so a rule surfaces a one-question suggestion there.
-
-The projection constraint: source `SKILL.md` is shared across tools via `.agent-src/`. `.claude/skills/<name>` is a whole-**directory symlink** to `.agent-src/skills/<name>`; `.claude/skills/<slug>/SKILL.md` for commands is a **symlink** inside a real dir. Augment skills symlink the same target. A Claude-only native `model:` therefore cannot live in the shared symlink target without also appearing in Augment.
-
-## Decision
-
-1. **Transport — Option A (neutral source field).** Source carries a tool-neutral `recommended_model:`; the Claude generator rewrites it to native `model:`; Augment keeps the neutral field for the rule to consume. **Council override rationale:** (a) the skill/command schemas are `additionalProperties: false`, so a native `model:` key in source would *fail* `validate_frontmatter` — Option B is not free as the council assumed; (b) the package's portability contract (`augment-edit-discipline`) forbids tool-specific keys in the portable source. Option A also matches the existing projection-transform philosophy (path rewrites, HRR-banner injection, Cursor `.mdc` field-dropping all already transform on projection).
-
-2. **Field + enum.** `recommended_model` with enum `opus | sonnet | gpt | inherit`. `inherit` = "no opinion, use the session model" (named to match Claude's own `inherit` value). `sonnet` is the cheapest tier — **no `haiku`** (see § Deferred). `gpt` has no Claude tier: it emits no native `model:` and only surfaces as a suggestion.
-
-3. **Claude projection shape — Option (b), minimal break.** Keep `.claude/skills/<name>` a real dir, symlink every sub-entry **except** `SKILL.md`, and render `SKILL.md` as a copy with `model:` injected — **only for skills that actually receive a native value** (`opus`/`sonnet`). Skills tagged `inherit`/`gpt`/untagged stay pure directory symlinks. This mirrors the existing command projection (real dir + handled `SKILL.md`), is idempotent on regenerate, and copies only the SKILL.md of model-bearing skills (disk-minimal).
-
-4. **Toggle gates native emission — `model.auto_switch`.** `.agent-settings.yml` `model.auto_switch: auto | suggest | off`, **default `suggest`**. The generator reads it: `auto` emits native `model:` into the Claude projection (auto-switch fires); `suggest` and `off` do **not** emit native `model:` — the rule surfaces a one-question suggestion on every surface instead. This resolves the council's trust-boundary concern: by default the package never silently overrides a user's explicit `/model` choice; native auto-switch is opt-in.
-
-## Consequences
-
-- Source stays portable and schema-valid; only the Claude projection carries `model:`.
-- Claude skills with a native recommendation become rendered `SKILL.md` copies (sub-files still symlinked); everything else stays a symlink.
-- The rule becomes the surface-aware decision layer (Phase 4); the task→model heuristics stay in the context file (cite, don't restate).
-- A coverage linter (Phase 5) makes an explicit recommendation or `inherit` mandatory on every skill/command, preventing silent drift.
-
-## Deferred (council challenges recorded, not dismissed)
-
-- **`haiku` tier.** The council argued the `sonnet` floor is a data-free exclusion and that haiku may suit truly mechanical tasks. Kept out of the enum for this PR (conservative quality guard for a structured-agent suite). Re-evaluation is **gated on the Phase 6 measurement** + per-skill eval data; adding `haiku` later is an additive enum change.
-- **Per-skill eval kill-switch.** The council wanted an automated "if eval failure > N%, revert to `inherit`" loop. No per-skill evals exist yet; the manual kill-switch is `model.auto_switch: off` or dropping the field (additive/reversible). Captured as a follow-up.
-- **Measurement-first sequencing.** The council preferred instrumenting cost before tagging. Phase 6 provides the before/after token-distribution delta; the ordering is a charter choice, noted.
-
-## Alternatives
-
-- **Option B — native `model:` in source.** Rejected: fails `additionalProperties: false` validation and violates the portability contract.
-- **Whole-directory copy for Claude skills.** Rejected: duplicates `evals/`, `schemas/`, etc. for zero benefit; Option (b) copies only `SKILL.md`.
-
-## References
-
-- `agents/roadmaps/road-to-per-skill-model-autoswitch.md` (charter).
-- `docs/contracts/multi-tool-projection-fidelity.md` (projection map; updated in Phase 3).
-- `contexts/model-recommendations.md` (task→model table; seeds the Phase 5 backfill).
-- Council convergence: anthropic/claude-sonnet-4-5 + openai/gpt-4o, design lens, 2026-05-30.

package/docs/decisions/ADR-035-model-capability-tiers.md

@@ -1,104 +0,0 @@
----
-adr: 035
-status: accepted
-date: 2026-05-30
-decision: model-capability-tiers
-supersedes: 034
-superseded_by: —
-phase: model-capability-tiers
-type: structural
-review_date: 2026-08-30
----
-
-# ADR-035 — Vendor-neutral model capability tiers (supersedes ADR-034)
-
-## Status
-
-**Accepted** · 2026-05-30. Supersedes **ADR-034**. AI Council
-(anthropic/claude-sonnet-4-5 + openai/gpt-4o, deep, design lens, 3 rounds,
-2026-05-30) converged on the design below.
-
-## Context
-
-ADR-034 shipped a per-skill `recommended_model` field with **vendor-specific
-values** (`opus | sonnet | gpt | inherit`). In use this produced a cross-vendor
-nonsense: a **Claude** user was recommended **`gpt`** for analysis-heavy skills.
-The values are also version-brittle (model names churn) and couple the portable
-source to specific vendors' line-ups. The fix is to recommend a **capability
-band**, not a model, and let each agent resolve the band to its own best model.
-
-## Decision
-
-1. **Tiers — `lite | medium | high` (+ `inherit`).** Pure capability descriptors
-   (reasoning horsepower), not use-case names. A 4th `frontier` tier is rejected
-   — it would map sparsely (one vendor's outlier) and break vendor-neutrality.
-   `inherit` = "no opinion, keep the session model".
-
-2. **Field rename `recommended_model` → `model_tier`.** The semantics changed
-   from a model identifier to an abstract band; keeping the old name "is lying in
-   code" (council). The 354-artefact rename is mechanical and worth the honesty.
-
-3. **Mapping ownership — the generator owns the Claude mapping, exclusively.**
-   This is the load-bearing decision. Exactly one place resolves a tier to a
-   concrete model: `scripts/condense.py`, because Claude Code is the only surface
-   that consumes a native `model:`. The mapping is `high → opus`,
-   `medium → sonnet`, `lite → haiku`. **Non-Claude agents are suggestion-only** —
-   the `model-recommendation` rule surfaces the tier *name* and the agent/user
-   maps it to their own line-up. The package maintains **no per-vendor runtime
-   table**; that would create the "two-clocks" drift failure (generator table vs
-   runtime table diverging as vendors rename models).
-
-4. **Long-context is orthogonal — optional `context: large` modifier.** Reasoning
-   horsepower and context length are independent (a 500-page-log summary is
-   low-reasoning + high-context). Model the rare long-context need as a sparse,
-   optional `context: large` frontmatter modifier, never as a tier. Most skills
-   omit it. It is metadata — it does not change the native Claude `model:` (the
-   tier owns the model choice).
-
-5. **Migration map.** `opus → high`, `sonnet → medium`, `gpt → high`,
-   `inherit → inherit`. The `gpt` band (large-context analysis) collapses into
-   `high` reasoning + an optional `context: large` modifier on the genuinely
-   long-context skills. A re-runnable classifier additionally routes
-   clearly-trivial mechanical work to `lite`.
-
-6. **`model.auto_switch` toggle unchanged** (`auto | suggest | off`, default
-   `suggest`). `suggest` emits no native `model:` and never overrides a user's
-   `/model` — the conservative staged-rollout default.
-
-## Consequences
-
-- No vendor model name leaves the band abstraction in source; a Claude user is
-  never recommended `gpt`.
-- The native `model:` exists only in the Claude projection, from a single map.
-- Other agents get a tier-name suggestion they resolve themselves — zero
-  per-vendor maintenance burden in the package.
-- Adding a vendor or renaming a model touches **one** mapping (the generator's
-  Claude row), not 354 artefacts.
-
-## Periodic staleness audit (council guard)
-
-The tier→model mapping is a contract that drifts as vendors rename/retire models.
-Guard: on each model-line-up change, update the single generator-owned Claude
-mapping (`high/medium/lite → model`). No artefact re-tagging is needed — the band
-is stable; only its resolution moves. Audit cadence: review at each release that
-touches model pricing/availability, and whenever a tier's mapped model is
-deprecated upstream.
-
-## Alternatives
-
-- **Keep concrete model names (ADR-034).** Rejected — the cross-vendor bug this
-  ADR fixes.
-- **Per-vendor runtime table consumed by the rule.** Rejected — the two-clocks
-  drift failure; suggestion-only is simpler and self-maintaining.
-- **Context length as a tier (`high-context`).** Rejected — conflates two
-  orthogonal axes; handled by the sparse `context: large` modifier instead.
-- **4th `frontier` tier.** Rejected — sparse cross-vendor mapping.
-
-## References
-
-- `agents/roadmaps/road-to-model-capability-tiers.md` (charter).
-- ADR-034 (superseded) — the concrete-model design this corrects.
-- `docs/contracts/multi-tool-projection-fidelity.md` (updated Phase 3).
-- `contexts/model-recommendations.md` (task→tier table; seeds the migration).
-- Council convergence: anthropic/claude-sonnet-4-5 + openai/gpt-4o, deep design
-  lens, 2026-05-30.

package/docs/decisions/ADR-036-global-install-browser-wizard-handoff.md

@@ -1,106 +0,0 @@
----
-adr: 036
-status: accepted
-date: 2026-06-01
-decision: global-install-browser-wizard-handoff
-supersedes: —
-superseded_by: —
-phase: v5.x · install-UX consistency
-type: forward-looking
----
-
-# ADR-036 — Global install hands off to the browser wizard (zero terminal prompts)
-
-## Status
-
-**Accepted** · 2026-06-01. Implements the install-UX half of
-[`road-to-self-update-and-global-hook-resolution`](../../agents/roadmaps/road-to-self-update-and-global-hook-resolution.md)
-(Phase 6). Builds on [`ADR-020`](ADR-020-global-only-consumer-scope.md)
-(global-only consumer scope) and reuses the wizard contract from
-[`gui-wizard`](../contracts/gui-wizard.md).
-
-## Context
-
-`npx @event4u/agent-config init` is the canonical first-time install
-(README Quickstart) and `agent-config upgrade` is the self-update path
-(ADR-020 update-lag fix). Both reach the global install through
-`scripts/install --global` → `install.py` `install_global()`. Field use
-surfaced four defects that made the global path drop into terminal
-interaction instead of the browser wizard the project path already used:
-
-1. **Terminal tool-picker.** `scripts/install`'s `prompt_tools()` fired
-   on every interactive run, pre-empting the wizard and — via
-   `TOOLS_EXPLICIT` — suppressing it (`_wizard_should_launch` treats an
-   explicit `--tools=` as "headless").
-2. **No wizard on `--global`.** `install_global()` returned before the
-   `_wizard_should_launch` / `_wizard_spawn` block; only the project
-   path launched the GUI.
-3. **Browser never opened.** `_wizard_await_ready` **printed** the
-   `WIZARD_READY` URL but never opened it (the child is spawned with
-   `--no-open` so the Python parent owns the open — it only printed).
-4. **Wrong identity + ADR-020 leak.** Spawning the wizard with
-   `--project-root <detect_root>` forced project write-root, so the
-   wizard read neither nor wrote the **global**
-   `~/.event4u/agent-config/settings/.agent-user.yml` (the saved
-   identity → name/language pre-fill defaulted to the OS account, e.g.
-   `mathiasberg`, instead of the saved `Matze`/`de`), and global content
-   would land in the project tree — an ADR-020 violation.
-
-## Decision
-
-On the interactive global-install path (`agent-config init` / `global` /
-`upgrade` / `refresh --global`), the install is **zero-terminal-interaction
-and hands off to the browser wizard**:
-
-- `scripts/install` skips `prompt_tools()` when the wizard will launch
-  (TTY · not `CI` · not `AGENT_CONFIG_NO_UI`) — the wizard is the single
-  tool-selection surface.
-- `install.py` launches the wizard after `install_global()` (parity with
-  the project path), gated by the single source of truth
-  `_wizard_should_launch`.
-- The wizard is spawned **without** `--project-root` so `resolveWriteRoot`
-  picks the **global** write root — the saved `.agent-user.yml` drives the
-  identity pre-fill, and no global content is written into the project
-  tree (reinforces ADR-020).
-- `_wizard_await_ready` opens the browser (`webbrowser.open`) after
-  printing the URL; the printed URL remains the headless fallback.
-- On the wizard-handoff path the run is non-interactive: foreign-file
-  conflicts auto-resolve to overwrite and the legacy migration runs
-  without the `[Y/n]` gate — no `--force`, no prompts. The wizard is the
-  settings + package surface that recreates fresh config.
-
-The terminal picker, conflict prompt, and migrate prompt remain the
-behaviour on **headless** paths (no TTY · `CI` · `--no-ui` ·
-explicit `--tools=`), where no wizard launches.
-
-## Consequences
-
-**Positive.**
-- "Run the command, it installs, then the wizard opens for packages +
-  settings" — the contract holds for `init` and `upgrade` alike.
-- A returning user's name/language pre-fill from the saved identity, not
-  the OS account.
-- Global content never leaks into the project tree on the wizard path.
-
-**Negative / trade-offs.**
-- Auto-overwrite + auto-migrate on the wizard path remove the per-file
-  confirmation. Scoped to the wizard-handoff path on paths agent-config
-  owns (ADR-020 global root); headless paths keep the prompts.
-- The browser-open + zero-prompt flow cannot be asserted in headless CI;
-  the welcome-step identity pre-fill (`Matze`/`de` from the global
-  write root) is covered by a Playwright drive.
-
-## Alternatives considered
-
-- **`npx` fallback inside the PostToolUse hook.** Rejected by the
-  2026-05-30 council (per-tool-call network + version drift) and again
-  2026-06-01; orthogonal to install UX. Hooks resolve the global binary.
-- **Keep the terminal prompts, document `--force`.** Rejected — the
-  maintainer's explicit contract is zero terminal interaction with a
-  browser handoff.
-
-## References
-
-- [`ADR-020`](ADR-020-global-only-consumer-scope.md) — global-only consumer scope.
-- [`gui-wizard`](../contracts/gui-wizard.md) — wizard apply contract.
-- [`road-to-self-update-and-global-hook-resolution`](../../agents/roadmaps/road-to-self-update-and-global-hook-resolution.md) — companion roadmap.

package/docs/decisions/ADR-037-cost-profile-untangle.md

@@ -1,117 +0,0 @@
----
-adr: 037
-status: accepted
-date: 2026-06-01
-decision: cost-profile-untangle
-supersedes: —
-superseded_by: —
-phase: cost-profile-untangle
-type: structural
-review_date: 2026-09-01
----
-
-# ADR-037 — Untangle `cost_profile` into single-purpose settings
-
-## Status
-
-**Accepted** · 2026-06-01. AI Council (anthropic/claude-sonnet-4-5 +
-openai/gpt-4o, analysis lens, 3 rounds, 2026-06-01) converged on the
-rename + keep-decoupled design below; findings were critically evaluated
-against the codebase before adoption.
-
-## Context
-
-The `cost_profile` setting had accreted multiple responsibilities plus a
-hard naming collision:
-
-1. **Canonical meaning** — rule-tier loading (`minimal | balanced | full |
-   custom`), a token-footprint lever resolved from `dist/router.json`.
-2. **Colliding second meaning** — a separate contract
-   (`memory-visibility-v1`) and the work-engine hook read the *same key*
-   `cost_profile` with an incompatible value set (`lean | standard |
-   verbose`) to gate the `🧠 Memory` visibility-line cadence. Because no
-   real install ever wrote `cost_profile: lean`, the suppress branch was
-   **unreachable dead code**.
-3. **Default drift** — the default was declared in four places with three
-   different answers (`balanced`, `minimal`, `standard`).
-4. **Migrated intent** — `cost_profile` was originally meant to gate
-   self-optimization; that capability had already moved to the independent
-   `pipelines.skill_improvement` setting + tier-2a rule loading.
-5. **Naming confusion** — four "cost"-sounding concepts (`cost_profile`,
-   the memory cadence, `/cost:report` + `cost.budgets`, and
-   `model_tier`/`model.auto_switch`) competed for one mental slot; only the
-   first two were literally named `cost_profile`, and the second was the
-   broken one.
-
-The root cause was the absence of a settings schema: nothing prevented one
-key from carrying two value vocabularies.
-
-## Decision
-
-1. **One key, one job.** Rename the canonical setting `cost_profile` →
-   `rule_loading_tier` (values unchanged: `minimal | balanced | full |
-   custom`). The name now describes the mechanism, not a side effect, which
-   makes the `/cost:report` mismatch obvious ("you can't lower your rule
-   loading tier to save money without losing guardrails").
-2. **Memory cadence owns its own key.** The visibility-line cadence moves
-   to `memory.cadence` (`auto | always | never`, default `always` —
-   behaviour-neutral; the previously-dead suppress path is now reachable as
-   `auto`). Named `memory.cadence`, not `memory_status`, to avoid a clash
-   with the existing `scripts/memory_status.py`.
-3. **Self-optimization stays decoupled.** `pipelines.skill_improvement`
-   remains the independent lever; `rule_loading_tier` is *not* re-coupled to
-   learning behaviour. The council was unanimous that coupling token
-   footprint to learning behaviour is the wrong axis.
-4. **Schema prevents recurrence.** A new
-   `scripts/schemas/agent-settings.schema.json` (+ CI validator) enum-
-   constrains the value-bearing keys so a value-vocabulary collision is a
-   hard CI failure, not silent dead code.
-5. **Migration, not break.** `install.py`'s `LEGACY_RENAME_MAP` rewrites
-   `cost_profile` → `rule_loading_tier`; loaders read the legacy key as a
-   fallback during a grace period. The default is consolidated to one
-   source of truth (`balanced`).
-
-### Deliberately *not* done (scope discipline)
-
-- **Command + file names kept** (`/set-cost-profile`,
-  `cost-profile-defaults.md`) — renaming them cascades through the
-  ownership-matrix, command-surface, discovery manifest, and marketplace
-  (all CI-enforced/generated); the cost/benefit did not clear the bar.
-  Their *content* now uses `rule_loading_tier`.
-- **`custom` left unchanged** — it is absent from `dist/router.json`
-  profiles (documented but not router-dispatched). Its implementation is a
-  pre-existing question, tracked as a follow-up, not part of this rename.
-- **`dist/router.json` `profiles` key kept** — it is the tier-list
-  structure, not the setting name; consumers may parse it.
-
-## Consequences
-
-- The silent dead-code bug is gone; the memory cadence is reachable and
-  tested.
-- A future settings-key collision fails CI immediately.
-- Existing installs migrate automatically; no manual action.
-- Internal naming is slightly inconsistent (command/file still say
-  "cost-profile" while the setting is `rule_loading_tier`) — an accepted
-  trade-off against a high-churn, low-value rename of generated surfaces.
-- Breaking change to a public settings key → next major (see
-  `BREAKING_CHANGES.md`).
-
-## Alternatives considered
-
-- **Re-couple `cost_profile` to self-optimization** (the original intent) —
-  rejected: couples two orthogonal axes (token footprint + learning
-  behaviour); the council and the existing decoupled architecture both
-  argue against it.
-- **Minimal fix — resolve only the collision, keep the `cost_profile`
-  name** — rejected: leaves the misleading "cost" name and so leaves part
-  of the four-concept confusion intact.
-- **Rename the command + doc files too** — deferred: disproportionate
-  cascade through CI-enforced manifests for marginal benefit.
-
-## References
-
-- `BREAKING_CHANGES.md` (next-major entry).
-- `docs/contracts/memory-visibility-v1.md` § Cadence interaction.
-- `docs/contracts/cost-profile-defaults.md` (rule-loading defaults).
-- `scripts/schemas/agent-settings.schema.json` + `scripts/validate_agent_settings.py`.
-- ADR-010 (profile / pack / preset boundary) — `cost_profile` axis renamed.

package/docs/decisions/ADR-038-canonical-settings-path.md

@@ -1,96 +0,0 @@
----
-adr: 038
-status: accepted
-date: 2026-06-01
-decision: canonical-settings-path
-supersedes: —
-superseded_by: —
-type: structural
----
-
-# ADR-038: Canonical settings path is `agents/settings/.agent-settings.yml`
-
-- **Status:** Accepted
-- **Date:** 2026-06-01
-
-## Context
-
-The project's settings *layer* lives under `agents/settings/` — it already
-holds `contexts/`, `policies/`, and the per-machine override
-`.agent-settings.local.yml` (relocated there by `4f887ae8`). The main
-developer settings file, however, stayed at the repo root as
-`./.agent-settings.yml`: `agent_settings.py` (`DEFAULT_PROJECT_FILE`),
-`install.py` (`SETTINGS_FILE`), `sync_agent_settings.py` (`DEFAULT_SETTINGS`),
-and ~30 reader scripts all hardcode the root path. The split is inconsistent —
-the override sits in the settings layer while the file it overrides sits at the
-root — and surfaced as a real defect: roadmaps and contributors referenced
-`agents/settings/.agent-settings.yml` (the location they expected), which then
-failed `check-references` because no such canonical file existed.
-
-Both files are gitignored (`.gitignore` matches the `.agent-settings.yml`
-basename anywhere) and per-machine; neither is ever committed.
-
-## Decision
-
-The canonical project settings file is **`agents/settings/.agent-settings.yml`**,
-co-located with the rest of the settings layer. The repo-root
-`./.agent-settings.yml` becomes a **back-compat read-fallback only**.
-
-- **Read precedence (deepest wins):** legacy root `.agent-settings.yml`
-  < canonical `agents/settings/.agent-settings.yml` < per-machine
-  `agents/settings/.agent-settings.local.yml`.
-- **Write target:** always `agents/settings/.agent-settings.yml`
-  (`canonical_settings_write_path`). The legacy root file is migrated into
-  the canonical location, never written afresh.
-- **Resolution helper:** `project_settings_path()` returns the canonical file
-  when present, else the legacy root file when present (back-compat), else the
-  canonical path (fresh repo). All direct readers route through it.
-- **Migration:** `install` and the `migrate` command relocate an existing root
-  `./.agent-settings.yml` to `agents/settings/.agent-settings.yml` once; no
-  consumer install breaks because the fallback keeps the old location readable
-  until it is moved.
-
-## Consequences
-
-- Settings layout is internally consistent: the main file and its override live
-  together under `agents/settings/`.
-- Existing installs keep working unchanged until migrated (read-fallback).
-- One-time cost: ~36 Python reader sites + the TS settings server/CLI route
-  through the helper; install/sync/migrate gain the relocation step; docs and
-  the gitignore-managed block name the canonical path.
-- The `.gitignore` basename match already covers the canonical path — no new
-  ignore entry required.
-
-## Amendment — 2026-06-03 · dev-mode resolution semantics
-
-Recorded alongside [`ADR-049`](ADR-049-configuration-trust-boundary.md) so a
-future contributor does not read `AGENT_CONFIG_DEV_MODE=1` as a settings-scope
-escape hatch.
-
-When `AGENT_CONFIG_DEV_MODE=1` (`scripts/install.py` treats the package repo as
-both source and project surface, per [`ADR-020`](ADR-020-global-only-consumer-scope.md)):
-
-- The package repo's `agents/settings/` **is** the project surface — its
-  `.agent-settings.yml` / `.ai-council.yml` are the maintainer's test fixtures
-  for exercising the loader against real files, not a workaround.
-- The user-global layer (`~/.event4u/agent-config/`) still provides the
-  whitelisted identity keys and provider secrets exactly as in a consumer install.
-- **No special merge logic.** The normal cascade composes (user-global whitelist
-  → project-canonical → local override). Dev-mode changes *which directory* is the
-  project surface, never *which keys* may cascade — the `MERGEABLE_KEYS` trust
-  boundary from [`ADR-049`](ADR-049-configuration-trust-boundary.md) holds
-  unchanged.
-
-## Alternatives considered
-
-- **Keep root canonical (status quo).** Rejected: leaves the override/main-file
-  split inconsistent and keeps surfacing as wrong-path references.
-- **Hard cut, no fallback.** Rejected: breaks every existing install (and this
-  repo) until each re-runs setup; the fallback is cheap insurance.
-
-## References
-
-- `scripts/_lib/agent_settings.py` — resolver cascade + `project_settings_path` / `canonical_settings_write_path`.
-- `4f887ae8` — prior relocation of `.agent-settings.local.yml` into `agents/settings/`.
-- `docs/guidelines/agent-infra/layered-settings.md` — precedence model.
-- `docs/contracts/migrate-command.md` — migration surface.