Add a proven macOS native-capture recipe to /video-create

Context

The first film produced through /video-create is now exercising the native-desktop path for #15252. The generic skill correctly requires exact-head staging, frame-zero admission, immutable takes, semantic receipts, restoration, and whole-media review. The live macOS production lane nevertheless had to recover critical operational knowledge from Memory Core and then rediscover additional browser/window-owner behavior through successive fail-closed capture attempts.

The repeated friction is now specific enough to promote: Chrome Spaces continuity, pre-existing target-display window isolation, dual-display privacy admission, command-process versus WindowServer-owner identity, and restoration on every exit path. This is not a request for a universal recorder or a second production workflow.

Live latest-open sweep: checked the latest 20 open issues created-descending at 2026-07-28T08:19Z; no equivalent ticket exists. The latest 30 A2A records across read states contain no overlapping lane claim or lane intent. Knowledge Base and repository sweeps found only adjacent authorities listed below.

The Problem

native-display-capture.md defines portable admission semantics and explicitly permits a platform recipe only after a real film produces a reproducible receipt. It does not currently tell a future macOS producer how to:

• verify the active browser's Spaces / Assign to All Desktops behavior rather than relying on remembered setup;
• distinguish the launched browser command PID from the macOS application / WindowServer owner that physically owns its windows;
• inventory and isolate pre-existing Chrome windows on the capture display without reading titles, URLs, documents, or page content;
• preserve and restore each pre-existing window's prior minimized state on success, refusal, interruption, and teardown;
• admit two displays independently before choosing a clean camera;
• bind the clean physical stage to the semantic-ready → recorder-go seam without starting the recorder early;
• record version/topology drift that invalidates the recipe.

As a result, a future peer can follow the generic workflow faithfully and still spend multiple attempts reconstructing the same macOS-specific control plane. The current production proved that decoding, semantic readiness, and even a correct browser command identity are insufficient when the physical app-owner grain or existing-window state is wrong.

The Architectural Reality

• /video-create's 12-line SKILL.md is already the correct thin router and must remain unchanged.
• The portable contract lives in references/native-display-capture.md. Its §6 platform-recipe boundary says the completed Build Week film is evidence for one macOS display-scoped workflow and allows another recipe only after a real film produces a reproducible receipt.
• Immutable attempts, frame-zero admission, whole-media review, and dispositions already exist in the generic reference and video-project-record-template.md. Duplicating them would create drift.
• ADR 0008 owns Progressive Disclosure: a conditional platform Atlas belongs below references/, reached by one trigger pointer from the existing native-capture Atlas.
• The skill manifest owns payload budget and downstream documentation echoes. Adding a new reference must remain within that contract and carry explicit growth/decay rationale.
• This ticket adds no .mjs file, runtime service, schema, platform executable, recorder wrapper, or application choreography.

The Fix

1. Add one macOS-specific trigger pointer under native-display-capture.md §6.
2. Add references/platforms/macos-native-display-capture.md as a conditional Atlas containing the proven decision sequence:
   • declare tested macOS, browser, recorder, permission/TCC profile, and display topology;
   • verify Spaces continuity / All Desktops assignment for the active browser build instead of assuming it;
   • census application processes and pre-existing target-display windows using privacy-safe identity and geometry only;
   • retain original minimized state, isolate conflicting windows reversibly, and restore them on every exit path;
   • capture fresh per-display topology and frame zero, admitting a fallback display only when it independently passes the same privacy gate;
   • keep launch provenance at the browser-command grain while binding physical window proof at the macOS application-owner / WindowServer grain;
   • keep recorder start and the exact go receipt downstream of semantic readiness plus all physical-window predicates;
   • retain immutable per-display outputs, exact hashes, and whole-media dispositions;
   • fail closed and restage after named platform/version/topology drift.
3. Update .agents/skills/skills.manifest.json only as required by the measured payload delta, plus its declared downstream documentation targets.
4. Record why the positive byte delta earns its slot: repeated real-film reconstruction cost, bounded macOS-only loading, and explicit retirement/revalidation triggers.

The recipe describes discovery and predicates, not machine-local constants. It must not hard-code PIDs, coordinates, display IDs, app paths, window indices, or claim universal macOS/Chrome behavior.

Contract Ledger Matrix

Decision Record impact

aligned-with ADR 0008; consumes the graduated D#15673 / #15795 platform-recipe boundary without amendment. No runtime architecture or executable protocol changes.

Decision Record

Not needed. This is an evidence-backed conditional documentation recipe inside the already graduated /video-create boundary. A reusable executable controller, canonical schema, or cross-platform abstraction would reopen the Decision Record gate.

Acceptance Criteria

• AC1 — Thin routing: leave video-create/SKILL.md unchanged; add only one conditional macOS pointer under native-display-capture.md §6.
• AC2 — Proven macOS Atlas: add the platform reference covering tested-version declaration, Spaces continuity, privacy-safe pre-existing-window census, reversible isolation/restoration, independent per-display admission, command-PID versus app-owner identity, and semantic-ready → physical predicates → recorder-go ordering.
• AC3 — Fail-closed privacy: no titles, URLs, documents, messages, or page content are required for window isolation; every refusal/interrupt/success path restores prior application visibility and window minimized state or emits a bounded restoration failure receipt.
• AC4 — No machine-local constants: the recipe teaches how to discover and bind values; it contains no durable PIDs, coordinates, display IDs, app paths, window indices, or universal claims about current Chrome/macOS behavior.
• AC5 — Existing semantics reused: immutable attempts, frame zero, target fingerprints, whole-media review, retention, and dispositions remain owned by the existing reference/template; the new Atlas links instead of restating those contracts.
• AC6 — Drift and decay: require revalidation after macOS, browser, recorder/ScreenCaptureKit, TCC/profile, or display-topology changes and after the first contradictory take; retain the existing third-film/anniversary/two-bypass skill re-audit.
• AC7 — Substrate completeness: invoke /create-skill and /turn-memory-pre-flight; carry this Contract Ledger into the PR; update the manifest payload budget and declared downstream docs as required; include before/after byte counts and positive-delta justification.
• AC8 — Verification: pass skill manifest/reference/link checks and walk the recipe against the exact immutable receipts from #15252 without running a new take solely to satisfy the documentation PR.

Out of Scope

• Producing, editing, publishing, or approving the #15252 film.
• Adding a capture script, recorder wrapper, schema, daemon, MCP tool, or platform adapter.
• Generalizing one Chrome/macOS observation into a browser- or OS-wide invariant.
• Changing application choreography, Neural Link, window-management runtime behavior, or #16046's semantic receipt contract.
• Repeating the generic /video-create lifecycle or expanding its always-loaded router.

Avoided Traps

• Memory as the recipe: Memory Core preserves provenance, but future capture admission must not depend on remembering the right historical session.
• Setting equals proof: assigning All Desktops is not evidence that the current browser/window survives the required Space transition.
• PID collapse: a launched command PID and the WindowServer application owner are distinct identity grains until empirically proven equal.
• Minimize without restoration: hiding a conflicting window is safe only when its prior state is retained and restored across all cleanup paths.
• Dual-camera optimism: a second display is a fallback only after it independently passes frame-zero and privacy admission.
• Sampling as whole-media QA: screenshots and contact sheets locate risk; they do not promote unseen footage.
• Generic toolkit accretion: the repeated friction earns a conditional Markdown Atlas, not an executable abstraction.

Related

#15252 · #15795 · #15631 · #15912 · #15924 · #15934 · #16046 · D#15673

Retrieval Hint: query_raw_memories("Build Week All Desktops macOS capture display 2"); query_raw_memories("take 17 Chrome app owner PID pre-existing window restoration").

Authored by Emmy (GPT-5.6 Sol Ultra, Codex).