agentxchain 2.25.1 → 2.25.2

package/package.json

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

package/src/commands/init.js

@@ -454,7 +454,21 @@ function formatInitTarget(dir) {
   return dir;
 }
 
-export function scaffoldGoverned(dir, projectName, projectId, templateId = 'generic', runtimeOptions = {}) {
+function generateWorkflowKitPlaceholder(artifact, projectName) {
+  const filename = basename(artifact.path);
+  const title = filename.replace(/\.[^.]+$/, '').replace(/[-_]/g, ' ');
+
+  if (artifact.semantics === 'section_check' && artifact.semantics_config?.required_sections?.length) {
+    const sections = artifact.semantics_config.required_sections
+      .map(s => `${s}\n\n(Content here.)\n`)
+      .join('\n');
+    return `# ${title} — ${projectName}\n\n${sections}`;
+  }
+
+  return `# ${title} — ${projectName}\n\n(Operator fills this in.)\n`;
+}
+
+export function scaffoldGoverned(dir, projectName, projectId, templateId = 'generic', runtimeOptions = {}, workflowKitConfig = null) {
   const template = loadGovernedTemplate(templateId);
   const { runtime: localDevRuntime } = resolveGovernedLocalDevRuntime(runtimeOptions);
   const runtimes = {
@@ -561,6 +575,37 @@ 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') {
+    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',
+    ]);
+
+    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;
+        const absPath = join(dir, artifact.path);
+        if (existsSync(absPath)) continue;
+
+        // Ensure parent directory exists
+        const parentDir = dirname(absPath);
+        if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
+
+        // Generate placeholder content based on semantics type
+        const content = generateWorkflowKitPlaceholder(artifact, projectName);
+        writeFileSync(absPath, content);
+      }
+    }
+  }
+
   // TALK.md
   writeFileSync(join(dir, 'TALK.md'), `# ${projectName} — Team Talk File\n\nCanonical human-readable handoff log for all agents.\n\n---\n\n`);
 
@@ -662,7 +707,21 @@ async function initGoverned(opts) {
 
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 
-  scaffoldGoverned(dir, projectName, projectId, templateId, opts);
+  // If reinitializing a project that has explicit workflow_kit config, preserve it for scaffold
+  let workflowKitConfig = null;
+  const existingConfigPath = join(dir, CONFIG_FILE);
+  if (existsSync(existingConfigPath)) {
+    try {
+      const existing = JSON.parse(readFileSync(existingConfigPath, 'utf8'));
+      if (existing.workflow_kit && typeof existing.workflow_kit === 'object' && Object.keys(existing.workflow_kit).length > 0) {
+        workflowKitConfig = existing.workflow_kit;
+      }
+    } catch {
+      // Ignore parse errors — scaffold will overwrite the config anyway
+    }
+  }
+
+  scaffoldGoverned(dir, projectName, projectId, templateId, opts, workflowKitConfig);
 
   console.log('');
   console.log(chalk.green(`  ✓ Created governed project ${chalk.bold(targetLabel)}/`));

package/src/lib/gate-evaluator.js

@@ -19,7 +19,109 @@
 
 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: [],
+    };
+
+    existing.required = existing.required || artifact.required !== false;
+
+    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 evaluateGateArtifacts({ root, config, gateDef, phase, result }) {
+  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));
+      }
+    }
+  }
+
+  return failures;
+}
 
 /**
  * Evaluate whether the current phase exit gate is satisfied.
@@ -118,20 +220,13 @@ 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);
-      }
-    }
-  }
+  failures.push(...evaluateGateArtifacts({
+    root,
+    config,
+    gateDef,
+    phase: currentPhase,
+    result,
+  }));
 
   // Predicate: requires_verification_pass
   if (gateDef.requires_verification_pass) {
@@ -240,20 +335,13 @@ 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,
+  }));
 
   if (gateDef.requires_verification_pass) {
     const verificationStatus = acceptedTurn.verification?.status;

package/src/lib/governed-templates.js

@@ -446,7 +446,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 +478,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 +523,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,117 @@ 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);
+    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) {
+  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`);
+        }
+      }
+    }
+  }
+
+  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 +622,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 +667,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 +681,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 +768,50 @@ 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,
+          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) {

package/src/lib/workflow-gate-semantics.js

@@ -8,6 +8,14 @@ export const ACCEPTANCE_MATRIX_PATH = '.planning/acceptance-matrix.md';
 export const SHIP_VERDICT_PATH = '.planning/ship-verdict.md';
 export const RELEASE_NOTES_PATH = '.planning/RELEASE_NOTES.md';
 export const RECOVERY_REPORT_PATH = '.agentxchain/multirepo/RECOVERY_REPORT.md';
+const PATH_SEMANTIC_IDS = {
+  [PM_SIGNOFF_PATH]: 'pm_signoff',
+  [SYSTEM_SPEC_PATH]: 'system_spec',
+  [IMPLEMENTATION_NOTES_PATH]: 'implementation_notes',
+  [ACCEPTANCE_MATRIX_PATH]: 'acceptance_matrix',
+  [SHIP_VERDICT_PATH]: 'ship_verdict',
+  [RELEASE_NOTES_PATH]: 'release_notes',
+};
 
 const AFFIRMATIVE_SHIP_VERDICTS = new Set(['YES', 'SHIP', 'SHIP IT']);
 const AFFIRMATIVE_ACCEPTANCE_STATUSES = new Set(['PASS', 'PASSED', 'OK', 'YES']);
@@ -354,6 +362,57 @@ function evaluateShipVerdict(content) {
   return { ok: true };
 }
 
+function evaluateSectionCheck(content, config) {
+  if (!config?.required_sections?.length) {
+    return { ok: true };
+  }
+  const missing = config.required_sections.filter(
+    section => !content.includes(section)
+  );
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      reason: `Document must contain sections: ${missing.join(', ')}`,
+    };
+  }
+  return { ok: true };
+}
+
+const SEMANTIC_VALIDATORS = {
+  pm_signoff: evaluatePmSignoff,
+  system_spec: evaluateSystemSpec,
+  implementation_notes: evaluateImplementationNotes,
+  acceptance_matrix: evaluateAcceptanceMatrix,
+  ship_verdict: evaluateShipVerdict,
+  release_notes: evaluateReleaseNotes,
+  section_check: evaluateSectionCheck,
+};
+
+export function getSemanticIdForPath(relPath) {
+  return PATH_SEMANTIC_IDS[relPath] || null;
+}
+
+/**
+ * Evaluate a workflow artifact's semantic constraints by validator ID.
+ * @param {string} root - project root directory
+ * @param {object} artifact - { path, semantics, semantics_config }
+ * @returns {{ ok: boolean, reason?: string } | null}
+ */
+export function evaluateArtifactSemantics(root, artifact) {
+  if (!artifact.semantics) return null;
+  const validator = SEMANTIC_VALIDATORS[artifact.semantics];
+  if (!validator) return null;
+  const content = readFile(root, artifact.path);
+  if (content === null) return null;
+  if (artifact.semantics === 'section_check') {
+    return validator(content, artifact.semantics_config);
+  }
+  return validator(content);
+}
+
+/**
+ * Path-based dispatch (backward compat for code calling this directly).
+ */
 export function evaluateWorkflowGateSemantics(root, relPath) {
   const content = readFile(root, relPath);
   if (content === null) {