@dtlabs/ai-toolkit 0.22.1 → 0.23.0

package/CHANGELOG.md

@@ -1,4 +1,12 @@
 ## 0.1.4 (2026-07-21)
+## [0.23.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.22.1...v0.23.0) (2026-10-22)
+
+
+### Features
+
+* **pm-phase2,task-executor:** shrink WBS skeleton payload, add dispatch evidence, short-circuit already-satisfied tasks (FTR-032) ([1ff9609](https://github.com/dtlab-tech/ai-toolkit/commit/1ff96090811b3ddeea2346fc3425bdae248c6d19))
+* **pm-phase2,task-executor:** WBS skeleton weight + dispatch evidence + already-satisfied short-circuit (FTR-032) ([fbfdb00](https://github.com/dtlab-tech/ai-toolkit/commit/fbfdb00f5a2bbd8afb944f5bcd2616ae1b073a1a))
+
 ## [0.22.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.22.0...v0.22.1) (2026-10-21)
 
 

package/lib/task-executor/index.js

@@ -37,6 +37,7 @@ const claudeProcess = require('./claude-process');
 const git          = require('./git');
 const ledger       = require('../execution-ledger');
 const agentRegistry = require('../agent-registry');
+const { createEvidence } = require('../workflow-worker-evidence');
 
 const IS_WINDOWS = process.platform === 'win32';
 
@@ -628,13 +629,32 @@ async function dispatchTaskAttempt(args) {
   // not yet authorized, so this cannot be empirically validated here. Flagged
   // for verification once that real-runtime test is authorized.
   const spawnArgs = baseSpawnArgs.concat([processIdentity]);
-  const spawnResult = await claudeProcess.spawnClaudeAgent({
-    claudePath: args.claudePath,
-    args: spawnArgs,
-    prompt: prompt,
-    cwd: args.projectDir,
-    taskTimeoutMs: args.taskTimeoutMs,
-  });
+
+  // FTR-032 (UC-02): persists a raw transcript/response for this specific dispatch attempt,
+  // independent of whether it succeeds, fails, or times out — the same createEvidence/save
+  // primitive pm-phase1/pm-phase2 already use for their own worker calls, scoped under this run's
+  // own executionRoot (not os.tmpdir()) so it survives alongside the run's other durable state.
+  const evidence = createEvidence(
+    { diagnosticsDir: path.join(executionRoot, 'evidence') },
+    runId,
+    identity,
+    { dispatchKind: 'implementation', taskId: task.id, attemptNumber: attemptNumber,
+      executable: args.claudePath, cwd: args.projectDir, args: spawnArgs }
+  );
+  let spawnResult;
+  try {
+    spawnResult = await claudeProcess.spawnClaudeAgent({
+      claudePath: args.claudePath,
+      args: spawnArgs,
+      prompt: prompt,
+      cwd: args.projectDir,
+      taskTimeoutMs: args.taskTimeoutMs,
+    });
+    evidence.save({ outcome: 'done', response: spawnResult, completedAt: new Date().toISOString() });
+  } catch (error) {
+    evidence.save({ outcome: 'failed', error: String(error), completedAt: new Date().toISOString() });
+    throw error;
+  }
 
   // 5. Raw capture only — no verification/review/checkpoint here.
   return {
@@ -646,6 +666,7 @@ async function dispatchTaskAttempt(args) {
     ledgerOperationId: ledgerOpenResult.operation_id,
     processIdentity: processIdentity,
     spawnResult: spawnResult,
+    evidencePath: evidence.file,
   };
 }
 
@@ -913,13 +934,29 @@ async function runReview(args) {
   const spawnArgs = Array.isArray(args.spawnArgs)
     ? args.spawnArgs
     : ['--print', '--output-format', 'json', '--agent', identity.nativeName, '--no-session-persistence'].concat(EXECUTOR_PERMISSION_BYPASS_ARGS);
-  const spawnResult = await claudeProcess.spawnClaudeAgent({
-    claudePath: args.claudePath,
-    args: spawnArgs,
-    prompt: prompt,
-    cwd: args.projectDir,
-    taskTimeoutMs: args.taskTimeoutMs,
-  });
+  // FTR-032 (UC-02): same evidence capture as dispatchTaskAttempt's own implementation dispatch,
+  // scoped under this run's own executionRoot — see that function's own comment for rationale.
+  const evidence = createEvidence(
+    { diagnosticsDir: path.join(executionRoot, 'evidence') },
+    runId,
+    identity,
+    { dispatchKind: 'review', taskId: task.id, attemptNumber: attemptNumber,
+      executable: args.claudePath, cwd: args.projectDir, args: spawnArgs }
+  );
+  let spawnResult;
+  try {
+    spawnResult = await claudeProcess.spawnClaudeAgent({
+      claudePath: args.claudePath,
+      args: spawnArgs,
+      prompt: prompt,
+      cwd: args.projectDir,
+      taskTimeoutMs: args.taskTimeoutMs,
+    });
+    evidence.save({ outcome: 'done', response: spawnResult, completedAt: new Date().toISOString() });
+  } catch (error) {
+    evidence.save({ outcome: 'failed', error: String(error), completedAt: new Date().toISOString() });
+    throw error;
+  }
 
   // 5. Raw capture + best-effort verdict extraction — no outcome persistence
   // here (US-04-TASK-BE-03 owns closing this out).
@@ -933,6 +970,7 @@ async function runReview(args) {
     nativeAgentName: identity.nativeName,
     ledgerOperationId: ledgerOpenResult.operation_id,
     spawnResult: spawnResult,
+    evidencePath: evidence.file,
     reviewPassed: verdict.passed,
     criticalFindings: verdict.criticalFindings,
     responseText: verdict.responseText,
@@ -2023,6 +2061,38 @@ async function _runTaskToResolution(ctx) {
 
     const attemptNumber = state.tasks[taskId].attempts.length + 1;
 
+    // FTR-032 (UC-03): on a task's FIRST attempt only, and only when it declares one or more
+    // verification commands, check once whether it is already satisfied BEFORE paying for a full
+    // implementation + review dispatch cycle — reported at ~20 real minutes of cost to conclude
+    // "nothing to do" on an already-satisfied 4-line task. Never applies to a retry (a prior
+    // failed attempt already proves verification did not already pass at task start) and never
+    // applies when there is nothing to confirm "already satisfied" against.
+    //
+    // Deliberately calls _runVerificationCommand directly, NOT runVerifications — the latter
+    // persists an immutable receipt per command keyed by taskId+attemptNumber+index; calling it
+    // here under attemptNumber=1 would collide with the REAL post-dispatch verification receipt
+    // for the same attempt whenever this check does NOT short-circuit (different timestamps,
+    // same receipt ID, a genuine RECEIPT_CONFLICT) — confirmed by a real test failure. This
+    // pre-check has nothing to attribute a receipt to yet (no attempt has been dispatched), so it
+    // intentionally persists nothing.
+    if (attemptNumber === 1 && task.verificationCommands.length > 0) {
+      let alreadySatisfied = true;
+      for (const command of task.verificationCommands) {
+        const outcome = await _runVerificationCommand(command, projectDir, ctx.taskTimeoutMs);
+        if (!(outcome.spawnError === null && outcome.exitCode === 0)) {
+          alreadySatisfied = false;
+          break;
+        }
+      }
+      if (alreadySatisfied) {
+        state = store.readState(executionRoot, runId);
+        state = state.setTaskStatus(taskId, 'skipped', { reason: 'already-satisfied-pre-dispatch' });
+        store.writeState(executionRoot, runId, state);
+        return;
+      }
+      // any failure: fall through to a normal dispatch below, unchanged
+    }
+
     let dispatchResult;
     try {
       dispatchResult = await dispatchTaskAttempt({

package/lib/task-executor/store.js

@@ -257,13 +257,17 @@ class State {
     return task;
   }
 
-  setTaskStatus(taskId, status) {
+  // extra (FTR-032): optional fields merged into the task entry alongside status — e.g.
+  // { reason: 'already-satisfied-pre-dispatch' } to distinguish a pre-dispatch short-circuit
+  // skip from the existing post-hoc no-op-checkpoint skip. Every existing call site passes
+  // exactly 2 arguments; extra defaults to undefined, and `extra || {}` makes this a no-op there.
+  setTaskStatus(taskId, status, extra) {
     const task = this._requireTask(taskId, 'setTaskStatus');
     if (TASK_STATUSES.indexOf(status) === -1) {
       throw _err('STATE_VALIDATION_ERROR', 'setTaskStatus: invalid status "' + status + '"; allowed: ' + TASK_STATUSES.join(', '));
     }
     const tasks = Object.assign({}, this.tasks);
-    tasks[taskId] = Object.assign({}, task, { status: status });
+    tasks[taskId] = Object.assign({}, task, { status: status }, extra || {});
     return this._clone({ tasks: tasks });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

package/src/claude/scripts/wbs-assembler.js

@@ -33,6 +33,19 @@ function _stringOrNull(value) {
   return value === DASH ? null : value
 }
 
+// Mirrors lib/task-executor/plan.js's own identically-named function — a non-numeric value is a
+// parse error, not silently coerced (the task's own "Estimate — agent minutes"/"Estimate —
+// tokens" fields are never `—`, per gaia-task-template.md's own placeholder contract, so `null`
+// here only ever means the label itself was missing from the field block).
+function _numberOrNull(value) {
+  if (value == null) return null
+  const n = Number(value)
+  if (Number.isNaN(n)) {
+    throw new Error(`wbs-assembler: expected a numeric value, got ${JSON.stringify(value)}`)
+  }
+  return n
+}
+
 // ── Template engine ───────────────────────────────────────────────────────────
 // Loads a canonical templates/gaia-{name}-template.md file and fills in its placeholders. The
 // template file is the single source of truth for field labels, their order, and section
@@ -147,6 +160,13 @@ function _parseVerificationCommands(text) {
 function parseTaskDetailBlock(text) {
   const fields = _parseFieldBlock(text)
   return {
+    // FTR-032: the per-task detail call's own template already asks for a real estimate in every
+    // response — the WBS skeleton call no longer does (see loadWorkBreakdown's per-task mapping
+    // below), so THIS is now the authoritative source, not a value silently discarded as before.
+    estimate: {
+      agentMinutes: _numberOrNull(fields['Estimate — agent minutes']),
+      tokens: _numberOrNull(fields['Estimate — tokens']),
+    },
     groupingRationale: _stringOrNull(fields['Grouping rationale']),
     verificationCommands: _parseVerificationCommands(text),
   }
@@ -298,7 +318,7 @@ function loadWorkBreakdown(inputPath) {
           agentType: skeletonTask.agentType,
           dependsOn: skeletonTask.dependsOn,
           acceptanceCriteria: skeletonTask.acceptanceCriteria,
-          estimate: skeletonTask.estimate,
+          estimate: detail.estimate,
           outputCount: skeletonTask.outputCount,
           groupingRationale: detail.groupingRationale,
           commit: skeletonTask.commit,

package/src/claude/workflows/pm-phase2.js

@@ -35,7 +35,7 @@ const SKELETON_SCHEMA = {
     tasks: { type: 'object', additionalProperties: {
       type: 'object',
       required: ['title', 'outcome', 'domain', 'agentType', 'dependsOn',
-        'acceptanceCriteria', 'estimate', 'outputCount', 'commit'],
+        'acceptanceCriteria', 'outputCount', 'commit'],
       properties: {
         title: { type: 'string' }, outcome: { type: 'string' },
         domain: { enum: ['BE', 'FE', 'DB', 'DevOps', 'INFRA', 'TEST'] },
@@ -46,8 +46,11 @@ const SKELETON_SCHEMA = {
         ['agentType']: { enum: ['developer-backend', 'developer-frontend', 'developer-testing', 'review-solution'] },
         dependsOn: { type: 'array', items: { type: 'string' } },
         acceptanceCriteria: { type: 'array', items: { type: 'string' } },
-        estimate: { type: 'object', required: ['agentMinutes', 'tokens'],
-          properties: { agentMinutes: { type: 'integer' }, tokens: { type: 'integer' } } },
+        // FTR-032: estimate (agentMinutes/tokens) deliberately removed from this schema — the
+        // per-task detail call already produces a real one in every response (its own template
+        // asks for it); wbs-assembler.js's parseTaskDetailBlock/loadWorkBreakdown now reads that
+        // value back instead, so asking for it again here would be pure duplicated cost on top
+        // of a call that already has to reason about every task in the feature in one turn.
         outputCount: { type: 'integer' },
         commit: { type: 'object', required: ['type', 'subject'],
           properties: { type: { type: 'string' }, subject: { type: 'string' } } },