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: ```json { "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 ```bash # 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 ```bash # 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 ```bash # 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**: ```json "grafts": { "total": <new count>, "breakdown": { "platform": <non-greenhouse count>, "greenhouse": <greenhouse_only count> } } ``` 2. **Add/remove flag entries**: ```json "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**: ```json "lastUpdated": "YYYY-MM-DD", "lastAuditedBy": "claude/<context>" ``` ### 6. Update KnownFlagId Type Edit `libs/engine/src/lib/platform/feature-flags/flags.ts`: ```typescript export type KnownFlagId = | "fireside_mode" | "scribe_mode" | "meadow_access" | "jxl_encoding" | "jxl_kill_switch" | "new_flag_id"; // Add new flag ``` ### 7. Commit Changes ```bash 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 ```bash # 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: ```bash # 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: ```bash # 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