@llman-sdd/core 0.3.1 → 0.5.1

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`。

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

@@ -1,7 +1,8 @@
-## 单轨 Feature 合约规范
+## 单轨 Feature 合约规范(原生 Gherkin 分层)
 
-每个 capability 只有一个 Gherkin 文件：扁平 `llmanspec/specs/<capability>.feature`（新默认）或目录 `llmanspec/specs/<capability>/` 内同名主文件（两种布局二选一，同 id 并存算冲突）。
-它是唯一的 spec 工件——不存在 `spec.toon`。
+每个 capability 只有一个 Gherkin 文件：扁平 `llmanspec/specs/<capability>.feature`（默认）或目录 `llmanspec/specs/<capability>/` 内同名主文件——二选一，同 id 两布局并存算冲突。它是唯一的 spec 工件（不存在 `spec.toon`）。
+
+格式使用**原生 Gherkin 分层**：`功能:` → `规则:`（需求：标题 + 自由文本描述 + `@req:<id>` 句柄）→ 嵌套 `场景:`（可执行 GWT 示例）。这是唯一的规范样式；历史标签（`@executable`/`@rule`/`@human`/`@manual`）不再使用，旧文件以 `spec migrate-native` 迁移。
 
 ```gherkin
 # language: zh-CN
@@ -11,19 +12,27 @@
 
 功能: sample
 
-  @req:r1 @human
-  场景: Rule title
-    System MUST do something.
+  @req:r1
+  规则: 描述一个需求要点
+    需求文本自由书写(不强制 MUST/SHALL 词),较长时拆多行便于人/agent 阅读。
+    第二行继续,描述行不得以 假如/当/那么/而且 开头(会被解析为步骤)。
+
+    场景: 一个可执行示例
+      假如 a precondition
+      当 a trigger happens
+      那么 the outcome is observed
 
-  @req:r1 @executable
-  场景: happy
-    假如 a precondition
-    当 a trigger happens
-    那么 the outcome is observed
+  @req:r2
+  规则: 暂不转写的需求(裸规则,会被聚合计数提示转写)
+    描述即现状需求的唯一载体;没有嵌套场景的规则计入裸规则聚合计数,交由
+    specs-compact 持续压降。
 ```
 
-- 头注释（`# capability:` / `# purpose:` / `# scope:`）必填；`scope` 驱动 staleness 检查。
-- `@human` 场景是人拥有的约束场景；规则 statement 全文放在场景描述里。改/删它只出 WARNING（报告制，不阻断门禁），用 git 分支对比审视；旧的锁定确认元数据 `rules_touched` / `agent_acked` / `@agent` 已删除，无别名也无兼容层。
-- `@executable` 场景是 runner 绑定的验收场景；用 `@req:<req_id>` 挂回规则。
-- 覆盖两态分级：enforced（有验收）/ pending——`list --specs` 逐项输出。
-- 场景 MUST 保持顶层：`Rule:` 块会被拒绝（runner 会静默跳过其中场景）。
+- 头注释（`# capability:` / `# purpose:` / `# scope:`）必填；`scope` 驱动过期检查。
+- **可执行场景优先**：行为一律以嵌套 `场景:`（假如/当/那么）表达并绑定 BDD 步骤代码、由 runner 执行——默认首选。仅当需求无法程序化表达（抽象目标、架构决策、治理/人工约束）或暂不转写时，才以 `规则:` 块承载，并在 proposal/design 记录理由。
+- `@req:<id>` 挂在 `规则:` 头标签，是全局唯一的需求句柄（resolve-req/next-req-id/条款引用共用）；重复或缺失由 validate 判 ERROR。
+- 规则描述为自由文本：不强制 MUST/SHALL 词；较长时拆多行便于审查，不使用 `- ` 列表前缀（会原样进入描述）。
+- 不在任何 `规则:` 内的顶层 `场景:` 是功能级示例(Gherkin 原生允许,无规则句柄、不告警、不参与规则统计);无嵌套场景的 `规则:` 是裸规则(聚合计数 INFO,`--include-info` 可见,review `pending` 信号计量)。
+- 改/删既有 `规则:` 只出 WARNING（报告制，不阻断门禁），用 git 分支对比审视；旧锁定确认元数据 `rules_touched` / `agent_acked` / `@agent` 已删除，无别名无兼容层。
+- 覆盖分级：enforced（含嵌套场景）/ pending（裸规则）——`list --specs` 逐项输出。
+- `规则:` 块是标准容器：嵌套 `场景:` 会被 runner 执行；两空格缩进层级（块 `规则:` 2 格、嵌套 `场景:` 4 格、步骤 6 格）。

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

@@ -1,6 +1,10 @@
 ## Archive 冷备引导
-- 当 archive 目录增长过大时，使用冷备维护：
+- archive 目录过大时用冷备维护（冻结 = 正文入 7z 冷备 + 以 `<YYYY-MM-DD>-<id>.yaml` 平铺索引卡替代目录，卡仅含 title 与 depends_on）：
   - 预览冻结候选：`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>`
+  - 列出已冻结条目：`llman-sdd archive freeze --list`
+  - 需要恢复时：`llman-sdd archive thaw --change <YYYY-MM-DD-id>`（正文解回目录并移除平铺卡）
 - freeze/thaw 仅用于日期归档目录（`YYYY-MM-DD-*`）；建议保留少量最近目录不冻结。
+- 平铺索引卡常驻磁盘：title（来自 proposal H1）与 depends_on（graph 依赖边种子）可 grep、可追溯；
+  id 与日期由文件名隐含——冻结 change 的用途与依赖关系无需解冻即可查阅，正文在 7z 冷备按需取用。
+- 在非主检出（不持有默认分支的 worktree）运行时打印警告（仅提示、不阻断）——有意为之才在该处继续。

package/templates/en/skills/llman-sdd-onboard.md

@@ -1,34 +0,0 @@
----
-name: "llman-sdd-onboard"
-description: "Onboard to the llman SDD workflow in a repository."
-metadata:
-  version: "{{ llman_version }}"
----
-
-# LLMAN SDD Onboard
-
-Use this skill to onboard to llman SDD in a repository.
-
-## Steps
-1. Read `llmanspec/config.yaml` for project context, conventions, and rules.
-2. Use `llman-sdd list --specs --json` to see all specs at a glance.
-   - Or use `llman-sdd context --task "<task description>" --paths "<files>"` to find task-relevant specs.
-   - If context returns `quality: "unavailable"`, run `llman-sdd index rebuild` first (default backend is `pageindex`; it needs `LLMAN_SDD_INDEX_CHAT_MODEL` for retrieval but not for rebuilding).
-3. Read only the `direct` spec files from context output.
-4. Assess change scale (see triage rules): behavioural contract change → full SDD; implementation change → quick path.
-5. Advance by path:
-   - **Full path**: planning shell (draft → designed [+design.md] → planned [+tasks.md]) → Branch binding → Specs landing (or `needs_specs_change: false`) → `readyToImplement=true` → apply → verify → finalize/archive (skill navigation: propose → apply → verify → archive).
-   - **Quick path**: no MUST/SHALL change; edit code and commit (live specs only on a bound branch — see `llman-sdd-quick`).
-6. Use `llman-sdd graph` to visualize change dependencies.
-
-> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.
-
-## Notes
-- `llmanspec/config.yaml` holds project context, rules, locale, and skills paths.
-- Locale affects templates/skills only; CLI stays English.
-- Refresh skills with `llman-sdd init --update`.
-
-{{ unit("skills/validation-hints") }}
-
-{{ unit("skills/ethics-governance") }}

package/templates/en/skills/llman-sdd-show.md

@@ -1,24 +0,0 @@
----
-name: "llman-sdd-show"
-description: "Inspect llmanspec changes and specs quickly."
-metadata:
-  version: "{{ llman_version }}"
----
-
-# LLMAN SDD Show
-
-Use this skill to inspect changes, specs, and JSON output.
-
-## Steps
-1. List items: `llman-sdd list` or `llman-sdd list --specs`.
-2. If the id is unknown or ambiguous, show the list and ask the user to pick.
-3. Show details: `llman-sdd show <id>`.
-4. Disambiguate with `--type change|spec` when needed.
-5. For changes, use `--json`: status SSOT fields are `stage` / `specsLanded` / `needsSpecsChange` / `readyToImplement` (never decide apply-readiness from vague "complete artifacts" wording).
-
-> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.
-
-{{ unit("skills/validation-hints") }}
-
-{{ unit("skills/ethics-governance") }}

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

@@ -1,28 +0,0 @@
-# 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/zh-Hans/skills/llman-sdd-onboard.md

@@ -1,34 +0,0 @@
----
-name: "llman-sdd-onboard"
-description: "了解 llman SDD 工作流并完成项目入门。"
-metadata:
-  version: "{{ llman_version }}"
----
-
-# LLMAN SDD 入门
-
-使用此 skill 让你快速了解 llman SDD 工作流。
-
-## 步骤
-1. 阅读 `llmanspec/config.yaml` 了解项目上下文、约定与规则。
-2. 使用 `llman-sdd list --specs --json` 了解项目中的 specs 概览。
-   - 或者使用 `llman-sdd context --task "<任务描述>" --paths "<路径>"` 获取与当前任务相关的 specs。
-   - 如果 context 返回 `quality: "unavailable"`，先运行 `llman-sdd index rebuild` 重建索引（默认 backend 为 `pageindex`；检索需 `LLMAN_SDD_INDEX_CHAT_MODEL`，但重建不需要）。
-3. 根据 context 的 `direct`/`related` 分类，只读 target spec 全文。
-4. 判断变更规模（见 triage 规则），决定走完整 SDD 流程或快速路径。
-5. 按路径推进：
-   - **完整路径**：规划壳（draft → designed [+design.md] → planned [+tasks.md]）→ Branch binding → Specs landing（或 `needs_specs_change: false`）→ `readyToImplement=true` → apply → verify → finalize/archive（Skill 导航：propose → apply → verify → archive）。
-   - **快速路径**：不改 MUST/SHALL，直接改代码 commit（触及 live specs 须已绑定分支，见 `llman-sdd-quick`）。
-6. 使用 `llman-sdd graph` 可视化变更依赖关系（depends_on/blocks）。
-
-> 命令细节用 `llman-sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
-> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman-sdd list --specs` / `llman-sdd show <capability>` 查全文。
-
-## 备注
-- `llmanspec/config.yaml` 包含项目上下文、规则、locale 与 skills 路径。
-- locale 仅影响模板与 skills，CLI 仍为英文。
-- 使用 `llman-sdd init --update` 刷新技能。
-
-{{ unit("skills/validation-hints") }}
-
-{{ unit("skills/ethics-governance") }}

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

@@ -1,24 +0,0 @@
----
-name: "llman-sdd-show"
-description: "快速查看 llmanspec 变更与 specs。"
-metadata:
-  version: "{{ llman_version }}"
----
-
-# LLMAN SDD 查看
-
-使用此 skill 快速查看变更与 specs。
-
-## 步骤
-1. 列出条目：`llman-sdd list` 或 `llman-sdd list --specs`。
-2. 如果 id 不明确，展示列表并让用户选择。
-3. 查看详情：`llman-sdd show <id>`。
-4. 需要时使用 `--type change|spec` 消除歧义。
-5. 对 change 使用 `--json`：状态 SSOT 字段为 `stage` / `specsLanded` / `needsSpecsChange` / `readyToImplement`（勿凭「完整工件」口头判断可否 apply）。
-
-> 命令细节用 `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/units/migrate-prompt.md

@@ -1,28 +0,0 @@
-# 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`）