@llman-sdd/core 0.3.0 → 0.5.0

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」）。
-- **风险** — 最多三条，按影响从高到低。
-- **待决策** — 明确的提问，或「无」。
+- **风险** — 最多三条，按影响降序。
+- **待决策** — 明确提问，或「无」。
 
-控制在十行以内；细节放在折叠线以下。
+十行以内；细节放折叠线以下。

package/templates/zh-Hans/units/skills/stage-guard.md

@@ -1,17 +1,17 @@
 ## 阶段守卫（`stage` / `readyToImplement`）
 
-用权威 JSON 判定（勿凭「完整工件」口头说法）：
+以权威 JSON 判定（勿凭「工件看着齐了」）：
 
 ```bash
-llman-sdd show <id> --json --type change
+llman-sdd show <id> --output json --type change
 ```
 
-解读字段：`stage`、`specsLanded`、`needsSpecsChange`、`readyToImplement`、`gateChecks`（逐项 `pass` + 未过时一行 `hint`）。
+读字段：`stage`、`specsLanded`、`needsSpecsChange`、`readyToImplement`、`gateChecks`（逐项 `pass` + 未过时的 `hint`）。
 
-| 条件 | 动作 |
+| 状态 | 动作 |
 |------|------|
-| `stage=draft`（仅 proposal.md） | STOP。长大到 Designed（补 design.md）→ Planned（补 tasks.md）→ Branch binding → Specs landing。draft 不能直接 apply/verify。若已有 proposal+design+tasks 仍是 `draft`：tasks 无 design 需先补 design.md。**不要**建 `changes/<id>/specs/`，**不要**先在默认分支改 live specs。 |
-| `stage=designed`（proposal + design） | 下一步：补 tasks.md → `planned`。规划工件齐全后再 `change start` / `attach`（Branch binding）。 |
-| `stage=planned`（proposal + design + tasks） | STOP 直到绑定：跑 `change start` / `attach`（Branch binding）→ `full`。 |
-| `stage=full` 且 `readyToImplement=false` | STOP。在**绑定分支**完成 Specs landing（编辑 `llmanspec/specs/**` 并 commit），或设 `needs_specs_change: false`。**不要**再跑 `change start`。丢失绑定分支 specs → checkout/重建 + 必要时 `attach --force`。 |
-| `readyToImplement=true` | 可通过 apply/verify 前置检查。`changes/<id>/specs/` 预期**不存在**，勿当缺失。 |
+| `stage=draft`（仅 proposal.md） | STOP。补 design.md → designed，补 tasks.md → planned，再绑定分支、落地 specs。draft 不能 apply/verify。若已有 proposal+tasks 而仍是 `draft`（缺 design.md——它是 stage 门槛）：先补 design.md。**不要**建 `changes/<id>/specs/`，**不要**在默认分支改 specs。 |
+| `stage=designed`（proposal + design） | 补 tasks.md → `planned`；规划文档齐全后再 `change start` / `attach`（绑定分支）。 |
+| `stage=planned`（proposal + design + tasks） | STOP 直到绑定：`change start` / `attach` → `full`。 |
+| `stage=full` 且 `readyToImplement=false` | 读未过的 `gateChecks` 分项。specs-landed 门未过 → 在**绑定分支**落地 specs（编辑 `llmanspec/specs/**` 并 commit），或设 `needs_specs_change: false`；**不要**重跑 `change start`（绑定分支上的 specs 丢失 → checkout/重建 + 必要时 `attach --force`）。specs-landed 门已绿而 tasks-done/validate/clean-tree 未过 → 实施中期的正常状态：继续 apply 勾 tasks，勿当落地失败。 |
+| `readyToImplement=true` | 完成信号：gateChecks 全绿（tasks 全勾 + validate 通过）——verify/finalize 前置已满足。`changes/<id>/specs/` 预期**不存在**，勿当缺失。 |

package/templates/zh-Hans/units/skills/structured-protocol.md

@@ -1,23 +1,20 @@
 ## Context
-- 先查状态再动手：change/spec 状态以 `llman-sdd show/list/validate` 输出为准。
-- 读 spec 全文前先用 `llman-sdd context --task --paths` 定位相关 specs。
+- 先查状态再动手：change/spec 状态以 `llman-sdd show/list/validate` 输出为准；读 spec 全文前先用 `llman-sdd context --task --paths` 定位。
 
 ## Goal
-- 本节命令达成一个可验证结果；结果路径与校验状态随报告输出。
+- 达成一个可验证结果；报告附结果路径与校验状态。
 
 ## Constraints
-- 遵守正文「硬约束/硬规则」，本节不复读。先判断变更规模选路径（triage）：行为合约变更走完整 SDD，实现层走 quick；不确定选完整 SDD（保守）。
-- 改动保持最小；已知校验错误禁止强行继续。
+- 遵守正文硬约束（不复读）。先判断规模选路径：合约变更走完整 SDD，实现层走 quick；不确定选完整 SDD。改动最小；已知校验错误禁止强行继续。
 
 ## Workflow
-- 每步以 `llman-sdd` 命令结果为事实来源；改动工件后必跑 `llman-sdd validate`。
-- 命令细节见下方生成式命令参考或 `llman-sdd <cmd> --help`。
+- 每步以 `llman-sdd` 命令结果为事实来源；改动工件后必跑 `llman-sdd validate`；命令细节见 `llman-sdd <cmd> --help`。
 
 ## Decision Policy
 - 高影响歧义先澄清再继续；事实自己查证，只有决策问用户。
 
 ## Output Contract
-- 报告先给人读摘要（结论 / 风险 / 待决策），机器细节随后。
+- 先给人读摘要（结论 / 风险 / 待决策），机器细节随后。
 
 ## Ethics Governance
 - `ethics.risk_level`：low——仅读写本仓库与 `llmanspec/`，无外发动作；正文另有声明时从其声明。

package/templates/zh-Hans/units/skills/validation-hints.md

@@ -1,7 +1,6 @@
 校验修复（单轨 feature-as-spec）：
 
-1）缺少头注释（`missing # capability: header comment`）：
-每个 capability `.feature`（`llmanspec/specs/<capability>.feature` 或 `llmanspec/specs/<capability>/<capability>.feature`）必须以以下注释开头：
+1）缺头注释（`missing # capability: header comment`）：每个 capability `.feature`（`llmanspec/specs/<capability>.feature` 或目录内同名主文件）必须以下列注释开头：
 ```
 # language: zh-CN
 # capability: <capability>
@@ -9,16 +8,13 @@
 # scope: src/
 ```
 
-2）tag 语法（`@human constraint scenario must carry an @req:<req_id> tag` / `orphan acceptance scenario`）：
-- 规则：`@req:<id> @human` —— statement 放场景描述（须含 MUST/SHALL）。
-- 验收：`@executable` 且至少一个 `@req:<id>` 挂到规则。
-- 禁止 `@human` 与 `@executable` 同场景；`@manual` 已在 0.3.0 移除——残留会被报迁移 ERROR，删掉该 tag 即可（`@human` 本身已承载人工判定语义）。
+2）原生分层格式（`rule must carry an @req:<req_id> tag on the rule header`）：
+- 规范样式只有一种：`@req:<id>` 挂在 `规则:` 块头标签,块内嵌套 `场景:`(假如/当/那么)是可执行示例——默认首选。
+- 仅当需求无法程序化表达或暂不转写时才保留无嵌套场景的 `规则:`(裸规则):描述自由文本,无 MUST/SHALL 强制;validate 以聚合计数提示,review `pending` 信号计量,specs-compact 负责压降。
+- 历史标签 `@executable`/`@rule`/`@human`/`@manual` 不再使用、解析惰性;旧文件报结构问题时运行 `llman-sdd spec migrate-native` 迁移。
+- 不在任何 `规则:` 内的顶层 `场景:` 是功能级示例:无规则句柄、不告警、不参与规则统计(Gherkin 原生语义)。
 
-3）遗留 `spec.toon`（`legacy spec.toon found ... run ... toon2features`）：
-运行 `llman-sdd project migrate --kind toon2features --yes`，审阅 diff 后提交。
-
-Git-native 护栏：
-- **Branch binding** → **Specs landing**：先 `change start` / `attach`，再在绑定的非默认分支编辑 live `.feature` 并 commit。
-- 锁定规则（报告制）：改/删既有 `@human` 场景只出 WARNING，不阻断 validate / change finalize / change diff；报告按 `@req:<id>` 指明被改的是哪条规则。控制点：git 分支对比 + `llman-sdd review` / `change diff` 的报告浮现。旧的锁定确认元数据（frontmatter `rules_touched` / `agent_acked`、`@agent` tag、`--yes` 的确认语义）已全部删除，无别名、无兼容层。
-- apply 前须 `readyToImplement=true`（或 `needs_specs_change: false`）。收尾优先 `change finalize`。
-- 勿使用 `change delta` / solidify / `*.feature.delta.toon`。
+分支护栏：
+- 先 `change start` / `attach` 绑定分支，再在绑定的非默认分支编辑 `.feature` 并 commit（落地 specs）。
+- 锁定规则（报告制）：改/删既有 `规则:` 块只出 WARNING，不阻断 validate / finalize / `change diff`；报告按 `@req:<id>` 指明被改规则。控制点：git 分支对比 + `llman-sdd review` / `change diff`。旧锁定确认元数据（frontmatter `rules_touched` / `agent_acked`、`@agent` tag、`--yes` 确认语义）已全部删除，无别名无兼容层。
+- `stage=full` 且 specs-landed 门通过（specsLanded ∨ `needs_specs_change: false`）即可进 apply；verify/finalize 须 `readyToImplement=true`（完成信号）。收口优先 `change finalize`。