@event4u/agent-config 5.4.1 → 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/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.