ForgeFlow 项目 MOC
ForgeFlow 当前工程策略与 V1 历史架构的导航，连接项目资产、版本演进及相关工程概念。
[!info] related notes
ForgeFlow 项目 MOC
从哪里开始
- [[forgeflow|ForgeFlow]]：先区分当前 Pi Agent 策略包与 V1 历史闭环；
- Agent Behavioral Contract：理解为什么“模型说完成”不能成为软件工程 acceptance；
- Agent 的 Configuration Provenance 与 Execution Provenance：理解 exact model/resource/config 与一次真实执行证据为什么必须分层；
- Agent Failure Attribution：理解 ForgeFlow 如何把 provider、workspace、review、integration、cleanup 等失败分开归因；
- Agent Safety Envelope：理解自动执行、自我改进和高权限变更为什么需要独立 gate。
V1 历史阅读路径
以下主题记录 V1 控制平面的设计，不代表当前 v3 策略包仍自行持有这些职责。
Durable planning 与生命周期
ForgeFlow 的核心不是“多 Agent 同时写代码”，而是把一次开发目标拆成 durable Plan / WorkItem / Execution / Review 状态，并让重启、retry、fallback、repair、integration 都沿同一条持久 lineage 继续。
相关入口：
- Agent Runtime 中 Command、Event、Replay、Resume 与状态层的关系；
- Agent DecisionTrace；
- Agent 的 Fallback、Abstain 与 Escalate。
Worktree、writer 与并行边界
V1 采用单项目单 active root Plan；不同根任务排队，一个大 Plan 内只对明确无冲突的 WorkItem 做 bounded parallel wave。每个 mutable worktree 同一时刻只有一个 writer，provider cleanup proof 是 retry writer handoff 和 terminal retirement 的前置条件。
这一块重点关注三个不变量：
- canonical repository 不被 autonomous worker 当作共享 mutable checkout；
- 并行 sibling 必须共享同一 integration base，并在 integration 时串行收敛；
- prompt 不是权限边界，最终 changed-file scope、Git linkage 与 writer ownership 都由 controller 验证。
Implementation、Review 与 acceptance
Implementation 成功只意味着产生了一个待验证 candidate。ForgeFlow 还要求独立 reviewer 固定在 exact candidate SHA，Review FAIL 进入 Repair/Retry，再 Review；最终集成后还要证明 provider session cleanup、worktree retirement、project lease release 和 release identity。
相关入口：
Resource 与 provider recovery
ForgeFlow 把模型、provider、agent backend、能力、tier、health 和 runtime admission 合成可治理 Resource。一次 Execution 选择后资源身份不可变；失败通过新的 execution lineage 进行 fallback，而不是让正在写代码的 session 静默换模型。
Provider/tool churn 与 workspace meaningful progress 也分开统计，因此重复 reasoning、读取、失败工具调用不能无限延长一个没有真实代码进展的实现任务。
Release provenance
Release 不是“main 已更新”就结束。ForgeFlow V1 将运行中的 artifact 绑定到 exact source SHA + artifact digest，并用真实 Provider 的 autonomous lifecycle smoke 生成 release-bound acceptance。新 artifact 不会继承旧 artifact 的 attestation。
Improvement 与 self-change
Repeated failure 可以进入 Improvement Candidate / diagnosis 流，但 diagnosis 只能在 controller 提供的受控证据上生成 typed proposal。adoption 仍然创建普通 ForgeFlow Plan；self-change、canary、promotion、autonomous promotion 是不同 gate，不允许一个“自我优化”开关绕过全部软件工程边界。
历史演进
历史架构构想保留了早期对 Execution Lease、Agent Bridge、Provider Gateway、多 Agent 并行与 UI 投影的探索。ForgeFlow V1 的关键演进是：去掉可视化办公室/员工产品隐喻，把产品边界收敛为 headless autonomous software engineering control plane，并把真正的安全不变量下沉为 Git、数据库、resource admission、review lineage 和 release provenance 等 deterministic contract。
项目事实边界
这张 MOC 组织稳定知识，不承担当前 commit、provider quota、运行中 Plan 或线上 health 的实时真值。实时实现状态必须回到 ForgeFlow 仓库、Release 与实际运行环境核验；不能假设 V1 控制平面 API 仍存在。
Digital Biome