Skip to content

docs: propose ADR-0061..0064 — the continuous creative workflow - #369

Merged
jeffcrouse merged 2 commits into
mainfrom
docs-adr-0061-0064-continuous-creative-workflow
Sep 18, 2026
Merged

jeffcrouse merged 2 commits into
mainfrom
docs-adr-0061-0064-continuous-creative-workflow

Conversation

@jeffcrouse

Copy link
Copy Markdown
Member

Summary

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

Also: a "Background Refinement Vocabulary (proposed)" section in the glossary, and a pointer from docs/README.md.

Reconciled against the trunk before proposing

# Question Resolution
1 Where does the preferred-version reference live? A document field. Promotion is one edit-gateway command that replaces content + pointer together, so UndoManager's whole-document snapshots restore both for free. A whole-document revision counter (per-clip rev from #313 is the precedent) backs the stale-promotion check, including unsaved manual edits. (ADR-0062 §1/§3/§4/§5)
2 What per-user state would a worker process share with the foreground? Named the real traps: VIVID_PORT (main.cpp:594), the single autosave/recovery slot under user_data_dir()/autosave/ (a worker autosave would populate the foreground's recovery prompt), crash-history/quarantine records, VIVID_NO_RECOVER. Project-local operators compile into the candidate copy on load (isolation holds; a compile per worker load; build outputs are not snapshot content). (ADR-0063 §2 + acceptance evidence)
3 Does a worker need a new offscreen render path? No. The deterministic offline AV export (av_bounce_app.cpp) already renders surface-free at a synthetic clock and is resumable. The gap is device-free bring-up: GpuContext::init needs a GLFWwindow*/compatibleSurface, and av_export_start refuses without a device-derived sample rate. Worker = headless GPU context + no audio device + sample rate as a job input. (ADR-0063 Consequences + acceptance evidence)
4 Candidate vs. the planned Take / Variation Well? Same audition/keep/choose pattern at version vs. cell scope. The well is in-document content; candidates live in work records with one pointer in the document. A promoted or kept clip-scoped candidate lands in the well as a take; the well never holds candidate identity, evidence, or feedback. (ADR-0062, ADR-0064 §4, glossary)
5 Drift between the discussion doc and the ADRs Aligned the ADR-0063 title and the four paragraphs that repeated pre-reconciliation claims.

Status

All four ADRs are proposed with acceptance evidence pending — no runner, automation, or UI change is created here. Proof sequence in the discussion doc: Review UX → persistence across agent restart → isolated background execution → multi-day rounds.

Test plan

  • Every relative link in the seven touched files resolves (scripted check)
  • Docs-only change — no build/test impact

🤖 Generated with Claude Code

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) <noreply@anthropic.com>
@jeffcrouse
jeffcrouse enabled auto-merge (squash) September 18, 2026 00:49
@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Production gate (core): ✅ PASS

  • 88/88 tests passed (0 failed) in 18.472s

@jeffcrouse
jeffcrouse merged commit 549f29a into main Sep 18, 2026
8 checks passed
@jeffcrouse
jeffcrouse deleted the docs-adr-0061-0064-continuous-creative-workflow branch September 18, 2026 01:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant