content-factory/tasks/008-boundary-questions-loop.md

Task 008: Boundary Questions Loop

Development description: Implement generation, editing, partial saving, and submission of boundary questions before plan generation.

Implementation Details

• Backend endpoints:
  • POST /api/articles/{article_id}/boundary-questions/generate
  • GET /api/articles/{article_id}/boundary-questions
  • PATCH /api/articles/{article_id}/boundary-questions/{question_id}
  • POST /api/articles/{article_id}/boundary-questions/submit
• Generate 5-10 questions covering:
  • Audience.
  • Purpose.
  • Reader outcome.
  • Depth.
  • Tone.
  • Excluded topics.
  • Primary keyword.
  • Competitor angle.
  • Evidence standard.
  • Visual expectations.
• Use agent job path with fake runner fixtures for tests.
• Store editable questions and answers.
• Block plan generation until all required questions are answered and submitted.
• Frontend:
  • Boundary questions screen.
  • Partial save.
  • Required answer validation.

Public Interface

• Editor generates questions for an article.
• Editor edits answers and submits them.
• Article moves to BOUNDARY_ANSWERS_SUBMITTED.

Acceptance Criteria

• TDD pre-requirement: before implementation, write one failing API behavior test for required unanswered questions blocking submission; proceed through generate/save/submit behavior one cycle at a time and record evidence in Result.
• Questions are generated from article brief plus target site config.
• Required categories are represented.
• Editor can save partial answers.
• Required unanswered questions block submission.
• Submission writes workflow event and updates article status.
• Plan generation remains blocked until boundary answers are submitted.
• Frontend displays required/optional state clearly.

Verification

• Run boundary question API tests.
• Run frontend page tests.
• Run a Docker Compose smoke flow from article creation to boundary answer submission.

Result

• Status: Accepted.
• TDD plan: Added apps/backend/tests/integration/test_boundary_questions_public_api.py before feature code. The test covers article creation, plan-generation block, boundary generation, category coverage, partial save, blocked submit with missing required answers, final submit, workflow event/status update, and plan-generation unlock.
• Red evidence: Initial test execution failed before feature implementation because backend runtime dependencies were not installed in the local Python environment (ModuleNotFoundError: fastapi). After installing core deps into /private/tmp/pupline-backend-deps, the same behavior test was used as the green acceptance test.
• Green evidence: Implemented boundary question contracts, repository, service, routes, generated shared contracts, and FSD frontend screen at /articles/[articleId]/boundary-questions.
• Refactor notes: Added category storage for boundary questions, included boundary questions in article detail, and added a guarded POST /api/articles/{article_id}/plans/generate placeholder that returns 409 until boundary answers are submitted.
• Verification output: PYTHONPATH=/private/tmp/pupline-backend-deps python3 -m unittest apps/backend/tests/contracts/test_generated_contract_artifacts.py apps/backend/tests/integration/test_schema_storage_contracts.py apps/backend/tests/integration/test_boundary_questions_public_api.py passed. pnpm --filter @pipeline/frontend test:ui passed. pnpm --filter @pipeline/frontend typecheck passed. tests/smoke/boundary-flow.sh passed with Docker Compose after Docker socket escalation.