agentxchain 2.81.0 → 2.83.0

package/README.md

@@ -13,6 +13,7 @@ Legacy IDE-window coordination is still shipped as a compatibility mode for team
 - [Quickstart](https://agentxchain.dev/docs/quickstart/)
 - [Getting Started](https://agentxchain.dev/docs/getting-started/)
 - [CLI reference](https://agentxchain.dev/docs/cli/)
+- [Lights-Out Scheduling](https://agentxchain.dev/docs/lights-out-scheduling/)
 - [Templates](https://agentxchain.dev/docs/templates/)
 - [Export schema reference](https://agentxchain.dev/docs/export-schema/)
 - [Adapter reference](https://agentxchain.dev/docs/adapters/)
@@ -71,6 +72,8 @@ Duplicate execution remains intentional for the current 36-file slice until a la
 
 ### Governed workflow
 
+Run `agentxchain init --governed` for the guided scaffold. Use the explicit non-interactive form below for scripts, CI, or copy-paste onboarding:
+
 ```bash
 agentxchain init --governed --goal "Build an API change planner for release teams" --dir my-agentxchain-project -y
 cd my-agentxchain-project
@@ -151,7 +154,7 @@ agentxchain step
 
 ## Command Sets
 
-### Governed
+### Governed lifecycle and execution
 
 | Command | What it does |
 |---|---|
@@ -171,10 +174,37 @@ agentxchain step
 | `replay turn` | Replay an accepted turn's machine-evidence commands from history for audit and drift detection |
 | `verify protocol` | Run the shipped protocol conformance suite against a target implementation |
 | `dashboard` | Open the local governance dashboard in your browser for repo-local runs or multi-repo coordinator initiatives, including pending gate approvals |
+| `run [--auto-approve] [--max-turns N] [--dry-run]` | Drive a governed run from start to completion — dispatches turns, handles gates, manages rejection/retry |
+
+### Governed proof and inspection
+
+| Command | What it does |
+|---|---|
+| `audit [--format json]` | Live governance audit report with cost summary, decision history, and artifact inventory |
+| `diff <left> <right>` | Compare two governed runs side by side (phase, decisions, artifacts, timing) |
+| `report` | Generate a governance report for the current run |
+| `events [--type <type>] [--limit N]` | Inspect the lifecycle event stream (turns, phases, gates, governance events) |
+| `history [--limit N] [--role <role>]` | Query accepted-turn history from append-only JSONL |
+| `role list\|show` | List all configured roles or inspect a single role's charter, runtime, and phase assignment |
+| `turn show` | Inspect the active turn in detail (assignment, artifacts, timing, verification) |
+| `phase list\|show` | List configured phases or inspect a single phase's gate requirements and state |
+| `gate list\|show [--evaluate]` | List configured gates or evaluate a gate's current pass/fail state |
+| `doctor [--json]` | Governed project health check: config, roles, runtimes, state, schedules, plugins, workflow-kit, connector handoff |
+| `connector check [--json]` | Live health probes for all configured connectors (api_proxy, remote_agent, MCP stdio/streamable_http) |
+
+### Governed automation, plugins, and continuity
+
+| Command | What it does |
+|---|---|
 | `multi init\|status\|step\|resume\|approve-gate\|resync` | Run the multi-repo coordinator lifecycle, including blocked-state recovery via `multi resume` |
 | `intake record\|triage\|approve\|plan\|start\|scan\|resolve` | Continuous-delivery intake: turn delivery signals into governed work items |
 | `intake handoff` | Bridge a planned intake intent to a coordinator workstream for multi-repo execution |
-| `plugin install\|list\|remove` | Install, inspect, or remove governed hook plugins backed by `agentxchain-plugin.json` manifests |
+| `schedule list\|run-due\|daemon\|status` | Run repo-local lights-out scheduling: inspect schedules, execute due runs, poll in a local daemon loop, or check daemon heartbeat |
+| `plugin install\|list\|remove` | Install, inspect, or remove governed hook plugins under `.agentxchain/plugins/` |
+| `plugin list-available` | List bundled built-in plugins installable by short name |
+| `export [--output <path>]` | Export run state for cross-machine continuity |
+| `restore --input <path>` | Restore run state from a prior export on a same-repo, same-commit checkout |
+| `restart` | Rebuild lost session context from `.agentxchain/session.json` |
 
 ### Shared utilities
 

package/bin/agentxchain.js

@@ -131,7 +131,7 @@ program
 program
   .command('init')
   .description('Create a new AgentXchain project folder')
-  .option('-y, --yes', 'Skip prompts, use defaults')
+  .option('-y, --yes', 'Skip guided prompts, use defaults')
   .option('--governed', 'Create a governed project (orchestrator-owned state)')
   .option('--dir <path>', 'Scaffold target directory. Use "." for in-place bootstrap.')
   .option('--template <id>', 'Governed scaffold template: generic, api-service, cli-tool, library, web-app, enterprise-app')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.81.0",
+  "version": "2.83.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/commands/init.js

@@ -5,7 +5,7 @@ import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { CONFIG_FILE, LOCK_FILE, STATE_FILE } from '../lib/config.js';
 import { generateVSCodeFiles } from '../lib/generate-vscode.js';
-import { loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS, buildSystemSpecContent } from '../lib/governed-templates.js';
+import { loadAllGovernedTemplates, loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS, buildSystemSpecContent } from '../lib/governed-templates.js';
 import { normalizeWorkflowKit, VALID_PROMPT_TRANSPORTS } from '../lib/normalized-config.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -527,6 +527,76 @@ function formatInitTarget(dir) {
   return dir;
 }
 
+function normalizeOptionalGoal(value) {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function buildGovernedTemplateChoices(templates = loadAllGovernedTemplates()) {
+  return templates.map((template) => ({
+    name: `${chalk.cyan(template.display_name)} (${template.id}) — ${template.description}`,
+    value: template.id,
+    short: template.id,
+  }));
+}
+
+export async function resolveGovernedInitAnswers(opts, prompt = (questions) => inquirer.prompt(questions)) {
+  const explicitDir = resolveInitDirOption(opts.dir);
+  let templateId = opts.template || null;
+
+  if (!templateId) {
+    const { template } = await prompt([{
+      type: 'list',
+      name: 'template',
+      message: 'Governed template:',
+      choices: buildGovernedTemplateChoices(),
+      default: 'generic',
+    }]);
+    templateId = template;
+  }
+
+  const { name } = await prompt([{
+    type: 'input',
+    name: 'name',
+    message: 'Project name:',
+    default: explicitDir
+      ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain Project')
+      : 'My AgentXchain Project',
+  }]);
+  const projectName = name;
+  let folderName = explicitDir || slugify(projectName);
+
+  let projectGoal = normalizeOptionalGoal(opts.goal);
+  if (!projectGoal) {
+    const { goal } = await prompt([{
+      type: 'input',
+      name: 'goal',
+      message: 'Project goal (recommended; shown to every agent turn):',
+      default: '',
+    }]);
+    projectGoal = normalizeOptionalGoal(goal);
+  }
+
+  if (!explicitDir) {
+    const { folder } = await prompt([{
+      type: 'input',
+      name: 'folder',
+      message: 'Folder name:',
+      default: folderName,
+    }]);
+    folderName = folder;
+  }
+
+  return {
+    explicitDir,
+    templateId,
+    projectName,
+    folderName,
+    goal: projectGoal,
+  };
+}
+
 function generateWorkflowKitPlaceholder(artifact, projectName) {
   const filename = basename(artifact.path);
   const title = filename.replace(/\.[^.]+$/, '').replace(/[-_]/g, ' ');
@@ -813,12 +883,24 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
 
 async function initGoverned(opts) {
   let projectName, folderName;
-  const templateId = opts.template || 'generic';
+  let templateId;
   let selectedTemplate;
   let explicitDir;
+  let projectGoal;
 
   try {
-    explicitDir = resolveInitDirOption(opts.dir);
+    if (opts.yes) {
+      explicitDir = resolveInitDirOption(opts.dir);
+      templateId = opts.template || 'generic';
+      projectGoal = normalizeOptionalGoal(opts.goal);
+    } else {
+      const answers = await resolveGovernedInitAnswers(opts);
+      explicitDir = answers.explicitDir;
+      templateId = answers.templateId;
+      projectName = answers.projectName;
+      folderName = answers.folderName;
+      projectGoal = answers.goal;
+    }
   } catch (err) {
     console.error(chalk.red(`  Error: ${err.message}`));
     process.exit(1);
@@ -842,27 +924,6 @@ async function initGoverned(opts) {
       ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain Project')
       : 'My AgentXchain Project';
     folderName = explicitDir || slugify(projectName);
-  } else {
-    const { name } = await inquirer.prompt([{
-      type: 'input',
-      name: 'name',
-      message: 'Project name:',
-      default: explicitDir
-        ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain Project')
-        : 'My AgentXchain Project'
-    }]);
-    projectName = name;
-    folderName = explicitDir || slugify(projectName);
-
-    if (!explicitDir) {
-      const { folder } = await inquirer.prompt([{
-        type: 'input',
-        name: 'folder',
-        message: 'Folder name:',
-        default: folderName
-      }]);
-      folderName = folder;
-    }
   }
 
   const dir = resolve(process.cwd(), folderName);
@@ -908,7 +969,10 @@ async function initGoverned(opts) {
     }
   }
 
-  const { config, scaffoldWorkflowKitConfig } = scaffoldGoverned(dir, projectName, projectId, templateId, opts, workflowKitConfig);
+  const scaffoldOptions = projectGoal
+    ? { ...opts, goal: projectGoal }
+    : { ...opts };
+  const { config, scaffoldWorkflowKitConfig } = scaffoldGoverned(dir, projectName, projectId, templateId, scaffoldOptions, workflowKitConfig);
 
   console.log('');
   console.log(chalk.green(`  ✓ Created governed project ${chalk.bold(targetLabel)}/`));
@@ -933,6 +997,9 @@ async function initGoverned(opts) {
   console.log(`  ${chalk.dim('Roles:')} ${promptRoleIds.join(', ')}`);
   console.log(`  ${chalk.dim('Phases:')} ${phaseNames.join(' → ')} ${chalk.dim(selectedTemplate.scaffold_blueprint ? '(template-defined; edit routing in agentxchain.json to customize)' : '(default; extend via routing in agentxchain.json)')}`);
   console.log(`  ${chalk.dim('Template:')} ${templateId}`);
+  if (config.project?.goal) {
+    console.log(`  ${chalk.dim('Goal:')} ${config.project.goal}`);
+  }
   console.log(`  ${chalk.dim('Dev runtime:')} ${formatGovernedRuntimeCommand(localDevRuntime)} ${chalk.dim(`(${localDevRuntime.prompt_transport})`)}`);
   console.log(`  ${chalk.dim('Protocol:')} governed convergence`);
   console.log('');

package/src/commands/intake-status.js

@@ -19,7 +19,7 @@ export async function intakeStatusCommand(opts) {
 
   // Detail mode: single intent
   if (result.intent) {
-    printIntentDetail(result.intent, result.event);
+    printIntentDetail(result.intent, result.event, result.next_action);
     process.exit(0);
   }
 
@@ -46,14 +46,17 @@ function printSummary(summary) {
       const pri = i.priority ? i.priority.padEnd(3) : '---';
       const tpl = (i.template || '---').padEnd(12);
       const st = statusColor(i.status);
-      console.log(`  ${chalk.dim(i.intent_id)}  ${pri}  ${tpl}  ${st}  ${chalk.dim(i.updated_at)}`);
+      const actionHint = i.next_action?.action_required && i.next_action?.label !== 'none'
+        ? `  ${chalk.dim(`→ ${i.next_action.label}`)}`
+        : '';
+      console.log(`  ${chalk.dim(i.intent_id)}  ${pri}  ${tpl}  ${st}  ${chalk.dim(i.updated_at)}${actionHint}`);
     }
   }
 
   console.log('');
 }
 
-function printIntentDetail(intent, event) {
+function printIntentDetail(intent, event, nextAction) {
   console.log('');
   console.log(chalk.bold(`  Intent: ${intent.intent_id}`));
   console.log(chalk.dim('  ' + '─'.repeat(44)));
@@ -93,6 +96,21 @@ function printIntentDetail(intent, event) {
     console.log(`    ${chalk.dim('Signal:')}  ${JSON.stringify(event.signal)}`);
   }
 
+  if (nextAction) {
+    console.log('');
+    console.log(chalk.dim('  Next Action:'));
+    console.log(`    ${nextAction.summary}`);
+    if (nextAction.command) {
+      console.log(`    ${chalk.dim('Command:')}  ${nextAction.command}`);
+    }
+    for (const alternative of nextAction.alternatives || []) {
+      console.log(`    ${chalk.dim('Alternative:')} ${alternative}`);
+    }
+    if (nextAction.recovery) {
+      console.log(`    ${chalk.dim('Recovery:')} ${nextAction.recovery}`);
+    }
+  }
+
   console.log('');
 }
 

package/src/commands/multi.js

@@ -235,6 +235,14 @@ export async function multiStepCommand(options) {
       // Fire on_escalation for the blocked resync
       fireEscalationHook(workspacePath, configResult.config, state, resync.blocked_reason || 'resync failure');
       console.error(`Coordinator resync entered blocked state: ${resync.blocked_reason || 'unknown reason'}`);
+      for (const mismatch of resync.mismatch_details || []) {
+        const codeTag = mismatch.code ? `[${mismatch.code}] ` : '';
+        console.error(`  - ${codeTag}${mismatch.message}`);
+        if (mismatch.code === 'repo_run_id_mismatch') {
+          console.error(`    expected: ${mismatch.expected_run_id}`);
+          console.error(`    actual:   ${mismatch.actual_run_id}`);
+        }
+      }
       process.exitCode = 1;
       return;
     }

package/src/commands/restart.js

@@ -167,7 +167,7 @@ export async function restartCommand(opts) {
   // Load state
   const statePath = join(root, STATE_PATH);
   if (!existsSync(statePath)) {
-    console.log(chalk.red('No governed run found. Use `agentxchain resume` or `agentxchain run` to start.'));
+    console.log(chalk.red('No governed run found. Use `agentxchain run` to start a governed run.'));
     process.exit(1);
   }
 

package/src/commands/resume.js

@@ -36,9 +36,9 @@ import {
   getDispatchEffectiveContextPath,
   getDispatchPromptPath,
 } from '../lib/turn-paths.js';
-import { safeWriteJson } from '../lib/safe-write.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { runHooks } from '../lib/hook-runner.js';
+import { summarizeRunProvenance } from '../lib/run-provenance.js';
 
 export async function resumeCommand(opts) {
   const context = loadProjectContext();
@@ -100,6 +100,11 @@ export async function resumeCommand(opts) {
     process.exit(1);
   }
 
+  if (state.pending_phase_transition || state.pending_run_completion) {
+    printRecoverySummary(state, 'This run is awaiting approval.');
+    process.exit(1);
+  }
+
   // §47: paused + retained turn with failed/retrying status → re-dispatch same turn
   if (state.status === 'paused' && activeCount > 0) {
     // Resolve which turn to re-dispatch
@@ -124,15 +129,18 @@ export async function resumeCommand(opts) {
 
     const turnStatus = retainedTurn.status;
     if (turnStatus === 'failed' || turnStatus === 'retrying') {
+      printResumeRunContext({ root, state, config });
       console.log(chalk.yellow(`Re-dispatching failed turn: ${retainedTurn.turn_id}`));
       console.log(`  Role:    ${retainedTurn.assigned_role}`);
       console.log(`  Attempt: ${retainedTurn.attempt}`);
       console.log('');
 
-      // Reactivate the run
-      state.status = 'active';
-      state.blocked_on = null;
-      safeWriteJson(statePath, state);
+      const reactivated = reactivateGovernedRun(root, state, { via: 'resume --turn', notificationConfig: config });
+      if (!reactivated.ok) {
+        console.log(chalk.red(`Failed to reactivate run: ${reactivated.error}`));
+        process.exit(1);
+      }
+      state = reactivated.state;
 
       // Write dispatch bundle for the existing turn
       const bundleResult = writeDispatchBundle(root, state, config);
@@ -181,6 +189,7 @@ export async function resumeCommand(opts) {
       process.exit(1);
     }
 
+    printResumeRunContext({ root, state, config });
     console.log(chalk.yellow(`Re-dispatching blocked turn: ${retainedTurn.turn_id}`));
     console.log(`  Role:    ${retainedTurn.assigned_role}`);
     console.log(`  Attempt: ${retainedTurn.attempt}`);
@@ -236,14 +245,18 @@ export async function resumeCommand(opts) {
 
   // §47: paused + run_id exists → resume same run
   if (state.status === 'paused' && state.run_id) {
-    state.status = 'active';
-    state.blocked_on = null;
-    state.blocked_reason = null;
-    state.escalation = null;
-    safeWriteJson(statePath, state);
+    const reactivated = reactivateGovernedRun(root, state, { via: 'resume', notificationConfig: config });
+    if (!reactivated.ok) {
+      console.log(chalk.red(`Failed to reactivate run: ${reactivated.error}`));
+      process.exit(1);
+    }
+    state = reactivated.state;
     console.log(chalk.green(`Resumed governed run: ${state.run_id}`));
   }
 
+  // Print run-context header before dispatch
+  printResumeRunContext({ root, state, config });
+
   // Resolve target role
   const roleId = resolveTargetRole(opts, state, config);
   if (!roleId) {
@@ -295,6 +308,53 @@ export async function resumeCommand(opts) {
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
+function printResumeRunContext({ root, state, config }) {
+  console.log('');
+  console.log(chalk.cyan.bold('agentxchain resume'));
+  console.log(`  ${chalk.dim('Run:')}      ${state?.run_id || '(uninitialized)'}`);
+  console.log(`  ${chalk.dim('Phase:')}    ${state?.phase || '(unknown)'}`);
+
+  const provenanceSummary = summarizeRunProvenance(state?.provenance);
+  if (provenanceSummary) {
+    console.log(`  ${chalk.dim('Origin:')}   ${chalk.magenta(provenanceSummary)}`);
+  }
+
+  if (state?.inherited_context?.parent_run_id) {
+    console.log(
+      `  ${chalk.dim('Inherits:')} ${chalk.magenta(
+        `parent ${state.inherited_context.parent_run_id} (${state.inherited_context.parent_status || 'unknown'})`
+      )}`
+    );
+  }
+
+  const activeGate = config?.routing?.[state?.phase]?.exit_gate || null;
+  if (activeGate) {
+    const gateStatus = state?.phase_gate_status?.[activeGate] || 'pending';
+    console.log(`  ${chalk.dim('Gate:')}     ${activeGate} (${gateStatus})`);
+
+    if (gateStatus !== 'passed') {
+      const gateDef = config?.gates?.[activeGate];
+      if (Array.isArray(gateDef?.requires_files) && gateDef.requires_files.length > 0) {
+        const fileChecks = gateDef.requires_files.map((filePath) => {
+          const exists = existsSync(join(root, filePath));
+          const shortPath = filePath.replace(/^\.planning\//, '');
+          return exists ? chalk.green(shortPath) : chalk.red(shortPath);
+        });
+        console.log(`  ${chalk.dim('Files:')}    ${fileChecks.join(chalk.dim(', '))}`);
+      }
+
+      const requirements = [];
+      if (gateDef?.requires_human_approval) requirements.push('human approval');
+      if (gateDef?.requires_verification_pass) requirements.push('verification pass');
+      if (requirements.length > 0) {
+        console.log(`  ${chalk.dim('Needs:')}    ${requirements.join(', ')}`);
+      }
+    }
+  }
+
+  console.log('');
+}
+
 function resolveTargetRole(opts, state, config) {
   const phase = state.phase;
   const routing = config.routing?.[phase];
@@ -422,6 +482,19 @@ function printAssignmentWarnings(assignResult) {
   }
 }
 
+function printRecoverySummary(state, heading) {
+  const recovery = deriveRecoveryDescriptor(state);
+  console.log(chalk.yellow(heading));
+  if (!recovery) {
+    return;
+  }
+  console.log(`  ${chalk.dim('Reason:')} ${recovery.typed_reason}`);
+  console.log(`  ${chalk.dim('Action:')} ${recovery.recovery_action}`);
+  if (recovery.detail) {
+    console.log(`  ${chalk.dim('Detail:')} ${recovery.detail}`);
+  }
+}
+
 function printAssignmentHookFailure(result, roleId) {
   const recovery = deriveRecoveryDescriptor(result.state);
   const hookName = result.hookResults?.blocker?.hook_name

package/src/commands/run.js

@@ -32,6 +32,7 @@ import { dispatchRemoteAgent, describeRemoteAgentTarget } from '../lib/adapters/
 import { runHooks } from '../lib/hook-runner.js';
 import { finalizeDispatchManifest } from '../lib/dispatch-manifest.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+import { summarizeRunProvenance } from '../lib/run-provenance.js';
 import { resolveGovernedRole } from '../lib/role-resolution.js';
 import { buildInheritedContext } from '../lib/run-context-inheritance.js';
 import {
@@ -179,6 +180,24 @@ export async function executeGovernedRun(context, opts = {}) {
   // ── Run header ──────────────────────────────────────────────────────────
   log(chalk.cyan.bold('agentxchain run'));
   log(chalk.dim(`  Max turns: ${maxTurns}  Gate mode: ${autoApprove ? 'auto-approve' : 'interactive'}`));
+  if (provenance) {
+    const provenanceSummary = summarizeRunProvenance(provenance);
+    if (provenanceSummary) {
+      log(`  ${chalk.dim('Origin:')}    ${chalk.magenta(provenanceSummary)}`);
+    }
+  }
+  if (inheritedContext) {
+    const ic = inheritedContext;
+    const phasesCount = ic.parent_phases_completed?.length || 0;
+    const decisionsCount = ic.recent_decisions?.length || 0;
+    const turnsCount = ic.recent_accepted_turns?.length || 0;
+    const parts = [];
+    if (phasesCount) parts.push(`${phasesCount} phase${phasesCount !== 1 ? 's' : ''}`);
+    if (decisionsCount) parts.push(`${decisionsCount} decision${decisionsCount !== 1 ? 's' : ''}`);
+    if (turnsCount) parts.push(`${turnsCount} turn${turnsCount !== 1 ? 's' : ''}`);
+    const detail = parts.length ? ` — ${parts.join(', ')}` : '';
+    log(`  ${chalk.dim('Inherits:')} ${chalk.magenta(`parent ${ic.parent_run_id} (${ic.parent_status || 'unknown'})${detail}`)}`);
+  }
   log('');
 
   // ── Track first-call for --role override ────────────────────────────────

package/src/commands/status.js

@@ -1,4 +1,6 @@
 import chalk from 'chalk';
+import { existsSync } from 'fs';
+import { join } from 'path';
 import { loadConfig, loadLock, loadProjectContext, loadProjectState, loadState } from '../lib/config.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { getActiveTurn, getActiveTurnCount, getActiveTurns } from '../lib/governed-state.js';
@@ -267,9 +269,29 @@ function renderGovernedStatus(context, opts) {
   if (state?.phase_gate_status) {
     console.log('');
     console.log(`  ${chalk.dim('Gates:')}`);
+    const activePhase = state.phase;
+    const activeRouting = config.routing?.[activePhase];
+    const activeExitGate = activeRouting?.exit_gate || null;
     for (const [gate, status] of Object.entries(state.phase_gate_status)) {
       const icon = status === 'passed' ? chalk.green('✓') : chalk.dim('○');
       console.log(`    ${icon} ${gate}: ${status}`);
+      if (status !== 'passed' && gate === activeExitGate && config.gates?.[gate]) {
+        const gateDef = config.gates[gate];
+        if (Array.isArray(gateDef.requires_files) && gateDef.requires_files.length > 0) {
+          const fileChecks = gateDef.requires_files.map(f => {
+            const exists = existsSync(join(root, f));
+            const short = f.replace(/^\.planning\//, '');
+            return exists ? chalk.green(short) : chalk.red(short);
+          });
+          console.log(`      ${chalk.dim('Files:')} ${fileChecks.join(chalk.dim(', '))}`);
+        }
+        const reqs = [];
+        if (gateDef.requires_human_approval) reqs.push('human approval');
+        if (gateDef.requires_verification_pass) reqs.push('verification pass');
+        if (reqs.length > 0) {
+          console.log(`      ${chalk.dim('Needs:')} ${reqs.join(', ')}`);
+        }
+      }
     }
   }
 
@@ -425,7 +447,7 @@ function renderWorkflowKitArtifactsSection(wkData) {
 
 function renderLastGateFailure(failure, config) {
   const entryRole = config?.routing?.[failure.phase]?.entry_role || null;
-  const suggestedCommand = entryRole ? `agentxchain assign ${entryRole}` : 'agentxchain assign <role>';
+  const suggestedCommand = entryRole ? `agentxchain step --role ${entryRole}` : 'agentxchain step --role <role>';
   const requestLabel = failure.gate_type === 'run_completion'
     ? 'Run completion'
     : `${failure.from_phase || failure.phase} -> ${failure.to_phase || 'unknown'}`;

package/src/commands/step.js

@@ -51,6 +51,7 @@ import {
 } from '../lib/adapters/local-cli-adapter.js';
 import { describeMcpRuntimeTarget, dispatchMcp, resolveMcpTransport } from '../lib/adapters/mcp-adapter.js';
 import { dispatchRemoteAgent, describeRemoteAgentTarget } from '../lib/adapters/remote-agent-adapter.js';
+import { summarizeRunProvenance } from '../lib/run-provenance.js';
 import {
   getDispatchAssignmentPath,
   getDispatchContextPath,
@@ -60,7 +61,6 @@ import {
   getTurnStagingResultPath,
 } from '../lib/turn-paths.js';
 import { dispatchApiProxy } from '../lib/adapters/api-proxy-adapter.js';
-import { safeWriteJson } from '../lib/safe-write.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { runHooks } from '../lib/hook-runner.js';
 import { finalizeDispatchManifest, verifyDispatchManifest } from '../lib/dispatch-manifest.js';
@@ -165,8 +165,8 @@ export async function stepCommand(opts) {
   }
 
   if (!skipAssignment) {
-    if (state.status === 'paused' && (state.pending_phase_transition || state.pending_run_completion)) {
-      printRecoverySummary(state, 'This run is paused for approval.');
+    if (state.pending_phase_transition || state.pending_run_completion) {
+      printRecoverySummary(state, 'This run is awaiting approval.');
       process.exit(1);
     }
 
@@ -231,10 +231,12 @@ export async function stepCommand(opts) {
       const turnStatus = pausedTurn?.status;
       if (turnStatus === 'failed' || turnStatus === 'retrying') {
         console.log(chalk.yellow(`Re-dispatching failed turn: ${pausedTurn.turn_id}`));
-        state.status = 'active';
-        state.blocked_on = null;
-        state.blocked_reason = null;
-        safeWriteJson(join(root, STATE_PATH), state);
+        const reactivated = reactivateGovernedRun(root, state, { via: 'step --resume', notificationConfig: config });
+        if (!reactivated.ok) {
+          console.log(chalk.red(`Failed to reactivate run: ${reactivated.error}`));
+          process.exit(1);
+        }
+        state = reactivated.state;
         skipAssignment = true;
 
         const bundleResult = writeDispatchBundle(root, state, config);
@@ -270,11 +272,12 @@ export async function stepCommand(opts) {
     }
 
     if (!skipAssignment && state.status === 'paused' && state.run_id) {
-      state.status = 'active';
-      state.blocked_on = null;
-      state.blocked_reason = null;
-      state.escalation = null;
-      safeWriteJson(join(root, STATE_PATH), state);
+      const reactivated = reactivateGovernedRun(root, state, { via: 'step', notificationConfig: config });
+      if (!reactivated.ok) {
+        console.log(chalk.red(`Failed to reactivate run: ${reactivated.error}`));
+        process.exit(1);
+      }
+      state = reactivated.state;
       console.log(chalk.green(`Resumed governed run: ${state.run_id}`));
     }
 
@@ -324,6 +327,8 @@ export async function stepCommand(opts) {
   const runtimeType = runtime?.type || role?.runtime_class || 'manual';
   const hooksConfig = config.hooks || {};
 
+  printStepRunContext({ root, state, config });
+
   if (bundleWritten && hooksConfig.after_dispatch?.length > 0) {
     const afterDispatchHooks = runHooks(root, hooksConfig, 'after_dispatch', {
       turn_id: turn.turn_id,
@@ -943,6 +948,53 @@ function printRecoverySummary(state, heading) {
   }
 }
 
+function printStepRunContext({ root, state, config }) {
+  console.log('');
+  console.log(chalk.cyan.bold('agentxchain step'));
+  console.log(`  ${chalk.dim('Run:')}      ${state?.run_id || '(uninitialized)'}`);
+  console.log(`  ${chalk.dim('Phase:')}    ${state?.phase || '(unknown)'}`);
+
+  const provenanceSummary = summarizeRunProvenance(state?.provenance);
+  if (provenanceSummary) {
+    console.log(`  ${chalk.dim('Origin:')}   ${chalk.magenta(provenanceSummary)}`);
+  }
+
+  if (state?.inherited_context?.parent_run_id) {
+    console.log(
+      `  ${chalk.dim('Inherits:')} ${chalk.magenta(
+        `parent ${state.inherited_context.parent_run_id} (${state.inherited_context.parent_status || 'unknown'})`
+      )}`
+    );
+  }
+
+  const activeGate = config?.routing?.[state?.phase]?.exit_gate || null;
+  if (activeGate) {
+    const gateStatus = state?.phase_gate_status?.[activeGate] || 'pending';
+    console.log(`  ${chalk.dim('Gate:')}     ${activeGate} (${gateStatus})`);
+
+    if (gateStatus !== 'passed') {
+      const gateDef = config?.gates?.[activeGate];
+      if (Array.isArray(gateDef?.requires_files) && gateDef.requires_files.length > 0) {
+        const fileChecks = gateDef.requires_files.map((filePath) => {
+          const exists = existsSync(join(root, filePath));
+          const shortPath = filePath.replace(/^\.planning\//, '');
+          return exists ? chalk.green(shortPath) : chalk.red(shortPath);
+        });
+        console.log(`  ${chalk.dim('Files:')}    ${fileChecks.join(chalk.dim(', '))}`);
+      }
+
+      const requirements = [];
+      if (gateDef?.requires_human_approval) requirements.push('human approval');
+      if (gateDef?.requires_verification_pass) requirements.push('verification pass');
+      if (requirements.length > 0) {
+        console.log(`  ${chalk.dim('Needs:')}    ${requirements.join(', ')}`);
+      }
+    }
+  }
+
+  console.log('');
+}
+
 function printDispatchBundleWarnings(bundleResult) {
   for (const warning of bundleResult.warnings || []) {
     console.log(chalk.yellow(`Dispatch bundle warning: ${warning}`));

package/src/lib/coordinator-recovery.js

@@ -239,6 +239,7 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
   const resyncedRepos = [];
   const projectedAcceptances = [];
   const barrierChanges = [];
+  const mismatchDetails = [];
 
   // Step 1: Refresh repo_runs from repo-local authority
   const updatedRepoRuns = { ...state.repo_runs };
@@ -262,6 +263,13 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
     if (repoRun.run_id && repoRun.run_id !== (repoState.run_id ?? null)) {
       const reason = buildRunIdMismatchReason(repoId, repoRun.run_id, repoState.run_id ?? null);
       runIdMismatches.push(reason);
+      mismatchDetails.push({
+        code: 'repo_run_id_mismatch',
+        repo_id: repoId,
+        expected_run_id: repoRun.run_id,
+        actual_run_id: repoState.run_id ?? null,
+        message: reason,
+      });
       errors.push(reason);
       continue;
     }
@@ -447,6 +455,7 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
     resynced_repos: [...new Set(resyncedRepos)],
     projected_acceptances: projectedAcceptances,
     barrier_changes: barrierChanges,
+    mismatch_details: mismatchDetails,
     errors,
     blocked_reason: blockedReason || undefined,
   };

package/src/lib/dispatch-bundle.js

@@ -118,6 +118,9 @@ export function writeDispatchBundle(root, state, config, opts = {}) {
     budget_reservation_usd: state.budget_reservations?.[turn.turn_id]?.reserved_usd ?? null,
     active_siblings: activeSiblings,
   };
+  if (turn.intake_context) {
+    assignment.intake_context = turn.intake_context;
+  }
   if (turn.conflict_context) {
     assignment.conflict_context = turn.conflict_context;
   }
@@ -523,6 +526,27 @@ function renderContext(state, config, root, turn, role) {
     lines.push('');
   }
 
+  if (turn.intake_context) {
+    lines.push('## Intake Intent');
+    lines.push('');
+    lines.push(`- **Intent:** ${turn.intake_context.intent_id || 'unknown'}`);
+    lines.push(`- **Event:** ${turn.intake_context.event_id || 'unknown'}`);
+    lines.push(`- **Source:** ${turn.intake_context.source || 'unknown'}`);
+    if (turn.intake_context.category) {
+      lines.push(`- **Category:** ${turn.intake_context.category}`);
+    }
+    if (turn.intake_context.charter) {
+      lines.push(`- **Charter:** ${turn.intake_context.charter}`);
+    }
+    if (Array.isArray(turn.intake_context.acceptance_contract) && turn.intake_context.acceptance_contract.length > 0) {
+      lines.push('- **Acceptance Contract:**');
+      for (const requirement of turn.intake_context.acceptance_contract) {
+        lines.push(`  - ${requirement}`);
+      }
+    }
+    lines.push('');
+  }
+
   // Inherited context from parent run (when --inherit-context was used)
   if (state.inherited_context) {
     // First turn gets the full rendering; subsequent turns get compact
@@ -1197,13 +1221,13 @@ function buildTurnResultTemplate(state, turn, roleId, role) {
     role: roleId,
     runtime_id: turn.runtime_id,
     status: 'completed',
-    summary: 'TODO: describe what you accomplished this turn',
+    summary: '<one-line summary of what you accomplished>',
     decisions: [
       {
         id: 'DEC-001',
         category: 'implementation',
-        statement: 'TODO: describe the decision',
-        rationale: 'TODO: explain why',
+        statement: '<what was decided and why it matters>',
+        rationale: '<reasoning behind this decision>',
       },
     ],
     objections: isReviewOnly
@@ -1211,29 +1235,29 @@ function buildTurnResultTemplate(state, turn, roleId, role) {
           {
             id: 'OBJ-001',
             severity: 'medium',
-            against_turn_id: state.last_completed_turn_id || 'TODO',
-            statement: 'TODO: challenge the previous turn (required for review_only roles)',
+            against_turn_id: state.last_completed_turn_id || '<turn_id of the turn you are reviewing>',
+            statement: '<specific objection to the previous turn — required for review_only roles>',
             status: 'raised',
           },
         ]
       : [],
-    files_changed: isReviewOnly ? [] : ['TODO: list every file you modified'],
+    files_changed: isReviewOnly ? [] : ['<path/to/modified/file>'],
     artifacts_created: [],
     verification: {
       status: isReviewOnly ? 'skipped' : 'pass',
-      commands: isReviewOnly ? [] : ['TODO: list commands you ran'],
+      commands: isReviewOnly ? [] : ['<command you ran to verify>'],
       evidence_summary: isReviewOnly
         ? 'Review turn — no verification commands required.'
-        : 'TODO: describe what you verified',
+        : '<what you verified and how>',
       machine_evidence: isReviewOnly
         ? []
-        : [{ command: 'TODO', exit_code: 0 }],
+        : [{ command: '<exact command that was run>', exit_code: 0 }],
     },
     artifact: {
       type: isReviewOnly ? 'review' : 'workspace',
       ref: isReviewOnly ? null : 'git:dirty',
     },
-    proposed_next_role: 'TODO',
+    proposed_next_role: '<role_id that should act next>',
     phase_transition_request: null,
     run_completion_request: null,
     needs_human_reason: null,

package/src/lib/governed-state.js

@@ -1774,6 +1774,12 @@ export function reactivateGovernedRun(root, state, details = {}) {
   if (!state || typeof state !== 'object') {
     return { ok: false, error: 'State is required.' };
   }
+  if (state.status !== 'blocked' && state.status !== 'paused') {
+    return { ok: false, error: `Cannot reactivate run: status is "${state.status}", expected "blocked" or "paused".` };
+  }
+  if (state.pending_phase_transition || state.pending_run_completion) {
+    return { ok: false, error: 'Cannot reactivate run: this run is awaiting approval. Use approve-transition or approve-completion.' };
+  }
 
   const now = new Date().toISOString();
   const wasEscalation = state.status === 'blocked' && typeof state.blocked_on === 'string' && state.blocked_on.startsWith('escalation:');
@@ -1819,7 +1825,7 @@ export function reactivateGovernedRun(root, state, details = {}) {
 // ── Core Operations ──────────────────────────────────────────────────────────
 
 /**
- * Initialize a governed run from idle state.
+ * Initialize a governed run from bootstrap state.
  * Creates a run_id and sets status to 'active'.
  *
  * @param {string} root - project root directory
@@ -1829,7 +1835,7 @@ export function reactivateGovernedRun(root, state, details = {}) {
 export function initializeGovernedRun(root, config, options = {}) {
   let state = readState(root);
   if (!state) {
-    return { ok: false, error: 'No governed state.json found' };
+    state = buildFreshIdleStateForNewRun(null, config);
   }
   const allowTerminalRestart = options.allow_terminal_restart === true
     && (state.status === 'completed' || state.status === 'blocked');
@@ -1837,8 +1843,8 @@ export function initializeGovernedRun(root, config, options = {}) {
     return { ok: false, error: 'Cannot initialize run: this run is already completed. Start a new project or reset state.' };
   }
   const allowBlockedBootstrap = state.status === 'blocked' && state.run_id === null && getActiveTurnCount(state) === 0;
-  if (state.status !== 'idle' && state.status !== 'paused' && !allowBlockedBootstrap && !allowTerminalRestart) {
-    return { ok: false, error: `Cannot initialize run: status is "${state.status}", expected "idle", "paused", or pre-run "blocked"` };
+  if (state.status !== 'idle' && !allowBlockedBootstrap && !allowTerminalRestart) {
+    return { ok: false, error: `Cannot initialize run: status is "${state.status}", expected "idle" or pre-run "blocked"` };
   }
   if (allowTerminalRestart) {
     state = buildFreshIdleStateForNewRun(state, config);

package/src/lib/intake.js

@@ -120,6 +120,122 @@ function readJsonDir(dirPath) {
     .filter(Boolean);
 }
 
+function buildIntakeNextAction(intent) {
+  const intentId = intent?.intent_id || '<intent_id>';
+  const status = intent?.status || 'unknown';
+  const resolveCommand = `agentxchain intake resolve --intent ${intentId}`;
+
+  switch (status) {
+    case 'detected':
+      return {
+        label: 'triage',
+        summary: 'Triage this detected intent so it can enter governed delivery.',
+        command: `agentxchain intake triage --intent ${intentId} --priority <p0-p3> --template <template_id> --charter "<charter>" --acceptance "<criterion>"`,
+        alternatives: [
+          `agentxchain intake triage --intent ${intentId} --suppress --reason "<reason>"`,
+        ],
+        recovery: null,
+        action_required: true,
+      };
+    case 'triaged':
+      return {
+        label: 'approve',
+        summary: 'Approve this triaged intent for planning or reject it explicitly.',
+        command: `agentxchain intake approve --intent ${intentId}`,
+        alternatives: [
+          `agentxchain intake triage --intent ${intentId} --reject --reason "<reason>"`,
+        ],
+        recovery: null,
+        action_required: true,
+      };
+    case 'approved':
+      return {
+        label: 'plan',
+        summary: 'Generate planning artifacts for this approved intent.',
+        command: `agentxchain intake plan --intent ${intentId}`,
+        alternatives: [],
+        recovery: null,
+        action_required: true,
+      };
+    case 'planned':
+      return {
+        label: 'start',
+        summary: 'Start repo-local execution or hand the intent off to a coordinator workstream.',
+        command: `agentxchain intake start --intent ${intentId}`,
+        alternatives: [
+          `agentxchain intake handoff --intent ${intentId} --coordinator-root <path> --workstream <id>`,
+        ],
+        recovery: null,
+        action_required: true,
+      };
+    case 'executing':
+      return {
+        label: 'resolve',
+        summary: intent?.target_workstream
+          ? 'Re-check the coordinator workstream outcome for this intent.'
+          : 'Re-check the governed run outcome for this intent.',
+        command: resolveCommand,
+        alternatives: [],
+        recovery: null,
+        action_required: true,
+      };
+    case 'blocked':
+      return {
+        label: 'recover',
+        summary: 'Resolve the linked run blockage, then re-check intake resolution.',
+        command: resolveCommand,
+        alternatives: [],
+        recovery: intent?.run_blocked_recovery || null,
+        action_required: true,
+      };
+    case 'completed':
+      return {
+        label: 'none',
+        summary: 'No action required. This intent completed successfully.',
+        command: null,
+        alternatives: [],
+        recovery: null,
+        action_required: false,
+      };
+    case 'suppressed':
+      return {
+        label: 'none',
+        summary: 'No action required. This intent was suppressed.',
+        command: null,
+        alternatives: [],
+        recovery: null,
+        action_required: false,
+      };
+    case 'rejected':
+      return {
+        label: 'none',
+        summary: 'No action required. This intent was rejected.',
+        command: null,
+        alternatives: [],
+        recovery: null,
+        action_required: false,
+      };
+    case 'failed':
+      return {
+        label: 'inspect',
+        summary: 'Manual inspection required. This intent is in a reserved failed state.',
+        command: null,
+        alternatives: [],
+        recovery: 'Inspect the linked intent and run artifacts manually before continuing.',
+        action_required: true,
+      };
+    default:
+      return {
+        label: 'inspect',
+        summary: 'Manual inspection required. The intent state is not recognized by the current intake surface.',
+        command: null,
+        alternatives: [],
+        recovery: null,
+        action_required: true,
+      };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Validation
 // ---------------------------------------------------------------------------
@@ -329,7 +445,13 @@ export function intakeStatus(root, intentId) {
     const intent = JSON.parse(readFileSync(intentPath, 'utf8'));
     const eventPath = join(dirs.events, `${intent.event_id}.json`);
     const event = existsSync(eventPath) ? JSON.parse(readFileSync(eventPath, 'utf8')) : null;
-    return { ok: true, intent, event, exitCode: 0 };
+    return {
+      ok: true,
+      intent,
+      event,
+      next_action: buildIntakeNextAction(intent),
+      exitCode: 0,
+    };
   }
 
   const events = readJsonDir(dirs.events);
@@ -354,6 +476,7 @@ export function intakeStatus(root, intentId) {
         template: i.template,
         status: i.status,
         updated_at: i.updated_at,
+        next_action: buildIntakeNextAction(i),
       })),
   };
 
@@ -521,6 +644,20 @@ export function startIntent(root, intentId, options = {}) {
     };
   }
 
+  const loadedEvent = readEvent(root, intent.event_id);
+  if (!loadedEvent.ok) {
+    return loadedEvent;
+  }
+  const { event } = loadedEvent;
+  const intakeContext = {
+    intent_id: intent.intent_id,
+    event_id: intent.event_id,
+    source: event.source || null,
+    category: event.category || null,
+    charter: intent.charter || null,
+    acceptance_contract: Array.isArray(intent.acceptance_contract) ? intent.acceptance_contract : [],
+  };
+
   // Load governed project context
   const context = loadProjectContext(root);
   if (!context) {
@@ -569,6 +706,10 @@ export function startIntent(root, intentId, options = {}) {
     };
   }
 
+  if (state.status === 'paused') {
+    return { ok: false, error: 'cannot start: run is paused (awaiting approval). Resolve the blocking gate before starting a new intake turn.', exitCode: 1 };
+  }
+
   if (state.pending_phase_transition) {
     return { ok: false, error: `cannot start: pending phase transition to "${state.pending_phase_transition}"`, exitCode: 1 };
   }
@@ -579,21 +720,20 @@ export function startIntent(root, intentId, options = {}) {
 
   // Bootstrap: idle with no run → initialize
   if (state.status === 'idle' && !state.run_id) {
-    const initResult = initializeGovernedRun(root, config);
+    const initResult = initializeGovernedRun(root, config, {
+      provenance: {
+        trigger: 'intake',
+        intake_intent_id: intent.intent_id,
+        trigger_reason: intent.charter || null,
+        created_by: 'operator',
+      },
+    });
     if (!initResult.ok) {
       return { ok: false, error: `run initialization failed: ${initResult.error}`, exitCode: 1 };
     }
     state = initResult.state;
   }
 
-  // Resume: paused with no active turns → reactivate
-  if (state.status === 'paused' && state.run_id) {
-    state.status = 'active';
-    state.blocked_on = null;
-    state.escalation = null;
-    safeWriteJson(statePath, state);
-  }
-
   // Resolve role
   const roleId = resolveIntakeRole(options.role, state, config);
   if (!roleId.ok) {
@@ -614,6 +754,12 @@ export function startIntent(root, intentId, options = {}) {
     return { ok: false, error: 'turn assignment succeeded but turn not found in state', exitCode: 1 };
   }
 
+  assignedTurn.intake_context = intakeContext;
+  if (state.active_turns?.[assignedTurn.turn_id]) {
+    state.active_turns[assignedTurn.turn_id].intake_context = intakeContext;
+    safeWriteJson(statePath, state);
+  }
+
   // Write dispatch bundle
   const bundleResult = writeDispatchBundle(root, state, config);
   if (!bundleResult.ok) {

package/src/lib/turn-result-validator.js

@@ -263,9 +263,68 @@ function validateSchema(tr) {
     }
   }
 
+  errors.push(...collectUnfilledTemplatePlaceholderErrors(tr));
+
   return errors;
 }
 
+function collectUnfilledTemplatePlaceholderErrors(tr) {
+  const errors = [];
+
+  checkPlaceholder(errors, 'summary', tr.summary);
+  checkPlaceholder(errors, 'proposed_next_role', tr.proposed_next_role);
+
+  if (Array.isArray(tr.decisions)) {
+    for (let i = 0; i < tr.decisions.length; i++) {
+      const decision = tr.decisions[i];
+      checkPlaceholder(errors, `decisions[${i}].statement`, decision?.statement);
+      checkPlaceholder(errors, `decisions[${i}].rationale`, decision?.rationale);
+    }
+  }
+
+  if (Array.isArray(tr.objections)) {
+    for (let i = 0; i < tr.objections.length; i++) {
+      const objection = tr.objections[i];
+      checkPlaceholder(errors, `objections[${i}].against_turn_id`, objection?.against_turn_id);
+      checkPlaceholder(errors, `objections[${i}].statement`, objection?.statement);
+    }
+  }
+
+  if (Array.isArray(tr.files_changed)) {
+    for (let i = 0; i < tr.files_changed.length; i++) {
+      checkPlaceholder(errors, `files_changed[${i}]`, tr.files_changed[i]);
+    }
+  }
+
+  const verification = tr.verification;
+  if (verification && typeof verification === 'object' && !Array.isArray(verification)) {
+    if (Array.isArray(verification.commands)) {
+      for (let i = 0; i < verification.commands.length; i++) {
+        checkPlaceholder(errors, `verification.commands[${i}]`, verification.commands[i]);
+      }
+    }
+    checkPlaceholder(errors, 'verification.evidence_summary', verification.evidence_summary);
+
+    if (Array.isArray(verification.machine_evidence)) {
+      for (let i = 0; i < verification.machine_evidence.length; i++) {
+        checkPlaceholder(
+          errors,
+          `verification.machine_evidence[${i}].command`,
+          verification.machine_evidence[i]?.command
+        );
+      }
+    }
+  }
+
+  return errors;
+}
+
+function checkPlaceholder(errors, fieldPath, value) {
+  if (typeof value === 'string' && /^<[^>]+>$/.test(value)) {
+    errors.push(`${fieldPath} contains an unfilled template placeholder: "${value}".`);
+  }
+}
+
 function validateDecision(dec, index) {
   const errors = [];
   const prefix = `decisions[${index}]`;

package/src/lib/workflow-gate-semantics.js

@@ -56,6 +56,31 @@ function evaluatePmSignoff(content) {
   return { ok: true };
 }
 
+const SYSTEM_SPEC_SCAFFOLD_PLACEHOLDER = /^\(.*\)$/;
+const SYSTEM_SPEC_ACCEPTANCE_SCAFFOLD = /^- \[ \] Name the executable checks/;
+
+function isSystemSpecPlaceholderLine(line) {
+  return SYSTEM_SPEC_SCAFFOLD_PLACEHOLDER.test(line) || SYSTEM_SPEC_ACCEPTANCE_SCAFFOLD.test(line);
+}
+
+function hasSectionRealContent(content, sectionHeader, isPlaceholderFn) {
+  const lines = content.split(/\r?\n/);
+  const headerIndex = lines.findIndex((line) => line.trim().startsWith(sectionHeader));
+  if (headerIndex === -1) {
+    return { found: false, hasContent: false };
+  }
+
+  for (let i = headerIndex + 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.startsWith('## ')) break;
+    if (!line) continue;
+    if (isPlaceholderFn(line)) continue;
+    return { found: true, hasContent: true };
+  }
+
+  return { found: true, hasContent: false };
+}
+
 function evaluateSystemSpec(content) {
   const requiredSections = ['## Purpose', '## Interface', '## Acceptance Tests'];
   const missingSections = requiredSections.filter((section) => !content.includes(section));
@@ -67,6 +92,21 @@ function evaluateSystemSpec(content) {
     };
   }
 
+  const placeholderSections = [];
+  for (const section of requiredSections) {
+    const result = hasSectionRealContent(content, section, isSystemSpecPlaceholderLine);
+    if (result.found && !result.hasContent) {
+      placeholderSections.push(section);
+    }
+  }
+
+  if (placeholderSections.length > 0) {
+    return {
+      ok: false,
+      reason: `${placeholderSections.join(' and ')} in .planning/SYSTEM_SPEC.md still contains only scaffold placeholder text. Replace placeholder content with real spec content before planning can exit.`,
+    };
+  }
+
   return { ok: true };
 }
 
@@ -362,6 +402,15 @@ function evaluateShipVerdict(content) {
   return { ok: true };
 }
 
+const SECTION_CHECK_SCAFFOLD_PLACEHOLDERS = [
+  /^\(Content here\.\)$/i,
+  /^\(Operator fills this in\.\)$/i,
+];
+
+function isSectionCheckPlaceholderLine(line) {
+  return SECTION_CHECK_SCAFFOLD_PLACEHOLDERS.some((re) => re.test(line));
+}
+
 function evaluateSectionCheck(content, config) {
   if (!config?.required_sections?.length) {
     return { ok: true };
@@ -375,6 +424,22 @@ function evaluateSectionCheck(content, config) {
       reason: `Document must contain sections: ${missing.join(', ')}`,
     };
   }
+
+  const placeholderSections = [];
+  for (const section of config.required_sections) {
+    const result = hasSectionRealContent(content, section, isSectionCheckPlaceholderLine);
+    if (result.found && !result.hasContent) {
+      placeholderSections.push(section);
+    }
+  }
+
+  if (placeholderSections.length > 0) {
+    return {
+      ok: false,
+      reason: `Sections still contain only scaffold placeholder text: ${placeholderSections.join(', ')}. Replace placeholder content before this gate can pass.`,
+    };
+  }
+
   return { ok: true };
 }