specsmd 0.0.0-dev.79 → 0.0.0-dev.80

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

@@ -44,6 +44,12 @@ You are the **Builder Agent** for FIRE (Fast Intent-Run Engineering).
 
   <step n="4" title="Route by State">
     <check if="active run exists">
+      <action>Read runs.active[0] from state.yaml</action>
+      <action>Read scope (single/batch/wide) and work_items array</action>
+      <action>Count items by status: completed, in_progress, pending</action>
+      <output>Active run {id} ({scope}) — {completed_count} done, {remaining_count} remaining</output>
+      <mandate>DO NOT treat completed items as needing re-execution</mandate>
+      <mandate>ONLY work on the current_item from state.yaml</mandate>
       <action>Resume execution — invoke run-execute skill</action>
     </check>
     <check if="pending work items exist">

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

@@ -61,28 +61,48 @@ Supports both single-item and multi-item (batch/wide) runs.
     </check>
 
     <check if="runs.active has entries">
-      <action>Load run state from .specs-fire/runs/{runs.active[0].id}/run.md</action>
-      <action>Get current_item and its status from state.yaml</action>
-      <action>Check for existing artifacts and LOAD if present:</action>
-
-      <substep>design.md → if exists, LOAD from .specs-fire/intents/{intent}/work-items/{id}-design.md</substep>
-      <substep>plan.md → if exists, LOAD from .specs-fire/runs/{run-id}/plan.md (skip plan generation)</substep>
-      <substep>test-report.md → if exists, tests already passed (skip to Step 6b)</substep>
-      <substep>review-report.md → if exists, review done (skip to Step 7)</substep>
-
-      <determine_resume_point>
-        | Artifacts Present | Resume At |
-        |-------------------|-----------|
-        | None | Step 3 (Generate Plan) |
-        | plan.md only | Step 5 (Implementation) |
-        | plan.md + test-report.md | Step 6b (Code Review) |
-        | plan.md + test-report.md + review-report.md | Step 7 (Complete Item) |
-      </determine_resume_point>
+      <action>Load active run from state.yaml runs.active[0]</action>
+      <action>Read scope (single/batch/wide) and work_items array</action>
+
+      <substep n="0a" title="Enumerate Work Item Status">
+        <action>For EACH work item in runs.active[0].work_items, classify by status:</action>
+        <action>Build status summary from state.yaml (NOT from artifact files):</action>
+        <format>
+          [DONE] {item-id} — completed
+          [WORKING] {item-id} (phase: {current_phase}) — in_progress
+          [PENDING] {item-id} — pending
+        </format>
+        <action>Count: completed={X}, in_progress={Y}, pending={Z}</action>
+      </substep>
+
+      <substep n="0b" title="Determine Resume Point for Current Item">
+        <action>Get current_item from state.yaml</action>
+        <action>Read current_phase from the current item's entry in work_items</action>
+
+        <determine_resume_point>
+          Use current_phase from state.yaml to determine resume point:
+
+          | current_phase | Resume At |
+          |---------------|-----------|
+          | plan (or unset) | Step 3 (Generate Plan) |
+          | execute | Step 5 (Implementation) |
+          | test | Step 6 (Run Tests) |
+          | review | Step 6b (Code Review) |
+        </determine_resume_point>
+      </substep>
+
+      <llm critical="true">
+        <mandate>NEVER call --complete-item for items with status "completed" — they are already done</mandate>
+        <mandate>NEVER re-execute steps (plan, implement, test) for completed items</mandate>
+        <mandate>ONLY work on the current_item identified in state.yaml</mandate>
+        <mandate>Use current_phase from state.yaml — do NOT infer phase from artifact file existence</mandate>
+      </llm>
 
       <output>
-        Resuming run {run-id} for work item {current_item}.
+        Resuming run {run-id} ({scope}) for work item {current_item}.
         Mode: {mode}
-        Loaded existing artifacts: {artifact_list}
+        Phase: {current_phase}
+        Status: {completed_count} done, {in_progress_count} working, {pending_count} pending
         Resuming at: Step {step_number}
       </output>
     </check>

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

@@ -21,6 +21,7 @@
  *   --decisions=JSON       - JSON array of {decision, choice, rationale}
  *   --tests=N              - Number of tests added
  *   --coverage=N           - Coverage percentage
+ *   --force                - Override phase guard (skip review phase check)
  */
 
 const fs = require('fs');
@@ -391,7 +392,7 @@ function updateRunLog(runLogPath, activeRun, params, completedTime, isFullComple
 // Complete Current Item (for batch runs)
 // =============================================================================
 
-function completeCurrentItem(rootPath, runId, params = {}) {
+function completeCurrentItem(rootPath, runId, params = {}, options = {}) {
   const completionParams = {
     filesCreated: params.filesCreated || [],
     filesModified: params.filesModified || [],
@@ -399,6 +400,7 @@ function completeCurrentItem(rootPath, runId, params = {}) {
     testsAdded: params.testsAdded || 0,
     coverage: params.coverage || 0,
   };
+  const force = options.force || false;
 
   validateInputs(rootPath, runId);
   const { statePath, runLogPath } = validateFireProject(rootPath, runId);
@@ -440,6 +442,16 @@ function completeCurrentItem(rootPath, runId, params = {}) {
     );
   }
 
+  // Phase guard: item must be at 'review' phase before completion
+  const currentPhase = workItems[currentItemIndex].current_phase;
+  if (!force && currentPhase !== 'review') {
+    throw fireError(
+      `Cannot complete item "${currentItemId}" — current phase is "${currentPhase || 'unknown'}", not "review".`,
+      'COMPLETE_051',
+      'The item must reach the review phase before completion. Use --force to override.'
+    );
+  }
+
   // Find next pending item
   let nextItem = null;
   for (let i = currentItemIndex + 1; i < workItems.length; i++) {
@@ -497,7 +509,7 @@ function completeCurrentItem(rootPath, runId, params = {}) {
 // Complete Entire Run
 // =============================================================================
 
-function completeRun(rootPath, runId, params = {}) {
+function completeRun(rootPath, runId, params = {}, options = {}) {
   const completionParams = {
     filesCreated: params.filesCreated || [],
     filesModified: params.filesModified || [],
@@ -505,6 +517,7 @@ function completeRun(rootPath, runId, params = {}) {
     testsAdded: params.testsAdded || 0,
     coverage: params.coverage || 0,
   };
+  const force = options.force || false;
 
   validateInputs(rootPath, runId);
   const { statePath, runLogPath } = validateFireProject(rootPath, runId);
@@ -537,6 +550,21 @@ function completeRun(rootPath, runId, params = {}) {
   const workItems = activeRun.work_items || [];
   const scope = activeRun.scope || 'single';
 
+  // Phase guard: all non-completed items must be at 'review' phase
+  if (!force) {
+    const notReady = workItems.filter(
+      item => item.status !== 'completed' && item.current_phase !== 'review'
+    );
+    if (notReady.length > 0) {
+      const list = notReady.map(i => `${i.id} (phase: ${i.current_phase || 'unknown'})`).join(', ');
+      throw fireError(
+        `Cannot complete run — ${notReady.length} item(s) have not reached review phase: ${list}.`,
+        'COMPLETE_060',
+        'All items must reach the review phase before run completion. Use --force to override.'
+      );
+    }
+  }
+
   // Mark all items as completed
   for (const item of workItems) {
     if (item.status !== 'completed') {
@@ -636,6 +664,7 @@ function parseArgs(args) {
     runId: args[1],
     completeItem: false,
     completeRunFlag: false,
+    force: false,
     filesCreated: [],
     filesModified: [],
     decisions: [],
@@ -649,6 +678,8 @@ function parseArgs(args) {
       result.completeItem = true;
     } else if (arg === '--complete-run') {
       result.completeRunFlag = true;
+    } else if (arg === '--force') {
+      result.force = true;
     } else if (arg.startsWith('--files-created=')) {
       try {
         result.filesCreated = JSON.parse(arg.substring('--files-created='.length));
@@ -690,6 +721,7 @@ function printUsage() {
   console.error('Flags:');
   console.error('  --complete-item  - Complete only the current work item (batch/wide runs)');
   console.error('  --complete-run   - Complete the entire run');
+  console.error('  --force          - Override phase guard (skip review phase check)');
   console.error('');
   console.error('Options:');
   console.error('  --files-created=JSON   - JSON array of {path, purpose}');
@@ -718,6 +750,7 @@ if (require.main === module) {
   const params = parseArgs(args);
 
   try {
+    const cliOptions = { force: params.force };
     let result;
     if (params.completeItem) {
       result = completeCurrentItem(params.rootPath, params.runId, {
@@ -726,7 +759,7 @@ if (require.main === module) {
         decisions: params.decisions,
         testsAdded: params.testsAdded,
         coverage: params.coverage,
-      });
+      }, cliOptions);
     } else {
       // Default: complete entire run
       result = completeRun(params.rootPath, params.runId, {
@@ -735,7 +768,7 @@ if (require.main === module) {
         decisions: params.decisions,
         testsAdded: params.testsAdded,
         coverage: params.coverage,
-      });
+      }, cliOptions);
     }
     console.log(JSON.stringify(result, null, 2));
     process.exit(0);

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

@@ -113,6 +113,18 @@ Plan the scope of a run by discovering available work items and suggesting group
         </action>
       </check>
 
+      <check if="state says completed but item is in runs.active[].work_items with current_phase != review">
+        <output>
+          **Suspect completion**: {work-item-id}
+          - state.yaml status: completed
+          - But current_phase: {current_phase} (not "review")
+          - Item is still in active run {run-id}
+          Resetting to in_progress — item was likely marked complete prematurely.
+        </output>
+        <action>Reset work item status to in_progress in state.yaml</action>
+        <action>Update frontmatter to match</action>
+      </check>
+
       <check if="in state.yaml but file missing">
         <output>Warning: {item} in state but file not found on disk</output>
       </check>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.0.0-dev.79",
+  "version": "0.0.0-dev.80",
   "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
   "main": "lib/installer.js",
   "bin": {