update-graft-inventory

name	update-graft-inventory
description	Update the graft (feature flag) inventory when flags are added or removed. Use when adding new grafts via migrations, after CI flags inventory mismatches, or periodically to ensure docs match production D1.

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