davinci-resolve-mcp 2.80.1 → 2.80.2

package/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.80.2
+
+Agent tooling only. Ten Claude Code skills that this repository has shipped and
+advertised were never loading; they load now. No runtime behavior changed and
+nothing under `src/` was touched.
+
+### Fixed
+
+- **The ten `.claude/skills/` domain skills were invisible to every agent.**
+  Claude Code discovers skills at `.claude/skills/<name>/SKILL.md`. All ten were
+  loose `.md` files at the top level of that directory — a layout the loader
+  does not scan — so `resolve-color`, `resolve-edit`, `resolve-conform`,
+  `resolve-delivery`, `resolve-audio`, `resolve-fusion`, `resolve-media-pool`,
+  `resolve-media-analysis`, `resolve-rough-cut`, and `resolve-mcp` never
+  appeared in a session, while the generated domain-routing block in `AGENTS.md`
+  and the index in `docs/README.md` both listed them as available. The failure
+  was silent: no warning, no error, no degraded mode. Each skill now lives in a
+  directory named for its frontmatter `name` (recorded as 100% renames, so
+  history follows), and both `docs/README.md` and
+  `scripts/agent-rules/README.md` — the file consulted when authoring a new
+  skill — state the directory requirement so the next one is not written back
+  into the bug.
+
+### Added
+
+- **Two opt-in `PreToolUse` guard scripts** for rules `AGENTS.md` has only ever
+  stated in prose. They ship as scripts and are deliberately *not* wired
+  repo-wide; `docs/README.md` carries the block to paste into a personal
+  gitignored `.claude/settings.local.json`. `frame_verification_guard.py`
+  refuses grade-applying actions on `timeline_item_color` until the session has
+  actually looked at a Resolve-rendered frame, and asks before `safe_copy_grade`
+  / `bulk_match_to_hero` push a whole-grade artifact across clips; `dry_run`
+  passes through. `source_media_guard.py` refuses shell commands that write,
+  move, or delete source media outside a scratch root — paths are normalized and
+  matched by whole path component, and a derivative-output directory
+  (`proxies`/`renders`/`exports`) exempts a *write* but never a delete or a
+  move, so a camera card with an `exports` folder is still a camera card. Its
+  docstring states what it cannot catch — extension-less directory deletes,
+  `find -delete`, `xargs rm`, and scripts that write media themselves — because
+  it is a tripwire for the common direct mistake, not a sandbox.
+- **Two review subagents** in `.claude/agents/`, run in their own context so
+  frame images stay out of the main session. `cut-reviewer` screens an assembled
+  timeline from its frames and is told explicitly that a metadata summary is not
+  a review, because assembling through an API succeeds loudly and fails quietly.
+  `grade-match-verifier` measures shot match numerically against the project's
+  R−B tolerance and must report the pixel count behind every masked
+  measurement — a near-empty skin mask returns a delta near zero and reads as a
+  perfect match.
+- **Two skills outside the domain routing.** `house-style` accumulates editorial
+  corrections so the same note is not given twice, and `/resolve-session`
+  reports connection, edition, project, timeline, and media-pool state before
+  editing begins.
+
+### Validation
+
+- Full offline suite: 2460 passed, 1 skipped — level with the v2.80.1 baseline,
+  as expected for a change that touches no runtime code.
+- Both guard scripts exercised against a 26-case matrix covering deny, ask, and
+  silent-allow: `ffprobe` reads, `ffmpeg` into scratch, `ffmpeg` overwriting a
+  card, chained `ffprobe && rm`, redirection onto a media file, glob `rm`,
+  quoted paths, writes into `renders`/`proxies`/`exports`, deletes out of those
+  same directories, `..` traversal, and ordinary repo commands (`git status`,
+  the test runner, `npm run build`).
+- No live Resolve validation: no behavior changed.
+
 ## What's New in v2.80.1
 
 A correction to the retime measurement contract published in v2.80.0, and a fix

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.80.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.80.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)

package/docs/README.md

@@ -47,19 +47,88 @@ Per-domain skills in `.claude/skills/` route craft ↔ live tools ↔ offline
 advanced tools automatically when an agent works in that domain. They are thin
 bridges — the authoritative depth stays in the kernels and guides above.
 
-- `resolve-mcp` (`.claude/skills/resolve.md`) — orientation/index: the map to the domain skills below (self-trigger; not an auto-loader)
-- `resolve-color` (`.claude/skills/color-grade.md`) — grading, looks, shot match, LUT/CDL/DRX
-- `resolve-edit` (`.claude/skills/timeline-edit.md`) — cutting, ranges, variants, changelist
-- `resolve-conform` (`.claude/skills/conform.md`) — conform, relink, finishing QC, grade tracing
-- `resolve-delivery` (`.claude/skills/delivery.md`) — render, deliverable QC, media/provenance
-- `resolve-fusion` (`.claude/skills/fusion.md`) — Fusion comps (titles, motion graphics, VFX)
-- `resolve-audio` (`.claude/skills/audio.md`) — audio/Fairlight tracks, buses, loudness, sync
-- `resolve-media-pool` (`.claude/skills/media-pool.md`) — media pool ingest, organize, multicam
-- `resolve-media-analysis` (`.claude/skills/media-analysis.md`) — source-safe media intelligence
+- `resolve-mcp` (`.claude/skills/resolve-mcp/SKILL.md`) — orientation/index: the map to the domain skills below (self-trigger; not an auto-loader)
+- `resolve-color` (`.claude/skills/resolve-color/SKILL.md`) — grading, looks, shot match, LUT/CDL/DRX
+- `resolve-edit` (`.claude/skills/resolve-edit/SKILL.md`) — cutting, ranges, variants, changelist
+- `resolve-conform` (`.claude/skills/resolve-conform/SKILL.md`) — conform, relink, finishing QC, grade tracing
+- `resolve-delivery` (`.claude/skills/resolve-delivery/SKILL.md`) — render, deliverable QC, media/provenance
+- `resolve-fusion` (`.claude/skills/resolve-fusion/SKILL.md`) — Fusion comps (titles, motion graphics, VFX)
+- `resolve-audio` (`.claude/skills/resolve-audio/SKILL.md`) — audio/Fairlight tracks, buses, loudness, sync
+- `resolve-media-pool` (`.claude/skills/resolve-media-pool/SKILL.md`) — media pool ingest, organize, multicam
+- `resolve-media-analysis` (`.claude/skills/resolve-media-analysis/SKILL.md`) — source-safe media intelligence
+
+Each skill is a directory containing `SKILL.md`. Claude Code does not discover
+loose `.md` files in `.claude/skills/`; a skill placed at the top level of that
+directory silently never loads.
+
+Two skills sit outside the domain routing:
+
+- `house-style` (`.claude/skills/house-style/SKILL.md`) — accumulated editorial
+  corrections, so the same note is not given twice. Claude-only; append to it
+  when an editorial decision is corrected.
+- `resolve-session` (`.claude/skills/resolve-session/SKILL.md`) — `/resolve-session`
+  connects, confirms edition and bridge, and reports project/timeline/pool state.
 
 The offline half of every one is the advanced server; see
 [Advanced Server](../resolve-advanced/README.md).
 
+## Claude Code Hooks and Subagents
+
+Two `PreToolUse` guards enforce rules `AGENTS.md` states in prose. They ship as
+scripts but are **not** wired up by default — the repository does not enable
+hooks on your behalf. Opt in by adding the block below to your own
+`.claude/settings.local.json` (gitignored, so it stays yours):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__davinci-resolve__(timeline_item_color|color_group)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/frame_verification_guard.py",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/source_media_guard.py",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Hooks are read at session start, so restart Claude Code after adding them. The
+two guards are:
+
+- `.claude/hooks/frame_verification_guard.py` — denies grade-applying actions on
+  `timeline_item_color` until the session has actually looked at a
+  Resolve-rendered frame, and asks before whole-grade artifacts
+  (`safe_copy_grade`, `bulk_match_to_hero`) overwrite hand-work. `dry_run`
+  passes through untouched.
+- `.claude/hooks/source_media_guard.py` — denies shell commands that write,
+  move, or delete source media outside a scratch root. Reads (`ffprobe`, and
+  `ffmpeg` writing into scratch) pass.
+
+Two review subagents in `.claude/agents/` run in their own context so frame
+images stay out of the main session:
+
+- `cut-reviewer` — screens an assembled timeline from its frames and reports on
+  pacing, shot order, continuity, and coverage gaps.
+- `grade-match-verifier` — measures shot match numerically from rendered frames
+  against the project's R−B tolerance, and reports mask pixel counts so an empty
+  skin mask cannot pass as a match.
+
 ## Authoring References
 
 - [Fuse + DCTL Authoring](authoring/fuse-dctl-authoring.md)

package/docs/kernels/audio-fairlight-kernel.md

@@ -88,7 +88,7 @@ patches audio **offline, no Resolve running**:
 
 Rule of thumb: plan/measure offline, apply mix/track changes live; use
 `fairlight` for bus work the scripting API can't reach. See the `resolve-audio`
-skill (`.claude/skills/audio.md`) and the `/audio_workflow` prompt.
+skill (`.claude/skills/resolve-audio/SKILL.md`) and the `/audio_workflow` prompt.
 
 ## Live Probe
 

package/docs/kernels/color-grade-kernel.md

@@ -134,7 +134,7 @@ Cross-server rules an agent must know:
 - **Deps.** The grading catalog needs `sharp`; call the advanced `capabilities`
   tool for live status and install hints.
 
-See the `resolve-color` skill (`.claude/skills/color-grade.md`) for the
+See the `resolve-color` skill (`.claude/skills/resolve-color/SKILL.md`) for the
 craft ↔ live ↔ offline routing and the frame-first rule.
 
 ## Live Probe

package/docs/kernels/fusion-composition-kernel.md

@@ -119,7 +119,7 @@ running**, via the `fusion` tool:
 Rule of thumb: author and verify the comp offline, then apply it live with
 `fusion_comp` `safe_add_tool` → `safe_set_inputs` → `safe_connect_tools` (the
 `to_api_calls` output maps directly onto those). See the `resolve-fusion` skill
-(`.claude/skills/fusion.md`) and the `/fusion_workflow` prompt.
+(`.claude/skills/resolve-fusion/SKILL.md`) and the `/fusion_workflow` prompt.
 
 ## Live Probe
 

package/docs/kernels/media-pool-ingest-kernel.md

@@ -137,7 +137,7 @@ actions):
 Rule of thumb: verify and inventory the card offline *before* importing, then
 import/organize live. `media` also serves the delivery side (see the
 `resolve-delivery` skill). See the `resolve-media-pool` skill
-(`.claude/skills/media-pool.md`) and the `/media_pool_workflow` prompt. Never
+(`.claude/skills/resolve-media-pool/SKILL.md`) and the `/media_pool_workflow` prompt. Never
 rename or derive camera originals without explicit approval.
 
 ## Live Evidence

package/docs/kernels/render-deliver-kernel.md

@@ -135,7 +135,7 @@ Rules an agent must know:
 - **Deps.** `deliverable`/`media` QC needs **ffmpeg + ffprobe on PATH** (GPL, not
   bundled) — call the advanced `capabilities` tool for status + install hints.
 
-See the `resolve-delivery` skill (`.claude/skills/delivery.md`) for the
+See the `resolve-delivery` skill (`.claude/skills/resolve-delivery/SKILL.md`) for the
 craft ↔ live ↔ offline routing.
 
 ## Live Evidence

package/docs/kernels/timeline-conform-interchange-kernel.md

@@ -121,7 +121,7 @@ Gotchas the live path shares:
 - **Deps.** `better-sqlite3` gates lineage/reverse/DB; `sharp`/ffmpeg gate frame
   compare — call the advanced `capabilities` tool.
 
-See the `resolve-conform` skill (`.claude/skills/conform.md`) for the
+See the `resolve-conform` skill (`.claude/skills/resolve-conform/SKILL.md`) for the
 craft ↔ live ↔ offline routing.
 
 ## Live Probe

package/docs/kernels/timeline-edit-kernel.md

@@ -196,7 +196,7 @@ Use these to answer "what changed between v3 and v4" or to hand a conform an
 accurate change list without opening either timeline. For conforming/relinking
 that change list, see the Timeline Conform / Interchange kernel and the
 `resolve-conform` skill; for the edit ↔ offline routing, see the `resolve-edit`
-skill (`.claude/skills/timeline-edit.md`).
+skill (`.claude/skills/resolve-edit/SKILL.md`).
 
 ## Development Guardrails
 

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.80.1"
+VERSION = "2.80.2"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.80.1",
+  "version": "2.80.2",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/scripts/agent-rules/README.md

@@ -24,7 +24,7 @@ cannot drift.
    | Platform | File(s) | Trigger | Source |
    |---|---|---|---|
    | Codex / OpenCode / Zed / others | `AGENTS.md` (`## Domain Routing` block) | always-on | generated block |
-   | Claude Code | `.claude/skills/*.md` | semantic (description) | hand-authored (rich) |
+   | Claude Code | `.claude/skills/<name>/SKILL.md` | semantic (description) | hand-authored (rich) |
    | Cursor | `.cursor/rules/*.mdc` | `alwaysApply` repo rule + per-domain `description` (agent-requested) | generated |
    | VS Code / Copilot | `.github/copilot-instructions.md` + `.github/instructions/*.instructions.md` | always-on + `applyTo` | generated |
    | Windsurf | `.windsurf/rules/*.md` + `.windsurfrules` | rules dir + legacy flat | generated |
@@ -33,7 +33,10 @@ cannot drift.
    | Continue | `.continue/rules/resolve-mcp.md` | always-on | generated |
    | Claude Desktop | — (chat client, no repo rules) | — | MCP prompts only |
 
-   `.claude/skills/*` stays hand-authored (Claude's rich semantic skills); every
+   `.claude/skills/*` stays hand-authored (Claude's rich semantic skills). Each
+   one is a **directory** holding a `SKILL.md` named for its frontmatter `name`;
+   a loose `.md` at the top level of `.claude/skills/` is never discovered and
+   fails silently. Every
    other file is generated. `AGENTS.md` remains the universal backstop for any
    client not listed. Always-on rule dirs (Cline/Roo/Continue) get one compact
    combined file (repo hygiene + domain table), since they load every rule file
@@ -61,8 +64,8 @@ node scripts/agent-rules/generate.mjs --check   # exit 1 if anything is stale (C
 ## Adding a domain or a platform
 
 - **New domain:** add an entry to `DOMAINS` in `generate.mjs`, add a matching
-  `@mcp.prompt` in `src/server.py`, and (optionally) a rich `.claude/skills/*.md`.
-  Regenerate.
+  `@mcp.prompt` in `src/server.py`, and (optionally) a rich
+  `.claude/skills/<name>/SKILL.md`. Regenerate.
 - **New platform:** add an `emit(...)` for its convention in `generate.mjs`,
   reusing `domainBody(d)` / `repoHygiene`. Regenerate. Do not hand-edit generated
   files — the drift guard will fail.

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.80.1"
+VERSION = "2.80.2"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.80.1"
+VERSION = "2.80.2"
 
 import base64
 import os