@neuroverseos/governance 0.1.6 → 0.2.2

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

@@ -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 };

package/dist/guard-engine-JLTUARGU.js

@@ -0,0 +1,10 @@
+import {
+  evaluateGuard,
+  eventToAllowlistKey
+} from "./chunk-4JRYGIO7.js";
+import "./chunk-4QXB6PEO.js";
+import "./chunk-YZFATT7X.js";
+export {
+  evaluateGuard,
+  eventToAllowlistKey
+};

package/dist/{impact-CHERK3O6.js → impact-XPECYRLH.js}

@@ -1,11 +1,13 @@
 import {
   generateImpactReport,
   renderImpactReport
-} from "./chunk-ITJ3LCPG.js";
+} from "./chunk-PDOZHZWL.js";
 import {
   readAuditLog
-} from "./chunk-FYPYZFV5.js";
-import "./chunk-B4NF3OLW.js";
+} from "./chunk-QPASI2BR.js";
+import "./chunk-4JRYGIO7.js";
+import "./chunk-4QXB6PEO.js";
+import "./chunk-YZFATT7X.js";
 
 // src/cli/impact.ts
 var USAGE = `

package/dist/{improve-YG6I6ERG.js → improve-GPUBKTEA.js}

@@ -1,12 +1,13 @@
 import {
   improveWorld,
   renderImproveText
-} from "./chunk-EIUHJXBB.js";
+} from "./chunk-GR6DGCZ2.js";
 import "./chunk-FYS2CBUW.js";
+import "./chunk-7P3S7MAY.js";
 import {
   loadWorld
-} from "./chunk-M3TZFGHO.js";
-import "./chunk-O5OMJMIE.js";
+} from "./chunk-JZPQGIKR.js";
+import "./chunk-YZFATT7X.js";
 
 // src/cli/improve.ts
 function parseArgs(argv) {