@event4u/agent-config 5.10.1 → 6.1.0

package/docs/decisions/ADR-053-agents-namespace-dual-role-resolution.md

@@ -0,0 +1,132 @@
+---
+adr: 053
+status: accepted
+date: 2026-06-05
+decision: agents-namespace-dual-role-resolution
+supersedes: —
+superseded_by: —
+phase: v6.0.x · workspace structural cleanup · Phase 2 (Step 4 design gate)
+type: structural
+---
+
+# ADR-053 — The maintainer `agents/` namespace is the dogfooded consumer convention (collision resolution)
+
+## Status
+
+**Accepted** · 2026-06-05. Resolves the deferred Step-4 design gate of the
+6.0.x workspace-structural-cleanup roadmap, closing the `agents/`-namespace
+remainder that [`ADR-050`](ADR-050-workspace-vs-package-root-boundary.md)
+explicitly deferred.
+Routed through the AI council (anthropic/claude-sonnet-4-5 + openai/gpt-4o,
+design mode, 2-round debate, 2026-06-05). Both members converged independently
+on Option B in round 1; the round-2 adversarial pass steel-manned Option A and is
+recorded under *Alternatives considered* with the reason it does not hold.
+
+## Context
+
+ADR-050 kept the maintainer `agents/` workspace at repo root ("workspace tooling
++ namespace") and deferred two coupled questions to this roadmap:
+
+1. Resolve the **maintainer-vs-consumer `agents/` collision** — the directory
+   `agents/` in this repo is simultaneously the maintainer workspace AND the
+   consumer-facing convention the package ships.
+2. Resolve the **settings-loader self-reference** — `agents/settings/.agent-settings.yml`
+   is read at runtime by `src/scripts/_lib/agent_settings.py`, so a naive move of
+   the workspace could brick the loader mid-move.
+
+Three facts, verified against the codebase on 2026-06-05, define the decision space:
+
+- **`agents/` is one name with two roles by design.** This repo's `agents/`
+  (`roadmaps/`, `settings/`, `runtime/`, `decisions/`) is a *compliant instance*
+  of the `agents/` tree the package installs into consumer projects
+  (`agents/settings/`, `agents/overrides/`, `agents/roadmaps/`, `.event4u-bridge.yml`).
+  The maintainer workspace and the shipped convention are the same directory name
+  because the package dogfoods its own convention.
+- **The loader is coupled to the convention, not to a maintainer-special path.**
+  `agent_settings.py` keys on `LOCAL_PROJECT_SUBDIR = ("agents", "settings")`,
+  anchors on a directory named `agents/` carrying any of `_AGENTS_DIR_MARKERS`
+  (`roadmaps/`, `settings/.ai-council.yml`, `roadmaps-progress.md`,
+  `.event4u-bridge.yml`), and defaults `MODULES_DEFAULTS["agent_folder"] = "agents"`.
+  These are *convention* identifiers — the same strings a consumer project carries.
+- **Reference scale.** 1106 tracked files outside `agents/` and `internal/`
+  reference `agents/` (~511 `src/`, ~260 generated `.agent-src/`, ~220 `docs/`,
+  ~93 `tests/`). The majority describe the *consumer convention* (templates,
+  generators, skills, docs), not this repo's workspace.
+
+## Decision
+
+1. **Keep `agents/` at repo root. The "collision" is conceptual, not structural,
+   and is resolved by naming the dual role — not by moving the directory.** The
+   maintainer workspace *is* a dogfooded instance of the shipped `agents/`
+   convention; that overlap is intentional and is the forcing function that keeps
+   the convention usable. There is nothing to physically separate.
+
+2. **Add an explicit, reviewable marker.** A tracked
+   [`agents/.maintainer-workspace.md`](../../agents/.maintainer-workspace.md)
+   names the dual role at the directory itself, so a reviewer encountering the
+   overlap sees the intent in place rather than inferring a mistake.
+
+3. **The loader needs no structural change; its relocation-safety is locked by a
+   pre-flight test.** `agent_settings.py` already resolves the project root from
+   `AGENT_CONFIG_PROJECT_ROOT` / `--root` / an anchor walk / `.git`, and reads
+   settings via a cascade. A regression test
+   (`tests/test_agent_settings_relocation_resilience.py`) proves the loader
+   resolves a settings file at an arbitrary relocated root with the default
+   location absent, and degrades to defaults (never bricks) when the file is gone.
+
+4. **No mass ref repoint.** Because the directory name does not change, the ~1106
+   `agents/` references stay valid. Step 6's "execute the disposition" reduces to
+   landing the marker + ADR + loader test; the full path-audit surface is
+   unchanged by this decision.
+
+## Consequences
+
+- **Positive.** The collision is resolved at the lowest defensible blast radius:
+  zero ref churn, zero loader fork, dogfooding integrity preserved, and the dual
+  role is now explicit rather than tribal knowledge.
+- **Positive.** Consistent with ADR-050 (which already placed `agents/` at root)
+  and with the package's "dogfood the convention" posture.
+- **Negative / accepted.** A reviewer must understand the dual role; the marker
+  file and this ADR are the mitigation. New contributors are pointed at both.
+- **Negative / accepted.** The maintainer workspace can never diverge in *name*
+  from the consumer convention without forking the loader — which is the point:
+  the constraint keeps the shipped convention honest.
+
+## Alternatives considered
+
+- **Option A — rename the maintainer workspace (`agents/` → `.agents/` /
+  `internal/agents/`).** Steel-manned in the round-2 debate as breaking a
+  "circular dogfooding" dependency and claimed to need only ~47 maintainer-tooling
+  ref changes with "no loader change". **Rejected** because the claim is
+  self-refuting: `agents/settings/` *is* the convention path the loader hardcodes
+  (`LOCAL_PROJECT_SUBDIR`), so moving the maintainer settings either (a) requires
+  dual-path loader logic ("maintainer ⇒ `.agents/`, consumer ⇒ `agents/`") — which
+  both members rejected in round 1 as strictly worse — or (b) leaves
+  `agents/settings/` in place, which does not resolve the collision it set out to
+  fix. Renaming a directory does not resolve a clash between that directory and a
+  *shipped convention of the same name*.
+- **Option C — relocate `agents/` contents to typed root homes
+  (`roadmaps/`, `settings/`, `runtime/`).** Rejected: removes the `agents/`
+  umbrella, breaks the loader anchor and the dogfooded convention, and forces a
+  doc/template rewrite for the largest blast radius of the three.
+
+## Inversion check
+
+This verdict flips only if external consumer projects are shown to organize their
+`agents/` tree identically to this maintainer workspace (project ADRs in
+`agents/decisions/`, runtime logs in `agents/runtime/`) — which would make the
+dual role convention-native rather than maintainer-specific and *strengthen* B —
+**or** if a consumer integration is shown to require a maintainer-distinct
+directory name, which would reopen A. Absent either, B stands.
+
+## References
+
+- [`ADR-050`](ADR-050-workspace-vs-package-root-boundary.md) — kept `agents/` at
+  root and deferred this collision + loader self-reference to here.
+- [`ADR-020`](ADR-020-global-only-consumer-scope.md) — the
+  `.event4u-bridge.yml` consumer anchor that the loader keys on.
+- [`agents/.maintainer-workspace.md`](../../agents/.maintainer-workspace.md) — the
+  explicit dual-role marker landed by this decision.
+- AI council, design mode, 2-round debate, 2026-06-05 (anthropic/claude-sonnet-4-5
+  + openai/gpt-4o) — round-1 convergence on Option B; round-2 adversarial pass
+  recorded above.

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.