# 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

- [x] 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`.
- [x] Plan generation creates version 1 and moves article to `PLAN_REVIEW_REQUIRED`.
- [x] Plan has at least four sections with purpose, key points, and evidence needs.
- [x] Direct plan edit creates a new immutable version.
- [x] Revision request writes workflow event and returns workflow to plan generation/revision.
- [x] Approval writes workflow event with actor, timestamp, and exact plan version.
- [x] Previous plan versions remain accessible.
- [x] 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: Accepted.
- TDD plan: Added `apps/backend/tests/integration/test_plan_generation_review_public_api.py` before implementation. The test starts from an article with submitted boundary answers, asserts research start is blocked before approval, then verifies plan generation, immutable edit versioning, revision request, approval event payload, and research unlock.
- Red evidence: Initial run failed with `409 != 404` for `POST /api/articles/{article_id}/research/start`, proving the public research gate was absent.
- Green evidence: Implemented plan contracts, schema fields, repository persistence, plan generation/review routes, research start gate, generated shared contracts, and FSD plan review frontend at `/articles/[articleId]/plans`.
- Refactor notes: Replaced the placeholder plan approval route with real plan lookup/status transitions. Added immutable plan versions and section-level key points/evidence needs while preserving previous versions in `GET /plans`.
- Verification output: `PYTHONPATH=/private/tmp/pupline-backend-deps python3 -m unittest apps/backend/tests/integration/test_plan_generation_review_public_api.py apps/backend/tests/integration/test_boundary_questions_public_api.py apps/backend/tests/integration/test_schema_storage_contracts.py apps/backend/tests/contracts/test_generated_contract_artifacts.py` passed. `pnpm --filter @pipeline/frontend test:ui` passed. `pnpm --filter @pipeline/frontend typecheck` passed. `tests/smoke/plan-flow.sh` passed with Docker Compose after Docker socket escalation.