agentxchain 2.44.0 → 2.46.0

package/README.md

@@ -24,7 +24,7 @@ Legacy IDE-window coordination is still shipped as a compatibility mode for team
 See governance before you scaffold a real repo:
 
 ```bash
-npx agentxchain demo
+npx --yes -p agentxchain@latest -c "agentxchain demo"
 ```
 
 Requires Node.js 18.17+ or 20.5+ and `git`. The demo creates a temporary governed repo, runs a full PM -> Dev -> QA lifecycle through the real runner interface, shows gates/decisions/objections, and removes the temp workspace when finished. No API keys, config edits, or manual turn authoring required.
@@ -33,12 +33,13 @@ Requires Node.js 18.17+ or 20.5+ and `git`. The demo creates a temporary governe
 
 ```bash
 npm install -g agentxchain
+agentxchain --version
 ```
 
-Or run without installing:
+For a zero-install one-off command, use the package-bound form:
 
 ```bash
-npx agentxchain init --governed --dir my-agentxchain-project -y
+npx --yes -p agentxchain@latest -c "agentxchain demo"
 ```
 
 ## Testing
@@ -62,7 +63,7 @@ Duplicate execution remains intentional for the current 36-file slice until a la
 ### Governed workflow
 
 ```bash
-npx agentxchain init --governed --dir my-agentxchain-project -y
+agentxchain init --governed --dir my-agentxchain-project -y
 cd my-agentxchain-project
 git init
 git add -A
@@ -74,13 +75,13 @@ agentxchain step --role pm
 The default governed dev runtime is `claude --print --dangerously-skip-permissions` with stdin prompt delivery. The non-interactive governed path needs write access, so do not pretend bare `claude --print` is sufficient for unattended implementation turns. If your local coding agent uses a different launch contract, set it during scaffold creation:
 
 ```bash
-npx agentxchain init --governed --dir my-agentxchain-project --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y
+agentxchain init --governed --dir my-agentxchain-project --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y
 ```
 
 If you want template-specific planning artifacts from day one:
 
 ```bash
-npx agentxchain init --governed --template api-service --dir my-agentxchain-project -y
+agentxchain init --governed --template api-service --dir my-agentxchain-project -y
 ```
 
 Built-in governed templates:
@@ -119,8 +120,8 @@ Default governed scaffolding configures QA as `api_proxy` with `ANTHROPIC_API_KE
 For initiatives spanning multiple governed repos, use the coordinator to add cross-repo sequencing and shared gates:
 
 ```bash
-npx agentxchain init --governed --template api-service --dir repos/backend -y
-npx agentxchain init --governed --template web-app --dir repos/frontend -y
+agentxchain init --governed --template api-service --dir repos/backend -y
+agentxchain init --governed --template web-app --dir repos/frontend -y
 agentxchain multi init
 agentxchain multi step --json
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.44.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/adapters/api-proxy-adapter.js

@@ -23,7 +23,7 @@
  *   All error returns include a `classified` ApiProxyError object with
  *   error_class, recovery instructions, and retryable flag.
  *
- * Supported providers: "anthropic", "openai", "google"
+ * Supported providers: "anthropic", "openai", "google", "ollama"
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'fs';
@@ -51,6 +51,7 @@ const PROVIDER_ENDPOINTS = {
   anthropic: 'https://api.anthropic.com/v1/messages',
   openai: 'https://api.openai.com/v1/chat/completions',
   google: 'https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent',
+  ollama: 'http://localhost:11434/v1/chat/completions',
 };
 
 // Bundled cost rates per million tokens (USD).
@@ -161,6 +162,22 @@ const PROVIDER_ERROR_MAPS = {
       { provider_error_type: 'INTERNAL', http_status: 500, error_class: 'unknown_api_error', retryable: true },
     ],
   },
+  // Ollama uses OpenAI-compatible error structure
+  ollama: {
+    extractErrorType(body) {
+      return typeof body?.error?.type === 'string' ? body.error.type : null;
+    },
+    extractErrorCode(body) {
+      return typeof body?.error?.code === 'string' ? body.error.code : null;
+    },
+    mappings: [
+      { provider_error_code: 'invalid_api_key', http_status: 401, error_class: 'auth_failure', retryable: false },
+      { provider_error_code: 'model_not_found', http_status: 404, error_class: 'model_not_found', retryable: false },
+      { provider_error_type: 'invalid_request_error', http_status: 400, body_pattern: /context|token.*limit|too.many.tokens/i, error_class: 'context_overflow', retryable: false },
+      { provider_error_type: 'invalid_request_error', http_status: 400, error_class: 'invalid_request', retryable: false },
+      { provider_error_type: 'rate_limit_error', http_status: 429, error_class: 'rate_limited', retryable: true },
+    ],
+  },
 };
 
 // ── Error classification ──────────────────────────────────────────────────────
@@ -465,7 +482,7 @@ function usageFromTelemetry(provider, model, usage, config) {
   let inputTokens = 0;
   let outputTokens = 0;
 
-  if (provider === 'openai') {
+  if (provider === 'openai' || provider === 'ollama') {
     inputTokens = Number.isFinite(usage.prompt_tokens) ? usage.prompt_tokens : 0;
     outputTokens = Number.isFinite(usage.completion_tokens) ? usage.completion_tokens : 0;
   } else if (provider === 'google') {
@@ -811,9 +828,10 @@ export async function dispatchApiProxy(root, state, config, options = {}) {
   const provider = runtime.provider;
   const model = runtime.model;
   const authEnv = runtime.auth_env;
-  const apiKey = process.env[authEnv];
+  const apiKey = authEnv ? process.env[authEnv] : null;
 
-  if (!apiKey) {
+  // Auth is required for cloud providers, optional for local providers (ollama)
+  if (!apiKey && authEnv) {
     const classified = classifyError(
       'missing_credentials',
       `Environment variable "${authEnv}" is not set — required for api_proxy`,
@@ -1124,6 +1142,15 @@ function buildOpenAiRequest(promptMd, contextMd, model, maxOutputTokens) {
   };
 }
 
+function buildOllamaRequest(promptMd, contextMd, model, maxOutputTokens) {
+  const openAiCompatible = buildOpenAiRequest(promptMd, contextMd, model, maxOutputTokens);
+  return {
+    ...openAiCompatible,
+    max_tokens: maxOutputTokens,
+    max_completion_tokens: undefined,
+  };
+}
+
 function buildGoogleHeaders(_apiKey) {
   // Google Gemini uses API key as a query parameter, not a header
   return {
@@ -1203,6 +1230,14 @@ function extractGoogleTurnResult(responseData) {
   return extraction;
 }
 
+function buildOllamaHeaders(apiKey) {
+  const headers = { 'Content-Type': 'application/json' };
+  if (apiKey) {
+    headers['Authorization'] = `Bearer ${apiKey}`;
+  }
+  return headers;
+}
+
 function buildProviderHeaders(provider, apiKey) {
   if (provider === 'openai') {
     return buildOpenAiHeaders(apiKey);
@@ -1210,6 +1245,9 @@ function buildProviderHeaders(provider, apiKey) {
   if (provider === 'google') {
     return buildGoogleHeaders(apiKey);
   }
+  if (provider === 'ollama') {
+    return buildOllamaHeaders(apiKey);
+  }
   return buildAnthropicHeaders(apiKey);
 }
 
@@ -1217,6 +1255,9 @@ function buildProviderRequest(provider, promptMd, contextMd, model, maxOutputTok
   if (provider === 'openai') {
     return buildOpenAiRequest(promptMd, contextMd, model, maxOutputTokens);
   }
+  if (provider === 'ollama') {
+    return buildOllamaRequest(promptMd, contextMd, model, maxOutputTokens);
+  }
   if (provider === 'google') {
     return buildGoogleRequest(promptMd, contextMd, model, maxOutputTokens);
   }
@@ -1304,7 +1345,7 @@ function extractOpenAiTurnResult(responseData) {
 }
 
 function extractTurnResult(responseData, provider = 'anthropic') {
-  if (provider === 'openai') {
+  if (provider === 'openai' || provider === 'ollama') {
     return extractOpenAiTurnResult(responseData);
   }
   if (provider === 'google') {
@@ -1324,10 +1365,17 @@ export {
   extractTurnResult,
   buildAnthropicRequest,
   buildOpenAiRequest,
+  buildOllamaRequest,
   buildGoogleRequest,
+  buildOllamaHeaders,
+  buildProviderHeaders,
+  buildProviderRequest,
   classifyError,
   classifyHttpError,
+  DEFAULT_RETRY_POLICY,
   BUNDLED_COST_RATES,
   BUNDLED_COST_RATES as COST_RATES, // backward compat alias
   getCostRates,
+  PROVIDER_ENDPOINTS,
+  RETRYABLE_ERROR_CLASSES,
 };

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,
@@ -24,7 +25,8 @@ import {
 
 const VALID_WRITE_AUTHORITIES = ['authoritative', 'proposed', 'review_only'];
 const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy', 'mcp', 'remote_agent'];
-const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai', 'google'];
+export const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai', 'google', 'ollama'];
+const AUTH_OPTIONAL_PROVIDERS = ['ollama'];
 export const VALID_PROMPT_TRANSPORTS = ['argv', 'stdin', 'dispatch_bundle_only'];
 const VALID_MCP_TRANSPORTS = ['stdio', 'streamable_http'];
 const DEFAULT_PHASES = ['planning', 'implementation', 'qa'];
@@ -388,7 +390,9 @@ export function validateV4Config(data, projectRoot) {
           errors.push(`Runtime "${id}": api_proxy requires "model" (e.g. "claude-sonnet-4-6")`);
         }
         if (typeof rt.auth_env !== 'string' || !rt.auth_env.trim()) {
-          errors.push(`Runtime "${id}": api_proxy requires "auth_env" (environment variable name for API key)`);
+          if (!AUTH_OPTIONAL_PROVIDERS.includes(rt.provider)) {
+            errors.push(`Runtime "${id}": api_proxy requires "auth_env" (environment variable name for API key)`);
+          }
         }
         if ('base_url' in rt) {
           if (typeof rt.base_url !== 'string' || !rt.base_url.trim()) {
@@ -509,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 };
 }
 
@@ -722,6 +732,7 @@ export function normalizeV3(raw) {
     hooks: {},
     notifications: {},
     budget: null,
+    policies: [],
     workflow_kit: normalizeWorkflowKit(undefined, DEFAULT_PHASES),
     retention: {
       talk_strategy: 'append_only',
@@ -786,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": {