the-grid-cc 1.7.13 → 1.7.15

package/docs/WIRING_VERIFICATION.md

@@ -0,0 +1,389 @@
+# Grid Wiring Verification
+
+This document verifies that all Grid components are properly integrated and referenced.
+
+**Status:** ✓ COMPLETE
+**Date:** 2026-01-23
+**Version:** 1.7.x
+
+---
+
+## MASTER CONTROL INTEGRATION
+
+### Commands Referenced in MC
+
+✓ `/grid` - Main entry point
+✓ `/grid:quick` - Fast execution
+✓ `/grid:refine` - Refinement swarm
+✓ `/grid:debug` - Bug investigation
+✓ `/grid:status` - Status display
+✓ `/grid:resume` - Resume missions
+✓ `/grid:daemon` - Background mode
+✓ `/grid:budget` - Cost tracking
+✓ `/grid:branch` - Git management
+✓ `/grid:model` - Model selection
+✓ `/grid:init` - Initialize state
+✓ `/grid:help` - Command reference
+✓ `/grid:mc` - Master Control
+✓ `/grid:program_disc` - Identity disc
+✓ `/grid:update` - Update Grid
+
+**Verification:** All commands present in Quick Reference section.
+
+---
+
+## AGENT PROGRAMS
+
+### Core Programs
+
+✓ `grid-planner.md` - Creates execution plans
+✓ `grid-executor.md` - Executes tasks
+✓ `grid-recognizer.md` - Verifies work
+✓ `grid-debugger.md` - Investigates bugs
+
+### Refinement Swarm
+
+✓ `grid-visual-inspector.md` - Screenshot analysis
+✓ `grid-e2e-exerciser.md` - E2E testing
+✓ `grid-persona-simulator.md` - User simulation
+✓ `grid-refinement-synth.md` - Synthesis
+
+### Specialist Programs
+
+✓ `grid-git-operator.md` - Git operations
+✓ `grid-accountant.md` - Cost tracking
+✓ `grid-researcher.md` - External research
+✓ `grid-scout.md` - Codebase recon
+
+### Support Programs
+
+✓ `grid-guard.md` - Sentinel/monitoring
+
+**Verification:** All agents listed in MC Quick Reference.
+
+---
+
+## SPAWN PROTOCOLS
+
+### MC Can Spawn
+
+| Program | Spawn Pattern | Verified |
+|---------|---------------|----------|
+| Planner | `Task(prompt="First, read ~/.claude/agents/grid-planner.md...")` | ✓ |
+| Executor | `Task(prompt="First, read ~/.claude/agents/grid-executor.md...")` | ✓ |
+| Recognizer | `Task(prompt="First, read ~/.claude/agents/grid-recognizer.md...")` | ✓ |
+| Debugger | `Task(prompt="First, read ~/.claude/agents/grid-debugger.md...")` | ✓ |
+| Visual Inspector | `Task(prompt="First, read ~/.claude/agents/grid-visual-inspector.md...")` | ✓ |
+| E2E Exerciser | `Task(prompt="First, read ~/.claude/agents/grid-e2e-exerciser.md...")` | ✓ |
+| Persona Simulator | `Task(prompt="First, read ~/.claude/agents/grid-persona-simulator.md...")` | ✓ |
+| Refinement Synth | `Task(prompt="First, read ~/.claude/agents/grid-refinement-synth.md...")` | ✓ |
+| Git Operator | `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...")` | ✓ |
+
+**Verification:** All spawn patterns follow standard protocol.
+
+---
+
+## STATE FILES
+
+### MC Knows About
+
+| File | Purpose | MC Reference |
+|------|---------|--------------|
+| `.grid/STATE.md` | Mission state | ✓ Quick Reference |
+| `.grid/LEARNINGS.md` | Past patterns | ✓ Quick Reference |
+| `.grid/SCRATCHPAD.md` | Live updates | ✓ Quick Reference |
+| `.grid/debug/` | Debug sessions | ✓ Quick Reference |
+| `.grid/budget.json` | Cost tracking | ✓ Quick Reference |
+| `.grid/config.json` | All settings | ✓ Quick Reference |
+| `.grid/CHECKPOINT.md` | Resume points | ✓ Quick Reference |
+| `.grid/research_cache/` | Research cache | ✓ Quick Reference |
+| `.grid/scout/` | Scout reports | ✓ Quick Reference |
+
+**Verification:** All critical state files referenced.
+
+---
+
+## CONFIGURATION INTEGRATION
+
+### Config Schema Coverage
+
+✓ `model_tier` - Model selection (quality/balanced/budget)
+✓ `git.*` - Git operations and branching
+✓ `budget.*` - Cost tracking and limits
+✓ `daemon.*` - Background execution
+✓ `verification.*` - Auto-verify behavior
+✓ `refinement.*` - Refinement swarm settings
+✓ `research.*` - External research settings
+✓ `scout.*` - Codebase recon settings
+✓ `scratchpad.*` - Live observability settings
+✓ `learnings.*` - Institutional memory settings
+✓ `debug.*` - Debug session settings
+✓ `ui.*` - Output formatting
+
+**Verification:** Complete config schema in `docs/CONFIG_SCHEMA.md`.
+
+---
+
+## PROTOCOL INTEGRATION
+
+### MC References Protocols
+
+✓ Wave Execution Protocol
+✓ Warmth Transfer Protocol
+✓ Checkpoint Protocol
+✓ Verification Protocol
+✓ Retry Protocol
+✓ Scratchpad Protocol
+✓ Budget Enforcement Protocol
+✓ Branch Management Protocol
+
+**Source:** `~/.claude/docs/MC_PROTOCOLS.md`
+**Referenced in:** MC Quick Reference
+
+---
+
+## COMMAND INTEGRATION
+
+### Commands Work With
+
+| Command | Uses Agents | Uses Config | Uses State |
+|---------|-------------|-------------|------------|
+| `/grid` | Planner, Executor, Recognizer | ✓ | ✓ |
+| `/grid:quick` | Executor | ✓ | ✓ |
+| `/grid:refine` | Visual, E2E, Persona, Synth | ✓ | ✓ |
+| `/grid:debug` | Debugger | ✓ | ✓ |
+| `/grid:status` | - | ✓ | ✓ |
+| `/grid:resume` | Executor | ✓ | ✓ |
+| `/grid:daemon` | All | ✓ | ✓ |
+| `/grid:budget` | Accountant | ✓ | ✓ |
+| `/grid:branch` | Git Operator | ✓ | ✓ |
+| `/grid:model` | - | ✓ | - |
+| `/grid:init` | - | ✓ | ✓ |
+
+**Verification:** All commands integrated with appropriate agents and state.
+
+---
+
+## CROSS-REFERENCES
+
+### MC → Agents
+
+- MC spawns agents via Task()
+- MC passes state/warmth/context
+- MC receives SUMMARY.md back
+- MC extracts lessons_learned
+
+✓ Protocol defined in MC_PROTOCOLS.md
+
+### Agents → State Files
+
+- Agents read STATE.md for context
+- Agents write SCRATCHPAD.md during work
+- Agents write SUMMARY.md after work
+- Agents read/write CHECKPOINT.md
+
+✓ All agents follow state protocols
+
+### Commands → MC
+
+- Commands invoke MC as orchestrator
+- MC delegates to appropriate agents
+- MC reports back to user
+
+✓ Clear command hierarchy
+
+### Config → All Components
+
+- MC reads config on startup
+- Agents receive config via spawn prompts
+- Commands respect config settings
+
+✓ Single source of truth: `.grid/config.json`
+
+---
+
+## BUDGET INTEGRATION
+
+### Budget Checkpoints
+
+✓ MC checks budget BEFORE every spawn
+✓ Accountant provides estimates
+✓ Budget blocks spawns if exceeded (hard enforcement)
+✓ Budget warns at 75%, confirms at 90%
+
+### Budget Data Flow
+
+```
+MC → spawn decision
+  ↓
+Accountant → estimate cost
+  ↓
+Budget check → allow/confirm/block
+  ↓
+MC → proceed or stop
+  ↓
+Record spawn in budget.json
+```
+
+**Verification:** Complete budget workflow integrated.
+
+---
+
+## GIT INTEGRATION
+
+### Git Workflows
+
+✓ Session start → Git Operator checks branch
+✓ Auto-create feature branches if on main
+✓ Atomic commits per thread
+✓ Auto-push after waves (configurable)
+✓ PR creation on completion
+
+### Git Data Flow
+
+```
+MC → session start
+  ↓
+Git Operator → branch check/create
+  ↓
+Executor → complete thread
+  ↓
+Git Operator → atomic commit
+  ↓
+MC → wave complete
+  ↓
+Git Operator → push (if auto_push=wave)
+  ↓
+MC → mission complete
+  ↓
+Git Operator → offer PR creation
+```
+
+**Verification:** Complete git workflow integrated.
+
+---
+
+## DAEMON INTEGRATION
+
+### Daemon Lifecycle
+
+✓ `/grid:daemon` starts background execution
+✓ Daemon writes heartbeat every 30s
+✓ Daemon checkpoints after each wave
+✓ Daemon resumes from checkpoints
+✓ Daemon notifications on events
+
+### Daemon Components
+
+✓ `.grid/daemon/{id}/` - Daemon state directory
+✓ `checkpoint.json` - Execution state
+✓ `heartbeat.json` - Health monitoring
+✓ `output.log` - Full output
+✓ `audit.log` - Action trail
+
+**Verification:** Complete daemon system integrated.
+
+---
+
+## RESUME INTEGRATION
+
+### Resume Capability
+
+✓ `/grid:resume` detects interrupted state
+✓ Validates state consistency (commits, files exist)
+✓ Reconstructs context from state files
+✓ Spawns continuation with warmth
+✓ Handles checkpoints, failures, session death
+
+### Resume Data Sources
+
+✓ `.grid/STATE.md` - Position and status
+✓ `.grid/CHECKPOINT.md` - Resume point
+✓ `.grid/WARMTH.md` - Learned patterns
+✓ `.grid/phases/*/SUMMARY.md` - Completed work
+✓ `.grid/SCRATCHPAD.md` - Live discoveries
+
+**Verification:** Complete resume workflow integrated.
+
+---
+
+## RESEARCH & SCOUT INTEGRATION
+
+### Pre-Planning Intelligence
+
+✓ MC spawns Scout for existing codebase analysis
+✓ MC spawns Researcher for external knowledge
+✓ Scout produces `.grid/scout/RECON_*.md`
+✓ Researcher produces `.grid/research_cache/*.md`
+✓ Planner receives both contexts
+
+### Intelligence Flow
+
+```
+MC → pre-planning phase
+  ↓
+Scout → analyze codebase (if exists)
+Researcher → search web (if needed)
+  ↓ (parallel)
+MC → collect intel
+  ↓
+Planner → plan with context
+```
+
+**Verification:** Intelligence gathering integrated.
+
+---
+
+## VERIFICATION CHECKLIST
+
+### All Components Present
+
+✓ 15 commands documented
+✓ 13 agent programs created
+✓ 9 state file types defined
+✓ 12 config sections specified
+✓ 8 major protocols documented
+
+### All References Valid
+
+✓ MC references all commands
+✓ MC references all agents
+✓ Commands reference appropriate agents
+✓ Agents reference state files
+✓ Config covers all settings
+
+### All Workflows Complete
+
+✓ Plan → Execute → Verify
+✓ Budget check → Spawn → Record
+✓ Branch → Commit → Push → PR
+✓ Checkpoint → Resume → Continue
+✓ Research → Scout → Plan
+
+### Documentation Complete
+
+✓ `commands/grid/*.md` - All commands
+✓ `agents/*.md` - All programs
+✓ `docs/MC_PROTOCOLS.md` - Detailed protocols
+✓ `docs/CONFIG_SCHEMA.md` - Complete schema
+✓ `docs/WIRING_VERIFICATION.md` - This doc
+
+---
+
+## INTEGRATION STATUS: COMPLETE
+
+All Grid components are properly wired and integrated:
+
+- ✓ Master Control knows all commands
+- ✓ Master Control can spawn all agents
+- ✓ All agents follow protocols
+- ✓ All state files documented
+- ✓ All config options defined
+- ✓ All workflows connected
+
+**The Grid is operational.**
+
+End of Line.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "the-grid-cc",
-  "version": "1.7.13",
+  "version": "1.7.15",
   "description": "Agent orchestration for Claude Code. You talk to Master Control. Master Control handles the rest.",
   "main": "index.js",
   "bin": {

package/templates/daemon-checkpoint.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "version": "1.0",
+  "daemon_id": "{YYYYMMDD-HHMMSS-slug}",
+  "created": "{ISO timestamp}",
+  "updated": "{ISO timestamp}",
+
+  "status": "starting",
+
+  "_status_values": [
+    "starting",
+    "executing",
+    "paused",
+    "checkpoint",
+    "complete",
+    "failed"
+  ],
+
+  "task": {
+    "description": "{user task description}",
+    "mode": "autopilot",
+    "original_prompt": "{full original prompt}"
+  },
+
+  "progress": {
+    "current_wave": 0,
+    "total_waves": 0,
+    "completed_blocks": [],
+    "current_block": null,
+    "percent": 0
+  },
+
+  "execution_state": {
+    "plan_data": {},
+    "completed_summaries": {},
+    "warmth": {},
+    "scratchpad_archive": []
+  },
+
+  "checkpoint_stack": [],
+
+  "checkpoint_history": [],
+
+  "metrics": {
+    "start_time": "{ISO timestamp}",
+    "elapsed_seconds": 0,
+    "programs_spawned": 0,
+    "commits_made": 0,
+    "estimated_remaining_seconds": 0
+  }
+}

package/templates/daemon-config.json

@@ -0,0 +1,28 @@
+{
+  "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
+    }
+  }
+}

package/templates/git-config.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Grid Git Autonomy Configuration",
+  "description": "Configuration for autonomous git operations in Grid sessions",
+  "type": "object",
+  "properties": {
+    "git": {
+      "type": "object",
+      "description": "Git autonomy settings",
+      "properties": {
+        "auto_branch": {
+          "type": "boolean",
+          "default": true,
+          "description": "Automatically create feature branch when starting work on protected branches"
+        },
+        "branch_prefix": {
+          "type": "string",
+          "default": "grid/",
+          "description": "Prefix for auto-created Grid branches",
+          "pattern": "^[a-z0-9-]+/$"
+        },
+        "auto_push": {
+          "type": "string",
+          "enum": ["immediate", "wave", "block", "manual"],
+          "default": "wave",
+          "description": "When to automatically push: immediate (every commit), wave (after wave completes), block (after block completes), manual (never)"
+        },
+        "auto_pr": {
+          "type": "boolean",
+          "default": false,
+          "description": "Automatically create pull request when session completes"
+        },
+        "protected_branches": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": ["main", "master", "production"],
+          "description": "Branches that require PRs and cannot be committed to directly"
+        },
+        "default_base": {
+          "type": "string",
+          "default": "main",
+          "description": "Default base branch for creating pull requests"
+        },
+        "sync_strategy": {
+          "type": "string",
+          "enum": ["merge", "rebase"],
+          "default": "merge",
+          "description": "Strategy for syncing feature branch with base: merge or rebase"
+        },
+        "commit_signing": {
+          "type": "boolean",
+          "default": false,
+          "description": "Sign commits with GPG (requires gpg configured)"
+        },
+        "wip_commits": {
+          "type": "boolean",
+          "default": true,
+          "description": "Create WIP commits on session pause for long-running work"
+        }
+      }
+    }
+  }
+}

package/templates/grid-state/.gitignore-entry

@@ -0,0 +1,3 @@
+# Grid state (local only)
+# Add this to your project's .gitignore
+.grid/

package/templates/grid-state/BLOCK-SUMMARY.md

@@ -0,0 +1,66 @@
+---
+cluster: null
+block: "00"
+block_name: "Block Name"
+status: complete  # in_progress | complete | failed
+started_at: "{ISO timestamp}"
+completed_at: "{ISO timestamp}"
+
+# Work completed
+commits:
+  - hash: "abc123"
+    message: "feat(00): Description"
+    files: ["path/to/file.js"]
+    timestamp: "{ISO timestamp}"
+
+artifacts_created:
+  - path: "path/to/file.js"
+    lines: 100
+    verified: true
+
+# Lessons learned
+lessons_learned:
+  codebase_patterns:
+    - "Pattern discovered"
+  gotchas:
+    - "Gotcha encountered"
+  user_preferences:
+    - "Preference inferred"
+  almost_did:
+    - "Approach considered but rejected"
+
+# Energy usage
+energy_used: 1000
+energy_remaining: 9000
+---
+
+# Block {N} Summary: {Block Name}
+
+## Overview
+{Brief description of what this block accomplished}
+
+## Threads Completed
+
+### Thread 1: {Thread Name}
+- **Status:** Complete
+- **Commit:** {hash}
+- **Files:** {list}
+- **Description:** {what was done}
+
+### Thread 2: {Thread Name}
+- **Status:** Complete
+- **Commit:** {hash}
+- **Files:** {list}
+- **Description:** {what was done}
+
+## Artifacts Created
+{List of all files/directories created with brief descriptions}
+
+## Lessons Learned
+{Key discoveries that will help future blocks}
+
+## Blockers Encountered
+{Any issues that blocked progress and how they were resolved}
+
+## Next Block Preview
+{Brief note about what the next block will tackle}

package/templates/grid-state/BLOCKERS.md

@@ -0,0 +1,31 @@
+---
+cluster: null
+active_blockers: 0
+resolved_blockers: 0
+last_updated: "{ISO timestamp}"
+---
+
+# Grid Blockers
+
+Issues that blocked progress. Used for resume and reporting.
+
+## Format
+
+Each blocker follows this format:
+
+```
+## Blocker {N}: {ACTIVE | RESOLVED}
+**Block:** {block_id}
+**Thread:** {thread_id}
+**Type:** {dependency_missing | human_action_required | external_service | bug}
+**Description:** {what's blocking}
+**Resolution:** {how it was resolved, if resolved}
+**Created At:** {timestamp}
+**Resolved At:** {timestamp, if resolved}
+```
+
+---
+
+## Blockers
+
+*(Blockers will appear below)*

package/templates/grid-state/CHECKPOINT.md

@@ -0,0 +1,59 @@
+---
+# Checkpoint metadata
+type: human_verify  # human_verify | decision | human_action | session_death | failure
+timestamp: "{ISO timestamp}"
+expires: null  # or ISO timestamp if time-sensitive
+
+# Position
+cluster: null
+block: "00"
+wave: 0
+thread: 0
+thread_name: "CHECKPOINT"
+
+# Progress snapshot
+progress:
+  blocks_complete: 0
+  blocks_total: 0
+  threads_complete: 0
+  threads_total: 0
+
+# Completed work (essential for continuation)
+completed_threads: []
+  # Example:
+  # - id: "02.1"
+  #   name: "Create BaseLayout"
+  #   commit: "abc123"
+  #   files: ["src/layouts/BaseLayout.astro"]
+  #   status: complete
+
+# Checkpoint-specific details
+checkpoint_details:
+  verification_instructions: |
+    {What the user needs to verify}
+  expected_behavior: |
+    {What should happen}
+
+# User action needed
+awaiting: "User to respond"
+
+# Warmth for continuation
+warmth:
+  codebase_patterns: []
+  gotchas: []
+  user_preferences: []
+
+# Optional fields
+# user_response: "{user's response when resuming}"
+---
+
+# Checkpoint
+
+## Summary
+{Brief description of what was accomplished and what needs to happen next}
+
+## Completed Work
+{List of completed threads with commits}
+
+## Next Steps
+{What will happen when execution resumes}