feat(plugins): add read-only lifecycle control plane

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -63,7 +63,7 @@ body:
         - Bundled with Qoder Desktop
         - Host marketplace or plugin manager
         - Qwen Code extension
-        - Cursor source-local --plugin-dir
+        - Cursor session evidence (installation unavailable)
         - Pi package (pi install or pi -e)
         - npm package or standalone CLI
         - Source checkout

README.md

@@ -156,6 +156,32 @@ each host, except that Qoder CLI can use the version bundled with Qoder Desktop.
 After installing or updating a plugin, start a new session or task so the host
 reloads its plugin inventory.
 
+### Inspect and plan plugin lifecycle changes
+
+The standalone CLI can inspect local Better Harness installation evidence for
+every host without contacting a registry or changing host configuration:
+
+```bash
+better-harness plugin status --host all
+better-harness doctor --platform all
+```
+
+Build a host-specific install, update, or removal plan before using that host's
+native UI or CLI. Plans preserve native steps as typed argv data for deliberate
+external execution; the human view does not turn them into shell command
+strings, and Better Harness does not execute them:
+
+```bash
+better-harness plugin plan install --host qwen --surface cli --scope user
+better-harness plugin verify --host qwen --surface cli
+```
+
+Host differences remain explicit. Qoder Desktop is bundled, Cursor is
+session-only while its native command contract is being reconciled, Pi
+lifecycle commands without current native evidence remain manual or
+unavailable, and WorkBuddy has no managed Better Harness plugin lifecycle
+surface.
+
 ### Claude Code
 
 Register this repository as a Claude Code marketplace:
@@ -268,35 +294,40 @@ session in the repository you want to analyze and run the report prompt:
 /better-harness analyze this project's AI coding workflow and generate an evidence-backed report
 ```
 
-Only when using Qoder CLI without Qoder Desktop, add this repository as a
-marketplace and install Better Harness manually:
+Only when using Qoder CLI without Qoder Desktop, inspect the current manual
+installation disposition before following Qoder's native marketplace flow:
 
 ```bash
-qodercli plugin marketplace add \
-  'https://github.com/QoderAI/better-harness.git'
-qodercli plugin install better-harness@better-harness
+better-harness plugin plan install --host qoder --surface cli --scope user
 ```
 
-Verify the manual installation:
+The planner does not emit the older install syntax because the current native
+help and this repository's historical documentation disagree. After a manual
+installation, verify only the currently observed inventory command:
 
 ```bash
 qodercli plugin list
+better-harness plugin verify --host qoder --surface cli
 ```
 
 Then start a new Qoder CLI session before using `/better-harness`.
 
 ### Cursor
 
-The Cursor plugin is not published to the marketplace yet. Load the
-source-local plugin for one Cursor Agent session:
+The Cursor plugin is not published to the marketplace. The repository carries
+the source-local manifest, but the current local Cursor help does not verify the
+historical `--plugin-dir` contract. Better Harness therefore reports the
+installation plan as unavailable instead of emitting that command:
 
 ```bash
 git clone https://github.com/QoderAI/better-harness.git
-cursor-agent --plugin-dir /path/to/better-harness
+better-harness plugin plan install --host cursor --surface agent --scope session
 ```
 
 Cursor session evidence is supported through workspace-matched transcripts,
-metadata, and audit logs. Partial or unavailable coverage remains explicit.
+metadata, and audit logs. A session that was loaded through a separately
+verified native route can be checked with `better-harness plugin verify --host
+cursor --surface agent`; partial or unavailable coverage remains explicit.
 
 ### GitHub Copilot
 
@@ -356,8 +387,11 @@ pi -e git:github.com/QoderAI/better-harness
 ```
 
 Pi discovers the `better-harness` Skill and the `/better-harness` prompt
-template through the `pi` manifest in `package.json`. Start a new Pi session
-in the repository you want to analyze and run the report prompt:
+template through the `pi` manifest in `package.json`. After a persistent
+`pi install`, start a new Pi session in the repository you want to analyze. For
+the single-run `pi -e` form, launch it from that repository and run the report
+prompt in that same Pi session; opening another session drops the temporary
+package:
 
 ```text
 /better-harness analyze this project's AI coding workflow and generate an evidence-backed report

README.zh-CN.md

@@ -149,6 +149,29 @@ Better Harness 开放了三个相互关联的层次，而不只是一个斜杠
 需要为每个宿主单独安装 Better Harness。安装或更新插件后，请启动新的会话或任务，
 让宿主重新加载插件清单。
 
+### 检查并规划插件生命周期变更
+
+独立 CLI 可以检查所有宿主的本地 Better Harness 安装证据，不访问远程注册表，
+也不修改宿主配置：
+
+```bash
+better-harness plugin status --host all
+better-harness doctor --platform all
+```
+
+在使用宿主原生 UI 或 CLI 前，可以先生成指定宿主的安装、更新或移除计划。
+计划会把原生步骤保留为带类型的 argv 数据，供用户审阅后在外部有意执行；
+人类可读视图不会把它们拼成 shell 命令字符串，Better Harness 也不会执行这些步骤：
+
+```bash
+better-harness plugin plan install --host qwen --surface cli --scope user
+better-harness plugin verify --host qwen --surface cli
+```
+
+宿主差异会保持显式：Qoder Desktop 为内置分发；Cursor 在原生命令合同完成核对前
+只保留会话级状态；Pi 缺少当前原生证据的生命周期操作会标记为手工或不可用；
+WorkBuddy 没有可管理的 Better Harness 插件生命周期入口。
+
 ### Claude Code
 
 将本仓库注册为 Claude Code Marketplace：
@@ -255,34 +278,37 @@ Better Harness 已内置于 [Qoder](https://qoder.com/) 桌面应用，因此无
 /better-harness 分析此项目的 AI 编码工作流并生成基于证据的报告
 ```
 
-只有在未安装 Qoder Desktop、单独使用 Qoder CLI 时，才需要手动添加本仓库作为
-Marketplace 并安装 Better Harness：
+只有在未安装 Qoder Desktop、单独使用 Qoder CLI 时，才需要在遵循 Qoder 原生
+Marketplace 流程前检查当前手工安装状态：
 
 ```bash
-qodercli plugin marketplace add \
-  'https://github.com/QoderAI/better-harness.git'
-qodercli plugin install better-harness@better-harness
+better-harness plugin plan install --host qoder --surface cli --scope user
 ```
 
-验证手动安装：
+由于当前原生 help 与本仓库历史文档不一致，计划器不会输出旧版安装语法。
+手工安装后，只使用已经观察到的 inventory 命令验证：
 
 ```bash
 qodercli plugin list
+better-harness plugin verify --host qoder --surface cli
 ```
 
 然后启动新的 Qoder CLI 会话，再使用 `/better-harness`。
 
 ### Cursor
 
-Cursor 插件尚未发布到 Marketplace。可以在单次 Cursor Agent 会话中从源码加载本地插件：
+Cursor 插件尚未发布到 Marketplace。仓库包含源码本地 manifest，但当前本机
+Cursor help 没有验证历史 `--plugin-dir` 合同，因此 Better Harness 会把安装计划
+标记为不可用，而不会输出该命令：
 
 ```bash
 git clone https://github.com/QoderAI/better-harness.git
-cursor-agent --plugin-dir /path/to/better-harness
+better-harness plugin plan install --host cursor --surface agent --scope session
 ```
 
 Cursor 会话证据来自与工作区匹配的会话记录、元数据和审计日志。
-覆盖范围不完整或不可用时会被明确标注。
+通过其他已验证原生路径加载的会话可以运行 `better-harness plugin verify --host
+cursor --surface agent`；覆盖范围不完整或不可用时会被明确标注。
 
 ### GitHub Copilot
 
@@ -337,7 +363,9 @@ pi -e git:github.com/QoderAI/better-harness
 ```
 
 Pi 通过 `package.json` 中的 `pi` manifest 发现 `better-harness` Skill 和
-`/better-harness` 提示模板。在需要分析的仓库中启动新的 Pi 会话，运行报告提示词：
+`/better-harness` 提示模板。持久化执行 `pi install` 后，请在要分析的仓库中启动
+新的 Pi 会话。使用单次 `pi -e` 时，请从该仓库启动并在同一 Pi 会话中运行报告
+提示词；另开会话会丢失临时加载的包：
 
 ```text
 /better-harness 分析此项目的 AI 编码工作流并生成基于证据的报告

docs/ARCHITECTURE.md

@@ -32,6 +32,67 @@ the target journey, contract, evidence, governance, and DX-measurement system.
 - New analyzers, scoring signals, and hook helpers should own modules when they represent distinct concerns.
 - Executable behavior belongs in business-named `scripts/<capability>/`; do not create `scripts/core/`.
 - Existing `scripts/core-change-watch/` and `scripts/session-analysis/` remain live owners until a tested migration lands.
+- `scripts/plugin-lifecycle/` owns read-only Better Harness lifecycle status,
+  deterministic plans, and verification. It composes only the public
+  `agent-customize` inventory and never executes a planned host mutation. Its
+  `read-only-command.mjs` is the shared strict parser/envelope/timeout runtime
+  for lifecycle and doctor commands; it is capability-scoped, not the
+  repository-wide authoritative command-contract owner. Identity/digest,
+  bounded runtime/path discovery, target resolution, status/verification, and
+  planning live in separate private modules; `target-resolution.mjs` is the
+  single owner for host, surface, and scope selection used by status and plan.
+  `model.mjs` owns the shared lifecycle schema version, Better Harness plugin
+  identity/version, base target, diagnostic, and assertion primitives used by
+  both status and plan validation; domain modules retain only their own state
+  vocabularies and invariants.
+  `status-row.mjs` is the single `PluginLifecycleStatusV1` row factory and
+  validator for both observed inventory and inventory-failure paths; status
+  core owns only collection, ordering, aggregation, and command summaries.
+  `plan-model.mjs` is the corresponding single `PluginLifecyclePlanV1`
+  transition, step-materialization, digest, and validation owner; plan core
+  only resolves the target, collects status, and delegates construction.
+  Planned mutations are typed as external `host-plugin-state` steps, while
+  post-apply verification is typed as read-only `host-observation` so consumers
+  never mistake a verification command for a mutation performed by the CLI.
+  `command-manifest.mjs` is the pure, read-only leaf metadata owner projected
+  into the root CLI registry; `command-definitions.mjs` binds that manifest to
+  lifecycle executors and `human-output.mjs` renderers. The plugin CLI performs
+  generic descriptor dispatch and must not branch on leaf names.
+  `index.mjs` is the only cross-capability behavioral import surface and
+  contains exports rather than implementation; the root registry's direct,
+  metadata-only manifest projection is the sole allowed exception so root help
+  does not load lifecycle runtime owners.
+- `scripts/host-support/` currently provides the validated shadow profiles used
+  by plugin lifecycle. While ADR-0002 remains proposed, the adapter matrix,
+  capability providers, manifests, and installation documentation remain
+  authoritative for their existing slices; the new profiles may detect drift
+  but do not silently replace those owners. Each host owns one module under
+  `scripts/host-support/profiles/`; `profile-model.mjs` is the single local
+  `HostSurfaceProfileV1` vocabulary and validation owner. Profile modules fail
+  during their own construction and are deeply immutable before registry
+  composition; the registry facade delegates local validation and owns only
+  cross-profile host-id and alias conflicts. `profile-builders.mjs` owns typed
+  construction helpers for evidence, operations, surfaces, and steps rather
+  than duplicating their invariants, and `profiles.mjs` only composes the
+  registry. Every provider-specific filesystem root read outside the selected
+  workspace must have an explicit `inventoryHomeRoutes` entry, including state
+  files, shared caches, and compatibility roots such as a user-level
+  `.agents/` directory. Each primary and secondary route declares its provider
+  option, an isolated path relative to `--host-home`, and a redacted safe
+  fallback label; providers return the effective resolved roots so doctor can
+  report them without exposing absolute user paths. Per-surface inventory,
+  bundled, session-only, or desktop-cache observation semantics are profile
+  data. Each surface also declares whether host discovery comes from its
+  executable, a provider diagnostic, or remains unobserved; bundled and
+  session-only surfaces do not read unrelated persistent inventory. Scope-
+  artifact ownership and native home binding are profile data as well. A shared
+  `scopeArtifactPolicy` or `nativeHomeBinding` requires versioned, traceable
+  native evidence. Without an evidenced binding that can represent every
+  emitted native step, an isolated-home mutation plan fails closed and omits
+  unbound native verification steps. Lifecycle status must not branch on
+  canonical host ids.
+- `scripts/harness-doctor/` owns the bounded host/plugin diagnostic view and
+  reuses plugin-lifecycle status rather than reimplementing host discovery.
 - `scripts/harness-analysis/canvas-preview/` owns reusable local Canvas serving,
   runtime discovery, transforms, the Harness preview fixture, and cross-platform
   browser helpers. Keeping it below `harness-analysis/` preserves the tested

docs/adapters/README.md

@@ -30,12 +30,50 @@ package through the `pi` manifest in `package.json`.
 | Claude Code | Analysis-capable source-local host | `.claude-plugin/` | `scripts/agent-customize/providers/claude.mjs` | `scripts/session-analysis/platforms/claude.mjs` | self-contained HTML + Markdown | `.claude` + `CLAUDE.md` + Plugin assets | `claude plugin validate --strict .` -> isolated install/discovery -> configured-asset baseline -> validated `html` render |
 | Codex | Analysis-capable source-local host | `.codex-plugin/` | `scripts/agent-customize/providers/codex.mjs` | `scripts/session-analysis/platforms/codex.mjs` | self-contained HTML + Markdown | `.codex` + `.agents` + `AGENTS.md` | `harness prepare --platform codex` -> finalize with `html-report` validation |
 | Qoder | First-class product host | `.qoder-plugin/` | `scripts/agent-customize/providers/qoder.mjs` | `scripts/session-analysis/platforms/qoder.mjs` | `better-harness` | `.qoder/rules` + `AGENTS.md` + output templates | `better-harness harness render --mode qoder-canvas --validate` |
-| Cursor | Analysis-capable source-local host | `.cursor-plugin/` | `scripts/agent-customize/providers/cursor.mjs` | `scripts/session-analysis/platforms/cursor.mjs` | self-contained HTML + Markdown | `.cursor` + `.codex` compatibility + `AGENTS.md` | `agent --plugin-dir . --mode ask --print` -> Cursor evidence bundle -> validated `html` render |
+| Cursor | Analysis-capable source-local host | `.cursor-plugin/` | `scripts/agent-customize/providers/cursor.mjs` | `scripts/session-analysis/platforms/cursor.mjs` | self-contained HTML + Markdown | `.cursor` + `.codex` compatibility + `AGENTS.md` | native `cursor-agent --help` contract check -> unavailable install plan -> Cursor evidence bundle -> validated `html` render |
 | Qwen Code | Analysis-capable source-local host | `qwen-extension.json` | `scripts/agent-customize/providers/qwen.mjs` | `scripts/session-analysis/platforms/qwen.mjs` | self-contained HTML + Markdown | `.qwen` + `QWEN.md` + `AGENTS.md` | `harness prepare --platform qwen` -> finalize with `html-report` validation |
 | GitHub Copilot | Analysis-capable source-local host | `.github/plugin/` | `scripts/agent-customize/providers/copilot.mjs` | `scripts/session-analysis/platforms/copilot.mjs` | self-contained HTML + Markdown | `.github` + `AGENTS.md` + `~/.copilot` | `copilot plugin marketplace add .` -> `copilot plugin install better-harness@better-harness` -> configured-asset baseline -> validated `html` render |
 | Pi | Analysis-capable source-local host | `pi` manifest in `package.json` | `scripts/agent-customize/providers/pi.mjs` | `scripts/session-analysis/platforms/pi.mjs` | self-contained HTML + Markdown | `.pi` + `.agents` + `AGENTS.md` | `pi install <source>` or `pi -e <source>` -> `/better-harness` prompt template -> validated `html` render |
 | WorkBuddy | Analysis-capable source-local host | none (skills install into `~/.workbuddy/skills`) | `scripts/agent-customize/providers/workbuddy.mjs` | `scripts/session-analysis/platforms/workbuddy.mjs` | self-contained HTML + Markdown | `~/.workbuddy` `AGENTS.md` + identity files + `.agents` + `AGENTS.md` | `session-analysis --platform workbuddy sources` -> validated `html` render |
 
+## Read-only Plugin Lifecycle
+
+`better-harness plugin status`, `plan`, and `verify` expose a Better Harness-only
+view over these adapters. The shadow declarations in `scripts/host-support/`
+record lifecycle evidence without replacing this matrix while ADR-0002 is
+proposed. Each host declaration lives in `scripts/host-support/profiles/<host>.mjs`
+and uses the shared typed constructors rather than copying registry logic. Each
+module is locally validated and deeply frozen before registry composition;
+aggregate validation adds only cross-host id and alias uniqueness. The
+same profile declares its provider home option and each surface's observation
+kind, so status collection does not carry a second host lookup table or
+host-specific branches. Lifecycle status and plan also share one private target
+resolver for aliases, explicit host requirements, surfaces, and scopes, keeping
+usage diagnostics consistent as profiles grow. Plugin leaf metadata is declared
+once and projected into the root command registry; runtime definitions bind the
+same entries to executors and human renderers without leaf-name branches. Every
+observed or inventory-failure status instance passes through one validated row
+factory, so host additions cannot invent a second status shape. Every lifecycle
+plan likewise passes through one transition and validation model: mutation
+steps declare external host-plugin-state effects, while follow-up verification
+steps declare read-only host-observation effects. The thin plan core does not
+copy lifecycle state policy when a host profile is added.
+Plans never execute and always preserve native surface differences:
+
+| Host surface | Lifecycle disposition |
+| --- | --- |
+| Claude Code CLI | Native install, update, remove, and details verification steps |
+| Codex CLI / Desktop | Native CLI argv; manual Desktop UI steps |
+| Qoder Desktop / CLI | Bundled Desktop; manual CLI install, verified list/remove, unavailable update |
+| Cursor Agent | Session-only evidence; install remains unavailable while the local help contract is stale |
+| Qwen Code | Native extension install/list argv; update and remove remain unavailable until safe scope-targeted mutation semantics are evidenced |
+| GitHub Copilot CLI | Native marketplace install, list, update, and uninstall argv |
+| Pi CLI / CLI session | Persistent user/project install guidance and inventory; separate `pi -e` session-only activation whose update/remove operations are not applicable |
+| WorkBuddy | `PLUGIN_LIFECYCLE_UNSUPPORTED`; adapter evidence remains available |
+
+The lifecycle commands do not read raw session transcripts, contact a registry,
+edit host settings, or register an `apply` path.
+
 ## Discovery And Evidence
 
 - Claude Code discovers the canonical root `skills/` directory through