npm - @tanlinfeng/project-docs-workflow - Versions diffs - 2.1.0 → 2.3.0 - Mend

@tanlinfeng/project-docs-workflow 2.1.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/skills/project-docs-workflow/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: project-docs-workflow
-description: Initialize or align a project's documentation workflow — issue tracker, ADRs, PDR product specs (goal/current), recommended five-step development workflow, and domain terminology. Run manually once per project (idempotent); creates missing files and reports alignment without overwriting.
+description: Initialize or align a project's documentation workflow — issue tracker, ADRs, PDR target specs with a separate Current status tree, recommended five-step development workflow, and domain terminology. Run manually once per project (idempotent); creates missing files and reports alignment without overwriting.
 disable-model-invocation: true
 ---
@@ -32,7 +32,7 @@ Canonical wording (templates use the same line with the deps path parameterized)
 Run from the target project root (`cwd`).
 1. **Inventory** every artifact in the checklist below. Classify each as *missing* or *existing*. Done when every row has a classification.
-2. **Create missing** files from their template, and create the issue directory tree.
+2. **Create missing** files from their template, and create the issue directory tree. Create the `docs/current/00-README.md` overview when missing — do not force module files.
 2b. **Fill placeholders**: fill only obvious, determinable *fill-in* placeholders (e.g. project name from the repo/directory name); list every remaining fill-in placeholder under `Next:` in the report. Format notation such as `<标题>` is documentation, not a placeholder — skip it.
 3. **Compare existing** files against their template: classify *aligned*, or *diff* with the specific differences listed.
 4. **Report** using the format below.
@@ -49,13 +49,16 @@ Run from the target project root (`cwd`).
 | `docs/issues/` directory tree | none — create dirs (below) |
 | `docs/adr/README.md` | `assets/templates/project/adr-readme.md` |
 | `docs/pdr/00-README.md` | `assets/templates/project/pdr-00-readme.md` |
+| `docs/current/00-README.md` | `assets/templates/project/current-00-readme.md` |
 | `CONTEXT.md` | `assets/templates/project/context.md` |
 - Create `AGENTS.md` only if missing — its whole content is this block; a file containing only this section is intentional (projects add their own guidance around it). If `AGENTS.md` exists: heading `## Agent skills` present → compare the block in place (never edit); absent → append the block at end of file, separated by one blank line. Only `AGENTS.md` is touched, never `CLAUDE.md`.
 - The provenance line sits immediately under the `## Agent skills` heading and is intentional — keep it (it identifies materialized files and their generation).
 - Issue tree: `bug/{human,agent,history}`, `feature/{human,agent,history}`, `chore/{human,agent,history}`, `suggestion/{human,agent}`; add a `.gitkeep` to each leaf directory (one containing no files). Do not run `git init`.
 - Dep fallbacks: init copies `references/deps/*` into the project's `docs/agents/deps/` as a whole-directory copy (content unchanged), so target projects are self-sufficient even without this skill installed.
+- Current tree: init creates the `docs/current/00-README.md` overview when missing; it does **not** force module files — add them as modules need describing. The Current tree is peer to PDR, never embedded in it.
 - Domain glossaries (e.g. `docs/common/glossary.md`) are **not** scaffolded; the rules cover them and projects create them on demand.
+- Rendering is **out of scope for init**: init creates no renderer config, artifacts, or hooks. HTML rendering is an optional, manual first-party skill (`docs-html-view`); see `references/rendering.md`.
 ### Alignment comparison (existing files)
@@ -63,6 +66,8 @@ Compare **rules, not bytes**. An existing file is **aligned** when every require
 **diff** = a required rule/section is missing, or a default rule is contradicted. Diffs are informational; init never auto-fixes. One bullet per file: `- <file>: <missing or contradicted rule>`.
+**Legacy drift** (existing projects): embedded current/progress material found in an existing project — e.g. per-module `04-current.md`, a `当前进展` section in the PDR README — is reported as informational legacy drift. init never moves, rewrites, or deletes it, and there is no installation migration script; migrating to a separate Current tree requires the user's explicit authorization.
 Ignore in every comparison: the provenance line; filled placeholders; index/table rows; module/term/entry names; language; extra content.
 Required elements per artifact:
@@ -70,9 +75,10 @@ Required elements per artifact:
 - `AGENTS.md` block: `## Agent skills` heading + three subsections (`### Issue tracker`, `### Domain docs`, `### Development workflow`).
 - `docs/agents/issues.md`: directory contract; human/agent responsibility; entry format (`Status:` line, `## 完成判据`, `## 步骤`, `## Log`; the `## 结果` section itself is optional); archiving suffixes (`-done`/`-drop`); suggestion routing.
 - `docs/agents/domain.md`: read CONTEXT.md + docs/adr before exploring; silently continue if missing; glossary vocabulary rule; ADR-conflict flagging.
-- `docs/agents/workflow.md`: recommended five-step flow (规划 / 骨架 / 细节 / 异常 / 回顾 with 回顾 = docs-sync wrap-up); align-before-build ordering; conversational alignment (no freeze); elastic granularity suggestion (≈0.5 人天 heuristic); issue `## 步骤` tracking + resume anchor; PDR goal/current gap→issue derivation; boundaries (deepwork / tdd / retro / grilling 调用 + 兜底指针).
-- `docs/adr/README.md`: lifecycle rules (edit+Log, delete→tombstone stub, no renumber); catalog table present.
-- `docs/pdr/00-README.md`: purpose; 最终目标 / 当前进展 overview sections; module index; reading order.
+- `docs/agents/workflow.md`: recommended five-step flow (规划 / 骨架 / 细节 / 异常 / 回顾 with 回顾 = docs-sync wrap-up); align-before-build ordering; conversational alignment (no freeze); elastic granularity suggestion (≈0.5 人天 heuristic); issue `## 步骤` tracking + resume anchor; PDR-target / Current gap→issue candidate derivation; wrap-up updates Current in place (facts only, no self-link or task history); boundaries (deepwork / tdd / retro / grilling 调用 + 兜底指针).
+- `docs/adr/README.md`: lifecycle rules (edit+Log, delete→tombstone stub, no renumber); catalog table present; reference sweep covers both `ADR-XXXX` and `adr/<NNNN>-<slug>.md` path links (any relative prefix).
+- `docs/pdr/00-README.md`: purpose; end-state overview; module index; reading order; link to the peer Current tree (no progress section, no embedded current); optional descriptive ADR link rule.
+- `docs/current/00-README.md`: purpose; the baseline (revision/date) the tree describes; module/topic index; reading order; link to the peer PDR tree; records as-built capabilities/limits, not task logs or planned work; optional descriptive ADR link rule.
 - `CONTEXT.md`: glossary structure (term blocks with `_Avoid_`).
 - `docs/issues/` tree: leaf directories exist (`.gitkeep` may be checked); extras informational only.
 - `docs/agents/deps/`: leaf files exist (`grilling.md`, `domain-modeling.md`, `tdd.md`, `doc-opt.md`, `boundaries.md`); extras informational only.
@@ -86,6 +92,7 @@ Write the report in the project's documentation language (default: Chinese, matc
 - Created: …
 - Aligned: …
 - Diff: one bullet per file: `- <file>: <missing or contradicted rule>`（仅供参考，不自动改；multi-file → multiple bullets）
+- Legacy drift: embedded current/progress paths found (e.g. `04-current.md`, `当前进展` section) — informational only, never moved or rewritten; migration needs explicit user authorization.
 - Next: remaining placeholders plus a one-line "do this first".
 ```
@@ -95,7 +102,9 @@ Rules carry the detail; read the one you need.
 - `references/issues.md` — issue tracker directory contract, entry format, `suggestion` routing.
 - `references/adr.md` — ADR lifecycle (edit + Log, delete → tombstone stub, reference sweep, catalog index), body shape.
-- `references/pdr.md` — PDR product-spec structure (`00-README` / `01-spec` / `02-interfaces` / `03-nfr` / `04-current` + `design/`), the goal/current & gap→issues layer, PDR↔ADR boundary.
+- `references/pdr.md` — PDR target-spec structure (`00-README` / `01-spec` / `02-interfaces` / `03-nfr` + `design/`), the target & gap→candidate-issue layer, PDR↔ADR and PDR↔Current boundaries.
+- `references/current.md` — Current as-built tree (`00-README` + module/topic docs), baseline & verification confidence, sync semantics, peer relationship to PDR, legacy-drift adoption.
+- `references/rendering.md` — optional docs HTML rendering contract: render scope (`docs/pdr` + `docs/current` + the complete `docs/adr`, not issues / agents), link-authoring rules (PDR↔Current, optional descriptive ADR path links), sources never rewritten, manual opt-in.
 - `references/terminology.md` — `CONTEXT.md` primary glossary, domain glossary, usage rules.
 - `references/workflow.md` — recommended single-issue development flow (five steps, alignment, granularity, tracking, docs-sync hooks, skill boundaries).
 - `references/coexistence.md` — how this profile sits beside `domain-modeling`, `grilling`, `deepwork`, `tdd`, `retro`, and the bundled `doc-opt`; and how its docs/issues conventions supersede older `.scratch`-style trackers.

package/skills/project-docs-workflow/assets/templates/entries/current-module.md ADDED Viewed

@@ -0,0 +1,19 @@
+<!-- 文件名：<模块>.md，位于 docs/current/；记录实际能力与限制；基线默认继承 00-README.md；不写任务日志 / 待办 / 计划中的能力。 -->
+# <模块> 现状
+> 关联：[PDR <模块>](../pdr/NN-<模块>/00-README.md)（需要指向决策时可加描述性短语 + 稳定 ADR 链接，例：支持 [离线使用](../adr/0003-offline.md)；不转述 ADR 理由、不自动推断链接）
+<基线默认继承 `00-README.md`；仅当本文件基于不同基线时在此覆写：基线 <具体 revision / release> ｜ 快照 YYYY-MM-DD。>
+## 实际能力
+- <现已具备的能力，行为口径；对应 PDR 的 FR-<模块>-NN（如有）。>
+## 关键行为与限制
+- <关键行为 / 边界；已知限制、注意事项。>
+## 验证信心（仅例外时写）
+- <仅当某结论的验证信心需单独说明（未验证 / 推断）时列出；已按默认口径验证的结论不必逐条举证。>

package/skills/project-docs-workflow/assets/templates/entries/pdr-spec.md CHANGED Viewed

@@ -2,7 +2,7 @@
 # <模块> 功能规格
-> 定位：<模块> 目标态功能规格（FR-<模块>-NN，逐条给验收判据）。依据见 [design/](design/)（无 design/ 目录则删去该链接）与相关 ADR。
+> 定位：<模块> 目标态功能规格（FR-<模块>-NN，逐条给验收判据）。依据见 [design/](design/)（无 design/ 目录则删去该链接）；需要指向决策时，用描述性短语 + 指向稳定 ADR 文件的普通 Markdown 链接（例：支持 [离线使用](../../adr/0003-offline.md)）——不转述 ADR 理由，不要求每条 FR 都挂 ADR，也不自动推断链接。
 ## 1. <功能分组>

package/skills/project-docs-workflow/assets/templates/project/adr-readme.md CHANGED Viewed

@@ -17,7 +17,8 @@
   - `> 经 ADR-XXXX 修订（日期）：一句话`
   - `> 已废弃（日期）：原因`
   - `> 已删除（日期）：原因`（墓碑桩）
-- **删除或语义修改**触发引用核查：优先派 subagent，无则自行 grep `ADR-\d{4}`（范围 = 全仓库；`docs/` 必改，代码注释逐一判定：保留 / 更新 / 就地注释；逐一处理后再收尾）。引用优先改指替代 ADR 编号；无替代则删去该句或就地注明「（ADR-XXXX 已删除）」。
+- **删除或语义修改**触发引用核查：优先派 subagent，无则自行 grep；须覆盖两种写法——`ADR-\d{4}` 编号，以及指向 ADR 文件的 Markdown 路径链接（按稳定文件名 `adr/<NNNN>-<slug>.md` 匹配，相对前缀任意，如 `docs/adr/…`、`../adr/…`、`../../adr/…`，可带 `#fragment`）。范围 = 全仓库；`docs/` 必改，代码注释逐一判定：保留 / 更新 / 就地注释；逐一处理后再收尾。引用优先改指替代 ADR 编号；无替代则删去该句或就地注明「（ADR-XXXX 已删除）」。
+- PDR / Current 可用描述性短语 + 普通 Markdown 链接指向 ADR 文件（例：支持 [离线使用](../adr/0003-offline.md)），不强制写 `ADR-XXXX` 标签；不要求每条需求都挂 ADR，也不自动推断链接。路径链接在墓碑桩化后仍有效（文件名不可变、墓碑桩照常渲染）；但语义修改改变了链接所指内容，故语义修改后须重新核对路径链接，而不只是编号。
 ## 目录

package/skills/project-docs-workflow/assets/templates/project/agents-block.md CHANGED Viewed

@@ -12,4 +12,4 @@
 ### Development workflow
-推荐五步流程：规划 / 骨架 / 细节 / 异常 / 回顾。开工前先读 PDR 目标与现状（各模块 `04-current.md`），与用户对齐本次范围与粒度；步骤记录在 issue 的 `## 步骤`。约定见 `docs/agents/workflow.md`。
+推荐五步流程：规划 / 骨架 / 细节 / 异常 / 回顾。开工前先读 PDR 目标（`docs/pdr/`）与 Current 现状（`docs/current/`），与用户对齐本次范围与粒度；步骤记录在 issue 的 `## 步骤`。约定见 `docs/agents/workflow.md`。

package/skills/project-docs-workflow/assets/templates/project/agents-issues.md CHANGED Viewed

@@ -48,15 +48,16 @@ docs/issues/
 （若本机安装了 project-docs-workflow：条目骨架 ~/.agents/skills/project-docs-workflow/assets/templates/entries/issue-entry.md；未安装则按本文格式创建。）
-- `Status` 就地更新；`## Log` 追加式记录，不改历史行。
+- `Status` 就地更新；`## Log` 追加式记录，不改历史行，仅记关键事件（范围变化 / 阻塞 / 交接 / 放弃），不需要逐步机械追加。
 - 涉及 adr / pdr 的改动，须同步更新对应文档。
-- 推进流程见 `workflow.md`（推荐五步：规划 / 骨架 / 细节 / 异常 / 回顾）；步骤状态就地更新，变更记 Log。
+- issue 可引用 FR / 文档；收尾更新 Current 事实时，不插入指向本 issue 的自链接或任务历史。
+- 推进流程见 `workflow.md`（推荐五步：规划 / 骨架 / 细节 / 异常 / 回顾）；步骤状态就地更新，关键事件记 Log。
 ## 与开发流程的衔接
-- 开工前与用户对齐本次范围与粒度（差距候选来自 PDR 目标与现状）。
-- 步骤按 `docs/agents/workflow.md` 推荐流程推进，状态就地更新，变更记 Log。
-- 收尾回顾时更新受影响模块的 `04-current.md`。
+- 开工前与用户对齐本次范围与粒度（差距候选来自 PDR 目标与 Current 现状）。
+- 步骤按 `docs/agents/workflow.md` 推荐流程推进，状态就地更新，关键事件记 Log。
+- 收尾回顾时对照变更检查 `docs/current/` 对应文件是否有需更新（只改事实，不插入指向 issue 的自链接或任务历史）。
 ## 相关

package/skills/project-docs-workflow/assets/templates/project/agents-workflow.md CHANGED Viewed

@@ -12,8 +12,9 @@
 ## 开工前对齐
-读 PDR 目标与现状（`docs/pdr/` 的 `01-spec` 与各模块 `04-current.md`），列出差距候选（模块 / FR、类型、切片、完成判据），与用户确认要做哪条并落 issue。
+读 PDR 目标（`docs/pdr/`）与 Current 现状（`docs/current/`），列出差距候选（模块 / FR、类型、切片、完成判据），与用户确认要做哪条并落 issue。差异只是候选：可能是漂移 / 质量 / 未验证 / 目标过时，不都是缺失功能。
+- 对齐范围内 agent 自主实现（遵守 ADR / 契约 / 安全）；高成本、破坏性或难以回退的决定先与用户确认。
 - 对话确认即可：不冻结、不设仪式行。
 - 需求变化时主动重对齐，并更新 issue 内的计划与完成判据。
 - 方向有歧义 → 调用 `grilling`（未安装则按 `docs/agents/deps/grilling.md` 执行）；`grill-me` 仅入口别名。
@@ -23,7 +24,7 @@
 ### 规划
-细化完成判据与步骤状态，给出 1–2 句方案。产出最小，不新开章节。PDR 的目标 / 现状差距分析在此完成（候选带模块 / FR、类型、切片、完成判据；用户挑选后才落 issue）。
+细化完成判据与步骤状态，给出 1–2 句方案。产出最小，不新开章节。PDR 目标与 Current 现状的差距分析在此完成（对照 `docs/pdr/` 与 `docs/current/`；候选带模块 / FR、类型、切片、完成判据；用户挑选后才落 issue）。
 ### 骨架
@@ -39,14 +40,14 @@
 ### 回顾（收尾回顾）
-issue 完成时做一次轻量的文档同步清单（`pdr/current`、`adr`、`context`、`issues`、`agents` 是否有需更新）；若无，一行 Log 即可。仅做文档同步；会话复盘属于 `retro`（未安装则按 `docs/agents/deps/boundaries.md` 执行）。
+issue 完成时做一次轻量的文档同步清单（`pdr`、`current`、`adr`、`context`、`issues`、`agents` 是否有需更新）；若无，一行 Log 即可。仅做文档同步；会话复盘属于 `retro`（未安装则按 `docs/agents/deps/boundaries.md` 执行）。
 ## 进度与续接
-- 步骤记录在 issue 的 `## 步骤` 清单（就地更新）；步骤变更追加一行 Log。
+- 步骤记录在 issue 的 `## 步骤` 清单（就地更新）；仅在关键节点（范围变化 / 阻塞 / 交接 / 放弃）记 Log，不需要逐步机械追加。
 - session 为软约束：session = 用户注意力窗口，节奏由用户掌握；agent 不得吞并超出对齐范围的工作。
 - 恢复时先读 issue 的 `## 步骤` 与 `## Log`，与用户确认续点后再继续。
-- issue 收尾时更新受影响模块的 `04-current.md`，并按 `issues.md` 归档。
+- issue 收尾时对照变更检查 Current：若变更已包含在选定基线内则更新 `docs/current/` 对应文件（只改事实，不插入指向 issue 的自链接或任务历史），否则不更新，在 issue 记待同步项；并按 `issues.md` 归档。
 ## 边界
@@ -57,5 +58,7 @@ issue 完成时做一次轻量的文档同步清单（`pdr/current`、`adr`、`c
 ## 相关
 - Issue 体系：`issues.md`
-- PDR 文档集：`../pdr/00-README.md`
+- PDR 目标文档集：`../pdr/00-README.md`
+- 现状文档集（Current）：`../current/00-README.md`
 - 依赖兜底文档（外部技能未安装时）：`docs/agents/deps/`
+- 文档 HTML 渲染（可选、手动）：独立技能 `docs-html-view`；本流程不自动安装 / 构建 / 渲染。

package/skills/project-docs-workflow/assets/templates/project/current-00-readme.md ADDED Viewed

@@ -0,0 +1,42 @@
+> 模板来源：project-docs-workflow v2（模板演进后可重跑幂等 init 对齐；本文件可按项目实际修改）
+# 现状文档集（Current）
+描述产品**当前实际**的能力、关键行为与限制，并给出各项结论相对**基线**的验证信心。与 [PDR 目标文档集](../pdr/00-README.md) 平级、互相独立；本集不写任务日志 / 待办 / 计划中的能力。
+## 基线
+<本集基线：**由项目显式选定**的代码快照 / 发布版本。若尚无选定基线，先向用户确认，不要默认取 main 或最新 release。写具体 revision / release + 日期；单独会移动的分支名不足以定位快照。例：vX.Y.Z（2026-XX-XX，commit abc123）。>
+<基线在本文件声明一次，各模块 / 主题文件默认继承，无需逐条重复举证。个别文件基于不同基线时（如某模块已随新基线前移），在该文件单独覆写并在下方索引注明。验证信心同理：默认口径在此说明，只有例外才逐条标注。>
+## Current 维护
+- 同步只跟随**选定基线**：只记录已包含在该基线内的变更；尚未进入基线的改动不写入。
+- issue 收尾时检查变更是否已包含在选定基线：是则更新受影响的 Current 文件（只改事实，不插入指向 issue 的自链接或任务历史）；否则不更新，在 issue 记一条待同步项。
+- 基线前移时刷新受影响的 Current 文件（无自动化 / 钩子，属评审动作）。
+- 实际状态未变则不改动。
+## 模块 / 主题索引
+| 模块 / 主题 | 定位 | 入口 |
+| :--- | :--- | :--- |
+<!-- 示例（新增时替换并删除本行）：| <模块名> | <一句话定位> | <模块>.md | -->
+## 阅读顺序
+<先读什么建立现状基线，再按模块读；跨模块主题按需单列。>
+## 与 PDR 的关系
+- PDR = 目标（`docs/pdr/`），本集 = 实际形态；两棵树各自可读、互不内嵌。
+- 两边的模块 / FR 用链接关联（语义 / 导航 / 契约链接皆可），多对多，不强制逐文件对应。
+- 需要指向某项决策时，用描述性短语 + 指向稳定 ADR 文件的普通 Markdown 链接（例：支持 [离线使用](../adr/0003-offline.md)）；不转述 ADR 理由，ADR 链接可选、不自动推断。
+- 对照目标与实际得到的是**候选**任务，供用户挑选；差异不都是缺失功能（可能是漂移 / 质量 / 未验证 / 目标过时）。
+## 新增模块 / 主题
+- 在本目录按需新增 `<模块>.md` 或主题文件（不强制编号对齐 PDR）；
+- 在上方索引与阅读顺序登记入口；基于不同基线的文件在此注明；
+- 结论默认继承本文件基线；仅当该文件基线不同或验证信心有例外时单独说明。

package/skills/project-docs-workflow/assets/templates/project/pdr-00-readme.md CHANGED Viewed

@@ -2,16 +2,12 @@
 # PDR 文档集
-PDR（Product Design Requirements）= 产品最终功能与形态规格书（目标态）：描述产品最终要长成什么样、由哪些模块构成、各模块对外契约与机制设计。
+PDR（Product Design Requirements）= 产品最终功能与形态规格书（目标态）：描述产品最终要长成什么样、由哪些模块构成、各模块对外契约与机制设计。只记**当前生效的最终目标**（粗 / 细要求都是已确认约束），不记现状与进展；现状见平级的 [现状文档集](../current/00-README.md)。
 ## 最终目标
 <一段话描述产品的最终形态；各模块的细化目标见其 `01-spec.md`。>
-## 当前进展
-<每个模块一行概览，并指向该模块的 `04-current.md`；只记状态与差距，不写流水账。>
 ## 模块索引
 | 区 / 模块 | 定位 | 入口 |
@@ -21,7 +17,9 @@ PDR（Product Design Requirements）= 产品最终功能与形态规格书（目
 ## 组织约定
-- 编号即阅读顺序：每模块 = 规格层（`00-README` / `01-spec` / `02-interfaces` / `03-nfr`）+ 现状快照（`04-current.md`，与目标的差距用于派生 issue）+ 设计子区（`design/`，机制级设计，不参与编号）。
+- 编号即阅读顺序：每模块 = 规格层（`00-README` / `01-spec` / `02-interfaces` / `03-nfr`）+ 设计子区（`design/`，机制级设计，不参与编号）。
+- 现状不在本集内：见平级的 [docs/current/](../current/00-README.md)；两边的模块 / FR 用链接关联（语义 / 导航 / 契约链接皆可），多对多，不逐文件对应。
+- 需要指向某项决策时，用描述性短语 + 指向稳定 ADR 文件的普通 Markdown 链接（例：支持 [离线使用](../adr/0003-offline.md)）；不转述 ADR 理由，不要求每条 FR 都挂 ADR，也不自动推断链接。
 - 模块外区：架构总纲、调研等跨模块材料按需单列，不占模块编号。
 ## 阅读顺序
@@ -31,6 +29,7 @@ PDR（Product Design Requirements）= 产品最终功能与形态规格书（目
 ## 新增模块
 - 在 `docs/pdr/` 下建编号目录（编号沿用阅读顺序，不插号）；
-- 补齐规格层四件套（`00-README` / `01-spec` / `02-interfaces` / `03-nfr`）与现状快照 `04-current.md`，机制细节进 `design/`；
+- 补齐规格层四件套（`00-README` / `01-spec` / `02-interfaces` / `03-nfr`），机制细节进 `design/`；
 - 在上方模块索引与阅读顺序中登记入口，明确对外接口的提供方归属；
+- 需要记录该模块现状时，在 `docs/current/` 增补对应文件（不强制对齐编号）；
 - 涉及产品形态的决策，同步落 ADR。

package/skills/project-docs-workflow/references/adr.md CHANGED Viewed

@@ -36,7 +36,11 @@ Status block on the first lines after the H1. Active entries carry none. Retired
 ## Reference sweep
-`ADR-XXXX` (4-digit zero-padded) is the only reference notation. Whenever an entry is **deleted or semantically edited**, the executor must sweep references: prefer a subagent; without one, grep directly. Pattern `ADR-\d{4}`; scope = the whole repository (`docs/` must be updated; code comments judged one by one: keep / update / annotate in place). Handle every hit before finishing. When a reference points at a deleted entry, prefer retargeting it to the replacing ADR number; with no replacement, drop the sentence or annotate it in place `(ADR-XXXX deleted)`.
+`ADR-XXXX` (4-digit zero-padded) is the native citation notation. PDR / Current may also link an ADR by **stable Markdown path** — e.g. `支持[离线使用](../../adr/0003-offline.md)`, optionally with a `#fragment`; there the descriptive phrase carries the meaning, so no `ADR-XXXX` label is required at the link site. Both notations are valid; this does not change the ADR lifecycle (see `rendering.md`).
+Whenever an entry is **deleted or semantically edited**, the executor must sweep references: prefer a subagent; without one, grep directly. Sweep **both notations** — the `ADR-\d{4}` number, and Markdown links to an ADR file by its stable filename pattern `adr/<NNNN>-<slug>.md` (any relative prefix — `docs/adr/…`, `../adr/…`, `../../adr/…`, with or without a `#fragment`). Scope = the whole repository (`docs/` must be updated; code comments judged one by one: keep / update / annotate in place). Handle every hit before finishing. When a reference points at a deleted entry, prefer retargeting it to the replacing ADR number; with no replacement, drop the sentence or annotate it in place `(ADR-XXXX deleted)`.
+Path links survive tombstoning (the filename is immutable) and a tombstone stays rendered, so such links keep resolving — but a **semantic** edit changes the content the link is about, so re-read and review each path-linked reference, not only the number.
 ## Index (README)

package/skills/project-docs-workflow/references/current.md ADDED Viewed

@@ -0,0 +1,39 @@
+# Current-state docs
+Current = what the product **is now, as built**: actual capabilities, key behavior, and limits, each stated against a project-specified baseline. A peer tree to the PDR (`pdr.md`), not a section of it. Default profile; overridable in project copies. Current is in the default render scope, together with the PDR tree and the complete ADR set (`rendering.md`).
+## Structure
+- `docs/current/00-README.md` — overview + navigation: it declares the **selected baseline** and, centrally, the verification-confidence convention, then indexes module / topic docs. No per-module status roll-up is required; link out.
+- Module docs — one per module as needed; each records actual capabilities, key behavior, and limits. Claims inherit the overview's baseline and confidence; a module doc overrides the baseline only when it genuinely differs.
+- Optional topic docs — cross-cutting areas (e.g. operations, data) added only when needed.
+- Layering is overview → module → optional topics. Add only what the project actually has; there is no fixed schema.
+The Current tree is **not numbered against PDR**: modules may align by name, but there is no file/paragraph mirroring. Link PDR modules / FRs explicitly and many-to-many.
+## What a Current doc records
+- **Baseline** — the **selected** baseline: a concrete revision / release plus the snapshot date. The project selects it explicitly; if none is chosen, ask the user — never silently default to `main` or the latest release. A mutable branch name alone is not a snapshot id; pin a revision or release.
+- **Actual capabilities** — what works now, in behavior terms.
+- **Limits and known constraints** — what does not work, downside, boundaries, caveats.
+- **Verification confidence** — how claims were established (tested / observed / inferred). Declare the norm centrally in the overview; state confidence per claim only where it matters (an exception), not repetitively for every claim.
+Do not record: task logs, todos, planned / future capabilities, per-issue progress. Those live in `docs/issues/` and the PDR. An issue wrap-up updates the affected Current **facts in place**; it never inserts a self-link to the issue or task history.
+## Sync
+- Current follows the **selected baseline**: record only changes included in that baseline. Refresh the affected Current docs when the baseline advances; a change not included in the selected baseline is not Current yet. Actual state unchanged → no edit.
+- Issue wrap-up **checks** whether the completed change is included in the selected baseline: yes → update the affected Current docs; no → leave them and record a pending sync item in the issue.
+- There is no automation or hook that writes Current. Sync is a review step, not a generated artifact.
+## Relationship to PDR
+- PDR = target (`pdr.md`); Current = as-built. Two independent, user-readable trees; neither embeds the other.
+- **Semantic / navigation / contract links** between the trees are expected — write ordinary relative Markdown links; there is no file/paragraph mirroring.
+- A Current doc may point at an ADR with a **descriptive phrase + a stable path link** (e.g. `支持[离线使用](../../adr/0003-offline.md)`); the description is written independently and the ADR's rationale is not transcluded. ADR links are optional, and the profile never infers them (see `rendering.md`).
+- Gap comparison reads both and yields **candidate** tasks for the user to choose — not every difference is a missing feature. A difference may be drift, a quality gap, unverified behavior, or an outdated target. An already-met coarse goal can still be refined; do not invent gaps.
+## Adoption (existing projects)
+- Existing docs are never overwritten or moved. If a project previously embedded current/progress material inside the PDR (e.g. per-module `04-current.md`, a 当前进展 section), init reports those paths as informational **legacy drift**.
+- Migrating to a separate Current tree is an explicit user decision; there is no installation migration script and no automatic move.

package/skills/project-docs-workflow/references/issues.md CHANGED Viewed

@@ -26,7 +26,7 @@ docs/issues/
 - Body: background and goal, as prose.
 - `## 完成判据` — completion criteria.
 - `## 结果（完成后填写，可选）` — outcome, filled in on completion (optional).
-- `## 步骤` — the five-step checklist from `workflow.md`; update it in place, and append a Log line on every step change. Materialized (Chinese) copies show:
+- `## 步骤` — the five-step checklist from `workflow.md`; update it in place. Step changes need no Log entry by themselves. Materialized (Chinese) copies show:
   ```
   ## 步骤
@@ -37,9 +37,10 @@ docs/issues/
   - [ ] 回顾（收尾回顾：文档同步）
   ```
-- `## Log` — dated lines appended in place; never rewrite history lines.
+- `## Log` — dated lines appended in place; existing lines are history and never rewritten. Record only key events, briefly: scope change, blocker, handoff, abandonment. Mechanical per-step entries are not required. A skipped-skeleton rationale on a pure fix is a legitimate key entry.
 - `Status` is updated in place.
 - Work that changes an ADR or PDR must sync those documents.
+- An issue may reference FRs / docs. A wrap-up that updates the Current tree changes **facts only** — it never inserts a self-link to the issue or task history (see `current.md`).
 - If the skill is installed, the skeleton lives at `~/.agents/skills/project-docs-workflow/assets/templates/entries/issue-entry.md`; otherwise create from the format above.
 ## `suggestion` routing

package/skills/project-docs-workflow/references/pdr.md CHANGED Viewed

@@ -1,33 +1,38 @@
 # PDR product specs
-PDR = target-state product spec ("产品规格书"): what the product should become, its modules, outward contracts, and mechanism design. Default profile; overridable in project copies.
+PDR = target-state product spec ("产品规格书"): the product's currently-effective final target — its modules, outward contracts, and mechanism design. Only confirmed constraints (coarse or fine) are recorded; implemented details are not auto-promoted into the PDR. Default profile; overridable in project copies.
 ## Structure
-- Module directories numbered by reading order (e.g. `01-architecture/`, `02-ui/`). Root `00-README.md` = module index + reading order.
+- Module directories numbered by reading order (e.g. `01-architecture/`, `02-ui/`). Root `00-README.md` = overview + module index + reading order.
 - Each module:
   - `00-README.md` — role / scope-boundary / dependencies / doc map.
   - `01-spec.md` — functional requirements, each with an `FR-<MODULE>-NN` ID and 验收判据 (acceptance criteria). FR IDs are stable and never reused; numbering is continuous per module.
   - `02-interfaces.md` — interface contracts. The providing module owns its outward interfaces; consumers reference them.
   - `03-nfr.md` — non-functional requirements.
-  - `04-current.md` — current-state snapshot vs the spec; dated, ≤1 page, conclusions and gaps only. See "Goal / current & gap→issues".
   - `design/` — optional mechanism-level design, **not numbered**.
 - Cross-module architecture and research material may live in module-external directories.
+- The PDR tree holds no current-state or progress material: no `04-current.md`, no 当前进展 section. Current state is a **peer tree** (`current.md`).
-## Goal / current & gap→issues
+## Target & gap→issues
-- **The spec is the goal.** `NN/01-spec.md` is the target state; there are no separate goal files — the details of the end state live in the module specs, not in root docs.
-- **Root README carries two sections.** `docs/pdr/00-README.md` gains 「最终目标」(one-paragraph end state; details live in the module specs) and 「当前进展」(one line of status per module, each pointing to that module's `04-current.md`).
-- **Per-module `04-current.md`** is a current-state snapshot measured against the spec: dated, ≤1 page, conclusions and gaps only (never a log). Updated by the agent at issue completion, as part of the wrap-up review (see `workflow.md`).
-- **Scope & adoption.** Applies to numbered modules. Existing projects adopt it lazily — per module, when that module is next touched; init reports the diff and never overwrites.
-- **Gap → issue.** At the Plan step the agent reads goal (spec) plus current, derives gap candidates (module / FR, suggested type, slice, acceptance criteria), and the user picks. Accepted candidates land as entries in `docs/issues/` whose 关联 records the module / FR. No idle auto-creation of issues.
+- **The PDR is the target.** `NN/01-spec.md` holds the target state; every recorded requirement — coarse or fine — is a confirmed constraint, not an unknown/unconfirmed classification. There are no separate goal files; the end-state details live in the module specs.
+- **Root README is overview/navigation.** It carries the end-state overview, module index, and reading order, and links the peer Current tree; it holds no progress section.
+- **Changes route by kind.** A goal change updates the PDR only after alignment; a decision with rationale and trade-offs routes to an ADR (see `adr.md`). Implementation inside an aligned scope proceeds autonomously, respecting ADRs, contracts, and security; high-cost, destructive, or hard-to-reverse decisions are confirmed with the user first. Implemented details do not flow back into the PDR automatically.
+- **Gap → issue.** At the Plan step the agent reads the PDR target plus Current state (`current.md`), derives **candidate** tasks (module / FR, suggested type, slice, acceptance criteria), and the user picks. Differences are candidates only — a difference may be drift, a quality gap, unverified behavior, or an outdated target, not necessarily a missing feature. An already-met coarse goal can still be refined; do not invent gaps. Accepted candidates land in `docs/issues/` whose 关联 records the module / FR. No idle auto-creation of issues.
 ## PDR ↔ ADR boundary
 - PDR = what the product should be (target state).
-- ADR = decisions with rationale and trade-offs.
+- ADR = decisions with rationale and trade-offs. The PDR may point at one with a **descriptive phrase + a stable path link** (e.g. `支持[离线使用](../../adr/0003-offline.md)`); the description is written independently and the ADR's rationale is **not** transcluded or summarized. No requirement must carry an ADR, and the profile never infers ADR links automatically (see `rendering.md`).
 - A suggestion's acceptance routes into an ADR or the PDR (see `issues.md`).
+## PDR ↔ Current boundary
+- Two independent, user-readable trees: `docs/pdr/` (target) and `docs/current/` (as-built). Neither embeds the other.
+- Modules may align by name, but there is no file/paragraph mirroring; link module / FR references explicitly, many-to-many. **Semantic / navigation / contract links** between the trees are expected — use ordinary relative Markdown links. See `current.md`.
+- PDR and Current are both in the default render scope, together with the complete ADR set; see `rendering.md`.
 ## Example (DA_AGENT) — not part of the general rules
 DA_AGENT is a concrete instance of this pattern: modules ui / agent / cpp-core / FPGA, plus architect and research as module-external areas; each module uses the spec layer `00-README / 01-spec / 02-interfaces / 03-nfr` with an unnumbered `design/` sub-area; FR prefixes read `FR-AGENT-NN`, `FR-UI-NN`, …; product scenarios sit in a separate `07-scenarios.md`. Source: DA_AGENT ADR-0026.

package/skills/project-docs-workflow/references/rendering.md ADDED Viewed

@@ -0,0 +1,29 @@
+# Docs HTML rendering (docs-html-view)
+Default profile; projects may override in their materialized copies.
+Rendering is an **optional, user-triggered** capability provided outside this profile by the first-party `docs-html-view` skill. This profile only fixes the **doc contract** rendering relies on: what is rendered, how links are written, and that sources are never rewritten. It never installs, builds, renders, or activates anything, and init creates no renderer artifact.
+## Default render scope
+- **In scope**: `docs/pdr/`, `docs/current/`, and the **complete** `docs/adr/` — retired entries and tombstone stubs included, with their retirement markers (`> 已废弃…` / `> 已删除…`) kept visible, so retired decisions stay navigable.
+- **Out of scope**: `docs/issues/`, `docs/agents/` — working material, not published docs.
+- A project may override the scope.
+## Sources are never rewritten
+- The Markdown sources stay the single source of truth and remain human-readable on their own; the renderer is **read-only** toward them — no normalization, no move, no rewrite.
+- Out-of-scope or dangling references are **reported**, never fixed in the source.
+- "Nothing to render" is a **failure**, not a silent success; the renderer never bootstraps the docs workflow on its own.
+## Link authoring
+- **PDR ↔ Current**: semantic / navigation / contract links between the two trees are expected (`pdr.md`, `current.md`). Write ordinary relative Markdown links so both the source and the render navigate.
+- **PDR / Current → ADR**: a **descriptive phrase + a stable path link** to the ADR file, e.g. `支持 [离线使用](../../adr/0003-offline.md)`. The description is written independently and stands on its own; the ADR's rationale is **not** transcluded or summarized. No requirement must carry an ADR, and the profile never infers ADR links automatically.
+- The native `ADR-XXXX` citation notation is unchanged; ADR deletion / semantic edit sweeps **both** notations (`adr.md`).
+## Manual, opt-in
+- Rendering is **user-triggered and manual**: no hook, no auto-build on doc edits, no change to the main init artifacts to create a renderer.
+- Install / init / first build only after explicit user consent obtained through the skill interaction; there is no custom orchestrator, manifest, or approval state machine.
+- To integrate, point the project at the `docs-html-view` skill explicitly; do not wire it into initialization.

package/skills/project-docs-workflow/references/workflow.md CHANGED Viewed

@@ -15,7 +15,8 @@ The default shape for developing a single issue: align, build a thin slice, fill
 - **Align before building**: implementation starts only after the alignment is done and the plan / steps are written (align → plan & steps → build).
 - Alignment is **conversational and soft**: no freeze, no ceremonial "aligned" record. Re-align proactively when needs change (feature-requirement drift).
 - On an ambiguous direction, invoke `grilling`（未安装则按 `references/deps/grilling.md` 执行）; `grill-me` is only an entry alias; `grill-with-docs` = `grilling` + `domain-modeling`（兜底 `references/deps/grilling.md` + `references/deps/domain-modeling.md`）.
-- **Gap analysis** happens here, at Plan: read the goal (spec) plus current state, derive gap candidates (module / FR, suggested type, slice, acceptance criteria), and let the user pick. No idle auto-creation of issues.
+- **Gap analysis** happens here, at Plan: read the PDR target plus Current state, derive **candidate** tasks (module / FR, suggested type, slice, acceptance criteria), and let the user pick. Differences are candidates only — a difference may be drift, a quality gap, unverified behavior, or an outdated target, not necessarily a missing feature; do not invent gaps. No idle auto-creation of issues.
+- **Autonomy within scope**: once aligned, the agent implements autonomously inside the agreed scope, respecting ADRs, contracts, and security; high-cost, destructive, or hard-to-reverse decisions are confirmed with the user first.
 ## The five steps
@@ -23,18 +24,18 @@ The default shape for developing a single issue: align, build a thin slice, fill
 2. **骨架 / Skeleton** — a minimal runnable vertical slice (ignore output / formatting polish); leave one piece of run evidence and show it to the user — the first review point. Skippable for pure fixes (Log the reason); mandatory for features and structural work.
 3. **细节 / Details** — main-path implementation, detail completion, code quality. `tdd`（未安装则按 `references/deps/tdd.md` 执行）is an optional internal loop.
 4. **异常 / Exceptions** — failure paths, boundaries, and stability after the main path. Real development blockers are handled immediately and Logged, never queued for this step.
-5. **回顾 / Wrap-up review** (收尾回顾) — a lightweight docs-sync checklist at issue completion (pdr/current, adr, context, issues, agents); if nothing needs updating, one Log line. Doc sync only; session / agent retrospectives belong to `retro`（未安装则按 `references/deps/boundaries.md` 执行）.
+5. **回顾 / Wrap-up review** (收尾回顾) — a lightweight docs-sync checklist at issue completion (pdr, current, adr, context, issues, agents); if nothing needs updating, one Log line. Doc sync only; session / agent retrospectives belong to `retro`（未安装则按 `references/deps/boundaries.md` 执行）.
 ## Progress & resume
-- The issue entry carries a `## 步骤` checklist (the five steps); update it **in place**. Every step change appends a Log line.
+- The issue entry carries a `## 步骤` checklist (the five steps); update it **in place**. The Log records only key events (scope change, blocker, handoff, abandonment), not every step change.
 - **Sessions are soft.** A session is the user's attention window; the user controls pace (they may new / compact between issues). The agent must not absorb work beyond the aligned scope.
 - **On resume**, read the issue's 步骤 plus Log first, then confirm the continuation point with the user.
 ## Docs sync hooks
 - **Plan**: gap → issue candidates land in `docs/issues`; the entry's 关联 records the module / FR.
-- **Wrap-up review**: update the module's `04-current.md` as part of completing the issue (see `pdr.md`); touch `adr` / `context` / `issues` / `agents` when the change warrants it.
+- **Wrap-up review**: check the change's effect on the Current tree (see `current.md`). If the completed change is part of the described state, update the affected Current docs **in place — facts only, never a self-link to the issue or task history**; otherwise leave them and record a pending sync item in the issue. Baseline advancement refreshes the relevant Current docs; actual state unchanged → no edit. Touch `adr` / `context` / `issues` / `agents` when the change warrants it.
 - **Archival**: archive the issue per `issues.md` when done / dropped.
 ## Boundaries
@@ -42,4 +43,4 @@ The default shape for developing a single issue: align, build a thin slice, fill
 - Large or high-risk multi-phase work → `deepwork`（未安装则按 `references/deps/boundaries.md` 执行）; never stack it with this flow.
 - `tdd`（未安装则按 `references/deps/tdd.md` 执行）nests inside Details; seam confirmation folds into the Plan alignment (no second gate).
 - `retro`（未安装则按 `references/deps/boundaries.md` 执行）owns session / agent retrospectives; the fifth step is docs sync only.
-- See `coexistence.md` for how this profile sits beside these skills.
+- Docs HTML rendering is optional and manual (`rendering.md`); it never runs as part of this flow — no auto-build on doc edits. See `coexistence.md` for how this profile sits beside these skills.

package/skills/project-docs-workflow/assets/templates/entries/pdr-current.md DELETED Viewed

@@ -1,19 +0,0 @@
-<!-- 文件名：04-current.md，位于模块根；现状快照（对照 01-spec.md 目标），收尾回顾时更新；≤1 页，只记结论与差距，不写流水账。 -->
-# <模块> 现状（Current）
-> 更新：YYYY-MM-DD ｜ 对照：01-spec.md
-## 进展概览
-- 已实现：<FR 或功能块，只记结论>
-- 部分实现：<…>
-- 未实现：<…>
-## 与目标的差距
-- <差距要点（对应 FR-<模块>-NN）>
-## 关键结论与已知问题
-- <结论 / 遗留；指向相关 issue / ADR>