docs: lock C2 changeset commit contract

docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md

@@ -554,13 +554,14 @@ commit gate 判定：
 
 当前最建议下一步执行：
 
-**Phase C2：ChangeSet commit 入库。**
+**Phase C2：ChangeSet commit 后端与前端实现。**
 
 原因：
 
 - A3 已完成真实只读投影，Phase B 已完成真实 Project Launch 创建链。
 - Phase C1 已把项目内消息、结构化候选、审查动作和证据链落到真实表。
-- 当前缺口是把已接受/已编辑的 ChangeItem 经 commit 写入 `truth_nodes / tasks / semantic_facts`，并补齐高风险 approval gate。
+- C2-contract 已锁定 commit API、原子提交规则、响应合同和失败语义。
+- 当前缺口是按合同把已接受/已编辑的 ChangeItem 经 commit 写入 `truth_nodes / tasks / semantic_facts`，并补齐高风险 approval gate。
 
 ### 7.1 Phase A 建议拆成三个小任务
 
@@ -610,6 +611,37 @@ commit gate 判定：
 
 ## 8. 进度台账
 
+### 2026-04-26 / G0 Freeze + C2 Contract / done
+
+完成内容：
+
+- 将当前非删除工作区成果直接 checkpoint 到 `master`，形成 `b52428f docs: codify PMFlow product delivery governance` 与 `e04ea4d chore: checkpoint current PMFlow workspace` 两个提交；删除痕迹未提交，避免未确认地固化旧截图、表格、tunnel 脚本和临时文件删除。
+- 收口 Phase C2 commit 合同：`POST /pmflow-os/change-sets/{change_set_id}/commit` 的请求体、权限、原子提交模式、响应结构、错误码、高风险 approval gate、C2 V1 objectType 白名单和 ProjectTruthState 投影规则。
+- 明确 C2 V1 默认 `mode=atomic`，任一 eligible item 写入失败时整个 commit 回滚，禁止半写入 Project Memory。
+- 明确 C2 必须实现 `Requirement / Decision / Task / Risk`；`Release` 可选；`ModelDecision / MetricSignal` 暂缓并必须 fail-closed。
+
+涉及文件：
+
+- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`
+- `docs/architecture/API_CONTRACTS.md`
+- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
+
+验证：
+
+- `git status --short --branch` 已确认 checkpoint 后仅剩未提交删除痕迹。
+- `git diff --cached --name-status` 阶段检查未发现删除项被纳入 checkpoint。
+- 本轮 C2-contract 只改合同文档，未新增代码、Schema 或 migration，未运行编译/单测。
+
+未完成或风险：
+
+- 工作区仍有未提交删除痕迹，需用户单独确认是否删除或恢复。
+- C2 后端 route/service/schema 与前端 API/store 尚未实现。
+
+下一步建议：
+
+- 执行 `C2-backend`：实现 atomic ChangeSet commit service、route、权限、事务、高风险 gate 与后端测试。
+- 合同稳定后并行执行 `C2-frontend`：接入 commit API，替换真实模式下的 demo-only `promoteAcceptedToGraph`。
+
 ### 2026-04-26 / Parallel Delivery Governance / done
 
 完成内容：

docs/architecture/API_CONTRACTS.md

@@ -1,5 +1,40 @@
 # 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`

docs/architecture/CODE_REFERENCE_INDEX.md

@@ -89,7 +89,7 @@
 - SSTC 负责人推荐接口：参考 `POST /projects/{project_id}/tasks/{task_id}/recommend-assignee`
 - SSTC 任务更新接口：参考 `PATCH /projects/{project_id}/tasks/{task_id}`
 - SSTC 发布创建接口：参考 `POST /projects/{project_id}/releases`
-- PMFlow OS 真实读路径与 C1 Change Review API：参考 `backend/app/api/pmflow_os_api/`、`backend/app/services/pmflow_os_projection_service.py`、`backend/app/services/pmflow_change_review_service.py`、`backend/app/schemas/pmflow_os.py`；只读提供 `GET /pmflow-os/projects/{project_id}/truth-state` 与 `GET /pmflow-os/projects/{project_id}/execution-summary`，复用 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync`，并读取 `pmflow_threads / pmflow_thread_messages / pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`；C1 写 API 包括 thread message、`proposed_items` extraction、ChangeSet detail、ChangeItem `accept/edit/defer`，不实现 commit
+- PMFlow OS 真实读路径与 C1 Change Review API：参考 `backend/app/api/pmflow_os_api/`、`backend/app/services/pmflow_os_projection_service.py`、`backend/app/services/pmflow_change_review_service.py`、`backend/app/schemas/pmflow_os.py`；只读提供 `GET /pmflow-os/projects/{project_id}/truth-state` 与 `GET /pmflow-os/projects/{project_id}/execution-summary`，复用 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync`，并读取 `pmflow_threads / pmflow_thread_messages / pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`；C1 写 API 包括 thread message、`proposed_items` extraction、ChangeSet detail、ChangeItem `accept/edit/defer`，C2 commit 合同已锁定为 `POST /pmflow-os/change-sets/{change_set_id}/commit`，默认 `mode=atomic`，实现前必须先读 `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md` 与 `docs/architecture/API_CONTRACTS.md`
 - Project Launch 真实创建链：参考 `backend/app/api/pmflow_launch_api/`、`backend/app/services/pmflow_launch_service.py`、`backend/app/schemas/pmflow_launch.py` 与模型 `backend/app/models/pmflow_launch.py`；接口为 `POST /pmflow-launch/drafts` 与 `POST /pmflow-launch/drafts/{draft_id}/confirm`，draft 只写 `pmflow_launch_drafts`，confirm 在同一事务内创建 `projects / user_projects / pmflow_threads / pmflow_thread_messages / truth_nodes / tasks / semantic_facts seed / operation_logs`
 - PMFlow Change Review 模型与 migration：参考 `backend/app/models/pmflow_change_review.py` 与 `backend/alembic/versions/20260426_add_pmflow_change_review_tables.py`；只包含 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`，本阶段不得新增或依赖 `/commit`
 

docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md

@@ -2,7 +2,7 @@
 
 版本日期：2026-04-26
 
-本文档是 PMFlow OS 从本地高保真主链走向真实数据闭环的产品级合同。它锁定对象真源、读写边界、状态流转和后续开发接口，避免 `frontend/src/features/pmflow-os/` 继续围绕 mock store 扩散。A3 已完成真实只读 projection，Phase B 已完成 Project Launch 创建链，Phase C1 已完成 Change Review 数据底座与审查状态机；ChangeSet commit 入库仍未实现。
+本文档是 PMFlow OS 从本地高保真主链走向真实数据闭环的产品级合同。它锁定对象真源、读写边界、状态流转和后续开发接口，避免 `frontend/src/features/pmflow-os/` 继续围绕 mock store 扩散。A3 已完成真实只读 projection，Phase B 已完成 Project Launch 创建链，Phase C1 已完成 Change Review 数据底座与审查状态机；Phase C2 commit 合同已收口，后续实现不得再自行改变 API shape。
 
 产品方向真源仍以 `docs/PMFLOW_PRODUCT_BLUEPRINT.md` 为准；UI 行为与状态标签以 `docs/PMFLOW_UI_CONTRACT.md` 为准；推进节奏以 `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md` 为准。
 
@@ -40,7 +40,7 @@ pmflow_approvals
 pmflow_evidence_links
 ```
 
-当前仍未实现 `/commit`，因此 accepted/edited ChangeItem 不得被投影成 confirmed Project Memory。
+当前仍未实现 `/commit` 代码，因此 accepted/edited ChangeItem 不得被投影成 confirmed Project Memory；但 C2 实现必须遵守本文 4.6 和第 5 节合同。
 
 ## 2. 对象映射表
 
@@ -261,29 +261,102 @@ POST /pmflow-os/change-items/{change_item_id}/defer
 
 ### 4.6 提交 ChangeSet
 
-Phase C1 尚未实现该接口；以下是 Phase C2 合同草案。
+Phase C2 必须按此合同实现，后端与前端不得自行发明其它请求或响应形状。
 
 ```text
 POST /pmflow-os/change-sets/{change_set_id}/commit
 ```
 
+Auth：
+
+- 当前用户必须是项目成员、`OWNER` 或 `REVIEWER`。
+- `tenant_id` 必须来自当前 JWT，不得从请求体传入。
+
+Request：
+
+```json
+{
+  "item_ids": ["12", "13"],
+  "mode": "atomic",
+  "note": "确认写入项目记忆"
+}
+```
+
+字段规则：
+
+- `item_ids` 可选；为空时提交该 ChangeSet 下全部 `accepted / edited` 项。
+- `mode` C2 V1 只允许 `atomic`；未来若支持部分提交，必须先更新本文档。
+- `note` 可选，仅进入审计，不参与业务字段生成。
+
 行为：
 
 - 只处理 `accepted / edited` 的 ChangeItem。
+- `pending_review / deferred / committed / skipped` 不写正式对象，只进入 `skippedItems` 明细。
+- C2 V1 使用单事务原子提交：任一 eligible item 写入失败时，整个 commit 回滚，不允许出现半写入 Project Memory。
 - 按 `objectType` 写入正式对象：
   - `Requirement / Decision / Risk / Release` -> `truth_nodes`
-  - `Task` -> `tasks` + 关联 `truth_nodes`
+  - `Task` -> `truth_nodes(node_type='task')` + `tasks.truth_node_id`
   - `ModelDecision` -> `project_model_bindings` 或绑定选择记录
   - `MetricSignal` -> 反馈/收入/ROI 相关记录，或生成下一轮 recommendation 草案
 - 创建或更新 `pmflow_evidence_links`。
 - 提交成功后触发 semantic facts 抽取/刷新。
-- ChangeSet 进入 `committed` 或 `partially_committed`。
+- 全部 eligible item 成功后 ChangeSet 进入 `committed`。
+- `partially_committed` 是未来扩展状态，C2 V1 不应写出该状态。
+
+Response `data`：
+
+```json
+{
+  "changeSet": {
+    "id": "10",
+    "status": "committed",
+    "rawStatus": "committed",
+    "committedAt": "2026-04-26T10:00:00+08:00",
+    "committedItemIds": ["12"],
+    "skippedItemIds": ["14"],
+    "failedItemIds": []
+  },
+  "committedItems": [
+    {
+      "changeItemId": "12",
+      "objectType": "Requirement",
+      "targetType": "truth_node",
+      "targetId": "301",
+      "status": "committed",
+      "evidenceIds": ["44"],
+      "semanticFactStatus": "queued"
+    }
+  ],
+  "skippedItems": [
+    {
+      "changeItemId": "14",
+      "objectType": "Task",
+      "status": "deferred",
+      "reason": "item_not_accepted_or_edited"
+    }
+  ],
+  "failedItems": [],
+  "projectTruthState": {}
+}
+```
+
+响应规则：
+
+- `projectTruthState` 可选；若返回，必须是 commit 后的后端真实 projection，不得由前端本地拼装。
+- `committedItems[].targetId` 必须是正式对象 id，如 `truth_nodes.id`、`tasks.id`、`project_model_bindings.id`。
+- `semanticFactStatus` 取值：`queued / seeded / skipped / failed`；失败不能影响已完成的正式对象写入，但必须进入审计或 failed detail。
 
 失败语义：
 
-- `409 no_accepted_items`：没有可提交项。
+- `404 changeset_not_found`：ChangeSet 不存在或不属于当前 tenant/project。
+- `409 changeset_not_reviewed`：仍存在 `pending_review` 项且请求未显式只提交 `item_ids`。
+- `409 changeset_already_committed`：ChangeSet 已经提交，不能重复提交。
+- `409 no_accepted_items`：没有 `accepted / edited` 可提交项。
 - `409 high_risk_approval_required`：高风险项缺少 required approval。
-- `500 commit_partial_failed`：部分项写入失败，必须返回成功/失败 item 明细，不得全部冒充成功。
+- `422 invalid_commit_item_ids`：`item_ids` 不属于该 ChangeSet 或包含不可提交状态。
+- `422 unsupported_object_type`：`objectType` 不在 C2 白名单。
+- `422 invalid_change_payload`：有效 payload 不满足正式对象必填字段。
+- `500 commit_failed`：写入正式对象失败；C2 V1 必须回滚整个事务，并返回 `failedItems` 明细，不得冒充部分成功。
 
 ### 4.7 获取执行桥摘要
 
@@ -301,22 +374,42 @@ GET /pmflow-os/projects/{project_id}/execution-summary
 
 `ChangeItem.objectType` 的提交规则：
 
+有效 payload 生成规则：
+
+- `edited` 项优先使用 `edited_payload`，否则使用 `payload`。
+- `PMFlowChangeItem.title / summary / diff` 是展示与审计主字段；payload 中同名字段只能补充，不能覆盖人工 edit 后的主字段。
+- 每个正式对象 content/payload 必须写入：`source=pmflow_change_set_commit`、`change_set_id`、`change_item_id`、`evidence_ids`、`confidence`、`risk_level`、`committed_by`、`committed_at`。
+- 所有正式写入必须带 `tenant_id` 查询边界；`truth_nodes` 历史模型若无显式 `tenant_id` 字段，必须通过所属 `project_id` 的 tenant 校验间接保证租户边界。
+
 | objectType | 正式写入目标 | 必填字段 | 写入后前端状态 |
 | --- | --- | --- | --- |
-| `Requirement` | `truth_nodes(node_type='requirement')` 或 charter content requirement block | `title`、`summary`、`stage`、证据 | `confirmed` |
+| `Requirement` | `truth_nodes(node_type='requirement')` | `title`、`summary`、`stage`、证据 | `confirmed` |
 | `Decision` | `truth_nodes(node_type='decision')` | `title`、`summary`、`owner`、证据 | `confirmed` |
-| `Task` | `tasks`，必要时创建关联 `truth_nodes` | `title`、`description/summary`、`priority`、`acceptanceCriteria` | `draft` 或 `in_progress` |
+| `Task` | `truth_nodes(node_type='task')` + `tasks` | `title`、`description/summary`、`priority`、`acceptanceCriteria` | `draft` |
 | `Risk` | `truth_nodes(node_type='risk')` | `title`、`summary`、`riskLevel`、`mitigation`、证据 | `confirmed` |
 | `ModelDecision` | `project_model_bindings` 或 `model_recommendation_snapshots` 引用 | `catalog_item_id` 或推荐快照引用 | `confirmed` |
 | `Release` | `truth_nodes(node_type='release')` + release validation 引用 | `title`、`summary`、gate items | `check_pending/ready` |
 | `MetricSignal` | `feedback_ingests`、`revenue_events`、`roi_snapshots` 投影或 recommendation 草案 | source、value、window | `confirmed` |
 
+C2 V1 白名单：
+
+- 必须实现：`Requirement / Decision / Task / Risk`。
+- 可实现但不阻塞 C2：`Release`。
+- 暂缓实现：`ModelDecision / MetricSignal`，若收到这两类 item，必须返回 `422 unsupported_object_type`，不得假成功。
+
 禁止规则：
 
 - 禁止 `accept` 时直接写正式对象。
 - 禁止没有 evidence 的高风险项进入 `commit`。
 - 禁止把 AI 生成内容直接投影为 `Project Memory` confirmed facts。
 - 禁止让前端用本地 `promoteAcceptedToGraph` 代替后端 commit。
+- 禁止 commit 后仍让 `activeChangeSetId` 指向已 committed 的 ChangeSet；projection 应选择最近 open/reviewed ChangeSet，或返回 `null`。
+
+高风险 approval gate：
+
+- `risk_level=high` 的 item 必须存在同 item 的 `pmflow_approvals` 记录，且 `decision in ('approved','edited')`、`after_status in ('accepted','edited')`。
+- 高风险 item 必须能解析到至少一个 evidence link；ChangeSet 级 evidence 可以继承给 item，但 response 里必须显式返回 `evidenceIds`。
+- gate 失败时整个 commit 不写入正式对象。
 
 ## 6. Execution Bridge 复用合同