@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/skills/memory-consolidation/SKILL.md

@@ -0,0 +1,266 @@
+---
+model_tier: medium
+name: memory-consolidation
+description: "Use when consolidating session signals into curated memory — four-phase loop ORIENT → GATHER → CONSOLIDATE → PRUNE. Triggers on 'mine my sessions', 'consolidate memory', 'review intake signals'."
+status: active
+tier: senior
+domain: engineering
+context_spine: [repo]
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# memory-consolidation
+
+## When to use
+
+- Intake JSONL has accumulated unreviewed signals and `/memory:load` shows the inline-review block.
+- A pattern recurred across recent sessions (correction, preference, decision, repeat-bug) and is at risk of being forgotten by the next fresh chat.
+- Before closing out a multi-day implementation, capture project-scoped facts so the next agent does not re-discover them.
+
+Do NOT use for one-off code review notes (those belong in PR comments,
+not memory), for user-attribute facts like name or IDE preference (the
+`onboard` flow owns those), or for transient TODOs (use the task list).
+
+## Cognition cluster
+
+- **Mental model 5 — Signal vs. noise.** A consolidation pass that
+  promotes 30 entries from a 50-message session is noise; the Pareto
+  cut is roughly 3–5 promote-worthy signals per cycle. See
+  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 5.
+- **Mental model 12 — Defense in depth.** Date-discipline, tag
+  intersection, and per-invocation transcript-access confirmation are
+  three independent guards; any one alone fails open. See § 12.
+
+## Procedure
+
+The loop is four sequential phases. Each phase has one exit gate; do
+not advance until the gate is green.
+
+### Phase 1 — ORIENT (review scope and assess adapter)
+
+1. Confirm scope: which project, which time window, which transcript
+   source. Default window: last 14 days. The agent must read the
+   user's last chat message for an explicit `--since` override before
+   defaulting.
+2. Inspect the current curated state: list files under
+   `agents/memory/` and check the most recent `last_validated`
+   timestamps. Identify which schemas are stale before mining adds
+   noise.
+3. Review the **repo** slot of the [context-spine](../../../docs/contracts/context-spine.md)
+   for project boundaries (modules, owners, sensitive paths). If empty,
+   note the gap in the consolidation report; do not invent.
+4. Resolve the `TranscriptAdapter` for the current host (see Adapter
+   contract below). If no adapter matches, stop and route the user to
+   `/memory:propose` for manual signal entry. Do **not** synthesize.
+
+**Exit gate:** scope, window, adapter all named. If any one is
+missing, stop.
+
+### Phase 2 — GATHER SIGNAL
+
+1. Stream transcript turns through the four signal regex families:
+   - **Correction:** `actually|wrong|stop doing|don't do|that's not what|nicht so`.
+   - **Preference:** `prefer|always|never|standard|i want|ich will`.
+   - **Decision:** `let's go with|decided|we'll use|entschieden`.
+   - **Pattern (recurring):** the same file path or symbol appears in
+     ≥ 3 turns within 24 hours.
+2. For each match, extract a **normalised fact** — strip personal
+   pronouns, IDE chrome, timestamps, and turn-id. The fact must be
+   project-scoped (refers to a file, module, command, or invariant)
+   not user-scoped (refers to *me*, *Matze*, *my IDE*).
+3. Drop user-attribute matches. If the fact cannot survive the
+   normalisation, discard it. The miner is a strict gate.
+
+**Exit gate:** ≤ 5 normalised facts per cycle. More than 5 means the
+miner is too loose; tighten patterns and re-run before promoting.
+
+### Phase 3 — CONSOLIDATE
+
+1. Tag each fact via the schema-routing table:
+
+   | Tag | Schema |
+   |---|---|
+   | `convention` | `agents/memory/conventions.yml` |
+   | `invariant` | `agents/memory/domain-invariants.yml` |
+   | `gotcha` | `agents/memory/operational-gotchas.yml` |
+   | `pattern` | `agents/memory/recurring-patterns.yml` |
+
+   A fact may carry **two** tags; the promoter resolves via tag
+   intersection, not by file extension. See
+   [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md)
+   for the file-backed retrieval contract over the curated YAML.
+
+2. Append each fact as one JSONL line to
+   `agents/memory/intake/<primary-tag>.jsonl` with required fields
+   per the contract: `ts`, `type`, `key`, `observation`, `source:
+   agent`, `session_id`, plus the new optional `tags: [<one>, <two>]`.
+   Intake is **gitignored, local scratch** — only entries promoted to
+   curated YAML (next phase) become team-shared (committed).
+3. Default to `--preview` mode: render the JSONL block to stdout and
+   stop. Only `--commit-intake` writes the file.
+
+**Exit gate:** every fact carries ≥ 1 tag and a JSONL-shape that
+validates against the contract.
+
+### Phase 4 — PRUNE & INDEX
+
+1. After promotion (handled by `/memory:promote`, not this skill),
+   archive the consumed JSONL lines into
+   `agents/memory/intake/.archive/YYYY-Www.jsonl` — week-bucketed,
+   not day-bucketed (defeats session-context inference attacks).
+2. **Delete `status: archived` curated entries.** Once an entry is
+   marked `archived` (by review or supersession), remove it from the hot
+   file — **git history is the cold archive** (`git log -- <file>`
+   recovers it). This keeps the committed memory small without a decay
+   engine. Do not keep an `agents/memory/archive/` directory.
+3. If an *active* curated entry's `last_validated` is older than 90 days
+   AND no signal in the last 30 days touched its `key`, mark it stale in
+   the consolidation report — but do **not** auto-delete a still-active
+   entry. Only `archived` entries are deleted; staleness is a flag, not a
+   delete trigger.
+
+**Exit gate:** report cites ≥ 0 promotions, ≥ 0 stale flags, and the
+count of `archived` entries deleted (git history retains them).
+
+## Write-time curation discipline
+
+Memory quality comes from what you write, not from a heavy store. Apply
+these at GATHER + CONSOLIDATE (adapted from MemSkill's memory-operation
+skills — github.com/ViktorAxelsen/MemSkill, Apache-2.0, commit `9907c35f8cc7`):
+
+- **Dedupe before insert.** Compare against retrieved entries; never add a
+  fact already covered. Split distinct facts into separate entries.
+- **Merge on refresh, preserve what still holds.** When a fact updates an
+  existing entry, merge into one item and keep the details that remain true.
+- **Delete only on explicit contradiction.** Remove a curated entry only when
+  evidence directly contradicts or cancels it. If uncertain, keep it.
+- **Prefer no-op under uncertainty.** A chunk with no new, corrective, or
+  actionable information records nothing — silence beats speculation.
+- **Skip trivial / fleeting / speculative content.** Capture durable,
+  reusable facts, not transcripts or one-off chatter.
+- **One durable fact per entry.** No narrative blobs — each entry is a single
+  PATTERN / CONVENTION / INVARIANT / GOTCHA the next agent can act on.
+
+This is **meta-memory**: the skill of *how to remember* (what to extract,
+keep, forget) — distinct from the remembered content. The store stays simple
+and file-backed; the discipline lives here. Do **not** add
+INSERT/UPDATE/DELETE/NOOP operation machinery (append-only JSONL + curated
+YAML need no such ops) and do **not** import any retrieval / decay / trust
+engine.
+
+## TranscriptAdapter contract
+
+The miner is host-agnostic by design. A `TranscriptAdapter` for host
+`X` ships:
+
+- **Discover:** function returning the absolute path(s) of session
+  transcripts for the active project, scoped to the `--since` window.
+  Phase 1 ships the Claude-Code adapter only; absent adapter →
+  `not-supported-on-this-host`.
+- **Iterate:** generator yielding turn objects with `{role, ts,
+  text}`. Adapter strips IDE chrome and tool-call boilerplate before
+  yielding.
+- **Redact:** function applied to every yielded text — drops user
+  names, file paths outside the repo root, and any personal
+  identifier the consumer project lists in
+  `.agent-settings.yml` under `memory.redact_patterns`.
+
+The GATHER implementation lives in the single mining command
+`/memory:mine-session` (`scripts/mine_session.py`). It reads the
+**cross-host** chat-history JSONL log (`agents/runtime/.agent-chat-history`,
+written by platform hooks on every host), falling back to the per-host
+Claude-Code transcript when the log is absent. `--mode=[signals|proposals|both]`
+selects intake signals and/or rule/skill proposal seeds — the latter folds in
+the former `/chat-history learn`.
+
+## In-task notes → cross-run lessons (RDP)
+
+The Reasoning Discipline Protocol writes an **in-task** session-notes file
+(hypotheses, killed beliefs, predictions, decisions, uncertainty — structure in
+[`notes-first-reasoning`](../../rules/notes-first-reasoning.md)). That file is
+ephemeral working state, not curated memory. This skill is the **promotion path**:
+when an in-task killed-belief, calibrated prediction, or decision *generalises*
+beyond the task, consolidate it here as a durable cross-run lesson (one lesson per
+file, with why it mattered). Apply the same signal-vs-noise discipline — most
+in-task notes stay in-task and are discarded with the task.
+
+## Related Skills
+
+**WHEN to use this**
+
+- Intake JSONL has > 10 unreviewed signals.
+- A correction / preference recurred across ≥ 3 sessions.
+- Closing out a multi-day implementation.
+
+**WHEN NOT to use this**
+
+- One-off PR review notes — comment on the PR.
+- User-attribute facts (name, IDE) — those belong to the
+  [`onboard`](../../commands/onboard.md) flow, not curated memory.
+- Transient TODOs — use the task-list tools.
+- A single bug fix that does not generalise — fix the bug, do not
+  memorise it.
+
+## When the agent should load this
+
+- "Mine my recent sessions for memory signals."
+- "Consolidate the intake stream into curated entries."
+- "What did we decide about X across the last week?"
+- "Review unreviewed memory signals before I switch projects."
+- "Run a memory consolidation cycle."
+
+## Output
+
+1. **Consolidation report** — Markdown block printed to stdout: scope
+   (project, window, host), signal counts per class, list of
+   normalised facts with tag and target schema, stale-flag list. No
+   side effects in `--preview` mode.
+2. **Intake JSONL appendix** — only with `--commit-intake`: appended
+   lines to `agents/memory/intake/<tag>.jsonl`. Lines validate
+   against the contract.
+3. **Archive bucket** — only after `/memory:promote` runs and lifts
+   the lines into curated YAML: appends to
+   `agents/memory/intake/.archive/YYYY-Www.jsonl`. Week-bucketed.
+
+## Gotcha
+
+- Mining without `--confirm-transcript-access` reads zero turns and
+  prints an opt-in hint. The flag is per-invocation, not persistent.
+- The miner is a strict gate. > 5 normalised facts per cycle means
+  the regex set is too loose, not that the session was rich.
+- A fact tagged `gotcha + invariant` lands in the `gotcha` JSONL
+  (primary tag); the promoter reads tag intersection to decide the
+  curated YAML target.
+- Date-discipline: the `check_memory.py` linter rejects
+  `yesterday|today|tomorrow|last/next/this week|month|year` in curated
+  YAML without an `YYYY-MM-DD` anchor within ±20 chars. Re-anchor
+  before commit.
+
+## Do NOT
+
+- Do NOT auto-trigger this skill on session end. The flow is manual,
+  per-invocation, and confirmed.
+- Do NOT vendor patterns or text from any external source. Concept and
+  procedure structure are the only adoption surface.
+- Do NOT promote a normalised fact whose `key` falls outside the
+  repo root or names another consumer project.
+- Do NOT delete a stale curated entry without explicit user
+  confirmation. Stale-flag is the most this skill emits.
+
+## Runnable example
+
+After a 4-day refactor of `app/Services/PaymentGateway`, run a
+consolidation cycle:
+
+- `/memory:mine-session --since 2026-05-06 --confirm-transcript-access --preview`.
+- Miner surfaces 4 facts: 1 correction (`PaymentGateway::charge` must
+  not throw on idempotency replays — `convention`), 1 decision
+  (`Stripe webhook signing key lives in `config/services.php` only —
+  `gotcha`), 2 patterns (`PaymentGatewayTest` flakes when seeded data
+  carries timestamps in microseconds — `pattern + gotcha`).
+- Report cites 0 stale flags. Re-run with `--commit-intake` after
+  spot-checking the 4 facts.
+- Hand off to `/memory:promote` for the curated-YAML write.

package/dist/agent-src/skills/merge-conflicts/SKILL.md

@@ -0,0 +1,195 @@
+---
+model_tier: inherit
+name: merge-conflicts
+description: "Use when the user has merge conflicts or says \"resolve conflicts\". Understands conflict markers, resolution strategies, and verification workflow."
+domain: process
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# merge-conflicts
+
+## When to use
+
+Use this skill when:
+- A merge or rebase produces conflicts
+- The user asks to "resolve conflicts", "fix merge", or "update branch"
+- CI fails because the branch is behind main
+- The `prepare-for-review` command encounters conflicts
+
+## Procedure: Resolve merge conflicts
+
+### 1. Understand the situation
+
+Before touching any conflict:
+
+```bash
+# What files have conflicts?
+git diff --name-only --diff-filter=U
+
+# What branch are we merging from/into?
+git log --oneline -1 HEAD
+git log --oneline -1 MERGE_HEAD   # or REBASE_HEAD for rebase
+```
+
+### 2. Read both sides
+
+For each conflicted file:
+
+1. **Read the full conflict** — not just the markers, but the surrounding context.
+2. **Understand "ours"** — what does the current branch intend?
+3. **Understand "theirs"** — what does the incoming branch intend?
+4. **Check if both changes are needed** — often both sides added different things.
+
+### 3. Resolution strategies
+
+| Situation | Strategy |
+|---|---|
+| Both sides changed the same line differently | **Ask the user** — this is a semantic conflict |
+| Both sides added different code in the same area | **Keep both** — combine the additions in logical order |
+| One side deleted, other side modified | **Ask the user** — deletion intent vs modification intent |
+| Lock file conflicts (`composer.lock`, `package-lock.json`) | **Regenerate** — accept theirs, then run `composer install` / `npm install` |
+| Migration conflicts (same timestamp) | **Rename** — adjust timestamp to avoid collision |
+| Auto-generated files (OpenAPI spec, baselines) | **Regenerate** — resolve source, then regenerate the output |
+| Formatting-only conflicts | **Accept either** — then run quality tools to normalize |
+
+### 4. File-type specific rules (stack-aware)
+
+#### Source files (any language)
+
+- After resolving, check that import statements are correct (no duplicates, no missing imports). Applies to PHP `use`, JS/TS `import`, Python `import`, Go `import`, Rust `use`.
+- Verify the resolved file parses with the project's type-checker / linter on just the touched file:
+  - PHP: `php -l filename.php` then `vendor/bin/phpstan analyse path/to/file.php`
+  - TypeScript: `tsc --noEmit` (full project) or `eslint path/to/file.ts`
+  - Python: `python -m py_compile path/to/file.py` then `mypy path/to/file.py`
+  - Go: `go vet ./path/to/pkg/...`
+  - Rust: `cargo check`
+
+#### Database migrations
+
+- Never merge two migrations that modify the same table into one.
+- If both branches added migrations, keep both — adjust timestamps / ordering to avoid collision.
+- After resolving, run migrations against a disposable database to verify:
+  - Laravel: `php artisan migrate --env=testing`
+  - Symfony / Doctrine: `php bin/console doctrine:migrations:migrate --env=test --no-interaction`
+  - Node / Prisma: `pnpm prisma migrate dev --schema=...`
+  - Node / Knex: `pnpm knex migrate:latest --env test`
+  - Python / Alembic: `alembic upgrade head` (against a test DB URL)
+  - Go / golang-migrate: `migrate -path ./migrations -database "$TEST_DATABASE_URL" up`
+
+#### Config files
+
+- `composer.json` — resolve, then run `composer update --lock` to regenerate `composer.lock`.
+- `package.json` — resolve, then run `npm install` to regenerate `package-lock.json`.
+- `.env.example` — keep all new entries from both sides.
+
+#### Test files
+
+- If both sides added tests to the same file, keep all tests.
+- If both sides modified the same test, understand what each test is verifying and combine.
+
+### 5. When to ask the user
+
+**Always ask** when:
+- Both sides changed the **same business logic** differently (semantic conflict)
+- A deletion conflicts with a modification (intent is unclear)
+- The conflict involves **authorization or security** logic
+- You're unsure which side is "correct"
+
+**Resolve without asking** when:
+- Both sides added different, non-overlapping code
+- Lock file / auto-generated file conflicts
+- Import statement ordering
+- Formatting-only differences
+
+### 6. Verify after resolution
+
+After resolving ALL conflicts:
+
+```bash
+# 1. Check no conflict markers remain (stack-agnostic — no --include filter)
+grep -rn "<<<<<<< \|======= \|>>>>>>> " . \
+  --exclude-dir=node_modules --exclude-dir=vendor --exclude-dir=.git
+```
+
+```bash
+# 2. Syntax-check changed files (stack-dependent — pick the row that matches the project)
+# PHP:    find . -name "*.php" -newer .git/MERGE_HEAD -exec php -l {} \;
+# TS:     tsc --noEmit
+# Python: python -m compileall -q .
+# Go:     go build ./...
+# Rust:   cargo check
+```
+
+```bash
+# 3. Run the project's quality tools — resolve via the quality-tools skill, Taskfile,
+#    package.json scripts, composer.json scripts, or Makefile. Examples per stack:
+# PHP:    vendor/bin/phpstan analyse
+# TS:     pnpm lint
+# Python: ruff check && mypy
+# Go:     golangci-lint run
+# Rust:   cargo clippy
+```
+
+```bash
+# 4. Run tests — full suite, not just the touched files
+# PHP:    php artisan test    (or vendor/bin/pest)
+# TS:     pnpm test
+# Python: pytest
+# Go:     go test ./...
+# Rust:   cargo test
+```
+
+```bash
+# 5. Complete the merge/rebase
+git add .
+# Don't commit — let the user decide when to commit
+```
+
+## Common pitfalls
+
+| Pitfall | Prevention |
+|---|---|
+| Accepting "ours" blindly | Always read both sides first |
+| Missing a conflict marker | Run `grep -rn "<<<<<<< "` after resolving |
+| Breaking imports | Check `use` statements after merge |
+| Losing new code | Compare the resolved file with both original versions |
+| Forgetting to regenerate lock files | Always run package manager after resolving `*.json` |
+
+## Rebase vs Merge
+
+| Approach | When to use |
+|---|---|
+| `git merge main` | Default — preserves history, safer for shared branches |
+| `git rebase main` | Only when explicitly asked — rewrites history, cleaner log |
+
+**Never rebase without explicit permission** (per `no-commit` rule).
+
+## Output format
+
+1. Resolved conflict with both sides' intent preserved
+2. Summary of resolution strategy per file
+
+## Auto-trigger keywords
+
+- merge conflict
+- resolve conflict
+- rebase conflict
+- conflict markers
+- branch behind main
+- update branch
+
+## Gotcha
+
+- Never resolve conflicts by deleting code you don't understand — ask the user.
+- The model tends to accept "ours" or "theirs" wholesale instead of merging logic from both sides.
+- Always run tests after resolving conflicts — successful merge != correct merge.
+- Lock file conflicts (composer.lock, package-lock.json) should be resolved by re-running the package manager.
+
+## Do NOT
+
+- Do NOT rebase or force-push without explicit permission.
+- Do NOT leave conflict markers (`<<<<<<<`) in any file.
+- Do NOT skip verification (project type-checker + tests) after resolving.

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

@@ -0,0 +1,197 @@
+---
+model_tier: inherit
+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
+domain: product
+workspaces:
+  - small-business
+packs:
+  - ai-video
+lifecycle: experimental
+trust:
+  level: experimental
+install:
+  default: false
+  removable: true
+---
+
+# 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`).
+
+Blueprint intent-class decoding — the blueprint CAMERA block names
+one of six provider-agnostic intent classes; map it to the move types
+above before encoding:
+
+| Intent class | Move-type mapping |
+|---|---|
+| static hold | lock-off |
+| push-in | push / dolly-in |
+| pull-back | pull / dolly-out |
+| lateral track | truck / pan |
+| handheld drift | handheld / gimbal-glide |
+| orbit | crane / arc via truck+pan |
+
+Adapter quirks (per-provider encoding of the mapped move):
+
+- **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.
+- **LENS handling** — blueprint mm + aperture translate to the
+  provider's nearest lens / FOV idiom; never forward raw mm to a
+  provider that lacks lens grammar.
+- **DURATION handling** — the blueprint value is free; clamp to the
+  provider ceiling here and record the clamp in `review.md` (a
+  silent clamp is a drift bug).
+
+### 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.
+- Blueprint carries DIALOGUE → the mux fallback cannot speak text
+  lines. Emit a mandatory `AUDIO DOWNGRADE` warning block in
+  `motion-prompt.txt` AND `adapter-notes.md` listing every dialogue
+  line that will not render. The decision whether that is acceptable
+  belongs to the orchestrator gate (adapter-contract § Audio
+  ownership) — this skill translates, it never validates, and it
+  NEVER silently strips dialogue.
+
+### 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/settings/policies/media/disclosure.md`](../../../agents/settings/policies/media/disclosure.md) — every distributed clip → non-removable AI-generation disclosure; refuse adapter flags that suppress it.
+- [`agents/settings/policies/media/transparency.md`](../../../agents/settings/policies/media/transparency.md) — provider provenance (C2PA / SynthID) preserved; refuse re-encode flags that strip provenance.
+- [`agents/settings/policies/media/voice-cloning.md`](../../../agents/settings/policies/media/voice-cloning.md) — motion prompt requests `audio: native` in named voice.
+- [`agents/settings/policies/media/brand-impersonation.md`](../../../agents/settings/policies/media/brand-impersonation.md) — copies recognised brand's chyron / mascot / signature transition.
+
+Refuse-and-surface; motion prompt cannot launder upstream policy gap.
+