@alan512/experienceengine 0.1.3 → 0.2.1

package/docs/user-guide.md

@@ -59,10 +59,12 @@ When it injects guidance, you will usually see a lightweight notice like:
 [ExperienceEngine] Injected 1 strategy hint for this task.
 ```
 
-If there is no intervention, it stays silent.
+If there is no intervention, it stays silent during the task. The delivery decision is still recorded, so `ee inspect --last` and host-side inspection can explain whether ExperienceEngine skipped because the match was weak, the node was not safe to ship yet, or the decision stayed in a conservative path.
 
 When ExperienceEngine is less certain but still sees a credible same-family match, it may choose a conservative injection instead of skipping entirely. In that case the injected block stays smaller by default, but mature low-risk nodes can still include a short `Goal / Steps / Avoid` structure when that makes the guidance more actionable.
 
+ExperienceEngine now uses a deterministic match scorecard before live delivery. Same-repo, high-match experience can ship directly when trust is already strong. Same-repo conservative experience can be promoted after a successful high-match reuse. Cross-repo matches are allowed only as conservative candidates unless later evidence proves they are safe in the new scope.
+
 When you inspect the latest turn, you may also see a learning decision such as:
 
 ```text
@@ -155,6 +157,8 @@ ee status
 
 Use `ee init` once to initialize ExperienceEngine's shared distillation, embedding, and secret state. New host installations should reuse that same shared EE state instead of asking you to re-enter the same API key per host window.
 
+For Codex, `ee status` and `ee doctor codex` also show whether the `ee` CLI fallback is available on `PATH`. Codex MCP wiring can still be healthy without that fallback, but explicit operator commands such as `ee inspect --last` need either a PATH-visible `ee` binary or an explicit package invocation.
+
 In practical terms, the routine loop currently looks like this:
 
 - `Codex`
@@ -251,9 +255,9 @@ When you inspect a specific node, ExperienceEngine now also shows a lightweight
 
 ## How MCP Interaction Works
 
-For `Codex` and `Claude Code`, ExperienceEngine is designed to work mainly through MCP.
+For `Codex` and `Claude Code`, ExperienceEngine is designed to keep routine review and management inside the host session first.
 
-That means after installation, you usually do not leave the agent session to manage ExperienceEngine. Instead, you ask the agent naturally and the agent can call ExperienceEngine MCP resources, prompts, and tools for you.
+That means after installation, you usually do not leave the agent session to manage ExperienceEngine. Instead, you ask the agent naturally and the host uses its native EE wiring for routine interaction.
 
 This is one host-specific implementation of the same shared product model described above:
 
@@ -275,14 +279,23 @@ Typical examples:
 
 ### MCP Interaction Model
 
-ExperienceEngine exposes three MCP categories:
+`Codex` exposes a layered MCP surface:
+
+- `Direct tools`
+  - core loop actions like lookup, recording important tool outcomes, finalize, last-feedback, capabilities, and doctor
+- `Routine read resources`
+  - read-only state like last interaction, recent history, repo summary, and routine node views
+- `Brokered advanced actions`
+  - lower-frequency inspect, admin, maintenance, and high-impact plan/execute flows exposed through a small broker tool surface instead of many direct schemas
 
-- `Resources`
-  - read-only state like last interaction, recent history, nodes, doctor output, update state, and backups
-- `Prompts`
-  - reusable workflows that guide the agent to inspect or manage ExperienceEngine safely
-- `Tools`
-  - executable actions like feedback, scope toggles, node lifecycle changes, and high-impact operations
+For `Codex`, this means routine host-native interaction stays discoverable, while long-tail admin and maintenance actions are reached through brokered actions rather than public prompts or one-tool-per-action registration.
+
+`Claude Code` still uses both `hooks` and `MCP`:
+
+- hooks drive runtime capture and injection
+- MCP drives inspect, control, and operational interaction
+
+So the two hosts share the same product model, but they do not expose the exact same interaction shape.
 
 For high-impact actions, ExperienceEngine does not execute immediately. It uses a:
 
@@ -352,12 +365,13 @@ These are operator-facing controls, not the preferred public onboarding path.
 
 ## Embedding Retrieval
 
-ExperienceEngine now supports a multi-provider embedding stack for semantic retrieval.
+ExperienceEngine now supports a multi-provider embedding stack inside a staged hybrid retrieval pipeline.
 
 Retrieval is now hybrid by default:
 
-- semantic retrieval remains the main recall path
-- lexical retrieval and query normalization help preserve engineering intent when the prompt wording shifts
+- query normalization and rewrite happen first so retrieval keeps engineering intent when prompt wording shifts
+- lexical and semantic retrieval are fused into one candidate shortlist instead of treating semantic retrieval as the unquestioned main path
+- policy enrichment stays separate from retrieval scoring, so maturity and governance signals do not replace retrieval evidence
 - reranking can promote a better-matching candidate above older score advantages, especially when an external reranker is configured
 
 Default behavior (`embeddingProvider = "api"`):
@@ -369,6 +383,12 @@ Default behavior (`embeddingProvider = "api"`):
 - if the API provider fails, ExperienceEngine falls back to the managed local model
 - if the local model fails, ExperienceEngine falls back to legacy hash-based retrieval
 
+Prompt-time behavior:
+
+- first-turn or prompt-only retrieval may not have any tool names or failure signatures yet
+- ExperienceEngine treats those fields as opportunistic evidence, not required retrieval inputs
+- when prompt-only evidence is sparse, lexical, semantic, and policy stages still run with the task summary and context summary alone
+
 Offline behavior (`embeddingProvider = "local"`):
 
 - the default local model is `Xenova/multilingual-e5-small`
@@ -414,6 +434,8 @@ ee install openclaw
 What happens:
 - ExperienceEngine installs as an OpenClaw plugin/runtime integration (not `src/adapters/`)
 - OpenClaw runtime events are used for intervention and persistence
+- OpenClaw uses the shared background learning loop by default
+- async hybrid posttask review stays disabled by default unless the runtime is explicitly overridden
 - management remains mostly through CLI fallback today
 - install ends with a short cold-start note so users know capture is active before the first formal hint appears
 
@@ -511,6 +533,9 @@ Useful commands:
 ```bash
 ee doctor codex
 ee upgrade codex
+ee codex exec -C /path/to/repo -s read-only "Say ok and exit."
+printf "Say ok and exit." | ee codex exec -C /path/to/repo -s read-only -
+ee codex exec --ee-session-id ci-smoke-1 -C /path/to/repo -s read-only "Say ok and exit."
 ```
 
 First validation:
@@ -529,6 +554,12 @@ Host note:
 - ExperienceEngine installs a longer `startup_timeout_sec` for Codex automatically
 - this avoids MCP handshake failures on slower local startups
 - if Codex still cannot see ExperienceEngine in new sessions, re-run `ee install codex`
+- `ee codex exec` is a deterministic wrapper for non-interactive runs
+- the wrapper owns `lookup -> child codex exec -> record -> finalize` outside the child process
+- for wrapped runs, ExperienceEngine removes the nested `experienceengine` MCP server from the child Codex config temporarily so lifecycle evidence is not double-written
+- use prompt `-` when you want the wrapper to read task instructions from stdin; child Codex still receives a wrapped prompt argument and does not inherit stdin
+- use `--ee-session-id <id>` when CI or debugging needs a stable ExperienceEngine session id
+- `codex exec review` is not wrapped yet; keep using native Codex review or the MCP/CLI surfaces for review workflows
 
 Developer validation docs:
 

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "experienceengine",
   "name": "ExperienceEngine",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Context-aware experience intervention controller for coding and debugging tasks.",
   "configSchema": {
     "type": "object",
@@ -28,6 +28,15 @@
         "type": "string",
         "description": "Directory used to store raw runtime payload captures."
       },
+      "distillerProvider": {
+        "type": "string",
+        "enum": ["openai", "anthropic", "gemini", "openrouter", "deepseek", "bedrock", "vertex_gemini", "groq", "openai_compatible"],
+        "description": "Distillation provider reused by phase 2 provider-backed explain."
+      },
+      "distillerModel": {
+        "type": "string",
+        "description": "Distillation model identifier reused by phase 2 provider-backed explain."
+      },
       "maxHints": {
         "type": "integer",
         "minimum": 1,
@@ -39,6 +48,44 @@
         "minimum": 0,
         "maximum": 1,
         "description": "Trigger threshold for intervention gating."
+      },
+      "hybridEnabled": {
+        "type": "boolean",
+        "description": "Enable the hybrid routing layer."
+      },
+      "hybridSyncExplainEnabled": {
+        "type": "boolean",
+        "description": "Allow bounded sync escalation for explicit explanation requests."
+      },
+      "hybridAsyncPostmortemEnabled": {
+        "type": "boolean",
+        "description": "Allow bounded async postmortem review for eligible completed runs."
+      },
+      "hybridAsyncPostmortemLlmEnabled": {
+        "type": "boolean",
+        "description": "Enable provider-backed postmortem_review in phase 3."
+      },
+      "hybridExplainLlmEnabled": {
+        "type": "boolean",
+        "description": "Enable provider-backed explain_decision in phase 2."
+      },
+      "hybridExplainProviderMode": {
+        "type": "string",
+        "enum": ["shared_distiller"],
+        "description": "Provider resolution mode for phase 2 explain_decision."
+      },
+      "hybridExplainModelProfileVersion": {
+        "type": "string",
+        "description": "Version label for the provider-backed explain_decision model profile."
+      },
+      "hybridPostmortemProviderMode": {
+        "type": "string",
+        "enum": ["shared_distiller"],
+        "description": "Provider resolution mode for phase 3 postmortem_review."
+      },
+      "hybridPostmortemModelProfileVersion": {
+        "type": "string",
+        "description": "Version label for the provider-backed postmortem_review model profile."
       }
     }
   },
@@ -61,11 +108,44 @@
       "label": "Capture Directory",
       "placeholder": "./data/runtime-captures"
     },
+    "distillerProvider": {
+      "label": "Distiller Provider"
+    },
+    "distillerModel": {
+      "label": "Distiller Model"
+    },
     "maxHints": {
       "label": "Max Hints"
     },
     "triggerThreshold": {
       "label": "Trigger Threshold"
+    },
+    "hybridEnabled": {
+      "label": "Hybrid Enabled"
+    },
+    "hybridSyncExplainEnabled": {
+      "label": "Hybrid Sync Explain Enabled"
+    },
+    "hybridAsyncPostmortemEnabled": {
+      "label": "Hybrid Async Postmortem Enabled"
+    },
+    "hybridAsyncPostmortemLlmEnabled": {
+      "label": "Hybrid Async Postmortem LLM Enabled"
+    },
+    "hybridExplainLlmEnabled": {
+      "label": "Hybrid Explain LLM Enabled"
+    },
+    "hybridExplainProviderMode": {
+      "label": "Hybrid Explain Provider Mode"
+    },
+    "hybridExplainModelProfileVersion": {
+      "label": "Hybrid Explain Model Profile Version"
+    },
+    "hybridPostmortemProviderMode": {
+      "label": "Hybrid Postmortem Provider Mode"
+    },
+    "hybridPostmortemModelProfileVersion": {
+      "label": "Hybrid Postmortem Model Profile Version"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alan512/experienceengine",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "type": "module",
   "description": "Experience governance for coding agents: learn from real task outcomes, inject reusable hints, and retire low-value guidance.",
   "license": "MIT",
@@ -11,7 +11,15 @@
   "openclaw": {
     "extensions": [
       "./dist/plugin/openclaw-plugin.js"
-    ]
+    ],
+    "compat": {
+      "pluginApi": ">=2026.4.1",
+      "minGatewayVersion": "2026.4.1"
+    },
+    "build": {
+      "openclawVersion": "2026.4.1",
+      "pluginSdkVersion": "2026.4.1"
+    }
   },
   "engines": {
     "node": ">=20.0.0"
@@ -37,6 +45,7 @@
     "dev": "tsx watch src/cli/index.ts",
     "evaluate:openclaw-baseline": "tsx src/cli/index.ts evaluate openclaw-baseline",
     "evaluate:openclaw-scenarios": "tsx src/cli/index.ts evaluate openclaw-scenarios --pack high-confidence",
+    "evaluate:codex-lifecycle": "tsx src/cli/index.ts evaluate codex-lifecycle",
     "maintenance:merge-warning-variants": "tsx scripts/maintenance/merge-warning-variants.ts",
     "runtime:promote-payload": "tsx scripts/openclaw/promote-runtime-payload.ts",
     "runtime:replay-fixture": "tsx scripts/openclaw/replay-runtime-fixture.ts",

package/plugins/claude-code-experienceengine/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "experienceengine",
   "description": "Context-aware experience intervention controller for Claude Code.",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "author": {
     "name": "ExperienceEngine"
   },

package/plugins/claude-code-experienceengine/scripts/install-deps.sh

@@ -11,7 +11,7 @@ PACKAGE_ENTRY="${PACKAGE_DIR}/dist/cli/index.js"
 STAMP_PATH="${PLUGIN_DATA}/.experienceengine-plugin-version"
 EXPERIENCE_ENGINE_HOME_PATH="${EXPERIENCE_ENGINE_HOME:-${PLUGIN_DATA}/experienceengine-home}"
 STATE_PATH="${EXPERIENCE_ENGINE_HOME_PATH}/claude-marketplace-state.json"
-PACKAGE_VERSION="0.1.3"
+PACKAGE_VERSION="0.2.1"
 PACKAGE_SPEC="${EXPERIENCE_ENGINE_PLUGIN_PACKAGE_SPEC:-@alan512/experienceengine@${PACKAGE_VERSION}}"
 
 mkdir -p "${PLUGIN_DATA}"