SDD 能力底座
状态文件与门禁
.aiko.yaml 字段、写入后校验、phase-guard 三形态、mtime 管辖与 vibe
.aiko.yaml 是 change 的唯一权威状态。这一页是它的字段手册和门禁机制。
关键字段
| 字段 | 取值 | 说明 |
|---|---|---|
workflow | full / spec / hotfix / tweak | 工作流（init 时确认，open 阶段可重选） |
phase | open / design / build / verify / archive | 当前阶段（禁止直接 set，走 transition） |
requirement | sdd-input slug / chat | 需求归属（init 第三参或 set 补挂） |
design_doc / plan | 路径 | Superpowers 产物（full） |
build_mode | subagent-driven-development / executing-plans / direct | 执行方式（direct 仅 hotfix/tweak/spec） |
tdd_mode | tdd / direct | TDD 强度 |
review_mode | off / standard / thorough | 验证期代码审查 |
isolation | branch / worktree | 隔离方式 |
verify_mode | light / full | 验证深度 |
verify_result | pending / pass / fail | 验证结论 |
verification_report / branch_status | 路径 / pending·handled | 归档证据 |
写入与校验
- 写入一律走
aiko-state.sh（init / set / transition），字段名白名单 + 枚举校验 - 每次写入后过
aiko-yaml-validate.sh（必填字段+枚举+路径存在性），坏文件当场失败 - 面板严格镜像
.aiko.yaml，不做文件存在性推断
phase-guard（写文件门禁）
- 判定源：写目标落在 change 目录 → 用该 change 的
.aiko.yaml；否则按 mtime 最近的活跃 change 管辖（多 change 并行不串） - 白名单：open/design 只许规格产物；build 起放源码（full 要五字段齐）；archive 封笔
- 三形态：Claude（PreToolUse hook，exit code）、Codex（managed hook，deny JSON）、opencode（plugin throw）——共享同一
aiko-hook-guard.sh - vibe：
AIKO_SDD_MODE=vibe全阶段放行，门禁只在 SDD 会话生效
校验报错怎么办
| 报错 | 处理 |
|---|---|
Unknown field | 字段名拼错，看 aiko-state.sh 的合法字段列表 |
tdd_mode must be tdd or direct（等枚举错） | 值不在枚举内，按提示重设 |
| 校验器报缺字段/非法值 | .aiko.yaml 被手写坏：对照字段表修回，再重跑触发校验的命令 |
design_doc must point to an existing… | 先产 Design Doc 再 set <change> design_doc <路径> |