update-graft-inventory

Update Graft Inventory Skill

When to Activate

Activate this skill when:

• Adding new feature flags via SQL migrations
• Removing or deprecating grafts
• The graft-inventory CI check fails
• You want to verify inventory matches production D1
• After applying migrations that add grafts

Files Involved

File	Purpose
.github/graft-inventory.json	Source of truth for graft counts and metadata
libs/engine/migrations/*.sql	Migration files that define grafts
libs/engine/src/lib/platform/feature-flags/flags.ts	Type definitions (KnownFlagId)
docs/guides/adding-grafts-and-flags.md	Developer guide (grafts = Grove term for feature flags)

Inventory Structure

The inventory tracks grafts with full metadata:

{
	"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"
		}
	]
}

Step-by-Step Process

1. List Grafts from Migrations

# 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. Query Production 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. Compare with Inventory

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

4. Identify Discrepancies

Look for:

• New grafts: In migrations/D1 but not in inventory
• Removed grafts: In inventory but not in D1
• Changed metadata: Type, greenhouse_only, or description changed

5. Update Inventory JSON

Edit .github/graft-inventory.json:

1. Update counts:

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

2. Add/remove flag entries:

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

3. Update metadata:

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

6. Update KnownFlagId Type

Edit 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. Commit Changes

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"

Quick Reference Commands

# 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

Adding a New Graft (Full Checklist)

When adding a new graft:

• Create migration file: libs/engine/migrations/XXX_name.sql
• Apply migration: npx wrangler d1 execute grove-engine-db --remote --file=...
• Add to KnownFlagId type in flags.ts
• Add entry to .github/graft-inventory.json flags array
• Update inventory counts (total, breakdown.platform/greenhouse, byType)
• Update lastUpdated and lastAuditedBy
• Commit all changes together

Verifying Production Sync

After updating, verify production matches:

# 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;"

If they don't match, migrations may need to be applied:

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

CI Integration

The .github/workflows/graft-inventory.yml workflow:

• Runs on PRs touching libs/engine/migrations/*.sql
• Runs on PRs touching libs/engine/src/lib/feature-flags/**
• Parses migrations for INSERT statements
• Compares count to inventory
• Comments on PRs when there's a mismatch
• Creates issues for drift on scheduled runs (Wednesdays)

When CI fails, run this skill to fix the mismatch.

Checklist

Before finishing:

• Production D1 graft count matches inventory total
• All flags in D1 have entries in inventory flags array
• KnownFlagId type includes all flag IDs
• lastUpdated date is today
• Counts add up: total = platform + greenhouse
• Type breakdown is accurate
• Changes committed with descriptive message