@prd-improve/cli 2.0.0 → 2.0.1

package/dist/skill/prd-improve-forge/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: prd-improve-forge
-description: Use when the user wants to write, refine, or structure a PRD for a specific feature — turning vague ideas, meeting notes, chat snippets, or legacy docs into a complete, edge-case-specified requirements spec. Unlike generic PRD helpers, it drives multi-round boundary questioning (P0/P1/P2 priorities) through feature-type checklists and produces a structured YAML spec, not free-form Markdown. Triggers on phrases like '写 PRD'、'整理需求'、'规范化需求'、'把 X 整理成 PRD'、'梳理功能边界'、'会议纪要整理成需求'、'聊天记录整理成 PRD'、'把这个想法变成规格'、'帮我做需求规格化' or English equivalents. Also handles refresh mode — updating an existing PRD against a new or changed PRD version — triggered by '同步新版 PRD'、'重新 sync'、'基于新版 PRD 更新'、'PRD 改了'、'PRD 升级了'、'feature 升级'、'对齐 PRD'、'incorporate PRD changes' or equivalents. Also handles closeout mode — closing out a delivered feature's PRD (backfilling open-question resolutions, recording as-built deviations, marking it shipped) — triggered by '收尾'、'交付收口'、'closeout'、'上线了把 PRD 收口'、'把这个 feature 收口'、'标记 shipped' or English equivalents ('close out the PRD', 'mark it shipped', 'post-delivery wrap-up'). DO NOT trigger for: (a) general product strategy / OKR / roadmap discussion with no specific feature scope; (b) writing code, implementation, architecture, or technical design docs; (c) editing a single field of an already-finalized PRD; (d) high-level vision documents or pitch decks; (e) a near-total rewrite of an existing PRD (start a fresh PRD instead).
+description: >-
+  Use when users need to write or refine a feature PRD from vague ideas, meeting notes, chats, or legacy docs; refresh an existing PRD after requirements change; or close out a delivered feature. Triggers include '写 PRD'、'整理需求'、'规范化需求'、'梳理功能边界'、'同步新版 PRD'、'PRD 升级了'、'交付收口'、'标记 shipped'、'incorporate PRD changes'、'close out the PRD', and equivalents. Do not use for strategy or roadmaps without a specific feature, implementation or architecture docs, isolated single-field edits, high-level vision or pitch decks, or near-total rewrites.
 ---
 
 # PRD Improve Forge
@@ -30,8 +31,10 @@ description: Use when the user wants to write, refine, or structure a PRD for a
 
 按以下顺序判定:
 
-0. **触发词 ∈ closeout 集合 + `working/prd.yaml` 存在且 frozen/ 下 ≥1 版** → closeout 模式 → 跳第 8 步
-   （working 不存在或从未 frozen → 告知用户「该 feature 还没有可收口的 PRD」,转白板/正常流程）
+0. **触发词 ∈ closeout 集合 + `working/prd.yaml` 存在** → closeout 模式 → 跳第 8 步
+   - working 已 `shipped` 且需要补证据/新迭代 → 先 `prd reopen <slug>`,再进入第 8 步
+   - working 已 `shipped` 但没有 frozen/manifest 交付版(`shipped-but-unfrozen`) → 同样 reopen 后首次 closeout,不得手工补 manifest/frozen
+   - working 不存在 → 告知用户「该 feature 还没有可收口的 PRD」,转白板/正常流程
 1. **触发词 ∈ refresh 集合 + `working/prd.yaml` 存在** → refresh 模式 → 跳第 7 步
 2. **触发词 ∈ refresh 集合 + `working/prd.yaml` 不存在** →
    询问用户「未找到现有 yaml,确认要走白板模式从 0 生成吗?」
@@ -221,6 +224,7 @@ description: Use when the user wants to write, refine, or structure a PRD for a
 
 - `.prd/features/<slug>/working/prd.yaml` 存在 → 继续
   - 不存在 → fallback 白板模式,明确告知用户
+- working 的 `meta.lifecycle.status` 是 `shipped` → **写盘前先跑 `prd reopen <slug>`**;不得手编 lifecycle 字段,也不得只改 shipped working 后停在 validate
 - 用户给了新 PRD?
   - 没给 → 询问路径或让粘贴文本
   - 给了 → 继续
@@ -296,15 +300,21 @@ AI 在 7.4 完成后,**必须输出**:
 - N 处变化已应用 / X 处拒绝 / Y 处新 open_questions
 - 文件路径(yaml + CHANGELOG.md)
 - 自检结果(若新 blocking 必须明示)
-- 下一步建议:解决 blocking → `prd freeze v1.1`
+- 下一步建议:
+  - 尚未交付的评审迭代 → 解决 blocking 后 `prd freeze <slug> --auto`
+  - 从 shipped 重开的已交付功能 → 解决 blocking、核对 as-built 后进入第 8 步 `prd closeout <slug> --commit <hash> --auto`,生成下一竣工版
 
 ---
 
 ### 第 8 步:closeout 工作流(交付收尾)
 
 #### 8.0 前置检查
-- `.prd/features/<slug>/working/prd.yaml` 存在且 frozen/ 下 ≥1 版,否则转出
+- `.prd/features/<slug>/working/prd.yaml` 存在,否则转出；**首次 closeout 不要求预先存在 frozen**
 - schema_version 是 v0.3?不是 → 先引导 `prd migrate-yaml <slug>`(v0.2→v0.3 是离线纯版本号变更)
+- working 已 `shipped`?
+  - 需要补证据/新迭代 → 先 `prd reopen <slug>`;不要手编 status/shipped_at/landed_commit
+  - 无需改内容 → 只做 8.5.1 三方一致性审计,已一致则不重复 closeout
+  - 没有 frozen/manifest 交付版(`shipped-but-unfrozen`) → reopen 后继续 closeout,由 CLI 首次生成 v1.0
 - 定位落地 merge commit:问用户;用户不确定时从 `git log --oneline --merges -10` 提候选给用户挑
 
 #### 8.1 决议提取(证据源分级降级,不依赖特定工作流习惯)
@@ -341,15 +351,28 @@ working/CHANGELOG.md 不存在 → 先创建(`# Changelog` + `## [Unreleased]`
 #### 8.5 执行 + 收尾
 1. 写盘 working/prd.yaml(8.2/8.3 的全部改动)
 2. 跑 `prd closeout <slug> --commit <hash> --auto`
-3. 转告收口报告:竣工版号 / N 决议 / M carry-over / K 偏差 / CHANGELOG 状态
+3. 执行 8.5.1 完成门禁
+4. 转告收口报告:竣工版号 / N 决议 / M carry-over / K 偏差 / blocker / CHANGELOG 状态 / 三方一致性结果
 失败时转告 stderr(CLI 已含回滚与恢复提示),不要自行重试改盘。
 
+#### 8.5.1 完成门禁(不可只凭 validate 宣告完成)
+
+closeout 后逐项确认 **working / manifest / frozen** 三方一致:
+
+1. `working/prd.yaml` 的 lifecycle 为 `shipped`,且 `landed_commit` 等于本轮核验提交。
+2. `.prd/manifest.json` 对应 feature 的 `latest_frozen_version` 与 `shipped_version` 都等于本轮版本。
+3. 最新 `frozen/<version>/` 至少含 `prd.yaml` 与 `snapshot.json`,版本元数据与 manifest 一致。
+4. 对比本轮变更:既有 frozen 文件不得出现 `M` / `D`;只能新增下一版本目录。
+5. 重新跑 `prd validate --feature <slug>`。真实 blocker 保持并报告,不得为全绿降级 severity 或伪造 resolution。
+
+任一项不满足 → 报告实际不一致并停止,不手工改 frozen/manifest 伪造闭环。
+
 #### 8.6 refresh 联动(shipped 之后再迭代)
-refresh 一个已 shipped 的 feature 时:working 的 `lifecycle.status` 回 `"draft"`、删除 `shipped_at` / `landed_commit` 两行(上一轮交付事实由 frozen 链 + manifest 承载,不丢)。这是 `prd freeze` shipped 守卫指引的路;CLI 的 `prd refresh` 命令是索引报告,不修改 yaml。
+refresh 一个已 shipped 的 feature 时:**先运行 `prd reopen <slug>`**,由 CLI 把 working 的 status 复位为 `draft`、删除 `shipped_at` / `landed_commit`,同时保留 frozen 链、manifest 交付史与旧问题决议。`prd refresh` 只生成索引报告,不修改 yaml。refresh 写盘后若该功能已交付,必须重新 closeout 生成下一 frozen 版,不能只停在 working PASS。
 
 #### 8.7 批量收口变体(N feature 一轮)
 
-N 个 feature 同时收口时:每 feature 派一个 8.1 证据提取 agent 并行起草(prompt 附跨 feature 线索)→ 全表一轮拍板(按 feature 分组列决议草稿带证据指针,用户一次过)→ 逐 feature 执行 8.3-8.5。实测 9 feature 30 条决议 1 轮交互即可完成。
+N 个 feature 同时收口时:每 feature 派一个 8.1 证据提取 agent 并行起草(prompt 附跨 feature 线索)→ 全表一轮拍板(按 feature 分组列决议草稿带证据指针,用户一次过)→ **逐 feature 串行**执行 8.3-8.5(`closeout` 共享写 `.prd/manifest.json`,禁止多 Agent 并行写)。实测 9 feature 30 条决议 1 轮交互即可完成。
 
 ---
 
@@ -709,20 +732,22 @@ refresh 模式下,**因 PRD 删除 / 修改 + refers_to 引用关系**而产生
 
 | 平台 | 用法 |
 |---|---|
-| **Claude Code / Claude.ai** | 复制 `packages/skill/prd-improve-forge/` 到 `~/.claude/skills/` |
+| **Claude Code / Claude.ai** | `prd skill install`(默认 `~/.claude/skills/`) |
+| **Pi / 共享 Agent 目录** | `prd skill install --dir ~/.agents/skills`(或项目 `.agents/skills`) |
 | **Cursor** | SKILL.md 内容粘贴到项目 `.cursorrules`;`templates/` / `checklists/` / `examples/` 放项目根的 `.prd-skill/` |
 | **ChatGPT / Custom GPT** | SKILL.md 作为 system prompt;三个子目录上传为 knowledge |
-| **Codex / Antigravity** | SKILL.md 内容放 system prompt / rules;子目录放项目根 |
+| **Codex / Antigravity** | 优先安装到工具配置的 skills 目录;否则用 `prd skill print` 放 system prompt / rules,完整目录由 `prd skill path` 定位 |
 
-**核心工作流不变**:识别模式 + 类型 → 加载资源 → (长材料先摘要) → 分轮追问 / refresh diff → 严格遵守 9 条硬规则 → 输出到 `.prd/features/<slug>/working/prd.yaml`(白板)或就地更新 + CHANGELOG append(refresh),或决议回填 + `prd closeout`(closeout)。
+**核心工作流不变**:识别模式 + 类型 → 加载资源 → (长材料先摘要) → 分轮追问 / refresh diff → 严格遵守 9 条硬规则 → 输出/更新 working → validate → freeze/closeout → 执行 working / manifest / frozen 完成门禁。模型负责语义判断,CLI 负责确定性状态与版本。
 
 ---
 
 ## 版本与维护
 
-**当前版本:** SKILL.md v0.11 · 对应 schema_version v0.3(resolve command + batch closeout 2026-06-12 + v0.6 正交维度层 + v0.7 priority 分级纪律 + v0.8 source_materials 可移植性 + v0.9 data_and_api.applies_to 注释准确化 + v0.10 轻模式×维度落点指引 + v0.11 performance applies_to 校验对齐(EN-* 强制,模板注释同步))
+**当前版本:** SKILL.md v0.12 · 对应 schema_version v0.3(resolve command + batch closeout 2026-06-12 + v0.6 正交维度层 + v0.7 priority 分级纪律 + v0.8 source_materials 可移植性 + v0.9 data_and_api.applies_to 注释准确化 + v0.10 轻模式×维度落点指引 + v0.11 performance applies_to 校验对齐 + v0.12 shipped 迭代版本闭环门禁)
 
 **变更历史:**
+- v0.12 — shipped working 的证据修复/新迭代强制 `reopen → validate → closeout --auto`;修正首次 closeout 必须已有 frozen 的旧前提;支持 shipped-but-unfrozen 恢复;完成前核对 working / manifest / frozen 三方一致、历史 frozen 不可变;批量 closeout 的 manifest 写入串行化
 - v0.10 — 轻模式 × 命中维度的硬约束落点指引:精选 P0 问出的硬约束落 acceptance_criteria / open_questions(不因结构段轻模式为空而丢弃),撑不进 AC 即触发中途升级;两份 dimension 清单挂载协议同步补轻模式落点。修协议冲突
 - v0.9 — data_and_api.applies_to 注释逐行准确化:data/api/security 明确 EN-* only + 校验失败提示;performance 明确不做引用校验
 - v0.8 — source_materials.url 注释提示可移植路径(仓库相对 / PRD 章节锚点,避免本机绝对路径)+ 范例演示;推广 v1.21 as_built.evidence 同款提示

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prd-improve/cli",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "PRD Improve CLI - validate / freeze / context for .prd/features/*.yaml",
   "license": "MIT",
   "type": "module",