@tanlinfeng/project-docs-workflow 2.2.0 → 3.0.0

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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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/coexistence.md

@@ -8,31 +8,33 @@ Single-context layouts. Multi-context (`CONTEXT-MAP.md`) is not covered by this
 
 Active model-sharpening conversations. The base CONTEXT and ADR formats are compatible. Where both apply, **this profile's materialized rules govern project docs** — it is a superset of the base formats (ADR lifecycle v2 (in-place edit + Log, delete→tombstone stub, reference sweep, catalog-style README); issue routing). Do not fork or redefine the base formats beyond this house variant.
 
-Bundled lite version ships with the package; fallback doc `references/deps/domain-modeling.md`.
+Standalone skill optional; internal fallback `references/deps/domain-modeling.md`.
+
+> The package ships **no** standalone dependency skills: each referenced capability resolves by installed-skill name, otherwise by the internal fallback reference in `references/deps/`. Standalone names below may remain as optional upstream names.
 
 ## `grill-with-docs`
 
-A wrapper: `grilling` + `domain-modeling`. Unaffected. `grill-me` is only an entry alias of `grilling`.
+A wrapper: `grilling` + `domain-modeling`, **interleaved** — as each grilling round surfaces terms or decisions, they are written down immediately: a settled term goes into `CONTEXT.md`; a decision meeting the three ADR criteria (hard to reverse / surprising without context / real trade-off) is recorded as an ADR. `grill-me` is only an entry alias of `grilling` and has no separate flow.
 
-Bundled lite `grilling` ships with the package; fallback doc `references/deps/grilling.md` (and `references/deps/domain-modeling.md`).
+Standalone skills are optional; internal fallbacks `references/deps/grilling.md` + `references/deps/domain-modeling.md`.
 
 ## `deepwork`
 
 Large or high-risk multi-phase efforts run under `deepwork`. This profile's `workflow.md` is for routine single-issue development; the two are never stacked — pick one per effort.
 
-Bundled lite version ships with the package; fallback doc `references/deps/boundaries.md`.
+Standalone skill optional; internal fallback `references/deps/boundaries.md`.
 
 ## `tdd`
 
 Nests inside the Details step of `workflow.md` (red → green loop). Seam confirmation is folded into the Plan alignment — no second gate.
 
-Bundled lite version ships with the package; fallback doc `references/deps/tdd.md`.
+Standalone skill optional; internal fallback `references/deps/tdd.md`.
 
 ## `retro`
 
 The workflow's fifth step 收尾回顾 is documentation sync only. Session / agent retrospectives belong to `retro`, not here.
 
-Bundled lite version ships with the package; fallback doc `references/deps/boundaries.md`.
+Standalone skill optional; internal fallback `references/deps/boundaries.md`.
 
 ## `doc-opt`
 

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

@@ -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/deps/boundaries.md

@@ -1,5 +1,7 @@
 # 回退：边界类 skill（deepwork / retro / improve-codebase-architecture）
 
+> 内部回退（精简版），裁剪 / 改编自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 deepwork / retro / improve-codebase-architecture（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装对应完整 skill，请优先使用完整版。
+
 > 当某个边界类 skill 被引用但环境未安装时，按对应小节执行。
 
 ## deepwork
@@ -16,11 +18,11 @@
 
 1. **发生了什么**：读指定会话的原始记录（未指定则默认当前会话）。
 2. **保留什么**：哪些做法或环境配置有效。
-3. **改变什么**：给出针对 agent 环境的改进候选，按严重程度排序。
+3. **改变什么**：给出针对 agent **环境**的改进候选（导航指针、自动化检查、编码规范、全局指令瘦身、工具经济性、多余指令、信息可达性），按严重程度排序呈现给用户。
 
 ## improve-codebase-architecture
 
-代码库架构改进的路线（找出「深化模块」的机会，把浅模块变深，提升可测试性与 AI 可导航性），建立在领域模型与架构词汇之上。
+代码库架构改进的路线（找出「深化模块」的机会，把浅模块变深，提升可测试性与 AI 可导航性），建立在领域模型与共享架构词汇（module / interface / depth / seam / adapter / leverage / locality）之上。
 
 **无完整流程时**：本技能包不提供扫描与 HTML 报告流程；需要术语或 ADR 支持时，**转 `domain-modeling`**（未安装则见同目录 `domain-modeling.md`）。
 

package/skills/project-docs-workflow/references/deps/domain-modeling.md

@@ -2,7 +2,7 @@
 
 > 当需要调用 `domain-modeling` 但环境未安装该 skill 时，按本文执行。
 
-> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 domain-modeling（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+> 内部回退（精简版），裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 domain-modeling（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
 
 主动构建并打磨项目的领域模型：挑战术语、构造边界场景、在术语与决策成型时立刻写下。**修改**模型才算本流程；只是为查词而读 `CONTEXT.md` 不算。
 

package/skills/project-docs-workflow/references/deps/grilling.md

@@ -2,7 +2,9 @@
 
 > 当需要调用 `grilling` 但环境未安装该 skill 时，按本文执行。
 
-> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 grilling（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+> 内部回退（精简版），裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 grilling（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+> `grill-me` 只是本流程的入口别名，本身不含独立流程；`grill-with-docs` = 本流程 + `domain-modeling`（见同目录 `domain-modeling.md`），两者交织进行。
 
 持续追问用户，直到对方案达成共同理解。把它建模成一棵**设计树**：每个决策分叉出依赖它的子决策。用**轮次**遍历这棵树。
 

package/skills/project-docs-workflow/references/deps/tdd.md

@@ -2,7 +2,7 @@
 
 > 当需要调用 `tdd` 但环境未安装该 skill 时，按本文执行。
 
-> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 tdd（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+> 内部回退（精简版），裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 tdd（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
 
 以测试先行的方式构建功能或修 bug：red → green 循环。
 
@@ -12,7 +12,7 @@
 2. **红**：写一个失败的测试。测试通过公共接口验证行为，读起来像规格（描述 WHAT 而非 HOW），每个测试一个逻辑断言。不要 mock 内部协作者，不要走旁路（绕过接口查数据库）。
 3. **绿**：只写刚好让这个测试通过的实现。不加预判未来测试的投机功能。
 4. **重复**：以**纵向切片**推进——一个测试 → 一个实现 → 重复，每个测试是回应上一轮所学的一发**曳光弹**。不要「先写完所有测试再写所有实现」。
-5. **重构**不属于 red → green 循环；它属于评审阶段。
+5. **重构**不属于 red → green 循环；它属于评审阶段（代码评审；若环境有 `code-review` 则按其执行）。
 
 探索代码库时读 `CONTEXT.md`（若存在），让测试名匹配领域语言，并遵守相关 ADR。
 

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

@@ -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

@@ -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

@@ -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

@@ -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/deepwork/SKILL.md

@@ -1,15 +0,0 @@
----
-name: deepwork
-description: 高成本、多阶段、高风险深度工作会议的边界占位；与五步流程互斥，需要完整工作流时请另行安装。
-disable-model-invocation: true
----
-
-# Deepwork（边界占位）
-
-本 skill 只界定边界，不含完整流程；需要完整的 deepwork 工作流时请单独安装。
-
-- **适用**：成本高、风险大、需跨多个阶段推进的整块工作。
-- **互斥**：与 `project-docs-workflow` 的五步流程（规划 / 骨架 / 细节 / 异常 / 回顾）互斥——同一个 effort 只能选一个，绝不叠加。
-- **无完整 deepwork 时**：退回一个最小的分阶段计划，每个阶段设评审闸门：计划 → 实现 → 评审，逐阶段推进。
-
-术语或 ADR 需求交给 `domain-modeling`。

package/skills/domain-modeling/SKILL.md

@@ -1,83 +0,0 @@
----
-name: domain-modeling
-description: 构建并打磨项目的领域模型与术语。当讨论代码库术语、编写或修改 CONTEXT.md、或记录/编辑 ADR 时使用。
----
-
-# Domain Modeling（领域建模）
-
-> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 domain-modeling（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
-
-在设计的同时**主动**构建并打磨项目的领域模型。这是主动的纪律：质疑术语、构造边界场景、在术语和决策成型的那一刻就把它们写下来。（只是为查词而读 `CONTEXT.md` 不算本 skill——那是任何 skill 都能做的一行习惯；本 skill 用于**修改**模型，而不只是消费它。）
-
-## 文件结构
-
-多数仓库只有一个上下文：
-
-```
-/
-├── CONTEXT.md
-├── docs/
-│   └── adr/
-│       ├── 0001-event-sourced-orders.md
-│       └── 0002-postgres-for-write-model.md
-└── src/
-```
-
-若根目录存在 `CONTEXT-MAP.md`，说明仓库有多个上下文，由它指向每个上下文的位置。
-
-**惰性创建**：只在有内容可写时才建文件。没有 `CONTEXT.md`，就在第一个术语确定时创建；没有 `docs/adr/`，就在需要第一条 ADR 时创建。
-
-## 会话中的动作
-
-- **对照词汇表质疑**：用户用词与 `CONTEXT.md` 冲突时立刻指出。「你的词汇表把 cancellation 定义为 X，但你说的似乎是 Y，到底是哪个？」
-- **锐化模糊表达**：用户用含糊或一词多义的词时，提出精确的规范术语。「你说的 account 是指 Customer 还是 User？这是两回事。」
-- **讨论具体场景**：讨论领域关系时用具体场景压力测试，逼用户把概念边界说清楚。
-- **与代码交叉验证**：用户描述某处如何工作时，核对代码是否一致；矛盾要当面提出。「你的代码取消整个 Order，但你刚说可以部分取消，哪个对？」
-- **立即更新 CONTEXT.md**：术语一确定就当场写入，不要攒批。
-
-`CONTEXT.md` 必须完全不含实现细节：它是词汇表，不是 spec、草稿本或实现决策仓库。
-
-## CONTEXT.md 格式
-
-```md
-# {上下文名称}
-
-{一两句话说明这是什么上下文、为什么存在。}
-
-## Language
-
-**Order**：
-{一或两句话的术语描述}
-_Avoid_: Purchase, transaction
-```
-
-规则：
-
-- **有主见**：同一概念有多个词时，选最好的一个，其余列入 `_Avoid_`。
-- **定义紧致**：最多一两句，定义它**是什么**，不是**做什么**。
-- **只收本项目特有概念**：通用编程概念（超时、错误类型、工具模式）不进，哪怕项目大量使用它们。
-- **自然成簇时可分子标题**；单一内聚领域用平铺列表即可。
-
-## ADR
-
-ADRs 放在 `docs/adr/`，顺序编号：`0001-slug.md`、`0002-slug.md`。编号时扫描现有文件取最大号加一。
-
-**模板极简**（一条 ADR 可以只有一段）：
-
-```md
-# {决策的简短标题}
-
-{1-3 句：背景是什么、决定了什么、为什么。}
-```
-
-价值在于记录**做过这个决策**及其**原因**，而非填满小节。可选小节仅在确有价值时加：`Status` frontmatter（`proposed | accepted | deprecated | superseded by ADR-NNNN`）、Considered Options、Consequences。
-
-**仅当以下三条同时成立才提议写 ADR**：
-
-1. **难以逆转**：以后改主意的代价可观。
-2. **无背景会令人意外**：未来的读者会想「当初为什么这么做？」
-3. **是真实取舍的结果**：确有替代方案，且有特定理由选中这一个。
-
-缺任何一条就跳过——容易反悔的将来直接反悔即可；不意外的没人会问；没有替代方案的记下来也只是「我们做了显而易见的事」。
-
-典型合格情形：架构形态；上下文间的集成模式；带锁定的技术选型（数据库、消息总线、认证、部署目标）；边界与范围决策（显式的「不做」同样有价值）；刻意偏离常规路径的做法；代码里看不见的约束；拒绝理由非显然的替代方案。

package/skills/domain-modeling/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Domain Modeling"
-  short_description: "Build and sharpen a domain model"

package/skills/grill-me/SKILL.md

@@ -1,13 +0,0 @@
----
-name: grill-me
-description: 追问式访谈（grilling）的入口别名，用于把计划或设计压到没有含糊之处。
-disable-model-invocation: true
----
-
-# Grill Me
-
-> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 grill-me（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
-
-`grill-me` 只是 `grilling` 的入口别名，本身不含流程。
-
-请改调用 `grilling` skill；若环境未安装，按 `project-docs-workflow/references/deps/grilling.md` 执行。

package/skills/grill-with-docs/SKILL.md

@@ -1,18 +0,0 @@
----
-name: grill-with-docs
-description: 追问式访谈的同时产出文档（ADR 与术语表）。
-disable-model-invocation: true
----
-
-# Grill with Docs
-
-> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 grill-with-docs（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
-
-`grill-with-docs` 是一个包装器：把 `grilling` 与 `domain-modeling` 一起跑。
-
-- 用 `grilling` 推进设计树、逐轮追问，直到达成共同理解。
-- 同时用 `domain-modeling`：术语确定时当场写入 `CONTEXT.md`；决策满足「难以逆转 / 无背景会意外 / 真实取舍」三条时记录 ADR。
-
-两个流程交织进行：每轮追问中浮现的术语与决策，立刻落成文档。
-
-若环境未安装，按 `project-docs-workflow/references/deps/grilling.md` 与 `project-docs-workflow/references/deps/domain-modeling.md` 执行。