content-factory/tasks/009-plan-generation-and-review.md

Task 009: Plan Generation And Review Gate

Development description: Implement article plan generation, immutable plan versioning, direct plan edits, revision requests, and final plan approval before research.

Implementation Details

• Backend endpoints:
  • POST /api/articles/{article_id}/plan/generate
  • GET /api/articles/{article_id}/plans
  • GET /api/articles/{article_id}/plans/{plan_id}
  • PATCH /api/articles/{article_id}/plans/{plan_id}
  • POST /api/articles/{article_id}/plans/{plan_id}/approve
  • POST /api/articles/{article_id}/plans/{plan_id}/request-revision
• Plan generation uses:
  • Brief.
  • Boundary answers.
  • Target site config.
  • Output schema.
• Plan must include:
  • Title options.
  • Recommended title.
  • Reader persona.
  • Search intent.
  • Thesis.
  • At least four sections.
  • Claims to prove.
  • Evidence needs.
  • Visual needs.
  • SEO notes.
  • Risks.
• Edits create new immutable versions rather than mutating approval-relevant content in place.
• Research cannot start until plan is approved.

Public Interface

• Editor generates a plan.
• Editor edits, requests revision, or approves the plan.
• Approved plan becomes the production contract for research.

Acceptance Criteria

• TDD pre-requirement: before implementation, write one failing public API test showing research cannot start before plan approval; implement generation/review behavior in vertical cycles and record evidence in Result.
• Plan generation creates version 1 and moves article to PLAN_REVIEW_REQUIRED.
• Plan has at least four sections with purpose, key points, and evidence needs.
• Direct plan edit creates a new immutable version.
• Revision request writes workflow event and returns workflow to plan generation/revision.
• Approval writes workflow event with actor, timestamp, and exact plan version.
• Previous plan versions remain accessible.
• Frontend supports approve, request revision, direct edit, section notes, source requirements, excluded sources, visual requirements, tone, audience, and SEO keyword changes.

Verification

• Run plan API integration tests with fake runner output.
• Run frontend plan review tests.
• Run a Docker Compose smoke flow through plan approval.

Result

• Status: Pending execution.
• TDD plan: To be filled during execution.
• Red evidence: To be filled during execution.
• Green evidence: To be filled during execution.
• Refactor notes: To be filled during execution.
• Verification output: To be filled during execution.