@colin4k1024/tsp 2.5.1 → 2.5.3

package/bin/lib/install-surface.js

@@ -37,6 +37,11 @@ const TARGET_METADATA = Object.freeze({
     installPath: '~/.config/opencode/',
     scope: 'home-level',
   },
+  cangming: {
+    label: 'Cangming',
+    installPath: '~/.config/cangming/',
+    scope: 'home-level',
+  },
   codebuddy: {
     label: 'CodeBuddy',
     installPath: './.codebuddy/',

package/commands/dashboard.md

@@ -0,0 +1,105 @@
+# Dashboard Command
+
+Real-time progress visibility for goals, waves, and triage. Shows what the loop
+is doing, how much budget remains, and what needs human attention.
+
+## Usage
+
+`/dashboard`
+
+## Output
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  LOOP ENGINEERING DASHBOARD                                  ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  ACTIVE GOALS                                                ║
+║  ─────────────                                               ║
+║  ▶ [goal-a1b2c3d4] "Fix all failing tests"                  ║
+║    Iteration: 3/15 | Budget: $1.20/$10 | Time: 25m/2h       ║
+║    Last oracle: FAIL — 2 tests still failing in auth module  ║
+║    Next hint: Focus on token refresh mock                    ║
+║                                                              ║
+║  ⏸ [goal-e5f6g7h8] "Achieve 80% coverage"                   ║
+║    Iteration: 7/15 | Budget: $3.50/$10 | Paused             ║
+║                                                              ║
+║  HEARTBEAT                                                   ║
+║  ─────────────                                               ║
+║  Status: Running (interval: 30m)                             ║
+║  Last run: 12m ago — 2/3 passed, 1 goal created             ║
+║  Next run: 18m                                               ║
+║  Budget: $0.80/$2.00 per hour                                ║
+║                                                              ║
+║  TRIAGE INBOX                                                ║
+║  ─────────────                                               ║
+║  [3 pending] [1 high] [2 medium]                             ║
+║  • HIGH: sentry — 5 unresolved errors (2h ago)               ║
+║  • MED:  lint — 4 new lint errors (30m ago)                  ║
+║  • MED:  deps — 2 moderate vulnerabilities (1d ago)          ║
+║                                                              ║
+║  WAVE EXECUTION                                              ║
+║  ─────────────                                               ║
+║  (No active waves)                                           ║
+║                                                              ║
+║  REWORK TRACKING                                             ║
+║  ─────────────                                               ║
+║  Persistent trouble spots: 1                                 ║
+║  • src/auth/refresh.ts — 3 attempts, last: fail             ║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+## Data Sources
+
+The dashboard aggregates from:
+
+| Source | Location |
+|--------|----------|
+| Active goals | `~/.claude/goals/*.json` |
+| Heartbeat state | `~/.claude/heartbeat-last-run.json` |
+| Triage inbox | `~/.claude/triage/inbox.jsonl` |
+| Wave progress | Worker `status.md` files in coordination dirs |
+| Rework tracking | `~/.claude/rework-tracking.json` |
+| Cost tracking | Goal history `costDollars` fields |
+
+## Sections
+
+### Active Goals
+- State icon: ▶ (active), ⏸ (paused), ✓ (converged), ⚠ (escalated)
+- Progress: iteration/max, cost/budget, time/duration
+- Last oracle verdict and hint
+
+### Heartbeat
+- Running/stopped status
+- Last run results (passed/failed count)
+- Time to next run
+- Hourly budget usage
+
+### Triage Inbox
+- Pending count by severity
+- Top 3 most recent items with source and age
+- Action hint: "Use /triage to act on items"
+
+### Wave Execution
+- Active wave index / total waves
+- Per-worker status and progress estimate
+- Critical path and ETA (when workers report progress)
+
+### Rework Tracking
+- Persistent trouble spots (files with 3+ rework attempts)
+- Escalation recommendations
+
+## Integration
+
+- **`/goal status`**: Dashboard includes goal details
+- **`/heartbeat status`**: Dashboard includes heartbeat state
+- **`/triage stats`**: Dashboard includes inbox summary
+- **Wave execution**: Dashboard tracks parallel worker progress
+
+## Arguments
+
+$ARGUMENTS:
+- (none) — Show full dashboard
+- `--compact` — One-line summary per section
+- `--json` — Machine-readable output

package/commands/goal.md

@@ -0,0 +1,142 @@
+# Goal Command
+
+Define and run a goal-oriented autonomous loop with an external completion oracle.
+
+The goal primitive keeps iterating until verifiable stopping conditions are met,
+checked by a SEPARATE model (the oracle) to eliminate author-bias.
+
+## Usage
+
+`/goal <subcommand> [args]`
+
+## Subcommands
+
+### Create & Start
+
+```
+/goal "make all tests pass"
+/goal "achieve 80% coverage" --budget-iterations 10 --budget-dollars 5
+/goal "fix lint errors in src/" --checker sonnet
+```
+
+Creates a new goal, infers stopping conditions from the objective, and starts
+the maker-oracle loop immediately.
+
+**Auto-inferred stopping conditions:**
+- "tests pass" → `npm test` exit code 0
+- "coverage N%" → coverage report >= N
+- "lint clean" → `npm run lint` exit code 0
+- "build passes" → `npm run build` exit code 0
+- Custom: specify with `--condition "command"`
+
+### Status
+
+```
+/goal status
+/goal status <goalId>
+```
+
+Show active goals with current iteration, oracle verdict history, budget usage,
+and estimated remaining iterations.
+
+### Resume
+
+```
+/goal resume
+/goal resume <goalId>
+```
+
+Resume an active goal from a previous session. Reads state from
+`~/.claude/goals/{goalId}.json` and re-enters the maker loop with the oracle's
+last `nextHint` as guidance.
+
+### Pause
+
+```
+/goal pause
+/goal pause <goalId>
+```
+
+Pause without abandoning. State is persisted for later `/goal resume`.
+
+### List
+
+```
+/goal list
+```
+
+Show all goals (active, paused, converged, escalated) with summary stats.
+
+## The Maker-Oracle Loop
+
+```
+┌─────────────────────────────────────────────────────┐
+│  /goal "fix all tests"                              │
+│                                                     │
+│  ┌─────────┐    ┌─────────┐    ┌──────────┐       │
+│  │  MAKER  │───▶│ ORACLE  │───▶│ CONVERGE │       │
+│  │(primary)│    │(checker)│    │  or LOOP │       │
+│  └─────────┘    └─────────┘    └──────────┘       │
+│       ▲              │                   │          │
+│       │         verdict: fail            │          │
+│       │         + nextHint               │          │
+│       └──────────────┘                   │          │
+│                                          │          │
+│  Budget exhausted? ──▶ ESCALATE to triage│          │
+└─────────────────────────────────────────────────────┘
+```
+
+1. **Maker** (your primary model) executes one iteration toward the objective
+2. **Oracle** (different model, read-only) evaluates ALL stopping conditions
+3. If all pass → goal state becomes `converged`
+4. If any fail → oracle provides `nextHint` → maker iterates again
+5. If budget exhausted → goal becomes `escalated` → lands in triage inbox
+
+## Oracle Behavior
+
+The oracle:
+- Uses a DIFFERENT model than the maker (default: haiku for speed/cost)
+- Has READ-ONLY tool access (Read, Bash without writes)
+- Cannot modify code — only evaluate conditions
+- Returns structured verdict: `{converged, reasons[], nextHint}`
+- Is the reason you can walk away from a running loop
+
+## Budget Controls
+
+| Control | Default | Flag |
+|---------|---------|------|
+| Max iterations | 15 | `--budget-iterations N` |
+| Max duration | 2h | `--budget-duration Nh` |
+| Max cost | $10 | `--budget-dollars N` |
+| Checker model | haiku | `--checker model` |
+
+When ANY budget limit is hit, the goal escalates rather than continuing blindly.
+
+## State Persistence
+
+Goals persist to `~/.claude/goals/{goalId}.json` (follows goal.schema.json).
+
+- Active goals survive session restarts
+- SessionStart hook displays active goal reminder
+- Full iteration history is preserved for debugging
+
+## Integration
+
+- **Triage inbox:** Escalated goals create triage items (`/triage`)
+- **Heartbeat:** Heartbeat scans can auto-create goals (`/heartbeat`)
+- **Checkpoint:** Each iteration creates an implicit checkpoint
+- **Verification loop:** Oracle uses verification-loop patterns internally
+
+## Arguments
+
+$ARGUMENTS:
+- `<objective>` — Natural language goal description (quoted string)
+- `--budget-iterations N` — Max iterations (default 15)
+- `--budget-duration Nm|Nh` — Max wall time (default 2h)
+- `--budget-dollars N` — Max cost USD (default 10)
+- `--checker model` — Oracle model (default haiku)
+- `--condition "command"` — Additional stopping condition command
+- `status [goalId]` — Show goal status
+- `resume [goalId]` — Resume paused/interrupted goal
+- `pause [goalId]` — Pause active goal
+- `list` — List all goals

package/commands/heartbeat.md

@@ -0,0 +1,129 @@
+# Heartbeat Command
+
+Run discovery scans on a schedule to find issues, auto-create goals, or surface
+findings to the triage inbox. The heartbeat is what makes a loop an actual loop —
+not a one-shot run.
+
+## Usage
+
+`/heartbeat <subcommand> [args]`
+
+## Subcommands
+
+### Start
+
+```
+/heartbeat start
+/heartbeat start --interval 30m
+/heartbeat start --scan test-health,lint-drift
+```
+
+Registers a recurring CronCreate job that runs configured scans. Empty runs
+(all scans pass) archive themselves silently.
+
+### Stop
+
+```
+/heartbeat stop
+```
+
+Cancels the recurring heartbeat job via CronDelete.
+
+### Status
+
+```
+/heartbeat status
+```
+
+Shows:
+- Last scan time and results
+- Next scheduled run
+- Budget usage (cost per hour)
+- Active scan configurations
+
+### Run Once
+
+```
+/heartbeat run
+```
+
+Execute all configured scans immediately (one-shot, no scheduling).
+
+## Configuration
+
+Heartbeat reads from `.claude/heartbeat.yaml` in the project root:
+
+```yaml
+heartbeat:
+  interval: "30m"       # How often to tick (default: 30m)
+  scans:
+    - name: "test-health"
+      command: "npm test 2>&1 | tail -10"
+      onFailure: "auto-goal"    # auto-create a goal to fix it
+      description: "Run test suite"
+    - name: "lint-drift"
+      command: "npm run lint -- --quiet 2>&1 | wc -l"
+      threshold: 0               # numeric threshold: pass if output <= threshold
+      onFailure: "triage"        # surface to triage inbox for human
+      description: "Check lint errors"
+    - name: "dependency-audit"
+      command: "npm audit --production 2>&1 | grep -c 'vulnerabilities'"
+      threshold: 0
+      onFailure: "triage"
+      description: "Audit dependencies"
+    - name: "type-check"
+      command: "npx tsc --noEmit 2>&1; echo EXIT:$?"
+      onFailure: "auto-goal"
+      description: "TypeScript type checking"
+  budget:
+    maxDollarsPerHour: 2.0      # Pause heartbeat if cost exceeds this
+    pauseOnExhaust: true         # Pause vs stop on budget exhaust
+```
+
+## Scan Classification
+
+Each scan result is classified into an action:
+
+| Action | Behavior |
+|--------|----------|
+| `auto-goal` | Create a goal automatically from the failure (e.g., "fix 3 failing tests") |
+| `triage` | Append to triage inbox for human review |
+| `notify` | Desktop notification only (informational) |
+| `ignore` | Log silently, take no action |
+
+## Flow
+
+```
+┌────────────────────────────────────────────┐
+│  /heartbeat start                          │
+│                                            │
+│  CronCreate (every 30m)                    │
+│       │                                    │
+│       ▼                                    │
+│  Run all scans                             │
+│       │                                    │
+│  ┌────┼────────┬──────────┐               │
+│  ▼    ▼        ▼          ▼               │
+│ PASS  FAIL     FAIL       FAIL            │
+│  │    (goal)   (triage)   (notify)        │
+│  │      │        │          │             │
+│  ▼      ▼        ▼          ▼             │
+│ Skip  /goal    /triage    Desktop         │
+│       create   inbox      notification    │
+└────────────────────────────────────────────┘
+```
+
+## Integration
+
+- **`/goal`**: Heartbeat auto-creates goals from `auto-goal` scan failures
+- **`/triage`**: Heartbeat populates triage inbox from `triage` scan failures
+- **Budget**: Integrates with cost tracking; pauses if hourly budget exceeded
+- **Hooks**: Uses CronCreate/CronDelete for scheduling (7-day auto-expiry applies)
+
+## Arguments
+
+$ARGUMENTS:
+- `start [--interval Nm|Nh] [--scan name1,name2]` — Start recurring heartbeat
+- `stop` — Cancel heartbeat
+- `status` — Show heartbeat state
+- `run` — Execute scans once (no scheduling)

package/commands/triage.md

@@ -0,0 +1,108 @@
+# Triage Command
+
+View and act on findings that the loop could not auto-resolve. The triage inbox
+is where issues land when they need human judgment.
+
+## Usage
+
+`/triage [subcommand] [args]`
+
+## Subcommands
+
+### List (default)
+
+```
+/triage
+/triage list
+/triage list --source heartbeat
+/triage list --severity high
+```
+
+Show pending triage items with source, severity, and suggested actions.
+
+### Act
+
+```
+/triage act <id> goal      # Promote to a goal (auto-fix)
+/triage act <id> dismiss   # Dismiss (not actionable)
+/triage act <id> defer     # Defer to next session
+```
+
+Take action on a triage item. `goal` creates a goal from the finding.
+
+### Stats
+
+```
+/triage stats
+```
+
+Show inbox health metrics: pending count, sources breakdown, age distribution.
+
+### Clear
+
+```
+/triage clear --resolved
+/triage clear --older-than 7d
+```
+
+Remove resolved or stale items.
+
+## Triage Item Structure
+
+Each item in the inbox has:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Unique identifier (e.g., `triage-lq4x8`) |
+| `source` | Where it came from (e.g., `heartbeat:lint-drift`, `goal:escalated`) |
+| `severity` | `high`, `medium`, `low` |
+| `summary` | One-line description |
+| `detail` | Full scan output or error context |
+| `suggestedActions` | What the system recommends |
+| `createdAt` | When the item was created |
+| `status` | `pending`, `acted`, `dismissed`, `deferred` |
+
+## Sources
+
+Items enter triage from:
+
+1. **Heartbeat scans** with `onFailure: "triage"` classification
+2. **Escalated goals** that exhausted their budget without converging
+3. **Manual** items added by the user
+4. **Connectors** (MCP) that discover issues from external tools
+
+## Flow
+
+```
+┌──────────────┐     ┌─────────┐     ┌──────────────┐
+│  Heartbeat   │────▶│ TRIAGE  │────▶│  /triage act │
+│  Goal escape │     │  INBOX  │     │  goal/dismiss│
+│  Connectors  │     │ (.jsonl)│     │  /defer      │
+└──────────────┘     └─────────┘     └──────────────┘
+                          │
+                          ▼
+                    Statusline: [Triage: N]
+```
+
+## Storage
+
+Inbox is stored as newline-delimited JSON at `~/.claude/triage/inbox.jsonl`.
+This format is:
+- Append-only (safe for concurrent writes)
+- Human-readable (one JSON object per line)
+- Easy to grep and filter
+
+## Integration
+
+- **`/heartbeat`**: Primary source of triage items
+- **`/goal`**: Escalated goals create triage items; triage items can become goals
+- **Statusline**: Hook shows `[Triage: N]` count when items are pending
+- **Session start**: Active triage items mentioned in session context
+
+## Arguments
+
+$ARGUMENTS:
+- `list [--source name] [--severity level]` — List pending items (default)
+- `act <id> goal|dismiss|defer` — Take action on an item
+- `stats` — Show inbox metrics
+- `clear --resolved|--older-than Nd` — Clean up resolved/stale items

package/hooks/harness-context-monitor.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+// DEPRECATED: This hook's functionality has been merged into suggest-compact.js.
+// The strategic-compact hook now covers all thresholds (65/70/85/95%).
+// This file is retained for backward compatibility but is no longer registered in hooks.json.
+//
 // harness-context-monitor.js — PostToolUse hook (all tools)
 // Reads context metrics from the bridge file written by harness-statusline.js
 // and injects advisory warnings into agent context when usage is high.

package/hooks/harness-statusline.js

@@ -52,22 +52,45 @@ process.stdin.on('end', () => {
     if (remaining != null) {
       const usableRemaining = Math.max(0, ((remaining - AUTO_COMPACT_BUFFER_PCT) / (100 - AUTO_COMPACT_BUFFER_PCT)) * 100);
       usedPct = Math.max(0, Math.min(100, Math.round(100 - usableRemaining)));
+    } else if (data.transcript_path) {
+      // Parse actual token usage from transcript JSONL (CCometixLine approach)
+      try {
+        const { resolveTranscriptMetrics } = require('../scripts/lib/transcript-usage');
+        const modelId = (data.model && data.model.id) || process.env.CLAUDE_MODEL || null;
+        const metrics = resolveTranscriptMetrics(data.transcript_path, modelId);
+        if (metrics) {
+          usedPct = Math.max(0, Math.min(100, Math.round(metrics.usagePct)));
+        }
+      } catch (_) { /* ignore */ }
 
-      // Write bridge file for harness-context-monitor.js
-      if (session) {
+      // Final fallback: file size estimate
+      if (usedPct == null) {
         try {
-          const bridgePath = path.join(os.tmpdir(), `harness-ctx-${session}.json`);
-          fs.writeFileSync(bridgePath, JSON.stringify({
-            session_id: session,
-            remaining_percentage: remaining,
-            used_pct: usedPct,
-            active_role: activeRole,
-            timestamp: Math.floor(Date.now() / 1000),
-          }));
+          const stat = fs.statSync(data.transcript_path);
+          const estimatedTokens = Math.round(stat.size * 0.25);
+          if (estimatedTokens > 0) {
+            usedPct = Math.max(0, Math.min(100, Math.round((estimatedTokens / 200000) * 100)));
+          }
         } catch (_) { /* ignore */ }
       }
+    }
+
+    // Write bridge file for downstream hooks (suggest-compact, context-monitor)
+    if (usedPct != null && session) {
+      try {
+        const bridgePath = path.join(os.tmpdir(), `harness-ctx-${session}.json`);
+        fs.writeFileSync(bridgePath, JSON.stringify({
+          session_id: session,
+          remaining_percentage: remaining != null ? remaining : null,
+          used_pct: usedPct,
+          active_role: activeRole,
+          timestamp: Math.floor(Date.now() / 1000),
+        }));
+      } catch (_) { /* ignore */ }
+    }
 
-      // Build progress bar (10 segments)
+    // Build progress bar (10 segments)
+    if (usedPct != null) {
       const filled = Math.floor(usedPct / 10);
       const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
       if (usedPct < 50) {

package/hooks/hooks.json

@@ -68,6 +68,17 @@
         "description": "Doc file warning: warn about non-standard documentation files (exit code 0; warns only)",
         "id": "pre:write:doc-file-warning"
       },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/harness-statusline.js\""
+          }
+        ],
+        "description": "Display current role and context usage statusline (must run before strategic-compact to write bridge file)",
+        "id": "pre:all:harness-statusline"
+      },
       {
         "matcher": "*",
         "hooks": [
@@ -77,7 +88,7 @@
             "timeout": 10
           }
         ],
-        "description": "Suggest strategic context compaction when context usage crosses 70/85/95% thresholds",
+        "description": "Suggest strategic context compaction when context usage crosses 65/70/85/95% thresholds",
         "id": "pre:all:strategic-compact"
       },
       {
@@ -152,28 +163,6 @@
         "description": "Check MCP server health before MCP tool execution and block unhealthy MCP calls",
         "id": "pre:mcp-health-check"
       },
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/harness-statusline.js\""
-          }
-        ],
-        "description": "Display current role and context usage statusline",
-        "id": "pre:all:harness-statusline"
-      },
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/harness-context-monitor.js\""
-          }
-        ],
-        "description": "Monitor context budget, warn at 35%/25% thresholds",
-        "id": "pre:all:harness-context-monitor"
-      },
       {
         "matcher": "Bash",
         "hooks": [
@@ -234,6 +223,17 @@
         "description": "Load previous context and detect package manager on new session",
         "id": "session:start"
       },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/session-start-goal-resume.js\""
+          }
+        ],
+        "description": "Check for active goals from previous sessions and inject resume reminder",
+        "id": "session:goal-resume"
+      },
       {
         "matcher": "*",
         "hooks": [