@event4u/agent-config 2.23.0 → 2.25.0

package/.agent-src/rules/roadmap-ci-steps-policy.md

@@ -0,0 +1,145 @@
+---
+type: "auto"
+tier: "2a"
+description: "When authoring or executing roadmaps — forbid task ci / make test / npm run check steps when quality.local_auto_run is false; skip inline at execution"
+source: package
+triggers:
+  - path_prefix: "agents/roadmaps/"
+  - path_prefix: "app/Modules/"
+  - keyword: "task ci"
+  - keyword: "make test"
+  - keyword: "npm run check"
+  - keyword: "pnpm run check"
+  - keyword: "yarn check"
+  - keyword: "composer test"
+  - phrase: "run the quality pipeline"
+  - phrase: "run task ci"
+  - phrase: "run the full ci"
+applies_to_user_types:
+  - "maintainer"
+  - "developer"
+validator_ignore:
+  - type: "substring"
+    pattern: "agents/roadmaps/"
+    reason: "Rule's subject is roadmap files under agents/roadmaps/; every body link points there by design."
+  - type: "substring"
+    pattern: ".agent-settings.yml"
+    reason: "Rule reads quality.local_auto_run from .agent-settings.yml; naming the file is the contract."
+---
+
+# Roadmap CI-Steps Policy
+
+## Iron Law
+
+```
+WHEN quality.local_auto_run IS FALSE,
+ROADMAPS MUST NOT SCHEDULE FULL-PIPELINE CI STEPS,
+AND EXECUTION MUST SKIP THEM INLINE WITH [-] AND A REASON.
+```
+
+When `quality.local_auto_run: false` in `.agent-settings.yml`, every
+full-pipeline gate run during roadmap work is wasted wall-clock and
+tokens — remote CI on the PR is the authoritative gate. Roadmaps
+must neither schedule nor execute them locally. New CI gates and
+smoke/test files added by the roadmap itself are exempt — they must
+run once locally to count as verified evidence per
+[`verify-before-complete`](verify-before-complete.md).
+
+## Forbidden step patterns (authoring + execution)
+
+A step is **CI-shaped** when its text matches any pattern below.
+Case-insensitive. Line-bounded — literal must appear inside the
+step's `- [ ]` line or its immediate inline `<!-- … -->` / `(…)` note.
+
+| Pattern | Example |
+|---|---|
+| `task ci` | `Run task ci before the boundary` |
+| `task ci-strict` | `task ci-strict release gate` |
+| `task ci-fast` | `task ci-fast smoke` |
+| `make test` | `Run make test on phase boundary` |
+| `make ci` | `make ci pre-merge` |
+| `npm run check` / `pnpm run check` / `yarn check` | `npm run check before commit` |
+| `composer test` | `composer test on every phase` |
+| `vendor/bin/phpunit` (whole-suite, no path arg) | `vendor/bin/phpunit` |
+| `php artisan test` (no `--filter`) | `php artisan test` |
+
+Targeted commands (`vendor/bin/phpstan analyse app/Modules/X`,
+`php artisan test --filter=…`, `npm run lint -- --fix path/`) are
+**not** CI-shaped — narrow verifications, allowed regardless of the
+setting.
+
+## Carve-outs — when CI-shaped steps are still allowed
+
+1. **New CI gate / smoke test / test file landed by this roadmap.**
+   Once-locally execution is mandatory under
+   [`verify-before-complete`](verify-before-complete.md) carve-out
+   (see `templates/agent-settings.md` § `quality.local_auto_run`).
+   Mark the step with `<!-- carve-out: new-gate-verification -->`
+   on the same line; linter and execution loop honour it and let the
+   step run.
+2. **`quality.local_auto_run: true`.** Opt-in restores pre-policy
+   behaviour — linter no-ops, execution loop runs CI steps unmodified.
+3. **Acceptance-criteria block at end of roadmap.** Final-gate prose
+   like "All quality gates pass (`task ci`)" inside an
+   `## Acceptance criteria` section is documentation, not an
+   executable step (no `- [ ]` checkbox in front). Linter ignores;
+   execution loop never reaches it as a step.
+
+## Authoring — linter blocks at write-time
+
+`task lint-roadmap-ci-steps` (wired into `task ci-fast` /
+`lint-roadmap-complexity` cadence) scans `agents/roadmaps/*.md` and
+`app/Modules/*/agents/roadmaps/*.md`. Exit code:
+
+- `0` — no CI-shaped steps, or setting is `true`, or every match is
+  carve-out-marked.
+- `1` — at least one CI-shaped step in an active (non-archived,
+  non-skipped) roadmap with `quality.local_auto_run: false` and no
+  carve-out marker. Linter prints file, line, matched literal, and
+  suggested rewording.
+
+Archive (`agents/roadmaps/archive/`) and skipped
+(`agents/roadmaps/skipped/`) are out of scope — they record history,
+not future work.
+
+## Execution — process-loop skips inline
+
+Wrappers `/roadmap:process-step|phase|full` honour the policy at the
+top of [`roadmap-process-loop § 5`](../contexts/execution/roadmap-process-loop.md#5-step-loop):
+
+1. Before running a step, match its text against the patterns above.
+2. CI-shaped **and** `quality.local_auto_run: false` **and** no
+   carve-out marker → flip checkbox to `[-]` (cancelled), append a
+   one-line reason as inline note, regenerate the dashboard, continue
+   to next step. **Never** run the gate.
+3. CI-shaped **and** `quality.local_auto_run: true` → run normally.
+4. Carve-out-marked → run regardless of the setting.
+
+The `[-]` reason format is fixed:
+`<!-- skipped: quality.local_auto_run=false → remote CI is the gate -->`.
+Per [`roadmap-progress-sync`](roadmap-progress-sync.md) the flip and
+dashboard regen happen in the **same reply** that decides to skip;
+saving skips for the archive commit is a rule violation.
+
+## Failure modes
+
+- Authoring `- [ ] Run task ci` while `local_auto_run: false` — linter
+  fails the PR.
+- Executing a CI-shaped step without inline-skip flip — Iron Law
+  violation; loop never reaches the gate.
+- Carve-out marker on an *existing* pipeline run — abuse; the marker
+  is reserved for **new** gates introduced by the same roadmap.
+- Hiding the literal inside a fenced bash block to dodge the linter —
+  linter matches inside fenced blocks too (see
+  `scripts/lint_roadmap_ci_steps.py`).
+
+## See also
+
+- [`verify-before-complete`](verify-before-complete.md) — Iron Law
+  this rule narrows; carve-out cites it.
+- [`roadmap-progress-sync`](roadmap-progress-sync.md) — inline flip +
+  dashboard regen contract.
+- `templates/agent-settings.md` § `quality.local_auto_run` — source
+  of the toggle and its carve-out wording.
+- [`contexts/execution/roadmap-process-loop`](../contexts/execution/roadmap-process-loop.md)
+  — § 5 owns the inline-skip mechanics.

package/.agent-src/rules/roadmap-progress-sync.md

@@ -25,16 +25,17 @@ Roadmap touch = create / rename / delete / move file, add/rename/remove a phase,
 ```
 EVERY DONE STEP FLIPS [ ] → [x] IN THE SAME REPLY THAT LANDS THE WORK.
 NO "I UPDATE THE ROADMAP AT THE END OF THE PHASE."
-NO "FOUR STEPS DONE, ONE COMMIT, ONE REGEN."
 A REPLY THAT LANDS A VERIFIED STEP WITHOUT FLIPPING ITS CHECKBOX
 IS A RULE VIOLATION, NOT AN OVERSIGHT.
 ```
 
-`/roadmap:process-step`, `/roadmap:process-phase`, `/roadmap:process-full`, and any other multi-step autonomous run flip the box for step N **before** moving on to step N+1. The dashboard is a real-time monitor, not a post-hoc summary. Batched flips at the archive commit defeat the dashboard's purpose.
+`/roadmap:process-step`, `/roadmap:process-phase`, `/roadmap:process-full`, and any other multi-step autonomous run flip the box for step N **before** moving on to step N+1. The checkbox itself is the real-time monitor — the markdown file is the source of truth, the dashboard is a derived view.
 
 **Step counts as done** when its code/doc change is written and saved AND the verification cited in the step has passed (fresh output in this reply or an earlier one).
 
-**In-progress marker.** When a step takes more than one reply, mark it `[~]` the moment work starts and regen — the user sees one row move `[ ] → [~] → [x]` instead of silent rows. `[~]` stays open for `count_open` but advances the phase percentage.
+**In-progress marker.** When a step takes more than one reply, mark it `[~]` the moment work starts — the user sees one row move `[ ] → [~] → [x]` instead of silent rows. `[~]` stays open for `count_open` but advances the phase percentage.
+
+**Dashboard regen cadence — opt-in batching.** The checkbox flip is non-batchable. The **subprocess regen** (`./agent-config roadmap:progress`) is batchable per `roadmap.dashboard_regen_cadence` in `.agent-settings.yml` (`per_step` default · `every_5_steps` · `phase_boundary`). Run end, phase boundary, and any file-shape touch (rename / phase add / archive — Iron Law 1) always force an immediate regen regardless of cadence.
 
 ## Pre-send self-check — MANDATORY
 
@@ -42,10 +43,15 @@ Before sending any reply that landed roadmap work:
 
 1. Did this reply land a step (code/doc saved + verification passed)?
 2. Is its checkbox flipped to `[x]` / `[~]` / `[-]` in `agents/roadmaps/<file>.md`? If no → flip, then continue.
-3. Did `./agent-config roadmap:progress` run after the flip? If no → run, then continue.
+3. Is regen due now per `roadmap.dashboard_regen_cadence`?
+   - `per_step` → yes, always.
+   - `every_5_steps` → yes when this is the 5th, 10th, … closed step in the run, or the last step of the reply.
+   - `phase_boundary` → only when this reply closes the phase or run.
+   - Any file-shape touch (rename / phase add / archive) → yes, regardless of cadence.
+   If yes and not run yet → run `./agent-config roadmap:progress`, then continue.
 4. Did `count_open` reach 0? If yes → `git mv` to `archive/` and regen again — same reply.
 
-Any "no" at step 2 or 3 → reply is incomplete. Do not send.
+Any "no" at step 2 → reply is incomplete. Do not send. A skipped step 3 regen is fine when cadence permits — checkbox truth lives in the markdown file.
 
 Long-form mechanics (failure-mode catalog, Copilot fallback, `[~]` vs `[ ]` semantics, hook + CI defence-in-depth) live in `guideline:agent-infra/roadmap-progress-mechanics`.
 Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/skills/character-consistency/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: character-consistency
+description: "Use when a character must stay visually identical across AI video scenes — locks identity tokens (silhouette, palette, wardrobe, prop) in JSON. Triggers 'character lock', 'same character'."
+personas:
+  - hollywood-director
+source: package
+domain: product
+---
+
+# character-consistency
+
+> Lock a character's visual identity into
+> `agents/ai-video/<project>/characters/<id>.json` so every scene
+> reuses the **exact same tokens** verbatim. Downstream skills
+> ([`video-director`](../video-director/SKILL.md),
+> [`pixar-storyteller`](../pixar-storyteller/SKILL.md),
+> [`motion-choreographer`](../motion-choreographer/SKILL.md)) read
+> this file and never paraphrase. Verified by visual regression
+> (pixel similarity ≥ 95%, Phase 6 Step 3).
+
+## When to use
+
+- A multi-scene run names the same character on screen more than
+  once — Character Lock is mandatory before the second scene drafts.
+- A character drift bug landed (face / outfit / prop changed between
+  scenes) — re-lock and rerun the affected scenes.
+- A series, episode, or recurring ad uses the same on-screen identity.
+
+Do NOT use when:
+
+- One-shot scene with no recurring character — overhead is wasted.
+- The "character" is an object or environment, not a person /
+  creature — use a `style.json` lock pattern in the project's notes
+  instead.
+
+## Procedure
+
+### Step 0: Inspect
+
+1. Check `agents/ai-video/<project>/characters/` — if a lock already
+   exists for this id, **read it, do not redraft**. Edits require an
+   explicit revision note (Phase 6 visual regression must rerun).
+2. Confirm the character will appear in ≥ 2 scenes; one-shot → skip.
+
+### Step 1: Draft identity tokens
+
+Emit a JSON file at
+`agents/ai-video/<project>/characters/<character-id>.json` with the
+following fields. Every field is mandatory; missing field → fail
+the lock.
+
+```json
+{
+  "id": "kebab-case-id",
+  "name": "Display Name",
+  "silhouette": "one-line read of the body shape from 30m",
+  "palette": ["#hex1", "#hex2", "#hex3"],
+  "wardrobe": "garment list, materials, era",
+  "signature_prop": "the one object that travels with them",
+  "posture_default": "how they stand when not acting",
+  "eye_behavior": "blink rhythm, glance habit",
+  "face": "age band, skin tone, hair (length / color / texture), distinguishing marks",
+  "voice_note": "timbre + cadence for native-audio adapters; null if N/A",
+  "reference_frame": "scenes/<id>/frames/<n>.png or null",
+  "version": 1
+}
+```
+
+### Step 2: Reference frame
+
+1. After the first scene renders, copy the highest-quality frame
+   showing the character full-face and full-body to
+   `agents/ai-video/<project>/characters/<id>.ref.png`.
+2. Update `reference_frame` in the JSON to point at it.
+3. Phase 6 visual regression compares every subsequent scene's
+   character frame against this reference (ImageMagick `compare`
+   ≥ 95% similarity).
+
+### Step 3: Validate
+
+1. JSON parses (`jq . characters/<id>.json` exits 0).
+2. All mandatory fields present and non-empty.
+3. Palette has ≥ 2 and ≤ 5 hex values.
+4. Downstream skills cite this file by path, never paraphrase its
+   contents.
+
+## Output format
+
+1. **`agents/ai-video/<project>/characters/<id>.json`** — locked
+   identity tokens, schema above.
+2. **`agents/ai-video/<project>/characters/<id>.ref.png`** —
+   reference frame (added after first render).
+3. **`agents/ai-video/<project>/characters/CHANGELOG.md`** — one
+   line per revision: `v<n> · YYYY-MM-DD · reason · scenes-to-rerun`.
+
+## Gotcha
+
+- The model wants to "improve" identity tokens on each scene —
+  this is the silent drift failure. Tokens are immutable until a
+  revision note bumps `version`.
+- Palette without a count fails downstream — adapters need a small
+  closed set (2–5 hex).
+- `voice_note: null` is explicit; missing the key entirely breaks
+  the schema validator.
+- Reference frame is captured *after* the first successful render,
+  not before — bootstrap scenes have no reference and only the
+  JSON locks them.
+- A revision (`version` bumped) requires Phase 6 visual regression
+  to rerun against every prior scene that used the old version.
+
+## Do NOT
+
+- Do NOT paraphrase identity tokens when drafting scene prompts —
+  copy verbatim or break the lock.
+- Do NOT edit a locked JSON in place without bumping `version` and
+  adding a CHANGELOG line.
+- Do NOT skip the reference frame after the first render — visual
+  regression has nothing to compare against.
+- Do NOT lock a character that appears in only one scene.
+
+## Policies
+
+When a character lock would identify or render a real person, consult before emitting the JSON:
+
+- [`agents/policies/media/likeness.md`](../../../agents/policies/media/likeness.md) — real-person identity tokens require a cited likeness release.
+- [`agents/policies/media/public-figures.md`](../../../agents/policies/media/public-figures.md) — recognised public figures carry the harder gate (publicity rights + transformative-intent).
+- [`agents/policies/media/voice-cloning.md`](../../../agents/policies/media/voice-cloning.md) — when `voice_note` references a real person's voice.
+- [`agents/policies/media/disclosure.md`](../../../agents/policies/media/disclosure.md) — outputs carrying a real-person lock require the non-removable AI-generation disclosure downstream.
+
+Refuse-and-surface the file path; do not silently sanitise the prompt.
+

package/.agent-src/skills/git-workflow/SKILL.md

@@ -77,6 +77,139 @@ The project uses `.github/pull_request_template.md`:
 - `main` is default/production branch.
 - Merge strategy: merge commits (not squash).
 
+## Procedure: Safe squash-after-push
+
+Use ONLY when the user explicitly authorized a squash on a branch that
+is already on origin. The whole sequence runs in **one turn** — never
+end the session between rewrite and push.
+
+Trigger context: `post-push-rewrite-discipline` rule routed here.
+
+### 1. Snapshot before touching anything
+
+```bash
+BRANCH=$(git branch --show-current)
+DATE=$(date +%F)
+git fetch origin
+git tag "safe-squash-pre/${BRANCH}/${DATE}" HEAD
+git tag "safe-squash-origin/${BRANCH}/${DATE}" "@{u}"
+```
+
+Two tags = two recoveries (local tip + origin tip). Do not skip the
+tags — `git reflog` is TTL-bounded and unreliable across sessions.
+
+### 2. Verify aligned starting state
+
+```bash
+git rev-list --left-right --count HEAD...@{u}
+```
+
+- `0  0` → aligned, proceed.
+- `N  0` (local ahead) → unpushed work, proceed.
+- `0  N` (origin ahead) → `git pull --ff-only` first, then re-check.
+- `M  N` (both non-zero) → **divergent**. Abandon the squash and run
+  § Divergent-State Recovery below.
+
+### 3. Perform the squash
+
+Default — soft-reset path (single token-cheap rewrite):
+
+```bash
+git reset --soft "$(git merge-base HEAD <base>)"
+git commit -m "<conventional commit message>"
+```
+
+Interactive rebase only when the user wants per-commit control — it
+replays derived files (`.compression-hashes.json`, router projections)
+per commit and conflicts on every replay.
+
+### 4. Re-push in the SAME turn
+
+```bash
+FETCHED_SHA=$(git rev-parse "@{u}")
+git push --force-with-lease="${BRANCH}:${FETCHED_SHA}" origin "${BRANCH}"
+git fetch origin
+[ "$(git rev-parse HEAD)" = "$(git rev-parse @{u})" ] \
+  && echo "OK: origin matches HEAD" \
+  || echo "MISMATCH — do not end session"
+```
+
+If the push fails (pre-push hook, network, token budget):
+- Fix the underlying cause **now**.
+- Re-push immediately.
+- Do not commit new work on top of the squashed-but-unpushed tip.
+- Do not end the session until `HEAD == @{u}`.
+
+### 5. Hand off only with verified parity
+
+Report exactly:
+- pre-squash tip SHA (from step 1)
+- pre-squash tag name (for recovery)
+- post-squash tip SHA == origin SHA (verified in step 4)
+- PR number, if any, and confirm it picked up the new tip
+
+## Procedure: Divergent-State Recovery
+
+Fires when `git rev-list --left-right --count HEAD...@{u}` shows
+**both** sides non-zero on the current branch.
+
+### 1. Stop. Do not pull.
+
+A blind `git pull --rebase` here replays remote commits on top of a
+local history that may already represent the same work in a different
+shape — guaranteed conflict storm in derived files, possible
+double-application of the same change. This is the documented failure
+mode behind `post-push-rewrite-discipline`.
+
+### 2. Tag both sides immediately
+
+```bash
+TS=$(date +%FT%H%M)
+git tag "diverged-local/${TS}" HEAD
+git tag "diverged-origin/${TS}" "@{u}"
+```
+
+### 3. Diagnose: which side is the correct future?
+
+```bash
+git log --oneline @{u}..HEAD   # local-only commits
+git log --oneline HEAD..@{u}   # origin-only commits
+git diff @{u}..HEAD --stat     # shape of local-ahead work
+```
+
+Decision matrix:
+
+| Pattern | Future | Action |
+|---|---|---|
+| Local has the same logical work as origin, just reshaped (squash/rebase) | **Local** | After PR-review check (step 4), `git push --force-with-lease=<branch>:<origin-sha>` |
+| Origin has commits local does not reflect (another contributor pushed) | **Origin** | Tag any local-ahead work for cherry-pick, then `git reset --hard @{u}` |
+| Both sides have genuine independent work | **ask user** | Never decide silently — surface the two commit lists and let the user pick |
+
+### 4. PR review-comment check (mandatory before any force-push)
+
+If a PR is open on this branch:
+```bash
+gh pr view --json reviews,comments
+# or via GitHub API: /repos/<owner>/<repo>/pulls/<num>/{reviews,comments}
+```
+
+If review comments are anchored to commits that the force-push will
+erase → STOP, ask the user how to preserve them. A force-push that
+destroys live review feedback is unrecoverable from the agent side.
+
+### 5. Recover or proceed
+
+Use the tags from step 2 to restore either side if step 4 surfaces a
+problem. After resolution, verify `HEAD == @{u}` and report both
+SHAs plus the tags created.
+
+## Hard prohibitions on a pushed branch
+
+- No `git pull --rebase` after detecting divergent state.
+- No `git push --force` without `--force-with-lease=<branch>:<sha>`.
+- No squash-then-end-session — the push must complete in the same turn.
+- No reflog-only recovery — always tag the state explicitly first.
+
 ## Output format
 
 1. Commits following conventional commit format

package/.agent-src/skills/motion-choreographer/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: motion-choreographer
+description: "Use when turning a locked still + blueprint into a provider-tuned motion prompt — camera, primary + secondary motion, physics, native-audio sync. Triggers 'motion prompt for Veo/Kling/Sora'."
+personas:
+  - ai-video-technical-director
+source: package
+domain: product
+---
+
+# motion-choreographer
+
+> Turn an approved still + the 12-block scene blueprint into a
+> provider-tuned **motion prompt** that the target video adapter
+> consumes. Camera choreography, primary subject motion, secondary
+> environment motion, physics constraints, and — when the adapter
+> declares `audio: native` — a synchronized audio direction block.
+> Reads adapter capabilities from
+> [`adapter-contract.md`](../../../scripts/ai-video/lib/adapter-contract.md);
+> never speaks to a network API.
+
+## When to use
+
+- An image is locked (operator picked one candidate via
+  `operator-pick.sh`) and the next step is motion + audio direction
+  for the video adapter.
+- The blueprint exists in `scenes/<id>/blueprint.json` but the
+  motion prompt has not been emitted yet.
+- A provider switch (Veo → Kling, Sora → Higgsfield) requires the
+  same scene retuned for the new adapter's capability profile.
+
+Do NOT use when:
+
+- The blueprint is still prose only — run
+  [`scene-expander`](../scene-expander/SKILL.md) → `parse-blueprint.sh`
+  first.
+- No still has been locked — the operator-selection checkpoint
+  must complete first.
+- The output is a still graphic — `canvas-design`.
+
+## Procedure
+
+### Step 0: Inspect
+
+1. Read `scenes/<id>/blueprint.json` — fail loud if missing.
+2. Read `scenes/<id>/selection.json` — fail loud if missing; the
+   locked image path is required as the motion anchor.
+3. Read the target adapter's capability via
+   `scripts/ai-video/adapters/<id>.sh capability`. Cache `audio=*`
+   for Step 3.
+4. If a `character.json` lock exists, load it verbatim — identity
+   tokens are immutable.
+
+### Step 1: Camera choreography
+
+Emit a `CAMERA MOTION` block with the move type, distance, speed
+in seconds, and start-end framing.
+
+- Move types: lock-off, pan, tilt, dolly-in, dolly-out, truck,
+  pedestal, push, pull, handheld, gimbal-glide, crane, whip.
+- Speed in seconds per beat (`0.4s push, hold 1.6s, 0.4s pull`).
+- Start and end framing named (`MS → CU`, `WS → MS`).
+
+Adapter quirks:
+
+- **Veo** — accepts named moves; prefers ≤ 8s clips.
+- **Kling** — motion intensity 0–1 token; map our speed to that.
+- **Sora** — natural-language move + duration; no token.
+- **Higgsfield** — preset-driven; pick the preset that matches the
+  move; record the preset id in the motion prompt.
+
+### Step 2: Primary + secondary motion
+
+Two blocks:
+
+1. **PRIMARY MOTION** — what the subject does, beat-counted, with
+   physics anchors (mass, contact points, momentum). Reuse `ACTION`
+   from the blueprint; refine for the adapter's preferred verb
+   density.
+2. **SECONDARY MOTION** — what the world does (hair, fabric,
+   foliage, water, dust, particles, breath). One layer per line.
+
+### Step 3: Audio direction (conditional)
+
+If adapter capability is `audio: native` AND the blueprint's
+`audio.enable_native_audio` is `true`:
+
+Emit an `AUDIO DIRECTION` block with:
+
+- `DIALOGUE TIMING` — `speaker @ 0.4s: "line"` per dialogue entry.
+- `AMBIENT LAYERS` — copy from blueprint; one layer per line.
+- `SYNC CUES` — which action beat maps to which audio cue
+  (`footstep @ 1.2s`, `door close @ 2.1s`).
+
+If adapter capability is `audio: none`:
+
+- Emit a `# AUDIO: ffmpeg-mux fallback` comment with the
+  blueprint's audio paths queued for stitch-time mux.
+- Set `enable_native_audio: false` in the motion-prompt JSON.
+
+### Step 4: Physics constraints
+
+Emit `PHYSICS` — a short list of what the model must respect:
+gravity direction, contact friction, fluid behavior, hair / cloth
+inertia, lens parallax. Single line per constraint.
+
+### Step 5: Emit motion-prompt JSON
+
+Write `scenes/<id>/motion-prompt.json` with the adapter-contract
+stdin shape. The orchestrator pipes this into the video adapter's
+`submit` subcommand.
+
+### Step 6: Validate
+
+1. JSON parses (`jq .`).
+2. `requires.audio_native` is consistent with the chosen adapter's
+   capability.
+3. Duration in the motion prompt matches blueprint duration ±0.
+4. Identity tokens (if `character.json` exists) are verbatim.
+
+## Output format
+
+1. **`scenes/<id>/motion-prompt.json`** — adapter-contract stdin.
+2. **`scenes/<id>/motion-prompt.txt`** — labeled prose blocks
+   (CAMERA MOTION · PRIMARY MOTION · SECONDARY MOTION · AUDIO
+   DIRECTION · PHYSICS) for operator review.
+3. **`scenes/<id>/adapter-notes.md`** — which adapter, which
+   capability, which preset / model, with rationale.
+
+## Gotcha
+
+- The model wants to "improve" the blueprint's `SUBJECT` block —
+  identity tokens are immutable; refuse the temptation.
+- Picking `audio: native` on an adapter that returns `audio: none`
+  produces silent video — always read capability first, never
+  guess from the adapter name.
+- Higgsfield preset id must be recorded; otherwise the rerun
+  drifts to whichever preset the model picks on the next call.
+- Sora durations > 8s often degrade — clamp at the adapter table
+  limit; surface the clamp to the operator.
+
+## Do NOT
+
+- Do NOT emit motion prompts for an adapter whose capability you
+  did not query this turn.
+- Do NOT skip the still-locked check — motion direction without an
+  anchored image diverges on every call.
+- Do NOT paraphrase identity tokens from `character.json`.
+- Do NOT call any network API — this skill is provider-tuning
+  prose only.
+
+## Policies
+
+Motion prompts inherit upstream blueprint constraints. Before emitting provider-tuned prose:
+
+- [`agents/policies/media/disclosure.md`](../../../agents/policies/media/disclosure.md) — every distributed clip → non-removable AI-generation disclosure; refuse adapter flags that suppress it.
+- [`agents/policies/media/transparency.md`](../../../agents/policies/media/transparency.md) — provider provenance (C2PA / SynthID) preserved; refuse re-encode flags that strip provenance.
+- [`agents/policies/media/voice-cloning.md`](../../../agents/policies/media/voice-cloning.md) — motion prompt requests `audio: native` in named voice.
+- [`agents/policies/media/brand-impersonation.md`](../../../agents/policies/media/brand-impersonation.md) — copies recognised brand's chyron / mascot / signature transition.
+
+Refuse-and-surface; motion prompt cannot launder upstream policy gap.
+