@entelligentsia/forgecli 1.0.10 → 1.0.20

package/dist/forge-payload/tools/banners.cjs

@@ -32,6 +32,7 @@
 //   node banners.cjs --subtitle "Forging your SDLC"
 //   node banners.cjs --progress 5 12 "Templates"
 //   node banners.cjs --phase 7 12 "Workflows" ember
+//   node banners.cjs --badge forge --quiet    (automated/orchestrator use: zero stdout)
 
 // ─── Plain-mode detection ─────────────────────────────────────────────────────
 // Resolved at call-time so tests can flip env vars dynamically.
@@ -51,6 +52,12 @@ function stripAnsi(s) {
 // Soft override — set by `--plain` CLI flag to force plain mode for one run.
 let FORCE_PLAIN = false;
 
+// Quiet mode — set by `--quiet` CLI flag to suppress all stdout output.
+// Used by the orchestrator loop so banner output does not enter the LLM context
+// window (output remains visible on a real TTY via the human's terminal but is
+// not fed back as tool-call response text).
+let QUIET_MODE = false;
+
 // ─── ANSI helpers ─────────────────────────────────────────────────────────────
 const R = '\x1b[0m';
 const B = '\x1b[1m';
@@ -376,6 +383,7 @@ function _maybePlain(s) {
 
 // ─── CLI ───────────────────────────────────────────────────────────────────────
 // node banners.cjs [<name>] [--gallery] [--badge <name>] [--mark <name>] [--list]
+// node banners.cjs --badge <name> --quiet   (suppress all stdout; orchestrator use)
 
 if (require.main === module) {
   let args = process.argv.slice(2);
@@ -387,38 +395,49 @@ if (require.main === module) {
     args = args.slice(0, plainIdx).concat(args.slice(plainIdx + 1));
   }
 
+  // --quiet may appear anywhere; consume it before dispatch.
+  // When set, all stdout is suppressed (exit 0 still guaranteed on success).
+  const quietIdx = args.indexOf('--quiet');
+  if (quietIdx !== -1) {
+    QUIET_MODE = true;
+    args = args.slice(0, quietIdx).concat(args.slice(quietIdx + 1));
+  }
+
+  // Helper: write to stdout only when not in quiet mode.
+  const emit = (s) => { if (!QUIET_MODE) process.stdout.write(s); };
+
   try {
     if (!args.length || args[0] === '--gallery') {
-      process.stdout.write(gallery() + '\n');
+      emit(gallery() + '\n');
     } else if (args[0] === '--list') {
-      console.log(list().map(n => {
+      emit(list().map(n => {
         const b = BANNERS[n];
         return `${b.emoji}  ${n.padEnd(8)} — ${b.tagline}`;
-      }).join('\n'));
+      }).join('\n') + '\n');
     } else if (args[0] === '--badge') {
-      console.log(badge(args[1] || ''));
+      emit(badge(args[1] || '') + '\n');
     } else if (args[0] === '--mark') {
-      console.log(mark(args[1] || ''));
+      emit(mark(args[1] || '') + '\n');
     } else if (args[0] === '--subtitle') {
-      console.log(subtitle(args.slice(1).join(' ')));
+      emit(subtitle(args.slice(1).join(' ')) + '\n');
     } else if (args[0] === '--progress') {
       const n = Number(args[1]);
       const total = Number(args[2]);
       const label = args.slice(3).join(' ') || undefined;
-      console.log(progressBar(n, total, { label }));
+      emit(progressBar(n, total, { label }) + '\n');
     } else if (args[0] === '--phase') {
       const n = Number(args[1]);
       const total = Number(args[2]);
       const name = args[3] || '';
       const bannerKey = args[4] || 'forge';
       const mode = args[5];   // optional 'fast' | 'full'
-      console.log(phaseHeader(n, total, name, bannerKey, mode ? { mode } : undefined));
+      emit(phaseHeader(n, total, name, bannerKey, mode ? { mode } : undefined) + '\n');
     } else if (args[0] === '--rule') {
       // --rule [text]   Zen-blue em-dash horizontal rule (with optional label)
       const text = args.slice(1).join(' ') || undefined;
-      console.log(ruleLine(text));
+      emit(ruleLine(text) + '\n');
     } else {
-      process.stdout.write(render(args[0]) + '\n');
+      emit(render(args[0]) + '\n');
     }
   } catch (e) {
     console.error(e.message);

package/dist/forge-payload/tools/check-structure.cjs

@@ -132,9 +132,17 @@ function validateManifest(manifest, forgeRoot) {
     fragments: path.join(basePackDir, 'workflows', '_fragments'),
     templates: path.join(basePackDir, 'templates'),
     commands:  path.join(basePackDir, 'commands'),
+    'workflows-js': path.join(basePackDir, 'workflows-js'),
+    // tools: not base-pack-sourced — source is forgeRoot/tools/ (verbatim vendor).
+    // Uses recursive enumeration to include lib/*.cjs with the lib/ prefix.
+    tools: path.join(forgeRoot, 'tools'),
     // schemas: not base-pack-sourced — source is forgeRoot/schemas/
   };
 
+  // Namespaces that require recursive enumeration (files may include path prefixes
+  // like lib/*.cjs). The walker returns relative paths with forward slashes.
+  const recursiveNs = new Set(['tools']);
+
   const manifestOnly = [];  // Files in manifest but not in base-pack
   const basePackOnly = [];   // Files in base-pack but not in manifest
 
@@ -147,14 +155,31 @@ function validateManifest(manifest, forgeRoot) {
 
     const manifestFiles = new Set(ns.files || []);
 
-    // Read base-pack source directory
+    // Read base-pack source directory (flat or recursive depending on namespace)
     let basePackFiles = [];
     try {
-      basePackFiles = fs.readdirSync(sourceDir).filter(f => {
-        // Only include regular files, skip subdirectories (like _fragments under workflows)
-        const stat = fs.statSync(path.join(sourceDir, f));
-        return stat.isFile();
-      });
+      if (recursiveNs.has(nsKey)) {
+        // Recursive walk: enumerate all files, returning paths relative to sourceDir
+        // (with forward-slash separators). Excludes *.test.cjs files.
+        const walkDir = (dir, prefix) => {
+          const entries = fs.readdirSync(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+              walkDir(path.join(dir, entry.name), relPath);
+            } else if (entry.isFile() && !entry.name.endsWith('.test.cjs')) {
+              basePackFiles.push(relPath);
+            }
+          }
+        };
+        walkDir(sourceDir, '');
+      } else {
+        basePackFiles = fs.readdirSync(sourceDir).filter(f => {
+          // Only include regular files, skip subdirectories (like _fragments under workflows)
+          const stat = fs.statSync(path.join(sourceDir, f));
+          return stat.isFile();
+        });
+      }
     } catch {
       // Directory doesn't exist — all manifest files are manifestOnly
       for (const f of manifestFiles) {
@@ -183,9 +208,65 @@ function validateManifest(manifest, forgeRoot) {
   return { manifestOnly, basePackOnly };
 }
 
+// Checks whether the vendored .forge/tools/ directory is present, and whether
+// the version marker (.forge/tools/.forge-tools-version) matches the active
+// plugin version from .forge/config.json (paths.forgeRef).
+//
+// Returns:
+//   { present, vendoredVersion, activeVersion, stale, reason }
+//
+//   present        — true if .forge/tools/ directory exists
+//   vendoredVersion — version string from .forge-tools-version (or null)
+//   activeVersion   — version string from paths.forgeRef in config (or null)
+//   stale          — true when: dir absent=false; marker absent=true; versions differ=true
+//   reason         — 'ok' | 'missing' | 'marker-absent' | 'version-mismatch'
+function checkToolsVersion(projectRoot) {
+  const toolsDir = path.join(projectRoot, '.forge', 'tools');
+  const markerFile = path.join(toolsDir, '.forge-tools-version');
+  const configFile = path.join(projectRoot, '.forge', 'config.json');
+
+  // Dir absent → not stale (just missing)
+  if (!fs.existsSync(toolsDir)) {
+    return { present: false, vendoredVersion: null, activeVersion: null, stale: false, reason: 'missing' };
+  }
+
+  // Read active version from config
+  let activeVersion = null;
+  if (fs.existsSync(configFile)) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+      activeVersion = (cfg && cfg.paths && cfg.paths.forgeRef) ? cfg.paths.forgeRef : null;
+    } catch {
+      // unparseable — leave activeVersion null
+    }
+  }
+
+  // Marker absent → stale
+  if (!fs.existsSync(markerFile)) {
+    return { present: true, vendoredVersion: null, activeVersion, stale: true, reason: 'marker-absent' };
+  }
+
+  // Read vendored version from marker
+  let vendoredVersion = null;
+  try {
+    const marker = JSON.parse(fs.readFileSync(markerFile, 'utf8'));
+    vendoredVersion = (marker && marker.version) ? marker.version : null;
+  } catch {
+    // unparseable marker → treat as marker-absent
+    return { present: true, vendoredVersion: null, activeVersion, stale: true, reason: 'marker-absent' };
+  }
+
+  // Version mismatch → stale
+  if (activeVersion && vendoredVersion && vendoredVersion !== activeVersion) {
+    return { present: true, vendoredVersion, activeVersion, stale: true, reason: 'version-mismatch' };
+  }
+
+  return { present: true, vendoredVersion, activeVersion, stale: false, reason: 'ok' };
+}
+
 // ── Exports ────────────────────────────────────────────────────────────────────
 
-module.exports = { checkNamespaces, validateManifest };
+module.exports = { checkNamespaces, validateManifest, checkToolsVersion };
 
 // ── CLI ────────────────────────────────────────────────────────────────────────
 

package/dist/forge-payload/tools/collate.cjs

@@ -108,9 +108,23 @@ function resolveTaskDir(task, sprintDirPath, engPath) {
   const normalizedTaskPath = task.path ? task.path.replace(/\\/g, '/').replace(/\/$/, '') : null;
   const normalizedEngPath  = engPath   ? engPath.replace(/\\/g, '/').replace(/\/$/, '')  : '';
 
-  // Case 1: path is under the engineering root — it IS the task directory
+  // Case 1: path is under the engineering root — it IS (or is a file inside)
+  // the task directory. Some store records carry task.path pointing at a file
+  // inside the task dir (e.g. .../FORGE-S22-T04/PLAN.md) rather than the dir
+  // itself; in that case basename(path) is the filename, not the dir. Only
+  // trust Case 1 when its candidate resolves to a real directory on disk —
+  // otherwise fall through to the filesystem scan, which resolves by taskId.
   if (normalizedTaskPath && normalizedEngPath && normalizedTaskPath.startsWith(normalizedEngPath + '/')) {
-    return resultOk(path.basename(normalizedTaskPath));
+    const candidate = path.basename(normalizedTaskPath);
+    // Can't verify against disk — preserve legacy behaviour and trust the path.
+    if (!sprintDirPath) return resultOk(candidate);
+    const candidatePath = path.join(sprintDirPath, candidate);
+    // Trust Case 1 only when the candidate is a real directory. If it's a file
+    // (task.path pointed at a doc inside the dir) or absent, fall through to the
+    // filesystem scan below, which resolves the dir by taskId.
+    if (fs.existsSync(candidatePath) && fs.statSync(candidatePath).isDirectory()) {
+      return resultOk(candidate);
+    }
   }
 
   // Case 2 (and fallback for case 1 missing): filesystem scan
@@ -597,6 +611,38 @@ function buildCostReport(sprint, events, orphanSidecars, huskPrimaries) {
     }
   }
 
+  // --- Section 3b: Incomplete passes (aborted / failed attempts) ---
+  // forge-cli ≥1.0.16 emits phase events with verdict "aborted" (user cancel)
+  // or "failed" (halt-on-failure) so the provider-billed tokens of incomplete
+  // attempts reach the store. Those tokens ARE included in the Per-Task /
+  // Per-Role / Model Split totals above (totals are verdict-agnostic — this
+  // closes the under-count where aborted passes were invisible); this section
+  // makes the incomplete share visible rather than silently mixed in.
+  lines.push('## Incomplete Passes', '');
+  {
+    const INCOMPLETE_VERDICTS = new Set(['aborted', 'failed']);
+    const incompleteEvents = tokenEvents.filter(e => INCOMPLETE_VERDICTS.has(e.verdict));
+    if (incompleteEvents.length === 0) {
+      lines.push('_No incomplete passes in this sprint._', '');
+    } else {
+      const rows = [['Task', 'Phase', 'Outcome', 'Input Tokens', 'Output Tokens', 'Est. Cost USD']];
+      const sorted = [...incompleteEvents].sort((a, b) =>
+        String(a.taskId || '').localeCompare(String(b.taskId || '')) ||
+        String(a.phase || '').localeCompare(String(b.phase || '')));
+      for (const e of sorted) {
+        rows.push([
+          e.taskId || '(unknown)',
+          e.phase || '(unknown)',
+          e.verdict,
+          fmtTokens(e.inputTokens || 0),
+          fmtTokens(e.outputTokens || 0),
+          fmtCost(e.estimatedCostUSD || 0),
+        ]);
+      }
+      lines.push(padTable(rows), '');
+    }
+  }
+
   // --- Section 4: Model split ---
   lines.push('## Model Split', '');
   {

package/dist/forge-payload/tools/manage-config.cjs

@@ -418,7 +418,7 @@ if (subcmd === 'resolve-forge-root') {
 
   const { config } = readConfig();
   const forgeRef = getByPath(config, 'paths.forgeRef');
-  const forgeRoot = getByPath(config, 'paths.forgeRoot');
+  // Note: paths.forgeRoot read removed in FORGE-S29-T03 (Priority 3 deprecated).
 
   // Priority 2: Scan cache/marketplace directories by forgeRef
   if (forgeRef && typeof forgeRef === 'string') {
@@ -442,14 +442,12 @@ if (subcmd === 'resolve-forge-root') {
     }
   }
 
-  // Priority 3: Fallback to paths.forgeRoot (deprecated but still read)
-  if (forgeRoot && typeof forgeRoot === 'string') {
-    console.log(forgeRoot);
-    process.exit(0);
-  }
+  // Priority 3 (paths.forgeRoot fallback) removed — FORGE-S29-T03.
+  // paths.forgeRoot is deprecated and no longer used as a resolution fallback.
+  // Relying on it masks misconfigured projects and blocks the FORGE_ROOT retirement.
 
   // No resolution possible
-  console.error('× Cannot resolve Forge plugin root: no CLAUDE_PLUGIN_ROOT env var, no forgeRef cache match, and no forgeRoot in config.');
+  console.error('× Cannot resolve Forge plugin root: no CLAUDE_PLUGIN_ROOT env var and no forgeRef cache match. Run /forge:update to refresh.');
   process.exit(1);
 }
 

package/dist/forge-payload/tools/parse-gates.cjs

@@ -154,4 +154,76 @@ function parseAfter(rest, lineNo) {
   return { phase: m[1], verdict };
 }
 
-module.exports = { parseGates };
+// parseOutputs — same fence-scan logic as parseGates but for ```outputs phase=X blocks.
+// Closed grammar: only `artifact` and `require` directives are allowed.
+// Unknown directives throw (parity with parseGates).
+const OUTPUTS_FENCE_OPEN = /^```outputs\s+phase=([A-Za-z0-9_-]+)\s*$/;
+
+function parseOutputs(markdown) {
+  if (typeof markdown !== 'string' || markdown.length === 0) return {};
+  const lines = markdown.split('\n');
+  const result = {};
+  let currentPhase = null;
+  let inFence = false;
+  let fenceStartLine = -1;
+  let fenceBuffer = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNo = i + 1;
+    if (!inFence) {
+      const m = line.match(OUTPUTS_FENCE_OPEN);
+      if (m) {
+        currentPhase = m[1];
+        if (result[currentPhase]) {
+          throw new Error(
+            `parse-gates: line ${lineNo}: duplicate outputs block for phase "${currentPhase}"`,
+          );
+        }
+        inFence = true;
+        fenceStartLine = lineNo;
+        fenceBuffer = [];
+      }
+      continue;
+    }
+    // Inside an outputs fence
+    if (FENCE_CLOSE.test(line)) {
+      result[currentPhase] = parseOutputsBlock(fenceBuffer, fenceStartLine);
+      inFence = false;
+      currentPhase = null;
+      fenceBuffer = [];
+      continue;
+    }
+    fenceBuffer.push({ text: line, lineNo });
+  }
+  if (inFence) {
+    throw new Error(`parse-gates: unterminated \`\`\`outputs fence opened at line ${fenceStartLine}`);
+  }
+  return result;
+}
+
+function parseOutputsBlock(bufferedLines, _fenceStartLine) {
+  const spec = { artifacts: [], require: [] };
+  for (const { text, lineNo } of bufferedLines) {
+    const trimmed = text.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) continue;
+    const firstSpace = trimmed.search(/\s/);
+    if (firstSpace < 0) {
+      throw new Error(`parse-gates: line ${lineNo}: malformed directive "${trimmed}"`);
+    }
+    const directive = trimmed.slice(0, firstSpace);
+    const rest = trimmed.slice(firstSpace + 1).trim();
+    switch (directive) {
+      case 'artifact':
+        spec.artifacts.push(parseArtifact(rest, lineNo));
+        break;
+      case 'require':
+        spec.require.push(parsePredicate(rest, lineNo));
+        break;
+      default:
+        throw new Error(`parse-gates: line ${lineNo}: unknown directive "${directive}"`);
+    }
+  }
+  return spec;
+}
+
+module.exports = { parseGates, parseOutputs };

package/dist/forge-payload/tools/postflight-gate.cjs

@@ -0,0 +1,298 @@
+'use strict';
+
+// postflight-gate.cjs — evaluates a phase's declared outputs block against
+// the filesystem / task state, post-subagent-return. Returns structured failure
+// data so the orchestrator (run-task.ts) can halt before FSM advance when outputs
+// are not satisfied.
+//
+// Pure function: only fs.existsSync / fs.statSync / fs.readFileSync. No writes,
+// no network, no LLM, no process spawns.
+//
+// CLI shim: node postflight-gate.cjs --phase <name> --task <taskId>
+// Exit codes: 0 (ok), 1 (guard failed), 2 (invalid args / parse error)
+// Stdout on exit 1: single JSON line { phase, reasonCode, detail, remediation }
+//
+// New reasonCodes (FORGE-S26-T19):
+//   output-missing  — artifact path does not exist
+//   output-stub     — artifact exists but size < min= bytes
+//   require-failed  — require predicate over state field failed
+//   tool-error      — internal parse or store-read failure
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * postflight({ phase, outputs, state, substitutions })
+ *
+ * @param {string} phase - Phase name (e.g. 'implement')
+ * @param {object} outputs - Parsed outputs spec from parseOutputs() — { [phase]: { artifacts, require } }
+ * @param {object} [state] - Task/bug state for require predicates (e.g. { task: {...} })
+ * @param {object} [substitutions] - Template variable substitutions (e.g. { engineering, sprint, task })
+ * @returns {{ ok: boolean, missing: string[], reasonCode: string, detail: string, remediation: string }}
+ */
+function postflight({ phase, outputs, state = {}, substitutions = {} }) {
+  const spec = outputs && outputs[phase];
+  if (!spec) {
+    // No outputs block for this phase — pass through (no-op)
+    return { ok: true, missing: [], reasonCode: null, detail: '', remediation: '' };
+  }
+
+  const missing = [];
+
+  for (const art of spec.artifacts || []) {
+    const resolved = applySubstitutions(art.path, substitutions);
+    let exists = false;
+    let size = 0;
+    try {
+      const st = fs.statSync(resolved);
+      exists = st.isFile();
+      size = st.size;
+    } catch (_) {
+      exists = false;
+    }
+    if (!exists) {
+      missing.push(`output-missing: artifact absent: ${resolved}`);
+    } else if (size < (art.minBytes || 0)) {
+      missing.push(
+        `output-stub: artifact too small: ${resolved} (${size} bytes, need >= ${art.minBytes})`,
+      );
+    }
+  }
+
+  for (const pred of spec.require || []) {
+    if (!evalPredicate(pred, state)) {
+      missing.push(
+        `require-failed: ${describePredicate(pred)} (got ${JSON.stringify(readField(pred.field, state))})`,
+      );
+    }
+  }
+
+  if (missing.length === 0) {
+    return { ok: true, missing: [], reasonCode: null, detail: '', remediation: '' };
+  }
+
+  const { reasonCode, detail, remediation } = buildStructuredFailure(phase, missing);
+  return { ok: false, missing, reasonCode, detail, remediation };
+}
+
+function applySubstitutions(template, subs) {
+  return template.replace(/\{(\w+)\}/g, (full, key) => {
+    if (Object.prototype.hasOwnProperty.call(subs, key)) return String(subs[key]);
+    return full;
+  });
+}
+
+function walkPath(dottedPath, root) {
+  const parts = dottedPath.split('.');
+  let cur = root;
+  for (const p of parts) {
+    if (cur === null || cur === undefined) return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+function readField(dottedPath, state) {
+  // Direct walk first (supports explicit `task.status` / `bug.status` paths).
+  const direct = walkPath(dottedPath, state);
+  if (direct !== undefined) return direct;
+  // The materialized outputs blocks use BARE record paths
+  // (`summaries.plan.verdict`) while the CLI wraps the record as
+  // { task: record } — fall back to the entity record so those resolve.
+  // (CART-S03-T01 false-halt: every bare require evaluated undefined.)
+  if (state && state.task) {
+    const viaTask = walkPath(dottedPath, state.task);
+    if (viaTask !== undefined) return viaTask;
+  }
+  if (state && state.bug) {
+    const viaBug = walkPath(dottedPath, state.bug);
+    if (viaBug !== undefined) return viaBug;
+  }
+  return undefined;
+}
+
+/**
+ * Build template substitutions for an entity's artifact directory.
+ * Canonical layouts:
+ *   tasks: <engineering>/sprints/<sprintId>/<taskId>/
+ *   bugs:  <engineering>/bugs/<bugId>/
+ * {sprint} is defined as the path segment under <engineering> that contains
+ * the entity dir — `sprints/<sprintId>` for tasks, `bugs` for bugs.
+ * (CART-S03-T01 false-halt: {sprint} was substituted with the bare sprintId,
+ * dropping the `sprints/` segment, so every artifact check missed.)
+ */
+function buildSubstitutions({ taskRecord, engineeringRoot, entityId }) {
+  const rec = taskRecord || {};
+  const isBug = Boolean(rec.bugId) || /-BUG-/.test(String(entityId || ''));
+  let sprint;
+  if (isBug) {
+    sprint = 'bugs';
+  } else if (rec.sprintId) {
+    sprint = `sprints/${rec.sprintId}`;
+  } else {
+    sprint = '{sprint}'; // unresolvable — leave the placeholder visible in the report
+  }
+  return {
+    engineering: engineeringRoot,
+    sprint,
+    task: entityId,
+  };
+}
+
+function evalPredicate(pred, state) {
+  const actual = readField(pred.field, state);
+  switch (pred.op) {
+    case '==':
+      return String(actual) === String(pred.value);
+    case '!=':
+      return String(actual) !== String(pred.value);
+    case 'in':
+      return (pred.value || []).map(String).includes(String(actual));
+    default:
+      throw new Error(`postflight-gate: unknown predicate op "${pred.op}"`);
+  }
+}
+
+function describePredicate(pred) {
+  if (pred.op === 'in') return `${pred.field} in [${(pred.value || []).join(', ')}]`;
+  return `${pred.field} ${pred.op} ${pred.value}`;
+}
+
+function buildStructuredFailure(phase, missing) {
+  let reasonCode = 'tool-error';
+  const detailParts = [];
+
+  for (const m of missing) {
+    detailParts.push(m);
+    if (reasonCode === 'tool-error') {
+      if (/^output-missing/i.test(m)) {
+        reasonCode = 'output-missing';
+      } else if (/^output-stub/i.test(m)) {
+        reasonCode = 'output-stub';
+      } else if (/^require-failed/i.test(m)) {
+        reasonCode = 'require-failed';
+      }
+    }
+  }
+
+  const detail = detailParts.join('; ');
+
+  const remediationMap = {
+    'output-missing': 'Re-run the phase that produces this artifact (e.g. /forge:implement), then retry.',
+    'output-stub': 'The artifact was produced but appears incomplete (stub). Ensure the phase wrote a complete file.',
+    'require-failed': 'Correct the task/bug state so it satisfies the postflight require predicate, then retry.',
+    'tool-error': 'Check the outputs block configuration and store records; run node .forge/tools/postflight-gate.cjs manually for diagnostics.',
+  };
+
+  return {
+    reasonCode,
+    detail,
+    remediation: remediationMap[reasonCode],
+  };
+}
+
+module.exports = { postflight, buildSubstitutions };
+
+// CLI shim — only runs when invoked directly
+if (require.main === module) {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.phase || !args.task) {
+    process.stderr.write('Usage: postflight-gate.cjs --phase <phaseName> --task <taskId>\n');
+    process.exit(2);
+  }
+
+  const { parseOutputs } = require('./parse-gates.cjs');
+
+  // Resolve config
+  let engineeringRoot = 'engineering';
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.resolve(process.cwd(), '.forge/config.json'), 'utf8'));
+    if (cfg.paths && cfg.paths.engineering) engineeringRoot = cfg.paths.engineering;
+  } catch (_) { /* fall back to default */ }
+
+  // Load task record
+  let taskRecord = null;
+  try {
+    const store = require('./store.cjs');
+    taskRecord = store.getTask(args.task);
+  } catch (_) {
+    // store.cjs not available or task not found — continue with substitutions from args
+  }
+
+  // Build substitutions (canonical entity-dir resolution — sprints/<id> or bugs)
+  const substitutions = buildSubstitutions({
+    taskRecord,
+    engineeringRoot,
+    entityId: args.task,
+  });
+
+  // Load workflow markdown (scan .forge/workflows/ for phase)
+  const workflowMd = loadWorkflowMarkdown(args.phase);
+  if (!workflowMd) {
+    process.stderr.write(`postflight-gate: no outputs block defined for phase "${args.phase}" — skipping\n`);
+    process.exit(0);
+  }
+
+  let outputs;
+  try {
+    outputs = parseOutputs(workflowMd);
+  } catch (err) {
+    process.stderr.write(`postflight-gate: ${err.message}\n`);
+    process.exit(2);
+  }
+
+  if (!outputs[args.phase]) {
+    process.stderr.write(`postflight-gate: no outputs block for phase "${args.phase}" — skipping\n`);
+    process.exit(0);
+  }
+
+  // Build state from task record
+  const state = {};
+  if (taskRecord) state.task = taskRecord;
+
+  const result = postflight({ phase: args.phase, outputs, state, substitutions });
+
+  if (result.ok) process.exit(0);
+
+  process.stderr.write(`Postflight guard failed for phase "${args.phase}":\n`);
+  for (const m of result.missing) process.stderr.write(`  - ${m}\n`);
+
+  // Emit structured JSON on stdout for orchestrators
+  process.stdout.write(JSON.stringify({
+    phase: args.phase,
+    reasonCode: result.reasonCode,
+    detail: result.detail,
+    remediation: result.remediation,
+  }) + '\n');
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--phase') out.phase = argv[++i];
+    else if (a === '--task') out.task = argv[++i];
+  }
+  return out;
+}
+
+function loadWorkflowMarkdown(phaseName) {
+  const workflowsDir = path.resolve(process.cwd(), '.forge/workflows');
+  let entries;
+  try {
+    entries = fs.readdirSync(workflowsDir).filter((f) => f.endsWith('.md'));
+  } catch (_) {
+    return null;
+  }
+  const fencePattern = new RegExp('^```outputs\\s+phase=' + escapeRegex(phaseName) + '\\s*$', 'm');
+  for (const entry of entries) {
+    const md = fs.readFileSync(path.join(workflowsDir, entry), 'utf8');
+    if (fencePattern.test(md)) return md;
+  }
+  return null;
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}