@herjarsa/omo-meta-governor 0.51.0 → 0.53.0

package/README.md

@@ -29,6 +29,8 @@
   - [Auto-upgrade (v0.26.0)](#auto-upgrade-v0260)
   - [Git hooks](#git-hooks)
   - [Process safeguards](#process-safeguards)
+  - [CLI-Anything hub (v0.28.0)](#cli-anything-hub-v0280)
+  - [On-demand upgrades (W4-C)](#on-demand-upgrades-w4-c)
 - [Persistence & observability](#persistence--observability)
 - [CI monitor (v0.25.0)](#ci-monitor-v0250)
 - [Configuration reference](#configuration-reference)
@@ -84,18 +86,18 @@ Minimal config to enable the governance pipeline:
 }
 ```
 
-### Oracle frequency (v0.38.4+, Option D)
+### Oracle frequency
 
 Controls when the plugin invokes Oracle for verification:
 
 ```jsonc
 {
   "oracle": {
-    // "per-stop" (default): Oracle invoked ONLY at the final-gate AND when
+    // "final-only" (default): Oracle invoked ONLY at the final-gate. Zero mid-work.
+    // "per-stop": Oracle invoked ONLY at the final-gate AND when
     // scoring reaches stop band (action === "stop"). warn/escalate log only.
-    // "final-only": Oracle invoked ONLY at the final-gate. Zero mid-work.
     // "off": Oracle never invoked automatically. Set oracleVerified manually.
-    "frequency": "per-stop"
+    "frequency": "final-only"
   }
 }
 ```
@@ -103,6 +105,18 @@ Controls when the plugin invokes Oracle for verification:
 The `<promise>DONE</promise>` / `<promise>PLAN-COMPLETE</promise>` final-gate
 ALWAYS invokes Oracle regardless of `oracle.frequency`.
 
+| `frequency` | Mid-work Oracle | Final-gate Oracle | Typical invocations / session |
+|---|---|---|---|
+| `final-only` (default) | Never — even `stop` decisions log without an Oracle prompt | Always | Exactly 1 (final-gate); zero mid-work interruptions |
+| `per-stop` | ONLY when scoring reaches the stop band (`action === "stop"`); `warn`/`escalate` log only (`escalation suppressed by oracle.frequency`) | Always | 1 (final-gate) + 1 per stop-level emergency |
+| `off` | Never invoked automatically | Never — set `oracleVerified` manually (e.g. via `omo_recall`) | 0 |
+
+Implementation: `selectEscalationTarget()` in `src/scoring-engine.ts`
+returns `null` for `off`/`final-only` (any action) and for `per-stop` unless
+action is `"stop"`; `src/plugin.ts` respects the `null` (logs `escalation
+suppressed by oracle.frequency`) while the DONE final-gate handler
+(`detectPlanCompleteSignal` path) invokes Oracle separately.
+
 ---
 
 ## What it does
@@ -404,6 +418,61 @@ Config: `graphSync.killOrphanedOnInit` (default `true`) — on graph-sync
 init the plugin sweeps orphaned `graphify`/`codegraph` processes left
 by previous crashed runs. Set to `false` to disable the sweep.
 
+### CLI-Anything hub (v0.28.0)
+
+Parallel to graph-sync, the plugin ensures the CLI-Anything ecosystem
+(`cli-hub` registry/installer + `npx skills` meta-skill) is installed and
+current. **Opt-out: enabled by default** — every default projection uses
+`!== false`, so omitting the block means ON:
+
+```jsonc
+{
+  "meta_governor": {
+    "cliAnything": {
+      "enabled": true,          // default true — opt-out
+      "autoInstall": true,      // default true
+      "autoUpgrade": true,      // default true
+      "upgradeCheckTtlMs": 86400000  // 24h registry-query TTL
+    }
+  }
+}
+```
+
+To disable (e.g. offline machines, hermetic tests):
+
+```jsonc
+{
+  "meta_governor": {
+    "cliAnything": { "enabled": false }
+  }
+}
+```
+
+Independent of `graphSync.enabled` (W1-A1 desanidado): disabling graphSync
+does NOT disable cliAnything and vice-versa. Both run fire-and-forget at
+factory invocation, never blocking session start. The test seam
+`__test_onCliAnythingInit` mirrors `__test_onGraphSyncInit` for placement
+assertions without spawning real subprocesses.
+
+### On-demand upgrades (W4-C)
+
+Two tools expose the backend upgrade path on demand (codegraph + graphify):
+
+| Tool | What it does | Use case |
+|------|--------------|----------|
+| `omo_upgrade_check` | Dry-run version table (installed / latest / upgrade-needed per backend). NEVER installs anything. | "Is an upgrade pending?" — safe to call any time |
+| `omo_upgrade_run` | Executes the upgrade path once. Respects the 24h TTL cache (`upgradeCheckTtlMs`, default `86400000`): skips with `skipped:true` when the cache is fresh. Best-effort, never throws. | "Upgrade the backends now" |
+
+Both are registered on all three surfaces: V1 `tool` hook (governance-enabled
+and governance-disabled paths), V2 (`registerOmoTools`), and MCP
+(`getAdapters()` + `MCP_TOOL_NAMES`).
+
+> **Nota `syncIntervalMs` (startup-only):** `syncIntervalMs` applies ONLY to
+> the `skillHub` registry sync (periodic background refresh of the skill
+> catalog). `omo_upgrade_check` / `omo_upgrade_run` are **on-demand /
+> startup-only** — they NEVER use `setInterval` and never poll in the
+> background.
+
 ## MCP server mode (v0.31.0)
 
 OpenCode Desktop and OpenChamber spawn `opencode serve` in HTTP/sidecar mode
@@ -575,6 +644,7 @@ All configuration lives under the `meta_governor` key in
 | `protocolEnforcement` | object | — | Sisyphus protocol enforcement. |
 | `skillPriming` | object | — | Proactive skill-selection nudge (v0.20.0). |
 | `graphSync` | object | — | Graph synchronization (auto-init codegraph/graphify). |
+| `cliAnything` | object | — | CLI-Anything hub auto-install + auto-upgrade (opt-out, enabled by default). |
 
 ### `decision`
 
@@ -678,6 +748,19 @@ All configuration lives under the `meta_governor` key in
 | `upgradeCachePath` | string | — | **v0.26.0** — path for the upgrade cache file. |
 | `checkGraphifyNeedsUpdate` | boolean | `true` | **v0.26.0** — run `graphify check-update` after upgrade. |
 
+### `cliAnything`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | boolean | `true` | Opt-out master switch — set `cliAnything.enabled:false` to disable. Canonical `!== false` projection. |
+| `autoInstall` | boolean | `true` | Auto-install `cli-hub` + meta-skill when missing. |
+| `autoUpgrade` | boolean | `true` | Auto-upgrade on factory init (TTL-gated). |
+| `cachePath` | string | — | Upgrade-check cache file (effective default `newPluginPaths().cliAnythingUpgradeCheck`). |
+| `upgradeCheckTtlMs` | number | `86400000` | Min ms between registry queries (24h). Effective default applied at call-site (`plugin.ts`). |
+| `cliHubBin` | string | `"cli-hub"` | Path to `cli-hub` binary. |
+| `skillsBin` | string | `"npx skills"` | Path to `npx skills` invocation. |
+| `installScope` | enum | `"global"` | `"global"` \| `"project"`. |
+
 ---
 
 ## Architecture overview

package/dist/adherence.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Adherence tracking — detects when the agent IGNORES an already-injected
+ * directive (same rule violated again after the injection was drained).
+ *
+ * Why this exists: protocol violations are injected into the agent context
+ * (system.transform drain, FASE 11 11e), but nothing measured whether the
+ * agent actually complied afterwards. A repeat violation of the same rule
+ * AFTER the agent saw the directive is evidence of non-adherence, not of a
+ * missing directive — so it is counted separately (`directives_ignored`)
+ * instead of re-injecting louder each time.
+ *
+ * Lifecycle (per session):
+ *   1. tool.execute.before detects violation of rule R.
+ *   2. If R was already injected (drained) in this session → reincidencia:
+ *      `directives_ignored` + `adherence_ignored` log. Never escalates by
+ *      itself for leve/media (counting only — explicit below).
+ *   3. system.transform drains pendingViolations → each distinct rule R in
+ *      the drained items is recorded via `recordInjection` (injected = the
+ *      agent saw it; detection alone does NOT mark — the agent may never
+ *      have seen an undrained queue).
+ *   4. Scoring: ONLY grave reincidence with repeatCount >= 2 (third strike
+ *      counting the original) floors the decision to `stop`. The
+ *      stop → paralysis → continue loop stays supreme: a persistent false
+ *      positive still resolves via paralysisOverride forcing continue after
+ *      N consecutive stops, so adherence can never deadlock a session.
+ *
+ * Severity policy (explicit):
+ *   - leve / media reincidence: counted in `directives_ignored`, NEVER
+ *     escalates on its own. See `adherenceFloor` — it returns null for
+ *     non-grave severities unconditionally.
+ *   - grave reincidence: counted; escalates to `stop` ONLY at repeatCount
+ *     >= ADHERENCE_STOP_REPEAT_THRESHOLD (2). Below that, the Wave B grave
+ *     floor (continue/warn → escalate) still applies as before.
+ *
+ * All helpers here are pure (no I/O, no Date.now, no globals) so they are
+ * unit-testable without the plugin factory.
+ */
+/** Rule -> times the rule's directive was drained (seen by the agent). */
+export type InjectedRules = Record<string, number>;
+/**
+ * How many times a rule's directive was already injected when a new
+ * violation arrives. repeatCount >= ADHERENCE_STOP_REPEAT_THRESHOLD means
+ * the third strike (original + 2 repeats).
+ */
+export declare const ADHERENCE_STOP_REPEAT_THRESHOLD = 2;
+/** Cap of distinct rules tracked per session (bounds per-session memory). */
+export declare const ADHERENCE_MAX_RULES = 50;
+/**
+ * Record that rule `rule` was injected (drained into agent context).
+ * Returns a NEW record (input is not mutated). When the record already
+ * holds ADHERENCE_MAX_RULES distinct rules, the new rule is dropped so a
+ * noisy session cannot grow memory unboundedly.
+ */
+export declare function recordInjection(rules: Readonly<InjectedRules>, rule: string): InjectedRules;
+/**
+ * How many times `rule` was already injected in this session (0 = never —
+ * the current violation is the first occurrence, NOT a reincidencia).
+ */
+export declare function countRepeat(rules: Readonly<InjectedRules>, rule: string): number;
+/**
+ * Adherence escalation floor. Returns "stop" ONLY for grave reincidence at
+ * or above the repeat threshold. leve/media ALWAYS return null (counted,
+ * never escalated — see module docstring). Unknown severities return null.
+ */
+export declare function adherenceFloor(severity: string, repeatCount: number): "stop" | null;
+/**
+ * Extract distinct rule names from drained violation entry strings.
+ * Entries are formatted as `[SEVERITY] rule: detail` (see plugin.ts queue
+ * site). Returns distinct rules in first-seen order; unparseable entries
+ * are skipped (never throw — drain is best-effort).
+ */
+export declare function parseInjectedRules(items: readonly string[]): string[];

package/dist/closed-loop-learning.d.ts

@@ -16,6 +16,25 @@
  * - No file I/O, no MCP calls — just decision logic + DI write.
  */
 import type { AgentmemoryWriteBackend, ClosedLoopConfig, Decision, Deviation, LearnFromOutcomeInput, LearnFromOutcomeOutput } from "./types";
+/**
+ * v0.51.1 (P1 lesson-spam guard, Wave A T-5df16a0e): minimum lesson
+ * confidence. Lessons below this are noise: 5311 Action-continue rows at
+ * confidence 0.3 flooded recall. Only high-value lessons persist.
+ */
+export declare const MIN_LESSON_CONFIDENCE = 0.5;
+/**
+ * Lesson confidence for a decision: the strongest available signal -
+ * max(|score|, best evidence confidence) - clamped to [0.3, 0.8].
+ * Evidence confidence matters: a warn at -0.4 backed by 0.8-confidence
+ * evidence is high-value signal, while a neutral continue near 0 with no
+ * evidence collapses to the 0.3 floor (below MIN_LESSON_CONFIDENCE).
+ */
+export declare function lessonConfidenceForDecision(decision: Decision): number;
+/**
+ * Neutral continues carry no learnable signal and must never persist as
+ * lessons - they were the entire 5311-row Action-continue spam class.
+ */
+export declare function isNeutralContinueDecision(decision: Decision): boolean;
 /** Severity ordering for threshold comparison. */
 declare const SEVERITY_ORDER: Record<string, number>;
 /**

package/dist/config.d.ts

@@ -83,24 +83,26 @@ export interface MetaGovernorPluginConfig {
     /** Model override for MetaGovernor internal LLM usage. */
     modelOverride?: ModelOverrideConfig;
     /**
-     * v0.38.4: Oracle invocation frequency. Controls when the plugin invokes
+     * Oracle invocation frequency. Controls when the plugin invokes
      * Oracle for verification — reduces noisy mid-work escalations.
      *
-     * - `"per-stop"` (default, Option D): Oracle is invoked ONLY at the
-     *   final-gate (`<promise>DONE</promise>`) AND when score crosses the
-     *   stop threshold (`≤ -stopThreshold`). warn/escalate decisions log
-     *   but do NOT inject an Oracle prompt mid-work. Best balance: silent
-     *   on normal work, brake on emergencies, mandatory at done.
-     *
-     * - `"final-only"` (Option A): Oracle is invoked ONLY at the final-gate.
+     * - `"final-only"` (default): Oracle is invoked ONLY at the final-gate.
      *   Even stop-level decisions log without injecting an Oracle prompt.
-     *   Use when you want zero mid-work interruptions.
+     *   Zero mid-work interruptions.
+     *
+     * - `"per-stop"`: Oracle is invoked at the final-gate
+     *   (`<promise>DONE</promise>`) AND when the scoring engine reaches the
+     *   stop band (action === "stop"). warn/escalate decisions log but do
+     *   NOT invoke Oracle mid-work. Brake on emergencies, mandatory at done.
+     *   (B3: wording copied from enforcement-resources.ts buildOracleRule;
+     *   the previous text said "ONLY at the final-gate ... AND when",
+     *   which is self-contradictory.)
      *
      * - `"off"`: Oracle is never invoked. The post-wave gate still requires
      *   `oracleVerified` — set it manually via `omo_recall` if you need it.
      */
     oracle?: {
-        /** @default "per-stop" */
+        /** @default "final-only" */
         frequency?: "per-stop" | "final-only" | "off";
     };
     /** Intervention config for visible decision injection. */
@@ -115,7 +117,8 @@ export interface MetaGovernorPluginConfig {
         minActionForMessage?: "warn" | "escalate" | "stop";
         /**
          * v0.10.0: rate-limit interventions to break instruction loops.
-         * @default 3
+         * v0.51.x (Wave A P3): severity-tiered quota — only escalate/stop consume.
+         * @default 5
          */
         maxInterventionsPerSession?: number;
         /**
@@ -220,6 +223,11 @@ export interface MetaGovernorPluginConfig {
         injectIntoSystem?: boolean;
         auditToolCalls?: boolean;
     };
+    /** Wave B workflow gates (explore-before-implement). All default false. */
+    workflowGates?: {
+        enabled?: boolean;
+        requirePlan?: boolean;
+    };
     /** Graph sync config for auto-initializing codegraph/graphify. */
     graphSync?: {
         /** @default true */
@@ -263,20 +271,28 @@ export interface MetaGovernorPluginConfig {
          * Default false (opt-in — multi-project users want explicit control). */
         addToGlobalGraph?: boolean;
     };
-    /** v0.28.0: CLI-Anything hub auto-install + auto-upgrade. Opt-in.
+    /** v0.28.0: CLI-Anything hub auto-install + auto-upgrade. Opt-out
+     *  (enabled by default; set `cliAnything.enabled: false` to disable).
      *  When enabled, the plugin ensures `cli-anything-hub` (pip) and
-     *  `cli-hub-meta-skill` (npx skills) are installed and current. */
+     *  `cli-hub-meta-skill` (npx skills) are installed and current.
+     *  Canonical projection is `!== false` (see loadOrchestratorConfig
+     *  cliAnything projection and orchestrator.ts CLI-Anything defaults). */
     cliAnything?: {
-        /** @default false */
+        /** @default true (opt-out via `cliAnything.enabled: false`;
+         * canonical `!== false` projection in orchestrator.ts) */
         enabled?: boolean;
         /** @default true */
         autoInstall?: boolean;
         /** @default true */
         autoUpgrade?: boolean;
+        /** @default newPluginPaths().cliAnythingUpgradeCheck
+         * (effective default applied at call-site, plugin.ts) */
         cachePath?: string;
-        /** @default 86400000 */
+        /** @default 86400000 (24h; effective default applied at call-site, plugin.ts:649) */
         upgradeCheckTtlMs?: number;
+        /** @default "cli-hub" */
         cliHubBin?: string;
+        /** @default "npx skills" */
         skillsBin?: string;
         /** @default "global" */
         installScope?: "global" | "project";

package/dist/custom-tools.d.ts

@@ -23,6 +23,19 @@ import type { SqliteBackend } from "./sqlite-backend";
 import type { GraphRetrieval } from "./graph-retrieval";
 import type { MetricsCollector } from "./metrics";
 import { type CodeGraphTools } from "./codegraph-tools";
+/**
+ * Canonical routing suffix for a tool description (Wave C part 2).
+ *
+ * Why this exists: the agent sees tool descriptions on every turn, while the
+ * graph-priming injection fires once per session. Embedding the canonical
+ * routing line in the description keeps "which tool for which question"
+ * visible without depending on that one-shot injection.
+ *
+ * Why lookup by ROUTING_MATRIX: the matrix is the single canonical source -
+ * reusing it here keeps descriptions in sync when the matrix changes, instead
+ * of duplicating tool-name literals at each call site.
+ */
+export declare function routingSuffixFor(toolName: string): string;
 /**
  * Module-level reference to the PendingDeliveryRegistry. The plugin
  * factory sets this once at startup. Bridge tools call it via
@@ -441,6 +454,29 @@ export declare function buildOmoHookStatusTool(deps: OmoHookStatusDeps): {
     args: {};
     execute(args: Record<string, never>, context: ToolContext): Promise<ToolResult>;
 };
+export interface OmoUpgradeDeps {
+    cwd: string;
+    /** Optional runner DI seam for tests. When undefined, uses real subprocesses. */
+    runner?: (cmd: string, opts?: {
+        timeoutMs?: number;
+    }) => string;
+    /** Min ms between registry queries. Default 24h. */
+    upgradeCheckTtlMs?: number;
+    /** Override the upgrade cache file path. Tests use this. */
+    upgradeCachePath?: string;
+}
+/** `omo_upgrade_check` — dry-run version check. NEVER installs anything. */
+export declare function buildOmoUpgradeCheckTool(deps: OmoUpgradeDeps): {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: ToolContext): Promise<ToolResult>;
+};
+/** `omo_upgrade_run` — perform the backend upgrade path once. Best-effort, never throws. */
+export declare function buildOmoUpgradeRunTool(deps: OmoUpgradeDeps): {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: ToolContext): Promise<ToolResult>;
+};
 export interface OmoCliAnythingDeps {
     cwd: string;
     /** Optional runner DI seam for tests. When undefined, uses real execSync. */

package/dist/enforcement-resources.d.ts

@@ -1,46 +1,23 @@
-/**
- * v0.37.0 (audit enforcement) — MCP enforcement resources for OpenChamber.
- *
- * Bug (audit v2 P0-2): In OpenChamber (HTTP mode), the plugin factory never
- * runs. Only MCP tools are exposed. All text-based instructions (Oracle rule 4,
- * agentmemory rule 8, skill-priming) live in `output.messages.push` /
- * `system.transform` which require plugin hooks. OpenChamber receives ZERO
- * enforcement.
- *
- * Fix: expose the rules as MCP resources that the agent can `resources/read`
- * at startup. Works in both plugin-CLI and OpenChamber modes.
- *
- * Contract:
- * - `meta-governor://rules/oracle` → Oracle gate rule text
- * - `meta-governor://rules/agentmemory` → omo_remember rule text
- * - `meta-governor://rules/skill-priming` → skill discovery rule text
- * - `meta-governor://rules/protocol` → Sisyphus protocol enforcement rules
- *
- * The returned text uses a `[SYSTEM-NUDGE]` prefix the LLM can detect.
- */
 export declare const ENFORCEMENT_RESOURCE_URIS: readonly ["meta-governor://rules/oracle", "meta-governor://rules/agentmemory", "meta-governor://rules/skill-priming", "meta-governor://rules/protocol"];
 export type EnforcementResourceUri = (typeof ENFORCEMENT_RESOURCE_URIS)[number];
 /**
- * Build the Oracle gate rule (v0.38.4 Option D — Oracle frequency).
+ * Build the Oracle gate rule (Oracle frequency).
  *
- * v0.38.4 REWRITE: Oracle is no longer auto-invoked mid-work for every
- * multi-file change. Instead, the `oracle.frequency` config controls when
- * Oracle fires:
- *   - `"per-stop"` (default): Oracle invoked at the final-gate
+ * Oracle is no longer auto-invoked mid-work for every multi-file change.
+ * Instead, the `oracle.frequency` config controls when Oracle fires:
+ *   - `"final-only"` (default): Oracle invoked ONLY at the final-gate.
+ *     Even stop-level decisions log without invoking Oracle mid-work.
+ *   - `"per-stop"`: Oracle invoked at the final-gate
  *     (<promise>DONE</promise>) AND when the scoring engine reaches the
  *     stop band (action === "stop"). warn/escalate log but do NOT
  *     invoke Oracle mid-work.
- *   - `"final-only"`: Oracle invoked ONLY at the final-gate. Even
- *     stop-level decisions log without invoking Oracle mid-work.
  *   - `"off"`: Oracle is NEVER invoked automatically. The agent must
  *     set `oracleVerified` manually (e.g. via omo_recall).
  *
  * The DONE final-gate is ALWAYS Oracle-verified regardless of frequency.
  *
  * Same MCP resource contract as before — `meta-governor://rules/oracle`
- * still returns this text. The previous "INVOKE triggers per multi-file
- * change" was the source of the noise — now mid-work Oracle is
- * gated by score band, not file count.
+ * still returns this text.
  */
 export declare function buildOracleRule(): string;
 /**

package/dist/graph-sync.d.ts

@@ -186,6 +186,13 @@ export declare const logToFile: typeof _logToFile;
  * triggering a network call.
  */
 export declare function isNewerVersion(installed: string | null | undefined, latest: string | null | undefined): boolean;
+/**
+ * P4 (v0.51.x): self-version STALE_CACHE polarity gate. Returns true ONLY
+ * when `latest` (npm registry) is strictly newer than `loaded` (running
+ * bundle) — equal versions (incl. "v"-prefix/whitespace variants) and
+ * loaded-newer-than-npm (local dev) stay silent. Pure: no I/O, no TTL.
+ */
+export declare function shouldWarnStaleCache(loaded: string | null | undefined, latest: string | null | undefined): boolean;
 /**
  * v0.12.0: persisted cache of latest-version lookups so we don't
  * hammer npm/pip registries on every plugin load.