splicedeck AGENTS.md

splicedeck — agent contract

Read by Codex, Claude Code, Cursor, Gemini CLI and any agent that honours AGENTS.md. Read this before touching anything.

A local-first video editor that an AI agent drives. One pass over a source produces both a cleaned long-form master and vertical clips. It remembers how each party likes to be cut.

The governing idea

A bookmark is the base. The casebook is the delta. findings.lock.txt is the receipt.

A style bookmark supplies opening settings. Per-party memory overrides individual fields where a human shipped something different and kept it. The resolver writes its answer to a committed lock file, so git diff reads as a behaviour changelog and git revert is a real behavioural rollback.

Hard rules

1. Pure-Python dependencies only. No compiled extension on any default path, ever, including transitively. On a clean Windows box with no Microsoft Visual C++ redistributable, ctranslate2 and onnxruntime both fail to load their DLLs. Speech recognition runs as a subprocess against an external binary, never as an imported wheel. A pull request that adds a wheel with a binary artifact on the default path is rejected regardless of what it does.
2. Local-complete, cloud-optional. A fresh clone with no API keys and no cloud account must render a finished, delivered file. Cloud tiers are opt-in accelerators behind the same interface. Nothing may become required.
3. ffmpeg is a child process. Never linked, never vendored, never bundled. Every filter-embedded path is escaped or made relative, because a Windows drive letter breaks filter parsing: : is the filter option separator.
4. Capability is proven by trial, never by feature list. ffmpeg -encoders lists encoders the hardware cannot run. On the reference machine h264_nvenc is listed and fails at runtime because the GPU has no encoder silicon, while h264_qsv succeeds. Detect by test-encoding.
5. weld/ is pure. It builds argv lists and filtergraph strings and returns them. No subprocess, no disk, no network, no clock. This is what makes the whole decision layer testable in CI with no ffmpeg and no GPU. Do not put I/O in it "just this once".
6. All time is an integer tick. No float ever enters the time domain. Ranges are in / out / at, never origin-plus-extent, so moving a cut is one number changing.
7. Nothing durable is authored by the model. Every memory tool argument is an identifier the pipeline minted — never a value, a string, or a path. A case records something a human did; the pipeline writes every field from its own ledger.
8. The server may write only casebook/pending/. It may read casebook/parties/, casebook/schema/, bookmarks/ and ledger/. Skills, prompts and executables are unreachable because nothing can reach them, not because something refuses.
9. A cut never lands inside a word. Snap to word boundaries from the index.
10. Describe the look, never the source. No preset, bookmark, axis value, element, directory, file, party identifier, commit message or documentation line may be named after — or documented as targeting — any real person living or dead, or any third-party brand, product, channel, publication or trade dress. This binds the casebook write gate too.
11. Media never enters git. Sources are content-addressed; the repository holds pointers. The hash is authoritative, the path is advisory.
12. Every failure is typed, and every refusal carries its correction as data — a list of ready-to-send calls, not prose the caller must parse.