@llman-sdd/core 0.3.1 → 0.5.1

package/templates/zh-Hans/skills/llman-sdd-quick.md

@@ -1,56 +1,41 @@
 ---
 name: "llman-sdd-quick"
-description: "快速路径：处理不改行为合约的小改动——重构、修错字、性能优化。不涉及 MUST/SHALL 变更。如发现需要改合约，立即切换到 propose 完整路径。"
+description: "快速路径：不改行为合约的小改动（重构/错字/性能）。要改 MUST/SHALL 就停，转 propose。"
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Quick Path
 
-对于不涉及行为合约变更的小改动使用此路径。
+不改行为合约的小改动用此路径。
 
 ## Pipeline 位置
 
 ```mermaid
 flowchart LR
-    explore["llman-sdd-explore<br/>探索"] --> quick
-
-    quick["★ llman-sdd-quick ★<br/>快速路径（你现在在这里）"]
-    quick --> commit["git commit<br/>完成"]
-
-    explore --> propose["完整路径:<br/>propose（含 Branch binding 与 Specs landing）→ apply → verify → archive"]
-    propose --> apply["..."]
-    apply --> verify["..."]
-    verify --> archive["..."]
+    quick["★ llman-sdd-quick"] --> commit["git commit"]
+    explore["llman-sdd-explore"] --> propose["完整路径：propose → apply → verify → archive"]
 
     style quick fill:#d4edda,stroke:#28a745,stroke-width:3px
 ```
 
-> 📍 快速路径：不改行为合约，直接改代码 commit。如果发现需要改合约 → STOP，改走完整路径 `llman-sdd-propose`
-> 🗺️ 完整路径含 Git-native Branch binding + Specs landing（不是把 Specs landing 当成独立 skill）
+> 📍 快速路径：直接改代码 commit。发现要改合约 → STOP，转 `llman-sdd-propose`。
 
-## 使用条件（所有条件必须满足）
+## 使用条件（全部满足）
 - 不改变任何 spec 中 MUST/SHALL 定义的外部可观测行为
-- 不涉及跨 capability 的修改
-- 不涉及迁移/兼容性
-- 不是 SDD 元规范变更
+- 不跨 capability；不涉及迁移/兼容性；不是 SDD 元规范变更
 
 ## 步骤
-1. 用 `llman-sdd context --task "..." --paths "..."` 确认无相关 spec 变更需要。
-   - 如果 context 返回 `quality: "unavailable"`，运行 `llman-sdd index rebuild`（默认 `pageindex`，无需模型）。
-   - 可以用 `llman-sdd list --specs --json` 查看 specs 元数据。
-2. 直接修改代码。
-3. 若要动 `llmanspec/specs/**`，STOP——除非已在绑定的非默认 change 分支上（迷你 change：`change start`/`attach` → 编辑 → commit）。禁止在默认分支 commit live specs，即使是 typo 或仅收紧 scope 也不行。优先把 live specs 维护路由到 `llman-sdd-propose`，或要求已有绑定分支。
-4. git commit（message 写明 why）。
-5. 无需 change 目录，无需 archive。
+1. 用 `llman-sdd context --task "..." --paths "..."` 确认无相关 spec 变更。
+   - context 返回 `quality: "unavailable"` → 先 `llman-sdd index check`：stale/缺失则 `llman-sdd index rebuild`（默认 pageindex，免模型）后重试；fresh 仍不可用（`LLMAN_SDD_INDEX_CHAT_MODEL` 未设）→ 改用 `llman-sdd list --specs` + 直读 `.feature`——勿循环 rebuild。
+2. 直接改代码。
+3. 若要动 `llmanspec/specs/**`，STOP——除非已在绑定的非默认 change 分支上（迷你 change：`change start`/`attach` → 编辑 → commit）。禁止在默认分支 commit specs，即使 typo 或仅收紧 scope 也不行。优先把 specs 维护路由到 `llman-sdd-propose`。
+4. git commit（message 写明 why）。无需 change 目录，无需 archive。
 
 ## 边界处理
-- 如果在修改中发现需要改变行为合约 → STOP，改走 `llman-sdd-propose`（完整路径）。
-- 如果涉及到多个文件且不确定 scope → 先用 `llman-sdd context` 确认。
-
-> 💡 快速路径完成 → git commit 即可。若需要走完整路径 → `llman-sdd-propose` → `llman-sdd-apply` → `llman-sdd-verify` → `llman-sdd-archive`
+- 修改中发现要改行为合约 → STOP，转 `llman-sdd-propose`。
+- 涉及多文件且 scope 不明 → 先用 `llman-sdd context` 确认。
 
-> 命令细节用 `llman-sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
-> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman-sdd list --specs` / `llman-sdd show <capability>` 查全文。
+{{ unit("skills/cli-footer") }}
 
 {{ unit("skills/ethics-governance") }}

package/templates/zh-Hans/skills/llman-sdd-research.md

@@ -1,46 +1,35 @@
 ---
 name: "llman-sdd-research"
-description: "以后台 agent 委托外部文献调研。当用户需要针对某个问题查阅官方文档/API/源码等一手资料、或想把阅读文献的活委托给后台 agent 时使用。"
+description: "委托后台 agent 查一手资料（官方文档/API/源码），产出带引用的调研文档。"
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Research
 
-启动一个**后台 agent** 做文献调研，这样你可以继续手头工作而它在读。
+启动**后台 agent** 做调研，你继续手头工作。辅助工具，任意阶段可用（常见于 explore/wayfinder）；产出回写 change 的 proposal「Further Notes」段。
 
-## Pipeline 位置
+## 后台 agent 的职责
 
-辅助工具，任意阶段可用。常见于 explore/wayfinder 阶段，为决策提供事实输入。产出回写 change 的 proposal「Further Notes」段，供后续阶段引用。
-
-> 📍 这是独立可选 skill；调研产出供主流程的 explore/propose 消费。
-
-## 职责
-
-后台 agent 的工作：
-
-1. 针对**一手资料**调研问题——官方文档、源码、spec、第一方 API——而非对它们的二手转述。把每个论断追溯到拥有它的源头。
-2. 把发现写入单个 Markdown 文件，为每个论断标注来源引用。
-3. 存放位置（仓库另有约定时优先遵循）：**默认** `llmanspec/changes/<current-change>/research/<topic>.md`（Change 文档，**不是** live specs）。仅当主题跨多个 change、归档后仍常引用时才写 `docs/research/`；**禁止**把单 change 选型/易腐深挖塞进 `docs/research/`。
-4. **禁止**本 skill 直接编辑 `llmanspec/specs/**`。若调研表明必须改 MUST/SHALL → 建议 `llman-sdd-propose`（Branch binding → Specs landing）。
+1. 针对**一手资料**调研——官方文档、源码、spec、第一方 API，而非二手转述；每个论断追溯到拥有它的源头。
+2. 发现写入单个 Markdown 文件，每条论断标注来源。
+3. 存放（仓库另有约定时优先）：**默认** `llmanspec/changes/<current-change>/research/<topic>.md`（change 文档，**不是** specs）。仅当主题跨多个 change、归档后仍常引用时才写 `docs/research/`；**禁止**把单 change 选型/易腐深挖塞进 `docs/research/`。
+4. **禁止**本 skill 直接编辑 `llmanspec/specs/**`。调研表明必须改 MUST/SHALL → 建议 `llman-sdd-propose`（绑定分支 → 落地 specs）。
 
 ## 步骤
 
-1. 明确要调研的问题（与用户确认；模糊时收窄到一个能被证实/证伪的问题）。
-2. 用 Agent 工具 `subagent_type=general-purpose` + `run_in_background: true` 启动后台调研，prompt 含：
-   - 问题陈述。
-   - 要求只引一手资料，每条论断标注来源 URL/路径。
-   - 输出文件路径（默认 `llmanspec/changes/<id>/research/<topic>.md`）。
-   - 字数上限（建议：聚焦事实，散文式叙述 < 1500 词）。
-3. 后台运行期间继续主流程工作；完成后收到通知。
-4. 读取产出，把关键结论摘要回写到当前 change 的 `proposal.md`「Further Notes」段（附文件指针）。
-5. 若调研揭示需要决策，建议进入 `llman-sdd-explore` 的逐问深挖分支。
+1. 明确调研问题（与用户确认；模糊时收窄到能被证实/证伪）。
+2. 用 Agent 工具 `subagent_type=general-purpose` + `run_in_background: true` 启动，prompt 含：
+   - 问题陈述；只引一手资料、每条论断标来源 URL/路径的要求；
+   - 输出文件路径（默认 `llmanspec/changes/<id>/research/<topic>.md`）；
+   - 字数上限（建议：聚焦事实，散文叙述 < 1500 词）。
+3. 后台运行期间继续主流程；完成后读产出，把关键结论摘要回写当前 change 的 `proposal.md`「Further Notes」段（附文件指针）。
+4. 若调研揭示需要决策，建议进入 `llman-sdd-explore` 的逐问深挖分支。
 
-## 与 wayfinder 的协作
+## 与 wayfinder 协作
 
-`llman-sdd-wayfinder` 的查资料 ticket 委托本 skill 后台解决；解决后回写 ticket proposal 并在 map 的 Decisions-so-far 记一行要点。
+`llman-sdd-wayfinder` 的查资料 ticket 委托本 skill 后台解决；解决后回写 ticket proposal，并在地图的 Decisions-so-far 记一行要点。
 
-> 命令细节用 `llman-sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
-> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman-sdd list --specs` / `llman-sdd show <capability>` 查全文。
+{{ unit("skills/cli-footer") }}
 
 {{ unit("skills/structured-protocol") }}

package/templates/zh-Hans/skills/llman-sdd-specs-compact.md

@@ -1,65 +1,40 @@
 ---
 name: "llman-sdd-specs-compact"
-description: "人类主动触发的维护工具。压缩去重 llman SDD specs——在归档积累较多后合并冗余 requirement/scenario，保留所有规范行为不变。不属于日常 pipeline：仅在用户明确要求压缩 specs 时才运行。"
+description: "压缩去重 specs：合并冗余 requirement/scenario，规范行为不变。仅用户明确要求时手动运行。"
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Specs Compact
 
-使用此 skill 在不改变规范行为的前提下压缩 specs。
-
-## Pipeline 位置
-
-```mermaid
-flowchart LR
-    archive["llman-sdd-archive<br/>归档完成后"] --> compact
-    compact["📎 llman-sdd-specs-compact<br/>压缩重构 specs（维护工具）"]
-
-    style compact fill:#e8f4e8,stroke:#28a745,stroke-width:2px
-```
-
-> 📎 维护工具，通常在归档积累较多后执行。日常开发 → `llman-sdd-propose`（含 Branch binding + Specs landing）/ `llman-sdd-apply`（须 `readyToImplement`）。
+在不改变规范行为的前提下压缩 specs。维护工具，不属于日常 pipeline，通常在归档积累较多后执行。
 
 ## Context
-- specs 会随着变更积累而膨胀，并出现重复 requirement/scenario。
-- 压缩必须保持可验证、可回归。
-- 当 archive 历史过大时，会干扰压缩评审与定位。
+- specs 随变更积累膨胀，出现重复 requirement/scenario；压缩必须可验证、可回归。
+- archive 历史过大时会干扰压缩评审与定位。
 
 ## Goal
-- 识别并合并冗余 requirement/scenario。
-- 形成更紧凑且可维护的规范结构。
+- 合并冗余 requirement/scenario，形成更紧凑可维护的规范结构。
 
 ## Constraints
-- 未经明确替代，不得删除规范性行为。
-- 尽量保持 requirement 标题稳定。
-- 每个保留 requirement 至少保留一个有效 scenario。
-- **编辑 live `llmanspec/specs/**` 须走 change**：先 Branch binding（`change start` / `attach`），在绑定分支上做 Specs landing 式提交；**禁止**在默认分支直接压缩改写 live specs。
+- 未经明确替代不得删除规范性行为；尽量保持 requirement 标题稳定；每个保留 requirement 至少一个有效 scenario。
+- **改 `llmanspec/specs/**` 须走 change**：先绑定分支（`change start` / `attach`），在绑定分支上编辑提交；**禁止**在默认分支直接压缩改写。
 
 ## Workflow
-1. 盘点当前 specs（`llman-sdd list --specs`）。
-2. 如果已归档历史较大，先执行 archive freeze：
-   - 预览：`llman-sdd archive freeze --dry-run`
-   - 执行：`llman-sdd archive freeze --before <YYYY-MM-DD> --keep-recent <N>`
-3. 识别跨 capability 的重叠项。
+1. 盘点 specs（`llman-sdd list --specs`）。
+2. 归档历史较大时先 freeze：预览 `llman-sdd archive freeze --dry-run`；执行 `llman-sdd archive freeze --before <YYYY-MM-DD> --keep-recent <N>`。
+3. 识别跨 capability 重叠（跨 specs 重复 req id：`llman-sdd project dedupe-req-ids --dry-run` 报告重映射计划）。
 4. 产出压缩计划（canonical requirements + keep/merge/remove 决策 + 迁移说明）。
-5. 执行并验证（`llman-sdd validate --specs --strict --no-interactive`）。
+5. 执行并验证（`llman-sdd validate --specs --strict`）。
 
 ## Decision Policy
-- 两条 requirement 语义等价时优先合并。
-- 仅在引用关系清晰时提取共享规范文本。
-- archive 目录噪声较大时，优先建议先 freeze 再压缩。
-- 若压缩会改变外部行为，必须先暂停并询问用户。
+- 语义等价优先合并；仅引用关系清晰时提取共享文本；archive 噪声大时先 freeze 再压缩。
+- 若压缩会改变外部行为，先暂停并询问用户。
 
 ## Output Contract
-- 输出按 capability 分组的压缩方案。
-- 包含：keep/merge/remove 决策及理由。
-- 包含验证命令与预期结果。
-
-> 💡 维护完成后，新需求走正常 pipeline：`llman-sdd-propose`（含 Branch binding + Specs landing）→ `llman-sdd-apply`（须 `readyToImplement`）→ `llman-sdd-verify` → `llman-sdd-archive`。
+- 按 capability 分组的压缩方案：keep/merge/remove 决策及理由 + 验证命令与预期结果。
 
-> 命令细节用 `llman-sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
-> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman-sdd list --specs` / `llman-sdd show <capability>` 查全文。
+{{ unit("skills/cli-footer") }}
 
 {{ unit("skills/validation-hints") }}
 

package/templates/zh-Hans/skills/llman-sdd-validate.md

@@ -1,31 +1,27 @@
 ---
 name: "llman-sdd-validate"
-description: "校验 llmanspec 变更与 specs 并提供修复提示。"
+description: "校验 change 与 specs，给出修复提示。"
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD 校验
 
-使用此 skill 校验变更/spec 格式与过期状态。
+校验 change/spec 格式与过期状态。
 
 ## 步骤
-1. 校验单个条目：`llman-sdd validate <id>`。
-2. 批量校验：`llman-sdd validate --all`（或 `--changes` / `--specs`）。
-3. 在 CI 或自动化场景中使用 `--strict` 与 `--no-interactive`。
-4. 若校验失败，汇总错误并给出最小、可执行的修复建议。
+1. 单个：`llman-sdd validate <id>`；批量：`llman-sdd validate --all`（或 `--changes` / `--specs`）；CI/自动化用 `--strict`。
+2. 校验失败时汇总错误，给出最小可执行的修复建议。
 {% if bdd_enabled %}
-5. **BDD 校验（Git-native Partitioned SSOT）**：
-   - 在**绑定分支**上验证 live `.feature` Gherkin 与 `@req` / 双写门禁（须已 Branch binding）。
-   - `.feature` 是 harness 权威——可执行 GWT 只在 live `.feature` 维护（无 solidify；无 `feature_delta` / `change delta`）。
-   - Change 生命周期门禁：`change start` / `attach`（Branch binding）、`finalize`（收口；自动提交 `archive(sdd): <id>`，`--no-commit` 跳过）/ `diff`（只读）。`change checkpoint` 已移除（无存档点概念：中途不必存档，`change finalize` 不要求干净树）。
-   - `llman-sdd validate --specs` 默认自动运行 `bdd.run_command`。
-   - 可用 `list --specs --json` 查看 `morphology`（含 `dualWriteCount`）。
-   - Change JSON 状态字段：`stage`（draft/designed/planned/full）/ `specsLanded` / `needsSpecsChange` / `readyToImplement`（`show --json`）。
+3. **BDD 校验**：
+   - 在**绑定分支**上验证 `.feature` Gherkin 与 `@req` / 双写门禁；`.feature` 是 harness 权威——可执行 GWT 只在其中维护。
+   - 生命周期门禁：`change start` / `attach`（绑定分支）、`finalize`（收口；自动提交 `archive(sdd): <id>`，`--no-commit` 跳过）/ `diff`（只读）。
+   - `llman-sdd validate --specs` 做结构与合约门禁；配置 `bdd.run_command` 时缺省执行该 harness（`--no-check` 跳过，`--check` 为兼容别名），无占位符的命令每次调用至多执行一次。
+   - `list --specs --json` 查看 `morphology`（ruleCount / ruleEnforcedCount / rulePendingCount / acceptanceCount / featureScenarioCount）。
+   - change JSON 状态字段：`stage`（draft/designed/planned/full）/ `specsLanded` / `needsSpecsChange` / `readyToImplement`（`show --output json`）。
 {% endif %}
 
-> 命令细节用 `llman-sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
-> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman-sdd list --specs` / `llman-sdd show <capability>` 查全文。
+{{ unit("skills/cli-footer") }}
 
 {{ unit("skills/validation-hints") }}
 

package/templates/zh-Hans/skills/llman-sdd-verify.md

@@ -1,56 +1,44 @@
 ---
 name: "llman-sdd-verify"
-description: "验证已实施的 llman SDD 变更是否与 specs/design/tasks 一致。产出分级报告（CRITICAL / WARNING / SUGGESTION），对比代码与工件。在 apply 完成后运行；全绿则可归档。"
+description: "验证已实施 change 与 specs/design/tasks 是否一致，产出 CRITICAL/WARNING/SUGGESTION 分级报告。apply 后运行，全绿可归档。"
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Verify
 
-使用此 skill 验证实现是否与该 change 的 artifacts 一致。
+验证实现是否与该 change 的工件一致。
 
 ## Pipeline 位置
 
-### Skill 导航（非生命周期；仅指示当前 skill）
-
 ```mermaid
 flowchart LR
-    apply["llman-sdd-apply<br/>实施"] --> verify
-    verify["★ llman-sdd-verify ★<br/>验证（你现在在这里）"]
-    verify --> archive["llman-sdd-archive<br/>归档"]
+    apply["llman-sdd-apply"] --> verify["★ llman-sdd-verify"]
+    verify --> archive["llman-sdd-archive"]
 
     style verify fill:#fff3cd,stroke:#ffc107,stroke-width:3px
 ```
 
-> 📍 你现在在验证阶段 → 通过后下一步 `llman-sdd-archive`（归档）；失败则回到 `llman-sdd-apply`（修复）。对应 Git-native 图中的 **I（verify）**，对象应已 Specs-landed（`readyToImplement=true`）。
-> 🗺️ Skill 导航 ≠ Git-native 生命周期；完整生命周期见底部 brief 单元。
+> 📍 你在验证阶段 → 通过则 `llman-sdd-archive`，失败回 `llman-sdd-apply` 修复。对象应已落地 specs 且 `readyToImplement=true`（全门绿——完成信号）。
 
 ## 硬约束
 
-- **必须先通过 apply 阶段全绿**：未完成实现的 change 跳过验证。
-- **CRITICAL 必须修复**：标记为 CRITICAL 的问题归档前必须修复。
-- **不要问「要不要继续」**：跑完整个验证流程，输出完整报告。
+- **必须先 apply 全绿**：未完成实现的 change 跳过验证。
+- **CRITICAL 必须修复**：归档前清零。
+- **亲自复跑门禁**：MUST 亲自重跑 `llman-sdd validate <id> --strict`（真实 harness）与项目门禁，MUST NOT 采信实现者报告的门禁结论；复跑结果与报告不符 → CRITICAL。
+- **`--no-check` 不是证据**：以 `--no-check` 取得的门禁证据 → CRITICAL。收口会执行已配置的 `bdd.run_command`，收口前不必再跑一遍；`--no-check` 打出的跳过说明不是通过。
+- **不要问「要不要继续」**：跑完整验证流程，输出完整报告。
 
 {{ unit("skills/stage-guard") }}
 
 ## 步骤
-1. 确定 change id（不明确时让用户从 `llman-sdd list --json` 选择）。
-2. 先跑一个快速校验门禁：
-   - `llman-sdd validate <id> --strict --no-interactive`
-   - **诊断结构问题（Gherkin 解析 / `@req` 链接 / 双写 / 全局 req_id 唯一性）时优先加 `--no-check`**（BDD-on 下跳过可能耗时的 `bdd.run_command`），结构门禁全绿后再跑完整 `--check`（full mode）。`FAIL <item_type>/<id>` 行会逐条列出失败项（在 Totals 行上方）。
-3. 阅读：
-   - feature 分支上的 live specs：`llmanspec/specs/**`（`<capability>.feature`）——SSOT
-   - `proposal.md` 与 `design.md`（如存在）
-   - `tasks.md`（理解实现范围）
-   - `llmanspec/changes/<id>/specs/` 若残留旧文档可忽略；SSOT 是 live specs
-4. **双轴审查（标准轴 + 合约轴分离，互不掩盖）**——对比 diff（`git diff <merge-base>...HEAD`，merge-base 用现算 `git merge-base <本地默认分支> HEAD`；存储的 base_sha 仅作审计、MUST NOT 参与范围计算）分两轴：
-   - **合约轴（Spec）**：实现是否满足 `@human` 规则的 MUST/SHALL 与 `@executable` 的 GWT。
-     - 缺失/部分实现的行为、错误实现、以及 diff 中未被 spec 要求的超范围改动。
-     - 给出最小修复建议，或建议更新 artifacts。
-   - **标准轴（Standards）**：代码是否符合 `AGENTS.md` 的编码规范 + 常见代码坏味（code smell）清单。
-     - **权威优先级**：`AGENTS.md` 文档规范 > 坏味清单（文档说了算）；工具已强制的项跳过。
-     - 坏味标记为**判断性提示**（「可能是 Feature Envy」），不是硬性违规。
-     - 坏味清单（每项「是什么 → 怎么修」）：
+1. 确定 change id（不明确时让用户从 `llman-sdd list --json` 选）。
+2. 快速校验门禁：`llman-sdd validate <id> --strict`。
+   - 诊断结构问题（Gherkin 解析 / `@req` 链接 / 双写 / req_id 唯一性）先跑结构校验（配置 `bdd.run_command` 时 validate 缺省执行该 harness，`--no-check` 跳过；harness 失败以 ERROR 落在对应 spec 条目）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条列出（`--output human` 输出 `FAIL <item_type>/<id>` 行，位于 `Totals` 上方）。
+3. 阅读：分支上的 `llmanspec/specs/**`（`<capability>.feature`，唯一事实来源）、`proposal.md` 与 `design.md`（如有）、`tasks.md`；`changes/<id>/specs/` 若有残留旧文档可忽略。
+4. **双轴审查（两轴分离，互不掩盖）**——对比 diff（`git diff <merge-base>...HEAD`，merge-base 现算 `git merge-base <本地默认分支> HEAD`；存储的 base_sha 仅审计、MUST NOT 参与范围计算）：
+   - **合约轴**：实现是否满足 `规则:` 块的需求表述(描述为自由文本,以其语义为准)与嵌套 `场景:` 的 GWT 步骤？缺失/部分实现、错误实现、spec 未要求的超范围改动 → 给最小修复建议或建议更新工件。前后对比类证据（计数、基线）核对测量位置：MUST 在 change 分支上测量（相对现算 merge-base）；默认分支测得的值通常恒为基线，不构成证据。
+   - **标准轴**：代码是否符合 `AGENTS.md` 规范 + 常见坏味清单。权威优先级：`AGENTS.md` > 坏味清单；工具已强制的跳过。坏味是**判断性提示**（「可能是 Feature Envy」），不是硬性违规：
 
      | 坏味 | 怎么修 |
      |------|--------|
@@ -64,32 +52,23 @@ flowchart LR
      | Divergent Change（一个文件因多个无关原因被改） | 拆分 |
      | Speculative Generality（为未发生的需求加抽象） | 删掉 |
      | Message Chains（长链 a.b().c()） | 隐入一个方法 |
-     | Middle Man（只转发） | 删掉，直连 |
+     | Middle Man（只转发） | 删掉直连 |
      | Refused Bequest（子类拒绝大部分继承） | 改组合 |
    - 两轴可并行（sub-agent）审查；报告 MUST 分离呈现，MUST NOT 合并或交叉重排（一轴通过不能掩盖另一轴失败）。
-5. **BDD-on 验证（Git-native Partitioned SSOT）**——仅当 `config.yaml` 含 `bdd:` 段时：
-   - 确认 change 已 attach，且当前在对应 feature 分支上。
-   - `llman-sdd validate --specs`：Gherkin + `@req`/双写门禁；默认跑 `bdd.run_command`（可用 `--no-check` 跳过）。
-   - 可选只读审查：`llman-sdd change diff <id>`（或 `--export-patch <path>`）。diff 仅作审查/导出——绝不当作 apply 步骤。
-   - 检查：无遗留 `spec.toon` / `*.feature.delta.toon`；若存在，先跑 toon2features（不要自创 solidify/找补步骤）。
-   - verify 通过后下一步：`llman-sdd-archive`（勿在此 inline finalize）。
+5. **BDD 验证**——仅当 `config.yaml` 含 `bdd:` 段：
+   - 确认 change 已绑定分支且当前在该分支上。
+   - `llman-sdd validate --specs`：Gherkin + `@req`/双写门禁；配置 `bdd.run_command` 时缺省执行该 harness（`--no-check` 跳过），失败映射为对应 spec 条目的 ERROR。
+   - 可选只读审查：`llman-sdd change diff <id>`（或 `--export-patch <path>`）——仅审查/导出，绝不当作 apply 步骤。
+   - verify 通过后下一步 `llman-sdd-archive`（勿在此 inline finalize）。
 {% if bdd_verify_prompt %}
    - 额外要求: {{ bdd_verify_prompt }}
 {% endif %}
-6. 输出简短报告：
-   - **CRITICAL**（归档前必须修复）
-   - **WARNING**（建议修复）
-   - **SUGGESTION**（可选优化）
-7. **人审检查点**：报告无 CRITICAL 后、建议归档前，运行 `llman-sdd review`：
-   - 退出码为零 → 建议 `llman-sdd-archive` 进行 finalize/archive。
-   - 非零退出 = CRITICAL 发现：用 `llman-sdd-apply` 修复后重跑 review；MUST NOT 带着 CRITICAL 进入 finalize/archive。
-
-> 💡 验证通过 → 下一步 `llman-sdd-archive`（归档）；有 CRITICAL → 回到 `llman-sdd-apply`（修复）
+6. 输出简短报告：**CRITICAL**（归档前必须修复）/ **WARNING**（建议修复）/ **SUGGESTION**（可选优化）。
+7. **人审关卡**：报告无 CRITICAL 后、建议归档前跑 `llman-sdd review`：退出码零 → 建议 `llman-sdd-archive`；非零 = CRITICAL → 用 `llman-sdd-apply` 修复后重跑 review；MUST NOT 带 CRITICAL 进入 finalize/archive。
 
 {{ unit("skills/git-native-flow-brief") }}
 {{ unit("skills/human-readable-summary") }}
-> 命令细节用 `llman-sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
-> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman-sdd list --specs` / `llman-sdd show <capability>` 查全文。
+{{ unit("skills/cli-footer") }}
 
 {{ unit("skills/validation-hints") }}
 

package/templates/zh-Hans/skills/llman-sdd-wayfinder.md

@@ -1,40 +1,37 @@
 ---
 name: "llman-sdd-wayfinder"
-description: "人类主动触发。把大型、一团乱的工作（超出单个 agent 会话容量）拆成一张决策地图，逐个解决决策直到路径清晰。仅手动触发，agent 禁止自动启用。"
+description: "把超出单会话的大型模糊工作拆成决策地图，逐个解决直到路径清晰。仅手动触发。"
 metadata:
   version: "{{ llman_version }}"
+disable-model-invocation: true
 ---
 
 # LLMAN SDD Wayfinder
 
-一个又大又乱的工作来了——大到单个 agent 会话装不下，还裹着一团迷雾：从现在到**目的地**的路还看不见。这个 skill 不急着动手，而是先把路找出来。
-
-它把路径画成 llman SDD 的 **change 依赖图**（`llman-sdd graph`）：每个子工作（ticket）解决一个**决策**而非交付一块代码，逐个解决直到路径清晰。
+一个又大又乱的工作来了——大到单个 agent 会话装不下，从现在到**目的地**的路还看不见。这个 skill 不急着动手，先把路找出来：把路径画成 change 依赖图（`llman-sdd graph`），每个子工作（ticket）解决一个**决策**而非交付代码，逐个解决直到路径清晰。
 
 ## Pipeline 位置
 
-辅助工具，用于主 pipeline 之前的**大型工作预规划**。地图清晰后，合并到主流程 `llman-sdd-propose`。
-
-> 📍 这是独立可选 skill；地图清晰后 → `llman-sdd-propose`（把决策收拢为可建计划）。
+辅助工具，用于主 pipeline 之前的**大型工作预规划**。地图清晰后 → `llman-sdd-propose` 收拢为可实施计划。
 
 ## 核心原则
 
-- **只规划，不动手**：每个 ticket 解决一个决策，地图完成于「路径清晰、无决策遗留」。想直接开干的冲动，通常是到了地图边界、该交接的信号。
-- **用名字指代**：在所有给人看的叙述里，用 ticket 的标题名称指代，MUST NOT 用裸 id/编号。
-- **单会话单 ticket**：每个会话只解决一个 ticket（查资料的 ticket 例外）。
+- **只规划，不动手**：每个 ticket 解决一个决策；地图完成于「路径清晰、无决策遗留」。想直接开干的冲动，通常是到了地图边界、该交接的信号。
+- **用名字指代**：给人看的叙述里用 ticket 标题指代，MUST NOT 用裸 id/编号。
+- **单会话单 ticket**（查资料 ticket 例外）。
 
 ## 地图结构
 
-地图本身是一个 change（总纲 proposal），它的子决策是 `depends_on` 的子 change。用 `llman-sdd graph <map-id> --scope active` 可视化当前**可着手项**。
+地图本身是一个 change（总纲 proposal），子决策是 `depends_on` 的子 change。用 `llman-sdd graph <map-id> --scope active` 可视化当前**可着手项**。
 
 地图的 `proposal.md` 结构：
 
 ```markdown
 ## Destination（目的地）
-<走到地图终点是什么样——spec/决策/变更。一两行。>
+<走到终点是什么样——spec/决策/变更。一两行。>
 
 ## Notes（备注）
-<领域；每会话应查的 skill；这次工作的常设偏好>
+<领域；每会话应查的 skill；常设偏好>
 
 ## Decisions so far（已定的决策）
 <!-- 索引：每个已关闭 ticket 一行，结论要点 + 链接 -->
@@ -48,40 +45,39 @@ metadata:
 
 ## Ticket 类型
 
-每个 ticket 是一个子 change，带 `wayfinder:<type>` 标注（写在 proposal 的标题或 frontmatter）：
+每个 ticket 是一个子 change，带 `wayfinder:<type>` 标注（写在 proposal 标题或 frontmatter）：
 
-- **Research（查资料，agent 自跑）**：读文档/API/本地资源，把决策在等的事实查出来。委托 `llman-sdd-research` 后台解决。
+- **Research（查资料，agent 自跑）**：读文档/API/本地资源，查出决策在等的事实。委托 `llman-sdd-research` 后台解决。
 - **Prototype（做原型，需人参与）**：用廉价粗糙的可运行物（throwaway 小程序或 UI 变体）把讨论具象化。
 - **逐问深挖（需人参与）**：用 `llman-sdd-explore` 的逐问深挖分支一问一答走清。**默认类型**。
-- **Task（杂活，需人或 agent 自跑）**：决策前必须先做的手动工作（注册服务、迁数据以看清形状）。
+- **Task（杂活，人或 agent）**：决策前必须先做的手动工作（注册服务、迁数据以看清形状）。
 
 ## 尚未清晰区
 
-地图**故意**不完整。判断一个点该不该现在就立成 ticket，只看一条：**现在能不能把问题说清楚**（不是能不能回答）。
-- 能说清楚 → 立 ticket（即使暂时被别的挡着）。
-- 还说不清楚 → 写进 **尚未清晰区**（比 ticket 粗，一团模糊可能日后变成多个 ticket，也可能一个都不变）。
+地图**故意**不完整。判断一个点该不该现在立 ticket，只看一条：**现在能不能把问题说清楚**（不是能不能回答）。
+- 能说清 → 立 ticket（即使暂时被挡）。
+- 说不清 → 写进**尚未清晰区**（一团模糊日后可能变成多个 ticket，也可能一个都不变）。
 
 ## 步骤
 
 ### 画地图
-1. **命名目的地**：用 `llman-sdd-explore` 的逐问深挖分支钉死这趟地图要通往哪里。
-2. **广度优先扫可着手项**：再次逐问深挖，扇开而非深挖一条，把开放决策和现在能迈的第一步浮出来。若**没有模糊点浮出**——路径已清晰、整个工作一个会话能装下——那就不需要地图，停下问用户想怎么做。
+1. **命名目的地**：用逐问深挖钉死这趟地图要通往哪里。
+2. **广度优先扫可着手项**：再次逐问深挖，扇开而非深挖一条，浮出开放决策与现在能迈的第一步。若**没有模糊点浮出**——路径已清晰、一个会话能装下——不需要地图，停下问用户想怎么做。
 3. **创建地图**（总纲 change）：`llman-sdd change new <map-id>`，填 Destination/Notes，Decisions-so-far 留空，模糊点写进尚未清晰区。
-4. **创建现在能说清的 ticket**为子 change，然后用 `llman-sdd graph` 接依赖边（第二步：先有 id 才能互引）。
+4. **创建现在能说清的 ticket** 为子 change，再用 `llman-sdd graph` 接依赖边（先有 id 才能互引）。
 5. 为每个查资料 ticket 启动 `llman-sdd-research` 后台 subagent。
 6. 停——画图是单个会话的活，不要顺手解决任何决策。
 
 ### 推进地图
 1. 加载地图（低分辨率视图，不用读每个 ticket 全文）。
-2. 选 ticket（用户指定或取可着手项的第一个），先完成 Branch binding（`change start` 或已有分支则 `change attach`）占住它。地图/ticket 的**规划壳**可短暂在默认分支；若 ticket 要改 live specs，须在绑定分支做 Specs landing。
-3. 解决它——按需深入（读相关 ticket 全文，调用 Notes 指定的 skill）。没把握时用 `llman-sdd-explore` 的逐问深挖。**不要**在未 binding 时改 `llmanspec/specs/**`。
-4. 记录解决：把答案作为结论写入该 ticket 的 proposal，关闭它，并在地图的 Decisions-so-far 追加一行要点 + 指针。
-5. 新增 ticket（先建再接线）；把答案让模糊点变清晰、升级成 ticket 的，从尚未清晰区移除。若答案揭示某 ticket 越过目的地，归入范围外而非在路径上解决。
+2. 选 ticket（用户指定或取可着手项第一个），先绑定分支（`change start` 或已有分支 `change attach`）占住它。规划文档可短暂在默认分支；ticket 要改 specs 时须在绑定分支落地。
+3. 解决它——按需深入（读相关 ticket 全文，调用 Notes 指定的 skill）；没把握时用逐问深挖。**不要**在未绑定时改 `llmanspec/specs/**`。
+4. 记录解决：答案写入该 ticket 的 proposal 并关闭它，在地图 Decisions-so-far 追加一行要点 + 指针。
+5. 新增 ticket（先建再接线）；答案让模糊点变清晰的，升级为 ticket 并移出尚未清晰区；答案揭示某 ticket 越过目的地的，归入范围外而非在路径上解决。
 
 ## 输出
-地图 change + 子决策 change 的依赖图（`llman-sdd graph`）。路径清晰后建议进入 `llman-sdd-propose`（含 Branch binding → Specs landing，至 `readyToImplement=true`）把决策收拢为可实施计划。
+地图 change + 子决策 change 的依赖图（`llman-sdd graph`）。路径清晰后建议 `llman-sdd-propose` 收拢为可实施计划。
 
-> 命令细节用 `llman-sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
-> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman-sdd list --specs` / `llman-sdd show <capability>` 查全文。
+{{ unit("skills/cli-footer") }}
 
 {{ unit("skills/structured-protocol") }}

package/templates/zh-Hans/units/skills/cli-footer.md

@@ -0,0 +1,2 @@
+> 命令细节用 `llman-sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman-sdd list --specs` / `llman-sdd show <capability>` 查全文。

package/templates/zh-Hans/units/skills/git-native-flow-brief.md

@@ -1,9 +1,10 @@
-## Git-native 生命周期（摘要）
+## Git 分支生命周期（摘要）
 
-勿混淆：**Skill 导航** ≠ **Git-native 生命周期**。全图见根 `AGENTS.md`「领域概念区分」或 `llman-sdd-propose` 内嵌全图。
+**Skill 导航** ≠ **分支生命周期**。全图见根 `AGENTS.md` 或 `llman-sdd-propose` 内嵌图。
 
 硬规则：
-1. **先** Branch binding（`change start` / `attach`）→ Full；**再** Specs landing（绑定分支编辑并 commit `llmanspec/specs/**`）。
-2. 无 live 合约变更 → `needs_specs_change: false`。apply 前须 `readyToImplement=true`。
-3. 收口用 `change finalize`（自动提交 `archive(sdd): <id>`；`--no-commit` 可跳过）。`change checkpoint` 已移除（调用即以非零退出报错，指向 finalize）。
-4. **禁止**在默认分支 commit live specs；已 attach 勿重复 `start`。
+1. **先**绑定分支（`change start` / `attach`）→ full；**再**落地 specs（绑定分支上编辑并 commit `llmanspec/specs/**`）。
+2. 无合约编辑 → `needs_specs_change: false`。`stage=full` 且 specs-landed 门通过即可进 apply；`readyToImplement=true`（全门绿）是 verify/finalize 前的完成信号。
+3. 收口用 `change finalize`（自动提交 `archive(sdd): <id>`；`--no-commit` 跳过）。
+4. **禁止**在默认分支 commit specs；已 attach 勿重复 `start`。
+5. worktree（可选）：`change start --worktree` 在独立 worktree 建分支、不动当前检出（`--base <branch>` 记录分叉源）；finalize 目标被其他 worktree 持有时自动在该 worktree 内执行（输出标注位置）。

package/templates/zh-Hans/units/skills/git-native-flow.md

@@ -1,30 +1,30 @@
-## Git-native 生命周期（权威全图）
+## Git 分支生命周期（权威全图）
 
-勿混淆两层：**Git-native 生命周期**（Branch binding → Specs landing → `readyToImplement`）与 **Skill 导航**（explore→propose→apply→verify→archive）。Specs landing **不是**独立 skill。
+两层别混：**分支生命周期**（绑定分支 → 落地 specs → `readyToImplement`）与 **skill 导航**（explore→propose→apply→verify→archive）。落地 specs **不是**独立 skill。
 
 ```mermaid
 flowchart TB
-  subgraph main_ok["允许短暂在默认分支"]
+  subgraph main_ok["可短暂在默认分支"]
     A["change new → draft<br/>仅 proposal.md"]
     B1["补 design.md → designed"]
     B2["补 tasks.md → planned"]
   end
 
-  subgraph gate_start["Branch binding"]
+  subgraph bind["绑定分支"]
     C{"工作区干净<br/>且在默认分支？"}
     D["change start<br/>建 sdd/&lt;id&gt; + 写 branch/base_branch/base_sha"]
     E["或手动 checkout -b<br/>再 change attach"]
   end
 
   subgraph specs_only["仅在本 change 分支"]
-    F["编辑 live llmanspec/specs/**（.feature）"]
-    G["commit → Specs landing<br/>现算 merge-base...HEAD 含 specs 路径"]
+    F["编辑 llmanspec/specs/**（.feature）"]
+    G["commit → 落地 specs<br/>现算 merge-base...HEAD 含 specs 路径"]
   end
 
-  subgraph implement["实现"]
+  subgraph implement["实施与收口"]
     H["apply：按 tasks 改代码<br/>可继续改 specs"]
     I["verify"]
-    J["finalize<br/>合并（squash 缺省）→ rename → 自动提交 archive(sdd): &lt;id&gt;<br/>目标分支才首次合入 specs"]
+    J["finalize：合并（默认 squash）→ 改名 → 自动提交 archive(sdd): &lt;id&gt;<br/>specs 首次进入目标分支"]
   end
 
   A --> B1 --> B2 --> C
@@ -34,7 +34,17 @@ flowchart TB
 ```
 
 硬规则：
-1. **先** `change start` / `attach`（Branch binding / 分支绑定）进入 Full；**再**在绑定的非默认分支编辑 `llmanspec/specs/**` 并 commit（Specs landing / 合约落地）。
-2. 无 live 合约变更时可设 frontmatter `needs_specs_change: false`。进入 apply 前 `llman-sdd show <id> --json` 的 `readyToImplement` 须为 true（`Full ∧ gateChecks 全过`；specs-landed 项 = `specsLanded ∨ needs_specs_change=false`；一切范围 = 现算 merge-base，存储 `base_sha` 仅审计）。
-3. `change checkpoint` 已移除（无存档点概念：中途不必存档，`change finalize` 不要求干净树）。收口一律 `llman-sdd change finalize <id>`：自动提交 `archive(sdd): <id>`（实现 diff + 改名一次提交）；`--no-commit` 跳过自动提交（CI/手动历史场景）。change 分支上提交自由（分段或 finalize 单次收尾均可）。
-4. **禁止**为过干净树门禁把 live specs commit 到默认分支；已 attach 时不要重复 `start`。
+1. **先** `change start` / `attach` 绑定分支（进入 full）；**再**在绑定的非默认分支编辑 `llmanspec/specs/**` 并 commit（落地 specs）。
+2. 无合约编辑的 change 设 frontmatter `needs_specs_change: false`。`stage=full` 且 specs-landed 门通过（specsLanded ∨ needs_specs_change=false）即可进 apply；`readyToImplement=true`（gateChecks 全过，含 tasks-done）是 verify/finalize 前的完成信号。diff 范围一律现算 merge-base；存储的 `base_sha` 仅审计。
+3. 收口一律 `llman-sdd change finalize <id>`：自动提交 `archive(sdd): <id>`（实现 diff + 改名一笔）；`--no-commit` 跳过自动提交。change 分支上提交自由（分段或 finalize 一次收尾均可）。
+4. **禁止**为过干净树门禁把 specs commit 到默认分支；已 attach 勿重复 `start`。
+
+Worktree 决策表：
+
+| 工作形态 | 命令 | 判据 |
+|---|---|---|
+| 单检出 | `llman-sdd change start <id>` | 在默认分支且树干净；直接切到新分支 |
+| 保留当前检出 / 并行 change | `llman-sdd change start <id> --worktree` | 分支建于独立 worktree（`sdd.worktree_root` / `sdd.worktree_naming` 可调，缺省仓库根兄弟目录），当前检出不动，输出含 worktree 路径；配 `--base <branch>` 记录非默认分叉源 |
+| 已在 feature 分支（含手工 wt/git-worktree） | `llman-sdd change attach <id>` | 分支已存在；`--base <branch>` 显式记录分叉源 |
+
+finalize 目标定位：目标分支被其他 worktree 持有时，`llman-sdd change finalize <id>` / `llman-sdd change archive <id>` 自动在该 worktree 内完成合并、改名与提交（输出含 `executed in target worktree <path>`）；持有 worktree 脏时中止报错并列出处置选项（零写入）。

package/templates/zh-Hans/units/skills/human-readable-summary.md

@@ -1,10 +1,9 @@
 # 人读摘要（强制）
 
-在本工作流中产出的每一份报告、交接或门禁输出，MUST 在任何机器细节之前
-先给出一段简短的人读摘要：
+每份报告、交接或门禁输出，MUST 在任何机器细节之前先给人读摘要：
 
 - **结论** — 一行（如「门禁全绿」/「发现 2 个 CRITICAL」）。
-- **风险** — 最多三条，按影响从高到低。
-- **待决策** — 明确的提问，或「无」。
+- **风险** — 最多三条，按影响降序。
+- **待决策** — 明确提问，或「无」。
 
-控制在十行以内；细节放在折叠线以下。
+十行以内；细节放折叠线以下。