@llman-sdd/core 0.1.0 → 0.1.2

package/templates/en/units/migrate-prompt.md

@@ -0,0 +1,28 @@
+# llman sdd project migrate — collaboration notes
+
+## Command intent
+
+- `llman sdd project migrate --kind toon2features`: legacy `spec.toon` → single-track `.feature` (one-shot, idempotent).
+- `llman sdd project migrate --kind specs-flatten`: pure single-file directories `specs/<cap>/<cap>.feature` → flat `specs/<cap>.feature` (git mv preserves history).
+
+## What the agent does
+
+- First confirm migration is actually needed (no legacy / single-file dirs → no-op).
+- Run `--dry-run` first and read the precheck report; resolve `conflict` / `misnamed` entries manually — never force.
+- After migrating, run `llman sdd validate --specs --strict --no-interactive` and the project BDD suite.
+
+## What the human does
+
+- Review the `scope_rewritten` report and the git diff (moves keep history).
+- Optionally point `# scope:` at the real source directory the spec governs.
+
+## Pitfalls
+
+- Dirs with multiple `.feature` files, foreign-named files, or auxiliary entries are NOT flattened (reported only).
+- Name conflicts must be resolved manually (both files are kept).
+- Self-referential `# scope:` entries are auto-rewritten to `specs/<cap>.feature`.
+
+## Next steps
+
+- `llman sdd validate --specs --strict --no-interactive`
+- project BDD run (e.g. `cargo test --features bdd`)

package/templates/en/units/skills/ethics-governance.md

@@ -0,0 +1,6 @@
+## Ethics Governance
+- `ethics.risk_level`: low — reads/writes this repo and `llmanspec/` only, no outward-facing actions; a skill body may override.
+- `ethics.prohibited_actions`: actions violating the skill body's hard rules; push / PR / external upload without an explicit user request.
+- `ethics.required_evidence`: conclusions backed by command output or file paths; gate state per `llman sdd validate`.
+- `ethics.refusal_contract`: gate CRITICAL not cleared → refuse to advance; self-repair cap reached → report a blocker.
+- `ethics.escalation_policy`: pause and ask the user before changing SDD contracts/templates or irreversible actions.

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

@@ -0,0 +1,9 @@
+## Git-native lifecycle (brief)
+
+Do not conflate **skill navigation** with the **Git-native lifecycle**. Full diagram: root `AGENTS.md` or the diagram inside `llman-sdd-propose`.
+
+Hard rules:
+1. **First** Branch binding (`change start` / `attach`) → Full; **then** Specs landing (edit and commit `llmanspec/specs/**` on the bound branch).
+2. No live contract edits → `needs_specs_change: false`. Apply requires `readyToImplement=true`.
+3. Close-out: `change finalize` (auto commit `archive(sdd): <id>`; `--no-commit` to skip). `change checkpoint` is removed (calling it exits non-zero and points to finalize).
+4. **Do not** commit live specs on the default branch; if already attached, do not re-run `start`.

package/templates/en/units/skills/git-native-flow.md

@@ -0,0 +1,40 @@
+## Git-native lifecycle (full diagram)
+
+Do not conflate two layers: the **Git-native lifecycle** (Branch binding → Specs landing → `readyToImplement`) vs **skill navigation** (explore→propose→apply→verify→archive). Specs landing is **not** a separate skill.
+
+```mermaid
+flowchart TB
+  subgraph main_ok["OK briefly on default branch"]
+    A["change new → draft<br/>proposal.md only"]
+    B1["add design.md → designed"]
+    B2["add tasks.md → planned"]
+  end
+
+  subgraph gate_start["Branch binding"]
+    C{"Clean tree<br/>and on default branch?"}
+    D["change start<br/>create sdd/&lt;id&gt; + write branch/base_branch/base_sha"]
+    E["or manual checkout -b<br/>then change attach"]
+  end
+
+  subgraph specs_only["Only on this change branch"]
+    F["Edit live llmanspec/specs/** (.feature)"]
+    G["commit → Specs landing<br/>live merge-base...HEAD includes specs paths"]
+  end
+
+  subgraph implement["Implement"]
+    H["apply: code per tasks<br/>may keep editing specs"]
+    I["verify"]
+    J["finalize<br/>merge (squash default) → rename → auto commit archive(sdd): &lt;id&gt;<br/>specs first hit default branch"]
+  end
+
+  A --> B1 --> B2 --> C
+  C -->|yes| D --> F
+  C -->|already on feature| E --> F
+  F --> G --> H --> I --> J
+```
+
+Hard rules:
+1. **First** `change start` / `attach` (Branch binding) to enter Full; **then** edit `llmanspec/specs/**` on the bound non-default branch and commit (Specs landing).
+2. For changes with no live contract edits, set frontmatter `needs_specs_change: false`. Enter apply only when `llman sdd show <id> --json` has `readyToImplement=true` — `Full ∧` every `gateChecks` item passes (specs-landed = `specsLanded ∨ needs_specs_change=false`; ranges are live merge-bases, stored `base_sha` is audit-only).
+3. `change checkpoint` is removed (no mid-flight archive point; `change finalize` does not require a clean tree). Close-out is `llman sdd change finalize <id>`: it auto-commits `archive(sdd): <id>` (impl diff + rename in one commit); `--no-commit` skips the auto commit for manual/CI histories. Commits on the change branch are free (segmented or finalize single-shot).
+4. **Do not** commit live specs to the default branch just to satisfy the clean-tree gate; if already attached, do not re-run `start`.

package/templates/en/units/skills/human-readable-summary.md

@@ -0,0 +1,10 @@
+# Human-Readable Summary (mandatory)
+
+Every report, handoff, or gate output you produce in this workflow MUST open
+with a short human-readable summary block before any machine detail:
+
+- **Verdict** — one line (e.g. "all gates green" / "2 CRITICAL found").
+- **Risks** — up to three bullets, highest impact first.
+- **Decisions needed** — explicit asks, or "none".
+
+Keep it under ten lines; details belong below the fold.

package/templates/en/units/skills/stage-guard.md

@@ -0,0 +1,17 @@
+## Stage guard (`stage` / `readyToImplement`)
+
+Decide from authoritative JSON (never from vague "complete artifacts" wording):
+
+```bash
+llman sdd show <id> --json --type change
+```
+
+Read: `stage`, `specsLanded`, `needsSpecsChange`, `readyToImplement`, `gateChecks` (per-item `pass` + one-line `hint` when failing).
+
+| Condition | Action |
+|-----------|--------|
+| `stage=draft` (proposal.md only) | STOP. Grow to Designed (add design.md) → Planned (add tasks.md) → Branch binding → Specs landing. Draft cannot apply/verify. If proposal+design+tasks exist but stage is still `draft`: tasks-without-design — add design.md first. **Do not** create `changes/<id>/specs/`; **do not** edit live specs on the default branch first. |
+| `stage=designed` (proposal + design) | Next: add tasks.md → `planned`. Run `change start` / `attach` (Branch binding) only after planning artifacts are complete. |
+| `stage=planned` (proposal + design + tasks) | STOP until binding: run `change start` / `attach` (Branch binding) → `full`. |
+| `stage=full` and `readyToImplement=false` | STOP. Finish Specs landing on the **bound branch** (edit `llmanspec/specs/**` and commit), or set `needs_specs_change: false`. **Do not** re-run `change start`. If specs on the bound branch were lost → checkout/recreate + `attach --force` if needed. |
+| `readyToImplement=true` | Pass apply/verify prerequisites. `changes/<id>/specs/` is expected to be **absent** — do not treat as missing. |

package/templates/en/units/skills/structured-protocol.md

@@ -0,0 +1,27 @@
+## Context
+- Check state before acting: change/spec status comes from `llman sdd show/list/validate` output.
+- Locate relevant specs with `llman sdd context --task --paths` before reading spec files.
+
+## Goal
+- Reach one verifiable outcome for this command; report result paths and validation state.
+
+## Constraints
+- Follow the hard rules in the skill body (not repeated here). Triage first: behavior-contract changes take the full SDD path, implementation-only changes take quick; when unsure choose full SDD.
+- Keep changes minimal; never force past a known validation failure.
+
+## Workflow
+- Treat `llman sdd` command output as the source of truth at every step; run `llman sdd validate` after touching artifacts.
+- Command details: the generated command reference below, or `llman sdd <cmd> --help`.
+
+## Decision Policy
+- Clarify high-impact ambiguity before proceeding; verify facts yourself, ask the user only for decisions.
+
+## Output Contract
+- Human-readable summary first (conclusion / risks / decisions needed), machine detail after.
+
+## Ethics Governance
+- `ethics.risk_level`: low — reads/writes this repo and `llmanspec/` only, no outward-facing actions; a skill body may override.
+- `ethics.prohibited_actions`: actions violating the skill body's hard rules; push / PR / external upload without an explicit user request.
+- `ethics.required_evidence`: conclusions backed by command output or file paths; gate state per `llman sdd validate`.
+- `ethics.refusal_contract`: gate CRITICAL not cleared → refuse to advance; self-repair cap reached → report a blocker.
+- `ethics.escalation_policy`: pause and ask the user before changing SDD contracts/templates or irreversible actions.

package/templates/en/units/skills/validation-hints.md

@@ -0,0 +1,24 @@
+Validation fixes (single-track feature-as-spec):
+
+1) Missing header comments (`missing `# capability:`` header comment`):
+Every capability `.feature` (`llmanspec/specs/<capability>.feature` or `llmanspec/specs/<capability>/<capability>.feature`) MUST start with:
+```
+# language: zh-CN
+# capability: <capability>
+# purpose: One-line overview.
+# scope: src/
+```
+
+2) Tag grammar (`@human constraint scenario must carry an @req:<req_id> tag` / `orphan acceptance scenario`):
+- Rules: `@req:<id> @human` — statement in the scenario description (MUST/SHALL required).
+- Acceptance: `@executable` + at least one `@req:<id>` linking a rule.
+- `@manual` requires `@human`. Never combine `@human` with `@executable`.
+
+3) Legacy `spec.toon` present (`legacy spec.toon found ... run ... toon2features`):
+Run `llman sdd project migrate --kind toon2features --yes`, review the diff, commit.
+
+Git-native guardrail:
+- **Branch binding** → **Specs landing**: first `change start` / `attach`, then edit live `.feature` files on the bound non-default branch and commit.
+- Locked rules (report-only): editing/removing an existing `@human` scenario yields a WARNING and never blocks validate / change finalize / change diff; the report names the edited rule by `@req:<id>`. Control points: git branch diff plus `llman sdd review` / `change diff` output. Legacy lock-ack metadata (frontmatter `rules_touched` / `agent_acked`, the `@agent` tag, the `--yes` ack semantics) is fully removed — no aliases, no compat layer (locked rules are report-only: a warning, never a block).
+- Apply requires `readyToImplement=true` (or `needs_specs_change: false`). Close-out prefers `change finalize`.
+- Do not use `change delta` / solidify / `*.feature.delta.toon`.

package/templates/en/units/spec/feature-contract.md

@@ -0,0 +1,29 @@
+## Canonical Single-Track Feature Contract
+
+Each capability is ONE Gherkin file: flat `llmanspec/specs/<capability>.feature` (default) or directory `llmanspec/specs/<capability>/` with a same-named main file — pick one layout, both at once is a conflict.
+It is the only spec artifact — there is no `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
+```
+
+- Header comments (`# capability:` / `# purpose:` / `# scope:`) are REQUIRED; `scope` drives staleness.
+- `@human` scenarios are human-owned constraints; their description carries the normative statement verbatim. Editing/removing them yields a WARNING only (report-only, never blocks a gate) — compare via git branch diff; the legacy lock-ack metadata `rules_touched` / `agent_acked` / `@agent` is removed with no aliases and no compat layer (locked rules are report-only: a warning, never a block).
+- `@executable` scenarios are runner-bound acceptance; they link rules via `@req:<req_id>`.
+- Coverage tiers: enforced (has acceptance) / manual (`@manual`) / pending. `list --specs` reports all three.
+- Scenarios MUST stay top-level: `Rule:` blocks are rejected (the runner skips them silently).

package/templates/en/units/workflow/archive-freeze-guidance.md

@@ -0,0 +1,6 @@
+## Archive Cold Backup Guidance
+- If archived directories are growing too large, use cold backup maintenance:
+  - Preview freeze candidates: `llman sdd archive freeze --dry-run`
+  - Freeze old archives: `llman sdd archive freeze --before <YYYY-MM-DD> --keep-recent <N>`
+  - Restore when needed: `llman sdd archive thaw --change <YYYY-MM-DD-id>`
+- Apply freeze/thaw only to dated archive directories (`YYYY-MM-DD-*`) and keep a small recent window unfrozen when possible.

package/templates/shared/review.html

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>llman sdd review — __GENERATED__</title>
+<style>
+  body { font-family: system-ui, sans-serif; margin: 2rem; }
+  .critical { color: #b91c1c; font-weight: 700; }
+  .warning { color: #b45309; }
+  table { border-collapse: collapse; margin: 1rem 0; }
+  td, th { border: 1px solid #ccc; padding: .3rem .6rem; }
+  pre.mermaid { background: #f8f8f8; padding: 1rem; white-space: pre; }
+</style>
+</head>
+<body>
+<h1>llman sdd review</h1>
+<p>critical=<span class="critical">__CRITICAL__</span>
+   warning=<span class="warning">__WARNING__</span></p>
+<h2>Signals</h2>
+<table id="signals">
+  <tr><th>kind</th><th>capability</th><th>count</th><th>detail</th></tr>
+</table>
+<h2>Graph</h2>
+<pre class="mermaid">
+__MERMAID__
+</pre>
+<script>
+  // Offline, dependency-free fill. If a mermaid runtime is present in the host
+  // page context it may render the <pre class="mermaid"> block; otherwise the
+  // text graph remains readable. This file stays a single self-contained
+  // artifact either way (sdd-review r51: no external resources, no local server).
+  const SIGNALS = __SIGNALS__;
+  const tbody = document.querySelector('#signals');
+  for (const s of SIGNALS) {
+    const tr = document.createElement('tr');
+    for (const v of [s.kind, s.capability, String(s.count), s.detail]) {
+      const td = document.createElement('td');
+      td.textContent = v;
+      tr.appendChild(td);
+    }
+    tbody.appendChild(tr);
+  }
+</script>
+</body>
+</html>

package/templates/zh-Hans/agents-root-stub.md

@@ -0,0 +1,9 @@
+# LLMAN 规范驱动开发
+
+本项目使用 llman SDD。阅读 `llmanspec/config.yaml` 了解 SDD 命令行为配置，以及 `llmanspec/AGENTS.md` 获取项目附加规则。
+
+## SDD 流水线
+
+使用 `/llman-sdd-explore` 开始，然后按照 pipeline：`/llman-sdd-propose` → `/llman-sdd-apply` → `/llman-sdd-verify` → `/llman-sdd-archive`。
+
+保留此托管块，便于 `llman sdd init --update` 刷新。

package/templates/zh-Hans/llmanspec-agents-stub.md

@@ -0,0 +1,6 @@
+# llmanspec AGENTS.md
+
+此文件由根目录的 `AGENTS.md` 托管块引用。可在此添加项目特定的规则、
+上下文或约定，以便 AI 代理遵守。
+
+<!-- 在此行下方添加你的规则 -->

package/templates/zh-Hans/skills/llman-sdd-apply-cycle.md

@@ -0,0 +1,75 @@
+---
+name: "llman-sdd-apply-cycle"
+description: "单个变更的闭环：门禁检查→实施→测试→校验→verify 建议→归档→提交。仅手动触发。Agent MUST NOT 自动调用。"
+metadata:
+  version: "{{ llman_version }}"
+disable-model-invocation: true
+---
+
+# LLMAN SDD Apply Cycle
+
+单个变更端到端闭环（手动）。须已 Branch binding 且 `readyToImplement=true`。
+
+**仅手动触发**：`/skill:llman-sdd-apply-cycle <change-id>`
+
+## 工作流
+
+### 0) 门禁 + 状态
+```bash
+llman sdd show <change-id> --json --type change
+```
+> 阶段判定：用 `llman sdd show <id> --json --type change` 的 `stage` / `readyToImplement` 字段；完整判定表见 llman-sdd-apply。
+
+- 须在绑定的非默认分支上。
+- `readyToImplement` 不为 true → STOP（先 Specs landing 或 `needs_specs_change: false`）；**不要**直接 finalize。
+- 进度以 `tasks.md` checkbox 为准（或 `llman sdd list` 的任务计数）；实现时仍须阅读 `tasks.md`、proposal/design 与绑定分支上的 live `llmanspec/specs/**`（SSOT）。
+
+### 1) 循环：实施 → 测试
+对每个未完成 task：
+1. 按 task + live specs 实现（最小改动）
+2. 运行 `tasks[].test`（若有）
+3. 失败则修复重试（自修复预算与 `llman-sdd-apply` 一致：上限 8 轮）
+4. 勾选 `tasks.md` 为 `[x]`
+
+### 2) 校验
+```bash
+llman sdd validate <change-id> --strict --no-interactive
+```
+失败则修复重试（自修复预算与 `llman-sdd-apply` 一致：上限 8 轮）。
+
+### 3) Verify（推荐）
+优先跑 `llman-sdd-verify`（或等效双轴自检）。有 CRITICAL → STOP，勿归档。
+
+### 4) 归档
+```bash
+llman sdd change finalize <change-id>
+```
+（工作区可脏；自动合并（squash 缺省）+ 文档改名 + **自动提交** `archive(sdd): <change-id>` 单进程完成。`--no-commit` 跳过自动提交用于手动/CI 历史——此时自行 `git add -A && git commit -m "archive(sdd): <change-id>"`。）
+
+`change checkpoint` 已移除；普通 `change archive` 命令保留为 fallback（不再要求任何 checkpointed 字段）。
+
+### 5) 提交（见步骤 4）
+finalize 已自动提交，除非传了 `--no-commit`。
+
+### 6) 可选清理
+```bash
+git branch -D <feature-branch>   # squash 后分支不再是 main 祖先，-d 会被拒绝
+```
+push / Hosting PR 仅当用户明确要求。
+
+## 硬约束
+- **禁止询问**「要不要继续」——除非 blocker，否则一路到底。
+- **禁止切换**其他 change，直到本 change 已归档并提交。
+- **重试上限**：自修复遵循 `llman-sdd-apply` 的 8 轮预算（含 diagnose 升级路径）。
+- **禁止**写 `changes/<id>/specs/` 或 `change delta`。
+- **禁止默认 push/PR**。
+
+## Ethics Governance
+- `ethics.risk_level`: medium
+- `ethics.prohibited_actions`: 未 `readyToImplement` 就实施/归档、切换其他 change、写 `changes/<id>/specs/`、未校验就提交、默认 push/PR
+- `ethics.required_evidence`: `readyToImplement=true`、validate --strict 通过、tasks 全勾、finalize/archive 成功
+- `ethics.refusal_contract`: 门禁或校验自修复 8 轮仍失败 → 报告 blocker，禁止强行归档
+- `ethics.escalation_policy`: 若改动 SDD 工作流 spec/模板，归档前暂停请用户确认
+
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。

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

@@ -0,0 +1,126 @@
+---
+name: "llman-sdd-apply"
+description: "在一个闭环内实施 llman SDD 变更的 tasks：写代码 → 跑测试 → 失败自修复 → 直到门禁全绿。自动更新 tasks.md 勾选状态并运行校验。用于提案完成后的实现阶段。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Apply
+
+使用此 skill 在**一个闭环内**按顺序完成 `llmanspec/changes/<id>/tasks.md` 的所有任务：
+实现代码 → 补测试/验收 → 跑门禁 → 失败自修复并重跑 → 全部通过后报告结果。
+除非遇到明确 blocker，否则**不要中途停下来问「要不要继续」**。
+
+## Pipeline 位置
+
+{{ unit("skills/git-native-flow-brief") }}
+
+### Skill 导航（非生命周期；仅指示当前 skill）
+
+```mermaid
+flowchart LR
+    propose["llman-sdd-propose<br/>提案"] --> apply
+    apply["★ llman-sdd-apply ★<br/>实施（须 readyToImplement）"]
+    apply --> verify["llman-sdd-verify<br/>验证"]
+    verify --> archive["llman-sdd-archive<br/>归档"]
+
+    style apply fill:#fff3cd,stroke:#ffc107,stroke-width:3px
+```
+
+> 📍 你现在在完整 Git-native 生命周期图中的 **H（apply）**：进入前须 Specs-landed（或 `needs_specs_change: false`）且 `readyToImplement=true` → 下一步 `llman-sdd-verify`
+
+## 硬约束
+
+- **SSOT 驱动**：以 `proposal.md` / `design.md` / `tasks.md` 及 feature 分支上的 live `llmanspec/specs/**` 为唯一事实来源；specs 中的 MUST/SHALL 必须逐条落实。
+- **范围锁定**：只实现当前 change 的范围；禁止顺手修「无关问题」。
+- **最小改动**：改动保持最小并严格围绕当前 tasks。
+- **禁止猜测**：需求不明确、specs 与实现矛盾时，先 STOP 并报告，不要自行假定行为。
+- **不保留旧兼容层**：若 change 要求改行为，直接全量升级到新写法，除非 tasks/proposal 明确写了要兼容。
+- **不要问「要不要继续」**：除非遇到无法自动解决的 blocker，否则一路执行到闭环结束。
+- **收尾**：本 skill 闭环以建议 `llman-sdd-verify` 结束；finalize/archive 由 `llman-sdd-archive` 负责（勿在自修复循环里 finalize）。
+
+## Commit 策略
+
+- **change 分支上提交自由**（无存档点概念：`change finalize` 不要求干净树）：可按 task/里程碑分段提交（利于 review），也可保持工作区不提交、交给 finalize 一次收尾——两条路都是一等公民。`change checkpoint` 已不存在（调用它以非零退出报错并指向 finalize），因此没有「中途存档点」要维护；`change finalize` 对两种形态都原生支持（不要求干净树）。
+- **默认收尾**：全部 task 过门禁且 verify 全绿后，`llman sdd change finalize <id>` 自动提交 `archive(sdd): <change-id>`（未提交的实现 diff + frontmatter + archive 改名一次提交）。不要在 apply 循环内 finalize。`--no-commit` 可跳过自动提交（手动/CI 历史、pre-commit hook 冲突场景）。
+- **blocker 中断**：必须因 blocker STOP 时，先做**一次** WIP commit（如 `wip(sdd): <change-id> <摘要>`）保全现场，再报告。
+
+## 步骤
+
+### 0) Preflight（必须做）
+- 读取并遵守：`llmanspec/config.yaml`、`AGENTS.md`（若存在）。
+- `git status --porcelain`：
+  - 若工作区不干净且改动不属于当前 change：先 `git stash push -u -m "llman-sdd-apply autopilot backup"` 做备份。
+- 运行 `llman sdd validate --all --strict --no-interactive`：
+  - 若失败且与当前 change 无关，先停下报告（工件不一致会导致实现无法以 SSOT 驱动）。
+- **检查 spec valid_scope 完整性**：使用 `llman sdd list --specs --json` 列出所有 spec，然后对每个 spec 验证其 `valid_scope` 中的每个路径是否存在于磁盘上。若存在缺失的文件/目录，停下并建议更新 spec（从 `valid_scope` 中移除已删除的路径）。
+
+### 1) 选择变更 id 并检查前置条件
+- 若已提供 change id，直接使用。
+- 否则从上下文推断；若不明确，运行 `llman sdd list --json` 并让用户选择。
+- 始终说明："使用变更：<id>"，并告知如何覆盖。
+- 确认已在经 `llman sdd change start <id>` 或 `change attach <id>` 绑定的非默认 feature 分支上（仅在需要重绑时用 `--force`）。分支上的 specs/features 即 SSOT——不要在 `changes/<id>/specs/` 下编写。
+{{ unit("skills/stage-guard") }}
+- 使用 `llman sdd context --task "<proposal 中的目标>" --paths "<specs 中的 scope>"` 获取相关 specs。
+  - 若 context 不可用，运行 `llman sdd index rebuild` 后重试。
+
+### 2) 阅读 SSOT 工件
+必须通读以下文件：
+- `llmanspec/changes/<id>/proposal.md`
+- `llmanspec/changes/<id>/design.md`（如存在）
+- `llmanspec/changes/<id>/tasks.md`
+- feature 分支上的 live specs：`llmanspec/specs/**`（`<capability>.feature`）——这是 SSOT
+
+将 `proposal.md` 和 `design.md` 中的决策整理为不可违反的硬约束清单。把 `tasks.md` 转成可执行的最小步骤序列（保持原顺序）。
+
+### 3) 展示状态
+- 进度："N/M tasks complete"
+- 接下来 1–3 个未完成任务（简短概览）
+
+### 4) 逐任务实施（闭环执行）
+对每个未完成 task：
+1. **实现**：严格按 task 描述 + specs 要求，改动保持最小。
+2. **完成后立刻更新 checkbox**：`- [ ]` → `- [x]`。
+3. 若 task 不明确、遇到 blocker、或发现 specs/design 与现实不一致 → STOP 并报告 blocker，不要自行假定。
+
+> 💡 上一阶段 `llman-sdd-propose`（已生成 tasks）；完成本阶段后 → `llman-sdd-verify`（验证）
+
+### 5) 验证与自修复循环（每个 task 或每批 task 完成后执行一次）
+运行项目门禁命令（根据项目实际选择）：
+- 相关测试集：`just test` 或 `cargo test --all`
+- 格式/lint：`just check` 或 `just lint` + `just fmt`
+- Git-native：留在绑定 feature 分支；按需编辑 live `llmanspec/specs/<capability>.feature`（扁平，或目录 `llmanspec/specs/<capability>/` 内主文件；规则 `@human`，验收 `@executable`）；spec 改动后跑 `llman sdd validate --specs`；分支上可自由提交（分段，或留脏交给 finalize）。勿使用 `change delta` / solidify / feature_delta；`change checkpoint` 已移除。
+- SDD 校验：`llman sdd validate <id> --strict --no-interactive`
+
+**若失败 → 进入自修复循环（不要问要不要继续）：**
+1. 解析失败原因（测试失败 / lint / 格式 / 校验错误）。
+2. **判定是否难定位的 bug**（测试失败原因不明 / 间歇性 flake / 回归且一眼看不穿）：
+   - **不是难定位的 bug**（明确的 lint/格式/编译错误/校验失败）：进行最小修复（不扩大范围），先重跑「最小失败复现命令」再重跑全部门禁。
+   - **难定位的 bug → 升级诊断子流程**：
+     1. **先建一个能复现失败的命令**（快、确定、agent 可运行，且能在这个 bug 上失败）——即一个能驱动真实 bug 路径并断言用户确切症状的命令。**MUST NOT 在没有这种命令前就开始猜原因**（盯着代码空想正是本流程要防止的失败）。
+     2. 运行并确认失败 → 最小化复现（逐个剔除输入/调用/配置/数据，只留关键部分）。
+     3. 生成 **3–5 个排序假设**，每个须可证伪（「若 X 是因，则改 Y 会让 bug 消失」）。
+     4. 单变量验证（一次只改一个），找到根因后修复。
+     5. 若没有合适的边界（seam）写回归测试，记录该架构缺口（交 `llman-sdd-arch-review`；该 skill 未在 `extra_skills` 启用时，把缺口写入该 change 的 `proposal.md` Further Notes 段或 `design.md`，MUST NOT 因此中断闭环）。
+3. 先重跑「最小失败复现命令」，再重跑全部门禁。
+4. 记录为一轮自修复：`Round N：失败点 → 修复 → 重跑 → 通过/失败`。
+
+**自修复上限 8 轮**；超过仍不通过视为 blocker：停止并输出 blocker 报告（含最后一次失败命令与输出摘要、你已尝试的修复）。
+
+**人审检查点（每个 task 批次门禁通过后）**：批次全绿后、进入下一批次或输出完成报告前，运行 `llman sdd review`：
+
+- 退出码为零 → 继续。
+- 非零退出 = 存在 CRITICAL 发现：STOP，修复后重跑 review；MUST NOT 带着 CRITICAL 进入下一批次或输出完成报告。
+
+### 6) 完成报告
+所有 task 完成 + 全部门禁通过后，输出结构化报告（见下方 Output Contract）。
+然后建议运行 `llman-sdd-verify` 进入验证阶段。
+
+> 💡 实施完成 → 下一步 `llman-sdd-verify`（验证）
+
+> 命令细节用 `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-arch-review.md

@@ -0,0 +1,65 @@
+---
+name: "llman-sdd-arch-review"
+description: "扫描 codebase 的薄模块（接口几乎等于实现），找出可以加深（藏更多行为到更小接口后）的候选。当用户想做架构审查、寻找模块加深机会、或想改善代码可测性与 AI 可导航性时使用。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Architecture Review
+
+扫描 codebase 的架构摩擦，找出**可以加深的模块**——把薄模块（接口几乎等于实现）改造成厚模块（小接口后藏大量行为）。目标是可测性与 AI 可导航性。
+
+## Pipeline 位置
+
+辅助工具，不属于主实现 pipeline（explore→propose→apply→verify→archive）。任意阶段可用，常在 explore 阶段触发以发现改进候选。
+
+> 📍 这是独立可选 skill，不替代任何 pipeline 阶段。
+
+## 设计词汇
+
+下面是一组关于模块形状的词，用来说清楚「哪里值得改」。MUST NOT 替换为「component」「service」「API」「boundary」（它们含义更宽、不够精确）：
+
+- **Module（模块）** — 有接口和实现的东西（函数/类/包/跨层切片都算）。
+- **Interface（接口）** — 调用者为正确使用所须知道的一切：类型签名，外加不变量、顺序约束、错误模式、性能特征。
+- **Depth（厚度）** — 接口背后的行为量。**厚** = 小接口后藏大量行为；**薄** = 接口几乎和实现一样复杂（调用者要懂的 ≈ 写代码要写的）。本 skill 要把薄的变厚。
+- **Seam（接缝）** — 不改调用处就能换实现的位置（接口栖身的地方）。llman 里接缝 = `*.feature` 的 GWT 步骤所驱动的公共边界。
+- **Leverage（杠杆）** — 调用者从厚度获得的好处：学一点接口就能驱动很多行为。
+- **Locality（局部性）** — 维护者从厚度获得的好处：变更/bug/知识/验证集中在一处，改一次到处生效。
+
+## 步骤
+
+### 1. 探索（先定范围，YAGNI）
+- 若用户指定了方向（模块/子系统/痛点），直接采信，跳过推断。
+- 否则回看 `git log --oneline` 找热点（反复出现的文件/区域）。
+- 优先读 live `<capability>.feature`（单轨 SSOT）与 `design.md`（已有 ADR），MUST NOT 另建 `CONTEXT.md`。
+- 用 Agent 工具（subagent_type=Explore）走查 codebase，记录摩擦点：
+  - 理解一个概念是否要在多个小模块间跳来跳去？
+  - 哪里模块**薄**（接口几乎和实现一样复杂，调用者没省事）？
+  - 哪里纯函数仅为可测性抽取，但真实 bug 藏在调用方式里（缺局部性）？
+  - 哪些部分没测或难以通过当前接口测试？
+
+### 2. 提出候选
+对每个候选，给出：
+- **Files** — 涉及哪些文件/模块。
+- **Problem** — 当前架构为何造成摩擦（用厚度/杠杆/局部性说清楚）。
+- **Solution** — 会改变什么的平实描述。
+- **Benefits** — 局部性与杠杆的改善，测试如何变好。
+- **Recommendation strength** — `Strong` / `Worth exploring` / `Speculative`。
+
+**删除验证**：对任何疑似薄的模块，想象删除它——复杂度是直接消失（它只是个透传，没价值）还是在 N 个调用点重新冒出来（它其实在扛事）？「重新冒出来」才是值得保留/加厚的信号。
+
+**ADR 冲突**：若候选与既有 `design.md` 决策矛盾，仅在摩擦真实到值得重开时才浮现，并在候选中标注（「与 design.md 的 X 决策冲突——但因…值得重开」）。
+
+### 3. 逐问深挖（用户选定候选后）
+用户从候选中选一个后，运行 `llman-sdd-explore` 的**逐问深挖分支**（触发词「深挖」）逐个走清决策——约束、依赖、加深后的模块形状、接缝后放什么、哪些测试存活。
+
+- 加深后的模块用到了 capability `.feature` 里没有的概念？→ 仅在 change 已 Branch binding 且当前在绑定分支上时，更新 live `.feature`（Specs landing）；否则 STOP，先走 `llman-sdd-propose` / `change start`，**禁止**在默认分支改 live specs。
+- 用户以关键理由拒绝候选？→ 仅当「难逆转 + 无上下文会困惑 + 真实权衡」三者皆满足时，建议记入 `design.md`。
+
+## 输出
+候选清单（文本；可选 HTML 报告写 OS temp dir 不落 repo）+ 用户选定后的逐问深挖决策记录（回写 proposal；合约变更须经 Specs landing 才回写 live `<capability>.feature`）。
+
+> 命令细节用 `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/skills/llman-sdd-archive.md

@@ -0,0 +1,85 @@
+---
+name: "llman-sdd-archive"
+description: "归档已完成的 llman SDD 变更。自动合并回基准分支（squash 缺省），再将 change 文档改名到 archive/。在 verify 报告全绿后运行。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD 归档
+
+使用此 skill 归档已完成的变更。前置：verify 全绿，且变更已 Branch binding、Specs landing 完成（或 `needs_specs_change: false`；归档时 live specs 已在绑定分支上）。`change finalize` **自动合并**到基准分支（目标：`--into` > 绑定 `base_branch` > 默认分支；方式：`--method` > 配置 `sdd.merge_method`，squash 缺省——feature diff + 改名收敛为目标分支单个 commit）、**将** change 文档改名到 `changes/archive/`，然后**自动提交** `archive(sdd): <change-id>`（实现 diff + 改名一次提交；`--no-commit` 跳过）。`change checkpoint` 已移除（无存档点概念：中途不必存档，`change finalize` 不要求干净树）。`git push` / Hosting PR 仅为可选。
+
+## Pipeline 位置
+
+```mermaid
+flowchart LR
+    verify["llman-sdd-verify<br/>验证"] --> archive
+    archive["★ llman-sdd-archive ★<br/>归档（你现在在这里）"]
+
+    style archive fill:#fff3cd,stroke:#ffc107,stroke-width:3px
+```
+
+> 📍 你现在在归档阶段：Git-native 生命周期的最后一站。
+> 📎 若 specs 逐渐膨胀，可运行 `llman-sdd-specs-compact` 压缩。
+
+## 硬约束
+
+- **必须先通过 verify 阶段全绿**：未通过验证的 change 禁止归档。
+- **须已 Branch binding**：`change start` / `attach` 已完成；无绑定则 STOP。
+- **SSOT 校验**：每个 change 归档前必须通过 `llman sdd validate <id> --strict --no-interactive`。
+- **不要问「要不要继续」**：批量归档时间线上一路执行到底，除非遇到无法自动解决的错误。
+- **收尾不默认导向 PR/push**：archive/finalize 后由 CLI 处理本地合并（squash 缺省），再一次性 `git commit` 提交收口。`git push` / Hosting PR 仅为可选——仅当用户或项目明确要求远程审查时才做。**Agent MUST NOT** 因本 skill 默认执行 push 或创建 PR。
+
+## 步骤
+
+### 0) Preflight
+- `git status --porcelain`：确认工作区改动属于已完成的 change。
+- 若有未预期改动，先处理（stash 或报告）。
+
+### 1) 确认目标变更
+- 确定目标 ID：单个或批量（来自用户输入或 `llman sdd list --json`）。
+- 始终说明："归档 IDs：<id1>, <id2>, ..."。
+- 确认每个 change 都已通过 verify 阶段的全绿验证。
+
+### 2) 逐个归档
+- **人审检查点（每个 id 归档执行前，含批量）**：运行 `llman sdd review --capability <id>`。退出码为零 → 继续；非零 = CRITICAL 发现：STOP 修复后重跑；MUST NOT 带着 CRITICAL 归档。
+- 先逐个校验：`llman sdd validate <id> --strict --no-interactive`。
+- 校验失败 → STOP 并报告；不要跳过校验强行归档。
+- 可选预览：`llman sdd change archive <id> --dry-run`。
+- 执行归档：
+  - 默认：`llman sdd change archive <id>`
+  - 仅工具类变更：`llman sdd change archive <id> --skip-specs`
+  - **任一失败立即停止**，报告剩余未处理 ID。
+- **Git-native 收尾**：
+  - 前置：已 Branch binding（`change start` / `attach`）；仍在绑定分支上（或合并后已在目标分支）。
+  - `change archive` / `change finalize` **先自动合并**（目标 `--into` > 绑定 `base_branch` > 默认分支；方式 squash 缺省或 `ff`；目标被其他 worktree 持有时跳过并打印手动命令），**再**将 change 文档改名到 `changes/archive/`——合并失败也不会回滚改名，降级提示显式可见。
+  - specs 下遗留 `*.feature.delta.toon` 或 `spec.toon` 均为迁移阻断项——跑 `llman sdd project migrate --kind toon2features`。
+  - **默认：`change finalize`（单命令收口）**——门禁 → 自动合并 → 文档改名 → **自动提交** `archive(sdd): <change-id>`（squash 缺省：实现 diff + 改名收敛为目标分支**单个**提交；无需手动 `git commit`；锁定规则改动为报告制 WARNING——只警告不阻断）：
+    ```text
+    1. 实现 live specs + 代码（工作区可保持脏；分支上提交自由——分段或完全不提交）
+    2. llman sdd change finalize <id>    # 门禁 + 合并（squash 缺省）+ 改名 + 自动提交
+    3. 可选：git commit --amend          # 调整提交说明；git branch -D <feature>  # squash 后分支不再是祖先，-d 会被 git 拒绝
+    ```
+    `--no-commit` 跳过自动提交（CI / pre-commit hook 冲突）：finalize 此时留脏工作区并打印手动 `git commit` 命令。幂等重试：自动提交失败后重跑会识别已归档改名并补提交。
+  - **Fallback：普通 `change archive <id>`**——同样的合并 + 改名，无自动提交；要求干净树。`checkpointed`/`checkpoint_sha` 字段已随 checkpoint 一同移除（无存档点概念：`change finalize` 不要求干净树）——无需预写任何存档字段，快照审查用 `change diff`。
+
+### 3) 全量校验
+- 全部归档完成后执行：`llman sdd validate --all --strict --no-interactive`。
+- 确认归档后的 specs 工件一致。
+
+### 4) Commit 引导
+- finalize 已自动提交（`archive(sdd): <id>`）；使用 `--no-commit` 时手动提交：`git add -A && git commit -m "archive(sdd): <id1>, <id2>"`（或本 skill 建议的格式）。
+- 可选：合并后 `git branch -D <feature>`（squash 后分支不再是 main 祖先，-d 会被拒绝）。push / Hosting PR 仅在用户或项目明确要求远程审查时才做。
+- **破坏性合约变更**（移除/重命名 frontmatter 字段、命令、tag 或 stage 值域）MUST 提供 `migrations/v<from>-v<to>/` 升级路径（README prompt + 一次性脚本，随仓库发布）——收口前确认它存在。
+- **archived `depends_on`**：archive 会把 change 目录改名为 `archive/YYYY-MM-DD-<id>`，但 validate 会把指向 archived/frozen id 的 `depends_on` 识别为 INFO（非 ERROR），所以**归档后无需**手动更新其它 change 的 `depends_on` frontmatter。
+
+> 💡 上一阶段 `llman-sdd-verify`（验证通过）→ 本阶段归档后闭环结束。若 specs 逐渐膨胀，可运行 `llman-sdd-specs-compact` 压缩。
+
+{{ unit("workflow/archive-freeze-guidance") }}
+
+> 命令细节用 `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") }}