From 5601544d739de79f68c4c37d599684f2ba72f7a3 Mon Sep 17 00:00:00 2001 From: Jeff Crouse Date: Thu, 17 Sep 2026 20:45:27 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20propose=20ADR-0061..0064=20=E2=80=94=20?= =?UTF-8?q?the=20continuous=20creative=20workflow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the discussion plan (docs/product/continuous-creative-workflow.md) and four proposed ADRs for background refinement + native review: - ADR-0061 creative work persists across bounded refinement rounds - ADR-0062 candidates are isolated, versioned, and promoted explicitly - ADR-0063 background work is resumable and uses an external runner - ADR-0064 review is a first-class workspace alongside creation Reconciled against the trunk before proposing: - the preferred-version reference is a DOCUMENT field, so promotion is one edit-gateway command and undo restores content + pointer together; a whole-document revision counter (per-clip `rev` precedent) backs the stale-promotion check (ADR-0062) - the worker shares no per-user mutable state: VIVID_PORT, the single autosave/recovery slot + crash/quarantine records, VIVID_NO_RECOVER; project-local operators compile into the candidate copy (ADR-0063) - the deterministic offline AV export is already the worker's surface-free render primitive; the gap is device-free bring-up (headless GPU context, no audio device, sample rate as a job input), not a new render loop (ADR-0063) - Candidate vs. the planned Take / Variation Well: same audition/keep/choose pattern at version vs. cell scope; a promoted or kept clip-scoped candidate lands in the well as a take; the well holds content only (ADR-0062/0064, glossary) All four remain `proposed` with acceptance evidence pending. Glossary gains a "Background Refinement Vocabulary (proposed)" section; docs/README.md points at the proposal. Co-Authored-By: Claude Opus 5 (1M context) --- docs/README.md | 7 + ...-work-persists-across-refinement-rounds.md | 71 +++++ ...es-are-isolated-and-promoted-explicitly.md | 80 +++++ ...background-work-uses-an-external-runner.md | 92 ++++++ ...eview-is-a-workspace-alongside-creation.md | 73 +++++ docs/product/continuous-creative-workflow.md | 286 ++++++++++++++++++ docs/product/glossary.md | 23 ++ 7 files changed, 632 insertions(+) create mode 100644 docs/decisions/ADR-0061-creative-work-persists-across-refinement-rounds.md create mode 100644 docs/decisions/ADR-0062-candidates-are-isolated-and-promoted-explicitly.md create mode 100644 docs/decisions/ADR-0063-background-work-uses-an-external-runner.md create mode 100644 docs/decisions/ADR-0064-review-is-a-workspace-alongside-creation.md create mode 100644 docs/product/continuous-creative-workflow.md diff --git a/docs/README.md b/docs/README.md index c87bad8be..4a6e7ada2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,6 +22,13 @@ are not the current product direction unless a newer ADR or roadmap explicitly p ## Document Types +Current proposal: [continuous creative workflow](product/continuous-creative-workflow.md) develops +the background refinement and native review workflow. Its proposed decisions are +[ADR-0061](decisions/ADR-0061-creative-work-persists-across-refinement-rounds.md), +[ADR-0062](decisions/ADR-0062-candidates-are-isolated-and-promoted-explicitly.md), +[ADR-0063](decisions/ADR-0063-background-work-uses-an-external-runner.md), and +[ADR-0064](decisions/ADR-0064-review-is-a-workspace-alongside-creation.md). + ### Product Product documents describe what Vivid 4 is for, who it serves, what concepts mean, and what diff --git a/docs/decisions/ADR-0061-creative-work-persists-across-refinement-rounds.md b/docs/decisions/ADR-0061-creative-work-persists-across-refinement-rounds.md new file mode 100644 index 000000000..b2f6021ef --- /dev/null +++ b/docs/decisions/ADR-0061-creative-work-persists-across-refinement-rounds.md @@ -0,0 +1,71 @@ +# ADR-0061: Creative Work Persists Across Bounded Refinement Rounds + +Status: proposed — product direction confirmed; workflow proof pending + +Date: 2026-09-17 + +Refines: [ADR-0008](ADR-0008-agent-capability-surface.md) and the +[PRD](../product/PRD.md). Design context and sequencing: +[continuous creative workflow](../product/continuous-creative-workflow.md). + +## Context + +A creator with a full-time job can give occasional direction and feedback, but cannot supervise +every edit. Vivid must support songs and visuals developing across days and agent conversations. +An interactive edit/capture loop alone does not preserve the purpose of the work, earlier choices, +or what should happen when the creator is unavailable. + +The user has confirmed native Mac review and free exploration in candidates, with the creator +choosing what becomes current. Useful progress per minute of creator attention is the objective. + +## Decision + +1. **Make refinement persistent and bounded.** The product loop is direction → exploration → + review → refinement. A work item records an objective, scope, dependencies, budget, and stopping + conditions. Each execution attempt is a run. Continuous availability does not imply continuous + computation; a round can end with no worthwhile improvement. +2. **Keep creative memory in the project.** Versioned briefs, protections, candidate provenance, + feedback, and review decisions are durable, agent-readable records. A fresh agent must recover + the work without the previous conversation. UI and MCP manipulate the same records. Provider + credentials and machine-specific execution details remain separate. +3. **Preserve human creative authority.** Agents explore within the brief and protections. Only an + explicit creator choice promotes a candidate. Silence does not accept or reject work. Feedback + retains the user's wording, its exact version/passage target, and any structured interpretation. + Project feedback does not automatically become a global taste preference. +4. **Distinguish protections from preferences.** A hard protection identifies what cannot change; + a preference guides exploration. Scope includes relevant dependencies: preserving notes alone + does not preserve their sound. Revised protections invalidate affected queued work and prevent + stale results from being promoted under obsolete rules. +5. **Limit demand for review.** Publish a small set of meaningful alternatives and a focused + question. A full review queue pauses dependent exploration; independent authorized work may + continue. Start by testing two alternatives and one unresolved decision per work item, not by + making these universal fixed limits. Notify on meaningful review readiness, failure, or required + action rather than every iteration. +6. **Separate evidence from preference.** Technical checks, content/intent evaluation, and human + preference are distinct records. Follow [ADR-0026](ADR-0026-evaluation-asserts-quality-against-intent.md) + when an evaluator is unavailable. Model scores cannot silently establish creative approval. + +## Alternatives Considered + +- **Conversation-only memory.** Loses continuity on restart or provider changes and makes review + depend on reading a transcript. +- **Unbounded autonomous refinement.** Encourages drift, resource consumption, and review backlog. +- **Require approval for every edit.** Consumes the attention this workflow is intended to conserve. +- **Automatically promote the highest-scoring candidate.** Conflicts with the confirmed authority + model and confuses an evaluator's judgment with the creator's preference. + +## Consequences + +Vivid gains durable coordination records in addition to creative content. Their schema, migrations, +and retention become product responsibilities. Agents can be replaced without replacing project +memory. Finishing/exporting remains a milestone within the continuing project. + +The first proof starts from an existing scene; blank-project composition and full-song development +remain later scope. Execution availability is addressed separately by +[ADR-0063](ADR-0063-background-work-uses-an-external-runner.md). + +## Acceptance Evidence Required + +Run two refinement rounds with real media. Restart the agent between them and demonstrate preserved +direction, feedback, and protections. Leave a review unanswered and show bounded work rather than +queue growth. Record a no-improvement outcome without inventing a candidate. Evidence is pending. diff --git a/docs/decisions/ADR-0062-candidates-are-isolated-and-promoted-explicitly.md b/docs/decisions/ADR-0062-candidates-are-isolated-and-promoted-explicitly.md new file mode 100644 index 000000000..e9b60148c --- /dev/null +++ b/docs/decisions/ADR-0062-candidates-are-isolated-and-promoted-explicitly.md @@ -0,0 +1,80 @@ +# ADR-0062: Candidates Are Isolated, Versioned, and Promoted Explicitly + +Status: proposed — persistence and concurrency proofs pending + +Date: 2026-09-17 + +Follows: [ADR-0061](ADR-0061-creative-work-persists-across-refinement-rounds.md). +Extends: [ADR-0017](ADR-0017-every-edit-is-reversible.md) and +[ADR-0018](ADR-0018-a-bad-operator-must-not-cost-you-your-work.md). + +## Context + +Background exploration must not replace the version the creator likes or overwrite manual edits. +Session undo records edits to one document; it does not provide independent candidate workspaces, +durable review evidence, or an explicit preferred version. Copying project.json alone does not +isolate mutable assets, project-local code, or plugin state. + +## Decision + +1. **Give versions immutable identity.** A version records a project snapshot, parentage, and + referenced dependencies. A candidate associates a version with its purpose, source brief, and + evidence. The preferred version is an explicit reference stored in the project document itself, + so it participates in save/load and session undo. The open editing session may have newer + unsaved edits and is not implicitly identical to that reference. +2. **Isolate the entire candidate.** Candidate writes cannot mutate the foreground document or + another version's dependencies. Mutable assets and project-local code require independent + storage or copy-on-write behavior. Capture available plugin state and dependency identity; + missing dependencies make reproduction unavailable rather than silently substituting content. + Reuse canonical persistence instead of inventing a second musical/visual document model. +3. **Separate audition, retention, and promotion.** Previewing does not modify the preferred version. + Keeping an alternative preserves it without choosing it. Promotion is an explicit creator action + applying the candidate as one reversible document edit through the edit gateway, which replaces + the document contents and the preferred-version reference together. +4. **Reject stale promotion.** Atomically validate the expected document revision, preferred-version + reference, brief, and protection revisions. The document revision is a whole-document counter + advanced by every edit-gateway command (the existing per-clip `rev` is the precedent), so unsaved + manual edits participate in that check. + On conflict, retain the candidate and request reconciliation; do not overwrite or automatically + merge whole projects in the first version. A replacement review must identify the new baseline. +5. **Keep history and evidence coherent.** Every rendered artifact identifies its input version, + passage, playback recipe, available seeds, and relevant dependencies. Retain actual media when + third-party behavior is not exactly reproducible. Later timing edits do not silently retarget + comments on old previews. Undoing promotion restores the prior document and preferred reference + in one step because both are document state; work records are append-only and record the + reversal as an event without deleting feedback or pretending completed runs never happened. +6. **Retain work deliberately.** Preferred versions, explicitly kept alternatives, and evidence for + unresolved reviews cannot be silently pruned. Temporary failed attempts may be collected under + an explicit retention policy. Storage format and deduplication are implementation choices. + +A candidate may affect one clip, a scene, or a whole project. The glossary's planned Take and +Variation Well are the same audition/keep/choose pattern at cell scope, stored *in* the document; a +candidate is that pattern at version scope, stored in the work records with one preferred-version +pointer in the document. When the well exists, promoting a clip-scoped candidate is the document +edit that adds its take to the cell's well and makes it live, and "keep as an alternative" adds the +take without making it live; until then a clip-scoped candidate promotes by replacing the clip. The +well receives content only — candidate identity, evidence, and feedback remain in the work records, +never duplicated into the well. Combining one candidate's audio with another's visuals creates a new +candidate requiring dependency checks and a new synchronized preview. + +## Alternatives Considered + +- **Explore in the active document and rely on undo.** Disrupts manual work and mixes two histories. +- **Copy only the session JSON.** Shared mutable files can change supposedly preserved candidates. +- **Use Git alone as the product model.** Useful underlying storage in some designs, but does not + itself define plugin-state capture, playback evidence, review decisions, or safe promotion. +- **Automatically merge all changes.** Musical and visual dependencies make syntactic success an + insufficient guarantee of creative compatibility. + +## Consequences + +Candidate isolation adds disk usage and dependency management. Explicit promotion makes exploration +safe but requires a conflict workflow. Snapshot and asset-manifest details need implementation design; +the first implementation may use complete copies before optimizing storage. + +## Acceptance Evidence Required + +Change shared shader/asset content in a candidate and prove the preferred version remains unchanged. +Edit the foreground project while rendering and prove stale promotion fails without loss. Promote, +undo, and redo while retaining truthful review history. Reload a saved candidate and identify any +unavailable dependencies. Evidence is pending. diff --git a/docs/decisions/ADR-0063-background-work-uses-an-external-runner.md b/docs/decisions/ADR-0063-background-work-uses-an-external-runner.md new file mode 100644 index 000000000..c3889c4e6 --- /dev/null +++ b/docs/decisions/ADR-0063-background-work-uses-an-external-runner.md @@ -0,0 +1,92 @@ +# ADR-0063: Background Work Is Resumable and Uses an External Runner + +Status: proposed — worker isolation and recovery proofs pending + +Date: 2026-09-17 + +Follows: [ADR-0061](ADR-0061-creative-work-persists-across-refinement-rounds.md) and +[ADR-0062](ADR-0062-candidates-are-isolated-and-promoted-explicitly.md). +Refines: [ADR-0006](ADR-0006-agent-external-mcp.md), +[ADR-0008](ADR-0008-agent-capability-surface.md), and +[ADR-0032](ADR-0032-audio-io-latency-and-export-are-product-surfaces.md). + +## Context + +MCP exposes operations but does not by itself schedule an agent or keep it running. Vivid currently +has one shared App/document per process. Its synchronous audio export and asynchronous AV export +both use the active session; additional windows share that state. These facilities are foundations, +not an isolated, durable background execution system. + +## Decision + +1. **Keep reasoning and scheduling external.** A swappable runner claims work, reasons, schedules + attempts, enforces provider budgets, and reports outcomes. Vivid owns durable work records, + candidate state, constraints, validation, and deterministic operations. The MCP bridge exposes + this contract; it is not the authoritative job store or a hidden scheduler. +2. **Execute candidates in a separate local worker process initially.** The worker loads an isolated + candidate and performs edits, rendering, and evaluation without changing the foreground session. + Start with one worker and one project. Validate GPU, plugin, audio device, file-path, port, and + recovery behavior before claiming background compatibility. Foreground playback takes priority; + resource limits may throttle or pause worker activity. + The worker shares no per-user mutable state with the foreground. Known shared state in the trunk + that must be separated or disabled for a worker: the control-server port (`VIVID_PORT`), the + single autosave/recovery slot and the crash-history and quarantine records under the user data + directory, and the launch-time recovery prompt (`VIVID_NO_RECOVER`). Project-local operators + compile into the project folder on load; a candidate copy therefore compiles into its own folder, + at the cost of a compile per worker load, and those build outputs are not part of the version + snapshot. +3. **Expose durable asynchronous jobs.** Submissions return stable IDs promptly. Status and results + identify exact input versions and output artifacts. Jobs distinguish queued, running, completed, + failed, canceled, and interrupted states. A work item waiting for review is distinct from a + completed execution job. Publish review readiness only after artifacts are complete and accessible. +4. **Make reconnection safe.** Submission/feedback deduplication keys prevent duplicate effects. + Renewable work leases identify the current runner; lease generations fence stale owners from + further authoritative writes after reassignment. On restart, reconcile interrupted work against + durable checkpoints. Restarting a render from the beginning is acceptable; sample-level resume + is not required. Do not promise exactly-once provider execution after an uncertain network result. +5. **Make cancellation and revision changes explicit.** Pause stops scheduling new work and reports + whether an active operation is still stopping. Cancel requests safe termination while preserving + completed artifacts. Recheck brief/protection revisions before further mutations and publication; + superseded results retain provenance but cannot be promoted under stale constraints. +6. **Expose compact updates and honest availability.** Clients can read changes after a cursor; + expired cursors have a full-resync path. Capability discovery distinguishes unavailable operations + and workers. “Queued; no runner connected” is not “working.” Disconnected runners become + interrupted/unknown after lease expiry. Provider cost is reported as unknown when unobservable. + +The MCP surface should add work, version, review, execution, and update families above existing +editing tools. Candidate selection must be explicit or bound unambiguously to an isolated worker; +it must never fall back to the foreground project. Endpoint names and storage layouts are deferred. + +## Alternatives Considered + +- **Embed a permanent model loop in Vivid.** Couples the application to provider and scheduling churn. +- **Treat a long-lived MCP connection as durable work.** Connection lifetime does not preserve intent, + job results, or ownership after restart. +- **Use another window of the same App.** Shares the document and engine, providing no isolation. +- **Immediately build a hosted worker fleet.** Adds asset, plugin, identity, and operational scope + before proving the local creative loop. + +## Consequences + +Worker supervision, local resource contention, migrations, and recovery become explicit engineering +work. The deterministic offline AV export is already a surface-free, resumable render of the visual +graph at a synthetic clock and is the worker's render primitive; it is not rebuilt. What the worker +adds is device-free process bring-up: a GPU context created without a window surface, no audio +device opened (the foreground keeps the hardware; the sample rate is a job input), and the durable +job/lease contract above. Wrapping the existing endpoints with a job ID alone provides neither +isolation nor durability. Provider integrations remain replaceable. + +## Open Availability Boundary + +The proposed first proof uses an awake Mac. Whether the product must continue executing while that +Mac sleeps is unresolved, not an accepted limitation. That requirement would need another execution +host. Define behavior separately for closing Review, quitting Vivid, runner exit, and system sleep; +do not label any stopped execution as active. No automation is created by this ADR. + +## Acceptance Evidence Required + +Render a candidate during foreground playback/editing from a worker that has opened neither a window +surface nor an audio device. Exercise cancel, worker crash, runner restart, +lease expiry/reassignment, stale-runner writes, duplicate submissions, and sleep/wake. Demonstrate +recovery without false completion, duplicate promotion, or foreground corruption, and prove a worker +crash or autosave never populates the foreground's recovery prompt. Evidence is pending. diff --git a/docs/decisions/ADR-0064-review-is-a-workspace-alongside-creation.md b/docs/decisions/ADR-0064-review-is-a-workspace-alongside-creation.md new file mode 100644 index 000000000..cdcd04c83 --- /dev/null +++ b/docs/decisions/ADR-0064-review-is-a-workspace-alongside-creation.md @@ -0,0 +1,73 @@ +# ADR-0064: Review Is a First-Class Workspace Alongside Creation + +Status: proposed — native review interaction proof pending + +Date: 2026-09-17 + +Follows: [ADR-0061](ADR-0061-creative-work-persists-across-refinement-rounds.md). +Amends, upon acceptance: [ADR-0013](ADR-0013-focus-first-strict-zone-ui.md) and +[ADR-0014](ADR-0014-visual-graph-is-home.md). +Preserves the authoring surfaces of [ADR-0009](ADR-0009-two-surface-bridge-and-native-reboot.md). + +## Context + +The session grid and visuals graph are appropriate places to create and edit. A returning creator +with two minutes available instead needs to hear/see what changed and provide useful direction. +Making them reconstruct agent activity from graph changes or a conversation wastes that time. +The confirmed first review surface is Vivid on the creator's Mac. + +## Decision + +1. **Provide explicit Review and Create workspaces.** Create retains the audio session and visuals + graph. Review emphasizes media, comparisons, and decisions. Preserve the selected workspace; + offer a pending-review shortcut without forcibly changing context. ADR-0014's graph-is-home rule + applies within Create rather than requiring the graph to be visible in every workspace. +2. **Make the return legible.** Show the preferred version with playback, a brief “since your last + review” summary, a small decision queue, and work status with pause/resume. Status distinguishes + work in progress, review readiness, waiting, paused, and blocked, with the relevant reason. + A raw tool transcript is supporting detail rather than the main review surface. +3. **Review perceptible differences.** Each item asks one focused question and includes the baseline + and candidate media. Provide synchronized A/B playback at the relevant bars/seconds and access + to surrounding context. Visual comparisons play motion with its audio. Listening-level matching + is labeled, reversible, and affects audition only; unadjusted playback remains available. +4. **Make choices unambiguous.** Use this version, Keep as an alternative (for a clip-scoped + candidate, this places a take in the cell's Variation Well), Revise, and Dismiss have separate + meanings. Previewing and commenting do not implicitly promote. “Neither” is a valid + answer. Choosing and providing feedback must persist without requiring a connected agent. +5. **Attach feedback to its subject.** Comments target a version and, optionally, a passage or + project object. Preserve original feedback and expose its interpreted scope. The creator can + inspect protections and current direction, then enter the relevant editor for detailed work. +6. **Keep domain identity clear.** Shared review chrome hosts an audiovisual decision; audio and + visual controls remain explicitly identified. This qualifies strict domain zoning for the + combined review surface without blending the authoring editors into an ambiguous control panel. + +Rendered reviews remain playable while the runner is disconnected or busy. Native review is the +first scope; phone/browser access and remote execution are independent future decisions. + +## Alternatives Considered + +- **Review only in external chat.** Can be a client of the same records, but loses native playback, + project context, and direct access to the editors as the primary workflow. +- **Add a permanent review panel beside every editor.** Crowds the creation surfaces and competes + with the focused layout without serving occasional review well. +- **Replace the graph with a universal dashboard.** Weakens the established visual authoring model. +- **Show all generated experiments.** Transfers the agent's filtering work to the creator. + +## Consequences + +The shell gains workspace navigation and a media-focused review surface. Review uses the persistent +records from ADR-0061 and promotion contract from ADR-0062; it cannot maintain a second decision +store. Saved preview media reduces contention with the background engine but consumes storage. + +Current scene exports do not reproduce an entire performance's scene launches. Review evidence must +include a playback recipe with timing, scene transitions, and warm-up when relevant. Begin with a +reproducible scene excerpt; do not present that proof as full-song review. A Cue Path versus timeline +decision is outside this ADR. + +## Acceptance Evidence Required + +Use real audio and moving visuals to compare a baseline and two alternatives. Measure whether a +returning creator can understand the change, choose or reject it, and leave passage-specific feedback +within two minutes without reading a transcript. Test no agent connection, old-version feedback, +neither-candidate selection, and returning to manual creation without losing context. Evidence is +pending; exact layout should follow this interaction proof. diff --git a/docs/product/continuous-creative-workflow.md b/docs/product/continuous-creative-workflow.md new file mode 100644 index 000000000..12582a002 --- /dev/null +++ b/docs/product/continuous-creative-workflow.md @@ -0,0 +1,286 @@ +# Continuous Creative Work: Discussion Plan + +Status: draft for discussion — proposed direction, not an accepted ADR or implementation spec + +Date: 2026-09-17 + +## Product premise + +Vivid should support a creator with a full-time job who can give occasional feedback while songs +and visuals develop over time. The central loop is direction → bounded exploration → review → +refinement. Work persists across conversations and application restarts; each review should require +little reconstruction of context. + +The goal is useful creative progress per minute of human attention. Continuous operation means +work can resume when appropriate; it does not require constant computation or constant changes. +Finishing and exporting remain possible milestones within a continuing project. + +Confirmed in discussion: the first review surface is Vivid on the creator's Mac. Background work +may explore freely in candidates within the brief and protections; the creator chooses what becomes +current. These preferences are settled inputs to the proposed design, not yet accepted ADRs. + +## A concrete day + +1. Before work, the creator says: “Keep the drums and bass. Make the chorus feel more expansive, + and let the visuals open up with it. Give me two directions.” +2. Vivid records that direction against the current project version. It distinguishes hard + protections from preferences and shows how the request was interpreted. +3. An external agent explores candidate copies within the time, cost, and scope available. It can + discard weak attempts, render excerpts, and check technical and musical/visual intent. +4. The creator returns to two synchronized audiovisual excerpts, a short account of what changed, + and one useful question. The current preferred version remains available for comparison. +5. The creator chooses A and comments at bar 25: “Keep this opening, but the particles get too busy.” +6. The decision and comment are saved against that exact candidate and passage. The next round + starts from the chosen version and revises the particle behavior within the existing direction. +7. If the creator does not return, the system preserves the results. It may continue independent + authorized work, but does not repeatedly branch an unresolved choice into an ever-growing queue. + +This is a proposed scenario, not a promise of current functionality. + +## Proposed product rules + +- Work and feedback outlive the agent conversation. A fresh agent can recover the brief, current + version, unresolved choices, protections, and why previous candidates were kept or rejected. +- Exploration preserves a known preferred version. Choosing a version and merely previewing it + are different actions. +- Human decisions and automated evaluation are recorded separately. A model's score cannot stand + in for the creator's preference or silently establish a new creative direction. +- Review is optional until a meaningful choice is needed. Routine iterations do not ask for + approval. Stated constraints bound what can proceed without further direction. +- Silence is neither acceptance nor rejection. A full review queue creates backpressure. +- When the creator returns to edit, their session remains responsive and their changes are protected. +- All surfaces use the same durable work records. Chat, native UI, and a possible remote review + surface must not maintain competing copies of feedback or project decisions. + +## Interface proposal + +Introduce an explicit **Review** workspace alongside **Create**. Create retains the session and +visual graph. Review emphasizes playback, comparisons, feedback, and resuming work. Preserve the +last selected workspace; test whether returning to pending reviews should offer a shortcut rather +than forcibly changing the creator's context. + +The first review screen should contain: + +- Current preferred version, immediately playable. +- A short “since your last review” summary. +- A small queue of decisions, each with one question, candidate media, and the baseline. +- A compact work indicator: working, ready for review, waiting, paused, or blocked, with a reason. +- A visible control to pause or resume background work. + +A review item supports synchronized A/B playback, a clearly labeled listening-level match option, +and jumping to the relevant bars or seconds. Matching playback levels must not alter the authored +mix. Keep access to unadjusted playback when judging loudness or dynamics. A short excerpt needs +access to surrounding context; a good eight-bar loop is not proof of a good song. + +Actions should distinguish **Use this version**, **Keep as an alternative**, **Revise**, and +**Dismiss**. A comment alone does not necessarily choose a version. Feedback can refer to audio, +visuals, their relationship, a project object, or a passage. Cross-domain review uses shared +workspace chrome with explicitly labeled audio/visual controls. + +“Use A's music with B's visuals” is a useful eventual interaction, but is a new composition that +requires compatibility checks and a new preview. It is not a free merge of two independent files: +tempo, mappings, timing, and dependencies may differ. + +### Persistent direction and protection + +Show a concise project brief with desired character, current focus, preserved elements, and things +to avoid. Retain the user's wording alongside any structured interpretation. + +Separate hard protections (“do not change these notes”) from preferences (“keep the feeling of this +groove”). Protection scope must be intelligible: preserving notes does not preserve perceived sound +if downstream effects, tempo, or mappings can still change. Report the covered objects and relevant +dependencies. Ambiguity need only block the affected work; other authorized work can continue. + +Feedback is project-specific by default. Inferring a permanent, global taste profile from one +rejected candidate would overgeneralize the creator's intent. + +## Proposed durable concepts + +These are provisional discussion terms, listed in the glossary under "Background Refinement +Vocabulary (proposed)". Their relationship to the planned Take, Variation, and Variation Well +concepts is stated in ADR-0062: the well is the same audition/keep/choose pattern at cell scope, +stored in the document, and is where a promoted or kept clip-scoped candidate lands. + +| Concept | Responsibility | +|---|---| +| Brief | Versioned creative direction, preferences, and protections. | +| Version | Immutable project snapshot with parentage and referenced assets/code/plugin state. | +| Candidate | A version proposed for a purpose, with its source brief, provenance, and evidence. | +| Work item | A bounded objective, scope, dependencies, budget, and stopping conditions. | +| Review item | A question about exact candidate versions and playable evidence. | +| Feedback | Original comment/choice, target version and passage, interpretation, and resolution. | +| Run | One execution attempt against a work item, recording inputs, progress, and outcome. | + +The preferred version is an explicit reference stored in the project document, so it saves, loads, +and undoes with the document. The open editing session may contain newer unsaved changes; those must +not be confused with the preferred snapshot. A candidate can concern a single clip or a whole +project; a clip-scoped one becomes a Take in the cell's well when promoted or kept. + +Record authored workflow metadata in portable, versioned project records. Keep media and opaque +plugin state as referenced assets, with integrity checks. Store machine-specific execution details, +credentials, and temporary caches separately. Durable run outcomes must survive even though live +process handles do not. This extends the older project-format sketch's authored/runtime distinction; +it does not make every transient status part of the creative document. + +Candidate isolation must include mutable assets, shaders, and project-local code, not just a copy +of project.json. Full snapshot format, deduplication, retention, and asset packaging need a later +implementation design. Accepted versions and unresolved review evidence cannot be silently pruned. + +## Architecture and ownership + +| Component | Owns | +|---|---| +| Vivid project/work layer | Versions, briefs, work items, feedback, reviews, validation, and atomic promotion. | +| External agent runner | Scheduling, reasoning, exploration strategy, provider use, and reporting progress. | +| Vivid execution worker | Loading an isolated candidate, applying edits, rendering, and producing evidence. | +| MCP bridge | Discovering capabilities and exposing the same project/work operations to external clients. | +| Review UI | Playback and authoring decisions over those shared records. | + +An external runner must actually be available for work to start. Writing a work item through MCP +does not itself launch or schedule an agent. Show “queued; no runner connected” distinctly from +“working.” A runner can change without losing creative history. + +Recommend proving a separate local execution process before designing an in-process multi-session +engine. Another Window shares the same App/session today and would not isolate background edits. +Separate processes still require resource limits and validation of plugin, GPU, device, recovery, +asset-path, and port behavior. They do not automatically guarantee background compatibility. + +Start with one active worker and one project. Playback in the foreground takes priority; pause or +throttle background rendering as necessary. Saving and reviewing results should work without a +connected agent. Closing a review window, quitting the worker, and putting the computer to sleep +have different consequences and must produce truthful status. Running while the machine sleeps +requires another execution host and is outside the proposed first local milestone. + +## MCP contract direction + +Add a small work/version/review layer above existing editing tools. Illustrative tool families: + +| Family | Operations and guarantees | +|---|---| +| Work | Read/update brief; create/list/claim work; report progress; pause/cancel. | +| Versions | Snapshot; create isolated candidate; inspect changes; promote against an expected revision. | +| Review | Publish/list review items; attach artifacts; record feedback; resolve choices. | +| Execution | Submit render/evaluation job; read status/result; cancel; discover capabilities. | +| Updates | Read changes after a cursor, with stable event IDs and a resync path for expired cursors. | + +Names and schemas are intentionally not frozen. Existing edits need explicit candidate targeting or +an unambiguous worker-bound session. Calls must never implicitly fall back to the foreground project. + +Required behavior: + +- Mutations carry expected revisions where stale writes matter. Promotion checks the current + document and brief/protection revisions atomically. If the creator edited meanwhile, retain the + candidate and report a conflict; first version should not attempt automatic whole-project merging. +- Retried submissions and feedback use deduplication keys so reconnects do not create duplicate + work, media, or decisions. One runner claims a work item through a renewable lease; an expired + claim is detected before another runner takes over. +- Long work returns stable IDs promptly. Completion links the exact input version to output media + and evaluation evidence. Publishing a review requires complete, accessible artifacts. +- A disconnected runner becomes interrupted or unknown after its lease expires, not silently + successful. Resume from durable checkpoints; restarting an interrupted render from the beginning + is acceptable initially. Sample-level render resumption is not required. +- Cancellation stops future work and requests the current operation to stop safely. Already finished + candidates remain inspectable. Project undo does not undo external execution or erase feedback. +- A new brief or protection invalidates dependent queued work. In-flight results retain their + provenance and are marked superseded when appropriate; they cannot be promoted under stale rules. + +Budget controls belong at the work/runner boundary: elapsed time, attempts, evaluation calls, +render resources, and provider spend where observable. Unknown cost is reported as unknown. Work +stops when its budget, review capacity, or useful exploration is exhausted. It must also be able to +say “no worthwhile improvement found” without manufacturing a review item. + +## Evidence and review quality + +Every preview identifies its version, source brief, rendered passage, render recipe, and dependencies. +For generative material, record available seeds and timing; preserve the actual rendered result even +when a plugin cannot reproduce it exactly. Feedback stays attached to the original version if later +edits change the passage's timing. + +Use technical checks to reject broken output; use content/semantic checks to assess stated intent; +use human feedback to establish preference. Keep those results distinct, including evaluator +unavailability. Do not repeatedly optimize a single score and call it artistic progress. + +Current exports render the current clip arming from beat zero. Reviewing a whole song or a section +transition needs an explicit playback recipe for scene launches/arrangement, start position, and +warm-up. Begin with a reproducible scene excerpt; prove passage and full-song rendering before +claiming unattended song development. This does not settle the separate timeline/Cue Path design. + +## Existing decisions and implementation evidence + +- [ADR-0006](../decisions/ADR-0006-agent-external-mcp.md) and + [ADR-0008](../decisions/ADR-0008-agent-capability-surface.md): retain the external agent and allow + contextual intent/feedback in Vivid. Clarify work scheduling and runner attachment. +- [ADR-0009](../decisions/ADR-0009-two-surface-bridge-and-native-reboot.md), + [ADR-0013](../decisions/ADR-0013-focus-first-strict-zone-ui.md), and + [ADR-0014](../decisions/ADR-0014-visual-graph-is-home.md): Review is an explicit alternate + workspace; the authoring layout remains intact in Create. An ADR must qualify the graph-at-launch + rule and explain shared review controls. +- [ADR-0017](../decisions/ADR-0017-every-edit-is-reversible.md): reuse canonical persistence and + the edit gateway; persistent versions complement session undo. Promotion should be one reversible + document action without rewinding the historical review record. +- [ADR-0018](../decisions/ADR-0018-a-bad-operator-must-not-cost-you-your-work.md): extend recovery + to worker failure and interrupted work. +- [ADR-0026](../decisions/ADR-0026-evaluation-asserts-quality-against-intent.md): preserve explicit + intent and honest evidence; do not equate evaluator success with human preference. +- [App architecture](../../app/ARCHITECTURE.md): one shared engine/document per process; + main-thread editing. [Audio export](../../app/src/cli/control_handlers_audio_export.cpp) is + synchronous; [AV export](../../app/src/cli/control_handlers_av_export.cpp) is asynchronous and + already renders surface-free at a synthetic clock (the worker's render primitive), but both use + the active App, and the process assumes a window-bound GPU context and a device-derived sample + rate. Isolated durable execution needs device-free bring-up around them, not a new render loop. +- [MCP tools](../../mcp/vivid_mcp.py) supply editing, capture, comparison, and evaluation + foundations. Clip writes already have a revision-check precedent in + [audio handlers](../../app/src/cli/control_handlers_audio.cpp); project-wide guards are a new contract. + +## Proposed sequence and proof gates + +1. **Review experience.** Prototype one brief, a baseline, two rendered alternatives, a passage + comment, and a preference decision. Use real media. Target: the creator can understand and steer + the change within two minutes without reading an agent transcript. Measure this, do not assume it. +2. **Persistent creative loop.** Save versions, feedback, and work items; drive one round through + existing tools on an explicitly separate working copy. Restart the agent and demonstrate it + resumes with the same decisions and protections. This proves persistence, not unattended execution. +3. **Background execution.** Run one bounded job with an isolated worker while the creator reviews + or edits. Prove responsive playback, conflict detection, cancellation, failure recovery, and no + damage to the preferred version. Test app/runner restart and sleep/wake behavior. +4. **Repeated refinement.** Run several rounds across days. Verify the review queue stays small, + feedback is applied, protected elements remain intact, and lack of improvement ends a round. + Extend from scene excerpts to section transitions and full-song context. +5. **Broader access, if needed.** Phone/browser review, multiple projects, additional workers, or + remote execution. Native Mac review is the confirmed first surface; remote access and remote + execution are separate future decisions. + +Pressure tests must also cover: no response for days; a manual edit while a candidate renders; +feedback on an older preview; an agent retry after a lost response; a worker crash; missing plugin +or asset; no evaluator; new protections during a run; and choosing neither candidate. Record actual +results before claiming these gates passed. + +## Proposed ADRs + +1. **[ADR-0061: Creative work persists across bounded refinement rounds](../decisions/ADR-0061-creative-work-persists-across-refinement-rounds.md).** Product loop, brief/feedback + ownership, human authority, review capacity, and stopping conditions. Refines the PRD and ADR-0008. +2. **[ADR-0062: Candidates are isolated, versioned, and promoted explicitly](../decisions/ADR-0062-candidates-are-isolated-and-promoted-explicitly.md).** Snapshot boundaries, dependency + integrity, preferred-version semantics, concurrency, and the relationship to undo/persistence. +3. **[ADR-0063: Background work is resumable and uses an external runner](../decisions/ADR-0063-background-work-uses-an-external-runner.md).** Host/runner/worker + boundaries, durable work and job contracts, budgets, failure recovery, and MCP responsibilities. +4. **[ADR-0064: Review is a first-class workspace alongside creation](../decisions/ADR-0064-review-is-a-workspace-alongside-creation.md).** Playback, scoped feedback, returning-user + navigation, and amendments to graph-home and domain-zone decisions. + +These records are drafted with proposed status. Acceptance should name the evidence and remaining +limitations. The interaction, persistence, and execution proofs are pending; the documents do not +claim implemented behavior. + +## Confirmed choices and remaining questions + +- **Confirmed — review location:** Vivid on the creator's Mac. Phone/browser review is deferred. +- **Confirmed — authority:** freely explore candidates within the brief and protections; the creator + explicitly chooses what becomes current. Automatic promotion is outside this first design. +- **Execution availability:** is an awake Mac sufficient initially, or must work continue when it is + asleep? An always-on local host and a hosted worker have different plugin and asset requirements. +- **First creative scope:** improve an existing scene/song, or also develop a blank project? Recommend + starting from an existing scene to test refinement separately from initial composition quality. +- **Stopping and review volume:** propose two meaningful alternatives per decision and one unresolved + decision per work item initially. Validate rather than hard-code these as universal limits. + +No runner, automation, production interface change, or accepted architectural decision is created by +this discussion document. diff --git a/docs/product/glossary.md b/docs/product/glossary.md index ecf7ff55c..01b89e566 100644 --- a/docs/product/glossary.md +++ b/docs/product/glossary.md @@ -14,6 +14,29 @@ schemas, APIs, UI labels, MCP tools, or implementation assumptions. ## Terms +### Background Refinement Vocabulary _(proposed)_ + +The following terms belong to the proposed +[continuous creative workflow](continuous-creative-workflow.md) and ADR-0061 through ADR-0064. +They describe unimplemented work and are not accepted product contracts yet. + +- **Brief:** versioned creative direction, preferences, and protections for a project or work item. +- **Version:** an immutable project snapshot with parentage and referenced dependencies. +- **Preferred Version:** the explicitly chosen version; the open editing session may contain newer + unsaved changes. +- **Candidate:** a version proposed for a purpose, with its source brief, provenance, and evidence. + Its scope can span a clip, scene, or project; a clip-scoped candidate, once promoted or kept, lands + in the cell's Variation Well as a Take (see Take, Variation Well). +- **Work Item:** a bounded objective with scope, dependencies, budget, and stopping conditions. +- **Run:** one execution attempt against a work item, with recorded inputs, progress, and outcome. +- **Review Item:** a focused question about exact candidate versions and playable evidence. +- **Feedback:** a recorded comment or choice with its version/passage target, interpretation, and + resolution. +- **Runner:** an external process that schedules and reasons about work through Vivid's contract. +- **Worker:** an isolated execution process that edits or renders candidate content. +- **Promotion:** the explicit creator action that makes a candidate current, subject to revision + and protection checks; distinct from previewing or keeping an alternative. + ### Agent The LLM collaborator that inspects, explains, edits, varies, and pressure-tests a Vivid project using