specsmd 0.0.0-dev.78 → 0.0.0-dev.79

package/flows/fire/agents/builder/skills/run-execute/scripts/{complete-run.js → complete-run.cjs}

@@ -5,15 +5,15 @@
  *
  * Supports both single and batch/wide runs.
  *
- * For single runs: Completes the run and clears active_run.
+ * For single runs: Completes the run and removes from runs.active[].
  * For batch/wide runs:
  *   - --complete-item: Marks current work item done, moves to next
  *   - --complete-run: Marks all items done and finalizes entire run
  *
  * Usage:
- *   Complete current item:  node complete-run.js <rootPath> <runId> --complete-item [options]
- *   Complete entire run:    node complete-run.js <rootPath> <runId> --complete-run [options]
- *   Complete (single/auto): node complete-run.js <rootPath> <runId> [options]
+ *   Complete current item:  node complete-run.cjs <rootPath> <runId> --complete-item [options]
+ *   Complete entire run:    node complete-run.cjs <rootPath> <runId> --complete-run [options]
+ *   Complete (single/auto): node complete-run.cjs <rootPath> <runId> [options]
  *
  * Options:
  *   --files-created=JSON   - JSON array of {path, purpose}
@@ -102,6 +102,128 @@ function validateFireProject(rootPath, runId) {
   return { statePath, runPath, runLogPath };
 }
 
+// =============================================================================
+// Frontmatter Helpers
+// =============================================================================
+
+/**
+ * Parse YAML frontmatter from markdown content.
+ * Returns { frontmatter: object, body: string } or null if no frontmatter.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  try {
+    const frontmatter = yaml.parse(match[1]);
+    const body = content.slice(match[0].length);
+    return { frontmatter, body };
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Reconstruct markdown content from frontmatter and body.
+ */
+function buildMarkdownWithFrontmatter(frontmatter, body) {
+  return `---\n${yaml.stringify(frontmatter)}---${body}`;
+}
+
+// =============================================================================
+// Markdown Frontmatter Sync
+// =============================================================================
+
+/**
+ * Update work item markdown file frontmatter with new status.
+ */
+function updateWorkItemMarkdown(rootPath, intentId, workItemId, status, runId, completedAt) {
+  const filePath = path.join(rootPath, '.specs-fire', 'intents', intentId, 'work-items', `${workItemId}.md`);
+
+  if (!fs.existsSync(filePath)) {
+    // File doesn't exist - not an error, just skip
+    return false;
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const parsed = parseFrontmatter(content);
+
+    if (!parsed) {
+      // No valid frontmatter - skip
+      return false;
+    }
+
+    // Update frontmatter fields
+    parsed.frontmatter.status = status;
+    if (runId) parsed.frontmatter.run_id = runId;
+    if (completedAt && status === 'completed') {
+      parsed.frontmatter.completed_at = completedAt;
+    }
+
+    const newContent = buildMarkdownWithFrontmatter(parsed.frontmatter, parsed.body);
+    fs.writeFileSync(filePath, newContent);
+    return true;
+  } catch (err) {
+    // Log but don't fail - markdown sync is best-effort
+    console.error(`Warning: Could not update work item markdown ${filePath}: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Update intent brief.md frontmatter based on work item statuses.
+ */
+function updateIntentMarkdown(rootPath, intentId, state) {
+  const filePath = path.join(rootPath, '.specs-fire', 'intents', intentId, 'brief.md');
+
+  if (!fs.existsSync(filePath)) {
+    return false;
+  }
+
+  try {
+    // Determine intent status from its work items
+    const intent = state.intents?.find(i => i.id === intentId);
+    if (!intent || !Array.isArray(intent.work_items)) {
+      return false;
+    }
+
+    const allCompleted = intent.work_items.every(wi => wi.status === 'completed');
+    const anyInProgress = intent.work_items.some(wi => wi.status === 'in_progress');
+
+    let newStatus = 'pending';
+    if (allCompleted) {
+      newStatus = 'completed';
+    } else if (anyInProgress || intent.work_items.some(wi => wi.status === 'completed')) {
+      newStatus = 'in_progress';
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const parsed = parseFrontmatter(content);
+
+    if (!parsed) {
+      return false;
+    }
+
+    // Only update if status actually changed
+    if (parsed.frontmatter.status === newStatus) {
+      return false;
+    }
+
+    parsed.frontmatter.status = newStatus;
+    if (allCompleted) {
+      parsed.frontmatter.completed_at = new Date().toISOString();
+    }
+
+    const newContent = buildMarkdownWithFrontmatter(parsed.frontmatter, parsed.body);
+    fs.writeFileSync(filePath, newContent);
+    return true;
+  } catch (err) {
+    console.error(`Warning: Could not update intent markdown ${filePath}: ${err.message}`);
+    return false;
+  }
+}
+
 // =============================================================================
 // State Operations
 // =============================================================================
@@ -140,6 +262,10 @@ function writeState(statePath, state) {
 // Run Log Operations
 // =============================================================================
 
+/**
+ * Update run.md using proper YAML parsing instead of fragile regex.
+ * This ensures frontmatter updates work regardless of field order or formatting.
+ */
 function updateRunLog(runLogPath, activeRun, params, completedTime, isFullCompletion) {
   let content;
   try {
@@ -152,35 +278,62 @@ function updateRunLog(runLogPath, activeRun, params, completedTime, isFullComple
     );
   }
 
-  // If full completion, update run status
+  // Parse frontmatter using YAML (robust approach)
+  const parsed = parseFrontmatter(content);
+  if (!parsed) {
+    throw fireError(
+      'Invalid run.md format - no valid YAML frontmatter found.',
+      'COMPLETE_032',
+      'Ensure run.md has valid ---\\n...\\n--- frontmatter.'
+    );
+  }
+
+  let { frontmatter, body } = parsed;
+
+  // Update frontmatter fields
   if (isFullCompletion) {
-    content = content.replace(/status: in_progress/, 'status: completed');
-    content = content.replace(/completed: null/, `completed: ${completedTime}`);
+    frontmatter.status = 'completed';
+    frontmatter.completed = completedTime;
   }
 
-  // Update work items status in frontmatter
+  frontmatter.current_item = activeRun.current_item || null;
+
+  // Update work_items array in frontmatter
   if (activeRun.work_items && Array.isArray(activeRun.work_items)) {
-    for (const item of activeRun.work_items) {
-      // Update status in YAML frontmatter
-      const statusPattern = new RegExp(`(id: ${item.id}\\n\\s+intent: [^\\n]+\\n\\s+mode: [^\\n]+\\n\\s+status: )(\\w+)`);
-      content = content.replace(statusPattern, `$1${item.status}`);
-
-      // Update status in markdown body
-      const bodyPattern = new RegExp(`(\\*\\*${item.id}\\*\\* \\([^)]+\\) — )(\\w+)`);
-      content = content.replace(bodyPattern, `$1${item.status}`);
-    }
+    frontmatter.work_items = activeRun.work_items.map(item => ({
+      id: item.id,
+      intent: item.intent,
+      mode: item.mode,
+      status: item.status,
+    }));
+  }
+
+  // Update markdown body sections
+  // Update Work Items section
+  if (activeRun.work_items && Array.isArray(activeRun.work_items)) {
+    const workItemsLines = activeRun.work_items.map((item, i) =>
+      `${i + 1}. **${item.id}** (${item.mode}) — ${item.status}`
+    ).join('\n');
 
-    // Update current_item in frontmatter
-    content = content.replace(/current_item: [^\n]+/, `current_item: ${activeRun.current_item || 'none'}`);
+    body = body.replace(
+      /## Work Items\n[\s\S]*?(?=\n## )/,
+      `## Work Items\n${workItemsLines}\n\n`
+    );
 
     // Update Current Item section
     if (activeRun.current_item) {
       const currentItem = activeRun.work_items.find(i => i.id === activeRun.current_item);
       if (currentItem) {
-        content = content.replace(/## Current Item\n[^\n]+/, `## Current Item\n${currentItem.id} (${currentItem.mode})`);
+        body = body.replace(
+          /## Current Item\n[^\n]+/,
+          `## Current Item\n${currentItem.id} (${currentItem.mode})`
+        );
       }
     } else {
-      content = content.replace(/## Current Item\n[^\n]+/, `## Current Item\n(all completed)`);
+      body = body.replace(
+        /## Current Item\n[^\n]+/,
+        `## Current Item\n(all completed)`
+      );
     }
   }
 
@@ -199,14 +352,14 @@ function updateRunLog(runLogPath, activeRun, params, completedTime, isFullComple
       : '(none)';
 
     // Replace placeholder sections
-    content = content.replace('## Files Created\n(none yet)', `## Files Created\n${filesCreatedText}`);
-    content = content.replace('## Files Modified\n(none yet)', `## Files Modified\n${filesModifiedText}`);
-    content = content.replace('## Decisions\n(none yet)', `## Decisions\n${decisionsText}`);
+    body = body.replace('## Files Created\n(none yet)', `## Files Created\n${filesCreatedText}`);
+    body = body.replace('## Files Modified\n(none yet)', `## Files Modified\n${filesModifiedText}`);
+    body = body.replace('## Decisions\n(none yet)', `## Decisions\n${decisionsText}`);
 
     // Add summary if not present
-    if (!content.includes('## Summary')) {
+    if (!body.includes('## Summary')) {
       const itemCount = activeRun.work_items ? activeRun.work_items.length : 1;
-      content += `
+      body += `
 
 ## Summary
 
@@ -220,8 +373,11 @@ function updateRunLog(runLogPath, activeRun, params, completedTime, isFullComple
     }
   }
 
+  // Reconstruct content with updated frontmatter and body
+  const newContent = buildMarkdownWithFrontmatter(frontmatter, body);
+
   try {
-    fs.writeFileSync(runLogPath, content);
+    fs.writeFileSync(runLogPath, newContent);
   } catch (err) {
     throw fireError(
       `Failed to write run log: ${err.message}`,
@@ -248,25 +404,22 @@ function completeCurrentItem(rootPath, runId, params = {}) {
   const { statePath, runLogPath } = validateFireProject(rootPath, runId);
   const state = readState(statePath);
 
-  if (!state.active_run) {
+  // Find run in active runs list
+  const activeRuns = state.runs?.active || [];
+  const runIndex = activeRuns.findIndex(r => r.id === runId);
+
+  if (runIndex === -1) {
     throw fireError(
-      'No active run found in state.yaml.',
+      `Run "${runId}" not found in active runs.`,
       'COMPLETE_040',
       'The run may have already been completed or was never started.'
     );
   }
 
-  if (state.active_run.id !== runId) {
-    throw fireError(
-      `Run ID mismatch. Active run is "${state.active_run.id}" but trying to complete "${runId}".`,
-      'COMPLETE_041',
-      `Complete the active run "${state.active_run.id}" first.`
-    );
-  }
-
+  const activeRun = activeRuns[runIndex];
   const completedTime = new Date().toISOString();
-  const workItems = state.active_run.work_items || [];
-  const currentItemId = state.active_run.current_item;
+  const workItems = activeRun.work_items || [];
+  const currentItemId = activeRun.current_item;
 
   // Find and mark current item as completed
   let currentItemIndex = -1;
@@ -292,17 +445,39 @@ function completeCurrentItem(rootPath, runId, params = {}) {
   for (let i = currentItemIndex + 1; i < workItems.length; i++) {
     if (workItems[i].status === 'pending') {
       workItems[i].status = 'in_progress';
+      workItems[i].current_phase = 'plan';
       nextItem = workItems[i];
       break;
     }
   }
 
-  // Update state
-  state.active_run.work_items = workItems;
-  state.active_run.current_item = nextItem ? nextItem.id : null;
+  // Update active run in list
+  activeRun.work_items = workItems;
+  activeRun.current_item = nextItem ? nextItem.id : null;
+  state.runs.active[runIndex] = activeRun;
 
   // Update run log
-  updateRunLog(runLogPath, state.active_run, completionParams, completedTime, false);
+  updateRunLog(runLogPath, activeRun, completionParams, completedTime, false);
+
+  // Sync markdown frontmatter for completed work item
+  const completedWorkItem = workItems.find(wi => wi.id === currentItemId);
+  if (completedWorkItem) {
+    updateWorkItemMarkdown(
+      rootPath,
+      completedWorkItem.intent,
+      currentItemId,
+      'completed',
+      runId,
+      completedTime
+    );
+    // Update intent status based on its work items
+    updateIntentMarkdown(rootPath, completedWorkItem.intent, state);
+  }
+
+  // Also update next item's markdown to in_progress
+  if (nextItem) {
+    updateWorkItemMarkdown(rootPath, nextItem.intent, nextItem.id, 'in_progress', null, null);
+  }
 
   // Save state
   writeState(statePath, state);
@@ -335,25 +510,32 @@ function completeRun(rootPath, runId, params = {}) {
   const { statePath, runLogPath } = validateFireProject(rootPath, runId);
   const state = readState(statePath);
 
-  if (!state.active_run) {
-    throw fireError(
-      'No active run found in state.yaml.',
-      'COMPLETE_040',
-      'The run may have already been completed or was never started.'
-    );
+  // Initialize runs structure if needed
+  if (!state.runs) {
+    state.runs = { active: [], completed: [] };
+  }
+  if (!Array.isArray(state.runs.active)) {
+    state.runs.active = [];
+  }
+  if (!Array.isArray(state.runs.completed)) {
+    state.runs.completed = [];
   }
 
-  if (state.active_run.id !== runId) {
+  // Find run in active runs list
+  const runIndex = state.runs.active.findIndex(r => r.id === runId);
+
+  if (runIndex === -1) {
     throw fireError(
-      `Run ID mismatch. Active run is "${state.active_run.id}" but trying to complete "${runId}".`,
-      'COMPLETE_041',
-      `Complete the active run "${state.active_run.id}" first.`
+      `Run "${runId}" not found in active runs.`,
+      'COMPLETE_040',
+      'The run may have already been completed or was never started.'
     );
   }
 
+  const activeRun = state.runs.active[runIndex];
   const completedTime = new Date().toISOString();
-  const workItems = state.active_run.work_items || [];
-  const scope = state.active_run.scope || 'single';
+  const workItems = activeRun.work_items || [];
+  const scope = activeRun.scope || 'single';
 
   // Mark all items as completed
   for (const item of workItems) {
@@ -363,11 +545,11 @@ function completeRun(rootPath, runId, params = {}) {
     }
   }
 
-  state.active_run.work_items = workItems;
-  state.active_run.current_item = null;
+  activeRun.work_items = workItems;
+  activeRun.current_item = null;
 
   // Update run log
-  updateRunLog(runLogPath, state.active_run, completionParams, completedTime, true);
+  updateRunLog(runLogPath, activeRun, completionParams, completedTime, true);
 
   // Build completed run record
   const completedRun = {
@@ -378,17 +560,15 @@ function completeRun(rootPath, runId, params = {}) {
       intent: i.intent,
       mode: i.mode,
     })),
+    started: activeRun.started,
     completed: completedTime,
   };
 
-  // Get existing runs history or initialize
-  const existingRuns = state.runs || { completed: [] };
-  const existingCompleted = Array.isArray(existingRuns.completed) ? existingRuns.completed : [];
-
   // Check for duplicate (idempotency)
-  const alreadyRecorded = existingCompleted.some(r => r.id === runId);
+  const alreadyRecorded = state.runs.completed.some(r => r.id === runId);
 
-  // Update work item status in intents
+  // Update work item status in intents (state.yaml)
+  const affectedIntents = new Set();
   if (Array.isArray(state.intents)) {
     for (const workItem of workItems) {
       for (const intent of state.intents) {
@@ -397,6 +577,8 @@ function completeRun(rootPath, runId, params = {}) {
             if (wi.id === workItem.id) {
               wi.status = 'completed';
               wi.run_id = runId;
+              wi.completed_at = completedTime;
+              affectedIntents.add(intent.id);
               break;
             }
           }
@@ -405,15 +587,32 @@ function completeRun(rootPath, runId, params = {}) {
     }
   }
 
-  // Update state
-  state.active_run = null;
-  state.runs = {
-    completed: alreadyRecorded ? existingCompleted : [...existingCompleted, completedRun],
-  };
+  // Remove from active runs and add to completed
+  state.runs.active.splice(runIndex, 1);
+  if (!alreadyRecorded) {
+    state.runs.completed.push(completedRun);
+  }
 
-  // Save state
+  // Save state first (so markdown sync has correct state)
   writeState(statePath, state);
 
+  // Sync markdown frontmatter for all completed work items
+  for (const workItem of workItems) {
+    updateWorkItemMarkdown(
+      rootPath,
+      workItem.intent,
+      workItem.id,
+      'completed',
+      runId,
+      workItem.completed_at || completedTime
+    );
+  }
+
+  // Update intent markdown for all affected intents
+  for (const intentId of affectedIntents) {
+    updateIntentMarkdown(rootPath, intentId, state);
+  }
+
   return {
     success: true,
     runId: runId,
@@ -480,9 +679,9 @@ function parseArgs(args) {
 
 function printUsage() {
   console.error('Usage:');
-  console.error('  Complete current item: node complete-run.js <rootPath> <runId> --complete-item [options]');
-  console.error('  Complete entire run:   node complete-run.js <rootPath> <runId> --complete-run [options]');
-  console.error('  Auto (single runs):    node complete-run.js <rootPath> <runId> [options]');
+  console.error('  Complete current item: node complete-run.cjs <rootPath> <runId> --complete-item [options]');
+  console.error('  Complete entire run:   node complete-run.cjs <rootPath> <runId> --complete-run [options]');
+  console.error('  Auto (single runs):    node complete-run.cjs <rootPath> <runId> [options]');
   console.error('');
   console.error('Arguments:');
   console.error('  rootPath  - Project root directory');
@@ -500,8 +699,8 @@ function printUsage() {
   console.error('  --coverage=N           - Coverage percentage');
   console.error('');
   console.error('Examples:');
-  console.error('  node complete-run.js /project run-003 --complete-item');
-  console.error('  node complete-run.js /project run-003 --complete-run --tests=5 --coverage=85');
+  console.error('  node complete-run.cjs /project run-003 --complete-item');
+  console.error('  node complete-run.cjs /project run-003 --complete-run --tests=5 --coverage=85');
 }
 
 // =============================================================================

package/flows/fire/agents/builder/skills/run-execute/scripts/{init-run.js → init-run.cjs}

@@ -11,12 +11,12 @@
  * - existing run folders in .specs-fire/runs/
  *
  * Usage:
- *   Single item: node init-run.js <rootPath> <workItemId> <intentId> <mode>
- *   Batch/Wide:  node init-run.js <rootPath> --batch '<workItemsJson>'
+ *   Single item: node init-run.cjs <rootPath> <workItemId> <intentId> <mode>
+ *   Batch/Wide:  node init-run.cjs <rootPath> --batch '<workItemsJson>'
  *
  * Examples:
- *   node init-run.js /project login-endpoint user-auth confirm
- *   node init-run.js /project --batch '[{"id":"wi-1","intent":"int-1","mode":"autopilot"}]'
+ *   node init-run.cjs /project login-endpoint user-auth confirm
+ *   node init-run.cjs /project --batch '[{"id":"wi-1","intent":"int-1","mode":"autopilot"}]'
  */
 
 const fs = require('fs');
@@ -317,13 +317,15 @@ function initRun(rootPath, workItems, scope) {
   // Read state
   const state = readState(statePath);
 
-  // Check for existing active run
-  if (state.active_run) {
-    throw fireError(
-      `A run is already active: "${state.active_run.id}".`,
-      'INIT_080',
-      `Complete or cancel run "${state.active_run.id}" before starting a new one.`
-    );
+  // Initialize runs structure if needed
+  if (!state.runs) {
+    state.runs = { active: [], completed: [] };
+  }
+  if (!Array.isArray(state.runs.active)) {
+    state.runs.active = [];
+  }
+  if (!Array.isArray(state.runs.completed)) {
+    state.runs.completed = [];
   }
 
   // Generate run ID (checks both history AND file system)
@@ -337,22 +339,23 @@ function initRun(rootPath, workItems, scope) {
   const startTime = new Date().toISOString();
   createRunLog(runPath, runId, workItems, detectedScope, startTime);
 
-  // Prepare work items for state with status tracking
+  // Prepare work items for state with status and phase tracking
   const stateWorkItems = workItems.map((item, index) => ({
     id: item.id,
     intent: item.intent,
     mode: item.mode,
     status: index === 0 ? 'in_progress' : 'pending',
+    current_phase: index === 0 ? 'plan' : null,
   }));
 
-  // Update state with active run
-  state.active_run = {
+  // Add to active runs list (supports multiple parallel runs)
+  state.runs.active.push({
     id: runId,
     scope: detectedScope,
     work_items: stateWorkItems,
     current_item: workItems[0].id,
     started: startTime,
-  };
+  });
 
   // Save state
   writeState(statePath, state);
@@ -375,8 +378,8 @@ function initRun(rootPath, workItems, scope) {
 
 function printUsage() {
   console.error('Usage:');
-  console.error('  Single item: node init-run.js <rootPath> <workItemId> <intentId> <mode>');
-  console.error('  Batch/Wide:  node init-run.js <rootPath> --batch \'<workItemsJson>\' [--scope=<scope>]');
+  console.error('  Single item: node init-run.cjs <rootPath> <workItemId> <intentId> <mode>');
+  console.error('  Batch/Wide:  node init-run.cjs <rootPath> --batch \'<workItemsJson>\' [--scope=<scope>]');
   console.error('');
   console.error('Arguments:');
   console.error('  rootPath      - Project root directory');
@@ -392,8 +395,8 @@ function printUsage() {
   console.error('  [{"id": "wi-1", "intent": "int-1", "mode": "autopilot"}, ...]');
   console.error('');
   console.error('Examples:');
-  console.error('  node init-run.js /project login-endpoint user-auth confirm');
-  console.error('  node init-run.js /project --batch \'[{"id":"wi-1","intent":"int-1","mode":"autopilot"}]\'');
+  console.error('  node init-run.cjs /project login-endpoint user-auth confirm');
+  console.error('  node init-run.cjs /project --batch \'[{"id":"wi-1","intent":"int-1","mode":"autopilot"}]\'');
 }
 
 if (require.main === module) {