videoclaw 3.0.0-alpha.1

package/docs/PRODUCTION_WORKFLOW.md

@@ -0,0 +1,148 @@
+# Production Workflow
+
+VideoClaw should feel like one reliable production workflow, not a catalog of
+commands. Keep the advanced command surface available, but introduce users
+through these three doors.
+
+For human operators, start with `vclaw studio --dry-run`. It maps goals like
+presenter video, UGC campaign, music video, copy-reference, review, and publish
+to the deterministic CLI commands described below.
+
+The matching workflow skills are:
+
+1. `video-production-handoff` for one project from creation into review and
+   publish handoff.
+2. `video-review-ui-qa` for browser review, mobile/desktop QA, and Review UI to
+   CLI truth alignment.
+3. `video-portfolio-ops` for multi-project reports, CSV/Obsidian handoff, and
+   operator queues.
+4. `video-release-readiness` for package-shape, generated-artifact, and release
+   verification evidence.
+
+For a short runbook that can be handed to an operator, use
+[`OPERATOR_HANDOFF.md`](./OPERATOR_HANDOFF.md).
+
+## 1. Make A Campaign Video
+
+Use this when the operator has an intent and needs a reviewed, provider-ready
+short-form video project.
+
+```bash
+vclaw video create "A 20s product story for ..." --project <slug> --production-mode director
+
+# Choose one review path.
+vclaw video review-ui --project <slug>
+
+# Or, when completed storyboard still candidates already exist:
+vclaw video review-autopilot --project <slug>
+
+vclaw video status --project <slug>
+```
+
+`review-ui` serves the packaged Review UI by default, so installed CLI users do
+not need a source checkout or a project-local `tmp/review-station/index.html`.
+Reserve `--ui-path` for testing a local replacement UI. `review-autopilot` is
+the non-interactive counterpart: use it instead of browser review only when the
+project already has completed storyboard still candidates and the operator wants
+the agent to lock the handoff.
+
+The expected result is a project with a brief, storyboard, locked stills,
+artifact-backed 4K handoff assets, a passing review report, and one clear next
+action. The system must not claim a publish handoff until `review-report.json`
+has `verdict: "pass"` and `metrics.publishReady: true`.
+
+Every storyboard-producing command (`create`, `storyboard`, `clone-execute`,
+`storyboard-from-clone`, `storyboard-review`, and `director-preflight
+--apply-content-fixes`) also emits `artifacts/story-bible.json` at
+storyboard-write time — a deterministic continuity bible (cast, settings, props,
+per-scene timeline, and continuity notes) derived from the brief, storyboard, and
+character profiles. It spends no credits and calls no providers; its path is
+surfaced as `storyBiblePath` in the command JSON output and recorded on the
+storyboard checkpoint. Downstream generation reads it so scenes and regenerations
+stay continuity-consistent. After director content-fixes are applied, the bible
+is regenerated to match.
+
+## 2. Review And Fix A Project
+
+Use this when a project exists but the operator is unsure whether it is safe to
+continue.
+
+```bash
+vclaw video status --project <slug>
+vclaw video next-actions
+vclaw video doctor-project --project <slug>
+vclaw video review-ui --project <slug>
+```
+
+Trust order:
+
+1. `status` tells the current stage and stale review state.
+2. `next-actions` tells the highest-priority human or agent action.
+3. `doctor-project` verifies artifacts and checkpoints.
+4. `review-ui` is the visual station for fixing images, references, 4K assets,
+   and final assembly checks.
+
+If these disagree, treat it as a product bug and fix the canonical artifact or
+derived next-action logic before continuing.
+
+## 3. Manage A Portfolio
+
+Use this when multiple video projects are in flight.
+
+```bash
+vclaw video metrics
+vclaw video report
+vclaw video export-csv
+vclaw video sync-obsidian
+```
+
+Portfolio views should communicate production truth for non-technical operators:
+what is blocked, what needs review, what is stale, what is ready to publish, and
+where spend or provider risk is accumulating. CSV exports include
+`reviewReportVerdict` and `reviewPublishReady` so spreadsheet handoffs can filter
+on the same review truth as the CLI and Review UI.
+
+For release handoff, keep source checkout commands and installed CLI commands
+separate. In this repository, use `node dist/cli/vclaw.js ...` only after
+building. Installed users should see `vclaw ...` examples.
+
+## Authoring aid: multi-shot prompts
+
+For a compressed cinematic clip, `vclaw video multi-shot` scaffolds a timecoded,
+non-repeating-camera shot plan (`cinematic-15s`, `seedance-10s`, `veo-8s`, or
+`runway-10s`), validates the hard rules (char budget, contiguous timecodes,
+metadata block), and can author prose end-to-end with `--auto`:
+
+```bash
+vclaw video multi-shot --plan                       # timecode scaffold + camera grid
+vclaw video multi-shot --validate --file prompt.txt # enforce the rules (nonzero exit on error)
+vclaw video multi-shot --plan --from-storyboard --project demo --scene 0 --route seedance-direct
+```
+
+It can run standalone, or hydrate action/characters/location defaults from a
+project storyboard scene with `--from-storyboard`. Project status/readiness
+summarize the latest persisted `multi-shot-prompt` artifact for review.
+Full reference: [`docs/CLI_REFERENCE.md`](./CLI_REFERENCE.md#multi-shot-prompt).
+
+## Production Readiness Rules
+
+- One source of truth: review handoff readiness comes from `review-report.json`.
+- Simple review command rule: `video review --verdict pass` is for projects that
+  already have equivalent review evidence outside the Review UI. Director image
+  handoffs should use `review-ui` or `review-autopilot` so publish readiness is
+  derived from locked stills, artifact-backed 4K assets, and final approvals.
+- No stale approval: if storyboard content changed after `storyboard.md`, refresh
+  the storyboard review before execution.
+- No marker-only handoff: a 4K/upscaled still must be an artifact-backed scene
+  candidate, not just a browser marker.
+- Keep verification output separate from source: local `outputs/`,
+  `.playwright-mcp/`, nested project `outputs/`, and Review UI screenshots
+  should remain ignored unless a fixture update is explicitly intentional.
+- No hidden provider switch: provider routes fail hard instead of silently
+  falling back.
+- Dry-run never demotes assets: the assets checkpoint preserves its
+  `asset-manifest` reference across all `execute` paths — including
+  `execute --dry-run` when the plan is not yet ready — instead of overwriting it
+  to `failed`, so a dry-run preview cannot strand a project's asset stage.
+- Every user-facing surface should give the same next action for the same
+  project state.

package/docs/PROJECT_LAYOUT.md

@@ -0,0 +1,262 @@
+# Project Layout
+
+This doc describes the canonical on-disk structure of a `videoclaw`
+project — the unit `vclaw video init <slug>` creates and every
+downstream stage operates on.
+
+## Slug rules
+
+Enforced at `vclaw video init` time:
+
+| Rule | Constraint |
+|---|---|
+| Allowed chars | `[a-z0-9-]` |
+| Must start with | `[a-z0-9]` (not `-`) |
+| Must end with | `[a-z0-9]` (not `-`) |
+| Length | 3–64 chars |
+| Disallowed substrings | `--`, leading `.`, reserved names (`history`, `artifacts`, `checkpoints`, `events`, `state`, `outputs`, `assets`, `obsidian`, `characters`, `notes`, `tmp`) |
+| Argv guard | Reject anything that looks like a flag (`^-`). Prevents the historical bug where `vclaw video init --project foo` parsed `--project` as the slug. |
+
+Recommended slug template when the user doesn't provide one:
+`<yyyy-mm-dd>-<noun>-<noun>` (e.g., `2026-05-25-disco-monster`).
+
+## Canonical layout
+
+```
+projects/<slug>/
+│
+├── project.json                # MANIFEST (see "project.json shape" below)
+├── storyboard.md               # Director-mode human-readable approval doc
+│                                 (absent in storyboard-mode until storyboard
+│                                 stage)
+│
+├── artifacts/                  # CANONICAL machine-readable outputs.
+│   │                             JSON only. Every file MUST have a schema
+│   │                             in schemas/video/artifacts/.
+│   ├── brief.json
+│   ├── storyboard.json
+│   ├── story-bible.json        # Deterministic continuity bible (cast,
+│   │                             settings, props, scene timeline, continuity
+│   │                             notes) auto-emitted at storyboard-write time.
+│   ├── asset-manifest.json
+│   ├── scene-candidates.json
+│   ├── scene-selection.json
+│   ├── reference-sheets.json
+│   ├── execution-plan.json
+│   ├── execution-report.json
+│   ├── review-report.json
+│   ├── publish-report.json
+│   ├── analyze-output.json
+│   ├── clone-plan.json
+│   ├── multi-shot-prompt.json  # Written only when `vclaw video multi-shot
+│   │                             --project <slug>` is used; absent for
+│   │                             standalone (no --project) invocations.
+│   ├── filmmaking-prompts.json # Character sheet, 9-panel storyboard grid,
+│   │                             reference map, and Seedance prompt packets.
+│   └── history/                # Snapshots of artifacts/ files on overwrite.
+│                                 Append-only. One subdir per artifact:
+│                                 history/brief/<ts>.json.
+│
+├── checkpoints/                # ONE FILE per stage. Tracks approval state,
+│   ├── brief.json                who approved when, retry count, verdict.
+│   ├── storyboard.json
+│   ├── assets.json
+│   ├── review.json
+│   └── publish.json
+│
+├── characters/                 # CANONICAL identity store for this project.
+│   └── characters.json
+│
+├── events/                     # Append-only timeline. JSONL.
+│   └── events.jsonl              Payloads use project-relative paths only.
+│
+├── notes/                      # Human-authored or model-authored MD.
+│   │                             Free-form. Anything NOT a canonical
+│   │                             JSON artifact lives here.
+│   └── (markdown files)
+│
+├── outputs/                    # DERIVED. Final encoded media only.
+│   ├── final/<slug>-<mode>.mp4   Created by publish stage.
+│   ├── scene-0.mp4               Per-scene renders.
+│   ├── scene-1.mp4
+│   └── ...                       (Gitignored at project level.)
+│
+├── preview.html                # DERIVED. Final portal showcase.
+├── edit.html                   # DERIVED. Editor edit/check portal.
+├── review.html                 # DERIVED. Editor review portal.
+├── client-review.html          # DERIVED. Client review portal.
+├── compare.html                # DERIVED. Version/run comparison portal.
+├── project-audit.jsonl         # Append-only preview portal generation/publish audit.
+│
+├── assets/                     # DERIVED. Intermediate visual assets.
+│   ├── storyboard-grid.png       Deterministic 3x3 production board from
+│   │                             `vclaw video storyboard-grid`.
+│   ├── storyboard/               Per-scene stills.
+│   ├── upscaled/                 Upscaled variants.
+│   └── ...                       (Gitignored.)
+│
+├── obsidian/                   # DERIVED. Mirror of canonical artifacts
+│                                 in Obsidian-friendly MD. Created by
+│                                 `vclaw video obsidian-export`.
+│                                 (Gitignored.)
+│
+└── state/                      # Derived state cache. Created on init by
+                                  ensureProjectWorkspace.
+```
+
+## Directory disposition
+
+| Directory | Always-present on init | Schema-enforced | Gitignored at project level |
+|---|---|---|---|
+| `project.json` | yes | yes | no (commit) |
+| `storyboard.md` | director-mode only | n/a (free-form) | no |
+| `artifacts/` | yes (empty) | **yes — every file** | no |
+| `artifacts/history/` | yes (mkdir at init) | yes | no |
+| `checkpoints/` | yes (empty) | yes (per-stage shape) | no |
+| `characters/` | yes (empty) | yes (characters.json shape) | no |
+| `events/` | yes (empty) | line shape enforced | no |
+| `state/` | yes (empty) | internal cache | no |
+| `notes/` | on demand | no (MD) | no |
+| `outputs/` | on demand | n/a (media) | **yes** |
+| `preview.html` / `edit.html` / `review.html` / `client-review.html` / `compare.html` | on portal generation | n/a (static HTML) | no |
+| `project-audit.jsonl` | on portal generation/publish | JSONL event shape | no |
+| `assets/` | on demand | n/a (media) | **yes** |
+| `obsidian/` | opt-in command | n/a (MD mirror) | **yes** |
+
+## Git tracking
+
+`vclaw video init` does **not** write a per-project `.gitignore` —
+`handleVideoInit` only writes `project.json`, the pending `brief`
+checkpoint, and the `project.initialized` event. Any gitignore handling
+is at the repo root, not per-project.
+
+The derived directories — `outputs/`, `assets/`, `obsidian/` — are
+re-generable from canonical artifacts and are the candidates to ignore
+if you wire up repo-root gitignore rules. `artifacts/`, `checkpoints/`,
+`characters/`, `events/`, `notes/`, `project.json`, and `storyboard.md`
+are **canonical by design** so a project is reproducible from its
+on-disk state.
+
+## `project.json` shape
+
+The manifest is `VideoProjectManifest` (`src/video/workspace.ts`). The
+pipeline manifest is **embedded inline** — there is no versioned
+reference and no `schemaVersion`. On init, `handleVideoInit` writes:
+
+```json
+{
+  "slug": "fresh-proof",
+  "productionMode": "director",
+  "createdAt": "2026-05-06T02:20:19.421Z",
+  "updatedAt": "2026-05-06T02:20:19.421Z",
+  "pipeline": { "name": "director", "stages": ["..."] },
+  "currentStage": "brief",
+  "lastCompletedStage": null,
+  "lastCheckpointStatus": "pending"
+}
+```
+
+Required fields:
+
+- `slug` — the project slug.
+- `productionMode` — `"storyboard"` or `"director"`.
+- `createdAt` / `updatedAt` — ISO timestamps.
+- `pipeline` — the **full embedded `VideoPipelineManifest` object**
+  (not a `pipelineRef` string). In practice only `pipeline.name` is read
+  back by downstream code.
+- `currentStage` / `lastCompletedStage` / `lastCheckpointStatus` —
+  stage-machine cursor. On init these are `"brief"`, `null`, and
+  `"pending"`.
+
+Optional fields, written only by `updateProjectManifestMetadata`
+(`owner`, `priority`, `dueDate`, `tags`, `blockedBy`, `blockedReason`)
+and `updateProjectManifestCinemaProfile` (`cinemaProfile`). There is no
+`schemaVersion`, no `pipelineRef`, no `createdBy`, and no nested
+`metadata` object.
+
+### `routePreference` (optional)
+
+An ordered list of provider route ids that overrides the built-in
+per-mode default ordering when `buildExecutionPlan` (`plan`/`produce`)
+picks a route:
+
+```json
+{
+  "routePreference": ["dreamina-useapi", "seedance-direct", "veo-useapi"]
+}
+```
+
+- Valid ids: `veo-useapi`, `runway-useapi`, `dreamina-useapi`,
+  `seedance-direct` (the `ProviderRouteId` union). An unknown id makes
+  `plan`/`produce` **fail at plan time** — free, before any submission.
+- Listed routes are tried first, in order; any built-in default route not
+  listed is appended as fallback, so a **partial** preference is safe (a
+  preferred route that turns out unavailable falls through to the rest).
+- **Absent/empty ⇒ byte-identical** to the built-in defaults
+  (`storyboard`: `veo-useapi` → `seedance-direct`; `director`:
+  `seedance-direct` → `veo-useapi`).
+
+Use it when a project must pin a route the default order wouldn't pick —
+e.g. an image-to-video project whose references are remote URLs needs
+`dreamina-useapi` (which uploads the bytes) rather than `seedance-direct`
+(which requires the provider to fetch the URL itself).
+
+## Event log shape
+
+`events.jsonl` lines follow the `VideoProjectEvent` envelope
+(`src/video/events.ts`): `{ type, recordedAt, payload? }`. There is no
+`id`/ULID and no `source` field.
+
+```jsonl
+{"type":"artifact.review-report.written","recordedAt":"2026-05-06T21:54:52.404Z","payload":{"artifactPath":"artifacts/review-report.json","verdict":"pass"}}
+```
+
+Readers split on newlines and `JSON.parse` each non-empty line;
+`appendProjectEvent` fills `recordedAt` if absent. Event-payload paths
+are project-relative by convention.
+
+## Artifact schema coverage guardrail
+
+The build pipeline includes `check:artifact-schema-coverage`
+(`scripts/check-artifact-schema-coverage.mjs`), which asserts:
+
+1. Every artifact name passed to `writeArtifact(workspace, '<name>', ...)`
+   in `src/video/**/*.ts` has a matching
+   `schemas/video/artifacts/<name>.schema.json`.
+2. Every schema in `schemas/video/artifacts/` has either a matching
+   `writeArtifact()` call OR is in the script's
+   `KNOWN_ALTERNATE_WRITERS` allowlist (audit-pending; some artifacts
+   are written via specialized helpers rather than the typed
+   `writeArtifact()` shim).
+
+**Modes:**
+
+- Default (advisory) — prints any drift but always exits 0. This is
+  what `check:release-readiness-lite` invokes, so the guardrail
+  reports status inline without blocking the release-readiness
+  pre-flight while the allowlist is being burned down.
+- `--strict` — exits 1 on drift. Wire into CI gates / pre-commit hooks
+  when you want hard enforcement. Currently zero unexpected drift
+  with the allowlist applied.
+
+Current allowlist (9 schemas needing per-artifact audit): `analyze-output`,
+`clone-plan`, `execution-plan`, `multi-shot-prompt`, `publish-report`,
+`reference-sheets`, `review-report`, `scene-candidates`, `scene-selection`.
+The audit work is tracked in `MERGE_PLAN.md` §A2.
+
+## Slug validation implementation
+
+The slug rules above are enforced by `validateInitSlug()` in
+`src/cli/vclaw.ts`, called from the `init` command before any
+filesystem operation. Test coverage in
+`src/tests/cli-init-slug-validation.test.ts` (6 cases):
+
+1. rejects `--project` as the slug (the historical argv-as-slug bug)
+2. rejects uppercase / whitespace / dots / underscores / leading dots / leading dashes
+3. rejects reserved per-project directory names
+4. rejects consecutive `--`
+5. rejects too-short / too-long
+6. accepts a well-formed slug (`2026-05-25-disco-monster`)
+
+Each failure mode has a distinct error message; the argv-as-slug case
+explicitly names the bug to make the fix discoverable.

package/docs/PROMPT_QUALITY.md

@@ -0,0 +1,214 @@
+# Prompt-quality preflight
+
+Seven mechanical anti-pattern checks driven by the Seedance 2.0 Handbook. They
+run inside `director-preflight` against every storyboard scene's text. They are
+**warnings by default** and promote to blocking **errors** when
+`DIRECTOR_STRICT_PROMPT_QUALITY=1` is set in the environment.
+
+The module (`src/video/prompt-quality.ts`) is pure: no disk I/O, no global
+state beyond reading the severity env var at runtime. The checks surface
+through the existing `director-preflight` JSON output — there is no new CLI
+command and no new smoke.
+
+## Issue codes
+
+| Code | What it catches | Threshold |
+|---|---|---|
+| `prompt-quality-adjective-soup` | A single clause piling up comma-separated modifiers | `> ADJECTIVE_SOUP_THRESHOLD` (default 4) |
+| `prompt-quality-multiple-actions` | Serial third-person-present actions in one clause | `> 1` |
+| `prompt-quality-multiple-camera-moves` | More than one camera-move family per prompt | `> 1` movement family |
+| `prompt-quality-style-word-overload` | Stacked "cinematic/epic/atmospheric" style words | `> STYLE_WORDS_THRESHOLD` (default 3) |
+| `prompt-quality-literary-emotion` | Inner-state language (`feels`, `profound sadness`) instead of visible behavior | any match |
+| `prompt-quality-overlong` | Prompt word count above the single-shot budget | `> OVERLONG_WORDS_THRESHOLD` (default 120) |
+| `negative-direction` | A negated motion/tempo clause (`no`/`don't`/`avoid`/`without`/`never` + `slow-motion`/`blur`/`motion`/`movement`/`zoom`/`camera shake`) — these models ignore negated direction | any match outside the sanctioned-negation allowlist (on-screen text, specular kill, anti-plastic) |
+
+Vocabularies live in `CAMERA_MOVE_VOCABULARY`, `SHOT_TYPE_VOCABULARY`, and
+`STYLE_VOCABULARY` in `src/video/prompt-quality.ts` and are deliberately short
+and conservative.
+
+Camera movement is checked separately from shot size. Movement families include
+`push-in`, `pull-out`, `tracking`, `orbit`, `static` / `locked-off`, `crane reveal`,
+`pan`, `tilt`, `zoom`, `handheld`, and `steadicam`. Shot-size terms such as
+`wide shot`, `medium shot`, `close-up`, and `establishing shot` do not count as
+movement conflicts, so `wide shot, slow push-in` is valid while `push-in and orbit`
+still raises `prompt-quality-multiple-camera-moves`.
+
+For Seedance image-to-video work, keep imported still-image guidance separate
+from motion prompting. The still image should carry composition, identity,
+wardrobe, props, lighting, and framing. The Seedance prompt should preserve the
+source image and add one visible action plus one camera move for a short clip.
+
+## Dialogue duration fit
+
+`director-preflight` also runs a dialogue timing check from `dialogue-fit.ts`.
+It is separate from the seven prompt-quality anti-pattern checks because it uses
+a duration budget rather than prompt wording alone.
+
+Default behavior:
+
+1. scenes without `durationSeconds` use a 15-second target
+2. spoken dialogue is estimated at about 2.5 words per second
+3. `DIALOGUE_DURATION_OVERFLOW` is emitted when the estimated spoken duration
+   exceeds the scene target
+4. the issue is a warning by default
+5. `DIRECTOR_STRICT_DIALOGUE_FIT=1` promotes it to a blocking error
+
+This check catches scripts that look fine as text but cannot be delivered
+naturally inside the clip duration.
+
+## Sample output
+
+A scene with adjective soup and a second camera move produces
+`director-preflight` JSON like:
+
+```json
+{
+  "pass": true,
+  "warnings": [
+    {
+      "severity": "warn",
+      "code": "prompt-quality-adjective-soup",
+      "scope": "scene:0",
+      "message": "Scene 1: clause has 6 adjectives (threshold: 4): ...",
+      "suggestion": "Tighten scene wording before approval; see docs/PROMPT_QUALITY.md."
+    }
+  ],
+  "errors": []
+}
+```
+
+Under `DIRECTOR_STRICT_PROMPT_QUALITY=1` the same issues appear on `errors`,
+`pass` flips to `false`, and `execute`/`produce` is blocked (director-mode
+preflight failures gate provider submission).
+
+## Promoting to blocking
+
+```bash
+DIRECTOR_STRICT_PROMPT_QUALITY=1 vclaw video director-preflight --project <slug>
+```
+
+Team workflows that want prompt-quality to be a release gate can export the
+variable in CI so every run treats handbook violations the same as content
+hazards. Teams still iterating can leave it unset and treat the warnings as
+review cues.
+
+## Integration points
+
+- Emitted by `checkPromptQuality` in `src/video/director-preflight.ts`.
+- Surfaces in the existing `vclaw video director-preflight` JSON payload.
+- Flows into `director-preflight`'s `result.warnings` / `result.errors`
+  buckets, so all downstream consumers (tests, CI checks, storyboard.md
+  approval review) see them automatically.
+
+## Multi-shot cinematic prompt validation
+
+`runMultiShotChecks(prompt, preset)` enforces the structural rules for
+multi-shot cinematic prompts. It lives in the same module as
+`runPromptQualityChecks` (`src/video/prompt-quality.ts`) and is invoked
+via:
+
+```bash
+vclaw video multi-shot --validate
+```
+
+Unlike the seven anti-pattern checks above, all issues from
+`runMultiShotChecks` are **always `error` severity** — they are
+structural requirements of the multi-shot format, not stylistic
+guidelines, so they cannot be downgraded to warnings by omitting
+`DIRECTOR_STRICT_PROMPT_QUALITY`.
+
+### Presets
+
+Four presets ship today, each declaring its own duration, shot-count
+window, per-shot duration bounds, and character budget. The default
+remains `cinematic-15s`; the others target a specific provider's clip
+duration:
+
+| Preset | total | shot range | shot count | maxChars |
+|---|---|---|---|---|
+| `cinematic-15s` *(default)* | 15 s | 2–5 s | 3–7 | 1500 |
+| `seedance-10s` | 10 s | 2–5 s | 2–5 | 1500 |
+| `veo-8s` | 8 s | 2–4 s | 2–4 | 1500 |
+| `runway-10s` | 10 s | 2–5 s | 2–5 | 1000 |
+
+### Issue codes
+
+| Code | What it catches |
+|---|---|
+| `multi-shot-timecode-parse` | A timecode in the prompt cannot be parsed |
+| `multi-shot-timecode-start` | First timecode is not `00:00` |
+| `multi-shot-timecode-gap` | Consecutive timecodes overlap or leave a gap |
+| `multi-shot-timecode-total` | Timecodes do not sum to the preset's `totalSeconds` |
+| `multi-shot-shot-duration` | A shot's duration falls outside the preset's `[minShotSeconds, maxShotSeconds]` |
+| `multi-shot-shot-count-out-of-range` | Parsed shot count is outside the preset's `[minShots, maxShots]` window. Message branches on under vs over |
+| `multi-shot-overlong` | Total prompt character count exceeds the preset's `maxChars` |
+| `multi-shot-repeated-parameter` | A consecutive pair of shots shares the same shot size, lens, angle, or camera movement |
+| `multi-shot-missing-metadata` | The required `Location / Style / Audio` metadata block is absent |
+
+Matching for consecutive-shot-repeat checks is hyphen/space-insensitive,
+so `push in` and `push-in` are treated as the same value.
+
+### Canonical vocabularies
+
+The shot-parameter vocabularies used for consecutive-repeat detection are
+defined in `src/video/prompt-quality.ts` and are now canonical for the
+entire module:
+
+- `SHOT_SIZE_VOCABULARY` — e.g. `wide shot`, `medium shot`, `close-up`
+- `LENS_VOCABULARY` — e.g. `wide angle`, `telephoto`, `macro`
+- `ANGLE_VOCABULARY` — e.g. `eye level`, `low angle`, `bird's eye`
+- `CAMERA_MOVE_VOCABULARY` — movement families shared with `runPromptQualityChecks`
+
+### Smoke
+
+```bash
+npm run smoke:multi-shot
+```
+
+Builds the project, runs `vclaw video multi-shot --plan`, then validates
+a fixture at `references/video/.fixtures/multi-shot-valid.txt` — a
+no-network plan → validate round-trip.
+
+## filmmaking-prompts artifact lint (`prompt-lint`)
+
+Distinct from the storyboard-scene anti-pattern checks above,
+`lintFilmmakingPrompts` (`src/video/prompt-lint.ts`) is a separate, pure
+validator that runs over a **`filmmaking-prompts.json` artifact** (not
+storyboard scenes). It is exposed as its own command:
+
+```bash
+vclaw video prompt-lint (--project <slug> | --file <path>) [--register prose|numeric] [--cast <Name:descriptor> ...] [--brand <token> ...]
+```
+
+Per Seedance packet it checks the 10-block order (text-driven packets only),
+word count (warn outside the **280–600 words/packet** window), the required
+video blocks `SUBJECT LOCK` / `CAPTURE REALISM` / `CAMERA CAPTURE` (text-driven
+only), the single-full-frame grid guard whenever a storyboard-grid reference is
+attached (else error — the grid leaks as a moving split-screen), no Kelvin/degree
+numeric tokens in a prose-register packet, and optional proper-name / brand scrubs
+when `--cast` / `--brand` are passed. Output is
+`{ packets: [{ sceneIndex, issues[] }], ok }`, where `ok` is true **iff** no
+`error`-severity issue is raised on any packet.
+
+### Issue codes
+
+| Code | What it catches |
+|---|---|
+| `seedance-block-order` | 10-block order violated (text-driven packets only) |
+| `word-count` | Packet word count outside the 280–600 window (warning) |
+| `missing-required-block` | A required video block (`SUBJECT LOCK` / `CAPTURE REALISM` / `CAMERA CAPTURE`) is absent |
+| `grid-guard-missing` | A storyboard-grid reference is attached but the single-full-frame guard is missing (error) |
+| `numeric-in-prose` | Kelvin/degree numeric tokens in a `prose`-register packet |
+| `proper-name-leak` | A proper name survives the cast scrub (only when `--cast` is passed) |
+| `brand-leak` | A brand token survives the scrub (only when `--brand` is passed) |
+
+## Follow-on roadmap
+
+- Per-project threshold overrides (today: hardcoded constants).
+- LLM-backed checks for subtler anti-patterns ("show don't tell", beat
+  structure).
+- Auto-fix suggestions, analogous to `DIRECTOR_AUTO_FIX_CONTENT=1` for
+  content hazards.
+- Tie into the Tier-2 prompt-structure schema (item 9 in
+  `MASTER_PLAN_ALIGNMENT.md`) so each check points at the matching schema
+  section.