@neuroverseos/governance 0.1.6 → 0.2.2

package/dist/cli/run.d.cts

@@ -0,0 +1,20 @@
+/**
+ * neuroverse run — Governed Runtime
+ *
+ * Modes:
+ *   --pipe          Pipe mode: JSON lines in → verdicts out (default if stdin is piped)
+ *   --interactive   Interactive chat session with a model
+ *
+ * Usage:
+ *   # Pipe mode — works with any language/framework
+ *   my_agent | neuroverse run --world ./world/ --plan plan.json
+ *
+ *   # Interactive mode — governed chat session
+ *   neuroverse run --world ./world/ --plan plan.json --provider openai
+ *
+ *   # Quick start — auto-detect world and plan
+ *   neuroverse run
+ */
+declare function main(args: string[]): Promise<void>;
+
+export { main };

package/dist/cli/run.d.ts

@@ -0,0 +1,20 @@
+/**
+ * neuroverse run — Governed Runtime
+ *
+ * Modes:
+ *   --pipe          Pipe mode: JSON lines in → verdicts out (default if stdin is piped)
+ *   --interactive   Interactive chat session with a model
+ *
+ * Usage:
+ *   # Pipe mode — works with any language/framework
+ *   my_agent | neuroverse run --world ./world/ --plan plan.json
+ *
+ *   # Interactive mode — governed chat session
+ *   neuroverse run --world ./world/ --plan plan.json --provider openai
+ *
+ *   # Quick start — auto-detect world and plan
+ *   neuroverse run
+ */
+declare function main(args: string[]): Promise<void>;
+
+export { main };

package/dist/cli/run.js

@@ -0,0 +1,143 @@
+import {
+  describeActiveWorld,
+  resolveWorldPath
+} from "../chunk-AKW5YVCE.js";
+import "../chunk-YZFATT7X.js";
+
+// src/cli/run.ts
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { join } from "path";
+function parseArg(args, flag) {
+  const idx = args.indexOf(flag);
+  return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : void 0;
+}
+function hasFlag(args, flag) {
+  return args.includes(flag);
+}
+function autoDetectPlan() {
+  const nvDir = ".neuroverse/plans";
+  if (!existsSync(nvDir)) return void 0;
+  const entries = readdirSync(nvDir).filter((e) => e.endsWith(".json"));
+  if (entries.length === 1) {
+    try {
+      return JSON.parse(readFileSync(join(nvDir, entries[0]), "utf-8"));
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+function loadPlan(path) {
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+var RUN_USAGE = `
+neuroverse run \u2014 Governed runtime for AI agents.
+
+Modes:
+  --pipe            JSON lines in \u2192 verdicts out (default if stdin is piped)
+  --interactive     Chat session with model + governance
+
+Options:
+  --world <path>    Path to world directory
+  --plan <path>     Path to plan.json
+  --level <level>   Enforcement level (basic|standard|strict)
+  --trace           Include evaluation trace in verdicts
+  --provider <name> Model provider (openai|anthropic|ollama)
+  --model <name>    Model name override
+  --api-key <key>   API key (or set via env var)
+
+Usage:
+  # Pipe mode \u2014 works with any agent
+  my_agent | neuroverse run --world ./world/ --plan plan.json
+
+  # Interactive mode \u2014 governed chat session
+  neuroverse run --interactive --world ./world/ --provider openai
+
+  # Auto-detect world and plan
+  neuroverse run
+`.trim();
+async function main(args) {
+  if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
+    process.stdout.write(RUN_USAGE + "\n");
+    process.exit(0);
+    return;
+  }
+  const worldPath = resolveWorldPath(parseArg(args, "--world"));
+  if (!worldPath) {
+    process.stderr.write(
+      "Error: No world found.\nUse --world <path>, set NEUROVERSE_WORLD, or run `neuroverse world use <name>`\n"
+    );
+    process.exit(1);
+    return;
+  }
+  const explicitWorld = parseArg(args, "--world");
+  const worldInfo = describeActiveWorld(explicitWorld);
+  if (worldInfo) {
+    process.stderr.write(`Using world: ${worldInfo.name}
+`);
+  }
+  const planPath = parseArg(args, "--plan");
+  const plan = planPath ? loadPlan(planPath) : autoDetectPlan();
+  const level = parseArg(args, "--level");
+  const trace = hasFlag(args, "--trace");
+  const isPipeMode = hasFlag(args, "--pipe") || !process.stdin.isTTY;
+  const isInteractive = hasFlag(args, "--interactive");
+  if (isInteractive) {
+    const providerName = parseArg(args, "--provider");
+    if (!providerName) {
+      process.stderr.write(
+        "Error: Interactive mode requires --provider (openai|anthropic|ollama)\n"
+      );
+      process.exit(1);
+      return;
+    }
+    const { resolveProvider, ModelAdapter } = await import("../model-adapter-BB7G4MFI.js");
+    const { runInteractiveMode } = await import("../session-VISISNWJ.js");
+    const modelConfig = resolveProvider(providerName, {
+      model: parseArg(args, "--model"),
+      apiKey: parseArg(args, "--api-key")
+    });
+    const model = new ModelAdapter(modelConfig);
+    await runInteractiveMode(
+      {
+        worldPath,
+        plan,
+        level,
+        trace,
+        onVerdict: (verdict, event) => {
+          if (verdict.status !== "ALLOW") {
+            process.stderr.write(
+              `  [${verdict.status}] ${event.intent} \u2014 ${verdict.reason ?? verdict.ruleId ?? "governance rule"}
+`
+            );
+          }
+        },
+        onPlanProgress: (progress) => {
+          process.stderr.write(
+            `  [plan] ${progress.completed}/${progress.total} (${progress.percentage}%)
+`
+          );
+        },
+        onPlanComplete: () => {
+          process.stderr.write(`  [plan] Complete!
+`);
+        }
+      },
+      model
+    );
+  } else if (isPipeMode) {
+    const { runPipeMode } = await import("../session-VISISNWJ.js");
+    await runPipeMode({
+      worldPath,
+      plan,
+      level,
+      trace
+    });
+  } else {
+    process.stdout.write(RUN_USAGE + "\n");
+    process.exit(0);
+  }
+}
+export {
+  main
+};

package/dist/{configure-ai-46JVG56I.js → configure-ai-TK67ZWZL.js}

@@ -1,11 +1,14 @@
 import {
   CONFIGURE_AI_EXIT_CODES,
-  createProvider,
+  createProvider
+} from "./chunk-Q6O7ZLO2.js";
+import {
   getConfigPath,
   loadConfig,
   redactConfig,
   saveConfig
-} from "./chunk-T4X42QXC.js";
+} from "./chunk-OT6PXH54.js";
+import "./chunk-YZFATT7X.js";
 
 // src/cli/configure-ai.ts
 function parseArgs(argv) {

package/dist/{derive-6NAEWLM5.js → derive-TLIV4OOU.js}

@@ -2,12 +2,14 @@ import {
   DeriveInputError,
   DeriveProviderError,
   deriveWorld
-} from "./chunk-D7BGWV2J.js";
+} from "./chunk-NF5POFCI.js";
 import {
   DERIVE_EXIT_CODES
-} from "./chunk-T4X42QXC.js";
+} from "./chunk-Q6O7ZLO2.js";
+import "./chunk-OT6PXH54.js";
 import "./chunk-XPDMYECO.js";
-import "./chunk-O5OMJMIE.js";
+import "./chunk-7P3S7MAY.js";
+import "./chunk-YZFATT7X.js";
 
 // src/cli/derive.ts
 function parseArgs(argv) {
@@ -117,7 +119,7 @@ Normalization: ${n.fixCount} fix(es) applied
       process.stderr.write(`
 Bootstrapping to ${args.bootstrapDir}...
 `);
-      const { main: bootstrapMain } = await import("./bootstrap-H4HHKQ5G.js");
+      const { main: bootstrapMain } = await import("./bootstrap-GXVDZNF7.js");
       await bootstrapMain([
         "--input",
         result.outputPath,

package/dist/doctor-QV6HELS5.js

@@ -0,0 +1,170 @@
+import {
+  loadConfig
+} from "./chunk-OT6PXH54.js";
+import {
+  __glob
+} from "./chunk-YZFATT7X.js";
+
+// import("../adapters/**/*") in src/cli/doctor.ts
+var globImport_adapters = __glob({
+  "../adapters/express.ts": () => import("./adapters/express.js"),
+  "../adapters/index.ts": () => import("./adapters/index.js"),
+  "../adapters/langchain.ts": () => import("./adapters/langchain.js"),
+  "../adapters/openai.ts": () => import("./adapters/openai.js"),
+  "../adapters/openclaw.ts": () => import("./adapters/openclaw.js")
+});
+
+// src/cli/doctor.ts
+var PACKAGE_VERSION = "0.2.0";
+var MIN_NODE_VERSION = 18;
+async function main(argv) {
+  const json = argv.includes("--json");
+  let worldPath;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--world" && i + 1 < argv.length) {
+      worldPath = argv[++i];
+    }
+  }
+  const checks = [];
+  const nodeVersion = process.version;
+  const major = parseInt(nodeVersion.slice(1), 10);
+  checks.push({
+    label: "Node version",
+    status: major >= MIN_NODE_VERSION ? "pass" : "fail",
+    value: nodeVersion,
+    detail: major < MIN_NODE_VERSION ? `Requires Node >= ${MIN_NODE_VERSION}` : void 0
+  });
+  checks.push({
+    label: "NeuroVerse version",
+    status: "pass",
+    value: PACKAGE_VERSION
+  });
+  try {
+    const config = await loadConfig();
+    if (config?.provider && config?.apiKey) {
+      checks.push({
+        label: "AI provider configured",
+        status: "pass",
+        value: `${config.provider}${config.model ? ` (${config.model})` : ""}`
+      });
+    } else {
+      checks.push({
+        label: "AI provider configured",
+        status: "warn",
+        value: "not configured",
+        detail: "Run: neuroverse configure-ai --provider openai --model gpt-4.1-mini --api-key <key>"
+      });
+    }
+  } catch {
+    checks.push({
+      label: "AI provider configured",
+      status: "warn",
+      value: "not configured",
+      detail: "Run: neuroverse configure-ai"
+    });
+  }
+  if (worldPath) {
+    try {
+      const { existsSync } = await import("fs");
+      const { join } = await import("path");
+      const hasWorld = existsSync(join(worldPath, "world.json"));
+      checks.push({
+        label: "World file detected",
+        status: hasWorld ? "pass" : "fail",
+        value: hasWorld ? worldPath : "not found",
+        detail: hasWorld ? void 0 : `No world.json found in ${worldPath}`
+      });
+    } catch {
+      checks.push({
+        label: "World file detected",
+        status: "fail",
+        value: "error reading path"
+      });
+    }
+  } else {
+    const { existsSync } = await import("fs");
+    const { join } = await import("path");
+    const candidates = ["./world", "./.neuroverse", "./worlds"];
+    let found;
+    for (const dir of candidates) {
+      if (existsSync(join(dir, "world.json"))) {
+        found = dir;
+        break;
+      }
+    }
+    checks.push({
+      label: "World file detected",
+      status: found ? "pass" : "warn",
+      value: found ?? "none found",
+      detail: found ? void 0 : "Build a world: neuroverse build <input.md>"
+    });
+  }
+  try {
+    const { evaluateGuard } = await import("./guard-engine-JLTUARGU.js");
+    checks.push({
+      label: "Guard engine",
+      status: typeof evaluateGuard === "function" ? "pass" : "fail",
+      value: "loaded"
+    });
+  } catch {
+    checks.push({ label: "Guard engine", status: "fail", value: "failed to load" });
+  }
+  try {
+    const { validateWorld } = await import("./validate-engine-UIABSIHD.js");
+    checks.push({
+      label: "Validation engine",
+      status: typeof validateWorld === "function" ? "pass" : "fail",
+      value: "loaded"
+    });
+  } catch {
+    checks.push({ label: "Validation engine", status: "fail", value: "failed to load" });
+  }
+  const adapterNames = ["openai", "express", "langchain", "openclaw"];
+  const loadedAdapters = [];
+  for (const name of adapterNames) {
+    try {
+      await globImport_adapters(`../adapters/${name}`);
+      loadedAdapters.push(name);
+    } catch {
+    }
+  }
+  checks.push({
+    label: "Adapters",
+    status: loadedAdapters.length > 0 ? "pass" : "warn",
+    value: loadedAdapters.length > 0 ? loadedAdapters.join(", ") : "none"
+  });
+  if (json) {
+    const hasFailure2 = checks.some((c) => c.status === "fail");
+    process.stdout.write(JSON.stringify({
+      status: hasFailure2 ? "fail" : "pass",
+      checks
+    }, null, 2) + "\n");
+    process.exit(hasFailure2 ? 1 : 0);
+    return;
+  }
+  process.stderr.write("\nNeuroVerse Environment Check\n");
+  process.stderr.write("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
+  const maxLabel = Math.max(...checks.map((c) => c.label.length));
+  for (const check of checks) {
+    const icon = check.status === "pass" ? "ok" : check.status === "warn" ? "!!" : "FAIL";
+    const pad = " ".repeat(maxLabel - check.label.length);
+    process.stderr.write(`  ${check.label}${pad}  ${icon}  ${check.value}
+`);
+    if (check.detail) {
+      process.stderr.write(`  ${" ".repeat(maxLabel)}      ${check.detail}
+`);
+    }
+  }
+  const hasFailure = checks.some((c) => c.status === "fail");
+  process.stderr.write("\n");
+  if (hasFailure) {
+    process.stderr.write("Some checks failed. Fix the issues above and re-run.\n");
+  } else {
+    process.stderr.write("System ready.\n");
+  }
+  process.stderr.write("\n");
+  process.exit(hasFailure ? 1 : 0);
+}
+export {
+  main
+};

package/dist/{explain-3B3VB6TL.js → explain-IDCRWMPX.js}

@@ -4,7 +4,8 @@ import {
 } from "./chunk-BUWWN2NX.js";
 import {
   loadWorld
-} from "./chunk-M3TZFGHO.js";
+} from "./chunk-JZPQGIKR.js";
+import "./chunk-YZFATT7X.js";
 
 // src/cli/explain.ts
 function parseArgs(argv) {

package/dist/{guard-67Y66P3I.js → guard-GFLQZY6U.js}

@@ -1,12 +1,18 @@
 import {
   GUARD_EXIT_CODES
 } from "./chunk-MWDQ4MJB.js";
+import {
+  describeActiveWorld,
+  resolveWorldPath
+} from "./chunk-AKW5YVCE.js";
 import {
   evaluateGuard
-} from "./chunk-B4NF3OLW.js";
+} from "./chunk-4JRYGIO7.js";
 import {
   loadWorld
-} from "./chunk-M3TZFGHO.js";
+} from "./chunk-JZPQGIKR.js";
+import "./chunk-4QXB6PEO.js";
+import "./chunk-YZFATT7X.js";
 
 // src/cli/guard.ts
 function parseArgs(argv) {
@@ -28,9 +34,6 @@ function parseArgs(argv) {
       }
     }
   }
-  if (!worldPath) {
-    throw new Error("--world <path> is required");
-  }
   return { worldPath, trace, level };
 }
 async function readStdin() {
@@ -43,6 +46,17 @@ async function readStdin() {
 async function main(argv = process.argv.slice(2)) {
   try {
     const args = parseArgs(argv);
+    const worldPath = resolveWorldPath(args.worldPath);
+    if (!worldPath) {
+      throw new Error(
+        "No world specified. Use --world <path>, set NEUROVERSE_WORLD, or run `neuroverse world use <name>`"
+      );
+    }
+    const worldInfo = describeActiveWorld(args.worldPath);
+    if (worldInfo) {
+      process.stderr.write(`Using world: ${worldInfo.name}
+`);
+    }
     const input = await readStdin();
     if (!input.trim()) {
       const errorResult = {
@@ -65,7 +79,7 @@ async function main(argv = process.argv.slice(2)) {
       process.stdout.write(JSON.stringify(errorResult, null, 2) + "\n");
       process.exit(GUARD_EXIT_CODES.ERROR);
     }
-    const world = await loadWorld(args.worldPath);
+    const world = await loadWorld(worldPath);
     const options = { trace: args.trace, level: args.level };
     const verdict = evaluateGuard(event, world, options);
     process.stdout.write(JSON.stringify(verdict, null, 2) + "\n");

package/dist/{guard-contract-D_RQz9kt.d.ts → guard-contract-Cm91Kp4j.d.cts}

@@ -271,6 +271,10 @@ interface IntentPattern {
 interface GuardsConfig {
     guards: Guard[];
     intent_vocabulary: Record<string, IntentPattern>;
+    /** All known action surfaces (e.g. "shell", "http", "db", "email", "deploy").
+     *  When declared, the validator checks that every surface has at least one
+     *  governing guard — surfaces without guards are reported as fail-open. */
+    tool_surfaces?: string[];
 }
 interface WorldDefinition {
     world: WorldIdentity;
@@ -287,6 +291,174 @@ interface WorldDefinition {
     metadata: WorldMetadata;
 }
 
+/**
+ * Plan Contract — Plan Enforcement Types
+ *
+ * Defines the input/output contract for plan-based governance.
+ *
+ * Plans are temporary guard overlays — "mom's rules for this trip."
+ * They define what an agent should do (steps) and what it must not
+ * exceed (constraints). Plans layer on top of worlds, narrowing
+ * behavior without overriding safety or world-level governance.
+ *
+ * INVARIANTS:
+ *   - Plans can only restrict, never expand. A plan cannot override a world BLOCK.
+ *   - Plan enforcement is deterministic: same event + same plan → same verdict.
+ *   - No AI in the evaluation loop. Parsing and evaluation are pure functions.
+ */
+interface PlanStep {
+    /** Auto-generated slug from label (e.g., "write_announcement_blog_post"). */
+    id: string;
+    /** Human-readable step name. */
+    label: string;
+    /** Optional detail about the step. */
+    description?: string;
+    /** Restrict this step to specific tools (optional). */
+    tools?: string[];
+    /** Step IDs that must complete first (optional). */
+    requires?: string[];
+    /** Semantic tags for action mapping (e.g., ["deploy", "marketing"]). */
+    tags?: string[];
+    /** Completion condition name (optional). */
+    verify?: string;
+    /** Current step status. */
+    status: 'pending' | 'active' | 'completed' | 'skipped';
+}
+interface PlanConstraint {
+    /** Auto-generated constraint ID. */
+    id: string;
+    /** Constraint type. 'approval' always returns PAUSE until human confirms. */
+    type: 'budget' | 'time' | 'scope' | 'approval' | 'custom';
+    /** Human-readable description. */
+    description: string;
+    /** Enforcement mode. */
+    enforcement: 'block' | 'pause';
+    /** Numeric limit (for budget/time). */
+    limit?: number;
+    /** Unit for the limit (e.g., "USD", "minutes"). */
+    unit?: string;
+    /** Pattern that activates this constraint. */
+    trigger?: string;
+}
+/**
+ * How step completion is determined:
+ *   - 'trust'    — caller asserts completion, plan advances (default)
+ *   - 'verified' — steps with a `verify` field require evidence to advance;
+ *                   steps without `verify` still advance on trust
+ */
+type PlanCompletionMode = 'trust' | 'verified';
+/**
+ * Evidence provided when advancing a step in verified mode.
+ * The verifier checks that evidence.type matches step.verify.
+ */
+interface StepEvidence {
+    /** Evidence type — must match the step's `verify` field. */
+    type: string;
+    /** Proof payload (URL, hash, output snippet, etc.). */
+    proof: string;
+    /** When the evidence was produced. */
+    timestamp?: string;
+}
+/**
+ * Result of attempting to advance a step.
+ */
+interface AdvanceResult {
+    /** Whether the step was successfully advanced. */
+    success: boolean;
+    /** Updated plan (if success). */
+    plan?: PlanDefinition;
+    /** Why advancement failed (if !success). */
+    reason?: string;
+    /** The evidence that was accepted (if verified mode). */
+    evidence?: StepEvidence;
+}
+interface PlanDefinition {
+    /** Unique plan identifier. */
+    plan_id: string;
+    /** Human-readable objective. */
+    objective: string;
+    /** Whether steps must run in order. */
+    sequential: boolean;
+    /**
+     * How step completion is determined.
+     *   - 'trust' (default) — caller asserts "done", plan advances
+     *   - 'verified' — steps with `verify` require evidence to advance
+     */
+    completion: PlanCompletionMode;
+    /** The steps in this plan. */
+    steps: PlanStep[];
+    /** Constraints that apply to this plan. */
+    constraints: PlanConstraint[];
+    /** Optional parent world ID. */
+    world_id?: string;
+    /** When this plan was created. */
+    created_at: string;
+    /** Optional expiry time. */
+    expires_at?: string;
+}
+type PlanStatus = 'ON_PLAN' | 'OFF_PLAN' | 'CONSTRAINT_VIOLATED' | 'PLAN_COMPLETE';
+interface PlanVerdict {
+    /** Whether the action is allowed by this plan. */
+    allowed: boolean;
+    /** Plan verdict status. */
+    status: PlanStatus;
+    /** Why the action was blocked or paused. */
+    reason?: string;
+    /** Which step this action matched (if any). */
+    matchedStep?: string;
+    /** Nearest step when OFF_PLAN (for agent self-correction). */
+    closestStep?: string;
+    /** How close the action was to the nearest step (0-1). */
+    similarityScore?: number;
+    /** Current plan progress. */
+    progress: PlanProgress;
+}
+interface PlanProgress {
+    /** Number of completed steps. */
+    completed: number;
+    /** Total number of steps. */
+    total: number;
+    /** Completion percentage. */
+    percentage: number;
+}
+interface PlanCheck {
+    /** The plan being enforced. */
+    planId: string;
+    /** Whether the action matched a plan step. */
+    matched: boolean;
+    /** Which step was matched. */
+    matchedStepId?: string;
+    /** Label of the matched step. */
+    matchedStepLabel?: string;
+    /** Nearest step when no match (for self-correction). */
+    closestStepId?: string;
+    /** Label of the nearest step. */
+    closestStepLabel?: string;
+    /** Similarity score to the nearest step. */
+    similarityScore?: number;
+    /** Whether step sequence requirements are satisfied. */
+    sequenceValid?: boolean;
+    /** Results of constraint checks. */
+    constraintsChecked: Array<{
+        constraintId: string;
+        passed: boolean;
+        reason?: string;
+    }>;
+    /** Current progress. */
+    progress: {
+        completed: number;
+        total: number;
+    };
+}
+declare const PLAN_EXIT_CODES: {
+    readonly ON_PLAN: 0;
+    readonly OFF_PLAN: 1;
+    readonly CONSTRAINT_VIOLATED: 2;
+    readonly ERROR: 3;
+    readonly PLAN_COMPLETE: 4;
+};
+type PlanExitCode = (typeof PLAN_EXIT_CODES)[keyof typeof PLAN_EXIT_CODES];
+
 /**
  * Guard Contract — CLI Governance Evaluation Types
  *
@@ -406,6 +578,8 @@ interface EvaluationTrace {
     invariantChecks: InvariantCheck[];
     /** Safety checks (injection, scope escape) */
     safetyChecks: SafetyCheck[];
+    /** Plan enforcement check (Phase 1.5) — present when a plan is active */
+    planCheck?: PlanCheck;
     /** Every role rule checked */
     roleChecks: RoleCheck[];
     /** Every declarative guard checked */
@@ -490,7 +664,7 @@ interface LevelCheck {
  */
 interface PrecedenceResolution {
     /** Which check category produced the final verdict */
-    decidingLayer: 'session-allowlist' | 'safety' | 'role' | 'guard' | 'kernel-rule' | 'level-constraint' | 'default-allow';
+    decidingLayer: 'session-allowlist' | 'safety' | 'plan-enforcement' | 'role' | 'guard' | 'kernel-rule' | 'level-constraint' | 'default-allow';
     /** Specific ID of the deciding check (guard ID, rule ID, etc.) */
     decidingId?: string;
     /** Resolution strategy used */
@@ -517,6 +691,12 @@ interface GuardEngineOptions {
      * The caller owns persistence (allow-once, allow-always, etc.).
      */
     sessionAllowlist?: Set<string>;
+    /**
+     * Active plan overlay — temporary task-scoped governance.
+     * When set, plan enforcement runs at Phase 1.5 (after safety, before roles).
+     * Plans can only restrict, never expand.
+     */
+    plan?: PlanDefinition;
 }
 declare const GUARD_EXIT_CODES: {
     readonly ALLOW: 0;
@@ -526,4 +706,4 @@ declare const GUARD_EXIT_CODES: {
 };
 type GuardExitCode = (typeof GUARD_EXIT_CODES)[keyof typeof GUARD_EXIT_CODES];
 
-export { type EvaluationTrace as E, type GuardVerdict as G, type InvariantCheck as I, type KernelRuleCheck as K, type LevelCheck as L, type PrecedenceResolution as P, type RoleCheck as R, type SafetyCheck as S, type ViabilityStatus as V, type WorldDefinition as W, type GuardEvent as a, type GuardEngineOptions as b, GUARD_EXIT_CODES as c, type GuardCheck as d, type GuardExitCode as e, type GuardStatus as f, type VerdictEvidence as g };
+export { type AdvanceResult as A, type EvaluationTrace as E, type GuardVerdict as G, type InvariantCheck as I, type KernelRuleCheck as K, type LevelCheck as L, type PlanDefinition as P, type RoleCheck as R, type StepEvidence as S, type ViabilityStatus as V, type WorldDefinition as W, type GuardEvent as a, type PlanProgress as b, type GuardEngineOptions as c, type PlanVerdict as d, type PlanCheck as e, GUARD_EXIT_CODES as f, type GuardCheck as g, type GuardExitCode as h, type GuardStatus as i, PLAN_EXIT_CODES as j, type PlanCompletionMode as k, type PlanConstraint as l, type PlanExitCode as m, type PlanStatus as n, type PlanStep as o, type PrecedenceResolution as p, type SafetyCheck as q, type VerdictEvidence as r };