@dtlabs/ai-toolkit 0.8.0 → 0.9.0

package/.claude/workflows/pm-phase1.js

@@ -13,18 +13,30 @@ export const meta = {
 
 async function appendLedgerEntry(featureDir, prefix, entry) {
   const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
-  const entryJson = JSON.stringify(entry)
+  // 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\n1. Read the file. If it does not exist or cannot be parsed as a JSON array, start with [].\n2. Push this object onto the array: ${entryJson}\n3. Write the full array back (JSON, 2-space indent). Return no output.`,
+    `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`
-  const updatesJson = JSON.stringify(updates)
+  // 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\n1. Read the file. If it does not exist or cannot be parsed as a JSON array, do nothing.\n2. Search from the end for the last entry where agent === "${agentKey}".\n3. If found, merge these fields into that entry: ${updatesJson}\n4. Write the full array back (JSON, 2-space indent). Return no output.\n5. If not found, do nothing.`,
+    `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' }
   )
 }
@@ -108,14 +120,13 @@ const errors      = []
 
 if (discoveryResult.needs_requirements) {
   const reqKey = 'generate-requirements:phase1'
-  const reqStartedAt = new Date().toISOString()
   await appendLedgerEntry(feature_dir, prefix, {
     agent: reqKey,
     phase: 'phase1',
     model: 'haiku',
     status: 'running',
     phase_delta_tokens: 0,
-    started_at: reqStartedAt,
+    started_at: '__TS__',
     completed_at: null,
   })
   const beforeReq = budget.spent()
@@ -123,7 +134,7 @@ if (discoveryResult.needs_requirements) {
   const reqTokens = budget.spent() - beforeReq
   await updateLedgerEntry(feature_dir, prefix, reqKey, {
     status: 'done',
-    completed_at: new Date().toISOString(),
+    completed_at: '__TS__',
     phase_delta_tokens: reqTokens,
   })
   tokenLedger.push({ agent: 'generate-requirements', model: 'haiku', phase_delta_tokens: reqTokens })
@@ -137,14 +148,13 @@ phase('Tech-Spec')
 
 if (discoveryResult.needs_tech_spec) {
   const specKey = 'generate-tech-spec:phase1'
-  const specStartedAt = new Date().toISOString()
   await appendLedgerEntry(feature_dir, prefix, {
     agent: specKey,
     phase: 'phase1',
     model: 'haiku',
     status: 'running',
     phase_delta_tokens: 0,
-    started_at: specStartedAt,
+    started_at: '__TS__',
     completed_at: null,
   })
   const beforeSpec = budget.spent()
@@ -152,7 +162,7 @@ if (discoveryResult.needs_tech_spec) {
   const specTokens = budget.spent() - beforeSpec
   await updateLedgerEntry(feature_dir, prefix, specKey, {
     status: 'done',
-    completed_at: new Date().toISOString(),
+    completed_at: '__TS__',
     phase_delta_tokens: specTokens,
   })
   tokenLedger.push({ agent: 'generate-tech-spec', model: 'haiku', phase_delta_tokens: specTokens })
@@ -171,14 +181,13 @@ 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}`
-  const valStartedAt = new Date().toISOString()
   await appendLedgerEntry(feature_dir, prefix, {
     agent: valKey,
     phase: 'phase1',
     model: 'haiku',
     status: 'running',
     phase_delta_tokens: 0,
-    started_at: valStartedAt,
+    started_at: '__TS__',
     completed_at: null,
   })
   const beforeVal = budget.spent()
@@ -186,7 +195,7 @@ for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
   const valTokens = budget.spent() - beforeVal
   await updateLedgerEntry(feature_dir, prefix, valKey, {
     status: 'done',
-    completed_at: new Date().toISOString(),
+    completed_at: '__TS__',
     phase_delta_tokens: valTokens,
   })
   tokenLedger.push({ agent: `validate-feature-docs (cycle ${cycle})`, model: 'haiku', phase_delta_tokens: valTokens })

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

@@ -13,18 +13,30 @@ export const meta = {
 
 async function appendLedgerEntry(featureDir, prefix, entry) {
   const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
-  const entryJson = JSON.stringify(entry)
+  // 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\n1. Read the file. If it does not exist or cannot be parsed as a JSON array, start with [].\n2. Push this object onto the array: ${entryJson}\n3. Write the full array back (JSON, 2-space indent). Return no output.`,
+    `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: 'Work Breakdown', model: 'haiku' }
   )
 }
 
 async function updateLedgerEntry(featureDir, prefix, agentKey, updates) {
   const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
-  const updatesJson = JSON.stringify(updates)
+  // 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\n1. Read the file. If it does not exist or cannot be parsed as a JSON array, do nothing.\n2. Search from the end for the last entry where agent === "${agentKey}".\n3. If found, merge these fields into that entry: ${updatesJson}\n4. Write the full array back (JSON, 2-space indent). Return no output.\n5. If not found, do nothing.`,
+    `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' }
   )
 }
@@ -45,14 +57,13 @@ phase('Work Breakdown')
 const tokenLedger = []
 
 log(`Running generate-work-breakdown for ${featurePath}`)
-const wbStartedAt = new Date().toISOString()
 await appendLedgerEntry(featureDir, prefix, {
   agent: 'generate-work-breakdown:phase2',
   phase: 'phase2',
   model: 'haiku',
   status: 'running',
   phase_delta_tokens: 0,
-  started_at: wbStartedAt,
+  started_at: '__TS__',
   completed_at: null,
 })
 const beforeWB = budget.spent()
@@ -64,7 +75,7 @@ await agent(featurePath, {
 const wbTokens = budget.spent() - beforeWB
 await updateLedgerEntry(featureDir, prefix, 'generate-work-breakdown:phase2', {
   status: 'done',
-  completed_at: new Date().toISOString(),
+  completed_at: '__TS__',
   phase_delta_tokens: wbTokens,
 })
 tokenLedger.push({ agent: 'generate-work-breakdown', model: 'haiku', phase_delta_tokens: wbTokens })

package/.claude/workflows/pm-phase3.js

@@ -11,6 +11,40 @@ export const meta = {
   ],
 }
 
+// ── Ledger helper functions ───────────────────────────────────────────────────
+// Route all ledger I/O through agent() — fs and require() are not available in
+// the Workflow runtime. Mirrors the pattern used by pm-phase2.js.
+
+async function appendLedgerEntry(featureDir, prefix, entry) {
+  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
+  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: 'Implementation', model: 'haiku' }
+  )
+}
+
+async function updateLedgerEntry(featureDir, prefix, agentKey, updates) {
+  const ledgerPath = `${featureDir}/${prefix}-token-ledger.json`
+  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: 'Implementation', model: 'haiku' }
+  )
+}
+
+// ── Parse args ────────────────────────────────────────────────────────────────
+
 // args: "<path-to-feature.md> --branch feature/FTR-NNN-slug"
 const argStr      = typeof args === 'string' ? args : ''
 const featurePath = argStr.trim().split(/\s+/)[0]
@@ -31,10 +65,13 @@ const csvPath     = `${featureDir}/${prefix}-Work-Breakdown.csv`
 
 log(`Reading CSV: ${csvPath}`)
 
+await appendLedgerEntry(featureDir, prefix, { agent: 'read-wb-csv:phase3', phase: 'phase3', model: 'haiku', status: 'running', phase_delta_tokens: 0, started_at: '__TS__', completed_at: null })
+const beforeCsv = budget.spent()
 const csvContent = await agent(
   `Read the file at path: ${csvPath}\nReturn ONLY the raw file contents, nothing else. No explanation, no formatting, no JSON wrapping — just the raw text of the file.`,
   { label: 'read-wb-csv', phase: 'Parse', model: 'haiku' }
 )
+await updateLedgerEntry(featureDir, prefix, 'read-wb-csv:phase3', { status: 'done', completed_at: '__TS__', phase_delta_tokens: budget.spent() - beforeCsv })
 
 // Parse CSV into structured phases — pure JS, no AI
 const rows = csvContent
@@ -148,6 +185,8 @@ const executePhase = async (implPhase) => {
 
     // Step 1 — impl groups in parallel (INFRA / BE / FE)
     if (implPhase.impl_groups.length > 0) {
+      const implKey = `${implPhase.impl_groups.map(g => g.agent_type).join('+')}:${implPhase.phase_id}${reworkCycle > 0 ? ':rework' + reworkCycle : ''}`
+      await appendLedgerEntry(featureDir, prefix, { agent: implKey, phase: 'phase3', model: 'sonnet', status: 'running', phase_delta_tokens: 0, started_at: '__TS__', completed_at: null })
       const beforeImpl = budget.spent()
       await parallel(implPhase.impl_groups.map(group => () =>
         agent(
@@ -160,16 +199,15 @@ const executePhase = async (implPhase) => {
         )
       ))
       const implTokens = budget.spent() - beforeImpl
-      tokenLedger.push({
-        agent: `${implPhase.impl_groups.map(g => g.agent_type).join('+')}:${implPhase.phase_id}${reworkCycle > 0 ? ':rework' + reworkCycle : ''}`,
-        model: 'sonnet',
-        phase_delta_tokens: implTokens,
-      })
+      await updateLedgerEntry(featureDir, prefix, implKey, { status: 'done', completed_at: '__TS__', phase_delta_tokens: implTokens })
+      tokenLedger.push({ agent: implKey, model: 'sonnet', phase_delta_tokens: implTokens })
       log(`Phase ${implPhase.phase_id} impl groups done — ${implTokens} tokens`)
     }
 
     // Step 2 — test groups in parallel (TEST) — after impl groups
     if (implPhase.test_groups.length > 0) {
+      const testKey = `developer-testing:${implPhase.phase_id}${reworkCycle > 0 ? ':rework' + reworkCycle : ''}`
+      await appendLedgerEntry(featureDir, prefix, { agent: testKey, phase: 'phase3', model: 'sonnet', status: 'running', phase_delta_tokens: 0, started_at: '__TS__', completed_at: null })
       const beforeTest = budget.spent()
       await parallel(implPhase.test_groups.map(group => () =>
         agent(
@@ -182,15 +220,14 @@ const executePhase = async (implPhase) => {
         )
       ))
       const testTokens = budget.spent() - beforeTest
-      tokenLedger.push({
-        agent: `developer-testing:${implPhase.phase_id}${reworkCycle > 0 ? ':rework' + reworkCycle : ''}`,
-        model: 'sonnet',
-        phase_delta_tokens: testTokens,
-      })
+      await updateLedgerEntry(featureDir, prefix, testKey, { status: 'done', completed_at: '__TS__', phase_delta_tokens: testTokens })
+      tokenLedger.push({ agent: testKey, model: 'sonnet', phase_delta_tokens: testTokens })
       log(`Phase ${implPhase.phase_id} test groups done — ${testTokens} tokens`)
     }
 
     // Step 3 — review-solution
+    const reviewKey = `review-solution:${implPhase.phase_id}`
+    await appendLedgerEntry(featureDir, prefix, { agent: reviewKey, phase: 'phase3', model: 'sonnet', status: 'running', phase_delta_tokens: 0, started_at: '__TS__', completed_at: null })
     const beforeReview = budget.spent()
     const review = await agent(
       `${featurePath} --scope ${implPhase.phase_id}`,
@@ -202,8 +239,9 @@ const executePhase = async (implPhase) => {
       }
     )
     const reviewTokens = budget.spent() - beforeReview
+    await updateLedgerEntry(featureDir, prefix, reviewKey, { status: 'done', completed_at: '__TS__', phase_delta_tokens: reviewTokens })
     tokenLedger.push({
-      agent: `review-solution:${implPhase.phase_id}`,
+      agent: reviewKey,
       model: 'sonnet',
       phase_delta_tokens: reviewTokens,
     })
@@ -238,16 +276,6 @@ const executePhase = async (implPhase) => {
   }
 
   phasesDone++
-
-  // Persist the cumulative token ledger to disk after every completed phase.
-  // budget.spent() is an in-memory counter — if the workflow is stopped (manual
-  // stop, crash, timeout) before the Actuals phase, all token data would be lost.
-  // Writing the full ledger here means the file always reflects real consumption
-  // up to the last completed phase, recoverable manually or by a resumed run.
-  await agent(
-    `Write the following JSON to ${featureDir}/${prefix}-token-ledger.json (overwrite the file if it exists):\n${JSON.stringify(tokenLedger, null, 2)}`,
-    { label: `persist-ledger:${implPhase.phase_id}`, phase: 'Implementation', model: 'haiku' }
-  )
 }
 
 // Execute waves: phases in the same wave run in parallel, waves are sequential
@@ -285,6 +313,7 @@ log(`Implementation complete — ${phasesDone} phases, ${usPassed.length} US pas
 // contention down to a single centralized run with one consolidated failure report.
 phase('Test')
 
+await appendLedgerEntry(featureDir, prefix, { agent: 'final-test-run', phase: 'phase3', model: 'haiku', status: 'running', phase_delta_tokens: 0, started_at: '__TS__', completed_at: null })
 const beforeTest = budget.spent()
 await agent(
   `Run the full test suite in the repository root and report the result.
@@ -297,6 +326,7 @@ Do NOT fix failing tests — only report them.`,
   { label: 'final-test-run', phase: 'Test', model: 'haiku' }
 )
 const testTokens = budget.spent() - beforeTest
+await updateLedgerEntry(featureDir, prefix, 'final-test-run', { status: 'done', completed_at: '__TS__', phase_delta_tokens: testTokens })
 tokenLedger.push({ agent: 'final-test-run', model: 'haiku', phase_delta_tokens: testTokens })
 log(`Test run complete — ${testTokens} tokens`)
 
@@ -317,6 +347,7 @@ let issuesDeferred = 0
 
 if (issuesOpen > 0 && issuesPath) {
   log(`Remediation: ${issuesOpen} OPEN issues`)
+  await appendLedgerEntry(featureDir, prefix, { agent: 'remediation', phase: 'phase3', model: 'sonnet', status: 'running', phase_delta_tokens: 0, started_at: '__TS__', completed_at: null })
   const beforeRem = budget.spent()
 
   const remResult = await agent(
@@ -339,6 +370,7 @@ Update the Issues Register Status column in place for each resolved/deferred iss
   )
 
   const remTokens = budget.spent() - beforeRem
+  await updateLedgerEntry(featureDir, prefix, 'remediation', { status: 'done', completed_at: '__TS__', phase_delta_tokens: remTokens })
   tokenLedger.push({ agent: 'remediation', model: 'sonnet', phase_delta_tokens: remTokens })
   issuesFixed    = remResult.issues_fixed    || 0
   issuesDeferred = remResult.issues_deferred || 0
@@ -359,6 +391,7 @@ const PR_SCHEMA = {
   required: ['pr_url'],
 }
 
+await appendLedgerEntry(featureDir, prefix, { agent: 'pr-and-registry', phase: 'phase3', model: 'sonnet', status: 'running', phase_delta_tokens: 0, started_at: '__TS__', completed_at: null })
 const beforePR = budget.spent()
 
 const prResult = await agent(
@@ -408,6 +441,7 @@ If the PR creation fails, return { "pr_url": "(PR creation failed)", "registry_u
 )
 
 const prTokens = budget.spent() - beforePR
+await updateLedgerEntry(featureDir, prefix, 'pr-and-registry', { status: 'done', completed_at: '__TS__', phase_delta_tokens: prTokens })
 tokenLedger.push({ agent: 'pr-and-registry', model: 'sonnet', phase_delta_tokens: prTokens })
 log(`PR done: ${prResult.pr_url} — ${prTokens} tokens`)
 
@@ -494,6 +528,7 @@ const ACTUALS_SCHEMA = {
   required: [],
 }
 
+await appendLedgerEntry(featureDir, prefix, { agent: 'write-actuals', phase: 'phase3', model: 'sonnet', status: 'running', phase_delta_tokens: 0, started_at: '__TS__', completed_at: null })
 const beforeActuals = budget.spent()
 
 await agent(
@@ -587,6 +622,7 @@ Return { "token_estimate_path": "<path>", "effort_estimate_path": "<path>" }.`,
 )
 
 const actualsTokens = budget.spent() - beforeActuals
+await updateLedgerEntry(featureDir, prefix, 'write-actuals', { status: 'done', completed_at: '__TS__', phase_delta_tokens: actualsTokens })
 tokenLedger.push({ agent: 'write-actuals', model: 'sonnet', phase_delta_tokens: actualsTokens })
 log(`Actuals written — ${actualsTokens} tokens`)
 

package/CHANGELOG.md

@@ -1,4 +1,19 @@
 ## 0.1.4 (2026-07-21)
+## [0.9.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.8.0...v0.9.0) (2026-08-05)
+
+
+### Features
+
+* **FTR-020:** add initial documentation for Atomic Work Breakdown, Execution Ledger, and Task Checkpoints and Resume ([c5f724a](https://github.com/dtlab-tech/ai-toolkit/commit/c5f724af068e003d36ec196cdec3502fe0c47333))
+
+
+### Bug Fixes
+
+* **pm-phase3:** replace require/fs/execSync with agent()-based ledger helpers ([1166d6f](https://github.com/dtlab-tech/ai-toolkit/commit/1166d6f17e913405ea737e74236742569740cd0a))
+* **pm-phase3:** replace require/fs/execSync with agent()-based ledger helpers ([bf4077c](https://github.com/dtlab-tech/ai-toolkit/commit/bf4077cca28920876185535aa553ec91c6ffc08b))
+* **pm-phase3:** replace require/fs/execSync with agent()-based ledger helpers ([bb4c88d](https://github.com/dtlab-tech/ai-toolkit/commit/bb4c88df20c62db09de327975ab57e045247dc51))
+* **workflows:** remove new Date() from all workflow call sites ([343b604](https://github.com/dtlab-tech/ai-toolkit/commit/343b604dba2d4d0b12e5590c1b5323b2a9e888f2))
+
 ## [0.8.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.7.0...v0.8.0) (2026-08-04)
 
 

package/package.json

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