specsmd 0.0.0-dev.9 → 0.0.0-dev.90

package/flows/fire/agents/builder/skills/run-execute/scripts/update-checkpoint.cjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+/**
+ * FIRE Checkpoint State Update Script
+ *
+ * Tracks explicit approval-gate state for the active work item in a run.
+ *
+ * Usage:
+ *   node update-checkpoint.cjs <rootPath> <runId> <checkpointState> [--item=<workItemId>] [--checkpoint=<name>]
+ *
+ * Examples:
+ *   node update-checkpoint.cjs /project run-fabriqa-2026-001 awaiting_approval --checkpoint=plan
+ *   node update-checkpoint.cjs /project run-fabriqa-2026-001 approved
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('yaml');
+
+const VALID_STATES = ['awaiting_approval', 'approved', 'none', 'not_required'];
+
+function fireError(message, code, suggestion) {
+  const err = new Error(`FIRE Error [${code}]: ${message} ${suggestion}`);
+  err.code = code;
+  err.suggestion = suggestion;
+  return err;
+}
+
+function normalizeCheckpointState(value) {
+  const normalized = String(value || '').toLowerCase().trim().replace(/[\s-]+/g, '_');
+  const map = {
+    waiting: 'awaiting_approval',
+    awaiting: 'awaiting_approval',
+    awaiting_approval: 'awaiting_approval',
+    pending_approval: 'awaiting_approval',
+    approval_needed: 'awaiting_approval',
+    approval_required: 'awaiting_approval',
+    approved: 'approved',
+    confirmed: 'approved',
+    accepted: 'approved',
+    resumed: 'approved',
+    none: 'none',
+    clear: 'none',
+    cleared: 'none',
+    reset: 'none',
+    not_required: 'not_required',
+    n_a: 'not_required',
+    na: 'not_required',
+    skipped: 'not_required'
+  };
+
+  return map[normalized] || null;
+}
+
+function validateInputs(rootPath, runId, checkpointState) {
+  if (!rootPath || typeof rootPath !== 'string' || rootPath.trim() === '') {
+    throw fireError('rootPath is required.', 'CHECKPOINT_001', 'Provide a valid project root path.');
+  }
+
+  if (!runId || typeof runId !== 'string' || runId.trim() === '') {
+    throw fireError('runId is required.', 'CHECKPOINT_002', 'Provide the run ID.');
+  }
+
+  const normalizedState = normalizeCheckpointState(checkpointState);
+  if (!normalizedState || !VALID_STATES.includes(normalizedState)) {
+    throw fireError(
+      `Invalid checkpointState: "${checkpointState}".`,
+      'CHECKPOINT_003',
+      `Valid states are: ${VALID_STATES.join(', ')}`
+    );
+  }
+
+  if (!fs.existsSync(rootPath)) {
+    throw fireError(
+      `Project root not found: "${rootPath}".`,
+      'CHECKPOINT_004',
+      'Ensure the path exists and is accessible.'
+    );
+  }
+
+  return normalizedState;
+}
+
+function validateFireProject(rootPath) {
+  const fireDir = path.join(rootPath, '.specs-fire');
+  const statePath = path.join(fireDir, 'state.yaml');
+
+  if (!fs.existsSync(fireDir)) {
+    throw fireError(
+      `FIRE project not initialized at: "${rootPath}".`,
+      'CHECKPOINT_010',
+      'Run fire-init first to initialize the project.'
+    );
+  }
+
+  if (!fs.existsSync(statePath)) {
+    throw fireError(
+      `State file not found at: "${statePath}".`,
+      'CHECKPOINT_011',
+      'The project may be corrupted. Try re-initializing.'
+    );
+  }
+
+  return { statePath };
+}
+
+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.', 'CHECKPOINT_020', 'Check state.yaml format.');
+    }
+    return state;
+  } catch (err) {
+    if (err.code && err.code.startsWith('CHECKPOINT_')) throw err;
+    throw fireError(
+      `Failed to read state file: ${err.message}`,
+      'CHECKPOINT_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}`,
+      'CHECKPOINT_022',
+      'Check file permissions and disk space.'
+    );
+  }
+}
+
+function updateCheckpoint(rootPath, runId, checkpointState, options = {}) {
+  const normalizedState = validateInputs(rootPath, runId, checkpointState);
+  const { statePath } = validateFireProject(rootPath);
+  const state = readState(statePath);
+
+  const activeRuns = state.runs?.active || [];
+  const runIndex = activeRuns.findIndex((run) => run.id === runId);
+  if (runIndex === -1) {
+    throw fireError(
+      `Run "${runId}" not found in active runs.`,
+      'CHECKPOINT_030',
+      'The run may have already been completed or was never started.'
+    );
+  }
+
+  const activeRun = activeRuns[runIndex];
+  const workItems = Array.isArray(activeRun.work_items) ? activeRun.work_items : [];
+  const targetItemId = options.itemId || activeRun.current_item;
+  if (!targetItemId) {
+    throw fireError(
+      `Run "${runId}" has no current item.`,
+      'CHECKPOINT_031',
+      'Specify --item=<workItemId> explicitly.'
+    );
+  }
+
+  const itemIndex = workItems.findIndex((item) => item.id === targetItemId);
+  if (itemIndex === -1) {
+    throw fireError(
+      `Work item "${targetItemId}" not found in run "${runId}".`,
+      'CHECKPOINT_032',
+      'Check the work item ID or run state.'
+    );
+  }
+
+  const item = workItems[itemIndex];
+  const previousState = item.checkpoint_state || null;
+  item.checkpoint_state = normalizedState;
+
+  if (typeof options.checkpoint === 'string' && options.checkpoint.trim() !== '') {
+    item.current_checkpoint = options.checkpoint.trim();
+  } else if (!item.current_checkpoint && (normalizedState === 'awaiting_approval' || normalizedState === 'approved')) {
+    item.current_checkpoint = 'plan';
+  }
+
+  if (!item.current_phase && normalizedState === 'awaiting_approval') {
+    item.current_phase = 'plan';
+  }
+
+  activeRun.work_items = workItems;
+  state.runs.active[runIndex] = activeRun;
+  writeState(statePath, state);
+
+  return {
+    success: true,
+    runId,
+    workItemId: targetItemId,
+    checkpointState: normalizedState,
+    previousCheckpointState: previousState,
+    currentCheckpoint: item.current_checkpoint || null
+  };
+}
+
+function parseOptions(argv) {
+  const options = {};
+  for (const arg of argv) {
+    if (arg.startsWith('--item=')) {
+      options.itemId = arg.slice('--item='.length);
+    } else if (arg.startsWith('--checkpoint=')) {
+      options.checkpoint = arg.slice('--checkpoint='.length);
+    } else {
+      throw fireError(
+        `Unknown option: ${arg}`,
+        'CHECKPOINT_033',
+        'Use --item=<workItemId> or --checkpoint=<name>.'
+      );
+    }
+  }
+  return options;
+}
+
+function printUsage() {
+  console.error('Usage:');
+  console.error('  node update-checkpoint.cjs <rootPath> <runId> <checkpointState> [--item=<workItemId>] [--checkpoint=<name>]');
+  console.error('');
+  console.error('checkpointState:');
+  console.error(`  ${VALID_STATES.join(', ')}`);
+  console.error('');
+  console.error('Examples:');
+  console.error('  node update-checkpoint.cjs /project run-fabriqa-2026-001 awaiting_approval --checkpoint=plan');
+  console.error('  node update-checkpoint.cjs /project run-fabriqa-2026-001 approved');
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  if (args.length < 3) {
+    printUsage();
+    process.exit(1);
+  }
+
+  const [rootPath, runId, checkpointState, ...optionArgs] = args;
+
+  try {
+    const options = parseOptions(optionArgs);
+    const result = updateCheckpoint(rootPath, runId, checkpointState, options);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  VALID_STATES,
+  normalizeCheckpointState,
+  updateCheckpoint
+};

package/flows/fire/agents/builder/skills/run-execute/scripts/update-phase.cjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+
+/**
+ * FIRE Phase Update Script
+ *
+ * Updates the current phase for a work item in an active run.
+ * Phases: plan → execute → test → review
+ *
+ * Usage:
+ *   node update-phase.cjs <rootPath> <runId> <phase>
+ *
+ * Examples:
+ *   node update-phase.cjs /project run-fabriqa-2026-001 execute
+ *   node update-phase.cjs /project run-fabriqa-2026-001 test
+ *   node update-phase.cjs /project run-fabriqa-2026-001 review
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('yaml');
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const VALID_PHASES = ['plan', 'execute', 'test', 'review'];
+
+// =============================================================================
+// 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, phase) {
+  if (!rootPath || typeof rootPath !== 'string' || rootPath.trim() === '') {
+    throw fireError('rootPath is required.', 'PHASE_001', 'Provide a valid project root path.');
+  }
+
+  if (!runId || typeof runId !== 'string' || runId.trim() === '') {
+    throw fireError('runId is required.', 'PHASE_002', 'Provide the run ID.');
+  }
+
+  if (!phase || !VALID_PHASES.includes(phase)) {
+    throw fireError(
+      `Invalid phase: "${phase}".`,
+      'PHASE_003',
+      `Valid phases are: ${VALID_PHASES.join(', ')}`
+    );
+  }
+
+  if (!fs.existsSync(rootPath)) {
+    throw fireError(
+      `Project root not found: "${rootPath}".`,
+      'PHASE_004',
+      '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');
+
+  if (!fs.existsSync(fireDir)) {
+    throw fireError(
+      `FIRE project not initialized at: "${rootPath}".`,
+      'PHASE_010',
+      'Run fire-init first to initialize the project.'
+    );
+  }
+
+  if (!fs.existsSync(statePath)) {
+    throw fireError(
+      `State file not found at: "${statePath}".`,
+      'PHASE_011',
+      'The project may be corrupted. Try re-initializing.'
+    );
+  }
+
+  return { statePath };
+}
+
+// =============================================================================
+// 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.', 'PHASE_020', 'Check state.yaml format.');
+    }
+    return state;
+  } catch (err) {
+    if (err.code && err.code.startsWith('PHASE_')) throw err;
+    throw fireError(
+      `Failed to read state file: ${err.message}`,
+      'PHASE_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}`,
+      'PHASE_022',
+      'Check file permissions and disk space.'
+    );
+  }
+}
+
+// =============================================================================
+// Main Function
+// =============================================================================
+
+/**
+ * Update the current phase for the active work item in a run.
+ *
+ * @param {string} rootPath - Project root directory
+ * @param {string} runId - Run ID
+ * @param {string} phase - New phase (plan, execute, test, review)
+ * @returns {object} Result with updated phase info
+ */
+function updatePhase(rootPath, runId, phase) {
+  validateInputs(rootPath, runId, phase);
+  const { statePath } = validateFireProject(rootPath, runId);
+  const state = readState(statePath);
+
+  // Find run in active runs list
+  const activeRuns = state.runs?.active || [];
+  const runIndex = activeRuns.findIndex(r => r.id === runId);
+
+  if (runIndex === -1) {
+    throw fireError(
+      `Run "${runId}" not found in active runs.`,
+      'PHASE_030',
+      'The run may have been completed or was never started.'
+    );
+  }
+
+  const activeRun = activeRuns[runIndex];
+  const workItems = activeRun.work_items || [];
+  const currentItemId = activeRun.current_item;
+
+  if (!currentItemId) {
+    throw fireError(
+      `No current item in run "${runId}".`,
+      'PHASE_031',
+      'The run may have completed all work items.'
+    );
+  }
+
+  // Find and update current item's phase
+  let updated = false;
+  let previousPhase = null;
+  for (const item of workItems) {
+    if (item.id === currentItemId) {
+      previousPhase = item.current_phase || 'plan';
+      item.current_phase = phase;
+      const mode = String(item.mode || '').toLowerCase();
+      const isApprovalMode = mode === 'confirm' || mode === 'validate';
+
+      if (isApprovalMode && phase !== 'plan') {
+        item.checkpoint_state = 'approved';
+        if (!item.current_checkpoint) {
+          item.current_checkpoint = 'plan';
+        }
+      } else if (!item.checkpoint_state) {
+        item.checkpoint_state = 'none';
+      }
+      updated = true;
+      break;
+    }
+  }
+
+  if (!updated) {
+    throw fireError(
+      `Current item "${currentItemId}" not found in work items.`,
+      'PHASE_032',
+      'The run state may be corrupted.'
+    );
+  }
+
+  // Update state
+  activeRun.work_items = workItems;
+  state.runs.active[runIndex] = activeRun;
+  writeState(statePath, state);
+
+  return {
+    success: true,
+    runId: runId,
+    workItemId: currentItemId,
+    previousPhase: previousPhase,
+    currentPhase: phase,
+  };
+}
+
+// =============================================================================
+// CLI Interface
+// =============================================================================
+
+function printUsage() {
+  console.error('Usage:');
+  console.error('  node update-phase.cjs <rootPath> <runId> <phase>');
+  console.error('');
+  console.error('Arguments:');
+  console.error('  rootPath  - Project root directory');
+  console.error('  runId     - Run ID (e.g., run-fabriqa-2026-001)');
+  console.error('  phase     - New phase: plan, execute, test, review');
+  console.error('');
+  console.error('Examples:');
+  console.error('  node update-phase.cjs /project run-fabriqa-2026-001 execute');
+  console.error('  node update-phase.cjs /project run-fabriqa-2026-001 test');
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 3) {
+    printUsage();
+    process.exit(1);
+  }
+
+  const [rootPath, runId, phase] = args;
+
+  try {
+    const result = updatePhase(rootPath, runId, phase);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { updatePhase, VALID_PHASES };

package/flows/fire/agents/builder/skills/run-execute/templates/plan.md.hbs

@@ -0,0 +1,61 @@
+---
+run: {{run_id}}
+work_item: {{work_item_id}}
+intent: {{intent_id}}
+mode: {{mode}}
+checkpoint: {{checkpoint_type}}
+approved_at: {{approved_at}}
+---
+
+# Implementation Plan: {{title}}
+
+## Approach
+
+{{approach}}
+
+## Files to Create
+
+| File | Purpose |
+|------|---------|
+{{#each files_to_create}}
+| `{{this.path}}` | {{this.purpose}} |
+{{/each}}
+{{#unless files_to_create}}
+| (none) | |
+{{/unless}}
+
+## Files to Modify
+
+| File | Changes |
+|------|---------|
+{{#each files_to_modify}}
+| `{{this.path}}` | {{this.changes}} |
+{{/each}}
+{{#unless files_to_modify}}
+| (none) | |
+{{/unless}}
+
+{{#if tests}}
+## Tests
+
+| Test File | Coverage |
+|-----------|----------|
+{{#each tests}}
+| `{{this.path}}` | {{this.coverage}} |
+{{/each}}
+{{/if}}
+
+{{#if technical_details}}
+## Technical Details
+
+{{technical_details}}
+{{/if}}
+
+{{#if design_doc}}
+## Based on Design Doc
+
+Reference: `{{design_doc}}`
+{{/if}}
+
+---
+*Plan approved at checkpoint. Execution follows.*

package/flows/fire/agents/builder/skills/run-execute/templates/test-report.md.hbs

@@ -0,0 +1,81 @@
+---
+run: {{run_id}}
+work_item: {{work_item_id}}
+intent: {{intent_id}}
+generated: {{generated_at}}
+status: {{status}}
+---
+
+# Test Report: {{title}}
+
+## Summary
+
+| Category | Passed | Failed | Skipped | Coverage |
+|----------|--------|--------|---------|----------|
+| Unit | {{unit_passed}} | {{unit_failed}} | {{unit_skipped}} | {{unit_coverage}}% |
+| Integration | {{integration_passed}} | {{integration_failed}} | {{integration_skipped}} | {{integration_coverage}}% |
+| **Total** | {{total_passed}} | {{total_failed}} | {{total_skipped}} | {{total_coverage}}% |
+
+## Acceptance Criteria Validation
+
+{{#each acceptance_criteria}}
+- {{#if this.passed}}✅{{else}}❌{{/if}} **{{this.criterion}}** — {{this.status}}
+{{/each}}
+
+## Tests Written
+
+### Unit Tests
+
+{{#each unit_tests}}
+- `{{this.file}}` — {{this.description}}
+{{/each}}
+
+### Integration Tests
+
+{{#each integration_tests}}
+- `{{this.file}}` — {{this.description}}
+{{/each}}
+
+## Test Commands
+
+```bash
+# Run all tests
+{{test_command}}
+
+# Run with coverage
+{{coverage_command}}
+```
+
+## Coverage Details
+
+{{#if coverage_details}}
+| Module | Statements | Branches | Functions | Lines |
+|--------|------------|----------|-----------|-------|
+{{#each coverage_details}}
+| `{{this.module}}` | {{this.statements}}% | {{this.branches}}% | {{this.functions}}% | {{this.lines}}% |
+{{/each}}
+{{else}}
+Coverage details not available.
+{{/if}}
+
+## Issues Found
+
+{{#if issues}}
+| Issue | Severity | Status |
+|-------|----------|--------|
+{{#each issues}}
+| {{this.description}} | {{this.severity}} | {{this.status}} |
+{{/each}}
+{{else}}
+No issues found during testing.
+{{/if}}
+
+## Ready for Completion
+
+- [{{#if all_tests_pass}}x{{else}} {{/if}}] All tests passing
+- [{{#if coverage_met}}x{{else}} {{/if}}] Coverage target met ({{coverage_target}}%)
+- [{{#if acceptance_met}}x{{else}} {{/if}}] All acceptance criteria validated
+- [{{#if no_critical_issues}}x{{else}} {{/if}}] No critical issues open
+
+---
+*Generated by specs.md - fabriqa.ai FIRE Flow Run {{run_id}}*