# API CONTRACTS

## PMFlow OS

### POST `/pmflow-os/change-sets/{change_set_id}/commit`
- Purpose: commit reviewed ChangeSet items into the official project truth layer.
- Auth: project member, `OWNER`, or `REVIEWER`; tenant comes from JWT.
- Request body:
  - `item_ids?: string[]` optional; default commits all `accepted / edited` items.
  - `mode: "atomic"` required for C2 V1.
  - `note?: string` audit note only.
- Behavior:
  - Processes only `accepted / edited` ChangeItems.
  - C2 V1 is atomic: any eligible item write failure rolls back the whole commit.
  - Required C2 objectType support: `Requirement / Decision / Task / Risk`.
  - Optional C2 objectType support: `Release`.
  - Unsupported for C2 V1: `ModelDecision / MetricSignal`, which must fail with `422 unsupported_object_type`.
  - `Requirement / Decision / Risk / Release` write to `truth_nodes`.
  - `Task` writes `truth_nodes(node_type='task')` plus `tasks.truth_node_id`.
  - High-risk items require item-level approval with `decision in ('approved','edited')` and `after_status in ('accepted','edited')`.
- Response data:
  - `changeSet`: `{ id, status, rawStatus, committedAt, committedItemIds, skippedItemIds, failedItemIds }`
  - `committedItems[]`: `{ changeItemId, objectType, targetType, targetId, status, evidenceIds, semanticFactStatus }`
  - `skippedItems[]`: `{ changeItemId, objectType, status, reason }`
  - `failedItems[]`: `{ changeItemId, objectType, code, message }`
  - `projectTruthState?`: optional backend projection after commit.
- Failure semantics:
  - `404 changeset_not_found`
  - `409 changeset_not_reviewed`
  - `409 changeset_already_committed`
  - `409 no_accepted_items`
  - `409 high_risk_approval_required`
  - `422 invalid_commit_item_ids`
  - `422 unsupported_object_type`
  - `422 invalid_change_payload`
  - `500 commit_failed`

## Signal & SSTC

### GET `/projects/{project_id}/signals`
- Response data:
  - `items[]` includes planner fields:
    - `planner_status: "pending" | "completed" | "failed"`
    - `planner_analyzed_at: string | null`
    - `planner_assignee_user_id: string | null`
    - `strategic_analysis: object`

## Model Routing

### GET `/model-routing/functions/{function_name}`
- Purpose: query effective routing for function
- Response data:
  - `function_name`
  - `provider`
  - `model`
  - `api_env`
  - `tier`
  - `source: "default" | "override"`

### PUT `/model-routing/functions/{function_name}`
- Auth: manager/admin only
- Request body:
  - `provider`, `model`, `api_env`, `tier`
- Side effects:
  - persist override into `integrations(type='model_routing')`
  - append audit to `operation_logs`

## Task Briefs

### GET `/task-briefs/center`
- Purpose: list generated brief cards

### GET `/task-briefs/templates`
- Purpose: list templates

### POST `/task-briefs/templates`
- Purpose: create template

### PUT `/task-briefs/templates/{template_id}`
- Purpose: update template

### GET `/task-briefs/runs`
- Purpose: list generation runs

### POST `/task-briefs/generate`
- Purpose: generate one task brief run

### GET `/task-briefs/contract-sync`
- Purpose: expose docs/contract sync status snapshot