indexion-sdd

indexion SDD（规格驱动开发）

将 indexion 的量化规格对齐工具与 SDD Agent 工作流（cc-sdd、codex 等）对接。

提供：RFC/文档 → SDD 草案、规格↔实现偏差检测，以及一个验证循环，将 indexion 的量化结果反馈给由 Agent 驱动的定性审查。

适用场景

• 用户想将 RFC 或规格实现为库/软件包
• 用户要求验证规格与实现是否一致
• 用户想使用 cc-sdd + codex + indexion 搭建 SDD 项目
• 用户说“运行 SDD 循环”或“根据规格进行验证”
• codex spec-impl 完成后，在合并前检查是否存在偏差

重要提示

• 将 cc-sdd 的 --lang 设置为与实现语言一致，而不是规格语言。 如果代码使用英语，请使用 --lang en。语言不匹配会破坏 spec align diff 的词汇匹配。

流程：RFC → 实现 → 验证

步骤 0：项目设置

# Create project directory
mkdir my-rfc-impl && cd my-rfc-impl

# Install cc-sdd for your agent — set lang to match the code language
npx cc-sdd@latest --codex-skills --lang en --yes   # codex (skills mode)
npx cc-sdd@latest --claude-skills --lang en --yes   # claude (skills mode)

# Initialize project (language-specific)
# e.g., cargo init, npm init, moon new, etc.

# Initialize git
git init && git add -A && git commit -m "init"

继续之前，确认 indexion 可用。偏差检查关卡（步骤 2.5）和验证循环（步骤 3）都依赖它：

indexion --version                       # must be installed
indexion kgf edges <any-source-file>     # must detect language and show edges

如果未安装 indexion，请先安装。如果无法识别规格格式对应的 KGF，请将 indexion 更新到包含该格式的版本。如果无法解决，请参阅步骤 2.7 中的备用方案。

步骤 1：规格 → SDD 草案（indexion）

获取规格文档（RFC、ISO 标准等），并进行准备：

# For RFC: save as markdown or .rfc.txt
indexion spec draft --output .kiro/specs/<feature>/requirements.md rfc_document.md

# For ISO/IEC standards: extract text from PDF with cleanup, then draft
python3 scripts/extract_iso_text.py spec.pdf <start_page> <end_page> spec.spec.txt
indexion spec draft --output .kiro/specs/<feature>/requirements.md spec.spec.txt

# Create spec.json (set requirements.generated=true, approved=true)

输出采用 ### Requirement N: 和 #### N.M: 层级结构，与 cc-sdd 预期的 ID 格式一致。Agent 的 $kiro-spec-requirements 阶段将进一步细化为包含验收标准的 EARS 格式。

支持的规格格式：

格式	扩展名	KGF 规格
RFC 纯文本	.rfc.txt	rfc-plaintext
ISO/IEC 技术文档	.spec.txt	technical-document
Markdown（README 等）	.md	markdown

步骤 1.5：规格忠实度检查（indexion）

编写需求后，验证其是否涵盖源规格：

# Check requirements ↔ original spec alignment
# (spec align now accepts document files as impl when no code files are found)
indexion spec align diff .kiro/specs/<feature>/requirements.md spec.spec.txt \
  --format markdown --threshold 0.3

# SPEC_ONLY items = requirements not covered by original spec
# DRIFTED items = requirements using different vocabulary from original spec

可追溯链： spec align 用于对齐处于相同抽象层级的文档。要实现完整的可追溯性，请检查每一对相邻文档：

# 1. Source spec ↔ requirements (fidelity)
indexion spec align diff requirements.md source-spec.spec.txt --threshold 0.3
# 2. Requirements ↔ design (design coverage)
indexion spec align diff requirements.md design.md --threshold 0.3
# 3. Requirements ↔ implementation (impl coverage) — after $kiro-impl
indexion spec align diff requirements.md src/ --threshold 0.3

不要将源规格直接与设计或代码对齐——它们的词汇空间差异太大（规范性规格语言、软件设计语言与代码标识符）。每一步都只跨越一个抽象层级的差距。

语义忠实度审查（无法自动化）：

spec align 会检查词汇重合度，但无法检测使用相同词汇却颠倒源规格意图的需求。常见的失败模式如下：

• 源规格：“DCTDecode 过滤器应解码 JPEG 数据并生成样本”
• 需求草案：“对于 DCTDecode，解码器应返回一个错误，指出该过滤器尚不受支持”

两者都提到了“DCTDecode”“过滤器”和“应”——词汇匹配，因此 spec align 会报告 MATCHED。但需求表达的意思与规格要求完全相反。这会造成一个隐蔽的差距，只有端到端测试失败时才会暴露（步骤 2.9）。

spec draft 生成需求后，请检查以下模式：

• "not yet supported"、"not implemented"、"placeholder"、"stub"——这些表示草案回避了某项规格要求
• 对于源规格要求“应解码/处理/转换”的内容，需求却写成“应返回错误”——意图颠倒
• 将多项规格功能归入单个“不支持”类别的需求——每项规格功能都应有独立的需求

继续步骤 2 前，请先修正这些问题。若不修正，就会造成符合规格的假象，只有端到端测试才能揭示问题。

步骤 2：Agent SDD 阶段（codex / claude）

cc-sdd v3+ 使用 skills 模式（$kiro-spec-* commands）。

各阶段之间设置 indexion 门禁的非交互式执行：

FEATURE=<feature>
SPEC_DIR=.kiro/specs/$FEATURE
REPORT_DIR=.indexion/sdd-reports/$FEATURE
mkdir -p $REPORT_DIR

# Helper: approve a phase in spec.json
approve() { jq --arg p "$1" '.approvals[$p].approved = true' $SPEC_DIR/spec.json > /tmp/spec.json && mv /tmp/spec.json $SPEC_DIR/spec.json; }

# --- Design ---
codex exec --full-auto --json -C . "\$kiro-spec-design $FEATURE -y" > $REPORT_DIR/design.jsonl
approve design
# Verify requirements ↔ design
indexion spec align diff $SPEC_DIR/requirements.md $SPEC_DIR/design.md \
  --format markdown --threshold 0.3 | tee $REPORT_DIR/req-design-align.md
git add $SPEC_DIR && git commit -m "spec: design for $FEATURE"

# --- Tasks ---
codex exec --full-auto --json -C . "\$kiro-spec-tasks $FEATURE -y" > $REPORT_DIR/tasks.jsonl
git add $SPEC_DIR && git commit -m "spec: tasks for $FEATURE"

# --- Impl Phase A: Types & Structures ---
# Phase A implements type definitions, error types, data structures,
# and public API surface. No logic implementations yet.
cat > $REPORT_DIR/impl-phase-a.md << 'PHASE_A_EOF'
## Context

You are implementing Phase A (Types & Structures) of the <FEATURE> feature.
Read `.kiro/specs/<FEATURE>/tasks.md` for task details and
`.kiro/specs/<FEATURE>/design.md` for the design.

## Phase A Scope

In this phase, implement ONLY:
- Public type definitions (structs, enums, type aliases)
- Error types
- Constants and configuration structures
- Public API function signatures with placeholder bodies
- Test scaffolding (test files with placeholder tests)

Do NOT implement:
- Parsing, conversion, or transformation logic
- Algorithm implementations
- Complex function bodies beyond trivial constructors/accessors

## Per-Task Drift Gate

After completing each task and committing, run:

```bash
indexion spec align diff .kiro/specs/<FEATURE>/requirements.md src/<pkg>/ --format markdown --threshold 0.3
indexion spec align status .kiro/specs/<FEATURE>/requirements.md src/<pkg>/ --threshold 0.3 --fail-on drifted

如果与你的任务相关的需求仍有 DRIFTED 项目，请修复它们 （在公开声明的文档注释中添加规范词汇）并重新提交。

所有任务完成后，spec align status --fail-on drifted 必须以状态码 0 退出。

重要事项

完成任务后提交你的工作。不要留下未提交的更改。 PHASE_A_EOF

sed -i '' "s//$FEATURE/g; s//$PKG/g" $REPORT_DIR/impl-phase-a.md

codex exec --full-auto --json -C .
"$(cat $REPORT_DIR/impl-phase-a.md)" > $REPORT_DIR/impl-phase-a.jsonl

等待阶段 A 完成后再运行门禁

indexion spec align status $SPEC_DIR/requirements.md src/$PKG/
--threshold 0.3 --fail-on drifted git add . && git commit -m "impl: Phase A types for $FEATURE"

--- 实现阶段 B：逻辑与算法 ---

阶段 B 实现实际处理逻辑。阶段 A 的类型

已经提交，因此阶段 B 侧重于函数体。

cat > $REPORT_DIR/impl-phase-b.md << 'PHASE_B_EOF'

上下文

你正在实现 功能的阶段 B（逻辑与算法）。 阶段 A（类型定义）已经提交。阅读 src/<pkg>/ 中现有的类型 定义，以及 .kiro/specs/<FEATURE>/design.md 中的设计。

阶段 B 范围

在此阶段，实现：

• 解析逻辑（读取器、解码器、解释器）
• 转换算法
• 超出基本类型构造的验证逻辑
• 类型之间的集成（将读取器连接到数据结构）
• 包含真实断言的完整测试实现

每项描述处理、转换、解释 或验证的需求都必须有对应的函数实现，而不能 只有类型定义。

SHALLOW 解决规则

当某项需求与某个文件中的类型定义匹配，而该文件没有非平凡函数实现（超过 4 行）时， 就会检测为 SHALLOW。解决方法：

在定义类型的同一文件中添加函数。

不要把逻辑放在单独的文件中——SHALLOW 是按文件检查的。如果某个类型定义在一个文件中，而其方法在另一个文件中， 那么该类型所在的文件仍然没有函数，会触发 SHALLOW。

可解决 SHALLOW 的函数示例：

• 类型上的方法，包含超过 4 行的逻辑（match 分支、循环、 验证、计算）
• 执行非平凡工作的构造函数（解析、验证）

无法解决 SHALLOW 的示例（过于简单，≤4 行）：

• 仅返回结构体字面量的默认构造函数
• 单行布尔访问器

每项任务的 Drift 门禁（含浅层检测）

完成每项任务并提交后，运行：

indexion spec align diff .kiro/specs/<FEATURE>/requirements.md src/<pkg>/ --format markdown --threshold 0.3
indexion spec align status .kiro/specs/<FEATURE>/requirements.md src/<pkg>/ --threshold 0.3 --fail-on any

--fail-on any 门禁包含 SHALLOW 检测：如果某项需求仅匹配到类型定义，而同一文件中没有函数实现， 则会将其标记为 SHALLOW。你必须添加函数 实现来解决 SHALLOW 项目。

如果仍有 DRIFTED、SPEC_ONLY 或 SHALLOW 项目，请先修复再继续。

所有任务完成后，spec align status --fail-on any 必须以状态码 0 退出， 且 Shallow: 0。

重要事项

完成任务后提交你的工作。不要留下未提交的更改。 PHASE_B_EOF

sed -i '' "s//$FEATURE/g; s//$PKG/g" $REPORT_DIR/impl-phase-b.md

codex exec --full-auto --json -C .
"$(cat $REPORT_DIR/impl-phase-b.md)" > $REPORT_DIR/impl-phase-b.jsonl & CODEX_PID=$!

**Monitor impl progress:**

```bash
# Real-time event stream
tail -f $REPORT_DIR/impl.jsonl | jq -r '
  if .type == "item.completed" and .item.type == "agent_message" then
    "MSG: " + (.item.text[:120])
  elif .type == "item.completed" and .item.type == "command_execution" then
    "CMD: " + (.item.command[:60]) + " -> " + (.item.exit_code|tostring)
  else empty end'

# Stall detection
ps -p $CODEX_PID -o cputime,%cpu
lsof -p $CODEX_PID 2>/dev/null | grep tcp

# Resume after interruption
codex exec resume --last

操作说明：

• 始终将 --json 与文件重定向和 tail -f 配合使用。通过 | tail 管道传输会抑制所有输出，直到执行完成。
• 对于较长的提示词，将其写入文件并使用 $(cat file.md)。Shell HEREDOC 与 $() 配合使用可能会导致 stdin 阻塞。
• 长时间运行实现任务期间，使用 /loop（Claude Code）每隔 60-120 秒 检查一次 git log --oneline -1 + ps。

步骤 2.5：逐任务漂移门禁（indexion）

每次 $kiro-impl 任务提交后，运行规格对齐检查，确认该任务已弥合对应的需求差距。如果当前任务涉及的需求仍为 DRIFTED、SPEC_ONLY 或 SHALLOW，则不要继续下一个任务。

阶段 A 门禁（仅类型——预期并容许出现 SHALLOW）：

indexion spec align status $SPEC_DIR/requirements.md src/ --threshold 0.3 --fail-on drifted

阶段 B 门禁（逻辑——SHALLOW 必须为零）：

indexion spec align diff $SPEC_DIR/requirements.md src/ --format markdown --threshold 0.3
indexion spec align status $SPEC_DIR/requirements.md src/ --threshold 0.3 --fail-on any

**SHALLOW 检测：**如果某项需求仅与某个文件中的类型/结构体/枚举声明匹配，而该文件不包含非平凡的函数实现（超过 4 行），spec align 会将其归类为 SHALLOW。这可以捕获两种情况：

1. Codex 编写类型定义以满足词汇匹配，却遗漏了需求所要求的实际处理逻辑。
2. Codex 在与类型定义不同的文件中添加了逻辑。SHALLOW 按文件检查，因此，即使某个文件中的类型只有另一个文件中才有方法，包含该类型的文件仍会触发 SHALLOW。

**解决方法：**在定义类型的同一文件中添加方法。平凡函数（构造函数、单行访问器，≤4 行）不计入。示例请参阅阶段 B 提示词模板。

在 Codex 提示词中加入此门禁时，应指示 Agent 在每次任务提交后运行这些命令，并在继续之前修复所有标记项。提示词中的示例指令块：

After completing each task (commit), run:
  indexion spec align diff ... --threshold 0.3
  indexion spec align status ... --threshold 0.3 --fail-on any
If DRIFTED, SPEC_ONLY, or SHALLOW items remain for the requirement
your task addresses, fix them before moving to the next task.
- DRIFTED: add spec vocabulary to public declaration doc comments
- SPEC_ONLY: implement the missing requirement
- SHALLOW: add non-trivial function implementations (>4 lines) to the
  SAME FILE where the matched type is defined. Do not add logic in a
  separate file — SHALLOW checks per-file.
When all tasks are done, spec align status --fail-on any must exit 0
with Shallow: 0.

步骤 2.6：阶段 B 迭代（SHALLOW 解决轮次）

阶段 B 很少能在一次 Codex 会话中解决所有 SHALLOW 项。常见原因：

• Codex 在新文件中添加逻辑，而不是在类型定义文件中添加
• Codex 添加了不计入统计的平凡构造函数/访问器（≤4 行）
• 添加了新的类型定义，却没有对应的逻辑

迭代流程：

每次阶段 B 会话完成后：

1. 运行 SHALLOW 审计：

   indexion spec align status $SPEC_DIR/requirements.md src/$PKG/ \
     --threshold 0.3 --fail-on shallow
   

2. 如果 Shallow: 0，则继续进行端到端验证（步骤 2.9）。

3. 如果 SHALLOW > 0，找出具体项：

   indexion spec align diff $SPEC_DIR/requirements.md src/$PKG/ \
     --format markdown --threshold 0.3 | grep SHALLOW
   

4. 编写有针对性的轮次提示词，其中：

   • 明确列出剩余的 SHALLOW 项
   • 指出需要添加函数的确切文件
   • 说明规则：在与类型相同的文件中添加函数
   • 指定要添加的方法（不要只写“修复 SHALLOW”）

5. 启动下一轮：

   codex exec --full-auto --json -C . \
     "$(cat $REPORT_DIR/round-N.md)" > $REPORT_DIR/round-N.jsonl &
   

**通常需要 2-3 轮。**第 1 轮添加核心逻辑，第 2 轮强制要求在同一文件中添加方法，第 3 轮处理剩余的边缘情况。

步骤 2.7：停滞检测与恢复

Codex 进程可能会停滞（API 连接丢失、审查循环受阻等）。在较长的阶段 B 会话中，这种情况很常见。

检测：

# Check process vitals
ps -p $CODEX_PID -o cputime,%cpu,etime
lsof -p $CODEX_PID 2>/dev/null | grep tcp

# Stall indicators (all must be true):
# - CPU time not increasing over 2+ checks
# - 0.0% CPU
# - No TCP connections
# - JSONL event count not increasing

恢复——绝不要手动提交：

确认停滞后：

1. 终止进程：kill $CODEX_PID
2. 检查已完成的内容：git log、git status、git diff --cached
3. 如果存在未提交的工作且测试通过，生成 indexion 报告：

   indexion spec align diff $SPEC_DIR/requirements.md src/ \
     --format markdown --threshold 0.3 -o $REPORT_DIR/align-current.md
   indexion spec verify --spec="$SPEC_DIR/requirements.md" src/ \
     --format md -o $REPORT_DIR/verify-current.md
   

4. 编写恢复提示词文件，其中：
   • 说明哪些任务已提交，哪些任务有未提交的工作
   • 将 indexion 报告作为当前状态的证据
   • 指示 Codex 验证并提交未提交的工作，然后继续
   • 要求对所有剩余任务使用逐任务漂移门禁（步骤 2.5）
5. 重启：codex exec --full-auto --json -C . "$(cat $REPORT_DIR/resume-prompt.md)" > $REPORT_DIR/impl-resume.jsonl &

**绝不要手动提交实现代码。**所有提交都必须由 Codex Agent 完成。手动提交会绕过 SDD 协议（RED→GREEN 证据、审查、验证），并使工作流失效。

步骤 2.8：漂移门禁代理（当 Codex 无法运行 indexion 时）

Codex 会在 impl 项目目录中运行 indexion 命令。如果 indexion 未安装、版本过旧，或缺少所需的 KGF 规范， 漂移门禁命令会在 Codex 中失败或超时。

预防措施（推荐）： 在开始 SDD 运行前，于步骤 0 中确认 indexion 能在项目目录中正常工作：

indexion --version
indexion kgf edges <any-project-file>   # should show edges, not errors

如果 indexion 不可用或无法正常工作，请先安装或更新它。

后备方案 — 编排器侧漂移门禁：

如果运行前无法修复 indexion（例如，所需的 KGF 规范尚未发布）， 则由编排器在外部运行漂移门禁：

1. 告诉 Codex 在 impl 提示词中跳过漂移门禁命令：

   The `indexion` binary is not available in this environment.
   Skip drift gate commands. The orchestrator will run them externally.
   

2. 每次 Codex 提交后，编排器运行：

   indexion spec align diff $SPEC_DIR/requirements.md src/ \
     --format markdown --threshold 0.3
   indexion spec align status $SPEC_DIR/requirements.md src/ \
     --threshold 0.3 --fail-on any
   

3. 如果出现 DRIFTED/SPEC_ONLY 项目，则使用外部生成的报告 执行词汇修复步骤（步骤 3.5）。

--specs-dir 注意事项： 直接运行 indexion 二进制文件时 （而非通过项目的构建工具运行），它可能无法自动找到 KGF 规范。 请显式传入 --specs-dir：

indexion spec align diff ... --specs-dir /path/to/indexion/kgfs

否则，spec align 可能会返回“未找到对齐数据”，因为 系统无法识别需求文档格式。

步骤 2.9：端到端验证（SHALLOW 之后）

解决所有 SHALLOW 项目（Shallow: 0）后，请验证实现是否确实能 端到端正常工作。spec align 只检查词汇，无法确认功能是否正确。

编写 E2E 测试，使用真实输入数据测试完整的处理流程：

# Example E2E pattern:
# 1. Load a real input file (not just synthetic fixtures)
# 2. Run the full processing pipeline end-to-end
# 3. Assert the output matches expected results

SHALLOW=0 后常见的 E2E 失败模式：

• 类型定义和逻辑函数都已存在，但处理流程在真实输入上报错（缺少编码表、不支持的 字体类型等）
• 所有测试在合成测试样例上都通过，但在真实文件上失败，因为测试样例未覆盖完整的 代码路径
• 函数已实现，但未接入顶层 API

如果 E2E 测试失败，请编写额外的 Codex 提示词，针对具体失败进行修复。spec align 门禁可确保词汇保持对齐，同时由 Codex 修复实现。

步骤 2.10：并行执行功能

多个功能可以在多个 Codex 会话中并行运行：

for FEATURE in feature-a feature-b feature-c; do
  codex exec --full-auto --json -C . \
    "$(cat $REPORT_DIR/$FEATURE/impl-phase-b.md)" \
    > $REPORT_DIR/$FEATURE/impl-phase-b.jsonl 2>&1 &
  echo "$FEATURE: $!"
done

注意事项：

• 多个 Codex 会话可能会编辑相互重叠的文件（例如，多个 功能都写入 src/graphics/）。除非修改了相同的行，否则 Git 会自动合并。
• 如果会话在不同分支中提交，合并冲突由编排器负责处理。
• 使用 /loop 监控所有会话 — 检查每个 PID 的事件数、提交和 进程状态。
• 并行会话更容易停滞（API 速率限制）。 请按会话使用步骤 2.7 进行检测。

步骤 3：验证循环（indexion + Agent）

这是 indexion 在纯 Agent 审查之外发挥作用的地方。

# Quantitative analysis only (no agent)
indexion spec verify --spec='.kiro/specs/<feature>/requirements.md' src/lib/ --format md
indexion spec align diff .kiro/specs/<feature>/requirements.md src/lib/ --format markdown --threshold 0.3
indexion spec align status .kiro/specs/<feature>/requirements.md src/lib/ --threshold 0.3 --fail-on any

# Full loop: indexion quantitative + agent qualitative + auto-fix
./scripts/sdd-validate.sh <feature>           # validate only
./scripts/sdd-validate.sh <feature> --fix     # validate + auto-fix NO-GO tasks

验证脚本会：

1. 运行 spec verify（规范与 impl 之间的词汇差异）
2. 运行 spec align diff（需求级别的漂移）
3. 运行 spec align trace（可追溯性矩阵）
4. 运行 spec align status（CI 风格的通过/失败检查）
5. 将所有报告注入 Agent 的 validate-impl 提示词
6. Agent 根据具体任务编号给出 GO/NO-GO 决策
7. 使用 --fix 时，自动针对失败的任务重新运行 spec-impl

步骤 3.5：词汇对齐修复（indexion + agent）

在 $kiro-validate-impl 通过后，如果 spec align 显示 DRIFTED/SPEC_ONLY，说明实现功能正确，但文档注释中缺少规范词汇。此步骤用于弥补这一差距。

注意： $kiro-validate-impl（cc-sdd）不会在内部调用 indexion 的 spec align。此步骤用于衔接这两个工具。

# 1. Generate alignment reports
indexion spec align diff .kiro/specs/<feature>/requirements.md src/ \
  --format markdown --threshold 0.3 -o .indexion/sdd-reports/align-diff.md
indexion spec verify --spec='.kiro/specs/<feature>/requirements.md' src/ \
  --format md -o .indexion/sdd-reports/verify-gaps.md

# 2. Write a prompt file (avoid HEREDOC — use file to prevent stdin blocking)
cat > .indexion/sdd-reports/vocab-fix-prompt.md << 'EOF'
The spec alignment tool reports that several requirements are DRIFTED,
SPEC_ONLY, or SHALLOW. For each item, determine whether it is:

1. **Implementation gap** (SPEC_ONLY) — the spec requirement is not
   implemented at all. Add the missing implementation and tests.
2. **Vocabulary gap** (DRIFTED) — the implementation exists but spec
   vocabulary is missing from public doc comments. Add spec terms to
   public declarations.
3. **Depth gap** (SHALLOW) — the requirement matched to type definitions
   only, with no function implementations in the same file. Add the
   actual processing/parsing/conversion logic that the requirement demands.

Your task:
- Read the alignment report below.
- For each DRIFTED or SPEC_ONLY requirement, search the codebase for
  related keywords from that requirement. If related code exists, it is
  a vocabulary gap — add doc comments. If no related code exists, it is
  an implementation gap — implement it.
- The alignment tool only extracts vocabulary from public declarations.
  Doc comments on private functions are invisible to the tool.
- Run the project's formatter and test suite after editing.
- Commit your changes. Do not leave changes uncommitted.

## Spec Align Diff Report
EOF
cat .indexion/sdd-reports/align-diff.md >> .indexion/sdd-reports/vocab-fix-prompt.md
echo -e "\n## Vocabulary Gap Report" >> .indexion/sdd-reports/vocab-fix-prompt.md
head -40 .indexion/sdd-reports/verify-gaps.md >> .indexion/sdd-reports/vocab-fix-prompt.md

# 3. Run agent with the prompt file
codex exec --full-auto --json -C . \
  "$(cat .indexion/sdd-reports/vocab-fix-prompt.md)" \
  > .indexion/sdd-reports/vocab-fix.jsonl &

# 4. Monitor (optional)
tail -f .indexion/sdd-reports/vocab-fix.jsonl | jq -r '
  if .type == "item.completed" and .item.type == "agent_message"
  then "MSG: " + (.item.text[:120])
  elif .type == "item.completed" and .item.type == "command_execution"
  then "CMD: " + (.item.command[:50]) + " -> " + (.item.exit_code|tostring)
  else empty end'

# 5. Re-check alignment after agent completes
indexion spec align status .kiro/specs/<feature>/requirements.md src/ \
  --threshold 0.3 --fail-on any

主要约束：

• 提示词不会规定要添加哪些具体词汇，而是提供对齐报告，让 Agent 判断需要修复的内容。
• Agent 必须仅针对公共声明进行处理——私有函数的文档注释对 spec align 不可见。
• 通常需要 1-2 轮修复。如果 SPEC_ONLY 仍然存在，可能需要指导 Agent：相关公共 API 入口应包含相应词汇（例如，顶层 open 函数应描述完整流程）。

已知盲点：

• 没有公共 API 的 CLI 入口点： 主模块/入口点模块通常没有公共声明——所有函数对模块而言都是私有的。spec align 只从公共声明中提取词汇，因此入口点模块始终会显示 Matched: 0 / SPEC_ONLY，涵盖所有要求。解决方法： 将 CLI 逻辑拆分到公开函数的库模块中，并让入口点充当精简的分发器。针对库模块而非入口点对齐要求。

• 空文档注释： Codex 经常只写文档注释的语法形式，却不添加任何实际文本。这些注释对 spec align 不可见，因为其中不包含任何词汇。词汇修复提示词必须明确指示 Agent：“不要留下空的文档注释。每个公共声明都必须有描述其用途的文档注释，并使用要求中的术语。”

• 仅包含内部实现的模块（私有函数）： 如果实现逻辑完全是私有的（非公共），spec align 就无法识别。这在筛选器/编解码器包中很常见：公共管线函数会分发到私有解码器。尽管存在实现逻辑，SHALLOW 仍会在类型文件上触发。解决方法： 将关键内部函数提升为公共函数（使其成为可测试的 API），或者将规范词汇集中到公共管线函数的文档注释中，让要求与该注释匹配。

• 字面要求与标识符匹配： 如果要求中引用了项目专属字面值（包名、表编号、配置键），而实现文档注释中没有提及完全相同的字面值，就会显示为 DRIFTED。这通常说明要求中包含不应出现的项目专属细节——应修改要求，改用通用描述，或者接受词汇修复 Agent 必须传播这些字面值。

• 将实现描述为“回退方案”，但规范实际要求实现： 当 Agent 为不受支持的功能提出“回退方案”时，应确认该功能是否确实是源规范的要求。例如，TrueType 字体 cmap 表解析被提出为“回退方案”，但实际上是规范对 TrueType 字体编码解析的强制要求。将规范要求描述为回退方案会导致优先级错误，并可能造成实现不完整。

• 词汇匹配 ≠ 功能正确性： DRIFTED=0 和 SHALLOW=0 可以确认词汇已对齐，但无法验证实现是否实际可用。E2E 测试（从真实文件中提取文本、比较视觉渲染结果）对于发现以下问题至关重要：

  • 可以编译但从未执行的类型定义
  • 处理真实输入时会报错的管线
  • 产生错误输出的坐标变换
  • 会静默返回空结果的字体/编码处理路径

步骤 4：检测文档漂移（plan reconcile）

实现完成后，使用 plan reconcile 检测实现代码与文档（README、文档注释等）之间的漂移：

# Detect impl ↔ documentation drift
indexion plan reconcile --format md src/lib/

# Restrict to specific docs
indexion plan reconcile --format md --doc 'README.md' src/lib/

在 SDD 工作流中，plan reconcile 与 spec align 相辅相成：

• spec align：requirements.md ↔ 实现代码（规格符合性）
• plan reconcile：实现代码 ↔ 文档（文档时效性）

使用 spec align 作为合并前的门禁（CI）。功能发布后，使用 plan reconcile 持续维护文档。

步骤 5：视觉 E2E 验证（像素差异）

对于会产生视觉输出的项目（PDF 渲染、SVG 导出、图像处理），基于词汇的 spec align 并不足够。应添加与参考渲染结果的像素级比较。

流水线：

1. 使用库生成输出（例如，pdf svg input.pdf output.svg）
2. 以固定 DPI 栅格化为 PNG（rsvg-convert、puppeteer 等）
3. 使用成熟工具生成参考 PNG（pdftoppm 等）
4. 使用 pixelmatch 进行比较——报告差异百分比

阈值：

• < 0.01%：像素级完美（仅有字体 AA 差异）
• < 0.1%：字形位置的轻微差异
• < 1%：明显的文本漂移或图像位置问题

• 1%：结构性渲染失败

**迭代改进：**要达到视觉精度，需要多轮迭代。每轮修复一个类别（字体映射 → 字形位置 → 图像 CTM → 颜色转换）。每轮都跟踪所有 PDF，以发现回归问题——修复一个 PDF 时不得破坏另一个。

视觉差异比较的已知局限：

• 不同栅格化工具的字体抗锯齿有所差异（rsvg-convert 与 pdftoppm）
• 子像素渲染取决于平台
• 对于跨栅格化工具比较，0.01% 可能是实际可达到的下限

独立命令

spec draft — RFC/文档 → SDD 需求草案

indexion spec draft <source-file-or-dir>
indexion spec draft --output requirements.md --format markdown rfc.md
indexion spec draft --profile sdd-requirement rfc.md

选项	默认值	说明
--output, -o	stdout	输出文件路径
--format	markdown	输出格式：markdown、json
--profile	sdd-requirement	草案配置文件（KGF 规格名称）
--max-requirements	64	提取需求的最大数量
--specs-dir	auto	KGF 规格目录

spec verify — 词汇缺口检查

indexion spec verify --spec='requirements.md' src/lib/ --format md

选项	默认值	说明
--spec	（必填）	规格文档 glob（可重复指定）
--format	json	输出格式：json、md、github-issue
--focus	all	Token 类型筛选器：ident、text、vocab、all
--max-candidates	200	输出中的最大项目数
-o, --output	stdout	输出文件路径

spec align diff — 需求级漂移

indexion spec align diff requirements.md src/lib/ --format markdown --threshold 0.3

报告：MATCHED、DRIFTED、SPEC_ONLY（规格中有但实现中无匹配项）、IMPL_ONLY（实现中有但规格中无匹配项）、SHALLOW（仅匹配到类型定义存根，没有函数实现）。

spec align trace — 可追溯性矩阵

indexion spec align trace requirements.md src/lib/ --format json --threshold 0.3

生成需求 → 实现映射，供审计使用。

spec align status — CI 门禁

indexion spec align status requirements.md src/lib/ --fail-on any --threshold 0.3
# Exit code non-zero on failure when used with --fail-on

--fail-on	说明
none	始终通过
drifted	存在任何 DRIFTED 时失败
spec-only	存在任何 SPEC_ONLY 时失败
shallow	存在任何 SHALLOW 时失败（仅有类型定义存根，没有函数实现）
any	存在 DRIFTED、SPEC_ONLY、SHALLOW 或 CONFLICT 时失败

spec align watch — 监视模式

indexion spec align watch --mode=diff requirements.md src/lib/
indexion spec align watch --mode=status requirements.md src/lib/

当规格或实现输入发生变化时，重新运行对齐检查。

spec align suggest — 对账建议

indexion spec align suggest requirements.md src/lib/ --format tasks --agent codex

生成可执行的建议，以弥合规格↔实现之间的差距。

阈值

SDD 对齐命令请使用 --threshold 0.3。默认值 0.6 过高，因为 SDD 验收标准是简短文本，要与代码和文档注释匹配，而不是进行整篇文档相似度比较。

多语言支持

SDD 流水线适用于任何具有 KGF 规格的语言。

SDD 的 KGF 要求

要让规范对齐功能正常工作，语言的 KGF 必须：

1. 在 declares 边中捕获文档注释 — doc 必须非空
2. 使用正确的 PEG 备选项顺序 — 在 Item 备选项中，DocComment 必须位于 声明规则之后
3. 处理文档注释与关键字之间的 NL — 在 doc:DocComment? 后使用 NL? 或 NL*

使用 indexion kgf edges <file> 验证 — 如果 declares 边缺少 doc=，则需要修复 KGF。