@alan512/experienceengine 0.2.0 → 0.3.0

package/dist/types/domain.d.ts

@@ -11,13 +11,32 @@ export type ValidationState = "pending_reuse_validation" | "validated_by_reuse"
 export type CorrectionScope = "task_local" | "repo_local" | "workflow_local" | "host_local" | "cross_repo_candidate";
 export type CorrectionCategory = "goal_interpretation" | "quality_bar" | "interaction_behavior" | "verification_order" | "implementation_boundary" | "style_constraint";
 export type InjectionMode = "skip" | "inject_conservative" | "inject";
+export type InterventionStrength = "diagnostic_hint" | "soft_recommendation" | "strong_recommendation" | "hard_constraint";
 export type InjectionRiskLevel = "low" | "medium" | "high";
+export type MatchBand = "high" | "medium" | "low";
+export type ScopeMatchBand = "same" | "related" | "cross" | "none";
+export type MatchScorecard = {
+    scopeMatch: ScopeMatchBand;
+    taskTypeMatch: MatchBand;
+    techStackMatch: MatchBand;
+    failureSignatureMatch: MatchBand;
+    artifactMatch: MatchBand;
+    intentMatch: MatchBand;
+    negativeEvidence: string[];
+    overallMatchBand: MatchBand;
+    directInjectEligible: boolean;
+};
 export type InterventionConfidence = "low" | "medium" | "high";
 export type InterventionBudgetClass = "none" | "single_hint" | "multi_hint";
 export type SyncSecondOpinionDecision = "allow" | "allow_conservative" | "skip";
 export type SyncSecondOpinionTrigger = "conservative_delivery_state" | "harm_history" | "close_score_margin" | "expectation_correction";
 export type EvaluationMode = "live" | "shadow" | "holdout";
 export type OutcomeSignal = "success" | "failure" | "unknown";
+export type AttributionVerdict = "strong_helped" | "weak_helped" | "neutral" | "unknown" | "weak_harmed" | "strong_harmed";
+export type AttributionConfidence = "low" | "medium" | "high";
+export type AttributionSource = "automatic" | "manual_override" | "diagnostic_record";
+export type RepoExperienceMode = "safe" | "fast_learning" | "strict";
+export type RepoCircuitState = "clear" | "tripped";
 export type ToolEventStatus = "success" | "failure" | "unknown";
 export type CandidateLifecycleState = "pending" | "distilled" | "failed" | "discarded";
 export type DistillationJobState = "pending" | "processing" | "succeeded" | "failed" | "discarded";
@@ -69,8 +88,27 @@ export type RetrievalContext = {
     modulePaths?: string[];
     expectationCorrectionIntent?: boolean;
 };
+export type RetrievalPolicyStageName = "retrieval_context" | "hard_filter" | "shortlist" | "semantic_rerank_backfill" | "policy_enrichment" | "decision_assembly";
+export type RetrievalPolicyStageDiagnostic = {
+    stage: RetrievalPolicyStageName;
+    acceptedCount?: number;
+    rejectedCount?: number;
+    passedCount?: number;
+    reasonCodes: string[];
+};
+export type RetrievalPolicyDiagnostics = {
+    stages: RetrievalPolicyStageDiagnostic[];
+};
+export type PolicyEnrichmentComponentCategory = "family_fit" | "specificity" | "feedback" | "maturity" | "penalty" | "expectation_correction" | "task_alignment" | "retrieval_context";
+export type PolicyEnrichmentComponent = {
+    name: string;
+    category: PolicyEnrichmentComponentCategory;
+    value: number;
+    reason: string;
+};
 export type ExperienceInputRecord = {
     record_id: string;
+    episode_id?: string;
     scope_id: string;
     session_id?: string;
     task_type: ResolvedTaskType;
@@ -83,6 +121,7 @@ export type ExperienceInputRecord = {
 };
 export type TaskRun = {
     id: string;
+    episode_id?: string;
     host: "openclaw" | "claude-code" | "codex";
     scope_id: string;
     session_id?: string;
@@ -101,6 +140,7 @@ export type TaskRun = {
 };
 export type OutcomeRecord = {
     id: string;
+    episode_id?: string;
     task_run_id: string;
     outcome_signal: OutcomeSignal;
     failure_signature?: string;
@@ -109,9 +149,10 @@ export type OutcomeRecord = {
 };
 export type ReviewEvent = {
     id: string;
+    episode_id?: string;
     node_id: string;
     task_run_id?: string;
-    event_type: "mark_helped" | "mark_harmed" | "mark_uncertain" | "cool" | "retire" | "quarantine" | "restore_conservative" | "restore_eligible";
+    event_type: "mark_helped" | "mark_harmed" | "mark_uncertain" | "cool" | "retire" | "quarantine" | "restore_conservative" | "restore_eligible" | "promote_eligible";
     source: "automatic" | "user";
     created_at: string;
 };
@@ -208,11 +249,12 @@ export type ExperienceNode = {
 };
 export type InjectionEvent = {
     injection_id: string;
+    episode_id?: string;
     session_id?: string;
     scope_id: string;
     task_type: TaskType;
     task_summary?: string;
-    mode: Exclude<InjectionMode, "skip">;
+    mode: InjectionMode;
     delivery_mode: EvaluationMode;
     delivered: boolean;
     injected_node_ids: string[];
@@ -224,6 +266,58 @@ export type InjectionEvent = {
     created_at: string;
     resolved_at?: string;
 };
+export type AttributionRecord = {
+    id: string;
+    injection_id?: string;
+    node_id: string;
+    episode_id?: string;
+    intervention_strength?: InterventionStrength;
+    injection_mode?: InjectionMode;
+    delivery_mode?: EvaluationMode;
+    delivered: boolean;
+    outcome: OutcomeSignal;
+    attribution_verdict: AttributionVerdict;
+    confidence: AttributionConfidence;
+    evidence_refs: string[];
+    user_override?: "helped" | "harmed" | "neutral";
+    source: AttributionSource;
+    attribution_reason?: FeedbackAttributionReason | "manual_override" | "diagnostic_record";
+    created_at: string;
+    resolved_at?: string;
+};
+export type RepoPolicy = {
+    scope_id: string;
+    configured_mode: RepoExperienceMode;
+    effective_mode: RepoExperienceMode;
+    circuit_state: RepoCircuitState;
+    circuit_reason?: string;
+    live_diagnostics_disabled: boolean;
+    created_at: string;
+    updated_at: string;
+    last_tripped_at?: string;
+    restored_at?: string;
+};
+export type EpisodeProjection = {
+    episode_id: string;
+    scope_id?: string;
+    session_id?: string;
+    task_run?: TaskRun;
+    input_records: ExperienceInputRecord[];
+    outcome_records: OutcomeRecord[];
+    injection_events: InjectionEvent[];
+    attribution_records: AttributionRecord[];
+    review_events: ReviewEvent[];
+};
+export type EpisodeSummary = {
+    episode_id: string;
+    scope_id: string;
+    session_id?: string;
+    task_type?: ResolvedTaskType;
+    task_summary?: string;
+    outcome?: OutcomeSignal;
+    created_at: string;
+    updated_at: string;
+};
 export type InjectionScorecardNode = {
     id: string;
     nodeType: ExperienceNodeType;
@@ -240,6 +334,7 @@ export type InjectionScorecardNode = {
 };
 export type InjectionScorecardCandidate = {
     id: string;
+    matchScorecard?: MatchScorecard;
     semanticScore?: number;
     lexicalScore?: number;
     fusedScore?: number;
@@ -251,6 +346,7 @@ export type InjectionScorecardCandidate = {
     rerankSource?: "heuristic" | "model";
     retrievalReasons?: string[];
     policyReasons?: string[];
+    policyComponents?: PolicyEnrichmentComponent[];
     taskFamilyMatch: boolean;
 };
 export type InterventionRejectedCandidate = {
@@ -261,6 +357,9 @@ export type InterventionRejectedCandidate = {
     totalScore?: number;
 };
 export type InterventionDecisionDiagnostics = {
+    interventionStrength?: InterventionStrength;
+    recordOnlyDiagnosticCandidateIds?: string[];
+    retrievalPolicyDiagnostics?: RetrievalPolicyDiagnostics;
     topCandidates: InjectionScorecardCandidate[];
     topCandidateScore?: number;
     scoreMargin?: number;
@@ -286,7 +385,8 @@ export type InjectionScorecard = {
     scopeId: string;
     taskType: TaskType;
     taskSummary: string;
-    mode: Exclude<InjectionMode, "skip">;
+    mode: InjectionMode;
+    interventionStrength?: InterventionStrength;
     riskLevel: InjectionRiskLevel;
     recommendation: string;
     reasons: string[];
@@ -308,6 +408,8 @@ export type InjectionScorecard = {
     secondOpinionReason?: string;
     secondOpinionTrigger?: SyncSecondOpinionTrigger;
     selectedCandidateIds?: string[];
+    recordOnlyDiagnosticCandidateIds?: string[];
+    retrievalPolicyDiagnostics?: RetrievalPolicyDiagnostics;
     rejectedCandidates?: InterventionRejectedCandidate[];
     nodes: InjectionScorecardNode[];
     createdAt: string;

package/dist/utils/text.js

@@ -13,7 +13,11 @@ export const tokenize = (value) => normalizeWhitespace(value)
     .filter(Boolean);
 const EXPERIENCE_INJECTION_HEADINGS = [
     "Execution hints from prior similar tasks:",
-    "Conservative execution hints:"
+    "Conservative execution hints:",
+    "Diagnostic lead from prior experience:",
+    "Relevant prior experience:",
+    "Validated prior experience:",
+    "Project constraint or explicit instruction:"
 ];
 export const stripLeadingExperienceInjection = (value) => {
     let next = value.trimStart();

package/dist/utils/text.js.map

@@ -1 +1 @@
-{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/utils/text.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/utils/text.ts"],"names":[],"mappings":"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"}

package/docs/assets/readme/inspect-last-example.svg

@@ -0,0 +1,37 @@
+<svg width="1200" height="920" viewBox="0 0 1200 920" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="1200" height="920" rx="20" fill="#0B1020"/>
+  <rect x="24" y="24" width="1152" height="64" rx="14" fill="#131A2E"/>
+  <circle cx="60" cy="56" r="9" fill="#FF5F57"/>
+  <circle cx="88" cy="56" r="9" fill="#FEBB2E"/>
+  <circle cx="116" cy="56" r="9" fill="#28C840"/>
+  <text x="600" y="62" text-anchor="middle" fill="#DDE7FF" font-family="DejaVu Sans Mono, monospace" font-size="24">ee inspect --last --verbose</text>
+
+  <rect x="24" y="104" width="1152" height="792" rx="14" fill="#0F172A"/>
+
+  <g font-family="DejaVu Sans Mono, monospace" font-size="24">
+    <text x="48" y="152" fill="#93C5FD">$ ee inspect --last --verbose</text>
+
+    <text x="48" y="198" fill="#E5E7EB">Session: session_last</text>
+    <text x="48" y="232" fill="#E5E7EB">Scope: scope_current_repo</text>
+    <text x="48" y="266" fill="#E5E7EB">Task type: test_debug</text>
+    <text x="48" y="300" fill="#E5E7EB">Intervention: inject</text>
+    <text x="48" y="334" fill="#E5E7EB">Delivery style: normal hint delivery</text>
+    <text x="48" y="368" fill="#E5E7EB">Automatic feedback: helped</text>
+
+    <text x="48" y="426" fill="#A7F3D0">Injected nodes:</text>
+    <text x="72" y="460" fill="#E5E7EB">- node_inspect strategy active system_derived</text>
+    <text x="96" y="494" fill="#E5E7EB">Trigger: Fix the failing auth test</text>
+    <text x="96" y="528" fill="#E5E7EB">Quality: strong</text>
+    <text x="96" y="562" fill="#E5E7EB">Best fit: test_debug tasks in this repo scope</text>
+
+    <text x="48" y="620" fill="#FDE68A">Scorecard:</text>
+    <text x="72" y="654" fill="#E5E7EB">- Risk: low</text>
+    <text x="72" y="688" fill="#E5E7EB">- Recommendation: Apply these hints, then mark helped or harmed.</text>
+    <text x="72" y="722" fill="#E5E7EB">- Why ExperienceEngine acted: best reusable guidance for this task.</text>
+    <text x="72" y="756" fill="#E5E7EB">- Trust summary: low-risk active guidance with helped signals.</text>
+
+    <text x="48" y="814" fill="#67E8F9">Hints:</text>
+    <text x="72" y="848" fill="#E5E7EB">- Run the failing auth test before editing and verify after the fix.</text>
+    <text x="48" y="882" fill="#C4B5FD">Outcome: success</text>
+  </g>
+</svg>

package/docs/releases/v0.2.1.md

@@ -0,0 +1,30 @@
+# ExperienceEngine v0.2.1
+
+Release date: 2026-05-02
+
+## Summary
+
+This development slice tightens Codex-era live-delivery quality after reviewing recent local ExperienceEngine usage.
+
+## Included
+
+- skipped delivery decisions are now persisted, so the latest turn can be explained even when no hint was injected
+- retrieval candidates now carry deterministic match scorecards before live delivery
+- high-trust, high-match same-scope experience can inject directly
+- high-match same-scope conservative experience can promote to normal eligible delivery after successful reuse
+- cross-scope reuse is available only through conservative candidates, not direct injection
+- `ee status` and `ee doctor codex` now report whether the `ee` CLI fallback is available on `PATH`
+- Codex managed setup now targets Codex-native hooks plus MCP: `codex_hooks` is enabled, ExperienceEngine-owned Codex hook entries are installed, and stale `experienceengine-claude-hook` drift can be repaired safely.
+- Codex project hooks now support the practical Windows Codex App + WSL Codex CLI split: repo hooks are shared through `.codex/hooks.json`, while MCP registration stays owned by each runtime's Codex home.
+- Codex hook runtime is leaner on the prompt path: prompt-time lookup uses a light runtime, full runtime/provider loading is deferred, and `PostToolUse` / `Stop` are queued for background processing.
+- Codex hook launchers use a fast path for hook execution so missing local embedding fallback dependencies do not block normal host interaction.
+- Source-repo host validation now covers Windows Codex App, WSL Codex CLI, Claude Code, and WSL OpenClaw writing to the same project scope.
+- OpenClaw prompt payloads now resolve the real project root from explicit host fields or nearby repo markers before scope selection; unresolved global OpenClaw workspace payloads are session-isolated instead of being reused as a broad project scope.
+
+## Notes
+
+- LLM usage remains in the existing places: posttask distillation and selective second-opinion review.
+- The new routing layer is deterministic and is intended to reduce both over-conservative same-scope skips and harmful broad reuse.
+- `UserPromptSubmit` remains intentionally synchronous because it owns live injection. The async queue applies to follow-up capture and finalize hooks.
+- Host validation statements in this release note refer to source-repo validation, not published npm package or host marketplace validation.
+- OpenClaw validation used the OpenClaw-compatible `openrouter/tencent/hy3-preview:free` model id. The bare `tencent/hy3-preview:free` id matched the Claude Code spelling but is marked missing by OpenClaw's model registry.

package/docs/releases/v0.3.0.md

@@ -0,0 +1,17 @@
+# ExperienceEngine v0.3.0
+
+v0.3.0 focuses on making the same project-level EE experience state usable across the current host set without leaking host-specific installation details into the published package.
+
+## Highlights
+
+- Added cross-runtime Codex hook launchers so a shared project can work from both Windows Codex App and WSL Codex CLI while writing to the same configured EE home.
+- Added cross-runtime Claude Code hook launchers and plugin MCP startup flow so marketplace installs no longer depend on local source-repo paths.
+- Improved Claude Code validation by checking both the Claude print transcript and the underlying EE MCP server tool list.
+- Improved OpenClaw repair diagnostics so a loaded, matching host-native plugin is not reported as needing restart.
+- Kept Codex `PreToolUse` disabled by default; Codex live injection remains on `UserPromptSubmit`, with `PostToolUse` and `Stop` used for learning and finalization.
+
+## Upgrade Notes
+
+- New npm users should install with `npm install -g @alan512/experienceengine@0.3.0`, then run `ee install <host>` or `ee upgrade <host>` for the hosts they use.
+- Existing users should run `ee upgrade codex`, `ee upgrade claude-code`, or `ee upgrade openclaw` after updating the npm package so host wiring is regenerated with the current launchers.
+- Mixed Windows App and WSL CLI Codex use should keep `EXPERIENCE_ENGINE_HOME` pointed at the same shared EE data directory if the user wants both hosts to share one project experience store.

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
@@ -105,7 +107,8 @@ Install ExperienceEngine through the host setup flow for:
     - `ee install codex`
   - native/manual fallback:
     - `codex mcp add experienceengine --env EXPERIENCE_ENGINE_HOME=$HOME/.experienceengine -- npx -y @alan512/experienceengine codex-mcp-server`
-  - after either path, start a new Codex session in this repo so the MCP wiring and `AGENTS.md` instruction block are picked up
+  - after the managed path, start a new Codex session in this repo so Codex-native hooks, MCP wiring, and the `AGENTS.md` instruction block are picked up
+  - the manual MCP fallback only installs the tool surface; use `ee install codex` or `ee repair codex` when hook lifecycle capture/injection is needed
 - `Claude Code`
   - host-native marketplace install:
     - add the bundled marketplace from GitHub:
@@ -155,6 +158,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`
@@ -249,6 +254,53 @@ When you inspect a specific node, ExperienceEngine now also shows a lightweight
 - the short drivers behind that judgment
 - a compact applicability profile covering best fit, scope validity, confidence, risk, and when to avoid reuse
 
+### Operator Review Workflow
+
+Use the operator review workflow when you want one read-only checkpoint across the current repo before deciding what to inspect next.
+
+The fallback CLI entry point is:
+
+```bash
+ee inspect review
+```
+
+For a specific workspace and a smaller checklist:
+
+```bash
+ee inspect review --cwd /path/to/repo --limit 3
+```
+
+The review report summarizes:
+
+- repo policy health and circuit state
+- hygiene finding counts
+- export draft counts
+- recommended review order
+- prioritized review items
+- review-only next actions
+- drill-down commands for detailed read-only reports
+
+The drill-down commands are manual inspection steps:
+
+```bash
+ee inspect repo
+ee inspect hygiene
+ee inspect export-drafts
+```
+
+In MCP-capable hosts, ask the host agent to inspect the ExperienceEngine operator review or read `experienceengine://review`. The structured payload uses the same source names as the CLI: `repo_policy`, `hygiene`, and `export_drafts`.
+
+This workflow is intentionally read-only. It does not:
+
+- restore repo policy
+- cool or retire nodes
+- write attribution or review events
+- create backups or snapshots
+- write instruction files, skills, or docs
+- export guidance automatically
+- open a console or mutation dashboard
+- coordinate team workflows
+
 ## How MCP Interaction Works
 
 For `Codex` and `Claude Code`, ExperienceEngine is designed to keep routine review and management inside the host session first.
@@ -518,10 +570,12 @@ ee install codex
 What happens:
 - ExperienceEngine registers its shared MCP server with Codex
 - new Codex MCP sessions can use ExperienceEngine interaction surfaces
+- ExperienceEngine writes Codex-native project hooks and enables `codex_hooks`
 - install ends with a short cold-start note so users know capture is active before the first formal hint appears
 
 Local state changes:
-- Codex MCP config in `~/.codex/config.toml`
+- project hook config in `.codex/hooks.json`
+- Codex MCP config in the active runtime's `~/.codex/config.toml`
 - ExperienceEngine-managed product state under `~/.experienceengine`
 
 Useful commands:
@@ -544,12 +598,19 @@ codex mcp get experienceengine
 Success looks like:
 - doctor reports the adapter as installed
 - `codex mcp get experienceengine` shows the server as enabled
+- doctor reports Codex hooks as healthy and `codex_hooks` as enabled
 - a new `codex exec` session can call ExperienceEngine MCP resources or tools
 
 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`
+- ExperienceEngine installs Codex-native hooks for prompt-time guidance, tool-result capture, and stop/finalize writeback
+- `UserPromptSubmit` is synchronous because it decides prompt-time injection
+- `PostToolUse` and `Stop` are queued for background processing by default
+- `PreToolUse` is not registered by default; set `EXPERIENCE_ENGINE_CODEX_PRETOOL_HOOK_ENABLED=1` only for synchronous gating experiments
+- in a Windows Codex App + WSL Codex CLI repo, `.codex/hooks.json` is shared project hook wiring, while MCP config is owned by each runtime's Codex home
+- `ee repair codex` refreshes project hooks and removes stale project-scoped ExperienceEngine MCP config
+- if Codex still cannot see ExperienceEngine or doctor reports hook drift, run `ee repair 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
@@ -557,6 +618,27 @@ Host note:
 - 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
 
+Diagnostics note:
+- `ee doctor codex` separates project hook health, `codex_hooks` enablement, MCP registration, and PATH-visible `ee` CLI fallback
+- Windows Codex App can have healthy project hooks even when a Windows `codex` CLI is not installed
+- WSL Codex CLI must have its own MCP registration in the WSL Codex home; it can still reuse the same repo `.codex/hooks.json`
+- on WSL, `ee doctor codex` also warns when `codex` resolves to a WindowsApps shim instead of the Linux Codex CLI
+
+Developer source-repo host validation lives at:
+
+- [docs/development/source-repo-host-validation.md](development/source-repo-host-validation.md)
+
+Source-repo host validation matrix:
+
+| Host path | Source-repo validation status | Notes |
+| --- | --- | --- |
+| Windows Codex App | Validated | Project hooks are healthy, default events are `UserPromptSubmit`, `PostToolUse`, and `Stop`, and task runs write to the shared project scope. |
+| WSL Codex CLI | Validated | WSL `codex exec` with shared `.codex/hooks.json` writes to the same ExperienceEngine home and `scope_id` as Windows Codex App. |
+| Claude Code on Windows | Validated | Real hooks fired `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `SessionEnd`; `SessionEnd` drained through the background queue and wrote to the shared project scope. |
+| OpenClaw on WSL | Validated | WSL OpenClaw gateway loaded the current ExperienceEngine plugin and wrote task runs to the shared ExperienceEngine home. ExperienceEngine now resolves the real project root from OpenClaw hook payloads or nearby repo markers before scope resolution. If OpenClaw only reports its global workspace, ExperienceEngine isolates that session instead of reusing unrelated global-workspace experience. OpenClaw validated with `openrouter/tencent/hy3-preview:free`; the bare `tencent/hy3-preview:free` id is marked missing by OpenClaw's model registry. |
+
+This matrix is source-repo validation only. Published npm package validation and host-native marketplace validation must be called out separately during release preparation.
+
 Developer validation docs:
 
 - [docs/development/codex-runtime-validation.md](development/codex-runtime-validation.md)
@@ -587,6 +669,10 @@ Useful fallback commands:
 ```bash
 ee inspect --last
 ee inspect recent injected 10
+ee inspect review
+ee inspect repo
+ee inspect hygiene
+ee inspect export-drafts
 ee inspect backups
 ee inspect active
 ee inspect node <id>
@@ -860,7 +946,7 @@ Claude Code:
 Codex:
 - run `ee doctor codex`
 - verify `codex mcp get experienceengine`
-- if a new Codex session still cannot see ExperienceEngine, run `ee install codex`
+- if doctor reports disabled hooks, stale Claude hook entries, WSL path drift, or missing MCP wiring, run `ee repair codex`
 - then start a new Codex session so the MCP connection is recreated
 
 ### What ExperienceEngine does not back up

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "experienceengine",
   "name": "ExperienceEngine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Context-aware experience intervention controller for coding and debugging tasks.",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@alan512/experienceengine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Experience governance for coding agents: learn from real task outcomes, inject reusable hints, and retire low-value guidance.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Alan-512/ExperienceEngine.git"
+    "url": "git+https://github.com/Alan-512/ExperienceEngine.git"
   },
   "openclaw": {
     "extensions": [
@@ -34,23 +34,13 @@
     "hooks",
     "plugins/claude-code-experienceengine",
     "README.md",
+    "docs/assets/readme",
     "docs/user-guide.md",
     "docs/releases",
     "openclaw.plugin.json",
     "scripts/claude-plugin",
     ".env.example"
   ],
-  "dependencies": {
-    "@huggingface/transformers": "^3.8.1",
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "@types/node": "^22.13.14",
-    "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
-    "vitest": "^3.0.9"
-  },
   "scripts": {
     "build": "node scripts/build/clean-dist.mjs && tsc -p tsconfig.build.json && node scripts/build/copy-sqlite-schema.mjs",
     "dev": "tsx watch src/cli/index.ts",
@@ -60,8 +50,20 @@
     "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",
+    "prepack": "pnpm build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "check": "pnpm typecheck && pnpm test && pnpm build"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.14",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
   }
-}
+}

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.2.0",
+  "version": "0.3.0",
   "author": {
     "name": "ExperienceEngine"
   },

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

@@ -2,16 +2,10 @@
   "mcpServers": {
     "experienceengine": {
       "type": "stdio",
-      "command": "node",
+      "command": "bash",
       "args": [
-        "${CLAUDE_PLUGIN_ROOT}/node_modules/@alan512/experienceengine/dist/cli/index.js",
-        "mcp-server"
-      ],
-      "env": {
-        "NODE_PATH": "${CLAUDE_PLUGIN_ROOT}/node_modules",
-        "EXPERIENCE_ENGINE_HOME": "${CLAUDE_PLUGIN_ROOT}/experienceengine-home",
-        "EXPERIENCE_ENGINE_CLAUDE_HOOK_SOURCE": "marketplace"
-      }
+        "${CLAUDE_PLUGIN_ROOT}/scripts/mcp-server.sh"
+      ]
     }
   }
 }

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.2.0"
+PACKAGE_VERSION="0.3.0"
 PACKAGE_SPEC="${EXPERIENCE_ENGINE_PLUGIN_PACKAGE_SPEC:-@alan512/experienceengine@${PACKAGE_VERSION}}"
 
 mkdir -p "${PLUGIN_DATA}"

package/plugins/claude-code-experienceengine/scripts/mcp-server.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PLUGIN_DATA="${CLAUDE_PLUGIN_DATA:-${CLAUDE_PLUGIN_ROOT:-}}"
+if [[ -z "${PLUGIN_DATA}" ]]; then
+  echo "CLAUDE_PLUGIN_DATA or CLAUDE_PLUGIN_ROOT is required" >&2
+  exit 1
+fi
+
+INSTALL_SCRIPT="${PLUGIN_DATA}/scripts/install-deps.sh"
+if [[ -x "${INSTALL_SCRIPT}" ]]; then
+  "${INSTALL_SCRIPT}" >&2
+fi
+
+export NODE_PATH="${PLUGIN_DATA}/node_modules${NODE_PATH:+:${NODE_PATH}}"
+export EXPERIENCE_ENGINE_HOME="${EXPERIENCE_ENGINE_HOME:-${PLUGIN_DATA}/experienceengine-home}"
+STATE_PATH="${EXPERIENCE_ENGINE_HOME}/claude-marketplace-state.json"
+
+node - "${STATE_PATH}" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+
+const [statePath] = process.argv.slice(2);
+let current = {};
+try {
+  current = JSON.parse(fs.readFileSync(statePath, "utf8"));
+} catch {}
+
+const next = {
+  adapter: "claude-code",
+  install_mode: "marketplace",
+  hook_source: "marketplace",
+  package_version: current.package_version,
+  written_at: current.written_at ?? new Date().toISOString(),
+  last_hook_seen_at: current.last_hook_seen_at,
+  last_mcp_seen_at: new Date().toISOString()
+};
+
+fs.mkdirSync(path.dirname(statePath), { recursive: true });
+fs.writeFileSync(statePath, `${JSON.stringify(next, null, 2)}\n`);
+NODE
+
+exec node --no-warnings "${PLUGIN_DATA}/node_modules/@alan512/experienceengine/dist/cli/index.js" mcp-server "$@"