agentxchain 2.25.1 → 2.26.0

package/src/lib/gate-evaluator.js

@@ -19,7 +19,131 @@
 
 import { existsSync } from 'fs';
 import { join } from 'path';
-import { evaluateWorkflowGateSemantics } from './workflow-gate-semantics.js';
+import {
+  evaluateArtifactSemantics,
+  evaluateWorkflowGateSemantics,
+  getSemanticIdForPath,
+} from './workflow-gate-semantics.js';
+
+function getWorkflowArtifactsForPhase(config, phase) {
+  const artifacts = config?.workflow_kit?.phases?.[phase]?.artifacts;
+  return Array.isArray(artifacts) ? artifacts : [];
+}
+
+function buildEffectiveGateArtifacts(config, gateDef, phase) {
+  const byPath = new Map();
+
+  if (Array.isArray(gateDef?.requires_files)) {
+    for (const filePath of gateDef.requires_files) {
+      byPath.set(filePath, {
+        path: filePath,
+        required: true,
+        useLegacySemantics: true,
+        semanticChecks: [],
+      });
+    }
+  }
+
+  for (const artifact of getWorkflowArtifactsForPhase(config, phase)) {
+    if (!artifact?.path) {
+      continue;
+    }
+
+    const existing = byPath.get(artifact.path) || {
+      path: artifact.path,
+      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) {
+        existing.semanticChecks.push({
+          semantics: artifact.semantics,
+          semantics_config: artifact.semantics_config || null,
+        });
+      }
+    }
+
+    byPath.set(artifact.path, existing);
+  }
+
+  return [...byPath.values()];
+}
+
+function addMissingFile(result, filePath) {
+  if (!result.missing_files.includes(filePath)) {
+    result.missing_files.push(filePath);
+  }
+}
+
+function prefixSemanticReason(filePath, reason) {
+  if (!reason || reason.includes(filePath)) {
+    return reason;
+  }
+  return `${filePath}: ${reason}`;
+}
+
+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);
+
+  for (const artifact of artifacts) {
+    const absPath = join(root, artifact.path);
+    if (!existsSync(absPath)) {
+      if (artifact.required) {
+        addMissingFile(result, artifact.path);
+        failures.push(`Required file missing: ${artifact.path}`);
+      }
+      continue;
+    }
+
+    if (artifact.useLegacySemantics) {
+      const semanticCheck = evaluateWorkflowGateSemantics(root, artifact.path);
+      if (semanticCheck && !semanticCheck.ok) {
+        failures.push(semanticCheck.reason);
+      }
+    }
+
+    for (const semantic of artifact.semanticChecks) {
+      const semanticCheck = evaluateArtifactSemantics(root, {
+        path: artifact.path,
+        semantics: semantic.semantics,
+        semantics_config: semantic.semantics_config,
+      });
+      if (semanticCheck && !semanticCheck.ok) {
+        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;
+}
 
 /**
  * Evaluate whether the current phase exit gate is satisfied.
@@ -117,21 +241,15 @@ export function evaluatePhaseExit({ state, config, acceptedTurn, root }) {
 
   const failures = [];
 
-  // Predicate: requires_files
-  if (gateDef.requires_files && Array.isArray(gateDef.requires_files)) {
-    for (const filePath of gateDef.requires_files) {
-      if (!existsSync(join(root, filePath))) {
-        result.missing_files.push(filePath);
-        failures.push(`Required file missing: ${filePath}`);
-        continue;
-      }
-
-      const semanticCheck = evaluateWorkflowGateSemantics(root, filePath);
-      if (semanticCheck && !semanticCheck.ok) {
-        failures.push(semanticCheck.reason);
-      }
-    }
-  }
+  // Predicate: requires_files + ownership
+  failures.push(...evaluateGateArtifacts({
+    root,
+    config,
+    gateDef,
+    phase: currentPhase,
+    result,
+    state,
+  }));
 
   // Predicate: requires_verification_pass
   if (gateDef.requires_verification_pass) {
@@ -240,20 +358,14 @@ export function evaluateRunCompletion({ state, config, acceptedTurn, root }) {
   const result = { ...baseResult, gate_id: gateId };
   const failures = [];
 
-  if (gateDef.requires_files && Array.isArray(gateDef.requires_files)) {
-    for (const filePath of gateDef.requires_files) {
-      if (!existsSync(join(root, filePath))) {
-        result.missing_files.push(filePath);
-        failures.push(`Required file missing: ${filePath}`);
-        continue;
-      }
-
-      const semanticCheck = evaluateWorkflowGateSemantics(root, filePath);
-      if (semanticCheck && !semanticCheck.ok) {
-        failures.push(semanticCheck.reason);
-      }
-    }
-  }
+  failures.push(...evaluateGateArtifacts({
+    root,
+    config,
+    gateDef,
+    phase: currentPhase,
+    result,
+    state,
+  }));
 
   if (gateDef.requires_verification_pass) {
     const verificationStatus = acceptedTurn.verification?.status;

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 };
 }
@@ -446,7 +490,26 @@ export function validateGovernedWorkflowKit(root, config = {}) {
   const gateRequiredFiles = uniqueStrings(
     Object.values(config?.gates || {}).flatMap((gate) => Array.isArray(gate?.requires_files) ? gate.requires_files : [])
   );
-  const requiredFiles = uniqueStrings([...GOVERNED_WORKFLOW_KIT_BASE_FILES, ...gateRequiredFiles]);
+
+  // Collect workflow-kit artifact paths from explicit config
+  const wkArtifactPaths = [];
+  const wk = config?.workflow_kit;
+  if (wk && wk.phases && typeof wk.phases === 'object') {
+    for (const phaseConfig of Object.values(wk.phases)) {
+      if (Array.isArray(phaseConfig.artifacts)) {
+        for (const a of phaseConfig.artifacts) {
+          if (a.path && a.required !== false) {
+            wkArtifactPaths.push(a.path);
+          }
+        }
+      }
+    }
+  }
+
+  const hasExplicitWorkflowKit = wk && wk._explicit === true;
+  const hasExplicitWorkflowKitArtifacts = hasExplicitWorkflowKit && Object.keys(wk.phases || {}).length > 0;
+  const baseFiles = hasExplicitWorkflowKit ? wkArtifactPaths : GOVERNED_WORKFLOW_KIT_BASE_FILES;
+  const requiredFiles = uniqueStrings([...baseFiles, ...gateRequiredFiles]);
   const present = [];
   const missing = [];
 
@@ -459,32 +522,38 @@ export function validateGovernedWorkflowKit(root, config = {}) {
     }
   }
 
-  const structuralChecks = GOVERNED_WORKFLOW_KIT_STRUCTURAL_CHECKS.map((check) => {
-    const absPath = join(root, check.file);
-    if (!existsSync(absPath)) {
+  // Build structural checks: from explicit workflow_kit semantics or hardcoded defaults
+  let structuralChecks;
+  if (hasExplicitWorkflowKit) {
+    structuralChecks = buildStructuralChecksFromWorkflowKit(root, wk, errors);
+  } else {
+    structuralChecks = GOVERNED_WORKFLOW_KIT_STRUCTURAL_CHECKS.map((check) => {
+      const absPath = join(root, check.file);
+      if (!existsSync(absPath)) {
+        return {
+          id: check.id,
+          file: check.file,
+          ok: false,
+          skipped: true,
+          description: check.description,
+        };
+      }
+
+      const content = readFileSync(absPath, 'utf8');
+      const ok = check.pattern.test(content);
+      if (!ok) {
+        errors.push(`Workflow kit file "${check.file}" must preserve its structural marker: ${check.description}.`);
+      }
+
       return {
         id: check.id,
         file: check.file,
-        ok: false,
-        skipped: true,
+        ok,
+        skipped: false,
         description: check.description,
       };
-    }
-
-    const content = readFileSync(absPath, 'utf8');
-    const ok = check.pattern.test(content);
-    if (!ok) {
-      errors.push(`Workflow kit file "${check.file}" must preserve its structural marker: ${check.description}.`);
-    }
-
-    return {
-      id: check.id,
-      file: check.file,
-      ok,
-      skipped: false,
-      description: check.description,
-    };
-  });
+    });
+  }
 
   return {
     ok: errors.length === 0,
@@ -498,6 +567,64 @@ export function validateGovernedWorkflowKit(root, config = {}) {
   };
 }
 
+function buildStructuralChecksFromWorkflowKit(root, wk, errors) {
+  const checks = [];
+  if (!wk.phases) return checks;
+
+  for (const [phase, phaseConfig] of Object.entries(wk.phases)) {
+    if (!Array.isArray(phaseConfig.artifacts)) continue;
+    for (const artifact of phaseConfig.artifacts) {
+      if (!artifact.semantics) continue;
+
+      if (artifact.semantics === 'section_check' && artifact.semantics_config?.required_sections?.length) {
+        for (const section of artifact.semantics_config.required_sections) {
+          const checkId = `wk_${phase}_${artifact.path.replace(/[^a-zA-Z0-9]/g, '_')}_section_${section.replace(/[^a-zA-Z0-9]/g, '_')}`;
+          const description = `${artifact.path} defines ${section}`;
+          const absPath = join(root, artifact.path);
+
+          if (!existsSync(absPath)) {
+            checks.push({ id: checkId, file: artifact.path, ok: false, skipped: true, description });
+            continue;
+          }
+
+          const content = readFileSync(absPath, 'utf8');
+          const ok = content.includes(section);
+          if (!ok) {
+            errors.push(`Workflow kit file "${artifact.path}" must contain section: ${section}.`);
+          }
+          checks.push({ id: checkId, file: artifact.path, ok, skipped: false, description });
+        }
+      } else if (artifact.semantics !== 'section_check') {
+        // Built-in semantic check — generate a structural check entry
+        const checkId = `wk_${phase}_${artifact.semantics}`;
+        const description = `${artifact.path} passes ${artifact.semantics} validation`;
+        const absPath = join(root, artifact.path);
+
+        if (!existsSync(absPath)) {
+          checks.push({ id: checkId, file: artifact.path, ok: false, skipped: true, description });
+          continue;
+        }
+
+        // For built-in validators, delegate to the hardcoded check if one exists
+        const hardcoded = GOVERNED_WORKFLOW_KIT_STRUCTURAL_CHECKS.find(c => c.file === artifact.path);
+        if (hardcoded) {
+          const content = readFileSync(absPath, 'utf8');
+          const ok = hardcoded.pattern.test(content);
+          if (!ok) {
+            errors.push(`Workflow kit file "${artifact.path}" must preserve its structural marker: ${hardcoded.description}.`);
+          }
+          checks.push({ id: checkId, file: artifact.path, ok, skipped: false, description: hardcoded.description });
+        } else {
+          // No hardcoded check for this semantic — mark as passing (runtime gate handles full validation)
+          checks.push({ id: checkId, file: artifact.path, ok: true, skipped: false, description });
+        }
+      }
+    }
+  }
+
+  return checks;
+}
+
 export const SYSTEM_SPEC_OVERLAY_SEPARATOR = '## Template-Specific Guidance';
 
 export function buildSystemSpecContent(projectName, overlay) {

package/src/lib/normalized-config.js

@@ -22,7 +22,29 @@ const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai'];
 export const VALID_PROMPT_TRANSPORTS = ['argv', 'stdin', 'dispatch_bundle_only'];
 const VALID_MCP_TRANSPORTS = ['stdio', 'streamable_http'];
 const DEFAULT_PHASES = ['planning', 'implementation', 'qa'];
+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',
@@ -448,9 +470,127 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...notificationValidation.errors);
   }
 
+  // Workflow Kit (optional but validated if present)
+  if (data.workflow_kit !== undefined) {
+    const wkValidation = validateWorkflowKitConfig(data.workflow_kit, data.routing, data.roles);
+    errors.push(...wkValidation.errors);
+  }
+
   return { ok: errors.length === 0, errors };
 }
 
+/**
+ * Validate the workflow_kit config section.
+ * Returns { ok, errors, warnings }.
+ */
+export function validateWorkflowKitConfig(wk, routing, roles) {
+  const errors = [];
+  const warnings = [];
+
+  if (wk === null || (typeof wk === 'object' && !Array.isArray(wk) && Object.keys(wk).length === 0)) {
+    // Empty workflow_kit is a valid opt-out
+    return { ok: true, errors, warnings };
+  }
+
+  if (!wk || typeof wk !== 'object' || Array.isArray(wk)) {
+    errors.push('workflow_kit must be an object');
+    return { ok: false, errors, warnings };
+  }
+
+  if (wk.phases !== undefined) {
+    if (!wk.phases || typeof wk.phases !== 'object' || Array.isArray(wk.phases)) {
+      errors.push('workflow_kit.phases must be an object');
+      return { ok: false, errors, warnings };
+    }
+
+    const routingPhases = routing ? new Set(Object.keys(routing)) : new Set(DEFAULT_PHASES);
+
+    for (const [phase, phaseConfig] of Object.entries(wk.phases)) {
+      if (!VALID_PHASE_NAME.test(phase)) {
+        errors.push(`workflow_kit phase name "${phase}" must be lowercase alphanumeric starting with a letter (hyphens and underscores allowed)`);
+        continue;
+      }
+
+      if (!routingPhases.has(phase)) {
+        warnings.push(`workflow_kit declares phase "${phase}" which is not in routing`);
+      }
+
+      if (!phaseConfig || typeof phaseConfig !== 'object' || Array.isArray(phaseConfig)) {
+        errors.push(`workflow_kit.phases.${phase} must be an object`);
+        continue;
+      }
+
+      if (!Array.isArray(phaseConfig.artifacts)) {
+        errors.push(`workflow_kit.phases.${phase}.artifacts must be an array`);
+        continue;
+      }
+
+      const seenPaths = new Set();
+      for (let i = 0; i < phaseConfig.artifacts.length; i++) {
+        const artifact = phaseConfig.artifacts[i];
+        const prefix = `workflow_kit.phases.${phase}.artifacts[${i}]`;
+
+        if (!artifact || typeof artifact !== 'object') {
+          errors.push(`${prefix} must be an object`);
+          continue;
+        }
+
+        if (typeof artifact.path !== 'string' || !artifact.path.trim()) {
+          errors.push(`${prefix} requires a non-empty path`);
+          continue;
+        }
+
+        if (artifact.path.includes('..')) {
+          errors.push(`${prefix} path must not traverse above project root (contains "..")`);
+          continue;
+        }
+
+        if (seenPaths.has(artifact.path)) {
+          errors.push(`duplicate artifact path "${artifact.path}" in phase "${phase}"`);
+        }
+        seenPaths.add(artifact.path);
+
+        if (artifact.semantics !== null && artifact.semantics !== undefined) {
+          if (typeof artifact.semantics !== 'string') {
+            errors.push(`${prefix} semantics must be a string or null`);
+          } else if (!VALID_SEMANTIC_IDS.includes(artifact.semantics)) {
+            errors.push(`${prefix} unknown semantics validator "${artifact.semantics}"; valid values: ${VALID_SEMANTIC_IDS.join(', ')}`);
+          } else if (artifact.semantics === 'section_check') {
+            if (!artifact.semantics_config || typeof artifact.semantics_config !== 'object') {
+              errors.push(`${prefix} section_check requires semantics_config`);
+            } else if (!Array.isArray(artifact.semantics_config.required_sections) || artifact.semantics_config.required_sections.length === 0) {
+              errors.push(`${prefix} section_check requires semantics_config.required_sections as a non-empty array`);
+            } else {
+              for (const section of artifact.semantics_config.required_sections) {
+                if (typeof section !== 'string' || !section.trim()) {
+                  errors.push(`${prefix} section_check required_sections must contain non-empty strings`);
+                  break;
+                }
+              }
+            }
+          }
+        }
+
+        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`);
+          }
+        }
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
 /**
  * Normalize a legacy v3 config into the internal shape.
  * Does NOT modify the original file — this is a read-time transformation.
@@ -492,6 +632,7 @@ export function normalizeV3(raw) {
     hooks: {},
     notifications: {},
     budget: null,
+    workflow_kit: normalizeWorkflowKit(undefined, DEFAULT_PHASES),
     retention: {
       talk_strategy: 'append_only',
       history_strategy: 'jsonl_append_only',
@@ -536,6 +677,9 @@ export function normalizeV4(raw) {
     }
   }
 
+  const routing = raw.routing || {};
+  const routingPhases = Object.keys(routing).length > 0 ? Object.keys(routing) : DEFAULT_PHASES;
+
   return {
     schema_version: 4,
     protocol_mode: 'governed',
@@ -547,11 +691,12 @@ export function normalizeV4(raw) {
     },
     roles,
     runtimes: raw.runtimes || {},
-    routing: raw.routing || {},
+    routing,
     gates: raw.gates || {},
     hooks: raw.hooks || {},
     notifications: raw.notifications || {},
     budget: raw.budget || null,
+    workflow_kit: normalizeWorkflowKit(raw.workflow_kit, routingPhases),
     retention: raw.retention || {
       talk_strategy: 'append_only',
       history_strategy: 'jsonl_append_only',
@@ -633,6 +778,51 @@ export function getMaxConcurrentTurns(config, phase) {
 }
 
 
+/**
+ * Normalize workflow_kit config.
+ * When absent, builds defaults from routing phases using DEFAULT_PHASE_ARTIFACTS.
+ * When present, normalizes artifact entries.
+ */
+export function normalizeWorkflowKit(raw, routingPhases) {
+  if (raw === undefined || raw === null) {
+    return buildDefaultWorkflowKit(routingPhases);
+  }
+
+  // Empty object is an explicit opt-out — no artifacts
+  if (typeof raw === 'object' && !Array.isArray(raw) && Object.keys(raw).length === 0) {
+    return { phases: {}, _explicit: true };
+  }
+
+  const phases = {};
+  if (raw.phases) {
+    for (const [phase, phaseConfig] of Object.entries(raw.phases)) {
+      phases[phase] = {
+        artifacts: (phaseConfig.artifacts || []).map(a => ({
+          path: a.path,
+          semantics: a.semantics || null,
+          semantics_config: a.semantics_config || null,
+          owned_by: a.owned_by || null,
+          required: a.required !== false,
+        })),
+      };
+    }
+  }
+
+  return { phases, _explicit: true };
+}
+
+function buildDefaultWorkflowKit(routingPhases) {
+  const phases = {};
+  for (const phase of routingPhases) {
+    if (DEFAULT_PHASE_ARTIFACTS[phase]) {
+      phases[phase] = {
+        artifacts: DEFAULT_PHASE_ARTIFACTS[phase].map(a => ({ ...a, semantics_config: null })),
+      };
+    }
+  }
+  return { phases };
+}
+
 // --- Internal helpers ---
 
 function inferWriteAuthority(agentId) {