@colin4k1024/tsp 2.5.1 → 2.5.2

package/scripts/lib/wave-cost-advisor.js

@@ -0,0 +1,155 @@
+'use strict';
+
+/**
+ * wave-cost-advisor.js
+ *
+ * Budget-aware wave scheduling for Loop Engineering.
+ * Calculates optimal parallelism based on remaining budget, estimated costs,
+ * and worker availability before launching a wave.
+ *
+ * Integrates with wave-execution skill and the workflow executor.
+ */
+
+const DEFAULT_COST_PER_WORKER = 0.50; // USD per worker iteration (conservative estimate)
+const DEFAULT_MAX_PARALLEL = 4;
+const DEFAULT_BUDGET = 10.0; // USD
+
+function createCostAdvisor(options = {}) {
+  const totalBudget = options.totalBudget || DEFAULT_BUDGET;
+  let spent = options.spent || 0;
+  const maxParallel = options.maxParallel || DEFAULT_MAX_PARALLEL;
+  const costPerWorker = options.costPerWorker || DEFAULT_COST_PER_WORKER;
+
+  return {
+    get remaining() { return totalBudget - spent; },
+    get spent() { return spent; },
+    get totalBudget() { return totalBudget; },
+
+    recordSpend(amount) {
+      spent += amount;
+    },
+
+    adviseBatchSize(taskCount, options = {}) {
+      const estimatedIterations = options.estimatedIterations || 1;
+      const taskCost = options.costPerTask || costPerWorker;
+      const maxWorkers = Math.min(taskCount, maxParallel);
+
+      if (spent >= totalBudget) {
+        return {
+          recommended: 0,
+          reason: 'budget_exhausted',
+          remaining: 0,
+          canAfford: 0,
+        };
+      }
+
+      const remaining = totalBudget - spent;
+      const costPerBatch = maxWorkers * taskCost * estimatedIterations;
+
+      if (costPerBatch <= remaining) {
+        return {
+          recommended: maxWorkers,
+          reason: 'within_budget',
+          remaining,
+          estimatedCost: costPerBatch,
+          canAfford: maxWorkers,
+        };
+      }
+
+      // Reduce parallelism to fit budget
+      const affordableWorkers = Math.max(1, Math.floor(remaining / (taskCost * estimatedIterations)));
+      const actualWorkers = Math.min(affordableWorkers, taskCount);
+
+      return {
+        recommended: actualWorkers,
+        reason: 'budget_constrained',
+        remaining,
+        estimatedCost: actualWorkers * taskCost * estimatedIterations,
+        canAfford: affordableWorkers,
+        requestedButDenied: maxWorkers - actualWorkers,
+      };
+    },
+
+    adviseWavePlan(waves, options = {}) {
+      const taskCost = options.costPerTask || costPerWorker;
+      const plan = [];
+      let projectedSpend = spent;
+
+      for (let i = 0; i < waves.length; i++) {
+        const wave = waves[i];
+        const taskCount = Array.isArray(wave) ? wave.length : wave.taskCount || 1;
+        const remaining = totalBudget - projectedSpend;
+
+        if (remaining <= 0) {
+          plan.push({
+            waveIndex: i,
+            status: 'deferred',
+            reason: 'budget_exhausted',
+            tasks: taskCount,
+            parallelism: 0,
+          });
+          continue;
+        }
+
+        const maxForWave = Math.min(taskCount, maxParallel);
+        const waveCost = maxForWave * taskCost;
+
+        if (waveCost <= remaining) {
+          plan.push({
+            waveIndex: i,
+            status: 'full',
+            tasks: taskCount,
+            parallelism: maxForWave,
+            estimatedCost: waveCost,
+          });
+          projectedSpend += waveCost;
+        } else {
+          const affordable = Math.max(1, Math.floor(remaining / taskCost));
+          const actual = Math.min(affordable, taskCount);
+          plan.push({
+            waveIndex: i,
+            status: 'reduced',
+            tasks: taskCount,
+            parallelism: actual,
+            estimatedCost: actual * taskCost,
+            note: `Reduced from ${maxForWave} to ${actual} workers due to budget`,
+          });
+          projectedSpend += actual * taskCost;
+        }
+      }
+
+      return {
+        plan,
+        projectedTotalCost: projectedSpend,
+        remainingAfterPlan: totalBudget - projectedSpend,
+        budgetUtilization: projectedSpend / totalBudget,
+      };
+    },
+
+    shouldPause() {
+      return spent >= totalBudget;
+    },
+
+    formatSummary() {
+      const pct = ((spent / totalBudget) * 100).toFixed(1);
+      return `Budget: $${spent.toFixed(2)} / $${totalBudget.toFixed(2)} (${pct}% used), $${(totalBudget - spent).toFixed(2)} remaining`;
+    },
+  };
+}
+
+function estimateGoalCost(goal, averageCostPerIteration) {
+  const remainingIterations = (goal.budget?.maxIterations || 15) - (goal.currentIteration || 0);
+  const avgCost = averageCostPerIteration || DEFAULT_COST_PER_WORKER;
+  return {
+    bestCase: avgCost,
+    expectedCase: avgCost * Math.min(3, remainingIterations),
+    worstCase: avgCost * remainingIterations,
+  };
+}
+
+module.exports = {
+  DEFAULT_COST_PER_WORKER,
+  DEFAULT_MAX_PARALLEL,
+  createCostAdvisor,
+  estimateGoalCost,
+};

package/skills/goal-convergence/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: goal-convergence
+description: "Goal-oriented autonomous loop with external completion oracle. Keeps iterating until verifiable stopping conditions are met, checked by a separate model."
+origin: ECC
+---
+
+# Goal Convergence
+
+Goal-oriented autonomous loop with external completion oracle.
+Based on Addy Osmani's Loop Engineering principle: "Keep going until a verifiable
+stopping condition holds, with a separate small model checking completion."
+
+## When to Activate
+
+- User invokes `/goal` command
+- Heartbeat auto-creates a goal from scan failures
+- Triage item is promoted to a goal via `/triage act <id> goal`
+- Session resumes with an active goal state file
+
+## Core Concept: Maker-Oracle Separation
+
+The model that wrote the code is too nice grading its own homework.
+A second model (the oracle) with different instructions and READ-ONLY tools
+catches what the first talked itself into.
+
+```
+Maker (primary model, full tools)
+  │
+  ▼ produces iteration output
+  │
+Oracle (different model, read-only)
+  │
+  ├─ ALL conditions pass → CONVERGE (goal done)
+  ├─ Some fail + budget remains → nextHint → LOOP (maker iterates)
+  └─ Budget exhausted → ESCALATE (triage inbox)
+```
+
+## Goal Lifecycle
+
+```
+CREATE → ACTIVE → [iterate] → CONVERGED
+                       │
+                       ├──── PAUSED (manual /goal pause)
+                       └──── ESCALATED (budget exhausted or repeated failure)
+```
+
+States:
+- `active`: Maker-oracle loop is running
+- `paused`: Manually paused, resumes with `/goal resume`
+- `converged`: All stopping conditions met, goal complete
+- `escalated`: Cannot converge within budget, needs human triage
+- `failed`: Explicitly abandoned
+
+## Stopping Conditions
+
+Each goal has one or more stopping conditions. ALL must pass for convergence.
+
+| Type | Command Pattern | Example |
+|------|----------------|---------|
+| `test_pass` | Test runner exits 0 | `npm test` |
+| `lint_clean` | Linter exits 0 | `npm run lint -- --quiet` |
+| `coverage_threshold` | Coverage >= N% | `npm test -- --coverage` |
+| `build_pass` | Build succeeds | `npm run build` |
+| `custom_command` | Any command exits 0 | `grep -r "TODO" src/ \| wc -l` |
+
+## Oracle Protocol
+
+The oracle receives:
+1. The goal objective (natural language)
+2. All stopping condition commands and their latest output
+3. The maker's iteration summary
+4. Previous iteration history (last 3)
+
+The oracle returns:
+```json
+{
+  "converged": false,
+  "conditionResults": [
+    {"type": "test_pass", "passed": false, "output": "2 tests failing"},
+    {"type": "lint_clean", "passed": true, "output": ""}
+  ],
+  "reasons": ["2 tests still failing in auth module"],
+  "nextHint": "Focus on src/auth/refresh.test.ts — the token expiry mock is stale",
+  "confidence": 0.85
+}
+```
+
+## Budget Management
+
+Three budget dimensions, any exhaustion triggers escalation:
+
+| Dimension | Default | Rationale |
+|-----------|---------|-----------|
+| Iterations | 15 | Prevents infinite loops |
+| Wall time | 2h | Bounds real-world duration |
+| Cost (USD) | $10 | Prevents runaway API spend |
+
+On escalation, the goal:
+1. Persists full state to `~/.claude/goals/{goalId}.json`
+2. Creates a triage inbox item with context
+3. Marks state as `escalated`
+4. Reports final status to user
+
+## Inter-Session Persistence
+
+Goals survive session restarts:
+1. `SessionEnd` hook serializes active goals
+2. `SessionStart` hook detects active goals and notifies user
+3. `/goal resume` re-enters the loop with oracle's last `nextHint`
+
+State file: `~/.claude/goals/{goalId}.json` (follows `schemas/goal.schema.json`)
+
+## Integration Points
+
+- **`/heartbeat`**: Auto-creates goals from scan failures
+- **`/triage`**: Escalated goals land in triage; triage items can become goals
+- **`/checkpoint`**: Each iteration implicitly checkpoints
+- **`/verify`**: Oracle internally uses verification patterns
+- **`wave-execution`**: Multiple goals can run in parallel waves
+- **`rework-loop`**: Failed iterations trigger blame-attributed rework
+
+## Hard Bans
+
+- Oracle MUST be a different model than maker (eliminates self-grading bias)
+- Oracle MUST NOT have write tools (prevents it from "helping" fix issues)
+- Goals MUST have at least one stopping condition (no open-ended loops)
+- Budget MUST have at least one limit set (no unbounded execution)
+- State MUST persist to disk (no goals lost on crash)
+
+## Example
+
+```
+User: /goal "make all tests pass"
+
+System infers:
+  objective: "make all tests pass"
+  stoppingConditions: [{type: "test_pass", command: "npm test"}]
+  budget: {maxIterations: 15, maxDuration: "2h", maxDollars: 10}
+  oracle: {model: "haiku"}
+
+Iteration 1:
+  Maker: reads test output, fixes obvious import error in auth.ts
+  Oracle: runs `npm test` → 1 test still failing → {converged: false, nextHint: "..."}
+
+Iteration 2:
+  Maker: fixes token refresh logic based on oracle hint
+  Oracle: runs `npm test` → all pass → {converged: true}
+
+Result: CONVERGED in 2 iterations, $0.45 spent
+```

package/skills/goframe-v2/examples/practices/quick-demo/manifest/config/config.yaml

@@ -1,15 +1,15 @@
-# https://goframe.org/docs/web/server-config-file-template
-server:
-  address:     ":8000"
-  openapiPath: "/api.json"
-  swaggerPath: "/swagger"
-
-# https://goframe.org/docs/core/glog-config
-logger:
-  level : "all"
-  stdout: true
-
-# https://goframe.org/docs/core/gdb-config-file
-database:
-  default:
+# https://goframe.org/docs/web/server-config-file-template
+server:
+  address:     ":8000"
+  openapiPath: "/api.json"
+  swaggerPath: "/swagger"
+
+# https://goframe.org/docs/core/glog-config
+logger:
+  level : "all"
+  stdout: true
+
+# https://goframe.org/docs/core/gdb-config-file
+database:
+  default:
     link: "mysql:root:12345678@tcp(127.0.0.1:3306)/test"

package/skills/loop-heartbeat/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: loop-heartbeat
+description: "Scheduled discovery automation that runs scans on a heartbeat interval, classifies findings, and routes them to goals or triage inbox."
+origin: ECC
+---
+
+# Loop Heartbeat
+
+Scheduled discovery automation that runs scans, finds issues, and routes findings
+to goals or triage. The heartbeat is what makes a loop a loop — not a one-shot run.
+
+Based on Addy Osmani's Loop Engineering: "Automations are the thing that makes
+a loop an actual loop. Run prompts on a schedule. Findings go to a triage inbox;
+empty runs archive themselves."
+
+## When to Activate
+
+- User invokes `/heartbeat start` to begin scheduled scans
+- User invokes `/heartbeat run` for a one-shot scan
+- A goal converges and follow-up scanning is needed
+- Project onboarding includes quality monitoring setup
+
+## Core Concept
+
+The heartbeat is the "discovery layer" of a loop. It answers: "What's broken right
+now?" on a recurring basis without human prompting.
+
+```
+Every 30 minutes:
+  ┌─ Run test suite ─── PASS → skip
+  ├─ Run linter ─────── FAIL → create goal (auto-fix)
+  ├─ Audit deps ─────── FAIL → triage inbox (human decision)
+  └─ Type check ─────── PASS → skip
+```
+
+## Configuration
+
+Create `.claude/heartbeat.yaml` in the project root:
+
+```yaml
+heartbeat:
+  interval: "30m"
+  scans:
+    - name: "test-health"
+      command: "npm test 2>&1 | tail -10"
+      onFailure: "auto-goal"
+      description: "Test suite health"
+    - name: "lint-drift"
+      command: "npm run lint -- --quiet 2>&1 | wc -l"
+      threshold: 0
+      onFailure: "triage"
+      description: "Lint error count"
+    - name: "type-check"
+      command: "npx tsc --noEmit 2>&1; echo EXIT:$?"
+      onFailure: "auto-goal"
+      description: "TypeScript type errors"
+  budget:
+    maxDollarsPerHour: 2.0
+    pauseOnExhaust: true
+```
+
+## Scan Result Classification
+
+| onFailure | Behavior | Use When |
+|-----------|----------|----------|
+| `auto-goal` | Creates `/goal` automatically | Machine can fix it (tests, lint, types) |
+| `triage` | Adds to `/triage` inbox | Human judgment needed (deps, security) |
+| `notify` | Desktop notification only | Informational, no action required |
+| `ignore` | Log silently | Monitoring only, aggregate later |
+
+## Budget Controls
+
+- `maxDollarsPerHour`: Pause heartbeat if scanning costs exceed this
+- `pauseOnExhaust`: If true, pause (resumable); if false, stop entirely
+- Goal creation inherits the default goal budget from `/goal` settings
+
+## Empty Run Handling
+
+When all scans pass:
+- No goals or triage items are created
+- Run is logged to `~/.claude/heartbeat-last-run.json`
+- Next run proceeds on schedule
+- This is the "archive themselves silently" behavior
+
+## Integration Points
+
+- **`/goal`**: `auto-goal` failures create goals via completion-oracle.js
+- **`/triage`**: `triage` failures append to `~/.claude/triage/inbox.jsonl`
+- **CronCreate**: Scheduling uses the Claude Code CronCreate primitive
+- **ScheduleWakeup**: Alternative for dynamic-interval loops
+- **Hooks**: Runs as a scheduled task, not a synchronous hook
+
+## Hard Bans
+
+- Heartbeat MUST NOT modify code (it's discovery-only)
+- Heartbeat MUST NOT create goals without a stopping condition
+- Budget limits MUST be enforced (no unbounded scan spending)
+- Failed scans MUST be classified (no silent failures)
+- Empty runs MUST NOT create noise (pass = skip)
+
+## Example Session
+
+```
+User: /heartbeat start
+
+System:
+  Loaded .claude/heartbeat.yaml (3 scans configured)
+  Registered CronCreate: every 30m
+  Next run: 30m from now
+  Budget: $2.00/hour
+
+[30 minutes later, heartbeat fires]
+
+Scan results:
+  ✓ test-health: all tests pass
+  ✗ lint-drift: 4 lint errors found → created goal-a1b2c3d4
+  ✓ type-check: no type errors
+
+Summary: 2/3 scans passed, 1 goal created
+```

package/skills/mcp-connector-bridge/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: mcp-connector-bridge
+description: "Active MCP connector polling that integrates external tools (issue trackers, error monitoring, CI) into the heartbeat loop for cross-system discovery."
+origin: ECC
+---
+
+# MCP Connector Bridge
+
+Active MCP connector polling that integrates external tools into the heartbeat loop.
+The difference between an agent that says "here is the fix" vs a loop that opens
+the PR, links the ticket, and pings the channel — by itself.
+
+## When to Activate
+
+- User configures `.claude/connectors.yaml` with active MCP servers
+- Heartbeat scheduler includes connector-based scans
+- User invokes `/heartbeat start` with connector scans configured
+- External event triggers a connector poll
+
+## Core Concept
+
+MCP connectors let the loop touch real tools: issue trackers, error monitoring,
+databases, CI systems, chat platforms. Without connectors, the loop is isolated
+to the local repo. With connectors, it can discover issues from anywhere.
+
+```
+Heartbeat tick
+  │
+  ├─ Local scans (test, lint, type-check)
+  │
+  └─ Connector scans (MCP servers)
+       ├─ GitHub: "List open issues assigned to me"
+       ├─ Sentry: "List unresolved errors in last 24h"
+       └─ Linear: "List my in-progress tasks stale >7d"
+```
+
+## Configuration
+
+Create `.claude/connectors.yaml`:
+
+```yaml
+connectors:
+  - name: "github-issues"
+    server: "github"
+    heartbeatScan: "List open issues assigned to me with label:bug"
+    triageOnNew: true
+    priority: "medium"
+
+  - name: "sentry-errors"
+    server: "sentry"
+    heartbeatScan: "List unresolved errors from last 24 hours"
+    triageOnNew: true
+    priority: "high"
+
+  - name: "linear-tasks"
+    server: "linear"
+    heartbeatScan: "List my in-progress tasks not updated in 7 days"
+    autoGoalOnStale: "7d"
+    priority: "low"
+
+  - name: "slack-mentions"
+    server: "slack"
+    heartbeatScan: "Check unread mentions in engineering channel"
+    triageOnNew: true
+    priority: "low"
+```
+
+## Connector Scan Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique connector identifier |
+| `server` | Yes | MCP server name (must be configured in mcp-configs/) |
+| `heartbeatScan` | Yes | Prompt to send to the MCP server |
+| `triageOnNew` | No | Create triage items for new findings |
+| `autoGoalOnStale` | No | Auto-create goal if stale beyond duration |
+| `priority` | No | Default severity for triage items (high/medium/low) |
+| `enabled` | No | Disable without removing (default: true) |
+
+## Health Check
+
+Before polling, verify connector is reachable:
+
+1. Check MCP server is configured in project MCP settings
+2. Verify server responds to basic query
+3. If unreachable: skip this connector, log warning
+4. If reachable: execute heartbeatScan prompt
+
+Builds on existing `pre:mcp-health-check` hook.
+
+## Result Classification
+
+Connector scan results follow the same classification as local scans:
+
+| Finding | Action |
+|---------|--------|
+| New issue discovered | → Triage item (if `triageOnNew: true`) |
+| Stale task detected | → Auto-goal (if `autoGoalOnStale` configured) |
+| No new findings | → Skip silently |
+| Connection failed | → Log warning, skip |
+
+## Integration Points
+
+- **`/heartbeat`**: Connector scans run alongside local scans during each tick
+- **`/triage`**: New connector findings populate the triage inbox
+- **`/goal`**: Stale task connectors can auto-create goals
+- **`mcp-configs/`**: Connector references must match configured MCP servers
+- **MCP health hook**: Validates connectivity before scan
+
+## Hard Bans
+
+- Connectors MUST NOT write to external systems during discovery (read-only scans)
+- Failed connections MUST NOT block local heartbeat scans
+- Connector output MUST be size-limited (prevent token overflow from large responses)
+- Credentials MUST NOT be stored in connectors.yaml (use MCP server config)
+- Polling frequency MUST respect rate limits of external services
+
+## Example Flow
+
+```
+Heartbeat tick (every 30m):
+  Local scans: ✓ tests pass, ✓ lint clean
+  Connector scans:
+    github-issues: Found 2 new bugs → triage inbox
+    sentry-errors: No new errors → skip
+    linear-tasks: 1 task stale 10 days → auto-goal created
+
+Result:
+  2 triage items created from GitHub
+  1 goal created from Linear stale task
+  Total: 3 actions from this tick
+```