PMFlow/docs/PLAN.md

# PMFlow Agentic Delivery Kernel（三个月母计划 / C 版）

## Summary（总体摘要）
这份计划不是“在 PMFlow 里再多接几个 Agent”，而是把 PMFlow 升级成一套 **稳定内核 + 可编译流程 + 可插拔策略 + 可回放投影 + 强治理护栏 + 可控迁移路径** 的交付操作系统。

本计划采用 `C` 版结构：**北极星母计划** + **迁移控制计划** 合一。

- 北极星母计划回答：三个月后系统应该长成什么样。
- 迁移控制计划回答：今天的 PMFlow 如何无事故地迁到那个形态。
- 任何 Program 只有同时满足“未来态正确”和“现网可迁移”两项，才算真正完成。

系统目标主链固定为：
`source_events（来源事实） -> requirement_topics（需求主题） -> intents（交付意图） -> workflow_definitions / workflow_versions（工作流定义 / 版本） -> runs（运行实例） -> assignments（调度单元） -> agent_events / agent_artifacts（执行事实 / 产物事实） -> change_sets（代码变更集） -> release_batches（发布批次） -> projections（投影视图） -> Feishu / PMFlow UI`

但在迁移完成前，系统的**现有真源**仍然被承认、被保护、被映射，绝不允许凭空假设“未来对象已经生效”。

## What “Perfect Execution” Means（什么叫可被完美执行）
这份计划被定义为“可被完美执行”，必须同时满足：

- 对每类业务事实，在任一阶段都只有一个被明文承认的真相源。
- 对人状态只能来自投影，不能来自 LLM 临时推断、半成品 artifact 或散落业务字段。
- 新旧对象之间必须有显式映射合同，禁止靠口头理解迁移。
- 所有 AI 调用都必须仍受 PMFlow 本地路由层、prompt registry、PromptRelease、`ai_call_logs`、Redis 缓存、零兜底原则约束。
- 所有执行动作都必须继续经过受控执行器、执行账本、幂等键与审计链。
- 任务拆解与分配必须继续优先消费人员能力图谱与负载事实，而不是仅按 runtime 能力分发。
- 每个 cutover 都必须写明切换条件、回滚条件和验证证据。

如果一份计划只描述目标架构，而没有写清现有真相源、兼容映射和切换证据，它可以是优秀蓝图，但不叫“完美可执行母计划”。

## How To Read This Plan（阅读方式）
本计划按两层来读：

- `Layer 1: North Star`：描述稳定内核、可变工作流、目标对象和目标分层。
- `Layer 2: Migration Control`：描述现有系统事实、新旧对象映射、Program 依赖顺序、灰度、回放、回滚与完成门槛。

任何执行者必须先读 `Current Truth and Constraints` 与 `Canonical Mapping Contract`，再进入 Program 拆解。不得跳过迁移控制层直接按未来态建模。

## Current Truth and Constraints（当前真相源与不可绕过约束）
### 当前真相源
以下对象是今天 PMFlow 中已经在线、必须尊重的控制面事实：

- `ingest_events`：当前入站事件幂等真源，所有入站事件必须先在这里去重。
- `work_items`：当前 AI PMO 人工控制、草稿确认、恢复闭环的主对象。
- `decision_records`：当前审批、策略门禁、确认需求和最终结果的决策事实。
- `ai_orchestration_runs`：当前异步运行账本和 ingress worker 主轴。
- `ai_worker_executions`：当前 worker 执行事实兼容账本。
- `operation_execution_ledger`：当前副作用幂等与执行结果审计真源。
- `feishu_reply_outbox`：当前对人消息发送的唯一受控出口。
- `backend/.control_plane/pmflow-routing-rules.json`：当前模型路由配置唯一真源。
- `ai_prompt_registry` + `PromptReleaseService`：当前 Prompt 治理与 serving 优先级真源。
- `ai_call_logs`：当前 AI 调用追溯真源。
- `skill_graph / recommend_personnel / required_skill_tag_ids`：当前任务拆解与负责人推荐的核心能力事实。

### 不可绕过的系统约束
以下约束不是“实现建议”，而是母计划级硬约束：

- 所有数据库写操作必须通过 Alembic migration，禁止运行期 DDL。
- 所有新增接口必须遵循 `{code, message, data}` 包络。
- 所有接口必须继续使用 JWT + tenant 依赖注入。
- 所有查询和事实沉淀都必须天然 tenant 隔离。
- 所有 AI 调用必须走 service 层、PMFlow 本地路由层 路由、`ai_call_logs`、Redis 缓存与重试治理。
- 所有用户可见核心业务内容禁止兜底文案、模板假成功和 stub 数据。
- 所有业务语义关键词、正则、`looks_like_*`、`*_HINTS/*_KEYWORDS` 只能留在 `workflow_semantic_planner` 或 prompt/catalog 配置层。
- 飞书回执继续只允许通过 `feishu_reply_outbox` 发送，禁止新增第二套对人发送通道。
- worker 不允许直接写核心业务表；所有写动作都必须经受控 executor 与执行账本。
- 前端组件禁止直接 `fetch`，仍必须通过 `frontend/src/api/` 封装层。

## North Star（北极星设计）
- `内核稳定`：账本、状态机骨架、事件协议、ACL、审计、投影契约优先冻结。
- `流程可变`：主流程不再写死在路由和 service if/else 里，而是 `workflow_version` 的编译产物。
- `策略可插拔`：topic 聚合、意图分类、编译、重规划、发布、升级、预算和回执映射都可以换版本。
- `执行可替换`：Mock、Codex、Claude、人工接管、外部系统都遵守同一协议。
- `视图只读`：飞书、PMFlow UI、管理视图、执行视图、审计视图全部来自投影层。
- `治理先行`：DLQ、replay、budget、quota、backpressure、alerts、manual takeover、rollout 不是补丁，而是一等模块。

## Stable Kernel vs Mutable Workflow（稳定内核与可变工作流）
以下对象必须尽早冻结，并尽量长期不动：

- `source_event`
- `requirement_topic`
- `intent`
- `run`
- `assignment`
- `agent_event`
- `agent_artifact`
- `change_set`
- `release_batch`
- `workflow_definition / workflow_version`
- `projection reducer contract`
- `ACL / audit / replay / DLQ` 契约

以下模块必须故意设计成可替换：

- topic merge / split / reparent 策略
- intent classifier
- workflow compiler
- planner / replanner
- release policy
- escalation policy
- reply mapping
- runtime adapter
- diff / QA / review gate
- quota / budget policy

## Canonical Object Model（目标规范对象模型）
- `SourceEvent`：记录谁从哪里在什么时候发来了什么，只追加，不覆盖。
- `RequirementTopic`：归并多个来源事件，支持 `merge / split / reparent`，不直接承载执行。
- `Intent`：表达系统要达成的交付意图，是工作流编译输入，不等于单条消息。
- `WorkflowDefinition`：定义节点类型、边类型、补偿点、门禁点、超时与升级点。
- `WorkflowVersion`：工作流模板的具体版本，运行实例必须绑定版本。
- `Run`：某个 intent 在某个 workflow version 下的一次执行实例。
- `Assignment`：最小可调度执行单元，只绑定能力和约束，不绑定具体 runtime 厂商。
- `AgentEvent`：执行事实日志，必须支持幂等、乱序处理、版本化 reducer。
- `AgentArtifact`：产物事实日志，不能直接当最终状态，需要经 reducer 归并。
- `ChangeSet`：代码交付聚合层，允许多个 assignment、多个 run 共同关联。
- `ReleaseBatch`：发布聚合层，允许多个 change set、多个 run 共同关联。
- `Projection`：管理视图、执行视图、审计视图、成本视图、风险视图全部从事实账本重建。
- `ManualTakeoverSession`：人工接管会话，负责 pause、resume、override、cancel、handoff。

## Canonical Mapping Contract（新旧对象映射合同）
这是本计划区别于“纯蓝图”的关键部分。任何新对象落地前，都必须回答：它与现有真源是什么关系。

### 1. 入站链路映射
- `ingest_events` 继续作为入站幂等闸门，直到 Program 7 完成读切换验证前都不得退场。
- `source_events` v1 不是绕开 `ingest_events` 的新入口，而是由 `ingest_events` 派生或 dual-write 的规范化来源账本。
- 在 replay 一致性未验证前，`source_events` 只能作为 shadow ledger，不得成为主读入口。

### 2. 控制面映射
- `work_items` 继续是当前人工确认、草稿确认、恢复执行和消息台控制面的主对象。
- `Run` v1 必须先定义成对 `work_items + ai_orchestration_runs` 的兼容抽象，而不是第二套独立控制面。
- `ManualTakeoverSession` v1 必须映射现有 `waiting_manual / draft_pending_confirm / decision / resume` 语义，不得先造一套平行人工接管 UI。
- `decision_records` 继续作为审批、门禁、风险、批准需求与最终结果的决策真源，直到其语义被完整映射进新控制面。

### 3. 执行事实映射
- `ai_orchestration_runs` 是 `Run Ledger v0`，应优先扩展为兼容型中轴，而不是直接废弃。
- `ai_worker_executions` 是 `Assignment Execution Fact v0`，应先适配进 assignment 事实模型。
- `operation_execution_ledger` 是副作用幂等与审计真源，`agent_events` v1 必须先从它映射、归一和补证据，不允许旁路写入。
- 所有 `execution_result.action_contract` 与 `action_param_source` 继续保留并写入执行账本，直到新协议完全接管。

### 4. 对人交互映射
- `feishu_reply_outbox` 继续是唯一对人发送出口。
- `Feishu Mapping` 只能复用现有 outbox 的 claim / retry / stale recovery 模式，不允许新建第二套发送消费者。
- 所有人类可见状态在迁移过程中也必须来自投影，不得直接读取 raw LLM 输出、草稿或 worker artifact 作为对人状态。

### 5. AI 治理映射
- `PMFlow 本地路由层` 路由规则继续是模型选择唯一真源，禁止在新内核中重新硬编码模型名或 provider。
- `ai_prompt_registry` 和 `PromptReleaseService` 继续是 Prompt 治理入口，禁止新 compiler 或 domain pack 绕过它们直接拼 prompt。
- `ai_call_logs` 继续是 AI 调用审计真源，Program 0 以后新增链路若未接入此表，视为未接入。
- Redis 缓存继续保留在 world model 静态层和 AI 调用基础设施层，新增链路只能扩展，不能把缓存语义上浮为用户可见业务兜底。

### 6. 能力图谱映射
- `Assignment` 不是简单“把任务发给 runtime”；它必须先经过能力约束。
- `skill_graph / recommend_personnel / required_skill_tag_ids` 必须进入 compiler input、assignment gate 和 approval context。
- 若某个调度设计无法回答“它如何优先使用人员能力图谱”，则该设计不符合 PMFlow 宪章，不允许进入 Program 3 之后阶段。

## Layered Architecture（目标分层架构）
### Layer A: Source and Topic Ledger（来源与主题账本层）
负责 `source_event` 入账、topic 聚合、topic 拆分、topic 关系维护。

### Layer B: Intent and Workflow Compiler（意图与工作流编译层）
负责把 `topic + context + policy + capability + skill graph` 编译为 `workflow_version` 和 `run plan`。

### Layer C: Execution Kernel（执行内核层）
负责 `run / assignment / event / artifact` 生命周期、claim、lease、heartbeat、replan、callback。

### Layer D: Delivery Aggregation（交付聚合层）
负责 `change_set / release_batch` 聚合、多 run 联动、shared PR/shared release 建模。

### Layer E: Projection and Interaction（投影与交互层）
负责 PMFlow UI、Feishu 回执、管理摘要、执行摘要、审计视图、成本视图。

### Layer F: Governance Plane（治理平面）
负责 ACL、audit、DLQ、replay、budget、quota、alerts、manual takeover、rollout、backfill。

## Codex Execution Discipline（Codex 执行纪律）
整个三个月计划必须按 `Program -> Package -> Packet` 三级执行。

### Program（项目级阶段）
代表稳定目标面，例如 `Truth Inventory`、`Workflow Compiler`、`Human Surfaces`。

### Package（能力包）
代表某个 Program 下的一组强相关能力，例如 `Run Mapping`、`Constraint Translator`、`Replay Projection`。

### Packet（最小可执行任务包）
代表一次真正落地的任务单位，必须满足：

- 一个 Packet 只属于一个 Program。
- 一个 Packet 最多覆盖一个稳定层和一个相邻层。
- 一个 Packet 涉及文件超过 `5` 个必须再拆。
- 一个 Packet 预估改动超过 `200` 行必须再拆。
- 一个 Packet 不允许同时改 `migration + runtime adapter + UI + compiler`。
- 一个 Packet 必须显式说明它依赖的“当前真源”与“目标对象”。
- 一个 Packet 必须声明 `read_scope`、`write_scope`、`feature_flags`、`tests`、`rollback`、`docs_impact`。
- 一个 Packet 必须给出可验证退出条件，不能只写“功能完成”。

### Packet Template（任务包模板）
每个 Packet 进入执行前必须显式写出：

- `packet_id`
- `program_id`
- `package_id`
- `goal`
- `current_truth_source`
- `target_object`
- `entry_criteria`
- `read_scope`
- `write_scope`
- `schema_change yes/no`
- `api_change yes/no`
- `projection_impact`
- `feature_flags`
- `idempotency_key_strategy`
- `audit_evidence`
- `verification`
- `rollback_plan`
- `docs_to_sync`

## Program Roadmap（Program 路线图）
### Program 0: Truth Inventory and Governance Baseline（真相源盘点与治理基线）
目标：先冻结现有真源、治理边界、幂等、路由、缓存、审计、开关、灰度和回退框架，不直接做业务增量。

Packages：
- `0.1 Truth Inventory`：盘点 `ingest_events / work_items / decision_records / ai_orchestration_runs / ai_worker_executions / operation_execution_ledger / feishu_reply_outbox` 的职责、主写入口、主读入口、幂等键。
- `0.2 AI Governance Baseline`：冻结 PMFlow 本地路由层 路由、Prompt registry、PromptRelease、`ai_call_logs`、Redis 缓存、零兜底与 fail-fast 原则。
- `0.3 Contract Freeze`：冻结对象主键、关联表、幂等键、事件包络、审计字段、版本字段、租户边界。
- `0.4 Rollout Strategy`：定义 `shadow mode / dual-write / dual-read / tenant canary / rollback / backfill`。
- `0.5 Metrics and SLO Baseline`：定义 `queue lag`、`claim timeout`、`replan rate`、`dead run count`、`release failure rate`、`manual takeover rate`、`token cost`。
- `0.6 Regression Baseline`：固定后端、前端、Docker、Feishu Web E2E 回归清单。
- `0.7 Docs Baseline`：锁定后续必须同步的 `CLAUDE.md`、部署文档、运行说明、操作员 runbook。

Exit Gate：
- 所有 flag 默认关闭且容器不因新 env 缺失而启动失败。
- 所有 AI 治理真源和现有控制面真源已成文。
- rollout、rollback、backfill、metrics 基线已成文。

### Program 1: Compatibility Mapping and Kernel Canonicalization（兼容映射与内核规范化）
目标：先定义新旧对象映射，再定义目标内核对象，禁止平行造核。

Packages：
- `1.1 Ingress Mapping`：定义 `ingest_events -> source_events` 的派生、dual-write、主读切换条件。
- `1.2 Work Item to Run Mapping`：定义 `work_items + ai_orchestration_runs -> runs` 的兼容模型。
- `1.3 Decision to Takeover Mapping`：定义 `decision_records + waiting_manual + draft_pending_confirm + resume -> manual_takeover / approval / confirmation`。
- `1.4 Worker Execution Mapping`：定义 `ai_worker_executions -> assignment facts`。
- `1.5 Side Effect Mapping`：定义 `operation_execution_ledger -> agent_events / change_sets`。
- `1.6 Delivery Aggregate Canonical IDs`：定义 `change_set / release_batch` 的主键候选、关联策略和幂等键。
- `1.7 Canonical Object Schemas`：在不破坏现有链路的前提下引入 `source_events / requirement_topics / intents / runs / assignments / agent_events / agent_artifacts / change_sets / release_batches`。
- `1.8 Compatibility Shell APIs`：明确哪些 API 继续读旧对象，哪些 API 可以 shadow 新对象，哪些 API 允许 dual-read。

Exit Gate：
- 每个新对象都存在对应的旧对象映射合同。
- 任意执行者都能说清每个阶段的主写和主读是谁。
- 不存在未映射就直接替代旧控制面的对象。

### Program 2: Worker Protocol and Constraint Translator（执行协议与约束翻译层）
目标：先冻结执行协议，再冻结 compiler 输出，避免顺序倒置。

Packages：
- `2.1 Worker Protocol`：统一 `goal / context / constraints / expected_outputs / callbacks / idempotency` 协议。
- `2.2 Callback Envelope`：统一 runtime 回调的状态、错误、重试、artifact、trace、route snapshot、prompt provenance 包络。
- `2.3 Constraint Translator`：生成 `allowed_paths / forbidden_paths / write_scope / required_tests / required_artifacts / release_policy / budget_scope`。
- `2.4 Mock Runtime`：用于 Docker、E2E、replay、演示和稳定验证。
- `2.5 Workspace and Secret Boundary`：工作区、env 注入、secret masking、网络访问、安全边界。
- `2.6 Base Commit Drift`：base commit pinning、shared branch race、rebase / rerun 策略。
- `2.7 Protocol Contract Tests`：Mock / Codex / Claude callback 一致性和约束执行一致性。

Exit Gate：
- compiler 尚未上线前，执行协议和约束翻译已经冻结。
- Mock 与真实 runtime 都遵守同一 callback 契约。
- runtime 更换不影响 compiler、kernel、projection。

### Program 3: Intent and Workflow Compiler（意图与工作流编译器）
目标：把主流程从“代码逻辑”降级为“版本化编译产物”，并把能力图谱与治理证据纳入输入。

Packages：
- `3.1 Capability Registry`：把 `write_spec / edit_code / run_tests / review_diff / deploy_release` 建成能力注册表。
- `3.2 Compiler Inputs`：输入必须包含 `intent + topic + project context + policy + capabilities + skill graph + budget + visibility + route snapshot + prompt provenance`。
- `3.3 Workflow Definition`：定义节点类型、边类型、gate、compensation、timeout、escalation。
- `3.4 Workflow Version`：每次流程变动只发新版本，老 run 固定跑老版本。
- `3.5 Compiler Outputs`：输出 `workflow_version`、`run_plan`、`assignment_graph`、`risk_summary`、`approval_requirements`、`constraint_bundle`。
- `3.6 Domain Pack Contract`：domain pack 只负责上下文构建、策略映射、reply mapping、progress mapping，不得承担事实写入。
- `3.7 Planner / Replanner Rules`：重规划必须规则触发，不允许 LLM 自由重构内核。

Exit Gate：
- compiler 输入中已经包含能力图谱、预算和 Prompt 治理证据。
- 同一意图在不同策略和能力约束下可编译出不同工作流版本。
- 后续主流程调整不需要改内核账本和对人协议。

### Program 4: Replay, Projection, and Forensics（回放、投影与取证）
目标：让所有视图都可回放、可恢复、可解释、可举证。

Packages：
- `4.1 Event Ordering`：定义 `sequence`、`event_ts`、`ingest_ts`、late event 处理。
- `4.2 Reducer Versioning`：定义 `reducer_version`、`snapshot_generation`、projection rebuild 机制。
- `4.3 Unified Progress Projection`：先做 service 级投影，不做数据库物化视图。
- `4.4 Specialized Projections`：执行视图、管理视图、审计视图、风险视图、成本视图。
- `4.5 Forensics`：保留 prompt version、model route、tool list、approval chain、superseded chain、route snapshot。
- `4.6 DLQ and Replay`：source ingress、worker callback、observer webhook、outbox 全部支持 DLQ 和 replay。
- `4.7 Projection Rebuild and Backfill`：支持历史 run / work item 的重建与一致性验证。

Exit Gate：
- 任意 projection 都可由账本重建。
- 乱序事件、重复事件、晚到事件不会破坏最终视图一致性。
- 给定一条用户可见结果，可以追到对应 route、prompt、approval、event 和 artifact 证据链。

### Program 5: Policy and Human Control（策略层与人工接管）
目标：让系统可控、可暂停、可人工接力，而不是只能自动跑。

Packages：
- `5.1 Topic Merge Policy`：topic merge/split/reparent 决策规则。
- `5.2 Diff / QA / Release Gates`：差异审查、QA 门禁、发布门禁版本化。
- `5.3 Budget / Quota / Backpressure`：tenant、project、runtime、repo、environment 维度限流和预算。
- `5.4 ACL and Visibility`：谁能看 topic、run、assignment、change set、release batch 必须显式控制。
- `5.5 Manual Takeover Session`：`pause / resume / cancel / override / handoff` 生命周期。
- `5.6 Approval and Confirmation`：普通确认、发布确认、回滚确认统一收敛，兼容现有草稿确认和审批链。
- `5.7 Escalation Policy`：超时、失败、预算打满、审批阻塞的升级路径。

Exit Gate：
- 任何自动流程都可被人工接管。
- 预算、并发、审批、可见性不再散落在业务逻辑里。
- 现有 `decision_records` 语义已被完整映射到新控制平面。

### Program 6: Delivery Aggregation and Human Surfaces（交付聚合与对人界面）
目标：让人类只看清晰视图，不碰底层执行细节。

Packages：
- `6.1 Change Set Aggregation`：shared PR、shared branch、shared commit window 统一归并。
- `6.2 Release Batch Orchestration`：多 change set 联合发布、部分成功、补偿路径。
- `6.3 Reporter`：只读投影，输出管理摘要、执行摘要、风险摘要、成本摘要。
- `6.4 PMFlow Query APIs`：项目进度、阻塞、最近发布、风险、异常统计查询。
- `6.5 Feishu Mapping`：所有回执统一走现有 outbox，不同步直发。
- `6.6 Human Views`：管理视图、执行视图、审计视图、成本视图、风险视图。
- `6.7 Confirmation UI Integration`：飞书卡片动作与 PMFlow UI 的人工控制统一。

Exit Gate：
- 所有人类可见状态都来自投影。
- 共享 PR / 共享发布能被正确表达，不误报“单任务已完成发布”。
- 飞书和 PMFlow UI 对同一业务事实没有两套口径。

### Program 7: Rollout, Validation, and Hardening（灰度、切换、验证与加固）
目标：保证上线过程可控、可验证、可追责，并把“未来态”真正切成“当前态”。

Packages：
- `7.1 Docker Validation`：dev compose、prod-like compose、容器内迁移、startup worker、flag 生效。
- `7.2 Web Feishu Validation`：现有 Playwright E2E 扩展，不旁路。
- `7.3 Shadow Mode`：新账本、新投影、新 compiler 先 shadow，主读仍指向旧链。
- `7.4 Dual-Write`：在 shadow 一致后，进入双写阶段。
- `7.5 Dual-Read and Cutover`：在双写稳定和 replay 一致后，按租户级切主读。
- `7.6 Backfill and Replay`：历史 run / work item 的回填与重建。
- `7.7 Failure Drills`：claim 冲突、observer 覆盖、late event、release partial failure、manual takeover、DLQ replay。
- `7.8 SLO and Alerts`：生产告警、看板、审计报告、值班升级。
- `7.9 Documentation Sync`：`CLAUDE.md`、部署文档、运行说明、运维 playbook 同步更新。

Exit Gate：
- 新内核在 Docker、网页端飞书、灰度租户、回放和失败演练中都稳定。
- 具备租户级 read cutover 与 rollback 能力。
- 文档与真实运行方式保持同步。

## Program Dependency Matrix（Program 依赖矩阵）
- `Program 0` 必须最先完成。
- `Program 1` 建在 `Program 0` 之上。
- `Program 2` 依赖 `Program 1` 的兼容映射冻结；不得晚于 `Program 3`。
- `Program 3` 建在 `Program 1 + Program 2` 之上。
- `Program 4` 建在 `Program 1 + Program 3` 之上。
- `Program 5` 建在 `Program 1 + Program 4` 的最小投影之上。
- `Program 6` 依赖 `Program 4/5` 的最小能力集。
- `Program 7` 贯穿始终，但真正的 read cutover 只能发生在 `Program 6` 稳定之后。
- 任意 Program 不允许跳过前置契约直接开发后置 UI、runtime 或 cutover。

## Validation Matrix（验证矩阵）
- `Backend`：`python -m py_compile`、相关单测、状态机测试、reducer 测试、迁移 up/down 回归。
- `Frontend`：`npm run build`、`tsc --noEmit`、关键 UI 查询链路。
- `Contract`：包络格式、JWT、tenant 隔离、幂等键、兼容旧 `/ai-pmo/*`、`/feishu/*`、`/rag/*`。
- `AI Governance`：PMFlow 本地路由层 route snapshot、Prompt registry、PromptRelease、`ai_call_logs`、Redis 缓存、零兜底原则。
- `Replay`：同一事件流重放得到同样 projection。
- `Runtime`：Mock / Codex / Claude callback 一致性与约束执行一致性。
- `Projection`：对人状态全部来自投影，且能追溯到底层事实链。
- `Docker`：dev compose、prod-like compose、容器迁移、startup worker、flag 生效。
- `Web Feishu E2E`：入站需求、topic 合流、阶段回执、确认动作、超时降级、统一进度查询。
- `Failure`：claim 冲突、late event、observer 覆盖、DLQ replay、shared PR blockage、partial release、manual takeover。

## Compatibility and Cutover Rules（兼容与切换规则）
- 不修改现有 `/ai-pmo/process-text` 的输入输出语义；先以 shadow mode 并行衍生新链。
- 不修改现有飞书 outbox 的核心幂等 / claim / retry / stale recovery 逻辑；只复用其模式。
- 不允许把 `source_system / source_message_id` 当唯一真源；必须保留独立来源账本与关联层。
- 不允许把一个 assignment 默认绑定单一 PR 或单一发布；共享交付必须经 `change_set / release_batch` 建模。
- 不允许 worker 直接写核心业务表；只能走受控 executor、event、artifact、callback API。
- 不允许把 LLM 推断直接当最终对人状态；所有对人状态都要经投影层。
- 不允许在 API 层写业务逻辑；新增逻辑继续归属 service 层。
- 不允许破坏 JWT、tenant、审计、幂等、Alembic 迁移规范。
- 不允许为了 E2E 测试旁路真实飞书接入方式。
- 不允许在未验证 Docker、replay、failure drills 前宣布阶段完成。
- 不允许在 replay 一致性、dual-write 稳定性和 rollback 演练通过前切主读。

## Defaults and Assumptions（默认决策与假设）
- 第一落地域固定是 `AI PMO Domain Pack`，但所有契约按多业务域设计。
- `project_progress_view` v1 仍采用 service 级投影，不做数据库物化视图。
- `Requirement Topic` v1 采用启发式聚合，但必须同时支持 split / reparent。
- `Intent` 是新的稳定对象，未来流程变更优先改 compiler，不优先改内核。
- `Workflow` 采用版本化图，不采用把流程硬编码在单一路由里的模式。
- `ChangeSet` v1 以 `repo + branch + PR` 为主键候选，无 PR 时以活跃提交窗口临时归并。
- `ReleaseBatch` v1 以一次逻辑发布窗口为单位，允许包含多个 change set。
- `Worker Runtime` 真实接入顺序为 `Mock -> Codex -> Claude`。
- `Policy Gate` 默认对生产发布保守，生产环境不开全自动发布。
- `Observer` 拥有最高外部事实优先级，`Reporter` 只读聚合结果。
- 这是一个三个月级母计划，后续 Codex 只能按 `Program -> Package -> Packet` 纪律推进，不能跳层乱做。

## Appendix A: Suggested Kickoff Sequence（建议开工顺序，非短期替代计划）
这部分不是把母计划降级成“两周计划”，而是避免大计划无人知道从哪里开工。

建议启动顺序：

1. `P0-Truth-01`：完成当前真源盘点文档。
2. `P0-Gov-02`：完成 AI 治理基线文档。
3. `P1-Map-01`：完成 `ingest_events -> source_events` 映射合同。
4. `P1-Map-02`：完成 `work_items + decision_records -> runs / manual takeover` 映射合同。
5. `P1-Map-03`：完成 `ai_orchestration_runs / ai_worker_executions / operation_execution_ledger -> runs / assignments / agent_events` 映射合同。
6. `P2-Proto-01`：冻结 worker protocol schema。
7. `P2-Proto-02`：冻结 constraint translator schema。
8. `P3-Comp-01`：冻结 compiler input contract，显式纳入能力图谱、Prompt 治理和 route snapshot。

只有当以上 8 个启动 Packet 完成后，才允许进入大规模 schema 扩展、runtime 接入和 UI 表达阶段。