@neuroverseos/governance 0.3.4 → 0.4.1

package/dist/index.cjs

@@ -419,6 +419,67 @@ function parseValueLiteral(raw) {
   if (!isNaN(num) && raw.trim() !== "") return num;
   return raw;
 }
+function parseLenses(content, startLine, issues) {
+  const lenses = [];
+  const subSections = splitH2Sections(content, startLine);
+  for (const sub of subSections) {
+    const props = parseKeyValueBullets(sub.content);
+    const lineNum = sub.startLine;
+    const directives = [];
+    const lines = sub.content.split("\n");
+    let directiveIndex = 0;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (line.startsWith(">")) {
+        const blockContent = line.slice(1).trim();
+        const colonIdx = blockContent.indexOf(":");
+        if (colonIdx > 0) {
+          const scope = blockContent.slice(0, colonIdx).trim();
+          let instruction = blockContent.slice(colonIdx + 1).trim();
+          for (let j = i + 1; j < lines.length; j++) {
+            const nextLine = lines[j].trim();
+            if (nextLine.startsWith(">")) {
+              const nextContent = nextLine.slice(1).trim();
+              const nextColon = nextContent.indexOf(":");
+              if (nextColon > 0 && !nextContent.slice(0, nextColon).includes(" ")) {
+                break;
+              }
+              instruction += " " + nextContent;
+              i = j;
+            } else {
+              break;
+            }
+          }
+          directives.push({
+            id: `${sub.name}_directive_${directiveIndex++}`,
+            scope,
+            instruction,
+            line: startLine + i
+          });
+        }
+      }
+    }
+    const tags = (props.tags ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    const defaultForRoles = (props.default_for_roles ?? props.roles ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    lenses.push({
+      id: sub.name,
+      name: props.name ?? sub.name,
+      tagline: props.tagline ?? "",
+      description: props.description ?? "",
+      tags,
+      formality: props.formality ?? "neutral",
+      verbosity: props.verbosity ?? "balanced",
+      emotion: props.emotion ?? "neutral",
+      confidence: props.confidence ?? "balanced",
+      defaultForRoles,
+      directives,
+      priority: props.priority ? parseInt(props.priority, 10) : 50,
+      stackable: props.stackable === "false" ? false : true,
+      line: lineNum
+    });
+  }
+  return lenses;
+}
 function parseWorldMarkdown(markdown) {
   const issues = [];
   const { frontmatter: fmRaw, sections } = splitSections(markdown);
@@ -456,8 +517,22 @@ function parseWorldMarkdown(markdown) {
   }
   const outcomesSection = findSection("Outcomes");
   const outcomes = outcomesSection ? parseOutcomes(outcomesSection.content, outcomesSection.startLine, issues) : [];
+  const lensesSection = findSection("Lenses");
+  const lenses = lensesSection ? parseLenses(lensesSection.content, lensesSection.startLine, issues) : [];
+  let lensPolicy;
+  let lensLockPin;
+  if (lensesSection) {
+    const topContent = lensesSection.content.split(/^##\s/m)[0];
+    const topProps = parseKeyValueBullets(topContent);
+    if (topProps.policy === "locked" || topProps.policy === "role_default" || topProps.policy === "user_choice") {
+      lensPolicy = topProps.policy;
+    }
+    if (topProps.lock_pin) {
+      lensLockPin = topProps.lock_pin;
+    }
+  }
   const parsedSections = sections.map((s) => s.name);
-  const knownSections = /* @__PURE__ */ new Set(["thesis", "invariants", "state", "assumptions", "rules", "gates", "outcomes"]);
+  const knownSections = /* @__PURE__ */ new Set(["thesis", "invariants", "state", "assumptions", "rules", "gates", "outcomes", "lenses"]);
   for (const section of sections) {
     if (!knownSections.has(section.name.toLowerCase())) {
       issues.push({
@@ -483,7 +558,10 @@ function parseWorldMarkdown(markdown) {
       assumptions,
       rules,
       gates,
-      outcomes
+      outcomes,
+      lenses,
+      lensPolicy,
+      lensLockPin
     },
     issues
   };
@@ -655,6 +733,36 @@ function emitWorldDefinition(parsed) {
       structural_indicators: rules.filter((r) => r.severity === "structural").map((r) => r.id)
     }
   };
+  const validScopes = /* @__PURE__ */ new Set(["response_framing", "language_style", "content_filtering", "value_emphasis", "behavior_shaping"]);
+  const lensConfigs = parsed.lenses.map((pl) => {
+    const directives = pl.directives.map((d) => ({
+      id: d.id,
+      scope: validScopes.has(d.scope) ? d.scope : "behavior_shaping",
+      instruction: d.instruction
+    }));
+    return {
+      id: pl.id,
+      name: pl.name,
+      tagline: pl.tagline,
+      description: pl.description,
+      tags: pl.tags,
+      tone: {
+        formality: pl.formality || "neutral",
+        verbosity: pl.verbosity || "balanced",
+        emotion: pl.emotion || "neutral",
+        confidence: pl.confidence || "balanced"
+      },
+      directives,
+      defaultForRoles: pl.defaultForRoles,
+      priority: pl.priority,
+      stackable: pl.stackable
+    };
+  });
+  const lensesConfig = lensConfigs.length > 0 ? {
+    lenses: lensConfigs,
+    ...parsed.lensPolicy ? { policy: parsed.lensPolicy } : {},
+    ...parsed.lensLockPin ? { lockPin: parsed.lensLockPin } : {}
+  } : void 0;
   const metadata = {
     format_version: "1.0.0",
     created_at: (/* @__PURE__ */ new Date()).toISOString(),
@@ -669,6 +777,7 @@ function emitWorldDefinition(parsed) {
     rules,
     gates,
     outcomes,
+    ...lensesConfig ? { lenses: lensesConfig } : {},
     metadata
   };
   return { world: worldDefinition, issues };
@@ -840,6 +949,9 @@ __export(index_exports, {
   DERIVE_EXIT_CODES: () => DERIVE_EXIT_CODES,
   FileAuditLogger: () => FileAuditLogger,
   GUARD_EXIT_CODES: () => GUARD_EXIT_CODES,
+  GitHubGovernanceBlockedError: () => GitHubGovernanceBlockedError,
+  GitHubGovernor: () => GitHubGovernor,
+  GitHubWebhookHandler: () => GitHubWebhookHandler,
   McpGovernanceServer: () => McpGovernanceServer,
   ModelAdapter: () => ModelAdapter,
   PLAN_EXIT_CODES: () => PLAN_EXIT_CODES,
@@ -859,6 +971,10 @@ __export(index_exports, {
   classifyIntent: () => classifyIntent,
   classifyIntentWithAI: () => classifyIntentWithAI,
   createAgentState: () => createAgentState,
+  createGitHubGovernor: () => createGitHubGovernor,
+  createGitHubGovernorFromWorld: () => createGitHubGovernorFromWorld,
+  createGitHubWebhookHandler: () => createGitHubWebhookHandler,
+  createGitHubWebhookHandlerFromWorld: () => createGitHubWebhookHandlerFromWorld,
   createGovernanceEngine: () => createGovernanceEngine,
   createGovernor: () => createGovernor,
   deriveWorld: () => deriveWorld,
@@ -873,6 +989,8 @@ __export(index_exports, {
   explainWorld: () => explainWorld,
   extractContentFields: () => extractContentFields,
   extractWorldMarkdown: () => extractWorldMarkdown,
+  formatForActions: () => formatForActions,
+  formatPRComment: () => formatPRComment,
   formatVerdict: () => formatVerdict,
   formatVerdictOneLine: () => formatVerdictOneLine,
   generateAdaptationNarrative: () => generateAdaptationNarrative,
@@ -910,6 +1028,7 @@ __export(index_exports, {
   tickAgentStates: () => tickAgentStates,
   validateWorld: () => validateWorld,
   verdictToAuditEvent: () => verdictToAuditEvent,
+  verdictToEvent: () => verdictToEvent,
   writeTempWorld: () => writeTempWorld
 });
 module.exports = __toCommonJS(index_exports);
@@ -1297,6 +1416,33 @@ function evaluateGuard(event, world, options = {}) {
   let decidingId;
   const guardsMatched = [];
   const rulesMatched = [];
+  if (options.emergencyOverride) {
+    checkInvariantCoverage(world, invariantChecks);
+    return buildVerdict(
+      "ALLOW",
+      void 0,
+      "emergency-override",
+      "Emergency override active \u2014 all governance rules suspended. Platform constraints still apply.",
+      world,
+      level,
+      invariantChecks,
+      guardsMatched,
+      rulesMatched,
+      includeTrace ? buildTrace(
+        invariantChecks,
+        safetyChecks,
+        planCheckResult,
+        roleChecks,
+        guardChecks,
+        kernelRuleChecks,
+        levelChecks,
+        "session-allowlist",
+        "emergency-override",
+        startTime
+      ) : void 0,
+      event.intent
+    );
+  }
   checkInvariantCoverage(world, invariantChecks);
   if (event.roleId && options.agentStates) {
     const agentState = options.agentStates.get(event.roleId);
@@ -1361,7 +1507,8 @@ function evaluateGuard(event, world, options = {}) {
           decidingLayer,
           decidingId,
           startTime
-        ) : void 0
+        ) : void 0,
+        event.intent
       );
     }
   }
@@ -1390,7 +1537,8 @@ function evaluateGuard(event, world, options = {}) {
         decidingLayer,
         decidingId,
         startTime
-      ) : void 0
+      ) : void 0,
+      event.intent
     );
   }
   if (options.plan) {
@@ -1425,7 +1573,8 @@ function evaluateGuard(event, world, options = {}) {
           decidingLayer,
           decidingId,
           startTime
-        ) : void 0
+        ) : void 0,
+        event.intent
       );
     }
   }
@@ -1454,7 +1603,8 @@ function evaluateGuard(event, world, options = {}) {
         decidingLayer,
         decidingId,
         startTime
-      ) : void 0
+      ) : void 0,
+      event.intent
     );
   }
   const guardVerdict = checkGuards(event, eventText, world, guardChecks, guardsMatched);
@@ -1492,7 +1642,8 @@ function evaluateGuard(event, world, options = {}) {
           decidingLayer,
           decidingId,
           startTime
-        ) : void 0
+        ) : void 0,
+        event.intent
       );
       verdict.intentRecord = intentRecord;
       if (guardVerdict.consequence) verdict.consequence = guardVerdict.consequence;
@@ -1525,7 +1676,8 @@ function evaluateGuard(event, world, options = {}) {
         decidingLayer,
         decidingId,
         startTime
-      ) : void 0
+      ) : void 0,
+      event.intent
     );
   }
   const levelVerdict = checkLevelConstraints(event, level, levelChecks);
@@ -1553,7 +1705,8 @@ function evaluateGuard(event, world, options = {}) {
         decidingLayer,
         decidingId,
         startTime
-      ) : void 0
+      ) : void 0,
+      event.intent
     );
   }
   const warning = guardVerdict?.warning;
@@ -1578,7 +1731,8 @@ function evaluateGuard(event, world, options = {}) {
       decidingLayer,
       decidingId,
       startTime
-    ) : void 0
+    ) : void 0,
+    event.intent
   );
 }
 function checkInvariantCoverage(world, checks) {
@@ -1955,7 +2109,7 @@ function buildTrace(invariantChecks, safetyChecks, planCheck, roleChecks, guardC
   }
   return trace;
 }
-function buildVerdict(status, reason, ruleId, warning, world, level, invariantChecks, guardsMatched, rulesMatched, trace) {
+function buildVerdict(status, reason, ruleId, warning, world, level, invariantChecks, guardsMatched, rulesMatched, trace, eventIntent) {
   const evidence = {
     worldId: world.world.world_id,
     worldName: world.world.name,
@@ -1975,8 +2129,27 @@ function buildVerdict(status, reason, ruleId, warning, world, level, invariantCh
   if (ruleId) verdict.ruleId = ruleId;
   if (warning) verdict.warning = warning;
   if (trace) verdict.trace = trace;
+  verdict.event = verdictToEvent(status, eventIntent);
   return verdict;
 }
+function verdictToEvent(status, intent) {
+  const statusEventMap = {
+    ALLOW: "action_allowed",
+    BLOCK: "action_blocked",
+    PAUSE: "action_paused",
+    MODIFY: "action_modified",
+    PENALIZE: "action_penalized",
+    REWARD: "action_rewarded",
+    NEUTRAL: "action_neutral"
+  };
+  return {
+    type: intent || statusEventMap[status] || "unknown_action",
+    actor: "agent",
+    source: "guard",
+    timestamp: Date.now(),
+    guardStatus: status
+  };
+}
 
 // src/providers/ai-provider.ts
 var ChatCompletionsProvider = class {
@@ -6663,15 +6836,25 @@ function simulateWorld(world, options = {}) {
   let collapseStep;
   let collapseRule;
   const sortedRules = [...world.rules].sort((a, b) => a.order - b.order);
+  const allEvents = options.events ?? [];
+  const eventsByStep = Array.from({ length: steps }, () => []);
+  for (let i = 0; i < allEvents.length; i++) {
+    const stepIdx = Math.min(i, steps - 1);
+    eventsByStep[stepIdx].push(allEvents[i]);
+  }
+  let totalEventsConsumed = 0;
   for (let stepNum = 1; stepNum <= steps; stepNum++) {
     if (collapsed) break;
+    const stepEvents = eventsByStep[stepNum - 1];
     const stepResult = evaluateStep(
       stepNum,
       sortedRules,
       state,
       assumptions,
-      world
+      world,
+      stepEvents
     );
+    totalEventsConsumed += stepResult.eventsApplied.length;
     simulationSteps.push(stepResult);
     if (stepResult.collapsed) {
       collapsed = true;
@@ -6690,14 +6873,38 @@ function simulateWorld(world, options = {}) {
     finalViability,
     collapsed,
     collapseStep,
-    collapseRule
+    collapseRule,
+    eventsConsumed: totalEventsConsumed
   };
 }
-function evaluateStep(stepNum, rules, state, assumptions, world) {
+function evaluateStep(stepNum, rules, state, assumptions, world, events = []) {
   const evaluations = [];
+  const eventApplications = [];
   let rulesFired = 0;
   let collapsed = false;
   const firedRuleIds = /* @__PURE__ */ new Set();
+  for (const evt of events) {
+    const application = {
+      eventType: evt.type,
+      rulesTriggered: [],
+      effects: []
+    };
+    for (const rule of rules) {
+      const eventTrigger = rule.triggers.find(
+        (t) => t.field === "event" && t.source === "state"
+      );
+      if (!eventTrigger) continue;
+      const matches = evaluateOperator(evt.type, eventTrigger.operator, eventTrigger.value);
+      if (!matches) continue;
+      application.rulesTriggered.push(rule.id);
+      firedRuleIds.add(rule.id);
+      for (const effect of rule.effects ?? []) {
+        const applied = applyEffect(effect, state);
+        if (applied) application.effects.push(applied);
+      }
+    }
+    eventApplications.push(application);
+  }
   for (const rule of rules) {
     if (collapsed) {
       evaluations.push({
@@ -6782,6 +6989,7 @@ function evaluateStep(stepNum, rules, state, assumptions, world) {
   const viability = classifyViability(state, world);
   return {
     step: stepNum,
+    eventsApplied: eventApplications,
     rulesEvaluated: evaluations,
     rulesFired,
     stateAfter: { ...state },
@@ -6903,6 +7111,19 @@ function renderSimulateText(result) {
   lines.push("");
   for (const step of result.steps) {
     lines.push(`STEP ${step.step}`);
+    if (step.eventsApplied && step.eventsApplied.length > 0) {
+      for (const evt of step.eventsApplied) {
+        lines.push(`  EVENT: ${evt.eventType}`);
+        if (evt.rulesTriggered.length > 0) {
+          lines.push(`    Rules triggered: ${evt.rulesTriggered.join(", ")}`);
+        }
+        for (const effect of evt.effects) {
+          const beforeStr = formatValue(effect.before);
+          const afterStr = formatValue(effect.after);
+          lines.push(`    ${effect.target}: ${beforeStr} -> ${afterStr}`);
+        }
+      }
+    }
     const fired = step.rulesEvaluated.filter((r) => r.triggered);
     const skipped = step.rulesEvaluated.filter((r) => !r.triggered && !r.excluded);
     const excluded = step.rulesEvaluated.filter((r) => r.excluded);
@@ -6938,6 +7159,9 @@ function renderSimulateText(result) {
     lines.push(`  ${key}: ${formatValue(value)}${marker}`);
   }
   lines.push("");
+  if (result.eventsConsumed > 0) {
+    lines.push(`EVENTS CONSUMED: ${result.eventsConsumed}`);
+  }
   lines.push(`VIABILITY: ${result.finalViability}`);
   if (result.collapsed) {
     lines.push(`COLLAPSED at step ${result.collapseStep} (rule: ${result.collapseRule})`);
@@ -7588,6 +7812,440 @@ function round(n, decimals = 3) {
   return Math.round(n * factor) / factor;
 }
 
+// src/adapters/github.ts
+init_world_loader();
+
+// src/adapters/shared.ts
+var GovernanceBlockedError = class extends Error {
+  verdict;
+  constructor(verdict, message) {
+    super(message ?? `[NeuroVerse] BLOCKED: ${verdict.reason ?? verdict.ruleId ?? "governance rule"}`);
+    this.name = "GovernanceBlockedError";
+    this.verdict = verdict;
+  }
+};
+function trackPlanProgress(event, state, callbacks) {
+  if (!state.activePlan) return;
+  const planVerdict = evaluatePlan(event, state.activePlan);
+  if (planVerdict.matchedStep) {
+    const advResult = advancePlan(state.activePlan, planVerdict.matchedStep);
+    if (advResult.success && advResult.plan) {
+      state.activePlan = advResult.plan;
+      state.engineOptions.plan = state.activePlan;
+    }
+    const progress = getPlanProgress(state.activePlan);
+    callbacks.onPlanProgress?.(progress);
+    if (progress.completed === progress.total) {
+      callbacks.onPlanComplete?.();
+    }
+  }
+}
+function buildEngineOptions(options, plan) {
+  return {
+    trace: options.trace ?? false,
+    level: options.level,
+    plan: plan ?? options.plan
+  };
+}
+
+// src/adapters/github.ts
+var GitHubGovernanceBlockedError = class extends GovernanceBlockedError {
+  action;
+  constructor(verdict, action) {
+    super(verdict, `[NeuroVerse] GitHub action blocked: ${action.action} on ${action.repository}`);
+    this.name = "GitHubGovernanceBlockedError";
+    this.action = action;
+  }
+};
+function extractBranch(ref) {
+  if (!ref) return void 0;
+  if (ref.startsWith("refs/heads/")) return ref.slice("refs/heads/".length);
+  if (ref.startsWith("refs/tags/")) return ref.slice("refs/tags/".length);
+  return ref;
+}
+function isProtectedBranch(branch, protectedBranches) {
+  if (!branch) return false;
+  return protectedBranches.some(
+    (pb) => branch === pb || branch.startsWith(`${pb}/`)
+  );
+}
+function defaultMapAction(action, protectedBranches, restrictedActors) {
+  const branch = action.branch ?? extractBranch(action.ref);
+  const isProtected = isProtectedBranch(branch, protectedBranches);
+  const isRestricted = action.actor ? restrictedActors.some((ra) => action.actor === ra || action.actor?.endsWith("[bot]")) : false;
+  let actionCategory = "other";
+  const act = action.action.toLowerCase();
+  if (act.includes("read") || act.includes("get") || act.includes("list") || act.includes("view")) {
+    actionCategory = "read";
+  } else if (act.includes("delete") || act.includes("remove") || act.includes("close")) {
+    actionCategory = "delete";
+  } else if (act.includes("deploy") || act.includes("run") || act.includes("execute") || act.includes("merge")) {
+    actionCategory = "network";
+  } else if (act.includes("create") || act.includes("push") || act.includes("write") || act.includes("update") || act.includes("edit")) {
+    actionCategory = "write";
+  } else if (act.includes("comment") || act.includes("review") || act.includes("notify")) {
+    actionCategory = "other";
+  }
+  return {
+    intent: action.action,
+    tool: "github",
+    scope: `${action.repository}${branch ? `@${branch}` : ""}`,
+    actionCategory,
+    direction: "input",
+    args: {
+      repository: action.repository,
+      ref: action.ref,
+      branch,
+      actor: action.actor,
+      protected_branch: isProtected,
+      restricted_actor: isRestricted,
+      ...action.metadata
+    }
+  };
+}
+function defaultMapWebhook(eventType, payload) {
+  const repo = payload.repository;
+  const repoFullName = repo?.full_name ?? "unknown/unknown";
+  const sender = payload.sender;
+  const actor = sender?.login ?? void 0;
+  const webhookAction = payload.action;
+  switch (eventType) {
+    case "push": {
+      const ref = payload.ref;
+      const branch = extractBranch(ref);
+      const forced = payload.forced;
+      return {
+        action: forced ? "force_push" : `push_to_${branch ?? "branch"}`,
+        repository: repoFullName,
+        ref,
+        branch,
+        actor,
+        metadata: {
+          forced: forced ?? false,
+          commits_count: payload.commits?.length ?? 0,
+          head_commit: payload.head_commit?.id
+        }
+      };
+    }
+    case "pull_request": {
+      const pr = payload.pull_request;
+      const base = pr?.base;
+      const baseBranch = base?.ref;
+      const prNumber = pr?.number;
+      const merged = pr?.merged;
+      const labels = pr?.labels?.map((l) => l.name) ?? [];
+      let action = `pull_request_${webhookAction ?? "unknown"}`;
+      if (webhookAction === "closed" && merged) {
+        action = "merge_pull_request";
+      }
+      return {
+        action,
+        repository: repoFullName,
+        branch: baseBranch,
+        actor,
+        metadata: {
+          pr_number: prNumber,
+          labels,
+          merged: merged ?? false,
+          draft: pr?.draft ?? false,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "release": {
+      const release = payload.release;
+      return {
+        action: `release_${webhookAction ?? "published"}`,
+        repository: repoFullName,
+        ref: release?.tag_name ? `refs/tags/${release.tag_name}` : void 0,
+        actor,
+        metadata: {
+          tag: release?.tag_name,
+          prerelease: release?.prerelease ?? false,
+          draft: release?.draft ?? false,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "deployment":
+    case "deployment_status": {
+      const deployment = payload.deployment ?? payload;
+      return {
+        action: eventType === "deployment" ? "create_deployment" : "deployment_status_update",
+        repository: repoFullName,
+        ref: deployment.ref,
+        actor,
+        metadata: {
+          environment: deployment.environment,
+          status: payload.deployment_status?.state,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "workflow_run": {
+      const run = payload.workflow_run;
+      return {
+        action: `workflow_${webhookAction ?? "completed"}`,
+        repository: repoFullName,
+        branch: run?.head_branch,
+        actor,
+        metadata: {
+          workflow_name: run?.name,
+          conclusion: run?.conclusion,
+          status: run?.status,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "issues": {
+      const issue = payload.issue;
+      return {
+        action: `issue_${webhookAction ?? "opened"}`,
+        repository: repoFullName,
+        actor,
+        metadata: {
+          issue_number: issue?.number,
+          labels: issue?.labels?.map((l) => l.name) ?? [],
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "issue_comment": {
+      return {
+        action: `issue_comment_${webhookAction ?? "created"}`,
+        repository: repoFullName,
+        actor,
+        metadata: {
+          issue_number: payload.issue?.number,
+          webhook_action: webhookAction
+        }
+      };
+    }
+    case "delete": {
+      return {
+        action: `delete_${payload.ref_type ?? "ref"}`,
+        repository: repoFullName,
+        ref: payload.ref,
+        actor,
+        metadata: {
+          ref_type: payload.ref_type
+        }
+      };
+    }
+    default: {
+      return {
+        action: webhookAction ? `${eventType}_${webhookAction}` : eventType,
+        repository: repoFullName,
+        actor,
+        metadata: { webhook_action: webhookAction }
+      };
+    }
+  }
+}
+var GitHubGovernor = class {
+  world;
+  options;
+  engineOptions;
+  activePlan;
+  protectedBranches;
+  restrictedActors;
+  mapFn;
+  constructor(world, options = {}) {
+    this.world = world;
+    this.options = options;
+    this.activePlan = options.plan;
+    this.engineOptions = buildEngineOptions(options, this.activePlan);
+    this.protectedBranches = options.protectedBranches ?? ["main", "master", "production"];
+    this.restrictedActors = options.restrictedActors ?? [];
+    this.mapFn = options.mapAction ?? ((action) => defaultMapAction(action, this.protectedBranches, this.restrictedActors));
+  }
+  /**
+   * Evaluate a GitHub action against governance rules.
+   * Returns a full result with verdict, event, and the original action.
+   */
+  evaluate(action) {
+    const event = this.mapFn(action);
+    this.engineOptions.plan = this.activePlan;
+    const verdict = evaluateGuard(event, this.world, this.engineOptions);
+    this.options.onEvaluate?.(verdict, event, action);
+    if (verdict.status === "ALLOW") {
+      trackPlanProgress(event, this, this.options);
+    }
+    return { verdict, event, action };
+  }
+  /**
+   * Evaluate and enforce — throws GitHubGovernanceBlockedError on BLOCK/PAUSE.
+   * Use this as a gate before executing GitHub API calls.
+   */
+  enforce(action) {
+    const result = this.evaluate(action);
+    if (result.verdict.status === "BLOCK" || result.verdict.status === "PAUSE") {
+      throw new GitHubGovernanceBlockedError(result.verdict, action);
+    }
+    return result;
+  }
+  /**
+   * Check if pushing to a branch is allowed.
+   * Convenience method for the most common governance check.
+   */
+  canPush(repository, branch, actor) {
+    return this.evaluate({
+      action: `push_to_${branch}`,
+      repository,
+      ref: `refs/heads/${branch}`,
+      branch,
+      actor
+    }).verdict;
+  }
+  /**
+   * Check if merging a PR is allowed.
+   */
+  canMerge(repository, targetBranch, prNumber, actor, labels) {
+    return this.evaluate({
+      action: "merge_pull_request",
+      repository,
+      branch: targetBranch,
+      actor,
+      metadata: { pr_number: prNumber, labels: labels ?? [] }
+    }).verdict;
+  }
+  /**
+   * Check if creating a release is allowed.
+   */
+  canRelease(repository, tag, actor, prerelease) {
+    return this.evaluate({
+      action: "release_published",
+      repository,
+      ref: `refs/tags/${tag}`,
+      actor,
+      metadata: { tag, prerelease: prerelease ?? false }
+    }).verdict;
+  }
+  /**
+   * Check if deploying to an environment is allowed.
+   */
+  canDeploy(repository, environment, ref, actor) {
+    return this.evaluate({
+      action: "create_deployment",
+      repository,
+      ref,
+      actor,
+      metadata: { environment }
+    }).verdict;
+  }
+};
+var GitHubWebhookHandler = class {
+  governor;
+  mapWebhookFn;
+  webhookSecret;
+  constructor(world, options = {}) {
+    this.governor = new GitHubGovernor(world, options);
+    this.mapWebhookFn = options.mapWebhook ?? defaultMapWebhook;
+    this.webhookSecret = options.webhookSecret;
+  }
+  /**
+   * Evaluate a webhook payload.
+   *
+   * @param eventType - The X-GitHub-Event header value
+   * @param payload - The parsed webhook body
+   */
+  evaluate(eventType, payload) {
+    const action = this.mapWebhookFn(eventType, payload);
+    const result = this.governor.evaluate(action);
+    return {
+      verdict: result.verdict,
+      event: result.event,
+      webhookEvent: eventType,
+      webhookAction: payload.action
+    };
+  }
+  /**
+   * Evaluate and enforce — throws on BLOCK/PAUSE.
+   */
+  enforce(eventType, payload) {
+    const result = this.evaluate(eventType, payload);
+    if (result.verdict.status === "BLOCK" || result.verdict.status === "PAUSE") {
+      const action = this.mapWebhookFn(eventType, payload);
+      throw new GitHubGovernanceBlockedError(result.verdict, action);
+    }
+    return result;
+  }
+  /** Access the underlying governor for direct action evaluation. */
+  getGovernor() {
+    return this.governor;
+  }
+  /** Get the configured webhook secret (for signature verification in your server). */
+  getWebhookSecret() {
+    return this.webhookSecret;
+  }
+};
+function formatForActions(verdict) {
+  const status = verdict.status === "ALLOW" ? "allowed" : verdict.status === "BLOCK" ? "blocked" : "paused";
+  const reason = verdict.reason ?? "";
+  const ruleId = verdict.ruleId ?? "";
+  const lines = [
+    `governance_status=${status}`,
+    `verdict_status=${verdict.status}`,
+    `reason=${reason}`,
+    `rule_id=${ruleId}`
+  ].join("\n");
+  return {
+    governance_status: status,
+    verdict_status: verdict.status,
+    reason,
+    rule_id: ruleId,
+    outputLines: lines
+  };
+}
+function formatPRComment(verdict, action) {
+  const icon = verdict.status === "ALLOW" ? "\u2705" : verdict.status === "BLOCK" ? "\u{1F6AB}" : "\u23F8\uFE0F";
+  const status = verdict.status;
+  let body = `## ${icon} Governance: ${status}
+
+`;
+  body += `**Action:** \`${action.action}\`
+`;
+  body += `**Repository:** \`${action.repository}\`
+`;
+  if (action.branch) {
+    body += `**Branch:** \`${action.branch}\`
+`;
+  }
+  if (action.actor) {
+    body += `**Actor:** \`${action.actor}\`
+`;
+  }
+  body += "\n";
+  if (verdict.reason) {
+    body += `**Reason:** ${verdict.reason}
+`;
+  }
+  if (verdict.ruleId) {
+    body += `**Rule:** \`${verdict.ruleId}\`
+`;
+  }
+  if (verdict.evidence?.invariantsSatisfied < verdict.evidence?.invariantsTotal) {
+    body += `**Invariants:** ${verdict.evidence.invariantsSatisfied}/${verdict.evidence.invariantsTotal} satisfied
+`;
+  }
+  body += "\n---\n*Evaluated by [NeuroVerse Governance](https://github.com/NeuroverseOS/neuroverseos-governance)*";
+  return body;
+}
+async function createGitHubGovernor(worldPath, options) {
+  const world = await loadWorld(worldPath);
+  return new GitHubGovernor(world, options);
+}
+function createGitHubGovernorFromWorld(world, options) {
+  return new GitHubGovernor(world, options);
+}
+async function createGitHubWebhookHandler(worldPath, options) {
+  const world = await loadWorld(worldPath);
+  return new GitHubWebhookHandler(world, options);
+}
+function createGitHubWebhookHandlerFromWorld(world, options) {
+  return new GitHubWebhookHandler(world, options);
+}
+
 // src/engine/api.ts
 init_world_loader();
 function handleHealthCheck() {
@@ -7664,6 +8322,9 @@ function handleCreateCapsule(body) {
   DERIVE_EXIT_CODES,
   FileAuditLogger,
   GUARD_EXIT_CODES,
+  GitHubGovernanceBlockedError,
+  GitHubGovernor,
+  GitHubWebhookHandler,
   McpGovernanceServer,
   ModelAdapter,
   PLAN_EXIT_CODES,
@@ -7683,6 +8344,10 @@ function handleCreateCapsule(body) {
   classifyIntent,
   classifyIntentWithAI,
   createAgentState,
+  createGitHubGovernor,
+  createGitHubGovernorFromWorld,
+  createGitHubWebhookHandler,
+  createGitHubWebhookHandlerFromWorld,
   createGovernanceEngine,
   createGovernor,
   deriveWorld,
@@ -7697,6 +8362,8 @@ function handleCreateCapsule(body) {
   explainWorld,
   extractContentFields,
   extractWorldMarkdown,
+  formatForActions,
+  formatPRComment,
   formatVerdict,
   formatVerdictOneLine,
   generateAdaptationNarrative,
@@ -7734,5 +8401,6 @@ function handleCreateCapsule(body) {
   tickAgentStates,
   validateWorld,
   verdictToAuditEvent,
+  verdictToEvent,
   writeTempWorld
 });