MVP-1 creator/reviewer loop

This explanation documents the MVP-1 creator/reviewer loop as implemented by the review loop orchestrator. It focuses on the orchestration flow, convergence rules, sticky decisions, and the protocol artifacts written to workspace storage.

Roles and orchestration flow

The MVP-1 loop is driven by run_review_loop_orchestrator, which coordinates a creator and reviewer runner (often backed by different models) and then persists the results.

  1. Load workspace state and look for existing candidates under copy/candidates/<asset_id>/candidate_*.json.

  2. If a seed candidate exists, wrap the creator so its first call receives that candidate as CreatorInput.previous_candidate.

  3. Wrap the reviewer so it can enforce locked selections for certain assets.

  4. Run the core loop engine (run_review_loop_engine) to produce new iterations and a protocol decision.

  5. Write protocol JSON (copy/protocol/...), candidates, reviews, selected text (if converged), and the updated state.json workspace snapshot.

Convergence rules

The loop engine decides convergence per iteration:

  • Converged when the reviewer verdict is ok and the creator returns done=True.

  • If the loop reaches max_iterations without convergence, the outcome is needs_human with reason iteration_limit.

  • A reviewer verdict of needs_human is recorded but does not stop the loop on its own.

  • If an existing protocol decision is terminal and has outcome locked, the engine returns immediately with no new writes, preventing replays from changing history.

Sticky decisions

Two sticky behaviors prevent regressions once a decision is made:

  • Locked protocol decisions: LoopDecision locks outcome, final_iteration, and reason when a terminal decision is created. When rerunning the loop, _merge_decision preserves locked fields from the existing decision, so later runs cannot override them.

  • Locked selected content: for slug, title_detail, title_seo, and subtitle_auphonic, the orchestrator checks for an existing selection under copy/selected/. If the current candidate differs, it injects a locked_selection error issue and downgrades an ok verdict to changes_requested.

Protocol artifacts

The MVP-1 loop produces protocol artifacts that can be inspected or surfaced by status tooling:

  • copy/protocol/<asset_id>/iteration_XX.json: per-iteration envelope with creator done, the candidate, and the reviewer payload.

  • copy/protocol/<asset_id>/state.json: protocol state snapshot with decision and all iterations; used by src/podcast_pipeline/entrypoints/status.py to report progress.

  • Supporting artifacts written alongside protocol files include:

    • copy/candidates/<asset_id>/candidate_<uuid>.json and rendered text formats.

    • copy/reviews/<asset_id>/iteration_XX.<reviewer>.json.

    • copy/selected/<asset_id>.<ext> when the loop converges.

References

  • Orchestrator: src/podcast_pipeline/review_loop_orchestrator.py

  • Loop engine: src/podcast_pipeline/review_loop_engine.py

  • Workspace layout: src/podcast_pipeline/workspace_store.py

  • Status view: src/podcast_pipeline/entrypoints/status.py