specsmd 0.0.0-dev.53 → 0.0.0-dev.55

package/flows/fire/agents/builder/agent.md

@@ -155,18 +155,21 @@ Each run creates a folder with its artifacts:
 .specs-fire/runs/{run-id}/
 ├── plan.md          # Approved implementation plan (confirm/validate modes)
 ├── run.md           # Run log (metadata, files changed, decisions)
+├── test-report.md   # Test results, coverage, and acceptance validation
 └── walkthrough.md   # Implementation walkthrough (for human review)
 ```
 
-**The trio**:
+**The quartet**:
 - **plan.md** — What we intended to do (approved at checkpoint)
 - **run.md** — What happened during execution
+- **test-report.md** — Test results and acceptance criteria validation
 - **walkthrough.md** — Human-readable summary after completion
 
 | Artifact | Location | Template |
 |----------|----------|----------|
 | Plan | `.specs-fire/runs/{run-id}/plan.md` | `skills/run-execute/templates/plan.md.hbs` |
 | Run Log | `.specs-fire/runs/{run-id}/run.md` | (generated by script) |
+| Test Report | `.specs-fire/runs/{run-id}/test-report.md` | `skills/run-execute/templates/test-report.md.hbs` |
 | Walkthrough | `.specs-fire/runs/{run-id}/walkthrough.md` | `skills/walkthrough-generate/templates/walkthrough.md.hbs` |
 
 ---

package/flows/fire/agents/builder/skills/run-execute/SKILL.md

@@ -57,7 +57,7 @@ Before executing scripts, ensure required dependencies are installed:
   </mandate>
 
   <step n="1" title="Initialize Run">
-    <action script="scripts/init-run.ts">Create run record</action>
+    <action script="scripts/init-run.js">Create run record</action>
     <action>Generate run ID: run-{NNN}</action>
     <action>Create folder: .specs-fire/runs/{run-id}/</action>
     <action>Set active_run in state.yaml</action>
@@ -66,7 +66,11 @@ Before executing scripts, ensure required dependencies are installed:
   <step n="2" title="Load Context">
     <action>Read work item from .specs-fire/intents/{intent}/work-items/{id}.md</action>
     <action>Read intent brief for broader context</action>
-    <action>Read project standards (.specs-fire/standards/)</action>
+    <action>Load ALL project standards:</action>
+    <substep>.specs-fire/standards/tech-stack.md — Technology choices</substep>
+    <substep>.specs-fire/standards/coding-standards.md — Code style and patterns</substep>
+    <substep>.specs-fire/standards/testing-standards.md — Testing strategy and coverage</substep>
+    <substep>.specs-fire/standards/system-architecture.md — Architecture context and constraints</substep>
     <action>Determine execution mode from work item</action>
   </step>
 
@@ -163,6 +167,12 @@ Before executing scripts, ensure required dependencies are installed:
   </step>
 
   <step n="6" title="Run Tests">
+    <action>Load testing standards from .specs-fire/standards/testing-standards.md</action>
+    <action>Write tests following testing standards:</action>
+    <substep>Unit tests for new/modified functions</substep>
+    <substep>Integration tests for API endpoints or workflows</substep>
+    <substep>Follow test naming and structure conventions</substep>
+
     <action>Run test suite</action>
     <check if="tests fail">
       <output>
@@ -171,11 +181,15 @@ Before executing scripts, ensure required dependencies are installed:
       <action>Fix failing tests</action>
       <action>Re-run tests</action>
     </check>
-    <action>Record test results and coverage</action>
+
+    <action>Validate acceptance criteria from work item</action>
+    <action>Measure coverage against target from testing-standards.md</action>
+    <action>Generate test report using template: templates/test-report.md.hbs</action>
+    <action>Save to: .specs-fire/runs/{run-id}/test-report.md</action>
   </step>
 
   <step n="7" title="Complete Run">
-    <action script="scripts/complete-run.ts">Finalize run record</action>
+    <action script="scripts/complete-run.js">Finalize run record</action>
     <action>Update state.yaml (clear active_run, mark work item complete)</action>
     <action>Generate run log: .specs-fire/runs/{run-id}/run.md</action>
   </step>
@@ -193,7 +207,9 @@ Before executing scripts, ensure required dependencies are installed:
       Tests added: {count}
       Coverage: {percentage}%
 
-      Walkthrough: .specs-fire/runs/{run-id}/walkthrough.md
+      Artifacts:
+      - Test Report: .specs-fire/runs/{run-id}/test-report.md
+      - Walkthrough: .specs-fire/runs/{run-id}/walkthrough.md
 
       Continue to next work item? [Y/n]
     </output>
@@ -208,8 +224,8 @@ Before executing scripts, ensure required dependencies are installed:
 
 | Script | Purpose |
 |--------|---------|
-| `scripts/init-run.ts` | Initialize run record and folder |
-| `scripts/complete-run.ts` | Finalize run and update state |
+| `scripts/init-run.js` | Initialize run record and folder |
+| `scripts/complete-run.js` | Finalize run and update state |
 
 ---
 

package/flows/fire/agents/builder/skills/run-execute/scripts/complete-run.js

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+
+/**
+ * FIRE Run Completion Script
+ *
+ * Finalizes a run by:
+ * 1. Recording the completed run in state.yaml runs.completed history
+ * 2. Updating work item status to completed
+ * 3. Clearing active_run
+ * 4. Updating run.md with completion data
+ *
+ * Usage: node complete-run.js <rootPath> <runId> [--files-created=JSON] [--files-modified=JSON] [--decisions=JSON] [--tests=N] [--coverage=N]
+ *
+ * Example: node complete-run.js /project run-003 --tests=5 --coverage=85
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('yaml');
+
+// =============================================================================
+// Error Helper
+// =============================================================================
+
+function fireError(message, code, suggestion) {
+  const err = new Error(`FIRE Error [${code}]: ${message} ${suggestion}`);
+  err.code = code;
+  err.suggestion = suggestion;
+  return err;
+}
+
+// =============================================================================
+// Validation
+// =============================================================================
+
+function validateInputs(rootPath, runId) {
+  if (!rootPath || typeof rootPath !== 'string' || rootPath.trim() === '') {
+    throw fireError('rootPath is required.', 'COMPLETE_001', 'Provide a valid project root path.');
+  }
+
+  if (!runId || typeof runId !== 'string' || runId.trim() === '') {
+    throw fireError('runId is required.', 'COMPLETE_002', 'Provide the run ID to complete.');
+  }
+
+  if (!fs.existsSync(rootPath)) {
+    throw fireError(
+      `Project root not found: "${rootPath}".`,
+      'COMPLETE_003',
+      'Ensure the path exists and is accessible.'
+    );
+  }
+}
+
+function validateFireProject(rootPath, runId) {
+  const fireDir = path.join(rootPath, '.specs-fire');
+  const statePath = path.join(fireDir, 'state.yaml');
+  const runsPath = path.join(fireDir, 'runs');
+  const runPath = path.join(runsPath, runId);
+  const runLogPath = path.join(runPath, 'run.md');
+
+  if (!fs.existsSync(fireDir)) {
+    throw fireError(
+      `FIRE project not initialized at: "${rootPath}".`,
+      'COMPLETE_010',
+      'Run fire-init first to initialize the project.'
+    );
+  }
+
+  if (!fs.existsSync(statePath)) {
+    throw fireError(
+      `State file not found at: "${statePath}".`,
+      'COMPLETE_011',
+      'The project may be corrupted. Try re-initializing.'
+    );
+  }
+
+  if (!fs.existsSync(runPath)) {
+    throw fireError(
+      `Run folder not found: "${runPath}".`,
+      'COMPLETE_012',
+      `Ensure run "${runId}" was properly initialized.`
+    );
+  }
+
+  if (!fs.existsSync(runLogPath)) {
+    throw fireError(
+      `Run log not found: "${runLogPath}".`,
+      'COMPLETE_013',
+      `The run may have been partially initialized.`
+    );
+  }
+
+  return { statePath, runPath, runLogPath };
+}
+
+// =============================================================================
+// State Operations
+// =============================================================================
+
+function readState(statePath) {
+  try {
+    const content = fs.readFileSync(statePath, 'utf8');
+    const state = yaml.parse(content);
+    if (!state || typeof state !== 'object') {
+      throw fireError('State file is empty or invalid.', 'COMPLETE_020', 'Check state.yaml format.');
+    }
+    return state;
+  } catch (err) {
+    if (err.code && err.code.startsWith('COMPLETE_')) throw err;
+    throw fireError(
+      `Failed to read state file: ${err.message}`,
+      'COMPLETE_021',
+      'Check file permissions and YAML syntax.'
+    );
+  }
+}
+
+function writeState(statePath, state) {
+  try {
+    fs.writeFileSync(statePath, yaml.stringify(state));
+  } catch (err) {
+    throw fireError(
+      `Failed to write state file: ${err.message}`,
+      'COMPLETE_022',
+      'Check file permissions and disk space.'
+    );
+  }
+}
+
+// =============================================================================
+// Run Log Operations
+// =============================================================================
+
+function updateRunLog(runLogPath, params, completedTime) {
+  let content;
+  try {
+    content = fs.readFileSync(runLogPath, 'utf8');
+  } catch (err) {
+    throw fireError(
+      `Failed to read run log: ${err.message}`,
+      'COMPLETE_030',
+      'Check file permissions.'
+    );
+  }
+
+  // Update status
+  content = content.replace(/status: in_progress/, 'status: completed');
+  content = content.replace(/completed: null/, `completed: ${completedTime}`);
+
+  // Format file lists
+  const filesCreatedText = params.filesCreated.length > 0
+    ? params.filesCreated.map(f => `- \`${f.path}\`: ${f.purpose || '(no purpose)'}`).join('\n')
+    : '(none)';
+
+  const filesModifiedText = params.filesModified.length > 0
+    ? params.filesModified.map(f => `- \`${f.path}\`: ${f.changes || '(no changes)'}`).join('\n')
+    : '(none)';
+
+  const decisionsText = params.decisions.length > 0
+    ? params.decisions.map(d => `- **${d.decision}**: ${d.choice} (${d.rationale || 'no rationale'})`).join('\n')
+    : '(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}`);
+
+  // Add summary if not present
+  if (!content.includes('## Summary')) {
+    content += `
+
+## Summary
+
+- Files created: ${params.filesCreated.length}
+- Files modified: ${params.filesModified.length}
+- Tests added: ${params.testsAdded}
+- Coverage: ${params.coverage}%
+- Completed: ${completedTime}
+`;
+  }
+
+  try {
+    fs.writeFileSync(runLogPath, content);
+  } catch (err) {
+    throw fireError(
+      `Failed to write run log: ${err.message}`,
+      'COMPLETE_031',
+      'Check file permissions.'
+    );
+  }
+}
+
+// =============================================================================
+// Main Function
+// =============================================================================
+
+function completeRun(rootPath, runId, params = {}) {
+  // Defaults for optional params
+  const completionParams = {
+    filesCreated: params.filesCreated || [],
+    filesModified: params.filesModified || [],
+    decisions: params.decisions || [],
+    testsAdded: params.testsAdded || 0,
+    coverage: params.coverage || 0,
+  };
+
+  // Validate inputs
+  validateInputs(rootPath, runId);
+
+  // Validate FIRE project structure
+  const { statePath, runLogPath } = validateFireProject(rootPath, runId);
+
+  // Read state
+  const state = readState(statePath);
+
+  // Validate active run matches
+  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.'
+    );
+  }
+
+  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.`
+    );
+  }
+
+  // Extract work item and intent from active run
+  const workItemId = state.active_run.work_item;
+  const intentId = state.active_run.intent;
+  const completedTime = new Date().toISOString();
+
+  // Update run log
+  updateRunLog(runLogPath, completionParams, completedTime);
+
+  // Build completed run record
+  const completedRun = {
+    id: runId,
+    work_item: workItemId,
+    intent: intentId,
+    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);
+
+  // Update work item status in intents
+  if (Array.isArray(state.intents)) {
+    for (const intent of state.intents) {
+      if (intent.id === intentId && Array.isArray(intent.work_items)) {
+        for (const workItem of intent.work_items) {
+          if (workItem.id === workItemId) {
+            workItem.status = 'completed';
+            workItem.run_id = runId;
+            break;
+          }
+        }
+        break;
+      }
+    }
+  }
+
+  // Update state
+  state.active_run = null;
+  state.runs = {
+    completed: alreadyRecorded ? existingCompleted : [...existingCompleted, completedRun],
+  };
+
+  // Save state
+  writeState(statePath, state);
+
+  // Return result
+  return {
+    success: true,
+    runId: runId,
+    workItemId: workItemId,
+    intentId: intentId,
+    completedAt: completedTime,
+    filesCreated: completionParams.filesCreated.length,
+    filesModified: completionParams.filesModified.length,
+    testsAdded: completionParams.testsAdded,
+    coverage: completionParams.coverage,
+  };
+}
+
+// =============================================================================
+// CLI Argument Parsing
+// =============================================================================
+
+function parseArgs(args) {
+  const result = {
+    rootPath: args[0],
+    runId: args[1],
+    filesCreated: [],
+    filesModified: [],
+    decisions: [],
+    testsAdded: 0,
+    coverage: 0,
+  };
+
+  for (let i = 2; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--files-created=')) {
+      try {
+        result.filesCreated = JSON.parse(arg.substring('--files-created='.length));
+      } catch (e) {
+        console.error('Warning: Could not parse --files-created JSON');
+      }
+    } else if (arg.startsWith('--files-modified=')) {
+      try {
+        result.filesModified = JSON.parse(arg.substring('--files-modified='.length));
+      } catch (e) {
+        console.error('Warning: Could not parse --files-modified JSON');
+      }
+    } else if (arg.startsWith('--decisions=')) {
+      try {
+        result.decisions = JSON.parse(arg.substring('--decisions='.length));
+      } catch (e) {
+        console.error('Warning: Could not parse --decisions JSON');
+      }
+    } else if (arg.startsWith('--tests=')) {
+      result.testsAdded = parseInt(arg.substring('--tests='.length), 10) || 0;
+    } else if (arg.startsWith('--coverage=')) {
+      result.coverage = parseFloat(arg.substring('--coverage='.length)) || 0;
+    }
+  }
+
+  return result;
+}
+
+// =============================================================================
+// CLI Interface
+// =============================================================================
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2) {
+    console.error('Usage: node complete-run.js <rootPath> <runId> [options]');
+    console.error('');
+    console.error('Arguments:');
+    console.error('  rootPath  - Project root directory');
+    console.error('  runId     - Run ID to complete (e.g., run-003)');
+    console.error('');
+    console.error('Options:');
+    console.error('  --files-created=JSON   - JSON array of {path, purpose}');
+    console.error('  --files-modified=JSON  - JSON array of {path, changes}');
+    console.error('  --decisions=JSON       - JSON array of {decision, choice, rationale}');
+    console.error('  --tests=N              - Number of tests added');
+    console.error('  --coverage=N           - Coverage percentage');
+    console.error('');
+    console.error('Example:');
+    console.error('  node complete-run.js /my/project run-003 --tests=5 --coverage=85');
+    process.exit(1);
+  }
+
+  const params = parseArgs(args);
+
+  try {
+    const result = completeRun(params.rootPath, params.runId, {
+      filesCreated: params.filesCreated,
+      filesModified: params.filesModified,
+      decisions: params.decisions,
+      testsAdded: params.testsAdded,
+      coverage: params.coverage,
+    });
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { completeRun };