docs: add Ground Control requirement specs as repo-local files

docs/requirements/PUL-A001/requirement.md

@@ -0,0 +1,28 @@
+---
+id: PUL-A001
+title: "Timeline library encapsulation"
+status: ACTIVE
+type: CONSTRAINT
+priority: MUST
+wave: 0
+created_at: 2026-04-30T19:18:12.240742Z
+updated_at: 2026-05-12T21:26:30.999476Z
+---
+
+# PUL-A001 — Timeline library encapsulation
+
+## Statement
+
+Scene modules SHALL NOT import the timeline library directly. Scene timelines SHALL be constructed via the timeline utilities exposed on the scene context.
+
+## Rationale
+
+Encapsulating the timeline library lets the runtime swap implementations without breaking scenes (ADR-003).
+
+## Traceability
+
+- CONSTRAINS → ADR `ADR-003` (GSAP as the Timeline Engine)
+- CONSTRAINS → ADR `ADR-008` (Agent-Native Authoring as a First-Class Architectural Constraint)
+- TESTS → TEST `tests/runtime/policy-a001-timeline-encapsulation.test.ts` (PUL-A001 source-policy gate (Vitest))
+- IMPLEMENTS → CODE_FILE `tests/runtime/source-policy.ts`
+- IMPLEMENTS → GITHUB_ISSUE `50`

docs/requirements/PUL-A002/requirement.md

@@ -0,0 +1,28 @@
+---
+id: PUL-A002
+title: "Audio library encapsulation"
+status: ACTIVE
+type: CONSTRAINT
+priority: MUST
+wave: 0
+created_at: 2026-04-30T19:18:16.076099Z
+updated_at: 2026-05-12T21:26:32.142508Z
+---
+
+# PUL-A002 — Audio library encapsulation
+
+## Statement
+
+Scene modules SHALL access audio playback only via the runtime audio context. Scenes SHALL NOT instantiate `HTMLAudioElement` or directly import the audio library, except where a scene drops down to raw Web Audio with a documented justification and registers cleanup with the runtime.
+
+## Rationale
+
+Per-scene cleanup and master mute depend on routed audio access (ADR-004, ADR-008).
+
+## Traceability
+
+- CONSTRAINS → ADR `ADR-004` (Howler.js as the Audio Engine)
+- CONSTRAINS → ADR `ADR-008` (Agent-Native Authoring as a First-Class Architectural Constraint)
+- TESTS → TEST `tests/runtime/policy-a002-audio-encapsulation.test.ts` (PUL-A002 source-policy gate (Vitest))
+- IMPLEMENTS → CODE_FILE `tests/runtime/source-policy.ts`
+- IMPLEMENTS → GITHUB_ISSUE `51`

docs/requirements/PUL-A003/requirement.md

@@ -0,0 +1,27 @@
+---
+id: PUL-A003
+title: "Optional rendering libraries are scene-local"
+status: ACTIVE
+type: CONSTRAINT
+priority: MUST
+wave: 0
+created_at: 2026-04-30T19:18:19.087658Z
+updated_at: 2026-05-12T21:26:33.394301Z
+---
+
+# PUL-A003 — Optional rendering libraries are scene-local
+
+## Statement
+
+The runtime core SHALL NOT import PixiJS, Three.js, or Phaser. Adoption of any of these libraries SHALL be scene-local.
+
+## Rationale
+
+Keeps the core lightweight and lets specialized rendering be opt-in per scene (ADR-005).
+
+## Traceability
+
+- CONSTRAINS → ADR `ADR-005` (DOM/CSS as the Default Rendering Surface)
+- TESTS → TEST `tests/runtime/policy-a003-rendering-libraries.test.ts` (PUL-A003 source-policy gate (Vitest))
+- IMPLEMENTS → CODE_FILE `tests/runtime/source-policy.ts`
+- IMPLEMENTS → GITHUB_ISSUE `52`

docs/requirements/PUL-A004/requirement.md

@@ -0,0 +1,27 @@
+---
+id: PUL-A004
+title: "Live runtime is independent of the export pipeline"
+status: ACTIVE
+type: CONSTRAINT
+priority: MUST
+wave: 0
+created_at: 2026-04-30T19:18:22.241247Z
+updated_at: 2026-05-12T21:26:34.152746Z
+---
+
+# PUL-A004 — Live runtime is independent of the export pipeline
+
+## Statement
+
+The runtime core SHALL NOT import Remotion or any video-rendering library. Export functionality SHALL live in a separate codebase that consumes the same scene metadata and composition manifests.
+
+## Rationale
+
+Separation of concerns between live playback and headless export (ADR-006).
+
+## Traceability
+
+- CONSTRAINS → ADR `ADR-006` (Remotion as a Parallel Export Path, Not the Live Runtime)
+- TESTS → TEST `tests/runtime/policy-a004-export-pipeline.test.ts` (PUL-A004 source-policy gate (Vitest))
+- IMPLEMENTS → CODE_FILE `tests/runtime/source-policy.ts`
+- IMPLEMENTS → GITHUB_ISSUE `53`

docs/requirements/PUL-A005/requirement.md

@@ -0,0 +1,28 @@
+---
+id: PUL-A005
+title: "Composition is declarative"
+status: ACTIVE
+type: CONSTRAINT
+priority: MUST
+wave: 0
+created_at: 2026-04-30T19:18:25.743385Z
+updated_at: 2026-05-12T21:26:35.304298Z
+---
+
+# PUL-A005 — Composition is declarative
+
+## Statement
+
+Compositions SHALL be expressed as declarative manifests of scene ids. The runtime SHALL NOT support imperative dispatch (e.g., `if/else` branching or position-based dispatch in a control script) as the source of truth for composition order.
+
+## Rationale
+
+Manifests-over-flow-control is a binding constraint of the agent-native model (ADR-002, ADR-008).
+
+## Traceability
+
+- CONSTRAINS → ADR `ADR-002` (Scene Registry and Composition Manifests as the Core Abstraction)
+- CONSTRAINS → ADR `ADR-008` (Agent-Native Authoring as a First-Class Architectural Constraint)
+- TESTS → TEST `tests/runtime/policy-a005-declarative-composition.test.ts` (PUL-A005 source-policy gate (Vitest))
+- IMPLEMENTS → CODE_FILE `src/compositions/default.ts` (Reference declarative composition manifest)
+- IMPLEMENTS → GITHUB_ISSUE `54`

docs/requirements/PUL-A006/requirement.md

@@ -0,0 +1,27 @@
+---
+id: PUL-A006
+title: "Live runtime is independent of slide frameworks"
+status: ACTIVE
+type: CONSTRAINT
+priority: MUST
+wave: 0
+created_at: 2026-04-30T19:18:33.320260Z
+updated_at: 2026-05-12T21:26:36.251439Z
+---
+
+# PUL-A006 — Live runtime is independent of slide frameworks
+
+## Statement
+
+The runtime core SHALL NOT import or depend on slide-framework primitives (e.g., reveal.js or Spectacle). Slide frameworks MAY be used in companion projects, separate from the runtime core.
+
+## Rationale
+
+Avoids the two-runtime coordination cost rejected in ADR-001.
+
+## Traceability
+
+- CONSTRAINS → ADR `ADR-001` (Custom Experience Runtime, Not a Slide Framework)
+- TESTS → TEST `tests/runtime/policy-a006-slide-frameworks.test.ts` (PUL-A006 source-policy gate (Vitest))
+- IMPLEMENTS → CODE_FILE `tests/runtime/source-policy.ts`
+- IMPLEMENTS → GITHUB_ISSUE `55`

docs/requirements/PUL-A007/requirement.md

@@ -0,0 +1,31 @@
+---
+id: PUL-A007
+title: "Scene id format"
+status: ACTIVE
+type: CONSTRAINT
+priority: MUST
+wave: 0
+created_at: 2026-04-30T19:18:36.039619Z
+updated_at: 2026-05-03T02:28:47.712651Z
+---
+
+# PUL-A007 — Scene id format
+
+## Statement
+
+Scene ids SHALL be lowercase ASCII consisting of letters, digits, and hyphens. Ids SHALL NOT be reused across scenes.
+
+## Rationale
+
+Stable, URL-safe, kebab-case ids are the agent-addressable identity contract (ADR-002, ADR-008).
+
+## Traceability
+
+- IMPLEMENTS → CODE_FILE `src/runtime/identifier.ts` (Kebab-case identifier predicate — KEBAB_IDENTIFIER_PATTERN + isKebabIdentifier)
+- CONSTRAINS → ADR `ADR-002` (Scene Registry and Composition Manifests as the Core Abstraction)
+- CONSTRAINS → ADR `ADR-008` (Agent-Native Authoring as a First-Class Architectural Constraint)
+- IMPLEMENTS → CODE_FILE `src/runtime/scene.ts` (Scene id format guard — SCENE_ID_PATTERN, isSceneId, isSceneIdOrNull)
+- IMPLEMENTS → CODE_FILE `src/runtime/registry.ts` (Scene id uniqueness enforcement — createSceneRegistry duplicate-id detection)
+- TESTS → TEST `tests/runtime/scene.test.ts` (Scene id format spec — 32 cases under "scene id format (PUL-A007)" + 9 defaultNext cases)
+- TESTS → TEST `tests/runtime/registry.test.ts` (Scene id uniqueness spec — duplicate-id describe block in registry.test.ts)
+- IMPLEMENTS → GITHUB_ISSUE `10` (PUL-A007: Scene id format)

docs/requirements/PUL-A008/requirement.md

@@ -0,0 +1,30 @@
+---
+id: PUL-A008
+title: "Mode dispatch in core"
+status: ACTIVE
+type: CONSTRAINT
+priority: MUST
+wave: 1
+created_at: 2026-04-30T19:18:39.441198Z
+updated_at: 2026-05-17T21:55:03.440234Z
+---
+
+# PUL-A008 — Mode dispatch in core
+
+## Statement
+
+Workbench mode dispatch SHALL be implemented in the runtime core. Scene modules SHALL NOT contain mode-specific branches except where they must respond to mode hints (e.g., suppressing audio in `mode=screenshot`).
+
+## Rationale
+
+Mode behavior must be uniform across scenes (ADR-007, ADR-008).
+
+## Traceability
+
+- CONSTRAINS → ADR `ADR-007` (Browser as the Default Workbench and Agent Collaboration Surface)
+- CONSTRAINS → ADR `ADR-008` (Agent-Native Authoring as a First-Class Architectural Constraint)
+- IMPLEMENTS → CODE_FILE `src/runtime/navigation.ts` (URL navigation grammar — NAVIGATION_MODES allowlist, parseNavigationSearch, effectiveMode (pure URL-derived mode dispatch boundary for PUL-A008 clause 1))
+- IMPLEMENTS → CODE_FILE `src/runtime/scene-loader.ts` (Scene loader — per-navigation mode dispatch: validateModeGrammar, audioOutputPolicyFor(mode), mode→runner-input hints, buildPresenterPipe, ctx.mode threading (PUL-A008 clause 1 in the runtime core))
+- IMPLEMENTS → DOCUMENTATION `docs/design/pul-a008-mode-dispatch-core-preflight.md` (PUL-A008 architectural preflight — consolidated repo-wide guardrails for mode-dispatch boundary, required reuse, cross-cutting layers, extensibility seam, and anti-patterns)
+- IMPLEMENTS → GITHUB_ISSUE `56` (Issue #56 — PUL-A008: Mode dispatch in core)
+- TESTS → TEST `tests/runtime/policy-a008-mode-dispatch.test.ts` (PUL-A008 source-policy gate — scene-local mode-literal branch detector (binary equality, switch/case, .includes membership) with const-alias resolution)

docs/requirements/PUL-A009/requirement.md

@@ -0,0 +1,31 @@
+---
+id: PUL-A009
+title: "Captions and prompter share metadata source"
+status: ACTIVE
+type: CONSTRAINT
+priority: MUST
+wave: 2
+created_at: 2026-04-30T19:18:42.131179Z
+updated_at: 2026-05-18T01:10:18.552804Z
+---
+
+# PUL-A009 — Captions and prompter share metadata source
+
+## Statement
+
+The prompter view SHALL be derived from the same caption metadata used by the runtime. There SHALL NOT be a separate authoring source for prompter content.
+
+## Rationale
+
+Single source of truth (ADR-008).
+
+## Traceability
+
+- CONSTRAINS → ADR `ADR-008` (Agent-Native Authoring as a First-Class Architectural Constraint)
+- IMPLEMENTS → CODE_FILE `src/runtime/scene.ts` (Caption interface + SceneModule.captions field + assertSceneModule schema gate — the canonical single-source authoring slot for prompter content (PUL-A009))
+- IMPLEMENTS → CODE_FILE `src/runtime/prompter.ts` (buildPrompterScript — single derivation seam reading exclusively from SceneModule.captions (PUL-A009 clause 1))
+- IMPLEMENTS → CODE_FILE `src/runtime/scene-loader.ts` (mode=prompter loader dispatch — routes navigation through buildPrompterScript(target) so prompter view is derived from caption metadata (PUL-A009 clause 1))
+- IMPLEMENTS → DOCUMENTATION `docs/design/pul-a009-captions-prompter-single-source-preflight.md` (PUL-A009 design preflight — consolidates binding guardrails for the single-source contract)
+- TESTS → TEST `tests/runtime/policy-a009-captions-single-source.test.ts` (PUL-A009 source-policy gate — 131 scanner self-tests + 4 runtime-tree assertions covering four sub-rules (interface fields, parallel schema declarations, prompter Caption import boundary, scene-module object literals))
+- TESTS → TEST `tests/runtime/prompter.test.ts` (Prompter derivation behavior tests — pin buildPrompterScript reading exclusively from scene.captions (PUL-A009 clause 1, pre-existing))
+- IMPLEMENTS → GITHUB_ISSUE `57` (PUL-A009: Captions and prompter share metadata source)

docs/requirements/PUL-A010/requirement.md

@@ -0,0 +1,28 @@
+---
+id: PUL-A010
+title: "Live and export share scene metadata"
+status: ACTIVE
+type: CONSTRAINT
+priority: SHOULD
+wave: 3
+created_at: 2026-04-30T19:18:44.804081Z
+updated_at: 2026-05-18T03:20:51.029768Z
+---
+
+# PUL-A010 — Live and export share scene metadata
+
+## Statement
+
+Any export pipeline SHALL consume the same scene metadata and composition manifests as the live runtime. Export-specific metadata SHALL NOT replace live-runtime metadata.
+
+## Rationale
+
+Shared metadata keeps the scene library as the single source of truth across surfaces (ADR-006).
+
+## Traceability
+
+- CONSTRAINS → ADR `ADR-006` (Remotion as a Parallel Export Path, Not the Live Runtime)
+- TESTS → TEST `tests/runtime/policy-a010-export-metadata-share.test.ts` (PUL-A010 export-metadata-share source-policy gate)
+- IMPLEMENTS → DOCUMENTATION `docs/design/pul-a010-live-export-metadata-preflight.md` (PUL-A010 design preflight)
+- IMPLEMENTS → GITHUB_ISSUE `58` (PUL-A010: Live and export share scene metadata)
+- IMPLEMENTS → PULL_REQUEST `121` (feat: add PUL-A010 live/export shared scene metadata gate)

docs/requirements/PUL-F001/requirement.md

@@ -0,0 +1,28 @@
+---
+id: PUL-F001
+title: "Scene module shape"
+status: ACTIVE
+type: FUNCTIONAL
+priority: MUST
+wave: 0
+created_at: 2026-04-30T19:16:11.856896Z
+updated_at: 2026-05-03T00:43:09.810404Z
+---
+
+# PUL-F001 — Scene module shape
+
+## Statement
+
+A scene module SHALL export an object containing the fields `id`, `title`, `tags`, `assets`, `captions`, `defaultNext`, `standalone`, `trailerSafe`, `create`, `timeline`, and `cleanup`. The `duration` field SHALL be present and SHALL be either a non-negative integer in milliseconds or `null` for an open-ended/interrupt-driven scene.
+
+## Rationale
+
+Defines the contract every scene satisfies. Required by the scene/composition model (ADR-002) and the agent-native authoring constraint (ADR-008).
+
+## Traceability
+
+- DOCUMENTS → ADR `ADR-002` (Scene Registry and Composition Manifests as the Core Abstraction)
+- DOCUMENTS → ADR `ADR-008` (Agent-Native Authoring as a First-Class Architectural Constraint)
+- IMPLEMENTS → CODE_FILE `src/runtime/scene.ts` (SceneModule contract + assertSceneModule + isSceneModule)
+- TESTS → TEST `tests/runtime/scene.test.ts` (SceneModule contract Vitest spec — 62 tests covering every clause)
+- IMPLEMENTS → GITHUB_ISSUE `6` (PUL-F001: Scene module shape)

docs/requirements/PUL-F002/requirement.md

@@ -0,0 +1,28 @@
+---
+id: PUL-F002
+title: "Scene registry"
+status: ACTIVE
+type: FUNCTIONAL
+priority: MUST
+wave: 0
+created_at: 2026-04-30T19:16:14.315443Z
+updated_at: 2026-05-03T01:28:03.625542Z
+---
+
+# PUL-F002 — Scene registry
+
+## Statement
+
+The runtime SHALL register scenes by their `id` field in a single registry. The registry SHALL be the only mechanism by which scenes are addressable for navigation.
+
+## Rationale
+
+Stable scene identity is the basis of compositions, URL navigation, and agent edits.
+
+## Traceability
+
+- DOCUMENTS → ADR `ADR-002` (Scene Registry and Composition Manifests as the Core Abstraction)
+- DOCUMENTS → ADR `ADR-008` (Agent-Native Authoring as a First-Class Architectural Constraint)
+- IMPLEMENTS → CODE_FILE `src/runtime/registry.ts` (Scene registry — createSceneRegistry / SceneRegistry)
+- TESTS → TEST `tests/runtime/registry.test.ts` (Scene registry contract spec (35 tests))
+- IMPLEMENTS → GITHUB_ISSUE `8` (PUL-F002: Scene registry)

docs/requirements/PUL-F003/requirement.md

@@ -0,0 +1,28 @@
+---
+id: PUL-F003
+title: "Composition manifest format"
+status: ACTIVE
+type: FUNCTIONAL
+priority: MUST
+wave: 0
+created_at: 2026-04-30T19:16:17.718055Z
+updated_at: 2026-05-03T03:52:17.839316Z
+---
+
+# PUL-F003 — Composition manifest format
+
+## Statement
+
+A composition manifest SHALL be a declarative ordered list of scene id references. Each entry MAY be a bare scene id string or an object containing a scene id and per-entry overrides for sub-range or behavior.
+
+## Rationale
+
+Compositions are first-class artifacts separate from scenes; they enable recomposition (full talk, short cut, trailer) without forking scenes.
+
+## Traceability
+
+- IMPLEMENTS → CODE_FILE `src/runtime/composition.ts` (Composition manifest format — types + assertCompositionManifest + isCompositionManifest)
+- TESTS → TEST `tests/runtime/composition.test.ts` (Composition manifest format Vitest spec — clauses C1-C3 + AC1-AC2 + ADR-002 fixtures)
+- IMPLEMENTS → GITHUB_ISSUE `12` (PUL-F003: Composition manifest format)
+- DOCUMENTS → ADR `ADR-002` (Scene Registry and Composition Manifests as the Core Abstraction)
+- DOCUMENTS → ADR `ADR-008` (Agent-Native Authoring as a First-Class Architectural Constraint)