@dtlabs/ai-toolkit 0.10.1 → 0.12.0

package/{.claude → src/claude}/workflows/pm-phase1.js

@@ -9,38 +9,6 @@ export const meta = {
   ],
 }
 
-// ── Ledger helper functions ───────────────────────────────────────────────────
-
-async function appendLedgerEntry(featureDir, prefix, entry) {
-  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
-  // started_at is generated via Bash inside the agent to get a real UTC timestamp with time
-  const entryWithoutTs = JSON.stringify({ ...entry, started_at: '__TS__', completed_at: null })
-  await agent(
-    `Append a JSON object to the ledger array at: ${ledgerPath}\n\n` +
-    `1. Run: date -u +"%Y-%m-%dT%H:%M:%SZ" and capture the output as NOW.\n` +
-    `2. Read the file. If it does not exist or cannot be parsed as a JSON array, start with [].\n` +
-    `3. Push this object onto the array, replacing "__TS__" in started_at with NOW: ${entryWithoutTs}\n` +
-    `4. Write the full array back (JSON, 2-space indent). Return no output.`,
-    { label: 'append-ledger', phase: 'Requirements', model: 'haiku' }
-  )
-}
-
-async function updateLedgerEntry(featureDir, prefix, agentKey, updates) {
-  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
-  // completed_at is generated via Bash inside the agent to get a real UTC timestamp with time
-  const updatesWithoutTs = JSON.stringify({ ...updates, completed_at: '__TS__' })
-  await agent(
-    `Update an entry in the ledger array at: ${ledgerPath}\n\n` +
-    `1. Run: date -u +"%Y-%m-%dT%H:%M:%SZ" and capture the output as NOW.\n` +
-    `2. Read the file. If it does not exist or cannot be parsed as a JSON array, do nothing.\n` +
-    `3. Search from the end for the last entry where agent === "${agentKey}".\n` +
-    `4. If found, merge these fields into that entry, replacing "__TS__" in completed_at with NOW: ${updatesWithoutTs}\n` +
-    `5. Write the full array back (JSON, 2-space indent). Return no output.\n` +
-    `6. If not found, do nothing.`,
-    { label: 'update-ledger', phase: 'Requirements', model: 'haiku' }
-  )
-}
-
 // ── Parse args ────────────────────────────────────────────────────────────────
 // args is the raw prompt string: "<path-to-feature.md> [--force]"
 const featurePath = args.split(/\s+/)[0]
@@ -104,7 +72,7 @@ log(`needs_requirements=${discoveryResult.needs_requirements} needs_tech_spec=${
 
 // ── Ensure ledger file exists (US-02-T02) ─────────────────────────────────────
 // If define-feature was not used, the ledger file will not exist yet.
-// Touch it with an empty array so appendLedgerEntry can always assume a valid base.
+// Touch it with an empty array so the ledger facade can always assume a valid base.
 const ledgerFilePath = `${feature_dir}/${prefix}-token-ledger.json`
 await agent(
   `Check whether the file ${ledgerFilePath} exists.\n\n1. Try to read the file using the Read tool.\n2. If the file does NOT exist: write it now using the Write tool with contents: []\n3. If the file already exists and is a valid JSON array: do nothing.\n4. If the file exists but is not valid JSON: overwrite it with: []\n5. Return no output.`,
@@ -120,23 +88,17 @@ const errors      = []
 
 if (discoveryResult.needs_requirements) {
   const reqKey = 'generate-requirements:phase1'
-  await appendLedgerEntry(feature_dir, prefix, {
-    agent: reqKey,
-    phase: 'phase1',
-    model: 'haiku',
-    status: 'running',
-    phase_delta_tokens: 0,
-    started_at: '__TS__',
-    completed_at: null,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${feature_dir} --prefix ${prefix} --agent ${reqKey} --phase phase1 --model haiku --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-open-requirements', phase: 'Requirements', model: 'haiku' }
+  )
   const beforeReq = budget.spent()
   const reqResult = await agent(featurePath, { agentType: 'generate-requirements', label: 'generate-requirements', phase: 'Requirements' })
   const reqTokens = budget.spent() - beforeReq
-  await updateLedgerEntry(feature_dir, prefix, reqKey, {
-    status: 'done',
-    completed_at: '__TS__',
-    phase_delta_tokens: reqTokens,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${feature_dir} --prefix ${prefix} --agent ${reqKey} --tokens ${reqTokens} --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-close-requirements', phase: 'Requirements', model: 'haiku' }
+  )
   tokenLedger.push({ agent: 'generate-requirements', model: 'haiku', phase_delta_tokens: reqTokens })
   log(`generate-requirements done — phase delta: ${reqTokens} tokens`)
 } else {
@@ -148,23 +110,17 @@ phase('Tech-Spec')
 
 if (discoveryResult.needs_tech_spec) {
   const specKey = 'generate-tech-spec:phase1'
-  await appendLedgerEntry(feature_dir, prefix, {
-    agent: specKey,
-    phase: 'phase1',
-    model: 'haiku',
-    status: 'running',
-    phase_delta_tokens: 0,
-    started_at: '__TS__',
-    completed_at: null,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${feature_dir} --prefix ${prefix} --agent ${specKey} --phase phase1 --model haiku --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-open-tech-spec', phase: 'Tech-Spec', model: 'haiku' }
+  )
   const beforeSpec = budget.spent()
   const specResult = await agent(featurePath, { agentType: 'generate-tech-spec', label: 'generate-tech-spec', phase: 'Tech-Spec' })
   const specTokens = budget.spent() - beforeSpec
-  await updateLedgerEntry(feature_dir, prefix, specKey, {
-    status: 'done',
-    completed_at: '__TS__',
-    phase_delta_tokens: specTokens,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${feature_dir} --prefix ${prefix} --agent ${specKey} --tokens ${specTokens} --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-close-tech-spec', phase: 'Tech-Spec', model: 'haiku' }
+  )
   tokenLedger.push({ agent: 'generate-tech-spec', model: 'haiku', phase_delta_tokens: specTokens })
   log(`generate-tech-spec done — phase delta: ${specTokens} tokens`)
 } else {
@@ -181,23 +137,17 @@ const MAX_CYCLES = 3
 for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
   log(`validate-feature-docs cycle ${cycle}`)
   const valKey = `validate-feature-docs:phase1:cycle${cycle}`
-  await appendLedgerEntry(feature_dir, prefix, {
-    agent: valKey,
-    phase: 'phase1',
-    model: 'haiku',
-    status: 'running',
-    phase_delta_tokens: 0,
-    started_at: '__TS__',
-    completed_at: null,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${feature_dir} --prefix ${prefix} --agent ${valKey} --phase phase1 --model haiku --attempt 1\n\nReturn no output.`,
+    { label: `ledger-open-validate-cycle-${cycle}`, phase: 'Validation', model: 'haiku' }
+  )
   const beforeVal = budget.spent()
   const valResult = await agent(featurePath, { agentType: 'validate-feature-docs', label: `validate-feature-docs (cycle ${cycle})`, phase: 'Validation' })
   const valTokens = budget.spent() - beforeVal
-  await updateLedgerEntry(feature_dir, prefix, valKey, {
-    status: 'done',
-    completed_at: '__TS__',
-    phase_delta_tokens: valTokens,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${feature_dir} --prefix ${prefix} --agent ${valKey} --tokens ${valTokens} --attempt 1\n\nReturn no output.`,
+    { label: `ledger-close-validate-cycle-${cycle}`, phase: 'Validation', model: 'haiku' }
+  )
   tokenLedger.push({ agent: `validate-feature-docs (cycle ${cycle})`, model: 'haiku', phase_delta_tokens: valTokens })
 
   // valResult is the agent's text output — check for gap indicators

package/{.claude → src/claude}/workflows/pm-phase2.js

@@ -7,42 +7,6 @@ export const meta = {
   ],
 }
 
-// ── Ledger helper functions ───────────────────────────────────────────────────
-// Route all ledger I/O through agent() — fs is not available in the workflow runtime.
-// Mirrors appendLedgerEntry / updateLedgerEntry from bin/cli.js (same contract).
-
-async function appendLedgerEntry(featureDir, prefix, entry) {
-  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
-  // Defaults come first so the caller can override started_at/completed_at.
-  // Skipped entries pass completed_at: '__TS__' to get a real timestamp; running entries
-  // pass completed_at: null to keep it null. Both are replaced/kept by the agent below.
-  const entryWithoutTs = JSON.stringify({ started_at: '__TS__', completed_at: null, ...entry })
-  await agent(
-    `Append a JSON object to the ledger array at: ${ledgerPath}\n\n` +
-    `1. Run: date -u +"%Y-%m-%dT%H:%M:%SZ" and capture the output as NOW.\n` +
-    `2. Read the file. If it does not exist or cannot be parsed as a JSON array, start with [].\n` +
-    `3. Push this object onto the array, replacing every "__TS__" string value in the object with NOW: ${entryWithoutTs}\n` +
-    `4. Write the full array back (JSON, 2-space indent). Return no output.`,
-    { label: 'append-ledger', phase: 'Work Breakdown', model: 'haiku' }
-  )
-}
-
-async function updateLedgerEntry(featureDir, prefix, agentKey, updates) {
-  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
-  // completed_at is generated via Bash inside the agent to get a real UTC timestamp with time
-  const updatesWithoutTs = JSON.stringify({ ...updates, completed_at: '__TS__' })
-  await agent(
-    `Update an entry in the ledger array at: ${ledgerPath}\n\n` +
-    `1. Run: date -u +"%Y-%m-%dT%H:%M:%SZ" and capture the output as NOW.\n` +
-    `2. Read the file. If it does not exist or cannot be parsed as a JSON array, do nothing.\n` +
-    `3. Search from the end for the last entry where agent === "${agentKey}".\n` +
-    `4. If found, merge these fields into that entry, replacing "__TS__" in completed_at with NOW: ${updatesWithoutTs}\n` +
-    `5. Write the full array back (JSON, 2-space indent). Return no output.\n` +
-    `6. If not found, do nothing.`,
-    { label: 'update-ledger', phase: 'Work Breakdown', model: 'haiku' }
-  )
-}
-
 // Output schemas for wb-validate and wb-render agent invocations (used by US-05)
 const WB_WRAPPER_SCHEMA = {
   type: 'object',
@@ -90,8 +54,21 @@ function normalizeError(err) {
 // args: "<path-to-feature.md>"
 const featurePath = (typeof args === 'string' ? args : '').trim().split(/\s+/)[0]
 
+// Feature directory = parent of the feature.md path. Separator-agnostic: the workflow
+// runtime provides no `path` module, so we cannot use path.dirname. Handle BOTH POSIX
+// "/" and Windows "\": strip a trailing "<sep>feature.md" tail when present; if the
+// input is already a directory (no feature.md tail), strip only a trailing separator.
+// This replaces the previous POSIX-only regex (/\/[^/]+$/), which left "\feature.md"
+// attached on Windows paths and produced malformed "…\feature.md/…json" paths that only
+// "worked" because an LLM wrapper agent silently repaired them.
+function deriveFeatureDir(featurePath) {
+  return /[/\\]feature\.md$/i.test(featurePath)
+    ? featurePath.replace(/[/\\]feature\.md$/i, '')
+    : featurePath.replace(/[/\\]+$/, '')
+}
+
 // Derive feature directory and prefix early (needed for ledger writes before metrics agent runs)
-const featureDir  = featurePath.replace(/\/[^/]+$/, '')
+const featureDir  = deriveFeatureDir(featurePath)
 const prefixMatch = featureDir.match(/([A-Z]+-\d+)/)
 const prefix      = prefixMatch ? prefixMatch[1] : 'FTR-000'
 
@@ -101,15 +78,11 @@ phase('Work Breakdown')
 const tokenLedger = []
 
 log(`Running generate-work-breakdown for ${featurePath}`)
-await appendLedgerEntry(featureDir, prefix, {
-  agent: 'generate-work-breakdown:phase2',
-  phase: 'phase2',
-  model: 'haiku',
-  status: 'running',
-  phase_delta_tokens: 0,
-  started_at: '__TS__',
-  completed_at: null,
-})
+const wbKey = 'generate-work-breakdown:phase2'
+await agent(
+  `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${featureDir} --prefix ${prefix} --agent ${wbKey} --phase phase2 --model haiku --attempt 1\n\nReturn no output.`,
+  { label: 'ledger-open-generate-work-breakdown', phase: 'Work Breakdown', model: 'haiku' }
+)
 const beforeWB = budget.spent()
 await agent(featurePath, {
   agentType: 'generate-work-breakdown',
@@ -117,11 +90,10 @@ await agent(featurePath, {
   phase:     'Work Breakdown',
 })
 const wbTokens = budget.spent() - beforeWB
-await updateLedgerEntry(featureDir, prefix, 'generate-work-breakdown:phase2', {
-  status: 'done',
-  completed_at: '__TS__',
-  phase_delta_tokens: wbTokens,
-})
+await agent(
+  `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${featureDir} --prefix ${prefix} --agent ${wbKey} --tokens ${wbTokens} --attempt 1\n\nReturn no output.`,
+  { label: 'ledger-close-generate-work-breakdown', phase: 'Work Breakdown', model: 'haiku' }
+)
 tokenLedger.push({ agent: 'generate-work-breakdown', model: 'haiku', phase_delta_tokens: wbTokens })
 log(`generate-work-breakdown done — phase delta: ${wbTokens} tokens`)
 
@@ -129,16 +101,16 @@ log(`generate-work-breakdown done — phase delta: ${wbTokens} tokens`)
 let wbValidatorReport = null
 let validateFailed = false
 let validateExitCode = null
-await appendLedgerEntry(featureDir, prefix, {
-  agent: 'wb-validate:phase2',
-  phase: 'phase2', model: 'haiku', status: 'running',
-  phase_delta_tokens: 0, started_at: '__TS__', completed_at: null,
-})
+const wbValidateKey = 'wb-validate:phase2'
+await agent(
+  `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${featureDir} --prefix ${prefix} --agent ${wbValidateKey} --phase phase2 --model haiku --attempt 1\n\nReturn no output.`,
+  { label: 'ledger-open-wb-validate', phase: 'Work Breakdown', model: 'haiku' }
+)
 const beforeValidate = budget.spent()
 try {
   const validateWrapper = await agent(
     `Run this command and return the result as structured output:\n` +
-    `node .claude/scripts/wb-validate.js "${featureDir}/${prefix}-Work-Breakdown.json" "${featureDir}/${prefix}-Requirements.md"\n\n` +
+    `ai-toolkit run-asset scripts/wb-validate.js -- "${featureDir}/${prefix}-Work-Breakdown.json" "${featureDir}/${prefix}-Requirements.md"\n\n` +
     `Capture exitCode (integer), stdout (string), stderr (string). Return all three.`,
     {
       label:  'wb-validate',
@@ -173,20 +145,14 @@ try {
   if (validateWrapper.exitCode === 1 && wbValidatorReport.valid) {
     throw new Error('Inconsistent wb-validate result: exit 1 with valid=true')
   }
-  await updateLedgerEntry(featureDir, prefix, 'wb-validate:phase2', {
-    status: 'done', completed_at: '__TS__',
-    phase_delta_tokens: budget.spent() - beforeValidate,
-  })
 } catch (err) {
   validateFailed = true
-  await updateLedgerEntry(featureDir, prefix, 'wb-validate:phase2', {
-    status: 'failed', completed_at: '__TS__',
-    phase_delta_tokens: budget.spent() - beforeValidate,
-    error_summary: normalizeError(err),
-    exit_code: err._exitCode ?? validateExitCode ?? null,
-  })
 }
 const validateTokens = budget.spent() - beforeValidate
+await agent(
+  `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${featureDir} --prefix ${prefix} --agent ${wbValidateKey} --tokens ${validateTokens} --attempt 1\n\nReturn no output.`,
+  { label: 'ledger-close-wb-validate', phase: 'Work Breakdown', model: 'haiku' }
+)
 const wbValidatorPassed = !validateFailed && wbValidatorReport !== null
   && wbValidatorReport.valid === true && wbValidatorReport.errors.length === 0
 log(`wb-validate: ${wbValidatorPassed ? 'passed' : 'failed/errors'} — ${validateTokens} tokens`)
@@ -195,18 +161,14 @@ log(`wb-validate: ${wbValidatorPassed ? 'passed' : 'failed/errors'} — ${valida
 let semanticResult = null
 let semanticFailed = false
 let semanticTokens = 0
+const semanticKey = 'validate-work-breakdown-semantic:phase2'
 if (!wbValidatorPassed) {
-  await appendLedgerEntry(featureDir, prefix, {
-    agent: 'validate-work-breakdown-semantic:phase2',
-    phase: 'phase2', model: 'sonnet', status: 'skipped',
-    phase_delta_tokens: 0, started_at: '__TS__', completed_at: '__TS__',
-  })
+  log('validate-work-breakdown-semantic: skipped (wb-validate did not pass)')
 } else {
-  await appendLedgerEntry(featureDir, prefix, {
-    agent: 'validate-work-breakdown-semantic:phase2',
-    phase: 'phase2', model: 'sonnet', status: 'running',
-    phase_delta_tokens: 0, started_at: '__TS__', completed_at: null,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${featureDir} --prefix ${prefix} --agent ${semanticKey} --phase phase2 --model sonnet --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-open-semantic-validator', phase: 'Work Breakdown', model: 'haiku' }
+  )
   const beforeSemantic = budget.spent()
   try {
     semanticResult = await agent(
@@ -218,18 +180,14 @@ if (!wbValidatorPassed) {
         schema:    WB_SEMANTIC_SCHEMA,
       }
     )
-    semanticTokens = budget.spent() - beforeSemantic
-    await updateLedgerEntry(featureDir, prefix, 'validate-work-breakdown-semantic:phase2', {
-      status: 'done', completed_at: '__TS__', phase_delta_tokens: semanticTokens,
-    })
   } catch (err) {
     semanticFailed = true
-    semanticTokens = budget.spent() - beforeSemantic
-    await updateLedgerEntry(featureDir, prefix, 'validate-work-breakdown-semantic:phase2', {
-      status: 'failed', completed_at: '__TS__', phase_delta_tokens: semanticTokens,
-      error_summary: normalizeError(err), exit_code: null,
-    })
   }
+  semanticTokens = budget.spent() - beforeSemantic
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${featureDir} --prefix ${prefix} --agent ${semanticKey} --tokens ${semanticTokens} --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-close-semantic-validator', phase: 'Work Breakdown', model: 'haiku' }
+  )
 }
 log(`semantic validator: ${semanticFailed ? 'failed' : semanticResult ? 'done' : 'skipped'}`)
 
@@ -237,23 +195,19 @@ log(`semantic validator: ${semanticFailed ? 'failed' : semanticResult ? 'done' :
 const canRender = wbValidatorPassed && !semanticFailed
 let renderFailed = false
 let renderResult = null
+const wbRenderKey = 'wb-render:phase2'
 if (!canRender) {
-  await appendLedgerEntry(featureDir, prefix, {
-    agent: 'wb-render:phase2',
-    phase: 'phase2', model: 'haiku', status: 'skipped',
-    phase_delta_tokens: 0, started_at: '__TS__', completed_at: '__TS__',
-  })
+  log('wb-render: skipped (wb-validate or semantic validator did not pass)')
 } else {
-  await appendLedgerEntry(featureDir, prefix, {
-    agent: 'wb-render:phase2',
-    phase: 'phase2', model: 'haiku', status: 'running',
-    phase_delta_tokens: 0, started_at: '__TS__', completed_at: null,
-  })
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger open --dir ${featureDir} --prefix ${prefix} --agent ${wbRenderKey} --phase phase2 --model haiku --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-open-wb-render', phase: 'Work Breakdown', model: 'haiku' }
+  )
   const beforeRender = budget.spent()
   try {
     renderResult = await agent(
       `Run this command and return the result as structured output:\n` +
-      `node .claude/scripts/wb-render.js "${featureDir}/${prefix}-Work-Breakdown.json" "${prefix}"\n\n` +
+      `ai-toolkit run-asset scripts/wb-render.js -- "${featureDir}/${prefix}-Work-Breakdown.json" "${prefix}"\n\n` +
       `Capture exitCode (integer), stdout (string), stderr (string).\n` +
       `Resolve the expected output paths:\n` +
       `  markdownPath = "${featureDir}/${prefix}-Work-Breakdown.md"\n` +
@@ -291,20 +245,15 @@ if (!canRender) {
         { _exitCode: renderResult.exitCode }
       )
     }
-    await updateLedgerEntry(featureDir, prefix, 'wb-render:phase2', {
-      status: 'done', completed_at: '__TS__',
-      phase_delta_tokens: budget.spent() - beforeRender,
-    })
   } catch (err) {
     renderFailed = true
-    await updateLedgerEntry(featureDir, prefix, 'wb-render:phase2', {
-      status: 'failed', completed_at: '__TS__',
-      phase_delta_tokens: budget.spent() - beforeRender,
-      error_summary: normalizeError(err),
-      exit_code: err._exitCode ?? renderResult?.exitCode ?? null,
-    })
   }
-  tokenLedger.push({ agent: 'wb-render', model: 'haiku', phase_delta_tokens: budget.spent() - beforeRender })
+  const renderTokens = budget.spent() - beforeRender
+  await agent(
+    `Run this shell command via Bash. If the --dir path contains spaces, enclose it in double quotes.\n\nai-toolkit ledger close --dir ${featureDir} --prefix ${prefix} --agent ${wbRenderKey} --tokens ${renderTokens} --attempt 1\n\nReturn no output.`,
+    { label: 'ledger-close-wb-render', phase: 'Work Breakdown', model: 'haiku' }
+  )
+  tokenLedger.push({ agent: 'wb-render', model: 'haiku', phase_delta_tokens: renderTokens })
 }
 
 tokenLedger.push({ agent: 'wb-validate', model: 'haiku', phase_delta_tokens: validateTokens })