@event4u/agent-config 5.10.1 → 6.0.0

package/docs/decisions/ADR-054-rule-adherence-decay-triggered-restate.md

@@ -0,0 +1,143 @@
+---
+adr: 054
+status: proposed
+date: 2026-06-05
+decision: rule-adherence-decay-triggered-restate
+supersedes: —
+superseded_by: —
+phase: v6.x · governance-loading reliability
+type: structural
+---
+
+# ADR-054 — Counter "the model ignores ALL rules" with decay-triggered re-state, not per-turn injection
+
+## Status
+
+**Proposed** · 2026-06-05. Drafted for maintainer review (design-first). Routed
+through the AI council (anthropic/claude-sonnet-4-5 + openai/gpt-4o, design
+mode, 2-round debate, 2026-06-05). Round 1 was split (per-turn injection vs.
+decay-triggered + kernel discipline); the round-2 adversarial pass **converged**
+both members against per-turn injection. Two council inaccuracies are corrected
+below under *Context* rather than carried forward.
+
+## Context
+
+**The narrow problem (operator-stated):** Claude *sometimes ignores the whole
+rule/skill layer at once* — the governance block silently drops out for a turn.
+The goal is narrow: **Always-rules respected always; Auto-rules respected when
+their trigger fires; do not force everything** (no blanket injection, no forcing
+Skill invocation).
+
+This is **not** a presence gap (in the default `eager-all` projection the kernel
++ rules are already in context every turn) and **not** a routing-coverage gap
+(`dist/router.json` maps triggers fine). It is an **attention/adherence**
+problem: the content is present but intermittently dismissed.
+
+**Verified mechanism facts:**
+
+- The 10-rule Always-kernel is ~25,590 **characters** (≤ 26k char cap, ~98%
+  full). *Correcting the council's "25k tokens":* that is ≈ 6–7k tokens, not 25k
+  — so the failure is **not** "the kernel fills 60% of the window". It is that a
+  large, invariant, governance-toned block in a long conversation reads as
+  low-information-density boilerplate and gets actively deprioritised as the
+  user's turn-by-turn history grows.
+- `context-hygiene` is an **Auto** rule (trigger-routed, with a `PostToolUse`
+  hook), **not** part of the kernel. *Correcting the council's claim* that it is
+  kernel — but its premise (long-context decay is real and tracked) is exactly
+  why it is the right state source for the trigger below.
+- The 7 shipped hooks are **state-only**; none re-surface or remind.
+- Claude Code hooks can **inject** context (`UserPromptSubmit` / `SessionStart`,
+  stdout or `hookSpecificOutput.additionalContext`, exit 0) but **cannot force**
+  the model to apply a rule or invoke a Skill (verified). The ceiling is real.
+
+## Decision
+
+Adopt a **decay-triggered compact re-state**, not a per-turn injection.
+
+1. **Trigger on decay, reuse existing state — do not fire every turn.** Hook into
+   the freshness signal `context-hygiene` already maintains
+   (`agents/runtime/state/context-hygiene.json`: turn count + the 20/40/60
+   milestones). A `UserPromptSubmit` hook injects the re-state **only** when a
+   decay threshold is crossed (and on `SessionStart`). Per-turn firing is
+   rejected (see *Alternatives*): an identical reminder every turn habituates the
+   model to dismiss it within 3–4 turns and worsens the signal-to-noise ratio
+   that caused the dismissal.
+
+2. **Payload = salience, not content.**
+   - **Always:** a compact roster of the kernel by Iron-Law heading (one line
+     each), not full bodies — the bodies are already projected.
+   - **Auto:** for each rule the *current prompt* matches in `dist/router.json`,
+     a one-line pointer ("in force this turn: `<rule>` — apply it"). Never inject
+     unmatched Auto-rules; never escalate an Auto-rule to always-on.
+   - Never inject skill bodies; never attempt to force a Skill call.
+
+3. **Always unconditional, Auto only on router match.** The re-state re-surfaces
+   the Always layer whenever it fires, and Auto pointers only for prompts that
+   match a trigger — preserving the always/auto contract exactly.
+
+4. **Claude Code first; graceful no-op elsewhere.** The hook writes to stdout /
+   `additionalContext` and exits 0. Tools without a context-injecting hook
+   ignore it; no new contract, no per-tool branching beyond the existing
+   dispatchers (Cursor/Cline already have them).
+
+5. **Honest ceiling, stated in-band.** The re-state counters decay-driven
+   *dismissal*; it cannot *force* adherence. The roster is phrased as a
+   directive the model is told to re-read, not as a guarantee.
+
+6. **Root-cause follow-up (separate gate, not bundled):** the deeper lever is
+   **kernel discipline** — keep the Always-kernel small and high-signal enough
+   that dropping it creates obvious incoherence (the council's "shrink to the
+   load-bearing Iron-Laws" argument). That touches the **contract-locked**
+   `kernel-membership` surface and must run as its own ADR + slow-rollout PR. It
+   is recorded here as the cure; this ADR ships the mitigation.
+
+## Consequences
+
+- **Positive.** Targets the actual failure (decay-driven total dismissal) with
+  the cheapest reversible lever, reusing machinery the package already runs
+  (context-hygiene state, `dist/router.json`). No per-turn token tax; no new
+  always-on surface; the always/auto split is preserved.
+- **Positive.** Delta-based, infrequent injection stays novel (avoids the
+  habituation that sinks per-turn injection).
+- **Negative / accepted.** It cannot guarantee adherence — a model can still
+  ignore an injected reminder. The honest mitigation, not a fix.
+- **Negative / accepted.** Adds a runtime evaluation of `dist/router.json` in the
+  `UserPromptSubmit` path; must stay fast and exit 0 on any error (hooks never
+  block the loop).
+- **Deferred.** The kernel-shrink cure is not executed here.
+
+## Alternatives considered
+
+- **Per-turn salience injection (round-1 minority, then rejected).** Inject the
+  kernel roster + matched-Auto pointers on *every* prompt. Rejected: an invariant
+  per-turn reminder trains the model to filter it as boilerplate within a few
+  turns and adds 500–1000 tokens/turn of governance text on top of an already
+  governance-heavy context — accelerating the very dismissal it tries to cure.
+  "Reliable firing" ≠ "reliable efficacy".
+- **Do nothing / rely on `eager-all` presence.** Rejected: presence is already
+  high; the failure is dismissal, which presence alone does not fix.
+- **Shrink the kernel now, in this ADR.** Deferred, not rejected: it is the
+  root-cause cure but edits a contract-locked surface (`kernel-membership`) and
+  needs its own slow-rollout gate — bundling it here would violate the
+  one-kernel-rule-per-PR discipline.
+
+## Inversion check
+
+This verdict flips if a measurement shows the model ignores a *small,
+decay-triggered* re-state just as readily as the projected block — in which case
+the only remaining lever is kernel-shrink (the follow-up), and the hook is
+dropped as theatre. The cheap way to find out: a trigger-adherence probe
+(does a known-trigger prompt produce rule-consistent behaviour with vs. without
+the re-state) before investing in per-tool rollout.
+
+## References
+
+- `docs/contracts/rule-router.md` — `dist/router.json` trigger→rule mapping the
+  re-state reads.
+- `docs/contracts/kernel-membership.md` — the contract-locked Always-kernel the
+  follow-up cure would touch.
+- `.agent-src/rules/context-hygiene.md` + `scripts/context_hygiene_hook.py` —
+  the freshness/turn-count state the decay trigger reuses.
+- AI council, design mode, 2-round debate, 2026-06-05 (anthropic/claude-sonnet-4-5
+  + openai/gpt-4o) — round-1 split, round-2 convergence on decay-triggered +
+  kernel discipline over per-turn injection.

package/docs/decisions/ADR-055-flow-layer-data-model.md

@@ -0,0 +1,235 @@
+---
+adr: 055
+status: proposed
+date: 2026-06-06
+decision: flow-layer-data-model
+supersedes: —
+superseded_by: —
+phase: v6.1 · product consolidation (Step 8b)
+type: structural
+---
+
+# ADR-055 — The flow-layer data model: a schema + validate-on-load lint, not a live resolver
+
+## Status
+
+**Proposed** · 2026-06-06. Drafted for maintainer review (design-first), as the
+data-model foundation for road-to-6.1.0 Step 8b. Routed through the AI council
+(anthropic/claude-sonnet-4-5 + openai/gpt-4o, design mode, deep) — convergence
+recorded under *Council convergence* below.
+
+## Context
+
+`Profile → Pack → Flow → Command → Skill → Rule` is the layered model the
+6.1.0 consolidation is built around. Four flows were scaffolded as inert stubs
+in 6.0.0-D Step 15b (`src/flows/{discovery,implementation,review,delivery}.yaml`),
+each carrying only `id` / `title` / `summary` / a `commands:` seed lifted from
+the command-classification worksheet `·_flow:` tags. They were "parsed by
+nothing" — documentation, not data.
+
+Step 8b's job is narrow: **make a flow a real, validated artefact** — define the
+schema for the three activation fields (`entry_points`, `default_path`,
+`skills`) and lint that every reference resolves. This is explicitly *not*
+Step 9 ("make the flow the primary view of the command surface"), which the
+prior 6.1 council flagged HIGH-risk and deferred to land last. Step 8b is the
+data-model floor Step 9 stands on.
+
+A prior council round (deliberating whether `process-full` should proceed at
+all now that PR2 merged) raised a hard objection: **you cannot write a flow
+schema before the data model exists**, and "stub file existence ≠ structure
+defined." This ADR answers that objection by *defining and committing to* the
+data model here — not merely writing it down, but binding it to a stated Step 9
+scope so the schema encodes a decided structure, not a guessed one.
+
+**Committed Step 9 scope (the schema is designed for exactly this):** "Primary
+view" means flows become the **first-class navigation surface** — the agent
+surfaces the four flows, lets the user pick an `entry_point`, and presents the
+`default_path` as a *suggested* command sequence with the flow's `skills` as
+context. Step 9 does **not** execute flows as branching workflow graphs (no
+conditional `transitions`, no automated skill invocation). Flows are **curated,
+navigable command lists**, not workflow engines. The three activated fields are
+sufficient for that scope, as this usage sketch shows:
+
+```python
+flow = load_flow("discovery")                 # id/title/summary + 3 fields
+show_menu(flow["entry_points"])               # daily front doors
+chosen = user_pick(flow["entry_points"])
+for cmd in flow["default_path"]:              # suggested sequence (not auto-run)
+    suggest(resolve_command(cmd))
+surface(flow["skills"])                        # contextual help
+```
+
+If Step 9's scope later widens to executable graphs, that is a **schema v2**
+event with a migration plan (see *Consequences*), not a silent in-place change.
+
+**Verified facts (this branch):**
+
+- Skills resolve at `src/skills/<slug>/SKILL.md` (223 skills); commands resolve
+  via `resolve_logical("commands/<ref>.md")` in `src/scripts/_lib/agent_src.py`,
+  which maps a logical command path to its physical backing (top-level stem or
+  `cluster/sub`). Every command + skill referenced by the four populated flows
+  resolves (verified: zero misses).
+- The established schema home is `src/scripts/schemas/` (`pack.schema.json`,
+  Draft-07), validated by `validate_pack_yaml.py` with a **shape-vs-resolution
+  split**: the JSON Schema fixes shape; the Python lint resolves references.
+- The worksheet/flow seeds use future-canonical names (`git-commit`,
+  `git-pr-create`). Per `pack.schema.json`'s own `$comment`, those are pack
+  `slug_prefix` *projections* (the `git` pack with `slug_prefix: git` projects
+  `commit` → `git-commit`) that land with Step 8 — they do **not** resolve in
+  the current layout.
+
+## Decision
+
+1. **Schema fixes shape; the lint enforces referential integrity.** Mirror the
+   `pack.schema.json` + `validate_pack_yaml.py` split. The JSON Schema
+   (`flow.schema.json`, Draft-07) requires `id`, `title`, `summary`,
+   `entry_points`, `default_path`, `skills`; `commands` stays optional
+   (descriptive seed). The schema validates slug/path *shape* only.
+   `lint_flows.py` validates that every `entry_points` / `default_path` /
+   `commands` entry resolves to a real command, every `skills` slug to a real
+   skill, the `id` equals the filename stem, the `id` is in the closed flow set,
+   and all four flows have a file. Errors are **granular and partial** — each
+   unresolved ref is its own line (not a generic "flow invalid"), with a
+   `difflib` "did you mean 'X'?" hint when a near-match exists. The `commands`
+   field stays optional and descriptive (the worksheet seed); Step 9 decides
+   whether to require it, drop it, or keep it as a human-readable index — Step 8b
+   does not force that call.
+
+2. **Schema location follows the repo convention, not the roadmap's literal
+   path.** Every JSON Schema in this repo lives in `src/scripts/schemas/`
+   alongside its validator (`pack.schema.json` + `validate_pack_yaml.py`); none
+   live at `src/schemas/`. Step 8b's prose said `src/schemas/flow.schema.json` —
+   almost certainly a path slip, since that directory holds no schemas. The file
+   lands at `src/scripts/schemas/flow.schema.json` next to `pack.schema.json`.
+   (Deviation noted so the roadmap text is not read as a contradiction.)
+
+3. **The flow set is closed and curated `{discovery, implementation, review,
+   delivery}`.** Enforced by the lint, **not** a schema `enum` — not because
+   enums are "brittle" in the abstract, but for two concrete reasons: (a) the
+   lint gives a readable "id 'x' not in {…}" error instead of a generic
+   schema-enum failure that reads as "malformed YAML"; (b) a developer can author
+   an experimental flow on a local branch without the schema rejecting the file —
+   the lint blocks it at PR time. `agent-admin` is **not** a flow (feedback-6):
+   it is the platform/system surface, not a user-work journey. **Design rule for
+   any future flow:** it must be a user-work journey with (a) distinct entry
+   points, (b) a coherent value stream, and (c) exit conditions. Cross-cutting
+   concerns (debugging, onboarding, config) are platform features or pack
+   surfaces, **not** flows. Adding one is an ADR-gated governance decision that
+   argues it as a *fifth user-work journey*.
+
+4. **Flows reference current LOGICAL command paths** (`pr/create`,
+   `fix/pr-comments`), not future slug-prefix projections (`git-pr-create`).
+   This keeps the validate-on-load gate green today. **This is a real coupling to
+   Step 8, not a trivial follow-up:** when Step 8 lands the pack `slug_prefix`
+   projections, `pr/create` may stop resolving (or resolve elsewhere) and the
+   flows go red. Migration plan: **Step 8's PR includes the one-time rewrite of
+   every flow ref** to its projected slug, and `lint_flows.py` accepts *both* the
+   logical and the projected form during a transition window so in-flight
+   branches still merge. If Step 8 slips, the dual-form acceptance becomes
+   permanent with a deprecation warning on the logical form. The coupling is
+   tracked here, not discovered later.
+
+5. **The four headline flows are the user-work journey discovery →
+   implementation → review → delivery.** Acceptance Criterion 5 of the 6.1
+   roadmap says "the 5 headline flows"; that "5" predates feedback-6 (which
+   demoted `agent-admin` from a 5th flow to the platform surface). The headline
+   count is **four user-work flows**; AC5 is updated to match.
+
+6. **Validation is CI-time in Step 8b; load-time validation is Step 9's
+   responsibility.** Today the flow files are **inert** — nothing in the agent
+   loop loads or executes them — so there is no time-of-check/time-of-use gap to
+   close: the only consumer is CI (`task lint-flows`), and a malformed flow that
+   somehow bypassed CI (emergency merge, lint override) still does nothing at
+   runtime. When Step 9 makes flows **load-bearing**, it MUST add a load-time
+   check at agent startup with an explicit failure mode (fail-safe: refuse to
+   start and name the offending file/field; opt-in graceful-degradation: drop the
+   broken flow with a warning). That load-time contract is called out here as a
+   Step 9 prerequisite so it is not forgotten, but it is **out of scope for
+   Step 8b** precisely because flows are still inert.
+
+## Consequences
+
+- **Positive.** Flows become first-class validated artefacts; a typo in an
+  `entry_point` or a renamed/removed command fails CI instead of rotting
+  silently. The data model Step 9 needs is now decided and encoded, unblocking
+  the higher-risk "primary view" work without committing to it. The
+  shape-vs-resolution split keeps the schema small and the policy in reviewable
+  Python.
+- **Negative / cost.** One new CI lint (`task lint-flows`, ~ms). When Step 8's
+  slug-prefix projections land, the flow refs need a one-time update (Decision 4
+  migration plan) — tracked, not silent.
+- **Rollback scope is *deferred*, not *independent*.** Today reverting Step 8b is
+  trivial (delete schema + lint + restore stubs; nothing depends on them). But
+  the instant Step 9 makes flows load-bearing, the rollback boundary **expands to
+  include both steps** — you can no longer revert 8b without reverting 9. This
+  ADR claims rollback-*deferred*, not rollback-*independent*; the honest cost is
+  stated rather than implied away.
+- **Risk: schema insufficiency discovered in Step 9.** If Step 9 cannot render
+  the primary view with `entry_points` / `default_path` / `skills` (e.g. it turns
+  out to need `transitions` / `exit_conditions` / per-command `skill_bindings`),
+  the schema needs a breaking change. Mitigation: **versioned schema** —
+  `flow.schema.json` is implicitly v1; a v2 ships its own file, and
+  `lint_flows.py` accepts both during a transition while the four flows migrate
+  (est. 4–6 h, carried in Step 9's PR). **Success metric for this ADR: Step 9
+  ships without a schema change.** If it cannot, the v2 path above applies — a
+  budgeted contingency, not a surprise. (Reserved speculative fields were
+  considered and rejected — see *Alternatives*.)
+- **No known external consumers.** The flow files were inert stubs (parsed by
+  nothing); making `entry_points` / `default_path` / `skills` required is a
+  breaking change only for a tool that *reads* the YAML, and there is no such
+  consumer today (no docs generator, IDE plugin, or script parses `src/flows/`).
+  If one appears, it must handle the three required fields.
+- **Neutral.** No runtime behavior change: nothing *executes* or even *loads* a
+  flow yet. The flow files remain inert to the agent loop; only CI now reads
+  them.
+
+## Alternatives considered
+
+- **Schema `enum` for the flow id.** Rejected — hard-locks the set in the
+  schema; growing/renaming a flow would mean editing the schema and the lint.
+  The closed set lives in the lint (one constant) instead.
+- **Resolve future-canonical slugs (`git-commit`) now.** Rejected — those
+  projections do not exist until Step 8's pack `slug_prefix` work; encoding them
+  now would make the gate red against a layout that does not yet exist.
+- **Put the schema at `src/schemas/` (roadmap's literal path).** Rejected —
+  splits the schema home; `pack.schema.json` and every validator expect
+  `src/scripts/schemas/`.
+- **Do Step 8b and Step 9 together.** Rejected — Step 9 (primary-view rewrite of
+  the command surface) is HIGH-risk and was deferred by the prior council; this
+  ADR delivers only the data-model floor.
+- **Reserve speculative workflow fields now** (`transitions`, `exit_conditions`,
+  `skill_bindings`, ignored by the lint). Rejected — unvalidated fields with no
+  current consumer are YAGNI and quietly commit v1 to a *guessed* execution
+  model. The schema-insufficiency risk they hedge is addressed more honestly by
+  the explicit **v2 + transition-window** migration (Decision-scope commitment +
+  *Consequences*), which keeps v1 minimal and surfaces a real schema change as a
+  real change rather than a silently-pre-blessed field.
+
+## Council convergence
+
+Two design-mode rounds (anthropic/claude-sonnet-4-5 + openai/gpt-4o, deep,
+2026-06-06). The first (scope) converged that: (a) the flow schema must encode a
+*decided* data model — "stub existence ≠ structure"; (b) Step 8b is legitimate
+only as the data-model definition, decoupled from Step 9's primary-view rewrite;
+(c) a mega-PR collapsing the remaining deferred steps is rejected. The second
+(this ADR) judged the design **sound but under-honest about risk** and converged
+on six fixes, all integrated above: the CI-time-vs-load-time boundary
+(Decision 6), the rollback-*deferred* framing + schema-versioning contingency +
+success metric (*Consequences*), the explicit Step 8 coupling + migration plan
+(Decision 4), the committed Step 9 scope + usage sketch (*Context*), the
+lint-not-`enum` rationale + future-flow design rule (Decision 3), and granular
+"did you mean?" lint errors (Decision 1). This ADR + the schema + lint is the
+minimal, rollback-**deferred** unit that satisfies the convergence.
+
+## References
+
+- `agents/roadmaps/road-to-6.1.0-product-consolidation.md` — Step 8b, AC5.
+- `src/flows/README.md` — flow-set definition + feedback-6 (`agent-admin` is not
+  a flow).
+- `src/scripts/schemas/flow.schema.json` · `src/scripts/lint_flows.py` — the
+  artefacts this ADR governs.
+- `src/scripts/schemas/pack.schema.json` · `src/scripts/validate_pack_yaml.py` —
+  the shape-vs-resolution pattern mirrored here.
+- `agents/reports/command-classification-6.0.0-d.md` — the `·_flow:` seed tags.
+- ADR-044 (amendment A3) — pack `slug_prefix` projection (the future-canonical
+  command names).

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

@@ -0,0 +1,124 @@
+---
+adr: 056
+status: accepted
+date: 2026-06-06
+decision: unvalidated-video-adapters-disposition
+supersedes: —
+superseded_by: —
+phase: video foundation validation (road-to-video-foundation-validation, Phase 4)
+type: structural
+---
+
+# ADR-056 — Disposition of the five unvalidated AI-video adapters
+
+## Status
+
+**Accepted** · 2026-06-10 (maintainer decision, in-session). Outcome: the
+alternative this draft originally rejected as wasteful — **validate all
+five** — is what the maintainer chose interactively, and it was the right
+call: provider keys were at hand, total validation spend stayed ~$30, and
+the live runs exposed real contract bugs in four adapters (Kling keypair/JWT
+auth, Replicate community-model create route, fal server-side duration
+validation, Higgsfield auth-header/upload/poll shapes — re-read from the
+official higgsfield-js SDK) that mocks could never have caught.
+
+**Disposition: all five validated, all five kept, all five promoted
+`experimental → stable`** (none removed; option A's removal rationale
+dissolved once every adapter actually worked):
+
+| Adapter | Validation | Promotion |
+|---|---|---|
+| `gemini-veo` | 10/10 renders (native audio) | stable (PR #457) |
+| `kling` | 1/1 (keypair/JWT rework) | stable (PR #459) |
+| `sora` | 1/1 (newly wired, OpenAI Videos API, native audio) | stable |
+| `openai-images` | 2/2 (sync adapter; real PNGs) | stable |
+| `higgsfield` | 1/1 image2video (SDK-corrected upload/auth/poll) | stable |
+
+The multiplexers (`fal`, `replicate` — also validated 3 models each, also
+stable) remain the preferred batch path; the per-model adapters are now
+honest, validated direct integrations rather than dead stubs.
+
+Original proposal text below is retained for provenance.
+
+---
+
+## Context
+
+Five adapters ship under `src/scripts/ai-video/adapters/`:
+`gemini-veo`, `higgsfield`, `kling`, `openai-images`, `sora`. All five are:
+
+- `lifecycle: experimental` — structural shape conformant only;
+- **stubs** — `submit`/`poll`/`fetch` each `aiv_die 9 "live … not yet wired"`; only `dry-run` (committed fixture) works;
+- **never validated** — `agents/reference/ai-video/smoke-traces/` does not exist; no adapter has ever round-tripped a real API call.
+
+The AI council flagged this as the foundation risk: downstream roadmaps
+(`road-to-video-provider-multiplexers`, `road-to-music-video-orchestration`)
+proposed shimming or falling back to these adapters — but you cannot shim or
+fall back to code that has never worked. Both members independently raised it;
+one recommended "delete four, validate one." Deletion is destructive and is the
+maintainer's call (per `non-destructive-by-default`), hence this ADR rather than
+an autonomous removal.
+
+The provider strategy also changed the calculus: the multiplexer roadmap
+adopts **fal.ai + Replicate** aggregator adapters, each reaching Kling / Wan2.2 /
+LTX-2 / Veo / Hunyuan through one `model_id`. That makes the per-model
+`kling` / `gemini-veo` / `sora` adapters largely redundant once the
+aggregators land — they would ride the multiplexers instead.
+
+## Decision (proposed — maintainer picks)
+
+Validate one first, then choose the disposition of the other four:
+
+1. **Validate one end-to-end.** Pick the single most stable shipped provider
+   (candidate: `gemini-veo` or `sora`), wire its real `submit/poll/fetch`
+   through the contract-v2 trust-boundary helpers (`aiv_scene_dir`,
+   `aiv_fetch_url`, `aiv_validate_artifact_path`), capture a smoke trace under
+   `agents/reference/ai-video/smoke-traces/`, and promote it `experimental →
+   stable`. This proves the contract before any multiplexer is built.
+
+2. **Disposition of the remaining four — choose one:**
+   - **(A) Remove** the per-model video stubs (`kling`, plus whichever of
+     `gemini-veo`/`sora` was not validated) once the fal/Replicate multiplexers
+     reach the same models. Keep `openai-images` (image path, still used by the
+     image render step) and the one validated video adapter. *Recommended* —
+     least dead code, no shim-to-nothing.
+   - **(B) Keep as thin reference shims** — retain one stub as a documented
+     "minimal adapter" example, delete the rest.
+   - **(C) Keep all, relabel** — leave the stubs in place, clearly marked
+     `experimental · unwired`, and let the multiplexers supersede them over time.
+
+**Recommendation:** validate `gemini-veo` (native-audio, relevant to music
+video), then path **(A)** — remove `kling` and `sora` stubs once the fal
+multiplexer reaches them, keep `openai-images` + validated `gemini-veo`.
+`higgsfield` is the only one with a distinct capability not covered by the
+aggregators (the `speak` lip-sync hook); keep it pending the lip-sync adapter
+decision in the music-video roadmap.
+
+No adapter is removed without explicit maintainer sign-off in this ADR
+(status → accepted with the chosen path).
+
+## Consequences
+
+- **If accepted:** the suite stops carrying four never-run code paths as
+  "foundation"; the multiplexers become the single video path; `higgsfield`'s
+  lip-sync hook is the one first-party capability retained.
+- **Trade-off:** removing per-model adapters loses the (theoretical) option of a
+  direct provider integration without an aggregator key. Mitigated — the
+  aggregators reach the same models, and ComfyUI (deferred) covers the
+  local-free path.
+- **Until decided:** the stubs stay; the multiplexer roadmap must NOT shim to
+  them (they would `aiv_die 9`).
+
+## Alternatives considered
+
+- **Validate all five before deciding** — rejected: wasteful given the
+  aggregators supersede most of them; validate one to prove the contract, then
+  decide.
+- **Autonomous deletion of four** — rejected: destructive, maintainer's call.
+
+## 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.
+- `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-057-consolidation-evidence-gate-outcomes.md

@@ -0,0 +1,135 @@
+---
+adr: 057
+status: proposed
+date: 2026-06-06
+decision: consolidation-evidence-gate-outcomes
+supersedes: —
+superseded_by: —
+phase: consolidation evidence-gates (road-to-6.2.0-consolidation-evidence-gates)
+type: structural
+---
+
+# ADR-057 — Consolidation evidence-gate outcomes (6.2.0)
+
+## Status
+
+**Proposed** · 2026-06-06. Records the outcome of running every gate in
+`road-to-6.2.0-consolidation-evidence-gates` (the council-deferred remainder of
+6.1.0). The roadmap is an **evidence-gate** plan: each step ships only behind a
+named gate (inline-invoke proof, debug-bypass proof, grep-zero-usage, usage
+signal). This ADR is the per-step decision provenance — the gate-checks were
+run, the evidence captured, and the verdicts recorded here before any change
+landed (Acceptance Criterion #3 of the roadmap).
+
+Design context routed through the AI council
+(anthropic/claude-sonnet-4-5 + openai/gpt-4o, design mode, 2 rounds +
+peer-review, 2026-06-06). Both members converged on a conservative reading:
+most gates are **not met**, and the package's existing safety posture argues
+against the aggressive structural changes this cycle. The destructive
+conversions are deferred or declined; the safe evidence/documentation slice
+ships.
+
+## Context
+
+6.1.0 shipped the low-risk consolidation slice (Flows primary *view* +
+recorded decisions) and deferred four items the council gated on real
+capability/safety proof or usage evidence. Running those gates this session
+produced the following verified evidence:
+
+- **Skill description-match is the package's primary selector** — all ~220
+  skills are reached by `description:` match (`src/scripts/skill_tools/
+  score_skill_relevance.py::rank`). The "inline-invoke path" a converted
+  command must satisfy is the same mechanism every skill already uses.
+- **Projection suppression is binary per slug.** `generate_claude_commands()`
+  skips a command slug when a same-named skill exists
+  (`if slug in skill_names: continue`). A command and a skill **cannot coexist
+  at the same slug** — creating `src/skills/<slug>/SKILL.md` silently removes
+  the command projection. There is no "coexist as fallback" option at one slug.
+- **The real `replaces:` alias set** is only: `git-commit`←`commit`,
+  `git-commit-in-chunks`←`commit-in-chunks`,`commit:in-chunks`,
+  `git-pr-create`←`create-pr`,
+  `git-pr-create-description-only`←`create-pr-description-only`,`create-pr:description-only`.
+  The roadmap's Step 8a named examples (`fix/pr-bot-comments`,
+  `fix/pr-developer-comments`) **never existed as aliases** — a roadmap
+  authoring error, corrected here and in the roadmap.
+- **grep-zero-usage FAILS** for every alias (non-zero):
+
+  ```bash
+  # source-only scope (excludes definitions, archive, generated trees)
+  grep -rIl --include='*.md' --include='*.py' --include='*.yml' --include='*.yaml' \
+    -- "<alias>" . | grep -vE 'agents/roadmaps/archive|/dist/|/\.agent-src/|/\.augment/|/\.claude/|/\.cursor/|/\.clinerules|src/domains/git/'
+  ```
+
+  `commit-in-chunks` → 17 files · `commit:in-chunks` → 22 · `create-pr:description-only`
+  → 17 · `create-pr-description-only` → 2. Several are live invocation forms,
+  not dead flat names.
+- **No usage telemetry exists.** No analytics JSONL is present;
+  `docs/command-flows.md` is referenced only by its own generator, the
+  Taskfile, and roadmaps — **zero** external/issue references. The 5b and 9b
+  usage signals have not flipped.
+
+## Decision
+
+| Step | Gate | Evidence | Verdict |
+|---|---|---|---|
+| **7a** convert `skill/preview` + `skills/discover` to skills | inline-invoke proof before deletion | Mechanism proven (test added); but slug-collision suppression + untested cross-provider description-match | **DEFER conversion.** Ship the inline-invoke proof; keep the commands. |
+| **7b** convert `review-routing` + `rule-compliance-audit` | guaranteed debug-bypass independent of the routing pipeline | The command form **is** the bypass; a skill reached only by description-match cannot debug a broken description-matcher (circular dependency) | **DECLINE conversion (KEEP command-only).** Document the intentional exception. |
+| **8a** drop grace-elapsed 6.0.0-D aliases | grep-zero-usage → drop; any hit → keep stub | grep strongly NON-ZERO (17–22 files) | **KEEP all aliases as stubs.** Record evidence + alias-lifecycle policy. |
+| **5b** fold `feature/explore`+`feature/roadmap` into `feature-plan` modes | evidence users treat them as modes of one goal | No usage signal; 6.1.0 KEEP-separate stands | **KEEP separate.** Not reopened. |
+| **9b** make Flows the runtime primary surface | signal that users navigate by the flow doc | Zero external doc references; no telemetry | **DEFER runtime change.** Doc stays the observation vehicle. |
+
+### Alias-lifecycle policy (Step 8a)
+
+Aliases declared via `replaces:` fall into two classes:
+
+- **Permanent migration stubs** — aliases for command names that existed before
+  the 6.0.0-D restructure (`commit`, `create-pr`, and their `:`-cluster forms).
+  These are a backward-compat contract for internal CI scripts and muscle
+  memory; they are **kept indefinitely** and shrink only on a future
+  grep-zero-usage pass.
+- **Deprecated stubs** — aliases for commands shipped 6.0.0+ would carry a
+  grace window and drop after grep-zero-usage for two consecutive releases.
+  None exist today.
+
+Re-run trigger: re-audit in a later cycle; if a previously non-zero alias drops
+to grep-zero (with a hardened exclusion set and a manual spot-check of live vs.
+stale hits), reopen it for deprecation. "Permanent" is therefore
+evidence-reversible, not absolute.
+
+## Consequences
+
+- **No capability lost.** Every command in scope still resolves: 7a/7b keep
+  their command form; 8a keeps every alias; 5b/9b are unchanged.
+- **The roadmap stays active.** 7a-conversion and 9b-runtime remain open,
+  blocked on future evidence (cross-provider validation / usage telemetry).
+  7b-conversion is cancelled (decided, not pending). 8a and 5b are done.
+- **Rollback path** — every change in the shipping PR is documentation, one
+  test, and roadmap/ADR edits; revert is a single `git revert` of the PR with
+  no runtime impact.
+- **Follow-up (not this cycle, council-suggested):** passive
+  flow-navigation telemetry would unblock both 7a (production reachability
+  baseline) and 9b (flow-doc usage signal). Deferred as out-of-scope here —
+  it is its own instrumentation roadmap, not an evidence-gate outcome.
+
+## Alternatives considered
+
+- **Ship the 7a conversion now** (delete commands, create skills). Rejected:
+  the council converged on DEFER — slug-collision suppression turns a partial
+  apply into a silent "source exists but does not project" state, and the
+  cross-provider description-match is unvalidated for a maintainer-only tool
+  with no telemetry to detect regression.
+- **Convert 7b with a CLI hatch** (`python3 scripts/...` as the bypass).
+  Rejected: adds a second invocation surface for the same tool when the
+  existing command form already satisfies the gate at zero new surface.
+- **Drop the grep-non-zero aliases anyway** (treat hits as stale). Rejected:
+  the gate's own rule is "any hit → keep as stub"; overriding it would be
+  exactly the silent-budget-bypass the gate exists to prevent.
+
+## References
+
+- `agents/roadmaps/archive/road-to-6.2.0-consolidation-evidence-gates.md` — the gated plan (archived 2026-06-06; deferred items 7a/9b kept in-archive per council deferred-resolution).
+- `docs/contracts/command-clusters.md` — cluster/alias model.
+- `docs/contracts/skill-dry-run.md`, `docs/contracts/skill-discovery.md` — the
+  contracts `skill/preview` + `skills/discover` implement.
+- `tests/test_inline_invoke_reachability.py` — the Step 7a inline-invoke proof.
+- ADR-056 — sibling council-informed, design-first disposition (video adapters).