@openprd/cli 0.1.9 → 0.1.10

package/README.md

@@ -39,7 +39,7 @@ OpenPrd 是一个轻量但结构化的 **PRD harness**。你只需要先把问
 
 ![OpenPrd 需求分流节奏](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-requirement-routing-zh.png)
 
-- **快速修正**：问题已经很明确，影响小，验收也清楚。通常直接处理，改完告诉你改了什么、怎么验证。
+- **直接处理**：问题已经很明确，影响小，验收也清楚。通常直接处理，改完告诉你改了什么、怎么验证。
 - **现有功能优化**：目标明确，但会牵动几个页面、状态或用户动作。OpenPrd 会先用人话给你一版 mini-plan，方向对了再继续。
 - **新功能 / 新流程方案**：范围更大，角色更多，或者业务风险还不清楚。先把用户场景、第一版、先不做什么和主要风险讲清楚，再进入完整方案和任务拆解。
 
@@ -59,24 +59,6 @@ OpenPrd 解决的问题，不只是“把 spec 写出来”，也不只是“把
 OpenPrd 最有特色的地方，在于它把“这次到底在做什么、谁来确认、凭什么继续往下走”
 做成稳定可见的协作面，而不是只留在 spec 文件或 prompt 流程里。
 
-## 内置最佳实践与默认增强能力
-
-OpenPrd 不只负责把需求流程排好。对于“先参考什么更靠谱”这件事，它也内置了一层最佳实践路由，先帮 Agent 找对证据源，再继续改设计、写文案或动代码。
-
-- **公开仓库架构理解**：需要看 GitHub 公开仓库的整体结构、关键流程和实现线索时，默认优先 `DeepWiki`
-- **第三方技术文档**：需要确认库、框架、API、CLI、MCP 的用法、配置、限制、版本差异或迁移路径时，默认优先 `Context7`
-- **图标与视觉资源**：需要选 UI 图标、AI 品牌图标、技术栈图标、3D 素材或功能图标时，会先按用途路由到更合适的来源，而不是让 Agent 临时乱找
-- **项目级长期参考**：被反复采纳的外部来源可以沉淀成项目自己的最佳实践清单，后面类似任务会优先复用
-
-这层能力的目的不是堆资料链接，而是把“先查哪里、为什么查这里、查到什么程度就够”变成稳定协作的一部分。对于 AI 编程来说，这会直接影响方案质量、技术判断和最终实现的稳定性。
-
-目前 OpenPrd 内置的常见增强方向包括：
-
-- `DeepWiki`：理解 GitHub 公开仓库的架构、模块关系和关键流程
-- `Context7`：获取最新的第三方技术文档、配置说明、版本差异和迁移信息
-- 图标与视觉资源路由：按场景优先参考 `Phosphor Icons`、`LobeHub Icons`、`Tech Icons`、`Thiings`、`iconfont`
-- 图标实现库建议：真正落到前端代码时，再按项目情况选择 `Lucide`、`Tabler`、`React Icons`
-
 ## 典型真实场景
 
 最近 30 天的 Codex 项目记录里，OpenPrd 反复出现在几类连续工作里：模糊需求澄清、
@@ -143,6 +125,19 @@ OpenPrd 会沿着两条看得见的循环，越用越贴合你们的协作方式
 - 下次会自动带上什么：先问什么、先看什么、交付前先收什么材料。
 - 为什么有用：团队不用每次重新解释“这类项目该怎么开场”，而是直接从更合适的默认方式开始。
 
+## 默认带上的增强能力
+
+OpenPrd 不只是帮你把协作流程说清楚，也会把“该去哪里找资料、先看什么再继续”这件事提前铺好。对公开仓库、第三方技术文档和图标素材，它会默认走更合适的增强路径，而不是等你每次手动提醒。
+
+![OpenPrd 默认增强能力](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-best-practices-zh.png)
+
+- **公开仓库 / 对标参考**：优先用 `DeepWiki` 更快看懂架构、关键流程和实现线索。
+- **第三方库 / CLI / SDK / MCP**：优先用 `Context7` 看最新文档、配置方式、版本差异和迁移说明。
+- **图标与视觉素材**：按用途分流到更合适的资源站或实现库，不把 UI 图标、AI 品牌、技术栈图标和 3D 素材混着找。
+- **项目自己的做法优先**：先看仓库里已经确认过的经验和约定，再补外部最佳实践，不让通用建议盖过项目语境。
+
+这些增强能力默认是“配上更好”，不是硬依赖。没配置也不会影响初始化或当前任务，只会在后续建议里提醒你补上。
+
 ## 功能
 
 - **Clarification-first**：`clarify -> capture -> classify -> interview -> synthesize -> diagram -> freeze -> handoff`
@@ -216,7 +211,7 @@ openprd init /path/to/project --template-pack agent
 npx @openprd/cli@latest init /path/to/project --template-pack agent
 ```
 
-`init` 会创建 `.openprd/`、`docs/basic/`、`AGENTS.md`，并生成 Codex / Claude / Cursor 三端引导。Codex 项目会同时写入 `.codex/config.toml`、`.codex/hooks.json`、`.codex/hooks/openprd-hook.mjs`，并开启用户级 Codex `codex_hooks = true`。
+`init` 会创建 `.openprd/`、`docs/basic/`、`AGENTS.md`，并生成 Codex / Claude / Cursor 三端引导。Codex 项目会同时写入 `.codex/config.toml`、`.codex/hooks.json`、`.codex/hooks/openprd-hook.mjs`，并开启用户级 Codex `hooks = true`。
 
 Codex hooks 默认使用 `lite` 模式：安装 `UserPromptSubmit`、轻量
 `PreToolUse` 写入门禁，以及轻量 `Stop` 收工回顾。明确提到 OpenPrd、PRD、深度调研、深度对标、复刻、
@@ -268,7 +263,7 @@ openprd clarify /path/to/project
 
 OpenPrd 会先按用户可见的需求类型接住这句话，而不是先让你填一堆表单：
 
-- **快速修正**：通常直接做，做完告诉你改了什么、怎么验。
+- **直接处理**：通常直接做，做完告诉你改了什么、怎么验。
 - **现有功能优化**：先给一版 mini-plan，你确认方向后再继续。
 - **新功能 / 新流程方案**：先把场景、范围、第一版和风险说清楚，再进入 `review`、`change` 和 `tasks`。
 
@@ -562,7 +557,7 @@ openprd loop /path/to/project --run --agent codex --dry-run
 
 - `AGENTS.md` 中的 OpenPrd 管理规则
 - `.codex/skills/`、`.codex/prompts/`、`.codex/config.toml`、`.codex/hooks.json` 和 `.codex/hooks/openprd-hook.mjs`
-- 用户级 Codex config 的 `features.codex_hooks = true`
+- 用户级 Codex config 的 `features.hooks = true`
 - `.claude/skills/`、`.claude/commands/openprd/` 和 `CLAUDE.md`
 - `.cursor/rules/openprd.mdc` 和 `.cursor/commands/`
 - `.openprd/harness/install-manifest.json`、`hook-state.json`、`events.jsonl`、`drift-report.json` 和 `visual-reviews/`
@@ -591,7 +586,7 @@ PreToolUse 写入门禁，并把匹配范围限制在直接编辑工具上，同
 Codex 或 Claude 会话只处理这一个任务。每个任务完成后必须先自测，失败就修复并
 重新自测；前端界面任务在 Codex 客户端优先用 Computer Use，在 Codex CLI 和
 Claude Code 中优先用 Playwright、MCP 浏览器自动化或项目已有 e2e 工具。验证
-通过后，`loop --finish` 会写入阶段性测试报告，并可为该任务生成独立 commit。
+通过后，`loop --finish` 会写入阶段性测试报告，并可在隔离 worktree 中为该任务生成独立 commit。
 界面任务完成前必须运行 `openprd visual-compare`：已有参考图时截实现图并走
 `--reference/--actual`，没有参考图但改动界面时先留修改前截图、完成后留修改后截图并走
 `--before/--after`，查看左右对比 JPG 后才能完成任务。
@@ -612,12 +607,15 @@ openprd loop . --plan --change <change-id>
 openprd loop . --next
 openprd loop . --prompt --agent codex
 openprd loop . --run --agent codex --dry-run
+openprd loop . --run --agent codex --worktree ../openprd-loop-wt --branch loop/feature-x --dry-run
 openprd loop . --run --agent claude --dry-run
 openprd loop . --verify --item T001.01
-openprd loop . --finish --item T001.01 --commit --message "新增版本说明入口"
+openprd loop . --finish --item T001.01 --worktree ../openprd-loop-wt --branch loop/feature-x --commit --message "新增版本说明入口"
 ```
 
-如果项目启用了 `release` 版本轨道，`loop --finish --commit` 会在成功提交后把当前任务的短文案累计到当前项目版本下，并尝试把同名本地 tag（例如 `0.1.23`）移动到最新 commit。若远端已存在同名 tag，OpenPrd 会提示风险并跳过本地 tag 改写，不会静默覆盖远端历史。
+如果项目启用了 `release` 版本轨道，`loop --finish --commit` 会在成功提交时把当前任务的短文案累计到当前项目版本下，并尝试把同名本地 tag（例如 `0.1.23`）移动到最新 commit。若远端已存在同名 tag，OpenPrd 会提示风险并跳过本地 tag 改写，不会静默覆盖远端历史。
+
+主工作区已经有未纳入本任务提交的改动时，`loop --finish --commit` 默认会阻断，提示你改用 `--worktree <path> --branch <name>`；只有你明确知道要在主工作区做 scoped commit 时，才显式加 `--allow-dirty-main`。提交范围也不再是 `git add -A`，而是按任务 `write-scope`、任务来源文件和本轮新增 touched files 收窄，避免把无关改动卷进单任务 commit。
 
 Loop 状态会沉淀在 `.openprd/harness/`：
 
@@ -625,11 +623,11 @@ Loop 状态会沉淀在 `.openprd/harness/`：
 - `feature-list.json`：每个任务都会带一个人类可读的 `taskHandle`，例如
   `change-id:T001.01:task-title`，方便跨对话继续同一任务，而不是只靠聊天 UUID
 - `progress.md`：给人看的进度记录
-- `agent-sessions.jsonl`：每次 prompt / run / finish 的结构化事件，也会记录任务句柄和任务标题
+- `agent-sessions.jsonl`：每次 prompt / run / finish 的结构化事件，也会记录任务句柄、任务标题、worktree 路径、分支和 commit sha
 - `bootstrap.sh`：每个新会话启动时执行的检查脚本
-- `loop-state.json`：当前任务 id、任务句柄、任务标题，以及最近一次 Agent 会话状态
+- `loop-state.json`：当前任务 id、任务句柄、任务标题、baseline 脏文件，以及最近一次 worktree / 分支 / commit 状态
 - `loop-prompts/`：生成过的单任务提示词，便于审计和复用
-- `test-reports/`：每个任务的阶段性测试报告，会和任务改动一起提交
+- `test-reports/`：每个任务的阶段性测试报告，供审查、回归和后续会话复用
 
 建议先用 `--dry-run`，让 OpenPrd 生成提示词和准确执行命令，但不直接启动 Agent。
 `--agent codex` / `--agent claude` 会使用默认 CLI 集成；只有需要接入团队自定义

package/README_EN.md

@@ -181,7 +181,7 @@ automatically.
 - **Project knowledge skills**: turn verified fixes and recurring diagnosis patterns into reusable `.openprd/knowledge/skills/` experience skills
 - **OpenPrd change and task execution**: materialize PRD snapshots into change files, validate them, apply accepted specs, archive changes, and advance structured tasks by dependency order
 - **Long-running agent loop**: turn accepted change tasks into one-task-per-session Codex or Claude execution prompts with verification, progress logs, and optional task commits
-- **Default agent integration**: generate Codex, Claude, and Cursor guidance from one OpenPrd source, including Codex hooks with `codex_hooks = true`
+- **Default agent integration**: generate Codex, Claude, and Cursor guidance from one OpenPrd source, including Codex hooks with `hooks = true`
 - **Agent harness skills**: repo-local skills for shared rules, workflow control, and diagram review
 
 ## Tech Stack
@@ -249,7 +249,7 @@ If `openprd` is not on `PATH` yet, run the same init command through `npx`:
 npx @openprd/cli@latest init /path/to/project --template-pack agent
 ```
 
-`init` creates `.openprd/`, `docs/basic/`, `AGENTS.md`, and generated Codex / Claude / Cursor guidance. Codex projects also get `.codex/config.toml`, `.codex/hooks.json`, `.codex/hooks/openprd-hook.mjs`, and user-level Codex `codex_hooks = true`.
+`init` creates `.openprd/`, `docs/basic/`, `AGENTS.md`, and generated Codex / Claude / Cursor guidance. Codex projects also get `.codex/config.toml`, `.codex/hooks.json`, `.codex/hooks/openprd-hook.mjs`, and user-level Codex `hooks = true`.
 
 Codex hooks default to `lite`: `UserPromptSubmit`, a lightweight `PreToolUse`
 write gate, and a lightweight `Stop` end-of-turn review. Context is injected for prompts that explicitly mention OpenPrd,
@@ -639,7 +639,7 @@ or `openprd setup` inside a project.
 
 - `AGENTS.md` managed OpenPrd rules
 - `.codex/skills/`, `.codex/prompts/`, `.codex/config.toml`, `.codex/hooks.json`, and `.codex/hooks/openprd-hook.mjs`
-- user-level Codex config with `features.codex_hooks = true`
+- user-level Codex config with `features.hooks = true`
 - `.claude/skills/`, `.claude/commands/openprd/`, and `CLAUDE.md`
 - `.cursor/rules/openprd.mdc` and `.cursor/commands/`
 - `.openprd/harness/install-manifest.json`, `hook-state.json`, `events.jsonl`, `drift-report.json`, and `visual-reviews/`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openprd/cli",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "AI-native PRD workspace and lifecycle CLI",
   "type": "module",
   "license": "MIT",
@@ -14,14 +14,35 @@
     "README_EN.md",
     "SECURITY.md",
     "bin",
-    "docs/assets",
     "scripts",
     "src",
     ".openprd",
     "!.openprd/artifacts",
     "!.openprd/artifacts/**",
+    "!.openprd/benchmarks/evidence",
+    "!.openprd/benchmarks/evidence/**",
+    "!.openprd/benchmarks/inbox",
+    "!.openprd/benchmarks/inbox/**",
+    "!.openprd/discovery",
+    "!.openprd/discovery/**",
+    "!.openprd/engagements/active/architecture-diagram.html",
+    "!.openprd/engagements/active/architecture-diagram.json",
+    "!.openprd/engagements/active/architecture-diagram.mmd",
+    "!.openprd/engagements/active/brainstorm.html",
+    "!.openprd/engagements/active/brainstorm.json",
     "!.openprd/harness",
     "!.openprd/harness/**",
+    "!.openprd/engagements/active/flows.md",
+    "!.openprd/engagements/active/handoff.md",
+    "!.openprd/engagements/active/product-flow-diagram.html",
+    "!.openprd/engagements/active/product-flow-diagram.json",
+    "!.openprd/engagements/active/product-flow-diagram.mmd",
+    "!.openprd/engagements/active/review.html",
+    "!.openprd/engagements/active/roles.md",
+    "!.openprd/engagements/work-units",
+    "!.openprd/engagements/work-units/**",
+    "!.openprd/exports",
+    "!.openprd/exports/**",
     "!.openprd/learning",
     "!.openprd/learning/**",
     "!.openprd/quality/evidence",
@@ -37,8 +58,26 @@
     "!.openprd/knowledge/patterns/**",
     "!.openprd/knowledge/skills",
     "!.openprd/knowledge/skills/**",
+    "!.openprd/knowledge/adoption.jsonl",
+    "!.openprd/knowledge/candidates",
+    "!.openprd/knowledge/candidates/**",
+    "!.openprd/knowledge/drafts",
+    "!.openprd/knowledge/drafts/**",
+    "!.openprd/knowledge/index.json",
+    "!.openprd/knowledge/review-signals.jsonl",
+    "!.openprd/reviews",
+    "!.openprd/reviews/**",
+    "!.openprd/sessions",
+    "!.openprd/sessions/**",
+    "!.openprd/state/changes.json",
+    "!.openprd/state/current.json",
     "!.openprd/state/events.jsonl",
+    "!.openprd/state/freeze.json",
+    "!.openprd/state/release-ledger.json",
     "!.openprd/state/task-graph.json",
+    "!.openprd/state/version-index.json",
+    "!.openprd/state/versions",
+    "!.openprd/state/versions/**",
     "!.openprd/engagements/active/decision-log.md",
     "!.openprd/engagements/active/open-questions.md",
     "!.openprd/engagements/active/progress.md",