@event4u/agent-config 5.10.1 → 6.1.0

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).

package/docs/decisions/ADR-058-condensed-output-relocation-to-dist.md

@@ -0,0 +1,94 @@
+---
+adr: 058
+status: accepted
+date: 2026-06-06
+decision: condensed-output-relocation-to-dist
+supersedes: —
+superseded_by: —
+phase: v6.2.x · workspace structural cleanup follow-up
+type: structural
+---
+
+# ADR-058 — Relocate the condensed output tree to `dist/agent-src/`
+
+## Status
+
+**Accepted** · 2026-06-06. Follow-up to [`ADR-051`](ADR-051-uncondensed-source-container-relocation.md)
+(uncondensed source container → `src/agent-src/`) and refines the root inventory
+of [`ADR-050`](ADR-050-workspace-vs-package-root-boundary.md). Routed through the
+AI council (anthropic/claude-sonnet-4-5 + openai/gpt-4o, design mode, 2026-06-06,
+2 rounds).
+
+## Context
+
+After the 6.0.x cleanup, two similarly named trees coexisted:
+
+- `src/agent-src/` — the **uncondensed source container** (ADR-051).
+- `.agent-src/` at the repo root — the **condensed output** (729 tracked
+  files), written by `condense.py`, shipped via npm `files[]`, consumed by the
+  `.augment/` projection, the Claude plugin marketplace, and the IDE-tool
+  symlink projections.
+
+The namespace collision made the root tree read as a migration leftover, and
+the maintainer asked for the root to be cleaned. ADR-051 had deliberately left
+the condensed output path untouched (its correctness gate was a byte-identical
+output snapshot), so the relocation needed its own decision.
+
+## Decision
+
+Relocate the condensed output from `.agent-src/` (repo root) to
+**`dist/agent-src/`**, tracked in git (carve-out `!/dist/agent-src/` next to the
+existing `!/dist/router.json`). Rationale, per the council convergence:
+
+- `dist/` is the established home for generated artifacts (compiled TS,
+  `router.json`, discovery manifests) and is already shipped via npm `files[]`.
+- Placing generated output under `src/` (Option C) was unanimously rejected —
+  it violates ADR-050's hand-authored-source trust boundary.
+- Keeping the tree tracked (vs. generate-on-publish, Option D) preserves the
+  git-consumed surfaces: the Claude plugin marketplace resolves
+  `./dist/agent-src/skills/<name>` from the cloned repo, and CI hash gates
+  keep verifying source↔output sync.
+- `package.json` `files[]` drops the `.agent-src/` entry; `dist/` already
+  ships, so the npm tarball keeps carrying the condensed tree.
+
+The council's named #1 failure mode — external consumers with hard-coded
+`.agent-src/` paths breaking on the cutover — is accepted: consumers are
+internal projects, the path change ships as a breaking change in
+`BREAKING_CHANGES.md`, and `condense.py` keeps stripping the legacy
+`.agent-src/` prefix defensively in `load_context` values.
+
+## Consequences
+
+- The repo root no longer carries a generated dot-tree; `src/agent-src/`
+  (source) and `dist/agent-src/` (output) are now visually and semantically
+  paired.
+- ~123 code/config files and ~143 live docs were repointed mechanically;
+  historical ADRs, archived roadmaps, and evidence snapshots keep the old
+  paths (they record past states).
+- Anything that wipes `dist/` wholesale would now delete a tracked tree —
+  guarded by the `.gitignore` carve-out structure (`/dist/*` with explicit
+  re-includes) and by CI's condensation/sync gates failing on a missing tree.
+- The `.augment/`, `.claude/`, `.cursor/` projections and the plugin
+  marketplace regenerate against the new location via `task sync` /
+  `task generate-tools`.
+
+## Alternatives considered
+
+- **Keep at root, document (Option A).** Rejected: the maintainer explicitly
+  wants the root cleaned; documentation alone does not remove the recurring
+  source-vs-output confusion.
+- **Move under `src/` (Option C).** Unanimously rejected by the council —
+  generated output inside the hand-authored source tier.
+- **Untrack + generate on publish (Option D / D-hybrid).** Rejected for now:
+  breaks git-consumed surfaces (plugin marketplace, clone-based installs) and
+  removes review diffs of condensed rules. Can be revisited once all consumer
+  paths run through the npm tarball.
+- **Rename in place, e.g. `.agent-dist/` (council Option E).** Solves the
+  namespace collision but keeps a generated dot-tree at the root — the
+  maintainer's stated complaint.
+
+## References
+
+- [`ADR-050`](ADR-050-workspace-vs-package-root-boundary.md) — workspace-vs-package trust boundary.
+- [`ADR-051`](ADR-051-uncondensed-source-container-relocation.md) — uncondensed source container move.
+- AI council, design mode, 2026-06-06 (anthropic/claude-sonnet-4-5 + openai/gpt-4o) — converged on Option B (`dist/agent-src/`) with tracked carve-out and breaking-change disclosure.

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

@@ -0,0 +1,161 @@
+---
+adr: 059
+status: accepted
+date: 2026-06-07
+decision: render-resume-filesystem-as-state
+supersedes: —
+superseded_by: —
+phase: video deferred design (road-to-video-deferred-design, Phase 1)
+type: structural
+---
+
+# ADR-059 — Resume-from-last-green-artifact: filesystem-as-state, no checkpoint file
+
+## Status
+
+**Accepted** · 2026-06-07. Design converged via two-round AI-council debate
+(anthropic/claude-sonnet-4-5 + openai/gpt-4o, design mode + peer review,
+2026-06-07). Both members independently converged on the same verdict in
+round 2; no tie-break round needed. Implementation in the same roadmap phase
+follows this design.
+
+## Context
+
+The `/video:from-song` and `/video:from-script` pipelines run expensive,
+multi-scene paid renders. A mid-batch failure (rate-limit 429, content-policy
+refusal, network drop, SIGINT) must not force re-paying for already-finished
+scenes. The command prose already promised "re-running resumes from the
+completed scenes (one project per invocation)" — but the state schema,
+invalidation rule, rollback semantics, and cleanup policy were never designed.
+A prior council round (2026-06-06) gated the implementation on exactly that
+design, with the meta-warning: *"don't build a skill suite as if it were a
+runtime framework."*
+
+Options on the table: (a) filesystem-as-state — a scene is "green" iff its
+directory holds a validated final artifact and no `error.json`; (b) a central
+schema-versioned `<project>/checkpoint.json`; (c) per-scene sentinel files
+plus a derived summary.
+
+## Decision
+
+**Filesystem-as-state with per-scene sentinels (option a refined by c). No
+central `checkpoint.json`. No job reattachment. No rollback machinery. No
+TTL cleanup.**
+
+### 1. State schema — the scene directory IS the state
+
+```
+<project>/scenes/<id>/
+  prompt.json     # the scene's render input (already exists) — hash source
+  final.mp4       # existence + validation = the "green" marker
+  error.json      # existence = failed (adapter error contract, already exists)
+  cost.json       # {"charged_usd": …, "adapter": "…", "model": "…"} — spend record
+```
+
+- **No `done` sentinel** — a validated `final.mp4` (or the adapter-emitted
+  clip name recorded in `prompt.json`) is the done marker.
+- **No `job_id` sentinel** — job reattachment is out of scope (below).
+- Any JSON the pipeline writes is written **atomically**: `jq … > tmp &&
+  mv tmp target`. A crash mid-write can never half-corrupt state.
+- All paths the resume scan consumes go through
+  `aiv_validate_artifact_path` (trust boundary v2) — a hostile or corrupted
+  scene dir cannot redirect the scan outside the project.
+
+### 2. Resume validity — input-hash equality, single source of truth
+
+A completed scene is **reusable** iff ALL of:
+
+1. `scenes/<id>/final.mp4` exists and passes artifact validation;
+2. no `scenes/<id>/error.json` is present;
+3. the SHA-256 of the scene's **current** render input (canonicalized
+   `prompt.json`: prompt blocks + ref-image content hashes + duration +
+   aspect + seed + provider id + model id + adapter-contract version)
+   equals the hash stored at render time (`prompt.json` carries
+   `input_sha256`).
+
+Anything else — prompt edited, script re-derived, provider/model switched,
+contract version bumped, vocal map re-signed, file hand-tampered — fails the
+hash equality and the scene re-renders. One rule covers the whole
+invalidation surface instead of an enumerated (and forever-incomplete)
+trigger list.
+
+### 3. Rollback — deletion, not machinery
+
+"Rollback" is the operator deleting state: `rm -rf <project>/scenes/3/` →
+the next run re-renders scene 3. Full reset = delete the project dir. The
+pipeline never auto-deletes a rendered artifact; partial spend stays visible
+in the per-scene `cost.json` and is summed in the run report
+(`spent so far: $X.YZ across N green scenes`).
+
+### 4. Cleanup — explicit, never ambient
+
+No TTL, no cron, no daemon (would violate the shell-first constraint). An
+explicit `--clean` flag on the pipeline commands removes failed-scene
+residue (`error.json`, partial downloads) before the run; the operator
+deletes whole projects manually. Disk usage is surfaced in the report when a
+project exceeds 2 GiB.
+
+### 5. Job reattachment — rejected (negative ROI)
+
+`poll`/`fetch` stay stateless per adapter-contract v2. An unfetched
+submitted job is simply re-submitted on resume. The council's cost/benefit
+analysis: the dominant failure modes (rate-limit, content-policy refusal)
+leave nothing to reattach; accidental-SIGINT reattach is an edge case that
+does not justify persisted job ids, their staleness window (providers purge
+jobs), or the widened trust surface.
+
+### 6. Kill-switch criteria — rated more important than resume
+
+The batch loop enforces, per scene: **max 1 auto-retry** on a transient
+failure (and only when `error.json` says `retryable: true` — and even then
+the orchestrator surfaces the retry rather than looping silently); a
+content-policy refusal halts the batch (never skip-and-continue past a
+policy signal); the summed `cost.json` spend is checked against
+`--max-spend-usd` before **every** live submit, not only at the upfront
+gate.
+
+### Meta-verdict (the question 5 answer)
+
+A persistent checkpoint *file* is *not* justified. Idempotent commands +
+filesystem-as-state + the existing one-batch-confirmation flow survive all
+four stress scenarios (mid-batch crash, operator hand-edit of one scene,
+provider/model switch between runs, script change between runs) with less
+code, fewer trust-boundary entries, and no schema-versioning burden. This is
+the "skill suite, not a runtime framework" answer.
+
+## Consequences
+
+- `from-song`/`from-script` Step "render scenes" gains a deterministic
+  resume scan (`resume-scan.sh`) instead of prose; the scan emits
+  per-scene `green | stale (hash mismatch) | failed | missing` and the
+  reasons.
+- `prompt.json` gains the `input_sha256` field at render time (additive).
+- `cost.json` becomes the per-scene spend record consumed by the report and
+  the mid-batch `--max-spend-usd` re-check.
+- No migration: projects without `input_sha256` simply re-render (safe
+  default — never reuse unverifiable state).
+
+## Alternatives considered
+
+- **Central `checkpoint.json` (option b)** — rejected: schema-versioning
+  burden, non-atomic multi-scene writes, a second source of truth that can
+  contradict the filesystem, wider trust surface (scene-id paths read from a
+  file), and no capability the sentinel design lacks.
+- **Enumerated invalidation triggers** — rejected: forever-incomplete
+  (adapter bug fixes, provider-side deletions, hand-edits); replaced by
+  input-hash equality.
+- **TTL cleanup** — rejected: needs a daemon/cron or per-run timestamp
+  sweeps; violates shell-first.
+- **Job reattachment via stored job_id** — rejected for MVP (negative ROI,
+  see § 5); revisit only with evidence of real SIGINT-resume demand.
+
+## References
+
+- Council artefact: two-round debate 2026-06-07 (members above), design
+  mode, peer review on — convergence summarized in this ADR per
+  `no-roadmap-references` (no session-file links).
+- `src/scripts/ai-video/lib/adapter-contract.md` — v2 trust boundary +
+  error contract this design builds on.
+- Roadmap: road-to-video-deferred-design, Phase 1 (transient layer —
+  not path-linked per `no-roadmap-references`).
+- ADR-056 — adapter disposition context (validation-first strategy).

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

@@ -0,0 +1,154 @@
+---
+adr: 060
+status: accepted
+date: 2026-06-07
+decision: comfyui-sandbox-model
+supersedes: —
+superseded_by: —
+phase: video deferred design (road-to-video-deferred-design, Phase 2)
+type: structural
+---
+
+# ADR-060 — ComfyUI local adapter: container-primary sandbox, pinned nodes, shipped templates only
+
+## Status
+
+**Accepted** · 2026-06-07. Design converged via two-round AI-council debate
+(anthropic/claude-sonnet-4-5 + openai/gpt-4o, design mode + peer review,
+2026-06-07): container-primary isolation with a remote escape hatch, hard
+pinned-node allowlist, package-shipped workflow templates only. The one
+divergence (soft-warn vs hard-refuse on unpinned nodes) resolved to
+**hard-refuse** — any escape hatch defeats the threat model. The adapter
+ships only after this design.
+
+## Context
+
+A local ComfyUI adapter is the local-free render path for GPU users
+(Wan2.2 TI2V-5B, Apache-2.0, as default template; LTX-2 for audio-sync).
+The prior council round (2026-06-06) ruled ComfyUI *"a hard no until
+sandboxed"*: custom nodes are arbitrary Python fetched from the internet, a
+workflow JSON can reference any node, and a stock ComfyUI server has full
+host-filesystem access. This package is a shell-first skill suite — it can
+*require* and *verify* a posture, but cannot enforce kernel-level isolation
+from a shell adapter. The design must name the smallest enforceable surface
+and the residual risk.
+
+## Decision
+
+### 1. Isolation — container-primary, remote escape hatch (hybrid a + d)
+
+- **Default (the only documented install path): containerized ComfyUI**
+  (Docker/Podman, NVIDIA container toolkit for CUDA):
+  - read-only image; `--cap-drop ALL --cap-add SYS_NICE` (GPU scheduling
+    needs SYS_NICE; nothing else is granted);
+  - **no host mounts** except two explicit volumes: models (read-only) and
+    a per-project artifacts volume (the only writable surface);
+  - `--network none` at generation time; `COMFYUI_ALLOW_NETWORK=true` is
+    the visible opt-in for model-download sessions ("download once, then
+    air-gap"). No egress allowlist in this ADR — domain allowlists for
+    model hosts are unenforceable false precision from a shell suite; the
+    network-off default is the policy lever.
+- **Remote escape hatch:** the adapter MAY target an operator-run ComfyUI
+  endpoint (`<endpoint>` in `agents/.ai-video.xml`). The package takes
+  **no responsibility for isolating a remote endpoint** — that posture is
+  the operator's, and the config requires the explicit marker
+  `<unsandboxed>accepted</unsandboxed>` for any endpoint the adapter
+  cannot verify as the shipped container. Refuse-and-surface otherwise.
+- **macOS:** no CUDA → the container path is **reference-only on macOS**
+  (domain-adoption-policy Gate 3 wording); the remote escape hatch is the
+  macOS path.
+
+### 2. Custom nodes — pinned allowlist, hard-refuse
+
+- The package ships `scripts/ai-video/lib/comfyui-nodes.allowlist.json`:
+  every entry pins **repo URL + git commit SHA** and carries a
+  `risk_tier: low|medium|high` field driving audit cadence (high =
+  monthly, low = quarterly review).
+- A workflow referencing a node outside the allowlist is **hard-refused**
+  (exit 7, named node). There is **no** `--allow-unaudited-nodes` flag and
+  no soft-warn mode — an escape hatch defeats the threat model (council
+  round 2, explicit convergence).
+- Kill-switch criteria: a node with >2 CVSS-≥7 CVEs in 90 days is removed
+  from the allowlist and dependent templates marked deprecated; a
+  demonstrated container escape against the documented constraint set
+  yanks the adapter from the default pack manifest pending ADR revision.
+
+### 3. Workflow templates — package-shipped only
+
+- Only the templates under `scripts/ai-video/lib/comfyui-templates/`
+  (Wan2.2 TI2V-5B default; LTX-2 audio-sync) are executable. Operator-
+  supplied workflow JSONs are rejected — the prompt surface is **parameter
+  substitution into the shipped template** via `jq --arg` (structured,
+  never string-spliced), with a charset whitelist on every substituted
+  value (the `model_id` tainted-input rule from contract v2 generalized).
+
+### 4. Filesystem + network boundary
+
+- Models directory: read-only mount. Output: per-project artifacts volume
+  only; the adapter validates every returned path with
+  `aiv_validate_artifact_path` against the project root (contract v2
+  unchanged — a local provider is still untrusted output).
+- Generation-time network: off by default (§ 1). The adapter itself talks
+  to ComfyUI's HTTP API on a loopback/container port only.
+
+### 5. Contract fit (v2)
+
+- `submit` → POST `/prompt` (returns `prompt_id`); `poll` → GET
+  `/history/<prompt_id>` (stateless); `fetch` → download via
+  `aiv_fetch_url` from `/view` into the scene dir. The async triple fits
+  without contract changes.
+- **Local-source rule (additive contract note):** a `kind="local"`
+  provider consumes local *input* paths (validated project-scoped) instead
+  of the https-only rule written for hosted lip-sync inputs — the https
+  rule exists because hosted providers must fetch the bytes; a local
+  engine reads the shared volume.
+- `cost_estimate`: a local render is priceable at **`0.0`** (no provider
+  charge — a *known* zero, distinct from an omitted/unknown estimate; the
+  cost gate continues to treat *missing* as `unknown`, never `0`).
+- GPU absence: detected at `submit` (ComfyUI unreachable / container not
+  running) → exit 3 with the setup hint, never a hang.
+
+## Residual risk (explicit)
+
+A malicious pinned node could still act within the container (CPU/GPU
+abuse, poisoning outputs on the shared artifacts volume). Mitigations:
+allowlist audit cadence by `risk_tier`, read-only model mount, network-off
+default. A kernel-grade guarantee is out of scope for a config suite — the
+container constraint set + pinned nodes + shipped-templates-only is the
+smallest enforceable surface that keeps "arbitrary Python from the
+internet" out of the execution path.
+
+## Consequences
+
+- The adapter (`scripts/ai-video/adapters/comfyui.sh`) ships
+  `lifecycle: experimental`, dry-run-first like every other adapter; the
+  live path requires the container posture above.
+- New lib artifacts: `comfyui-nodes.allowlist.json`,
+  `comfyui-templates/` (Wan2.2 TI2V-5B, LTX-2), each test-locked.
+- Setup documentation (container run line, model download session) lives
+  in the adapter header — docs-over-code where enforcement is impossible.
+
+## Alternatives considered
+
+- **OS-level sandbox (firejail/bwrap/sandbox-exec)** — rejected: per-OS
+  divergence, weaker GPU story, harder to verify from a shell adapter.
+- **Trusted-local (no sandbox, audited nodes only)** — rejected: "audited"
+  without isolation still executes arbitrary Python on the host; violates
+  the 2026-06-06 hard-no.
+- **Remote-only (no local story)** — rejected as the *only* mode: the
+  local-free path for GPU users is the feature; remote stays as the
+  escape hatch with explicit operator-owned risk.
+- **Soft-warn on unpinned nodes** — rejected (round-2 convergence): any
+  bypass flag reopens the arbitrary-Python door the sandbox exists to
+  close.
+
+## References
+
+- Council artefact: two-round debate 2026-06-07 (members above), design
+  mode, peer review on — convergence summarized inline per
+  `no-roadmap-references`.
+- ADR-059 — sibling design (resume) from the same roadmap phase.
+- `src/scripts/ai-video/lib/adapter-contract.md` — v2 contract the
+  adapter implements; local-source rule lands there as an additive note.
+- Roadmap: road-to-video-deferred-design, Phase 2 (transient layer —
+  not path-linked per `no-roadmap-references`).