@openprd/cli 0.1.11 → 0.1.18

package/.openprd/changes/loop-isolated-worktree-commit/tasks.md

@@ -0,0 +1,357 @@
+# 任务
+
+- [x] T001.01 评审生成的 spec 覆盖
+  - type: governance
+  - done: 生成的 agent-requirements spec 符合 PRD 意图
+  - verify: openprd change . --validate --change loop-isolated-worktree-commit
+  - test-layer: manual
+  - test-size: manual
+  - test-scope: governance
+  - evidence-plan: openprd change . --validate --change loop-isolated-worktree-commit
+  - upgrade-reason: 治理任务以结构校验、评审确认和变更状态证据为主
+  - execution-mode: serial
+  - parallel-group: governance
+  - write-scope: openprd/changes/**, .openprd/**
+  - owner-role: main-agent
+  - local-verify: openprd change . --validate --change loop-isolated-worktree-commit
+  - integration-owner: main-agent
+
+- [x] T001.02 接通界面入口、导航与页面挂载
+  - type: implementation
+  - deps: T001.01
+  - done: 用户可以从正确入口进入对应界面，页面挂载与状态收尾已经接通。 涉及: OpenPrd 的状态文件、review / change / tasks 主流程。
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.02 --evidence-required
+  - test-layer: integration, e2e
+  - test-size: large
+  - test-scope: user-flow
+  - evidence-plan: 主流程自动化、截图或 visual-compare 证据 + 本任务 verify 命令
+  - upgrade-reason: 触达用户可见路径，需要端到端或视觉级证据
+  - execution-mode: serial
+  - parallel-group: integration
+  - write-scope: src/**, test/**, docs/basic/**
+  - owner-role: main-agent
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.02 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.03 支持显式 worktree / branch 配置，或提供隔离运行包装命令
+  - type: implementation
+  - deps: T001.02
+  - done: 已完成：支持显式 worktree / branch 配置，或提供隔离运行包装命令
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.03 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: implementation
+  - write-scope: src/**, test/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.03 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.04 支持检测主工作区脏状态，并在 finish --commit 前阻断高风险路径
+  - type: implementation
+  - deps: T001.03
+  - done: 已完成：支持检测主工作区脏状态，并在 finish --commit 前阻断高风险路径
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.04 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: domain
+  - write-scope: src/**, test/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.04 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.05 支持基于 write-scope 或 touched files 生成本任务提交集
+  - type: implementation
+  - deps: T001.04
+  - done: 已完成：支持基于 write-scope 或 touched files 生成本任务提交集
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.05 --evidence-required
+  - test-layer: integration, security
+  - test-size: medium
+  - test-scope: security
+  - evidence-plan: 正向路径 + 越权、额度、并发或敏感信息负向验证
+  - upgrade-reason: 触达权限、安全、成本或滥用边界，需要至少集成级证据
+  - execution-mode: parallel-workers
+  - parallel-group: implementation
+  - write-scope: src/**, test/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.05 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.06 支持在 loop 状态、session 日志和测试报告中记录 commit 关联信息
+  - type: implementation
+  - deps: T001.05
+  - done: 已完成：支持在 loop 状态、session 日志和测试报告中记录 commit 关联信息
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.06 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.06 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.07 支持为未满足 commit 前置条件的任务给出清晰诊断与恢复指引
+  - type: implementation
+  - deps: T001.06
+  - done: 已完成：支持为未满足 commit 前置条件的任务给出清晰诊断与恢复指引
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.07 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: implementation
+  - write-scope: src/**, test/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.07 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.08 打通主流程闭环：用户为一个 change 进入 loop 开发时，OpenPrd 可显式创建或接入隔离 worktree 与命名 等 3 项
+  - type: implementation
+  - deps: T001.07
+  - done: 主流程关键节点已经打通，用户可以按预期从入口走到结果收尾。涉及: 用户为一个 change 进入 loop 开发时，OpenPrd 可显式创建或接入隔离 worktree 与命名分支，再在其中逐任务运行和提交 等 3 项。
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.08 --evidence-required
+  - test-layer: integration, e2e
+  - test-size: large
+  - test-scope: user-flow
+  - evidence-plan: 主流程自动化、截图或 visual-compare 证据 + 本任务 verify 命令
+  - upgrade-reason: 触达用户可见路径，需要端到端或视觉级证据
+  - execution-mode: serial
+  - parallel-group: integration
+  - write-scope: src/**, test/**, docs/basic/**
+  - owner-role: main-agent
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.08 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.09 验证在隔离 worktree 中连续完成多个 loop 任务时，每个任务都能生成独立 commit，并把 commitSha 写回状态
+  - type: verification
+  - deps: T001.08
+  - done: 已验证：在隔离 worktree 中连续完成多个 loop 任务时，每个任务都能生成独立 commit，并把 commitSha 写回状态
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.09 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.09 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.10 验证在脏主工作区直接尝试 finish --commit 时，会收到明确阻断和豁免提示
+  - type: verification
+  - deps: T001.09
+  - done: 已验证：在脏主工作区直接尝试 finish --commit 时，会收到明确阻断和豁免提示
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.10 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.10 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.11 验证从状态文件和 session 日志可以追溯每个任务对应的 worktree、branch、commit 和测试报告
+  - type: verification
+  - deps: T001.10
+  - done: 已验证：从状态文件和 session 日志可以追溯每个任务对应的 worktree、branch、commit 和测试报告
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.11 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.11 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.12 验证新能力不破坏现有 loop 的 plan、next、run、finish、verify 基本路径
+  - type: verification
+  - deps: T001.11
+  - done: 已验证：新能力不破坏现有 loop 的 plan、next、run、finish、verify 基本路径
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.12 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.12 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.13 回归非功能约束：默认路径必须安全，不能把无关改动静默卷入 commit / 行为必须可追踪，可从状态文件复原任务执行链路
+  - type: verification
+  - deps: T001.12
+  - done: 非功能约束已经回归确认。涉及: 默认路径必须安全，不能把无关改动静默卷入 commit / 行为必须可追踪，可从状态文件复原任务执行链路。
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.13 --evidence-required
+  - test-layer: integration, security
+  - test-size: medium
+  - test-scope: security
+  - evidence-plan: 正向路径 + 越权、额度、并发或敏感信息负向验证
+  - upgrade-reason: 触达权限、安全、成本或滥用边界，需要至少集成级证据
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.13 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.14 回归非功能约束：对现有 loop 用户保持兼容，新增能力应尽量显式开启或有明确默认策略 等 2 项
+  - type: verification
+  - deps: T001.13
+  - done: 非功能约束已经回归确认。涉及: 对现有 loop 用户保持兼容，新增能力应尽量显式开启或有明确默认策略 / 失败路径必须可恢复，不能留下半记录状态。
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.14 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.14 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.15 回归边界条件与失败处理：边界情况：用户在脏主工作区里直接尝试 finish --commit 等 8 项
+  - type: verification
+  - deps: T001.14
+  - done: 边界条件与失败处理已经回归确认。涉及: 边界情况：用户在脏主工作区里直接尝试 finish --commit 等 8 项。
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.15 --evidence-required
+  - test-layer: unit, integration
+  - test-size: medium
+  - test-scope: cli-contract
+  - evidence-plan: 单元测试锁定规则 + 集成或命令行契约验证
+  - upgrade-reason: 触达 CLI/API/Agent 契约或生成物，需要中间层验证
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.15 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.16 验证成本与额度护栏
+  - type: verification
+  - deps: T001.15
+  - done: 已验证免费、试用或低权限用户不能绕过额度、并发、频率或总量限制
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.16 --evidence-required
+  - test-layer: integration, security
+  - test-size: medium
+  - test-scope: security
+  - evidence-plan: 正向路径 + 越权、额度、并发或敏感信息负向验证
+  - upgrade-reason: 触达权限、安全、成本或滥用边界，需要至少集成级证据
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.16 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.17 验证滥用与越权路径
+  - type: verification
+  - deps: T001.16
+  - done: 已覆盖重复请求、并发请求、越权身份和异常恢复等负向场景
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.17 --evidence-required
+  - test-layer: integration, security
+  - test-size: medium
+  - test-scope: security
+  - evidence-plan: 正向路径 + 越权、额度、并发或敏感信息负向验证
+  - upgrade-reason: 触达权限、安全、成本或滥用边界，需要至少集成级证据
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.17 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.18 验证成本监控、报警和止损
+  - type: verification
+  - deps: T001.17
+  - done: 已确认用量或成本信号、报警阈值和人工/自动止损动作可执行
+  - verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.18 --evidence-required
+  - test-layer: integration, security
+  - test-size: medium
+  - test-scope: security
+  - evidence-plan: 正向路径 + 越权、额度、并发或敏感信息负向验证
+  - upgrade-reason: 触达权限、安全、成本或滥用边界，需要至少集成级证据
+  - execution-mode: parallel-workers
+  - parallel-group: verification
+  - write-scope: test/**, .openprd/harness/test-reports/**
+  - owner-role: worker
+  - local-verify: openprd tasks . --change loop-isolated-worktree-commit --item T001.18 --evidence-required
+  - integration-owner: main-agent
+
+- [x] T001.19 维护 docs/basic 项目基础文档
+  - type: documentation
+  - deps: T001.18
+  - done: 已检查 docs/basic 是否缺失或因本次需求、流程、结构、依赖、产品行为变化而过期；若涉及后端、脚本、Agent 或工具链变更，已同步评估 CLI 与 API 接入面，并在 backend-structure.md 中记录事实或不适用原因；需要更新的基础文档已同步
+  - verify: openprd standards . --verify
+  - test-layer: manual
+  - test-size: manual
+  - test-scope: docs
+  - evidence-plan: openprd standards . --verify
+  - upgrade-reason: 文档任务以标准校验和人工审查证据为主
+  - execution-mode: parallel-workers
+  - parallel-group: docs
+  - write-scope: docs/basic/**, README*.md
+  - owner-role: worker
+  - local-verify: openprd standards . --verify
+  - integration-owner: main-agent
+
+- [x] T001.20 更新文件说明书和文件夹 README
+  - type: documentation
+  - deps: T001.19
+  - done: 本次变更涉及的文件说明书和文件夹 README 已检查；缺失的已补齐，过期的已更新
+  - verify: openprd standards . --verify
+  - test-layer: manual
+  - test-size: manual
+  - test-scope: docs
+  - evidence-plan: openprd standards . --verify
+  - upgrade-reason: 文档任务以标准校验和人工审查证据为主
+  - execution-mode: parallel-workers
+  - parallel-group: docs
+  - write-scope: docs/basic/**, README*.md
+  - owner-role: worker
+  - local-verify: openprd standards . --verify
+  - integration-owner: main-agent
+
+- [x] T001.21 运行 OpenPrd spec 校验
+  - type: governance
+  - deps: T001.20
+  - done: 生成的 change 通过 OpenPrd 校验
+  - verify: openprd change . --validate --change loop-isolated-worktree-commit
+  - test-layer: manual
+  - test-size: manual
+  - test-scope: governance
+  - evidence-plan: openprd change . --validate --change loop-isolated-worktree-commit
+  - upgrade-reason: 治理任务以结构校验、评审确认和变更状态证据为主
+  - execution-mode: serial
+  - parallel-group: governance
+  - write-scope: openprd/changes/**, .openprd/**
+  - owner-role: main-agent
+  - local-verify: openprd change . --validate --change loop-isolated-worktree-commit
+  - integration-owner: main-agent

package/.openprd/changes/openprd/.openprd.yaml

@@ -0,0 +1,2 @@
+schema: openprd.change.v1
+generatedFrom: v0004

package/.openprd/changes/openprd/design.md

@@ -0,0 +1,46 @@
+# 设计
+
+## 背景
+
+用户已经确认，希望在现有短文案变化摘要的基础上，再补一个可选的项目级版本轨道：既能维护当前版本和版本内更新内容，也能在 commit 流里利用版本信息辅助打 tag，让 release notes、handoff 和外部同步有稳定来源。
+
+## 目标
+
+- 在 OpenPrd 现有内部 PRD 版本之上，新增一个可选的项目级 release/version 轨道，用来维护当前版本号与版本内更新项。
+- 把现有用户视角短文案摘要和项目版本轨道结合起来，让 commit、handoff、release notes 与外部同步都能复用同一套版本内变化条目。
+- 在用户显式使用 commit 流且版本信息可用时，提供与版本号协同的 tag 辅助能力，但保留高风险 git 行为的安全护栏。
+
+## 范围
+
+- 新增可选的项目级 release/version ledger，用于维护当前版本号、版本状态和版本内更新项。
+- 把现有变化摘要条目挂载到具体项目版本下，支持需求、Bug、handoff 摘要和 release notes 候选的累计。
+- 扩展 commit 流，在版本轨道已启用且用户显式执行 commit 时读取当前版本，并辅助创建或更新本地版本 tag。
+- 扩展 handoff、release notes 与后续外部同步出口，让它们可以从项目版本轨道导出版本内变化内容。
+- 补充 README、skills、文档和测试，并验证项目版本轨道与短文案摘要的协同效果。
+
+## 约束
+
+- 需要兼容现有 loop、handoff、review-presentation 和 html-artifacts 的调用契约。
+- 需要在 dirty workspace 中做窄改动，避免误伤正在进行的 test-strategy-router 等历史工作。
+- 依赖现有 OpenPrd CLI、review-presentation、html-artifacts、loop 和 handoff 导出流程。
+
+## 业务护栏
+
+- 成本来源: 无新增第三方付费调用成本；变化摘要完全基于本地上下文生成。
+- 额度限制: 不引入新的用户额度或发布配额限制；沿用现有 commit / handoff 执行门禁。
+- 滥用防护: 不默认自动 push、自动发布或自动 force 更新远端 tag。
+- 滥用防护: 只有在用户显式执行 commit 且版本轨道启用时，才进入版本 tag 辅助路径。
+- 滥用防护: 远端已有同名版本 tag 时，系统只提示风险和当前指向，不静默改写历史。
+- 监控信号: 关注生成摘要是否频繁退回技术细节、是否在测试中出现失真或空摘要。
+- 报警阈值: 如果三处输出中任一处无法生成可信摘要并持续回退，需要在测试中显式暴露。
+- 止损动作: 当上下文不足或摘要质量不可信时，回退到现有安全文案，不自动包装。
+
+## 风险与开放问题
+
+- 假设: 用户更看重人能快速扫懂的变化摘要，而不是技术完整性优先的底层说明。
+- 假设: 三处落点可以共用一套核心 formatter，再按场景做轻量渲染差异。
+- 风险: 如果 formatter 规则过死，可能把一些纯技术任务描述得失真。
+- 风险: 如果只改一处而没有共用 contract，后续很快会再次分叉。
+- 问题: 版本轨道是否需要支持 Unreleased 这种未定版态，还是只维护一个明确 current version。
+- 问题: 本地 tag 跟最新 commit 的策略是否只在未推远端前自动生效，还是需要更细的项目级配置。
+- 问题: Feishu 等外部同步出口首期是否只导出版本说明，不直接回写外部系统。

package/.openprd/changes/openprd/proposal.md

@@ -0,0 +1,36 @@
+# OpenPrd 项目级版本轨道与变化摘要
+
+## 背景与原因
+
+OpenPrd 现在已经有内部 PRD 版本和用户视角变化摘要，但还没有一个可选的项目级 release/version 轨道来维护当前版本号、版本内更新项，以及与 commit tag 的协同规则。结果是版本号已经在项目里被真实使用，却缺少一个本地真源来累计本版本的需求、Bug、handoff 摘要和最终发布说明。
+
+## 变更内容
+
+- 新增可选的项目级 release/version ledger，用于维护当前版本号、版本状态和版本内更新项。
+- 把现有变化摘要条目挂载到具体项目版本下，支持需求、Bug、handoff 摘要和 release notes 候选的累计。
+- 扩展 commit 流，在版本轨道已启用且用户显式执行 commit 时读取当前版本，并辅助创建或更新本地版本 tag。
+- 扩展 handoff、release notes 与后续外部同步出口，让它们可以从项目版本轨道导出版本内变化内容。
+- 补充 README、skills、文档和测试，并验证项目版本轨道与短文案摘要的协同效果。
+- OpenPrd 提供可选的项目级 release/version ledger，支持记录 current version、版本状态和版本内变化项。
+- 现有共享变化摘要规则支持把新增、修复、优化、调整、移除等条目关联到具体项目版本。
+- handoff 与 release notes 导出优先从项目版本轨道读取对应版本的变化条目。
+- 当版本轨道已启用且用户通过 OpenPrd 显式执行 commit 时，commit 流可以读取当前版本号并辅助创建或更新本地版本 tag。
+- 当用户未更新版本号时，后续变化默认继续累计到当前版本；当用户显式更新版本号后，新的变化进入下一个版本。
+- 新增项目级 release/version ledger，支持 current version、版本状态和版本内变化项存储。
+- 现有变化摘要层继续复用新增、修复、优化、调整、移除等短文案动作词，并能挂到具体项目版本下。
+- commit 流在启用版本轨道且用户明确执行时，可以读取当前版本并辅助创建或更新本地版本 tag；同版本多次提交时 tag 可移动到最新 commit。
+- README、skills、handoff/release 导出和测试同步说明版本轨道与 tag 协同规则。
+
+## 能力范围
+
+- `agent-requirements`: OpenPrd 项目级版本轨道与变化摘要 需求。
+
+## 影响范围
+
+- 主要用户: 维护 OpenPrd CLI、skills 和 review 产物的 OpenPrd maintainer
+- 主要用户: 使用 OpenPrd 执行任务并需要生成 commit、handoff 或版本说明的 Agent 使用者
+- 成本来源: 无新增第三方付费调用成本；变化摘要完全基于本地上下文生成。
+- 额度限制: 不引入新的用户额度或发布配额限制；沿用现有 commit / handoff 执行门禁。
+- 依赖: 依赖现有 OpenPrd CLI、review-presentation、html-artifacts、loop 和 handoff 导出流程。
+- 风险: 如果 formatter 规则过死，可能把一些纯技术任务描述得失真。
+- 风险: 如果只改一处而没有共用 contract，后续很快会再次分叉。

package/.openprd/changes/openprd/specs/agent-requirements/spec.md

@@ -0,0 +1,16 @@
+## 新增需求
+
+### 需求：OpenPrd 项目级版本轨道与变化摘要
+OpenPrd 现在已经有内部 PRD 版本和用户视角变化摘要，但还没有一个可选的项目级版本轨道来维护当前版本号、版本内更新项，以及与提交标签的协同规则。结果是版本号已经在项目里被真实使用，却缺少一个本地真源来累计本版本的需求、问题修复、交接摘要和最终发布说明。
+
+#### 场景：主流程成功
+- **当** 用户在项目里启用版本轨道后，OpenPrd 记录当前版本号，例如 0.1.23，并把后续变化条目累计到该版本下。
+- **则** 新增项目级版本账本，支持当前版本、版本状态和版本内变化项存储。
+
+#### 场景：边界情况保持可见
+- **当** 项目可能已经有自己的一套版本号规则，OpenPrd 需要允许手动修正当前版本号，而不是强推默认策略。
+- **则** 产品应保持该情况明确可见，以支持实现和验证
+
+#### 场景：失败模式得到处理
+- **当** 版本轨道和内部 PRD 版本被混用，导致用户误以为 v0003 就是项目发版号。
+- **则** 产品应提供有边界且可评审的结果

package/.openprd/changes/openprd/task-events.jsonl

@@ -0,0 +1,23 @@
+{"version":1,"at":"2026-06-02 13:24:40","changeId":"openprd","action":"advance","taskId":"T001.01","taskTitle":"评审生成的 spec 覆盖","ok":true,"verify":{"ok":true,"command":"openprd change . --validate --change openprd","exitCode":0,"stdout":"OpenPrd change 验证: 通过\nChange: openprd\n- OpenPrd change openprd: 1 个 spec delta。\n- openprd/changes/openprd/specs/agent-requirements/spec.md: 1 个需求。\n- 结构化 OpenPrd 任务: 22 个任务，21 条依赖；测试策略显式 22 个、推导 0 个；执行策略显式 0 个、推导 22 个。\n- OpenPrd 任务文件: 1 个文件，22 个 checkbox 任务，每个文件最多 25 个。\n- Standards docs root: docs/basic\n- Required docs: 6/6.\n- Manual templates: 2/2.\n- Development standards: code files ok <= 700 lines, attention <= 1500 lines.\n- Growth layer: enabled with user review required before applying candidates.\n","stderr":""},"evidence":null,"notes":null}
+{"version":1,"at":"2026-06-02 14:56:28","changeId":"openprd","action":"advance","taskId":"T001.02","taskTitle":"接通界面入口、导航与页面挂载","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.02 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:28","changeId":"openprd","action":"advance","taskId":"T001.03","taskTitle":"对齐共享契约与 Host API 调用边界","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.03 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:28","changeId":"openprd","action":"advance","taskId":"T001.04","taskTitle":"实现OpenPrd 提供可选的项目级 release/version ledger，支持记录 current version、版本状态和版本内变化项","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.04 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:28","changeId":"openprd","action":"advance","taskId":"T001.05","taskTitle":"实现现有共享变化摘要规则支持把新增、修复、优化、调整、移除等条目关联到具体项目版本","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.05 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:29","changeId":"openprd","action":"advance","taskId":"T001.06","taskTitle":"实现handoff 与 release notes 导出优先从项目版本轨道读取对应版本的变化条目","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.06 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:29","changeId":"openprd","action":"advance","taskId":"T001.07","taskTitle":"实现当版本轨道已启用且用户通过 OpenPrd 显式执行 commit 时，commit 流可以读取当前版本号并辅助创建或更新本地版本 tag","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.07 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:29","changeId":"openprd","action":"advance","taskId":"T001.08","taskTitle":"实现当用户未更新版本号时，后续变化默认继续累计到当前版本；当用户显式更新版本号后，新的变化进入下一个版本","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.08 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:29","changeId":"openprd","action":"advance","taskId":"T001.09","taskTitle":"打通主流程闭环：用户在项目里启用版本轨道后，OpenPrd 记录当前版本号，例如 0.1.23，并把后续变化条目累计到该版本下 等 4 项","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.09 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:29","changeId":"openprd","action":"advance","taskId":"T001.10","taskTitle":"验证新增项目级 release/version ledger，支持 current version、版本状态和版本内变化项存储","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.10 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:29","changeId":"openprd","action":"advance","taskId":"T001.11","taskTitle":"验证现有变化摘要层继续复用新增、修复、优化、调整、移除等短文案动作词，并能挂到具体项目版本下","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.11 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:29","changeId":"openprd","action":"advance","taskId":"T001.12","taskTitle":"验证commit 流在启用版本轨道且用户明确执行时，可以读取当前版本并辅助创建或更新本地版本 tag；同版本多次提交时 tag 可移动到最新 commit","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.12 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:29","changeId":"openprd","action":"advance","taskId":"T001.13","taskTitle":"验证README、skills、handoff/release 导出和测试同步说明版本轨道与 tag 协同规则","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.13 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:29","changeId":"openprd","action":"advance","taskId":"T001.14","taskTitle":"回归非功能约束：版本轨道是可选辅助信息，不应破坏现有没有版本管理习惯的项目流程 等 2 项","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.14 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:29","changeId":"openprd","action":"advance","taskId":"T001.15","taskTitle":"回归非功能约束：现有显式 commit message、自定义 handoff 内容和已有版本体系优先级不能被新能力静默覆盖 等 2 项","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.15 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:29","changeId":"openprd","action":"advance","taskId":"T001.16","taskTitle":"回归边界条件与失败处理：边界情况：项目可能已经有自己的一套版本号规则，OpenPrd 需要允许手动修正当前版本号，而不是强推默认策略 等 8 项","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.16 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:30","changeId":"openprd","action":"advance","taskId":"T001.17","taskTitle":"验证成本与额度护栏","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.17 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:30","changeId":"openprd","action":"advance","taskId":"T001.18","taskTitle":"验证滥用与越权路径","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.18 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:30","changeId":"openprd","action":"advance","taskId":"T001.19","taskTitle":"验证成本监控、报警和止损","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.19 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/quality/evidence/evo-quality-gates-20260602.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/quality/evidence/evo-quality-gates-20260602.md","notes":null}
+{"version":1,"at":"2026-06-02 14:56:51","changeId":"openprd","action":"advance","taskId":"T001.20","taskTitle":"维护 docs/basic 项目基础文档","ok":true,"verify":{"ok":true,"command":"openprd standards . --verify","exitCode":0,"stdout":"OpenPrd standards: 通过\nDocs root: docs/basic\n- Standards docs root: docs/basic\n- Required docs: 6/6.\n- Manual templates: 2/2.\n- Development standards: code files ok <= 700 lines, attention <= 1500 lines.\n- Growth layer: enabled with user review required before applying candidates.\n","stderr":""},"evidence":null,"notes":null}
+{"version":1,"at":"2026-06-02 14:56:52","changeId":"openprd","action":"advance","taskId":"T001.21","taskTitle":"更新文件说明书和文件夹 README","ok":true,"verify":{"ok":true,"command":"openprd standards . --verify","exitCode":0,"stdout":"OpenPrd standards: 通过\nDocs root: docs/basic\n- Standards docs root: docs/basic\n- Required docs: 6/6.\n- Manual templates: 2/2.\n- Development standards: code files ok <= 700 lines, attention <= 1500 lines.\n- Growth layer: enabled with user review required before applying candidates.\n","stderr":""},"evidence":null,"notes":null}
+{"version":1,"at":"2026-06-02 14:56:52","changeId":"openprd","action":"advance","taskId":"T001.22","taskTitle":"运行 OpenPrd spec 校验","ok":true,"verify":{"ok":true,"command":"openprd change . --validate --change openprd","exitCode":0,"stdout":"OpenPrd change 验证: 通过\nChange: openprd\n- OpenPrd change openprd: 1 个 spec delta。\n- openprd/changes/openprd/specs/agent-requirements/spec.md: 1 个需求。\n- 结构化 OpenPrd 任务: 22 个任务，21 条依赖；测试策略显式 22 个、推导 0 个；执行策略显式 0 个、推导 22 个。\n- OpenPrd 任务文件: 1 个文件，22 个 checkbox 任务，每个文件最多 25 个。\n- Standards docs root: docs/basic\n- Required docs: 6/6.\n- Manual templates: 2/2.\n- Development standards: code files ok <= 700 lines, attention <= 1500 lines.\n- Growth layer: enabled with user review required before applying candidates.\n","stderr":""},"evidence":null,"notes":null}
+{"version":1,"at":"2026-06-08 23:18:48","changeId":"openprd","action":"advance","taskId":"T001.03","taskTitle":"对齐共享契约与 Host API 调用边界","ok":true,"verify":{"ok":true,"command":"openprd tasks . --change openprd --item T001.03 --evidence-required","exitCode":0,"stdout":"OpenPrd task evidence: passed\nevidence: .openprd/harness/test-reports/openprd-session-registry-followup-20260608.md\nscope: task-only; workspace quality is reserved for phase/final gates","stderr":""},"evidence":".openprd/harness/test-reports/openprd-session-registry-followup-20260608.md","notes":null}