@alan512/experienceengine 0.3.3 → 0.3.5

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/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.
@@ -670,7 +694,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 +710,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.3",
+  "version": "0.3.5",
   "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.3",
+  "version": "0.3.5",
   "type": "module",
   "description": "Experience governance for coding agents: learn from real task outcomes, inject reusable hints, and retire low-value guidance.",
   "license": "MIT",