@event4u/agent-config 5.4.0 → 5.5.0

package/.agent-src/commands/knowledge/cross-repo.md

@@ -0,0 +1,71 @@
+---
+model_tier: inherit
+name: knowledge:cross-repo
+tier: 2
+cluster: knowledge
+sub: cross-repo
+description: Targeted, read-only retrieval over opted-in linked-project siblings (ADR-032 Option A). Pulls a shared type / API contract / config without bulk-including sibling files.
+skills: [file-editor]
+suggestion:
+  eligible: true
+  trigger_description: "what does the frontend expect, find the shared type in the other repo, check the sibling repo's API contract, /knowledge:cross-repo <query>"
+  trigger_context: "user needs context that lives in an attached sibling repo without copying its files in"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /knowledge cross-repo
+
+Targeted, **read-only** retrieval across the IDE-attached sibling repos the user
+has opted into (`linked_projects[].include: true`). Returns a bounded set of
+matches — a shared type, an API contract the frontend consumes, a config the
+sibling owns — **without bulk-including** any sibling file. Implements
+[`cross-repo-retrieval`](../../../docs/contracts/cross-repo-retrieval.md) and
+stays inside [ADR-032](../../../docs/decisions/ADR-032-linked-projects-scope.md)
+Option A.
+
+## Prerequisites
+
+- Python 3.10+ on the host.
+- At least one sibling opted in (`agent-config linked-projects:list` shows them).
+  No opted-in sibling → the command is inert with a clear message.
+
+## Steps
+
+### 1. Parse the query
+
+`/knowledge cross-repo "<query>" [--path-scope <glob>]`. The query is one
+concept (≥ 1 term > 2 chars). A `--path-scope` glob narrows the search and is
+**required** for `large`-flagged siblings.
+
+### 2. Run the retrieval
+
+```bash
+python3 scripts/cross_repo_retrieve.py "<query>" [--path-scope <glob>] [--max-chunks 8]
+```
+
+The script reads opted-in siblings only, runs a targeted path-glob + content
+grep (never a full walk), redacts secrets/PII from every chunk, and returns the
+retrieval envelope.
+
+### 3. Present matches
+
+Render the table: `source_repo · path · freshness · why`. Each row names the
+source sibling, the path inside it, the last-commit/mtime freshness stamp, and
+why it matched. Use the chunks as *context*, never as files to copy wholesale.
+
+### 4. Honour the scope guards
+
+- A `large` sibling without `--path-scope` is skipped with a note — re-run with
+  a scope. Do not remove the guard.
+- A sibling not `include: true` is never read.
+
+## Rules
+
+- **Read-only.** Never write to a sibling. Out-of-root writes still pass the
+  host permission gate; this surface writes nothing.
+- **Opt-in only, targeted only.** No full-tree sweep; no implicit inclusion.
+- **Secrets never cross repos** — the chunk redactor runs before any text is shown.
+- **One concept per invocation.** Do not chain.

package/.agent-src/commands/knowledge.md

@@ -33,6 +33,7 @@ contract — input shapes, bounds, redaction defaults, storage layout.
 | `/knowledge ingest` | `commands/knowledge/ingest.md` | Walk a local path, redact, chunk, persist to `agents/memory/knowledge/<ingest-id>/` |
 | `/knowledge list` | `commands/knowledge/list.md` | List existing ingests (table or JSON); pin / unpin by id prefix |
 | `/knowledge forget` | `commands/knowledge/forget.md` | Drop a single ingest by id prefix (atomic, no partial state) |
+| `/knowledge cross-repo` | `commands/knowledge/cross-repo.md` | Targeted read-only retrieval over opted-in linked-project siblings (ADR-032 Option A) |
 
 Sub-command names match the locked contract in
 [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
@@ -48,6 +49,7 @@ Sub-command names match the locked contract in
    > 1. ingest — point at a local folder, `.zip`, or file
    > 2. list — show what's already ingested (`--pin` / `--unpin` to flag)
    > 3. forget — drop an ingest by id prefix
+   > 4. cross-repo — targeted read-only retrieval over opted-in siblings
 
 ## Rules
 

package/.agent-src/commands/skill/preview.md

@@ -0,0 +1,67 @@
+---
+model_tier: inherit
+name: skill:preview
+tier: 2
+cluster: skill
+sub: preview
+description: Non-destructive preview of a skill — its declared steps, execution type, allowed tools, and file/command targets — before you run it. Read-only, no execution.
+skills: [file-editor]
+suggestion:
+  eligible: true
+  trigger_description: "what does this skill do, preview <skill> before running, what will it change, is it safe, /skill:preview competitive-positioning"
+  trigger_context: "user wants to inspect a skill's declared intent before committing to run it"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /skill preview
+
+Renders a skill's **declared intent** — its `## Steps`, execution type, handler,
+`allowed_tools`, and any file/command targets named in its body — so you can
+decide whether to run it. Read-only, no network, no execution. Implements the
+[`skill-dry-run`](../../../docs/contracts/skill-dry-run.md) contract.
+
+## Prerequisites
+
+- Python 3.10 + PyYAML on the host.
+- A skill name that resolves to `.agent-src/skills/<name>/SKILL.md`.
+
+## Steps
+
+### 1. Parse the argument
+
+`/skill preview <name> [--technical]`. The name is the first positional
+argument. Missing name → print usage and stop.
+
+### 2. Run the previewer
+
+```bash
+python3 scripts/skill_preview.py <name>
+```
+
+Add `--technical` for the raw frontmatter + numbered step list; default is the
+plain-language summary. `--format json` is machine-readable.
+
+### 3. Present the summary
+
+Show the plain-language preview: the skill's execution type (a manual-execution skill
+renders **"instructional only — no automatic execution"**; an assisted-execution skill
+renders its proposed actions), declared steps, tools, and any file/command
+targets. End on the contract reminder that preview shows *declared intent*, not
+a guarantee of side-effect-freeness.
+
+### 4. Hand back the decision
+
+Preview never runs the skill. After showing it, let the user decide whether to
+invoke the skill — that is the safe adoption loop:
+`/skills:discover` → `/skill:preview` → run.
+
+## Rules
+
+- **Read-only, no execution.** Preview inspects the SKILL.md; it does not run it.
+- **Not a sandbox** — it cannot prove a skill is harmless; it shows what the
+  skill *declares* it will touch.
+- **Malformed / missing SKILL.md → a structured error**, never a crash.
+- **One skill per invocation.**

package/.agent-src/commands/skill.md

@@ -0,0 +1,48 @@
+---
+model_tier: inherit
+name: skill
+tier: 2
+description: Single-skill orchestrator — routes to preview. Non-destructive "what will this skill do?" before you run it.
+cluster: skill
+type: orchestrator
+suggestion:
+  eligible: true
+  trigger_description: "what does this skill do, preview this skill before running, is this skill safe to run, what will it change, /skill:preview <name>"
+  trigger_context: "user wants to see a skill's declared steps + targets before committing to running it"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /skill
+
+Top-level orchestrator for the `/skill` family — **single-skill** operations
+(singular `skill` for one target; plural `/skills` is the catalog-wide
+discovery cluster). Today it carries one verb: `preview`.
+
+Anchors: [`skill-dry-run`](../docs/contracts/skill-dry-run.md) contract —
+what "preview" means, the explicit non-goals, and the surface.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/skill preview` | `commands/skill/preview.md` | Render a skill's declared steps, execution type, tools, and file/command targets before running it |
+
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/skill <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Steps` section verbatim.
+4. Unknown / missing sub-command → route to `preview` (the only verb today).
+
+## Rules
+
+- **Read-only.** Preview reads a skill's SKILL.md; it never runs the skill.
+- **Not a sandbox.** Preview surfaces *declared intent*, not a guarantee of
+  side-effect-freeness — a contract non-goal.
+- **One skill per invocation.** Do not chain.

package/.agent-src/commands/skills/discover.md

@@ -0,0 +1,76 @@
+---
+model_tier: inherit
+name: skills:discover
+tier: 2
+cluster: skills
+sub: discover
+description: Recommend skills for a role — ranked by four explained classes (most-useful-for-role, related-to-current-task, recently-adopted, popular-in-role). Local-only; every result carries a why.
+skills: [file-editor]
+suggestion:
+  eligible: true
+  trigger_description: "which skills should I use, recommend skills for my role, what fits this work, help me find a skill, /skills:discover sales"
+  trigger_context: "user wants a short, explained skill shortlist instead of scanning the 220-skill catalog"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /skills discover
+
+Surfaces a short, explained skill shortlist for a role. Reuses existing local
+signals only — the skill catalog frontmatter, the role's `skills.yml`
+shortlist, and (when present and not opted out) the local-analytics JSONL.
+Implements the [`skill-discovery`](../../../docs/contracts/skill-discovery.md)
+contract. Local-only, read-only, no network.
+
+## Prerequisites
+
+- Python 3.10 + PyYAML on the host (already a package dependency).
+- A role id — passed as `[role]`, or the active role from
+  `.agent-settings.yml` → `roles.active_role`.
+
+## Steps
+
+### 1. Resolve the role
+
+The user invokes `/skills discover [role]`. The role is the first positional
+argument. If omitted, the recommender falls back to `roles.active_role`. If
+neither resolves, it prints the available roles and stops — do not guess.
+
+### 2. Run the recommender
+
+```bash
+python3 scripts/skill_discovery.py --role <role>
+```
+
+Optional flags: `--format json` (machine-readable), `--limit N` (results per
+class, default 5). The script is pure-local and writes nothing.
+
+### 3. Present the table
+
+Render the recommender's Markdown table to the user:
+`skill · class · why · first command`. Each row's `why` names the *signal*
+(role match, domain adjacency, recent adoption, role popularity) — never a
+bare score. The four classes are:
+
+- `most-useful-for-role` — the role's priority shortlist.
+- `related-to-current-task` — same-domain peers not already shortlisted.
+- `recently-adopted` — used recently in this workspace (analytics) or the
+  shortlist tail when no usage signal exists yet.
+- `popular-in-role` — launched most by this role locally (analytics) or the
+  shortlist when no usage signal exists yet.
+
+### 4. Offer the first command
+
+Each row carries a `first command` — the natural way to start with that skill.
+Suggest the user pick one and run it. Do **not** auto-invoke a skill.
+
+## Rules
+
+- **Local-only, read-only.** No network, no writes, no prompt/response bodies.
+- **Every result has a non-empty `why`** — a contract invariant.
+- **Analytics opt-out honoured.** `AGENT_CONFIG_NO_LOCAL_ANALYTICS` env or
+  `analytics.local: off` → the analytics-backed classes fall back to the role
+  shortlist with an honest `why`; the surface never fabricates a usage signal.
+- **One role per invocation.** Do not chain.

package/.agent-src/commands/skills.md

@@ -0,0 +1,56 @@
+---
+model_tier: inherit
+name: skills
+tier: 2
+description: Skill discovery orchestrator — routes to discover. Local, explained skill recommendations over the catalog + role shortlists + optional local analytics.
+cluster: skills
+type: orchestrator
+suggestion:
+  eligible: true
+  trigger_description: "which skills should I use, recommend skills for my role, what skills fit this work, I can't find the right skill, /skills:discover"
+  trigger_context: "user is lost in the 220-skill catalog and wants a short, explained shortlist for their role"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /skills
+
+Top-level orchestrator for the `/skills` family — the **skill discovery**
+cluster. Turns existing local signals (the skill catalog, the active role's
+shortlist, and optional local analytics) into a short, *explained*
+recommendation list. Local-only, no network, honours the analytics opt-out.
+
+Anchors: [`skill-discovery`](../docs/contracts/skill-discovery.md) contract —
+input signals, the four recommendation classes, and the non-negotiable
+`why`-per-result requirement.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/skills discover` | `commands/skills/discover.md` | Rank skills for a role by four explained classes (most-useful / related / recently-adopted / popular) |
+
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/skills <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Steps` section
+   verbatim with the remaining args.
+4. If the sub-command is unknown or missing, route to `discover` (the only
+   sub-command today) and print its menu.
+
+## Rules
+
+- **Local-only.** The recommender reads local files only — the catalog, the
+  role `skills.yml`, and (if present and not opted out) the local-analytics
+  JSONL. No network, no writes.
+- **Every recommendation carries a `why`.** Never surface an unexplained
+  score — this is a contract invariant.
+- **Honours the analytics opt-out** (`AGENT_CONFIG_NO_LOCAL_ANALYTICS` env or
+  `analytics.local: off`); degrades to catalog + role shortlist gracefully.
+- **Do NOT chain sub-commands.** One `/skills <sub>` per turn.

package/.agent-src/commands/video/from-song.md

@@ -0,0 +1,317 @@
+---
+model_tier: inherit
+name: video:from-song
+tier: 2
+cluster: video
+sub: from-song
+description: Music-video from a song + reference images — accept or derive a timed scene script, optional character-lock, render, stitch, mux song as master track. Dry-run default; one batch gate for live calls.
+personas: [hollywood-director, ai-video-technical-director]
+skills: [song-to-script, scene-expander, video-director, character-consistency, motion-choreographer]
+suggestion:
+  eligible: true
+  trigger_description: "make a music video from a song, turn a track into a video, lip-sync clip from images and audio, AI music video"
+  trigger_context: "user supplies an audio file plus reference images and wants a final MP4 cut to the song"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: experimental
+trust:
+  level: experimental
+install:
+  default: false
+  removable: true
+---
+
+# /video:from-song
+
+`/video:from-song <images-dir> <song-file> [--brief "<description>"] [--auto-script] [--scene-durations <list>] [--character|--no-character] [--auto-pick] [--keep-native-audio] [--max-duration <min>] [--max-scenes <n>] [--image-provider <id>] [--video-provider <id>]`
+
+Turns a **song** plus a **folder of reference images** into a finished
+music-video. The scene script is either supplied by the operator
+(`--brief`) or derived from the audio itself (`--auto-script`); if
+neither flag is present the command asks. After the script exists this
+command reuses the same render path as
+[`/video:from-script`](from-script.md) and ends by muxing the song over
+the cut as the **master audio track**.
+
+Provider flags override the `<default-image-provider>` /
+`<default-video-provider>` from
+[`agents/.ai-video.xml`](../../../agents/templates/.ai-video.xml.example);
+absent flags fall back to the XML defaults.
+
+**Requires `pack-ai-video`.** The declared skills
+(`song-to-script`, `scene-expander`, `video-director`,
+`character-consistency`, `motion-choreographer`) ship in that pack; on a
+global-only install Step 1's `validate-deps.sh` fails fast with the
+missing-id list instead of an opaque mid-run error — install the pack
+and re-run.
+
+**Block-on-ambiguity:** a missing/empty images directory, an unreadable
+audio file, contradictory mode flags (`--brief` *and* `--auto-script`),
+contradictory character flags (`--character` *and* `--no-character`), or
+a contradictory provider flag halts the run with a precise message — no
+silent best-guess.
+
+## Inputs
+
+| Input | Required | Meaning |
+|---|---|---|
+| `<images-dir>` | yes | Folder of reference stills (`.png` / `.jpg`). When they contain a consistent human subject the on-screen identity is locked from them; otherwise the run is style-only (Step 6). |
+| `<song-file>` | yes | Audio track (`.mp3` / `.wav` / `.m4a`). Defines total duration and, in `--auto-script` mode, the scene structure. |
+| `--brief "<text>"` | one of brief/auto | Operator-written description of the video (mood, story, settings). |
+| `--auto-script` | one of brief/auto | Derive the script from the song via the `song-to-script` skill. |
+| `--scene-durations <list>` | no | Manual cut points (e.g. `0:00-0:15,0:15-0:30,…`). Overrides probe timing — the honest path when the track is flat (probe `method: interval`). |
+| `--character` / `--no-character` | no | Force character-lock on/off. Default: auto-detect a subject in `<images-dir>`. |
+| `--keep-native-audio` | no | Keep provider-generated audio instead of dropping it for the song (Step 8). |
+
+## Steps
+
+### 1. Validate dependencies
+
+```bash
+scripts/ai-video/lib/validate-deps.sh .agent-src.uncondensed/commands/video/from-song.md
+```
+
+Fails fast with the missing-id list if any declared persona / skill is
+absent from `.agent-src/personas/` or `.agent-src/skills/`. No network
+call has happened yet.
+
+Then confirm the **runtime helper scripts** exist and are executable —
+`scripts/ai-video/lib/probe-audio.sh`, `scripts/ai-video/lib/load-config.sh`,
+`scripts/ai-video/stitch.sh` — so a missing script fails here (with the
+path), not mid-run at Step 2/9.
+
+**Non-interactive contexts.** When stdin is not a TTY (CI, cron, headless
+harness) the command cannot prompt: it requires `--brief` or
+`--auto-script`, an explicit `--character`/`--no-character`, and
+`--auto-pick`, and refuses live calls outright. Missing any → fail fast
+with usage, never a deadlocked prompt.
+
+### 2. Validate inputs + media-governance input gate
+
+- `<images-dir>` exists and holds ≥1 `.png`/`.jpg`. Empty or missing →
+  halt, list what was found.
+- `<song-file>` exists and is a readable audio container (`ffprobe`
+  returns an audio stream). Probe its length + structure now:
+  ```bash
+  scripts/ai-video/lib/probe-audio.sh <song-file>
+  ```
+  Emits `{duration, method, warning?, sections:[…]}` (deterministic, no
+  network). `duration` becomes the target length of the final cut. A
+  `method: interval` result (flat / brick-walled track) is surfaced to
+  the operator with the suggestion to pass `--scene-durations` for
+  musical cuts — never presented as beat-synced.
+- **Media-governance input gate (mandatory).** Before any render,
+  consult the project-local media policies per
+  [`media-governance-routing`](../../rules/media-governance-routing.md):
+  - reference stills or brief depict a **real person's likeness** →
+    [`likeness`](../../../agents/settings/policies/media/likeness.md);
+  - a **recognised public figure** →
+    [`public-figures`](../../../agents/settings/policies/media/public-figures.md);
+  - the track is a **recognisable commercial song / a real artist's
+    voice** or the brief asks to clone one →
+    [`voice-cloning`](../../../agents/settings/policies/media/voice-cloning.md).
+  On a match: **refuse-and-surface** (one question per turn) — do not
+  best-guess past a likeness / rights concern.
+
+### 3. Cost + duration guard (theory of failure)
+
+Refuse, with a precise message, **before** loading providers:
+
+- a song longer than the configured cap (default 8 min) — a 45-minute
+  track would launch a runaway paid render;
+- a derived/briefed scene count above the cap (default 40 scenes).
+
+The operator raises a cap explicitly (`--max-duration` / `--max-scenes`)
+if they really mean it; the guard never silently proceeds.
+
+### 4. Load config + resolve providers
+
+Source `scripts/ai-video/lib/load-config.sh`. Resolve image / video
+provider: command flag → `agents/.ai-video.xml` default → fail with the
+available-providers list. A **malformed XML** or a default/flag naming a
+provider with no `scripts/ai-video/adapters/<id>.sh` → fail fast here
+with `provider '<id>' not found in adapters/` and the available list;
+never a cryptic shell error mid-run. Surface the resolved provider's **lifecycle
+tier** per
+[`provider-lifecycle-discipline`](../../rules/provider-lifecycle-discipline.md);
+all shipped adapters are `experimental` today, so the refuse-and-surface
+path fires before any live call. For a music-video the **song is the
+master track**, so a video provider with `audio-native=false` (e.g.
+`kling`) is fine; native-audio providers (`gemini-veo`, `sora`) still
+work — their audio is dropped at mux time in Step 8 unless
+`--keep-native-audio` or a lip-sync scene needs it.
+
+### 5. Select script mode (block on ambiguity)
+
+- `--brief` and `--auto-script` both present → halt: "Pick one source
+  for the script."
+- Exactly one present → use it.
+- **Neither present → ask, then stop and wait:**
+
+  ```
+  > How should I build the scene script?
+  >
+  > 1. From a description — I'll write the scenes to your brief
+  > 2. From the song — I'll derive scenes + timing from the audio
+  ```
+
+### 6. Build the timed scene script
+
+Run the [`song-to-script`](../../skills/song-to-script/SKILL.md) skill
+with the Step 2 probe result:
+
+- **Brief mode** — the operator brief is the creative source; the audio
+  sections drive only the **cut timing**.
+- **Auto mode** — the skill infers mood/energy per section and writes
+  both action and timing; vocal sections with lyrics populate
+  `dialogue:` for lip-sync.
+- `--scene-durations` (if passed) overrides probe timing verbatim.
+
+Output: `<project>/script.md` summing to the song length (reconciled in
+Step 8). Present the script, the section→scene map, **and the probe
+`method`**, then continue.
+
+### 7. Character lock — optional, auto-detected
+
+Detect whether `<images-dir>` contains a consistent **human subject**.
+**Consistent** = the same recognisable face recurs across the **majority**
+of stills. The branch:
+
+- **Consistent subject (or `--character`)** → run `character-consistency`
+  once, seeding it with `<images-dir>`. Writes `<project>/character.json`
+  (subject, palette, wardrobe, prop, seed) reused verbatim downstream;
+  the stills are passed as `ref_images` so the locked identity matches.
+- **No face at all (or `--no-character`)** → **skip the lock**, tell the
+  operator, and run **style-only continuity**: the reference stills set
+  palette / setting / look, and `song-to-script` runs in style mode
+  (abstract / landscape / visualiser videos are first-class — a face is
+  never required). Zero-face input is **not** an error.
+- **Ambiguous** (faces in only some stills, or several *distinct* faces
+  with no clear lead) → **block and ask** which subject to lock or whether
+  to go style-only. Never silently pick a mode on a coin-flip; the
+  `--character`/`--no-character` flags pre-answer this for non-interactive
+  runs.
+
+### 8. Render scenes (reuse from-script path) — ONE batch cost gate
+
+For each scene in `<project>/script.md`, run Steps 3–7 of
+[`/video:from-script`](from-script.md) verbatim: `scene-expander` →
+blueprint → `video-director` eight-block image prompt → operator pick →
+`motion-choreographer` → video adapter.
+
+**Single batch COST confirmation (not per-step).** `AIV_DRYRUN=true` is
+the default. Before the *first* live call, print the whole plan in one
+prompt — image+video adapter, models, total scene count, and total
+estimated cost — and refuse to continue without an explicit operator
+confirmation (a literal yes) in this turn (mirrors
+[`non-destructive-by-default`](../../rules/non-destructive-by-default.md)).
+Once confirmed, the run proceeds through every scene + stitch + mux
+without re-prompting **for cost**. The one remaining interactive surface
+is `from-script`'s per-scene **operator-pick** (best-of-N still
+selection) — a creative choice, not a spend gate; `--auto-pick` collapses
+it to best-of-1 so the batch is fully unattended (required in
+non-interactive contexts).
+
+**Mid-batch failure + abort.** A per-scene adapter failure (rate-limit
+`429`, provider content-policy refusal, network drop) **halts the batch**,
+writes the completed-scene state to `<project>/`, and surfaces which
+scene failed and why — it does not skip ahead or burn the rest of the
+budget. `SIGINT` (Ctrl-C) writes state and exits clean. Re-running the
+command resumes from the completed scenes (the "one project per
+invocation" resume path), so a failed or aborted run is recoverable
+without re-paying for finished scenes.
+
+### 9. Stitch + master-audio mux + duration reconciliation
+
+1. Build `<project>/manifest.json` with every scene as **video-only**
+   (`audio_embedded: false`) so the concat is silent — unless
+   `--keep-native-audio`, or a scene is flagged `character: talking`
+   (lip-sync), where dropping audio would desync mouth motion: keep that
+   scene's native audio and surface the mixed-audio decision rather than
+   silently dubbing.
+2. Concatenate:
+   ```bash
+   scripts/ai-video/stitch.sh <project>/manifest.json <project>/cut.mp4
+   ```
+3. **Reconcile duration explicitly** — compare the silent cut length to
+   the song:
+   - cut == song (±1.0 s) → mux straight through;
+   - cut **shorter** → offer `--loop-last` (hold the final scene) or
+     `--retime` (re-derive Step 6 timing); default = trim audio to the
+     cut with a short audio fade-out on the tail;
+   - cut **longer** → default = hard-trim video to the song length.
+
+   Never pad silently — **and never trim silently either**: whichever
+   default fires, report it concretely ("trimmed scene 12 from 18.0 s to
+   3.4 s to match the 3:45 song" / "faded the song tail by 0.6 s"), so the
+   operator sees exactly what the reconciliation did. Then mux the song as the master track:
+   ```bash
+   ffmpeg -loglevel error -y -i <project>/cut.mp4 -i <song-file> \
+     -map 0:v:0 -map 1:a:0 -c:v copy -c:a aac -shortest <project>/final.mp4
+   ```
+4. **Mandatory AI-generation disclosure (non-removable).** Embed the
+   disclosure metadata into `final.mp4` per
+   [`disclosure`](../../../agents/settings/policies/media/disclosure.md)
+   and, where the container supports it, a provenance tag per
+   [`transparency`](../../../agents/settings/policies/media/transparency.md).
+   The run **cannot complete** without the disclosure — it is not a flag.
+
+### 10. Report
+
+Print: project slug, final MP4 path, song length vs. cut length, probe
+`method`, scenes rendered, scenes skipped, script mode (`brief` | `auto`),
+subject mode (`character` | `style`), provider + lifecycle tier,
+**media-governance gate result** (pass / refused-and-surfaced — the audit
+record), **reconciliation action** taken (Step 9.3), disclosure
+confirmed, estimated cost (live mode) or `dry-run` marker. No commit. No
+push.
+
+## Rules
+
+- **No commit, no push, no PR.** Pipeline produces artefacts; the
+  operator chooses what to ship.
+- **Dry-run is the default.** One batch confirmation gates all live
+  calls — never a per-step interrogation, never a silent live run.
+- **Media governance is a hard gate.** Input likeness / public-figure /
+  voice checks block before render; the output MP4 always carries a
+  non-removable AI-generation disclosure.
+- **The song is the master audio track.** Provider-native audio is
+  dropped at mux unless `--keep-native-audio` or a lip-sync scene needs
+  it (surface the conflict, never silently dub).
+- **Cost + duration are guarded.** Over-cap songs / scene counts are
+  refused before any provider loads.
+- **Character lock is optional.** A no-face image folder produces a
+  style-only video; never abort for a missing subject.
+- **Block on ambiguity** — never silently best-guess the script source,
+  scene timing, provider, or character mode.
+- **Honest cut framing.** A flat track's `interval` cuts are never
+  presented as beat-synced; point the operator at `--scene-durations`.
+- **One project per invocation.** Re-running on the same project resumes
+  from existing artefacts (skips completed scenes); a failed or aborted
+  batch is recoverable this way without re-paying for finished scenes.
+- **Kill-switch.** Ships `lifecycle: experimental` · `install.default:
+  false`. Disable = remove the command + `song-to-script` skill (then
+  regenerate the projected tool trees); the `/video` orchestrator
+  degrades gracefully on an absent sub-command.
+
+## Policies
+
+- [`likeness`](../../../agents/settings/policies/media/likeness.md) ·
+  [`public-figures`](../../../agents/settings/policies/media/public-figures.md) ·
+  [`voice-cloning`](../../../agents/settings/policies/media/voice-cloning.md) —
+  input gate (Step 2).
+- [`disclosure`](../../../agents/settings/policies/media/disclosure.md) ·
+  [`transparency`](../../../agents/settings/policies/media/transparency.md) —
+  mandatory output disclosure (Step 9.4).
+
+## See also
+
+- [`/video:from-script`](from-script.md) — same render path from a
+  hand-written script
+- [`/video:scene`](scene.md) — single-scene iteration
+- [`/video:stitch`](stitch.md) — re-stitch after operator edits
+- [`song-to-script`](../../skills/song-to-script/SKILL.md) — audio →
+  timed scene script
+- [`scripts/ai-video/lib/adapter-contract.md`](../../../scripts/ai-video/lib/adapter-contract.md)