@openprd/cli 0.1.19 → 0.1.21

package/.openprd/engagements/active/prd.md

@@ -1,122 +1,154 @@
-# 画布协同闭环：标注改图、双向结构化工具、尺寸契约与唤起机制
+# OpenPrd 可解释项目控制平面与跨工具上下文升级
 > 语言规则：用户可见说明、PRD、spec 和 tasks 跟随用户当前主语言；无法判断时才使用简体中文兜底。PRD、OpenPrd、OpenSpec、API、SDK、CLI、TypeScript、JSON、HTTP、WebSocket、字段 key、命令名、品牌名、产品名和协议名等必要专有名词保留原文。
-- 版本: v0014
+- 版本: v0018
 - 负责人: OpenPrd
 - 产品场景: 以 Agent 为主要使用场景
 - 场景模板: 以 Agent 为主要使用场景
 - 状态: synthesized
-- 生成时间: 2026-07-06 22:49:20
+- 生成时间: 2026-07-10 23:07:12
 ## 元信息
 
-- 标题: 画布协同闭环：标注改图、双向结构化工具、尺寸契约与唤起机制
+- 标题: OpenPrd 可解释项目控制平面与跨工具上下文升级
 - 负责人: OpenPrd
-- 状态: synthesized
-- 版本: v0014
+- 状态: classified
+- 版本: v0018
 - 产品场景: 以 Agent 为主要使用场景
-- 日期: 2026-07-06
+- 日期: 2026-07-10
 
 ## 问题
 
-- 问题陈述: OpenPrd 画布目前只有单向的“发送给 Codex”整体交接：Agent 不能结构化读取用户在画布上的选区与标注，不能把生成图片精准放回画布锚点旁，标注修改意图靠用户口述或手动截图传递，协同链路断在“人标注完之后”这一步。
-- 为什么是现在: 对标 Cowart 已验证“标注改图闭环 + 画布双向结构化工具 + 生图尺寸契约 + 具名 skill 唤起”四件能力能显著降低人机视觉协同成本；OpenPrd 0.1.18 刚落地生图路由，正好把尺寸契约与路由串起来。
+- 问题陈述: 统一项目事实、并发运行态和上下文编译，降低 token、延迟、错误目标与长期维护成本
+- 为什么是现在: 0.1.19 已暴露多真相源、并发和跨版本迁移风险，需要在 0.1.20 建立兼容控制平面
 - 证据:
-  - Cowart 的 get_cowart_selection / insert_cowart_image / annotation-edit 元数据闭环已被 DeepWiki 调研确认
-  - OpenPrd 画布现状只有 placeholderId 回填和整体 handoff，无结构化选区读取
-  - 用户已确认按对标建议落地四项能力
+  - 近 30 天 817 个 Codex 线程中，362 个具有 OpenPrd CLI 形态，共 3145 次调用；run --context 554 次，93 个线程重复调用，额外调用 271 次，单线程最多 22 次。
+  - 56 个同项目 OpenPrd 线程在 5 分钟内并发启动；当前 feature-list、loop-state、current state 和全局镜像缺少 claim、lease、CAS 与 write-set 冲突协议。
+  - 当前 run-harness 已出现 findSessionWorkspaceCandidates 被删除但仍调用，以及显式 session 在精确解析前被 active change 抢占的回归。
+  - 当前 v0017 与 remove-session-tracking change 混入前一个 Canvas 需求内容，证明局部 capture 与多投影可以形成语义污染。
+  - 本机持久范围发现 86 个 .openprd，版本跨 0.1.0、0.1.11、0.1.15、0.1.19；Home 级 Codex Skill 还被 Claude 适配内容和软链接污染。
 
 ## 用户与相关方
 
 - 主要用户:
-  - 使用 OpenPrd 画布做视觉协同的开发者与产品设计协作者
+  - 用自然语言驱动 Codex、Cursor、Claude Code 完成产品开发的非专业或半专业用户
+  - 在同一代码项目中并发运行多个 Agent、线程、worktree 的开发者
+  - 需要持续维护需求、代码健康、知识与版本迁移的项目负责人
 - 次要用户:
-  - 待补充
+  - OpenPrd 集成与插件维护者
+  - 审阅业务范围、风险与验收结论的产品和业务协作者
 - 相关方:
-  - OpenPrd 维护者
-  - Codex/Cursor 上的 Vibe Coding 用户
+  - OpenPrd 产品与工程维护者
+  - 被 OpenPrd 管理的本地项目所有者
+  - Codex、Cursor、Claude Code 适配层维护者
 
 ## 目标与成功标准
 
 - 目标:
-  - 用户在画布上标注后，一句话就能让 Agent 读懂标注并生成修订图放回原图旁
-  - Agent 能结构化读取画布选区并把图片锚定回填
-  - 生图请求自动携带占位卡尺寸契约
-  - 用户能用自然语言稳定唤起画布协同
+  - 用唯一 Project Ledger 管理项目业务事实，并把 current、task graph、review、knowledge index 等降为可重建投影
+  - 用 Lane/Task Runtime 支持同项目多线程、多 Agent、多 worktree 安全 claim、lease、heartbeat、write-set 与 CAS
+  - 用 Context Compiler 向 Agent 提供最精准、最小 token、可缓存、可增量、可解释且默认只读的上下文
+  - 用 scoped Evidence 和 Gate 让局部任务不被无关项目债务阻断，同时保持发布级门禁
+  - 从同一 ReviewModel 生成小白可懂的业务视图和工程可执行视图，并保持同一 digest 与决策链
+  - 统一 Codex、Cursor、Claude Code 的 Adapter SPI、能力协商、事件归一和跨版本协议
+  - 把 Knowledge Evolution 变为有作用域、证据、有效期、替代链和可回滚的持续维护系统
+  - 安全将产品版本升级到 0.1.20，并刷新所有真实本地 OpenPrd 安装与旧项目
 - 成功指标:
-  - 标注改图闭环端到端可走通并有测试覆盖
-  - selection/insert-image API 有集成测试
-  - 尺寸契约出现在生图指引与占位卡 handoff 记录中
+  - 相同 revision 与请求生成稳定 context digest；默认完整 Capsule 不超过 800 tokens，Delta 不超过 250 tokens
+  - Context warm cache p95 小于 100ms，cold build p95 小于 500ms；run --context 对业务状态零写入
+  - 同一 task 的 100 个并发 claim 只允许一个成功；CAS 与 write-set 压力测试零 lost update
+  - 显式 session/thread/task/work-unit 目标解析准确率 100%，active change 只在无精确索引时作为 fallback
+  - 业务 Review 不泄露内部命令和实现噪声，工程 Review 保持文件、任务、测试、证据和版本全链路可追溯
+  - Codex、Cursor、Claude Code 通过同一适配契约 fixture，能力缺口被明确表达而不伪装支持
+  - 所有真实活跃本地项目升级到 0.1.20，归档未改动，单项目回滚演练成功，Home Skill 不再出现跨适配器漂移
 - 验收目标:
-  - canvas 服务新增 GET /api/selection 与 POST /api/insert-image 且测试通过
-  - 标注导出带 annotationEdit 元数据并能被 hook 指引消费
-  - hook 对画布协同意图注入引导语
+  - 全量单元、集成、并发、迁移、回滚、性能和三平台契约测试通过
+  - 最新 Markdown/HTML 测试报告、质量报告、架构与视觉证据可追溯
+  - standards、quality、run verify 与 doctor 在发布/刷新前全部健康
+  - 所有真实项目刷新报告包含版本、checksum、备份、迁移结果和失败回滚状态
 
 ## 验证与创业闭环
 
 - 可触达社区:
-  - 待补充
+  - 已经在本机真实项目中持续使用 OpenPrd、Codex、Cursor、Claude Code 的 Vibe Coding 用户与维护者
 - 第一批种子用户:
-  - 待补充
+  - 当前 43 个活跃或真实旧项目的维护者
+  - 近一个月具有 OpenPrd CLI 行为的 362 个 Codex 线程代表的真实任务样本
 - 社区契合与触达依据:
-  - 待补充
-- 当前替代方案: 待补充
+  - 团队本身就是高频 Vibe Coding 与多 Agent 协作者，拥有真实线程、真实项目、真实安装漂移和真实迁移样本，可以在自身工作流中完成 dogfood。
+- 当前替代方案: 依赖 AGENTS.md、Skill、change/tasks、session binding、run-state、质量报告和人工记忆拼接上下文；发生冲突时靠重新运行 context、手工检查状态或切换线程。
 - 痛点与替代证据:
-  - 待补充
+  - 重复 context、错误目标恢复、语义污染、全局 registry 膨胀、跨工具 Skill 漂移和 fleet 无事务更新均已在当前仓库与本机安装中复现。
 - 手工交付路径:
-  - 待补充
+  - 先以兼容模式建立 manifest、事件信封、原子存储与 Ledger shadow-write，再逐层切换 Runtime、Context、Gate、Review、Knowledge 和 Adapter；每层均用真实项目 fixture 与旧版本 fixture 对账。
 - 手工作战卡:
-  - 待补充
+  - 修复当前回归并冻结协议；建立 legacy/dual/ledger 三种存储模式；对每个旧项目执行 preflight、备份、临时生成、校验、原子替换与单项目回滚；按批次刷新 Home、Projects、Context 和活跃 worktree。
 - 承诺信号:
-  - 待补充
-- 首个低成本验证: 生成 change 与任务拆解后按序实现
+  - 用户明确授权完整实施、自动解决中间问题并刷新全部真实本地版本
+  - 现有线程与安装盘点提供了可量化的前后对比基线
+- 首个低成本验证: 在当前 OpenPrd 仓库先完成回归修复、项目 manifest、原子 Ledger、任务并发 Runtime 与只读 Context Capsule 的纵向闭环。
 - 先活下来方案:
-  - 待补充
+  - 保持 0.1.x CLI 和现有生成文件兼容；新内核先 shadow-write，出现不一致时可切回 legacy read，禁止一次性破坏旧项目。
 - 付费验证信号:
-  - 待补充
-- 第一版只做一件事: 待补充
-- 周末级验证: 待补充
+  - 本轮以真实使用频率、迁移覆盖、token 与执行时间下降、并发正确性和评审完成率作为价值证明，不引入商业收费动作。
+- 第一版只做一件事: 0.1.20 首先交付可兼容的 Project Manifest、Event Envelope、Atomic Store、Project Ledger、Lane/Task Runtime、Context Capsule，以及安全 fleet 升级；双投影 Review、Adapter SPI 与 Knowledge Evolution 必须有可用纵向能力，但旧投影可保留兼容入口。
+- 周末级验证: 用当前仓库、两个并发临时工作区、0.1.15/0.1.19 fixture 和 Home Skill 软链接 fixture 完成全链路演练。
 - 最小工具桥接:
-  - 待补充
+  - 先修复 exact session 优先级并实现一个具备 expectedRevision、idempotencyKey、原子写入和可重建投影的 Ledger stream。
 - 产品化门槛:
-  - 待补充
+  - 只有全量测试、并发压力、迁移幂等、回滚演练、三平台契约和真实项目 dry-run 均通过，才允许把 0.1.20 刷新到真实本地项目。
 - 第一批客户路径:
-  - 待补充
-- 初始收费假设: 待补充
-- 客户 1 盈利路径: 待补充
+  - 先覆盖当前机器上的 OpenPrd 自身仓库与活跃项目，再把协议和迁移路径推广到其他 OpenPrd 用户。
+- 初始收费假设: 本轮不改变开源 CLI 定价；价值通过更低上下文成本、更少返工和更稳定的长期项目维护体现。
+- 客户 1 盈利路径: 单项目减少一次错误目标执行、一次全量 context 重注入或一次手工迁移回滚即可抵消升级成本。
 - 销售与增长纪律:
-  - 待补充
-- 可逆性判断: 待补充
-- 客户真问题校验: 待补充
-- 价值观一致性: 待补充
+  - 先保证协议稳定、可回滚、可观测和旧项目兼容，再增加更多自动化；不以新增命令数量替代可验证的执行质量。
+- 可逆性判断: 每个迁移阶段支持 legacy/dual/ledger 模式、preimage backup、幂等 migration id 与按项目 restore；归档和发布副本默认保持不可变。
+- 客户真问题校验: 目标直接针对已观测的重复上下文、并发覆盖、错误目标、评审理解成本、跨版本漂移和长期知识失真，而不是为了架构整洁而重写。
+- 价值观一致性: 坚持用户可理解、Agent 可执行、事实可追溯、风险可回滚、知识可持续演进的 OpenPrd 产品原则。
 
 ## 范围与非目标
 
 - 范围内:
-  - canvas-workspace.js 新增选区状态持久化与查询 API
-  - canvas-workspace.js 新增锚定插图 API（anchorShapeId/placement/replaceHolder）
-  - canvas-app.html.js 标注修改请求导出（带元数据）与选区上报
-  - 生图占位卡尺寸契约写入 handoff 与生图指引
-  - codex-hook-runner-template.mjs 画布协同意图识别与引导注入
-  - agent-canonical-content.js 画布协同指引
-  - docs/basic 与 README 同步
+  - Project Manifest、Event Envelope、Atomic Store、Project Ledger 与可重建投影
+  - Session/Lane/Task Runtime：claim、lease、heartbeat、write-set、CAS、worktree/branch trace
+  - Context Capsule、Delta、Cache、token budget、authority/freshness、引用解析与 secret redaction
+  - project/change/work-unit/task/lane/operation 分级 Gate 与 Evidence
+  - Review canonical model、业务/工程双投影、决策与 Canvas 标注绑定
+  - Knowledge v3 生命周期、检索预算、telemetry 分离、Learning/Growth 边界
+  - Codex/Cursor/Claude Code Adapter SPI、能力协商、runtime detection 与生成文件漂移修复
+  - 协议/reader/writer/adapter/projection 版本、N/N-1 兼容、幂等迁移、备份与回滚
+  - fleet nested legacy 扫描、symlink 安全、registry 隔离/压缩和真实本地项目批量刷新
+  - 面向普通用户的中文产品文案、i18n 提醒和 Review Studio 视觉交互验证
 - 范围外:
-  - 不迁移 tldraw、不做 Codex widget 内嵌
-  - 不新建独立 MCP stdio server，复用画布本地 HTTP 服务
-  - 不改变现有发送给 Codex 的 app-server 桥接协议
+  - 不进行生产云端热修复、远程业务数据写入或替用户发布外部服务
+  - 不重写 Excalidraw/Canvas 引擎，不引入与控制平面无关的视觉资产系统
+  - 不静默删除历史 review、归档、release 副本或用户未提交源码改动
+  - 不在 0.1.20 直接移除全部 legacy 文件；先提供兼容投影和回滚窗口
+  - 不把 Codex、Cursor、Claude Code 不具备的生命周期能力伪装成已支持
+  - 不自动 push、npm publish 或创建远端 release，除非用户另行明确授权
 
 ## 场景与流程
 
 - 主流程:
-  - 用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放回原图右侧
-  - Agent 调 GET /api/selection 读取选中图形结构化数据
-  - Agent 调 POST /api/insert-image 把生成图锚定到指定图形旁
-  - 用户说“打开画布一起改图”即唤起画布协同
+  - Agent 进入已有项目，Adapter 识别运行环境，Context Compiler 基于 lane/task/revision 在预算内生成 Capsule 或 Delta
+  - 多个线程并发执行同一项目，Runtime 对 task 和 write-set 原子 claim，冲突被结构化返回，不相交任务可并行
+  - 业务用户打开 Review，先看到问题、价值、范围、流程、风险和验收；工程视图从同一 model 展示 change/task/file/test/evidence
+  - 任务完成后 Evidence 只更新相关 task/work-unit 投影；阶段或发布门禁再聚合项目级质量
+  - 旧项目升级前生成 plan 与 backup，迁移到 dual 模式并验证；失败只回滚当前项目
+  - Knowledge 由 observation 进入 candidate，经证据验证后生效；过期、冲突或被替代的知识不再进入 Context
 - 边界情况:
-  - 无选区时 selection API 返回空且 Agent 收到明确提示
-  - 锚点图形不存在时 insert-image 报错不写脏数据
-  - 占位卡无宽高时尺寸契约退化为默认比例
+  - 同一 session ID 在多个工作区有线索时不语义猜测，返回候选和安全阻断
+  - Agent 崩溃导致 lease 过期后，旧 heartbeat 不能覆盖新 claim
+  - Ledger JSONL 尾部半写、projection 损坏或 migration 重跑时可恢复且不重复应用
+  - workspace schema 过新时旧 writer 拒绝写入并说明最小兼容版本
+  - Home Skill 路径含跨目录 symlink 时拒绝跟随覆盖 canonical source，并给出可恢复迁移计划
+  - dirty worktree、detached worktree、归档、副本和 nested legacy 目录被明确分类，不误刷新
 - 失败模式:
-  - 画布服务未启动时 API 调用失败要提示先运行 openprd canvas
-  - 回填图片文件缺失时保持画布 scene 不变
+  - expectedRevision 不一致时返回 OPENPRD_REVISION_CONFLICT，不覆盖新状态
+  - write-set 冲突时保留当前 claim 并返回冲突任务、owner、lease 与重试条件
+  - Context 超预算时按 authority、scope、freshness 和 relevance 确定性裁剪，并列出 excluded reason
+  - 迁移校验失败时用 preimage 恢复当前项目，registry 不提交该项目新版本
+  - Adapter 能力不足时生成 capability gap，不继续要求不存在的 hook 或 UI
+  - Review model digest 不匹配时不接受确认，CSS/artifact 重渲染不得改变业务 model digest
 
 ## 可视化图表
 
@@ -124,30 +156,30 @@
 
 ```mermaid
 flowchart LR
-  entry["入口触发<br/>用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放回原图右侧"]
-  experience["产品内步骤<br/>Agent 调 GET /api/selection 读取选中图形结构化数据"]
-  decision{"决策点<br/>无选区时 selection API 返回空且 Agent 收到明确提示"}
-  success(["成功结果<br/>标注改图闭环端到端可走通并有测试覆盖"])
-  failure[["失败与恢复<br/>画布服务未启动时 API 调用失败要提示先运行 openprd canvas"]]
-  entry -->|"用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放回原…"| experience
-  experience -->|"Agent 调 GET /api/selection 读取选中图形结构化数据"| decision
-  decision -->|"用户在画布上标注后，一句话就能让 Agent 读懂标注并生成修订图放回原图旁"| success
-  decision -.->|"画布服务未启动时 API 调用失败要提示先运行 openprd canvas"| failure
+  entry["入口触发<br/>Agent 进入已有项目，Adapter 识别运行环境，Context Compiler 基于 lane/task/revis…"]
+  experience["产品内步骤<br/>多个线程并发执行同一项目，Runtime 对 task 和 write-set 原子 claim，冲突被结构化返回，不相交任务…"]
+  decision{"决策点<br/>同一 session ID 在多个工作区有线索时不语义猜测，返回候选和安全阻断"}
+  success(["成功结果<br/>相同 revision 与请求生成稳定 context digest；默认完整 Capsule 不超过 800 tokens，…"])
+  failure[["失败与恢复<br/>expectedRevision 不一致时返回 OPENPRD_REVISION_CONFLICT，不覆盖新状态"]]
+  entry -->|"Agent 进入已有项目，Adapter 识别运行环境，Context Compi…"| experience
+  experience -->|"多个线程并发执行同一项目，Runtime 对 task 和 write-set 原…"| decision
+  decision -->|"用唯一 Project Ledger 管理项目业务事实，并把 current、ta…"| success
+  decision -.->|"expectedRevision 不一致时返回 OPENPRD_REVISION_…"| failure
 ```
 
 ### 架构
 
 ```mermaid
 flowchart LR
-  users["主要用户<br/>使用 OpenPrd 画布做视觉协同的开发者与产品设计协作者"]
+  users["主要用户<br/>用自然语言驱动 Codex、Cursor、Claude Code 完成产品开发的非专业或半专业用户 · 在同一代码项目中并发运…"]
   subgraph solution["方案边界"]
-    experience["Agent 使用场景层<br/>用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放回原图右侧 · Agent 调 GET /api…"]
-    core["核心产品逻辑<br/>OpenPrd 画布目前只有单向的“发送给 Codex”整体交接：Agent 不能结构化读取用户在画布上的选区与标注，不能把生…"]
-    integrations["依赖与集成<br/>依赖 openprd canvas 本地服务 · 依赖 0.1.18 生图路由协议"]
-    governance[["约束与可靠性<br/>不写入敏感信息 · 画布数据留在本地项目目录"]]
-    delivery["验证与交接<br/>标注改图闭环端到端可走通并有测试覆盖 · selection/insert-image API 有集成测试 · 尺寸契约出现在…"]
+    experience["Agent 使用场景层<br/>Agent 进入已有项目，Adapter 识别运行环境，Context Compiler 基于 lane/task/revis…"]
+    core["核心产品逻辑<br/>统一项目事实、并发运行态和上下文编译，降低 token、延迟、错误目标与长期维护成本"]
+    integrations["依赖与集成<br/>现有 OpenPrd CLI、skills、hooks、workspace schema、review renderer、qu…"]
+    governance[["约束与可靠性<br/>上下文与日志不得包含 API key、token、账号、个人隐私或未脱敏 prompt 原文 · 迁移备份只包含当前任务需要的…"]]
+    delivery["验证与交接<br/>相同 revision 与请求生成稳定 context digest；默认完整 Capsule 不超过 800 tokens，…"]
   end
-  users -->|"用户在画布圈选原图并批注，点“标注修改请求”，Agent 读标注生成修订图并放…"| experience
+  users -->|"Agent 进入已有项目，Adapter 识别运行环境，Context Com…"| experience
   experience -->|"产品动作与编排"| core
   core -->|"依赖与外部服务"| integrations
   core -.->|"策略、可靠性与合规"| governance
@@ -159,67 +191,99 @@ flowchart LR
 ## 需求
 
 - 功能需求:
-  - 选区状态随画布保存并可查询
-  - 插图 API 支持 left/right/below 摆放与 holder 替换
-  - 标注导出携带 annotationEdit 与源图形 ID 元数据
-  - 生图占位卡 handoff 记录携带宽高与比例契约
-  - hook 识别画布协同意图并注入闭环指引
+  - 提供 project manifest、ledger append/read/head/verify/rebuild、projection replay API
+  - 提供 task claim/heartbeat/release、lease recovery、write-set conflict、lane binding API 与 CLI
+  - 提供 context compile/diff/cache/render/reference API，保持 run --context 兼容入口
+  - 提供 scoped gate/evidence evaluation 与明确 approval ID 绑定
+  - 提供 ReviewModel 业务/工程投影与稳定确认合同
+  - 提供 adapter detect/capabilities/install/normalize/render/handoff SPI
+  - 提供 Knowledge v3 validate/promote/deprecate/supersede/query 生命周期
+  - 提供 upgrade plan/dry-run/backup/atomic apply/restore 与 fleet 安全批处理
+  - 提供 registry prune/compact 与测试环境 OPENPRD_HOME 隔离
 - 非功能需求:
-  - 界面文案面向普通用户
-  - API 只监听本地回环地址
-  - 新增代码有集成测试覆盖
+  - Node.js 20.19+，优先零新增运行时依赖，复用现有 YAML 与 Sharp
+  - 所有核心写入具备原子替换、revision、幂等键、checksum 和 crash recovery
+  - 读取路径默认无业务状态写入；telemetry 与事实真相分离
+  - 面向普通用户的默认文案使用简体中文、结果导向且不暴露内部实现术语
+  - 新旧 CLI 在一个兼容周期内保持字段与退出码兼容，并标注 deprecated 字段
+  - 每个迁移步骤可重复执行、可审计、可单项目回滚
 - 业务规则:
-  - 只做已确认四项能力，不扩 UI 引擎替换
-  - 生图仍走 0.1.18 生图路由，不擅用付费 API
+  - Project Ledger 是业务事实唯一真相，Harness 只存运行态，Review/Current/Task/Knowledge Index 是投影
+  - 显式 ID 优先于语义和 active change fallback；不能用最近状态猜用户目标
+  - 局部 task 成功不因无关 workspace debt 失败；发布、handoff 和 fleet 刷新仍执行项目级门禁
+  - Knowledge 必须有作用域、来源和证据；telemetry 不得改变知识正文或检索真相
+  - 归档和备份默认不可变；真实刷新范围必须由 inventory 分类而非仅按目录名猜测
+  - 版本 0.1.20 验证通过前不得刷新真实项目
 
 ## 业务护栏
 
 - 成本来源:
-  - 主要成本是生图调用次数与画布服务本地资源
+  - 全量线程与项目扫描、并发压力测试、Review 视觉验证、旧项目备份和批量迁移
+  - 重复上下文注入和过宽文档读取造成的 token 与执行时间
 - 额度与限制:
-  - 首版按单画布会话协同，不开放批量自动改图
+  - 默认 context Capsule 800 tokens，Delta 250 tokens；超预算需可解释裁剪
+  - 真实 fleet 按 Home、Projects、Context、活跃 worktree 分批执行，归档不纳入
+  - 单项目迁移失败不继续覆盖该项目，也不阻断已经验证成功的其他项目
 - 滥用防护:
-  - insert-image 校验锚点与文件存在性，避免脏写
-  - API 仅本地回环访问
+  - 高风险操作绑定明确 lane/operation approval ID，短句确认不能放行其他 lane
+  - Symlink 路径、too-new schema、dirty archive 分类不明时拒绝破坏性写入
+  - Context 编译进行 secret redaction，Knowledge promotion 需要证据和 reviewer
 - 监控信号:
-  - ops.json handoff 记录数、回填成功率、API 错误率
+  - context token、cold/warm p50/p95、cache hit、included/excluded reason
+  - claim 冲突、lease recovery、CAS conflict、lost update、write-set overlap
+  - projection digest、migration digest、rollback result、adapter drift、registry stale count
+  - 业务 Review 完成率、需求修订次数、用户可理解性检查与技术词泄漏
 - 报警阈值:
-  - 回填连续失败时提示用户检查画布服务状态
+  - 任何 lost update、错误项目写入、归档 checksum 变化、secret 泄漏或无法回滚均为阻断
+  - Context 超预算、p95 超 SLO、adapter fixture 不一致或 migration 对账不一致阻断真实 fleet
+  - 质量报告 productionReady=false 时不得声称整体完成
 - 止损动作:
-  - 异常时停止自动回填，保留原画布快照并回退到手动流程
+  - 切回 legacy read/storageMode，停止后续批次并按项目 restore preimage
+  - 保留失败报告、revision、digest 和 capability gap，不用写死逻辑绕过门禁
+  - 对分类不明的归档、副本或 symlink 目标保持只读
 
 ## 约束、依赖与风险
 
 - 技术约束:
-  - 沿用 Excalidraw embed 与现有 canvas-sessions 文件存储
-  - Node 内置测试框架
-  - 不新增外部依赖
+  - 保持现有 CLI、JSONL/JSON workspace 与 Codex/Claude/Cursor 生成路径的向后兼容
+  - 当前 git worktree 含既有 i18n 和 unfinished session 修改，必须保留用户改动并分层整合，禁止 reset/stash
+  - Repo-local canonical source 与生成文件必须区分，写入前检查任一路径祖先是否为 symlink
+  - 测试必须使用隔离 OPENPRD_HOME，禁止污染真实全局 registry
+  - Review Studio 改动必须复用现有视觉系统并提供前后、焦点、验证与对齐证据
 - 合规要求:
-  - 不写入敏感信息
-  - 画布数据留在本地项目目录
+  - 上下文与日志不得包含 API key、token、账号、个人隐私或未脱敏 prompt 原文
+  - 迁移备份只包含当前任务需要的最小文件并保留本机权限，不向外发送
+  - 不修改用户归档、远程仓库或生产环境
 - 依赖:
-  - 依赖 openprd canvas 本地服务
-  - 依赖 0.1.18 生图路由协议
+  - 现有 OpenPrd CLI、skills、hooks、workspace schema、review renderer、quality/standards/test infrastructure
+  - 本机 Node.js、npm 全局软链接与真实 OpenPrd 项目 inventory
+  - Codex、Cursor、Claude Code 当前可观测的 runtime capability 与生成协议
 - 假设:
-  - 用户接受标注截图作为修改指令载体
-  - Excalidraw selection 数据足以表达锚定需求
+  - 0.1.20 可在不移除 legacy 文件的前提下交付兼容控制平面纵向能力
+  - 现有 43 个活跃真实项目与历史 0.1.15/0.1.19 fixture 足以覆盖主要迁移形态
+  - Codex、Cursor、Claude Code 平台差异可通过 capability negotiation 明确表达
 - 风险:
-  - Excalidraw 与 tldraw 数据模型差异导致锚定语义需要适配
-  - 标注文字识别依赖 Agent 视觉能力
+  - 改造横跨状态、hook、CLI、review、knowledge 与迁移，若没有兼容分层会形成大爆炸式回归
+  - 当前 dirty worktree 与语义污染状态可能把既有用户改动误当成稳定基线
+  - Home 级 Skill symlink 与通用 skills-sync 可能再次制造跨适配器漂移
+  - 全局 registry 已被测试临时目录污染，直接 compact 或 fleet 可能误删仍需的定位索引
+  - Review 双投影若没有 canonical digest 会再次产生两套真相
 - 开放问题:
-  - 后续是否把画布协同扩展为独立 MCP server 另行评估
+  - Ledger 默认读路径在 0.1.20 是否切换到 dual-read，或先保持 legacy-read + shadow ledger；本轮以安全对账结果决定
+  - Home 全局 Skill 最终采用 adapter-neutral shared 内容还是让外部 skills-sync 排除 OpenPrd；本轮优先实现兼容 shared 内容与 symlink fence
+  - 历史 Documents 归档保持不可变，只验证 scanner 排除，不纳入版本刷新
 
 ## 类型专项模块
 
 - 类型: Agent 使用场景专项
-- humanAgentContract: 标注意图由人给出，修订图生成与回填由 Agent 自动完成；替换原图等破坏性动作仍需人确认。
-- autonomyBoundary: Agent 可自动读选区、生成并旁位回填；不得覆盖或删除用户原图与标注。
-- toolBoundary: 使用画布本地 HTTP API、生图路由选定的内置生图工具与 OpenPrd CLI。
-- stateModel: 画布 scene/selection/ops 文件保存在 .openprd/harness/canvas-sessions/<session-key>/。
-- evalPlan: 集成测试覆盖 selection/insert-image/标注导出元数据/hook 引导注入，最终跑 dev-check 与发布前四项验证。
+- humanAgentContract: 用户负责目标、范围和高风险外部动作授权；Agent 可在已授权范围内完成架构实现、测试、迁移、回滚和本地刷新。所有事实变更写入 Ledger，所有运行 ownership 写入 Lane/Task Runtime。
+- autonomyBoundary: 本轮用户明确授权无需中途确认，Agent 可自动处理本地源码和本地 OpenPrd 项目；不得扩展到远程 push、npm publish、生产云写入、归档篡改或敏感信息外发。
+- toolBoundary: 使用当前工作区代码、OpenPrd CLI、测试工具、Product Design 审计与视觉证据、本机只读 inventory；所有文件编辑通过可审计补丁，真实迁移先 dry-run 和备份。
+- stateModel: Project Ledger 记录业务事实；Manifest 记录模型与兼容版本；Lane/Task Runtime 记录临时 ownership；Context Capsule 是只读编译结果；Review、Current、Task Graph、Knowledge Index、Learning 是可重建投影。
+- evalPlan: 使用 characterization、unit、integration、concurrency、crash recovery、migration、rollback、performance、adapter parity、visual comparison、full regression、standards/quality/run/doctor 和真实 fleet readback 逐层验收。
 
 ## 交接
 
 - 负责人: OpenPrd
-- 下一步: 生成 change 与任务拆解后按序实现
-- 目标系统: OpenPrd CLI 画布子系统
+- 下一步: 按阶段完成 P0 回归与协议冻结、P1-P8 纵向实现、全量验证、0.1.20 版本升级和真实本地项目分批刷新
+- 目标系统: OpenPrd CLI、当前源码仓库、本机全局集成和所有真实活跃 OpenPrd 项目

package/.openprd/engagements/active/review-presentation-v0018.json

@@ -0,0 +1,176 @@
+{
+  "diagram": {
+    "type": "map",
+    "note": "从同一项目事实生成业务和工程两种阅读视图。"
+  },
+  "mapNodes": {
+    "problem": {
+      "title": "当前问题",
+      "text": "多份状态让上下文重复且目标易错"
+    },
+    "goal": {
+      "title": "升级目标",
+      "text": "一次编译精准上下文并安全并发"
+    },
+    "scope": {
+      "title": "本次范围",
+      "text": "统一事实、运行态、评审与迁移"
+    },
+    "flow": {
+      "title": "使用流程",
+      "text": "识别任务、领取执行、留证沉淀"
+    },
+    "risk": {
+      "title": "主要风险",
+      "text": "旧项目和本地改动必须可回滚"
+    }
+  },
+  "flowNodes": [
+    {
+      "id": "step1",
+      "text": "识别项目版本与当前任务"
+    },
+    {
+      "id": "step2",
+      "text": "按预算生成上下文并安全执行"
+    },
+    {
+      "id": "step3",
+      "text": "验证结果并沉淀可复用知识"
+    }
+  ],
+  "flowEdges": [
+    {
+      "from": "step1",
+      "to": "step2"
+    },
+    {
+      "from": "step2",
+      "to": "step3"
+    }
+  ],
+  "panels": {
+    "flow": [
+      {
+        "summary": "优化进入项目",
+        "detail": "Agent 先识别项目版本、当前任务和可用能力，只读取本次需要的事实。"
+      },
+      {
+        "summary": "新增安全领取",
+        "detail": "多个线程同时工作时先领取任务和文件范围，冲突会明确说明而不是互相覆盖。"
+      },
+      {
+        "summary": "优化执行上下文",
+        "detail": "首次提供完整摘要，后续只补变化内容，减少重复阅读和等待。"
+      },
+      {
+        "summary": "新增分级验收",
+        "detail": "单个任务先验证自己的结果，阶段和发布再汇总整个项目的健康度。"
+      },
+      {
+        "summary": "新增安全升级",
+        "detail": "旧项目先预检和备份，逐个升级；单个项目失败只回滚自己。"
+      }
+    ],
+    "function": [
+      {
+        "summary": "新增项目账本",
+        "detail": "需求、决定、任务和证据都从一份可追溯事实生成，不再由多份当前状态互相覆盖。"
+      },
+      {
+        "summary": "新增并行协调",
+        "detail": "任务领取、有效期、文件范围和版本检查共同保障多线程协作。"
+      },
+      {
+        "summary": "优化上下文",
+        "detail": "上下文按任务、风险和预算编译，并解释哪些内容被纳入或省略。"
+      },
+      {
+        "summary": "新增双视图",
+        "detail": "业务用户先看价值、范围、风险和验收，工程人员从同一结论查看任务与证据。"
+      },
+      {
+        "summary": "优化知识沉淀",
+        "detail": "经验有来源、适用范围、有效期和替代关系，过期内容不会继续误导 Agent。"
+      },
+      {
+        "summary": "统一三种工具",
+        "detail": "Codex、Cursor 和 Claude Code 使用同一适配合同，并如实说明能力差异。"
+      },
+      {
+        "summary": "新增版本协议",
+        "detail": "项目会明确记录可读写版本、迁移历史和回滚信息，避免新旧工具混用误写。"
+      }
+    ],
+    "guardrail": [
+      {
+        "summary": "限制上下文",
+        "detail": "完整摘要和增量摘要都有明确预算，超出时按重要性稳定裁剪。"
+      },
+      {
+        "summary": "保护用户改动",
+        "detail": "未提交代码、归档和发布副本不会被静默覆盖或清理。"
+      },
+      {
+        "summary": "隔离敏感信息",
+        "detail": "密钥、账号和个人信息不会进入上下文缓存、日志或知识正文。"
+      },
+      {
+        "summary": "保留回退路径",
+        "detail": "新账本先与旧状态并行对账，验证失败可以切回旧读取方式。"
+      },
+      {
+        "summary": "保持归档不变",
+        "detail": "历史备份只用于兼容验证，不纳入真实版本刷新。"
+      }
+    ],
+    "risk": [
+      {
+        "summary": "防止整体重写",
+        "detail": "升级按原子存储、账本、运行态、上下文、适配、评审和知识逐层切换。"
+      },
+      {
+        "summary": "修复旧状态污染",
+        "detail": "新的 v0018 与控制平面 change 取代混入 Canvas 内容的旧快照。"
+      },
+      {
+        "summary": "修复工具漂移",
+        "detail": "共享 Skill 内容不再写死某个平台，平台差异留在各自命令和运行能力中。"
+      },
+      {
+        "summary": "清理测试污染",
+        "detail": "测试改用隔离的 OpenPrd Home，真实 registry 再经过备份和有效路径校验后压缩。"
+      },
+      {
+        "summary": "防止双重真相",
+        "detail": "业务和工程评审共享同一模型摘要，样式变化不会改变已确认的业务结论。"
+      }
+    ]
+  },
+  "designDirections": {
+    "note": "三种方向均沿用现有 OpenPrd 视觉语言；本轮内部选择双轨证据工作台。",
+    "directions": [
+      {
+        "id": "guided-business-review",
+        "title": "业务评审导览",
+        "image": ".openprd/design/active/review-studio-v020-directions/crops/01.png",
+        "summary": "逐块引导非技术用户完成评审",
+        "tradeoff": "最易理解，但工程追溯需要另开入口"
+      },
+      {
+        "id": "dual-evidence-workbench",
+        "title": "双轨证据工作台",
+        "image": ".openprd/design/active/review-studio-v020-directions/crops/02.png",
+        "summary": "同一结论切换业务与工程视角",
+        "tradeoff": "兼顾理解与追溯，需控制默认密度"
+      },
+      {
+        "id": "project-cockpit",
+        "title": "项目驾驶舱",
+        "image": ".openprd/design/active/review-studio-v020-directions/crops/03.png",
+        "summary": "一屏掌握项目健康与并行任务",
+        "tradeoff": "全局感最强，但超出首版评审范围"
+      }
+    ]
+  }
+}

package/.openprd/i18n-config.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "defaultLanguage": "zh-Hans",
+  "supportedLanguages": [
+    "zh-Hans",
+    "en"
+  ],
+  "enforceOnDevCheck": true,
+  "platforms": [],
+  "translationStrategy": "key-value-file",
+  "notes": "用户可随时修改此文件来调整默认语言、支持语种和检查策略"
+}

package/.openprd/ledger/events.jsonl

@@ -0,0 +1,6 @@
+{"schema":"openprd.event","version":1,"eventType":"workflow.next","projectId":"project_a63099e6-6438-424c-ac39-49337f485ede","streamId":"workflow:workspace","revision":1,"occurredAt":"2026-07-10T15:49:37.758Z","actor":{"type":"openprd-cli"},"causationId":null,"correlationId":null,"payload":{"type":"next","at":"2026-07-10 23:49:37","nextAction":"freeze","reason":"已有版本化 PRD，交接前应先 freeze。","missingRequiredFields":0},"metadata":{"compatibilityProjection":".openprd/state/events.jsonl","ledgerPosition":1},"eventId":"evt_11631ea88d6fab75bc5c8cafe42f6053"}
+{"schema":"openprd.event","version":1,"eventType":"workflow.next","projectId":"project_a63099e6-6438-424c-ac39-49337f485ede","streamId":"workflow:workspace","revision":2,"occurredAt":"2026-07-10T15:50:35.624Z","actor":{"type":"openprd-cli"},"causationId":null,"correlationId":null,"payload":{"type":"next","at":"2026-07-10 23:50:35","nextAction":"freeze","reason":"已有版本化 PRD，交接前应先 freeze。","missingRequiredFields":0},"metadata":{"compatibilityProjection":".openprd/state/events.jsonl","ledgerPosition":2},"eventId":"evt_8a85b3115c9b80b9fa515af4425266e3"}
+{"schema":"openprd.event","version":1,"eventType":"workflow.next","projectId":"project_a63099e6-6438-424c-ac39-49337f485ede","streamId":"workflow:workspace","revision":3,"occurredAt":"2026-07-10T15:50:54.664Z","actor":{"type":"openprd-cli"},"causationId":null,"correlationId":null,"payload":{"type":"next","at":"2026-07-10 23:50:54","nextAction":"freeze","reason":"已有版本化 PRD，交接前应先 freeze。","missingRequiredFields":0},"metadata":{"compatibilityProjection":".openprd/state/events.jsonl","ledgerPosition":3},"eventId":"evt_ac6e2da11c56e11bb7d9ed5a28235548"}
+{"schema":"openprd.event","version":1,"eventType":"workflow.next","projectId":"project_a63099e6-6438-424c-ac39-49337f485ede","streamId":"workflow:workspace","revision":4,"occurredAt":"2026-07-10T15:50:54.891Z","actor":{"type":"openprd-cli"},"causationId":null,"correlationId":null,"payload":{"type":"next","at":"2026-07-10 23:50:54","nextAction":"freeze","reason":"已有版本化 PRD，交接前应先 freeze。","missingRequiredFields":0},"metadata":{"compatibilityProjection":".openprd/state/events.jsonl","ledgerPosition":4},"eventId":"evt_297d1bb2d4f438b418122ed4784814ce"}
+{"schema":"openprd.event","version":1,"eventType":"workflow.next","projectId":"project_a63099e6-6438-424c-ac39-49337f485ede","streamId":"workflow:workspace","revision":5,"occurredAt":"2026-07-10T15:51:01.843Z","actor":{"type":"openprd-cli"},"causationId":null,"correlationId":null,"payload":{"type":"next","at":"2026-07-10 23:51:01","nextAction":"freeze","reason":"已有版本化 PRD，交接前应先 freeze。","missingRequiredFields":0},"metadata":{"compatibilityProjection":".openprd/state/events.jsonl","ledgerPosition":5},"eventId":"evt_5bab375b038d07987fd886e782ab736b"}
+{"schema":"openprd.event","version":1,"eventType":"workflow.work.units.backfilled","projectId":"project_a63099e6-6438-424c-ac39-49337f485ede","streamId":"workflow:workspace","revision":6,"occurredAt":"2026-07-11T11:23:43.123Z","actor":{"type":"openprd-cli"},"causationId":null,"correlationId":null,"payload":{"type":"work_units_backfilled","at":"2026-07-11 19:23:43","versions":18,"changedVersions":18},"metadata":{"compatibilityProjection":".openprd/state/events.jsonl","ledgerPosition":6},"eventId":"evt_19b2167661a74c24174705119098e339"}