---
cluster: grid-viz
block: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - tools/grid-viz/grid-viz.js
  - tools/grid-viz/package.json
  - tools/grid-viz/README.md
autonomous: true

must_haves:
  truths:
    - "User can run grid-viz.js and see formatted Grid state"
    - "Progress bar displays current block/phase completion"
    - "Recent scratchpad entries are visible"
    - "Active blockers and decisions are highlighted"
    - "Warmth/learnings count is shown"
  artifacts:
    - path: "tools/grid-viz/grid-viz.js"
      provides: "Main CLI visualization script"
      min_lines: 150
      exports: []
    - path: "tools/grid-viz/package.json"
      provides: "Package manifest with chalk dependency"
      exports: []
    - path: "tools/grid-viz/README.md"
      provides: "Usage documentation"
      min_lines: 20
  key_links:
    - from: "grid-viz.js"
      to: ".grid/STATE.md"
      via: "fs.readFileSync parse"
      pattern: "readFileSync.*STATE\\.md"
    - from: "grid-viz.js"
      to: ".grid/SCRATCHPAD.md"
      via: "fs.readFileSync parse"
      pattern: "readFileSync.*SCRATCHPAD\\.md"
    - from: "grid-viz.js"
      to: ".grid/LEARNINGS.md"
      via: "fs.readFileSync parse"
      pattern: "readFileSync.*LEARNINGS\\.md"
---

<objective>
Build a terminal visualization tool that displays Grid project state in a clear, colorful format.

Purpose: Provide quick visual insight into Grid project progress without reading raw markdown files.
Output: Single-file Node.js CLI tool with chalk-based terminal rendering.
</objective>

<context>
Grid projects store state in .grid/ directory with structured markdown files:
- STATE.md: Current cluster, blocks, threads, active programs
- SCRATCHPAD.md: Running notes, discoveries, decisions
- LEARNINGS.md: Lessons learned during execution

This tool reads these files and renders a dashboard view with:
- Color-coded sections (chalk)
- Progress indicators for blocks/threads
- Recent activity highlights
- Visual hierarchy

Target usage: `node grid-viz.js` from Grid project root or `node /path/to/grid-viz.js` from anywhere.
</context>

<threads>

<thread type="auto">
  <name>Thread 1: Create grid-viz.js with file parsing and terminal rendering</name>
  <files>tools/grid-viz/grid-viz.js</files>
  <action>
Create grid-viz.js as a single-file Node.js CLI tool:

1. **File Structure:**
   - Shebang line: `#!/usr/bin/env node`
   - Import: fs, path, chalk
   - Helper functions: parseStateFile(), parseScratchpad(), parseLearnings()
   - Rendering functions: renderHeader(), renderProgress(), renderScratchpad(), renderBlockers(), renderWarmth()
   - Main function: main()

2. **File Parsing:**
   - Read .grid/STATE.md: Extract cluster name, status, energy, blocks table
   - Read .grid/SCRATCHPAD.md: Extract last 5 entries (look for timestamped sections or bullet points)
   - Read .grid/LEARNINGS.md: Count total learnings entries
   - Handle missing files gracefully (show "No .grid/ directory found")

3. **Terminal Rendering:**
   - Header: Cyan bold "GRID PROJECT STATE" with cluster name
   - Progress section:
     - Green for COMPLETE blocks/threads
     - Yellow for IN_PROGRESS
     - White for PENDING
     - Bar visualization using Unicode box characters
   - Scratchpad: Recent discoveries (yellow highlights on key terms)
   - Blockers: Red-highlighted active decisions from STATE.md "I/O TOWER" section
   - Warmth: Count of learnings with flame emoji if >0

4. **Color Scheme:**
   - Headers: cyan bold
   - Success/complete: green
   - In-progress: yellow
   - Pending: white/dim
   - Errors/blockers: red
   - Highlights: magenta for important keywords

5. **Error Handling:**
   - Check if .grid/ exists in current directory
   - If not, show helpful message: "Not a Grid project. Run from Grid project root."
   - Gracefully handle malformed markdown

**What to avoid and WHY:**
- Avoid complex CLI argument parsing - This is a simple visualization tool, not a complex CLI. Keep it single-purpose.
- Avoid external markdown parsers - Use simple regex/string parsing to keep it lightweight and dependency-free except chalk.
- Avoid real-time watching - This is a snapshot tool. Running it again shows updated state.
  </action>
  <verify>Run `node tools/grid-viz/grid-viz.js` from /Users/jacweath/grid and confirm it displays formatted state with colors</verify>
  <done>grid-viz.js exists, reads all three .grid files, renders colorful terminal output with progress bars, scratchpad highlights, and warmth summary</done>
</thread>

<thread type="auto">
  <name>Thread 2: Create package.json and README.md</name>
  <files>tools/grid-viz/package.json, tools/grid-viz/README.md</files>
  <action>
Create supporting files:

1. **package.json:**
```json
{
  "name": "grid-viz",
  "version": "1.0.0",
  "description": "Terminal visualization for Grid project state",
  "main": "grid-viz.js",
  "bin": {
    "grid-viz": "./grid-viz.js"
  },
  "dependencies": {
    "chalk": "^4.1.2"
  },
  "engines": {
    "node": ">=14.0.0"
  }
}
```

2. **README.md:**
Include:
- Project description
- Installation: `npm install` in tools/grid-viz/
- Usage:
  - From Grid project: `node tools/grid-viz/grid-viz.js`
  - From anywhere: `node /path/to/grid-viz.js` (must be in Grid project dir)
  - Future: Install globally with `npm install -g`
- Screenshot/example output (ASCII art mockup)
- Requirements: Node 14+, chalk dependency
- What it displays:
  - Cluster status and energy
  - Block/thread progress
  - Recent scratchpad discoveries (last 5)
  - Active blockers from I/O Tower
  - Warmth summary (learnings count)

**What to avoid and WHY:**
- Avoid overpromising features - Document only what exists now. No "coming soon" features.
- Avoid complex installation steps - This is a dev tool for Grid maintainers, not public npm package (yet).
  </action>
  <verify>Verify package.json is valid JSON and README.md is clear and accurate</verify>
  <done>package.json and README.md exist with accurate content, npm install works in tools/grid-viz/</done>
</thread>

<thread type="auto">
  <name>Thread 3: Test grid-viz with Grid repo state and document output format</name>
  <files>tools/grid-viz/grid-viz.js</files>
  <action>
Test and refine the visualization:

1. **Test Cases:**
   - Run from /Users/jacweath/grid (has .grid/ directory)
   - Test with COMPLETE cluster (current state)
   - Verify colors render correctly in terminal
   - Check progress bar calculation (e.g., 4/4 threads = 100% = full bar)
   - Verify scratchpad parsing extracts recent entries
   - Confirm learnings count is accurate

2. **Output Format Refinement:**
   - Ensure proper spacing and alignment
   - Use Unicode box-drawing characters for visual structure:
     - ┌─┐ │ ├─┤ └─┘ for sections
     - ▓░ for progress bars
   - Keep total output under 50 lines for quick scanning
   - Make "no blockers" state clear (green checkmark)

3. **Edge Cases:**
   - Empty scratchpad (show "No recent activity")
   - Zero learnings (show "No learnings recorded yet")
   - Missing I/O Tower section (skip blockers section)
   - Malformed STATE.md (show error but don't crash)

4. **Documentation:**
   - Add inline comments explaining file parsing logic
   - Document expected .grid/ file structure at top of file
   - Include example output in README.md

**What to avoid and WHY:**
- Avoid assuming specific STATE.md formats - Parse flexibly since Grid state format may evolve.
- Avoid truncating important info - Show all blockers/decisions even if many (they're critical).
  </action>
  <verify>Run `cd /Users/jacweath/grid && node tools/grid-viz/grid-viz.js` and confirm output is clear, colorful, and informative</verify>
  <done>grid-viz tested successfully with Grid repo, handles edge cases gracefully, README includes example output</done>
</thread>

</threads>

<verification>
1. Run grid-viz from /Users/jacweath/grid and see formatted output
2. Check that colors display correctly (cyan headers, green success, yellow warnings, red errors)
3. Verify progress bars show correct completion percentages
4. Confirm scratchpad shows last 5 entries
5. Verify learnings count is accurate
6. Test error handling by running from non-Grid directory
7. Confirm package.json dependencies install correctly
</verification>

<success_criteria>
- grid-viz.js exists and is executable
- Displays Grid state with colors using chalk
- Shows progress bar for blocks/threads
- Renders recent scratchpad entries (last 5)
- Highlights active blockers/decisions
- Shows warmth summary (learnings count)
- Handles missing .grid/ directory gracefully
- README.md documents usage clearly
- Tool runs successfully from Grid project root
</success_criteria>