agentxchain 2.80.0 → 2.82.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 |
 |---|---|
@@ -167,12 +170,41 @@ agentxchain step
 | `approve-completion` | Approve a pending human-gated run completion |
 | `validate` | Validate governed kickoff wiring, a staged turn, or both |
 | `template validate` | Prove the template registry, workflow-kit scaffold contract, and planning artifact completeness (`--json` exposes a `workflow_kit` block) |
+| `verify turn` | Replay a staged turn's declared machine-evidence commands to confirm reproducibility before acceptance |
+| `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

@@ -60,6 +60,7 @@ import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
 import { verifyExportCommand, verifyProtocolCommand, verifyTurnCommand } from '../src/commands/verify.js';
+import { replayTurnCommand } from '../src/commands/replay.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
 import { rebindCommand } from '../src/commands/rebind.js';
 import { branchCommand } from '../src/commands/branch.js';
@@ -130,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')
@@ -388,6 +389,17 @@ verifyCmd
   .option('--format <format>', 'Output format: text or json', 'text')
   .action(verifyExportCommand);
 
+const replayCmd = program
+  .command('replay')
+  .description('Replay accepted governed evidence against the current workspace');
+
+replayCmd
+  .command('turn [turn_id]')
+  .description('Replay an accepted turn\'s declared machine-evidence commands from history')
+  .option('-j, --json', 'Output as JSON')
+  .option('--timeout <ms>', 'Per-command replay timeout in milliseconds', '30000')
+  .action(replayTurnCommand);
+
 program
   .command('migrate')
   .description('Migrate a legacy v3 project to governed format')

package/package.json

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

package/src/commands/doctor.js

@@ -8,6 +8,7 @@ import { getWatchPid } from './watch.js';
 import { loadNormalizedConfig, detectConfigVersion } from '../lib/normalized-config.js';
 import { readDaemonState, evaluateDaemonStatus } from '../lib/run-schedule.js';
 import { getGovernedVersionSurface, formatGovernedVersionLabel } from '../lib/protocol-version.js';
+import { PLUGIN_MANIFEST_FILE } from '../lib/plugins.js';
 
 export async function doctorCommand(opts = {}) {
   const root = findProjectRoot(process.cwd());
@@ -74,6 +75,7 @@ function governedDoctor(root, rawConfig, opts) {
     const check = checkRuntimeReachable(rtId, rt);
     checks.push(check);
   }
+  const connectorProbe = getConnectorProbeRecommendation(runtimes);
 
   // 4. State directory
   const stateDir = join(root, '.agentxchain');
@@ -130,6 +132,90 @@ function governedDoctor(root, rawConfig, opts) {
     }
   }
 
+  // 8. Installed plugin health (only when plugins are installed)
+  const installedPlugins = rawConfig.plugins || {};
+  const pluginNames = Object.keys(installedPlugins);
+  if (pluginNames.length > 0) {
+    for (const pluginName of pluginNames) {
+      const meta = installedPlugins[pluginName];
+      const checkId = `plugin_${pluginName.replace(/[^a-z0-9_-]/gi, '_')}`;
+
+      // Check install path exists
+      if (!meta.install_path) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: 'No install_path recorded', plugin_name: pluginName });
+        continue;
+      }
+      const installAbsPath = join(root, meta.install_path);
+      if (!existsSync(installAbsPath)) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: `Install path missing: ${meta.install_path}`, plugin_name: pluginName });
+        continue;
+      }
+
+      // Check manifest exists and is valid
+      const manifestPath = join(installAbsPath, PLUGIN_MANIFEST_FILE);
+      if (!existsSync(manifestPath)) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: 'Manifest file missing', plugin_name: pluginName });
+        continue;
+      }
+      let manifest;
+      try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      } catch (err) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: `Manifest is corrupt JSON: ${err.message}`, plugin_name: pluginName });
+        continue;
+      }
+
+      // Check hook files exist
+      const hookErrors = [];
+      if (manifest.hooks && typeof manifest.hooks === 'object') {
+        for (const [hookName, hookDef] of Object.entries(manifest.hooks)) {
+          if (!hookDef) continue;
+          const commands = Array.isArray(hookDef) ? hookDef : (hookDef.command ? [hookDef] : []);
+          for (const cmd of commands) {
+            const cmdArgs = cmd.command || cmd;
+            if (Array.isArray(cmdArgs) && cmdArgs.length > 0) {
+              const firstArg = cmdArgs[0];
+              if (typeof firstArg === 'string' && (firstArg.startsWith('./') || firstArg.startsWith('../'))) {
+                const hookFilePath = join(installAbsPath, firstArg);
+                if (!existsSync(hookFilePath)) {
+                  hookErrors.push(`${hookName}: ${firstArg}`);
+                }
+              }
+            }
+          }
+        }
+      }
+      if (hookErrors.length > 0) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: `Missing hook files: ${hookErrors.join(', ')}`, plugin_name: pluginName });
+        continue;
+      }
+
+      // Check config env vars (warn only)
+      const envWarnings = [];
+      const pluginConfig = meta.config || {};
+      for (const [key, value] of Object.entries(pluginConfig)) {
+        if (typeof value === 'string' && value.startsWith('$')) {
+          const envVar = value.slice(1);
+          if (!process.env[envVar]) {
+            envWarnings.push(envVar);
+          }
+        }
+      }
+      // Also check webhook_env pattern from config
+      if (pluginConfig.webhook_env && !process.env[pluginConfig.webhook_env]) {
+        if (!envWarnings.includes(pluginConfig.webhook_env)) {
+          envWarnings.push(pluginConfig.webhook_env);
+        }
+      }
+
+      if (envWarnings.length > 0) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'warn', detail: `Env var(s) not set: ${envWarnings.join(', ')}`, plugin_name: pluginName });
+      } else {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'pass', detail: `v${manifest.version || '?'}, ${Object.keys(manifest.hooks || {}).length} hooks`, plugin_name: pluginName });
+      }
+    }
+  }
+
   // Compute summary
   const failCount = checks.filter(c => c.level === 'fail').length;
   const warnCount = checks.filter(c => c.level === 'warn').length;
@@ -143,6 +229,9 @@ function governedDoctor(root, rawConfig, opts) {
       ...versionSurface,
       config_version: versionSurface.config_generation,
       overall,
+      connector_probe_recommended: connectorProbe.recommended,
+      connector_probe_runtime_ids: connectorProbe.runtimeIds,
+      connector_probe_detail: connectorProbe.detail,
       checks,
       fail_count: failCount,
       warn_count: warnCount,
@@ -173,6 +262,9 @@ function governedDoctor(root, rawConfig, opts) {
     } else {
       console.log(chalk.red(`  Not ready: ${failCount} failure${failCount > 1 ? 's' : ''}, ${warnCount} warning${warnCount > 1 ? 's' : ''}.`));
     }
+    if (failCount === 0 && connectorProbe.recommended) {
+      console.log(chalk.dim(`  Next: ${connectorProbe.detail}`));
+    }
     console.log('');
   }
 
@@ -236,6 +328,35 @@ function checkRuntimeReachable(rtId, rt) {
   }
 }
 
+function getConnectorProbeRecommendation(runtimes) {
+  const runtimeIds = [];
+
+  for (const [rtId, rt] of Object.entries(runtimes || {})) {
+    if (!rt || typeof rt !== 'object') continue;
+    if (rt.type === 'api_proxy' || rt.type === 'remote_agent') {
+      runtimeIds.push(rtId);
+      continue;
+    }
+    if (rt.type === 'mcp' && (rt.transport || 'stdio') === 'streamable_http') {
+      runtimeIds.push(rtId);
+    }
+  }
+
+  if (runtimeIds.length === 0) {
+    return {
+      recommended: false,
+      runtimeIds: [],
+      detail: null,
+    };
+  }
+
+  return {
+    recommended: true,
+    runtimeIds,
+    detail: 'run `agentxchain connector check` to live-probe api / remote HTTP runtimes before the first governed turn.',
+  };
+}
+
 function getCurrentPhase(root) {
   const statePath = join(root, '.agentxchain', 'state.json');
   if (!existsSync(statePath)) return null;

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/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/replay.js

@@ -0,0 +1,120 @@
+import chalk from 'chalk';
+
+import { loadProjectContext } from '../lib/config.js';
+import { normalizeVerification } from '../lib/repo-observer.js';
+import { resolveAcceptedTurnHistoryReference } from '../lib/accepted-turn-history.js';
+import {
+  DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS,
+  replayVerificationMachineEvidence,
+} from '../lib/verification-replay.js';
+
+export async function replayTurnCommand(turnId, opts = {}) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(2);
+  }
+
+  if (context.config.protocol_mode !== 'governed' || context.version !== 4) {
+    console.log(chalk.red('replay turn is only available in governed v4 projects.'));
+    process.exit(2);
+  }
+
+  const timeoutMs = Number.parseInt(String(opts.timeout || String(DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS)), 10);
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    console.log(chalk.red('replay turn requires a positive integer --timeout in milliseconds.'));
+    process.exit(2);
+  }
+
+  const { root, config } = context;
+  const resolved = resolveAcceptedTurnHistoryReference(root, turnId);
+  if (!resolved.ok) {
+    console.log(chalk.red(resolved.error));
+    process.exit(2);
+  }
+
+  const entry = resolved.entry;
+  const runtimeType = config.runtimes?.[entry.runtime_id]?.type || 'unknown';
+  const payload = {
+    source: 'history',
+    match_kind: resolved.match_kind,
+    turn_id: entry.turn_id,
+    resolved_turn_id: resolved.resolved_ref,
+    run_id: entry.run_id || null,
+    role: entry.role || null,
+    phase: entry.phase || null,
+    runtime_id: entry.runtime_id || null,
+    runtime_type: runtimeType,
+    accepted_at: entry.accepted_at || null,
+    declared_status: entry.verification?.status || 'skipped',
+    normalized_status: normalizeVerification(entry.verification, runtimeType).status,
+    timeout_ms: timeoutMs,
+    prior_verification_replay: entry.verification_replay || null,
+    ...replayVerificationMachineEvidence({
+      root,
+      verification: entry.verification,
+      timeoutMs,
+    }),
+  };
+
+  emitReplayTurn(payload, opts.json);
+  process.exit(payload.overall === 'match' ? 0 : 1);
+}
+
+function emitReplayTurn(payload, jsonMode) {
+  if (jsonMode) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold(`  Replay Turn: ${chalk.cyan(payload.turn_id)}`));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Source:')}     accepted history (${payload.match_kind})`);
+  console.log(`  ${chalk.dim('Run:')}        ${payload.run_id || '—'}`);
+  console.log(`  ${chalk.dim('Role:')}       ${payload.role || '—'}`);
+  console.log(`  ${chalk.dim('Phase:')}      ${payload.phase || '—'}`);
+  console.log(`  ${chalk.dim('Runtime:')}    ${payload.runtime_id || '—'} (${payload.runtime_type})`);
+  console.log(`  ${chalk.dim('Accepted:')}   ${payload.accepted_at || '—'}`);
+  console.log(`  ${chalk.dim('Declared:')}   ${payload.declared_status}`);
+  console.log(`  ${chalk.dim('Normalized:')} ${payload.normalized_status}`);
+  if (payload.prior_verification_replay) {
+    const prior = payload.prior_verification_replay;
+    const verifiedAt = prior.verified_at ? ` at ${prior.verified_at}` : '';
+    console.log(`  ${chalk.dim('Prior replay:')} ${prior.overall} (${prior.matched_commands || 0}/${prior.replayed_commands || 0})${verifiedAt}`);
+  }
+  console.log(`  ${chalk.dim('Outcome:')}    ${formatOutcome(payload.overall)}`);
+
+  if (payload.reason) {
+    console.log(`  ${chalk.dim('Reason:')}     ${payload.reason}`);
+    console.log('');
+    return;
+  }
+
+  console.log('');
+  for (const command of payload.commands || []) {
+    const marker = command.matched ? chalk.green('match') : chalk.red('mismatch');
+    console.log(`  [${marker}] ${command.command}`);
+    console.log(`    declared=${command.declared_exit_code} actual=${command.actual_exit_code == null ? 'null' : command.actual_exit_code}`);
+    if (command.signal) {
+      console.log(`    signal=${command.signal}`);
+    }
+    if (command.timed_out) {
+      console.log('    timed_out=true');
+    }
+    if (command.error) {
+      console.log(`    error=${command.error}`);
+    }
+  }
+
+  console.log('');
+  console.log(chalk.dim('  Replay uses the current workspace and shell environment. It verifies declared exit-code reproducibility, not historical stdout/stderr identity.'));
+  console.log('');
+}
+
+function formatOutcome(outcome) {
+  if (outcome === 'match') return chalk.green('match');
+  if (outcome === 'mismatch') return chalk.red('mismatch');
+  return chalk.yellow('not_reproducible');
+}
+

package/src/commands/resume.js

@@ -36,7 +36,6 @@ 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';
 
@@ -100,6 +99,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
@@ -129,10 +133,12 @@ export async function resumeCommand(opts) {
       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);
@@ -236,11 +242,12 @@ 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}`));
   }
 
@@ -422,6 +429,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/step.js

@@ -60,7 +60,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 +164,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 +230,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 +271,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}`));
     }
 

package/src/lib/accepted-turn-history.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const HISTORY_PATH = '.agentxchain/history.jsonl';
+
+export function queryAcceptedTurnHistory(root) {
+  const filePath = join(root, HISTORY_PATH);
+  if (!existsSync(filePath)) return [];
+
+  let content;
+  try {
+    content = readFileSync(filePath, 'utf8').trim();
+  } catch {
+    return [];
+  }
+
+  if (!content) return [];
+
+  return content
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter((entry) => entry && typeof entry.turn_id === 'string')
+    .reverse();
+}
+
+export function resolveAcceptedTurnHistoryReference(root, ref) {
+  const entries = queryAcceptedTurnHistory(root);
+
+  if (entries.length === 0) {
+    return {
+      ok: false,
+      error: 'No accepted turn history found. Accept at least one governed turn first.',
+    };
+  }
+
+  if (!ref) {
+    return {
+      ok: true,
+      entry: entries[0],
+      resolved_ref: entries[0].turn_id,
+      match_kind: 'latest',
+    };
+  }
+
+  const exact = entries.find((entry) => entry.turn_id === ref);
+  if (exact) {
+    return {
+      ok: true,
+      entry: exact,
+      resolved_ref: exact.turn_id,
+      match_kind: 'exact',
+    };
+  }
+
+  const prefixMatches = entries.filter((entry) => entry.turn_id.startsWith(ref));
+  if (prefixMatches.length === 1) {
+    return {
+      ok: true,
+      entry: prefixMatches[0],
+      resolved_ref: prefixMatches[0].turn_id,
+      match_kind: 'prefix',
+    };
+  }
+
+  if (prefixMatches.length > 1) {
+    return {
+      ok: false,
+      error: `Turn reference "${ref}" is ambiguous. Matches: ${prefixMatches.map((entry) => entry.turn_id).join(', ')}`,
+    };
+  }
+
+  return {
+    ok: false,
+    error: `Accepted turn ${ref} not found in history.`,
+  };
+}
+

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
@@ -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

@@ -521,6 +521,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 +583,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 +597,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 +631,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 };
 }