agentxchain 2.37.0 → 2.39.0

package/README.md

@@ -9,7 +9,9 @@ Legacy IDE-window coordination is still shipped as a compatibility mode for team
 ## Docs
 
 - [Quickstart](https://agentxchain.dev/docs/quickstart/)
+- [Getting Started](https://agentxchain.dev/docs/getting-started/)
 - [CLI reference](https://agentxchain.dev/docs/cli/)
+- [Templates](https://agentxchain.dev/docs/templates/)
 - [Export schema reference](https://agentxchain.dev/docs/export-schema/)
 - [Adapter reference](https://agentxchain.dev/docs/adapters/)
 - [Protocol spec (v6)](https://agentxchain.dev/docs/protocol/)
@@ -90,6 +92,15 @@ Built-in governed templates:
 - `web-app`: user flows, UI acceptance, browser support
 - `enterprise-app`: enterprise planning artifacts plus blueprint-backed `architect` and `security_reviewer` phases
 
+Inspect the shipped template surfaces instead of inferring them from docs:
+
+```bash
+agentxchain template list
+agentxchain template list --phase-templates
+```
+
+`template list` enumerates governed project templates. `template list --phase-templates` enumerates the reusable workflow-kit phase-template bundles you can reference from `workflow_kit.phases.<phase>.template`.
+
 `step` writes a turn-scoped bundle under `.agentxchain/dispatch/turns/<turn_id>/` and expects a staged result at `.agentxchain/staging/<turn_id>/turn-result.json`. Typical continuation:
 
 ```bash

package/bin/agentxchain.js

@@ -411,6 +411,7 @@ templateCmd
   .command('list')
   .description('List available governed templates')
   .option('-j, --json', 'Output as JSON')
+  .option('--phase-templates', 'List workflow-kit phase templates instead of governed project templates')
   .action(templateListCommand);
 
 templateCmd

package/dashboard/components/timeline.js

@@ -154,8 +154,19 @@ function renderContinuityPanel(continuity) {
     html += `<div class="turn-detail"><span class="detail-label">Checkpoint:</span> No session checkpoint recorded</div>`;
   }
 
-  if (continuity.restart_recommended) {
-    html += `<div class="turn-detail"><span class="detail-label">Restart:</span> <span class="mono">agentxchain restart</span></div>`;
+  if (continuity.drift_detected === true && Array.isArray(continuity.drift_warnings) && continuity.drift_warnings.length > 0) {
+    html += `<div class="turn-detail risks"><span class="detail-label">Drift:</span><ul>`;
+    for (const warning of continuity.drift_warnings) {
+      html += `<li>${esc(warning)}</li>`;
+    }
+    html += `</ul></div>`;
+  } else if (continuity.drift_detected === false) {
+    html += `<div class="turn-detail"><span class="detail-label">Drift:</span> none detected since checkpoint</div>`;
+  }
+
+  if (continuity.recommended_command) {
+    const detail = continuity.recommended_detail ? ` (${continuity.recommended_detail})` : '';
+    html += `<div class="turn-detail"><span class="detail-label">Action:</span> <span class="mono">${esc(continuity.recommended_command)}</span>${esc(detail)}</div>`;
   }
 
   if (continuity.recovery_report_path) {

package/package.json

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

package/src/commands/init.js

@@ -6,7 +6,7 @@ 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 { VALID_PROMPT_TRANSPORTS } from '../lib/normalized-config.js';
+import { normalizeWorkflowKit, VALID_PROMPT_TRANSPORTS } from '../lib/normalized-config.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '../templates');
@@ -628,6 +628,9 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
   const { runtime: localDevRuntime } = resolveGovernedLocalDevRuntime(runtimeOptions);
   const scaffoldConfig = buildScaffoldConfigFromTemplate(template, localDevRuntime, workflowKitConfig);
   const { roles, runtimes, routing, gates, prompts, workflowKitConfig: effectiveWorkflowKitConfig } = scaffoldConfig;
+  const scaffoldWorkflowKitConfig = effectiveWorkflowKitConfig
+    ? normalizeWorkflowKit(effectiveWorkflowKitConfig, Object.keys(routing))
+    : null;
   const initialPhase = Object.keys(routing)[0] || 'planning';
   const phaseGateStatus = Object.fromEntries(
     [...new Set(
@@ -709,7 +712,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
     const basePrompt = buildGovernedPrompt(roleId, role, {
       routing,
       gates,
-      workflowKitConfig: effectiveWorkflowKitConfig,
+      workflowKitConfig: scaffoldWorkflowKitConfig,
     });
     const prompt = appendPromptOverride(basePrompt, template.prompt_overrides?.[roleId]);
     writeFileSync(join(dir, '.agentxchain', 'prompts', `${roleId}.md`), prompt);
@@ -736,7 +739,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
 
   // Workflow-kit custom artifacts — only scaffold files from explicit workflow_kit config
   // that are not already handled by the default scaffold above
-  if (effectiveWorkflowKitConfig && effectiveWorkflowKitConfig.phases && typeof effectiveWorkflowKitConfig.phases === 'object') {
+  if (scaffoldWorkflowKitConfig && scaffoldWorkflowKitConfig.phases && typeof scaffoldWorkflowKitConfig.phases === 'object') {
     const defaultScaffoldPaths = new Set([
       '.planning/PM_SIGNOFF.md',
       '.planning/ROADMAP.md',
@@ -747,7 +750,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
       '.planning/RELEASE_NOTES.md',
     ]);
 
-    for (const phaseConfig of Object.values(effectiveWorkflowKitConfig.phases)) {
+    for (const phaseConfig of Object.values(scaffoldWorkflowKitConfig.phases)) {
       if (!Array.isArray(phaseConfig.artifacts)) continue;
       for (const artifact of phaseConfig.artifacts) {
         if (!artifact.path || defaultScaffoldPaths.has(artifact.path)) continue;
@@ -782,7 +785,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
     }
   }
 
-  return { config, state };
+  return { config, state, scaffoldWorkflowKitConfig };
 }
 
 async function initGoverned(opts) {
@@ -882,7 +885,7 @@ async function initGoverned(opts) {
     }
   }
 
-  const { config } = scaffoldGoverned(dir, projectName, projectId, templateId, opts, workflowKitConfig);
+  const { config, scaffoldWorkflowKitConfig } = scaffoldGoverned(dir, projectName, projectId, templateId, opts, workflowKitConfig);
 
   console.log('');
   console.log(chalk.green(`  ✓ Created governed project ${chalk.bold(targetLabel)}/`));
@@ -897,7 +900,7 @@ async function initGoverned(opts) {
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} reviews/`);
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('└──')} dispatch/`);
   console.log(`    ${chalk.dim('├──')} .planning/`);
-  const planningSummaryLines = buildPlanningSummaryLines(selectedTemplate, config.workflow_kit);
+  const planningSummaryLines = buildPlanningSummaryLines(selectedTemplate, scaffoldWorkflowKitConfig);
   for (const [index, line] of planningSummaryLines.entries()) {
     const branch = index === planningSummaryLines.length - 1 ? '└──' : '├──';
     console.log(`    ${chalk.dim('│')}    ${chalk.dim(branch)} ${line}`);

package/src/commands/restart.js

@@ -23,13 +23,13 @@ import {
   HISTORY_PATH,
   LEDGER_PATH,
 } from '../lib/governed-state.js';
-import { readSessionCheckpoint, SESSION_PATH } from '../lib/session-checkpoint.js';
+import { readSessionCheckpoint, writeSessionCheckpoint, captureBaselineRef, SESSION_PATH } from '../lib/session-checkpoint.js';
 
 /**
  * Generate a session recovery report summarizing the run state
  * so a new agent session can orient quickly.
  */
-function generateRecoveryReport(root, state, checkpoint) {
+function generateRecoveryReport(root, state, checkpoint, driftWarnings = []) {
   const lines = [
     '# Session Recovery Report',
     '',
@@ -102,7 +102,50 @@ function generateRecoveryReport(root, state, checkpoint) {
     }
   }
 
-  lines.push('## Next Steps', '', 'The next turn has been assigned. Check the dispatch bundle for context.', '');
+  // Pending gate / run completion surfacing
+  if (state.pending_phase_transition) {
+    const pt = state.pending_phase_transition;
+    lines.push(
+      '## Pending Phase Transition',
+      '',
+      `- **From**: ${pt.from}`,
+      `- **To**: ${pt.to}`,
+      `- **Gate**: ${pt.gate}`,
+      `- **Requested by**: ${pt.requested_by_turn || 'unknown'}`,
+      `- **Action**: Run \`agentxchain approve-transition\` to approve`,
+      '',
+    );
+  }
+
+  if (state.pending_run_completion) {
+    const pc = state.pending_run_completion;
+    lines.push(
+      '## Pending Run Completion',
+      '',
+      `- **Gate**: ${pc.gate}`,
+      `- **Requested by**: ${pc.requested_by_turn || 'unknown'}`,
+      `- **Action**: Run \`agentxchain approve-completion\` to approve`,
+      '',
+    );
+  }
+
+  // Repo-drift warnings
+  if (checkpoint?.baseline_ref && driftWarnings?.length > 0) {
+    lines.push('## Continuity Warnings', '');
+    for (const warning of driftWarnings) {
+      lines.push(`- ⚠ ${warning}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## Next Steps', '');
+  if (state.pending_phase_transition) {
+    lines.push('A phase transition is pending approval. Run `agentxchain approve-transition` before assigning new turns.', '');
+  } else if (state.pending_run_completion) {
+    lines.push('A run completion is pending approval. Run `agentxchain approve-completion` to finalize.', '');
+  } else {
+    lines.push('The next turn has been assigned. Check the dispatch bundle for context.', '');
+  }
 
   return lines.join('\n');
 }
@@ -160,6 +203,42 @@ export async function restartCommand(opts) {
     process.exit(1);
   }
 
+  // ── Repo-drift detection ────────────────────────────────────────────────
+  const driftWarnings = [];
+  if (checkpoint?.baseline_ref) {
+    const currentBaseline = captureBaselineRef(root);
+    const prev = checkpoint.baseline_ref;
+
+    if (prev.git_head && currentBaseline.git_head && prev.git_head !== currentBaseline.git_head) {
+      driftWarnings.push(`Git HEAD has moved since checkpoint: ${prev.git_head.slice(0, 8)} → ${currentBaseline.git_head.slice(0, 8)}`);
+    }
+    if (prev.git_branch && currentBaseline.git_branch && prev.git_branch !== currentBaseline.git_branch) {
+      driftWarnings.push(`Branch changed since checkpoint: ${prev.git_branch} → ${currentBaseline.git_branch}`);
+    }
+    if (prev.workspace_dirty === false && currentBaseline.workspace_dirty === true) {
+      driftWarnings.push('Workspace was clean at checkpoint but is now dirty');
+    }
+  }
+
+  if (driftWarnings.length > 0) {
+    for (const warning of driftWarnings) {
+      console.log(chalk.yellow(`⚠ ${warning}`));
+    }
+  }
+
+  // ── Pending gate / completion check ────────────────────────────────────
+  if (state.pending_phase_transition) {
+    const pt = state.pending_phase_transition;
+    console.log(chalk.yellow(`Pending phase transition: ${pt.from} → ${pt.to} (gate: ${pt.gate})`));
+    console.log(chalk.dim('Run `agentxchain approve-transition` to approve before assigning new turns.'));
+  }
+
+  if (state.pending_run_completion) {
+    const pc = state.pending_run_completion;
+    console.log(chalk.yellow(`Pending run completion (gate: ${pc.gate})`));
+    console.log(chalk.dim('Run `agentxchain approve-completion` to finalize.'));
+  }
+
   // Handle abandoned active turns (assigned but never completed)
   const activeTurns = getActiveTurns(state);
   const activeTurnCount = getActiveTurnCount(state);
@@ -167,9 +246,29 @@ export async function restartCommand(opts) {
     const turnIds = Object.keys(activeTurns);
     console.log(chalk.yellow(`Warning: ${activeTurnCount} turn(s) were assigned but never completed: ${turnIds.join(', ')}`));
     console.log(chalk.dim('These turns will be available for the next agent to complete.'));
+
+    // Fail closed if retained turn + irreconcilable drift
+    if (driftWarnings.length > 0) {
+      console.log(chalk.yellow('Active turns exist with repo drift since checkpoint. Reconnecting with warnings.'));
+      console.log(chalk.dim('Inspect the drift before continuing work on the retained turns.'));
+    }
   }
 
-  // If paused, reactivate
+  // If pending gate/completion, do not bypass — surface and exit with recovery
+  if (state.pending_phase_transition || state.pending_run_completion) {
+    // Write checkpoint for the reconnect
+    writeSessionCheckpoint(root, state, 'restart_reconnect');
+
+    const recoveryReport = generateRecoveryReport(root, state, checkpoint, driftWarnings);
+    const recoveryPath = join(root, '.agentxchain/SESSION_RECOVERY.md');
+    const recoveryDir = dirname(recoveryPath);
+    if (!existsSync(recoveryDir)) mkdirSync(recoveryDir, { recursive: true });
+    writeFileSync(recoveryPath, recoveryReport);
+    console.log(chalk.dim(`  Recovery report: .agentxchain/SESSION_RECOVERY.md`));
+    return;
+  }
+
+  // If paused or idle without a pending approval gate, reactivate.
   if (state.status === 'paused' || state.status === 'idle') {
     const reactivated = reactivateGovernedRun(root, state, {
       reason: 'session_restart',
@@ -198,6 +297,8 @@ export async function restartCommand(opts) {
       process.exit(1);
     }
 
+    // assignGovernedTurn already writes a checkpoint at turn_assigned
+
     console.log(chalk.green(`✓ Restarted run ${state.run_id}`));
     console.log(chalk.dim(`  Phase: ${phase}`));
     console.log(chalk.dim(`  Turn: ${assignment.turn?.id || 'assigned'}`));
@@ -206,6 +307,9 @@ export async function restartCommand(opts) {
       console.log(chalk.dim(`  Last checkpoint: ${checkpoint.checkpoint_reason} at ${checkpoint.last_checkpoint_at}`));
     }
   } else {
+    // Reconnect to existing active turns — write checkpoint
+    writeSessionCheckpoint(root, state, 'restart_reconnect');
+
     console.log(chalk.green(`✓ Reconnected to run ${state.run_id}`));
     console.log(chalk.dim(`  Phase: ${phase}`));
     console.log(chalk.dim(`  Active turns: ${Object.keys(activeTurns).join(', ')}`));
@@ -213,7 +317,7 @@ export async function restartCommand(opts) {
   }
 
   // Write session recovery report
-  const recoveryReport = generateRecoveryReport(root, state, checkpoint);
+  const recoveryReport = generateRecoveryReport(root, state, checkpoint, driftWarnings);
   const recoveryPath = join(root, '.agentxchain/SESSION_RECOVERY.md');
   const recoveryDir = dirname(recoveryPath);
   if (!existsSync(recoveryDir)) mkdirSync(recoveryDir, { recursive: true });

package/src/commands/status.js

@@ -268,8 +268,21 @@ function renderContinuityStatus(continuity, state) {
     console.log(`  ${chalk.dim('Checkpoint:')} ${chalk.yellow('No session checkpoint recorded')}`);
   }
 
-  if (continuity.restart_recommended) {
-    console.log(`  ${chalk.dim('Restart:')} ${chalk.cyan('agentxchain restart')} (rebuild session context from disk)`);
+  if (continuity.drift_detected === true) {
+    const [firstWarning, ...remainingWarnings] = continuity.drift_warnings || [];
+    if (firstWarning) {
+      console.log(`  ${chalk.dim('Drift:')}    ${chalk.yellow(firstWarning)}`);
+    }
+    for (const warning of remainingWarnings) {
+      console.log(`  ${chalk.dim('         ')} ${chalk.yellow(warning)}`);
+    }
+  } else if (continuity.drift_detected === false) {
+    console.log(`  ${chalk.dim('Drift:')}    ${chalk.green('none detected since checkpoint')}`);
+  }
+
+  if (continuity.recommended_command) {
+    const detail = continuity.recommended_detail ? ` (${continuity.recommended_detail})` : '';
+    console.log(`  ${chalk.dim('Action:')}   ${chalk.cyan(continuity.recommended_command)}${chalk.dim(detail)}`);
   }
 
   if (continuity.recovery_report_path) {

package/src/commands/template-list.js

@@ -1,7 +1,12 @@
 import chalk from 'chalk';
 import { loadAllGovernedTemplates, VALID_GOVERNED_TEMPLATE_IDS } from '../lib/governed-templates.js';
+import { listWorkflowKitPhaseTemplates } from '../lib/workflow-kit-phase-templates.js';
 
 export function templateListCommand(opts) {
+  if (opts.phaseTemplates) {
+    return listPhaseTemplates(opts);
+  }
+
   if (opts.json) {
     const templates = loadAllGovernedTemplates();
     const output = templates.map((t) => ({
@@ -34,4 +39,40 @@ export function templateListCommand(opts) {
     console.log('');
   }
   console.log(chalk.dim(`  Usage: agentxchain template set <id>\n`));
+  console.log(chalk.dim(`  Tip: use --phase-templates to list workflow-kit phase templates.\n`));
+}
+
+function listPhaseTemplates(opts) {
+  const templates = listWorkflowKitPhaseTemplates();
+
+  if (opts.json) {
+    const output = templates.map((t) => ({
+      id: t.id,
+      description: t.description,
+      artifacts: t.artifacts.map((a) => ({
+        path: a.path,
+        semantics: a.semantics || null,
+        semantics_config: a.semantics_config || null,
+        required: a.required,
+      })),
+    }));
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold('\n  Workflow-kit phase templates:\n'));
+  for (const t of templates) {
+    console.log(`  ${chalk.cyan(t.id)} — ${t.description}`);
+    for (const a of t.artifacts) {
+      const req = a.required ? chalk.green('required') : chalk.dim('optional');
+      const sem = a.semantics ? chalk.yellow(a.semantics) : chalk.dim('none');
+      console.log(`    ${a.path}  [${req}] [semantics: ${sem}]`);
+      if (a.semantics === 'section_check' && a.semantics_config?.required_sections) {
+        console.log(`      sections: ${a.semantics_config.required_sections.join(', ')}`);
+      }
+    }
+    console.log('');
+  }
+  console.log(chalk.dim('  Usage in agentxchain.json:'));
+  console.log(chalk.dim('    "workflow_kit": { "phases": { "<phase>": { "template": "<id>" } } }\n'));
 }

package/src/lib/continuity-status.js

@@ -1,9 +1,111 @@
 import { existsSync } from 'fs';
 import { join } from 'path';
-import { readSessionCheckpoint } from './session-checkpoint.js';
+import { captureBaselineRef, readSessionCheckpoint } from './session-checkpoint.js';
 
 export const SESSION_RECOVERY_PATH = '.agentxchain/SESSION_RECOVERY.md';
 
+function deriveRecommendedContinuityAction(state) {
+  if (!state) {
+    return {
+      recommended_command: null,
+      recommended_reason: 'no_state',
+      recommended_detail: null,
+      restart_recommended: false,
+    };
+  }
+
+  if (state.pending_phase_transition) {
+    const pt = state.pending_phase_transition;
+    return {
+      recommended_command: 'agentxchain approve-transition',
+      recommended_reason: 'pending_phase_transition',
+      recommended_detail: `${pt.from || 'unknown'} -> ${pt.to || 'unknown'} (gate: ${pt.gate || 'unknown'})`,
+      restart_recommended: false,
+    };
+  }
+
+  if (state.pending_run_completion) {
+    const pc = state.pending_run_completion;
+    return {
+      recommended_command: 'agentxchain approve-completion',
+      recommended_reason: 'pending_run_completion',
+      recommended_detail: pc.gate ? `gate: ${pc.gate}` : null,
+      restart_recommended: false,
+    };
+  }
+
+  if (!['blocked', 'completed', 'failed'].includes(state.status)) {
+    return {
+      recommended_command: 'agentxchain restart',
+      recommended_reason: 'restart_available',
+      recommended_detail: 'rebuild session context from disk',
+      restart_recommended: true,
+    };
+  }
+
+  return {
+    recommended_command: null,
+    recommended_reason: state.status === 'blocked' ? 'blocked' : 'terminal_state',
+    recommended_detail: null,
+    restart_recommended: false,
+  };
+}
+
+function deriveCheckpointDrift(root, checkpoint, staleCheckpoint) {
+  if (!checkpoint?.baseline_ref || staleCheckpoint) {
+    return {
+      drift_detected: null,
+      drift_warnings: [],
+    };
+  }
+
+  const currentBaseline = captureBaselineRef(root);
+  const previousBaseline = checkpoint.baseline_ref;
+
+  if (
+    currentBaseline.git_head == null
+    && currentBaseline.git_branch == null
+    && currentBaseline.workspace_dirty == null
+  ) {
+    return {
+      drift_detected: null,
+      drift_warnings: [],
+    };
+  }
+
+  const driftWarnings = [];
+
+  if (
+    previousBaseline.git_head
+    && currentBaseline.git_head
+    && previousBaseline.git_head !== currentBaseline.git_head
+  ) {
+    driftWarnings.push(
+      `Git HEAD has moved since checkpoint: ${previousBaseline.git_head.slice(0, 8)} -> ${currentBaseline.git_head.slice(0, 8)}`
+    );
+  }
+
+  if (
+    previousBaseline.git_branch
+    && currentBaseline.git_branch
+    && previousBaseline.git_branch !== currentBaseline.git_branch
+  ) {
+    driftWarnings.push(`Branch changed since checkpoint: ${previousBaseline.git_branch} -> ${currentBaseline.git_branch}`);
+  }
+
+  if (
+    previousBaseline.workspace_dirty === false
+    && currentBaseline.workspace_dirty === true
+  ) {
+    driftWarnings.push('Workspace was clean at checkpoint but is now dirty');
+  }
+
+  return {
+    drift_detected: driftWarnings.length > 0,
+    drift_warnings: driftWarnings,
+  };
+}
+
 export function getContinuityStatus(root, state) {
   const checkpoint = readSessionCheckpoint(root);
   const recoveryReportPath = existsSync(join(root, SESSION_RECOVERY_PATH))
@@ -18,10 +120,18 @@ export function getContinuityStatus(root, state) {
     && checkpoint.run_id !== state.run_id
   );
 
+  const action = deriveRecommendedContinuityAction(state);
+  const drift = deriveCheckpointDrift(root, checkpoint, staleCheckpoint);
+
   return {
     checkpoint,
     stale_checkpoint: staleCheckpoint,
     recovery_report_path: recoveryReportPath,
-    restart_recommended: !!state && !['blocked', 'completed', 'failed'].includes(state.status),
+    restart_recommended: action.restart_recommended,
+    recommended_command: action.recommended_command,
+    recommended_reason: action.recommended_reason,
+    recommended_detail: action.recommended_detail,
+    drift_detected: drift.drift_detected,
+    drift_warnings: drift.drift_warnings,
   };
 }

package/src/lib/governed-state.js

@@ -1352,6 +1352,11 @@ export function markRunBlocked(root, details) {
 
   writeState(root, updatedState);
 
+  // Session checkpoint — non-fatal, written after blocked state is persisted
+  writeSessionCheckpoint(root, updatedState, 'blocked', {
+    role: turnId ? (getActiveTurns(updatedState)[turnId]?.assigned_role || null) : null,
+  });
+
   emitBlockedNotification(root, details.notificationConfig, updatedState, {
     category: details.category,
     blockedOn: details.blockedOn,
@@ -1753,6 +1758,13 @@ export function assignGovernedTurn(root, config, roleId) {
   };
 
   writeState(root, updatedState);
+
+  // Session checkpoint — non-fatal, written after every successful turn assignment
+  writeSessionCheckpoint(root, updatedState, 'turn_assigned', {
+    role: roleId,
+    dispatch_dir: `.agentxchain/dispatch/turns/${turnId}`,
+  });
+
   const assignedTurn = updatedState.active_turns[turnId];
   const result = { ok: true, state: attachLegacyCurrentTurnAlias(updatedState), turn: assignedTurn };
   if (warnings.length > 0) {

package/src/lib/normalized-config.js

@@ -15,6 +15,12 @@
 import { validateHooksConfig } from './hook-runner.js';
 import { validateNotificationsConfig } from './notification-runner.js';
 import { SUPPORTED_TOKEN_COUNTER_PROVIDERS } from './token-counter.js';
+import {
+  buildDefaultWorkflowKitArtifactsForPhase,
+  expandWorkflowKitPhaseArtifacts,
+  isWorkflowKitPhaseTemplateId,
+  VALID_WORKFLOW_KIT_PHASE_TEMPLATE_IDS,
+} from './workflow-kit-phase-templates.js';
 
 const VALID_WRITE_AUTHORITIES = ['authoritative', 'proposed', 'review_only'];
 const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy', 'mcp', 'remote_agent'];
@@ -26,25 +32,6 @@ export { DEFAULT_PHASES };
 const VALID_PHASE_NAME = /^[a-z][a-z0-9_-]*$/;
 const VALID_SEMANTIC_IDS = ['pm_signoff', 'system_spec', 'implementation_notes', 'acceptance_matrix', 'ship_verdict', 'release_notes', 'section_check'];
 
-/**
- * Default artifact map for phases when workflow_kit is absent from config.
- * Only phases present in this map get default artifacts.
- */
-const DEFAULT_PHASE_ARTIFACTS = {
-  planning: [
-    { path: '.planning/PM_SIGNOFF.md', semantics: 'pm_signoff', required: true },
-    { path: '.planning/SYSTEM_SPEC.md', semantics: 'system_spec', required: true },
-    { path: '.planning/ROADMAP.md', semantics: null, required: true },
-  ],
-  implementation: [
-    { path: '.planning/IMPLEMENTATION_NOTES.md', semantics: 'implementation_notes', required: true },
-  ],
-  qa: [
-    { path: '.planning/acceptance-matrix.md', semantics: 'acceptance_matrix', required: true },
-    { path: '.planning/ship-verdict.md', semantics: 'ship_verdict', required: true },
-    { path: '.planning/RELEASE_NOTES.md', semantics: 'release_notes', required: true },
-  ],
-};
 const VALID_API_PROXY_RETRY_JITTER = ['none', 'full'];
 const VALID_API_PROXY_RETRY_CLASSES = [
   'rate_limited',
@@ -566,14 +553,35 @@ export function validateWorkflowKitConfig(wk, routing, roles) {
         continue;
       }
 
-      if (!Array.isArray(phaseConfig.artifacts)) {
+      let templateValid = true;
+      if (phaseConfig.template !== undefined) {
+        if (typeof phaseConfig.template !== 'string' || !phaseConfig.template.trim()) {
+          errors.push(`workflow_kit.phases.${phase}.template must be a non-empty string`);
+          templateValid = false;
+        } else if (!isWorkflowKitPhaseTemplateId(phaseConfig.template)) {
+          errors.push(
+            `workflow_kit.phases.${phase}.template "${phaseConfig.template}" is unknown; valid values: ${VALID_WORKFLOW_KIT_PHASE_TEMPLATE_IDS.join(', ')}`,
+          );
+          templateValid = false;
+        }
+      }
+
+      if (phaseConfig.artifacts !== undefined && !Array.isArray(phaseConfig.artifacts)) {
         errors.push(`workflow_kit.phases.${phase}.artifacts must be an array`);
         continue;
       }
 
+      if (phaseConfig.template === undefined && phaseConfig.artifacts === undefined) {
+        errors.push(`workflow_kit.phases.${phase} must declare template, artifacts, or both`);
+        continue;
+      }
+
       const seenPaths = new Set();
-      for (let i = 0; i < phaseConfig.artifacts.length; i++) {
-        const artifact = phaseConfig.artifacts[i];
+      const expandedArtifacts = templateValid
+        ? expandWorkflowKitPhaseArtifacts(phaseConfig)
+        : Array.isArray(phaseConfig.artifacts) ? phaseConfig.artifacts : [];
+      for (let i = 0; i < expandedArtifacts.length; i++) {
+        const artifact = expandedArtifacts[i];
         const prefix = `workflow_kit.phases.${phase}.artifacts[${i}]`;
 
         if (!artifact || typeof artifact !== 'object') {
@@ -845,7 +853,7 @@ export function getMaxConcurrentTurns(config, phase) {
 
 /**
  * Normalize workflow_kit config.
- * When absent, builds defaults from routing phases using DEFAULT_PHASE_ARTIFACTS.
+ * When absent, builds defaults from routing phases using the built-in phase templates.
  * When present, normalizes artifact entries.
  */
 export function normalizeWorkflowKit(raw, routingPhases) {
@@ -862,7 +870,7 @@ export function normalizeWorkflowKit(raw, routingPhases) {
   if (raw.phases) {
     for (const [phase, phaseConfig] of Object.entries(raw.phases)) {
       phases[phase] = {
-        artifacts: (phaseConfig.artifacts || []).map(a => ({
+        artifacts: expandWorkflowKitPhaseArtifacts(phaseConfig).map(a => ({
           path: a.path,
           semantics: a.semantics || null,
           semantics_config: a.semantics_config || null,
@@ -879,9 +887,10 @@ export function normalizeWorkflowKit(raw, routingPhases) {
 function buildDefaultWorkflowKit(routingPhases) {
   const phases = {};
   for (const phase of routingPhases) {
-    if (DEFAULT_PHASE_ARTIFACTS[phase]) {
+    const templateArtifacts = buildDefaultWorkflowKitArtifactsForPhase(phase);
+    if (templateArtifacts) {
       phases[phase] = {
-        artifacts: DEFAULT_PHASE_ARTIFACTS[phase].map(a => ({ ...a, semantics_config: null })),
+        artifacts: templateArtifacts.map(a => ({ ...a, semantics_config: a.semantics_config || null })),
       };
     }
   }

package/src/lib/session-checkpoint.js

@@ -2,9 +2,10 @@
  * Session checkpoint — automatic state markers for cross-session restart.
  *
  * Writes .agentxchain/session.json at every governance boundary
- * (turn acceptance, phase transition, gate approval, run completion)
- * so that `agentxchain restart` can reconstruct dispatch context
- * without any in-memory session state.
+ * (turn assignment, acceptance, phase transition, blocked state,
+ * gate approval, run completion, restart/reconnect) so that
+ * `agentxchain restart` can reconstruct dispatch context without
+ * any in-memory session state.
  *
  * Design rules:
  *   - Checkpoint writes are non-fatal: failures log a warning and do not
@@ -12,11 +13,13 @@
  *   - The file is always overwritten, not appended.
  *   - run_id in session.json must agree with state.json; mismatch is a
  *     corruption signal.
+ *   - state.json is always authoritative; session.json is recovery metadata.
  */
 
 import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { randomBytes } from 'crypto';
+import { execSync as shellExec } from 'child_process';
 
 const SESSION_PATH = '.agentxchain/session.json';
 
@@ -27,6 +30,25 @@ function generateSessionId() {
   return `session_${randomBytes(8).toString('hex')}`;
 }
 
+/**
+ * Capture git baseline ref for repo-drift detection.
+ * Non-fatal: returns partial/null fields on failure.
+ */
+export function captureBaselineRef(root) {
+  try {
+    const gitHead = shellExec('git rev-parse HEAD', { cwd: root, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    const gitBranch = shellExec('git rev-parse --abbrev-ref HEAD', { cwd: root, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    const statusOutput = shellExec('git status --porcelain', { cwd: root, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    return {
+      git_head: gitHead,
+      git_branch: gitBranch,
+      workspace_dirty: statusOutput.length > 0,
+    };
+  } catch {
+    return { git_head: null, git_branch: null, workspace_dirty: null };
+  }
+}
+
 /**
  * Read the current session checkpoint, or null if none exists.
  */
@@ -40,12 +62,21 @@ export function readSessionCheckpoint(root) {
   }
 }
 
+/**
+ * Extract active turn IDs from governed state.
+ */
+function getActiveTurnIds(state) {
+  const turns = state.active_turns || {};
+  return Object.keys(turns);
+}
+
 /**
  * Write or update the session checkpoint.
  *
  * @param {string} root - project root
  * @param {object} state - current governed state (from state.json)
- * @param {string} reason - checkpoint reason (e.g. 'turn_accepted', 'phase_approved', 'run_completed')
+ * @param {string} reason - checkpoint reason (e.g. 'turn_assigned', 'turn_accepted',
+ *                          'phase_approved', 'run_completed', 'blocked', 'restart_reconnect')
  * @param {object} [extra] - optional extra context fields
  */
 export function writeSessionCheckpoint(root, state, reason, extra = {}) {
@@ -58,20 +89,40 @@ export function writeSessionCheckpoint(root, state, reason, extra = {}) {
       : generateSessionId();
 
     const currentTurn = state.current_turn || null;
-    const lastTurnId = currentTurn?.id || currentTurn?.turn_id || state.last_completed_turn_id || null;
+    const activeTurnIds = getActiveTurnIds(state);
+    const lastTurnId = currentTurn?.id || currentTurn?.turn_id
+      || (activeTurnIds.length > 0 ? activeTurnIds[activeTurnIds.length - 1] : null)
+      || state.last_completed_turn_id || null;
     const lastRole = currentTurn?.role || currentTurn?.assigned_role || extra.role || null;
     const lastPhase = state.current_phase || state.phase || null;
 
+    // Derive last_completed_turn_id from history or state
+    const lastCompletedTurnId = state.last_completed_turn_id || existing?.last_completed_turn_id || null;
+
+    // Derive pending gates
+    const pendingGate = state.pending_phase_transition?.gate || state.pending_transition?.gate || null;
+    const pendingRunCompletion = state.pending_run_completion?.gate || null;
+
+    // Capture git baseline for repo-drift detection
+    const baselineRef = extra.baseline_ref || captureBaselineRef(root);
+
     const checkpoint = {
       session_id: sessionId,
       run_id: state.run_id,
       started_at: existing?.started_at || new Date().toISOString(),
       last_checkpoint_at: new Date().toISOString(),
+      checkpoint_reason: reason,
+      run_status: state.status || null,
+      phase: lastPhase,
+      last_phase: lastPhase, // backward compat alias for report.js consumers
       last_turn_id: lastTurnId,
-      last_phase: lastPhase,
+      last_completed_turn_id: lastCompletedTurnId,
+      active_turn_ids: activeTurnIds,
       last_role: lastRole,
-      run_status: state.status || null,
-      checkpoint_reason: reason,
+      pending_gate: pendingGate,
+      pending_run_completion: pendingRunCompletion ? true : null,
+      blocked: state.status === 'blocked',
+      baseline_ref: baselineRef,
       agent_context: {
         adapter: extra.adapter || null,
         dispatch_dir: extra.dispatch_dir || null,

package/src/lib/workflow-kit-phase-templates.js

@@ -0,0 +1,102 @@
+function cloneJsonCompatible(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+const WORKFLOW_KIT_PHASE_TEMPLATE_REGISTRY = Object.freeze({
+  'planning-default': {
+    description: 'Core planning proof surface for governed repos.',
+    artifacts: [
+      { path: '.planning/PM_SIGNOFF.md', semantics: 'pm_signoff', required: true },
+      { path: '.planning/SYSTEM_SPEC.md', semantics: 'system_spec', required: true },
+      { path: '.planning/ROADMAP.md', semantics: null, required: true },
+    ],
+  },
+  'implementation-default': {
+    description: 'Implementation proof surface for governed repos.',
+    artifacts: [
+      { path: '.planning/IMPLEMENTATION_NOTES.md', semantics: 'implementation_notes', required: true },
+    ],
+  },
+  'qa-default': {
+    description: 'QA and ship-verdict proof surface for governed repos.',
+    artifacts: [
+      { path: '.planning/acceptance-matrix.md', semantics: 'acceptance_matrix', required: true },
+      { path: '.planning/ship-verdict.md', semantics: 'ship_verdict', required: true },
+      { path: '.planning/RELEASE_NOTES.md', semantics: 'release_notes', required: true },
+    ],
+  },
+  'architecture-review': {
+    description: 'Structured architecture-review document with required sections.',
+    artifacts: [
+      {
+        path: '.planning/ARCHITECTURE.md',
+        semantics: 'section_check',
+        semantics_config: {
+          required_sections: ['## Context', '## Proposed Design', '## Trade-offs', '## Risks'],
+        },
+        required: true,
+      },
+    ],
+  },
+  'security-review': {
+    description: 'Structured security-review document with required sections.',
+    artifacts: [
+      {
+        path: '.planning/SECURITY_REVIEW.md',
+        semantics: 'section_check',
+        semantics_config: {
+          required_sections: ['## Threat Model', '## Findings', '## Verdict'],
+        },
+        required: true,
+      },
+    ],
+  },
+});
+
+export const VALID_WORKFLOW_KIT_PHASE_TEMPLATE_IDS = Object.freeze(
+  Object.keys(WORKFLOW_KIT_PHASE_TEMPLATE_REGISTRY),
+);
+
+const DEFAULT_WORKFLOW_KIT_PHASE_TEMPLATE_BY_PHASE = Object.freeze({
+  planning: 'planning-default',
+  implementation: 'implementation-default',
+  qa: 'qa-default',
+});
+
+export function listWorkflowKitPhaseTemplates() {
+  return VALID_WORKFLOW_KIT_PHASE_TEMPLATE_IDS.map((id) => loadWorkflowKitPhaseTemplate(id));
+}
+
+export function isWorkflowKitPhaseTemplateId(templateId) {
+  return VALID_WORKFLOW_KIT_PHASE_TEMPLATE_IDS.includes(templateId);
+}
+
+export function loadWorkflowKitPhaseTemplate(templateId) {
+  if (!isWorkflowKitPhaseTemplateId(templateId)) {
+    throw new Error(
+      `Unknown workflow-kit phase template "${templateId}". Valid templates: ${VALID_WORKFLOW_KIT_PHASE_TEMPLATE_IDS.join(', ')}`,
+    );
+  }
+
+  const template = WORKFLOW_KIT_PHASE_TEMPLATE_REGISTRY[templateId];
+  return {
+    id: templateId,
+    description: template.description,
+    artifacts: cloneJsonCompatible(template.artifacts),
+  };
+}
+
+export function expandWorkflowKitPhaseArtifacts(phaseConfig = {}) {
+  const templateArtifacts = phaseConfig.template
+    ? loadWorkflowKitPhaseTemplate(phaseConfig.template).artifacts
+    : [];
+  const explicitArtifacts = Array.isArray(phaseConfig.artifacts)
+    ? cloneJsonCompatible(phaseConfig.artifacts)
+    : [];
+  return [...templateArtifacts, ...explicitArtifacts];
+}
+
+export function buildDefaultWorkflowKitArtifactsForPhase(phase) {
+  const templateId = DEFAULT_WORKFLOW_KIT_PHASE_TEMPLATE_BY_PHASE[phase];
+  return templateId ? loadWorkflowKitPhaseTemplate(templateId).artifacts : null;
+}