@event4u/agent-config 5.5.0 → 5.6.0

package/.agent-src/commands/image/analyse.md

@@ -0,0 +1,51 @@
+---
+model_tier: high
+name: image:analyse
+tier: 2
+cluster: image
+sub: analyse
+description: Analyse a character image down to the smallest mole and diff it against a canon — per-feature spec, OCR tattoo text, severity-ranked drift report.
+personas: [hollywood-director]
+skills: [image-analyser]
+suggestion:
+  eligible: true
+  trigger_description: "analyse a character image, check character accuracy, does this render match the canon, find what drifted"
+  trigger_context: "user supplies an image path/URL (and optionally a character id) and wants a detailed feature extraction or canon diff"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /image:analyse
+
+Run the [`image-analyser`](../../skills/image-analyser/SKILL.md) skill on an
+image. Args: `<path-or-url>` (required) `[character-id]` (optional — the canon
+to diff against, e.g. `veikko`).
+
+## Steps
+
+1. **Resolve the image** — accept a path or public URL. Apply the input gate
+   (refuse blurry / sub-resolution / unreadable; per the `image-ocr` contract).
+2. **Governance check** — real-person likeness → route through
+   [`media-governance-routing`](../rules/media-governance-routing.md) first.
+3. **Run `image-analyser`** — section-by-section extraction (the "down to the
+   smallest mole" pass), OCR sub-pass for lettered tattoos, hard-feature
+   enhancement on low-confidence regions. Emit the Layer-2 observation
+   (per-feature `confidence` + `unverifiable[]`).
+4. **If `[character-id]` is given** — diff against
+   `agents/reference/ai-video/<project>/characters/<id>.json` per the rubric in
+   [`canon-spec.md`](../../skills/image-analyser/canon-spec.md): per-feature
+   `match|partial|miss`, the canon-breaking hard gate, per-section scores.
+
+## Output
+
+1. Observation JSON (Layer 2).
+2. Diff table (if a canon was given): `feature · severity · expected · observed · verdict · confidence · fix`.
+3. Verdict line: `GATE: pass|FAIL` + per-section scores.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR.**
+- **The image wins over the text** — never invent an unseen feature; mark it `unverifiable`.
+- **Read-only** — analysis only; generation is `/image:create`.

package/.agent-src/commands/image/create.md

@@ -0,0 +1,53 @@
+---
+model_tier: high
+name: image:create
+tier: 2
+cluster: image
+sub: create
+description: Generate a character image to spec — assemble a max-fidelity, anchors-first prompt from a Canon Spec; governance- and provider-gated, dry-run by default.
+personas: [hollywood-director]
+skills: [image-creator, character-consistency]
+suggestion:
+  eligible: true
+  trigger_description: "generate this character, render to spec, create the image, make every feature match the canon"
+  trigger_context: "user supplies a character id (and a scene brief) and wants a maximally-accurate generation prompt or render"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /image:create
+
+Run the [`image-creator`](../../skills/image-creator/SKILL.md) skill. Args:
+`<character-id>` (required) `"<scene>"` (setting + pose). Optional: a prior
+`/image:analyse` diff to fold in (loop mode).
+
+## Steps
+
+1. **Governance gate FIRST** — real-person likeness → route through
+   [`media-governance-routing`](../rules/media-governance-routing.md) +
+   `agents/settings/policies/media/` before emitting anything.
+2. **Provider gate** — read the resolved provider's tier; non-stable
+   (experimental/deprecated/community) → surface the tier and **ask** before
+   any live call (per
+   [`provider-lifecycle-discipline`](../rules/provider-lifecycle-discipline.md)).
+   `AIV_DRYRUN=true` is the default.
+3. **Assemble the prompt, anchors first** — load the Canon Spec; front-load the
+   hard-to-render `identity_anchors` (heterochromia, hair-split), then physique,
+   face + marks, per-location tattoos (exact `text`), outfit, jewelry; add the
+   asymmetry block + negative block + engine settings.
+4. **Generate** through the existing adapter layer (`scripts/ai-video/adapters/`)
+   only on explicit confirmation. **Verify** the output with `/image:verify`.
+
+## Output
+
+1. Generation prompt — anchors · positive · asymmetry · negative · engine settings.
+2. Provider + tier line (the audit entry).
+3. The `/image:verify` call to run on the result.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR.**
+- **No live provider call without explicit per-turn confirmation** + a stable (or confirmed non-stable) provider.
+- **Never claim "canon-perfect"** without an `image-analyser` verify pass (per `verify-before-complete`).

package/.agent-src/commands/image/verify.md

@@ -0,0 +1,48 @@
+---
+model_tier: high
+name: image:verify
+tier: 2
+cluster: image
+sub: verify
+description: Verify a candidate render against its canon — run the analyser in loop mode, emit the gate verdict + remaining diff, halt-and-surface on non-pass.
+personas: [hollywood-director]
+skills: [image-analyser]
+suggestion:
+  eligible: true
+  trigger_description: "verify this render, does the generated image pass the canon, re-check fidelity after regeneration, loop-verify"
+  trigger_context: "user has a generated candidate image + a character id and wants the canon-fidelity gate verdict"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /image:verify
+
+The verify step of the fidelity loop — runs
+[`image-analyser`](../../skills/image-analyser/SKILL.md) on a candidate render
+against its canon and reports the loop stop-state. Args: `<path-or-url>`
+(required) `<character-id>` (required).
+
+## Steps
+
+1. **Analyse + diff** — run `image-analyser` on the candidate against
+   `agents/reference/ai-video/<project>/characters/<id>.json` (the rubric in
+   [`canon-spec.md`](../../skills/image-analyser/canon-spec.md)).
+2. **Apply the loop stop conditions** — PASS (canon-breaking gate clear + every
+   per-section score ≥ threshold) · plateau · oscillation · budget.
+3. **Non-PASS → halt and surface** the best candidate + its remaining diff +
+   the concrete correction directives to feed back into `/image:create`. Never
+   silently accept drift (per `verify-before-complete`).
+
+## Output
+
+1. `GATE: pass|FAIL` + per-section scores.
+2. Remaining diff (canon-breaking + major misses) with per-miss fixes.
+3. Loop verdict: `PASS` | `continue (feed fixes to /image:create)` | `halt (plateau/oscillation/budget)`.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR.**
+- **Read-only** — verification only; regeneration is `/image:create`.
+- **The human approves the final** — the loop proposes, never declares canon-perfect on its own.

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

@@ -0,0 +1,69 @@
+---
+model_tier: inherit
+name: image
+tier: 2
+cluster: image
+description: Character-image fidelity orchestrator — analyse, create, and verify a character image against its canon. Routes to analyse, create, verify.
+type: orchestrator
+suggestion:
+  eligible: true
+  trigger_description: "analyse a character image against a canon, generate a character image to spec, verify a render's fidelity, character-image accuracy"
+  trigger_context: "user supplies a character image or character id and wants analysis, generation, or canon-fidelity verification"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /image
+
+Top-level orchestrator for the `/image:*` family — character-image
+**fidelity** work: analyse an image down to the smallest mole, generate one
+to spec, verify a candidate against its **Canon Spec**. Schema, rubric, and
+the create→analyse→regenerate loop: [`canon-spec.md`](../../skills/image-analyser/canon-spec.md).
+Generation is a paid surface: every live provider call is **dry-run /
+refuse-and-surface by default** and needs explicit per-turn confirmation per
+[`provider-lifecycle-discipline`](../rules/provider-lifecycle-discipline.md).
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/image:analyse <path-or-url> [character-id]` | `commands/image/analyse.md` | Extract a full per-feature spec from an image; diff against a canon, flag drift down to the smallest mole |
+| `/image:create <character-id> "<scene>"` | `commands/image/create.md` | Assemble a max-fidelity, anchors-first generation prompt from a Canon Spec; governance- + provider-gated |
+| `/image:verify <path-or-url> <character-id>` | `commands/image/verify.md` | Loop-verify a candidate render against its canon; emit the gate verdict + remaining diff |
+
+## Dispatch
+
+1. Parse `/image <sub-command> [args]`. Sub-command = first token; match
+   against the table's exact names only. A token that is a **file path or
+   URL** (contains `/`, `.`, or a known image extension — e.g. `img_2.png`,
+   `shots/veikko.jpg`) is NOT a sub-command: it is the image argument for
+   `analyse` / `verify`. Never treat `img_2.png` as the `analyse`
+   sub-command. On this ambiguity → ask rather than best-guess.
+2. Look up the sub-command and execute its file verbatim with the remaining args.
+3. Unknown / missing sub-command → print the table and ask:
+
+   > 1. analyse — extract + diff an image against a canon
+   > 2. create — generate a character image to spec
+   > 3. verify — loop-verify a render's fidelity
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** — subcommands never do this.
+- **Do NOT chain subcommands.** One `/image <sub>` per turn.
+- **Generation is a paid, gated surface.** `create` never fires a live
+  provider call without surfacing the provider tier and an explicit
+  per-turn confirmation; mirrors
+  [`non-destructive-by-default`](../rules/non-destructive-by-default.md)
+  and [`provider-lifecycle-discipline`](../rules/provider-lifecycle-discipline.md).
+- **Governance first.** A real-person likeness routes through
+  [`media-governance-routing`](../rules/media-governance-routing.md)
+  before any prompt is emitted.
+- **Edit `.agent-src.uncondensed/` only.** Generated mirrors regenerate.
+
+## See also
+
+- [`image-analyser`](../../skills/image-analyser/SKILL.md) · [`image-creator`](../../skills/image-creator/SKILL.md) — the skills these commands invoke.
+- [`canon-spec.md`](../../skills/image-analyser/canon-spec.md) — schema, fidelity rubric, fidelity loop.
+- [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md) — `image` cluster registration.

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

@@ -164,14 +164,37 @@ 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.
+- **Auto mode** — skill infers mood/energy per section, writes action +
+  timing; vocal sections populate `dialogue:` for lip-sync **from the
+  transcribed vocal map**, not the brief.
 - `--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.
+Output: `<project>/script.md` summing to song length (reconciled in
+Step 8). Present script, section→scene map, **and probe `method`**, then
+continue.
+
+#### 6a. Vocal map + sign-off gate (lip-sync / singer-assigned runs)
+
+```
+TIMING AND SINGER COME FROM THE TRANSCRIBED AUDIO, NEVER A SKELETON OR
+A GUESSED STRETCH. NO PAID RENDER UNTIL THE OPERATOR SIGNS OFF THE MAP.
+```
+
+Governed by [`media-sync-ground-truth`](../../rules/media-sync-ground-truth.md).
+When the track has vocals **and** the run assigns singers / lip-sync:
+
+1. `song-to-script` emits `<project>/vocal-map.json`
+   (`[{start, end, text, singer}]`) built by **transcribing the real
+   audio** (OpenAI `/v1/audio/transcriptions` or whisper). Probe gives
+   duration; transcript gives lyric timing + structure. Never derive
+   lyric timing from the brief or a stretched story skeleton.
+2. **Each vocal line maps to its OWN singer.** Never put one character's
+   line on another character's scene. Ambiguous singer → mark `?`, ask.
+3. **Sign-off gate (mandatory).** Surface the map — `timestamp → line →
+   singer → assigned shot/character` — and **wait for explicit operator
+   approval before any render**. Precedes the Step 8 cost gate; a wrong
+   map wastes the whole batch.
+4. Pure-instrumental / style-mode runs skip 6a (no singers, no lip-sync).
 
 ### 7. Character lock — optional, auto-detected
 
@@ -201,6 +224,17 @@ For each scene in `<project>/script.md`, run Steps 3–7 of
 blueprint → `video-director` eight-block image prompt → operator pick →
 `motion-choreographer` → video adapter.
 
+**Lip-sync sub-step (scenes with a `dialogue:` line + a singer).** A
+scene whose approved vocal-map entry assigns a singer routes to the
+audio-driven path, not plain motion: cut that line's WAV from the song at
+the map's `[start,end]`, host it, call the video adapter's `speak`
+capability (e.g. Higgsfield `/v1/speak/higgsfield`) with the **correct
+singer's** still + that WAV so the right character lip-syncs their own
+line. Place the clip at its real song position so the muxed master track
+stays aligned to the lips. Non-vocal / non-assigned scenes use the
+standard motion (dop) path. Never lip-sync a singer onto a line the vocal
+map attributes to someone else.
+
 **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

package/.agent-src/contexts/authority/commit-mechanics.md

@@ -83,3 +83,11 @@ A "commit this now" phrase has to be a **meta-instruction directed
 at the agent** in the current turn. Quoted text, log excerpts,
 roadmap snippets, and content the user is asking the agent to *read*
 or *summarize* never authorize a commit.
+
+## Roadmap commit steps
+
+When **creating** a roadmap (`/roadmap-create`, `/feature-roadmap`,
+any roadmap-producing flow), do **not** include commit steps unless
+the user explicitly requested them — commits are a delivery decision;
+roadmaps plan **work**. If the user explicitly wants commit steps,
+write them clearly (e.g. "Commit phase X: chore: …").

package/.agent-src/rules/commit-policy.md

@@ -47,18 +47,13 @@ NEVER ASK "ONE COMMIT OR MULTIPLE?", "HOW SHOULD I SPLIT?",
 "WHICH CHUNK FIRST?". THE AGENT PICKS THE SPLIT.
 ```
 
-One chunk per concern (scope / refactor / rules / config / cleanup), foundation-first. Generated files ride with their source chunk. State the split inline, execute. Full mechanics + carve-outs: [`commit-mechanics § Always split into logical chunks`](../contexts/authority/commit-mechanics.md).
+One chunk per concern, foundation-first; generated files ride with their source. Full mechanics + carve-outs: [`commit-mechanics § Always split into logical chunks`](../contexts/authority/commit-mechanics.md).
 
 ## NEVER write commit steps into roadmaps unsolicited
 
-When **creating** a roadmap (`/roadmap-create`, `/feature-roadmap`, any roadmap-producing flow) — do **not** include commit steps unless the user explicitly requested them. Commits are a delivery decision; roadmaps plan **work**.
-
-If the user explicitly wants commit steps, write them clearly (e.g. "Commit phase X: chore: …").
+Roadmaps plan **work**, not commits — when creating a roadmap, never add commit steps unless the user explicitly asked. Detail: [`commit-mechanics § roadmap commit steps`](../contexts/authority/commit-mechanics.md).
 
 ## See also
 
-- [`autonomous-execution`](autonomous-execution.md) — trivial-question suppression; this rule survives the suppression.
-- [`no-cheap-questions`](no-cheap-questions.md) — commit asks are cheap by construction; this rule is the canonical Iron Law.
 - [`scope-control`](scope-control.md) — git-ops permission gate (push, merge, branch, PR, tag).
-- [`/commit`](../commands/commit.md) — split and commit with confirmation.
-- [`/commit:in-chunks`](../commands/commit/in-chunks.md) — auto-split, no confirmation.
+- [`no-cheap-questions`](no-cheap-questions.md) — canonical Iron Law. · [`autonomous-execution`](autonomous-execution.md) · [`/commit`](../commands/commit.md) · [`/commit:in-chunks`](../commands/commit/in-chunks.md).

package/.agent-src/rules/media-sync-ground-truth.md

@@ -0,0 +1,58 @@
+---
+type: "auto"
+tier: "2a"
+description: "Audio-synced video (lip-sync, beat-cuts, music video) — derive timing + singer from the transcribed real audio, never a planning doc; sign off the vocal map before any paid render"
+triggers:
+  - keyword: "lip-sync"
+  - keyword: "lip sync"
+  - keyword: "lipsync"
+  - keyword: "music video"
+  - keyword: "beat-cut"
+  - keyword: "/video:from-song"
+  - keyword: "vocal map"
+  - phrase: "cut to the beat"
+  - phrase: "sing the"
+  - phrase: "mit den lippen"
+  - phrase: "lippen passend"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# Media Sync — Ground Truth Is the Audio
+
+## The Iron Law
+
+```
+NEVER LIP-SYNC OR CUT A MUSIC VIDEO OFF A PLANNING DOC.
+TRANSCRIBE THE REAL AUDIO FIRST. TIMING AND SINGER COME FROM THE
+TRANSCRIPT, NEVER FROM A DREHBUCH SKELETON OR A GUESSED TIME-STRETCH.
+WRONG-SINGER-ON-WRONG-LINE IS A RENDER-MONEY-BURNING FAILURE.
+MAP → SIGN-OFF → RENDER. NO BLIND BATCHES.
+```
+
+For audio-synced video (lip-sync, beat-aligned cuts, music videos), truth for **timing** + **who-sings-what** is the **actual audio** — transcribed to timestamped lines with a singer per segment. A creative skeleton (story / Drehbuch) encodes *intent*, not the delivered audio; a guessed stretch makes it worse. Lip-sync amplifies every mismatch — wrong mouth on wrong words is instantly, glaringly wrong, and the render already cost money.
+
+## What this requires
+
+1. **Transcribe the real audio** → timestamped lines (OpenAI `/v1/audio/transcriptions` or whisper). Probe gives duration; transcript gives structure. Build `<project>/vocal-map.json`: `[{start, end, text, singer}]`.
+2. **Label singers onto the transcribed timeline**, never the reverse. A who-sings doc only *labels* lines; never *defines* the timeline.
+3. **Align cuts to real lyrical/musical phrases** — not arbitrary fixed-length windows.
+4. **Each vocal line lip-syncs to its OWN singer.** Never cross-assign one character's mouth onto another's part.
+5. **Sign-off gate** — surface the vocal map (timestamp → line → singer → shot) for explicit operator approval **before** any paid render.
+6. **Lip-sync sparingly** — only where a frontal close-up of the correct singer supports it; model lip-sync on singing is imperfect, so use cinematic motion (dop) for the rest.
+
+## Failure modes
+
+- Stretched `story.md` as singer/timing source → one character mouths another's lines (canonical odins-beard failure).
+- Fixed 5s windows landing off-phrase → jarring cuts + weird mouth motion.
+- Firing a multi-clip batch before the vocal map is approved → budget burned on throwaway output.
+- Trusting a guessed time-stretch to "match" the song length.
+
+## See also
+
+- [`/video:from-song`](../commands/video/from-song.md) — vocal-map + sign-off gate (Step 6) and lip-sync sub-step (Step 8).
+- [`song-to-script`](../skills/song-to-script/SKILL.md) — builds the transcribed vocal map.
+- [`media-governance-routing`](media-governance-routing.md) — sibling tier-2a media rule (likeness / disclosure).
+- [`non-destructive-by-default`](non-destructive-by-default.md) — the paid-render confirmation floor the sign-off gate builds on.

package/.agent-src/skills/image-analyser/SKILL.md

@@ -0,0 +1,121 @@
+---
+model_tier: high
+name: image-analyser
+description: "Use to analyse a character image down to the smallest mole and diff against a canon — per-feature spec, OCR-reads tattoo text, flags drift. Triggers 'analyse this image', 'match the canon'."
+personas:
+  - hollywood-director
+domain: product
+workspaces:
+  - small-business
+packs:
+  - ai-video
+lifecycle: experimental
+trust:
+  level: experimental
+install:
+  default: false
+  removable: true
+---
+
+# image-analyser
+
+> Read a character image, extract **every** feature (face marks, per-location
+> tattoos incl. lettered text, exact hair split, per-eye colour, jewelry,
+> asymmetry), diff against the character's canon so drift is caught **before** it
+> ships. Output feeds [`image-creator`](../image-creator/SKILL.md) + the fidelity
+> loop. Schema + rubric + loop: [`canon-spec.md`](canon-spec.md).
+
+## When to use
+
+- "Analyse this image / character", "does this match the canon", "check
+  character accuracy", "find what's wrong with this render".
+- Verify step of the fidelity loop (after `image-creator` generates).
+- Bootstrap a Canon Spec from an authoritative portrait (*image wins over text*).
+
+NOT for: scene/motion review (→ `video-director`), non-character art
+(→ `canvas-design`), cross-scene token locking (→ `character-consistency`,
+which consumes this skill's output).
+
+## Input
+
+- Image **path or public URL** (per the `vision-analyze` shape).
+- Optional: reference Canon Spec / character id (e.g.
+  `agents/reference/ai-video/<project>/characters/<id>.json`) to diff against.
+- **Input gate** (per the `image-ocr` contract): refuse blurry / sub-resolution
+  / unreadable inputs with a clear reason rather than guessing.
+
+## Procedure
+
+1. **Read the image.** A vision-capable model views it directly. No new
+   dependency; if a cloud-vision/OCR backend is wanted, ask first
+   (`missing-tool-handling`).
+2. **Section-by-section extraction** (the "down to the smallest mole" pass) —
+   one pass per section: `physique`, `face` (+ marks/scars/moles), `hair`
+   (colour, split line, length, braids, shaved areas), `eyes` (per-eye colour,
+   heterochromia, ring, kohl), `tattoos` (per body location: motif, style,
+   and **text** if lettered), `jewelry`, `outfit`, cross-feature `asymmetry`.
+3. **OCR sub-pass for lettered tattoos** — read runic/block text exactly
+   (knuckle runes, `S-U-S-I`, scalp runes, mic glyph), never approximate.
+4. **Hard-feature enhancement** — for a faint mole, an unclear hair-split line,
+   or heterochromia in shadow: re-pass on a crop/zoom of that region **before**
+   marking it. Only then mark genuinely unresolvable features `unverifiable`.
+5. **Emit the `observation` layer** (Layer 2 in `canon-spec.md`): observed value
+   + `confidence` (high|medium|low) per feature + `unverifiable[]`. Confidence
+   lives here, **never** written back onto the canon (Layer 1).
+6. **If a reference is given — diff + score** per the rubric: per-feature
+   `match|partial|miss`, the **canon-breaking hard gate**, per-section scores,
+   advisory roll-up, `low`-confidence misses flagged `needs-better-image`
+   (not a hard fail). Emit concrete correction directives per miss.
+
+## The one rule that overrides everything
+
+**The image wins over the text.** Extracting from an authoritative portrait and
+the canon text disagrees → record what is *visible*. Verifying a candidate
+against the canon → the canon's `identity` is the truth. Never invent a feature
+the image does not show (per `direct-answers` — no invented facts); mark it
+`unverifiable` instead.
+
+## Output format
+
+1. **Observation JSON** (Layer 2) — observed features + per-feature confidence + `unverifiable[]`.
+2. **Diff table** (only if a reference was given): `feature · severity · expected · observed · verdict (match/partial/miss) · confidence · fix`.
+3. **Verdict line:** `GATE: pass|FAIL (canon-breaking misses: …)` + per-section scores + advisory roll-up.
+
+## Example (safe vs unsafe)
+
+- Safe: `eyes — canon-breaking — expected blue-left/green-right — observed both blue — MISS (high) — fix: regenerate with heterochromia anchor front-loaded`.
+- Unsafe: reporting `eyes — match` when the green eye is out of frame. If unseen → `unverifiable`, not `match`.
+
+## Gotchas
+
+- Hands/knuckles often out of frame → tattoo text `unverifiable`, not a miss.
+- A strong face must not mask a broken hair split — that is why scores are
+  per-section, not one number.
+- Symmetric characters (Sigrún, Bjørn) vs the asymmetric one (Veikko): check
+  the left/right invariant explicitly for the Loki-marked character.
+
+## Do NOT
+
+- Do NOT score an unseen feature as `match` — if it is out of frame or
+  unresolvable, mark it `unverifiable` (per `direct-answers`, no invented facts).
+- Do NOT write `confidence` / `unverifiable` back onto the canon (Layer 1) — they
+  are the analyser's epistemic state (Layer 2) and never mutate the truth layer.
+- Do NOT collapse the rubric to a single number — a strong face must never mask a
+  canon-breaking hair/eye miss; scores stay per-section with a hard gate.
+- Do NOT approximate lettered tattoo text — OCR it exactly or mark it `unverifiable`.
+- Do NOT analyse a real-person likeness without routing through
+  `media-governance-routing` first.
+
+## Policies
+
+Character images can carry a real person's likeness. Before analysing a
+real-person likeness, route through `media-governance-routing` and consult
+`agents/settings/policies/media/likeness.md` + `public-figures.md`. Fictional
+characters (e.g. the odins-beard trio) are exempt; the routing decision is the
+agent's, in-session.
+
+## Related skills
+
+- [`image-creator`](../image-creator/SKILL.md) — consumes the diff; the loop partner.
+- [`character-consistency`](../character-consistency/SKILL.md) — consumes the load-bearing token subset of the `identity` layer.
+- [`canon-spec.md`](canon-spec.md) — schema, rubric, fidelity loop.

package/.agent-src/skills/image-analyser/canon-spec.md

@@ -0,0 +1,109 @@
+# Character Canon Spec — schema, fidelity rubric, fidelity loop
+
+Shared contract consumed by [`image-analyser`](SKILL.md) and
+[`image-creator`](../image-creator/SKILL.md). Defines the structured truth a
+character image is reconciled against, how a candidate is scored, and how the
+create→analyse→regenerate loop converges.
+
+> **Design lock (AI-council, anthropic/claude-sonnet-4-5 + openai/gpt-4o, 2-round
+> debate, user-invoked):** keep **ontology and epistemology separate**.
+> `confidence` is a property of a *verification attempt*, **not** of the
+> character — so it never lives on a canon leaf. Three layers below. The rubric
+> is a **vector + hard gate**, never one scalar. The loop uses **plateau +
+> oscillation detection**, not a bare iteration count.
+
+## The three layers
+
+A character record is split so each layer changes for a different reason:
+
+### Layer 1 — `identity` (immutable canon · the character truth)
+
+What the character *is*. Per-leaf `severity` only — **no confidence**, no
+verification state. Source of truth = the canon (the book + its authoritative
+portraits; *the image wins over the text*).
+
+```jsonc
+{
+  "id": "veikko",
+  "identity": {
+    "physique": { "value": "lean wiry athletic, 1.82m, broad shoulders narrow hips", "severity": "major" },
+    "face":     { "value": "...", "marks": [ { "value": "tiny scar above right mouth corner", "severity": "minor" } ] },
+    "hair":     { "value": "vertical split: LEFT pitch-black / RIGHT platinum-blond, long open to chest, no shaved sides", "severity": "canon-breaking" },
+    "eyes":     { "left": "ice-blue", "right": "forest-green", "heterochromia": true, "severity": "canon-breaking" },
+    "tattoos":  [ { "location": "central chest", "motif": "Vegvisir compass", "style": "blackwork", "severity": "canon-breaking" },
+                  { "location": "left chest", "motif": "Loki serpent biting tail", "severity": "canon-breaking" },
+                  { "location": "knuckles", "motif": "block letters", "text": "S-U-S-I", "severity": "major" } ],
+    "jewelry":  [ { "value": "massive round silver watch, RIGHT wrist", "severity": "major" } ],
+    "outfit_variants": [ { "name": "studio-casual", "value": "black sleeveless tank under open leather vest" } ]
+  },
+  "identity_anchors": ["hair", "eyes", "tattoos[central chest]", "tattoos[left chest]", "jewelry[watch]"],
+  "notes": "Loki = asymmetry everywhere (hair, eyes, tattoos)."
+}
+```
+
+- **`severity`** ∈ `canon-breaking | major | minor` — how much a miss matters.
+- **`identity_anchors`** — the must-never-drift list. **Derived rule:** every
+  `severity: canon-breaking` leaf MUST be an anchor; anchors MAY also name
+  cross-feature invariants (e.g. "asymmetry") that no single leaf captures.
+- Relationship to [`character-consistency`](../character-consistency/SKILL.md):
+  its existing token JSON (`agents/reference/ai-video/<project>/characters/<id>.json`)
+  is the **load-bearing subset** of this `identity` layer. The Canon Spec is the
+  richer superset; `image-analyser` emits the token subset into that exact file
+  so there is **one** character record, not two.
+
+### Layer 2 — `observation` (verification state · the analyser's output)
+
+What a *specific image* shows, per attempt. **This** is where `confidence`
+lives (`high | medium | low`, the `image-ocr` pattern) plus `unverifiable[]`
+for features the image cannot resolve (occluded / low-res). Never written back
+onto Layer 1.
+
+```jsonc
+{
+  "source": "agents/tmp/odins-beard/img_2.png", "character": "veikko",
+  "observed": { "hair": { "value": "near-uniform light/blond, split not distinct", "confidence": "high" },
+                "eyes": { "value": "both read blue; green not visible", "confidence": "medium" } },
+  "unverifiable": ["tattoos[knuckles].text (hands out of frame)"]
+}
+```
+
+### Layer 3 — `generative_hints` (prompt-assembly guidance)
+
+How to render the identity well: anchor ordering (hard-to-render anchors first
+— heterochromia, hair-split), per-engine caveats, negative-prompt seeds. Read
+by `image-creator`; never confused with the canon itself.
+
+## Fidelity rubric — vector + hard gate (not one scalar)
+
+A diff scores each observed feature `match | partial | miss`, then reports a
+**vector**, not a single number:
+
+1. **Canon-breaking gate (hard).** ANY `canon-breaking` leaf at `miss` → overall
+   **FAIL**, regardless of everything else. Non-negotiable.
+2. **Per-section scores.** `face`, `hair`, `eyes`, `tattoos`, `outfit`, `jewelry`
+   each get their own 0–100 (severity-weighted within the section). Surfaced
+   individually so a strong face can't mask a broken hair split.
+3. **Headline.** A weighted roll-up is shown for convenience but is **advisory** —
+   the gate + per-section vector decide pass/fail, not the roll-up.
+4. **Low-confidence discipline.** A `miss` on a `low`-confidence observation is
+   reported as `needs-better-image`, **not** counted as a hard miss — avoids
+   false-fail on an un-resolvable feature (re-pass per SKILL § enhancement first).
+
+## Fidelity loop — plateau + oscillation detection
+
+`image-creator` generates → `image-analyser` re-reads the output against the
+character's Layer-1 identity → diff → feed `canon-breaking` + `major` misses back
+as refined prompt directives → regenerate.
+
+Stop conditions (first to fire):
+
+- **PASS** — canon-breaking gate clear AND every per-section score ≥ its
+  threshold.
+- **Plateau** — N consecutive rounds with no per-section score improvement →
+  stop; the prompt is not the bottleneck (provider/seed is).
+- **Oscillation** — fixing feature X regresses a previously-passing feature Y
+  (tracked across rounds) → stop; surface the trade-off, do not thrash.
+- **Budget** — hard ceiling on rounds as a backstop.
+
+On any non-PASS stop → **halt and surface** the best candidate + its remaining
+diff for human review. **Never silently accept drift** (per `verify-before-complete`).

package/.agent-src/skills/image-analyser/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "image-analyser",
+  "description": "5 should-trigger + 5 should-not-trigger. Should-trigger covers the analyse / canon-diff / accuracy-check / drift-find / bootstrap-from-portrait paths (DE + EN). Should-not covers the near-miss neighbours whose vocabulary overlaps: scene/motion review (video-director), non-character art (canvas-design), cross-scene token lock (character-consistency), generation (image-creator), and document OCR (generic).",
+  "queries": [
+    {"q": "analyse this character image down to the last detail", "trigger": true},
+    {"q": "does img_2.png match the Charakterbuch canon?", "trigger": true},
+    {"q": "check this render for character accuracy — what drifted?", "trigger": true},
+    {"q": "vergleiche das Bild mit der Charakterbeschreibung, jedes Merkmal", "trigger": true},
+    {"q": "build a canon spec from this authoritative portrait", "trigger": true},
+    {"q": "turn this scene idea into a cinematic video prompt", "trigger": false, "note": "scene/motion → video-director"},
+    {"q": "design a poster for the band", "trigger": false, "note": "static non-character art → canvas-design"},
+    {"q": "lock this character's tokens so every scene reuses them", "trigger": false, "note": "cross-scene token lock → character-consistency"},
+    {"q": "generate Veikko in the forge scene to spec", "trigger": false, "note": "generation → image-creator"},
+    {"q": "extract the text from this scanned invoice", "trigger": false, "note": "plain document OCR, not character analysis"}
+  ]
+}