@event4u/agent-config 9.7.0 → 9.9.0

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

@@ -1,132 +0,0 @@
----
-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

@@ -1,143 +0,0 @@
----
-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

@@ -1,235 +0,0 @@
----
-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

@@ -1,124 +0,0 @@
----
-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/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.