@alan512/experienceengine 0.3.5 → 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.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

@@ -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,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.
@@ -369,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
@@ -386,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:

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "experienceengine",
   "name": "ExperienceEngine",
-  "version": "0.3.5",
+  "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.5",
+  "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",