@llman-sdd/core 0.3.1 → 0.5.1

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

@@ -1,64 +1,53 @@
 ---
 name: "llman-sdd-draft"
-description: "快速把一个 change 想法记成草案提案（仅 proposal.md，经 `change new --from`）。不强制 tasks/design/specs/attach。用于随手记 idea 或未来需求；准备好后用 propose 正式化。"
+description: "把 change 想法记成草案（仅 proposal.md，不问 id）。随手记 idea/未来需求；落实时走 propose。"
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD 草案（Draft）
 
-把一个 change 想法记成**草案提案**（仅 `proposal.md` skeleton）。这是「先把 idea / 未来需求记下来」的轻量入口——不做 triage、不写 tasks、不编辑 live specs、不 attach。等想法准备好落实时，用 `llman-sdd-propose` 正式化。
+把 change 想法记成**草案**（仅 `proposal.md` skeleton）——「先记下来」的轻量入口：不判断规模、不写 tasks、不改 specs、不 attach。落实时用 `llman-sdd-propose` 正式化。
 
 ## Pipeline 位置
 
 ```mermaid
 flowchart LR
-    draft["★ llman-sdd-draft ★<br/>草案（你现在在这里）"] -.->|"正式化"| propose["llman-sdd-propose<br/>提案"]
-    propose --> apply["llman-sdd-apply<br/>实施"]
-    apply --> verify["llman-sdd-verify<br/>验证"]
-    verify --> archive["llman-sdd-archive<br/>归档"]
+    draft["★ llman-sdd-draft"] -.->|"正式化"| propose["llman-sdd-propose"]
+    propose --> apply["llman-sdd-apply"] --> verify["llman-sdd-verify"] --> archive["llman-sdd-archive"]
 
     style draft fill:#fff3cd,stroke:#ffc107,stroke-width:3px
 ```
 
-> 📍 你现在在草案阶段 → 下一步：完善 `proposal.md`，然后运行 `llman-sdd-propose` 正式化
-> 📎 本技能创建**草案** change（仅 proposal.md）。完整提案走 Git-native：tasks → Branch binding → Specs landing（见 propose 的生命周期图）
-> 🗺️ Skill 导航 ≠ Git-native 生命周期；Branch binding / Specs landing 不是独立 skill
+> 📍 草案阶段 → 下一步：完善 `proposal.md`，然后 `llman-sdd-propose` 正式化。
 
 ## 硬约束
 
-- **MUST NOT 询问用户 change id**：由 `change new --from` 从描述推导并告知用户。
-- **MUST NOT 创建 tasks/design/specs/attach**：本技能仅创建 `proposal.md` 草案壳。完整规划工件属于 `llman-sdd-propose`。
-- **MUST NOT 做 triage 或判断变更规模**：那是 propose 的职责。若用户想开始实现，建议 `llman-sdd-propose`。
-- **适用边界**：若描述明显涉及 MUST/SHALL 行为合约变更或多文件改动，建议用 `llman-sdd-propose` 而非停在草案——但仍先建草案壳以免想法丢失。
-- **frontmatter 有固定 schema**：充实 `proposal.md` 时只接受 `llmanspec/AGENTS.md`「Change Proposal Frontmatter SSOT」中的合法字段（含 `depends_on`、`blocks`、`branch`、`base_sha`、`needs_specs_change`）。`status`/`title`/`priority`/`author` 等会被 `llman-sdd validate` 报 ERROR 拒绝。生命周期阶段是推断量——用 `llman-sdd show`/`list` 查看，绝不写进 frontmatter。正文 MUST NOT 复读 frontmatter 字段（不要 `## Status` 段）；正文 H1 用人类可读标题，不要复读 change id。
+- **MUST NOT 询问 change id**：由 `change new --from` 从描述推导并告知用户。
+- **MUST NOT 创建 tasks/design/specs/attach**：只建 `proposal.md` 草案；完整规划归 `llman-sdd-propose`。
+- **MUST NOT 判断变更规模**：那是 propose 的职责。用户想开始实现 → 建议 `llman-sdd-propose`。
+- **适用边界**：描述明显涉及 MUST/SHALL 合约变更或多文件改动时，建议 `llman-sdd-propose`——但仍先建草案以免想法丢失。
+- **frontmatter 有固定 schema**：`proposal.md` 只接受 `llmanspec/AGENTS.md`「Change Proposal Frontmatter SSOT」的合法字段（`depends_on`、`blocks`、`branch`、`base_sha`、`needs_specs_change` 等）；`status`/`title`/`priority`/`author` 会被 `llman-sdd validate` 报 ERROR。生命周期阶段是推断量（用 `llman-sdd show`/`list` 查），绝不写进 frontmatter。正文 MUST NOT 复读 frontmatter 字段（不要 `## Status` 段）；H1 用人类可读标题，不复读 change id。
 
 ## 步骤
 
 ### 0) Preflight
-- 读取 `llmanspec/config.yaml` 了解项目上下文、规则、locale。
-- 必须存在 `llmanspec/`；若不存在，提示先运行 `llman-sdd init`，然后 STOP。
+- 读 `llmanspec/config.yaml`；`llmanspec/` 不存在则提示先跑 `llman-sdd init`，然后 STOP。
 
 ### 1) 捕获描述
-- 直接采用用户的描述（如「draft: 加一个导出 json 的命令」「记一下: sdd change 应该支持 worktree」）。
-- **MUST NOT 询问 change id。** 由描述推导。
+- 直接采用用户描述（如「draft: 加一个导出 json 的命令」「记一下: sdd change 应该支持 worktree」）。**MUST NOT 询问 change id。**
 
-### 2) 创建草案壳
+### 2) 创建草案
 ```bash
 llman-sdd change new --from "<用户描述>"
 ```
-- CLI 会生成合法的 kebab-case id（清洗 + 校验），在 `llmanspec/changes/<生成的 id>/` 下创建 `proposal.md`（含 `## Why` / `## What Changes` TODO 段的 skeleton），并打印最终 id 与路径。
-- 若生成的 id 与既有 change 冲突，CLI 以非零退出码失败；建议改写描述或用 `--force` 覆盖（对草案很罕见）。
+- CLI 生成合法 kebab-case id，在 `llmanspec/changes/<id>/` 建 `proposal.md`（含 `## Why` / `## What Changes` TODO 段），并打印 id 与路径。
+- id 冲突时 CLI 非零退出；建议改写描述或 `--force` 覆盖（草案罕见）。
 
 ### 3) 告知并交接
-- **MUST 告知用户已生成的 id**（例如「已创建草案 change `<id>`，路径 `llmanspec/changes/<id>/proposal.md`」）。
-- 建议下一步：
-  - 现在或稍后完善 `proposal.md`（Why / What Changes / Capabilities / Impact）。
-  - 准备好落实时，运行 `llman-sdd-propose` 正式化（triage + tasks → `change start`/`attach` → Specs landing）。
+- **MUST 告知生成的 id**（「已创建草案 change `<id>`，路径 `llmanspec/changes/<id>/proposal.md`」）。
+- 建议下一步：完善 `proposal.md`（Why / What Changes / Capabilities / Impact）；落实时跑 `llman-sdd-propose`。
 
-> 💡 草案已记 → 下一步：编辑 `proposal.md`，然后 `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/ethics-governance") }}

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

@@ -1,78 +1,64 @@
 ---
 name: "llman-sdd-explore"
-description: "进入 llman SDD 探索模式：理清思路、调查需求、分析问题。仅思考，禁止写代码。用于意图不明确或需要分析后再行动的场景。"
+description: "探索模式：理清思路、调查需求、分析问题；只思考不写代码。意图不明或需先分析再行动时用。"
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Explore
 
-当用户希望在开始实现之前先理清思路、调查问题或澄清需求时，使用此 skill。
+在开始实现前理清思路、调查问题、澄清需求时用此 skill。
 
-**重要：探索模式只用于思考，不用于实现。**
-- 你可以阅读文件、搜索代码、调查代码库。
-- 你可以创建/更新规划壳工件（proposal/design/tasks）。
-- live specs：**只读**，除非 change 已 Branch-bound 且你在该分支上；否则 STOP 并建议 `llman-sdd-propose` / `change start`。
-- 你绝对不能在探索模式下写应用代码或实现功能。
+**探索模式只思考，不实现：**
+- 可以读文件、搜代码、调查代码库。
+- 可以建/改规划文档（proposal/design/tasks）。
+- `llmanspec/specs/**` **只读**——除非 change 已绑定分支且你在该分支上；否则 STOP 并建议 `llman-sdd-propose` / `change start`。
+- 禁止写应用代码。
 
 ## Pipeline 位置
 
 {{ unit("skills/git-native-flow-brief") }}
 
-### Skill 导航（非生命周期；仅指示当前 skill）
-
 ```mermaid
 flowchart LR
-    explore["★ llman-sdd-explore ★<br/>探索（你现在在这里）"]
-    explore --> propose["llman-sdd-propose<br/>提案（含 Branch binding 与 Specs landing）"]
-    propose --> apply["llman-sdd-apply<br/>实施"]
-    apply --> verify["llman-sdd-verify<br/>验证"]
-    verify --> archive["llman-sdd-archive<br/>归档"]
+    explore["★ llman-sdd-explore"] --> propose["llman-sdd-propose"]
+    propose --> apply["llman-sdd-apply"]
+    apply --> verify["llman-sdd-verify"]
+    verify --> archive["llman-sdd-archive"]
 
     style explore fill:#fff3cd,stroke:#ffc107,stroke-width:3px
 ```
 
-> 📍 你现在在探索阶段（仅思考）→ 常规路径下一步 `llman-sdd-propose`（提案）
-> 📎 如果是小改动（不改行为合约），可直接走 `llman-sdd-quick`（快速路径）
-> 🗺️ Skill 导航 ≠ Git-native 生命周期
+> 📍 你在探索阶段 → 下一步通常 `llman-sdd-propose`；小改动（不改合约）走 `llman-sdd-quick`。
 
-## 探索姿态
-- 好奇而不教条
-- 以真实代码为依据
-- 需要时用 ASCII 图可视化
-- 同时保留多个选项与权衡
+## 姿态
+- 好奇而不教条，以真实代码为依据。
+- 需要时用 ASCII 图可视化；同时保留多个选项与权衡。
 
 ## 建议动作
-1. 使用 `llman-sdd context --task "<任务>" --paths "<文件>"` 快速定位相关 specs。
-   - 阅读 context 的 `direct` 列出的 spec 全文（这些是必须理解的合约）。
-   - 如果 context 不可用，运行 `llman-sdd index rebuild`（默认 `pageindex`，无需模型）后重试。
+1. 用 `llman-sdd context --task "<任务>" --paths "<文件>"` 定位相关 specs，通读其 `direct` 列出的 spec 全文（这些是必须理解的合约）。
+   - context 不可用 → 先 `llman-sdd index check`：stale/缺失则 `llman-sdd index rebuild`（默认 pageindex，免模型）后重试；fresh 仍不可用（`LLMAN_SDD_INDEX_CHAT_MODEL` 未设）→ 改用 `llman-sdd list --specs` + 直读 `.feature`——勿循环 rebuild。
 2. 澄清目标与约束（问 1–3 个问题）。
-3. **逐问深挖分支（可选，仅当用户显式触发时进入）**：触发词为「深挖」「grill」「逐个问」「彻底理清」。进入后一问一答走清决策：
-   - **一次只问一个问题**，并附你的推荐答案，等用户反馈后再继续下一个。
-   - **事实 vs 决策分离**：能通过读 capability `.feature`/代码/运行命令查证的事实，自行查证，**不问**用户；只有**决策**（取舍、偏好、范围边界）才交给用户。
-   - **术语校准**：遇到术语冲突或模糊词时立即指出（「你的 spec 定义 'X' 为 A，但你刚说成 B——哪个对？」）；解决后：若 change 已 Branch binding 且在绑定分支上，可更新 live `.feature`（Specs landing）；否则只记入 `proposal.md`，**禁止**在默认分支改 live specs。MUST NOT 另建 `CONTEXT.md` 词表作为第二权威。
-   - **决策回写**：已解决的决策回写到该 change 的 `proposal.md`「Open Questions」段（规划壳；可短暂在默认分支）。
-   - **完成判据**：每个待定决策都已解决或被显式推迟。未触发时保持默认（问 1–3 个问题）行为不变。
-4. 如果某个 change id 相关，阅读 `llmanspec/changes/<id>/` 下的 artifacts。
-   - 诊断校验错误时优先跑 `llman-sdd validate <spec> --strict --no-check`（fast mode，跳过可能耗时的 `bdd.run_command`），先解决结构门禁（Gherkin / `@req` 链接 / 双写 / req_id 唯一性），再跑 full mode（`--check` 或 `cargo test --features bdd`）。错误输出中的 `FAIL <item_type>/<id>` 行会逐条指明失败项。
+3. **逐问深挖分支（可选，用户显式触发才进入）**：触发词「深挖」「grill」「逐个问」「彻底理清」。进入后一问一答走清决策：
+   - 一次只问一个问题，附你的推荐答案，等反馈再问下一个。
+   - 事实 vs 决策分离：能读 `.feature`/代码/跑命令查证的事实自行查证，**不问**用户；只有决策（取舍、偏好、范围边界）才问。
+   - 术语校准：术语冲突或模糊立即指出（「spec 定义 'X' 为 A，你刚说成 B——哪个对？」）；解决后：已绑定分支且当前在绑定分支上 → 更新 `.feature`；否则只记入 `proposal.md`，禁止在默认分支改 specs。MUST NOT 另建 `CONTEXT.md` 词表当第二权威。
+   - 决策回写：已解决的决策写进该 change 的 `proposal.md`「Open Questions」段。
+   - 完成判据：每个待定决策都已解决或显式推迟。未触发时保持默认（问 1–3 个问题）。
+4. 涉及某个 change id 时，读 `llmanspec/changes/<id>/` 下的工件。
+   - 诊断校验错误先跑 `llman-sdd validate <spec> --strict` 过结构门禁（Gherkin / `@req` 链接 / 双写 / req_id 唯一性）；配置了 `bdd.run_command` 时 validate 缺省执行该 harness（`--no-check` 跳过）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条指明；`--output human` 输出人读 `FAIL <item_type>/<id>` 行。
 5. 探索 2–3 个选项与权衡。
-6. 判断变更规模（triage），确定是否需要走完整 SDD 流程。
-7. 当结论逐渐清晰时，建议用户把它记录下来（不要自动写入）：
-   - 范围变化 / 设计决策 / 工作项 → 规划壳（`proposal.md` / `design.md` / `tasks.md`）
-   - 约束 / 可执行 harness → **仅建议**写入 live `llmanspec/specs/**`（每 capability 一个 `.feature`）；实际编辑须先 Branch binding，再 Specs landing。探索模式未 binding 时只记到 proposal，勿直接改 live specs。
-
-> Git-native：先 `change start`/`attach`（Branch binding）进入 Full，再在绑定分支编辑 live `.feature`（Specs landing）；无 `change delta` / solidify / feature_delta。
+6. 判断变更规模，确定是否走完整 SDD。
+7. 结论清晰时建议用户记录（勿自动写）：
+   - 范围/设计/工作项 → 规划文档（`proposal.md` / `design.md` / `tasks.md`）
+   - 约束/可执行 harness → **仅建议**写入 `llmanspec/specs/**`；实际编辑须先绑定分支。未绑定时只记 proposal。
 
 ## 退出探索模式
-当用户准备开始实现时，根据变更规模选择路径：
-- 行为合约变更 → `llman-sdd-propose`（创建提案工件）
-- 小改动 / 不改合约 → `llman-sdd-quick`（快速路径）
-- `readyToImplement=true` → `llman-sdd-apply`（按 tasks 实施）
-若用户在探索模式中要求你开始实现，STOP 并提醒其先退出探索模式。
-
-> 💡 探索完成 → 下一步 `llman-sdd-propose`（提案）或 `llman-sdd-quick`（快速路径）
+- 行为合约变更 → `llman-sdd-propose`
+- 小改动 / 不改合约 → `llman-sdd-quick`
+- change 已落地 specs（`stage=full`、specs-landed 门绿）→ `llman-sdd-apply`
+若用户在探索中要求开始实现，STOP 并提醒先退出探索模式。
 
-> 命令细节用 `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-ff.md

@@ -1,38 +1,33 @@
 ---
 name: "llman-sdd-ff"
-description: "Fast-forward：一次性创建规划壳（proposal/design/tasks），再 Branch binding + Specs landing。禁止写入 changes/<id>/specs/。"
+description: "一趟走完 propose 等价路径：规划文档 → 绑定分支 → 落地 specs。"
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Fast-Forward (FF)
 
-快速走完 propose 等价路径：规划壳 → Branch binding → Specs landing（至 `readyToImplement=true`）。**不是**旧的 `changes/<id>/specs/` delta 模型。
+快速走完 propose 等价路径：规划文档 → 绑定分支 → 落地 specs（至 specs-landed 门通过）。**不是**旧的 `changes/<id>/specs/` delta 模型。
 
 ## 硬约束
 
-- **规划壳**只写在 `llmanspec/changes/<id>/`（proposal/design/tasks）。
-- Live 合约只写在绑定分支的 `llmanspec/specs/**`（Specs landing）。
-- **禁止**创建 `llmanspec/changes/<id>/specs/` 或 `*.feature.delta.toon`。
-- 进入 apply 前须 `readyToImplement=true`。
+- 规划文档只写在 `llmanspec/changes/<id>/`（proposal/design/tasks）；specs 只写在绑定分支的 `llmanspec/specs/**`。
+- **禁止**创建 `llmanspec/changes/<id>/specs/`。
+- `stage=full` 且 specs-landed 门通过（或 `needs_specs_change: false`）即可进 apply；verify/finalize 须 `readyToImplement=true`。
 
 ## 步骤
 
-1. 询问用户：一句话描述、change id（或派生）、受影响 capability、确认最终 id。
+1. 取得一句话描述；change id 未给则推导并宣布（非阻塞，同 propose 规则）；确定受影响 capability。
 2. 确保已 `llman-sdd init`（存在 `llmanspec/`）。
-3. 若 `llmanspec/changes/<id>/` 已存在：询问补齐或换 id；勿未确认就覆盖。
-4. 创建**规划壳**（可短暂在默认分支）：
-   - `llman-sdd change new <id>`（或手写）→ 充实 `proposal.md`
-   - `design.md`（按需）
-   - `tasks.md`
-5. **Branch binding**：`llman-sdd change start <id>`（干净树 + 默认分支）或手动建分支后 `change attach <id>`。
-6. **Specs landing**：在绑定分支编辑 live `llmanspec/specs/<capability>.feature`（扁平，或目录主文件）并 commit；无合约变更则 `needs_specs_change: false`。
-7. 校验：`llman-sdd validate <id> --strict --no-interactive`。
-8. 用 `llman-sdd show <id> --json` 确认 `readyToImplement=true` 后，建议 `llman-sdd-apply`（不要在未就绪时建议 apply）。
+3. `llmanspec/changes/<id>/` 已存在：询问补齐或换 id；勿未确认就覆盖。
+4. 建规划文档（可短暂在默认分支）：`llman-sdd change new <id>`（或手写）→ 充实 `proposal.md` → `design.md`（按需）→ `tasks.md`。
+5. **绑定分支**：`llman-sdd change start <id>`（干净树 + 默认分支）或手动建分支后 `change attach <id>`。
+6. **落地 specs**：在绑定分支编辑 `llmanspec/specs/<capability>.feature`（扁平，或目录主文件）并 commit；无合约变更设 `needs_specs_change: false`。
+7. 校验：`llman-sdd validate <id> --strict`。
+8. 用 `llman-sdd show <id> --output json` 确认 specs-landed 门绿（`specsLanded`/`needsSpecsChange`）后建议 `llman-sdd-apply`（未落地前不要建议）。
 
 {{ unit("skills/git-native-flow-brief") }}
-> 命令细节用 `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") }}
 
 {{ unit("skills/ethics-governance") }}

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

@@ -1,58 +1,46 @@
 ---
 name: "llman-sdd-graph"
-description: "以 mermaid 图可视化 llman SDD 变更间的依赖关系（depends_on/blocks）。辅助工具，任意阶段可用，不属于主实现 pipeline。"
+description: "用 mermaid 图可视化 change 依赖（depends_on/blocks）。辅助工具，任意阶段可用。"
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD 依赖图
 
-使用此 skill 可视化变更之间的依赖关系。
-
-## Pipeline 位置
-
-```mermaid
-flowchart LR
-    pipeline["主 pipeline:<br/>propose → apply → verify → archive"]
-    graph["📎 llman-sdd-graph<br/>依赖可视化（辅助工具）"]
-    graph -.->|任意阶段可用| pipeline
-
-    style graph fill:#e8f4e8,stroke:#28a745,stroke-width:2px
-```
-
-> 📎 辅助工具，可在 pipeline 任意阶段使用。需要提案 → `llman-sdd-propose`；需要实施 → 仅当 `readyToImplement=true` 时用 `llman-sdd-apply`。
+可视化 change 之间的依赖关系。辅助工具，不属于主 pipeline（propose → apply → verify → archive），任意阶段可用。
 
 ## 用法
 
-**聚焦视图（seed 模式）：** 展示指定变更及其关系邻域。
+**聚焦视图（seed 模式）**——指定 change 及其关系邻域：
 
 ```bash
-llman-sdd graph <change-id>              # 该变更 + 直接关系（depth 1）
+llman-sdd graph <change-id>              # 该 change + 直接关系（depth 1）
 llman-sdd graph <change-id> --depth 3    # 递归 3 层
-llman-sdd graph <change-id> --depth 0    # 仅该变更自身
+llman-sdd graph <change-id> --depth 0    # 仅自身
 ```
 
-seed 模式沿 upstream（depends_on）、downstream（被谁依赖）、blocks 三个方向遍历，自动发现活跃和已归档变更。
+沿 upstream（depends_on）、downstream（被谁依赖）、blocks 三方向遍历，自动发现活跃与已归档 change。
 
-**全局视图（scope 模式）：** 按范围展示所有变更。
+**全局视图（scope 模式）**——以 scope 内节点为根，沿 `depends_on` 展开一层（depth 1，缺省），避免无限依赖链；`--depth` 同样约束全图模式：
 
 ```bash
-llman-sdd graph                          # 所有活跃变更（默认）
-llman-sdd graph --scope archived         # 所有已归档（已完成）变更
-llman-sdd graph --scope all              # 全部
+llman-sdd graph                          # 活跃 change + 直接依赖（depth 1 缺省）
+llman-sdd graph --scope archived         # 已归档 + 直接依赖
+llman-sdd graph --scope all              # 全部 + 直接依赖
+llman-sdd graph --depth 0                # 仅 scope 内节点（不拉依赖 target）
+llman-sdd graph --depth 3                # 依赖链递归展开 3 层
 ```
 
 ## 输出
 
-- 输出为 mermaid flowchart 到标准输出，可管道到文件或渲染器：
+- mermaid flowchart 到 stdout，可管道到文件或渲染器：
   ```
   llman-sdd graph c50 > deps.mmd
   llman-sdd graph c50 --depth 2 | mmdc -i - -o deps.png
   ```
-- 已归档（已完成）变更以 "✓ done" 后缀和绿色高亮显示。
-- 当图中存在互不相连的分组时，每组渲染为独立的 subgraph，标注 "Active"、"Done" 或 "Mixed"。
+- 已归档 change 以 "✓ done" 后缀和绿色高亮显示；互不相连的分组各渲染为独立 subgraph，标注 "Active" / "Done" / "Mixed"。
 
-## 提案 frontmatter 格式
+## 依赖声明（proposal frontmatter）
 
 ```yaml
 ---
@@ -61,14 +49,8 @@ depends_on:
 blocks:
   - blocked-change-id
 ---
-
-## Why
-...
 ```
 
-> 💡 这只是辅助工具 — 主流程：`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/cli-footer") }}
 
 {{ unit("skills/ethics-governance") }}

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

@@ -1,119 +1,105 @@
 ---
 name: "llman-sdd-propose"
-description: "创建带规划工件（proposal/tasks；先 `change start`/`attach` 完成 Branch binding，再在绑定分支编辑 live specs/feature）的 llman SDD 变更提案。用于 MUST/SHALL 行为合约变更。"
+description: "为 MUST/SHALL 行为合约变更创建提案（proposal/tasks → 绑定分支 → 落地 specs）。小改动走 quick，记想法走 draft。"
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Propose
 
-创建一个带规划工件的新 change（proposal + tasks；design 可选），**先** `change start`（或 `attach`）完成 Branch binding，**然后**在绑定分支上编辑 live `llmanspec/specs/<capability>.feature`（扁平，或目录主文件）（Specs landing）、校验，并建议下一步。
+创建带规划文档的新 change（proposal + tasks；design 可选）：**先** `change start`（或 `attach`）绑定分支，**再**在绑定分支编辑 `llmanspec/specs/<capability>.feature`（扁平，或目录主文件）落地 specs、校验，并建议下一步。
 
 ## Pipeline 位置
 
 {{ unit("skills/git-native-flow") }}
 {{ unit("skills/human-readable-summary") }}
 
-### Skill 导航（非生命周期；仅指示当前 skill）
-
 ```mermaid
 flowchart LR
-    explore["llman-sdd-explore<br/>探索"] --> propose
-    propose["★ llman-sdd-propose ★<br/>提案（Branch binding + Specs landing）"]
-    propose --> apply["llman-sdd-apply<br/>实施"]
-    apply --> verify["llman-sdd-verify<br/>验证"]
-    verify --> archive["llman-sdd-archive<br/>归档"]
+    explore["llman-sdd-explore"] --> propose["★ llman-sdd-propose"]
+    propose --> apply["llman-sdd-apply"]
+    apply --> verify["llman-sdd-verify"]
+    verify --> archive["llman-sdd-archive"]
 
     style propose fill:#fff3cd,stroke:#ffc107,stroke-width:3px
 ```
 
-> 📍 你现在在 propose 阶段：上方 Git-native 路径为 **规划壳（draft → designed → planned）→ Branch binding → Specs landing**（直到 `readyToImplement=true`）→ 下一步：`llman-sdd-apply`
-> 📎 小改动（不改行为合约）请走 `llman-sdd-quick`（快速路径）
+> 📍 你在 propose 阶段：规划文档（draft → designed → planned）→ 绑定分支 → 落地 specs（至 specs-landed 门通过）→ 下一步 `llman-sdd-apply`。小改动走 `llman-sdd-quick`。
 
 ## 硬约束
 
-- **change id 非阻塞**：用户已给出 id 则直接采用；否则从任务描述推导一个合法 kebab-case id（动词前缀开头，通过 CLI 的 id 合法性检查，并遵循 `llmanspec/AGENTS.md` 声明的命名约定），宣布所用 id 与覆盖方式后继续，MUST NOT 等待确认——Branch binding 前更换 id 成本很低。仅当用户想先记 idea（草案、无需 id）时转 `llman-sdd-draft`。
-- **Live specs 是 SSOT**：只在 Branch binding **之后**、在**绑定的非默认分支**上编辑 `llmanspec/specs/**`（Specs landing）。**不要**在默认分支上改 live specs；**不要**在 `changes/<id>/specs/` 下撰写或使用 `change delta`（已移除）。规划壳可以短暂留在默认分支。
-- **不要问「要不要继续」**：一口气执行完整 propose 阶段，生成工件并校验。
+- **change id 非阻塞**：用户给了就用；否则从任务描述推导合法 kebab-case id（动词前缀，过 CLI id 检查，遵循 `llmanspec/AGENTS.md` 命名约定），宣布所用 id 与覆盖方式后继续，MUST NOT 等确认——绑定分支前换 id 成本很低。只想先记 idea（不要 id）时转 `llman-sdd-draft`。
+- **specs 是唯一事实来源**：只在绑定分支**之后**、在**绑定的非默认分支**上编辑 `llmanspec/specs/**`。**不要**在默认分支改 specs。规划文档可短暂留在默认分支。
+- **不要问「要不要继续」**：一口气执行完 propose，生成工件并校验。
 {% if extra_skill_continue %}
-- **change 已存在**：STOP。若 `readyToImplement=true`，建议 `llman-sdd-apply`；否则用 `llman-sdd-continue` 补完 Branch binding / Specs landing 或规划壳。
+- **change 已存在**：STOP。specs-landed 门已绿 → 建议 `llman-sdd-apply`；否则用 `llman-sdd-continue` 补绑定分支 / 落地 specs 或规划文档。
 {% else %}
-- **change 已存在**：STOP。若 `readyToImplement=true`，建议 `llman-sdd-apply`；否则补完规划壳 / Branch binding / Specs landing（编辑 `llmanspec/changes/<id>/`，或在配置启用 `extra_skills: [llman-sdd-continue]`）。
+- **change 已存在**：STOP。specs-landed 门已绿 → 建议 `llman-sdd-apply`；否则补规划文档 / 绑定分支 / 落地 specs（编辑 `llmanspec/changes/<id>/`，或配置 `extra_skills: [llman-sdd-continue]`）。
 {% endif %}
-- **frontmatter 有固定 schema**：充实 `proposal.md` 时只接受 `llmanspec/AGENTS.md`「Change Proposal Frontmatter SSOT」中的合法字段（含 `depends_on`、`blocks`、`branch`、`base_sha`、`needs_specs_change`）。`status`/`title`/`priority`/`author` 等会被 `llman-sdd validate` 报 ERROR 拒绝；生命周期阶段是推断量（用 `llman-sdd show`/`list` 查询），绝不写进 frontmatter。正文 MUST NOT 复读 frontmatter 字段；正文 H1 是人类可读标题，不是 change id 的复读。
+- **frontmatter 有固定 schema**：`proposal.md` 只接受 `llmanspec/AGENTS.md`「Change Proposal Frontmatter SSOT」的合法字段（`depends_on`、`blocks`、`branch`、`base_sha`、`needs_specs_change` 等）；`status`/`title`/`priority`/`author` 会被 `llman-sdd validate` 报 ERROR。生命周期阶段是推断量（用 `llman-sdd show`/`list` 查），绝不写进 frontmatter。正文 MUST NOT 复读 frontmatter 字段；H1 用人类可读标题，不复读 change id。
 
 ## 快速记录分流
 
-若用户只是想**记一个 idea**（如「draft 一个提案」「记下 X」「之后要做 Y」）而不需要完整规划，转 `llman-sdd-draft` skill——它经 `change new --from` 创建仅含 `proposal.md` 的草案壳（不问 id、无 tasks/specs/attach）。完整 propose（triage + tasks → `change start`/`attach` → Specs landing）从这里开始。
+只想**记一个 idea**（「draft 一个提案」「记下 X」「之后要做 Y」）→ `llman-sdd-draft`：经 `change new --from` 建仅含 `proposal.md` 的草案（不问 id、无 tasks/specs/attach）。完整 propose 从这里开始。
 
 ## 步骤
 
 ### 0) 预检
 - 读 `llmanspec/config.yaml` 获取项目上下文、规则、locale。
-- `llman-sdd validate --all --strict --no-interactive`：确认现有工件干净。
-  - 若已有错误，STOP 并报告（在脏工件上叠新 change 会造成级联错误）。
-- **检查 spec valid_scope 完整性**：用 `llman-sdd list --specs --json` 列出全部 specs，逐个核对其 `valid_scope` 中的路径在磁盘上是否存在。任何 scope 文件/目录缺失时，STOP 并建议更新该 spec（从 `valid_scope` 移除已删除的路径）。
-
-### 1) 评估 change 规模（triage）
-1. 判定类型：
-   - **行为合约变更**（修改 MUST/SHALL、改变外部行为）→ 完整 SDD 工作流
-   - **实现层变更**（重构、typo、性能）→ 走 `llman-sdd-quick` 快速路径
-   - **元规范变更**（SDD 模板/流程）→ 完整 SDD 工作流
-   - 不确定时选完整 SDD（保守）。
+- `llman-sdd validate --all --strict` 确认现有工件干净；有错误则 STOP 并报告（脏工件上叠新 change 会级联出错）。
+- **检查 spec valid_scope 完整性**：`llman-sdd list --specs --json` 列出全部 specs，逐个核对 `valid_scope` 路径在磁盘上存在；有缺失则 STOP 并建议更新该 spec（移除已删路径）。
+
+### 1) 判断变更规模
+1. 分类：
+   - **行为合约变更**（改 MUST/SHALL、改外部行为）→ 完整 SDD
+   - **实现层变更**（重构、typo、性能）→ `llman-sdd-quick`
+   - **元规范变更**（SDD 模板/流程）→ 完整 SDD
+   - 不确定选完整 SDD（保守）。
 2. 用 `llman-sdd context --task "<目标>" --paths "<范围>"` 找相关 specs。
-   - context 不可用时，跑 `llman-sdd index rebuild`（默认 `pageindex`，无需模型）后继续。
-3. 收集输入：
-   - 一段简短的变更描述
-   - 一个 change id（用户给出则用之；否则按上面的非阻塞规则推导并宣布）
-   - 受影响的 capability（用于命名 `specs/<capability>`）
+   - context 不可用 → 先 `llman-sdd index check`：stale/缺失则 `llman-sdd index rebuild`（默认 pageindex，免模型）后重试；fresh 仍不可用（`LLMAN_SDD_INDEX_CHAT_MODEL` 未设）→ 改用 `llman-sdd list --specs` + 直读 `.feature`——勿循环 rebuild。
+3. 收集输入：简短变更描述；change id（用户给了就用，否则按非阻塞规则推导并宣布）；受影响 capability（命名 `specs/<capability>`）。
 
 ### 2) 确认项目已初始化
-   - `llmanspec/` 必须存在；若缺失，让用户运行 `llman-sdd init`，然后 STOP。
+- `llmanspec/` 必须存在；缺失则让用户跑 `llman-sdd init`，然后 STOP。
 
 ### 3) 创建 change 目录与工件
-   - 优先用 `llman-sdd change new <change-id>` 生成 `proposal.md` 草案壳（或手动创建 `llmanspec/changes/<change-id>/`）。
+- 优先 `llman-sdd change new <change-id>` 生成 `proposal.md` 草案（或手动建 `llmanspec/changes/<change-id>/`）。
 {% if extra_skill_continue %}
-   - change 已存在时，STOP 并建议 `llman-sdd-continue`。
+- change 已存在时 STOP 并建议 `llman-sdd-continue`。
 {% else %}
-   - change 已存在时，STOP 并建议补齐缺失工件或 `llman-sdd-apply`（可通过 `extra_skills` 启用 continue）。
+- change 已存在时 STOP 并建议补齐缺失工件或 `llman-sdd-apply`（可经 `extra_skills` 启用 continue）。
 {% endif %}
-   - 充实 `proposal.md`（Why / What Changes / Capabilities / Impact）
-   - 仅当存在权衡/迁移时写 `design.md`
-   - **写 tasks.md 前确认测试边界（seam，接缝）**：列出将要测试的 seam 并与用户确认。seam = 由 `*.feature` GWT 步骤驱动的公共边界（CLI 子进程或公共接口）——MUST 复用既有 harness seam，MUST NOT 脱离 `.feature` 凭空发明 seam。没有 `.feature` 时，seam = 被测的 CLI 子命令或公共函数边界。
-   - `tasks.md`：按**垂直切片**拆分（每个 task 打穿 schema→API→UI→tests 一条窄而完整的路径，可独立验证），并带 `[blocked-by: <task-id>]` 依赖标记。**大范围重构例外**（一个机械改动扫全库、单点编辑牵动大量调用处）：按 expand-contract 排序（旧的旁边加新的 → 分批迁移调用处 → 删掉旧的），不强拆垂直切片。
-   - **先** `llman-sdd change start <change-id>`（推荐；默认分支上工作树干净时）或手动建分支后 `change attach <change-id>` 到达 Full（bound）。
-   - **然后**在绑定的非默认分支上编辑 live `llmanspec/specs/<capability>.feature`（扁平，或目录 `llmanspec/specs/<capability>/` 内主文件）并 commit（Specs landing）。**不要**在 start 之前改 live specs；**不要**为过干净树门禁把 live specs commit 到默认分支。已 attach 时勿重复 `start`（丢失 specs 时用 checkout/重建 + `attach --force` 恢复）。
-   - 无 live 合约编辑的 change，设置 frontmatter `needs_specs_change: false`。仅当 `llman-sdd show <id> --json` 给出 `readyToImplement=true` 才进入 apply。
-   - **破坏性合约变更**（移除/重命名字段、命令、tag 或 stage 值域）MUST 规划升级路径：`migrations/v<from>-v<to>/`（README prompt + 一次性脚本，随仓库发布）——写进提案的 What Changes。
+- 充实 `proposal.md`（Why / What Changes / Capabilities / Impact）；仅当有权衡/迁移时写 `design.md`。
+- **写 tasks.md 前确认测试边界（seam）**：列出要测的 seam 并与用户确认。seam = 由 `*.feature` GWT 步骤驱动的公共边界（CLI 子进程或公共接口）——MUST 复用既有 harness seam，MUST NOT 脱离 `.feature` 凭空发明；没有 `.feature` 时，seam = 被测的 CLI 子命令或公共函数边界。
+- `tasks.md` 按**垂直切片**拆（每个 task 打穿 schema→API→UI→tests 一条窄而完整的路径，可独立验证），带 `[blocked-by: <task-id>]` 依赖标记。**大范围重构例外**（一个机械改动扫全库、单点编辑牵动大量调用处）：按先加后删排序（新的加在旧的旁边 → 分批迁移调用处 → 删旧的），不强拆垂直切片。**tasks.md 只列实现与验证任务**：收口（`change finalize` / `change archive`）是流水线步骤，MUST NOT 列为任务——收口的任务门要求全部任务已勾，列了必然自相矛盾（勾选即虚报、不勾则收口被拒，实施期 `validate --strict` 永红）。前后对比类完成判据（计数、基线）MUST 注明在 change 分支上测量（相对 merge-base）——默认分支测得的值通常恒为基线。
+- **先** `llman-sdd change start <change-id>`（推荐；默认分支上工作树干净时；保留当前检出用 `--worktree`，非默认分叉源用 `--base <branch>`）或手动建分支后 `change attach <change-id>`。
+- **再**在绑定的非默认分支编辑 `llmanspec/specs/<capability>.feature`（扁平，或目录 `llmanspec/specs/<capability>/` 内主文件）并 commit（落地 specs）。**不要**在 start 前改 specs；**不要**为过干净树门禁把 specs commit 到默认分支。已 attach 勿重复 `start`（specs 丢失用 checkout/重建 + `attach --force` 恢复）。
+- 无合约编辑的 change 设 frontmatter `needs_specs_change: false`。`llman-sdd show <id> --output json` 显示 `stage=full` 且 specs-landed 门通过即可进 apply；`readyToImplement=true`（全门）是 verify/finalize 的完成信号。
+- **破坏性合约变更**（移除/重命名字段、命令、tag 或 stage 值域）MUST 规划升级路径：`migrations/v<from>-v<to>/` 下写 README（升级提示；一次性脚本可行时随仓库提供）——写进提案 What Changes。
 
 ### 4) 校验
-   ```bash
-   llman-sdd validate <change-id> --strict --no-interactive
-   ```
-   这一步 MUST 通过后才能继续。若出现 TOON 解析错误，修复引号：表格式行中含逗号/冒号/括号的值必须加双引号。
+```bash
+llman-sdd validate <change-id> --strict
+```
+MUST 通过才能继续；失败项在 validate 输出的 `items[].issues[]` 逐条指明，按条修复后重跑。
 
 ### 4a) 可选 BDD runner（`bdd:` 段）
-- 读 `llmanspec/config.yaml`。是否含 `bdd:` 段？
-  - **有**：`validate --check` 会跑 harness；撰写仍按 4b 执行。
-  - **无**：若本次 change 涉及可执行行为场景（用户会想运行的 Given/When/Then），**一次性、前置**询问：「本次变更看起来有可执行行为。要启用 `bdd:` runner 段以便把场景作为 `.feature` 校验吗？（会向 `config.yaml` 加一个 `bdd:` 段——仅 runner，不改变生命周期。）」
-    - **是**：展示要添加的精确 `bdd:` 段（`run_command` 选匹配项目测试框架的——rstest-bdd 用 `cargo test --features bdd`，pytest-bdd 用 `pytest {feature_dir} -k {feature_name} -v`）。让用户确认或修改后写入 `config.yaml`，再按 4b 规则继续。
-    - **否**：feature 仍做结构校验；仅跳过 runner 执行。
-- **MUST NOT 静默添加 `bdd:` 段**——总是先询问。添加它会改变全项目 `validate --check` 的行为。
+- 读 `llmanspec/config.yaml` 是否含 `bdd:` 段：
+  - **有**：`bdd.run_command` 是项目的 BDD 执行入口；validate 在目标集含 spec 时缺省执行它（`--no-check` 跳过）。撰写仍按 4b。
+  - **无**：若本次 change 含可执行行为场景（用户会想运行的 Given/When/Then），**一次性前置**询问是否启用 `bdd:` runner 段（会向 `config.yaml` 加一个 `bdd:` 段——仅 runner，不改生命周期）。**是**：展示要加的精确 `bdd:` 段（`run_command` 选匹配项目测试框架的——rstest-bdd 用 `cargo test --features bdd`，pytest-bdd 用 `pytest {feature_dir} -k {feature_name} -v`），用户确认或修改后写入 `config.yaml`，再按 4b 继续。**否**：feature 仍做结构校验；BDD 执行责任始终在项目测试套件。
+- **MUST NOT 静默添加 `bdd:` 段**——总是先问。添加它会向全项目声明 BDD 执行入口。
 
 ### 4b) 单轨 feature 撰写
-- 规划壳（proposal/design/tasks）可短暂留在默认分支；**不要**在默认分支上编辑 live `llmanspec/specs/**`。Branch binding 之后，Specs landing 与实现都发生在绑定分支上。
-- **单轨**：每个 capability 只有一个 `<capability>.feature`。约束规则是 `@req:<id> @human` 场景（statement 全文放描述）；可执行验收场景带 `@executable` 并用 `@req:<req_id>` 挂回规则。绝不把场景嵌进 `Rule:` 块（runner 会静默跳过其中场景）。
-- change 壳：`llman-sdd change new <change-id>` → 填 proposal/design/tasks → `llman-sdd change start <change-id>`（或 `change attach`）→ **然后**在绑定分支编辑 live specs 并 commit（Specs landing）。
-- **不要**使用 `change delta` / solidify / `*.feature.delta.toon`；存在活跃 `*.feature.delta.toon` 或遗留 `spec.toon` 时，先跑 `llman-sdd project migrate --kind toon2features`。
+- 规划文档可短暂留在默认分支；**不要**在默认分支编辑 `llmanspec/specs/**`。绑定分支后，落地 specs 与实现都在绑定分支上。
+- **单轨**：每个 capability 只有一个 `<capability>.feature`。规范样式为原生 Gherkin 分层：`@req:<id>` 挂 `规则:` 块头，块内嵌套 `场景:`（假如/当/那么 步骤，绑定 runner 步骤代码并被执行——**默认首选形态**）；仅当需求无法程序化表达（抽象目标、架构决策、治理/人工约束）或暂不转写时，才留下无嵌套场景的 `规则:` 块（裸规则，描述自由文本）并在 proposal/design 记录理由。历史标签（@executable/@rule/@human/@manual）不再使用。
+- **描述可读性**：`规则:` 描述较长时拆成多行便于审查（官方解析器按行保留）；描述行不加 `- ` 列表前缀（会原样进入描述），也不得以 `假如/当/那么/而且`（en `Given/When/Then/And/But`）开头——会被 Gherkin 解析为步骤。
+- **结构化新增首选**：向既有 capability 追加规则/场景，优先 `llman-sdd spec next-req-id`（全局 rN 分配）+ `spec add-req`（追加 `规则:` 块）+ `spec add-scenario`（向规则块插入嵌套 `场景:`）。新建 capability 用 `spec skeleton <capability>`；rN 反查用 `spec resolve-req <rN>`。旧式标签文件先 `spec migrate-native`。手改 `.feature` 保留为逃生门（适合改既有条款）。
+- **可执行场景优先判据**（写新条款前先判定）：凡 GWT（假如/当/那么）可表达、绑定步骤代码的自动化判定行为 MUST 落成嵌套 `场景:`——纯文字规则无行为守护。用例如下：行为可程序判定（如「当 运行 validate 后,那么 stdout 为 TOON 且退出码为 0」）→ 嵌套 `场景:`；抽象目标/架构决策暂不可程序判定 → 裸 `规则:` 块（无嵌套场景，聚合计数提示，交 specs-compact），并在 proposal/design 记录理由。
 
 ### 5) 总结并建议下一步
-   - 进入实现阶段：`llman-sdd-apply`。
-   - 需要再想清楚：`llman-sdd-explore`。
-
-> 💡 提案完成 → 下一步：`llman-sdd-apply`（实施）
+- 进入实现：`llman-sdd-apply`；需要再想清楚：`llman-sdd-explore`。
 
-> 命令细节用 `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") }}
 
 {{ unit("skills/structured-protocol") }}