agentxchain 2.38.0 → 2.40.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/app.js

@@ -16,7 +16,7 @@ import { render as renderBlockers } from './components/blockers.js';
 import { render as renderArtifacts } from './components/artifacts.js';
 
 const VIEWS = {
-  timeline: { fetch: ['state', 'continuity', 'history', 'audit', 'annotations'], render: renderTimeline },
+  timeline: { fetch: ['state', 'continuity', 'history', 'audit', 'annotations', 'connectors'], render: renderTimeline },
   ledger: { fetch: ['ledger'], render: renderLedger },
   hooks: { fetch: ['audit', 'annotations'], render: renderHooks },
   blocked: { fetch: ['state', 'audit', 'coordinatorState', 'coordinatorAudit'], render: renderBlocked },
@@ -41,6 +41,7 @@ const API_MAP = {
   coordinatorAudit: '/api/coordinator/hooks/audit',
   coordinatorBlockers: '/api/coordinator/blockers',
   workflowKitArtifacts: '/api/workflow-kit-artifacts',
+  connectors: '/api/connectors',
 };
 
 const viewState = {

package/dashboard/components/gate.js

@@ -82,7 +82,8 @@ function aggregateEvidence(turns) {
         allDecisions.push(dec);
       }
     }
-    const files = turn.observed_artifact?.files_changed || turn.files_changed || [];
+    const observed = turn.observed_artifact?.files_changed;
+    const files = (Array.isArray(observed) && observed.length > 0) ? observed : (turn.files_changed || []);
     for (const f of files) {
       if (!allFiles.includes(f)) {
         allFiles.push(f);

package/dashboard/components/timeline.js

@@ -177,7 +177,60 @@ function renderContinuityPanel(continuity) {
   return html;
 }
 
-export function render({ state, continuity, history, annotations, audit }) {
+function connectorBadge(state) {
+  const colors = {
+    healthy: 'var(--green)',
+    failing: 'var(--red)',
+    active: 'var(--yellow)',
+    never_used: 'var(--text-dim)',
+  };
+  const color = colors[state] || 'var(--text-dim)';
+  return `<span class="badge" style="color:${color};border-color:${color}">${esc(state || 'unknown')}</span>`;
+}
+
+function renderConnectorHealthPanel(connectorsPayload) {
+  const connectors = Array.isArray(connectorsPayload?.connectors)
+    ? connectorsPayload.connectors
+    : [];
+  if (connectors.length === 0) return '';
+
+  let html = `<div class="section"><h3>Connector Health</h3><div class="turn-list">`;
+  for (const connector of connectors) {
+    html += `<div class="turn-card">
+      <div class="turn-header">
+        <span class="mono">${esc(connector.runtime_id)}</span>
+        ${connectorBadge(connector.state)}
+      </div>
+      <div class="turn-detail"><span class="detail-label">Type:</span> ${esc(connector.type || 'unknown')}</div>
+      <div class="turn-detail"><span class="detail-label">Target:</span> <span class="mono">${esc(connector.target || 'unknown')}</span></div>
+      <div class="turn-detail"><span class="detail-label">Reachable:</span> ${esc(connector.reachable || 'unknown')}</div>`;
+
+    if (Array.isArray(connector.active_turn_ids) && connector.active_turn_ids.length > 0) {
+      html += `<div class="turn-detail"><span class="detail-label">Active turns:</span> <span class="mono">${esc(connector.active_turn_ids.join(', '))}</span></div>`;
+    }
+
+    if (connector.last_success_at) {
+      html += `<div class="turn-detail"><span class="detail-label">Last success:</span> ${esc(connector.last_success_at)}</div>`;
+    }
+    if (connector.last_failure_at) {
+      html += `<div class="turn-detail"><span class="detail-label">Last failure:</span> ${esc(connector.last_failure_at)}</div>`;
+    }
+    if (connector.last_error) {
+      html += `<div class="turn-detail risks"><span class="detail-label">Last error:</span> ${esc(connector.last_error)}</div>`;
+    }
+    if (connector.attempts_made != null || connector.latency_ms != null) {
+      const attempts = connector.attempts_made != null ? connector.attempts_made : 'n/a';
+      const latency = connector.latency_ms != null ? `${connector.latency_ms}ms` : 'n/a';
+      html += `<div class="turn-detail"><span class="detail-label">Attempt telemetry:</span> attempts ${esc(attempts)} / latency ${esc(latency)}</div>`;
+    }
+
+    html += `</div>`;
+  }
+  html += `</div></div>`;
+  return html;
+}
+
+export function render({ state, continuity, history, annotations, audit, connectors }) {
   if (!state) {
     return `<div class="placeholder"><h2>No Run</h2><p>No governed run found. Start one with <code class="mono">agentxchain init --governed</code></p></div>`;
   }
@@ -198,6 +251,7 @@ export function render({ state, continuity, history, annotations, audit }) {
   </div>`;
 
   html += renderContinuityPanel(continuity);
+  html += renderConnectorHealthPanel(connectors);
 
   // Active turns
   if (activeTurns.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.38.0",
+  "version": "2.40.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -30,6 +30,7 @@
     "postflight:downstream": "bash scripts/release-downstream-truth.sh",
     "bump:release": "bash scripts/release-bump.sh",
     "sync:homebrew": "bash scripts/sync-homebrew.sh",
+    "verify:post-publish": "bash scripts/verify-post-publish.sh",
     "build:macos": "bun build bin/agentxchain.js --compile --target=bun-darwin-arm64 --outfile=dist/agentxchain-macos-arm64",
     "build:linux": "bun build bin/agentxchain.js --compile --target=bun-linux-x64 --outfile=dist/agentxchain-linux-x64",
     "publish:npm": "bash scripts/publish-npm.sh"

package/scripts/verify-post-publish.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Post-publish repo-mirror verification — the executable contract that
+# ensures main is green after a release publish completes.
+#
+# Three-phase Homebrew lifecycle:
+#   Phase 1 (pre-publish):  formula URL updated, SHA carried from previous version
+#   Phase 2 (post-publish): npm live, but repo mirror SHA is stale
+#   Phase 3 (post-sync):    repo mirror SHA matches published tarball — main is green
+#
+# This script transitions from Phase 2 → Phase 3 and verifies the result.
+#
+# Usage: bash scripts/verify-post-publish.sh [--target-version <semver>]
+#   If --target-version is omitted, reads from package.json.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLI_DIR="${SCRIPT_DIR}/.."
+cd "$CLI_DIR"
+
+TARGET_VERSION=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target-version)
+      if [[ -z "${2:-}" ]]; then
+        echo "Error: --target-version requires a semver argument" >&2
+        exit 1
+      fi
+      TARGET_VERSION="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$TARGET_VERSION" ]]; then
+  TARGET_VERSION="$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json','utf8')).version)")"
+fi
+
+echo "Post-Publish Verification: v${TARGET_VERSION}"
+echo "============================================="
+echo ""
+
+# Step 1: Verify npm serves the version
+echo "[1/4] Checking npm registry..."
+NPM_VERSION="$(npm view "agentxchain@${TARGET_VERSION}" version 2>/dev/null || echo "")"
+if [[ "$NPM_VERSION" != "$TARGET_VERSION" ]]; then
+  echo "  FAIL: npm does not serve agentxchain@${TARGET_VERSION} (got: '${NPM_VERSION}')"
+  echo "  This script must run AFTER npm publish completes."
+  exit 1
+fi
+echo "  OK: npm serves v${TARGET_VERSION}"
+
+# Step 2: Sync the repo mirror to the published tarball
+echo "[2/4] Syncing repo mirror to published tarball..."
+bash "${SCRIPT_DIR}/sync-homebrew.sh" --target-version "$TARGET_VERSION"
+echo "  OK: repo mirror synced"
+
+# Step 3: Run the full test suite WITHOUT the preflight skip
+echo "[3/4] Running full test suite (no preflight skip)..."
+echo "  This verifies the Homebrew mirror contract passes with the real SHA."
+npm test
+echo "  OK: full test suite green"
+
+# Step 4: Summary
+echo ""
+echo "============================================="
+echo "Post-publish verification PASSED."
+echo "  - npm: agentxchain@${TARGET_VERSION} live"
+echo "  - repo mirror: SHA synced to published tarball"
+echo "  - test suite: green without preflight skip"
+echo ""
+echo "Main is now in Phase 3 (post-sync). Commit and push the mirror update."

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

@@ -3,6 +3,8 @@ import { loadConfig, loadLock, loadProjectContext, loadProjectState, loadState }
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { getActiveTurn, getActiveTurnCount, getActiveTurns } from '../lib/governed-state.js';
 import { getContinuityStatus } from '../lib/continuity-status.js';
+import { getConnectorHealth } from '../lib/connector-health.js';
+import { deriveWorkflowKitArtifacts } from '../lib/workflow-kit-artifacts.js';
 
 export async function statusCommand(opts) {
   const context = loadProjectContext();
@@ -76,6 +78,9 @@ function renderGovernedStatus(context, opts) {
   const { root, config, version } = context;
   const state = loadProjectState(root, config);
   const continuity = getContinuityStatus(root, state);
+  const connectorHealth = getConnectorHealth(root, config, state);
+
+  const workflowKitArtifacts = deriveWorkflowKitArtifacts(root, config, state);
 
   if (opts.json) {
     console.log(JSON.stringify({
@@ -85,6 +90,8 @@ function renderGovernedStatus(context, opts) {
       config,
       state,
       continuity,
+      connector_health: connectorHealth,
+      workflow_kit_artifacts: workflowKitArtifacts,
     }, null, 2));
     return;
   }
@@ -105,6 +112,7 @@ function renderGovernedStatus(context, opts) {
   console.log('');
 
   renderContinuityStatus(continuity, state);
+  renderConnectorHealthStatus(connectorHealth);
 
   const activeTurnCount = getActiveTurnCount(state);
   const activeTurns = getActiveTurns(state);
@@ -227,6 +235,8 @@ function renderGovernedStatus(context, opts) {
     }
   }
 
+  renderWorkflowKitArtifactsSection(workflowKitArtifacts);
+
   if (state?.budget_status) {
     console.log('');
     console.log(`  ${chalk.dim('Budget:')}   spent $${formatUsd(state.budget_status.spent_usd)} / remaining $${formatUsd(state.budget_status.remaining_usd)}`);
@@ -243,6 +253,48 @@ function renderGovernedStatus(context, opts) {
   console.log('');
 }
 
+function renderConnectorHealthStatus(connectorHealth) {
+  const connectors = Array.isArray(connectorHealth?.connectors)
+    ? connectorHealth.connectors
+    : [];
+  if (connectors.length === 0) {
+    return;
+  }
+
+  console.log(`  ${chalk.dim('Connectors:')}`);
+  for (const connector of connectors) {
+    const stateLabel = formatConnectorState(connector.state);
+    console.log(`    ${stateLabel} ${chalk.bold(connector.runtime_id)} — ${connector.type} (${connector.target})`);
+
+    if (connector.active_turn_ids.length > 0) {
+      console.log(`      ${chalk.dim('Active turns:')} ${connector.active_turn_ids.join(', ')}`);
+    }
+
+    if (connector.last_error) {
+      console.log(`      ${chalk.dim('Last error:')} ${connector.last_error}`);
+    } else if (connector.last_success_at) {
+      console.log(`      ${chalk.dim('Last success:')} ${connector.last_success_at}`);
+    } else if (connector.last_attempt_at) {
+      console.log(`      ${chalk.dim('Last attempt:')} ${connector.last_attempt_at}`);
+    }
+  }
+  console.log('');
+}
+
+function formatConnectorState(state) {
+  switch (state) {
+    case 'healthy':
+      return chalk.green('● healthy');
+    case 'failing':
+      return chalk.red('✗ failing');
+    case 'active':
+      return chalk.yellow('● active');
+    case 'never_used':
+    default:
+      return chalk.dim('○ never_used');
+  }
+}
+
 function renderContinuityStatus(continuity, state) {
   if (!continuity) return;
 
@@ -292,6 +344,25 @@ function renderContinuityStatus(continuity, state) {
   console.log('');
 }
 
+function renderWorkflowKitArtifactsSection(wkData) {
+  if (!wkData || !wkData.artifacts || wkData.artifacts.length === 0) return;
+
+  const artifacts = wkData.artifacts;
+  console.log('');
+  console.log(`  ${chalk.dim('Artifacts:')} (${wkData.phase})`);
+  for (const a of artifacts) {
+    const icon = a.exists ? chalk.green('✓') : (a.required ? chalk.red('✗') : chalk.yellow('○'));
+    const reqLabel = a.required ? '' : chalk.dim(' (optional)');
+    const ownerLabel = a.owned_by
+      ? chalk.dim(` [${a.owned_by}${a.owner_resolution === 'entry_role' ? '*' : ''}]`)
+      : '';
+    console.log(`    ${icon} ${a.path}${ownerLabel}${reqLabel}`);
+  }
+  if (artifacts.some(a => a.owner_resolution === 'entry_role')) {
+    console.log(`    ${chalk.dim('* = ownership inferred from entry_role')}`);
+  }
+}
+
 function formatPhase(phase) {
   const colors = { discovery: chalk.blue, build: chalk.green, qa: chalk.yellow, deploy: chalk.magenta, blocked: chalk.red };
   return (colors[phase] || chalk.white)(phase);

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/connector-health.js

@@ -0,0 +1,319 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+
+const HISTORY_PATH = '.agentxchain/history.jsonl';
+const STAGING_DIR = '.agentxchain/staging';
+const CONNECTOR_RUNTIME_TYPES = new Set(['local_cli', 'api_proxy', 'mcp', 'remote_agent']);
+
+function safeReadJson(absPath) {
+  try {
+    if (!existsSync(absPath)) return null;
+    return JSON.parse(readFileSync(absPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function safeReadJsonl(absPath) {
+  try {
+    if (!existsSync(absPath)) return [];
+    const raw = readFileSync(absPath, 'utf8').trim();
+    if (!raw) return [];
+    return raw.split('\n').filter(Boolean).map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+function toMillis(value) {
+  if (typeof value !== 'string' || value.length === 0) return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function chooseLatest(left, right) {
+  if (!left) return right || null;
+  if (!right) return left;
+  const leftMs = toMillis(left.at);
+  const rightMs = toMillis(right.at);
+  if (leftMs === null) return right;
+  if (rightMs === null) return left;
+  return rightMs >= leftMs ? right : left;
+}
+
+function chooseLatestDefined(left, right) {
+  if (right == null) return left ?? null;
+  if (left == null) return right;
+  return right;
+}
+
+function formatCommand(command, args = []) {
+  if (Array.isArray(command)) {
+    return command.join(' ');
+  }
+  if (typeof command === 'string' && command.length > 0) {
+    return [command, ...(Array.isArray(args) ? args : [])].join(' ');
+  }
+  return null;
+}
+
+function formatTarget(runtime) {
+  switch (runtime?.type) {
+    case 'api_proxy':
+      return [runtime.provider, runtime.model].filter(Boolean).join(' / ') || 'unknown target';
+    case 'remote_agent':
+      return runtime.url || 'unknown target';
+    case 'mcp':
+      return runtime.transport === 'streamable_http'
+        ? (runtime.url || 'unknown target')
+        : (formatCommand(runtime.command, runtime.args) || 'unknown target');
+    case 'local_cli':
+      return formatCommand(runtime.command, runtime.args) || 'unknown target';
+    default:
+      return 'unknown target';
+  }
+}
+
+function getLatestAttemptFromTrace(trace) {
+  if (!trace || typeof trace !== 'object' || Array.isArray(trace)) return null;
+  const attempts = Array.isArray(trace.attempts) ? trace.attempts : [];
+  if (attempts.length === 0) return null;
+  const last = attempts[attempts.length - 1];
+  if (!last || typeof last !== 'object') return null;
+  const startedAt = typeof last.started_at === 'string' ? last.started_at : null;
+  const completedAt = typeof last.completed_at === 'string' ? last.completed_at : startedAt;
+  let latencyMs = null;
+  const startedMs = toMillis(startedAt);
+  const completedMs = toMillis(completedAt);
+  if (startedMs !== null && completedMs !== null && completedMs >= startedMs) {
+    latencyMs = completedMs - startedMs;
+  }
+  return {
+    at: completedAt,
+    turn_id: trace.turn_id || null,
+    runtime_id: trace.runtime_id || null,
+    attempts_made: Number.isInteger(trace.attempts_made) ? trace.attempts_made : attempts.length,
+    final_outcome: trace.final_outcome || null,
+    latency_ms: latencyMs,
+  };
+}
+
+function buildConnectorEntry(runtimeId, runtime) {
+  return {
+    runtime_id: runtimeId,
+    type: runtime.type,
+    target: formatTarget(runtime),
+    state: 'never_used',
+    reachable: 'unknown',
+    active_turn_ids: [],
+    active_roles: [],
+    last_turn_id: null,
+    last_role: null,
+    last_phase: null,
+    last_attempt_at: null,
+    last_success_at: null,
+    last_failure_at: null,
+    latency_ms: null,
+    attempts_made: null,
+    last_error: null,
+    _latest_success: null,
+    _latest_failure: null,
+    _latest_attempt: null,
+    _latest_identity: null,
+  };
+}
+
+function applyIdentityTarget(entry, candidate) {
+  if (!candidate) return;
+  entry.last_turn_id = candidate.turn_id || entry.last_turn_id;
+  entry.last_role = candidate.role || entry.last_role;
+  entry.last_phase = candidate.phase || entry.last_phase;
+}
+
+function finalizeConnectorEntry(entry) {
+  entry.last_attempt_at = entry._latest_attempt?.at || null;
+  entry.latency_ms = entry._latest_attempt?.latency_ms ?? null;
+  entry.attempts_made = entry._latest_attempt?.attempts_made ?? null;
+  entry.last_success_at = entry._latest_success?.at || null;
+  entry.last_failure_at = entry._latest_failure?.at || null;
+  entry.last_error = entry._latest_failure?.error || null;
+
+  const hasActive = entry.active_turn_ids.length > 0;
+  const hasFailure = Boolean(entry._latest_failure);
+  const hasSuccess = Boolean(entry._latest_success);
+
+  if (hasActive && !hasFailure) {
+    entry.state = 'active';
+  } else {
+    const failureMs = toMillis(entry.last_failure_at);
+    const successMs = toMillis(entry.last_success_at);
+    if (failureMs !== null && (successMs === null || failureMs >= successMs)) {
+      entry.state = 'failing';
+    } else if (hasSuccess || entry._latest_attempt?.final_outcome === 'success') {
+      entry.state = 'healthy';
+    } else if (hasActive) {
+      entry.state = 'active';
+    } else {
+      entry.state = 'never_used';
+    }
+  }
+
+  if (entry.type === 'local_cli') {
+    entry.reachable = 'unknown';
+  } else if (entry._latest_attempt?.final_outcome === 'success' || entry.state === 'healthy') {
+    entry.reachable = 'yes';
+  } else if (entry._latest_failure) {
+    entry.reachable = 'no';
+  } else {
+    entry.reachable = 'unknown';
+  }
+
+  delete entry._latest_success;
+  delete entry._latest_failure;
+  delete entry._latest_attempt;
+  delete entry._latest_identity;
+  return entry;
+}
+
+export function getConnectorHealth(root, config, state) {
+  const runtimeEntries = Object.entries(config?.runtimes || {})
+    .filter(([, runtime]) => CONNECTOR_RUNTIME_TYPES.has(runtime?.type))
+    .sort(([left], [right]) => left.localeCompare(right, 'en'));
+
+  const connectors = runtimeEntries.map(([runtimeId, runtime]) => buildConnectorEntry(runtimeId, runtime));
+  const connectorMap = Object.fromEntries(connectors.map((entry) => [entry.runtime_id, entry]));
+
+  const turnRuntimeIndex = {};
+
+  for (const turn of Object.values(state?.active_turns || {})) {
+    if (!turn || typeof turn !== 'object') continue;
+    const entry = connectorMap[turn.runtime_id];
+    if (!entry) continue;
+    if (typeof turn.turn_id === 'string') {
+      turnRuntimeIndex[turn.turn_id] = turn.runtime_id;
+      entry.active_turn_ids.push(turn.turn_id);
+    }
+    if (typeof turn.assigned_role === 'string' && !entry.active_roles.includes(turn.assigned_role)) {
+      entry.active_roles.push(turn.assigned_role);
+    }
+    entry._latest_identity = chooseLatestDefined(entry._latest_identity, {
+      turn_id: turn.turn_id || null,
+      role: turn.assigned_role || null,
+      phase: state?.phase || null,
+    });
+  }
+
+  for (const entry of connectors) {
+    entry.active_turn_ids.sort((a, b) => a.localeCompare(b, 'en'));
+    entry.active_roles.sort((a, b) => a.localeCompare(b, 'en'));
+  }
+
+  const history = safeReadJsonl(join(root, HISTORY_PATH));
+  for (const item of history) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) continue;
+    const runtimeId = item.runtime_id;
+    const entry = connectorMap[runtimeId];
+    if (!entry) continue;
+
+    if (typeof item.turn_id === 'string') {
+      turnRuntimeIndex[item.turn_id] = runtimeId;
+    }
+
+    const acceptedAt = typeof item.accepted_at === 'string' ? item.accepted_at : null;
+    if (!acceptedAt) continue;
+
+    const successCandidate = {
+      at: acceptedAt,
+      turn_id: item.turn_id || null,
+      role: item.role || null,
+      phase: item.phase || null,
+    };
+    entry._latest_success = chooseLatest(entry._latest_success, successCandidate);
+    entry._latest_identity = chooseLatestDefined(entry._latest_identity, successCandidate);
+  }
+
+  const stagingRoot = join(root, STAGING_DIR);
+  if (existsSync(stagingRoot)) {
+    for (const child of readdirSync(stagingRoot, { withFileTypes: true })) {
+      if (!child.isDirectory()) continue;
+      const turnId = child.name;
+      const turnDir = join(stagingRoot, turnId);
+      const trace = safeReadJson(join(turnDir, 'retry-trace.json'));
+      const apiError = safeReadJson(join(turnDir, 'api-error.json'));
+      const runtimeId = trace?.runtime_id || turnRuntimeIndex[turnId] || null;
+      const entry = runtimeId ? connectorMap[runtimeId] : null;
+      if (!entry) continue;
+
+      const latestAttempt = getLatestAttemptFromTrace(trace);
+      if (latestAttempt) {
+        entry._latest_attempt = chooseLatest(entry._latest_attempt, latestAttempt);
+        const identity = {
+          turn_id: latestAttempt.turn_id || turnId,
+          role: null,
+          phase: null,
+        };
+        if (latestAttempt.final_outcome === 'success') {
+          entry._latest_success = chooseLatest(entry._latest_success, {
+            at: latestAttempt.at,
+            turn_id: latestAttempt.turn_id || turnId,
+            role: null,
+            phase: null,
+          });
+        } else if (latestAttempt.final_outcome === 'failure' || latestAttempt.final_outcome === 'aborted') {
+          entry._latest_failure = chooseLatest(entry._latest_failure, {
+            at: latestAttempt.at,
+            turn_id: latestAttempt.turn_id || turnId,
+            role: null,
+            phase: null,
+            error: apiError?.message || latestAttempt.final_outcome,
+          });
+        }
+        entry._latest_identity = chooseLatestDefined(entry._latest_identity, identity);
+      }
+
+      if (apiError && !latestAttempt) {
+        const stats = statSync(turnDir);
+        entry._latest_failure = chooseLatest(entry._latest_failure, {
+          at: stats.mtime.toISOString(),
+          turn_id: turnId,
+          role: null,
+          phase: null,
+          error: apiError.message || apiError.error_class || 'runtime_error',
+        });
+        entry._latest_identity = chooseLatestDefined(entry._latest_identity, {
+          turn_id: turnId,
+          role: null,
+          phase: null,
+        });
+      } else if (apiError && entry._latest_failure && entry._latest_failure.turn_id === turnId) {
+        entry._latest_failure.error = apiError.message || apiError.error_class || entry._latest_failure.error;
+      }
+    }
+  }
+
+  const blockedTurnId = state?.blocked_reason?.turn_id || null;
+  if (blockedTurnId && turnRuntimeIndex[blockedTurnId] && connectorMap[turnRuntimeIndex[blockedTurnId]]) {
+    const entry = connectorMap[turnRuntimeIndex[blockedTurnId]];
+    const detail = state?.blocked_reason?.recovery?.detail || state?.blocked_on || 'runtime_blocked';
+    const blockedAt = state?.blocked_reason?.blocked_at || null;
+    entry._latest_failure = chooseLatest(entry._latest_failure, {
+      at: blockedAt,
+      turn_id: blockedTurnId,
+      role: null,
+      phase: state?.phase || null,
+      error: detail,
+    });
+    entry._latest_identity = chooseLatestDefined(entry._latest_identity, {
+      turn_id: blockedTurnId,
+      role: null,
+      phase: state?.phase || null,
+    });
+  }
+
+  return {
+    connectors: connectors.map((entry) => {
+      applyIdentityTarget(entry, entry._latest_failure || entry._latest_success || entry._latest_identity);
+      return finalizeConnectorEntry(entry);
+    }),
+  };
+}

package/src/lib/dashboard/bridge-server.js

@@ -19,6 +19,7 @@ import { FileWatcher } from './file-watcher.js';
 import { approvePendingDashboardGate } from './actions.js';
 import { readCoordinatorBlockerSnapshot } from './coordinator-blockers.js';
 import { readWorkflowKitArtifacts } from './workflow-kit-artifacts.js';
+import { readConnectorHealthSnapshot } from './connectors.js';
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -286,6 +287,12 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
       return;
     }
 
+    if (pathname === '/api/connectors') {
+      const result = readConnectorHealthSnapshot(workspacePath);
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     // API routes
     if (pathname.startsWith('/api/')) {
       const result = readResource(agentxchainDir, pathname);

package/src/lib/dashboard/connectors.js

@@ -0,0 +1,41 @@
+import { loadProjectContext } from '../config.js';
+import { readJsonFile } from './state-reader.js';
+import { getConnectorHealth } from '../connector-health.js';
+import { join } from 'path';
+
+export function readConnectorHealthSnapshot(workspacePath) {
+  const context = loadProjectContext(workspacePath);
+  if (!context || context.config.protocol_mode !== 'governed') {
+    return {
+      ok: false,
+      status: 404,
+      body: {
+        ok: false,
+        code: 'config_missing',
+        error: 'Project config not found. Run `agentxchain init --governed` first.',
+      },
+    };
+  }
+
+  const state = readJsonFile(join(workspacePath, '.agentxchain'), 'state.json');
+  if (!state) {
+    return {
+      ok: false,
+      status: 404,
+      body: {
+        ok: false,
+        code: 'state_missing',
+        error: 'Run state not found. Run `agentxchain init --governed` first.',
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      ok: true,
+      ...getConnectorHealth(workspacePath, context.config, state),
+    },
+  };
+}

package/src/lib/dashboard/workflow-kit-artifacts.js

@@ -10,9 +10,9 @@
  * See: WORKFLOW_KIT_DASHBOARD_SPEC.md
  */
 
-import { existsSync } from 'fs';
 import { join } from 'path';
-import { loadConfig } from '../config.js';
+import { loadConfig, loadProjectContext, loadProjectState } from '../config.js';
+import { deriveWorkflowKitArtifacts } from '../workflow-kit-artifacts.js';
 import { readJsonFile } from './state-reader.js';
 
 /**
@@ -22,8 +22,10 @@ import { readJsonFile } from './state-reader.js';
  * @returns {{ ok: boolean, status: number, body: object }}
  */
 export function readWorkflowKitArtifacts(workspacePath) {
-  const configResult = loadConfig(workspacePath);
-  if (!configResult) {
+  const context = loadProjectContext(workspacePath);
+  const governedContext = context?.config?.protocol_mode === 'governed' ? context : null;
+  const legacyConfigResult = governedContext ? null : loadConfig(workspacePath);
+  if (!governedContext && !legacyConfigResult) {
     return {
       ok: false,
       status: 404,
@@ -35,8 +37,11 @@ export function readWorkflowKitArtifacts(workspacePath) {
     };
   }
 
-  const agentxchainDir = join(workspacePath, '.agentxchain');
-  const state = readJsonFile(agentxchainDir, 'state.json');
+  const root = governedContext?.root || legacyConfigResult.root;
+  const config = governedContext?.config || legacyConfigResult.config;
+  const state = governedContext
+    ? loadProjectState(root, config)
+    : readJsonFile(join(root, '.agentxchain'), 'state.json');
   if (!state) {
     return {
       ok: false,
@@ -49,7 +54,6 @@ export function readWorkflowKitArtifacts(workspacePath) {
     };
   }
 
-  const config = configResult.config;
   const phase = state.phase || null;
 
   if (!config.workflow_kit) {
@@ -89,8 +93,8 @@ export function readWorkflowKitArtifacts(workspacePath) {
     };
   }
 
-  const artifacts = Array.isArray(phaseConfig.artifacts) ? phaseConfig.artifacts : [];
-  if (artifacts.length === 0) {
+  const snapshot = deriveWorkflowKitArtifacts(root, config, state);
+  if (!snapshot) {
     return {
       ok: true,
       status: 200,
@@ -102,30 +106,13 @@ export function readWorkflowKitArtifacts(workspacePath) {
     };
   }
 
-  const entryRole = config.routing?.[phase]?.entry_role || null;
-
-  const result = artifacts
-    .filter((a) => a && typeof a.path === 'string')
-    .map((a) => {
-      const hasExplicitOwner = typeof a.owned_by === 'string' && a.owned_by.length > 0;
-      return {
-        path: a.path,
-        required: a.required !== false,
-        semantics: a.semantics || null,
-        owned_by: hasExplicitOwner ? a.owned_by : entryRole,
-        owner_resolution: hasExplicitOwner ? 'explicit' : 'entry_role',
-        exists: existsSync(join(workspacePath, a.path)),
-      };
-    })
-    .sort((a, b) => a.path.localeCompare(b.path, 'en'));
-
   return {
     ok: true,
     status: 200,
     body: {
       ok: true,
       phase,
-      artifacts: result,
+      artifacts: snapshot.artifacts,
     },
   };
 }

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,52 @@ 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 (Array.isArray(phaseConfig.artifacts)) {
+        const explicitSeenPaths = new Set();
+        for (const artifact of phaseConfig.artifacts) {
+          if (!artifact || typeof artifact !== 'object') {
+            continue;
+          }
+          if (typeof artifact.path !== 'string' || !artifact.path.trim()) {
+            continue;
+          }
+          if (explicitSeenPaths.has(artifact.path)) {
+            errors.push(`duplicate artifact path "${artifact.path}" in phase "${phase}"`);
+            continue;
+          }
+          explicitSeenPaths.add(artifact.path);
+        }
+      }
+
+      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 +870,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 +887,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 +904,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/workflow-kit-artifacts.js

@@ -0,0 +1,36 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+export function deriveWorkflowKitArtifacts(root, config, state) {
+  if (!config?.workflow_kit) return null;
+
+  const phase = state?.phase || null;
+  if (!phase) return null;
+
+  const phaseConfig = config.workflow_kit.phases?.[phase];
+  if (!phaseConfig) return null;
+
+  const artifacts = Array.isArray(phaseConfig.artifacts) ? phaseConfig.artifacts : [];
+  if (artifacts.length === 0) return null;
+
+  const entryRole = config.routing?.[phase]?.entry_role || null;
+
+  return {
+    ok: true,
+    phase,
+    artifacts: artifacts
+      .filter((artifact) => artifact && typeof artifact.path === 'string')
+      .map((artifact) => {
+        const hasExplicitOwner = typeof artifact.owned_by === 'string' && artifact.owned_by.length > 0;
+        return {
+          path: artifact.path,
+          required: artifact.required !== false,
+          semantics: artifact.semantics || null,
+          owned_by: hasExplicitOwner ? artifact.owned_by : entryRole,
+          owner_resolution: hasExplicitOwner ? 'explicit' : 'entry_role',
+          exists: existsSync(join(root, artifact.path)),
+        };
+      })
+      .sort((a, b) => a.path.localeCompare(b.path, 'en')),
+  };
+}

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

@@ -0,0 +1,128 @@
+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)
+    : [];
+  const mergedArtifacts = templateArtifacts.map((artifact) => cloneJsonCompatible(artifact));
+  const indexByPath = new Map(
+    mergedArtifacts
+      .filter((artifact) => artifact && typeof artifact.path === 'string')
+      .map((artifact, index) => [artifact.path, index]),
+  );
+
+  for (const artifact of explicitArtifacts) {
+    if (!artifact || typeof artifact.path !== 'string') {
+      mergedArtifacts.push(artifact);
+      continue;
+    }
+
+    const existingIndex = indexByPath.get(artifact.path);
+    if (existingIndex === undefined) {
+      indexByPath.set(artifact.path, mergedArtifacts.length);
+      mergedArtifacts.push(artifact);
+      continue;
+    }
+
+    mergedArtifacts[existingIndex] = {
+      ...mergedArtifacts[existingIndex],
+      ...artifact,
+    };
+  }
+
+  return mergedArtifacts;
+}
+
+export function buildDefaultWorkflowKitArtifactsForPhase(phase) {
+  const templateId = DEFAULT_WORKFLOW_KIT_PHASE_TEMPLATE_BY_PHASE[phase];
+  return templateId ? loadWorkflowKitPhaseTemplate(templateId).artifacts : null;
+}

package/src/templates/governed/enterprise-app.json

@@ -145,49 +145,33 @@
     "workflow_kit": {
       "phases": {
         "planning": {
-          "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 }
-          ]
+          "template": "planning-default"
         },
         "architecture": {
+          "template": "architecture-review",
           "artifacts": [
             {
               "path": ".planning/ARCHITECTURE.md",
-              "semantics": "section_check",
               "owned_by": "architect",
-              "semantics_config": {
-                "required_sections": ["## Context", "## Proposed Design", "## Trade-offs", "## Risks"]
-              },
               "required": true
             }
           ]
         },
         "implementation": {
-          "artifacts": [
-            { "path": ".planning/IMPLEMENTATION_NOTES.md", "semantics": "implementation_notes", "required": true }
-          ]
+          "template": "implementation-default"
         },
         "security_review": {
+          "template": "security-review",
           "artifacts": [
             {
               "path": ".planning/SECURITY_REVIEW.md",
-              "semantics": "section_check",
               "owned_by": "security_reviewer",
-              "semantics_config": {
-                "required_sections": ["## Threat Model", "## Findings", "## Verdict"]
-              },
               "required": true
             }
           ]
         },
         "qa": {
-          "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 }
-          ]
+          "template": "qa-default"
         }
       }
     }