update-graft-inventory

Graft インベントリの更新スキル

有効にするタイミング

次の場合にこのスキルを有効にします。

• SQL マイグレーションで新しい機能フラグを追加するとき
• graft を削除または非推奨にするとき
• graft-inventory CI チェックが失敗したとき
• インベントリが本番環境の D1 と一致することを確認するとき
• graft を追加するマイグレーションの適用後

関連ファイル

ファイル	目的
.github/graft-inventory.json	graft の数とメタデータの信頼できる情報源
libs/engine/migrations/*.sql	graft を定義するマイグレーションファイル
libs/engine/src/lib/platform/feature-flags/flags.ts	型定義（KnownFlagId）
docs/guides/adding-grafts-and-flags.md	開発者ガイド（graft は Grove における機能フラグの呼称です）

インベントリの構造

インベントリには、完全なメタデータとともに graft が記録されています。

{
	"grafts": {
		"total": 10,
		"breakdown": {
			"platform": 8,
			"greenhouse": 2
		},
		"byType": {
			"boolean": 9,
			"number": 1
		}
	},
	"flags": [
		{
			"id": "fireside_mode",
			"name": "Fireside Mode",
			"type": "boolean",
			"greenhouseOnly": true,
			"migration": "040_fireside_scribe_grafts.sql",
			"description": "AI-assisted writing prompts"
		}
	]
}

手順

1. マイグレーションから graft を一覧表示する

# Extract all flag IDs from migration INSERT statements
grep -hoP "INSERT OR IGNORE INTO feature_flags.*?VALUES\s*\(\s*'\K[a-z_]+" libs/engine/migrations/*.sql | sort -u

2. 本番環境の D1 にクエリする

# Get actual flags from production database
npx wrangler d1 execute grove-engine-db --remote --command="SELECT id, name, flag_type, greenhouse_only, enabled FROM feature_flags ORDER BY id;"

3. インベントリと比較する

# Read current inventory
cat .github/graft-inventory.json | jq '.flags[].id' | sort

4. 不一致を特定する

次の点を確認します。

• 新しい graft：マイグレーション／D1 にはあるが、インベントリにはない
• 削除された graft：インベントリにはあるが、D1 にはない
• 変更されたメタデータ：type、greenhouse_only、または description が変更されている

5. インベントリ JSON を更新する

.github/graft-inventory.json を編集します。

1. 件数を更新する：

   "grafts": {
     "total": <new count>,
     "breakdown": {
       "platform": <non-greenhouse count>,
       "greenhouse": <greenhouse_only count>
     }
   }
   

2. フラグのエントリーを追加／削除する：

   "flags": [
     {
       "id": "new_flag_id",
       "name": "Human Readable Name",
       "type": "boolean",
       "greenhouseOnly": false,
       "migration": "XXX_migration_name.sql",
       "description": "What this flag controls"
     }
   ]
   

3. メタデータを更新する：

   "lastUpdated": "YYYY-MM-DD",
   "lastAuditedBy": "claude/<context>"
   

6. KnownFlagId 型を更新する

libs/engine/src/lib/platform/feature-flags/flags.ts を編集します。

export type KnownFlagId =
	| "fireside_mode"
	| "scribe_mode"
	| "meadow_access"
	| "jxl_encoding"
	| "jxl_kill_switch"
	| "new_flag_id"; // Add new flag

7. 変更をコミットする

git add .github/graft-inventory.json libs/engine/src/lib/platform/feature-flags/flags.ts
git commit -m "docs: update graft inventory

- Add <flag_id> to inventory
- Update total: X -> Y
- Update KnownFlagId type"

コマンド早見表

# Count grafts in migrations
grep -c "INSERT OR IGNORE INTO feature_flags" libs/engine/migrations/*.sql | awk -F: '{sum+=$2} END {print sum}'

# List all flag IDs
grep -hoP "INSERT OR IGNORE INTO feature_flags.*?VALUES\s*\(\s*'\K[a-z_]+" libs/engine/migrations/*.sql | sort -u

# Count greenhouse-only grafts
npx wrangler d1 execute grove-engine-db --remote --command="SELECT COUNT(*) FROM feature_flags WHERE greenhouse_only = 1;"

# Full flag details from production
npx wrangler d1 execute grove-engine-db --remote --command="SELECT * FROM feature_flags ORDER BY id;"

# Check which migrations haven't been applied
# Compare migration file flag IDs vs production D1 flag IDs

新しい graft の追加（完全なチェックリスト）

新しい graft を追加するときは、次の手順に従います。

• マイグレーションファイルを作成する：libs/engine/migrations/XXX_name.sql
• マイグレーションを適用する：npx wrangler d1 execute grove-engine-db --remote --file=...
• flags.ts の KnownFlagId 型に追加する
• .github/graft-inventory.json の flags 配列にエントリーを追加する
• インベントリの件数（total、breakdown.platform/greenhouse、byType）を更新する
• lastUpdated と lastAuditedBy を更新する
• すべての変更をまとめてコミットする

本番環境との同期を確認する

更新後、本番環境と一致していることを確認します。

# Expected count
jq '.grafts.total' .github/graft-inventory.json

# Actual count in production
npx wrangler d1 execute grove-engine-db --remote --command="SELECT COUNT(*) as count FROM feature_flags;"

一致しない場合は、マイグレーションの適用が必要な可能性があります。

# Apply a specific migration
npx wrangler d1 execute grove-engine-db --remote --file=libs/engine/migrations/XXX_name.sql

CI との連携

.github/workflows/graft-inventory.yml ワークフローは、次の処理を行います。

• libs/engine/migrations/*.sql に変更がある PR で実行されます
• libs/engine/src/lib/feature-flags/** に変更がある PR で実行されます
• マイグレーション内の INSERT 文を解析します
• 件数をインベントリと比較します
• 不一致がある場合、PR にコメントします
• 定期実行時（水曜日）に、差異に関する Issue を作成します

CI が失敗した場合は、このスキルを実行して不一致を修正してください。

チェックリスト

完了する前に、次の項目を確認します。

• 本番環境の D1 の graft 件数が、インベントリの total と一致している
• D1 のすべてのフラグに、インベントリの flags 配列内のエントリーがある
• KnownFlagId 型にすべてのフラグ ID が含まれている
• lastUpdated の日付が今日になっている
• 件数が合計と一致している：total = platform + greenhouse
• 型の内訳が正確である
• 内容がわかるメッセージを付けて変更がコミットされている