@event4u/agent-config 6.0.0 → 7.0.0

package/docs/decisions/ADR-013-discovery-frontmatter-contract.md

@@ -125,6 +125,8 @@ Amendments to the workspace list require an ADR-013 amendment.
 | `meta` | Artefacts that maintain *this* package (`agent-config` itself). |
 | `git` | Git workflow — commit, pull requests, branch sync. Carries `slug_prefix: git` (ADR-044 §A3); `requires: engineering-base`. Added 2026-06-04 for 6.0.0-D Step 12 Class B1 (`commit`→`git-commit`, `create-pr`→`git-pr-create`). |
 | `frontend-design` | Grounded design intelligence — design-knowledge corpus + BM25 grounding engine, design tokens, stack best-practice and chart/typography knowledge. `requires: engineering-base`; `suggests: react, nextjs`. Added 2026-06-07 (ADR-061). |
+| `analysis-workbench` | RCA, post-mortem, premortem, decision-review as an integrated learning loop. `requires: engineering-base`; opt-in under the `engineering` workspace. Added 2026-06-15 (ADR-096). |
+| `brand` | Brand as a first-class UX layer — archetype/voice/identity grounding corpus, brand→token derivation, and consistency governance that constrains UI. `requires: frontend-design`; `suggests: ai-image`; opt-in under the `engineering` workspace. Added 2026-06-16 (road-to-image-brand-typography Phase B). |
 
 Amendments to the pack list require an ADR-013 amendment and the
 matching `src/config/discovery/packs.yml` row in the same PR.
@@ -267,7 +269,7 @@ and `profile.id` reservations holds.
 Added pack id `frontend-design` to the closed vocabulary (grounded design
 intelligence — design-knowledge corpus + BM25 grounding engine, design tokens,
 stack best-practice and chart/typography knowledge, adopted from the MIT
-`nextlevelbuilder/ui-ux-pro-max-skill` corpus per ADR-061). Mirrored in
+an external reference corpus per ADR-061). Mirrored in
 [`src/config/discovery/packs.yml`](../../src/config/discovery/packs.yml) and the
 `ADR_PACKS` frozenset in
 [`scripts/lint_discovery_vocabulary.py`](../../src/scripts/lint_discovery_vocabulary.py).
@@ -279,6 +281,20 @@ openai/gpt-4o, converged A2: opt-in pack over inflating `engineering-base`
 with ~1 MB of design data). Additive, no rename; non-overlap with
 cost-profile and `profile.id` reservations holds.
 
+### 2026-06-16 — New `brand` pack
+
+Added pack id `brand` to the closed vocabulary (brand as a first-class UX layer
+— archetype/voice/identity grounding corpus, brand→token derivation, and
+consistency governance that constrains UI). Mirrored in
+[`src/config/discovery/packs.yml`](../../src/config/discovery/packs.yml) and the
+`ADR_PACKS` frozenset in
+[`scripts/lint_discovery_vocabulary.py`](../../src/scripts/lint_discovery_vocabulary.py).
+`workspaces: [engineering]`, `requires: [frontend-design]`, `suggests:
+[ai-image]` (pack-brand exports tokens, pack-ai-image consumes them — B → A),
+`trust_level_default: professional`, `size_class: medium`. Council-resolved
+2026-06-13 (road-to-image-brand-typography Phase B). Additive, no rename;
+non-overlap with cost-profile and `profile.id` reservations holds.
+
 ## Cross-references
 
 - [ADR-007 — Agent Discovery Scopes](ADR-007-agent-discovery-scopes.md):

package/docs/decisions/ADR-026-explain-mode-translation.md

@@ -112,6 +112,6 @@ glossary YAMLs translate forward.
 ## Cross-references
 
 - Contract: [`docs/contracts/explain-modes.md`](../contracts/explain-modes.md).
-- Envelope: [`docs/contracts/agent-memory-contract.md`](../contracts/agent-memory-contract.md).
+- Envelope: [`internal/schemas/retrieval-v1.schema.json`](../../internal/schemas/retrieval-v1.schema.json).
 - Workspace: [`ADR-025`](ADR-025-workspace-chrome.md), [`docs/contracts/daily-workspace.md`](../contracts/daily-workspace.md).
 - Roles: [`docs/contracts/role-experience.md`](../contracts/role-experience.md).

package/docs/decisions/ADR-056-unvalidated-video-adapters-disposition.md

@@ -119,6 +119,6 @@ No adapter is removed without explicit maintainer sign-off in this ADR
 ## References
 
 - `road-to-video-foundation-validation.md` (Phase 4) — the step this ADR closes.
-- `src/scripts/ai-video/lib/adapter-contract.md` (v2) — the trust-boundary helpers a validated adapter must use.
+- `src/scripts/media/lib/adapter-contract.md` (v2) — the trust-boundary helpers a validated adapter must use.
 - `provider-lifecycle-discipline` rule — the `experimental → stable` promotion gate.
 - AI council convergence (claude-sonnet-4-5 + gpt-4o, 2026-06-06): validation-first; multiplexer pivot supersedes per-model adapters.

package/docs/decisions/ADR-059-render-resume-filesystem-as-state.md

@@ -154,7 +154,7 @@ the "skill suite, not a runtime framework" answer.
 - Council artefact: two-round debate 2026-06-07 (members above), design
   mode, peer review on — convergence summarized in this ADR per
   `no-roadmap-references` (no session-file links).
-- `src/scripts/ai-video/lib/adapter-contract.md` — v2 trust boundary +
+- `src/scripts/media/lib/adapter-contract.md` — v2 trust boundary +
   error contract this design builds on.
 - Roadmap: road-to-video-deferred-design, Phase 1 (transient layer —
   not path-linked per `no-roadmap-references`).

package/docs/decisions/ADR-060-comfyui-sandbox-model.md

@@ -148,7 +148,7 @@ internet" out of the execution path.
   mode, peer review on — convergence summarized inline per
   `no-roadmap-references`.
 - ADR-059 — sibling design (resume) from the same roadmap phase.
-- `src/scripts/ai-video/lib/adapter-contract.md` — v2 contract the
+- `src/scripts/media/lib/adapter-contract.md` — v2 contract the
   adapter implements; local-source rule lands there as an additive note.
 - Roadmap: road-to-video-deferred-design, Phase 2 (transient layer —
   not path-linked per `no-roadmap-references`).

package/docs/decisions/ADR-061-corpus-grounding-layer.md

@@ -119,7 +119,7 @@ Recorded in `src/skills/design-intelligence/ATTRIBUTION.md`.
 | Fork | Resolution |
 |---|---|
 | Pack placement | **New `frontend-design` pack** (ADR-013 amendment, same PR). `requires: [engineering-base]`, `suggests: [react, nextjs]` — corpus is stack-agnostic data, React never required. Keeps ~1 MB of design data out of `engineering-base`. |
-| `google-fonts.csv` (745 KB, 1923 rows) | **Skip.** Redundant with the public Google Fonts API; `typography.csv` (73 curated pairings) carries the pairing decision. Document the API fallback for fonts outside the curated set. |
+| `google-fonts.csv` (745 KB, 1923 rows) | **Skip.** Redundant with the public Google Fonts API; `font-pairings-reference.csv` (73 curated pairings) carries the pairing decision. Document the API fallback for fonts outside the curated set. |
 | Stack-corpus surfacing | **`--stack <name>` search domain** on the one grounding engine — single mechanism, no 16-way prose-staleness vector. |
 | Brand→token pipeline | **Defer** with a watch note pinning the upstream commit SHA; adopt on first consumer demand. |
 
@@ -168,3 +168,50 @@ Recorded in `src/skills/design-intelligence/ATTRIBUTION.md`.
   Gemini-suite watch note.
 - Upstream: `nextlevelbuilder/ui-ux-pro-max-skill` @
   `b7e3af80f6e331f6fb456667b82b12cade7c9d35` (last checked 2026-06-07).
+
+## Amendment — 2026-06-16 (§8/§9 superseded in part)
+
+The image/brand/typography work re-examined the gated and deferred items of
+§8/§9 on the merits for the product vision. A two-round merits council
+(anthropic/claude-sonnet-4-5 + openai/gpt-4o, 2026-06-13, design lens,
+web-research-grounded) overturned three of them. The four-operation routing
+(§1) and the no-forked-engine principle (§2) are unchanged — the brand corpus
+is a second instance of the same grounding engine.
+
+- **§8 brand→token defer — resolved, no longer deferred.** This work was the
+  "first consumer demand" §8 named. `brand-to-tokens` ships: brand decisions →
+  a DTCG `.tokens.json` source of truth → `design-tokens/scripts/tokens.py`
+  (no Node). The same `.tokens.json` is the export pack-ai-image's brand-asset
+  generation and the greenfield-scaffold seed consume.
+- **§8 font fork — superseded.** "Skip `google-fonts.csv`, rely on the live
+  Google Fonts API" is replaced by **adopt-lite pinned metadata**: pin the MIT
+  `google-font-metadata` mirror (or a slim top-N slice) as a deterministic
+  offline **Reference**; the live API needs a key, is nondeterministic, and
+  carries no pairing metadata. `font-pairings-reference.csv` stays the curated
+  pairing Reference with a freshness contract.
+- **§9 brand-asset generation — superseded, ADOPTED.** The Gemini generative
+  brand-asset suite (logo/CIP/banner/social) was gated as a possible second
+  image-gen stack. The merits pass established it never was one: generation is
+  structured prompting + brand-token injection + provider routing on the
+  **existing** adapters (now the neutral `scripts/media/` substrate), with a
+  `recraft`/LLM-SVG vector path for marks raster models can't emit. Generation
+  lives in **pack-ai-image**; brand governance/tokens stay in **pack-brand**,
+  which exports tokens pack-ai-image consumes (dependency B → A, never
+  inverted). The `domain-watch/generative-brand-assets.md` gate is cleared.
+- **§9 slide/presentation engine — confirmed out of scope, but reasoned.**
+  Document assembly ≠ brand UX; owning a render engine (reveal.js / Presenton /
+  Gamma) is scope creep. pack-brand instead **exports validated brand
+  templates** (Marp/reveal YAML with locked brand variables) for the user's own
+  deck tools — enforcement via the template, not engine ownership. Re-open only
+  on evidenced demand.
+
+The brand corpus deviates from the §8-implied "adopt the SHA-pinned claudekit
+brand sub-skills" framing: it is **original-authored** from public brand
+frameworks (Jung / Mark-Pearson archetypes, public messaging frameworks),
+`upstream: null` — honest provenance, no third-party SHA to pin, no §4b file
+marking. The shared grounding engine is still attributed via
+`design-intelligence/ATTRIBUTION.md`.
+
+Implementing roadmap: `road-to-image-brand-typography` (Phase A–D),
+archived 2026-06-16; live-validation + command-surface follow-on tracked in
+its sibling follow-up roadmap.

package/docs/decisions/ADR-088-no-external-runtime-federation.md

@@ -5,7 +5,7 @@ date: 2026-06-11
 decision: no-external-runtime-federation
 supersedes: —
 superseded_by: —
-phase: ruflo-coexistence
+phase: external-runtime-coexistence
 type: structural
 ---
 
@@ -14,30 +14,30 @@ type: structural
 ## Status
 
 **Accepted** · 2026-06-11. Lands with the closure of PR #262
-("ruflo coexistence bridge") as superseded.
+("external-runtime coexistence bridge") as superseded.
 
 ## Context
 
-[`ruvnet/ruflo`](https://github.com/ruvnet/ruflo) is a multi-agent
+An external multi-agent runtime is a multi-agent
 orchestration **runtime** (swarms, persistent memory / RAG, an MCP server,
 a hooks system, background workers). It also writes `.claude/` lifecycle
 hooks, so it shares a Claude Code project's `.claude/` directory with
 `event4u/agent-config`.
 
-PR #262 (authored 2026-05-27) proposed a "ruflo coexistence bridge" with four
+PR #262 (authored 2026-05-27) proposed an "external-runtime coexistence bridge" with four
 parts:
 
 1. **Plugin-scope hook delivery** — ship agent-config's Claude hooks via the
    plugin (`hooks/hooks.json`) instead of the shared `.claude/settings.json`
    hooks array, to stop colliding with neighbour tools' hook arrays.
-2. **`detect_ruflo` + `coexist`/`skip` mode + dispatcher skip-gate** — detect
-   ruflo, offer a one-time choice, optionally skip agent-config's own
+2. **`detect_external` + `coexist`/`skip` mode + dispatcher skip-gate** — detect
+   the external runtime, offer a one-time choice, optionally skip agent-config's own
    dispatcher so the two tools' hooks don't double-fire.
-3. **A detection-gated `ruflo-bridge` pack** (`ruflo-routing` rule +
-   `ruflo-orchestration` skill) documenting ruflo's MCP-tool surface and a
-   persona→agent-type map so the host agent can **drive ruflo's swarm**.
+3. **A detection-gated `external-runtime-bridge` pack** (`external-runtime-routing` rule +
+   `external-runtime-orchestration` skill) documenting the external runtime's MCP-tool surface and a
+   persona→agent-type map so the host agent can **drive the external runtime's swarm**.
 4. **A coexistence contract + an 8-phase roadmap** (later phases: shared
-   cross-tool memory, collision namespacing, git-layer enforcement of ruflo
+   cross-tool memory, collision namespacing, git-layer enforcement of the external runtime's
    swarm commits, docs).
 
 Two things happened on `main` after the PR was authored:
@@ -47,15 +47,14 @@ Two things happened on `main` after the PR was authored:
   `ensure_claude_bridge` writes only `enabledPlugins`, canonical id
   `agent-config@event4u`). agent-config no longer owns the `settings.json`
   hooks array, so it coexists with *any* neighbour tool's hooks generically —
-  ruflo included. The original hook-collision motivation is solved without
-  anything ruflo-specific.
-- **(B) A "ruflo adoption" decision was recorded** (cross-vendor council,
-  claude-sonnet-4-5 + gpt-4o, 2026-05-06; see archived
-  `road-to-ruflo-adoption` and [`docs/parity/ruflo.md`](../parity/ruflo.md)).
-  Verdict: harvest only **portable** patterns from ruflo (ADR methodology,
-  cost-tracker, HMAC signing) and **explicitly do not couple to ruflo's
+  the external runtime included. The original hook-collision motivation is solved without
+  anything external-runtime-specific.
+- **(B) An "external-runtime adoption" decision was recorded** (cross-vendor council,
+  claude-sonnet-4-5 + gpt-4o, 2026-05-06; see an internal parity record (local-only)).
+  Verdict: harvest only **portable** patterns from the external runtime (ADR methodology,
+  cost-tracker, HMAC signing) and **explicitly do not couple to the external runtime's
   runtime / swarm / MCP tools** — wording used: "out of suite identity".
-  Candidates requiring ruflo's runtime (`observe-trace`, `test-gaps`) were
+  Candidates requiring the external runtime (`observe-trace`, `test-gaps`) were
   dropped for that reason; an MCP/HTTP-bridge was only "deferred-with-trigger".
 
 PR #262's parts 2–4 are precisely the runtime coupling decision (B) rejected.
@@ -77,10 +76,10 @@ not a feature, smuggled in via an incremental PR.
 
 1. **agent-config does not bridge to, or drive, external tool runtimes.**
    It is a **content suite** (skills, rules, commands) for AI coding tools —
-   not a runtime coordinator. It ships no `ruflo-orchestration`,
+   not a runtime coordinator. It ships no `external-runtime-orchestration`,
    `cursor-orchestration`, `aider-routing`, `windsurf-bridge`, or equivalent
    artifact that calls another tool's runtime / swarm / MCP surface. This is a
-   **category** boundary, not a ruflo-specific one. Consistent with the
+   **category** boundary, not an external-runtime-specific one. Consistent with the
    "no app runtime" identity in
    [`package-self-orientation`](../contracts/package-self-orientation.md).
 
@@ -95,7 +94,7 @@ not a feature, smuggled in via an incremental PR.
 3. **Federation is a separate, explicit decision.** If agent-config should ever
    expand from skill-suite to a "federation platform" that orchestrates
    external orchestrators, that requires its **own** ADR answering, at minimum:
-   (a) should the suite take on that identity; (b) the generic design (ruflo +
+   (a) should the suite take on that identity; (b) the generic design (an external runtime +
    Cursor + Copilot + Windsurf, not one vendor); (c) the maintenance model for
    N external bridges; (d) the trust contract — who validates an external
    runtime's output, and how agent-config's safety floors
@@ -112,9 +111,9 @@ not a feature, smuggled in via an incremental PR.
   neighbour tool's installation, version, or MCP-tool stability.
 - The maintenance surface does not grow by one bridge per orchestrator, and
   behaviour does not vary by which neighbours are installed.
-- Users who run both agent-config and ruflo (or any neighbour) get hook
+- Users who run both agent-config and the external runtime (or any neighbour) get hook
   coexistence for free via plugin scope; they do not get agent-config-driven
-  ruflo orchestration.
+  external-runtime orchestration.
 - Future "let's just add detection / a bridge for tool X" PRs have a recorded
   boundary to point at, preventing re-litigation. They are redirected to the
   generic, protocol-level, ADR-gated path in (2)–(3).
@@ -124,7 +123,7 @@ not a feature, smuggled in via an incremental PR.
 - **Finish & merge PR #262 as-is** — rejected: reintroduces the runtime
   coupling decision (B) dropped, across an unvalidated trust boundary, and
   enacts a strategic pivot without an explicit decision.
-- **Repurpose to the defensive sliver only** (`detect_ruflo` + dispatcher
+- **Repurpose to the defensive sliver only** (`detect_external` + dispatcher
   skip-gate + a generalised neighbour-coexistence contract) — rejected as the
   default: the council found it wrong-layer (coordination belongs at the
   protocol layer, not in tool-specific detection code) and redundant given (A),
@@ -136,10 +135,10 @@ not a feature, smuggled in via an incremental PR.
 
 ## References
 
-- PR #262 — "feat: ruflo coexistence bridge" (closed as superseded, 2026-06-11).
-- [`docs/parity/ruflo.md`](../parity/ruflo.md) — ruflo parity verdict
+- PR #262 — "feat: external-runtime coexistence bridge" (closed as superseded, 2026-06-11).
+- An internal parity record (local-only) — external-runtime parity verdict
   (all patterns mechanism-covered; no runtime coupling).
-- Archived `road-to-ruflo-adoption` — the 2026-05-06 cross-vendor council
+- An internal parity record (local-only) — the 2026-05-06 cross-vendor council
   decision: harvest portable patterns, "out of suite identity" for the runtime.
 - [`package-self-orientation`](../contracts/package-self-orientation.md) —
   "no app runtime" identity.

package/docs/decisions/ADR-090-visibility-command-frontmatter-field.md

@@ -0,0 +1,95 @@
+---
+adr: 090
+status: accepted
+date: 2026-06-13
+decision: visibility-command-frontmatter-field
+supersedes: —
+superseded_by: —
+phase: command-surface-refactor-residuals
+type: structural
+---
+
+# ADR-090 — First-class `visibility:` command-frontmatter field
+
+## Status
+
+**Accepted** · 2026-06-13. Decided by AI council (anthropic/claude-sonnet-4-5
++ openai/gpt-4o, peer-review, deep) — converged on **Option A** with execution
+refinements. Council necessity-gate: borderline (3 necessary / 3 unnecessary);
+proceeded on the standing reviewer ask plus design-intent evidence already in
+the codebase (the `visibilityLabel(tier)` helper and the
+`# Proxy until the 'visibility:' field lands` comment).
+
+## Context
+
+A reviewer repeatedly asked for a real
+`visibility: visible | advanced | internal` command-frontmatter field instead of
+overloading the integer `tier:` (`0/1/2`) as the visibility proxy
+(`docs/contracts/command-surface-tiers.md`). All 150 command sources under
+`src/domains/<pack>/<verb>/command.md` carry `tier:`; no `visibility:` field
+existed.
+
+Design-intent evidence already in the tree:
+
+- `src/cli/commands/commands.ts` has `visibilityLabel(tier) →
+  {0:'visible',1:'advanced',2:'internal'}` and a `--visible` filter on
+  `VISIBLE_TIERS={0,1}`. The consumer surface already speaks "visibility",
+  derived from the integer.
+- `src/scripts/audit_command_surface.py` carries a standing comment:
+  `# Proxy until the 'visibility:' field lands (6.0.0-C Step 4b)`.
+
+`tier:` was always a backend integer encoding; "visibility" is the correct
+domain concept for a classification surface consumed by humans and LLM routers.
+Keeping the integer as the contract source of truth is a reversed abstraction.
+
+## Decision
+
+**Option A — `visibility:` becomes the classifier source of truth; `tier:`
+stays as a derived, back-compat alias.**
+
+1. Add an optional `visibility:` enum (`visible | advanced | internal`) to the
+   command frontmatter schema. Keep `tier:` (`0/1/2`) in the schema as a
+   back-compat alias.
+2. Backfill `visibility:` on all 150 command sources, derived from the current
+   `tier:` mapping: `0 → visible`, `1 → advanced`, `2 → internal`. Scripted +
+   auditable (one diff, reviewable).
+3. Repoint every reader to **prefer `visibility:`, fall back to `tier:`**:
+   `commands.ts` (ls/explain), `audit_command_surface.py` (per-pack
+   visible-command budget), `build_discovery_manifest.py`.
+4. The discovery manifest is a **published data contract**. To avoid a silent
+   breaking change for external consumers that read the integer `tier` key, the
+   manifest **dual-emits** both `tier` and `visibility` during the deprecation
+   window.
+5. Validation is **backfill-first, then enforce**: once every command carries
+   `visibility:`, the existing tier lint (`lint_command_tiers.py`) is extended
+   to require `visibility:` present + a valid enum + consistent with `tier:`
+   when both are set. No new standalone script; the check rides the existing
+   lint that already runs in CI.
+
+### Rejected alternatives
+
+- **Option B — hard rename `tier:` → `visibility:`, drop `tier:`.** Cleanest
+  end-state but largest blast radius and a hard break of the published manifest
+  contract with no migration window. Deferred; may follow once the deprecation
+  window closes.
+- **Option C — keep `tier:` authoritative, add `visibility:` only as a
+  validate-when-present label (category-field precedent).** Lowest blast radius
+  but fails the phase acceptance criterion ("`visibility:` … is the classifier's
+  source of truth").
+
+## Consequences
+
+- Two fields encode the same concept during the deprecation window → drift risk,
+  mitigated by the lint consistency check (when both present, they must agree)
+  and the scripted single-source backfill.
+- External manifest consumers keep working (dual-emit); migration to read
+  `visibility` can proceed on their own schedule.
+- A future ADR may drop `tier:` (Option B end-state) once readers and the
+  manifest have fully migrated; `tier:` removal is out of scope here.
+
+## References
+
+- `agents/roadmaps/archive/road-to-command-surface-refactor-residuals.md` — Phase 1.
+- `docs/contracts/command-surface-tiers.md` — tier contract this field supersedes
+  as the human-facing source of truth.
+- ADR-048 — the `category:` validate-when-present precedent weighed against here.

package/docs/decisions/ADR-091-split-meta-capability-packs.md

@@ -0,0 +1,113 @@
+---
+adr: 091
+status: accepted
+date: 2026-06-13
+decision: split-meta-capability-packs
+supersedes: —
+superseded_by: —
+phase: command-surface-refactor-residuals
+type: structural
+---
+
+# ADR-091 — Split the `meta` pack into capability-scoped packs (logical re-tag)
+
+## Status
+
+**Accepted** · 2026-06-13. Decided by AI council (anthropic/claude-sonnet-4-5
++ openai/gpt-4o, peer-review, deep) — converged on **logical re-tag, phased,
+memory-first**, and flagged the `council`/`challenge-me`/`grill-me`
+surface-map↔pack ontology mismatch as the real defect to fix.
+
+## Context
+
+`meta` was one capability pack owning the artefacts that maintain the package
+itself: **68 commands** (`pack: meta`) + **58 skills** (`packs: [meta]`),
+`artefact_count: 263`, `size_class: core`, `always_on: true`, `domain: meta`.
+A reviewer and the 6.1.0 roadmap (line 103) repeatedly asked to split it into
+capability-scoped packs; it was punted twice.
+
+Verified mechanism facts that shaped the decision:
+
+- Pack-manifest membership is the frontmatter `packs:` axis
+  (`generate_pack_manifests.py::_collect_flat` → `pid in fm['packs']`); the
+  per-pack visible-command budget groups by the canonical `pack:` owner.
+- Command **slugs are derived from the physical `src/domains/<pack>/<subpath>`
+  path**, independent of the `pack:`/`packs:` tags. A frontmatter re-tag
+  therefore changes ownership **without** changing any slug → no deprecation
+  aliases needed.
+- The discovery resolver's `always_on` seeding is vocabulary-driven
+  (`config/packs.always_on_packs`), not hard-coded to the string `meta`.
+- A **physical** re-parent hits real friction: an orchestrator-root command
+  (`/memory`, `/council`) lives at `src/domains/<pack>/<cluster>/command.md`
+  and cannot sit at a pack root (the activation gate rejects a bare
+  `src/domains/<pack>/command.md`), and `slug_prefix` only resolves for packs
+  homed under `src/domains/`. This is the hidden cost that stalled the split
+  twice.
+- The council's stated "budget violation (8.5×)" premise is **false**: the
+  68 are mostly tier-2 *internal* commands (uncapped); meta's *visible* count
+  is within its budget of 8 (`audit_command_surface.py --budget` → 0 over
+  budget). There is no CI-forcing function; the driver is capability clarity.
+
+## Decision
+
+**Logical re-tag.** Carve three cohesive capabilities out of `meta` by
+re-tagging command frontmatter (`pack:` + `packs:`) and adding the new pack
+ids to `src/config/discovery/packs.yml`. Command files stay physically under
+`src/domains/meta/<cluster>/` (no moves → no slug churn → no aliases); the new
+packs are homed under `src/packs/<id>/` like the other capability packs.
+
+New packs (all `workspaces: [agent-config-maintainer]`, `trust_level_default:
+core`, `always_on: false` — opt-in capabilities surfaced to the maintainer
+workspace):
+
+| Pack | Clusters carved out | size_class |
+|---|---|---|
+| `memory` | `memory`, `chat-history` | small |
+| `analytics` | `analytics`, `cost-report` | small |
+| `product-reasoning` | `council`, `challenge-me`, `grill-me` | medium |
+
+`meta` **stays** the `always_on` platform / agent-admin core pack (agents,
+mode, profile, override, sync-*, optimize, skill(s), condense, context,
+orchestrate, package-reset, set-cost-profile, upstream-contribute,
+review-routing, rule-compliance-audit, agent-handoff, agent-status,
+check-current-md) plus all 58 skills. `review-routing` +
+`rule-compliance-audit` (governance, 2 commands) stay folded into `meta`
+rather than a 2-command pack of their own.
+
+The `knowledge` cluster is intentionally **not** part of `memory`: it is
+already owned by `pack: product-discovery` (`src/domains/product-discovery/
+knowledge/`), not `meta`, so it is out of this split's scope.
+
+`product-reasoning` resolves the ontology bug: `council`/`challenge-me`/
+`grill-me` are classified `product` in `src/flows/surface-map.yaml` but were
+owned by `pack: meta`. They now have an owning capability pack.
+
+### Rejected / deferred
+
+- **Physical re-parent** (moving command dirs under `src/domains/<newpack>/`):
+  deferred — the orchestrator-root + `slug_prefix` friction above makes it a
+  separate, careful change with deprecation-alias cost, and the logical re-tag
+  already satisfies the acceptance criterion. Recorded as a follow-up.
+- **`governance` as its own pack**: rejected — 2 commands do not warrant a
+  budget unit; folded into `meta`.
+- **Big-bang full split** in one pass: rejected per the council's phased
+  guidance; executed memory-first as the proof, then analytics +
+  product-reasoning in the same change once the pipeline was proven green.
+
+## Consequences
+
+- The carved commands move from the `always_on` meta surface to opt-in
+  capability packs scoped to the `agent-config-maintainer` workspace; the
+  maintainer still resolves them via that workspace.
+- `meta`'s `artefact_count` drops; three new `pack.yaml` manifests are
+  generated; the discovery manifest gains the new pack tags.
+- Pack-dependency, budget, and marketplace lints stay green (verified).
+- Physical co-location of the carved commands under their new pack homes
+  remains a future, alias-bearing change.
+
+## References
+
+- `agents/roadmaps/archive/road-to-command-surface-refactor-residuals.md` — Phase 2.
+- `docs/contracts/capability-packs.md` — pack ownership + budget model.
+- `src/flows/surface-map.yaml` — the `product` classification reconciled here.
+- ADR-057 — consolidation-evidence-gate outcomes (physical folding out of scope).

package/docs/decisions/ADR-092-defer-command-tier-alias-removal.md

@@ -0,0 +1,93 @@
+---
+adr: 092
+status: accepted
+date: 2026-06-13
+decision: defer-command-tier-alias-removal
+supersedes: —
+superseded_by: —
+phase: metadata-and-command-surface-leanness
+type: structural
+---
+
+# ADR-092 — Defer the command `tier:` alias removal (close ADR-090 Option B as deferred-with-forcing-function)
+
+## Status
+
+**Accepted** · 2026-06-13. Decided by AI council (anthropic/claude-sonnet-4-5
++ openai/gpt-4o, peer-review, deep) — converged on **defer**, with a
+forcing-function refinement: a defer without a re-open mechanism is
+abandonment in disguise.
+
+## Context
+
+[ADR-090](ADR-090-visibility-command-frontmatter-field.md) made `visibility:`
+the command-classifier source of truth and kept the integer `tier:` (`0/1/2`)
+as a back-compat alias, **deferring** the alias removal ("Option B") "once
+readers and the manifest have fully migrated". This ADR closes that deferred
+question with the Phase-3 investigation evidence.
+
+Investigation findings (`road-to-metadata-and-command-surface-leanness`, Phase 3):
+
+- **Integer-`tier` readers are internal:** `src/cli/commands/commands.ts`
+  (fallback after `visibility`), `src/scripts/audit_command_surface.py`
+  (report column + budget fallback), `src/scripts/build_discovery_manifest.py`
+  (**dual-emits `tier`** into the manifest). `src/cli/python/workspace_hosts.py`
+  uses a semantically unrelated host-inventory tier.
+- **The discovery manifest is a published npm artifact** — `package.json`
+  `files` + `build:discovery` in `prepack` + `prepublishOnly:
+  check_release_includes_discovery.py`. It dual-emits the integer `tier`.
+  **External npm consumers that read the integer key are unknown.**
+- The defer rests on a **Runtime Risk that cannot be ruled out** (a consumer
+  may register/branch on the integer `tier`), not on evidence that such a
+  consumer exists. Maximal caution by default.
+
+## Decision
+
+**Defer Option B.** Keep the `tier:` alias + the manifest dual-emit. Do not
+remove `tier:` now: the published manifest's external consumers are unknown,
+so the "unknown external consumers = hard stop" rule applies.
+
+The defer is a **waypoint, not an end state** — it ships with a re-open
+forcing function so it cannot calcify into permanent debt:
+
+1. **Re-open mechanism (one of):**
+   - **Versioned manifest** — publish `discovery-manifest` v2 *without* `tier`
+     alongside v1; v1 header carries `deprecated: true` + a `sunset` date;
+     after the soak window with no breakage reported, drop `tier`.
+   - **Evidence of zero external integer-`tier` reads** (manifest-fetch
+     telemetry / a documented "tier key deprecated" notice + soak).
+2. **Time-boxed review** — re-evaluate at the next minor-release planning (or
+   within 12 months, whichever is first), escalating to the maintainer with
+   pre-committed options (build the v2 mechanism · proceed · keep deferred).
+3. Execution of the removal itself is carried to
+   `road-to-tier-removal.md` (blocked on the mechanism above), not this ADR.
+
+### Rejected alternatives
+
+- **Accept now — drop `tier:` immediately.** Breaks the published-manifest
+  contract for unknown consumers with no migration window. Hard stop.
+- **Record the defer in the evidence note only, no ADR.** The re-open trigger
+  + escalation is *decision-level* content (who authorised the timeout, under
+  what gate it proceeds), not evidence — it belongs in a decision record. The
+  investigation evidence stays in
+  `agents/settings/contexts/tier-visibility-and-merge-evidence.md`.
+
+## Consequences
+
+- The `tier:` ⇄ `visibility:` dual-field persists during the deferral;
+  drift is mitigated by the `lint_command_tiers.py` consistency check (when
+  both present, they must agree).
+- The removal is **cheaply reversible** if ever executed: restoring the `tier`
+  field is a manifest schema patch (< 1h to publish), far below the rollback
+  cost of a runtime or DB change — but reversibility does not lift the
+  unknown-consumer hard stop.
+- `road-to-tier-removal.md` institutionalises the trigger so the defer stays
+  visible in planning rather than becoming folklore.
+
+## References
+
+- [ADR-090](ADR-090-visibility-command-frontmatter-field.md) — the deferred
+  Option B this ADR closes.
+- `docs/contracts/command-surface-tiers.md` — tier/visibility contract.
+- `agents/settings/contexts/tier-visibility-and-merge-evidence.md` —
+  consumer-investigation evidence.