specsmd 0.1.44 → 0.1.46

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

@@ -204,6 +204,8 @@ Supports both single-item and multi-item (batch/wide) runs.
     <action>Save plan IMMEDIATELY using template: templates/plan.md.hbs</action>
     <action>Write to: .specs-fire/runs/{run-id}/plan.md</action>
     <output>Plan saved to: .specs-fire/runs/{run-id}/plan.md</output>
+    <action>Mark checkpoint as waiting:</action>
+    <code>node scripts/update-checkpoint.cjs {rootPath} {runId} awaiting_approval --checkpoint=plan</code>
 
     <checkpoint>
       <template_output section="plan">
@@ -232,6 +234,8 @@ Supports both single-item and multi-item (batch/wide) runs.
       <action>Update plan.md with changes</action>
       <goto step="3b"/>
     </check>
+    <action>Mark checkpoint approved:</action>
+    <code>node scripts/update-checkpoint.cjs {rootPath} {runId} approved --checkpoint=plan</code>
     <goto step="5"/>
   </step>
 
@@ -242,6 +246,8 @@ Supports both single-item and multi-item (batch/wide) runs.
     <action>Write to: .specs-fire/runs/{run-id}/plan.md</action>
     <action>Include reference to design doc in plan</action>
     <output>Plan saved to: .specs-fire/runs/{run-id}/plan.md</output>
+    <action>Mark checkpoint as waiting:</action>
+    <code>node scripts/update-checkpoint.cjs {rootPath} {runId} awaiting_approval --checkpoint=plan</code>
 
     <checkpoint>
       <template_output section="plan">
@@ -270,6 +276,8 @@ Supports both single-item and multi-item (batch/wide) runs.
       <action>Update plan.md with changes</action>
       <goto step="3c"/>
     </check>
+    <action>Mark checkpoint approved:</action>
+    <code>node scripts/update-checkpoint.cjs {rootPath} {runId} approved --checkpoint=plan</code>
     <goto step="5"/>
   </step>
 
@@ -520,6 +528,7 @@ Supports both single-item and multi-item (batch/wide) runs.
   | Script | Purpose | Usage |
   |--------|---------|-------|
   | `scripts/init-run.cjs` | Initialize run record and folder | Creates run.md with all work items |
+  | `scripts/update-checkpoint.cjs` | Mark approval gate state for active item | `awaiting_approval` / `approved` |
   | `scripts/update-phase.cjs` | Update current work item's phase | `node scripts/update-phase.cjs {rootPath} {runId} {phase}` |
   | `scripts/complete-run.cjs` | Finalize run and update state | `--complete-item` or `--complete-run` |
 

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

@@ -305,6 +305,9 @@ function updateRunLog(runLogPath, activeRun, params, completedTime, isFullComple
       intent: item.intent,
       mode: item.mode,
       status: item.status,
+      current_phase: item.current_phase || null,
+      checkpoint_state: item.checkpoint_state || null,
+      current_checkpoint: item.current_checkpoint || null,
     }));
   }
 
@@ -427,6 +430,12 @@ function completeCurrentItem(rootPath, runId, params = {}) {
     if (workItems[i].id === currentItemId) {
       workItems[i].status = 'completed';
       workItems[i].completed_at = completedTime;
+      if (workItems[i].mode === 'confirm' || workItems[i].mode === 'validate') {
+        workItems[i].checkpoint_state = 'approved';
+        workItems[i].current_checkpoint = workItems[i].current_checkpoint || 'plan';
+      } else {
+        workItems[i].checkpoint_state = workItems[i].checkpoint_state || 'not_required';
+      }
       currentItemIndex = i;
       break;
     }
@@ -446,6 +455,10 @@ function completeCurrentItem(rootPath, runId, params = {}) {
     if (workItems[i].status === 'pending') {
       workItems[i].status = 'in_progress';
       workItems[i].current_phase = 'plan';
+      workItems[i].checkpoint_state = 'none';
+      workItems[i].current_checkpoint = (workItems[i].mode === 'confirm' || workItems[i].mode === 'validate')
+        ? 'plan'
+        : null;
       nextItem = workItems[i];
       break;
     }
@@ -543,6 +556,12 @@ function completeRun(rootPath, runId, params = {}) {
       item.status = 'completed';
       item.completed_at = completedTime;
     }
+    if (item.mode === 'confirm' || item.mode === 'validate') {
+      item.checkpoint_state = 'approved';
+      item.current_checkpoint = item.current_checkpoint || 'plan';
+    } else {
+      item.checkpoint_state = item.checkpoint_state || 'not_required';
+    }
   }
 
   activeRun.work_items = workItems;

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

@@ -233,7 +233,11 @@ function createRunLog(runPath, runId, workItems, scope, startTime) {
   // Format work items for run.md
   const workItemsList = workItems.map((item, index) => {
     const status = index === 0 ? 'in_progress' : 'pending';
-    return `  - id: ${item.id}\n    intent: ${item.intent}\n    mode: ${item.mode}\n    status: ${status}`;
+    const currentPhase = index === 0 ? 'plan' : 'null';
+    const currentCheckpoint = index === 0 && (item.mode === 'confirm' || item.mode === 'validate')
+      ? 'plan'
+      : 'null';
+    return `  - id: ${item.id}\n    intent: ${item.intent}\n    mode: ${item.mode}\n    status: ${status}\n    current_phase: ${currentPhase}\n    checkpoint_state: none\n    current_checkpoint: ${currentCheckpoint}`;
   }).join('\n');
 
   const currentItem = workItems[0];
@@ -346,6 +350,10 @@ function initRun(rootPath, workItems, scope) {
     mode: item.mode,
     status: index === 0 ? 'in_progress' : 'pending',
     current_phase: index === 0 ? 'plan' : null,
+    checkpoint_state: 'none',
+    current_checkpoint: (index === 0 && (item.mode === 'confirm' || item.mode === 'validate'))
+      ? 'plan'
+      : null,
   }));
 
   // Add to active runs list (supports multiple parallel runs)

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-001 awaiting_approval --checkpoint=plan
+ *   node update-checkpoint.cjs /project run-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-001 awaiting_approval --checkpoint=plan');
+  console.error('  node update-checkpoint.cjs /project run-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

@@ -171,6 +171,17 @@ function updatePhase(rootPath, runId, phase) {
     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;
     }

package/lib/dashboard/fire/model.js

@@ -78,6 +78,15 @@ function normalizeTimestamp(value) {
   return String(value);
 }
 
+function normalizeCheckpointState(value) {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const normalized = value.toLowerCase().trim().replace(/[\s-]+/g, '_');
+  return normalized === '' ? undefined : normalized;
+}
+
 function parseDependencies(raw) {
   if (Array.isArray(raw)) {
     return raw.filter((item) => typeof item === 'string' && item.trim() !== '');
@@ -97,7 +106,9 @@ function normalizeRunWorkItem(raw, fallbackIntentId = '') {
       intentId: fallbackIntentId,
       mode: 'confirm',
       status: 'pending',
-      currentPhase: undefined
+      currentPhase: undefined,
+      checkpointState: undefined,
+      currentCheckpoint: undefined
     };
   }
 
@@ -107,7 +118,9 @@ function normalizeRunWorkItem(raw, fallbackIntentId = '') {
       intentId: fallbackIntentId,
       mode: 'confirm',
       status: 'pending',
-      currentPhase: undefined
+      currentPhase: undefined,
+      checkpointState: undefined,
+      currentCheckpoint: undefined
     };
   }
 
@@ -121,13 +134,27 @@ function normalizeRunWorkItem(raw, fallbackIntentId = '') {
   const currentPhase = typeof raw.current_phase === 'string'
     ? raw.current_phase
     : (typeof raw.currentPhase === 'string' ? raw.currentPhase : undefined);
+  const checkpointState = typeof raw.checkpoint_state === 'string'
+    ? raw.checkpoint_state
+    : (typeof raw.checkpointState === 'string'
+      ? raw.checkpointState
+      : (typeof raw.approval_state === 'string'
+        ? raw.approval_state
+        : (typeof raw.approvalState === 'string' ? raw.approvalState : undefined)));
+  const currentCheckpoint = typeof raw.current_checkpoint === 'string'
+    ? raw.current_checkpoint
+    : (typeof raw.currentCheckpoint === 'string'
+      ? raw.currentCheckpoint
+      : (typeof raw.checkpoint === 'string' ? raw.checkpoint : undefined));
 
   return {
     id,
     intentId,
     mode,
     status,
-    currentPhase
+    currentPhase,
+    checkpointState,
+    currentCheckpoint
   };
 }
 
@@ -206,7 +233,18 @@ function normalizeState(rawState) {
       currentItem: typeof run.current_item === 'string'
         ? run.current_item
         : (typeof run.currentItem === 'string' ? run.currentItem : ''),
-      started: normalizeTimestamp(run.started) || ''
+      started: normalizeTimestamp(run.started) || '',
+      checkpointState: normalizeCheckpointState(
+        run.checkpoint_state
+        || run.checkpointState
+        || run.approval_state
+        || run.approvalState
+      ),
+      currentCheckpoint: typeof run.current_checkpoint === 'string'
+        ? run.current_checkpoint
+        : (typeof run.currentCheckpoint === 'string'
+          ? run.currentCheckpoint
+          : (typeof run.checkpoint === 'string' ? run.checkpoint : undefined))
     };
   }).filter(Boolean);
 
@@ -221,6 +259,17 @@ function normalizeState(rawState) {
     return {
       id: typeof run.id === 'string' ? run.id : '',
       workItems: workItemsRaw.map((item) => normalizeRunWorkItem(item, fallbackIntentId)).filter((item) => item.id !== ''),
+      checkpointState: normalizeCheckpointState(
+        run.checkpoint_state
+        || run.checkpointState
+        || run.approval_state
+        || run.approvalState
+      ),
+      currentCheckpoint: typeof run.current_checkpoint === 'string'
+        ? run.current_checkpoint
+        : (typeof run.currentCheckpoint === 'string'
+          ? run.currentCheckpoint
+          : (typeof run.checkpoint === 'string' ? run.checkpoint : undefined)),
       completed: normalizeTimestamp(run.completed) || ''
     };
   }).filter(Boolean);

package/lib/dashboard/fire/parser.js

@@ -65,6 +65,21 @@ function listMarkdownFiles(dirPath) {
   }
 }
 
+function getFirstStringValue(record, keys) {
+  if (!record || typeof record !== 'object') {
+    return undefined;
+  }
+
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === 'string' && value.trim() !== '') {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
 function parseRunLog(runLogPath) {
   const content = readFileSafe(runLogPath);
   if (!content) {
@@ -73,15 +88,40 @@ function parseRunLog(runLogPath) {
       workItems: [],
       currentItem: null,
       startedAt: undefined,
-      completedAt: undefined
+      completedAt: undefined,
+      checkpointState: undefined,
+      currentCheckpoint: undefined
     };
   }
 
   const frontmatter = parseFrontmatter(content);
+  const currentItem = getFirstStringValue(frontmatter, ['current_item', 'currentItem', 'work_item', 'workItem']);
+  const itemMode = getFirstStringValue(frontmatter, ['mode']);
+  const itemStatus = getFirstStringValue(frontmatter, ['status']);
+  const itemPhase = getFirstStringValue(frontmatter, ['current_phase', 'currentPhase']);
+  const itemCheckpointState = getFirstStringValue(frontmatter, [
+    'checkpoint_state',
+    'checkpointState',
+    'approval_state',
+    'approvalState'
+  ]);
+  const itemCheckpoint = getFirstStringValue(frontmatter, ['current_checkpoint', 'currentCheckpoint', 'checkpoint']);
+
   const workItemsRaw = Array.isArray(frontmatter.work_items)
     ? frontmatter.work_items
     : (Array.isArray(frontmatter.workItems) ? frontmatter.workItems : []);
 
+  if (workItemsRaw.length === 0 && typeof currentItem === 'string' && currentItem !== '') {
+    workItemsRaw.push({
+      id: currentItem,
+      mode: itemMode,
+      status: itemStatus,
+      current_phase: itemPhase,
+      checkpoint_state: itemCheckpointState,
+      current_checkpoint: itemCheckpoint
+    });
+  }
+
   const workItems = workItemsRaw
     .map((item) => normalizeRunWorkItem(item))
     .filter((item) => item.id !== '');
@@ -89,16 +129,54 @@ function parseRunLog(runLogPath) {
   return {
     scope: normalizeScope(frontmatter.scope),
     workItems,
-    currentItem: typeof frontmatter.current_item === 'string'
-      ? frontmatter.current_item
-      : (typeof frontmatter.currentItem === 'string' ? frontmatter.currentItem : null),
+    currentItem: currentItem || null,
     startedAt: typeof frontmatter.started === 'string' ? frontmatter.started : undefined,
     completedAt: typeof frontmatter.completed === 'string'
       ? frontmatter.completed
-      : undefined
+      : undefined,
+    checkpointState: itemCheckpointState,
+    currentCheckpoint: itemCheckpoint
   };
 }
 
+function mergeRunWorkItems(primaryItems, fallbackItems) {
+  const primary = Array.isArray(primaryItems) ? primaryItems : [];
+  const fallback = Array.isArray(fallbackItems) ? fallbackItems : [];
+
+  if (primary.length === 0) {
+    return fallback;
+  }
+
+  if (fallback.length === 0) {
+    return primary;
+  }
+
+  const fallbackById = new Map(fallback.map((item) => [item.id, item]));
+  const merged = primary.map((item) => {
+    const fallbackItem = fallbackById.get(item.id);
+    if (!fallbackItem) {
+      return item;
+    }
+
+    return {
+      ...fallbackItem,
+      ...item,
+      checkpointState: item.checkpointState || fallbackItem.checkpointState,
+      currentCheckpoint: item.currentCheckpoint || fallbackItem.currentCheckpoint,
+      currentPhase: item.currentPhase || fallbackItem.currentPhase
+    };
+  });
+
+  const knownIds = new Set(merged.map((item) => item.id));
+  for (const fallbackItem of fallback) {
+    if (!knownIds.has(fallbackItem.id)) {
+      merged.push(fallbackItem);
+    }
+  }
+
+  return merged;
+}
+
 function scanWorkItems(intentPath, intentId, stateWorkItems, warnings) {
   const workItemsPath = path.join(intentPath, 'work-items');
   const fileWorkItemIds = listMarkdownFiles(workItemsPath)
@@ -202,11 +280,15 @@ function scanRuns(rootPath, normalizedState) {
     const stateActiveRun = stateActiveMap.get(runId);
     const stateCompletedRun = stateCompletedMap.get(runId);
 
-    const workItems = (stateActiveRun?.workItems && stateActiveRun.workItems.length > 0)
+    const stateRunWorkItems = (stateActiveRun?.workItems && stateActiveRun.workItems.length > 0)
       ? stateActiveRun.workItems
       : ((stateCompletedRun?.workItems && stateCompletedRun.workItems.length > 0)
         ? stateCompletedRun.workItems
-        : parsedRunLog.workItems);
+        : []);
+    const workItems = mergeRunWorkItems(
+      stateRunWorkItems.length > 0 ? stateRunWorkItems : parsedRunLog.workItems,
+      parsedRunLog.workItems
+    );
 
     const completedAt = stateCompletedRun?.completed || parsedRunLog.completedAt || undefined;
 
@@ -215,6 +297,8 @@ function scanRuns(rootPath, normalizedState) {
       scope: stateActiveRun?.scope || parsedRunLog.scope || 'single',
       workItems,
       currentItem: stateActiveRun?.currentItem || parsedRunLog.currentItem || null,
+      checkpointState: stateActiveRun?.checkpointState || parsedRunLog.checkpointState,
+      currentCheckpoint: stateActiveRun?.currentCheckpoint || parsedRunLog.currentCheckpoint,
       folderPath,
       startedAt: stateActiveRun?.started || parsedRunLog.startedAt || '',
       completedAt: completedAt === 'null' ? undefined : completedAt,

package/lib/dashboard/tui/app.js

@@ -253,6 +253,313 @@ function getCurrentRun(snapshot) {
   return activeRuns[0] || null;
 }
 
+function normalizeToken(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.toLowerCase().trim().replace(/[\s-]+/g, '_');
+}
+
+function getCurrentFireWorkItem(run) {
+  const workItems = Array.isArray(run?.workItems) ? run.workItems : [];
+  if (workItems.length === 0) {
+    return null;
+  }
+  return workItems.find((item) => item.id === run.currentItem)
+    || workItems.find((item) => normalizeToken(item?.status) === 'in_progress')
+    || workItems[0]
+    || null;
+}
+
+function readFileTextSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function extractFrontmatterBlock(content) {
+  if (typeof content !== 'string') {
+    return null;
+  }
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return match ? match[1] : null;
+}
+
+function extractFrontmatterValue(frontmatterBlock, key) {
+  if (typeof frontmatterBlock !== 'string' || typeof key !== 'string' || key === '') {
+    return null;
+  }
+
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const expression = new RegExp(`^${escapedKey}\\s*:\\s*(.+)$`, 'mi');
+  const match = frontmatterBlock.match(expression);
+  if (!match) {
+    return null;
+  }
+
+  const raw = String(match[1] || '').trim();
+  if (raw === '') {
+    return '';
+  }
+
+  return raw
+    .replace(/^["']/, '')
+    .replace(/["']$/, '')
+    .trim();
+}
+
+const FIRE_AWAITING_APPROVAL_STATES = new Set([
+  'awaiting_approval',
+  'waiting',
+  'pending_approval',
+  'approval_needed',
+  'approval_required',
+  'checkpoint_pending'
+]);
+
+const FIRE_APPROVED_STATES = new Set([
+  'approved',
+  'confirmed',
+  'accepted',
+  'resumed',
+  'done',
+  'completed',
+  'cleared',
+  'none',
+  'not_required',
+  'skipped'
+]);
+
+function parseFirePlanCheckpointMetadata(run) {
+  if (!run || typeof run.folderPath !== 'string' || run.folderPath.trim() === '') {
+    return { hasPlan: false, checkpointState: null, checkpoint: null };
+  }
+
+  const planPath = path.join(run.folderPath, 'plan.md');
+  if (!fileExists(planPath)) {
+    return { hasPlan: false, checkpointState: null, checkpoint: null };
+  }
+
+  const content = readFileTextSafe(planPath);
+  const frontmatter = extractFrontmatterBlock(content);
+  if (!frontmatter) {
+    return { hasPlan: true, checkpointState: null, checkpoint: null };
+  }
+
+  const checkpointState = normalizeToken(
+    extractFrontmatterValue(frontmatter, 'checkpoint_state')
+    || extractFrontmatterValue(frontmatter, 'checkpointState')
+    || extractFrontmatterValue(frontmatter, 'approval_state')
+    || extractFrontmatterValue(frontmatter, 'approvalState')
+    || ''
+  ) || null;
+  const checkpoint = extractFrontmatterValue(frontmatter, 'current_checkpoint')
+    || extractFrontmatterValue(frontmatter, 'currentCheckpoint')
+    || extractFrontmatterValue(frontmatter, 'checkpoint')
+    || null;
+
+  return {
+    hasPlan: true,
+    checkpointState,
+    checkpoint
+  };
+}
+
+function resolveFireApprovalState(run, currentWorkItem) {
+  const itemState = normalizeToken(
+    currentWorkItem?.checkpointState
+    || currentWorkItem?.checkpoint_state
+    || currentWorkItem?.approvalState
+    || currentWorkItem?.approval_state
+    || ''
+  );
+  const runState = normalizeToken(
+    run?.checkpointState
+    || run?.checkpoint_state
+    || run?.approvalState
+    || run?.approval_state
+    || ''
+  );
+  const planState = parseFirePlanCheckpointMetadata(run);
+  const state = itemState || runState || planState.checkpointState || null;
+  const checkpoint = currentWorkItem?.currentCheckpoint
+    || currentWorkItem?.current_checkpoint
+    || run?.currentCheckpoint
+    || run?.current_checkpoint
+    || planState.checkpoint
+    || null;
+
+  return {
+    state,
+    checkpoint,
+    source: itemState
+      ? 'item-state'
+      : (runState
+        ? 'run-state'
+        : (planState.checkpointState ? 'plan-frontmatter' : null))
+  };
+}
+
+function getFireRunApprovalGate(run, currentWorkItem) {
+  const mode = normalizeToken(currentWorkItem?.mode);
+  const status = normalizeToken(currentWorkItem?.status);
+  if (!['confirm', 'validate'].includes(mode) || status !== 'in_progress') {
+    return null;
+  }
+
+  const phase = normalizeToken(getCurrentPhaseLabel(run, currentWorkItem));
+  if (phase !== 'plan') {
+    return null;
+  }
+
+  const resolvedApproval = resolveFireApprovalState(run, currentWorkItem);
+  if (!resolvedApproval.state) {
+    return null;
+  }
+
+  if (FIRE_APPROVED_STATES.has(resolvedApproval.state)) {
+    return null;
+  }
+
+  if (!FIRE_AWAITING_APPROVAL_STATES.has(resolvedApproval.state)) {
+    return null;
+  }
+
+  const modeLabel = String(currentWorkItem?.mode || 'confirm').toUpperCase();
+  const itemId = String(currentWorkItem?.id || run.currentItem || 'unknown-item');
+  const checkpointLabel = String(resolvedApproval.checkpoint || 'plan').replace(/[_\s]+/g, '-');
+
+  return {
+    flow: 'fire',
+    title: 'Approval Needed',
+    message: `${run.id}: ${itemId} (${modeLabel}) is waiting at ${checkpointLabel} checkpoint`,
+    checkpoint: checkpointLabel,
+    source: resolvedApproval.source
+  };
+}
+
+function isFireRunAwaitingApproval(run, currentWorkItem) {
+  return Boolean(getFireRunApprovalGate(run, currentWorkItem));
+}
+
+function detectFireRunApprovalGate(snapshot) {
+  const run = getCurrentRun(snapshot);
+  if (!run) {
+    return null;
+  }
+
+  const currentWorkItem = getCurrentFireWorkItem(run);
+  if (!currentWorkItem) {
+    return null;
+  }
+
+  return getFireRunApprovalGate(run, currentWorkItem);
+}
+
+function normalizeStageName(stage) {
+  return normalizeToken(stage).replace(/_/g, '-');
+}
+
+function getAidlcCheckpointSignalFiles(boltType, stageName) {
+  const normalizedType = normalizeToken(boltType).replace(/_/g, '-');
+  const normalizedStage = normalizeStageName(stageName);
+
+  if (normalizedType === 'simple-construction-bolt') {
+    if (normalizedStage === 'plan') return ['implementation-plan.md'];
+    if (normalizedStage === 'implement') return ['implementation-walkthrough.md'];
+    if (normalizedStage === 'test') return ['test-walkthrough.md'];
+    return [];
+  }
+
+  if (normalizedType === 'ddd-construction-bolt') {
+    if (normalizedStage === 'model') return ['ddd-01-domain-model.md'];
+    if (normalizedStage === 'design') return ['ddd-02-technical-design.md'];
+    if (normalizedStage === 'implement') return ['implementation-walkthrough.md'];
+    if (normalizedStage === 'test') return ['ddd-03-test-report.md'];
+    return [];
+  }
+
+  if (normalizedType === 'spike-bolt') {
+    if (normalizedStage === 'explore') return ['spike-exploration.md'];
+    if (normalizedStage === 'document') return ['spike-report.md'];
+    return [];
+  }
+
+  return [];
+}
+
+function hasAidlcCheckpointSignal(bolt, stageName) {
+  const fileNames = Array.isArray(bolt?.files) ? bolt.files : [];
+  const lowerNames = new Set(fileNames.map((name) => String(name || '').toLowerCase()));
+  const expectedFiles = getAidlcCheckpointSignalFiles(bolt?.type, stageName)
+    .map((name) => String(name).toLowerCase());
+
+  for (const expectedFile of expectedFiles) {
+    if (lowerNames.has(expectedFile)) {
+      return true;
+    }
+  }
+
+  if (normalizeStageName(stageName) === 'adr') {
+    for (const name of lowerNames) {
+      if (/^adr-[\w-]+\.md$/.test(name)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+function isAidlcBoltAwaitingApproval(bolt) {
+  if (!bolt || normalizeToken(bolt.status) !== 'in_progress') {
+    return false;
+  }
+
+  const currentStage = normalizeStageName(bolt.currentStage);
+  if (!currentStage) {
+    return false;
+  }
+
+  const stages = Array.isArray(bolt.stages) ? bolt.stages : [];
+  const stageMeta = stages.find((stage) => normalizeStageName(stage?.name) === currentStage);
+  if (normalizeToken(stageMeta?.status) === 'completed') {
+    return false;
+  }
+
+  return hasAidlcCheckpointSignal(bolt, currentStage);
+}
+
+function detectAidlcBoltApprovalGate(snapshot) {
+  const bolt = getCurrentBolt(snapshot);
+  if (!bolt) {
+    return null;
+  }
+
+  if (!isAidlcBoltAwaitingApproval(bolt)) {
+    return null;
+  }
+
+  return {
+    flow: 'aidlc',
+    title: 'Approval Needed',
+    message: `${bolt.id}: ${bolt.currentStage || 'current'} stage is waiting for confirmation`
+  };
+}
+
+function detectDashboardApprovalGate(snapshot, flow) {
+  const effectiveFlow = getEffectiveFlow(flow, snapshot);
+  if (effectiveFlow === 'fire') {
+    return detectFireRunApprovalGate(snapshot);
+  }
+  if (effectiveFlow === 'aidlc') {
+    return detectAidlcBoltApprovalGate(snapshot);
+  }
+  return null;
+}
+
 function getCurrentPhaseLabel(run, currentWorkItem) {
   const phase = currentWorkItem?.currentPhase || '';
   if (typeof phase === 'string' && phase !== '') {
@@ -1185,10 +1492,8 @@ function buildFireCurrentRunGroups(snapshot) {
 
   const workItems = Array.isArray(run.workItems) ? run.workItems : [];
   const completed = workItems.filter((item) => item.status === 'completed').length;
-  const currentWorkItem = workItems.find((item) => item.id === run.currentItem)
-    || workItems.find((item) => item.status === 'in_progress')
-    || workItems[0]
-    || null;
+  const currentWorkItem = getCurrentFireWorkItem(run);
+  const awaitingApproval = isFireRunAwaitingApproval(run, currentWorkItem);
 
   const currentPhase = getCurrentPhaseLabel(run, currentWorkItem);
   const phaseTrack = buildPhaseTrack(currentPhase);
@@ -1232,7 +1537,7 @@ function buildFireCurrentRunGroups(snapshot) {
   return [
     {
       key: `current:run:${run.id}:summary`,
-      label: `${run.id} [${run.scope}] ${completed}/${workItems.length} items`,
+      label: `${run.id} [${run.scope}] ${completed}/${workItems.length} items${awaitingApproval ? ' [APPROVAL]' : ''}`,
       files: []
     },
     {
@@ -1258,9 +1563,10 @@ function buildCurrentGroups(snapshot, flow) {
     }
     const stages = Array.isArray(bolt.stages) ? bolt.stages : [];
     const completedStages = stages.filter((stage) => stage.status === 'completed').length;
+    const awaitingApproval = isAidlcBoltAwaitingApproval(bolt);
     return [{
       key: `current:bolt:${bolt.id}`,
-      label: `${bolt.id} [${bolt.type}] ${completedStages}/${stages.length} stages`,
+      label: `${bolt.id} [${bolt.type}] ${completedStages}/${stages.length} stages${awaitingApproval ? ' [APPROVAL]' : ''}`,
       files: filterExistingFiles([
         ...collectAidlcBoltFiles(bolt),
         ...collectAidlcIntentContextFiles(snapshot, bolt.intent)
@@ -2403,6 +2709,10 @@ function createDashboardApp(deps) {
     }, [showErrorPanelForSections]);
 
     const effectiveFlow = getEffectiveFlow(activeFlow, snapshot);
+    const approvalGate = detectDashboardApprovalGate(snapshot, activeFlow);
+    const approvalGateLine = approvalGate
+      ? `[APPROVAL NEEDED] ${approvalGate.message}`
+      : '';
     const currentGroups = buildCurrentGroups(snapshot, activeFlow);
     const currentExpandedGroups = { ...expandedGroups };
     for (const group of currentGroups) {
@@ -2411,11 +2721,24 @@ function createDashboardApp(deps) {
       }
     }
 
-    const currentRunRows = toExpandableRows(
+    const currentRunRowsBase = toExpandableRows(
       currentGroups,
       getNoCurrentMessage(effectiveFlow),
       currentExpandedGroups
     );
+    const currentRunRows = approvalGate
+      ? [
+        {
+          kind: 'info',
+          key: 'approval-gate',
+          label: approvalGateLine,
+          color: 'yellow',
+          bold: true,
+          selectable: false
+        },
+        ...currentRunRowsBase
+      ]
+      : currentRunRowsBase;
     const shouldHydrateSecondaryTabs = deferredTabsReady || ui.view !== 'runs';
     const runFileGroups = buildRunFileEntityGroups(snapshot, activeFlow, {
       includeBacklog: shouldHydrateSecondaryTabs
@@ -3027,12 +3350,14 @@ function createDashboardApp(deps) {
     const showErrorPanel = Boolean(error) && rows >= 18;
     const showGlobalErrorPanel = showErrorPanel && ui.view !== 'health' && !ui.showHelp;
     const showErrorInline = Boolean(error) && !showErrorPanel;
+    const showApprovalBanner = approvalGateLine !== '' && !ui.showHelp;
     const showStatusLine = statusLine !== '';
     const densePanels = rows <= 28 || cols <= 120;
 
     const reservedRows =
       2 +
       (showFlowBar ? 1 : 0) +
+      (showApprovalBanner ? 1 : 0) +
       (showFooterHelpLine ? 1 : 0) +
       (showGlobalErrorPanel ? 5 : 0) +
       (showErrorInline ? 1 : 0) +
@@ -3266,6 +3591,13 @@ function createDashboardApp(deps) {
       React.createElement(Text, { color: 'cyan' }, buildHeaderLine(snapshot, activeFlow, watchEnabled, watchStatus, lastRefreshAt, ui.view, fullWidth)),
       React.createElement(FlowBar, { activeFlow, width: fullWidth, flowIds: availableFlowIds }),
       React.createElement(TabsBar, { view: ui.view, width: fullWidth, icons, flow: activeFlow }),
+      showApprovalBanner
+        ? React.createElement(
+          Text,
+          { color: 'black', backgroundColor: 'yellow', bold: true },
+          truncate(approvalGateLine, fullWidth)
+        )
+        : null,
       showErrorInline
         ? React.createElement(Text, { color: 'red' }, truncate(buildErrorLines(error, fullWidth)[0] || 'Error', fullWidth))
         : null,
@@ -3300,5 +3632,8 @@ module.exports = {
   truncate,
   fitLines,
   safeJsonHash,
-  allocateSingleColumnPanels
+  allocateSingleColumnPanels,
+  detectDashboardApprovalGate,
+  detectFireRunApprovalGate,
+  detectAidlcBoltApprovalGate
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "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": {