@llman-sdd/core 0.1.0 → 0.1.1

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

@@ -0,0 +1,66 @@
+---
+name: "llman-sdd-specs-compact"
+description: "人类主动触发的维护工具。压缩去重 llman SDD specs——在归档积累较多后合并冗余 requirement/scenario，保留所有规范行为不变。不属于日常 pipeline：仅在用户明确要求压缩 specs 时才运行。"
+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`）。
+
+## Context
+- specs 会随着变更积累而膨胀，并出现重复 requirement/scenario。
+- 压缩必须保持可验证、可回归。
+- 当 archive 历史过大时，会干扰压缩评审与定位。
+
+## Goal
+- 识别并合并冗余 requirement/scenario。
+- 形成更紧凑且可维护的规范结构。
+
+## Constraints
+- 未经明确替代，不得删除规范性行为。
+- 尽量保持 requirement 标题稳定。
+- 每个保留 requirement 至少保留一个有效 scenario。
+- **编辑 live `llmanspec/specs/**` 须走 change**：先 Branch binding（`change start` / `attach`），在绑定分支上做 Specs landing 式提交；**禁止**在默认分支直接压缩改写 live specs。
+
+## 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 的重叠项。
+4. 产出压缩计划（canonical requirements + keep/merge/remove 决策 + 迁移说明）。
+5. 执行并验证（`llman sdd validate --specs --strict --no-interactive`）。
+
+## Decision Policy
+- 两条 requirement 语义等价时优先合并。
+- 仅在引用关系清晰时提取共享规范文本。
+- 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`。
+
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。
+
+{{ unit("skills/validation-hints") }}
+
+{{ unit("skills/ethics-governance") }}

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

@@ -0,0 +1,32 @@
+---
+name: "llman-sdd-validate"
+description: "校验 llmanspec 变更与 specs 并提供修复提示。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD 校验
+
+使用此 skill 校验变更/spec 格式与过期状态。
+
+## 步骤
+1. 校验单个条目：`llman sdd validate <id>`。
+2. 批量校验：`llman sdd validate --all`（或 `--changes` / `--specs`）。
+3. 在 CI 或自动化场景中使用 `--strict` 与 `--no-interactive`。
+4. 若校验失败，汇总错误并给出最小、可执行的修复建议。
+{% 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`）。
+{% endif %}
+
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。
+
+{{ unit("skills/validation-hints") }}
+
+{{ unit("skills/ethics-governance") }}

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

@@ -0,0 +1,96 @@
+---
+name: "llman-sdd-verify"
+description: "验证已实施的 llman SDD 变更是否与 specs/design/tasks 一致。产出分级报告（CRITICAL / WARNING / SUGGESTION），对比代码与工件。在 apply 完成后运行；全绿则可归档。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Verify
+
+使用此 skill 验证实现是否与该 change 的 artifacts 一致。
+
+## Pipeline 位置
+
+### Skill 导航（非生命周期；仅指示当前 skill）
+
+```mermaid
+flowchart LR
+    apply["llman-sdd-apply<br/>实施"] --> verify
+    verify["★ llman-sdd-verify ★<br/>验证（你现在在这里）"]
+    verify --> archive["llman-sdd-archive<br/>归档"]
+
+    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 单元。
+
+## 硬约束
+
+- **必须先通过 apply 阶段全绿**：未完成实现的 change 跳过验证。
+- **CRITICAL 必须修复**：标记为 CRITICAL 的问题归档前必须修复。
+- **不要问「要不要继续」**：跑完整个验证流程，输出完整报告。
+
+{{ 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」），不是硬性违规。
+     - 坏味清单（每项「是什么 → 怎么修」）：
+
+     | 坏味 | 怎么修 |
+     |------|--------|
+     | Mysterious Name（名不达意） | 重命名 |
+     | Duplicated Code（重复逻辑） | 抽取共享部分 |
+     | Feature Envy（方法更爱用别人的数据） | 把方法移过去 |
+     | Data Clumps（同组字段到处走） | 打包成类型 |
+     | Primitive Obsession（原始类型充当领域概念） | 给专门类型 |
+     | Repeated Switches（同类 switch 反复出现） | 多态或共享 map |
+     | Shotgun Surgery（一处改动散落多处） | 聚到一个模块 |
+     | Divergent Change（一个文件因多个无关原因被改） | 拆分 |
+     | Speculative Generality（为未发生的需求加抽象） | 删掉 |
+     | Message Chains（长链 a.b().c()） | 隐入一个方法 |
+     | 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）。
+{% 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`（修复）
+
+{{ 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/validation-hints") }}
+
+{{ unit("skills/structured-protocol") }}

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

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

package/templates/zh-Hans/units/migrate-prompt.md

@@ -0,0 +1,28 @@
+# llman sdd project migrate — 协作说明
+
+## 命令意图
+
+- `llman sdd project migrate --kind toon2features`：遗留 `spec.toon` → 单轨 `.feature`（一次性迁移，幂等）。
+- `llman sdd project migrate --kind specs-flatten`：纯同名单文件目录 `specs/<cap>/<cap>.feature` → 扁平 `specs/<cap>.feature`（git mv 保留历史）。
+
+## Agent 该做什么
+
+- 先确认是否真需要迁移（无 legacy / 单文件目录 → no-op）。
+- 先跑 `--dry-run` 看预检查报告；`conflict` / `misnamed` 项人工处理，勿强行迁移。
+- 迁移后运行 `llman sdd validate --specs --strict --no-interactive` 与项目 BDD 套件。
+
+## 人类该做什么
+
+- 检查 `scope_rewritten` 报告与 git diff（mv 保留历史）。
+- 顺手把 `# scope:` 指向该规范管辖的真实源码目录。
+
+## 陷阱
+
+- 含多个 `.feature`、异名文件或附属文件的目录不会自动扁平（只报告）。
+- 重名冲突必须人工解决（两文件都保留）。
+- 自引用 `# scope:` 会被自动改写为 `specs/<cap>.feature`。
+
+## 下一步
+
+- `llman sdd validate --specs --strict --no-interactive`
+- 项目 BDD 运行（如 `cargo test --features bdd`）

package/templates/zh-Hans/units/skills/ethics-governance.md

@@ -0,0 +1,6 @@
+## Ethics Governance
+- `ethics.risk_level`：low——仅读写本仓库与 `llmanspec/`，无外发动作；正文另有声明时从其声明。
+- `ethics.prohibited_actions`：违反正文「硬约束」的动作；未经用户明确要求的 push / PR / 外部上传。
+- `ethics.required_evidence`：结论须有命令输出或文件路径佐证；门禁状态以 `llman sdd validate` 为准。
+- `ethics.refusal_contract`：门禁 CRITICAL 未清零 → 拒绝进入下一阶段；自修复达上限 → 报告 blocker。
+- `ethics.escalation_policy`：改动 SDD 合约/模板或执行不可逆动作前，暂停并请用户确认。

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

@@ -0,0 +1,9 @@
+## Git-native 生命周期（摘要）
+
+勿混淆：**Skill 导航** ≠ **Git-native 生命周期**。全图见根 `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`。

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

@@ -0,0 +1,40 @@
+## Git-native 生命周期（权威全图）
+
+勿混淆两层：**Git-native 生命周期**（Branch binding → Specs landing → `readyToImplement`）与 **Skill 导航**（explore→propose→apply→verify→archive）。Specs landing **不是**独立 skill。
+
+```mermaid
+flowchart TB
+  subgraph main_ok["允许短暂在默认分支"]
+    A["change new → draft<br/>仅 proposal.md"]
+    B1["补 design.md → designed"]
+    B2["补 tasks.md → planned"]
+  end
+
+  subgraph gate_start["Branch binding"]
+    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 路径"]
+  end
+
+  subgraph implement["实现"]
+    H["apply：按 tasks 改代码<br/>可继续改 specs"]
+    I["verify"]
+    J["finalize<br/>合并（squash 缺省）→ rename → 自动提交 archive(sdd): &lt;id&gt;<br/>目标分支才首次合入 specs"]
+  end
+
+  A --> B1 --> B2 --> C
+  C -->|是| D --> F
+  C -->|已在 feature| E --> F
+  F --> G --> H --> I --> J
+```
+
+硬规则：
+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`。

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

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

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

@@ -0,0 +1,17 @@
+## 阶段守卫（`stage` / `readyToImplement`）
+
+用权威 JSON 判定（勿凭「完整工件」口头说法）：
+
+```bash
+llman sdd show <id> --json --type change
+```
+
+解读字段：`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/` 预期**不存在**，勿当缺失。 |

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

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

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

@@ -0,0 +1,24 @@
+校验修复（单轨 feature-as-spec）：
+
+1）缺少头注释（`missing # capability: header comment`）：
+每个 capability `.feature`（`llmanspec/specs/<capability>.feature` 或 `llmanspec/specs/<capability>/<capability>.feature`）必须以以下注释开头：
+```
+# language: zh-CN
+# capability: <capability>
+# purpose: 一句话概述
+# 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>` 挂到规则。
+- `@manual` 须与 `@human` 同用；禁止 `@human` 与 `@executable` 同场景。
+
+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`。

package/templates/zh-Hans/units/spec/feature-contract.md

@@ -0,0 +1,29 @@
+## 单轨 Feature 合约规范
+
+每个 capability 只有一个 Gherkin 文件：扁平 `llmanspec/specs/<capability>.feature`（新默认）或目录 `llmanspec/specs/<capability>/` 内同名主文件（两种布局二选一，同 id 并存算冲突）。
+它是唯一的 spec 工件——不存在 `spec.toon`。
+
+```gherkin
+# language: zh-CN
+# capability: sample
+# purpose: One-line overview.
+# scope: src/
+
+功能: sample
+
+  @req:r1 @human
+  场景: Rule title
+    System MUST do something.
+
+  @req:r1 @executable
+  场景: happy
+    假如 a precondition
+    当 a trigger happens
+    那么 the outcome is observed
+```
+
+- 头注释（`# capability:` / `# purpose:` / `# scope:`）必填；`scope` 驱动 staleness 检查。
+- `@human` 场景是人拥有的约束场景；规则 statement 全文放在场景描述里。改/删它只出 WARNING（报告制，不阻断门禁），用 git 分支对比审视；旧的锁定确认元数据 `rules_touched` / `agent_acked` / `@agent` 已删除，无别名也无兼容层。
+- `@executable` 场景是 runner 绑定的验收场景；用 `@req:<req_id>` 挂回规则。
+- 覆盖三态分级：enforced（有验收）/ manual（`@manual`）/ pending——`list --specs` 逐项输出。
+- 场景 MUST 保持顶层：`Rule:` 块会被拒绝（runner 会静默跳过其中场景）。

package/templates/zh-Hans/units/workflow/archive-freeze-guidance.md

@@ -0,0 +1,6 @@
+## Archive 冷备引导
+- 当 archive 目录增长过大时，使用冷备维护：
+  - 预览冻结候选：`llman sdd archive freeze --dry-run`
+  - 冻结旧归档：`llman sdd archive freeze --before <YYYY-MM-DD> --keep-recent <N>`
+  - 需要恢复时：`llman sdd archive thaw --change <YYYY-MM-DD-id>`
+- freeze/thaw 仅用于日期归档目录（`YYYY-MM-DD-*`）；建议保留少量最近目录不冻结。