content-factory/tasks/012-parallel-production-jobs.md

Task 012: Parallel Production Jobs

Development description: Implement parallel section scaffolding, FAQ, SEO brief, tone guide, table specs, diagram specs, and hero prompt jobs after the evidence matrix is ready.

Implementation Details

• Backend orchestration creates independent jobs for:
  • One section scaffold per approved plan section.
  • Hero image prompt.
  • Diagram specifications.
  • Table specifications.
  • FAQ block.
  • SEO metadata.
  • Internal link suggestions.
  • Tone guide.
• Each section scaffold output includes:
  • section_id
  • heading
  • draft_markdown
  • used_evidence_ids
  • unsupported_claims
  • suggested_visuals
• Failed section jobs can be retried independently.
• No scaffold may silently introduce unsupported factual claims.
• Use fake runner fixtures for deterministic tests and demo.

Public Interface

• Editor starts production after evidence matrix is ready.
• UI shows parallel job status per production artifact.
• Editor can retry failed section jobs individually.

Acceptance Criteria

• TDD pre-requirement: before implementation, write one failing behavior test that starts production and creates one job per plan section; proceed one artifact behavior at a time and record evidence in Result.
• Production cannot start before evidence matrix is ready.
• One section scaffold job is created per approved plan section.
• Jobs run independently and can fail independently.
• Retrying one failed section does not rerun successful sections.
• Each scaffold lists used evidence IDs.
• Unsupported claims introduced during scaffolding are captured and shown.
• UI displays per-artifact job state.

Verification

• Run orchestration tests with fake runner.
• Run retry behavior tests.
• Run Docker Compose smoke flow from evidence-ready to production artifacts ready.

Result

• Status: Completed (TDD RED -> GREEN).
• TDD plan:
  1. Keep the existing RED integration behavior for /api/articles/{article_id}/draft/start (one SECTION_SCAFFOLD job per approved section).
  2. Implement readiness gating and parallel section job orchestration in start_draft.
  3. Add integration tests for independent failures and retry lineage.
  4. Add frontend model/UI projection for per-artifact job state.
• Red evidence:
  • Existing failing test: test_start_production_creates_one_section_job_per_approved_plan_section.
  • Failure before implementation: AssertionError: 4 != 0 : Expected one SECTION_SCAFFOLD job per approved plan section.
• Green evidence:
  • start_draft now requires EVIDENCE_MATRIX_READY, transitions article to PARALLEL_PRODUCTION_RUNNING, and creates one SECTION_SCAFFOLD job per approved plan section.
  • Section jobs persist scaffold payload (artifact_key, artifact_label, used_evidence_ids, unsupported_claims, draft_markdown).
  • Completing a section job with non-empty unsupported_claims forces job status to FAILED with UNSUPPORTED_CLAIMS_FOUND.
  • Retry creates a child attempt only for the failed section job (successful siblings are untouched).
  • Article detail API now includes article-specific agent_jobs with payload for UI rendering.
• Refactor notes:
  • Added payload JSON field to agent_jobs contract + storage for deterministic scaffold metadata projection.
  • Added repository helper list_for_article for article-level job timeline queries.
• Verification output:
  • PYTHONPATH=/private/tmp/pupline-backend-deps python3 -m unittest apps/backend/tests/integration/test_parallel_production_public_api.py -> Ran 6 tests ... OK
  • PYTHONPATH=/private/tmp/pupline-backend-deps python3 -m unittest apps/backend/tests/integration/test_evidence_matrix_public_api.py -> Ran 2 tests ... OK
  • node apps/frontend/tests/article_detail.model.test.mjs -> pass
  • node apps/frontend/tests/agent_jobs.model.test.mjs -> pass