agentxchain 2.25.2 → 2.27.0

package/README.md

@@ -88,6 +88,7 @@ Built-in governed templates:
 - `cli-tool`: command surface, platform support, distribution checklist
 - `library`: public API, compatibility policy, release and adoption checklist
 - `web-app`: user flows, UI acceptance, browser support
+- `enterprise-app`: enterprise planning artifacts plus blueprint-backed `architect` and `security_reviewer` phases
 
 `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:
 

package/bin/agentxchain.js

@@ -120,7 +120,7 @@ program
   .option('-y, --yes', 'Skip prompts, use defaults')
   .option('--governed', 'Create a governed project (orchestrator-owned state)')
   .option('--dir <path>', 'Scaffold target directory. Use "." for in-place bootstrap.')
-  .option('--template <id>', 'Governed scaffold template: generic, api-service, cli-tool, library, web-app')
+  .option('--template <id>', 'Governed scaffold template: generic, api-service, cli-tool, library, web-app, enterprise-app')
   .option('--dev-command <parts...>', 'Governed local-dev command parts. Include {prompt} for argv prompt delivery.')
   .option('--dev-prompt-transport <mode>', 'Governed local-dev prompt transport: argv, stdin, dispatch_bundle_only')
   .option('--schema-version <version>', 'Schema version (3 for legacy, or use --governed for current)')
@@ -469,7 +469,7 @@ intakeCmd
   .description('Triage a detected intent — set priority, template, charter, and acceptance')
   .option('--intent <id>', 'Intent ID to triage')
   .option('--priority <level>', 'Priority level (p0, p1, p2, p3)')
-  .option('--template <id>', 'Governed template (generic, api-service, cli-tool, library, web-app)')
+  .option('--template <id>', 'Governed template (generic, api-service, cli-tool, library, web-app, enterprise-app)')
   .option('--charter <text>', 'Delivery charter text')
   .option('--acceptance <text>', 'Comma-separated acceptance criteria')
   .option('--suppress', 'Suppress the intent instead of triaging')

package/package.json

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

package/src/commands/init.js

@@ -142,7 +142,7 @@ const GOVERNED_GATES = {
   }
 };
 
-function buildGovernedPrompt(roleId, role) {
+function buildGovernedPrompt(roleId, role, scaffoldContext = {}) {
   const rolePrompts = {
     pm: buildPmPrompt,
     dev: buildDevPrompt,
@@ -154,7 +154,7 @@ function buildGovernedPrompt(roleId, role) {
   if (builder) return builder(role);
 
   // Fallback for custom roles
-  return buildGenericPrompt(roleId, role);
+  return buildGenericPrompt(roleId, role, scaffoldContext);
 }
 
 function buildPmPrompt(role) {
@@ -351,7 +351,66 @@ If you cannot resolve the deadlock:
 `;
 }
 
-function buildGenericPrompt(roleId, role) {
+function summarizeRoleWorkflow(roleId, scaffoldContext = {}) {
+  const routing = scaffoldContext.routing || {};
+  const gates = scaffoldContext.gates || {};
+  const workflowKitConfig = scaffoldContext.workflowKitConfig || {};
+  const ownedPhases = Object.entries(routing)
+    .filter(([, route]) => route?.entry_role === roleId)
+    .map(([phaseName]) => phaseName);
+  const gateLines = [];
+  const artifactLines = [];
+  const ownershipLines = [];
+
+  for (const phaseName of ownedPhases) {
+    const exitGate = routing[phaseName]?.exit_gate;
+    if (exitGate) {
+      gateLines.push(`- ${phaseName}: ${exitGate}`);
+    }
+
+    const phaseArtifacts = Array.isArray(workflowKitConfig?.phases?.[phaseName]?.artifacts)
+      ? workflowKitConfig.phases[phaseName].artifacts.filter((artifact) => artifact?.path)
+      : [];
+    const workflowArtifacts = phaseArtifacts
+      .map((artifact) => artifact.path)
+      .filter(Boolean);
+    const gateArtifacts = Array.isArray(gates?.[exitGate]?.requires_files)
+      ? gates[exitGate].requires_files.filter(Boolean)
+      : [];
+    const ownedArtifacts = [...new Set([...workflowArtifacts, ...gateArtifacts])];
+    if (ownedArtifacts.length > 0) {
+      artifactLines.push(`- ${phaseName}: ${ownedArtifacts.join(', ')}`);
+    }
+
+    const enforcedArtifacts = phaseArtifacts
+      .filter((artifact) => artifact.owned_by === roleId)
+      .map((artifact) => artifact.path);
+    if (enforcedArtifacts.length > 0) {
+      const verb = enforcedArtifacts.length === 1 ? 'requires' : 'require';
+      ownershipLines.push(
+        `- ${phaseName}: ${enforcedArtifacts.join(', ')} ${verb} an accepted turn from you before the gate can pass`,
+      );
+    }
+  }
+
+  return { ownedPhases, gateLines, artifactLines, ownershipLines };
+}
+
+function buildGenericPrompt(roleId, role, scaffoldContext = {}) {
+  const workflowSummary = summarizeRoleWorkflow(roleId, scaffoldContext);
+  const primaryPhasesSection = workflowSummary.ownedPhases.length > 0
+    ? `\n## Primary Phases\n\n- ${workflowSummary.ownedPhases.join(', ')}\n`
+    : '';
+  const phaseGatesSection = workflowSummary.gateLines.length > 0
+    ? `\n## Phase Gates\n\n${workflowSummary.gateLines.join('\n')}\n`
+    : '';
+  const workflowArtifactsSection = workflowSummary.artifactLines.length > 0
+    ? `\n## Workflow Artifacts You Own\n\n${workflowSummary.artifactLines.join('\n')}\n`
+    : '';
+  const ownershipSection = workflowSummary.ownershipLines.length > 0
+    ? `\n## Ownership Enforcement\n\n${workflowSummary.ownershipLines.join('\n')}\n`
+    : '';
+
   return `# ${role.title} — Role Prompt
 
 You are the **${role.title}** on this project.
@@ -371,7 +430,7 @@ ${role.write_authority === 'authoritative'
     ? 'You may modify product files directly.'
     : role.write_authority === 'proposed'
       ? 'You may propose changes via patches.'
-      : 'You may NOT modify product files. Only create review artifacts under `.planning/` and `.agentxchain/reviews/`.'}
+      : 'You may NOT modify product files. Only create review artifacts under `.planning/` and `.agentxchain/reviews/`.'}${primaryPhasesSection}${phaseGatesSection}${workflowArtifactsSection}${ownershipSection}
 `;
 }
 
@@ -468,13 +527,115 @@ function generateWorkflowKitPlaceholder(artifact, projectName) {
   return `# ${title} — ${projectName}\n\n(Operator fills this in.)\n`;
 }
 
+function cloneJsonCompatible(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function buildScaffoldConfigFromTemplate(template, localDevRuntime, workflowKitConfig) {
+  const blueprint = template.scaffold_blueprint || null;
+  const roles = cloneJsonCompatible(blueprint?.roles || GOVERNED_ROLES);
+  const runtimes = cloneJsonCompatible(blueprint?.runtimes || GOVERNED_RUNTIMES);
+
+  if (!blueprint || Object.values(roles).some((role) => role?.runtime === 'local-dev')) {
+    runtimes['local-dev'] = localDevRuntime;
+  }
+
+  const routing = cloneJsonCompatible(blueprint?.routing || GOVERNED_ROUTING);
+  const gates = cloneJsonCompatible(blueprint?.gates || GOVERNED_GATES);
+  const effectiveWorkflowKitConfig = workflowKitConfig || cloneJsonCompatible(blueprint?.workflow_kit || null);
+  const prompts = Object.fromEntries(
+    Object.keys(roles).map((roleId) => [roleId, `.agentxchain/prompts/${roleId}.md`])
+  );
+
+  return {
+    roles,
+    runtimes,
+    routing,
+    gates,
+    prompts,
+    workflowKitConfig: effectiveWorkflowKitConfig,
+  };
+}
+
+const PHASE_DISPLAY_NAMES = Object.freeze({
+  qa: 'QA',
+});
+
+function formatPhaseDisplayName(phaseKey) {
+  if (PHASE_DISPLAY_NAMES[phaseKey]) {
+    return PHASE_DISPLAY_NAMES[phaseKey];
+  }
+  return phaseKey.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function buildRoadmapPhaseTable(routing, roles) {
+  const rows = Object.entries(routing).map(([phaseKey, phaseConfig]) => {
+    const phaseName = formatPhaseDisplayName(phaseKey);
+    const entryRole = phaseConfig.entry_role;
+    const role = roles[entryRole];
+    const goal = role?.mandate || phaseName;
+    const status = phaseKey === Object.keys(routing)[0] ? 'In progress' : 'Pending';
+    return `| ${phaseName} | ${goal} | ${status} |`;
+  });
+  return `| Phase | Goal | Status |\n|-------|------|--------|\n${rows.join('\n')}\n`;
+}
+
+function buildPlanningSummaryLines(template, workflowKitConfig) {
+  const lines = [
+    'PM_SIGNOFF.md / ROADMAP.md / SYSTEM_SPEC.md',
+    'acceptance-matrix.md / ship-verdict.md',
+    'RELEASE_NOTES.md',
+  ];
+  const templatePlanningFiles = Array.isArray(template?.planning_artifacts)
+    ? template.planning_artifacts
+      .map((artifact) => artifact?.filename)
+      .filter(Boolean)
+    : [];
+  const defaultScaffoldPaths = new Set([
+    '.planning/PM_SIGNOFF.md',
+    '.planning/ROADMAP.md',
+    '.planning/SYSTEM_SPEC.md',
+    '.planning/IMPLEMENTATION_NOTES.md',
+    '.planning/acceptance-matrix.md',
+    '.planning/ship-verdict.md',
+    '.planning/RELEASE_NOTES.md',
+  ]);
+  const customWorkflowFiles = [];
+
+  if (workflowKitConfig?.phases && typeof workflowKitConfig.phases === 'object') {
+    for (const phaseConfig of Object.values(workflowKitConfig.phases)) {
+      if (!Array.isArray(phaseConfig?.artifacts)) continue;
+      for (const artifact of phaseConfig.artifacts) {
+        if (!artifact?.path || defaultScaffoldPaths.has(artifact.path)) continue;
+        customWorkflowFiles.push(basename(artifact.path));
+      }
+    }
+  }
+
+  if (templatePlanningFiles.length > 0) {
+    lines.push(`template: ${templatePlanningFiles.join(' / ')}`);
+  }
+  const uniqueCustomWorkflowFiles = [...new Set(customWorkflowFiles)];
+  if (uniqueCustomWorkflowFiles.length > 0) {
+    lines.push(`workflow: ${uniqueCustomWorkflowFiles.join(' / ')}`);
+  }
+
+  return lines;
+}
+
 export function scaffoldGoverned(dir, projectName, projectId, templateId = 'generic', runtimeOptions = {}, workflowKitConfig = null) {
   const template = loadGovernedTemplate(templateId);
   const { runtime: localDevRuntime } = resolveGovernedLocalDevRuntime(runtimeOptions);
-  const runtimes = {
-    ...GOVERNED_RUNTIMES,
-    'local-dev': localDevRuntime,
-  };
+  const scaffoldConfig = buildScaffoldConfigFromTemplate(template, localDevRuntime, workflowKitConfig);
+  const { roles, runtimes, routing, gates, prompts, workflowKitConfig: effectiveWorkflowKitConfig } = scaffoldConfig;
+  const initialPhase = Object.keys(routing)[0] || 'planning';
+  const phaseGateStatus = Object.fromEntries(
+    [...new Set(
+      Object.values(routing)
+        .map((route) => route?.exit_gate)
+        .filter(Boolean)
+    )].map((gateId) => [gateId, 'pending'])
+  );
   const config = {
     schema_version: '1.0',
     template: template.id,
@@ -483,10 +644,10 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
       name: projectName,
       default_branch: 'main'
     },
-    roles: GOVERNED_ROLES,
+    roles,
     runtimes,
-    routing: GOVERNED_ROUTING,
-    gates: GOVERNED_GATES,
+    routing,
+    gates,
     budget: {
       per_turn_max_usd: 2.0,
       per_run_max_usd: 50.0,
@@ -496,25 +657,23 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
       talk_strategy: 'append_only',
       history_strategy: 'jsonl_append_only'
     },
-    prompts: {
-      pm: '.agentxchain/prompts/pm.md',
-      dev: '.agentxchain/prompts/dev.md',
-      qa: '.agentxchain/prompts/qa.md',
-      eng_director: '.agentxchain/prompts/eng_director.md'
-    },
+    prompts,
     rules: {
       challenge_required: true,
       max_turn_retries: 2,
       max_deadlock_cycles: 2
     }
   };
+  if (effectiveWorkflowKitConfig) {
+    config.workflow_kit = effectiveWorkflowKitConfig;
+  }
 
   const state = {
     schema_version: '1.1',
     run_id: null,
     project_id: projectId,
     status: 'idle',
-    phase: 'planning',
+    phase: initialPhase,
     accepted_integration_ref: null,
     active_turns: {},
     turn_sequence: 0,
@@ -524,11 +683,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
     escalation: null,
     queued_phase_transition: null,
     queued_run_completion: null,
-    phase_gate_status: {
-      planning_signoff: 'pending',
-      implementation_complete: 'pending',
-      qa_ship_verdict: 'pending'
-    },
+    phase_gate_status: phaseGateStatus,
     budget_reservations: {},
     budget_status: {
       spent_usd: 0,
@@ -550,15 +705,19 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
   writeFileSync(join(dir, '.agentxchain', 'decision-ledger.jsonl'), '');
 
   // Prompt templates
-  for (const [roleId, role] of Object.entries(GOVERNED_ROLES)) {
-    const basePrompt = buildGovernedPrompt(roleId, role);
+  for (const [roleId, role] of Object.entries(roles)) {
+    const basePrompt = buildGovernedPrompt(roleId, role, {
+      routing,
+      gates,
+      workflowKitConfig: effectiveWorkflowKitConfig,
+    });
     const prompt = appendPromptOverride(basePrompt, template.prompt_overrides?.[roleId]);
     writeFileSync(join(dir, '.agentxchain', 'prompts', `${roleId}.md`), prompt);
   }
 
   // Planning artifacts
   writeFileSync(join(dir, '.planning', 'PM_SIGNOFF.md'), `# PM Signoff — ${projectName}\n\nApproved: NO\n\n> This scaffold starts blocked on purpose. Change this to \`Approved: YES\` only after a human reviews the planning artifacts and is ready to open the planning gate.\n\n## Discovery Checklist\n- [ ] Target user defined\n- [ ] Core pain point defined\n- [ ] Core workflow defined\n- [ ] MVP scope defined\n- [ ] Out-of-scope list defined\n- [ ] Success metric defined\n\n## Notes for team\n(PM and human add final kickoff notes here.)\n`);
-  writeFileSync(join(dir, '.planning', 'ROADMAP.md'), `# Roadmap — ${projectName}\n\n## Phases\n\n| Phase | Goal | Status |\n|-------|------|--------|\n| Planning | Align scope, requirements, acceptance criteria | In progress |\n| Implementation | Build and verify | Pending |\n| QA | Challenge correctness and ship readiness | Pending |\n`);
+  writeFileSync(join(dir, '.planning', 'ROADMAP.md'), `# Roadmap — ${projectName}\n\n## Phases\n\n${buildRoadmapPhaseTable(routing, roles)}`);
   writeFileSync(join(dir, '.planning', 'SYSTEM_SPEC.md'), buildSystemSpecContent(projectName, template.system_spec_overlay));
   writeFileSync(join(dir, '.planning', '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`);
   const baseAcceptanceMatrix = `# Acceptance Matrix — ${projectName}\n\n| Req # | Requirement | Acceptance criteria | Test status | Last tested | Status |\n|-------|-------------|-------------------|-------------|-------------|--------|\n| (QA fills this from ROADMAP.md) | | | | | |\n`;
@@ -577,7 +736,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 (workflowKitConfig && workflowKitConfig.phases && typeof workflowKitConfig.phases === 'object') {
+  if (effectiveWorkflowKitConfig && effectiveWorkflowKitConfig.phases && typeof effectiveWorkflowKitConfig.phases === 'object') {
     const defaultScaffoldPaths = new Set([
       '.planning/PM_SIGNOFF.md',
       '.planning/ROADMAP.md',
@@ -588,7 +747,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
       '.planning/RELEASE_NOTES.md',
     ]);
 
-    for (const phaseConfig of Object.values(workflowKitConfig.phases)) {
+    for (const phaseConfig of Object.values(effectiveWorkflowKitConfig.phases)) {
       if (!Array.isArray(phaseConfig.artifacts)) continue;
       for (const artifact of phaseConfig.artifacts) {
         if (!artifact.path || defaultScaffoldPaths.has(artifact.path)) continue;
@@ -629,6 +788,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
 async function initGoverned(opts) {
   let projectName, folderName;
   const templateId = opts.template || 'generic';
+  let selectedTemplate;
   let explicitDir;
 
   try {
@@ -649,6 +809,7 @@ async function initGoverned(opts) {
     console.error('    web-app       Governed scaffold for a web application');
     process.exit(1);
   }
+  selectedTemplate = loadGovernedTemplate(templateId);
 
   if (opts.yes) {
     projectName = explicitDir
@@ -721,47 +882,54 @@ async function initGoverned(opts) {
     }
   }
 
-  scaffoldGoverned(dir, projectName, projectId, templateId, opts, workflowKitConfig);
+  const { config } = scaffoldGoverned(dir, projectName, projectId, templateId, opts, workflowKitConfig);
 
   console.log('');
   console.log(chalk.green(`  ✓ Created governed project ${chalk.bold(targetLabel)}/`));
   console.log('');
+  const promptRoleIds = Object.keys(config.roles);
+  const phaseNames = Object.keys(config.routing);
   console.log(`    ${chalk.dim('├──')} agentxchain.json  ${chalk.dim('(governed)')}`);
   console.log(`    ${chalk.dim('├──')} .agentxchain/`);
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} state.json / history.jsonl / decision-ledger.jsonl`);
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} staging/`);
-  console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} prompts/  ${chalk.dim('(pm, dev, qa, eng_director)')}`);
+  console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} prompts/  ${chalk.dim(`(${promptRoleIds.join(', ')})`)}`);
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} reviews/`);
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('└──')} dispatch/`);
   console.log(`    ${chalk.dim('├──')} .planning/`);
-  console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} PM_SIGNOFF.md / ROADMAP.md / SYSTEM_SPEC.md`);
-  console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} acceptance-matrix.md / ship-verdict.md`);
-  console.log(`    ${chalk.dim('│')}    ${chalk.dim('└──')} RELEASE_NOTES.md`);
+  const planningSummaryLines = buildPlanningSummaryLines(selectedTemplate, config.workflow_kit);
+  for (const [index, line] of planningSummaryLines.entries()) {
+    const branch = index === planningSummaryLines.length - 1 ? '└──' : '├──';
+    console.log(`    ${chalk.dim('│')}    ${chalk.dim(branch)} ${line}`);
+  }
   console.log(`    ${chalk.dim('└──')} TALK.md`);
   console.log('');
-  console.log(`  ${chalk.dim('Roles:')} pm, dev, qa, eng_director`);
-  console.log(`  ${chalk.dim('Phases:')} planning → implementation → qa ${chalk.dim('(default; extend via routing in agentxchain.json)')}`);
+  console.log(`  ${chalk.dim('Roles:')} ${promptRoleIds.join(', ')}`);
+  console.log(`  ${chalk.dim('Phases:')} ${phaseNames.join(' → ')} ${chalk.dim(selectedTemplate.scaffold_blueprint ? '(template-defined; edit routing in agentxchain.json to customize)' : '(default; extend via routing in agentxchain.json)')}`);
   console.log(`  ${chalk.dim('Template:')} ${templateId}`);
   console.log(`  ${chalk.dim('Dev runtime:')} ${formatGovernedRuntimeCommand(localDevRuntime)} ${chalk.dim(`(${localDevRuntime.prompt_transport})`)}`);
   console.log(`  ${chalk.dim('Protocol:')} governed convergence`);
   console.log('');
 
   // Readiness hint: tell user which roles work immediately vs which need API keys
-  const allRuntimes = { ...GOVERNED_RUNTIMES, 'local-dev': localDevRuntime };
-  const needsKey = Object.entries(allRuntimes)
-    .filter(([, rt]) => rt.auth_env)
-    .map(([id, rt]) => ({ id, env: rt.auth_env }));
-  if (needsKey.length > 0) {
-    const envVars = [...new Set(needsKey.map(r => r.env))];
-    const roleNames = needsKey.map(r => r.id);
+  const allRuntimes = config.runtimes;
+  const manualRoleIds = Object.entries(config.roles)
+    .filter(([, role]) => allRuntimes[role.runtime]?.type === 'manual')
+    .map(([roleId]) => roleId);
+  const rolesNeedingKeys = Object.entries(config.roles)
+    .filter(([, role]) => Boolean(allRuntimes[role.runtime]?.auth_env))
+    .map(([roleId, role]) => ({ roleId, env: allRuntimes[role.runtime].auth_env }));
+  if (rolesNeedingKeys.length > 0) {
+    const envVars = [...new Set(rolesNeedingKeys.map((r) => r.env))];
+    const roleNames = rolesNeedingKeys.map((r) => r.roleId);
     const hasKeys = envVars.every(v => process.env[v]);
     if (hasKeys) {
       console.log(`  ${chalk.green('Ready:')} all runtimes configured (${envVars.join(', ')} detected)`);
     } else {
-      console.log(`  ${chalk.yellow('Mixed-mode:')} pm and eng_director work immediately (manual).`);
+      console.log(`  ${chalk.yellow('Mixed-mode:')} ${manualRoleIds.join(', ')} work immediately (manual).`);
       console.log(`  ${chalk.yellow('  ')}${roleNames.join(', ')} need ${chalk.bold(envVars.join(', '))} to dispatch automatically.`);
       console.log(`  ${chalk.yellow('  ')}Without it, those turns fall back to manual input.`);
-      if (allRuntimes['manual-qa']) {
+      if (config.roles?.qa?.runtime === 'api-qa' && allRuntimes['manual-qa']) {
         console.log(`  ${chalk.yellow('  ')}No-key QA path: change ${chalk.bold('roles.qa.runtime')} from ${chalk.bold('"api-qa"')} to ${chalk.bold('"manual-qa"')} in ${chalk.bold('agentxchain.json')}.`);
       }
     }

package/src/commands/template-list.js

@@ -10,6 +10,7 @@ export function templateListCommand(opts) {
       description: t.description,
       planning_artifacts: (t.planning_artifacts || []).map((a) => a.filename),
       prompt_overrides: Object.keys(t.prompt_overrides || {}),
+      scaffold_blueprint_roles: Object.keys(t.scaffold_blueprint?.roles || {}),
       acceptance_hints: t.acceptance_hints || [],
     }));
     console.log(JSON.stringify(output, null, 2));
@@ -27,6 +28,9 @@ export function templateListCommand(opts) {
     if (t.prompt_overrides && Object.keys(t.prompt_overrides).length > 0) {
       console.log(`    Prompt overrides: ${Object.keys(t.prompt_overrides).join(', ')}`);
     }
+    if (t.scaffold_blueprint?.roles && Object.keys(t.scaffold_blueprint.roles).length > 0) {
+      console.log(`    Scaffold roles: ${Object.keys(t.scaffold_blueprint.roles).join(', ')}`);
+    }
     console.log('');
   }
   console.log(chalk.dim(`  Usage: agentxchain template set <id>\n`));

package/src/commands/template-set.js

@@ -64,6 +64,12 @@ export async function templateSetCommand(templateId, opts) {
 
   // ── Load manifest ─────────────────────────────────────────────────────
   const manifest = loadGovernedTemplate(templateId);
+  if (manifest.scaffold_blueprint) {
+    console.error(chalk.red(`  Error: Template "${templateId}" defines a custom governed team blueprint.`));
+    console.error(chalk.yellow(`  Use ${chalk.bold(`agentxchain init --governed --template ${templateId}`)} for new repos.`));
+    console.error(chalk.yellow('  Retrofitting an existing repo to a blueprint-backed team is deferred until a dedicated migrator exists.'));
+    process.exit(1);
+  }
   const projectName = config.project?.name || 'Untitled';
 
   // ── Build mutation plan ───────────────────────────────────────────────

package/src/lib/adapters/manual-adapter.js

@@ -105,7 +105,7 @@ function getPhaseGateHints(phase, roleId, config) {
     hints.push('.planning/IMPLEMENTATION_NOTES.md — record what you built and how to verify');
   } else if (phase === 'qa' && (roleId === 'qa' || roleId === 'human')) {
     hints.push('.planning/acceptance-matrix.md — mark each requirement PASS/FAIL');
-    hints.push('.planning/ship-verdict.md — change "## Verdict: PENDING" → "## Verdict: SHIP"');
+    hints.push('.planning/ship-verdict.md — change "## Verdict: PENDING" → "## Verdict: YES"');
     hints.push('.planning/RELEASE_NOTES.md — user impact, verification summary, upgrade notes');
   }
 

package/src/lib/gate-evaluator.js

@@ -54,10 +54,15 @@ function buildEffectiveGateArtifacts(config, gateDef, phase) {
       required: false,
       useLegacySemantics: false,
       semanticChecks: [],
+      owned_by: null,
     };
 
     existing.required = existing.required || artifact.required !== false;
 
+    if (artifact.owned_by && typeof artifact.owned_by === 'string') {
+      existing.owned_by = artifact.owned_by;
+    }
+
     if (artifact.semantics) {
       const legacySemanticId = existing.useLegacySemantics ? getSemanticIdForPath(artifact.path) : null;
       if (artifact.semantics !== legacySemanticId) {
@@ -87,7 +92,17 @@ function prefixSemanticReason(filePath, reason) {
   return `${filePath}: ${reason}`;
 }
 
-function evaluateGateArtifacts({ root, config, gateDef, phase, result }) {
+function hasRoleParticipationInPhase(state, phase, roleId) {
+  const history = state?.history;
+  if (!Array.isArray(history)) {
+    return false;
+  }
+  return history.some(
+    turn => turn.phase === phase && turn.role === roleId,
+  );
+}
+
+function evaluateGateArtifacts({ root, config, gateDef, phase, result, state }) {
   const failures = [];
   const artifacts = buildEffectiveGateArtifacts(config, gateDef, phase);
 
@@ -118,6 +133,13 @@ function evaluateGateArtifacts({ root, config, gateDef, phase, result }) {
         failures.push(prefixSemanticReason(artifact.path, semanticCheck.reason));
       }
     }
+
+    // Charter enforcement: verify owning role participated in this phase
+    if (artifact.owned_by && !hasRoleParticipationInPhase(state, phase, artifact.owned_by)) {
+      failures.push(
+        `"${artifact.path}" requires participation from role "${artifact.owned_by}" in phase "${phase}", but no accepted turn from that role was found`,
+      );
+    }
   }
 
   return failures;
@@ -219,13 +241,14 @@ export function evaluatePhaseExit({ state, config, acceptedTurn, root }) {
 
   const failures = [];
 
-  // Predicate: requires_files
+  // Predicate: requires_files + ownership
   failures.push(...evaluateGateArtifacts({
     root,
     config,
     gateDef,
     phase: currentPhase,
     result,
+    state,
   }));
 
   // Predicate: requires_verification_pass
@@ -341,6 +364,7 @@ export function evaluateRunCompletion({ state, config, acceptedTurn, root }) {
     gateDef,
     phase: currentPhase,
     result,
+    state,
   }));
 
   if (gateDef.requires_verification_pass) {

package/src/lib/governed-state.js

@@ -2129,6 +2129,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     turn_id: turnResult.turn_id,
     run_id: turnResult.run_id,
     role: turnResult.role,
+    phase: state.phase,
     runtime_id: turnResult.runtime_id,
     status: turnResult.status,
     summary: turnResult.summary,
@@ -2280,12 +2281,13 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         };
       }
     } else {
+      const nextHistoryEntries = [...historyEntries, historyEntry];
       const postAcceptanceState = {
         ...state,
         active_turns: remainingTurns,
         turn_sequence: acceptedSequence,
+        history: nextHistoryEntries,
       };
-      const nextHistoryEntries = [...historyEntries, historyEntry];
       const completionSource = turnResult.run_completion_request
         ? turnResult
         : findHistoryTurnRequest(nextHistoryEntries, state.queued_run_completion?.requested_by_turn, 'run_completion');

package/src/lib/governed-templates.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { validateV4Config } from './normalized-config.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -11,9 +12,10 @@ export const VALID_GOVERNED_TEMPLATE_IDS = Object.freeze([
   'cli-tool',
   'library',
   'web-app',
+  'enterprise-app',
 ]);
 
-const VALID_PROMPT_OVERRIDE_ROLES = new Set(['pm', 'dev', 'qa', 'eng_director']);
+const VALID_ROLE_ID_PATTERN = /^[a-z0-9_-]+$/;
 
 function validatePlanningArtifacts(artifacts, errors) {
   if (!Array.isArray(artifacts)) {
@@ -50,8 +52,8 @@ function validatePromptOverrides(promptOverrides, errors) {
   }
 
   for (const [roleId, content] of Object.entries(promptOverrides)) {
-    if (!VALID_PROMPT_OVERRIDE_ROLES.has(roleId)) {
-      errors.push(`prompt_overrides contains unknown role "${roleId}"`);
+    if (!VALID_ROLE_ID_PATTERN.test(roleId)) {
+      errors.push(`prompt_overrides contains invalid role ID "${roleId}" (must match ${VALID_ROLE_ID_PATTERN})`);
     }
     if (typeof content !== 'string' || !content.trim()) {
       errors.push(`prompt_overrides["${roleId}"] must be a non-empty string`);
@@ -73,6 +75,47 @@ function validateAcceptanceHints(acceptanceHints, errors) {
   }
 }
 
+const VALID_SCAFFOLD_BLUEPRINT_KEYS = new Set([
+  'roles',
+  'runtimes',
+  'routing',
+  'gates',
+  'workflow_kit',
+]);
+
+function validateScaffoldBlueprint(scaffoldBlueprint, errors) {
+  if (scaffoldBlueprint === undefined) return;
+  if (!scaffoldBlueprint || typeof scaffoldBlueprint !== 'object' || Array.isArray(scaffoldBlueprint)) {
+    errors.push('scaffold_blueprint must be an object when provided');
+    return;
+  }
+
+  for (const key of Object.keys(scaffoldBlueprint)) {
+    if (!VALID_SCAFFOLD_BLUEPRINT_KEYS.has(key)) {
+      errors.push(`scaffold_blueprint contains unknown key "${key}"`);
+    }
+  }
+
+  const validation = validateV4Config({
+    schema_version: '1.0',
+    project: {
+      id: 'template-manifest',
+      name: 'Template Manifest',
+    },
+    roles: scaffoldBlueprint.roles,
+    runtimes: scaffoldBlueprint.runtimes,
+    routing: scaffoldBlueprint.routing,
+    gates: scaffoldBlueprint.gates,
+    workflow_kit: scaffoldBlueprint.workflow_kit,
+  });
+
+  if (!validation.ok) {
+    for (const error of validation.errors) {
+      errors.push(`scaffold_blueprint ${error}`);
+    }
+  }
+}
+
 const VALID_SPEC_OVERLAY_KEYS = new Set([
   'purpose_guidance',
   'interface_guidance',
@@ -138,6 +181,7 @@ export function validateGovernedTemplateManifest(manifest, expectedId = null) {
   validatePromptOverrides(manifest.prompt_overrides, errors);
   validateAcceptanceHints(manifest.acceptance_hints, errors);
   validateSystemSpecOverlay(manifest.system_spec_overlay, errors);
+  validateScaffoldBlueprint(manifest.scaffold_blueprint, errors);
 
   return { ok: errors.length === 0, errors };
 }

package/src/lib/normalized-config.js

@@ -472,7 +472,7 @@ export function validateV4Config(data, projectRoot) {
 
   // Workflow Kit (optional but validated if present)
   if (data.workflow_kit !== undefined) {
-    const wkValidation = validateWorkflowKitConfig(data.workflow_kit, data.routing);
+    const wkValidation = validateWorkflowKitConfig(data.workflow_kit, data.routing, data.roles);
     errors.push(...wkValidation.errors);
   }
 
@@ -483,7 +483,7 @@ export function validateV4Config(data, projectRoot) {
  * Validate the workflow_kit config section.
  * Returns { ok, errors, warnings }.
  */
-export function validateWorkflowKitConfig(wk, routing) {
+export function validateWorkflowKitConfig(wk, routing, roles) {
   const errors = [];
   const warnings = [];
 
@@ -574,6 +574,16 @@ export function validateWorkflowKitConfig(wk, routing) {
         if (artifact.required !== undefined && typeof artifact.required !== 'boolean') {
           errors.push(`${prefix} required must be a boolean`);
         }
+
+        if (artifact.owned_by !== undefined && artifact.owned_by !== null) {
+          if (typeof artifact.owned_by !== 'string') {
+            errors.push(`${prefix} owned_by must be a string`);
+          } else if (!/^[a-z0-9_-]+$/.test(artifact.owned_by)) {
+            errors.push(`${prefix} owned_by "${artifact.owned_by}" is not a valid role ID (must be lowercase alphanumeric with hyphens/underscores)`);
+          } else if (roles && typeof roles === 'object' && !roles[artifact.owned_by]) {
+            errors.push(`${prefix} owned_by "${artifact.owned_by}" does not reference a defined role`);
+          }
+        }
       }
     }
   }
@@ -791,6 +801,7 @@ export function normalizeWorkflowKit(raw, routingPhases) {
           path: a.path,
           semantics: a.semantics || null,
           semantics_config: a.semantics_config || null,
+          owned_by: a.owned_by || null,
           required: a.required !== false,
         })),
       };

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

@@ -0,0 +1,195 @@
+{
+  "id": "enterprise-app",
+  "display_name": "Enterprise App",
+  "description": "Governed scaffold for multi-role product delivery with explicit architecture and security-review phases.",
+  "version": "1",
+  "protocol_compatibility": ["1.0", "1.1"],
+  "planning_artifacts": [
+    {
+      "filename": "integration-boundaries.md",
+      "content_template": "# Integration Boundaries — {{project_name}}\n\n## Systems And Owners\n| System | Owner | Dependency type | Contract |\n|--------|-------|-----------------|----------|\n| | | | |\n\n## Cross-Team Dependencies\n- External approvals required:\n- Deployment dependencies:\n- Data-sharing constraints:\n"
+    },
+    {
+      "filename": "data-classification.md",
+      "content_template": "# Data Classification — {{project_name}}\n\n## Data Types\n| Data type | Sensitivity | Storage boundary | Notes |\n|-----------|-------------|------------------|-------|\n| | | | |\n\n## Compliance Constraints\n- Retention requirements:\n- Encryption expectations:\n- Audit obligations:\n"
+    },
+    {
+      "filename": "risk-register.md",
+      "content_template": "# Risk Register — {{project_name}}\n\n## Delivery Risks\n| Risk | Likelihood | Impact | Mitigation | Owner |\n|------|------------|--------|------------|-------|\n| | | | | |\n\n## Ship Blockers\n- Blocking risk thresholds:\n- Conditions for mitigated ship:\n"
+    }
+  ],
+  "prompt_overrides": {
+    "pm": "Drive cross-functional clarity early. Enterprise delivery fails when integration owners, rollout boundaries, or security obligations are left implicit.",
+    "architect": "Own the architecture phase. Make interface boundaries, data flow, and trade-offs explicit before dev starts implementation.",
+    "dev": "Treat integration safety, data handling, and architecture drift as first-class delivery risks. Do not bypass the architecture or security contracts.",
+    "security_reviewer": "Threat-model the shipped change, record findings explicitly, and block progression when risks are unresolved or undocumented.",
+    "qa": "Do not sign off until the architecture and security-review artifacts agree with the shipped behavior and verification evidence."
+  },
+  "acceptance_hints": [
+    "Architecture decisions reviewed before implementation started",
+    "Security review findings closed or explicitly accepted",
+    "Integration boundaries and rollout risks documented before ship request"
+  ],
+  "system_spec_overlay": {
+    "purpose_guidance": "Describe the enterprise workflow, the internal or external users it serves, and why this product needs governed multi-role delivery instead of a simple feature implementation.",
+    "interface_guidance": "List the product boundaries, key integrations, data flows, and authority handoffs. Reference integration-boundaries.md for the cross-system contract.",
+    "behavior_guidance": "Describe the expected system behavior across architecture, implementation, and security-review concerns. Include deployment and rollback assumptions.",
+    "error_cases_guidance": "List integration failures, auth or entitlement risks, rollout hazards, and security findings that would block release. Reference risk-register.md for mitigation expectations.",
+    "acceptance_tests_guidance": "- [ ] Architecture artifact documents boundaries and trade-offs\n- [ ] Security review captures findings and explicit verdict\n- [ ] Verification covers critical user and integration paths\n- [ ] Rollout or mitigation plan is documented before ship approval"
+  },
+  "scaffold_blueprint": {
+    "roles": {
+      "pm": {
+        "title": "Product Manager",
+        "mandate": "Protect scope clarity, user value, and cross-functional delivery readiness.",
+        "write_authority": "review_only",
+        "runtime": "manual-pm"
+      },
+      "architect": {
+        "title": "Architect",
+        "mandate": "Define the system boundary, integration contracts, and technical trade-offs before implementation commits to a design.",
+        "write_authority": "review_only",
+        "runtime": "manual-architect"
+      },
+      "dev": {
+        "title": "Developer",
+        "mandate": "Implement approved work safely and verify behavior.",
+        "write_authority": "authoritative",
+        "runtime": "local-dev"
+      },
+      "security_reviewer": {
+        "title": "Security Reviewer",
+        "mandate": "Challenge data handling, auth boundaries, and exploit paths before work proceeds to final QA.",
+        "write_authority": "review_only",
+        "runtime": "manual-security"
+      },
+      "qa": {
+        "title": "QA",
+        "mandate": "Challenge correctness, acceptance coverage, and ship readiness.",
+        "write_authority": "review_only",
+        "runtime": "api-qa"
+      },
+      "eng_director": {
+        "title": "Engineering Director",
+        "mandate": "Resolve tactical deadlocks and enforce technical coherence.",
+        "write_authority": "review_only",
+        "runtime": "manual-director"
+      }
+    },
+    "runtimes": {
+      "manual-pm": { "type": "manual" },
+      "local-dev": {
+        "type": "local_cli",
+        "command": ["claude", "--print", "--dangerously-skip-permissions"],
+        "cwd": ".",
+        "prompt_transport": "stdin"
+      },
+      "api-qa": {
+        "type": "api_proxy",
+        "provider": "anthropic",
+        "model": "claude-sonnet-4-6",
+        "auth_env": "ANTHROPIC_API_KEY"
+      },
+      "manual-qa": { "type": "manual" },
+      "manual-architect": { "type": "manual" },
+      "manual-security": { "type": "manual" },
+      "manual-director": { "type": "manual" }
+    },
+    "routing": {
+      "planning": {
+        "entry_role": "pm",
+        "allowed_next_roles": ["pm", "architect", "eng_director", "human"],
+        "exit_gate": "planning_signoff"
+      },
+      "architecture": {
+        "entry_role": "architect",
+        "allowed_next_roles": ["architect", "dev", "pm", "eng_director", "human"],
+        "exit_gate": "architecture_review"
+      },
+      "implementation": {
+        "entry_role": "dev",
+        "allowed_next_roles": ["dev", "security_reviewer", "qa", "architect", "eng_director", "human"],
+        "exit_gate": "implementation_complete"
+      },
+      "security_review": {
+        "entry_role": "security_reviewer",
+        "allowed_next_roles": ["dev", "qa", "architect", "eng_director", "human"],
+        "exit_gate": "security_review_signoff"
+      },
+      "qa": {
+        "entry_role": "qa",
+        "allowed_next_roles": ["dev", "qa", "eng_director", "human"],
+        "exit_gate": "qa_ship_verdict"
+      }
+    },
+    "gates": {
+      "planning_signoff": {
+        "requires_files": [".planning/PM_SIGNOFF.md", ".planning/ROADMAP.md", ".planning/SYSTEM_SPEC.md"],
+        "requires_human_approval": true
+      },
+      "architecture_review": {
+        "requires_files": [".planning/ARCHITECTURE.md"]
+      },
+      "implementation_complete": {
+        "requires_files": [".planning/IMPLEMENTATION_NOTES.md"],
+        "requires_verification_pass": true
+      },
+      "security_review_signoff": {
+        "requires_files": [".planning/SECURITY_REVIEW.md"]
+      },
+      "qa_ship_verdict": {
+        "requires_files": [".planning/acceptance-matrix.md", ".planning/ship-verdict.md", ".planning/RELEASE_NOTES.md"],
+        "requires_human_approval": true
+      }
+    },
+    "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 }
+          ]
+        },
+        "architecture": {
+          "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 }
+          ]
+        },
+        "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 }
+          ]
+        }
+      }
+    }
+  }
+}