indexion-sdd

indexion SDD（仕様駆動開発）

indexion の定量的な仕様アラインメントツールを SDD エージェントのワークフロー（cc-sdd、codex など）に連携します。

RFC／ドキュメントから SDD のドラフトを作成し、仕様と実装の乖離を検出して、indexion の定量的な結果をエージェント主導の定性的なレビューに反映する検証ループを提供します。

使用する場面

• 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 に依存します。

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 形式に一致します。エージェントの $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

元の仕様と設計またはコードを直接アラインしないでください。語彙の範囲が大きく異なるためです（規範的な仕様の言葉遣い、ソフトウェア設計、コード識別子）。各段階で抽象度の差を 1 つずつ橋渡しします。

意味上の忠実性レビュー（自動化できません）：

spec align は語彙の重なりを確認しますが、同じ語彙を使いながら元の仕様の意図を逆転させている要件は検出できません。よくある失敗例：

• 元の仕様：「DCTDecode フィルターは JPEG データをサンプルにデコードしなければならない」
• 要件のドラフト：「DCTDecode について、デコーダーはフィルターがまだサポートされていないことを示すエラーを返さなければならない」

どちらにも「DCTDecode」、「filter」、「shall」が含まれているため、語彙は一致し、spec align は MATCHED と報告します。しかし、この要件は仕様が求めることと反対の内容です。これにより、E2E テストが失敗するまで表面化しない隠れたギャップが生じます（ステップ 2.9）。

spec draft が要件を生成した後、次のパターンがないか確認してください：

• "not yet supported"、"not implemented"、"placeholder"、"stub" — ドラフトが仕様の要件への対応を先送りしたことを示します
• 元の仕様で "shall decode/process/convert" とされているものに対する "shall return an error" — 意図の逆転です
• 複数の仕様機能を、単一の「未サポート」グループにまとめた要件 — 仕様の機能ごとに個別の要件を設けてください

ステップ 2 に進む前に、これらを修正してください。そのままにしておくと、E2E テストでしか発覚しない、仕様に適合しているという誤った安心感につながります。

ステップ 2：エージェントの SDD フェーズ（codex / claude）

cc-sdd v3+ は skills モード（$kiro-spec-* コマンド）を使用します。

フェーズ間に 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 行以下）：

• 構造体リテラルを返すだけのデフォルトコンストラクター
• 1 行だけのブール値アクセサー

タスクごとの Drift ゲート（shallow 検出あり）

各タスクを完了してコミットした後、次を実行します。

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 は Shallow: 0 の状態で終了コード 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 内で $() を使うと、標準入力がブロックされることがあります。
• 長時間の実装実行中は、/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 に分類します。これにより、次の 2 つのパターンを検出します。

1. Codex が用語の一致を満たすために型定義を記述し、要件が求める実際の処理ロジックを省略する。
2. Codex が型定義とは別のファイルにロジックを追加する。SHALLOW はファイルごとにチェックされるため、一方のファイルに型があり、別のファイルにしかメソッドがない場合も、型があるファイルで SHALLOW が発生します。

解決方法： 型が定義されているファイルにメソッドを追加します。単純な関数（コンストラクターや 1 行のアクセサーなど、4 行以下のもの）はカウントされません。例については、フェーズ B のプロンプトテンプレートを参照してください。

このゲートを Codex プロンプトに含める場合は、各タスクのコミット後にこれらのコマンドを実行し、次へ進む前にフラグが付いた項目を修正するよう、エージェントに指示してください。プロンプト用の指示ブロックの例：

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 セッション 1 回で、すべての 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 の場合は、E2E 検証（ステップ 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 エージェントが行う必要があります。手動でコミットすると、SDD プロトコル（RED→GREEN の根拠、レビュー、検証）を迂回し、ワークフローが無効になります。

ステップ 2.8：Drift Gate プロキシ（Codex が indexion を実行できない場合）

Codex は impl プロジェクトディレクトリ内で indexion コマンドを実行します。 indexion がインストールされていない、バージョンが古すぎる、または必要な KGF 仕様がない場合、 drift gate コマンドは Codex 内で失敗するか、タイムアウトします。

予防策（推奨）： SDD の実行を開始する前に、ステップ 0 でプロジェクトディレクトリ内の indexion が正常に動作することを確認します。

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

indexion が利用できない、または動作しない場合は、まずインストールまたは更新してください。

フォールバック — オーケストレーター側の drift gate：

実行前に indexion を修正できない場合（例：必要な KGF 仕様がまだリリースされていない場合）、 オーケストレーターが外部で drift gate を実行します。

1. impl プロンプトで drift gate コマンドをスキップするよう Codex に指示します。

   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 が「No alignment data found」を返すことがあります。

ステップ 2.9：E2E 検証（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 gate によって、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 + エージェント）

ここで indexion は、エージェントによるレビューだけの場合を超える価値を発揮します。

# 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. すべてのレポートを、エージェントの validate-impl プロンプトに挿入します。
6. エージェントが、具体的なタスク番号を示した 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 を呼び出しません。このステップでは、2 つのツールを橋渡しします。

# 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

主な制約：

• プロンプトでは、追加する具体的な用語を指定しません。整合性レポートを提示し、何を修正するかはエージェントに判断させます。
• エージェントは公開宣言のみを対象にする必要があります。非公開関数のドキュメントコメントは spec align から参照できません。
• 一般的には、修正サイクルは 1～2 回です。SPEC_ONLY が解消されない場合は、該当する公開 API のエントリーポイントに用語を記載するよう、エージェントに指示する必要があります（たとえば、トップレベルの open 関数で処理全体を説明します）。

既知の盲点：

• 公開 API のない CLI エントリーポイント： メインモジュールやエントリーポイントのモジュールには、公開宣言がなく、すべての関数がモジュール内で非公開になっていることがよくあります。spec align は公開宣言からのみ用語を抽出するため、エントリーポイントのモジュールでは常に、すべての要件について Matched: 0 / SPEC_ONLY と表示されます。回避策： CLI のロジックを公開関数を提供するライブラリモジュールに分割し、エントリーポイントは薄いディスパッチャーにします。エントリーポイントではなく、ライブラリに対して要件を整合させます。

• 空のドキュメントコメント： Codex は、実際のテキストがないドキュメントコメント構文をよく書きます。用語が含まれていないため、これらは spec align から参照できません。用語修正プロンプトでは、エージェントに次のように明示する必要があります。「ドキュメントコメントを空のままにしないでください。すべての公開宣言に、要件で使われている用語を用いて目的を説明するドキュメントコメントを付けてください。」

• 内部専用モジュール（非公開関数）： 実装ロジックがすべて非公開の場合、spec align から参照できません。これは、公開パイプライン関数が非公開デコーダーを呼び出すフィルター／コーデックパッケージでよく見られます。ロジックが存在していても、型定義ファイルで SHALLOW が発生します。回避策： 主要な内部関数を公開してテスト可能な API とするか、仕様の用語を公開パイプライン関数のドキュメントコメントにまとめ、そこで要件と一致させます。

• 要件のリテラル値と識別子の照合： パッケージ名、テーブル番号、設定キーなど、プロジェクト固有のリテラル値に言及する要件は、実装のドキュメントコメントに正確なリテラル値が記載されていないと DRIFTED と表示されます。通常これは、要件に含めるべきではないプロジェクト固有の詳細が含まれていることを示しています。要件を一般的な説明に修正するか、用語修正エージェントにこれらのリテラル値を反映させます。

• 「フォールバック」という位置づけと仕様で必須の実装： エージェントが未対応機能の「フォールバック」を提案した場合、その機能が元の仕様で実際に必須とされているか確認してください。たとえば、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/

plan reconcile は、SDD ワークフローにおいて spec align を補完します。

• spec align：requirements.md ↔ 実装コード（仕様への準拠）
• plan reconcile：実装コード ↔ ドキュメント（ドキュメントの最新性）

マージ前のゲート（CI）には spec align を使います。機能のリリース後に継続してドキュメントを保守するには、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% 超：レンダリングの構造的な失敗

反復的な改善： 視覚的な精度を高めるには、複数回の反復が必要です。各回で 1 つのカテゴリを修正します（フォントマッピング → グリフの位置調整 → 画像 CTM → 色変換）。回帰を検出できるよう、各回ですべての PDF を追跡します。ある 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	トークン種別のフィルター：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 が 1 つでもあれば失敗
spec-only	SPEC_ONLY が 1 つでもあれば失敗
shallow	SHALLOW（関数の実装がない型のみのスタブ）が 1 つでもあれば失敗
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 の選択肢を正しい順序で記述する — DocComment は Item の選択肢で宣言ルールの後に配置すること
3. ドキュメントコメントとキーワードの間の NL を処理する — doc:DocComment? の後に NL? または NL* を指定すること

次のコマンドで確認します：indexion kgf edges <file> — declares エッジに doc= がない場合は、KGF を修正する必要があります。