@alan512/experienceengine 0.3.5 → 0.4.0

package/docs/user-guide.md

@@ -299,6 +299,7 @@ The review report summarizes:
 - repo policy health and circuit state
 - hygiene finding counts
 - export draft counts
+- autonomous governance status, recent automatic actions, guarded actions, failures, and legacy pending approvals
 - recommended review order
 - prioritized review items
 - review-only next actions
@@ -310,9 +311,10 @@ The drill-down commands are manual inspection steps:
 ee inspect repo
 ee inspect hygiene
 ee inspect export-drafts
+ee inspect governance
 ```
 
-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`.
+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`, `export_drafts`, and `governance`.
 
 This workflow is intentionally read-only. It does not:
 
@@ -325,6 +327,79 @@ This workflow is intentionally read-only. It does not:
 - open a console or mutation dashboard
 - coordinate team workflows
 
+## Autonomous Hygiene Governance
+
+ExperienceEngine runs hygiene governance automatically through the host-attached runtime. Host startup, prompt lookup, posttask finalization, and stop events wake a cheap due check for the current canonical scope. The persisted schedule, lease, backoff, finding hash, and action budget decide whether real governance work runs, so frequent host restarts do not multiply governance frequency.
+
+The automatic path applies validated experience-store mutations without routine user approval:
+
+- exact duplicate merges that preserve evidence
+- near-duplicate and conflicted semantic merges with evidence preserved
+- stale shadow-only retirement
+- delivery downgrades from live eligibility to conservative delivery
+- quarantine for invalidated or harmed live guidance
+- guarded promotion to conservative delivery
+- guarded soft-retire for records that should leave delivery
+
+High-impact experience-node actions use guarded automatic execution instead of approval. Guarded execution keeps the mutation reversible and conservative: rows are not physically deleted, before/after snapshots and affected row hashes are recorded, merged or promoted canonical guidance cannot become directly eligible for live injection, and retired/conflicting source nodes are quarantined. Broad rewrites, export writing, repo policy changes, and restore actions are outside automatic experience-store governance and are rejected unless a separate explicit workflow owns them.
+
+Read-only inspection surfaces:
+
+```bash
+ee inspect governance
+ee inspect review
+```
+
+MCP resources:
+
+```text
+experienceengine://governance
+experienceengine://governance/approvals
+experienceengine://review
+```
+
+Fallback drain command:
+
+```bash
+ee maintenance governance drain --cwd /path/to/repo
+```
+
+That command is for explicit operator troubleshooting or catch-up. It uses the same scheduler, lease, validator, audit, and rollback snapshot path as host-attached governance. An optional keeper can wake the same drain path for stricter wall-clock schedules, but it does not bypass budgets, leases, deterministic validators, guarded execution rules, or rollback safeguards.
+
+## Governed Portable Experience
+
+ExperienceEngine connects retrieval, attribution, and lifecycle layers to support governed, cautious sharing of experience nodes across different repositories and scopes.
+
+### Portability Bands & SemVer Compatibility
+
+When retrieving experience candidates for a task, ExperienceEngine calculates a cross-repository compatibility scorecard. This scorecard determines how safe the guidance is in the current environment using the following **Portability Bands**:
+- `validated_portable`: Highly compatible. The node matches the local programming language, and any shared dependencies have verified SemVer compatibility.
+- `cautiously_portable`: Medium compatibility. Reused with caution, usually limited to conservative delivery state until local execution success is demonstrated.
+- `incompatible`: The node requires frameworks or languages not present in the current project. Delivery is blocked.
+
+Compatibility scoring factors in **SemVer matching penalties**:
+- Framework or dependency version mismatches subtract penalty points (e.g. minor or major version drift).
+- Language mismatches (e.g., trying to use Python guidance in a TypeScript codebase) flag the node as incompatible.
+
+### Causal Trajectory Attribution
+
+During post-task finalization, ExperienceEngine verifies if the host agent actually adopted the expectations of an injected hint. This **Causal Trajectory Attribution** produces a precise verdict:
+- `adoption_detected`: The agent successfully matched the expectations of the injected hint (e.g., specific file modifications or CLI tool executions).
+- `non_adoption_detected`: The agent completed the task but did not follow the suggested guidance.
+- `unverifiable`: The task ended in failure, or outcomes could not be traced clearly.
+
+These trajectory verdicts prevent false positives in outcome attribution, ensuring that helpfulness or harm is only counted if the agent actually used the guidance.
+
+### Quarantine Leases & Shadow-Probe Release
+
+To ensure quarantined nodes have a safe path back to eligibility without erasing historical lessons:
+1. **Quarantine Leases**: When a node is quarantined due to harm or invalidation, it is given a lease duration.
+2. **Lease Expiration**: Once the lease expires, the node is transitioned to a special `shadow_probe` delivery state.
+3. **Shadow Probe**: While in `shadow_probe`, the node is evaluated silently behind the scenes. If the agent finishes tasks using this guidance without any new harm, a **no-harm pass counter** is incremented.
+4. **Conservative Restoration**: Upon successfully passing the shadow probe, the node is restored to `conservative_only` delivery (rather than direct live eligibility).
+5. **Repeated-Harm Retirement**: If the node causes repeated harm during its shadow probe or live recovery, it is permanently retired.
+6. **Preservation of History**: Throughout this cycle, historical helped/harmed counts, original delivery states, and release attempt logs are strictly preserved.
+
 ## How MCP Interaction Works
 
 For `Codex` and `Claude Code`, ExperienceEngine is designed to keep routine review and management inside the host session first.
@@ -369,7 +444,7 @@ For `Codex`, this means routine host-native interaction stays discoverable, whil
 
 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:
+For high-impact operator actions outside routine experience governance, ExperienceEngine does not execute immediately. It uses a:
 
 ```text
 plan -> review -> explicit confirmation -> execute
@@ -386,6 +461,8 @@ That applies to:
 - import
 - rollback
 
+Autonomous experience governance is different: it is constrained to the experience store and uses guarded automatic execution plus rollback snapshots instead of routine human approval.
+
 ## Current Governance Surface
 
 Today, ExperienceEngine's minimal governance surface is:
@@ -488,6 +565,13 @@ Notes:
 - the recommended registry for managed model downloads is `https://registry.npmjs.org`
 - `ee doctor ...` reports a first-value readiness summary so users can see how much captured evidence exists before the first durable node is promoted
 
+### Offline Profiles, Manifest Health, and Vector Migration
+
+For air-gapped or sensitive environments, ExperienceEngine supports fully offline semantic retrieval:
+- **Offline Profiles**: Set `embeddingProvider = "local"` and configure an offline profile (such as `strict-offline`) in settings. ExperienceEngine will rely entirely on local ONNX model assets.
+- **Manifest Health Verification**: When running `ee doctor`, the system validates the health of the local offline profile. It reads the model manifest files, checks checksums, and detects corrupted assets. If a strict-offline profile is active but files are missing or corrupt, a warning is raised automatically.
+- **Vector Migration**: Upgrading embedding models or altering dimensions requires vector migration. ExperienceEngine tracks vector migration status for every node (`migrated`, `pending`, etc.) along with timestamps and migration errors. You can inspect this status via `ee inspect node:<id>` or `ee doctor`.
+
 Maintenance:
 
 ```bash

package/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alan512/experienceengine",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "type": "module",
   "description": "Experience governance for coding agents: learn from real task outcomes, inject reusable hints, and retire low-value guidance.",
   "license": "MIT",