agentxchain 2.45.0 → 2.46.0

package/package.json

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

package/src/commands/accept-turn.js

@@ -23,6 +23,36 @@ export async function acceptTurnCommand(opts = {}) {
     resolutionMode: opts.resolution || 'standard',
   });
   if (!result.ok) {
+    if (result.error_code === 'policy_escalation' || result.error_code === 'policy_violation') {
+      const recovery = result.state ? deriveRecoveryDescriptor(result.state, config) : null;
+      const retainedTurnId = result.state?.blocked_reason?.turn_id || opts.turn || '(unknown)';
+      const policyTitle = result.error_code === 'policy_escalation'
+        ? 'Turn Acceptance Escalated By Policy'
+        : 'Turn Acceptance Blocked By Policy';
+
+      console.log('');
+      console.log(chalk.yellow(`  ${policyTitle}`));
+      console.log(chalk.dim('  ' + '─'.repeat(44)));
+      console.log('');
+      console.log(`  ${chalk.dim('Turn:')}     ${retainedTurnId}`);
+      console.log(`  ${chalk.dim('Error:')}    ${result.error}`);
+      const violations = Array.isArray(result.policy_violations) ? result.policy_violations : [];
+      for (const violation of violations) {
+        console.log(`  ${chalk.dim('Policy:')}   ${violation.policy_id} (${violation.rule})`);
+        console.log(`  ${chalk.dim('Detail:')}   ${violation.message}`);
+      }
+      if (recovery) {
+        console.log(`  ${chalk.dim('Reason:')}   ${recovery.typed_reason}`);
+        console.log(`  ${chalk.dim('Owner:')}    ${recovery.owner}`);
+        console.log(`  ${chalk.dim('Action:')}   ${recovery.recovery_action}`);
+        console.log(`  ${chalk.dim('Turn:')}     ${recovery.turn_retained ? 'retained' : 'cleared'}`);
+      } else {
+        console.log(`  ${chalk.dim('Action:')}   Fix the policy condition, then rerun agentxchain accept-turn`);
+      }
+      console.log('');
+      process.exit(1);
+    }
+
     if (result.error_code?.startsWith('hook_') || result.error_code === 'hook_blocked') {
       const recovery = deriveRecoveryDescriptor(result.state);
       const activeTurn = result.state?.current_turn;

package/src/commands/init.js

@@ -547,11 +547,14 @@ function buildScaffoldConfigFromTemplate(template, localDevRuntime, workflowKitC
     Object.keys(roles).map((roleId) => [roleId, `.agentxchain/prompts/${roleId}.md`])
   );
 
+  const policies = cloneJsonCompatible(blueprint?.policies || []);
+
   return {
     roles,
     runtimes,
     routing,
     gates,
+    policies,
     prompts,
     workflowKitConfig: effectiveWorkflowKitConfig,
   };
@@ -627,7 +630,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
   const template = loadGovernedTemplate(templateId);
   const { runtime: localDevRuntime } = resolveGovernedLocalDevRuntime(runtimeOptions);
   const scaffoldConfig = buildScaffoldConfigFromTemplate(template, localDevRuntime, workflowKitConfig);
-  const { roles, runtimes, routing, gates, prompts, workflowKitConfig: effectiveWorkflowKitConfig } = scaffoldConfig;
+  const { roles, runtimes, routing, gates, policies, prompts, workflowKitConfig: effectiveWorkflowKitConfig } = scaffoldConfig;
   const scaffoldWorkflowKitConfig = effectiveWorkflowKitConfig
     ? normalizeWorkflowKit(effectiveWorkflowKitConfig, Object.keys(routing))
     : null;
@@ -667,6 +670,9 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
       max_deadlock_cycles: 2
     }
   };
+  if (policies && policies.length > 0) {
+    config.policies = policies;
+  }
   if (effectiveWorkflowKitConfig) {
     config.workflow_kit = effectiveWorkflowKitConfig;
   }

package/src/lib/blocked-state.js

@@ -4,6 +4,8 @@ import {
   deriveEscalationRecoveryAction,
   deriveHookTamperRecoveryAction,
   deriveNeedsHumanRecoveryAction,
+  derivePolicyEscalationDetail,
+  derivePolicyEscalationRecoveryAction,
   getActiveTurnCount,
 } from './governed-state.js';
 
@@ -53,6 +55,13 @@ function maybeRefreshRecoveryAction(state, config, persistedRecovery, turnRetain
     });
   }
 
+  if (typedReason === 'policy_escalation') {
+    return derivePolicyEscalationRecoveryAction(state, config, {
+      turnRetained,
+      turnId,
+    });
+  }
+
   if (typedReason === 'conflict_loop' && isLegacyConflictLoopRecoveryAction(currentAction)) {
     return deriveConflictLoopRecoveryAction(turnId);
   }
@@ -158,6 +167,21 @@ export function deriveRecoveryDescriptor(state, config = null) {
     };
   }
 
+  if (state.blocked_on.startsWith('policy:')) {
+    const policyId = state.blocked_on.slice('policy:'.length).trim() || null;
+    return {
+      typed_reason: 'policy_escalation',
+      owner: 'human',
+      recovery_action: derivePolicyEscalationRecoveryAction(state, config, {
+        turnRetained,
+        turnId: state.blocked_reason?.turn_id ?? null,
+        policyId,
+      }),
+      turn_retained: turnRetained,
+      detail: derivePolicyEscalationDetail(state, { policyId }),
+    };
+  }
+
   return {
     typed_reason: 'unknown_block',
     owner: 'human',

package/src/lib/governed-state.js

@@ -21,6 +21,7 @@ import { randomBytes, createHash } from 'crypto';
 import { safeWriteJson } from './safe-write.js';
 import { validateStagedTurnResult } from './turn-result-validator.js';
 import { evaluatePhaseExit, evaluateRunCompletion } from './gate-evaluator.js';
+import { evaluatePolicies } from './policy-evaluator.js';
 import {
   captureBaseline,
   observeChanges,
@@ -350,6 +351,58 @@ export function deriveDispatchRecoveryAction(state, config, options = {}) {
   return `Resolve the dispatch issue, then run ${command}`;
 }
 
+function normalizePolicyId(policyId) {
+  if (typeof policyId !== 'string') {
+    return null;
+  }
+  const trimmed = policyId.trim();
+  return trimmed || null;
+}
+
+function getPolicyIdFromBlockedState(state) {
+  if (typeof state?.blocked_on !== 'string' || !state.blocked_on.startsWith('policy:')) {
+    return null;
+  }
+  return normalizePolicyId(state.blocked_on.slice('policy:'.length));
+}
+
+export function derivePolicyEscalationDetail(state, options = {}) {
+  if (typeof options.detail === 'string' && options.detail.trim()) {
+    return options.detail.trim();
+  }
+
+  if (typeof state?.blocked_reason === 'string' && state.blocked_reason.trim()) {
+    return state.blocked_reason.trim();
+  }
+
+  const policyId = normalizePolicyId(options.policyId) || getPolicyIdFromBlockedState(state);
+  return policyId ? `Policy "${policyId}" triggered` : (state?.blocked_on || 'Policy escalation');
+}
+
+export function derivePolicyEscalationRecoveryAction(state, config, options = {}) {
+  const command = deriveBlockedRecoveryCommand(state, config, {
+    turnRetained: options.turnRetained,
+    turnId: options.turnId,
+  });
+  const policyId = normalizePolicyId(options.policyId) || getPolicyIdFromBlockedState(state);
+  return policyId
+    ? `Resolve policy "${policyId}" condition, then run ${command}`
+    : `Resolve the policy condition, then run ${command}`;
+}
+
+export function readTurnCostUsd(turnResult) {
+  if (!turnResult || typeof turnResult !== 'object') {
+    return null;
+  }
+  if (typeof turnResult.cost?.usd === 'number') {
+    return turnResult.cost.usd;
+  }
+  if (typeof turnResult.cost?.total_usd === 'number') {
+    return turnResult.cost.total_usd;
+  }
+  return null;
+}
+
 export function deriveHookTamperRecoveryAction(state, config, options = {}) {
   const command = deriveBlockedRecoveryCommand(state, config, {
     turnRetained: options.turnRetained,
@@ -1149,6 +1202,13 @@ export function reconcileRecoveryActionsWithConfig(state, config) {
         turnId,
       });
     }
+  } else if (typedReason === 'policy_escalation') {
+    nextAction = derivePolicyEscalationRecoveryAction(state, config, {
+      turnRetained,
+      turnId,
+      policyId: getPolicyIdFromBlockedState(state),
+    });
+    shouldRefresh = currentAction !== nextAction;
   } else if (typedReason === 'conflict_loop') {
     shouldRefresh = isLegacyConflictLoopRecoveryAction(currentAction);
     if (shouldRefresh) {
@@ -1262,6 +1322,25 @@ function inferBlockedReasonFromState(state) {
     });
   }
 
+  if (state.blocked_on.startsWith('policy:')) {
+    const policyId = getPolicyIdFromBlockedState(state);
+    return buildBlockedReason({
+      category: 'policy_escalation',
+      recovery: {
+        typed_reason: 'policy_escalation',
+        owner: 'human',
+        recovery_action: derivePolicyEscalationRecoveryAction(state, null, {
+          turnRetained,
+          turnId: activeTurn?.turn_id ?? state.blocked_reason?.turn_id ?? null,
+          policyId,
+        }),
+        turn_retained: turnRetained,
+        detail: derivePolicyEscalationDetail(state, { policyId }),
+      },
+      turnId: activeTurn?.turn_id ?? state.blocked_reason?.turn_id ?? null,
+    });
+  }
+
   return null;
 }
 
@@ -2047,6 +2126,83 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   const artifactType = turnResult.artifact?.type || 'review';
   const derivedRef = deriveAcceptedRef(observation, artifactType, state.accepted_integration_ref);
   const historyEntries = readJsonlEntries(root, HISTORY_PATH);
+
+  // Policy evaluation — declarative governance rules (spec: POLICY_ENGINE_SPEC.md)
+  const policyResult = evaluatePolicies(config.policies || [], {
+    currentPhase: state.phase,
+    turnRole: turnResult.role,
+    turnStatus: turnResult.status,
+    turnCostUsd: readTurnCostUsd(turnResult),
+    history: historyEntries,
+  });
+
+  if (policyResult.blocks.length > 0) {
+    const blockMessages = policyResult.blocks.map((v) => v.message);
+    return {
+      ok: false,
+      error: `Policy violation: ${blockMessages.join('; ')}`,
+      error_code: 'policy_violation',
+      policy_violations: policyResult.violations,
+    };
+  }
+
+  if (policyResult.escalations.length > 0) {
+    const escalationMessages = policyResult.escalations.map((v) => v.message);
+    const policyId = policyResult.escalations[0].policy_id;
+    const turnRetained = getActiveTurnCount(state) > 0;
+    const recovery = {
+      typed_reason: 'policy_escalation',
+      owner: 'human',
+      recovery_action: derivePolicyEscalationRecoveryAction(state, config, {
+        turnRetained,
+        turnId: currentTurn.turn_id,
+        policyId,
+      }),
+      turn_retained: turnRetained,
+      detail: derivePolicyEscalationDetail(state, {
+        policyId,
+        detail: escalationMessages.join('; '),
+      }),
+    };
+    const blockedState = {
+      ...state,
+      status: 'blocked',
+      blocked_on: `policy:${policyId}`,
+      blocked_reason: buildBlockedReason({
+        category: 'policy_escalation',
+        recovery,
+        turnId: currentTurn.turn_id,
+        blockedAt: now,
+      }),
+    };
+    writeState(root, blockedState);
+    recordRunHistory(root, blockedState, config, 'blocked');
+    emitBlockedNotification(root, config, blockedState, {
+      category: 'policy_escalation',
+      blockedOn: blockedState.blocked_on,
+      recovery,
+    }, currentTurn);
+    appendJsonl(root, LEDGER_PATH, {
+      timestamp: now,
+      decision: 'policy_escalation',
+      turn_id: currentTurn.turn_id,
+      role: turnResult.role,
+      phase: state.phase,
+      violations: policyResult.escalations.map((v) => ({
+        policy_id: v.policy_id,
+        rule: v.rule,
+        message: v.message,
+      })),
+    });
+    return {
+      ok: false,
+      error: `Policy escalation: ${escalationMessages.join('; ')}`,
+      error_code: 'policy_escalation',
+      state: attachLegacyCurrentTurnAlias(blockedState),
+      policy_violations: policyResult.violations,
+    };
+  }
+
   const conflict = detectAcceptanceConflict(currentTurn, observedArtifact, historyEntries);
 
   if (conflict) {
@@ -2527,6 +2683,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     completionResult,
     hookResults,
     ...(budgetWarning ? { budget_warning: budgetWarning } : {}),
+    ...(policyResult.warnings.length > 0 ? { policy_warnings: policyResult.warnings } : {}),
   };
 }
 

package/src/lib/governed-templates.js

@@ -80,6 +80,7 @@ const VALID_SCAFFOLD_BLUEPRINT_KEYS = new Set([
   'runtimes',
   'routing',
   'gates',
+  'policies',
   'workflow_kit',
 ]);
 
@@ -106,6 +107,7 @@ function validateScaffoldBlueprint(scaffoldBlueprint, errors) {
     runtimes: scaffoldBlueprint.runtimes,
     routing: scaffoldBlueprint.routing,
     gates: scaffoldBlueprint.gates,
+    policies: scaffoldBlueprint.policies,
     workflow_kit: scaffoldBlueprint.workflow_kit,
   });
 

package/src/lib/normalized-config.js

@@ -14,6 +14,7 @@
 
 import { validateHooksConfig } from './hook-runner.js';
 import { validateNotificationsConfig } from './notification-runner.js';
+import { validatePolicies, normalizePolicies } from './policy-evaluator.js';
 import { SUPPORTED_TOKEN_COUNTER_PROVIDERS } from './token-counter.js';
 import {
   buildDefaultWorkflowKitArtifactsForPhase,
@@ -512,6 +513,12 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...wkValidation.errors);
   }
 
+  // Policies (optional but validated if present)
+  if (data.policies !== undefined) {
+    const policyValidation = validatePolicies(data.policies);
+    errors.push(...policyValidation.errors);
+  }
+
   return { ok: errors.length === 0, errors };
 }
 
@@ -725,6 +732,7 @@ export function normalizeV3(raw) {
     hooks: {},
     notifications: {},
     budget: null,
+    policies: [],
     workflow_kit: normalizeWorkflowKit(undefined, DEFAULT_PHASES),
     retention: {
       talk_strategy: 'append_only',
@@ -789,6 +797,7 @@ export function normalizeV4(raw) {
     hooks: raw.hooks || {},
     notifications: raw.notifications || {},
     budget: raw.budget || null,
+    policies: normalizePolicies(raw.policies),
     workflow_kit: normalizeWorkflowKit(raw.workflow_kit, routingPhases),
     retention: raw.retention || {
       talk_strategy: 'append_only',

package/src/lib/policy-evaluator.js

@@ -0,0 +1,330 @@
+/**
+ * Policy evaluator — declarative governance rules for turn acceptance.
+ *
+ * Policies are config-driven rules that evaluate on every turn acceptance.
+ * Gates evaluate at phase boundaries. Hooks run external commands.
+ * Policies evaluate built-in governance rules on every accepted turn.
+ *
+ * Pure functions only — no I/O, no side effects.
+ */
+
+/**
+ * Registry of built-in rule evaluators.
+ * Each evaluator: (params, context) → { triggered: boolean, message: string }
+ */
+const RULE_EVALUATORS = {
+  max_turns_per_phase: (params, ctx) => {
+    const count = ctx.history.filter(
+      (entry) => entry.phase === ctx.currentPhase,
+    ).length;
+    if (count >= params.limit) {
+      return {
+        triggered: true,
+        message: `phase "${ctx.currentPhase}" has reached ${count}/${params.limit} accepted turns`,
+      };
+    }
+    return { triggered: false, message: '' };
+  },
+
+  max_total_turns: (params, ctx) => {
+    const count = ctx.history.length;
+    if (count >= params.limit) {
+      return {
+        triggered: true,
+        message: `run has reached ${count}/${params.limit} total accepted turns`,
+      };
+    }
+    return { triggered: false, message: '' };
+  },
+
+  max_consecutive_same_role: (params, ctx) => {
+    const role = ctx.turnRole;
+    let consecutive = 0;
+    for (let i = ctx.history.length - 1; i >= 0; i--) {
+      if (ctx.history[i].role === role) {
+        consecutive++;
+      } else {
+        break;
+      }
+    }
+    // The current turn (not yet in history) adds one more
+    consecutive += 1;
+    if (consecutive > params.limit) {
+      return {
+        triggered: true,
+        message: `role "${role}" has ${consecutive} consecutive turns (limit: ${params.limit})`,
+      };
+    }
+    return { triggered: false, message: '' };
+  },
+
+  max_cost_per_turn: (params, ctx) => {
+    const cost = ctx.turnCostUsd;
+    if (cost != null && cost > params.limit_usd) {
+      return {
+        triggered: true,
+        message: `turn cost $${cost.toFixed(2)} exceeds limit $${params.limit_usd.toFixed(2)}`,
+      };
+    }
+    return { triggered: false, message: '' };
+  },
+
+  require_status: (params, ctx) => {
+    if (!params.allowed.includes(ctx.turnStatus)) {
+      return {
+        triggered: true,
+        message: `status "${ctx.turnStatus}" is not in allowed set [${params.allowed.join(', ')}]`,
+      };
+    }
+    return { triggered: false, message: '' };
+  },
+};
+
+export const VALID_POLICY_RULES = Object.keys(RULE_EVALUATORS);
+export const VALID_POLICY_ACTIONS = ['block', 'warn', 'escalate'];
+export const VALID_POLICY_TURN_STATUSES = [
+  'completed',
+  'blocked',
+  'needs_human',
+  'failed',
+];
+const VALID_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
+
+/**
+ * Validate a single policy definition at config load time.
+ * Returns an array of error strings (empty if valid).
+ */
+export function validatePolicy(policy, index) {
+  const errors = [];
+  const prefix = `policies[${index}]`;
+
+  if (!policy || typeof policy !== 'object') {
+    return [`${prefix}: must be an object`];
+  }
+
+  if (typeof policy.id !== 'string' || !VALID_ID_PATTERN.test(policy.id)) {
+    errors.push(`${prefix}: id must be a lowercase kebab-case string`);
+  }
+
+  if (!VALID_POLICY_RULES.includes(policy.rule)) {
+    errors.push(
+      `${prefix}: unknown rule "${policy.rule}"; valid rules: ${VALID_POLICY_RULES.join(', ')}`,
+    );
+  }
+
+  if (!VALID_POLICY_ACTIONS.includes(policy.action)) {
+    errors.push(
+      `${prefix}: action must be one of ${VALID_POLICY_ACTIONS.join(', ')}`,
+    );
+  }
+
+  // Rule-specific param validation
+  if (VALID_POLICY_RULES.includes(policy.rule)) {
+    const paramErrors = validatePolicyParams(policy.rule, policy.params, prefix);
+    errors.push(...paramErrors);
+  }
+
+  // Scope validation (optional)
+  if (policy.scope != null) {
+    if (typeof policy.scope !== 'object') {
+      errors.push(`${prefix}: scope must be an object`);
+    } else {
+      if (policy.scope.phases != null && !Array.isArray(policy.scope.phases)) {
+        errors.push(`${prefix}: scope.phases must be an array`);
+      }
+      if (policy.scope.roles != null && !Array.isArray(policy.scope.roles)) {
+        errors.push(`${prefix}: scope.roles must be an array`);
+      }
+    }
+  }
+
+  return errors;
+}
+
+function validatePolicyParams(rule, params, prefix) {
+  const errors = [];
+
+  switch (rule) {
+    case 'max_turns_per_phase':
+    case 'max_total_turns':
+      if (!params || typeof params.limit !== 'number' || params.limit < 1) {
+        errors.push(`${prefix}: params.limit must be a number >= 1`);
+      }
+      break;
+
+    case 'max_consecutive_same_role':
+      if (!params || typeof params.limit !== 'number' || params.limit < 1) {
+        errors.push(`${prefix}: params.limit must be a number >= 1`);
+      }
+      break;
+
+    case 'max_cost_per_turn':
+      if (
+        !params ||
+        typeof params.limit_usd !== 'number' ||
+        params.limit_usd <= 0
+      ) {
+        errors.push(`${prefix}: params.limit_usd must be a number > 0`);
+      }
+      break;
+
+    case 'require_status':
+      if (
+        !params ||
+        !Array.isArray(params.allowed) ||
+        params.allowed.length === 0
+      ) {
+        errors.push(`${prefix}: params.allowed must be a non-empty array`);
+      } else {
+        for (const status of params.allowed) {
+          if (!VALID_POLICY_TURN_STATUSES.includes(status)) {
+            errors.push(
+              `${prefix}: params.allowed contains invalid status "${status}"; valid statuses: ${VALID_POLICY_TURN_STATUSES.join(', ')}`,
+            );
+          }
+        }
+      }
+      break;
+  }
+
+  return errors;
+}
+
+/**
+ * Validate the full policies array at config load time.
+ * Returns { ok: boolean, errors: string[] }.
+ */
+export function validatePolicies(policies) {
+  if (policies == null) {
+    return { ok: true, errors: [] };
+  }
+
+  if (!Array.isArray(policies)) {
+    return { ok: false, errors: ['policies must be an array'] };
+  }
+
+  const errors = [];
+  const ids = new Set();
+
+  for (let i = 0; i < policies.length; i++) {
+    const policyErrors = validatePolicy(policies[i], i);
+    errors.push(...policyErrors);
+
+    if (policies[i]?.id) {
+      if (ids.has(policies[i].id)) {
+        errors.push(`policies[${i}]: duplicate id "${policies[i].id}"`);
+      }
+      ids.add(policies[i].id);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Evaluate all policies against the current turn context.
+ *
+ * @param {Array} policies - normalized policies from config
+ * @param {object} context
+ * @param {string} context.currentPhase
+ * @param {string} context.turnRole - role of the turn being accepted
+ * @param {string} context.turnStatus - status from turn result
+ * @param {number|null} context.turnCostUsd - cost from turn result
+ * @param {Array} context.history - accepted history entries
+ * @returns {PolicyEvaluationResult}
+ *
+ * @typedef {object} PolicyEvaluationResult
+ * @property {boolean} ok - true if no block/escalate violations
+ * @property {PolicyViolation[]} violations - all triggered policies
+ * @property {PolicyViolation[]} blocks - violations with action "block"
+ * @property {PolicyViolation[]} escalations - violations with action "escalate"
+ * @property {PolicyViolation[]} warnings - violations with action "warn"
+ *
+ * @typedef {object} PolicyViolation
+ * @property {string} policy_id
+ * @property {string} rule
+ * @property {string} action
+ * @property {string} message
+ */
+export function evaluatePolicies(policies, context) {
+  const result = {
+    ok: true,
+    violations: [],
+    blocks: [],
+    escalations: [],
+    warnings: [],
+  };
+
+  if (!Array.isArray(policies) || policies.length === 0) {
+    return result;
+  }
+
+  for (const policy of policies) {
+    // Scope check: skip if out of scope
+    if (policy.scope) {
+      if (
+        Array.isArray(policy.scope.phases) &&
+        policy.scope.phases.length > 0 &&
+        !policy.scope.phases.includes(context.currentPhase)
+      ) {
+        continue;
+      }
+      if (
+        Array.isArray(policy.scope.roles) &&
+        policy.scope.roles.length > 0 &&
+        !policy.scope.roles.includes(context.turnRole)
+      ) {
+        continue;
+      }
+    }
+
+    const evaluator = RULE_EVALUATORS[policy.rule];
+    if (!evaluator) {
+      continue; // Unknown rules caught at config validation
+    }
+
+    const evaluation = evaluator(policy.params || {}, context);
+    if (!evaluation.triggered) {
+      continue;
+    }
+
+    const violation = {
+      policy_id: policy.id,
+      rule: policy.rule,
+      action: policy.action,
+      message:
+        policy.message ||
+        `Policy "${policy.id}": ${evaluation.message}`,
+    };
+
+    result.violations.push(violation);
+
+    switch (policy.action) {
+      case 'block':
+        result.blocks.push(violation);
+        break;
+      case 'escalate':
+        result.escalations.push(violation);
+        break;
+      case 'warn':
+        result.warnings.push(violation);
+        break;
+    }
+  }
+
+  result.ok = result.blocks.length === 0 && result.escalations.length === 0;
+  return result;
+}
+
+/**
+ * Normalize policies config: null/undefined → [], validate, return.
+ */
+export function normalizePolicies(raw) {
+  if (raw == null) {
+    return [];
+  }
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw;
+}

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

@@ -142,6 +142,26 @@
         "requires_human_approval": true
       }
     },
+    "policies": [
+      {
+        "id": "phase-turn-cap",
+        "rule": "max_turns_per_phase",
+        "params": { "limit": 15 },
+        "action": "escalate"
+      },
+      {
+        "id": "total-turn-cap",
+        "rule": "max_total_turns",
+        "params": { "limit": 60 },
+        "action": "escalate"
+      },
+      {
+        "id": "no-role-monopoly",
+        "rule": "max_consecutive_same_role",
+        "params": { "limit": 4 },
+        "action": "block"
+      }
+    ],
     "workflow_kit": {
       "phases": {
         "planning": {