@llman-sdd/core 0.3.1 → 0.5.0

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