agentxchain 2.14.0 → 2.16.0

package/src/commands/intake-handoff.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+import { handoffIntent } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
+
+export async function intakeHandoffCommand(opts) {
+  const root = requireIntakeWorkspaceOrExit(opts);
+
+  if (!opts.intent) {
+    const msg = '--intent <id> is required';
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(1);
+  }
+
+  if (!opts.coordinatorRoot) {
+    const msg = '--coordinator-root <path> is required';
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(1);
+  }
+
+  if (!opts.workstream) {
+    const msg = '--workstream <id> is required';
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(1);
+  }
+
+  const result = handoffIntent(root, opts.intent, {
+    coordinatorRoot: opts.coordinatorRoot,
+    workstreamId: opts.workstream,
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.ok) {
+    console.log('');
+    console.log(chalk.green(`  Handed off intent ${result.intent.intent_id}`));
+    console.log(`  Workstream: ${result.intent.target_workstream.workstream_id}`);
+    console.log(`  Super Run:  ${result.super_run_id}`);
+    console.log(`  Handoff:    ${result.handoff_path}`);
+    console.log(chalk.dim('  Status:     planned → executing (coordinator-managed)'));
+    console.log('');
+  } else {
+    console.log(chalk.red(`  ${result.error}`));
+  }
+
+  process.exit(result.exitCode);
+}

package/src/commands/intake-plan.js

@@ -1,18 +1,9 @@
 import chalk from 'chalk';
-import { findProjectRoot } from '../lib/config.js';
 import { planIntent } from '../lib/intake.js';
-import { basename } from 'node:path';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakePlanCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   if (!opts.intent) {
     const msg = '--intent <id> is required';

package/src/commands/intake-record.js

@@ -1,19 +1,11 @@
 import chalk from 'chalk';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { findProjectRoot } from '../lib/config.js';
 import { recordEvent } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeRecordCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   let payload;
   try {

package/src/commands/intake-resolve.js

@@ -1,17 +1,9 @@
 import chalk from 'chalk';
-import { findProjectRoot } from '../lib/config.js';
 import { resolveIntent } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeResolveCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   if (!opts.intent) {
     const msg = '--intent <id> is required';

package/src/commands/intake-scan.js

@@ -1,19 +1,11 @@
 import chalk from 'chalk';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { findProjectRoot } from '../lib/config.js';
 import { scanSource, SCAN_SOURCES } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeScanCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   if (!opts.source) {
     const msg = `--source is required. Supported scan sources: ${SCAN_SOURCES.join(', ')}`;

package/src/commands/intake-start.js

@@ -1,17 +1,9 @@
 import chalk from 'chalk';
-import { findProjectRoot } from '../lib/config.js';
 import { startIntent } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeStartCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   if (!opts.intent) {
     const msg = '--intent <id> is required';

package/src/commands/intake-status.js

@@ -1,17 +1,9 @@
 import chalk from 'chalk';
-import { findProjectRoot } from '../lib/config.js';
 import { intakeStatus } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeStatusCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   const result = intakeStatus(root, opts.intent || null);
 
@@ -72,6 +64,10 @@ function printIntentDetail(intent, event) {
   console.log(`  ${chalk.dim('Charter:')}   ${intent.charter || '—'}`);
   console.log(`  ${chalk.dim('Created:')}   ${intent.created_at}`);
   console.log(`  ${chalk.dim('Updated:')}   ${intent.updated_at}`);
+  if (intent.target_workstream) {
+    console.log(`  ${chalk.dim('Workstream:')} ${intent.target_workstream.workstream_id}`);
+    console.log(`  ${chalk.dim('Super Run:')}  ${intent.target_workstream.super_run_id}`);
+  }
 
   if (intent.acceptance_contract && intent.acceptance_contract.length > 0) {
     console.log('');

package/src/commands/intake-triage.js

@@ -1,17 +1,9 @@
 import chalk from 'chalk';
-import { findProjectRoot } from '../lib/config.js';
 import { triageIntent } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeTriageCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   if (!opts.intent) {
     const msg = '--intent <id> is required';

package/src/commands/intake-workspace.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, parse as pathParse, resolve } from 'node:path';
+import { findProjectRoot } from '../lib/config.js';
+import { COORDINATOR_CONFIG_FILE } from '../lib/coordinator-config.js';
+
+function findCoordinatorWorkspaceRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  const { root: fsRoot } = pathParse(dir);
+
+  while (true) {
+    if (existsSync(join(dir, COORDINATOR_CONFIG_FILE))) {
+      return dir;
+    }
+    if (dir === fsRoot) {
+      return null;
+    }
+    dir = join(dir, '..');
+  }
+}
+
+function listCoordinatorChildRepos(coordinatorRoot) {
+  const configPath = join(coordinatorRoot, COORDINATOR_CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    return [];
+  }
+
+  try {
+    const raw = JSON.parse(readFileSync(configPath, 'utf8'));
+    return Object.keys(raw?.repos || {});
+  } catch {
+    return [];
+  }
+}
+
+export function requireIntakeWorkspaceOrExit(opts, startDir = process.cwd()) {
+  const projectRoot = findProjectRoot(startDir);
+  if (projectRoot) {
+    return projectRoot;
+  }
+
+  const coordinatorRoot = findCoordinatorWorkspaceRoot(startDir);
+  const childRepos = coordinatorRoot ? listCoordinatorChildRepos(coordinatorRoot) : [];
+  const repoHint = childRepos.length > 0
+    ? ` Available child repos: ${childRepos.join(', ')}.`
+    : '';
+  const error = coordinatorRoot
+    ? `intake commands are repo-local only. Found coordinator workspace at ${coordinatorRoot} (${COORDINATOR_CONFIG_FILE}). Run intake inside a child governed repo (agentxchain.json).${repoHint} Then use \`agentxchain multi step\` for cross-repo coordination.`
+    : 'agentxchain.json not found';
+
+  if (opts.json) {
+    console.log(JSON.stringify({ ok: false, error }, null, 2));
+  } else {
+    console.log(chalk.red(error));
+  }
+
+  process.exit(2);
+}

package/src/commands/migrate.js

@@ -165,14 +165,15 @@ export async function migrateCommand(opts) {
     routing,
     gates: {
       planning_signoff: {
-        requires_files: ['.planning/PM_SIGNOFF.md', '.planning/ROADMAP.md'],
+        requires_files: ['.planning/PM_SIGNOFF.md', '.planning/ROADMAP.md', '.planning/SYSTEM_SPEC.md'],
         requires_human_approval: true
       },
       implementation_complete: {
+        requires_files: ['.planning/IMPLEMENTATION_NOTES.md'],
         requires_verification_pass: true
       },
       qa_ship_verdict: {
-        requires_files: ['.planning/acceptance-matrix.md', '.planning/ship-verdict.md'],
+        requires_files: ['.planning/acceptance-matrix.md', '.planning/ship-verdict.md', '.planning/RELEASE_NOTES.md'],
         requires_human_approval: true
       }
     },
@@ -311,8 +312,11 @@ ${report.requires_human_review.map((r, i) => `${i + 1}. ${r}`).join('\n')}
   const planningFiles = {
     'PM_SIGNOFF.md': `# PM Signoff — ${projectName}\n\nApproved: NO\n`,
     'ROADMAP.md': `# Roadmap — ${projectName}\n\n(Migrated from v3. Review and update.)\n`,
+    'SYSTEM_SPEC.md': `# System Spec — ${projectName}\n\n## Purpose\n\n(Describe the migrated subsystem purpose.)\n\n## Interface\n\n(List the commands, files, APIs, or contracts this repo owns.)\n\n## Behavior\n\n(Describe the expected runtime behavior.)\n\n## Error Cases\n\n(List the important failure modes.)\n\n## Acceptance Tests\n\n- [ ] Name the executable checks required before implementation resumes.\n\n## Open Questions\n\n- (Capture migration-specific gaps here.)\n`,
+    'IMPLEMENTATION_NOTES.md': `# Implementation Notes — ${projectName}\n\n## Changes\n\n(Dev fills this during implementation)\n\n## Verification\n\n(Dev fills this during implementation)\n\n## Unresolved Follow-ups\n\n(Dev lists any known gaps, tech debt, or follow-up items here.)\n`,
     'acceptance-matrix.md': `# Acceptance Matrix — ${projectName}\n\n(QA fills this.)\n`,
-    'ship-verdict.md': `# Ship Verdict — ${projectName}\n\n## Verdict: PENDING\n`
+    'ship-verdict.md': `# Ship Verdict — ${projectName}\n\n## Verdict: PENDING\n`,
+    'RELEASE_NOTES.md': `# Release Notes — ${projectName}\n\n## User Impact\n\n(QA fills this during the QA phase)\n\n## Verification Summary\n\n(QA fills this during the QA phase)\n\n## Upgrade Notes\n\n(QA fills this during the QA phase)\n\n## Known Issues\n\n(QA fills this during the QA phase)\n`
   };
   for (const [file, content] of Object.entries(planningFiles)) {
     const path = join(root, '.planning', file);

package/src/commands/multi.js

@@ -5,6 +5,7 @@
  *   multi init         — bootstrap a multi-repo coordinator run
  *   multi status       — show coordinator status and repo-run snapshots
  *   multi step         — reconcile repo truth, then dispatch or request the next coordinator gate
+ *   multi resume       — clear coordinator blocked state after operator recovery
  *   multi approve-gate — approve a pending phase transition or completion gate
  *   multi resync       — detect divergence and rebuild coordinator state from repo authority
  */
@@ -26,7 +27,11 @@ import {
   requestCoordinatorCompletion,
   requestPhaseTransition,
 } from '../lib/coordinator-gates.js';
-import { detectDivergence, resyncFromRepoAuthority } from '../lib/coordinator-recovery.js';
+import {
+  detectDivergence,
+  resyncFromRepoAuthority,
+  resumeCoordinatorFromBlockedState,
+} from '../lib/coordinator-recovery.js';
 import {
   fireCoordinatorHook,
   buildAssignmentPayload,
@@ -154,7 +159,7 @@ export async function multiStepCommand(options) {
     // Fire on_escalation hook (advisory — cannot block, only notifies)
     fireEscalationHook(workspacePath, configResult.config, state, state.blocked_reason || 'unknown reason');
     console.error(`Coordinator is blocked: ${state.blocked_reason || 'unknown reason'}`);
-    console.error('Resolve the blocked state before stepping.');
+    console.error('Resolve the blocked state, then run `agentxchain multi resume` before stepping again.');
     process.exitCode = 1;
     return;
   }
@@ -362,6 +367,57 @@ function maybeRequestCoordinatorGate(workspacePath, state, config) {
   return { ok: false, type: 'run_completion', blockers: completionEvaluation.blockers };
 }
 
+// ── multi resume ───────────────────────────────────────────────────────────
+
+export async function multiResumeCommand(options) {
+  const workspacePath = process.cwd();
+  const configResult = loadCoordinatorConfig(workspacePath);
+
+  if (!configResult.ok) {
+    console.error('Coordinator config error:');
+    for (const err of configResult.errors || []) {
+      console.error(`  - ${typeof err === 'string' ? err : err.message || JSON.stringify(err)}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const state = loadCoordinatorState(workspacePath);
+  if (!state) {
+    console.error('No coordinator state found. Run `agentxchain multi init` first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = resumeCoordinatorFromBlockedState(workspacePath, state, configResult.config);
+
+  if (!result.ok) {
+    console.error(result.error || 'Coordinator recovery failed.');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      ok: true,
+      previous_status: 'blocked',
+      resumed_status: result.resumed_status,
+      blocked_reason: result.blocked_reason,
+      pending_gate: result.state?.pending_gate || null,
+      resync: result.resync,
+    }, null, 2));
+    return;
+  }
+
+  console.log(`Coordinator resumed: ${result.resumed_status}`);
+  console.log(`Previous block: ${result.blocked_reason}`);
+  if (result.resumed_status === 'paused' && result.state?.pending_gate) {
+    console.log(`Next action: agentxchain multi approve-gate (${result.state.pending_gate.gate})`);
+  } else {
+    console.log('Next action: agentxchain multi step');
+  }
+}
+
 // ── multi approve-gate ─────────────────────────────────────────────────────
 
 export async function multiApproveGateCommand(options) {

package/src/commands/run.js

@@ -14,10 +14,12 @@
 
 import chalk from 'chalk';
 import { createInterface } from 'readline';
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { loadProjectContext, loadProjectState } from '../lib/config.js';
 import { runLoop } from '../lib/run-loop.js';
+import { buildRunExport } from '../lib/export.js';
+import { buildGovernanceReport, formatGovernanceReportMarkdown } from '../lib/report.js';
 import { dispatchApiProxy } from '../lib/adapters/api-proxy-adapter.js';
 import {
   dispatchLocalCli,
@@ -328,6 +330,32 @@ export async function runCommand(opts) {
     }
   }
 
+  // ── Auto governance report ──────────────────────────────────────────────
+  if (opts.report !== false && result.state) {
+    try {
+      const reportsDir = join(root, '.agentxchain', 'reports');
+      mkdirSync(reportsDir, { recursive: true });
+
+      const exportResult = buildRunExport(root);
+      if (exportResult.ok) {
+        const runId = result.state.run_id || 'unknown';
+        const exportPath = join(reportsDir, `export-${runId}.json`);
+        writeFileSync(exportPath, JSON.stringify(exportResult.export, null, 2));
+
+        const reportResult = buildGovernanceReport(exportResult.export, { input: exportPath });
+        const reportPath = join(reportsDir, `report-${runId}.md`);
+        writeFileSync(reportPath, formatGovernanceReportMarkdown(reportResult.report));
+
+        console.log('');
+        console.log(chalk.dim(`  Governance report: .agentxchain/reports/report-${runId}.md`));
+      } else {
+        console.log(chalk.dim(`  Governance report skipped: ${exportResult.error}`));
+      }
+    } catch (err) {
+      console.log(chalk.dim(`  Governance report failed: ${err.message}`));
+    }
+  }
+
   // ── Exit code ───────────────────────────────────────────────────────────
   const successReasons = new Set(['completed', 'gate_held', 'caller_stopped', 'max_turns_reached']);
   if (result.ok || successReasons.has(result.stop_reason)) {

package/src/commands/template-set.js

@@ -2,7 +2,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import chalk from 'chalk';
 import { CONFIG_FILE } from '../lib/config.js';
-import { loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS } from '../lib/governed-templates.js';
+import { loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS, SYSTEM_SPEC_OVERLAY_SEPARATOR } from '../lib/governed-templates.js';
 
 const LEDGER_PATH = '.agentxchain/decision-ledger.jsonl';
 const PROMPT_OVERRIDE_SEPARATOR = '## Project-Type-Specific Guidance';
@@ -76,6 +76,7 @@ export async function templateSetCommand(templateId, opts) {
     prompts_missing_paths: [],
     prompts_missing_files: [],
     acceptance_hints_status: 'none',
+    system_spec_overlay_status: 'none',
   };
 
   // Planning artifacts
@@ -127,6 +128,22 @@ export async function templateSetCommand(templateId, opts) {
     }
   }
 
+  // System spec overlay
+  const systemSpecOverlay = manifest.system_spec_overlay;
+  const systemSpecPath = join(root, '.planning', 'SYSTEM_SPEC.md');
+  if (systemSpecOverlay && Object.keys(systemSpecOverlay).length > 0) {
+    if (!existsSync(systemSpecPath)) {
+      plan.system_spec_overlay_status = 'missing_file';
+    } else {
+      const specContent = readFileSync(systemSpecPath, 'utf8');
+      if (specContent.includes(SYSTEM_SPEC_OVERLAY_SEPARATOR)) {
+        plan.system_spec_overlay_status = 'existing_guidance';
+      } else {
+        plan.system_spec_overlay_status = 'append';
+      }
+    }
+  }
+
   // ── Dry run: print plan and exit ──────────────────────────────────────
   if (opts.dryRun) {
     console.log(chalk.bold(`\n  Template: ${previousTemplate} → ${templateId}\n`));
@@ -175,6 +192,16 @@ export async function templateSetCommand(templateId, opts) {
     } else {
       console.log(`    ${chalk.dim('(none)')}`);
     }
+    console.log('\n  System spec overlay:');
+    if (plan.system_spec_overlay_status === 'append') {
+      console.log(`    .planning/SYSTEM_SPEC.md: ${chalk.green('WILL APPEND template guidance')}`);
+    } else if (plan.system_spec_overlay_status === 'existing_guidance') {
+      console.log(`    .planning/SYSTEM_SPEC.md: ${chalk.dim('ALREADY HAS guidance (skip)')}`);
+    } else if (plan.system_spec_overlay_status === 'missing_file') {
+      console.log(`    .planning/SYSTEM_SPEC.md: ${chalk.yellow('MISSING FILE (skip)')}`);
+    } else {
+      console.log(`    ${chalk.dim('(none)')}`);
+    }
     console.log(chalk.dim('\n  No changes written. Use without --dry-run to apply.\n'));
     process.exit(0);
   }
@@ -242,7 +269,24 @@ export async function templateSetCommand(templateId, opts) {
     console.log(chalk.yellow('  Warning: .planning/acceptance-matrix.md not found. Skipping template guidance hints.'));
   }
 
-  // 5. Decision ledger
+  // 5. Append system spec overlay
+  if (plan.system_spec_overlay_status === 'append' && existsSync(systemSpecPath)) {
+    const specContent = readFileSync(systemSpecPath, 'utf8');
+    const guidanceLines = [];
+    if (systemSpecOverlay.purpose_guidance) guidanceLines.push(`**Purpose:** ${systemSpecOverlay.purpose_guidance}`);
+    if (systemSpecOverlay.interface_guidance) guidanceLines.push(`**Interface:** ${systemSpecOverlay.interface_guidance}`);
+    if (systemSpecOverlay.behavior_guidance) guidanceLines.push(`**Behavior:** ${systemSpecOverlay.behavior_guidance}`);
+    if (systemSpecOverlay.error_cases_guidance) guidanceLines.push(`**Error Cases:** ${systemSpecOverlay.error_cases_guidance}`);
+    if (systemSpecOverlay.acceptance_tests_guidance) guidanceLines.push(`**Acceptance Tests:**\n${systemSpecOverlay.acceptance_tests_guidance}`);
+    if (systemSpecOverlay.extra_sections) guidanceLines.push(systemSpecOverlay.extra_sections);
+    const guidanceBlock = guidanceLines.join('\n\n');
+    const appended = `${specContent}\n\n${SYSTEM_SPEC_OVERLAY_SEPARATOR}\n\n${guidanceBlock}\n`;
+    writeFileSync(systemSpecPath, appended);
+  } else if (plan.system_spec_overlay_status === 'missing_file') {
+    console.log(chalk.yellow('  Warning: .planning/SYSTEM_SPEC.md not found. Skipping template spec overlay.'));
+  }
+
+  // 6. Decision ledger
   const ledgerEntry = {
     type: 'template_set',
     timestamp: new Date().toISOString(),
@@ -260,6 +304,8 @@ export async function templateSetCommand(templateId, opts) {
     prompt_missing_files: plan.prompts_missing_files,
     acceptance_hints_appended: plan.acceptance_hints_status === 'append',
     acceptance_hints_skipped_reason: plan.acceptance_hints_status === 'append' ? null : plan.acceptance_hints_status,
+    system_spec_overlay_appended: plan.system_spec_overlay_status === 'append',
+    system_spec_overlay_skipped_reason: plan.system_spec_overlay_status === 'append' ? null : plan.system_spec_overlay_status,
     operator: 'human',
   };
   appendJsonl(root, LEDGER_PATH, ledgerEntry);
@@ -275,5 +321,8 @@ export async function templateSetCommand(templateId, opts) {
   if (plan.acceptance_hints_status === 'append') {
     console.log(`  Appended template guidance to acceptance-matrix.md`);
   }
+  if (plan.system_spec_overlay_status === 'append') {
+    console.log(`  Appended template-specific guidance to SYSTEM_SPEC.md`);
+  }
   console.log('');
 }

package/src/lib/adapter-interface.js

@@ -0,0 +1,31 @@
+/**
+ * Adapter Interface — declared public boundary for shipped adapter dispatch.
+ *
+ * This module gives external runners a stable way to reuse the first-party
+ * adapters without importing deep internal source paths.
+ */
+
+export {
+  printManualDispatchInstructions,
+  waitForStagedResult,
+  readStagedResult,
+} from './adapters/manual-adapter.js';
+
+export {
+  dispatchLocalCli,
+  saveDispatchLogs,
+  resolvePromptTransport,
+} from './adapters/local-cli-adapter.js';
+
+export { dispatchApiProxy } from './adapters/api-proxy-adapter.js';
+
+export {
+  DEFAULT_MCP_TOOL_NAME,
+  DEFAULT_MCP_TRANSPORT,
+  dispatchMcp,
+  resolveMcpToolName,
+  resolveMcpTransport,
+  describeMcpRuntimeTarget,
+} from './adapters/mcp-adapter.js';
+
+export const ADAPTER_INTERFACE_VERSION = '0.1';