the-grid-cc 1.7.14 → 1.7.15

package/docs/CONFIG_SCHEMA.md

@@ -0,0 +1,479 @@
+# Grid Configuration Schema
+
+Complete reference for `.grid/config.json` - the master configuration file for all Grid settings.
+
+---
+
+## MASTER CONFIG STRUCTURE
+
+```json
+{
+  "version": "1.7.x",
+  "initialized": "2026-01-23T10:00:00Z",
+
+  "model_tier": "quality",
+
+  "git": {
+    "auto_branch": true,
+    "branch_prefix": "grid/",
+    "auto_push": "wave",
+    "auto_pr": true,
+    "protected_branches": ["main", "master", "production"],
+    "default_base": "main",
+    "sync_strategy": "merge",
+    "commit_signing": false,
+    "wip_commits": true
+  },
+
+  "budget": {
+    "enabled": true,
+    "budget_limit": null,
+    "currency": "USD",
+    "enforcement": "hard",
+    "warning_threshold": 0.75,
+    "confirmation_threshold": 0.90
+  },
+
+  "daemon": {
+    "default_mode": "autopilot",
+    "max_runtime_hours": 24,
+    "checkpoint_on_wave_complete": true,
+    "heartbeat_interval_seconds": 30,
+    "stall_threshold_minutes": 30,
+
+    "notifications": {
+      "system": true,
+      "sound": true,
+      "webhook": null
+    },
+
+    "notify_on": {
+      "start": false,
+      "checkpoint": true,
+      "complete": true,
+      "error": true,
+      "stall": true
+    },
+
+    "cleanup": {
+      "auto_clean_completed_days": 7,
+      "keep_audit_logs": true
+    }
+  },
+
+  "verification": {
+    "auto_verify": true,
+    "wave_level": true,
+    "skip_for_types": []
+  },
+
+  "refinement": {
+    "auto_refine": true,
+    "skip_backend_only": true,
+    "persona_count": 3,
+    "parallel_execution": true
+  },
+
+  "research": {
+    "auto_research": true,
+    "cache_duration_hours": 24,
+    "parallel_searches": true,
+    "max_sources_per_query": 10
+  },
+
+  "scout": {
+    "auto_scout": true,
+    "timeout_seconds": 120,
+    "max_file_scan": 100,
+    "max_depth": 4
+  },
+
+  "scratchpad": {
+    "mandatory": true,
+    "archive_on_wave_complete": true,
+    "max_entries_before_archive": 100
+  },
+
+  "learnings": {
+    "auto_capture": true,
+    "load_on_startup": true
+  },
+
+  "debug": {
+    "persist_sessions": true,
+    "max_session_age_days": 30
+  },
+
+  "ui": {
+    "progress_updates": "live",
+    "emoji": false,
+    "color": true,
+    "verbose": false
+  }
+}
+```
+
+---
+
+## FIELD REFERENCE
+
+### Top Level
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `version` | string | "1.7.x" | Grid version |
+| `initialized` | ISO timestamp | (auto) | When config was created |
+| `model_tier` | enum | "quality" | Default model tier: quality/balanced/budget |
+
+---
+
+### Git Section
+
+Controls git operations and branch management.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `auto_branch` | boolean | true | Auto-create feature branches |
+| `branch_prefix` | string | "grid/" | Prefix for Grid branches |
+| `auto_push` | enum | "wave" | Push timing: wave/block/manual/immediate |
+| `auto_pr` | boolean | true | Offer PR creation on completion |
+| `protected_branches` | array | ["main",...] | Branches that require PRs |
+| `default_base` | string | "main" | Default base branch for PRs |
+| `sync_strategy` | enum | "merge" | How to sync: merge/rebase |
+| `commit_signing` | boolean | false | GPG sign commits |
+| `wip_commits` | boolean | true | Allow WIP commits for long sessions |
+
+**Auto Push Modes:**
+- `wave` - Push after each wave completes (default)
+- `block` - Push after each block completes
+- `manual` - Never auto-push
+- `immediate` - Push after every commit
+
+**Sync Strategy:**
+- `merge` - git merge origin/main
+- `rebase` - git rebase origin/main
+
+---
+
+### Budget Section
+
+Controls cost tracking and spending limits.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | boolean | true | Enable budget tracking |
+| `budget_limit` | number\|null | null | Max spending (null = unlimited) |
+| `currency` | string | "USD" | Currency for display |
+| `enforcement` | enum | "hard" | hard=block, soft=warn only |
+| `warning_threshold` | number | 0.75 | Warn at 75% usage |
+| `confirmation_threshold` | number | 0.90 | Require confirmation at 90% |
+
+**Enforcement Modes:**
+- `hard` - Block spawns when budget exceeded
+- `soft` - Warn but allow spawns
+
+**Thresholds:**
+- 0.0-0.75: Normal operation
+- 0.75-0.90: Display warnings
+- 0.90-1.0: Require confirmation before spawn
+- 1.0+: Block spawns (if hard enforcement)
+
+---
+
+### Daemon Section
+
+Controls background execution mode.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `default_mode` | enum | "autopilot" | Default execution mode |
+| `max_runtime_hours` | number | 24 | Max daemon runtime |
+| `checkpoint_on_wave_complete` | boolean | true | Checkpoint after each wave |
+| `heartbeat_interval_seconds` | number | 30 | Heartbeat frequency |
+| `stall_threshold_minutes` | number | 30 | Alert if no heartbeat |
+
+**Notifications:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `system` | boolean | true | System notifications |
+| `sound` | boolean | true | Play sound alerts |
+| `webhook` | string\|null | null | Webhook URL for notifications |
+
+**Notify On:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `start` | boolean | false | Notify on daemon start |
+| `checkpoint` | boolean | true | Notify on checkpoints |
+| `complete` | boolean | true | Notify on completion |
+| `error` | boolean | true | Notify on errors |
+| `stall` | boolean | true | Notify on stalls |
+
+**Cleanup:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `auto_clean_completed_days` | number | 7 | Delete completed daemons after N days |
+| `keep_audit_logs` | boolean | true | Keep audit logs even after cleanup |
+
+---
+
+### Verification Section
+
+Controls automatic verification behavior.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `auto_verify` | boolean | true | Auto-spawn Recognizer after SUCCESS |
+| `wave_level` | boolean | true | Verify at wave level (vs block level) |
+| `skip_for_types` | array | [] | Block types to skip verification |
+
+**Example skip types:**
+```json
+{
+  "skip_for_types": ["prototype", "throwaway", "spike"]
+}
+```
+
+---
+
+### Refinement Section
+
+Controls refinement swarm behavior.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `auto_refine` | boolean | true | Auto-run refinement after building |
+| `skip_backend_only` | boolean | true | Skip refinement for backend-only changes |
+| `persona_count` | number | 3 | Number of personas to simulate |
+| `parallel_execution` | boolean | true | Run refinement agents in parallel |
+
+---
+
+### Research Section
+
+Controls external research behavior.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `auto_research` | boolean | true | Auto-research unfamiliar tech |
+| `cache_duration_hours` | number | 24 | How long to cache research |
+| `parallel_searches` | boolean | true | Execute searches in parallel |
+| `max_sources_per_query` | number | 10 | Max sources to analyze per query |
+
+---
+
+### Scout Section
+
+Controls codebase reconnaissance behavior.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `auto_scout` | boolean | true | Auto-scout existing codebases |
+| `timeout_seconds` | number | 120 | Max scout duration (2 minutes) |
+| `max_file_scan` | number | 100 | Max files to scan per type |
+| `max_depth` | number | 4 | Max directory depth to scan |
+
+---
+
+### Scratchpad Section
+
+Controls live observability during execution.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `mandatory` | boolean | true | Programs MUST write to scratchpad |
+| `archive_on_wave_complete` | boolean | true | Archive after each wave |
+| `max_entries_before_archive` | number | 100 | Archive threshold |
+
+---
+
+### Learnings Section
+
+Controls institutional memory capture.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `auto_capture` | boolean | true | Capture learnings after completion |
+| `load_on_startup` | boolean | true | Load learnings at session start |
+
+---
+
+### Debug Section
+
+Controls debug session persistence.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `persist_sessions` | boolean | true | Keep debug sessions in .grid/debug/ |
+| `max_session_age_days` | number | 30 | Delete sessions older than N days |
+
+---
+
+### UI Section
+
+Controls output formatting and display.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `progress_updates` | enum | "live" | Update frequency: live/wave/block/silent |
+| `emoji` | boolean | false | Use emoji in output |
+| `color` | boolean | true | Use ANSI colors |
+| `verbose` | boolean | false | Show detailed internal operations |
+
+**Progress Update Modes:**
+- `live` - Show real-time scratchpad updates
+- `wave` - Update after each wave
+- `block` - Update after each block
+- `silent` - No progress updates (status on demand only)
+
+---
+
+## CONFIGURATION COMMANDS
+
+### Initialize Default Config
+
+```bash
+/grid:init
+```
+
+Creates `.grid/config.json` with defaults.
+
+### Update Config
+
+```bash
+/grid:model quality          # Set model tier
+/grid:budget set $50         # Set budget limit
+/grid:branch --auto-push=block  # Change push timing
+```
+
+### View Current Config
+
+```bash
+/grid:status --config
+```
+
+---
+
+## CONFIGURATION OVERRIDES
+
+### Environment Variables
+
+Environment variables override config file:
+
+```bash
+GRID_MODEL_TIER=balanced
+GRID_GIT_AUTO_PUSH=manual
+GRID_BUDGET_LIMIT=100
+GRID_DEBUG_VERBOSE=true
+```
+
+### Per-Session Overrides
+
+Specify at invocation:
+
+```bash
+/grid --no-verify "build feature"
+/grid --budget-check=false "quick fix"
+/grid --model=sonnet "simple task"
+```
+
+---
+
+## MIGRATION
+
+### From Older Versions
+
+If config is missing fields, defaults are used. Run:
+
+```bash
+/grid:init --merge
+```
+
+Merges new defaults with existing config without overwriting.
+
+---
+
+## VALIDATION
+
+Config is validated on load. Invalid configs show:
+
+```
+CONFIG ERROR
+============
+
+Invalid config: .grid/config.json
+
+Issues:
+- model_tier must be one of: quality, balanced, budget
+- budget.budget_limit must be number or null
+- git.auto_push must be one of: wave, block, manual, immediate
+
+Fix the config or run /grid:init --reset to restore defaults.
+```
+
+---
+
+## EXAMPLES
+
+### Budget-Conscious Setup
+
+```json
+{
+  "model_tier": "balanced",
+  "budget": {
+    "enabled": true,
+    "budget_limit": 25.00,
+    "enforcement": "hard"
+  },
+  "verification": {
+    "auto_verify": false
+  },
+  "refinement": {
+    "auto_refine": false
+  }
+}
+```
+
+### Team Collaboration Setup
+
+```json
+{
+  "git": {
+    "auto_branch": true,
+    "auto_push": "wave",
+    "auto_pr": true,
+    "commit_signing": true
+  },
+  "daemon": {
+    "notifications": {
+      "webhook": "https://hooks.slack.com/services/..."
+    }
+  }
+}
+```
+
+### Fast Iteration Setup
+
+```json
+{
+  "model_tier": "quality",
+  "verification": {
+    "auto_verify": true
+  },
+  "refinement": {
+    "auto_refine": false
+  },
+  "research": {
+    "auto_research": false
+  },
+  "git": {
+    "auto_push": "immediate"
+  }
+}
+```
+
+---
+
+End of Line.