@girardmedia/bootspring 2.1.0 → 2.1.2

package/cli/build.js

@@ -165,6 +165,10 @@ async function run(args) {
     case 'all':
       return buildLoop(projectRoot, parsedArgs);
 
+    case 'migrate-todo':
+    case 'migrate':
+      return migrateTodoFormat(projectRoot, parsedArgs);
+
     case 'backfill':
     case 'recover':
     case 'hydrate':
@@ -350,7 +354,7 @@ ${c.bold}Phase:${c.reset} ${nextTask.phase || 'MVP'}
 ${c.bold}Source:${c.reset} ${nextTask.source || 'PRD.md'}
 
 ${c.cyan}${c.bold}Tell Claude Code:${c.reset}
-  "Read planning/TASK_QUEUE.md, find ${nextTask.id}, and implement it"
+  "Read planning/TODO.md, find ${nextTask.id}, and implement it"
 
 ${c.dim}When done, run: bootspring build done${c.reset}
 `);
@@ -462,7 +466,7 @@ async function markTaskDone(projectRoot, _args = {}) {
     console.log(`
 ${c.cyan}${c.bold}▶ Next: ${nextTask.title}${c.reset} (${nextTask.id})
 
-${c.bold}Continue building:${c.reset} Read planning/TASK_QUEUE.md, implement ${nextTask.id}
+${c.bold}Continue building:${c.reset} Read planning/TODO.md, implement ${nextTask.id}
 ${c.dim}Then run: bootspring build done${c.reset}
 `);
   } else {
@@ -545,7 +549,7 @@ ${c.bold}Progress:${c.reset} ${stats.completed}/${stats.total} tasks (${Math.rou
 ${c.bold}Git Mode:${c.reset} ${noCommit ? 'Disabled' : noPush ? 'Commit only' : 'Commit + Push'}
 
 ${c.bold}Workflow:${c.reset}
-  1. Read planning/TASK_QUEUE.md, find ${currentTask?.id || 'current task'}
+  1. Read planning/TODO.md, find ${currentTask?.id || 'current task'}
   2. Implement the task
   3. Run: ${c.cyan}bootspring build done${c.reset}${!noCommit ? `
      (Auto-commits: "feat(${currentTask?.id}): ${currentTask?.title?.slice(0, 40) || 'task'}...")${!noPush ? `
@@ -1225,6 +1229,171 @@ ${c.bold}Next steps:${c.reset}
 `);
 }
 
+/**
+ * Extract non-task supplementary content from TASK_QUEUE.md.
+ * Captures context notes, architecture diagrams, integration guidelines,
+ * and any section that isn't the task table or per-task detail blocks.
+ */
+function extractSupplementaryContent(queueContent) {
+  const lines = queueContent.split('\n');
+  const sections = [];
+  let currentSection = null;
+  let inTaskTable = false;
+  let inTaskDetail = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Detect task table (starts with | Position | or | # |)
+    if (/^\|\s*(Position|#)\s*\|/.test(line)) {
+      inTaskTable = true;
+      continue;
+    }
+    // Still in task table (rows starting with |)
+    if (inTaskTable && /^\|/.test(line)) {
+      continue;
+    }
+    if (inTaskTable && !/^\|/.test(line)) {
+      inTaskTable = false;
+    }
+
+    // Detect per-task detail blocks (### task-XXX: or ### bs-XXX:)
+    if (/^###\s+(task-\d+|bs-\d+)\s*:/.test(line)) {
+      inTaskDetail = true;
+      continue;
+    }
+    // End task detail at next ### or ## heading
+    if (inTaskDetail && /^#{2,3}\s+/.test(line) && !/^###\s+(task-\d+|bs-\d+)\s*:/.test(line)) {
+      inTaskDetail = false;
+    }
+    if (inTaskDetail) continue;
+
+    // Skip the header, queue status heading, and generated boilerplate
+    if (/^#\s+.*Implementation Queue/.test(line)) continue;
+    if (/^>\s*(Ordered task queue|Last Updated|Current Version)/.test(line)) continue;
+    if (/^## Queue Status/.test(line)) { inTaskTable = true; continue; }
+    if (/^## Task Details/.test(line)) { inTaskDetail = true; continue; }
+    if (/^\*Generated by/.test(line)) continue;
+    if (/^---$/.test(line.trim())) continue;
+
+    // Detect section headings for supplementary content
+    if (/^##\s+/.test(line) && !/^## (Queue Status|Task Details|Execution Guidelines)/.test(line)) {
+      if (currentSection) sections.push(currentSection);
+      currentSection = { heading: line, lines: [] };
+      continue;
+    }
+
+    // Execution Guidelines is useful — keep it
+    if (/^## Execution Guidelines/.test(line)) {
+      if (currentSection) sections.push(currentSection);
+      currentSection = { heading: line, lines: [] };
+      continue;
+    }
+
+    if (currentSection) {
+      currentSection.lines.push(line);
+    }
+  }
+
+  if (currentSection) sections.push(currentSection);
+
+  // Filter out empty sections and build output
+  const output = sections
+    .filter(s => s.lines.some(l => l.trim().length > 0))
+    .map(s => `${s.heading}\n\n${s.lines.join('\n').trim()}`)
+    .join('\n\n---\n\n');
+
+  return output.trim();
+}
+
+/**
+ * Migrate from TASK_QUEUE.md to TODO.md as single source of truth.
+ */
+async function migrateTodoFormat(projectRoot, args = {}) {
+  const planningDir = path.join(projectRoot, 'planning');
+  const queuePath = path.join(planningDir, 'TASK_QUEUE.md');
+  const todoPath = path.join(planningDir, 'TODO.md');
+  const keepQueue = Boolean(args['keep-queue'] || args.keepQueue);
+
+  console.log(`
+${c.cyan}${c.bold}Migrating to TODO.md as Single Source of Truth${c.reset}
+`);
+
+  // Step 1: Ensure we have build state with tasks
+  let state = buildState.load(projectRoot);
+
+  if (!state || !state.implementationQueue || state.implementationQueue.length === 0) {
+    if (fs.existsSync(queuePath)) {
+      console.log(`${c.dim}No build state — syncing tasks from TASK_QUEUE.md first...${c.reset}`);
+      try {
+        const taskExtractor = require('../core/task-extractor');
+        const result = taskExtractor.syncFromTaskQueue(projectRoot);
+        if (result.total > 0) {
+          console.log(`${c.green}✓${c.reset} Synced ${result.total} tasks from TASK_QUEUE.md`);
+          state = buildState.load(projectRoot);
+        }
+      } catch {
+        // Fall through
+      }
+    }
+
+    if (!state || !state.implementationQueue || state.implementationQueue.length === 0) {
+      console.log(`${c.red}No tasks found. Run 'bootspring seed build' first or ensure TASK_QUEUE.md exists.${c.reset}`);
+      return;
+    }
+  }
+
+  // Step 2: Extract non-task content from TASK_QUEUE.md (context notes, diagrams, guidelines)
+  let supplementaryContent = '';
+  if (fs.existsSync(queuePath)) {
+    const queueContent = fs.readFileSync(queuePath, 'utf-8');
+    supplementaryContent = extractSupplementaryContent(queueContent);
+  }
+
+  // Step 3: Generate enriched TODO.md with full task metadata
+  const planningTemplate = require('../generators/templates/build-planning.template');
+  let todo = planningTemplate.generateTodo(state.implementationQueue, {
+    projectName: state.projectName
+  });
+
+  // Append supplementary content if any was extracted
+  if (supplementaryContent) {
+    todo += `\n---\n\n## Reference (from TASK_QUEUE.md)\n\n${supplementaryContent}\n`;
+  }
+
+  fs.writeFileSync(todoPath, todo);
+
+  const stats = buildState.getStats(projectRoot);
+  console.log(`${c.green}✓${c.reset} Generated TODO.md with ${state.implementationQueue.length} tasks (${stats?.completed || 0} completed)`);
+  if (supplementaryContent) {
+    console.log(`${c.green}✓${c.reset} Preserved supplementary content (context notes, diagrams, guidelines)`);
+  }
+
+  // Step 4: Archive TASK_QUEUE.md unless --keep-queue
+  if (fs.existsSync(queuePath) && !keepQueue) {
+    const archivePath = path.join(planningDir, 'TASK_QUEUE.md.bak');
+    fs.renameSync(queuePath, archivePath);
+    console.log(`${c.green}✓${c.reset} Archived TASK_QUEUE.md → TASK_QUEUE.md.bak`);
+  } else if (fs.existsSync(queuePath) && keepQueue) {
+    console.log(`${c.dim}Kept TASK_QUEUE.md (--keep-queue)${c.reset}`);
+  }
+
+  console.log(`
+${c.green}${c.bold}Migration complete${c.reset}
+
+${c.bold}What changed:${c.reset}
+  - ${c.cyan}planning/TODO.md${c.reset} is now the single source of truth
+  - Task IDs, source, description, acceptance criteria, and status are all inline
+  - Non-task content (context notes, diagrams, guidelines) preserved in Reference section
+  - Build loop reads TODO.md instead of TASK_QUEUE.md
+${!keepQueue && fs.existsSync(path.join(planningDir, 'TASK_QUEUE.md.bak')) ? `  - Old TASK_QUEUE.md archived as TASK_QUEUE.md.bak
+` : ''}
+${c.bold}Next steps:${c.reset}
+  Run ${c.cyan}bootspring build status${c.reset} to verify
+  Run ${c.cyan}bootspring build next${c.reset} to continue building
+`);
+}
+
 /**
  * Show help
  */
@@ -1252,6 +1421,7 @@ ${c.bold}Commands:${c.reset}
   ${c.cyan}bootspring build status${c.reset}    View detailed progress
   ${c.cyan}bootspring build task${c.reset}      View current task details
   ${c.cyan}bootspring build plan${c.reset}      View the full master plan
+  ${c.cyan}bootspring build migrate-todo${c.reset}  Migrate TASK_QUEUE.md → TODO.md (single source of truth)
   ${c.cyan}bootspring build backfill${c.reset}  Recover preseed + SEED + TASK_QUEUE artifacts
   ${c.cyan}bootspring build reset${c.reset}     Start over
 

package/generators/templates/agents.template.js

@@ -52,7 +52,7 @@ function generate(config) {
   sections.push('');
   sections.push('This loops through all tasks:');
   sections.push('1. Run `bootspring build task` (current task comes from `planning/BUILD_STATE.json`)');
-  sections.push('2. Read that task\'s acceptance criteria in `planning/TASK_QUEUE.md`');
+  sections.push('2. Read that task\'s acceptance criteria in `planning/TODO.md`');
   sections.push('3. Implement and validate the task');
   sections.push('4. Run `bootspring build done` (auto-queues next)');
   sections.push('');
@@ -153,8 +153,7 @@ function generatePlanningAgents(_config) {
   sections.push('');
   sections.push('| File | Purpose |');
   sections.push('|------|---------|');
-  sections.push('| `TASK_QUEUE.md` | Ordered task queue and acceptance criteria |');
-  sections.push('| `TODO.md` | Full task checklist |');
+  sections.push('| `TODO.md` | **Source of truth** — task checklist with acceptance criteria |');
   sections.push('| `BUILD_STATE.json` | Build state and current task ID (do not edit) |');
   sections.push('| `CONTEXT.md` | Build context summary |');
   sections.push('');
@@ -162,7 +161,7 @@ function generatePlanningAgents(_config) {
   sections.push('## Workflow');
   sections.push('');
   sections.push('1. Run `bootspring build task` to identify the current task ID');
-  sections.push('2. Read the matching section in `TASK_QUEUE.md` for acceptance criteria');
+  sections.push('2. Read the matching task in `TODO.md` for acceptance criteria');
   sections.push('3. Implement in the main codebase (not here)');
   sections.push('4. Ensure acceptance criteria are met');
   sections.push('5. Run `npm run lint && npm run test`');

package/generators/templates/build-planning.template.js

@@ -93,7 +93,7 @@ Run \`bootspring build task\` to get the current \`in_progress\` task from \`BUI
 ## Workflow
 
 1. Run \`bootspring build task\` to identify the current task ID
-2. Read the matching section in \`TASK_QUEUE.md\` for acceptance criteria
+2. Read the matching task in \`TODO.md\` for acceptance criteria
 3. Implement in the main codebase (not in this folder)
 4. Ensure acceptance criteria are met
 5. Run quality checks: \`npm run lint && npm run test\`
@@ -104,8 +104,7 @@ Run \`bootspring build task\` to get the current \`in_progress\` task from \`BUI
 
 | File | Purpose |
 |------|---------|
-| \`TASK_QUEUE.md\` | Ordered task queue and acceptance criteria |
-| \`TODO.md\` | Full task checklist |
+| \`TODO.md\` | **Source of truth** — task checklist with acceptance criteria |
 | \`BUILD_STATE.json\` | Build state and current task ID (do not edit directly) |
 | \`CONTEXT.md\` | Build context summary |
 
@@ -254,7 +253,19 @@ function generateTodo(tasks, options = {}) {
 
   let content = `# ${projectName} - Build Todo
 
-> Checklist for autonomous build completion
+> Single source of truth for autonomous build execution
+> Updated: ${new Date().toISOString().split('T')[0]}
+
+---
+
+## Program Status
+
+| Metric | Value |
+|---|---:|
+| Total Tasks | ${tasks.length} |
+| Completed | ${tasks.filter(t => t.status === 'completed').length} |
+| Remaining | ${tasks.filter(t => t.status === 'pending').length} |
+| In Progress | ${tasks.filter(t => t.status === 'in_progress').length} |
 
 ---
 
@@ -265,17 +276,42 @@ function generateTodo(tasks, options = {}) {
     const total = phaseTasks.length;
     const percent = total > 0 ? Math.round((completed / total) * 100) : 0;
 
-    content += `## ${formatPhaseName(phaseName)} (${percent}%)
+    content += `## ${formatPhaseName(phaseName)} (${completed}/${total} — ${percent}%)
 
 `;
 
     for (const task of phaseTasks) {
       const checkbox = task.status === 'completed' ? '[x]' : '[ ]';
-      content += `- ${checkbox} ${task.title}\n`;
+      const statusTag = task.status === 'completed' ? ' (`completed`)' :
+        task.status === 'in_progress' ? ' (`in_progress`)' :
+        task.status === 'blocked' ? ' (`blocked`)' :
+        task.status === 'skipped' ? ' (`skipped`)' : '';
+      content += `- ${checkbox} \`${task.id}\` ${task.title}${statusTag}\n`;
+
+      // Source traceability
+      if (task.source) {
+        const sourceStr = task.sourceSection
+          ? `${task.source} (${task.sourceSection})`
+          : task.source;
+        content += `  - **Source:** ${sourceStr}\n`;
+      }
+
+      // Description
+      if (task.description) {
+        content += `  - **Description:** ${task.description}\n`;
+      }
+
+      // Complexity and dependencies
+      if (task.estimatedComplexity && task.estimatedComplexity !== 'medium') {
+        content += `  - **Complexity:** ${task.estimatedComplexity}\n`;
+      }
+      if (task.dependencies && task.dependencies.length > 0) {
+        content += `  - **Dependencies:** ${task.dependencies.join(', ')}\n`;
+      }
 
-      // Add acceptance criteria as sub-items
+      // Acceptance criteria as sub-items (all of them — this is the source of truth)
       if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
-        for (const criteria of task.acceptanceCriteria.slice(0, 3)) {
+        for (const criteria of task.acceptanceCriteria) {
           const subCheckbox = task.status === 'completed' ? '[x]' : '[ ]';
           content += `  - ${subCheckbox} ${criteria}\n`;
         }
@@ -285,18 +321,7 @@ function generateTodo(tasks, options = {}) {
     content += '\n---\n\n';
   }
 
-  content += `## Progress Summary
-
-| Metric | Value |
-|--------|-------|
-| Total Tasks | ${tasks.length} |
-| Completed | ${tasks.filter(t => t.status === 'completed').length} |
-| Remaining | ${tasks.filter(t => t.status === 'pending').length} |
-| In Progress | ${tasks.filter(t => t.status === 'in_progress').length} |
-
----
-
-*Updated: ${new Date().toISOString()}*
+  content += `*Updated: ${new Date().toISOString()}*
 `;
 
   return content;
@@ -643,27 +668,28 @@ function updateFromState(projectRoot, state) {
 
   const tasks = state.implementationQueue;
   const planningDir = path.join(projectRoot, 'planning');
-  const queuePath = path.join(planningDir, 'TASK_QUEUE.md');
-  const existingQueue = fs.existsSync(queuePath)
-    ? fs.readFileSync(queuePath, 'utf-8')
-    : '';
-  const existingVersionMatch = existingQueue.match(/\*\*Current Version:\*\*\s*([^\n]+)/i)
-    || existingQueue.match(/>\s*Current Version:\s*([^\n]+)/i);
-  const queueVersion = existingVersionMatch
-    ? existingVersionMatch[1].trim()
-    : DEFAULT_QUEUE_VERSION;
-
-  // Regenerate TODO.md with current status
+
+  // Regenerate TODO.md — the single source of truth
   const todo = generateTodo(tasks, { projectName: state.projectName });
   fs.writeFileSync(path.join(planningDir, 'TODO.md'), todo);
 
-  // Regenerate TASK_QUEUE.md
-  const queue = generateImplementationQueue(tasks, {
-    projectName: state.projectName,
-    lastUpdated: new Date().toISOString().split('T')[0],
-    queueVersion
-  });
-  fs.writeFileSync(queuePath, queue);
+  // Legacy: also regenerate TASK_QUEUE.md if it already exists (backward compat)
+  const queuePath = path.join(planningDir, 'TASK_QUEUE.md');
+  if (fs.existsSync(queuePath)) {
+    const existingQueue = fs.readFileSync(queuePath, 'utf-8');
+    const existingVersionMatch = existingQueue.match(/\*\*Current Version:\*\*\s*([^\n]+)/i)
+      || existingQueue.match(/>\s*Current Version:\s*([^\n]+)/i);
+    const queueVersion = existingVersionMatch
+      ? existingVersionMatch[1].trim()
+      : DEFAULT_QUEUE_VERSION;
+
+    const queue = generateImplementationQueue(tasks, {
+      projectName: state.projectName,
+      lastUpdated: new Date().toISOString().split('T')[0],
+      queueVersion
+    });
+    fs.writeFileSync(queuePath, queue);
+  }
 }
 
 module.exports = {

package/generators/templates/claude.template.js

@@ -33,7 +33,7 @@ function generate(config) {
   sections.push('### Before Writing ANY Code');
   sections.push('1. Read `planning/MASTER_PLAN.md` - Overall vision and phases');
   sections.push('2. Run `bootspring build task` - Current task ID comes from `planning/BUILD_STATE.json`');
-  sections.push('3. Read `planning/TASK_QUEUE.md` - Acceptance criteria for that task ID');
+  sections.push('3. Read `planning/TODO.md` - Find the task ID and its acceptance criteria');
   sections.push('4. Read `planning/CONTEXT.md` - Current build context');
   sections.push('5. Understand the acceptance criteria before implementing');
   sections.push('');
@@ -53,9 +53,8 @@ function generate(config) {
   sections.push('| File | Purpose | When to Read |');
   sections.push('|------|---------|--------------|');
   sections.push('| `MASTER_PLAN.md` | Overall vision, phases, success criteria | **Always read first** |');
-  sections.push('| `TASK_QUEUE.md` | All tasks with acceptance criteria (look up current task ID here) | **Before each task** |');
+  sections.push('| `TODO.md` | **Source of truth** — all tasks with acceptance criteria | **Before each task** |');
   sections.push('| `CONTEXT.md` | Current build context and decisions | Before each task |');
-  sections.push('| `TODO.md` | Checkbox task list | Update after completing |');
   sections.push('| `BUILD_STATE.json` | Machine state - source of current task ID | Reference only |');
   sections.push('');
   sections.push('---');
@@ -231,7 +230,7 @@ function generate(config) {
   sections.push('│         ↓                                                   │');
   sections.push('│  bootspring build task → get in_progress task ID            │');
   sections.push('│         ↓                                                   │');
-  sections.push('│  Read planning/TASK_QUEUE.md for acceptance criteria         │');
+  sections.push('│  Read planning/TODO.md for acceptance criteria               │');
   sections.push('│         ↓                                                   │');
   sections.push('│  Implement task (meet acceptance criteria)                  │');
   sections.push('│         ↓                                                   │');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@girardmedia/bootspring",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Thin client for Bootspring cloud MCP, hosted agents, and paywalled workflow intelligence",
   "keywords": [
     "ai",