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

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

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+
+/**
+ * FIRE Run Initialization Script
+ *
+ * Creates run record in state.yaml and run folder structure.
+ * Ensures deterministic run ID generation by checking BOTH:
+ * - runs.completed history in state.yaml
+ * - existing run folders in .specs-fire/runs/
+ *
+ * Usage: node init-run.js <rootPath> <workItemId> <intentId> <mode>
+ *
+ * Example: node init-run.js /project login-endpoint user-auth confirm
+ */
+
+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
+// =============================================================================
+
+const VALID_MODES = ['autopilot', 'confirm', 'validate'];
+
+function validateInputs(rootPath, workItemId, intentId, mode) {
+  if (!rootPath || typeof rootPath !== 'string' || rootPath.trim() === '') {
+    throw fireError('rootPath is required.', 'INIT_001', 'Provide a valid project root path.');
+  }
+
+  if (!workItemId || typeof workItemId !== 'string' || workItemId.trim() === '') {
+    throw fireError('workItemId is required.', 'INIT_010', 'Provide a valid work item ID.');
+  }
+
+  if (!intentId || typeof intentId !== 'string' || intentId.trim() === '') {
+    throw fireError('intentId is required.', 'INIT_020', 'Provide a valid intent ID.');
+  }
+
+  if (!mode || !VALID_MODES.includes(mode)) {
+    throw fireError(
+      `Invalid mode: "${mode}".`,
+      'INIT_030',
+      `Valid modes are: ${VALID_MODES.join(', ')}`
+    );
+  }
+
+  if (!fs.existsSync(rootPath)) {
+    throw fireError(
+      `Project root not found: "${rootPath}".`,
+      'INIT_040',
+      'Ensure the path exists and is accessible.'
+    );
+  }
+}
+
+function validateFireProject(rootPath) {
+  const fireDir = path.join(rootPath, '.specs-fire');
+  const statePath = path.join(fireDir, 'state.yaml');
+  const runsPath = path.join(fireDir, 'runs');
+
+  if (!fs.existsSync(fireDir)) {
+    throw fireError(
+      `FIRE project not initialized at: "${rootPath}".`,
+      'INIT_041',
+      'Run fire-init first to initialize the project.'
+    );
+  }
+
+  if (!fs.existsSync(statePath)) {
+    throw fireError(
+      `State file not found at: "${statePath}".`,
+      'INIT_042',
+      'The project may be corrupted. Try re-initializing.'
+    );
+  }
+
+  return { fireDir, statePath, runsPath };
+}
+
+// =============================================================================
+// 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.', 'INIT_050', 'Check state.yaml format.');
+    }
+    return state;
+  } catch (err) {
+    if (err.code && err.code.startsWith('INIT_')) throw err;
+    throw fireError(
+      `Failed to read state file: ${err.message}`,
+      'INIT_051',
+      '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}`,
+      'INIT_052',
+      'Check file permissions and disk space.'
+    );
+  }
+}
+
+// =============================================================================
+// Run ID Generation (CRITICAL - checks both history and file system)
+// =============================================================================
+
+function generateRunId(runsPath, state) {
+  // Ensure runs directory exists
+  if (!fs.existsSync(runsPath)) {
+    fs.mkdirSync(runsPath, { recursive: true });
+  }
+
+  // Source 1: Get max from state.yaml runs.completed history
+  let maxFromHistory = 0;
+  if (state.runs && Array.isArray(state.runs.completed)) {
+    for (const run of state.runs.completed) {
+      if (run.id) {
+        const match = run.id.match(/^run-(\d+)$/);
+        if (match) {
+          const num = parseInt(match[1], 10);
+          if (num > maxFromHistory) maxFromHistory = num;
+        }
+      }
+    }
+  }
+
+  // Source 2: Get max from file system (defensive)
+  let maxFromFileSystem = 0;
+  try {
+    const entries = fs.readdirSync(runsPath);
+    for (const entry of entries) {
+      if (/^run-\d{3,}$/.test(entry)) {
+        const num = parseInt(entry.replace('run-', ''), 10);
+        if (num > maxFromFileSystem) maxFromFileSystem = num;
+      }
+    }
+  } catch (err) {
+    throw fireError(
+      `Failed to read runs directory: ${err.message}`,
+      'INIT_060',
+      'Check directory permissions.'
+    );
+  }
+
+  // Use MAX of both to ensure no duplicates
+  const maxNum = Math.max(maxFromHistory, maxFromFileSystem);
+  const nextNum = maxNum + 1;
+
+  return `run-${String(nextNum).padStart(3, '0')}`;
+}
+
+// =============================================================================
+// Run Folder Creation
+// =============================================================================
+
+function createRunFolder(runPath) {
+  try {
+    fs.mkdirSync(runPath, { recursive: true });
+  } catch (err) {
+    throw fireError(
+      `Failed to create run folder: ${err.message}`,
+      'INIT_070',
+      'Check directory permissions and disk space.'
+    );
+  }
+}
+
+function createRunLog(runPath, runId, workItemId, intentId, mode, startTime) {
+  const runLog = `---
+id: ${runId}
+work_item: ${workItemId}
+intent: ${intentId}
+mode: ${mode}
+status: in_progress
+started: ${startTime}
+completed: null
+---
+
+# Run: ${runId}
+
+## Work Item
+${workItemId}
+
+## Files Created
+(none yet)
+
+## Files Modified
+(none yet)
+
+## Decisions
+(none yet)
+`;
+
+  const runLogPath = path.join(runPath, 'run.md');
+  try {
+    fs.writeFileSync(runLogPath, runLog);
+  } catch (err) {
+    throw fireError(
+      `Failed to create run log: ${err.message}`,
+      'INIT_071',
+      'Check file permissions.'
+    );
+  }
+}
+
+// =============================================================================
+// Main Function
+// =============================================================================
+
+function initRun(rootPath, workItemId, intentId, mode) {
+  // Validate inputs
+  validateInputs(rootPath, workItemId, intentId, mode);
+
+  // Validate FIRE project structure
+  const { statePath, runsPath } = validateFireProject(rootPath);
+
+  // 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.`
+    );
+  }
+
+  // Generate run ID (checks both history AND file system)
+  const runId = generateRunId(runsPath, state);
+  const runPath = path.join(runsPath, runId);
+
+  // Create run folder
+  createRunFolder(runPath);
+
+  // Create run log
+  const startTime = new Date().toISOString();
+  createRunLog(runPath, runId, workItemId, intentId, mode, startTime);
+
+  // Update state with active run
+  state.active_run = {
+    id: runId,
+    work_item: workItemId,
+    intent: intentId,
+    mode: mode,
+    started: startTime,
+  };
+
+  // Save state
+  writeState(statePath, state);
+
+  // Return result
+  return {
+    success: true,
+    runId: runId,
+    runPath: runPath,
+    workItemId: workItemId,
+    intentId: intentId,
+    mode: mode,
+    started: startTime,
+  };
+}
+
+// =============================================================================
+// CLI Interface
+// =============================================================================
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 4) {
+    console.error('Usage: node init-run.js <rootPath> <workItemId> <intentId> <mode>');
+    console.error('');
+    console.error('Arguments:');
+    console.error('  rootPath    - Project root directory');
+    console.error('  workItemId  - Work item ID to execute');
+    console.error('  intentId    - Intent ID containing the work item');
+    console.error('  mode        - Execution mode (autopilot, confirm, validate)');
+    console.error('');
+    console.error('Example:');
+    console.error('  node init-run.js /my/project login-endpoint user-auth confirm');
+    process.exit(1);
+  }
+
+  const [rootPath, workItemId, intentId, mode] = args;
+
+  try {
+    const result = initRun(rootPath, workItemId, intentId, mode);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { initRun };

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 FIRE Run {{run_id}}*

package/flows/fire/agents/orchestrator/skills/project-init/SKILL.md

@@ -104,8 +104,11 @@ Initialize a new FIRE project by detecting workspace type and setting up standar
     <action>Create .specs-fire/runs/</action>
     <action>Create .specs-fire/standards/</action>
     <action>Generate .specs-fire/state.yaml (include autonomy_bias)</action>
-    <action>Generate .specs-fire/standards/tech-stack.md</action>
-    <action>Generate .specs-fire/standards/coding-standards.md</action>
+    <action>Generate standards using templates:</action>
+    <substep>tech-stack.md — templates/tech-stack.md.hbs</substep>
+    <substep>coding-standards.md — templates/coding-standards.md.hbs</substep>
+    <substep>testing-standards.md — templates/testing-standards.md.hbs</substep>
+    <substep>system-architecture.md — templates/system-architecture.md.hbs</substep>
   </step>
 
   <step n="6" title="Complete">
@@ -120,7 +123,9 @@ Initialize a new FIRE project by detecting workspace type and setting up standar
       ├── runs/
       └── standards/
           ├── tech-stack.md
-          └── coding-standards.md
+          ├── coding-standards.md
+          ├── testing-standards.md
+          └── system-architecture.md
       ```
 
       Ready to capture your first intent.
@@ -136,6 +141,10 @@ Initialize a new FIRE project by detecting workspace type and setting up standar
 
 ## Output
 
-- `.specs-fire/state.yaml` — Central state file
-- `.specs-fire/standards/tech-stack.md` — Technology choices
-- `.specs-fire/standards/coding-standards.md` — Coding conventions
+| Artifact | Location | Template |
+|----------|----------|----------|
+| State | `.specs-fire/state.yaml` | — |
+| Tech Stack | `.specs-fire/standards/tech-stack.md` | `templates/tech-stack.md.hbs` |
+| Coding Standards | `.specs-fire/standards/coding-standards.md` | `templates/coding-standards.md.hbs` |
+| Testing Standards | `.specs-fire/standards/testing-standards.md` | `templates/testing-standards.md.hbs` |
+| System Architecture | `.specs-fire/standards/system-architecture.md` | `templates/system-architecture.md.hbs` |

package/flows/fire/agents/orchestrator/skills/project-init/templates/coding-standards.md.hbs

@@ -0,0 +1,149 @@
+# Coding Standards
+
+## Overview
+
+{{overview}}
+
+## Code Formatting
+
+**Tool**: {{formatter}}
+**Config**: {{formatter_config}}
+**Enforcement**: {{formatter_enforcement}}
+
+### Key Settings
+
+{{#each formatter_settings}}
+- **{{this.setting}}**: {{this.value}}
+{{/each}}
+
+## Linting
+
+**Tool**: {{linter}}
+**Base Config**: {{linter_base}}
+**Strictness**: {{linter_strictness}}
+
+### Key Rules
+
+{{#each linter_rules}}
+- `{{this.rule}}`: {{this.setting}} — {{this.rationale}}
+{{/each}}
+
+## Naming Conventions
+
+### Variables and Functions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+{{#each naming_conventions}}
+| {{this.element}} | {{this.convention}} | `{{this.example}}` |
+{{/each}}
+
+### Files and Folders
+
+{{#each file_naming}}
+- **{{this.type}}**: {{this.convention}} (e.g., `{{this.example}}`)
+{{/each}}
+
+## File Organization
+
+### Project Structure
+
+```
+{{project_structure}}
+```
+
+### Conventions
+
+{{#each organization_conventions}}
+- **{{this.item}}**: {{this.convention}}
+{{/each}}
+
+## Import Order
+
+```{{language}}
+{{import_order_example}}
+```
+
+**Rules**:
+{{#each import_rules}}
+- {{this}}
+{{/each}}
+
+## Error Handling
+
+### Pattern
+
+**Approach**: {{error_pattern}}
+
+### Guidelines
+
+{{#each error_guidelines}}
+- {{this}}
+{{/each}}
+
+### Example
+
+```{{language}}
+{{error_example}}
+```
+
+## Logging
+
+**Tool**: {{logging_tool}}
+**Format**: {{logging_format}}
+
+### Log Levels
+
+| Level | Usage |
+|-------|-------|
+{{#each log_levels}}
+| {{this.level}} | {{this.usage}} |
+{{/each}}
+
+### Guidelines
+
+**Always log**:
+{{#each log_always}}
+- {{this}}
+{{/each}}
+
+**Never log**:
+{{#each log_never}}
+- {{this}}
+{{/each}}
+
+## Comments and Documentation
+
+### When to Comment
+
+{{#each comment_guidelines}}
+- {{this}}
+{{/each}}
+
+### Documentation Format
+
+**Functions**: {{doc_format_functions}}
+**Classes**: {{doc_format_classes}}
+
+## Code Patterns
+
+### Preferred Patterns
+
+{{#each preferred_patterns}}
+#### {{this.name}}
+
+{{this.description}}
+
+```{{../language}}
+{{this.example}}
+```
+{{/each}}
+
+### Anti-Patterns to Avoid
+
+{{#each anti_patterns}}
+- **{{this.name}}**: {{this.why}}
+{{/each}}
+
+---
+*Generated by FIRE project-init*

package/flows/fire/agents/orchestrator/skills/project-init/templates/system-architecture.md.hbs

@@ -0,0 +1,101 @@
+# System Architecture
+
+## Overview
+
+{{overview}}
+
+## System Context
+
+{{system_context}}
+
+### Context Diagram
+
+```
+{{context_diagram}}
+```
+
+### Users
+
+{{#each users}}
+- **{{this.name}}**: {{this.description}}
+{{/each}}
+
+### External Systems
+
+{{#each external_systems}}
+- **{{this.name}}**: {{this.purpose}}
+{{/each}}
+
+## Architecture Pattern
+
+**Pattern**: {{architecture_pattern}}
+**Rationale**: {{architecture_rationale}}
+
+## Component Architecture
+
+### Components
+
+{{#each components}}
+#### {{this.name}}
+
+- **Purpose**: {{this.purpose}}
+- **Responsibilities**: {{this.responsibilities}}
+- **Dependencies**: {{this.dependencies}}
+{{/each}}
+
+### Component Diagram
+
+```
+{{component_diagram}}
+```
+
+## Data Flow
+
+{{data_flow_description}}
+
+```
+{{data_flow_diagram}}
+```
+
+## Technology Stack
+
+| Layer | Technology | Purpose |
+|-------|------------|---------|
+{{#each tech_stack}}
+| {{this.layer}} | {{this.technology}} | {{this.purpose}} |
+{{/each}}
+
+## Non-Functional Requirements
+
+### Performance
+
+{{#each nfr_performance}}
+- **{{this.metric}}**: {{this.target}}
+{{/each}}
+
+### Security
+
+{{#each nfr_security}}
+- {{this}}
+{{/each}}
+
+### Scalability
+
+{{scalability_approach}}
+
+## Constraints
+
+{{#each constraints}}
+- {{this}}
+{{/each}}
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+{{#each key_decisions}}
+| {{this.decision}} | {{this.choice}} | {{this.rationale}} |
+{{/each}}
+
+---
+*Generated by FIRE project-init*