specsmd 0.0.0-dev.86 → 0.0.0-dev.87

package/README.md

@@ -89,6 +89,21 @@ During installation, select your flow:
 
 The installer detects your AI coding tools and sets up agent definitions, slash commands, and project structure for your selected flow.
 
+### Live Dashboard (FIRE)
+
+Track FIRE state continuously from terminal:
+
+```bash
+npx specsmd@latest dashboard
+```
+
+Useful options:
+
+```bash
+npx specsmd@latest dashboard --flow fire --path . --refresh-ms 1000
+npx specsmd@latest dashboard --no-watch
+```
+
 ### Install VS Code Extension (Optional)
 
 Track your progress visually with our sidebar extension:

package/bin/cli.js

@@ -2,6 +2,7 @@
 
 const { program } = require('commander');
 const installer = require('../lib/installer');
+const dashboard = require('../lib/dashboard');
 const packageJson = require('../package.json');
 
 program
@@ -18,4 +19,17 @@ program
     .description('Uninstall specsmd from the current project')
     .action(installer.uninstall);
 
-program.parse(process.argv);
+program
+    .command('dashboard')
+    .description('Live terminal dashboard for flow state (FIRE first)')
+    .option('--flow <flow>', 'Flow to inspect (fire|aidlc|simple), default auto-detect')
+    .option('--path <dir>', 'Workspace path', process.cwd())
+    .option('--worktree <nameOrPath>', 'Initial git worktree (branch name, worktree name, id, or absolute path)')
+    .option('--refresh-ms <n>', 'Fallback refresh interval in milliseconds (default: 1000)', '1000')
+    .option('--no-watch', 'Render once and exit')
+    .action((options) => dashboard.run(options));
+
+program.parseAsync(process.argv).catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+});

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

@@ -130,7 +130,7 @@ You are the **Builder Agent** for FIRE (Fast Intent-Run Engineering).
 
   ```yaml
   run:
-    id: run-001
+    id: run-fabriqa-2026-001
     scope: batch  # single | batch | wide
     work_items:
       - id: login-endpoint
@@ -165,7 +165,7 @@ You are the **Builder Agent** for FIRE (Fast Intent-Run Engineering).
   | Create run.md | (handled by init-run.cjs) | ❌ NO direct write |
   | Update state.yaml | (handled by scripts) | ❌ NO direct edit |
 
-  <check if="about to mkdir .specs-fire/runs/run-XXX">
+  <check if="about to mkdir .specs-fire/runs/run-<worktree>-XXX">
     <action>STOP — use init-run.cjs instead</action>
   </check>
   <check if="about to edit state.yaml directly">

package/flows/fire/agents/builder/skills/code-review/SKILL.md

@@ -42,7 +42,7 @@ Review code written during a run, auto-fix no-brainer issues, and suggest improv
     - path: src/routes/index.ts
       changes: Added login route
 
-  run_id: run-001
+  run_id: run-fabriqa-2026-001
   intent_id: user-auth
   ```
 

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

@@ -248,6 +248,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">
@@ -276,6 +278,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>
 
@@ -286,6 +290,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">
@@ -314,6 +320,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>
 
@@ -574,6 +582,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` |
 
@@ -593,8 +602,8 @@ Supports both single-item and multi-item (batch/wide) runs.
       ```json
       {
         "success": true,
-        "runId": "run-001",
-        "runPath": "/project/.specs-fire/runs/run-001",
+        "runId": "run-fabriqa-2026-001",
+        "runPath": "/project/.specs-fire/runs/run-fabriqa-2026-001",
         "scope": "batch",
         "workItems": [...],
         "currentItem": "wi-1"
@@ -606,10 +615,10 @@ Supports both single-item and multi-item (batch/wide) runs.
   <script name="complete-run.cjs">
     ```bash
     # Complete current item (batch runs - moves to next item)
-    node scripts/complete-run.cjs /project run-001 --complete-item
+    node scripts/complete-run.cjs /project run-fabriqa-2026-001 --complete-item
 
     # Complete entire run (single runs or final item in batch)
-    node scripts/complete-run.cjs /project run-001 --complete-run \
+    node scripts/complete-run.cjs /project run-fabriqa-2026-001 --complete-run \
       --files-created='[{"path":"src/new.ts","purpose":"New feature"}]' \
       --files-modified='[{"path":"src/old.ts","changes":"Added import"}]' \
       --tests=5 --coverage=85
@@ -619,7 +628,7 @@ Supports both single-item and multi-item (batch/wide) runs.
       ```json
       {
         "success": true,
-        "runId": "run-001",
+        "runId": "run-fabriqa-2026-001",
         "completedItem": "wi-1",
         "nextItem": "wi-2",
         "remainingItems": 1,
@@ -632,7 +641,7 @@ Supports both single-item and multi-item (batch/wide) runs.
       ```json
       {
         "success": true,
-        "runId": "run-001",
+        "runId": "run-fabriqa-2026-001",
         "scope": "batch",
         "workItemsCompleted": 2,
         "completedAt": "2026-01-20T..."
@@ -664,7 +673,7 @@ Supports both single-item and multi-item (batch/wide) runs.
   After init-run.cjs creates a run:
 
   ```
-  .specs-fire/runs/run-001/
+  .specs-fire/runs/run-fabriqa-2026-001/
   ├── run.md           # Created by init-run.cjs, updated by complete-run.cjs
   ├── plan.md          # Created BEFORE implementation (ALL modes - required)
   ├── test-report.md   # Created AFTER tests pass (required)

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

@@ -306,6 +306,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,
     }));
   }
 
@@ -429,6 +432,12 @@ function completeCurrentItem(rootPath, runId, params = {}, options = {}) {
     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;
     }
@@ -458,6 +467,10 @@ function completeCurrentItem(rootPath, runId, params = {}, options = {}) {
     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;
     }
@@ -571,6 +584,12 @@ function completeRun(rootPath, runId, params = {}, options = {}) {
       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;
@@ -716,7 +735,7 @@ function printUsage() {
   console.error('');
   console.error('Arguments:');
   console.error('  rootPath  - Project root directory');
-  console.error('  runId     - Run ID to complete (e.g., run-003)');
+  console.error('  runId     - Run ID to complete (e.g., run-fabriqa-2026-003)');
   console.error('');
   console.error('Flags:');
   console.error('  --complete-item  - Complete only the current work item (batch/wide runs)');
@@ -731,8 +750,8 @@ function printUsage() {
   console.error('  --coverage=N           - Coverage percentage');
   console.error('');
   console.error('Examples:');
-  console.error('  node complete-run.cjs /project run-003 --complete-item');
-  console.error('  node complete-run.cjs /project run-003 --complete-run --tests=5 --coverage=85');
+  console.error('  node complete-run.cjs /project run-fabriqa-2026-003 --complete-item');
+  console.error('  node complete-run.cjs /project run-fabriqa-2026-003 --complete-run --tests=5 --coverage=85');
 }
 
 // =============================================================================

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

@@ -152,26 +152,61 @@ function writeState(statePath, state) {
 }
 
 // =============================================================================
-// Run ID Generation (CRITICAL - checks both history and file system)
+// Run ID Generation (CRITICAL - checks state and file system)
 // =============================================================================
 
-function generateRunId(runsPath, state) {
+function sanitizeWorktreeToken(value) {
+  const normalized = String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return normalized || 'workspace';
+}
+
+function resolveWorktreeToken(rootPath) {
+  const baseName = path.basename(path.resolve(String(rootPath || '')));
+  return sanitizeWorktreeToken(baseName);
+}
+
+function parseRunSequence(runId, worktreeToken) {
+  if (typeof runId !== 'string' || runId.trim() === '') {
+    return null;
+  }
+
+  const legacyMatch = runId.match(/^run-(\d+)$/);
+  if (legacyMatch) {
+    const parsed = parseInt(legacyMatch[1], 10);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+
+  const worktreeMatch = runId.match(/^run-([a-z0-9][a-z0-9-]*)-(\d+)$/);
+  if (worktreeMatch && worktreeMatch[1] === worktreeToken) {
+    const parsed = parseInt(worktreeMatch[2], 10);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+
+  return null;
+}
+
+function generateRunId(rootPath, 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;
-        }
-      }
+  const worktreeToken = resolveWorktreeToken(rootPath);
+  let maxFromState = 0;
+
+  // Source 1: Get max from state.yaml run history (active + completed)
+  const stateRuns = state?.runs || {};
+  const stateRunRecords = [
+    ...(Array.isArray(stateRuns.active) ? stateRuns.active : []),
+    ...(Array.isArray(stateRuns.completed) ? stateRuns.completed : [])
+  ];
+  for (const run of stateRunRecords) {
+    const num = parseRunSequence(run?.id, worktreeToken);
+    if (num != null && num > maxFromState) {
+      maxFromState = num;
     }
   }
 
@@ -180,9 +215,9 @@ function generateRunId(runsPath, state) {
   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;
+      const num = parseRunSequence(entry, worktreeToken);
+      if (num != null && num > maxFromFileSystem) {
+        maxFromFileSystem = num;
       }
     }
   } catch (err) {
@@ -194,10 +229,10 @@ function generateRunId(runsPath, state) {
   }
 
   // Use MAX of both to ensure no duplicates
-  const maxNum = Math.max(maxFromHistory, maxFromFileSystem);
+  const maxNum = Math.max(maxFromState, maxFromFileSystem);
   const nextNum = maxNum + 1;
 
-  return `run-${String(nextNum).padStart(3, '0')}`;
+  return `run-${worktreeToken}-${String(nextNum).padStart(3, '0')}`;
 }
 
 // =============================================================================
@@ -233,7 +268,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];
@@ -329,7 +368,7 @@ function initRun(rootPath, workItems, scope) {
   }
 
   // Generate run ID (checks both history AND file system)
-  const runId = generateRunId(runsPath, state);
+  const runId = generateRunId(rootPath, runsPath, state);
   const runPath = path.join(runsPath, runId);
 
   // Create run folder
@@ -346,6 +385,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-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

@@ -10,9 +10,9 @@
  *   node update-phase.cjs <rootPath> <runId> <phase>
  *
  * Examples:
- *   node update-phase.cjs /project run-001 execute
- *   node update-phase.cjs /project run-001 test
- *   node update-phase.cjs /project run-001 review
+ *   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');
@@ -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;
     }
@@ -208,12 +219,12 @@ function printUsage() {
   console.error('');
   console.error('Arguments:');
   console.error('  rootPath  - Project root directory');
-  console.error('  runId     - Run ID (e.g., run-001)');
+  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-001 execute');
-  console.error('  node update-phase.cjs /project run-001 test');
+  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) {

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

@@ -58,7 +58,7 @@ Display current run status and progress.
 <example_output>
 
   ```
-  ## Run Status: run-003
+  ## Run Status: run-fabriqa-2026-003
 
   **Work Item**: Add session management
   **Intent**: User Authentication