content-factory/tasks/002-shared-domain-contracts.md

Task 002: Shared Domain Contracts

Development description: Implement the shared domain schema package that defines workflow statuses, role names, API DTOs, and validation contracts used consistently by backend, frontend, runner, and tests.

Implementation Details

• Define canonical enums for:
  • Roles: ADMIN, EDITOR.
  • Article workflow statuses from ARTICLE_BRIEF_CREATED through PUBLISH_COMMIT_CREATED.
  • Agent job statuses and error categories.
  • Claim support statuses and risk levels.
  • Publishing statuses.
• Define shared request/response schemas for:
  • Article create/list/detail.
  • Target site config.
  • Script/config version.
  • Agent job.
  • Research artifact manifest.
  • Plan, draft, evidence, asset, review, and publish commit summaries.
• Choose one source of truth for validation:
  • Recommended implementation: Pydantic models in backend plus generated OpenAPI client/types for frontend.
  • Shared package may hold OpenAPI schema snapshots and TypeScript types generated from backend.
• Add schema validation tests for representative valid and invalid payloads.

Public Interface

• Backend exposes OpenAPI JSON with the canonical contracts.
• Frontend imports generated API types instead of duplicating DTO shapes.
• Runner consumes backend contracts for job input/output validation.

Acceptance Criteria

• TDD pre-requirement: before implementation, write a failing contract test for one externally visible DTO and one invalid payload; proceed one schema at a time and record red-green evidence in Result.
• Workflow status transitions use shared constants rather than string literals spread across apps.
• Role names are exactly ADMIN and EDITOR.
• Generated frontend types match backend OpenAPI.
• Contract tests fail on missing required fields and invalid enum values.
• Runner job output schemas can be validated without importing frontend code.

Verification

• Run backend schema tests.
• Generate frontend API types.
• Run a typecheck in frontend against generated types.

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.