the-grid-cc 1.7.14 → 1.7.16

package/commands/grid/init.md

@@ -22,7 +22,7 @@ Initialize the `.grid/` directory structure for the current project. This create
 Create the complete `.grid/` directory structure:
 
 ```bash
-mkdir -p .grid/plans .grid/phases .grid/discs .grid/debug .grid/refinement/screenshots .grid/refinement/e2e .grid/refinement/personas
+mkdir -p .grid/plans .grid/phases .grid/discs .grid/debug .grid/daemon .grid/refinement/screenshots .grid/refinement/e2e .grid/refinement/personas
 ```
 
 ### Directory Purposes
@@ -34,6 +34,7 @@ mkdir -p .grid/plans .grid/phases .grid/discs .grid/debug .grid/refinement/scree
 | `.grid/phases/` | Execution artifacts (SUMMARY.md files) | Mission-scoped |
 | `.grid/discs/` | Identity Discs for Programs | Session-scoped |
 | `.grid/debug/` | Debug session state | Survives /clear |
+| `.grid/daemon/` | Daemon execution state | Mission-scoped |
 | `.grid/refinement/` | Refinement swarm outputs | Mission-scoped |
 
 ## CORE STATE FILES
@@ -234,6 +235,36 @@ Configuration for Grid behavior:
 }
 ```
 
+### budget.json (Budget Tracking)
+
+Initialize from template if not exists:
+
+```bash
+if [ ! -f .grid/budget.json ]; then
+  cp .grid/budget.template.json .grid/budget.json
+fi
+```
+
+Budget configuration for cost tracking (see `/grid:budget` for details):
+
+```json
+{
+  "budget_limit": null,
+  "currency": "USD",
+  "enforcement": "hard",
+  "warning_threshold": 0.75,
+  "confirmation_threshold": 0.90,
+  "current_session": {
+    "estimated_cost": 0,
+    "spawns": []
+  },
+  "history": {
+    "total_cost": 0,
+    "total_spawns": 0
+  }
+}
+```
+
 ## INITIALIZATION BEHAVIOR
 
 ### Step 1: Check Existing State
@@ -262,6 +293,7 @@ mkdir -p .grid/plans
 mkdir -p .grid/phases
 mkdir -p .grid/discs
 mkdir -p .grid/debug
+mkdir -p .grid/daemon
 mkdir -p .grid/refinement/screenshots
 mkdir -p .grid/refinement/e2e
 mkdir -p .grid/refinement/personas
@@ -302,11 +334,13 @@ Directory structure created:
 ├── DECISIONS.md          User decisions log
 ├── BLOCKERS.md           Blocker tracking
 ├── config.json           Grid configuration
+├── budget.json           Budget tracking (cost management)
 │
 ├── plans/                Execution plans
 ├── phases/               Execution artifacts (SUMMARY.md files)
 ├── discs/                Identity Discs for Programs
 ├── debug/                Debug session state
+├── daemon/               Daemon execution state (long-running tasks)
 └── refinement/           Refinement swarm outputs
     ├── screenshots/
     ├── e2e/

package/commands/grid/mc.md

@@ -341,30 +341,77 @@ These cause MC to go rogue. If you catch yourself doing ANY of these, STOP.
 ## QUICK REFERENCE
 
 ```
+CORE PROGRAMS
+─────────────
 Spawn Planner:    Task(prompt="First, read ~/.claude/agents/grid-planner.md...", ...)
 Spawn Executor:   Task(prompt="First, read ~/.claude/agents/grid-executor.md...", ...)
 Spawn Recognizer: Task(prompt="First, read ~/.claude/agents/grid-recognizer.md...", ...)
 Spawn Debugger:   Task(prompt="First, read ~/.claude/agents/grid-debugger.md...", ...)
 
-Refinement Swarm:
-  Visual:    Task(prompt="First, read ~/.claude/agents/grid-visual-inspector.md...", ...)
-  E2E:       Task(prompt="First, read ~/.claude/agents/grid-e2e-exerciser.md...", ...)
-  Persona:   Task(prompt="First, read ~/.claude/agents/grid-persona-simulator.md...", ...)
-  Synth:     Task(prompt="First, read ~/.claude/agents/grid-refinement-synth.md...", ...)
-
+REFINEMENT SWARM
+────────────────
+Visual:    Task(prompt="First, read ~/.claude/agents/grid-visual-inspector.md...", ...)
+E2E:       Task(prompt="First, read ~/.claude/agents/grid-e2e-exerciser.md...", ...)
+Persona:   Task(prompt="First, read ~/.claude/agents/grid-persona-simulator.md...", ...)
+Synth:     Task(prompt="First, read ~/.claude/agents/grid-refinement-synth.md...", ...)
+
+SPECIALIST PROGRAMS
+───────────────────
+Git Ops:      Task(prompt="First, read ~/.claude/agents/grid-git-operator.md...", ...)
+Accountant:   Task(prompt="First, read ~/.claude/agents/grid-accountant.md...", ...)
+Researcher:   Task(prompt="First, read ~/.claude/agents/grid-researcher.md...", ...)
+Scout:        Task(prompt="First, read ~/.claude/agents/grid-scout.md...", ...)
+
+COMMANDS
+────────
+/grid              Main entry point (AUTOPILOT mode)
+/grid:quick        Fast execution (trivial tasks)
+/grid:refine       Refinement swarm (visual, e2e, personas)
+/grid:debug        Systematic bug investigation
+/grid:status       Grid status and progress
+/grid:resume       Resume interrupted missions
+/grid:daemon       Background execution mode
+/grid:budget       Cost tracking and limits
+/grid:branch       Git branch management
+/grid:model        Configure model selection
+/grid:init         Initialize Grid state
+/grid:help         Command reference
+/grid:mc           Master Control (this)
+/grid:program_disc View program identity disc
+/grid:update       Update Grid to latest
+
+OPERATIONS
+──────────
 Parallel spawn:   Multiple Task() calls in ONE message
 Wave execution:   Read wave numbers from plan frontmatter, auto-verify after each
 Verification:     Automatic after SUCCESS (wave-level, opt-out via verify: false)
 Quick mode:       Auto-detect trivial builds (<=5 files, single block, clear scope)
 Checkpoints:      Present via I/O Tower, spawn fresh with warmth
-State:            Check .grid/STATE.md on startup
-Learnings:        Check .grid/LEARNINGS.md for past patterns
-Scratchpad:       .grid/SCRATCHPAD.md for live discoveries (MANDATORY writes)
-Debug:            Check .grid/debug/ for investigation graphs
-Warmth:           lessons_learned in SUMMARY.md frontmatter
-Retry:            Pass failure report to retry spawns
-Plan pipeline:    Planner returns structured YAML with inline content
-Protocols:        Full details in ~/.claude/docs/MC_PROTOCOLS.md
+Budget checks:    Before EVERY spawn, enforce limits
+Branch management: Auto-create feature branches, never commit to main
+Cost tracking:    Record all spawns, estimate cluster costs
+
+STATE FILES
+───────────
+State:        .grid/STATE.md - Current mission state
+Learnings:    .grid/LEARNINGS.md - Past patterns
+Scratchpad:   .grid/SCRATCHPAD.md - Live discoveries (MANDATORY writes)
+Debug:        .grid/debug/ - Investigation graphs
+Budget:       .grid/budget.json - Cost tracking
+Config:       .grid/config.json - All settings
+Checkpoint:   .grid/CHECKPOINT.md - Resume points
+
+TRANSFER
+────────
+Warmth:       lessons_learned in SUMMARY.md frontmatter
+Retry:        Pass failure report to retry spawns
+Research:     Cache in .grid/research_cache/
+Scout:        Recon reports in .grid/scout/
+
+PROTOCOLS
+─────────
+Plan pipeline: Planner returns structured YAML with inline content
+Full details:  ~/.claude/docs/MC_PROTOCOLS.md
 ```
 
 End of Line.

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.