blueprint-sync-ids

すべての PRD、ADR、PRP、work-order をスキャンし、ID がないドキュメントに ID を割り当てて、マニフェストレジストリを更新します。

フラグ

フラグ	説明
--dry-run	ファイルを変更せずに変更内容をプレビューします
--link-issues	孤立したドキュメントに対して GitHub issue も作成します

前提条件

• Blueprint が初期化済みであること（docs/blueprint/manifest.json が存在する）
• docs/prds/、docs/adrs/、docs/prps/、または docs/blueprint/work-orders/ にドキュメントが 1 つ以上存在する

手順

ステップ 1: ID レジストリを初期化する

マニフェストに id_registry が存在するか確認します。

jq -e '.id_registry' docs/blueprint/manifest.json >/dev/null 2>&1

存在しない場合は初期化します。

{
  "id_registry": {
    "last_prd": 0,
    "last_prp": 0,
    "documents": {},
    "github_issues": {}
  }
}

ステップ 2: PRD をスキャンする

for prd in docs/prds/*.md; do
  [ -f "$prd" ] || continue

  # Check for existing ID in frontmatter
  existing_id=$(head -50 "$prd" | grep -m1 "^id:" | sed 's/^id:[[:space:]]*//')

  if [ -z "$existing_id" ]; then
    echo "NEEDS_ID: $prd"
  else
    echo "HAS_ID: $prd ($existing_id)"
  fi
done

ステップ 3: ADR をスキャンする

for adr in docs/adrs/*.md; do
  [ -f "$adr" ] || continue

  # ADR ID derived from filename (0001-title.md → ADR-0001)
  filename=$(basename "$adr")
  num=$(echo "$filename" | grep -oE '^[0-9]{4}')

  if [ -n "$num" ]; then
    expected_id="ADR-$num"
    existing_id=$(head -50 "$adr" | grep -m1 "^id:" | sed 's/^id:[[:space:]]*//')

    if [ -z "$existing_id" ]; then
      echo "NEEDS_ID: $adr (should be $expected_id)"
    elif [ "$existing_id" != "$expected_id" ]; then
      echo "MISMATCH: $adr (has $existing_id, should be $expected_id)"
    else
      echo "HAS_ID: $adr ($existing_id)"
    fi
  fi
done

ステップ 4: PRP をスキャンする

for prp in docs/prps/*.md; do
  [ -f "$prp" ] || continue

  existing_id=$(head -50 "$prp" | grep -m1 "^id:" | sed 's/^id:[[:space:]]*//')

  if [ -z "$existing_id" ]; then
    echo "NEEDS_ID: $prp"
  else
    echo "HAS_ID: $prp ($existing_id)"
  fi
done

ステップ 5: Work-Order をスキャンする

for wo in docs/blueprint/work-orders/*.md; do
  [ -f "$wo" ] || continue

  # WO ID derived from filename (003-task.md → WO-003)
  filename=$(basename "$wo")
  num=$(echo "$filename" | grep -oE '^[0-9]{3}')

  if [ -n "$num" ]; then
    expected_id="WO-$num"
    existing_id=$(head -50 "$wo" | grep -m1 "^id:" | sed 's/^id:[[:space:]]*//')

    if [ -z "$existing_id" ]; then
      echo "NEEDS_ID: $wo (should be $expected_id)"
    else
      echo "HAS_ID: $wo ($existing_id)"
    fi
  fi
done

ステップ 6: 検出結果を報告する

Document ID Scan Results

PRDs:
- With IDs: X
- Missing IDs: Y
  - docs/prds/feature-a.md
  - docs/prds/feature-b.md

ADRs:
- With IDs: X
- Missing IDs: Y
- Mismatched IDs: Z

PRPs:
- With IDs: X
- Missing IDs: Y

Work-Orders:
- With IDs: X
- Missing IDs: Y

Total: X documents, Y need IDs

ステップ 7: ID を割り当てる（--dry-run の場合を除く）

ID が必要な各ドキュメントに対して、次の処理を行います。

PRD:

1. 次の PRD 番号を取得します：jq '.id_registry.last_prd' manifest.json + 1
2. ID を生成します：PRD-NNN（ゼロ埋め）
3. 先頭の --- の後にフロントマターへ挿入します。

   id: PRD-001
   

4. マニフェストを更新します：last_prd をインクリメントし、documents に追加します

ADR:

1. ファイル名から ID を導出します：0003-title.md → ADR-0003
2. フロントマターに挿入します
3. マニフェストの documents に追加します

PRP:

1. 次の PRP 番号を取得します：jq '.id_registry.last_prp' manifest.json + 1
2. ID を生成します：PRP-NNN
3. フロントマターに挿入します
4. マニフェストを更新します：last_prp をインクリメントし、documents に追加します

Work-Order:

1. ファイル名から ID を導出します：003-task.md → WO-003
2. フロントマターに挿入します
3. マニフェストの documents に追加します

ステップ 8: タイトルとリンクを抽出する

各ドキュメントについて、次の情報も抽出します。

• タイトル：最初の # 見出し、またはフロントマターの name／title フィールド
• 既存のリンク：フロントマターの relates-to、implements、github-issues
• ステータス：フロントマターから取得します

マニフェストレジストリに保存します。

{
  "documents": {
    "PRD-001": {
      "path": "docs/prds/user-auth.md",
      "title": "User Authentication",
      "status": "Active",
      "relates_to": ["ADR-0003"],
      "github_issues": [42],
      "created": "2026-01-15"
    }
  }
}

ステップ 9: GitHub issue インデックスを作成する

すべてのドキュメントをスキャンして github-issues フィールドを探し、逆引きインデックスを作成します。

{
  "github_issues": {
    "42": ["PRD-001", "PRP-002"],
    "45": ["WO-003"]
  }
}

ステップ 10: 孤立したドキュメントの issue を作成する（--link-issues の場合）

github-issues がないドキュメントごとに、次の処理を行います。

question: "Create GitHub issue for {ID}: {title}?"
options:
  - label: "Yes, create issue"
    description: "Creates [{ID}] {title} issue"
  - label: "Skip this one"
    description: "Leave unlinked for now"
  - label: "Skip all remaining"
    description: "Don't prompt for more orphans"

該当する場合：

gh issue create \
  --title "[{ID}] {title}" \
  --body "## {Document Type}

**ID**: {ID}
**Document**: \`{path}\`

{Brief description from document}

---
*Auto-generated by /blueprint:sync-ids*" \
  --label "{type-label}"

ドキュメントのフロントマターとマニフェストを、新しい issue 番号で更新します。

ステップ 11: タスクレジストリを更新する

docs/blueprint/manifest.json のタスクレジストリエントリを更新します。

jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --argjson processed "${DOCS_CHECKED:-0}" \
  --argjson created "${IDS_ASSIGNED:-0}" \
  '.task_registry["sync-ids"].last_completed_at = $now |
   .task_registry["sync-ids"].last_result = "success" |
   .task_registry["sync-ids"].stats.runs_total = ((.task_registry["sync-ids"].stats.runs_total // 0) + 1) |
   .task_registry["sync-ids"].stats.items_processed = $processed |
   .task_registry["sync-ids"].stats.items_created = $created' \
  docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

ステップ 12: 最終レポート

ID Sync Complete

Assigned IDs:
- PRD-003: docs/prds/payment-flow.md
- PRD-004: docs/prds/notifications.md
- PRP-005: docs/prps/stripe-integration.md

Updated Manifest:
- last_prd: 4
- last_prp: 5
- documents: 22 entries
- github_issues: 18 mappings

{If --link-issues:}
Created GitHub Issues:
- #52: [PRD-003] Payment Flow
- #53: [PRP-005] Stripe Integration

Still orphaned (no GitHub issues):
- ADR-0004: Database Migration Strategy
- WO-008: Add error handling

Run `/blueprint:status` to see full traceability report.

エラー処理

条件	対応
マニフェストがない	エラー：最初に /blueprint:init を実行してください
ドキュメントが見つからない	警告：スキャンするドキュメントがありません
フロントマターの解析エラー	警告：ファイルをスキップし、手動修正が必要なファイルとして報告します
gh が利用できない	issue の作成をスキップし、ユーザーに警告します
書き込み権限がない	エラー：ファイルのアクセス権を確認してください

マニフェストスキーマ

同期後、マニフェストには次の内容が含まれます。

{
  "id_registry": {
    "last_prd": 4,
    "last_prp": 5,
    "documents": {
      "PRD-001": {
        "path": "docs/prds/user-auth.md",
        "title": "User Authentication",
        "status": "Active",
        "relates_to": ["ADR-0003"],
        "implements": [],
        "github_issues": [42],
        "created": "2026-01-10"
      },
      "ADR-0003": {
        "path": "docs/adrs/0003-session-storage.md",
        "title": "Session Storage Strategy",
        "status": "Accepted",
        "domain": "authentication",
        "relates_to": ["PRD-001"],
        "github_issues": [],
        "created": "2026-01-12"
      }
    },
    "github_issues": {
      "42": ["PRD-001", "PRP-002"],
      "45": ["WO-003"]
    }
  }
}