@dtlabs/ai-toolkit 0.9.0 → 0.10.0

package/.claude/scripts/tests/fixtures/wb-valid.json

@@ -0,0 +1,189 @@
+{
+  "schemaVersion": 2,
+  "feature": "FTR-014",
+  "phases": [
+    {
+      "id": "INFRA",
+      "type": "infrastructure",
+      "title": "Shared infrastructure setup",
+      "commit": {
+        "type": "feat",
+        "subject": "add shared infrastructure scaffolding"
+      },
+      "tasks": [
+        {
+          "id": "INFRA-TASK-INFRA-01",
+          "title": "Create scripts directory structure",
+          "outcome": "The .claude/scripts directory exists and is included in installer copy paths",
+          "domain": "INFRA",
+          "agentType": "developer-backend",
+          "dependsOn": [],
+          "acceptanceCriteria": [],
+          "verification": {
+            "commands": [
+              "ls .claude/scripts"
+            ]
+          },
+          "estimate": {
+            "agentMinutes": 5,
+            "tokens": 8000
+          },
+          "outputCount": 1,
+          "groupingRationale": "Single responsibility",
+          "commit": {
+            "type": "feat",
+            "subject": "create .claude/scripts directory"
+          }
+        },
+        {
+          "id": "INFRA-TASK-INFRA-02",
+          "title": "Define schema v2 constants in wb-validate.js",
+          "outcome": "Constants block (SCHEMA_VERSION, REQUIRED_PHASE_FIELDS, REQUIRED_TASK_FIELDS, VALID_DOMAINS, VALID_AGENT_TYPES) is present at the top of wb-validate.js",
+          "domain": "INFRA",
+          "agentType": "developer-backend",
+          "dependsOn": [
+            "INFRA-TASK-INFRA-01"
+          ],
+          "acceptanceCriteria": [],
+          "verification": {
+            "commands": [
+              "node -e \"const v = require('./.claude/scripts/wb-validate.js'); console.log('ok')\""
+            ]
+          },
+          "estimate": {
+            "agentMinutes": 10,
+            "tokens": 15000
+          },
+          "outputCount": 1,
+          "groupingRationale": "Single responsibility",
+          "commit": {
+            "type": "feat",
+            "subject": "add schema v2 constants to wb-validate.js"
+          }
+        },
+        {
+          "id": "INFRA-TASK-TEST-01",
+          "title": "Create test fixture for AC table parser",
+          "outcome": "tests/fixtures/ac-table-format.md exists with a valid AC table in the Section 3.2 contract format",
+          "domain": "TEST",
+          "agentType": "developer-testing",
+          "dependsOn": [],
+          "acceptanceCriteria": [],
+          "verification": {
+            "commands": [
+              "ls .claude/scripts/tests/fixtures/ac-table-format.md"
+            ]
+          },
+          "estimate": {
+            "agentMinutes": 8,
+            "tokens": 12000
+          },
+          "outputCount": 1,
+          "groupingRationale": "Single responsibility",
+          "commit": {
+            "type": "test",
+            "subject": "add AC table parser fixture"
+          }
+        }
+      ]
+    },
+    {
+      "id": "US-01",
+      "type": "user-story",
+      "title": "Implement deterministic structural validator wb-validate.js",
+      "commit": {
+        "type": "feat",
+        "subject": "implement wb-validate.js structural validator"
+      },
+      "tasks": [
+        {
+          "id": "US-01-TASK-BE-01",
+          "title": "Implement wb-validate.js entry point with JSON parse and schema version check",
+          "outcome": "wb-validate.js parses the input JSON file and exits with code 2 if the file is missing or malformed, and exits with code 1 if schemaVersion is not exactly 2",
+          "domain": "BE",
+          "agentType": "developer-backend",
+          "dependsOn": [
+            "INFRA-TASK-INFRA-02"
+          ],
+          "acceptanceCriteria": [
+            "AC-05"
+          ],
+          "verification": {
+            "commands": [
+              "node .claude/scripts/wb-validate.js --help",
+              "npm test -- tests/cli/wb-validate.test.js --testNamePattern='schema version'"
+            ]
+          },
+          "estimate": {
+            "agentMinutes": 10,
+            "tokens": 20000
+          },
+          "outputCount": 1,
+          "groupingRationale": "Single responsibility",
+          "commit": {
+            "type": "feat",
+            "subject": "add wb-validate.js entry point with JSON parse and schema check"
+          }
+        },
+        {
+          "id": "US-01-TASK-BE-02",
+          "title": "Implement unique ID and required field validation in wb-validate.js",
+          "outcome": "wb-validate.js detects duplicate task IDs across all phases and reports missing or null required phase/task fields with category unique_id_violation or missing_field",
+          "domain": "BE",
+          "agentType": "developer-backend",
+          "dependsOn": [
+            "US-01-TASK-BE-01"
+          ],
+          "acceptanceCriteria": [
+            "AC-05"
+          ],
+          "verification": {
+            "commands": [
+              "npm test -- tests/cli/wb-validate.test.js --testNamePattern='unique ID'",
+              "npm test -- tests/cli/wb-validate.test.js --testNamePattern='required field'"
+            ]
+          },
+          "estimate": {
+            "agentMinutes": 8,
+            "tokens": 18000
+          },
+          "outputCount": 1,
+          "groupingRationale": "Single responsibility",
+          "commit": {
+            "type": "feat",
+            "subject": "add unique ID and required field validation to wb-validate.js"
+          }
+        },
+        {
+          "id": "US-01-TASK-TEST-01",
+          "title": "Write Jest tests for wb-validate.js schema version and unique ID checks",
+          "outcome": "tests/cli/wb-validate.test.js exists and all schema version and unique ID test cases pass under npm test",
+          "domain": "TEST",
+          "agentType": "developer-testing",
+          "dependsOn": [
+            "US-01-TASK-BE-01",
+            "US-01-TASK-BE-02"
+          ],
+          "acceptanceCriteria": [
+            "AC-05"
+          ],
+          "verification": {
+            "commands": [
+              "npm test -- tests/cli/wb-validate.test.js"
+            ]
+          },
+          "estimate": {
+            "agentMinutes": 15,
+            "tokens": 30000
+          },
+          "outputCount": 1,
+          "groupingRationale": "Single responsibility",
+          "commit": {
+            "type": "test",
+            "subject": "add wb-validate.js schema version and unique ID tests"
+          }
+        }
+      ]
+    }
+  ]
+}

package/.claude/scripts/tests/helpers/buildWaves.js

@@ -0,0 +1,21 @@
+// Extracted verbatim from pm-phase3.js — must remain in sync
+
+const buildWaves = (phases) => {
+  const done   = new Set()
+  const waves  = []
+  let remaining = [...phases]
+  while (remaining.length > 0) {
+    const ready = remaining.filter(p => p.depends_on.every(d => done.has(d)))
+    if (ready.length === 0) {
+      // Circular or unresolvable deps — run the rest sequentially to avoid deadlock
+      waves.push(remaining)
+      break
+    }
+    waves.push(ready)
+    ready.forEach(p => done.add(p.phase_id))
+    remaining = remaining.filter(p => !done.has(p.phase_id))
+  }
+  return waves
+}
+
+module.exports = { buildWaves }

package/.claude/scripts/tests/helpers/pm-phase2-flow.js

@@ -0,0 +1,29 @@
+'use strict'
+
+// Pure orchestration predicates extracted from pm-phase2 for testability
+
+function wbValidatorPassed(validateFailed, wbValidatorReport) {
+  return !validateFailed
+    && wbValidatorReport !== null
+    && wbValidatorReport.valid === true
+    && Array.isArray(wbValidatorReport.errors)
+    && wbValidatorReport.errors.length === 0
+}
+
+function canRunSemantic(validateFailed, wbValidatorReport) {
+  return wbValidatorPassed(validateFailed, wbValidatorReport)
+}
+
+function canRunRender(validateFailed, wbValidatorReport, semanticFailed) {
+  return wbValidatorPassed(validateFailed, wbValidatorReport) && !semanticFailed
+}
+
+function gate2IsBlocked(validateFailed, wbValidatorReport, semanticFailed, renderFailed, semanticResult) {
+  return validateFailed
+    || !wbValidatorPassed(validateFailed, wbValidatorReport)
+    || semanticFailed
+    || renderFailed
+    || Boolean(semanticResult && semanticResult.findings && semanticResult.findings.some(f => f.blocking))
+}
+
+module.exports = { wbValidatorPassed, canRunSemantic, canRunRender, gate2IsBlocked }

package/.claude/scripts/tests/helpers/pm-phase2-gate2.js

@@ -0,0 +1,55 @@
+'use strict'
+
+function buildGate2Payload(options) {
+  const {
+    wbValidatorReport = null,
+    validateFailed = false,
+    semanticResult = null,
+    semanticFailed = false,
+    renderResult = null,
+    renderFailed = false,
+  } = options
+
+  const wbValidatorPassed = !validateFailed
+    && wbValidatorReport !== null
+    && wbValidatorReport.valid === true
+    && Array.isArray(wbValidatorReport.errors)
+    && wbValidatorReport.errors.length === 0
+
+  return {
+    js_validator_report:       wbValidatorReport,
+    js_validator_failed:       validateFailed,
+    semantic_validator_result: semanticResult,
+    semantic_validator_failed: semanticFailed,
+    renderer_result:           renderResult,
+    renderer_failed:           renderFailed,
+    duration_bands:      wbValidatorReport ? wbValidatorReport.durationBands : null,
+    domain_distribution: wbValidatorReport ? wbValidatorReport.domainDistribution : null,
+    warning_band_tasks:  wbValidatorReport
+      ? (wbValidatorReport.warnings || [])
+          .filter(w => w.category === 'duration_warning')
+          .map(w => ({ taskId: w.taskId, agentMinutes: w.details ? w.details.agentMinutes : null }))
+      : [],
+    split_required_tasks: wbValidatorReport
+      ? (wbValidatorReport.errors || [])
+          .filter(e => e.category === 'split_required')
+          .map(e => ({ taskId: e.taskId, agentMinutes: e.details ? e.details.agentMinutes : null }))
+      : [],
+    must_ac_uncovered: wbValidatorReport
+      ? (wbValidatorReport.errors || [])
+          .filter(e => e.category === 'must_ac_uncovered')
+          .map(e => ({ acId: e.details ? e.details.acId : null }))
+      : [],
+    phase_unschedulable: wbValidatorReport && wbValidatorReport.dependencies
+      ? (wbValidatorReport.dependencies.phaseUnschedulable || [])
+      : [],
+    gate2_blocked:
+      validateFailed ||
+      !wbValidatorPassed ||
+      semanticFailed ||
+      renderFailed ||
+      Boolean(semanticResult && semanticResult.findings && semanticResult.findings.some(f => f.blocking)),
+  }
+}
+
+module.exports = { buildGate2Payload }

package/.claude/scripts/tests/helpers/pm-phase2-ledger.js

@@ -0,0 +1,108 @@
+'use strict'
+
+// Pure simulation of the ledger state machine from pm-phase2.js
+// Input: the scenario (which steps pass/fail/skip)
+// Output: array of ledger entry specifications that pm-phase2 would write
+
+function simulateLedgerEntries(scenario) {
+  const {
+    validateFailed = false,
+    validateExitCode = 0,
+    validateError = null,
+    validateTokens = 0,
+    wbValidatorReport = null,
+    semanticSkipped = false,
+    semanticFailed = false,
+    semanticError = null,
+    semanticTokens = 0,
+    renderSkipped = false,
+    renderFailed = false,
+    renderError = null,
+    renderExitCode = null,
+    renderTokens = 0,
+  } = scenario
+
+  const wbValidatorPassed = !validateFailed
+    && wbValidatorReport !== null
+    && wbValidatorReport.valid === true
+    && Array.isArray(wbValidatorReport.errors)
+    && wbValidatorReport.errors.length === 0
+
+  const entries = []
+
+  // Step 2: wb-validate
+  // Always appends 'running', then updates to 'done' or 'failed'
+  entries.push({
+    agent: 'wb-validate:phase2',
+    status_sequence: validateFailed ? ['running', 'failed'] : ['running', 'done'],
+    final_status: validateFailed ? 'failed' : 'done',
+    phase_delta_tokens: validateTokens,
+    error_summary: validateFailed ? (validateError || '<unknown error>') : undefined,
+    exit_code: validateFailed ? (validateExitCode ?? null) : undefined,
+  })
+
+  // Step 3: semantic validator
+  if (!wbValidatorPassed) {
+    entries.push({
+      agent: 'validate-work-breakdown-semantic:phase2',
+      status_sequence: ['skipped'],
+      final_status: 'skipped',
+      phase_delta_tokens: 0,
+      error_summary: undefined,
+      exit_code: undefined,
+    })
+  } else if (semanticFailed) {
+    entries.push({
+      agent: 'validate-work-breakdown-semantic:phase2',
+      status_sequence: ['running', 'failed'],
+      final_status: 'failed',
+      phase_delta_tokens: semanticTokens,
+      error_summary: semanticError || '<unknown error>',
+      exit_code: null,
+    })
+  } else {
+    entries.push({
+      agent: 'validate-work-breakdown-semantic:phase2',
+      status_sequence: ['running', 'done'],
+      final_status: 'done',
+      phase_delta_tokens: semanticTokens,
+      error_summary: undefined,
+      exit_code: undefined,
+    })
+  }
+
+  // Step 4: wb-render
+  const canRender = wbValidatorPassed && !semanticFailed
+  if (!canRender) {
+    entries.push({
+      agent: 'wb-render:phase2',
+      status_sequence: ['skipped'],
+      final_status: 'skipped',
+      phase_delta_tokens: 0,
+      error_summary: undefined,
+      exit_code: undefined,
+    })
+  } else if (renderFailed) {
+    entries.push({
+      agent: 'wb-render:phase2',
+      status_sequence: ['running', 'failed'],
+      final_status: 'failed',
+      phase_delta_tokens: renderTokens,
+      error_summary: renderError || '<unknown error>',
+      exit_code: renderExitCode,
+    })
+  } else {
+    entries.push({
+      agent: 'wb-render:phase2',
+      status_sequence: ['running', 'done'],
+      final_status: 'done',
+      phase_delta_tokens: renderTokens,
+      error_summary: undefined,
+      exit_code: undefined,
+    })
+  }
+
+  return entries
+}
+
+module.exports = { simulateLedgerEntries }

package/.claude/scripts/tests/installer.scripts-distribution.test.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs   = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '../../..'); // toolkit root
+const SCRIPTS         = path.join(ROOT, '.claude', 'scripts');
+const WB_VALIDATE     = path.join(SCRIPTS, 'wb-validate.js');
+const WB_RENDER       = path.join(SCRIPTS, 'wb-render.js');
+const CLI_SRC         = fs.readFileSync(path.join(ROOT, 'bin', 'cli.js'), 'utf8');
+const INSTALL_TOOLKIT_SRC = fs.readFileSync(
+  path.join(ROOT, '.claude', 'agents', 'install-toolkit.md'), 'utf8'
+);
+
+// Helper: extract the body of installLocal from CLI_SRC (up to installGlobal)
+function extractInstallLocalBody() {
+  const localStart  = CLI_SRC.indexOf('async function installLocal');
+  const globalStart = CLI_SRC.indexOf('async function installGlobal');
+  return CLI_SRC.slice(localStart, globalStart);
+}
+
+// Helper: extract the body of installGlobal from CLI_SRC (up to function help)
+function extractInstallGlobalBody() {
+  const globalStart = CLI_SRC.indexOf('async function installGlobal');
+  const helpStart   = CLI_SRC.indexOf('\nfunction help(');
+  return helpStart === -1
+    ? CLI_SRC.slice(globalStart)
+    : CLI_SRC.slice(globalStart, helpStart);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Group 1: Source files exist (precondition)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('installer.scripts-distribution — Group 1: source files exist', () => {
+  test('wb-validate.js exists at .claude/scripts/wb-validate.js in the toolkit root', () => {
+    expect(fs.existsSync(WB_VALIDATE)).toBe(true);
+  });
+
+  test('wb-render.js exists at .claude/scripts/wb-render.js in the toolkit root', () => {
+    expect(fs.existsSync(WB_RENDER)).toBe(true);
+  });
+
+  test('wb-validate.js passes Node.js syntax check (node --check)', () => {
+    const result = spawnSync(process.execPath, ['--check', WB_VALIDATE], { encoding: 'utf8' });
+    expect(result.status).toBe(0);
+  });
+
+  test('wb-render.js passes Node.js syntax check (node --check)', () => {
+    const result = spawnSync(process.execPath, ['--check', WB_RENDER], { encoding: 'utf8' });
+    expect(result.status).toBe(0);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Group 2: Local install includes scripts (static verification)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('installer.scripts-distribution — Group 2: local install includes scripts', () => {
+  test('installLocal in bin/cli.js maps the entire .claude directory (which includes .claude/scripts/)', () => {
+    // The local install maps { src: path.join(packageRoot, '.claude'), dest: ... }
+    // so the whole .claude/ tree — including .claude/scripts/ — is included automatically.
+    const localBody = extractInstallLocalBody();
+    expect(localBody).toContain("path.join(packageRoot, '.claude')");
+  });
+
+  test('.claude/scripts/ directory contains wb-validate.js and wb-render.js', () => {
+    const files = fs.readdirSync(SCRIPTS);
+    expect(files).toContain('wb-validate.js');
+    expect(files).toContain('wb-render.js');
+  });
+
+  test('wb-validate.js with no args exits with code 2 (usage error) and writes to stderr', () => {
+    // Arrange: no arguments — the script should emit a usage error
+    // Act
+    const result = spawnSync(process.execPath, [WB_VALIDATE], { encoding: 'utf8' });
+    // Assert
+    expect(result.status).toBe(2);
+    expect(result.stderr.length).toBeGreaterThan(0);
+  });
+
+  test('wb-render.js with no args exits with code 1 (usage error) and writes to stderr', () => {
+    // Arrange: no arguments — the script should emit a usage message
+    // Act
+    const result = spawnSync(process.execPath, [WB_RENDER], { encoding: 'utf8' });
+    // Assert
+    expect(result.status).toBe(1);
+    expect(result.stderr.length).toBeGreaterThan(0);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Group 3: Global install mapping includes scripts (static verification)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('installer.scripts-distribution — Group 3: global install mapping includes scripts', () => {
+  test('installGlobal in bin/cli.js contains a mapping entry for .claude/scripts', () => {
+    // The mapping line is: { src: path.join(packageRoot, '.claude', 'scripts'), ... }
+    const globalBody = extractInstallGlobalBody();
+    expect(globalBody).toContain("'scripts'");
+  });
+
+  test('global install destination path for scripts is derived from target + scripts', () => {
+    // The mapping line is: { ..., dest: path.join(target, 'scripts') }
+    // where target = path.join(homedir, '.claude') → dest = ~/.claude/scripts
+    expect(CLI_SRC).toContain("path.join(target, 'scripts')");
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Group 4: install-toolkit.md agent mentions scripts (static verification)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('installer.scripts-distribution — Group 4: install-toolkit.md mentions scripts', () => {
+  test('install-toolkit.md contains the string .claude/scripts/', () => {
+    expect(INSTALL_TOOLKIT_SRC).toContain('.claude/scripts/');
+  });
+
+  test('install-toolkit.md contains wb-validate.js', () => {
+    expect(INSTALL_TOOLKIT_SRC).toContain('wb-validate.js');
+  });
+
+  test('install-toolkit.md contains wb-render.js', () => {
+    expect(INSTALL_TOOLKIT_SRC).toContain('wb-render.js');
+  });
+
+  test('install-toolkit.md mentions "Six source directories" (confirming the scripts table row was added)', () => {
+    expect(INSTALL_TOOLKIT_SRC).toContain('Six source directories');
+  });
+});