kind: llman.sdd.spec
name: "sdd-workflow"
purpose: "Define the llman SDD workflow and its OpenSpec-compatible behaviors for `llmanspec/`."
valid_scope[2]: src/,tests/
requirements[46]{req_id,title,statement}:
  r1,SDD 初始化脚手架,"`llman sdd init [path]` 命令 MUST 在目标路径创建 `llmanspec/` 目录结构，包括 `llmanspec/AGENTS.md`、`llmanspec/project.md`、`llmanspec/config.yaml`、`llmanspec/specs/`、`llmanspec/changes/` 与 `llmanspec/changes/archive/`。命令 MUST 在 `llmanspec/config.yaml` 顶部写入 `yaml-language-server` schema 头注释，指向 `llmanspec-config` schema URL。命令 MUST 创建或刷新 repo 根目录下的 `AGENTS.md` 受管块以指向 `llmanspec/AGENTS.md`。当 `llmanspec/` 已存在时，命令 MUST 报错并且不修改任何文件。生成的 `llmanspec/AGENTS.md` MUST 包含 LLMANSPEC 受管提示块且包含完整 llman sdd 方法论说明。 初始化生成的 `llmansp"
  r2,SDD 指令与提示词刷新,"`llman sdd update [path]` MUST 刷新 `llmanspec/AGENTS.md` 的 LLMANSPEC 受管提示块，同时 MUST 保持 `llmanspec/specs/**` 与 `llmanspec/changes/**` 不被修改。命令 MUST 刷新 repo 根目录 `AGENTS.md` 的 LLMANSPEC 受管块并保留非受管内容。更新 `llmanspec/AGENTS.md` 时 MUST 仅替换 LLMANSPEC 受管提示块，并保留受管块以外的用户内容。更新时必须使用 `llmanspec/config.yaml` 的 locale 选择模板。"
  r3,SDD 本地化配置与模板加载,`llman sdd` MUST 使用项目级配置 `llmanspec/config.yaml` 解析 locale，并基于 `templates/sdd/<locale>/` 加载 `llmanspec/AGENTS.md`、`llmanspec/project.md` 与 sdd skills 内容。locale 仅影响模板与 skills 输出，不影响 CLI 文本。
  r4,SDD Skills 生成与更新,"`llman sdd update-skills` 生成的 workflow skills 集 MUST 新增 `llman-sdd-specs-compact`，并在现有 `llman-sdd-*` skills 中使用统一结构化提示协议（见 `sdd-structured-skill-prompts` capability）。当目标工具为 Claude 时，命令 MUST 同步生成 `.claude/commands/llman-sdd/*.md` workflow commands，且其命令提示内容 MUST 直接来自对应的 `templates/sdd/<locale>/skills/llman-sdd-*.md`（单一真源）。"
  r5,SDD 模板区域复用,SDD 模板与 skills MUST 使用基于 MiniJinja 的模板单元注入机制进行复用。系统 MUST 通过显式模板单元标识符完成注入渲染，并在缺失单元、重复注册或渲染失败时报错并中止。
  r6,SDD 命令范围,"`llman sdd` MUST 暴露以下命令集合：`init`、`update`、`update-skills`、`list`、`show`、`validate`、`archive`、`import`、`export`、`convert`。 其中： - `import` 与 `export` MUST 作为 `llmanspec` 与外部规范目录互转的唯一入口。 - `convert` MUST 作为 `llmanspec` 内部 `ison / toon / yaml` 风格之间显式迁移的入口。 实现 MUST NOT 暴露 `migrate --from/--to` 兼容别名。 在 SDD 子命令组中 MUST 不提供 `change`、`view`、`completion`、`config` 等额外子命令。"
  r7,SDD OpenSpec 双向互转,"系统 MUST 提供： - `llman sdd import --style openspec [path]`，将 `openspec/` 迁移到 `llmanspec/` - `llman sdd export --style openspec [path]`，将 `llmanspec/` 迁移到 `openspec/` `--style` MUST 为必填，且当前仅允许值 `openspec`。命令 MUST 覆盖 `specs`、active `changes` 与 `changes/archive`。源侧非标准目录（例如 `explorations/`）MUST 输出 warning，并按相对路径复制到目标侧。目标存在同名文件冲突时 MUST 失败且 MUST NOT 覆盖。"
  r8,SDD 互转执行安全门禁,"`import/export` MUST 默认先输出完整 dry-run 计划。真实写入 MUST 仅在交互终端中通过双确认后执行（`Confirm` + 确认短语）。非交互环境 MUST 在输出 dry-run 后拒绝写入并返回非零。迁移写入成功后 MUST 提示是否删除旧迁移目录（源目录），默认 MUST 为“不删除”。"
  r9,SDD 互转元数据兼容,"`export` MUST 在缺失时自动补齐 OpenSpec 元数据： - `openspec/config.yaml`（至少包含 `schema: spec-driven`） - active change 的 `.openspec.yaml`（包含 `schema` 与 `created`） `import` MUST 在主 spec 缺失 llman frontmatter 时补齐最小必需键： - `llman_spec_valid_scope` - `llman_spec_valid_commands` - `llman_spec_evidence`"
  r10,SDD 列表与查看,"`llman sdd list` 默认 MUST 列出 `llmanspec/changes/` 下除 `archive` 外的变更 ID，提供 `--specs` 时 MUST 列出 `llmanspec/specs/` 下的 spec ID，提供 `--changes` 时 MUST 显式列出变更。`llman sdd list` MUST 支持 `--sort`（默认 `recent`，可选 `name`）。`llman sdd show` MUST 输出指定 change/spec 的原始 markdown（非 JSON 模式），并遵循 OpenSpec 的自动识别与 `--type change|spec` 覆盖规则。`list` 与 `show` MUST 支持 `--json` 机器可读输出：change JSON 输出 `id/title/deltaCount/deltas`，spec JSON 输出 `id/title/overview/requirementCount/requirements/metadata`。spec JSON MUST 支持 `--requi"
  r11,SDD 交互提示与非交互提示,`llman sdd show` 与 `llman sdd validate` MUST 按 OpenSpec 的交互体验实现：在可交互环境下提供选择式流程；在不可交互或显式禁用交互时输出一致的提示语并退出非零。
  r12,SDD 校验,"`llman sdd validate` MUST 校验 spec 与 delta 的格式：spec 必须包含 `## Purpose` 与 `## Requirements`，每个 requirement 文本必须包含 `SHALL` 或 `MUST`，且至少包含一个 `#### Scenario:`；delta 必须使用 `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`，每个 requirement 块必须包含文本与场景，同一 requirement 不得出现在多个 section，`RENAMED` section 若存在必须包含 `FROM/TO` 对。命令 MUST 支持 `--all --changes --specs --type change|spec --strict --no-interactive --json`。`--json` 输出 MUST 采用 OpenSpec 顶层 validate 结构（`items`/`summary`/`version`），单项校验亦使用同一结构。"
  r13,SDD 校验提示增强,`llman sdd validate` 在非 JSON 模式下 MUST 为常见结构错误提供可执行修复提示，包含最小示例片段与推荐命令。
  r14,Spec 校验元数据（YAML Frontmatter）,"`llmanspec/specs/<id>/spec.md` MUST 以 YAML frontmatter 开头，包含以下键： - `llman_spec_valid_scope` - `llman_spec_valid_commands` - `llman_spec_evidence` `llman_spec_valid_scope` MUST 是 repo 根目录相对路径的列表或单个字符串；列表项/字符串可以用逗号分隔多个路径。校验范围匹配规则 MUST 为“路径完全相等或以 `<path>/` 为前缀”。`llman_spec_valid_commands` 与 `llman_spec_evidence` MUST 为非空字符串或字符串列表，用于记录最小验证证据。`llman sdd validate` MUST 在校验 spec 时解析并校验这些元数据，缺失或为空 MUST 视为校验失败并提示。"
  r15,Spec 过期（staleness）校验,"`llman sdd validate` MUST 对 specs 进行 staleness 评估： - 基准 MUST 使用 `git merge-base <base-ref> HEAD`，`<base-ref>` 默认 `origin/main`，不存在时回退 `origin/master`，并允许通过 `LLMANSPEC_BASE_REF` 覆盖。 - 校验范围 MUST 使用 `git diff --name-only <base>..HEAD` 获取变更路径，并与 `llman_spec_valid_scope` 匹配。 - 若变更触及范围且 `llmanspec/specs/<id>/spec.md` 未在 `<base>..HEAD` 中更新，则 MUST 标记为 `STALE`。 - 若 spec 更新但范围未触及，则 MUST 记录为 `INFO`。 - 若 Git 无法解析 base（如无 remote / 无 merge-base），则 MUST 记录 `WARN` 并跳过 staleness 评估；`--strict` MUST 将 `WARN` 升级为 `"
  r16,SDD 归档流程,"`llman sdd archive` MUST 支持子命令组工作流，并保持兼容入口可用： - 兼容入口：`llman sdd archive <change-id>`（等价于 `llman sdd archive run <change-id>`） - 标准入口：`llman sdd archive run <change-id>` `archive run` MUST 延续当前行为：将 delta 合并到 `llmanspec/specs`，并将 change 移动到 `llmanspec/changes/archive/YYYY-MM-DD-<change-id>`；`--skip-specs`、`--dry-run`、隐藏 `--force` 行为 MUST 保持一致。"
  r17,"SDD 归档 dry-run","`llman sdd archive --dry-run` MUST 输出将要修改/移动的文件与目标路径，并 MUST 不进行任何文件写入。"
  r18,SDD 归档冻结与解冻,"`llman sdd archive freeze` MUST 将 `llmanspec/changes/archive/` 下符合 `YYYY-MM-DD-*` 的目录合并写入单一冷备文件 `llmanspec/changes/archive/freezed_changes.7z.archived`，并在成功后移除本次冻结源目录。`llman sdd archive thaw` MUST 从该冷备文件恢复归档目录到默认 `.thawed/`（或 `--dest` 指定目录），并支持 `--change` 选择性恢复。"
  r19,SDD 模板版本元信息,"SDD locale 模板 MUST 包含 `llman-template-version` 元信息。对于带 YAML frontmatter 的模板，frontmatter MUST 在 `metadata` 字段中包含 `llman-template-version` 键；其他模板 MUST 在第一行使用 `<!-- llman-template-version: N -->` 形式。相同相对路径的不同 locale 模板 MUST 使用相同的版本值。仓库 MUST 提供维护者检查命令以验证版本一致性与模板集合一致性。"
  r20,SDD 归档前置校验,"`llman sdd archive` MUST 在修改 specs 或移动 change 目录之前，对本次涉及的 specs 执行与 `llman sdd validate --strict --no-interactive` 等价的校验（包括 frontmatter 与 staleness）。归档校验 MUST 以重建后的 spec 内容为准，并在 staleness 判断中将本次归档涉及的 spec 视为已更新。任何 Error 或 Warn MUST 阻止归档并返回非零。"
  r21,SDD skills 输出符合 Agent Skills SKILL.md 规范,"`llman sdd update-skills` MUST 生成符合 Agent Skills 规范的 `SKILL.md` frontmatter，至少包含 `name` 与 `description`： - `name` MUST 与技能目录名一致，且仅包含小写字母/数字/连字符、长度 1-64、不得以连字符开头/结尾、不得包含连续连字符。 - `description` MUST 为 1-1024 字符的非空描述文本。 - `license`、`compatibility`、`metadata`、`allowed-tools` MAY 在需要时提供。"
  r22,SDD skills 不暴露绕过参数,"`llman sdd update-skills` 生成的 skills 内容 MUST 不包含 `--force` 绕过提示或示例。"
  r23,SDD Future 记录文件为可选,"`llmanspec/changes/<change-id>/future.md` MUST 作为可选记录文件存在，用于承载延期项与分叉路线。缺失该文件 MUST NOT 阻塞 `llman sdd validate` 或 `llman sdd archive`。 与 future 相关的 `skills/*.md` 模板 MUST 提供“future 到执行”的注入式引导：将 future 条目分类为 `now|later|drop`，并为 `now` 条目映射后续 change 与首个可执行动作（如 `/llman-sdd:new`、`/llman-sdd:continue`、`/llman-sdd:ff`、`llman-sdd-apply`）。"
  r24,SDD 模板结构化提示协议,"`templates/sdd/{locale}/skills/*.md` MUST 提供统一结构化章节（或等价命名）：`Context`、`Goal`、`Constraints`、`Workflow`、`Decision Policy`、`Output Contract`。模板 MUST 为自包含规则，不得要求先调用外部技能作为前置步骤。"
  r25,SDD 重构保持行为一致,SDD 模块重构 MUST 保持所有 `llman sdd` 子命令的行为、输出与退出码一致，并且不得改变模板内容与配置生成路径。
  r26,change/spec ID 必须作为标识符处理而不是路径,"所有接受 `change-id` 或 `spec-id` 的 `llman sdd` 子命令 MUST 将其视为标识符。实现 MUST 拒绝包含路径分隔符或穿越片段的值（例如：`/`、`\\\\`、`..`），并 MUST NOT 因此在 `llmanspec/` 之外执行任何文件系统操作。"
  r27,list 的冲突 flag 必须显式报错,"`llman sdd list` MUST 将 `--specs` 与 `--changes` 视为互斥参数。若同时提供，两者冲突 MUST 返回非零错误并说明冲突原因。"
  r28,"update-skills multi-tool 下的 --path 不得造成覆盖","当一次 `llman sdd update-skills` 生成多个 tool 的 skills 时，若仅提供单个 `--path` 覆盖路径，而实现无法保证不同 tool 的输出互不覆盖，则命令 MUST 以非零错误拒绝执行并给出安全用法提示。"
  r29,SDD Workflow Command Bindings,"SDD MUST 提供 llman sdd workflow commands 的工具适配文件，并由 `llman sdd update-skills` 负责生成/刷新。命令绑定内容 MUST 引导用户进入 llman sdd 的工作流（`llmanspec/`）并与 skills 的动作集合保持一致。命令绑定 MUST 仅包含 workflow 命令集合，不得生成 legacy commands（例如旧式 `/openspec:*` 体系）。 当前版本中，workflow command bindings MUST 仅为 Claude Code 生成。实现 MUST NOT 为 Codex 生成 `.codex/prompts/llman-sdd-*.md` 绑定文件。"
  r30,SDD Archive Skill Supports Batch,"`llman-sdd-archive` skill MUST 同时覆盖单个与批量归档协议：列出活动 changes、让用户确认一个或多个 change IDs、按顺序执行归档，并在完成后运行一次全量校验。批量归档 MUST 默认遵循与单个归档一致的护栏（需要确认目标、失败时停止并报告）。"
  r31,SDD Explore 模式 Skill,"`llman-sdd-explore` skill MUST 提供探索模式指导，允许 AI 助手在问题分析、设计思考阶段提供帮助。探索模式 MUST 明确禁止直接实现代码，仅允许阅读代码、创建 artifacts、提出问题。skill 内容 MUST 包含：stance 定义、可执行的操作列表、与 llmanspec 的交互方式、结束探索的引导。"
  r32,SDD Continue Skill,"`llman-sdd-continue` skill MUST 指导 AI 助手继续未完成的变更，创建下一个待完成的 artifact。skill MUST 检查当前变更状态，识别已完成和待创建的 artifacts，按依赖顺序创建下一个 artifact。若所有 artifacts 已完成，skill MUST 引导用户进入 apply 阶段或 archive。当变更处于 draft 阶段（仅 proposal.md）时，skill MUST 显式提示这是 draft 提案，并指引按 specs → design → tasks 顺序长大到 full 后方可实现。"
  r33,SDD Apply Skill,"`llman-sdd-apply` skill MUST 指导 AI 助手实施 tasks.md 中的任务。skill MUST 读取变更的上下文文件（proposal、specs、design、tasks），按顺序实施未完成的任务，每完成一个任务后更新 tasks.md 中的 checkbox 状态。实施过程中遇到问题时 skill MUST 暂停并请求用户指导。skill MUST 在实施前执行阶段守卫：通过 `llman sdd show <id> --json` 读取权威 `stage`，当 stage 不为 `full` 时 MUST 拒绝实施并 STOP，引导用户使用 `llman-sdd-continue` 将变更长大到 full（proposal → specs → design → tasks）。draft 阶段的守卫文案 MUST 明确指出这是 draft 提案、需先补 specs → design → tasks。"
  r34,"SDD Fast-Forward Skill","`llman-sdd-ff` skill MUST 指导 AI 助手快速创建变更的所有 artifacts（proposal → specs → design → tasks），无需逐步确认。skill MUST 在创建前询问用户对变更的描述，然后依次创建所有 artifacts，最后显示完成状态和后续可用操作。"
  r35,SDD Verify Skill,"`llman-sdd-verify` skill MUST 指导 AI 助手验证实现与变更 artifacts 的一致性。skill MUST 读取 specs 和 design，检查代码实现是否符合规范，识别不一致之处并提供修复建议。验证通过后 skill MUST 引导用户进行 archive。skill MUST 在验证前执行阶段守卫：通过 `llman sdd show <id> --json` 读取权威 `stage`，当 stage 不为 `full` 时 MUST 拒绝验证并 STOP，引导用户使用 `llman-sdd-continue` 将变更长大到 full 后再验证。"
  r36,SDD Sync Skill,"`llman-sdd-sync` skill MUST 指导 AI 助手以可复现的人工作业协议将变更中的 delta specs 同步到主 specs，而不归档变更目录。skill MUST 指导用户检查 delta、手动应用 ADDED/MODIFIED/REMOVED/RENAMED 到对应主 specs，并在完成后运行验证命令。"
  r37,Archive Merge Emits ISON Spec Payload,`llman sdd archive` MUST merge delta changes into main specs using structured ISON semantics and emit ISON payload output.
  r38,SDD Provides ISON Authoring Commands,"`llman sdd` MUST provide an explicit command group for ISON spec authoring/editing to reduce manual edits of `llmanspec/**/spec.md`. At minimum, the CLI MUST support: - generating a main spec skeleton for a capability - adding a requirement to a main spec - adding a scenario to a main spec (keyed by `req_id` + `scenario.id`) - generating a delta spec skeleton for a change + capability - adding/removing/updating delta ops (add/modify/remove/rename requirement) - adding scenarios for add/modify op"
  r39,CLI Provides Lightweight Spec Metadata for Agents,"The CLI MUST provide an agent-friendly way to fetch a spec’s feature name/purpose without retrieving full requirement bodies. At minimum, `llman sdd show` MUST support a JSON metadata-only mode for specs: - command shape: `llman sdd show <spec-id> --type spec --json --meta-only` - output MUST include: - `id` (spec id / directory name) - `featureId` (from `object.spec.name`) - `title` (human-facing name; defaults to `featureId`) - `overview` (from `object.spec.purpose`) - `requirementCount` - `me"
  r40,"Validation Fails on JSON-in-ISON Payloads","`llman sdd validate` MUST fail when any `llmanspec` main spec or delta spec contains a fenced ` ```ison ` payload that is JSON. The error MUST be actionable and MUST include: - a concrete hint to rewrite the payload into canonical table/object ISON (for example: main spec uses `object.spec` + `table.requirements` + `table.scenarios`; delta spec uses `object.delta` + `table.ops` + `table.op_scenarios`)."
  r41,No Automatic Migration Is Required for Legacy Repos,"The system MUST enforce canonical table/object ISON for `llmanspec` specs and deltas. The system MUST NOT require (or depend on) an automatic migration command as part of the workflow. Users MUST manually rewrite legacy JSON-in-` ```ison ` payloads into the canonical table/object ISON schema before using `llman sdd` successfully."
  r42,SDD Propose Skill,"`llman-sdd-propose` skill MUST guide an AI assistant to create a new change and generate all planning artifacts in one pass (proposal + delta specs + tasks; design optional), then run validation and suggest next actions."
  r43,变更完整度阶段检测,`llman sdd validate` MUST 在校验变更时检测并报告变更的完整度阶段。阶段定义为：`draft`（仅 proposal.md）、`specified`（proposal.md + specs/*/spec.md）、`designed`（proposal.md + specs/ + design.md）、`full`（proposal.md + specs/ + design.md + tasks.md）。校验输出 MUST 包含当前阶段标识。
  r44,Design 前置约束,"`llman sdd validate` MUST 在变更包含 `tasks.md` 但缺少 `design.md` 时报 ERROR。该约束在 strict 与 non-strict 模式下均 MUST 生效。错误消息 MUST 包含具体的修复指引。"
  r45,分级校验消息,"`llman sdd validate` MUST 根据 strict/non-strict 模式输出不同级别的完整度消息：non-strict 模式下缺少可选 artifact 时 MUST 输出可见的 INFO 级阶段提示（即使整体校验通过，draft 等非 full 阶段的提示仍 MUST 被打印给用户）；strict 模式下未达到 designed 阶段 MUST 输出 WARN（由 INFO 升级）。校验输出 MUST 在所有阶段都包含当前阶段标识，且不得在 valid 时吞掉阶段提示。"
  r46,List 与 Show 阶段输出,`llman sdd list` MUST 在变更列表输出中包含 stage 列，显示每个变更的完整度阶段（draft/specified/designed/full）。JSON 输出 MUST 包含 `stage` 字段。`llman sdd show <id>` 在展示 change 时 MUST 输出当前阶段标识：非 JSON（文本）模式在标题后打印 stage 行；JSON 模式 MUST 包含 `stage`（draft/specified/designed/full）、`artifacts`（已存在的 artifact 文件名列表）与 `readyToImplement`（当且仅当 stage 为 full 时为 true）字段。`stage` MUST 由 artifacts 存在性隐式推断（与 validate 的 `determine_stage` 同源），不引入额外状态文件。
scenarios[119]{req_id,id,given,when,then}:
  r1,初始化新项目,"",用户在不存在 `llmanspec/` 的目录执行 `llman sdd init`,必要的目录结构与模板文件被创建
  r1,初始化指定路径,"",用户执行 `llman sdd init <path>`,在 `<path>` 下创建 `llmanspec/` 结构与模板文件
  r1,初始化时生成提示块,"",`llman sdd init` 生成 `llmanspec/AGENTS.md`,"文件中包含 `<!-- LLMANSPEC:START -->` 与 `<!-- LLMANSPEC:END -->` 包裹的提示块"
  r1,初始化时写入配置,"","`llman sdd init --lang en` 运行",`llmanspec/config.yaml` 被写入且 locale 为 `en`
  r1,"初始化时写入-schema-头注释","",`llman sdd init` 生成 `llmanspec/config.yaml`,"文件顶部包含 `yaml-language-server` schema 头注释"
  r1,"初始化时生成根-agents","",`llman sdd init` 运行,repo 根目录 `AGENTS.md` 被创建或刷新受管块并指向 `llmanspec/AGENTS.md`
  r1,"已存在-llmanspec-目录","",用户在已有 `llmanspec/` 的目录执行 `llman sdd init`,命令返回错误且不做任何更改
  r1,"openspec-共存","",`openspec/` 已存在但 `llmanspec/` 不存在,`llman sdd init` 仅创建 `llmanspec/` 且不修改 `openspec/`
  r2,更新指令文件,"",用户执行 `llman sdd update`,指令/模板文件被刷新且现有 specs 与 changes 内容保持不变
  r2,更新指定路径,"",用户执行 `llman sdd update <path>`,仅更新 `<path>/llmanspec/` 下的指令与模板文件
  r2,未初始化时更新,"",目标路径下不存在 `llmanspec/`,命令返回错误并提示先执行 `llman sdd init`
  r2,保留用户自定义内容,"",`llmanspec/AGENTS.md` 含有用户自定义内容且包含 LLMANSPEC 受管块,update 仅替换受管块并保留其他内容
  r2,"更新根-agents","",repo 根目录 `AGENTS.md` 存在且包含 LLMANSPEC 受管块,update 仅替换受管块并保留其他内容
  r2,"openspec-共存","",`openspec/` 与 `llmanspec/` 同时存在,`llman sdd update` 不修改 `openspec/`
  r3,"初始化写入-locale-配置","","用户执行 `llman sdd init --lang zh-Hans`","`llmanspec/config.yaml` 写入 `locale: zh-Hans` 且包含版本字段"
  r3,"locale-回退链","","配置 locale 为 `zh-Hans` 但缺少 `templates/sdd/zh-Hans/...`","按 `zh-Hans` → `zh` → `en` 顺序回退"
  r3,"locale-仅影响模板与-skills","","`llmanspec/config.yaml` 设置 locale 为 `zh-Hans`",`llmanspec/AGENTS.md` 与 sdd skills 使用中文模板
  r4,"生成包含-specs-compact-skill","","用户执行 `llman sdd update-skills --no-interactive --tool codex`","目标路径下存在 `llman-sdd-specs-compact/SKILL.md`"
  r4,结构化协议在已生成技能中可见,"","用户执行 `llman sdd update-skills --no-interactive --all`","生成的 `llman-sdd-archive` 与 `llman-sdd-explore` 等技能均包含统一结构化章节"
  r5,引用模板单元并成功渲染,"",模板声明注入一个已注册的共享单元,生成结果中包含该单元的渲染内容且无未解析占位符
  r5,模板单元缺失,"",模板声明的单元标识符在当前 locale 与回退链中都不存在,命令报错并退出非零
  r5,模板单元注册冲突,"",同一渲染上下文中存在重复的单元标识符定义,命令报错并拒绝继续渲染
  r6,"帮助文本包含-import-export-convert","","用户执行 `llman sdd --help`",帮助文本包含 `import`、`export` 与 `convert`
  r6,"style-参数强约束","","用户执行 `llman sdd import` 或 `llman sdd export` 且缺少 `--style`","命令返回非零并提示 `--style openspec` 为必填"
  r6,旧命名不可用,"","用户执行 `llman sdd migrate --from openspec`",命令返回未知子命令错误
  r7,"style-参数缺失","","用户执行 `llman sdd import` 或 `llman sdd export` 且未传 `--style`","命令返回非零并提示需要 `--style openspec`"
  r7,"style-参数非法","","用户执行 `llman sdd import --style unknown`",命令返回非零并提示仅支持 `openspec`
  r7,非标准目录复制并警告,"",源目录包含非标准目录（例如 `openspec/explorations/`）,命令输出 warning
  r7,目标冲突即失败,"",目标目录存在计划写入的同名文件,命令返回非零并中止
  r8,非交互环境仅演练,"","用户在非交互环境执行 `llman sdd export --style openspec`","命令输出 dry-run 计划并返回非零"
  r8,交互双确认后执行,"","用户在交互环境执行 `llman sdd import --style openspec` 且通过双确认",命令执行实际写入
  r8,默认不删除旧目录,"",迁移写入成功后进入“删除旧目录”提示,默认选项为“不删除”
  r9,"导出自动创建-openspec-config","","用户执行 `llman sdd export --style openspec` 且目标缺失 `openspec/config.yaml`","命令创建该文件并写入 `schema: spec-driven`"
  r9,"导入补齐-frontmatter","","用户执行 `llman sdd import --style openspec` 且主 spec 缺失 llman frontmatter",命令在写入时补齐所需 frontmatter 键
  r10,默认列出变更,"",用户执行 `llman sdd list`,输出包含 `llmanspec/changes/` 下的变更目录（排除 `archive`）
  r10,"列出-specs","","用户执行 `llman sdd list --specs`",输出包含 `llmanspec/specs/` 下的 spec 目录
  r10,"列出变更-显式","","用户执行 `llman sdd list --changes`",输出包含 `llmanspec/changes/` 下的变更目录（排除 `archive`）
  r10,查看变更,"","用户执行 `llman sdd show <change-id> --type change`","输出 `llmanspec/changes/<change-id>/proposal.md` 的原始内容"
  r10,"查看-spec","","用户执行 `llman sdd show <spec-id> --type spec`","输出 `llmanspec/specs/<spec-id>/spec.md` 的原始内容"
  r10,自动识别与歧义处理,"","用户执行 `llman sdd show <item-name>` 且未指定 `--type`","自动识别 change/spec；若同时匹配则报错并提示使用 `--type change|spec`"
  r10,"json-输出-changes","","用户执行 `llman sdd list --json`","输出 JSON 结构：`{ \"changes\": [{ \"name\": \"...\", \"completedTasks\": 0, \"totalTasks\": 0, \"lastModified\": \"...\", \"status\": \"no-tasks|in-progress|complete\" }] }`"
  r10,"json-输出-specs","","用户执行 `llman sdd list --specs --json`","输出 JSON 数组，元素包含 `{ \"id\": \"...\", \"title\": \"...\", \"requirementCount\": 0 }`（与 `openspec spec list --json` 一致）"
  r10,"json-输出-show","","用户执行 `llman sdd show <id> --json`","输出 OpenSpec 对齐的 JSON（change: `id/title/deltaCount/deltas...`；spec: `id/title/overview/requirementCount/requirements/metadata...`）"
  r10,"json-输出-spec-过滤","","用户执行 `llman sdd show <spec-id> --json --requirement 1 --no-scenarios`",仅返回指定序号的 requirement 且不包含 scenarios
  r10,"json-输出-参数冲突","","用户执行 `llman sdd show <spec-id> --json --requirements --requirement 1`",命令返回错误并提示参数冲突
  r11,"show-交互选择","",用户执行 `llman sdd show` 且终端可交互,提示选择类型，提示语为 `What would you like to show?`
  r11,"show-非交互提示语","","用户执行 `llman sdd show` 且为非交互环境或使用 `--no-interactive`","输出以下提示并退出码为 1： `Nothing to show. Try one of:` ` llman sdd show <item>` ` llman sdd show --type change` ` llman sdd show --type spec` `Or run in an interactive terminal.`"
  r11,"validate-交互选择","",用户执行 `llman sdd validate` 且终端可交互,提示选择验证范围，提示语为 `What would you like to validate?`
  r11,"validate-非交互提示语","","用户执行 `llman sdd validate` 且为非交互环境或使用 `--no-interactive`","输出以下提示并退出码为 1： `Nothing to validate. Try one of:` ` llman sdd validate --all` ` llman sdd validate --changes` ` llman sdd validate --specs` ` llman sdd validate <item-name>` `Or run in an interactive terminal.`"
  r12,非法场景标题,"","某个 requirement 使用了不合法的场景标题（非 `#### Scenario:`）",校验失败并报告具体文件
  r12,"缺少-purpose-或-requirements","",spec 缺少 `## Purpose` 或 `## Requirements` 章节,校验失败并报告具体文件
  r12,"requirement-缺少-shall-must","",requirement 文本未包含 `SHALL` 或 `MUST`,校验失败并报告具体 requirement
  r12,"renamed-缺少配对","",delta 包含 `## RENAMED Requirements` 但未提供 FROM/TO 配对,校验失败并报告具体文件
  r12,合法变更,"",变更包含完整且格式正确的 deltas 与必需文件,校验成功并返回退出码 0
  r12,"校验-json-输出","","用户执行 `llman sdd validate <id> --json`",输出包含 `items`、`summary` 与 `version` 的机器可读 JSON
  r12,校验歧义,"","`llman sdd validate <item-name>` 同时匹配 change 与 spec","报错并提示使用 `--type change|spec`"
  r13,缺少必需章节,"",spec 缺少 `## Purpose` 或 `## Requirements`,输出提示包含期望标题与最小示例片段
  r13,场景标题格式错误,"","requirement 使用了非 `#### Scenario:` 标题","输出提示包含标准 `#### Scenario:` 示例"
  r13,"无-delta-变更","",change 目录中未找到任何 delta,输出提示包含 delta section 示例与文件路径提示
  r14,"缺少-frontmatter","",spec 文件缺少 YAML frontmatter 或缺少任一必需键,`llman sdd validate` 报错并提示补充校验元数据
  r14,"frontmatter-字符串与列表","",`llman_spec_valid_scope` 使用字符串或 YAML 列表,`llman sdd validate` 解析为等价的路径列表
  r15,"范围触及但-spec-未更新","",`<base>..HEAD` 变更触及 `llman_spec_valid_scope`，且 spec 文件未更新,staleness 状态为 `STALE` 且在输出中提示
  r15,"spec-更新但范围未触及","",spec 文件更新，但变更未触及 `llman_spec_valid_scope`,staleness 状态为 `INFO`
  r15,"无法解析-base","","git 无法解析 merge-base","staleness 记录为 `WARN`，`--strict` 时视为错误"
  r16,兼容入口仍可归档,"","用户执行 `llman sdd archive add-sample`","命令成功归档并与 `llman sdd archive run add-sample` 结果一致"
  r16,"run-子命令行为与历史一致","","用户执行 `llman sdd archive run <change-id> --skip-specs`",仅移动目录到 archive 且不修改主 specs
  r16,"force-仍保持隐藏","","用户执行 `llman sdd archive --help` 或 `llman sdd archive run --help`","帮助文本不显示 `--force`"
  r17,"归档-dry-run","","用户执行 `llman sdd archive <change-id> --dry-run`",输出预览信息且文件系统无任何改动
  r18,单文件冻结,"",用户执行 `llman sdd archive freeze`,生成或更新 `freezed_changes.7z.archived`
  r18,"冻结-dry-run","","用户执行 `llman sdd archive freeze --dry-run`",仅输出候选与目标文件
  r18,冻结失败保护,"",冻结写入冷备文件失败,命令返回非零
  r18,解冻默认目录,"",用户执行 `llman sdd archive thaw`,内容恢复到 `llmanspec/changes/archive/.thawed/`
  r18,解冻过滤与目标目录,"","用户执行 `llman sdd archive thaw --change <id> --dest <path>`",仅恢复所选目录到 `<path>`
  r19,模板版本一致性检查,"","维护者运行 `just check-sdd-templates`",命令在缺失元信息、缺少 locale 模板或版本不一致时退出非零
  r20,校验失败阻止归档,"","用户执行 `llman sdd archive <change-id>` 且任一 spec 校验失败",命令退出非零，且不写入/移动任何文件
  r20,"staleness-警告视为失败","",staleness 状态为 `STALE` 或 `WARN`,归档失败并提示修复
  r20,允许强制绕过,"","用户执行 `llman sdd archive <change-id> --force`",归档继续执行即使校验失败
  r20,"force-参数隐藏","","用户执行 `llman sdd archive --help`","帮助输出不包含 `--force`"
  r20,"skip-specs-跳过校验","","用户执行 `llman sdd archive <change-id> --skip-specs`",不执行归档前的 spec 校验
  r20,错误提示不引导绕过,"",归档因校验失败而中止,"输出仅提示修复校验问题，不提示 `--force`"
  r21,"name-与目录一致","","`llman sdd update-skills` 写入 `llman-sdd-archive/SKILL.md`","frontmatter `name` 为 `llman-sdd-archive`"
  r21,"description-非空","","`llman sdd update-skills` 生成任意 SKILL.md",frontmatter `description` 为非空字符串
  r22,"skills-不包含-force","","维护者运行 `llman sdd update-skills`","生成的 SKILL.md 不提及 `--force`"
  r23,"缺失-future-不阻塞","",change 不包含 `future.md`,"`llman sdd validate <change-id> --type change` 仍可通过"
  r23,"future-条目可转执行","",生成后的 skill/template 处理 `future.md` 中的延期或分叉条目,输出包含 `now|later|drop` 分类与后续落地动作建议
  r24,"skills-模板包含结构化章节","","维护者运行 `llman sdd update-skills`",生成技能中可见结构化章节
  r24,模板无外部技能硬依赖,"",检查生成的 `SKILL.md`,不存在“先调用外部技能再执行”的硬依赖描述
  r25,"sdd-重构后回归","",`src/sdd/` 的模块结构被重组,"`sdd init/update/update-skills/list/show/validate/archive` 的行为与输出保持不变"
  r26,"拒绝路径穿越-id","",用户运行 `llman sdd archive ../oops`,命令返回错误，且不会移动或修改任何文件
  r27,"同时传入-specs-与-changes","","用户运行 `llman sdd list --specs --changes`",命令返回错误并以非零退出
  r28,"multi-tool-path-被拒绝","","用户运行 `llman sdd update-skills --no-interactive --all --path ./skills-out`",命令以非零退出并解释如何安全地按 tool 生成（避免覆盖）
  r29,"仅生成-workflow-commands","","用户执行 `llman sdd update-skills --no-interactive --tool claude --commands-only`","`.claude/commands/llman-sdd/` 下仅存在命令文件（`new/continue/ff/apply/verify/sync/archive/explore/onboard`）"
  r29,"命令绑定指向-llman-sdd-工作流","","用户调用任一 `/llman-sdd:<command>` 触发对应命令绑定",命令绑定文本引导其在 `llmanspec/` 下执行对应动作（创建 artifacts / 实施 tasks / 归档等），并引用 `llman sdd` 命令用于验证闭环
  r29,"codex-不生成-command-prompts","","用户执行 `llman sdd update-skills --no-interactive --tool codex`","命令仅生成/刷新 Codex skills，且 MUST NOT 在 `.codex/prompts/` 下生成 `llman-sdd-*.md`"
  r30,批量归档多个变更,"","用户调用 `llman-sdd-archive` 并提供多个 change IDs","skill 指导依次运行 `llman sdd archive run <id>`（或兼容入口 `llman sdd archive <id>`），并在结束后运行 `llman sdd validate --strict --no-interactive`"
  r31,探索模式进入,"","用户调用 `llman-sdd-explore`（或通过 `/llman-sdd:explore` 进入）",AI 助手进入探索模式，可阅读代码和创建 artifacts，但不实现功能
  r31,探索模式退出,"",用户在探索模式中准备开始实现,"skill 引导用户使用 `llman-sdd-new-change`、`llman-sdd-ff` 或 `/llman-sdd:new` 开始正式工作流"
  r32,"continue-draft-提示",变更处于 draft 阶段（仅 proposal.md）,"用户调用 llman-sdd-continue",skill 显式提示这是 draft 提案，并指引按 specs → design → tasks 顺序长大到 full 后方可实现
  r33,"apply-draft-守卫",变更处于非 full 阶段（如 draft，仅有 proposal.md）,"用户调用 llman-sdd-apply","skill 通过 show 读取 stage 后拒绝实施并 STOP，引导使用 llman-sdd-continue 长大到 full"
  r33,"apply-full-放行",变更处于 full 阶段（proposal.md + specs/ + design.md + tasks.md）,"用户调用 llman-sdd-apply",skill 正常实施 tasks.md 中的任务
  r34,快速创建变更,"","用户调用 `llman-sdd-ff <change-name>`",skill 询问变更描述后依次创建 proposal、specs、design、tasks
  r34,变更已存在,"","用户调用 `llman-sdd-ff <change-name>` 但该变更已存在","skill 提示使用 `llman-sdd-continue` 继续"
  r35,"verify-non-full-守卫",变更处于非 full 阶段,"用户调用 llman-sdd-verify","skill 通过 show 读取 stage 后拒绝验证并 STOP，引导使用 llman-sdd-continue 长大到 full"
  r36,"同步-delta-specs","","用户调用 `llman-sdd-sync <change-name>`",skill 提供可复现步骤，指导手动将 delta specs 同步到主 specs 目录
  r36,同步后验证,"",delta specs 已合并到主 specs,"skill 运行 `llman sdd validate --specs` 验证合并结果"
  r37,"archive-applies-ops-and-writes-merged-ison","",a change contains delta spec ops and a user runs `llman sdd archive <change>`,archive applies add/modify/remove/rename operations over requirement ids
  r38,"generate-delta-skeleton-and-add-an-op","",a maintainer creates a new change directory and needs to add a delta requirement,the maintainer can use the CLI to generate a delta spec skeleton and add an op without manual table editing
  r39,"agent-fetches-spec-feature-name-cheaply","",an agent needs the spec feature name/purpose for prompt assembly,"the agent can call `llman sdd show <spec-id> --type spec --json --meta-only`"
  r40,"validate-blocks-legacy-payloads","","a user runs `llman sdd validate` (with or without `--strict`) on a project containing JSON-in-` ```ison ` payloads","validation fails with non-zero exit"
  r41,"user-chooses-when-to-switch-formats","","a repository remains on legacy JSON-in-` ```ison ` payloads",`llman sdd validate` fails with a clear canonical rewrite hint
  r42,"propose-creates-a-change-and-artifacts","","a user invokes `llman-sdd-propose` with a change description (and/or a change id)","the assistant creates `llmanspec/changes/<change-id>/` with `proposal.md`, `specs/**`, and `tasks.md` (and `design.md` when needed)"
  r43,"仅有-proposal",变更目录仅包含 proposal.md,"用户执行 `llman sdd validate <change-id>`",输出包含阶段标识 `draft`
  r43,完整变更,变更目录包含 proposal.md + specs/ + design.md + tasks.md,"用户执行 `llman sdd validate <change-id>`",输出包含阶段标识 `full`
  r44,"tasks-无-design",变更目录包含 proposal.md、specs/、tasks.md 但缺少 design.md,"用户执行 `llman sdd validate <change-id>`",校验失败并输出 ERROR 级别消息
  r44,"tasks-有-design",变更目录包含 proposal.md、specs/、design.md、tasks.md,"用户执行 `llman sdd validate <change-id>`",不产生 design 前置约束相关的错误
  r45,"non-strict-draft-可见",变更处于 draft 阶段（仅 proposal.md）,"用户执行 `llman sdd validate <change-id>`（非 strict）",输出包含可见的 INFO 级阶段提示，且不因整体校验通过（valid）而被吞掉
  r45,"strict-draft-warn",变更处于 draft 阶段,"用户执行 `llman sdd validate <change-id> --strict`",输出由 INFO 升级的 WARN 级阶段提示（strict 下为 ERROR）
  r46,"show-json-stage",变更目录存在且包含 proposal.md,"用户执行 `llman sdd show <id> --json --type change`",JSON 输出包含 stage、artifacts 与 readyToImplement 字段，且 readyToImplement 在 stage 非 full 时为 false
  r46,"show-text-stage",变更目录存在,用户执行 `llman sdd show <id>`（非 JSON）,输出包含当前阶段标识（draft/specified/designed/full）
