PMFlow/docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md

# PMFlow 产品推进执行标准

版本日期：2026-04-24

本文档是 PMFlow 产品方案落地的推进标准。它回答四件事：

- 当前产品方案推进到哪里了。
- 下一步应该继续往哪里推进。
- 每次推进的范围、验收和文档回写怎么做。
- 新开 Codex 线程时如何接续，避免重做、漏做或偏离方向。

产品方向真源仍以 `docs/PMFLOW_PRODUCT_BLUEPRINT.md` 为准。本文档不重新定义战略，只管理落地节奏和进度。

## 1. 当前推进判断

截至 2026-04-24，PMFlow 已经完成“产品方向收敛 + 前端本地高保真主链 + 后端局部控制面”的阶段，但还没有完成“真实数据闭环产品化”。

### 1.1 已经推进到位的部分

#### 产品方向

- 已明确 PMFlow 不是“聊天工具 + 项目管理工具”，而是“对话驱动的 AI 产品执行操作系统”。
- 已明确首版方向为 `solo-first, team-ready`，面向个人开发者、一人公司、半技术产品创作者和 1-10 人 AI 应用小团队。
- 已明确团队协作不是传统多人维护任务表，而是围绕 AI 维护的项目真相层进行异步审查和人机混编执行。
- 已明确 V1 主链为：`创意输入 -> AI 结构化提取 -> 变更确认 -> 项目对象沉淀 -> 任务拆解 -> 推送 IDE / agent -> 开发与测试回写 -> 发布 -> 数据反馈 -> 下一轮迭代`。

真源：

- `docs/PMFLOW_PRODUCT_BLUEPRINT.md`
- `USER.md`

#### 前端产品域

当前已经存在三条独立产品域：

- `frontend/src/features/personal-space/`
  - 空间入口。
  - 用本地 mock 展示继续推进、待我确认、AI 正在推进、暂存想法、草案箱和新建项目入口。
- `frontend/src/features/project-launch/`
  - 新项目启动台。
  - 用本地状态机覆盖意图输入、AI 工作、人类确认、草案修改、失败态、创建成功态和移动端 bottom sheet。
- `frontend/src/features/pmflow-os/`
  - PMFlow OS 项目内主体验。
  - 已有本地 truth store 和页面：`CommandCenter / StructuredExtraction / ChangeReview / MemoryWritebackResult / WorkGraph / ExecutionBridge / ReleaseGrowth / TeamLayer / ProjectMemory`。
  - 已有本地状态动作：`sendMessage -> generateExtraction -> acceptChange/editChange/deferChange -> promoteAcceptedToGraph -> pushTaskToExecution -> writeBackExecution -> publishRelease -> ingestGrowthSignal`。

当前性质：

- 这是产品主链的高保真原型和本地行为闭环。
- 还不是正式后端数据闭环。
- 不接真实 AI 提取，不写真实数据库，不消费真实项目对象。

#### 后端控制面

当前已经出现 AI 应用项目控制面的初步生产化能力：

- `backend/app/models/ai_project_control.py`
  - 模型目录、项目模型绑定、模型推荐快照、模型用量、模型评测。
  - Prompt Package。
  - IDE 工作区绑定、Repo 绑定、GitHub App 安装/仓库/webhook 投递。
  - TaskCodeLink、ProgressEvent、DevSession。
  - ReleaseValidationRun、FeedbackIngest、IterationRecommendation、RevenueEvent、ROISnapshot、ComplianceCheckRun、EvidencePack。
- `backend/app/services/ai_project_control_service.py`
  - 模型推荐、模型绑定、prompt package、开发同步、GitHub/repo 绑定、进度事件、发布验证、反馈/收入/合规等服务能力。
- `backend/app/api/sstc_api/model_control.py`
  - 模型推荐、模型绑定、模型用量、Prompt Package、发布验证、反馈摄取、收入记录、合规检查等接口。
- `backend/app/api/dev_sync.py`
  - GitHub App 安装、仓库绑定、开发任务、项目 dev-sync summary、任务进度事件等接口。

当前性质：

- 后端已经有 V1 产品化需要的部分基础对象和接口。
- 但它们还没有和 `frontend/src/features/pmflow-os/` 的本地 truth store 正式打通。
- `ChangeSet / Approval / Evidence / Project Memory` 这条主产品链仍主要停留在前端本地态和旧 SSTC/semantic facts 体系之间，缺少统一的 PMFlow OS 产品级 API 合同。

### 1.2 当前缺口

当前最大缺口不是再讨论产品方向，而是：

**把已经成立的产品主链从本地原型推进成真实可用的数据闭环。**

关键缺口按优先级排序：

1. `Project Thread / ChangeSet / Evidence / Approval / Project Memory` 的前后端合同没有完全收口。
2. `project-launch` 还没有接真实 AI 结构化、真实项目创建和真实草案确认。
3. `pmflow-os` 本地 store 还没有接后端读写，当前仍是 mock truth store。
4. `ChangeReview` 的接受、修改、暂缓还没有写入正式对象、审批记录和证据链。
5. `ExecutionBridge` 页面还没有消费 dev-sync / GitHub / PromptPackage 真实接口。
6. `ReleaseGrowth` 还没有把 release validation、feedback、revenue、ROI、compliance 真实数据串成发布后反馈循环。
7. `TeamLayer` 仍是产品表达层，缺少真实成员角色、Role Inbox、Decision Desk、Team Feed 的数据模型和审查流程。

## 2. 下一步推进方向

下一步不要扩大战线，不要新增“大模块”。正确方向是：

**把 V1 主链真实闭环化。**

也就是从“本地高保真原型”推进到“真实项目对象 + 真实 AI 提取 + 真实确认写入 + 真实执行回写”。

### 2.1 下一阶段总目标

阶段目标命名为：

**V1 Productized Loop**

验收标准：

- 用户从 `/project-launch` 输入一个 AI 应用创意。
- 后端生成可审查的结构化草案或变更集。
- 用户确认后创建项目，并写入项目真相层。
- 进入 `/command-center` 后能看到真实项目线程、结构化提取、待确认项和项目对象。
- 用户接受变更后，正式对象、审批记录、证据链同步更新。
- 至少一个任务能生成 Prompt Package，并进入 Execution Bridge。
- Execution Bridge 能消费真实 dev-sync summary 或 progress event。
- 发布/反馈页能消费至少一类真实 release validation / feedback / revenue / compliance 数据。

### 2.2 暂不推进的方向

下一阶段暂不推进：

- 完整财务系统。
- 完整合规平台。
- 企业组织树和复杂权限矩阵。
- 多项目 portfolio。
- 应用市场、投融资、孵化生态。
- 前台多 agent 选择器。
- 与产品主链无关的后台治理页扩展。

这些都不是当前瓶颈。

## 3. 推荐推进顺序

### 3.0 功能原型一致性治理

任何 PMFlow 核心功能在继续出图、重画、实现或新开线程接续前，必须先确认是否已有 canonical 功能契约。若已有契约，后续只能在该契约下新增状态、补充局部区域或做明确版本迭代，不能把同一功能重新设计成另一套页面。

功能契约至少包含：

- 功能定位
- 页面/状态列表
- 固定导航壳
- 核心对象模型
- 状态标签体系
- 用户动作
- AI 动作
- 系统状态
- 移动端规则
- 不可随意改变的部分
- 可扩展的部分

确认流程：

1. 先列出本轮涉及的功能清单。
2. 每次只提交一个功能契约给用户确认。
3. 用户确认后，才把该功能契约写入本文档或对应产品真源。
4. 后续原型图、实现、验收都以已确认契约为准。
5. 如需重构，必须先说明旧版是什么、新版改什么、迁移影响是什么，并得到明确确认。

当前需要逐个确认的功能清单：

- 新项目启动台
- 个人空间首页
- 项目指挥台
- 本轮结构化提取
- 决策与待确认
- 项目记忆
- 移动端底部导航
- 项目切换器
- 项目工作台
- 开发执行联动
- 发布与增长
- 团队协作

### Phase A：产品合同收口

目标：

把 `pmflow-os` 本地类型、现有 SSTC/semantic facts/ai_project_control 后端对象和 V1 蓝图对象对齐。

范围：

- 梳理 `ProjectThread / ChangeSet / ChangeItem / Evidence / Approval / ProjectMemory / ExecutionRun` 的后端合同。
- 明确哪些对象复用现有表，哪些需要新表或投影表。
- 明确 `frontend/src/features/pmflow-os/types.ts` 如何映射到 API response。
- 明确哪些接口走已有 `sstc_api` / `dev_sync`，哪些需要新增 `pmflow_os_api`。

产物：

- API/Schema 设计说明或直接 Pydantic schema。
- 更新 `docs/architecture/CODE_REFERENCE_INDEX.md`。
- 如新增表，必须 Alembic migration。

验收：

- 能回答“前端每一个本地对象从哪个后端字段来，写回到哪里去”。
- 不能再出现前端原型对象和后端业务对象各讲各话。

### Phase B：Project Launch 真实创建链

目标：

把新项目启动台从本地状态机接到真实项目创建/草案确认主链。

范围：

- `/project-launch` 意图输入接真实 API。
- AI 结构化结果必须产出可审查草案，而不是直接静默创建。
- 用户确认后创建项目，并跳转真实 `/command-center`。
- 创建结果必须写入项目真相层初始对象：Idea、Requirement、Decision、Risk、Task 或等价 SSTC 对象。

验收：

- 真实接口创建项目。
- 失败时显式失败，不用 mock 冒充成功。
- 创建成功后进入真实项目上下文。
- 项目创建前移动端仍不展示正式底部导航。

### Phase C：Change Review 与 Project Memory 写入

目标：

让对话/结构化提取生成的 ChangeSet 能被接受、修改、暂缓，并写入正式项目对象和证据链。

当前拆分：

- C1：真实 Change Review 数据底座与审查状态机，已实现 `ChangeSet / ChangeItem / Approval / EvidenceLink` 表和 `accept / edit / defer`，但不 commit。
- C2：提交入库，把已接受/已编辑 ChangeItem 写入 `truth_nodes / tasks / semantic_facts` 并完成高风险 approval gate。

范围：

- `StructuredExtractionPage` 接真实提取结果。
- `ChangeReviewPage` 接真实 ChangeSet。
- 接受/修改/暂缓动作调用后端。
- C2 写入后 `ProjectMemoryPage / WorkGraphPage / TeamFeed` 能读到最新对象。

验收：

- ChangeSet 有 Evidence。
- 高风险变更需要 Approval。
- C1 接受后只进入 `accepted / edited / deferred` 审查状态，不进入 Project Memory。
- C2 commit 后对象状态从 proposed/draft 进入 confirmed 或对应正式状态。
- 暂缓后不进入项目真相层，但仍留审计。

### Phase D：Execution Bridge 真实开发同步

目标：

让 PMFlow 真正连接开发执行，而不是只展示执行概念。

范围：

- `ExecutionBridgePage` 消费 `devSyncApi`。
- 任务能生成 Prompt Package。
- 能绑定 repo 或展示 GitHub App 安装状态。
- 能创建或读取 ProgressEvent。
- 能把 PR/commit/test 信息回写到任务和 Team Feed。

验收：

- 至少一个真实任务能进入执行桥。
- 能看到真实 Prompt Package 或 dev task。
- 能看到真实 progress event。
- 任务状态能随回写变化。

### Phase E：Release / Growth 轻量闭环

目标：

上线后反馈进入下一轮迭代，不停在“开发完成”。

范围：

- `ReleaseGrowthPage` 消费 release validation。
- 支持 feedback ingest。
- 支持 revenue event 或基础 ROI snapshot。
- 支持 compliance check 的轻量门禁。
- 反馈能生成 IterationRecommendation 或下一轮 ChangeSet。

验收：

- 发布前有门禁。
- 发布后有反馈/收入/成本/合规至少一类真实信号。
- 信号能回流为下一轮建议，不只是展示图表。

### Phase F：Team-ready 最小闭环

目标：

不做重型团队管理，但补齐小团队围绕项目真相层协作的最小能力。

范围：

- 成员归属。
- 角色收件箱 Role Inbox。
- Team Feed。
- Decision Desk 或高风险变更多人审查。
- Agent Workforce 的只读可见化。

验收：

- 不同角色看到不同待处理项。
- 高风险 ChangeSet 能指定 reviewer/owner。
- Team Feed 展示 AI 提取、人工确认、执行回写、测试/发布变化。

## 4. 单次任务范围标准

每次 Codex 执行产品推进任务，必须控制为一个“可闭环增量”，不要跨太多面。

### 4.1 默认范围

一次任务最多覆盖：

- 一个产品表面：如 Project Launch / Change Review / Execution Bridge。
- 一个后端合同或服务切片。
- 一个前端接入切片。
- 对应测试。
- 对应文档进度回写。

如果预计改动超过 5 个核心文件或超过约 200 行业务代码，必须先拆子任务，除非是同一根因的缺陷修复。

### 4.2 推荐任务模板

每次新任务开始前，先给自己明确：

- 本次要推进的 Phase。
- 本次要打通的用户路径。
- 涉及的前端入口。
- 涉及的后端 API / service / model。
- 本次不处理的边界。
- 最小验证命令。
- 完成后要更新的进度文档。

### 4.3 禁止范围漂移

产品推进任务里禁止顺手做：

- 无关视觉重构。
- 无关后台治理页扩展。
- 无关权限体系大改。
- 无关 AI prompt 大改。
- 无关模型路由策略调整。
- 无关文案大清洗。

除非这些问题直接阻断本次用户路径。

### 4.4 Codex 并行推进协议

PMFlow 允许多个 Codex 线程并行推进，但并行单位必须是明确的 `Packet`，不能是“一个大模块”或“一个方向”。没有 `write_scope` 的任务不允许并行执行。

每个并行 `Packet` 开始前必须声明：

- `packet_id`
- `phase`
- `owner_thread`
- `base_ref`
- `read_scope`
- `write_scope`
- `forbidden_paths`
- `shared_files`
- `depends_on`
- `merge_after`
- `verification`
- `docs_to_sync`

并行硬规则：

- 只有 `write_scope` 不重叠的 Packet 才允许并行。
- 任意两个 Packet 若同时需要改 `router / schema / migration / shared API client / shared store / CLAUDE.md / CODE_REFERENCE_INDEX.md`，必须串行。
- 每轮并行最多保留一个 `contract / migration / router owner`；其它线程只能消费该 owner 已定义的稳定接口。
- 并行线程不得在自己的 `write_scope` 外做“顺手修复”；发现阻塞问题时，只记录到 integration notes 或新建后续 Packet。
- 同一批并行开发必须指定一个 `integration owner`，负责最终合并共享文件、跑集成验证和更新进度台账。

### 4.5 V1 Productized Loop 默认并行切片

V1 主链并行开发默认按 lane 切分：

- `Contract Lane`：API / Schema / DB migration / 核心对象合同，只允许单线程拥有。
- `Backend Lane`：service + route + tests，必须依赖 Contract Lane。
- `Frontend Lane`：`frontend/src/api/` + React Query / store 接入，必须依赖稳定 API 合同。
- `UI Lane`：页面展示、状态、交互、响应式，只能改功能域内组件，不能改 API 合同。
- `Docs/Test Lane`：回归补充、文档同步、验证矩阵，可以和非共享代码并行，但最终由 integration owner 统一收口。

默认合并顺序：

1. Contract / migration
2. Backend service / API
3. Frontend API / store
4. UI / page
5. Docs / test / integration

### 4.6 Phase C2 并行试点拆包

当前下一阶段 `Phase C2：ChangeSet commit 入库` 默认拆成四个 Packet：

- `C2-contract`
  - Lane：`Contract Lane`
  - 目标：定义 commit API、写入规则、高风险 approval gate、响应合同和失败语义。
  - 写范围：PMFlow OS 产品合同、API 合同、schema 草案或对应设计文档。
  - 退出条件：后端和前端实现线程不需要再自行决定 API shape。
- `C2-backend`
  - Lane：`Backend Lane`
  - 目标：实现 ChangeSet commit service、route、transaction、权限边界和后端测试。
  - 依赖：`C2-contract`
  - 写范围：`backend/app/api/pmflow_os_api/`、`backend/app/services/pmflow_change_review_service.py`、`backend/app/schemas/pmflow_os.py`、相关 tests；若需要 migration，必须回到 Contract Lane 串行处理。
- `C2-frontend`
  - Lane：`Frontend Lane`
  - 目标：接入 commit API，更新 `pmflow-os` store、Change Review 状态和错误/成功反馈。
  - 依赖：`C2-contract`
  - 写范围：`frontend/src/api/pmflowOs.ts`、`frontend/src/features/pmflow-os/store.tsx`、`ChangeReviewPage` 或 owned 组件测试。
- `C2-docs-verification`
  - Lane：`Docs/Test Lane`
  - 目标：同步产品推进台账、代码索引、API 合同、架构库存，并执行最终集成验证。
  - 依赖：`C2-backend`、`C2-frontend`
  - 写范围：文档和验证记录；共享文档由 integration owner 统一合并。

`C2-contract` 必须先完成；`C2-backend` 和 `C2-frontend` 只能在合同稳定后有限并行；最终必须由一个 integration owner 统一收口。

### 4.7 分支与 worktree 协议

并行开发默认使用独立分支和独立 worktree：

- 分支命名：`codex/<packet_id>`。
- 每个 Packet 必须记录启动时的 `base_ref`。
- 每个并行线程优先使用独立 git worktree，避免同一工作区文件互相覆盖。
- 合并前必须检查当前分支是否落后主集成分支。
- 合并前必须检查 `git diff --name-only`，确认没有写出 `write_scope`。
- 触碰共享高冲突文件时，必须交由 integration owner 合并。

### 4.8 Packet commit 协议

并行开发不是“每改一行就提交”，也不是“多个 Packet 混在一个长期分支里攒”。默认规则：

- 一个 Packet 对应一个短生命周期分支：`codex/<packet_id>`。
- Packet 完成、验证通过、文档同步完成后，必须形成至少一个可审查 commit。
- Codex 必须自行执行 commit gate 判定，不把“该不该提交”默认丢给用户判断。
- 复杂 Packet 可以在同一分支内做多个 checkpoint commit，但每个 commit 都必须是逻辑完整切片，不能提交半成品、失败验证或越界改动。
- 不允许把多个不同 Packet 的实现混进同一个 commit。
- 不允许在旧 Packet 分支上继续做新 Packet；新 Packet 必须从最新 integration base 或明确依赖分支重新开 `codex/<new_packet_id>`。
- 如果新 Packet 依赖尚未合并的 `Contract Lane`，优先等待合同分支合入；确需提前开发时，必须以该合同分支作为 `base_ref`，并在任务包里写明 `depends_on / merge_after`。
- integration owner 只合并通过 `Parallel Integration Gate` 的 Packet commit；未验证 commit 只能留在 Packet 分支内，不进入主集成分支。
- 每个 Packet 合并后，旧 Packet 分支只用于追溯，不再追加新业务改动。

commit gate 判定：

- `auto_commit`：满足全部条件时，Codex 应自行提交当前 Packet 分支。
  - 当前改动全部在 `write_scope` 内。
  - 没有混入用户或其它线程的未归属改动。
  - 触碰共享高冲突文件时，当前线程就是该文件的 owner 或 integration owner。
  - 必要验证已通过；若验证无法执行，原因和影响已经写入结果与任务包。
  - 必要文档已同步。
  - commit 内容只包含当前 Packet。
- `hold_no_commit`：满足任一条件时，Codex 不得提交，只能报告阻塞和证据。
  - 验证失败且失败与本 Packet 相关。
  - `git diff --name-only` 发现越界改动。
  - 工作区混入无法归属的用户改动或其它线程改动。
  - 发现 migration 多 head、合同不稳定、API shape 未定或依赖 Packet 未完成。
  - 需要破坏性删除、重置、强推、覆盖、批量迁移等高风险操作。
- `ask_before_commit`：满足任一条件时，Codex 必须先说明事实并等用户拍板。
  - 用户明确要求只改不提交。
  - commit 需要包含共享高冲突文件，但当前线程不是 owner。
  - 验证无法运行且该 Packet 风险较高。
  - 需要把多个 Packet 的改动临时合在一个 commit 里。
  - 需要提交历史遗留脏改动才能让当前 Packet 自洽。

推荐 commit 节奏：

1. `contract` Packet：合同文档、schema 草案或 migration 约束稳定后 commit。
2. `backend` Packet：后端实现和对应测试通过后 commit。
3. `frontend` Packet：API/store/UI 接入和对应前端验证通过后 commit。
4. `docs-verification` Packet：文档同步、最终验证记录和进度台账完成后 commit。

### 4.9 Parallel Integration Gate

每批并行开发结束后，integration owner 必须执行集成验收：

- `git diff --name-only` 检查每个 Packet 是否越界。
- 后端改动：`python -m py_compile` + 相关 `pytest`。
- 前端改动：`npm run typecheck` + `npm run build` + 相关 focused tests。
- migration 改动：`alembic heads` 必须单 head；必要时执行 `alembic upgrade head`。
- 文档：产品推进台账、代码索引、API 合同、架构库存同步完成。
- 若后端或 migration 改动已经落地，按项目规则执行热部署/重启；若不能执行，必须明确写阻塞原因。

## 5. 每次完成后的进度回写标准

后续 Codex 每完成一个 PMFlow 产品推进任务，必须自己更新进度，不需要用户额外提醒。

### 5.1 必须更新的地方

每次完成后至少更新：

1. 本文档 `## 8. 进度台账`
   - 新增一条记录。
   - 写清完成内容、影响范围、验证结果、下一步建议。
2. 如果新增/删除/重命名文件或入口：
   - 更新 `CLAUDE.md`
   - 更新 `docs/architecture/ARCHITECTURE_INVENTORY.md`
   - 更新 `docs/architecture/CODE_REFERENCE_INDEX.md`
3. 如果新增/修改 API/Schema：
   - 更新 `docs/architecture/CODE_REFERENCE_INDEX.md`
   - 必要时更新 `docs/architecture/API_CONTRACTS.md`
4. 如果新增运行边界、禁止项或系统行为约束：
   - 更新 `docs/architecture/RUNTIME_GUARDRAILS.md`
5. 如果改变产品战略或不可偏离项：
   - 更新 `docs/PMFLOW_PRODUCT_BLUEPRINT.md`
   - 更新 `USER.md`

### 5.2 进度台账记录格式

每条记录必须包含：

- 日期。
- Phase。
- 状态：`done / partial / blocked`。
- 完成内容。
- 涉及文件。
- 验证命令和结果。
- 未完成或风险。
- 下一步建议。

### 5.3 什么时候不用更新蓝图

普通实现、接 API、修 bug、补测试，不更新产品蓝图。

只有以下情况才更新蓝图：

- 用户改变产品定位。
- V1 范围改变。
- 团队方向改变。
- 新增/删除核心产品表面。
- 改变不可偏离项。

## 6. 新开线程接续标准

任何新 Codex 线程，如果用户要求继续 PMFlow 产品推进，必须先读：

1. `USER.md`
2. `docs/PMFLOW_PRODUCT_BLUEPRINT.md`
3. `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
4. `CLAUDE.md`
5. `docs/architecture/CODE_REFERENCE_INDEX.md`

然后再查当前目标相关代码。

新线程不得：

- 重新讨论 PMFlow 是否应该做对话驱动 OS。
- 重新建议变成传统项目管理工具。
- 重新发散大而全模块。
- 忽略 `## 8. 进度台账` 直接从头设计。
- 把本地原型当成真实后端闭环。
- 把已有后端 `ai_project_control / dev_sync / sstc model_control` 忽略后重造一套。

## 7. 当前下一步推荐任务

当前最建议下一步执行：

**Phase C2：ChangeSet commit 后端与前端实现。**

原因：

- A3 已完成真实只读投影，Phase B 已完成真实 Project Launch 创建链。
- Phase C1 已把项目内消息、结构化候选、审查动作和证据链落到真实表。
- C2-contract 已锁定 commit API、原子提交规则、响应合同和失败语义。
- 当前缺口是按合同把已接受/已编辑的 ChangeItem 经 commit 写入 `truth_nodes / tasks / semantic_facts`，并补齐高风险 approval gate。

### 7.1 Phase A 建议拆成三个小任务

#### A1：对象合同映射

目标：

把 `frontend/src/features/pmflow-os/types.ts` 里的对象逐一映射到现有后端对象或新增对象。

输出：

- 一张合同映射表。
- 明确复用 `TruthNode / Task / semantic facts / ai_project_control` 的边界。
- 明确是否需要新增 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`。

#### A2：API 合同设计

目标：

定义 PMFlow OS 读写 API：

- 获取项目线程和当前 Project Memory。
- 创建结构化提取请求。
- 获取 ChangeSet。
- 接受/修改/暂缓 ChangeItem。
- 将确认结果写入 Work Graph / Project Memory。
- 获取 Execution Bridge summary。

输出：

- Pydantic schema。
- API 路由设计。
- API response envelope。

#### A3：最小真实读路径

目标：

先让 `CommandCenter / ProjectMemory / WorkGraph` 从真实后端读取一个项目的摘要和正式对象。

输出：

- 前端 API 封装。
- React Query 接入。
- 本地 mock 降为 fallback/demo，不再是正式路径。
- 最小测试。

## 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

完成内容：

- 新增 Codex 并行推进协议，明确并行单位必须是带 `read_scope / write_scope / forbidden_paths / shared_files / base_ref / merge_after` 的 Packet。
- 建立 V1 Productized Loop 默认并行 lane：`Contract / Backend / Frontend / UI / Docs-Test`，并固定合同、后端、前端、UI、文档集成的合并顺序。
- 将下一阶段 Phase C2 拆成 `C2-contract / C2-backend / C2-frontend / C2-docs-verification` 四个可分派 Packet，明确依赖和写范围。
- 新增分支、worktree、Packet commit 与 commit gate 协议：并行线程默认使用 `codex/<packet_id>` 分支、记录 `base_ref`、优先独立 worktree；Packet 完成后由 Codex 自行判定 `auto_commit / hold_no_commit / ask_before_commit`，通过验证后形成可审查 commit，新 Packet 从最新 integration base 或明确依赖分支重新开分支。
- 新增 `Parallel Integration Gate`，要求 integration owner 检查越界 diff、后端/前端/migration 验证、文档同步和热部署说明。

涉及文件：

- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
- `docs/architecture/TASK_BRIEF_TEMPLATE.md`
- `AGENTS.md`
- `CLAUDE.md`
- `docs/architecture/ARCHITECTURE_INVENTORY.md`

验证：

- 文档静态检查通过：新增协议覆盖并行前置条件、Packet 模板、write scope / forbidden paths、共享文件锁、branch / worktree / base ref、Packet commit、commit gate、merge order、integration gate。
- 本轮只改治理文档，未新增代码、API、Schema 或 migration，未运行编译/单测。

未完成或风险：

- 当前仓库仍是大面积脏工作区；正式启动多线程并行前，需要先冻结当前改动归属，避免历史脏状态被误判为新冲突。

下一步建议：

- 以 `C2-contract` 作为第一条并行治理试点 Packet，先锁定 ChangeSet commit 合同，再分派后端和前端线程。

### 2026-04-25 / Phase A - PMFlow OS Product Contract / done

完成内容：

- 新增 PMFlow OS 产品合同，明确 `ProjectTruthState / Thread / Message / ChangeSet / ChangeItem / Evidence / Approval / Requirement / Decision / Task / Risk / ModelDecision / TestRun / Release / MetricSignal / ExecutionContext / TeamFeed` 的前后端映射。
- 明确复用边界：正式项目对象优先复用 `truth_nodes / tasks / semantic_facts`，AI 应用控制面复用 `ai_project_control` 与 SSTC model_control，执行桥复用 `dev_sync / prompt_packages / progress_events`。
- 明确建议新增但本轮不建表的 PMFlow OS 专属合同对象：`pmflow_threads / pmflow_thread_messages / pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`。
- 定义 PMFlow OS API 草案：`truth-state / messages / extractions / change-set detail / accept / edit / defer / commit / execution-summary`。
- 明确 `accept/edit/defer` 只改变审查状态，`commit` 才写入 `truth_nodes / tasks / semantic_facts` 等正式对象。

涉及文件：

- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`
- `docs/architecture/CODE_REFERENCE_INDEX.md`
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
- `CLAUDE.md`
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`

验证：

- 静态检查引用路径与核心对象完成。
- 本轮只改文档，未新增代码、API、Schema 或 migration，未运行编译/单测。

未完成或风险：

- API 尚未实现，数据库 migration 尚未创建。
- `truth_nodes.node_type` 的历史值需要在后续 projection 实现时做白名单映射。
- `ChangeSet / Approval / EvidenceLink / Thread` 仍需后续实现真实表与服务。

下一步建议：

- 执行 A3 最小真实读路径：新增只读 `pmflow_os_api` projection，先实现 `GET /pmflow-os/projects/{project_id}/truth-state` 与 `GET /pmflow-os/projects/{project_id}/execution-summary`。

### 2026-04-25 / A3 - PMFlow OS 最小真实读路径 / done

完成内容：

- 新增只读后端入口 `backend/app/api/pmflow_os_api/`，注册 `GET /pmflow-os/projects/{project_id}/truth-state` 与 `GET /pmflow-os/projects/{project_id}/execution-summary`，统一返回 `{code,message,data}`。
- 新增 `backend/app/services/pmflow_os_projection_service.py` 与 `backend/app/schemas/pmflow_os.py`，把 `ProjectTruthState` 投影接到真实后端对象：`Requirement / Decision / Risk / Release` 来自 `truth_nodes`，`Task` 来自 `tasks`，`Project Memory` 来自 `truth_nodes + semantic_facts`，`ExecutionContext` 来自 `dev-sync summary + prompt_packages + progress_events + repo/task code link`。
- `Thread / ChangeSet / ChangeItem / Approval / EvidenceLink` 本轮没有稳定表，不用 mock 冒充；接口返回空集合并通过 `projectionWarnings` 明确说明。
- 新增前端 API `frontend/src/api/pmflowOs.ts`，封装 `getPMFlowTruthState(projectId)` 与 `getPMFlowExecutionSummary(projectId)`。
- `frontend/src/features/pmflow-os/store.tsx` 现支持 `?projectId=<id>` 通过 React Query 读取真实 `truth-state`；只有显式 `?demo=1` 或 `?dataSource=demo` 才启用本地 mock 演示动作。真实 API 失败时显示错误/空态，不静默 fallback 成 mock 成功。
- `ProjectMemoryPage` 在真实模式下展示后端 `projectMemory.truthNodeFacts / semanticFacts`，不再把前端 mock 当作项目记忆来源。

涉及文件：

- `backend/app/api/pmflow_os_api/__init__.py`
- `backend/app/services/pmflow_os_projection_service.py`
- `backend/app/schemas/pmflow_os.py`
- `backend/app/api/router.py`
- `backend/tests/test_pmflow_os_projection_api.py`
- `frontend/src/api/pmflowOs.ts`
- `frontend/src/features/pmflow-os/store.tsx`
- `frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx`
- `frontend/src/features/pmflow-os/pages/CommandCenterPage.tsx`
- `frontend/src/features/pmflow-os/pages/ProjectMemoryPage.tsx`
- `docs/architecture/CODE_REFERENCE_INDEX.md`
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
- `CLAUDE.md`

验证：

- 静态路径检查完成。
- 后端：`python -m py_compile`（Python 3.12 runtime）通过。
- 后端：`pytest tests/test_pmflow_os_projection_api.py -q` 通过，覆盖空项目 truth-state、Project Memory projection、tasks projection、execution-summary 空态、tenant/project 权限边界。
- 后端 router import smoke：`from app.api.router import api_router` 通过。
- 前端：`npm run typecheck` 通过。
- 前端：`npm run build` 通过。

剩余缺口：

- 本轮不新增 migration，因此 `Thread / ChangeSet / ChangeItem / Approval / EvidenceLink` 仍为空集合或 warning；后续 Phase C 再补真实表与 mutation。
- `WorkGraph / ExecutionBridge / ReleaseGrowth` 仍有部分静态展示区，A3 只保证 truth store 与 Project Memory 真实读取入口，不做 UI 重画和完整页面数据替换。
- 后端代码已改，但当前是在本地开发工作区执行验证，未连接运行中的部署服务；热部署/重启需要在实际部署环境执行。

### 2026-04-25 / Phase B - Project Launch 真实创建链 / done

完成内容：

- 新增 Phase B 专用启动链表 migration `backend/alembic/versions/20260425_add_pmflow_launch_tables.py`，只创建 `pmflow_launch_drafts / pmflow_threads / pmflow_thread_messages`；本轮未创建 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`。
- 新增后端启动链入口 `backend/app/api/pmflow_launch_api/`，注册 `POST /pmflow-launch/drafts` 与 `POST /pmflow-launch/drafts/{draft_id}/confirm`，统一返回 `{code,message,data}`。
- 新增 `backend/app/services/pmflow_launch_service.py` 与 `backend/app/schemas/pmflow_launch.py`：草案生成调用 `llm_service.generate_structured_object(function_name="pmflow_launch_draft_v1")` 并显式传 `routing_meta`；结构化失败返回明确错误或 warnings，不用模板句冒充成功。
- confirm 在同一事务内锁定草案并创建 `Project / UserProject / PMFlowThread / PMFlowThreadMessage / truth_nodes / tasks / semantic_facts seed / OperationLog`，随后更新草案 `status=confirmed` 与 `confirmed_project_id`；重复 confirm 幂等返回同一 `project_id`，不重复写正式对象。
- `truth_nodes.content` 与任务 payload 写入 `launch_draft_id / thread_id / thread_message_id / source=pmflow_launch_confirmed_draft / confidence / evidence`，确保初始 Project Memory 与 Task 能追溯到启动草案和首条用户输入。
- A3 `truth-state` projection 已更新为优先读取 `pmflow_threads` 默认启动线程与 `pmflow_thread_messages`，Project Memory 仍只来自 `truth_nodes + semantic_facts`，不从 launch draft 直接拼。
- 新增前端 API `frontend/src/api/pmflowLaunch.ts`，封装 `createPMFlowLaunchDraft` 与 `confirmPMFlowLaunchDraft`。
- `frontend/src/features/project-launch/useProjectLaunchState.ts` 默认走真实 API；只有显式 `?demo=1` 或 `?dataSource=demo` 才启用本地演示状态机。draft/confirm 失败进入明确失败态，不静默跳 mock 成功态。
- 新增 `/pmflow-os` route alias，创建成功后使用后端返回的 `/pmflow-os?projectId=<id>` 进入 A3 真实读路径。

涉及文件：

- `backend/alembic/versions/20260425_add_pmflow_launch_tables.py`
- `backend/app/models/pmflow_launch.py`
- `backend/app/api/pmflow_launch_api/__init__.py`
- `backend/app/services/pmflow_launch_service.py`
- `backend/app/schemas/pmflow_launch.py`
- `backend/app/services/pmflow_os_projection_service.py`
- `backend/app/config/ai_prompts_catalog/part_scenes_06.py`
- `backend/app/services/llm_service/shared_part_01.py`
- `backend/tests/test_pmflow_launch_api.py`
- `backend/tests/test_pmflow_os_projection_api.py`
- `frontend/src/api/pmflowLaunch.ts`
- `frontend/src/features/project-launch/useProjectLaunchState.ts`
- `frontend/src/features/project-launch/useProjectLaunchState.test.ts`
- `frontend/src/router/index.tsx`
- `docs/architecture/CODE_REFERENCE_INDEX.md`
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
- `CLAUDE.md`

验证：

- 后端：`python -m py_compile` 新增后端模块、migration、router、prompt 聚合文件通过。
- 后端：`pytest tests/test_pmflow_launch_api.py tests/test_pmflow_os_projection_api.py -q` 通过，覆盖 draft 成功、结构化字段缺失、warnings、confirm 创建 Project/thread/message/truth_nodes/tasks、truth-state 回读、幂等、过期/跨 tenant/跨 user、rollback。
- Alembic：`alembic upgrade head` 在本地开发 PostgreSQL 成功从 `20260421_finalize_v1_productization` 升级到 `20260425_add_pmflow_launch_tables`。
- 前端：`npm run test -- src/features/project-launch/useProjectLaunchState.test.ts` 通过，覆盖真实 draft API、draft 失败、confirm 成功、confirm 失败不进成功态、显式 demo 分支。
- 前端：`npm run typecheck` 通过。
- 前端：`npm run build` 通过。

剩余缺口：

- Phase B 只覆盖首次 Project Launch 创建链；项目内后续 ChangeSet / ChangeItem / Approval / EvidenceLink 审查系统仍留给 Phase C。
- 初始 `semantic_facts` seed 仅写用户确认后的 project-level facts；完整异步抽取和治理仍复用既有 semantic facts 管线。

### 2026-04-26 / Phase C1 - PMFlow Change Review 数据底座与审查状态机 / done

完成内容：

- 新增 C1 review 表 migration `backend/alembic/versions/20260426_add_pmflow_change_review_tables.py`，只创建 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`；未新增 commit 或 Phase C2 表。
- 新增模型 `backend/app/models/pmflow_change_review.py`，所有表包含 `tenant_id`，并按 `tenant_id + project_id` 查询；`ChangeItem` 归属 `ChangeSet`，`Approval` 记录 `accept / edit / defer` 的 before/after，`EvidenceLink` 可引用 thread message。
- 新增服务 `backend/app/services/pmflow_change_review_service.py`，实现项目内消息、`proposed_items` extraction、ChangeSet detail、accept/edit/defer 审查状态机；老项目无真实线程时仅允许 `default` 或 `thread-project-{project_id}` 懒创建默认线程。
- 在 `backend/app/api/pmflow_os_api/` 扩展 `/pmflow-os` API：`POST /projects/{project_id}/threads/{thread_id}/messages`、`POST /projects/{project_id}/extractions`、`GET /projects/{project_id}/change-sets/{change_set_id}`、`POST /change-items/{change_item_id}/accept|edit|defer`，统一响应包络。
- `PMFlowOSProjectionService` 已投影 `changeSets / changeItems / evidence / approvals`，`activeChangeSetId` 取最近 open ChangeSet，`loopStage` 映射为 `command_idle / extraction_ready / review_open`；Project Memory 仍只来自 `truth_nodes + semantic_facts`。
- 前端 `frontend/src/api/pmflowOs.ts` 增加 Change Review API wrapper；`frontend/src/features/pmflow-os/store.tsx` 真实模式调用后端 message/extraction/accept/edit/defer，并在成功后 refetch truth-state。真实模式不再本地 promote accepted item，也不假装写入项目记忆；demo 模式仍需显式 `?demo=1` 或 `?dataSource=demo`。

涉及文件：

- `backend/alembic/versions/20260426_add_pmflow_change_review_tables.py`
- `backend/app/models/pmflow_change_review.py`
- `backend/app/services/pmflow_change_review_service.py`
- `backend/app/api/pmflow_os_api/__init__.py`
- `backend/app/schemas/pmflow_os.py`
- `backend/app/services/pmflow_os_projection_service.py`
- `backend/tests/test_pmflow_change_review_api.py`
- `backend/tests/test_pmflow_os_projection_api.py`
- `frontend/src/api/pmflowOs.ts`
- `frontend/src/features/pmflow-os/store.tsx`
- `frontend/src/features/pmflow-os/store.api.test.tsx`
- `frontend/src/features/pmflow-os/pages/ChangeReviewPage.tsx`
- `frontend/src/features/pmflow-os/components/ProjectStructuredLoop.tsx`
- `docs/architecture/CODE_REFERENCE_INDEX.md`
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
- `CLAUDE.md`

验证：

- 后端：`python -m py_compile` 新增后端模型、service、schema、router、migration 通过。
- 后端：`pytest tests/test_pmflow_change_review_api.py tests/test_pmflow_os_projection_api.py tests/test_pmflow_launch_api.py -q` 通过，覆盖 message 懒创建线程、extraction、change items、evidence link、detail、accept/edit/defer、reviewed 自动推进、权限边界、truth-state 投影，以及 accepted/edited 不进入 Project Memory。
- Alembic：`alembic heads` 返回 `20260426_add_pmflow_change_review_tables (head)`；`alembic upgrade head` 在本地开发 PostgreSQL 成功从 `20260425_add_pmflow_launch_tables` 升级到 `20260426_add_pmflow_change_review_tables`。
- 前端：`npm run test -- src/features/pmflow-os` 通过。
- 前端：`npm run typecheck` 通过。
- 前端：`npm run build` 通过；Vite 仍提示既有循环 chunk warning，但构建成功。

剩余缺口：

- C1 不实现 `/commit`，不写 `truth_nodes / tasks / semantic_facts`；accepted/edited 仅代表审查状态，不代表 confirmed Project Memory。
- `POST /extractions` 本轮只接收 `proposed_items`，不默认调用 LLM 结构化提取；AI extraction 主链留给后续阶段。
- 高风险 `risk_level=high` 本轮只记录风险等级和 approval，commit gate 留给 C2。

下一步建议：

- 执行 Phase C2：实现 ChangeSet commit，把 `accepted / edited` ChangeItem 按对象类型写入正式 `truth_nodes / tasks / semantic_facts`，并补齐高风险 approval gate 与部分失败回滚/明细返回。

### 2026-04-24 / Product Blueprint / done

完成内容：

- 整理并落盘 PMFlow 产品蓝图真源。
- 明确 PMFlow 是“对话驱动的 AI 产品执行操作系统”。
- 明确 `solo-first, team-ready`、项目真相层、ChangeSet 待确认、Execution Bridge、人机混编团队等不可偏离项。

涉及文件：

- `docs/PMFLOW_PRODUCT_BLUEPRINT.md`
- `USER.md`
- `CLAUDE.md`
- `docs/architecture/ARCHITECTURE_INVENTORY.md`

验证：

- 文档新增与引用检查完成。
- 无代码改动，未运行编译/测试。

下一步：

- 执行 Phase A：PMFlow OS 产品合同收口。

### 2026-04-24 / Delivery Standard / done

完成内容：

- 建立 PMFlow 产品推进执行标准。
- 记录当前推进状态、下一阶段方向、Phase A-F 推进顺序、单次任务范围标准和完成后进度回写标准。
- 明确新开线程必须先读蓝图、执行标准和代码索引，避免重做或漏做。

涉及文件：

- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
- `USER.md`
- `CLAUDE.md`
- `docs/architecture/ARCHITECTURE_INVENTORY.md`

验证：

- 文档新增与引用检查完成。
- 无代码改动，未运行编译/测试。

下一步：

- 从 A1 对象合同映射开始，把前端 `pmflow-os/types.ts` 与后端现有对象逐一对齐。