Demo Reel Adapter

Demo Reel adapter (dot-agent-deck)

The adapter is the repo-specific half of PRD #180. It discovers the work-list and builds a manifest.json, then hands it to the repo-agnostic engine (demo-reel, reel.sh). The engine renders the cards, stitches the MP4, and (with --publish) uploads it — it knows nothing about Rust, #[spec], tests/CATALOG.md, or .dot-agent-deck/recordings/. The only contract between the two is the manifest:

[{ "title": "...", "description": "...", "clip": "<path-to-.cast|.gif|.mp4>" }, ...]

Everything dot-agent-deck-specific (which tests, where their title/description live, the catalog ordering) lives here; nothing of it leaks into the engine.

Usage

# Default: select in-scope e2e tests, build the manifest, invoke the engine.
.claude/skills/demo-reel-adapter/build.sh                         # stitch only
.claude/skills/demo-reel-adapter/build.sh --out reel.mp4 --publish  # stitch + upload

Run the full reel pipeline from the repo root so the default relative paths (.dot-agent-deck/recordings, tests/CATALOG.md) resolve. The engine resolves clip paths relative to its own CWD, so it is invoked from the same directory.

Title composition

The engine names the uploaded video after its --out basename unless given a --title; the engine is repo-agnostic and has no notion of a PRD, so the adapter composes a descriptive title and forwards it. The format is:

<repo> · PRD #<prd> · PR #<pr> — <short desc>

for example dot-agent-deck · PRD #180 · PR #182 — PRD demo reel. Each piece is derived from the repo and the current branch:

Composition degrades gracefully — a missing repo/PRD/PR drops only its own segment — so it never errors. Pass --title "…" to override the whole thing verbatim; this is needed for manual/dogfood runs where the branch/PRD don't match the clips being stitched. Inspect what would be used without publishing via build.sh title.

Selection rule (concern a)

select lists the recording dirs under .dot-agent-deck/recordings/<id>/ that are in scope for this branch's reel. File-level granularity; robustness over cleverness. A dir is in scope iff all three hold:

1. It contains a full-stream.cast — the e2e proxy. The cargo xtask docs generator writes a test.md for every #[spec] test but emits a cast only for L2 tests; L1 render tests have a test.md and no cast, so they are excluded by construction (which is also exactly the right "user-journey" subset). Casts are local-only (PRD #77) and only written on failure or under DOT_AGENT_DECK_RECORD=1, so the reel step runs the relevant e2e tests with that flag first; without casts, every dir fails this check and the step clean-skips. That run is LOCAL and is not discharged by CI — CI's lane 1 (CLAUDE.md rule 5) sets no such flag and uploads no casts, and every reel-eligible test is a lane-2 test that CI does not run at all — and since issue #502 removed the pre-PR full-tier obligation there is no longer an unfiltered run to piggyback on, so record the tests the branch adds or changes by filter with DOT_AGENT_DECK_RECORD=1 cargo test-e2e-live <filter>.

A reel-eligible cast comes from a run that held a real agent credential, and this skill publishes it. Eligibility requires a real agent spinning up, which is exactly the e2e-live boundary, so every cast that reaches --publish was recorded by a process holding your credentials — and the URL goes into the PR body and the changelog fragment, which flows into the public release notes. Two things stand between a key and a public URL, and it is worth being precise about which does what.

The upload is PRIVATE by default, and that is the boundary that actually holds: upload.sh creates the video with privacyStatus: private and reel.sh --publish passes no privacy flag, so this automated path cannot produce a third-party-visible video at all. Only the channel owner, and any account they deliberately share it with, can watch it; flipping it to unlisted before a release is a deliberate human step, and the video id survives the flip so the link already in the PR keeps working. See docs/develop/demo-reel.md.

The harness's redaction of full-stream.cast is best-effort, not a guarantee. It removes registered credential values, including ones the terminal wrapped across rows, and it is not optional housekeeping — but it is a blocklist: it can only remove values something registered, and its matcher is known incomplete in two reproduced ways (a registered value starting inside an earlier match, and a decoy continuation that suppresses a real one). docs/develop/e2e-lanes.md has the mechanism and names both gaps. So do not treat a redacted cast as a scanned cast: watch the reel before you flip it public, per docs/develop/demo-reel.md, and treat private-by-default plus that review as the thing standing between a credential and a public URL. 2. Its catalog entry carries the [reel] eligibility marker (see Reel-eligibility marker below). Eligibility is opt-in: a cast alone means the test is PTY-attached, not that it belongs in the reel, so an unmarked test is excluded even with a cast and a changed source. This gate is evaluated last even though it is listed second: the three conditions are ANDed, so order cannot change which dirs are selected, but checking the marker last means its excluding '<id>' … has no [reel] marker diagnostic fires only for a dir that would otherwise have been selected — a genuine near-miss — rather than for every unmarked recording on disk. 3. Its source file changed on this branch vs origin/main. Each test.md carries a **Source:** <dir>/<file>::<fn>`` line. The file is matched by basename against git diff --name-only origin/main restricted to *.rs. select first does a best-effort git fetch origin main so the diff is against the true remote tip, not a stale local main. Basename matching sidesteps the test.md <immediate-parent>/<file> path quirk and is robust for the flat tests/*.rs (and src/*.rs) layout this repo uses.

The recording dir is named after the test function (e.g. mytest), while the catalog id (e.g. mouse/button/001) lives in the test.md H1 — the two are not the same string, which is why ids for ordering are read from the H1, not the dir name.

Reel-eligibility marker: real user-facing usage only

A cast just means a test is PTY-attached; it does not mean it belongs in the reel. A clip exists so a human can watch and validate real behavior — so a test that drives the feature under a test-only artifice must not become a clip, because the viewer would be validating a fiction. Eligibility is therefore opt-in and explicit: a test is a reel candidate only when an author has marked it, and only if it exercises the feature the way a user actually runs it — a real agent genuinely spinning up (spawn → agent → work). Never mark a synthetic/stand-in test: cat, scripted echo, recorder-stub binaries, terminal-probe, or synthesized/fake hook events. Concretely, a marked test must not rely on:

• non-representative CLI flags a user would never pass (e.g. pi --no-builtin-tools, or tool allow/deny-lists that force a particular code path);
• stand-in binaries (cat, echo scripts) standing in for a real agent;
• delivering a prompt as a command-line argument when production delivers it by injection — the pane must be seeded the way the daemon does it (write_to_pane_and_submit), not agent … '<prompt>'.

If a feature can only be proven under such an artifice, split it: a real-usage test for the reel plus a separate headless (non-recorded) test for the forensic proof. This applies CLAUDE.md rule 4's "validate it AS A USER ACTUALLY USES AND SEES IT" bar at the clip-selection boundary.

The marker: a trailing [reel] on the catalog line

The marker is a small trailing tag on the test's ##### <id> — <headline> line in tests/CATALOG.md — the same line the adapter already parses for ordering, so no gitignored artifact and no Rust macro change are involved:

##### codex/live/001 — A real interactive cheap-model Codex run … reports live status (PRD #20). [reel]

• Default is NOT eligible. A line with no [reel] (or an id absent from the catalog) is never selected, so an unmarked/artifice test can never auto-select as a clip even with a cast and a changed source.
• Both concerns enforce it. select (concern a) and assemble (concern b) each drop an unmarked id, so an injected id list can no more smuggle an unmarked test in than a cast-less one.
• The marker never reaches the card. cargo xtask docs copies the catalog headline (marker and all) verbatim into test.md's H1, so the adapter strips a trailing [reel] when lifting the title — the card shows clean text.
• One ##### <id> catalog line can back several recording dirs (two test functions sharing one catalog id); marking the single line makes all of them eligible.

Recording discipline for a [reel]-marked test

Marking a test [reel] means its cast will be published as video, so the recording itself has to be publishable. Two constraints come from the asciinema format and the reel's frame, and neither is fixable downstream — the engine can only render what the cast contains. Both were learned the hard way on PRD #339, whose first reel (HYXKJokZ8JI) was unwatchable.

Never resize the terminal mid-recording

An asciinema v2 cast stores one terminal size, in its header, and the format has no resize event. A recorder that is resized mid-session writes the final size — so every earlier, wider frame in the stream is replayed into a narrower grid and hard-wraps into garbage. PRD #339's cast declared 60 columns while its earlier frames addressed column 68, and the resulting clip was illegible.

To demonstrate width-dependent behaviour, change the app's own layout inside a fixed terminal — open a pane, add cards, toggle the layout, narrow a card by adding a sibling — rather than changing the terminal. The app reflowing at a constant terminal size is both a valid demonstration and a recordable one. (The engine warns when a cast addresses a column beyond its header width, but by then the recording already has to be redone.)

Record at laptop-ish proportions, roughly 16:9

The reel's canvas is a fixed landscape 16:9 frame and segments are fit into it, never cropped, so a portrait cast can only ever occupy a centre strip with black bars either side. Character cells are roughly 1:2.3, so ~16:9 means about 4x as many columns as rows:

Pick the grid for what the scenario needs to show, then keep the ratio near 4:1. The engine warns when a clip is more than 35% off the canvas aspect, naming the coverage it will get.

Assembly rule (concern b)

assemble is pure: given a list of recording-dir IDs it reads only test.md and CATALOG.md (no test-body parsing, no git, no network) and emits the manifest:

• title ← the test.md H1 line, minus the leading # and a trailing [reel] marker (e.g. mouse/button/001 — Beta renders its label.).
• description ← the ## Scenario paragraph(s), blank lines dropped and collapsed to a single line.
• catalog id (for ordering only) ← the part of the H1 before the first — (em dash).
• clip ← <recordings>/<id>/full-stream.cast.
• Any ID lacking a full-stream.cast is excluded (the same L1 guard as selection, applied at assembly so an injected list can't smuggle an L1 test in).
• Any ID whose catalog entry lacks the [reel] marker is excluded (the same eligibility guard as selection, applied at assembly so an injected list can't smuggle an unmarked test in).
• Entries are ordered by catalog id's line position in CATALOG.md (the authoritative order); an id absent from the catalog sorts last.
• Clean skip: if no ID resolves to a reel-eligible e2e clip it writes no manifest and exits 0, printing either the plain skipped: no e2e tests changed on this branch or, when an ID was dropped for a missing marker, the eligibility message that names it (see Which clean skip you got).

Splitting selection (a) from assembly (b) is deliberate: (b) is deterministic and fixture-testable, and it has exactly one impure edge — resolving the commit the provenance gate checks against, which REEL_ADAPTER_EXPECT_COMMIT overrides and which is resolved lazily, so a list that reaches no provenance check touches no git at all. That is what most of the acceptance test below exercises.

Cast provenance (issue #808)

The three selection gates are a test -f plus two static facts about the test — is it branch-scoped, is its catalog line marked — so none of them says anything about the artifact. A full-stream.cast an older revision left on disk satisfies every one of them, which means the adapter could stitch a clip from an unknown revision into a video whose URL goes into the PR body and the changelog fragment, and from there into the public release notes.

PR #805 fixed the cheap half: the harness now discards the previous run's artifacts at launch (before it spawns anything) and on skip_unless!'s runtime-skip path, and a deletion that fails for any reason other than NotFound panics instead of warning. tests/harness_isolation.rs carries all three guards. That closes every route that reaches one of those call sites — and two routes do not:

1. A filtered run — the normal way anyone works, and what CLAUDE.md rule 5 asks for — never selects the test at all, so nothing on the discard path executes and an unselected test's older cast is untouched.
2. skip_unless! evaluates its preflight expression before _skip_if_err is entered: skip_unless!(check_claude_available()) calls the check first and only then hands the Result over, so a kill or an abort inside a check_*_available — or inside an importer it calls, which is where the credential work happens — lands before the skip-path discard.

Provenance covers both at once, which is why the answer was not a third discard. The harness writes a provenance.json sidecar beside each dump, and assemble checks it.