ultra-builder-pro-cli 0.17.1 → 0.19.1

package/docs/ARCHITECTURE.md

@@ -1,10 +1,8 @@
 # Ultra Builder Pro CLI — Architecture
 
-> Single-page entry point for reviewers and contributors. The detailed
-> roadmap and decision log live in [`docs/PLAN.zh-CN.md`](./PLAN.zh-CN.md);
-> this file freezes the architectural shape that the PLAN drives toward.
->
-> Trace: PLAN §4, decisions D12 / D13 / D18 / D20 / D29 / D32 / D33.
+> Single-page entry point for reviewers and contributors. Current authority and
+> package boundaries live in [`docs/DECISIONS.md`](./DECISIONS.md); executable
+> behavior remains defined by source, schemas, and tests.
 
 ## 1. One sentence
 
@@ -143,9 +141,9 @@ same authoritative state shape without rewriting application code.
 
 Initialization completes after local authority, classification, Git/scaffold setup,
 and read-back verification. It does not start or complete research. An explicit
-`ultra-research` invocation then records a disposition for each of the seventeen
-coverage areas and executes, verifies, or reuses only the evidence needed to converge
-the baseline.
+`ultra-research` invocation then records the model-selected semantic coverage and
+executes, verifies, or reuses only the evidence needed to converge the baseline.
+Omitted catalog areas create no workflow row.
 
 Auto initialization preserves an existing Git repository and HEAD. When Git is absent,
 it initializes `main`, adds the symlink-safe `.ultra` rule to `.gitignore`, and persists
@@ -248,7 +246,8 @@ snapshot as an output; test, review, and delivery reports carry its digest forwa
 
 `change.breadcrumb` derives the compact current position from state.db. Session,
 edit, resume, and OpenCode lifecycle hooks invoke one bundled read-only reader
-and inject only this breadcrumb, never the intent body,
+and inject it only while state.db proves an active, blocked, or ready workflow,
+never the intent body,
 provider content, or a conversation summary. A changed Git HEAD, task contract, or
 Change semantic authority marks the snapshot stale and permits recompilation through
 `change.context`.
@@ -259,6 +258,14 @@ baseline/change ownership, and transaction boundaries, then persists them. It
 does not call Anthropic, OpenAI, or another model provider and needs no separate
 model API credential.
 
+Plugin installation does not activate a semantic workflow and never edits the
+user's `CLAUDE.md`, `AGENTS.md`, or equivalent durable instructions. Public
+workflows require explicit user invocation. A completed workflow returns
+mechanically allowed transitions and a host-owned recommendation, then stops;
+it never launches the next public workflow. OpenCode realizes this boundary
+with explicit commands backed by private plugin workflow assets, while Claude,
+Codex, and Kimi use their native implicit-invocation controls.
+
 File count, token estimate, and context-share overflow produce warnings, never a
 refusal. The agent may narrow reads, load files lazily, or split a slice when that
 preserves correctness; it must not raise a threshold merely to clear a gate or
@@ -370,11 +377,12 @@ host-specific plugin, MCP, hook, launcher, and runtime contracts expected at
 that install scope. It never attributes a package to an enclosing consumer
 repository commit.
 
-`ubp --doctor [--json]` is read-only: it recomputes hashes and validates those
-entry points, returning a non-zero degraded result for missing/corrupt
-provenance, content drift, or broken host wiring. This is separate from
-`system.doctor`, which diagnoses project state, projection, incidents, sessions,
-and backup-first workflow recovery.
+`ubp --all --global --doctor [--json]` is read-only: it recomputes hashes and
+validates those entry points, returning a non-zero degraded result for
+missing/corrupt provenance, content drift, or broken host wiring. A single host
+can be selected instead of `--all`. This is separate from `system.doctor`, which
+diagnoses project state, projection, incidents, sessions, and backup-first
+workflow recovery.
 
 ## 8. Two timelines — rule layer vs execution layer
 
@@ -412,7 +420,7 @@ shippable; downstream slip never blocks an earlier release.
 | How do CLI subcommands map to MCP tools?           | [`spec/cli-protocol.md`](../spec/cli-protocol.md)   |
 | Exact SQLite schema?                               | [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) |
 | What does a tasks.json look like after projection? | [`spec/fixtures/valid/tasks.v4.5.json`](../spec/fixtures/valid/tasks.v4.5.json) |
-| Phase-by-phase work breakdown + decision log       | [`docs/PLAN.zh-CN.md`](./PLAN.zh-CN.md)             |
+| Current authority and package decisions            | [`docs/DECISIONS.md`](./DECISIONS.md)               |
 | When does each workflow write, invalidate, and converge state? | [`docs/WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md) |
 
 ## 10. Verifying the architecture

package/docs/DECISIONS.md

@@ -0,0 +1,75 @@
+# Ultra Builder Pro decision contract
+
+This document records the current product and authority boundaries that apply to
+the distributed package. Executable behavior remains defined by source,
+`spec/mcp-tools.yaml`, and `spec/schemas/state-db.sql`; `package.json` is the
+release-version authority.
+
+## Authority split
+
+| Layer | Owns | Must not own |
+|---|---|---|
+| User intent | Goals, acceptance, non-goals, material product trade-offs, risk acceptance, and authorization for irreversible or external effects | Facts that the current checkout or runtime can establish directly |
+| Host model | Classification, investigation, research coverage, solution design, task decomposition, context, test and review strategy, documentation impact, and next-action recommendations | Fabricated evidence, bypassed authorization, or durable lifecycle state |
+| Ultra MCP | IDs, state, digests, provenance, freshness, locks, leases, transactions, recovery, and legal state transitions | Product direction, a fixed research route, technology selection, or business decisions |
+| Host adapter | Native Skill discovery, user-question surfaces, tool invocation, installation, and runtime wiring | A second project-state authority |
+| Hook | Lifecycle observation, compact DB-derived context, recovery hints, and generated-projection protection | Ordinary development blocking or semantic route selection |
+
+`.ultra/state.db` is the only durable Ultra lifecycle authority. Generated JSON
+and Markdown are projections or evidence artifacts. Prompt text, chat history,
+external memory, and code-graph payloads are not Ultra authority.
+
+## Research coverage
+
+The research references form an optional semantic catalog. The host model
+selects only the areas justified by the current goal and evidence, records an
+evidence-based selection reason, and always includes synthesis. Omitted catalog
+areas create no workflow rows. An explicit `not_applicable` or accepted
+`deferred` entry is recorded only when preserving that exclusion is useful.
+
+MCP validates generic invariants: selected identifiers must exist, dispositions
+must be legal, reused or excluded evidence must be referenced, synthesis must be
+active, and at least one non-synthesis area must be applicable. MCP does not
+choose the coverage set.
+
+## Lifecycle boundaries
+
+- `ultra-init` classifies and initializes local project authority. It does not
+  perform product research or start another workflow.
+- `ultra-research` establishes or refreshes evidence and converges a baseline
+  only after the required user decisions and local Git authority exist.
+- `ultra-change` owns post-baseline product deltas. Research, planning,
+  development, testing, review, and delivery remain separately invocable
+  capabilities with DB-enforced prerequisites.
+- `ultra-deliver` converges local Ultra evidence. Commit, push, publish, deploy,
+  messaging, and other external effects remain separately authorized host
+  actions.
+
+## Package boundary
+
+The package contains the public Ultra workflows, internal review-rule Skills,
+host-specific collaboration companions, MCP runtime, adapters, lifecycle hooks,
+and minimal project bootstrap. General browser, deployment, framework,
+discovery, memory, and graph capabilities remain owned by their separately
+installed providers. Ultra stores only bounded provider metadata references.
+
+## Installation provenance
+
+Each host installation records package identity, repository, source commit when
+available, installed-asset hashes, and contract targets. A local source checkout
+also records whether it was dirty and a deterministic worktree digest. An npm
+installation has no package-local Git repository and records those source
+checkout fields as `null`; it never inherits an enclosing consumer repository.
+
+Installation and project diagnostics are read-only unless an explicit repair or
+install action is requested. No local workflow completion authorizes a remote,
+release, deployment, or destructive effect.
+
+## Current source map
+
+- Runtime architecture: [`ARCHITECTURE.md`](./ARCHITECTURE.md)
+- Workflow state and invalidation: [`WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md)
+- Host compatibility: [`RUNTIME-COMPAT-MATRIX.md`](./RUNTIME-COMPAT-MATRIX.md)
+- Plugin and user-instruction boundary: [`PLUGIN-ISOLATION-CONTRACT.md`](./PLUGIN-ISOLATION-CONTRACT.md)
+- MCP interface: [`../spec/mcp-tools.yaml`](../spec/mcp-tools.yaml)
+- Database contract: [`../spec/schemas/state-db.sql`](../spec/schemas/state-db.sql)

package/docs/LEGACY-CLI-CROSSWALK.md

@@ -24,7 +24,7 @@ contract and adds stronger authority, recovery, or portability.
 | Original capability | Current implementation | Compatibility result |
 |---|---|---|
 | Init gathers project facts, creates Ultra files, and establishes Git | `task.init_project` performs deterministic classification, scaffold, schema, Git bootstrap, read-back verification, and then stops | Preserved and strengthened. Init has its own completion boundary and never starts research implicitly. |
-| Complete product and architecture research | `ultra-research` retains the 17 semantic areas as a coverage catalog with execute/verify/reuse/not-applicable/deferred dispositions | Preserved without questionnaire overload. Necessary reports, typed semantic records, source digests, and material decision checkpoints add durable evidence. |
+| Complete product and architecture research | `ultra-research` retains the semantic reference catalog while the model selects only applicable areas and records execute/verify/reuse/not-applicable/deferred dispositions as needed | Preserved without questionnaire overload. Necessary reports, typed semantic records, source digests, and material decision checkpoints add durable evidence. |
 | Planning converts accepted research into executable work with dependencies | `ultra-plan` persists complete change-owned task contracts and an exact dependency graph | Preserved and strengthened with topology, acceptance coverage, public seams, verification commands, and plan digests. |
 | Development uses isolated Git work, TDD, verification, review, commit, and integration | `ultra-dev`, `session.*`, and the session runner create real worktrees and retain task/review/commit evidence | Preserved and strengthened. Process exit cannot complete a task; uncommitted or unintegrated worktrees cannot be deleted. |
 | Test checks wiring, acceptance, regression, build, performance, security, and failures | `ultra-test` emits a change-bound immutable report covering each applicable dimension | Preserved and strengthened with HEAD, context, task-set, and report-digest validation. |
@@ -83,7 +83,7 @@ task.init_project
   -> greenfield classification
   -> Git bootstrap when absent
   -> init read-back and completion
-  -> explicit full research with 17 coverage dispositions
+  -> explicit full research with model-selected coverage
   -> selected execute/verify/reuse work and synthesis
   -> owner-authorized local checkpoint commit when Git is unborn
   -> baseline.record
@@ -99,7 +99,7 @@ task.init_project
   -> brownfield classification and selected scope
   -> preserve current Git HEAD and dirty-state evidence
   -> init read-back and completion
-  -> explicit adoption research with 17 coverage dispositions
+  -> explicit adoption research with model-selected coverage
   -> characterization verification + known-red/gap ledger
   -> baseline.record + owner approval
   -> baseline.converge

package/docs/PLUGIN-ISOLATION-CONTRACT.md

@@ -0,0 +1,54 @@
+# Plugin Isolation Contract
+
+Ultra Builder Pro is an explicitly invoked, removable workflow plugin. Installation
+must not change a user's durable engineering policy or initialize any repository.
+
+## Owned surfaces
+
+An adapter may write only:
+
+- the host's plugin-owned command, skill, worker, hook, and runtime directories;
+- the host registry or manifest entries required to load those assets;
+- the plugin's own provenance and managed-file markers.
+
+The first command allowed to create project authority is `ultra-init`. Once invoked,
+Ultra owns only the repository-local `.ultra/` authority and its generated projections.
+
+## Surfaces Ultra does not own
+
+Install, update, doctor, and uninstall must not create, rewrite, trim, merge, or delete:
+
+- user-level `CLAUDE.md`, `AGENTS.md`, or equivalent instruction files;
+- repository-level instruction files;
+- project source, Git history, remotes, or `.ultra/` data;
+- memory or code-graph provider data.
+
+Existing Ultra marker blocks in a user handbook are legacy user content after this
+contract takes effect. They are not silently removed because the plugin cannot prove
+ownership or preserve unrelated edits. The owner may review and remove them separately.
+
+## Activation
+
+Public Ultra workflows run only after an explicit user command or skill invocation.
+Completion of one workflow may return allowed transitions and a recommendation, but it
+must not start another public workflow.
+
+Host adapters prevent implicit model activation with the strongest native mechanism:
+
+- Claude Code and Kimi Code mark public workflow skills as model-disabled;
+- Codex marks workflow metadata as implicit-invocation-disabled;
+- OpenCode exposes public workflows through commands backed by private plugin assets,
+  not through the model-discoverable skill catalog.
+
+Internal review-rule skills remain available only to their bounded workers.
+
+## Idle behavior
+
+Outside a repository containing `.ultra/state.db`, all Ultra hooks are silent. Inside
+an initialized repository they remain silent unless a DB-authoritative workflow is
+active, blocked, or ready. The sole idle-time enforcement is protection against direct
+writes to generated Ultra projections; the DB remains authoritative.
+
+Installation tests preserve byte-for-byte snapshots of all supported user handbook
+paths. Runtime tests cover explicit activation, idle silence, active recovery, and
+projection protection.

package/docs/ROADMAP.md

@@ -1,9 +1,9 @@
 # ultra-builder-pro-cli — Roadmap
 
-> **Current roadmap**. [`PLAN.zh-CN.md`](./PLAN.zh-CN.md) preserves the original
-> phase plan and decision history. Current executable contracts live in
-> `spec/`, `AGENT-CONTEXT.md`, and `RUNTIME-COMPAT-MATRIX.md`; those sources win
-> when historical plan text differs.
+> **Current roadmap**. [`DECISIONS.md`](./DECISIONS.md) defines the current
+> authority and package boundaries. Executable contracts live in `spec/`,
+> `AGENT-CONTEXT.md`, and `RUNTIME-COMPAT-MATRIX.md`; source and contract tests
+> win when roadmap text drifts.
 
 **Goal**: distribute the Ultra Builder Pro engineering loop as native Claude
 Code, OpenCode, Codex, and Kimi Code plugins, and run it with isolated sessions
@@ -13,7 +13,8 @@ sharing one authoritative workflow store.
 
 **Distribution channels (v1.0)**: npm · Homebrew · pip.
 
-**Release line**: `0.16.x`; every release is gated by `npm run verify:release`.
+**Release line**: the `package.json` version; every release is gated by
+`npm run verify:release`.
 
 ---
 
@@ -39,11 +40,11 @@ sharing one authoritative workflow store.
 | 5     | Recovery + staleness + auto-routing            | ✅ done (D43) → v0.2 |
 | 6     | Monitoring + telemetry                          | ✅ done (D44) → v0.2 |
 | 4.6b  | Full conformance suite                         | ✅ done (D45) — 20 conformance + 21 resolveTarget tests |
-| 7     | tagged tasks + skill mining; retired Ultra memory handed to cloud-mem/claude-mem | ✅ superseded by D50 boundary cleanup |
+| 7     | tagged tasks + skill mining; retired Ultra memory delegated to external providers | ✅ superseded by the package-boundary cleanup |
 | 8A    | Plan automation (parse / topo / expand + artifact + human gate) | ✅ done (D47, `a932cb8`) → v0.3 |
 | 8B    | Execution automation (dispatch / parallel worktree / merge) | ✅ done (D48, `8224159`) — **v0.3 ready** |
 | 8C    | Continuous change packets + context compiler + convergence + doctor | ✅ done (D52) |
-| 10    | Context Spine v2 + breadcrumb + fresh-context budget + spec learning + two-axis review | ✅ done |
+| 10    | Context Manifest v3 + breadcrumb + fresh-context budget + spec learning + two-axis review | ✅ done |
 | 11    | Greenfield/brownfield baseline adoption + advisory context budgets + convergence gate | ✅ done |
 | 12    | Repository evidence snapshots + gap ledger + migration re-adoption + incident governance | ✅ done |
 | 13    | Durable init-to-delivery workflows + task execution contracts + immutable stage evidence | ✅ done |
@@ -79,16 +80,15 @@ ultra-tools/                ← CLI fallback, migration, and diagnostics
     └── legacy-memory.cjs   (explicit inspect/archive/confirmed prune)
 
 bin/install.js              ← multi-runtime installer
-bin/handbook.js             ← explicit managed user-handbook sync
 adapters/                   ← native Claude/OpenCode/Codex plugin builders
 skills/                     ← allowlisted Ultra workflows, internal rules, and collab companions
 hooks/                      ← 7 executable workflow hooks + shared Context Spine helper; OpenCode uses native JavaScript hooks
 docs/
-├── PLAN.zh-CN.md                historical phase plan + decision log
+├── DECISIONS.md                 current authority and package boundaries
 ├── ARCHITECTURE.md              Phase 1 single-page entry point
 ├── WORKFLOW-LIFECYCLE.md        baseline classification + DB transition contract
 ├── AGENT-CONTEXT.md             Phase 3 canonical runtime context contract
-├── USER-HANDBOOK-CONTRACT.md    managed CLAUDE.md / AGENTS.md boundary
+├── PLUGIN-ISOLATION-CONTRACT.md install, activation, idle, and ownership contract
 ├── RUNTIME-COMPAT-MATRIX.md     Phase 4 runtime capability matrix
 ├── STATE-DB-ACCESS-POLICY.md    Phase 2 multi-process write contract
 ├── COMMIT-HASH-BACKFILL.md      Phase 2.8 two-commit completion flow
@@ -106,6 +106,6 @@ npm audit
 
 ## Out of scope for v1.0 (deferred)
 
-PLAN §13 lists Copilot / Cursor / Windsurf / 7 more runtimes, web
-dashboard / TUI, team-collab server, plugin
-marketplace.
+Additional runtimes, a web dashboard or TUI, a team-collaboration server, and
+an independent plugin marketplace remain deferred until a current product
+decision brings them into scope.

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -15,10 +15,10 @@ not installed.
 |---|---|---|---|---|
 | Package form | `.claude-plugin` native plugin | native config bundle + JS plugin | personal `.codex-plugin` | managed `kimi.plugin.json` plugin |
 | Public entry | `/ultra-*`, `/learn` | `/ultra-*`, `/learn` | `$ultra-builder-pro:<skill>` | `/ultra-builder-pro:<command>` |
-| Public Ultra workflows | 12 | 12 | 12 | 12 |
+| Public Ultra workflows | 12, model invocation disabled | 12 commands backed by private workflow assets | 12, implicit invocation disabled | 12, model invocation disabled |
 | Internal agent-rule skills | 4, non-user-facing | 4, non-user-facing | 4 with implicit invocation disabled | 4, consumed by review workers |
 | Collaboration companions | `codex-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` | `cc-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` |
-| Host bootstrap | native plugin context | native plugin context | native plugin context | `using-ultra-builder-pro` session-start skill |
+| Automatic workflow bootstrap | N/A | N/A | N/A | N/A |
 | External browser/deploy/framework skills | N/A | N/A | N/A | N/A |
 
 Codex converts workflows into namespaced skills and records eleven legacy
@@ -46,21 +46,17 @@ not presented as nonexistent custom agents.
 
 | Lifecycle | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
-| Session context/health | FULL, DB-derived Context Spine breadcrumb on native `SessionStart` | FULL, the native JS plugin invokes the same bundled DB breadcrumb reader; health via `system.doctor` | FULL, DB-derived breadcrumb on native `SessionStart` | FULL, DB-derived breadcrumb via session-start skill + hooks |
+| Session context/health | FULL, active-workflow breadcrumb on native `SessionStart` | FULL, native JS plugin injects only an active-workflow breadcrumb; health via `system.doctor` | FULL, active-workflow breadcrumb on native `SessionStart` | FULL, active-workflow breadcrumb via native hooks |
 | Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects projection writes | FULL, `PreToolUse Edit|Write|apply_patch` | FULL, native `PreToolUse Edit|Write` deny contract |
 | Pre-compact checkpoint | FULL | FULL | FULL | FULL, native `PreCompact` |
 | Post-compact context injection | FULL | FULL, native compacting context | FULL, native `PostCompact` restore | DEGRADED; checkpoint restoration runs, but Kimi 0.26/0.27 does not reinject fire-and-forget hook text |
 | Stop lifecycle advisory | FULL, native non-blocking `Stop` | N/A, no equivalent stop event needed | FULL, native non-blocking `Stop` | FULL, native non-blocking `Stop` |
 | Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL | FULL, native `SubagentStart` / `SubagentStop` |
 
-Kimi's session bootstrap therefore also instructs recovery to inspect
-`.ultra/runtime/checkpoint.json` and call Ultra status/doctor after compaction.
-This keeps durable recovery intact without claiming dynamic context injection
-that the host does not guarantee.
-
-Health/context hooks inspect initialized projects; projection protection also
-applies at baseline, while compact/stop/subagent enforcement remains
-active-workflow scoped. No host receives prompt capture, transcript capture,
+Health/context, compact, stop, and subagent hooks remain silent unless
+`.ultra/state.db` proves an active, blocked, or ready workflow. Projection
+protection applies to every initialized project because generated projections
+must never become a second authority. No host receives prompt capture, transcript capture,
 observation journaling, session-summary memory, generic command blocking, or
 generic post-edit policy.
 Baseline-adoption and context-budget warnings are injected as advisory context;
@@ -73,7 +69,7 @@ they do not deny edits or stop active incident work.
 | stdio MCP registration | plugin `.mcp.json` | `opencode.json` local MCP entry | plugin `.mcp.json` | plugin `mcpServers` entry |
 | Live/declared contracts | 50 | 50 | 50 | 50 |
 | Greenfield/brownfield baseline adoption | FULL | FULL | FULL | FULL |
-| Context Spine v2 / breadcrumb | FULL | FULL, same bundled read-only DB reader as every hook | FULL | FULL |
+| Context Manifest v3 / breadcrumb | FULL | FULL, same bundled read-only DB reader as every hook | FULL | FULL |
 | Approval-gated spec learning | FULL | FULL | FULL | FULL |
 | Host-native review/discovery/ask | native | native | documented in `codex-capability-map.json` | native Kimi tools and workers |
 | Durable authority | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` |
@@ -89,18 +85,19 @@ generated launcher recovers the project from the inherited `PWD`, sets
 cannot be established. On POSIX it intentionally uses `env node` because Kimi
 0.26/0.27's embedded Node ABI differs from the ABI used to install `better-sqlite3`.
 
-## 5. User handbook presentation
+## 5. User instruction isolation
 
 | Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
 | Durable user file | `~/.claude/CLAUDE.md` | `~/.config/opencode/AGENTS.md` | `~/.codex/AGENTS.md` | `~/.kimi-code/AGENTS.md` |
 | Automatic overwrite by plugin install | no | no | no | no |
-| Explicit managed-block sync | `ubp-handbook --runtime claude` | `ubp-handbook --runtime opencode` | `ubp-handbook --runtime codex` | `ubp-handbook --runtime kimi` |
-| Backup before change | FULL | FULL | FULL | FULL |
+| Writer shipped by Ultra | N/A | N/A | N/A | N/A |
+| Uninstall removes user instructions | no | no | no | no |
 
-The Kimi plugin installer does not edit `~/.kimi-code/config.toml`. Handbook
-sync remains a separate, previewable action so user policy and plugin mechanics
-do not become one irreversible mutation.
+The Kimi plugin installer also does not edit `~/.kimi-code/config.toml`. Durable
+user preferences belong to each host and remain outside Ultra's ownership.
+Legacy Ultra handbook text is not proof of plugin ownership and is never
+silently rewritten or removed.
 
 ## 6. Install, update, and uninstall
 
@@ -113,9 +110,15 @@ do not become one irreversible mutation.
 | Preserves unrelated config | FULL | FULL | FULL | FULL, including `config.toml` and unrelated registry records |
 | Uninstall ownership guard | managed plugin root | sentinels + owned MCP entry | managed root/manifest/agent headers | managed root + exact registry record |
 | Normalized install provenance | FULL | FULL | FULL | FULL |
-| Read-only `ubp --doctor` | FULL | FULL | FULL | FULL |
+| Local-source dirty state and worktree digest | FULL | FULL | FULL | FULL |
+| Read-only `ubp --all --global --doctor` | FULL | FULL | FULL | FULL |
 | Asset-content and host-contract drift detection | FULL | FULL | FULL | FULL |
 
+Package-local Git provenance never falls through to an enclosing consumer
+repository. Source installs record commit, dirty state, and a deterministic
+worktree digest; registry installs record unavailable checkout fields as
+`null`.
+
 Kimi's global managed root is
 `~/.kimi-code/plugins/managed/ultra-builder-pro`; its only registry mutation is
 the owned `ultra-builder-pro` entry in `~/.kimi-code/plugins/installed.json`.
@@ -143,8 +146,8 @@ records. Uninstall refuses an unmanaged or conflicting root.
   skills and generic/memory hooks from re-entering a package.
 - `tests/retired-runtime.test.cjs` prevents retired runtime code or prompt text
   from re-entering active product surfaces.
-- `adapters/_shared/tests/handbook.test.cjs` verifies host rendering, backup,
-  migration, and idempotency.
+- `adapters/_shared/tests/plugin-isolation.test.cjs` and `tests/install.test.cjs`
+  verify the absence of a handbook writer and byte-preservation of all user instruction files.
 - `adapters/_shared/tests/provenance.test.cjs` verifies normalized manifests,
   content hashes, source attribution, corruption handling, and contract drift.
 - `tests/install.test.cjs` verifies healthy four-host doctor output and

package/docs/STATE-DB-ACCESS-POLICY.md

@@ -1,7 +1,7 @@
 # `.ultra/state.db` access policy
 
-> Phase 2.2 contract. Trace: PLAN §6 Phase 2.2, decisions D18 / D32 / D37,
-> risks R21 / R25.
+> Multi-process access contract. Current authority is defined by
+> [`DECISIONS.md`](./DECISIONS.md) and the live database schema.
 
 `.ultra/state.db` is the only authoritative state store for baselines, changes,
 decision threads/items, tasks, workflow runs/steps, events, sessions, incidents,

package/docs/WORKFLOW-LIFECYCLE.md

@@ -35,12 +35,13 @@ authority, and no new stage may start on an archived or cancelled change. Doctor
 recovers a legacy change without this link into an explicitly blocked workflow;
 it does not fabricate the missing provenance.
 
-Ultra does not select an MVP. Product scope and material delivery posture are owner
-decisions. The seventeen research areas are a coverage catalog, not a forced
-questionnaire. Initial greenfield and brownfield research must disposition every area
-as `execute`, `verify_existing`, `reuse`, `not_applicable`, or accepted `deferred`;
-only selected necessary work executes. Bounded change research records the same
-selection rationale over its smaller scope.
+Ultra does not select product scope or material delivery posture; those remain user
+decisions. Research references form an optional catalog, not a forced questionnaire.
+The host model selects only evidence-relevant areas and records one coverage rationale.
+MCP validates identifiers, dispositions, evidence requirements, synthesis, and at
+least one applicable semantic area. Omitted areas create no workflow step. An explicit
+`not_applicable` or accepted `deferred` row is retained only when its exclusion is
+material.
 
 ## 2. How `ultra-init` classifies a repository
 
@@ -325,7 +326,7 @@ current gate evidence do block.
 
 ```text
 ultra-init -> Git/scaffold/authority verification -> init completed
--> explicit ultra-research -> disposition 17 coverage areas -> selected evidence work
+-> explicit ultra-research -> model-selected coverage -> selected evidence work
 -> local checkpoint when Git is unborn -> baseline approval
 -> ultra-change -> optional bounded research/plan -> dev -> risk-selected test/review
 -> local deliver/archive
@@ -335,7 +336,7 @@ ultra-init -> Git/scaffold/authority verification -> init completed
 
 ```text
 ultra-init -> preserve Git/classify brownfield -> init completed
--> explicit adoption research -> disposition 17 coverage areas
+-> explicit adoption research -> model-selected coverage
 -> selected characterization/known-red evidence -> gap ledger -> owner approval
 -> first ultra-change -> optional bounded research/plan -> dev -> test/review -> deliver
 ```
@@ -389,8 +390,9 @@ parallel workflow or substitutes a Prompt summary for DB state.
 
 ## 9. Recovery and diagnosis
 
-Use `system.doctor` for project authority and `ubp --doctor` for installed host
-assets. Both are read-only unless an explicit project repair command is chosen.
+Use `system.doctor` for project authority and
+`ubp --all --global --doctor` for installed host assets. Both are read-only
+unless an explicit project repair command is chosen.
 
 During an explicit repair, a legacy active change that predates durable workflows gets
 one blocked change run at `bind-baseline` with

package/hooks/active_task_context.py

@@ -52,7 +52,7 @@ def main() -> None:
     except ContextSpineError as exc:
         print(f"[active_task_context] cannot inspect Context Spine: {exc}", file=sys.stderr)
         breadcrumb = None
-    if breadcrumb and breadcrumb.get("change_id"):
+    if breadcrumb and breadcrumb.get("workflow"):
         print(json.dumps({"hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "additionalContext": render_breadcrumb(root, breadcrumb),

package/hooks/context_spine.py

@@ -22,7 +22,7 @@ class Breadcrumb(dict):
 
 def find_root(start: Path):
     for root in (start, *start.parents):
-        if (root / ".ultra").is_dir():
+        if (root / ".ultra" / "state.db").is_file():
             return root
     return None
 

package/hooks/health_check.py

@@ -27,6 +27,22 @@ def hook_input() -> dict:
         return {}
 
 
+def has_active_workflow(db_path: Path) -> bool:
+    if not db_path.is_file():
+        return False
+    try:
+        uri = f"file:{db_path}?mode=ro"
+        with sqlite3.connect(uri, uri=True, timeout=1) as conn:
+            row = conn.execute(
+                """SELECT 1 FROM workflow_runs
+                   WHERE status IN ('active', 'blocked', 'ready')
+                   LIMIT 1"""
+            ).fetchone()
+            return row is not None
+    except sqlite3.Error:
+        return False
+
+
 def inspect(root: Path) -> dict:
     db_path = root / ".ultra" / "state.db"
     report = {"status": "healthy", "project": str(root), "checks": {}}
@@ -171,6 +187,9 @@ def main() -> None:
     if root is None:
         print(json.dumps({}))
         return
+    if not has_active_workflow(root / ".ultra" / "state.db"):
+        print(json.dumps({}))
+        return
     report = inspect(root)
     if report["status"] != "healthy":
         print("[Ultra health] " + json.dumps(report, ensure_ascii=False, sort_keys=True), file=sys.stderr)

package/hooks/pre_stop_check.py

@@ -34,7 +34,7 @@ def main() -> None:
         print(f"[pre_stop_check] cannot inspect Context Spine: {exc}", file=sys.stderr)
         allow_stop()
         return
-    if breadcrumb and breadcrumb.get("change_id"):
+    if breadcrumb and breadcrumb.get("workflow"):
         allowed = ", ".join(breadcrumb.get("allowed_transitions") or []) or "none"
         required = breadcrumb.get("required_transition") or "none"
         print(

package/hooks/workflow_checkpoint.py

@@ -33,7 +33,7 @@ def main() -> None:
         print(f"[workflow_checkpoint] cannot inspect Context Spine: {exc}", file=sys.stderr)
         print(json.dumps({}))
         return
-    if not breadcrumb or not breadcrumb.get("change_id"):
+    if not breadcrumb or not breadcrumb.get("workflow"):
         print(json.dumps({}))
         return
 

package/hooks/workflow_context.py

@@ -28,7 +28,7 @@ def main() -> None:
     except ContextSpineError as exc:
         print(f"[workflow_context] cannot inspect Context Spine: {exc}", file=sys.stderr)
         breadcrumb = None
-    if breadcrumb:
+    if breadcrumb and breadcrumb.get("workflow"):
         context = render_breadcrumb(root, breadcrumb)
     else:
         print(json.dumps({}))

package/hooks/workflow_resume.py

@@ -64,7 +64,7 @@ def main() -> None:
     text = None
     try:
         breadcrumb = read_breadcrumb(root)
-        if breadcrumb:
+        if breadcrumb and breadcrumb.get("workflow"):
             text = render_breadcrumb(root, breadcrumb)
     except ContextSpineError as exc:
         print(f"[workflow_resume] cannot inspect Context Spine: {exc}", file=sys.stderr)