@alan512/experienceengine 0.3.4 → 0.3.6

package/dist/store/sqlite/schema.sql

@@ -289,3 +289,101 @@ CREATE TABLE IF NOT EXISTS scope_task_stats (
   updated_at TEXT NOT NULL,
   PRIMARY KEY (scope_id, task_type)
 );
+
+CREATE TABLE IF NOT EXISTS hygiene_governance_schedules (
+  scope_id TEXT PRIMARY KEY,
+  last_governed_at TEXT,
+  next_due_at TEXT NOT NULL,
+  pending_reasons_json TEXT NOT NULL DEFAULT '[]',
+  last_run_status TEXT,
+  last_failure_class TEXT,
+  backoff_until TEXT,
+  last_finding_hash TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS hygiene_governance_leases (
+  scope_id TEXT PRIMARY KEY,
+  lease_owner TEXT NOT NULL,
+  lease_expires_at TEXT NOT NULL,
+  acquired_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS hygiene_governance_runs (
+  run_id TEXT PRIMARY KEY,
+  scope_id TEXT NOT NULL,
+  trigger TEXT NOT NULL,
+  status TEXT NOT NULL,
+  failure_class TEXT,
+  failure_message TEXT,
+  checkpoint_json TEXT,
+  started_at TEXT,
+  finished_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS hygiene_governance_plans (
+  plan_id TEXT PRIMARY KEY,
+  run_id TEXT,
+  scope_id TEXT NOT NULL,
+  status TEXT NOT NULL,
+  finding_hash TEXT,
+  risk TEXT,
+  plan_json TEXT NOT NULL,
+  validator_result_json TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS hygiene_governance_actions (
+  action_id TEXT PRIMARY KEY,
+  plan_id TEXT,
+  run_id TEXT,
+  scope_id TEXT NOT NULL,
+  action_type TEXT NOT NULL,
+  status TEXT NOT NULL,
+  affected_ids_json TEXT NOT NULL DEFAULT '[]',
+  affected_row_hashes_json TEXT NOT NULL DEFAULT '{}',
+  action_json TEXT NOT NULL DEFAULT '{}',
+  validator_decision_json TEXT,
+  before_snapshot_id TEXT,
+  after_state_json TEXT,
+  rollback_of_action_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  applied_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS hygiene_governance_approvals (
+  approval_id TEXT PRIMARY KEY,
+  action_id TEXT NOT NULL,
+  plan_id TEXT,
+  scope_id TEXT NOT NULL,
+  status TEXT NOT NULL,
+  confirmation_token_hash TEXT,
+  token_expires_at TEXT,
+  diff_summary TEXT,
+  affected_row_hashes_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  decided_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS hygiene_governance_snapshots (
+  snapshot_id TEXT PRIMARY KEY,
+  scope_id TEXT NOT NULL,
+  action_id TEXT NOT NULL,
+  row_refs_json TEXT NOT NULL,
+  snapshot_json TEXT NOT NULL,
+  row_hashes_json TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_hygiene_governance_runs_scope ON hygiene_governance_runs(scope_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_hygiene_governance_plans_scope ON hygiene_governance_plans(scope_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_hygiene_governance_actions_scope ON hygiene_governance_actions(scope_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_hygiene_governance_approvals_scope ON hygiene_governance_approvals(scope_id, status);
+CREATE INDEX IF NOT EXISTS idx_hygiene_governance_snapshots_action ON hygiene_governance_snapshots(action_id);

package/docs/releases/v0.3.5.md

@@ -0,0 +1,42 @@
+# ExperienceEngine v0.3.5
+
+v0.3.5 productizes inspection and operator surfaces in one release: Quality Band becomes the shared trust explanation model, and CLI/MCP surfaces now distinguish routine, operator, and advanced workflows.
+
+## What Changed
+
+- Added a shared derived Quality Band explanation with `strong`, `building`, and `risky` bands.
+- Added stable reason codes, readable reasons, evidence references, and review-only action text for node inspection.
+- Preserved existing `qualityBand` and `qualityDrivers` public fields while adding the richer structured `quality` payload.
+- Updated `ee inspect --last`, `ee inspect node:<id>`, and `ee inspect repo` to show Quality Band context.
+- Exposed the same structured Quality Band fields through Codex/MCP inspection and broker payloads.
+- Added shared routine/operator/advanced surface tier metadata.
+- Reworked default CLI help so routine host-first review, operator workflows, and advanced/experimental commands are grouped separately.
+- Added tier metadata to Codex broker action listings while preserving existing action ids, categories, and risk levels.
+- Updated MCP capabilities to expose routine, operator, and advanced surface groupings.
+- Updated README, README.zh-CN, user guide, and architecture docs to describe workflow tier separately from mutation risk.
+- Hardened OpenClaw upgrade/repair reinstall handling so path/archive reinstalls safely clear stale ExperienceEngine plugin paths and allow-list entries before reinstalling.
+- Added unit coverage for strong/building/risky derivation, CLI output, repo summary output, and Codex/MCP structured payloads.
+
+## Boundaries
+
+- Quality Band is explanatory only.
+- It does not mutate nodes, create a new lifecycle state, or replace delivery gating.
+- Runtime injection still depends on the existing delivery state, repo policy, scorecard, and second-opinion paths.
+- Surface tiers are presentation and metadata only.
+- Existing CLI commands and Codex broker action ids remain available.
+- Operator review, hygiene, and export drafts remain read-only inspection flows; tier labeling does not imply policy restore, node mutation, or export writing.
+- Risk and tier are separate axes: read-only operator workflows can be low-risk, while install/upgrade/import/rollback remain high-impact operator workflows.
+
+## Validation
+
+- `pnpm exec tsc --noEmit`
+- `pnpm exec vitest run tests/unit/quality-band.test.ts tests/unit/interaction-service.test.ts tests/unit/inspect-command.test.ts tests/unit/codex-mcp-server.test.ts tests/unit/repo-summary.test.ts tests/unit/operator-review-flow.test.ts`
+- `pnpm exec vitest run tests/unit/cli-dispatch.test.ts tests/unit/codex-broker-tools.test.ts tests/unit/codex-mcp-server.test.ts`
+- `pnpm exec openspec validate formalize-quality-band-inspection-model --strict`
+- `pnpm exec openspec validate complete-operator-surface-boundaries --strict`
+- `pnpm exec openspec validate --all --strict`
+- `pnpm check`
+- Source-build Windows smoke: `node dist\cli\index.js inspect --last`, `node dist\cli\index.js inspect repo`, `node dist\cli\index.js doctor codex`, `node dist\cli\index.js doctor claude-code`
+- Source-build WSL smoke: `node dist/cli/index.js upgrade openclaw`, `node dist/cli/index.js doctor openclaw`, `node dist/cli/index.js inspect repo`, `node dist/cli/index.js inspect --last`
+
+Published npm package and host marketplace validation should be repeated after release because the smoke checks above used the source build.

package/docs/releases/v0.3.6.md

@@ -0,0 +1,28 @@
+# v0.3.6
+
+`v0.3.6` adds autonomous hygiene governance. ExperienceEngine can now periodically govern duplicated, stale, or risky local experience without requiring users to run routine hygiene commands by hand.
+
+## Added
+
+- Added persisted per-scope governance schedules, leases, runs, plans, actions, legacy approval records, and rollback snapshots.
+- Added host-attached governance wakeups from startup, prompt lookup, posttask finalization, and stop paths.
+- Added bounded LLM-assisted governance planning, deterministic validation, safe automatic application, and guarded automatic execution for high-impact experience-node actions.
+- Added MCP resources for `experienceengine://governance` and `experienceengine://governance/approvals`.
+- Kept brokered governance approval actions as a compatibility surface for existing approval records.
+- Added CLI fallback surfaces:
+  - `ee inspect governance`
+  - `ee maintenance governance drain`
+
+## Behavior Notes
+
+- Hygiene inspection and operator review remain read-only.
+- Routine governance is automatic and host-attached; CLI drain is an operator fallback for troubleshooting or catch-up.
+- Frequent host open/close cycles do not define governance cadence. The persisted schedule, lease, backoff, finding hash, and action budget do.
+- Safe automatic actions include exact duplicate merge, stale shadow-only retirement, delivery downgrade, and quarantine.
+- High-impact experience-node actions are applied as guarded soft changes: semantic/conflicted merges preserve evidence and downgrade live eligibility, promotion lands at conservative delivery, and deletion is a soft-retire with rollback snapshots. Broad rewrites, export writing, repo policy changes, and restore actions are rejected by automatic experience governance.
+
+## Validation
+
+- Targeted unit coverage for scheduler, LLM planner, validator, applicator, guarded execution, CLI, MCP, runtime, and operator review paths.
+- `pnpm tsc --noEmit --pretty false`
+- `openspec validate add-autonomous-hygiene-governance --strict`

package/docs/user-guide.md

@@ -221,6 +221,27 @@ Use `ee` for:
 - learning and intervention inspection
 - quick helped / harmed feedback
 
+ExperienceEngine surfaces are grouped by workflow tier:
+
+- `Routine`
+  - host-first review and feedback
+  - `ee status`
+  - `ee doctor <host>`
+  - `ee inspect --last`
+  - `ee helped` / `ee harmed`
+- `Operator`
+  - `ee install|upgrade|repair <host>`
+  - `ee inspect review`
+  - `ee inspect hygiene`
+  - `ee inspect export-drafts`
+  - managed backup/export/import/rollback
+- `Advanced / experimental`
+  - `ee maintenance ...`
+  - raw evaluation commands
+  - broker internals and developer diagnostics
+
+Workflow tier is separate from mutation risk. Operator review, hygiene, and export drafts are operator-tier but read-only. Install, upgrade, import, and rollback are operator-tier and high-impact.
+
 `ee status` and `ee doctor` now also summarize recent retrieval health in product language. They still show the raw counters, but they additionally explain whether ExperienceEngine is mostly injecting, mostly staying conservative, or still skipping too many close-match tasks in the current repo.
 
 Their roles are intentionally different:
@@ -251,9 +272,12 @@ That output now tells you both:
 When you inspect a specific node, ExperienceEngine now also shows a lightweight quality judgment layer:
 
 - a `quality band` (`strong`, `building`, or `risky`)
-- the short drivers behind that judgment
+- a short summary, reason codes, readable reasons, and evidence references behind that judgment
+- a review-only action for `building` or `risky` guidance when a closer look is useful
 - a compact applicability profile covering best fit, scope validity, confidence, risk, and when to avoid reuse
 
+The same Quality Band model is also exposed in host-native MCP inspection payloads and in `ee inspect repo` as a current-scope distribution. It is explanatory only: it helps you judge whether guidance is strong, still building, or risky, but it does not by itself change delivery state, mutate nodes, or gate injection.
+
 ### 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.
@@ -275,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
@@ -286,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:
 
@@ -301,6 +327,45 @@ 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.
+
 ## How MCP Interaction Works
 
 For `Codex` and `Claude Code`, ExperienceEngine is designed to keep routine review and management inside the host session first.
@@ -345,7 +410,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
@@ -362,6 +427,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:
@@ -670,7 +737,12 @@ Use `ee` directly when:
 Useful fallback commands:
 
 ```bash
+# Routine fallback
 ee inspect --last
+ee helped
+ee harmed
+
+# Operator inspection
 ee inspect recent injected 10
 ee inspect review
 ee inspect repo
@@ -681,8 +753,6 @@ ee inspect active
 ee inspect node <id>
 ee inspect state retired
 ee inspect type warning
-ee helped
-ee harmed
 ee feedback --last helped
 ee feedback node <id> harmed
 ee disable scope

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "experienceengine",
   "name": "ExperienceEngine",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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.4",
+  "version": "0.3.6",
   "type": "module",
   "description": "Experience governance for coding agents: learn from real task outcomes, inject reusable hints, and retire low-value guidance.",
   "license": "MIT",