ultra-builder-pro-cli 0.6.0 → 0.8.1

package/.ultra-template/changes/active/.gitkeep

@@ -0,0 +1 @@
+

package/.ultra-template/changes/archive/.gitkeep

@@ -0,0 +1 @@
+

package/CHANGELOG.md

@@ -7,6 +7,84 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.1] — 2026-07-17
+
+### Fixed
+
+- Removed a retired-surface name accidentally reintroduced in the D53 decision
+  note. The unchanged retirement contract caught it before `v0.8.0` reached npm;
+  this immutable patch release carries the complete harness closure forward.
+
+## [0.8.0] — 2026-07-17
+
+### Added
+
+- Added a first-class incident debug lane: incident changes now create a
+  registered `diagnosis.md` artifact whose reproduction, hypotheses, root
+  cause, regression-test, and recovery sections are required by convergence.
+- Added normalized install-provenance manifests for Claude Code, OpenCode, and
+  Codex plus read-only `ubp --doctor [--json]` checks for asset hashes and
+  host-specific plugin, hook, MCP, launcher, and runtime entry points.
+
+### Fixed
+
+- Turned workflow compaction checkpoints into a real recovery consumer:
+  resume now rejects malformed or terminal checkpoints, selects the newest
+  valid live/checkpoint state, and atomically restores missing or older live
+  workflow state before re-injecting context.
+
+## [0.7.0] — 2026-07-17
+
+### Added
+
+- Added `ultra-change` and `ultra-doctor` as native workflows on Claude Code,
+  OpenCode, and Codex. Daily fixes, features, redesigns, and incidents now stay
+  attached to an explicit change packet after the initial baseline delivery.
+- Added seven `change.*` MCP tools and `system.doctor`, advancing the live MCP
+  contract to 29 tools and `.ultra/state.db` to schema `9.0` with 15 tables for
+  changes, artifacts, context snapshots, trace links, incidents, projection
+  jobs, and durable event-consumer cursors.
+- Added deterministic convergence and archive gates for task completion, spec
+  deltas, tests, documentation impact, review evidence, context freshness, and
+  baseline reconciliation.
+
+### Changed
+
+- `task.init_project` now initializes `state.db` immediately and creates active
+  and archived change roots. `tasks.json` remains a generated projection.
+- MCP mutations now commit authority first, enqueue a durable projection job,
+  process it, and expose projection status in MCP metadata instead of silently
+  swallowing projection failures.
+- Session-start and edit hooks now understand initialized baselines and active
+  changes. Health checks surface incidents, projection lag, orphan sessions,
+  and missing change artifacts; direct writes to the task projection remain
+  blocked even outside a command-scoped workflow.
+- Memory and code-graph content are exclusively owned by separately installed
+  providers. Ultra accepts only provider metadata references in compiled change
+  contexts and never stores recalled content, graph payloads, or embeddings.
+
+### Fixed
+
+- Wired spec-staleness consumption, crash recovery, projection processing, and
+  durable cursors into the real orchestrator loop instead of leaving production
+  helpers unconsumed.
+- Kept `intent.md` synchronized with authoritative change updates, linked task
+  status events to their newly assigned change, and included `plan.export`
+  events in projection accounting.
+- Added atomic projection claims and backup-first recovery for failed or stale
+  interrupted jobs so a crashed projector cannot remain invisibly `running`.
+- Kept all three native plugin bundles, MCP launchers, agents, hooks, commands,
+  and user-handbook renderings on one explicit Ultra-owned asset allowlist.
+
+### Removed
+
+- Removed the internal filesystem graph watcher and its dependency; external
+  graph providers own indexing and refresh.
+- Removed the retired command-proxy detector, installer option, managed handbook
+  block, cache artifacts, prompts, configuration, and documentation surface.
+- Stopped publishing the archived pre-CLI manual in the npm package; it remains
+  repository history and cannot be mistaken for an active plugin contract.
+
 ## [0.6.0] — 2026-07-17
 
 ### Changed
@@ -21,9 +99,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
-- Removed the Gemini CLI adapter, `--gemini` installer surface, extension and
-  conformance packaging, pricing entries, `gemini-collab`, and all active Ultra
-  prompts and documentation that offered Gemini as an advisor or runtime.
+- Removed the retired fourth-runtime adapter, installer surface, extension and
+  conformance packaging, pricing entries, collaboration companion, and all
+  active Ultra prompts and documentation that offered it as an advisor.
 
 ### Fixed
 
@@ -189,8 +267,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - D49 tech-debt sweep: stale Phase comments (`"scheduled for Phase 1"`,
   `"not implemented in Phase 3.1"`) replaced with accurate `unknown verb`
-  messages; `docs/ROADMAP.md` status table synchronized; `.gitignore`
-  excludes `.rtk/` local filter cache.
+  messages; `docs/ROADMAP.md` status table synchronized.
 
 ### Tests
 
@@ -201,13 +278,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Phase 6 — monitoring + live code graph** (D44): RTK soft-dependency hook
-  (`adapters/_shared/rtk-detect.cjs`) with `--skip-rtk` flag and install hint;
-  token / cost telemetry with per-runtime pricing table, `telemetry` table +
+- **Phase 6 — monitoring + live code graph** (D44): token / cost telemetry
+  with per-runtime pricing table, `telemetry` table +
   daily `.ultra/telemetry/YYYY-MM-DD.jsonl`; `ultra-tools status --cost`
   panel with by-runtime / by-task / by-session aggregation; chokidar-based
-  code-graph watcher with debounce / awaitWriteFinish / batch thresholds,
-  opt-in via `--with-graph-watcher`.
+  then-experimental incremental graph watcher with debounce and batch thresholds.
 - **Phase 5 — execution resilience** (D43): `recovery.cjs` boot-time orphan
   scan using live PID probe; `circuit_breaker` table with `recordTaskFailure`
   counter and `resetCircuitBreaker` escape hatch; spec-change staleness
@@ -257,7 +332,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   skill manifest, CLI protocol + mapping table; 5 spec validators.
 - **Phase 0 — skeleton**: multi-runtime installer scaffolding.
 
-[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.5.3...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.8.1...HEAD
+[0.8.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.8.0...v0.8.1
+[0.8.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.5.3...v0.6.0
 [0.5.3]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.5.2...v0.5.3
 [0.5.2]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.5.0...v0.5.1

package/README.md

@@ -8,7 +8,7 @@ authoritative `.ultra/state.db`.
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-0.6.0-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.8.1-blue)](./CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#verification)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-informational)](./package.json)
@@ -23,18 +23,26 @@ authoritative `.ultra/state.db`.
 
 - **Builds host-native plugins from one allowlist.** Claude Code, OpenCode, and
   Codex receive their own command/skill, agent, hook, and MCP representation.
-  Install and uninstall are symmetric on every supported host.
+  Install and uninstall are symmetric on every supported host; `ubp --doctor`
+  verifies the installed asset hashes and host entry points without mutation.
 - **Shares state across runtimes.** `.ultra/state.db` (SQLite + WAL) is the
-  authoritative source for tasks, sessions, events, and telemetry. `tasks.json`
-  and context markdown are generated projections, not handwritten.
+  authoritative source for changes, tasks, sessions, events, incidents,
+  projection jobs, and telemetry. `tasks.json` and context markdown are
+  generated projections, not handwritten.
 - **Keeps memory ownership explicit.** Ultra Builder Pro does not collect
   prompts, transcripts, observations, summaries, or cross-session memory.
   Install cloud-mem/claude-mem separately if persistent memory is wanted.
 - **Runs real PRDs end-to-end.** `task.parse_prd` → `lib/topo.cjs` waves →
   `.ultra/execution-plan.json` → parallel worktree sessions → auto-merge back.
-- **Observes without overhead.** Per-task / per-session / per-runtime token
-  and cost telemetry; live code-review-graph watcher on file save;
-  subscribe-events cursor for real-time dashboards.
+- **Keeps daily work convergent.** `/ultra-change` creates a bounded delta and
+  context manifest; `/ultra-deliver` requires docs/test/review evidence and
+  baseline reconciliation before archive. `/ultra-doctor` reports incidents,
+  projection lag, orphan sessions, and backup-first mechanical recovery.
+  Incident changes additionally require a five-section `diagnosis.md` covering
+  reproduction, hypotheses, root cause, regression test, and recovery.
+- **Keeps external context external.** Memory and code-graph providers retain
+  their own content; Ultra stores only provider/project/revision/status metadata
+  references in a compiled change context.
 
 ## Quickstart
 
@@ -52,12 +60,16 @@ npx ultra-builder-pro-cli --claude --global
 
 # Uninstall (symmetric)
 npx ultra-builder-pro-cli --all --local --uninstall
+
+# Read-only installation provenance and drift diagnosis
+npx ultra-builder-pro-cli --all --local --doctor
+npx ultra-builder-pro-cli --all --local --doctor --json
 ```
 
 After install, start a new host session/task and point it at the project.
 Claude Code and OpenCode expose native command forms. Codex exposes the same workflows as namespaced plugin
 skills such as `$ultra-builder-pro:ultra-init`, `$ultra-builder-pro:ultra-plan`,
-and `$ultra-builder-pro:ultra-dev`; `command-map.json` records the nine legacy
+and `$ultra-builder-pro:ultra-dev`; `command-map.json` records the eleven legacy
 command mappings (`ultra-review` remains a directly invocable skill).
 See [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.md)
 for per-runtime capabilities.
@@ -68,16 +80,17 @@ for per-runtime capabilities.
 |-------|---------|----------------|
 | **skill** (`skills/ultra-*/`) | Knowledge — prompts, workflows, prose | Runtime's native skill/prompt loader picks them up after install |
 | **MCP** (`mcp-server/`) | Authoritative state — reads/writes `.ultra/state.db` via stdio JSON-RPC | Primary path for task / session / event / plan operations |
-| **CLI** (`ultra-tools`, `bin/*`) | Shell fallback for CI and non-MCP contexts | `ultra-tools task init-project`, `ubp-orchestrator run`, `ultra-tools status --cost` |
+| **CLI** (`ultra-tools`, `bin/*`) | Selected initialization, recovery, diagnostics, and orchestration surfaces | `ultra-tools task init-project`, `ultra-tools system doctor`, `ubp-orchestrator run` |
 
-The three layers share one `.ultra/state.db`. See
+The layers share one `.ultra/state.db`, but the CLI is not a mirror of every MCP
+tool: continuous change mutations are MCP-only and fail closed. See
 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the full contract and
-[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 21 live contracts.
+[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 29 live contracts.
 Review, impact discovery, skill resolution, and user interaction stay on each
 Host's native surfaces; the generated Codex capability map documents those
 replacements without advertising non-existent MCP tools.
 
-The package boundary is deliberate: ten public Ultra workflow skills, four
+The package boundary is deliberate: twelve public Ultra workflow skills, four
 internal review-rule skills, and host-specific collaboration companions. Browser,
 deployment, skill-discovery, and framework guidance belong to their original plugins.
 
@@ -99,30 +112,33 @@ Full details in [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.m
 ## Typical workflow
 
 ```bash
-# 1. Initialize a project (writes .ultra/ skeleton; state.db stays lazy)
+# 1. Initialize a project (writes .ultra/ skeleton and initializes state.db)
 ultra-tools task init-project --name myapp
 
 # 2. Turn a PRD into a task graph + execution plan (human-gate via dry-run)
 #    (invoked by /ultra-plan skill or via MCP task.parse_prd + plan.export)
 
 # 3. Run the plan — parallel sessions, auto-merge back to main on success
-ubp-orchestrator run --with-graph-watcher
+ubp-orchestrator run
 
-# 4. Monitor cost and progress
+# 4. Monitor cost, progress, and runtime health
 ultra-tools status
 ultra-tools status --cost --since 24h
 ultra-tools session list --json
+ultra-tools system doctor
 ```
 
 Or let the skills drive it. In Codex, invoke
 `$ultra-builder-pro:ultra-plan` → `$ultra-builder-pro:ultra-dev` →
-`$ultra-builder-pro:ultra-status`; other runtimes retain their native command form.
+`$ultra-builder-pro:ultra-status`; after the baseline is delivered, daily work
+starts with `$ultra-builder-pro:ultra-change`. Other runtimes retain their
+native command form.
 
 ## CLI surface
 
 | Binary | Purpose |
 |--------|---------|
-| `ultra-builder-pro-cli` / `ubp` | Installer — `--claude / --opencode / --codex / --all`, `--local / --global`, `--uninstall`, `--skip-rtk` |
+| `ultra-builder-pro-cli` / `ubp` | Installer — `--claude / --opencode / --codex / --all`, `--local / --global`, `--uninstall`; read-only install checks via `--doctor [--json]` |
 | `ubp-orchestrator` | Session dispatch daemon — `run`, `start`, `stop`, `status` |
 | `ultra-tools` | State-layer CLI — `task`, `session`, `status`, `db`, `migrate`; explicit `legacy-memory` archive/prune migration |
 | `ubp-handbook` | Preview/apply the managed Ultra contract in `CLAUDE.md` / `AGENTS.md`, with backup |
@@ -156,6 +172,11 @@ Individual suites: `test:state`, `test:orch`, `test:spec`, `test:rest`.
   or `./.opencode` etc.; `--global` writes to the user-level dir). The
   install log prints the exact target path. Restart Claude Code/OpenCode or
   start a new Codex task after changing an installed plugin.
+- **Installed hook/MCP path is missing or stale**: run
+  `npx ultra-builder-pro-cli --<runtime> --local --doctor` first. It compares
+  the recorded install provenance with current asset hashes and validates the
+  host-specific hook, MCP, plugin, and runtime-manifest entry points. Reinstall
+  only after preserving the degraded report as evidence.
 - **Legacy Ultra memory data remains on disk**: inspect first with
   `ultra-tools legacy-memory inspect`, archive with
   `ultra-tools legacy-memory archive`, then prune only with the explicit
@@ -169,7 +190,7 @@ Individual suites: `test:state`, `test:orch`, `test:spec`, `test:rest`.
 
 | Doc | What's in it |
 |-----|--------------|
-| [`docs/PLAN.zh-CN.md`](./docs/PLAN.zh-CN.md) | Authoritative 12-phase execution plan (zh-CN) — decisions, risks, timeline |
+| [`docs/PLAN.zh-CN.md`](./docs/PLAN.zh-CN.md) | Historical 12-phase plan and decision log with a current-boundary overlay |
 | [`docs/ROADMAP.md`](./docs/ROADMAP.md) | One-page English roadmap + phase status |
 | [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | Single-page system architecture |
 | [`docs/AGENT-CONTEXT.md`](./docs/AGENT-CONTEXT.md) | Canonical runtime context contract |
@@ -177,7 +198,6 @@ Individual suites: `test:state`, `test:orch`, `test:spec`, `test:rest`.
 | [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.md) | Per-runtime capability matrix |
 | [`docs/STATE-DB-ACCESS-POLICY.md`](./docs/STATE-DB-ACCESS-POLICY.md) | Multi-process write contract |
 | [`docs/COMMIT-HASH-BACKFILL.md`](./docs/COMMIT-HASH-BACKFILL.md) | Two-commit task-completion flow |
-| [`docs/LEGACY-HERMES.md`](./docs/LEGACY-HERMES.md) | Archived pre-CLI "Hermes 6.6" documentation |
 | [`CHANGELOG.md`](./CHANGELOG.md) | v0.1 → current release notes |
 
 ## License

package/adapters/_shared/handbook.cjs

@@ -14,21 +14,21 @@ const HOSTS = Object.freeze({
   claude: Object.freeze({
     name: 'Claude Code',
     handbook: ['.claude', 'CLAUDE.md'],
-    invocation: '`/ultra-init`, `/ultra-research`, `/ultra-plan`, `/ultra-dev`, `/ultra-test`, `/ultra-review`, and `/ultra-deliver`; diagnostics use `/ultra-status` and `/ultra-think`',
+    invocation: '`/ultra-init`, `/ultra-research`, `/ultra-plan`, `/ultra-change`, `/ultra-dev`, `/ultra-test`, `/ultra-review`, and `/ultra-deliver`; diagnostics use `/ultra-status`, `/ultra-think`, and `/ultra-doctor`',
     collaboration: '`/codex-collab` is an explicitly requested read-only advisor',
     coordination: 'Claude Code task UI is host coordination; it does not replace Ultra task state',
   }),
   codex: Object.freeze({
     name: 'Codex',
     handbook: ['.codex', 'AGENTS.md'],
-    invocation: '`$ultra-builder-pro:ultra-init`, `$ultra-builder-pro:ultra-research`, `$ultra-builder-pro:ultra-plan`, `$ultra-builder-pro:ultra-dev`, `$ultra-builder-pro:ultra-test`, `$ultra-builder-pro:ultra-review`, and `$ultra-builder-pro:ultra-deliver`; diagnostics use `$ultra-builder-pro:ultra-status` and `$ultra-builder-pro:ultra-think`',
+    invocation: '`$ultra-builder-pro:ultra-init`, `$ultra-builder-pro:ultra-research`, `$ultra-builder-pro:ultra-plan`, `$ultra-builder-pro:ultra-change`, `$ultra-builder-pro:ultra-dev`, `$ultra-builder-pro:ultra-test`, `$ultra-builder-pro:ultra-review`, and `$ultra-builder-pro:ultra-deliver`; diagnostics use `$ultra-builder-pro:ultra-status`, `$ultra-builder-pro:ultra-think`, and `$ultra-builder-pro:ultra-doctor`',
     collaboration: '`$ultra-builder-pro:cc-collab` is an explicitly requested read-only advisor',
     coordination: 'The Codex plan is turn-facing coordination; it does not replace Ultra task state',
   }),
   opencode: Object.freeze({
     name: 'OpenCode',
     handbook: ['.config', 'opencode', 'AGENTS.md'],
-    invocation: '`/ultra-init`, `/ultra-research`, `/ultra-plan`, `/ultra-dev`, `/ultra-test`, `/ultra-review`, and `/ultra-deliver`; diagnostics use `/ultra-status` and `/ultra-think`',
+    invocation: '`/ultra-init`, `/ultra-research`, `/ultra-plan`, `/ultra-change`, `/ultra-dev`, `/ultra-test`, `/ultra-review`, and `/ultra-deliver`; diagnostics use `/ultra-status`, `/ultra-think`, and `/ultra-doctor`',
     collaboration: '`/cc-collab` and `/codex-collab` are explicitly requested read-only advisors',
     coordination: 'OpenCode session coordination does not replace Ultra task state',
   }),
@@ -52,11 +52,12 @@ function renderHandbook(runtime) {
     `- Workflow entry points: ${value.invocation}.`,
     `- Collaboration boundary: ${value.collaboration}. The current host remains primary and owns final verification.`,
     `- Coordination boundary: ${value.coordination}.`,
-    '- Authority: `.ultra/state.db` is the only durable Ultra authority for tasks, sessions, events, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
-    '- Memory boundary: Ultra Builder Pro does not capture prompts, transcripts, observations, summaries, or cross-session memory. Persistent memory belongs to a separately installed provider such as cloud-mem or claude-mem.',
-    '- Hook boundary: Ultra hooks are workflow-only lifecycle adapters and are no-ops unless `.ultra/workflow-state.json` describes an active non-terminal workflow. Generic command blocking and post-edit policy stay in user or repository governance.',
+    '- Authority: `.ultra/state.db` is the only durable Ultra authority for changes, tasks, sessions, events, incidents, projection state, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
+    '- Memory and graph boundary: Ultra Builder Pro does not capture prompts, transcripts, observations, summaries, cross-session memory, or code-graph content. Separately installed providers own that data; Ultra may store only their metadata references in a change context manifest.',
+    '- Hook boundary: Ultra hooks observe workflow/change lifecycle only. Health/context may run when `.ultra/state.db` exists; projection protection is always authoritative, while edit/compact/stop/subagent enforcement remains active-workflow scoped. Generic command blocking and post-edit policy stay in user or repository governance.',
+    '- Installation boundary: `ubp --doctor` is the read-only authority for installed asset provenance, content hashes, and host entry-point wiring; `system.doctor` remains scoped to project state and workflow recovery.',
     '- Agent boundary: the bundled review and debugging agents are bounded workers. They use the current checkout and parent-supplied context, do not own private persistent state, and never replace the primary agent.',
-    '- Package boundary: only the ten Ultra workflows, four internal review-rule skills, and host-specific collaboration companions belong to this plugin. General browser, deployment, discovery, and framework skills must be installed from their owners.',
+    '- Package boundary: only the twelve Ultra workflows, four internal review-rule skills, and host-specific collaboration companions belong to this plugin. General browser, deployment, discovery, and framework skills must be installed from their owners.',
     END_MARKER,
   ].join('\n');
 }

package/adapters/_shared/provenance.cjs

@@ -0,0 +1,286 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { listRelative, writeAtomic } = require('./file-ops.cjs');
+
+const SCHEMA_VERSION = 1;
+const DIGEST_ALGORITHM = 'sha256';
+
+function issue(code, details = {}) {
+  return { code, ...details };
+}
+
+function safeRelative(value) {
+  if (typeof value !== 'string' || !value.trim() || path.isAbsolute(value)) {
+    throw new Error(`provenance asset path must be relative: ${String(value)}`);
+  }
+  const normalized = path.normalize(value);
+  if (normalized === '..' || normalized.startsWith(`..${path.sep}`)) {
+    throw new Error(`provenance asset path escapes its root: ${value}`);
+  }
+  return normalized;
+}
+
+function normalizeRoots(roots) {
+  if (!roots || typeof roots !== 'object' || Array.isArray(roots)) {
+    throw new Error('provenance roots must be an object');
+  }
+  const normalized = {};
+  for (const [name, root] of Object.entries(roots)) {
+    if (!/^[a-z][a-z0-9_-]*$/.test(name) || typeof root !== 'string' || !root.trim()) {
+      throw new Error(`invalid provenance root: ${name}`);
+    }
+    normalized[name] = path.resolve(root);
+  }
+  if (Object.keys(normalized).length === 0) throw new Error('at least one provenance root is required');
+  return normalized;
+}
+
+function normalizeRef(ref, roots) {
+  if (!ref || typeof ref !== 'object' || Array.isArray(ref) || !roots[ref.root]) {
+    throw new Error(`invalid provenance asset root: ${ref && ref.root}`);
+  }
+  return { root: ref.root, path: safeRelative(ref.path) };
+}
+
+function resolveRef(roots, ref) {
+  const normalized = normalizeRef(ref, roots);
+  const root = roots[normalized.root];
+  const target = path.resolve(root, normalized.path);
+  if (target !== root && !target.startsWith(`${root}${path.sep}`)) {
+    throw new Error(`provenance asset escapes root ${normalized.root}: ${normalized.path}`);
+  }
+  return { ...normalized, target };
+}
+
+function hashFile(file) {
+  return crypto.createHash(DIGEST_ALGORITHM).update(fs.readFileSync(file)).digest('hex');
+}
+
+function normalizeAssetRefs(assets, roots) {
+  if (!Array.isArray(assets) || assets.length === 0) {
+    throw new Error('at least one provenance asset is required');
+  }
+  const unique = new Map();
+  for (const input of assets) {
+    const ref = normalizeRef(input, roots);
+    unique.set(`${ref.root}\0${ref.path}`, ref);
+  }
+  return [...unique.values()].sort((a, b) => (
+    a.root.localeCompare(b.root) || a.path.localeCompare(b.path)
+  ));
+}
+
+function digestEntries(entries) {
+  const hash = crypto.createHash(DIGEST_ALGORITHM);
+  for (const entry of entries) {
+    hash.update(entry.root);
+    hash.update('\0');
+    hash.update(entry.path);
+    hash.update('\0');
+    hash.update(entry.sha256);
+    hash.update('\0');
+    hash.update(String(entry.size_bytes));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+function sourceCommit(repoRoot) {
+  if (!fs.existsSync(path.join(repoRoot, '.git'))) return null;
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], {
+    cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  const value = result.status === 0 ? result.stdout.trim() : '';
+  return /^[0-9a-f]{40,64}$/i.test(value) ? value : null;
+}
+
+function repositoryUrl(pkg) {
+  if (typeof pkg.repository === 'string') return pkg.repository;
+  if (pkg.repository && typeof pkg.repository.url === 'string') return pkg.repository.url;
+  return typeof pkg.homepage === 'string' ? pkg.homepage : null;
+}
+
+function packageSource(repoRoot) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+  return {
+    packageInfo: { name: pkg.name, version: pkg.version },
+    repository: repositoryUrl(pkg),
+    sourceCommit: sourceCommit(repoRoot),
+  };
+}
+
+function assetRefsForTree(rootName, root, { exclude = [] } = {}) {
+  const excluded = new Set(exclude.map((entry) => path.normalize(entry)));
+  return listRelative(root)
+    .filter((entry) => !excluded.has(path.normalize(entry)))
+    .map((entry) => ({ root: rootName, path: entry }));
+}
+
+function writeProvenance({
+  file, adapter, packageInfo, repository, sourceCommit: commit = null,
+  roots: inputRoots, assets: inputAssets, contracts: inputContracts = {},
+}) {
+  if (!file || !adapter || !packageInfo?.name || !packageInfo?.version || !repository) {
+    throw new Error('provenance file, adapter, package, version, and repository are required');
+  }
+  const roots = normalizeRoots(inputRoots);
+  const refs = normalizeAssetRefs(inputAssets, roots);
+  const assets = refs.map((ref) => {
+    const { target } = resolveRef(roots, ref);
+    const stat = fs.statSync(target);
+    if (!stat.isFile()) throw new Error(`provenance asset is not a file: ${target}`);
+    return { ...ref, size_bytes: stat.size, sha256: hashFile(target) };
+  });
+  const contracts = {};
+  for (const [name, ref] of Object.entries(inputContracts || {})) {
+    if (!/^[a-z][a-z0-9_-]*$/.test(name)) throw new Error(`invalid provenance contract: ${name}`);
+    contracts[name] = normalizeRef(ref, roots);
+  }
+  const manifest = {
+    schema_version: SCHEMA_VERSION,
+    adapter,
+    package: { name: packageInfo.name, version: packageInfo.version },
+    source: { repository, commit: commit || null },
+    installed_at: new Date().toISOString(),
+    roots,
+    content: { algorithm: DIGEST_ALGORITHM, digest: digestEntries(assets) },
+    assets,
+    contracts,
+  };
+  writeAtomic(path.resolve(file), `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+function invalidReport(file, status, problem, adapter = null) {
+  return {
+    adapter,
+    status,
+    manifest_path: path.resolve(file),
+    package: null,
+    source: null,
+    content_digest: null,
+    checks: {
+      manifest: { status: 'fail' },
+      assets: { status: 'unknown', checked: 0, failed: 0 },
+      contracts: { status: 'unknown', checked: 0, failed: 0 },
+    },
+    issues: [problem],
+  };
+}
+
+function inspectProvenance({ file, expectedAdapter = null, expectedPackageVersion = null }) {
+  const manifestPath = path.resolve(file);
+  if (!fs.existsSync(manifestPath)) {
+    return invalidReport(
+      manifestPath, 'missing', issue('PROVENANCE_MISSING', { path: manifestPath }), expectedAdapter,
+    );
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) throw new Error('manifest must be an object');
+    if (manifest.schema_version !== SCHEMA_VERSION) throw new Error(`unsupported schema ${manifest.schema_version}`);
+    if (!manifest.package?.name || !manifest.package?.version || !manifest.source?.repository) {
+      throw new Error('package and source metadata required');
+    }
+  } catch (error) {
+    return invalidReport(
+      manifestPath, 'degraded', issue('PROVENANCE_INVALID', { message: error.message }), expectedAdapter,
+    );
+  }
+
+  const issues = [];
+  let roots;
+  try {
+    roots = normalizeRoots(manifest.roots);
+  } catch (error) {
+    return invalidReport(
+      manifestPath, 'degraded', issue('PROVENANCE_INVALID', { message: error.message }), expectedAdapter,
+    );
+  }
+  if (expectedAdapter && manifest.adapter !== expectedAdapter) {
+    issues.push(issue('ADAPTER_MISMATCH', { expected: expectedAdapter, actual: manifest.adapter }));
+  }
+  if (expectedPackageVersion && manifest.package.version !== expectedPackageVersion) {
+    issues.push(issue('PACKAGE_VERSION_MISMATCH', {
+      expected: expectedPackageVersion, actual: manifest.package.version,
+    }));
+  }
+
+  const assets = Array.isArray(manifest.assets) ? manifest.assets : [];
+  if (assets.length === 0) issues.push(issue('PROVENANCE_INVALID', { message: 'assets required' }));
+  let assetFailures = 0;
+  for (const asset of assets) {
+    try {
+      const { target, root, path: assetPath } = resolveRef(roots, asset);
+      if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+        assetFailures += 1;
+        issues.push(issue('ASSET_MISSING', { root, path: assetPath }));
+        continue;
+      }
+      const actual = hashFile(target);
+      if (actual !== asset.sha256) {
+        assetFailures += 1;
+        issues.push(issue('ASSET_HASH_MISMATCH', {
+          root, path: assetPath, expected: asset.sha256, actual,
+        }));
+      }
+    } catch (error) {
+      assetFailures += 1;
+      issues.push(issue('ASSET_INVALID', { message: error.message }));
+    }
+  }
+  if (manifest.content?.algorithm !== DIGEST_ALGORITHM
+    || manifest.content?.digest !== digestEntries(assets)) {
+    issues.push(issue('MANIFEST_DIGEST_MISMATCH'));
+  }
+
+  const contracts = manifest.contracts && typeof manifest.contracts === 'object'
+    && !Array.isArray(manifest.contracts) ? manifest.contracts : {};
+  let contractFailures = 0;
+  for (const [name, ref] of Object.entries(contracts)) {
+    try {
+      const { target, root, path: contractPath } = resolveRef(roots, ref);
+      if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+        contractFailures += 1;
+        issues.push(issue('CONTRACT_TARGET_MISSING', { contract: name, root, path: contractPath }));
+      }
+    } catch (error) {
+      contractFailures += 1;
+      issues.push(issue('CONTRACT_INVALID', { contract: name, message: error.message }));
+    }
+  }
+
+  return {
+    adapter: manifest.adapter,
+    status: issues.length === 0 ? 'healthy' : 'degraded',
+    manifest_path: manifestPath,
+    package: manifest.package,
+    source: manifest.source,
+    content_digest: manifest.content?.digest || null,
+    checks: {
+      manifest: { status: 'pass' },
+      assets: { status: assetFailures === 0 ? 'pass' : 'fail', checked: assets.length, failed: assetFailures },
+      contracts: {
+        status: contractFailures === 0 ? 'pass' : 'fail',
+        checked: Object.keys(contracts).length,
+        failed: contractFailures,
+      },
+    },
+    issues,
+  };
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  DIGEST_ALGORITHM,
+  assetRefsForTree,
+  inspectProvenance,
+  packageSource,
+  writeProvenance,
+};

package/adapters/_shared/runtime-assets.cjs

@@ -18,6 +18,8 @@ const CORE_PUBLIC_SKILLS = Object.freeze([
   'ultra-deliver',
   'ultra-status',
   'ultra-think',
+  'ultra-change',
+  'ultra-doctor',
 ]);
 
 const INTERNAL_AGENT_SKILLS = Object.freeze([

package/adapters/_shared/tests/handbook.test.cjs

@@ -25,7 +25,10 @@ test('renders one common contract with host-native invocation syntax', () => {
   assert.match(opencode, /\/ultra-plan/);
   for (const rendered of [claude, codex, opencode]) {
     assert.match(rendered, /\.ultra\/state\.db/);
-    assert.match(rendered, /claude-mem|cloud-mem/);
+    assert.match(rendered, /Separately installed providers/);
+    assert.match(rendered, /ultra-change/);
+    assert.match(rendered, /ultra-doctor/);
+    assert.match(rendered, /metadata references/);
     assert.doesNotMatch(rendered, /\.ultra\/memory|memory\.retain|memory\.recall/);
     assert.match(rendered, new RegExp(BEGIN_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
     assert.match(rendered, new RegExp(END_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));