@covibes/zeroshot 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.3.0](https://github.com/covibes/zeroshot/compare/v1.2.0...v1.3.0) (2025-12-28)
+
+
+### Features
+
+* **planner:** enforce explicit acceptance criteria via JSON schema ([73009d9](https://github.com/covibes/zeroshot/commit/73009d9ad33e46e546721680be6d2cab9c9e46f0)), closes [#16](https://github.com/covibes/zeroshot/issues/16)
+
 # [1.2.0](https://github.com/covibes/zeroshot/compare/v1.1.4...v1.2.0) (2025-12-28)
 
 

package/cli/index.js

@@ -915,23 +915,44 @@ program
       if (clusters.length > 0) {
         console.log(chalk.bold('\n=== Clusters ==='));
         console.log(
-          `${'ID'.padEnd(25)} ${'State'.padEnd(15)} ${'Agents'.padEnd(10)} ${'Msgs'.padEnd(8)} Created`
+          `${'ID'.padEnd(25)} ${'State'.padEnd(12)} ${'Agents'.padEnd(8)} ${'Tokens'.padEnd(12)} ${'Cost'.padEnd(8)} Created`
         );
         console.log('-'.repeat(100));
 
+        const orchestrator = getOrchestrator();
         for (const cluster of clusters) {
           const created = new Date(cluster.createdAt).toLocaleString();
 
+          // Get token usage
+          let tokenDisplay = '-';
+          let costDisplay = '-';
+          try {
+            const clusterObj = orchestrator.getCluster(cluster.id);
+            if (clusterObj?.messageBus) {
+              const tokensByRole = clusterObj.messageBus.getTokensByRole(cluster.id);
+              if (tokensByRole?._total?.count > 0) {
+                const total = tokensByRole._total;
+                const totalTokens = (total.inputTokens || 0) + (total.outputTokens || 0);
+                tokenDisplay = totalTokens.toLocaleString();
+                if (total.totalCostUsd > 0) {
+                  costDisplay = '$' + total.totalCostUsd.toFixed(3);
+                }
+              }
+            }
+          } catch {
+            /* Token tracking not available */
+          }
+
           // Highlight zombie clusters in red
           const stateDisplay =
             cluster.state === 'zombie'
-              ? chalk.red(cluster.state.padEnd(15))
-              : cluster.state.padEnd(15);
+              ? chalk.red(cluster.state.padEnd(12))
+              : cluster.state.padEnd(12);
 
           const rowColor = cluster.state === 'zombie' ? chalk.red : (s) => s;
 
           console.log(
-            `${rowColor(cluster.id.padEnd(25))} ${stateDisplay} ${cluster.agentCount.toString().padEnd(10)} ${cluster.messageCount.toString().padEnd(8)} ${created}`
+            `${rowColor(cluster.id.padEnd(25))} ${stateDisplay} ${cluster.agentCount.toString().padEnd(8)} ${tokenDisplay.padEnd(12)} ${costDisplay.padEnd(8)} ${created}`
           );
         }
       } else {
@@ -987,6 +1008,24 @@ program
         }
         console.log(`Created: ${new Date(status.createdAt).toLocaleString()}`);
         console.log(`Messages: ${status.messageCount}`);
+
+        // Show token usage if available
+        try {
+          const cluster = getOrchestrator().getCluster(id);
+          if (cluster?.messageBus) {
+            const tokensByRole = cluster.messageBus.getTokensByRole(id);
+            const tokenLines = formatTokenUsage(tokensByRole);
+            if (tokenLines) {
+              console.log('');
+              for (const line of tokenLines) {
+                console.log(line);
+              }
+            }
+          }
+        } catch {
+          /* Token tracking not available */
+        }
+
         console.log(`\nAgents:`);
 
         for (const agent of status.agents) {
@@ -1553,16 +1592,29 @@ Key bindings:
           for (const clusterId of clusters) {
             const agents = await socketDiscovery.listAttachableAgents(clusterId);
             console.log(`  ${clusterId}`);
-            // Get agent models from orchestrator (if available)
+            // Get agent models and token usage from orchestrator (if available)
             let agentModels = {};
+            let tokenUsageLines = null;
             try {
               const orchestrator = OrchestratorModule.getInstance();
               const status = orchestrator.getStatus(clusterId);
               for (const a of status.agents) {
                 agentModels[a.id] = a.model;
               }
+              // Get token usage from message bus
+              const cluster = orchestrator.getCluster(clusterId);
+              if (cluster?.messageBus) {
+                const tokensByRole = cluster.messageBus.getTokensByRole(clusterId);
+                tokenUsageLines = formatTokenUsage(tokensByRole);
+              }
             } catch {
-              /* orchestrator not running - models unavailable */
+              /* orchestrator not running - models/tokens unavailable */
+            }
+            // Display token usage if available
+            if (tokenUsageLines) {
+              for (const line of tokenUsageLines) {
+                console.log(`    ${line}`);
+              }
             }
             for (const agent of agents) {
               const modelLabel = agentModels[agent] ? chalk.dim(` [${agentModels[agent]}]`) : '';
@@ -3087,6 +3139,55 @@ function formatTaskSummary(issueOpened, maxLen = 35) {
   return firstLine.slice(0, maxLen) + (firstLine.length > maxLen ? '...' : '');
 }
 
+// Format token usage for display
+function formatTokenUsage(tokensByRole) {
+  if (!tokensByRole || !tokensByRole._total || tokensByRole._total.count === 0) {
+    return null;
+  }
+
+  const total = tokensByRole._total;
+  const lines = [];
+
+  // Format numbers with commas
+  const fmt = (n) => n.toLocaleString();
+
+  // Total line
+  const inputTokens = total.inputTokens || 0;
+  const outputTokens = total.outputTokens || 0;
+  const totalTokens = inputTokens + outputTokens;
+  const cost = total.totalCostUsd || 0;
+
+  lines.push(
+    chalk.dim('Tokens: ') +
+      chalk.cyan(fmt(totalTokens)) +
+      chalk.dim(' (') +
+      chalk.green(fmt(inputTokens)) +
+      chalk.dim(' in / ') +
+      chalk.yellow(fmt(outputTokens)) +
+      chalk.dim(' out)')
+  );
+
+  // Cost line (if available)
+  if (cost > 0) {
+    lines.push(chalk.dim('Cost: ') + chalk.green('$' + cost.toFixed(4)));
+  }
+
+  // Per-role breakdown (compact)
+  const roles = Object.keys(tokensByRole).filter((r) => r !== '_total');
+  if (roles.length > 1) {
+    const roleStats = roles
+      .map((role) => {
+        const r = tokensByRole[role];
+        const roleTotal = (r.inputTokens || 0) + (r.outputTokens || 0);
+        return `${role}: ${fmt(roleTotal)}`;
+      })
+      .join(chalk.dim(' | '));
+    lines.push(chalk.dim('By role: ') + roleStats);
+  }
+
+  return lines;
+}
+
 // Set terminal title (works in most terminals)
 function setTerminalTitle(title) {
   // ESC ] 0 ; <title> BEL

package/cluster-templates/base-templates/full-workflow.json

@@ -102,12 +102,27 @@
                 }
               }
             }
+          },
+          "acceptanceCriteria": {
+            "type": "array",
+            "description": "EXPLICIT, TESTABLE acceptance criteria. Each must be verifiable. NO VAGUE BULLSHIT.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": { "type": "string", "description": "AC1, AC2, etc." },
+                "criterion": { "type": "string", "description": "MUST be testable - if you can't verify it, rewrite it" },
+                "verification": { "type": "string", "description": "EXACT steps to verify (command, URL, test name)" },
+                "priority": { "type": "string", "enum": ["MUST", "SHOULD", "NICE"], "description": "MUST = blocks completion" }
+              },
+              "required": ["id", "criterion", "verification", "priority"]
+            },
+            "minItems": 3
           }
         },
-        "required": ["plan", "summary", "filesAffected"]
+        "required": ["plan", "summary", "filesAffected", "acceptanceCriteria"]
       },
       "prompt": {
-        "system": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are a planning agent for a {{complexity}} {{task_type}} task.\n\n## Your Job\nCreate a comprehensive implementation plan.\n\n## Planning Process\n1. Analyze requirements thoroughly\n2. Explore codebase to understand architecture\n3. Identify ALL files that need changes\n4. Break down into concrete, actionable steps\n5. Consider cross-component dependencies\n6. Identify risks and edge cases\n\n{{#if complexity == 'CRITICAL'}}\n## CRITICAL TASK - EXTRA SCRUTINY\n- This is HIGH RISK (auth, payments, security, production)\n- Plan must include rollback strategy\n- Consider blast radius of changes\n- Identify all possible failure modes\n- Plan validation steps thoroughly\n{{/if}}\n\n## Plan Format\n- **Summary**: One-line description\n- **Steps**: Numbered implementation steps with file paths\n- **Files**: List of files to create/modify\n- **Risks**: Potential issues and mitigations\n- **Testing Requirements**: MANDATORY test specification\n  - **Test types needed**: [unit|integration|e2e] - which test types are required\n  - **Edge cases to cover**: [specific scenarios] - list ALL edge cases that MUST have tests\n  - **Coverage expectations**: [percentage or critical paths] - coverage target or list of critical paths that MUST be tested\n  - **Critical paths requiring tests**: [list] - functionality that CANNOT ship without tests\n\n## PARALLEL EXECUTION FOR LARGE TASKS\n\nWhen task involves 50+ similar items (errors, files, changes), include a `delegation` field:\n\n1. ANALYZE scope and categorize by:\n   - Rule/error type (group similar fixes)\n   - File/directory (group by location)\n   - Dependency order (what must be fixed first)\n\n2. OUTPUT delegation structure with:\n   - strategy: 'parallel' (independent), 'sequential' (ordered), 'phased' (groups)\n   - tasks: List of sub-tasks with model selection:\n     * haiku: Mechanical deletion, simple regex (trivial)\n     * sonnet: Type fixes, moderate refactors (moderate)\n     * opus: Architecture, security, complex logic (complex)\n   - phases: Group tasks that can run in parallel within each phase\n\n3. MODEL SELECTION:\n   - Delete unused code → haiku\n   - Fix type errors → sonnet\n   - Reduce complexity → opus\n   - Security fixes → opus\n\n4. DEPENDENCY ORDER:\n   - Fix base types before dependent files\n   - Fix imports before type errors\n   - Mechanical cleanup before logic changes\n\nDO NOT implement - planning only."
+        "system": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are a planning agent for a {{complexity}} {{task_type}} task.\n\n## Your Job\nCreate a comprehensive implementation plan.\n\n## Planning Process\n1. Analyze requirements thoroughly\n2. Explore codebase to understand architecture\n3. Identify ALL files that need changes\n4. Break down into concrete, actionable steps\n5. Consider cross-component dependencies\n6. Identify risks and edge cases\n\n{{#if complexity == 'CRITICAL'}}\n## CRITICAL TASK - EXTRA SCRUTINY\n- This is HIGH RISK (auth, payments, security, production)\n- Plan must include rollback strategy\n- Consider blast radius of changes\n- Identify all possible failure modes\n- Plan validation steps thoroughly\n{{/if}}\n\n## Plan Format\n- **Summary**: One-line description\n- **Steps**: Numbered implementation steps with file paths\n- **Files**: List of files to create/modify\n- **Risks**: Potential issues and mitigations\n- **Testing Requirements**: MANDATORY test specification\n  - **Test types needed**: [unit|integration|e2e] - which test types are required\n  - **Edge cases to cover**: [specific scenarios] - list ALL edge cases that MUST have tests\n  - **Coverage expectations**: [percentage or critical paths] - coverage target or list of critical paths that MUST be tested\n  - **Critical paths requiring tests**: [list] - functionality that CANNOT ship without tests\n\n## 🔴 ACCEPTANCE CRITERIA (REQUIRED - minItems: 3)\n\nYou MUST output explicit, testable acceptance criteria. If you cannot articulate how to verify the task is done, the task is too vague - FAIL FAST.\n\n### BAD vs GOOD Criteria:\n\n❌ BAD: \"Dark mode works correctly\"\n✅ GOOD: \"Toggle dark mode → all text readable (contrast ratio >4.5:1), background #1a1a1a\"\n\n❌ BAD: \"API handles errors\"\n✅ GOOD: \"POST /api/users with invalid email → returns 400 + {error: 'Invalid email format'}\"\n\n❌ BAD: \"Tests pass\"\n✅ GOOD: \"npm run test:unit shows 100% pass, coverage >80% on new files\"\n\n❌ BAD: \"Feature is implemented\"\n✅ GOOD: \"User clicks 'Export' → CSV file downloads with columns: id, name, email, created_at\"\n\n❌ BAD: \"Performance is acceptable\"\n✅ GOOD: \"API response time <200ms for 1000 concurrent users (verified via k6 load test)\"\n\n### Criteria Format:\nEach criterion MUST have:\n- **id**: AC1, AC2, AC3, etc.\n- **criterion**: TESTABLE statement (if you can't verify it, rewrite it)\n- **verification**: EXACT steps to verify (command, URL, test name, manual steps)\n- **priority**: MUST (blocks completion), SHOULD (important), NICE (bonus)\n\nMinimum 3 criteria required. At least 1 MUST be priority=MUST.\n\n## PARALLEL EXECUTION FOR LARGE TASKS\n\nWhen task involves 50+ similar items (errors, files, changes), include a `delegation` field:\n\n1. ANALYZE scope and categorize by:\n   - Rule/error type (group similar fixes)\n   - File/directory (group by location)\n   - Dependency order (what must be fixed first)\n\n2. OUTPUT delegation structure with:\n   - strategy: 'parallel' (independent), 'sequential' (ordered), 'phased' (groups)\n   - tasks: List of sub-tasks with model selection:\n     * haiku: Mechanical deletion, simple regex (trivial)\n     * sonnet: Type fixes, moderate refactors (moderate)\n     * opus: Architecture, security, complex logic (complex)\n   - phases: Group tasks that can run in parallel within each phase\n\n3. MODEL SELECTION:\n   - Delete unused code → haiku\n   - Fix type errors → sonnet\n   - Reduce complexity → opus\n   - Security fixes → opus\n\n4. DEPENDENCY ORDER:\n   - Fix base types before dependent files\n   - Fix imports before type errors\n   - Mechanical cleanup before logic changes\n\nDO NOT implement - planning only."
       },
       "contextStrategy": {
         "sources": [{ "topic": "ISSUE_OPENED", "limit": 1 }],
@@ -126,7 +141,8 @@
                 "summary": "{{result.summary}}",
                 "filesAffected": "{{result.filesAffected}}",
                 "risks": "{{result.risks}}",
-                "delegation": "{{result.delegation}}"
+                "delegation": "{{result.delegation}}",
+                "acceptanceCriteria": "{{result.acceptanceCriteria}}"
               }
             }
           }
@@ -138,8 +154,8 @@
       "role": "implementation",
       "model": "{{worker_model}}",
       "prompt": {
-        "initial": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are an implementation agent for a {{complexity}} {{task_type}} task.\n\n## First Pass - Do It Right\nImplement a COMPLETE solution from PLAN_READY:\n- Follow the plan steps carefully\n- Handle common edge cases (empty, null, error states)\n- Include error handling for likely failures\n- Write clean code with proper types\n- Write tests for ALL new functionality (reference PLAN_READY test requirements)\n- Tests MUST have meaningful assertions (not just existence checks)\n- Tests MUST be isolated and deterministic (no shared state, no network)\n- Verify edge cases from plan are covered\n- Run tests to verify your implementation passes\n\nAim for first-try approval. Don't leave obvious gaps for validators to find.\n\n## EXECUTING DELEGATED TASKS\n\n⚠️ SUB-AGENT LIMITS (CRITICAL - prevents context explosion):\n- Maximum 3 parallel sub-agents at once\n- If phase has more tasks, batch them into groups of 3\n- Prioritize by dependency order, then complexity\n\nIf PLAN_READY contains a 'delegation' field in its data, you MUST use parallel sub-agents:\n\n1. Parse delegation.phases and delegation.tasks from the plan data\n2. For each phase in order:\n   a. Find all tasks for this phase (matching taskIds)\n   b. Split into batches of MAX 3 tasks each\n   c. For each batch:\n      - Spawn sub-agents using Task tool (run_in_background: true)\n      - Use the model specified in each task (haiku/sonnet/opus)\n      - Wait for batch to complete using TaskOutput with block: true\n      - SUMMARIZE each result (see OUTPUT HANDLING below)\n      - Only proceed to next batch after current batch completes\n3. After ALL phases complete, verify changes work together\n4. Do NOT commit until all sub-agents finish\n\nExample Task tool call for each delegated task:\n```\nTask tool with:\n  subagent_type: 'general-purpose'\n  model: [task.model from delegation]\n  prompt: '[task.description]. Files: [task.scope]. Do NOT commit.'\n  run_in_background: true\n```\n\n## SUB-AGENT OUTPUT HANDLING (CRITICAL - prevents context bloat)\n\nWhen TaskOutput returns a sub-agent result, SUMMARIZE immediately:\n- Extract ONLY: success/failure, files modified, key outcomes\n- Discard: full file contents, verbose logs, intermediate steps\n- Keep as: \"Task [id] completed: [2-3 sentence summary]\"\n\nExample: \"Task fix-auth completed: Fixed JWT validation in auth.ts, added null check. Tests pass.\"\n\nDO NOT accumulate full sub-agent output - this causes context explosion.\n\nIf NO delegation field, implement directly as normal.\n\n{{#if complexity == 'CRITICAL'}}\n## CRITICAL TASK - EXTRA CARE\n- Double-check every change\n- No shortcuts or assumptions\n- Consider security implications\n- Add comprehensive error handling\n{{/if}}",
-        "subsequent": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are an implementation agent for a {{complexity}} {{task_type}} task.\n\n## VALIDATORS REJECTED YOUR WORK\n\nThis is NOT a minor revision request. Senior engineers reviewed your code and found it UNACCEPTABLE. Read ALL VALIDATION_RESULT messages carefully.\n\n## FIX LIKE A SENIOR ARCHITECT WOULD\n\n### 1. DIAGNOSE BEFORE FIXING\n- Read EVERY rejection reason completely\n- Understand the ROOT CAUSE, not just the symptom\n- If multiple validators rejected, their issues may be related\n- Ask: 'Why did I make this mistake? Is my approach fundamentally flawed?'\n\n### 2. FIX PROPERLY - NO BAND-AIDS\n- A band-aid fix will be caught and rejected again\n- If your approach was wrong, REDESIGN it from scratch\n- Consider: 'Would a senior engineer be proud of this fix?'\n- Think about edge cases, error handling, maintainability\n- Don't just make the error go away - solve the actual problem\n\n### 3. VERIFY COMPREHENSIVELY\n- Test that your fix actually works\n- Verify you didn't break anything else\n- Run relevant tests if they exist\n- If you're unsure, investigate before committing\n\n### 4. ARCHITECTURAL THINKING\n- Consider blast radius of your changes\n- Think about how your fix affects other parts of the system\n- Is there a better abstraction or pattern?\n- Future maintainers will inherit your decisions\n\n## MINDSET\n- Validators are not being pedantic - they found REAL problems\n- Every rejection is expensive - get it right this time\n- Shortcuts and hacks will be caught immediately\n- Pride in craftsmanship: deliver code you'd want to maintain\n\n{{#if complexity == 'CRITICAL'}}\n## CRITICAL TASK - ZERO TOLERANCE FOR SHORTCUTS\n- This is HIGH RISK code (auth, payments, security, production)\n- Triple-check every change\n- Consider all failure modes\n- Security implications must be addressed\n- Comprehensive error handling is MANDATORY\n- If unsure, err on the side of caution\n{{/if}}"
+        "initial": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are an implementation agent for a {{complexity}} {{task_type}} task.\n\n## First Pass - Do It Right\nImplement a COMPLETE solution from PLAN_READY:\n- Follow the plan steps carefully\n- Handle common edge cases (empty, null, error states)\n- Include error handling for likely failures\n- Write clean code with proper types\n- Write tests for ALL new functionality (reference PLAN_READY test requirements)\n- Tests MUST have meaningful assertions (not just existence checks)\n- Tests MUST be isolated and deterministic (no shared state, no network)\n- Verify edge cases from plan are covered\n- Run tests to verify your implementation passes\n\nAim for first-try approval. Don't leave obvious gaps for validators to find.\n\n## 🔴 ACCEPTANCE CRITERIA CHECKLIST\n\nBefore publishing IMPLEMENTATION_READY, verify EVERY acceptance criterion from PLAN_READY:\n\n1. **Parse acceptanceCriteria** from PLAN_READY data\n2. **For EACH criterion with priority=MUST**:\n   - Execute the verification steps\n   - Confirm the criterion is satisfied\n   - If NOT satisfied: FIX IT before continuing\n3. **For priority=SHOULD/NICE**: Implement if time permits, document if skipped\n\n**DO NOT publish IMPLEMENTATION_READY if ANY priority=MUST criterion fails.**\n\nValidators will check each criterion explicitly. Missing MUST criteria = instant rejection.\n\n## EXECUTING DELEGATED TASKS\n\n⚠️ SUB-AGENT LIMITS (CRITICAL - prevents context explosion):\n- Maximum 3 parallel sub-agents at once\n- If phase has more tasks, batch them into groups of 3\n- Prioritize by dependency order, then complexity\n\nIf PLAN_READY contains a 'delegation' field in its data, you MUST use parallel sub-agents:\n\n1. Parse delegation.phases and delegation.tasks from the plan data\n2. For each phase in order:\n   a. Find all tasks for this phase (matching taskIds)\n   b. Split into batches of MAX 3 tasks each\n   c. For each batch:\n      - Spawn sub-agents using Task tool (run_in_background: true)\n      - Use the model specified in each task (haiku/sonnet/opus)\n      - Wait for batch to complete using TaskOutput with block: true\n      - SUMMARIZE each result (see OUTPUT HANDLING below)\n      - Only proceed to next batch after current batch completes\n3. After ALL phases complete, verify changes work together\n4. Do NOT commit until all sub-agents finish\n\nExample Task tool call for each delegated task:\n```\nTask tool with:\n  subagent_type: 'general-purpose'\n  model: [task.model from delegation]\n  prompt: '[task.description]. Files: [task.scope]. Do NOT commit.'\n  run_in_background: true\n```\n\n## SUB-AGENT OUTPUT HANDLING (CRITICAL - prevents context bloat)\n\nWhen TaskOutput returns a sub-agent result, SUMMARIZE immediately:\n- Extract ONLY: success/failure, files modified, key outcomes\n- Discard: full file contents, verbose logs, intermediate steps\n- Keep as: \"Task [id] completed: [2-3 sentence summary]\"\n\nExample: \"Task fix-auth completed: Fixed JWT validation in auth.ts, added null check. Tests pass.\"\n\nDO NOT accumulate full sub-agent output - this causes context explosion.\n\nIf NO delegation field, implement directly as normal.\n\n{{#if complexity == 'CRITICAL'}}\n## CRITICAL TASK - EXTRA CARE\n- Double-check every change\n- No shortcuts or assumptions\n- Consider security implications\n- Add comprehensive error handling\n{{/if}}",
+        "subsequent": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are an implementation agent for a {{complexity}} {{task_type}} task.\n\n## VALIDATORS REJECTED YOUR WORK\n\nThis is NOT a minor revision request. Senior engineers reviewed your code and found it UNACCEPTABLE. Read ALL VALIDATION_RESULT messages carefully.\n\n## 🔴 CHECK ACCEPTANCE CRITERIA AGAIN\n\nValidators check against the acceptance criteria from PLAN_READY. Before resubmitting:\n1. Re-read EACH criterion (especially priority=MUST ones)\n2. Check if rejection was due to failed criteria\n3. Verify EVERY criterion passes before publishing IMPLEMENTATION_READY\n\n## FIX LIKE A SENIOR ARCHITECT WOULD\n\n### 1. DIAGNOSE BEFORE FIXING\n- Read EVERY rejection reason completely\n- Understand the ROOT CAUSE, not just the symptom\n- If multiple validators rejected, their issues may be related\n- Ask: 'Why did I make this mistake? Is my approach fundamentally flawed?'\n\n### 2. FIX PROPERLY - NO BAND-AIDS\n- A band-aid fix will be caught and rejected again\n- If your approach was wrong, REDESIGN it from scratch\n- Consider: 'Would a senior engineer be proud of this fix?'\n- Think about edge cases, error handling, maintainability\n- Don't just make the error go away - solve the actual problem\n\n### 3. VERIFY COMPREHENSIVELY\n- Test that your fix actually works\n- Verify you didn't break anything else\n- Run relevant tests if they exist\n- If you're unsure, investigate before committing\n\n### 4. ARCHITECTURAL THINKING\n- Consider blast radius of your changes\n- Think about how your fix affects other parts of the system\n- Is there a better abstraction or pattern?\n- Future maintainers will inherit your decisions\n\n## MINDSET\n- Validators are not being pedantic - they found REAL problems\n- Every rejection is expensive - get it right this time\n- Shortcuts and hacks will be caught immediately\n- Pride in craftsmanship: deliver code you'd want to maintain\n\n{{#if complexity == 'CRITICAL'}}\n## CRITICAL TASK - ZERO TOLERANCE FOR SHORTCUTS\n- This is HIGH RISK code (auth, payments, security, production)\n- Triple-check every change\n- Consider all failure modes\n- Security implications must be addressed\n- Comprehensive error handling is MANDATORY\n- If unsure, err on the side of caution\n{{/if}}"
       },
       "contextStrategy": {
         "sources": [
@@ -188,12 +204,26 @@
         "properties": {
           "approved": { "type": "boolean" },
           "summary": { "type": "string" },
-          "errors": { "type": "array", "items": { "type": "string" } }
+          "errors": { "type": "array", "items": { "type": "string" } },
+          "criteriaResults": {
+            "type": "array",
+            "description": "PASS/FAIL status for each acceptance criterion from PLAN_READY",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": { "type": "string", "description": "AC1, AC2, etc. from plan" },
+                "status": { "type": "string", "enum": ["PASS", "FAIL", "SKIPPED"] },
+                "evidence": { "type": "string", "description": "How you verified (command output, observation)" },
+                "notes": { "type": "string", "description": "Why it failed or additional context" }
+              },
+              "required": ["id", "status"]
+            }
+          }
         },
-        "required": ["approved", "summary"]
+        "required": ["approved", "summary", "criteriaResults"]
       },
       "prompt": {
-        "system": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are a requirements validator for a {{complexity}} {{task_type}} task.\n\n## Your Role\nVerify implementation meets requirements. Be thorough. Hold a high bar.\n\n## Validation Checklist - ALL must pass:\n1. Does implementation address ALL requirements from ISSUE_OPENED?\n2. Are edge cases handled? (empty, null, boundaries, error states)\n3. Is error handling present for failure paths?\n4. Are types strict? (no any, no ts-ignore)\n5. Is input validation present at boundaries?\n\n## 🔴 INSTANT REJECTION (Zero tolerance - REJECT immediately):\n- TODO/FIXME/HACK/XXX comments in code = REJECT (incomplete work)\n- console.log/print/debug statements left in code = REJECT (debugging artifacts)\n- Mock/stub/fake implementations where real code expected = REJECT (lazy implementation)\n- Empty catch blocks or error swallowing = REJECT (hiding failures)\n- \"Will implement later\" or partial work = REJECT (incomplete delivery)\n- Any requirement skipped without \"OUT OF SCOPE\" in original spec = REJECT (ignoring requirements)\n- Commented-out code blocks = REJECT (dead code)\n- `any` type in TypeScript = REJECT (type escape hatch)\n\nThese are AUTOMATIC rejections. No exceptions. No \"it's mostly done\". The code is either COMPLETE or it's REJECTED.\n\n## BLOCKING Issues (must reject):\n- Missing core functionality\n- Missing error handling for common failures\n- Hardcoded values that should be configurable\n- Crashes on empty/null input\n- Types not strict\n\n## NON-BLOCKING Issues (note in summary, don't reject alone):\n- Minor style preferences\n- Could be slightly DRYer\n- Rare edge cases\n\n## Output\n- approved: true if all BLOCKING criteria pass\n- summary: Assessment with blocking and non-blocking issues noted\n- errors: List of BLOCKING issues only"
+        "system": "## 🚫 YOU CANNOT ASK QUESTIONS\n\nYou are running non-interactively. There is NO USER to answer.\n- NEVER use AskUserQuestion tool\n- NEVER say \"Should I...\" or \"Would you like...\"\n- When unsure: Make the SAFER choice and proceed.\n\nYou are a requirements validator for a {{complexity}} {{task_type}} task.\n\n## Your Role\nVerify implementation meets requirements. Be thorough. Hold a high bar.\n\n## 🔴 ACCEPTANCE CRITERIA VERIFICATION (REQUIRED)\n\n**You MUST check EVERY acceptance criterion from PLAN_READY.**\n\n### Verification Process:\n1. **Parse acceptanceCriteria** from PLAN_READY data\n2. **For EACH criterion**:\n   a. Execute the verification steps specified in the criterion\n   b. Record PASS or FAIL with evidence (command output, observation)\n   c. If FAIL: Add to errors array if priority=MUST\n3. **Output criteriaResults** with status for each criterion\n\n### Automatic Rejection Rules:\n- ANY criterion with priority=MUST that fails → approved: false\n- SHOULD/NICE criteria can fail without rejection (note in summary)\n\n### Example criteriaResults:\n```json\n[\n  {\"id\": \"AC1\", \"status\": \"PASS\", \"evidence\": \"npm test shows 15/15 passing\"},\n  {\"id\": \"AC2\", \"status\": \"FAIL\", \"evidence\": \"POST /api/users returns 500\", \"notes\": \"Missing validation\"},\n  {\"id\": \"AC3\", \"status\": \"PASS\", \"evidence\": \"Manual test: dark mode toggle works\"}\n]\n```\n\n## Validation Checklist - ALL must pass:\n1. Does implementation address ALL requirements from ISSUE_OPENED?\n2. Are edge cases handled? (empty, null, boundaries, error states)\n3. Is error handling present for failure paths?\n4. Are types strict? (no any, no ts-ignore)\n5. Is input validation present at boundaries?\n\n## 🔴 INSTANT REJECTION (Zero tolerance - REJECT immediately):\n- TODO/FIXME/HACK/XXX comments in code = REJECT (incomplete work)\n- console.log/print/debug statements left in code = REJECT (debugging artifacts)\n- Mock/stub/fake implementations where real code expected = REJECT (lazy implementation)\n- Empty catch blocks or error swallowing = REJECT (hiding failures)\n- \"Will implement later\" or partial work = REJECT (incomplete delivery)\n- Any requirement skipped without \"OUT OF SCOPE\" in original spec = REJECT (ignoring requirements)\n- Commented-out code blocks = REJECT (dead code)\n- `any` type in TypeScript = REJECT (type escape hatch)\n\nThese are AUTOMATIC rejections. No exceptions. No \"it's mostly done\". The code is either COMPLETE or it's REJECTED.\n\n## BLOCKING Issues (must reject):\n- Missing core functionality\n- Missing error handling for common failures\n- Hardcoded values that should be configurable\n- Crashes on empty/null input\n- Types not strict\n- **ANY priority=MUST criterion that fails**\n\n## NON-BLOCKING Issues (note in summary, don't reject alone):\n- Minor style preferences\n- Could be slightly DRYer\n- Rare edge cases\n- priority=SHOULD/NICE criteria that fail\n\n## Output\n- approved: true if all BLOCKING criteria pass AND all priority=MUST acceptance criteria pass\n- summary: Assessment with blocking and non-blocking issues noted\n- errors: List of BLOCKING issues only\n- criteriaResults: PASS/FAIL for EACH acceptance criterion"
       },
       "contextStrategy": {
         "sources": [
@@ -218,7 +248,8 @@
               "text": "{{result.summary}}",
               "data": {
                 "approved": "{{result.approved}}",
-                "errors": "{{result.errors}}"
+                "errors": "{{result.errors}}",
+                "criteriaResults": "{{result.criteriaResults}}"
               }
             }
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@covibes/zeroshot",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Multi-agent orchestration engine for Claude - cluster coordinator and CLI",
   "main": "src/orchestrator.js",
   "bin": {

package/src/agent/agent-lifecycle.js

@@ -282,6 +282,8 @@ async function executeTask(agent, triggeringMessage) {
       });
 
       // Publish TOKEN_USAGE event for aggregation and tracking
+      // CRITICAL: Include taskId for causal linking - allows consumers to group
+      // messages by task regardless of interleaved timing from async hooks
       if (result.tokenUsage) {
         agent.messageBus.publish({
           cluster_id: agent.cluster.id,
@@ -294,6 +296,7 @@ async function executeTask(agent, triggeringMessage) {
               role: agent.role,
               model: agent._selectModel(),
               iteration: agent.iteration,
+              taskId: agent.currentTaskId, // Causal linking for message ordering
               ...result.tokenUsage,
             },
           },

package/src/ledger.js

@@ -116,6 +116,84 @@ class Ledger extends EventEmitter {
     }
   }
 
+  /**
+   * Append multiple messages atomically using a transaction
+   * All messages get contiguous timestamps and are committed together.
+   * If any insert fails, the entire batch is rolled back.
+   *
+   * Use this for task completion messages to prevent interleaving:
+   * - TOKEN_USAGE, TASK_COMPLETED, and hook messages published atomically
+   * - Other agents' messages cannot appear between them
+   *
+   * @param {Array<Object>} messages - Array of message objects
+   * @returns {Array<Object>} Array of appended messages with generated IDs
+   */
+  batchAppend(messages) {
+    if (!Array.isArray(messages) || messages.length === 0) {
+      return [];
+    }
+
+    // Create transaction function - all inserts happen atomically
+    const insertMany = this.db.transaction((msgs) => {
+      const results = [];
+      const baseTimestamp = Date.now();
+
+      for (let i = 0; i < msgs.length; i++) {
+        const message = msgs[i];
+        const id = message.id || `msg_${crypto.randomBytes(16).toString('hex')}`;
+        // Use incrementing timestamps to preserve order within batch
+        const timestamp = message.timestamp || (baseTimestamp + i);
+
+        const record = {
+          id,
+          timestamp,
+          topic: message.topic,
+          sender: message.sender,
+          receiver: message.receiver || 'broadcast',
+          content_text: message.content?.text || null,
+          content_data: message.content?.data ? JSON.stringify(message.content.data) : null,
+          metadata: message.metadata ? JSON.stringify(message.metadata) : null,
+          cluster_id: message.cluster_id,
+        };
+
+        this.stmts.insert.run(
+          record.id,
+          record.timestamp,
+          record.topic,
+          record.sender,
+          record.receiver,
+          record.content_text,
+          record.content_data,
+          record.metadata,
+          record.cluster_id
+        );
+
+        results.push(this._deserializeMessage(record));
+      }
+
+      return results;
+    });
+
+    try {
+      // Execute transaction (atomic - all or nothing)
+      const appendedMessages = insertMany(messages);
+
+      // Invalidate cache
+      this.cache.clear();
+
+      // Emit events for subscriptions AFTER transaction commits
+      // This ensures listeners see consistent state
+      for (const fullMessage of appendedMessages) {
+        this.emit('message', fullMessage);
+        this.emit(`topic:${fullMessage.topic}`, fullMessage);
+      }
+
+      return appendedMessages;
+    } catch (error) {
+      throw new Error(`Failed to batch append messages: ${error.message}`);
+    }
+  }
+
   /**
    * Query messages with filters
    * @param {Object} criteria - Query criteria
@@ -269,6 +347,77 @@ class Ledger extends EventEmitter {
     return rows.map((row) => this._deserializeMessage(row));
   }
 
+  /**
+   * Get aggregated token usage by agent role
+   * Queries TOKEN_USAGE messages and sums tokens per role
+   * @param {String} cluster_id - Cluster ID
+   * @returns {Object} Token usage aggregated by role
+   *   Example: {
+   *     implementation: { inputTokens: 5000, outputTokens: 2000, totalCostUsd: 0.05, count: 3 },
+   *     validator: { inputTokens: 3000, outputTokens: 1500, totalCostUsd: 0.03, count: 2 },
+   *     _total: { inputTokens: 8000, outputTokens: 3500, totalCostUsd: 0.08, count: 5 }
+   *   }
+   */
+  getTokensByRole(cluster_id) {
+    if (!cluster_id) {
+      throw new Error('cluster_id is required for getTokensByRole');
+    }
+
+    // Query all TOKEN_USAGE messages for this cluster
+    const sql = `SELECT * FROM messages WHERE cluster_id = ? AND topic = 'TOKEN_USAGE' ORDER BY timestamp ASC`;
+    const stmt = this.db.prepare(sql);
+    const rows = stmt.all(cluster_id);
+
+    const byRole = {};
+    const total = {
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadInputTokens: 0,
+      cacheCreationInputTokens: 0,
+      totalCostUsd: 0,
+      count: 0,
+    };
+
+    for (const row of rows) {
+      const message = this._deserializeMessage(row);
+      const data = message.content?.data || {};
+      const role = data.role || 'unknown';
+
+      // Initialize role bucket if needed
+      if (!byRole[role]) {
+        byRole[role] = {
+          inputTokens: 0,
+          outputTokens: 0,
+          cacheReadInputTokens: 0,
+          cacheCreationInputTokens: 0,
+          totalCostUsd: 0,
+          count: 0,
+        };
+      }
+
+      // Aggregate tokens for this role
+      byRole[role].inputTokens += data.inputTokens || 0;
+      byRole[role].outputTokens += data.outputTokens || 0;
+      byRole[role].cacheReadInputTokens += data.cacheReadInputTokens || 0;
+      byRole[role].cacheCreationInputTokens += data.cacheCreationInputTokens || 0;
+      byRole[role].totalCostUsd += data.totalCostUsd || 0;
+      byRole[role].count += 1;
+
+      // Aggregate totals
+      total.inputTokens += data.inputTokens || 0;
+      total.outputTokens += data.outputTokens || 0;
+      total.cacheReadInputTokens += data.cacheReadInputTokens || 0;
+      total.cacheCreationInputTokens += data.cacheCreationInputTokens || 0;
+      total.totalCostUsd += data.totalCostUsd || 0;
+      total.count += 1;
+    }
+
+    // Add total as special _total key
+    byRole._total = total;
+
+    return byRole;
+  }
+
   /**
    * Subscribe to new messages
    * @param {Function} callback - Called with each new message

package/src/message-bus.js

@@ -126,6 +126,48 @@ class MessageBus extends EventEmitter {
     return this.ledger.getAll(cluster_id);
   }
 
+  /**
+   * Publish multiple messages atomically
+   * All messages are committed in a single transaction with contiguous timestamps.
+   * Use this for task completion to prevent message interleaving between agents.
+   *
+   * @param {Array<Object>} messages - Array of messages to publish
+   * @returns {Array<Object>} Published messages with IDs
+   */
+  batchPublish(messages) {
+    // Validate all messages
+    for (const message of messages) {
+      if (!message.cluster_id) {
+        throw new Error('cluster_id is required for all messages');
+      }
+      if (!message.topic) {
+        throw new Error('topic is required for all messages');
+      }
+      if (!message.sender) {
+        throw new Error('sender is required for all messages');
+      }
+    }
+
+    // Delegate to ledger's atomic batchAppend
+    const published = this.ledger.batchAppend(messages);
+
+    // Emit to topic-specific listeners for each message
+    for (const msg of published) {
+      this.emit(`topic:${msg.topic}`, msg);
+    }
+
+    return published;
+  }
+
+  /**
+   * Get aggregated token usage by role (passthrough to ledger)
+   * @param {String} cluster_id - Cluster ID
+   * @returns {Object} Token usage aggregated by role with _total key
+   */
+  getTokensByRole(cluster_id) {
+    return this.ledger.getTokensByRole(cluster_id);
+  }
+
   /**
    * Register a WebSocket client for broadcasts
    * @param {WebSocket} ws - WebSocket connection