ultra-builder-pro-cli 0.17.0 → 0.18.0

package/adapters/_shared/provenance.cjs

@@ -90,15 +90,76 @@ function digestEntries(entries) {
   return hash.digest('hex');
 }
 
+function runGit(repoRoot, args, encoding = 'utf8') {
+  const result = spawnSync('git', args, {
+    cwd: repoRoot,
+    encoding,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return result.status === 0 ? result.stdout : null;
+}
+
 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() : '';
+  const result = runGit(repoRoot, ['rev-parse', 'HEAD']);
+  const value = typeof result === 'string' ? result.trim() : '';
   return /^[0-9a-f]{40,64}$/i.test(value) ? value : null;
 }
 
+function sourceWorktreeState(repoRoot, commit) {
+  if (!fs.existsSync(path.join(repoRoot, '.git'))) {
+    return { sourceDirty: null, sourceWorktreeDigest: null };
+  }
+  const status = runGit(
+    repoRoot, ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--', '.'], null,
+  );
+  if (!Buffer.isBuffer(status)) {
+    return { sourceDirty: null, sourceWorktreeDigest: null };
+  }
+  const trackedDiff = commit
+    ? runGit(repoRoot, ['diff', '--binary', 'HEAD', '--', '.'], null)
+    : runGit(repoRoot, ['diff', '--binary', '--cached', '--', '.'], null);
+  const unstagedDiff = commit
+    ? Buffer.alloc(0)
+    : runGit(repoRoot, ['diff', '--binary', '--', '.'], null);
+  const untrackedOutput = runGit(
+    repoRoot, ['ls-files', '--others', '--exclude-standard', '-z', '--', '.'],
+  );
+  if (!Buffer.isBuffer(trackedDiff) || !Buffer.isBuffer(unstagedDiff)
+    || typeof untrackedOutput !== 'string') {
+    return { sourceDirty: null, sourceWorktreeDigest: null };
+  }
+
+  const hash = crypto.createHash(DIGEST_ALGORITHM);
+  hash.update('ultra-source-worktree-v1\0');
+  hash.update(commit || 'unborn');
+  hash.update('\0');
+  hash.update(status);
+  hash.update('\0');
+  hash.update(trackedDiff);
+  hash.update('\0');
+  hash.update(unstagedDiff);
+  hash.update('\0');
+  const untrackedPaths = untrackedOutput.split('\0').filter(Boolean).sort();
+  for (const relative of untrackedPaths) {
+    const target = path.resolve(repoRoot, relative);
+    if (target !== repoRoot && !target.startsWith(`${path.resolve(repoRoot)}${path.sep}`)) {
+      return { sourceDirty: null, sourceWorktreeDigest: null };
+    }
+    const stat = fs.lstatSync(target);
+    hash.update(relative);
+    hash.update('\0');
+    if (stat.isSymbolicLink()) hash.update(fs.readlinkSync(target));
+    else if (stat.isFile()) hash.update(fs.readFileSync(target));
+    hash.update('\0');
+  }
+  return {
+    sourceDirty: status.length > 0,
+    sourceWorktreeDigest: hash.digest('hex'),
+  };
+}
+
 function repositoryUrl(pkg) {
   if (typeof pkg.repository === 'string') return pkg.repository;
   if (pkg.repository && typeof pkg.repository.url === 'string') return pkg.repository.url;
@@ -107,10 +168,12 @@ function repositoryUrl(pkg) {
 
 function packageSource(repoRoot) {
   const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+  const commit = sourceCommit(repoRoot);
   return {
     packageInfo: { name: pkg.name, version: pkg.version },
     repository: repositoryUrl(pkg),
-    sourceCommit: sourceCommit(repoRoot),
+    sourceCommit: commit,
+    ...sourceWorktreeState(repoRoot, commit),
   };
 }
 
@@ -123,11 +186,18 @@ function assetRefsForTree(rootName, root, { exclude = [] } = {}) {
 
 function writeProvenance({
   file, adapter, packageInfo, repository, sourceCommit: commit = null,
+  sourceDirty: dirty = null, sourceWorktreeDigest: worktreeDigest = 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');
   }
+  if (dirty !== null && typeof dirty !== 'boolean') {
+    throw new Error('provenance source dirty state must be a boolean or null');
+  }
+  if (worktreeDigest !== null && !/^[0-9a-f]{64}$/i.test(worktreeDigest)) {
+    throw new Error('provenance source worktree digest must be a SHA-256 digest or null');
+  }
   const roots = normalizeRoots(inputRoots);
   const refs = normalizeAssetRefs(inputAssets, roots);
   const assets = refs.map((ref) => {
@@ -145,7 +215,12 @@ function writeProvenance({
     schema_version: SCHEMA_VERSION,
     adapter,
     package: { name: packageInfo.name, version: packageInfo.version },
-    source: { repository, commit: commit || null },
+    source: {
+      repository,
+      commit: commit || null,
+      dirty,
+      worktree_digest: worktreeDigest,
+    },
     installed_at: new Date().toISOString(),
     roots,
     content: { algorithm: DIGEST_ALGORITHM, digest: digestEntries(assets) },
@@ -188,6 +263,15 @@ function inspectProvenance({ file, expectedAdapter = null, expectedPackageVersio
     if (!manifest.package?.name || !manifest.package?.version || !manifest.source?.repository) {
       throw new Error('package and source metadata required');
     }
+    if (manifest.source.dirty !== undefined && manifest.source.dirty !== null
+      && typeof manifest.source.dirty !== 'boolean') {
+      throw new Error('source dirty state must be a boolean or null');
+    }
+    if (manifest.source.worktree_digest !== undefined
+      && manifest.source.worktree_digest !== null
+      && !/^[0-9a-f]{64}$/i.test(manifest.source.worktree_digest)) {
+      throw new Error('source worktree digest must be a SHA-256 digest or null');
+    }
   } catch (error) {
     return invalidReport(
       manifestPath, 'degraded', issue('PROVENANCE_INVALID', { message: error.message }), expectedAdapter,

package/adapters/_shared/runtime-assets.cjs

@@ -51,16 +51,6 @@ const MCP_DEPENDENT_SKILLS = Object.freeze([
   'ultra-doctor',
 ]);
 
-const RETIRED_SKILLS = Object.freeze([
-  'agent-browser',
-  'find-skills',
-  'recall',
-  'use-railway',
-  'vercel-composition-patterns',
-  'vercel-react-best-practices',
-  'vercel-react-native-skills',
-]);
-
 const WORKFLOW_HOOK_FILES = Object.freeze([
   'active_task_context.py',
   'context_spine.py',
@@ -98,7 +88,6 @@ module.exports = {
   SUPPORTED_RUNTIMES,
   COLLAB_SKILLS_BY_RUNTIME,
   MCP_DEPENDENT_SKILLS,
-  RETIRED_SKILLS,
   WORKFLOW_HOOK_FILES,
   isSupportedRuntime,
   skillPolicy,

package/bin/handbook.js

@@ -7,17 +7,23 @@ const path = require('node:path');
 
 const {
   applyHandbook,
+  applyFullHandbook,
   mergeHandbook,
+  previewFullHandbook,
   resolveHandbookFile,
 } = require('../adapters/_shared/handbook.cjs');
 
 function usage() {
   return [
     'Usage:',
-    '  ubp-handbook preview --runtime <claude|codex|opencode|kimi> [--file <path>]',
+    '  ubp-handbook preview --runtime <claude|codex|opencode|kimi> [--file <path>] [--full]',
     '  ubp-handbook apply   --runtime <claude|codex|opencode|kimi> [--file <path>]',
+    '  ubp-handbook apply   --runtime <claude|codex|opencode|kimi> [--file <path>] --full --confirm <token>',
     '',
-    'The apply command creates a timestamped backup before changing an existing file.',
+    'Default mode merges only the Ultra runtime contract.',
+    'Full mode replaces legacy unmarked prompt content with the complete host-native handbook,',
+    'preserves other provider-managed marker blocks, and creates a timestamped backup.',
+    'A full preview prints the target content to stdout and its apply confirmation token to stderr.',
   ].join('\n');
 }
 
@@ -26,24 +32,71 @@ function parse(argv) {
   const action = args.shift();
   let runtime = null;
   let file = null;
+  let full = false;
+  let confirmation = null;
+  function valueFor(flag, index) {
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+    return value;
+  }
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--runtime') runtime = args[++i];
-    else if (args[i] === '--file') file = args[++i];
+    if (args[i] === '--runtime') {
+      runtime = valueFor('--runtime', i);
+      i += 1;
+    } else if (args[i] === '--file') {
+      file = valueFor('--file', i);
+      i += 1;
+    }
+    else if (args[i] === '--full') full = true;
+    else if (args[i] === '--confirm') {
+      confirmation = valueFor('--confirm', i);
+      i += 1;
+    }
     else throw new Error(`unknown argument: ${args[i]}`);
   }
   if (!['preview', 'apply'].includes(action) || !runtime) throw new Error(usage());
-  return { action, runtime, file };
+  if (!['claude', 'codex', 'opencode', 'kimi'].includes(runtime)) {
+    throw new Error(`unsupported handbook runtime: ${runtime}`);
+  }
+  if (action === 'apply' && full && !confirmation) {
+    throw new Error('full handbook apply requires --confirm <token> from a current full preview');
+  }
+  if (confirmation && (action !== 'apply' || !full)) {
+    throw new Error('--confirm is valid only with apply --full');
+  }
+  return {
+    action,
+    runtime,
+    file,
+    full,
+    confirmation,
+  };
 }
 
 function main() {
-  const { action, runtime, file } = parse(process.argv);
+  const {
+    action,
+    runtime,
+    file,
+    full,
+    confirmation,
+  } = parse(process.argv);
   const target = path.resolve(file || resolveHandbookFile(runtime, { homeDir: os.homedir() }));
   if (action === 'preview') {
     const existing = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
-    process.stdout.write(mergeHandbook(existing, runtime));
+    if (full) {
+      const preview = previewFullHandbook({ runtime, file: target });
+      process.stdout.write(preview.content);
+      process.stderr.write(`Full apply confirmation: ${preview.confirmation}\n`);
+    } else {
+      process.stdout.write(mergeHandbook(existing, runtime));
+    }
     return;
   }
-  process.stdout.write(JSON.stringify(applyHandbook({ runtime, file: target })) + '\n');
+  const result = full
+    ? applyFullHandbook({ runtime, file: target, confirmation })
+    : applyHandbook({ runtime, file: target });
+  process.stdout.write(JSON.stringify(result) + '\n');
 }
 
 try {

package/docs/AGENT-CONTEXT.md

@@ -193,18 +193,29 @@ Archive before prune; the confirmation token is intentionally required.
 
 ## 10. User handbook integration
 
-General engineering doctrine remains user-owned in `CLAUDE.md` or `AGENTS.md`.
-Ultra Builder Pro contributes one managed section only. Preview or apply it with:
+General engineering doctrine lives in the host's durable `CLAUDE.md` or `AGENTS.md`.
+Ultra Builder Pro supports two explicit operations. Default mode updates only the
+bounded runtime contract:
 
 ```bash
 ubp-handbook preview --runtime codex
 ubp-handbook apply --runtime codex
 ```
 
-Supported runtime names are `claude`, `codex`, `opencode`, and `kimi`. Apply creates a
-timestamped backup, replaces only the marked block, and can migrate the old
-Codex `## Ultra Builder Pro Runtime Contract` section without touching the next
-user section. Plugin adapters themselves do not silently overwrite handbooks.
+Full mode replaces legacy unmarked prompt content with one complete host-native
+engineering handbook:
+
+```bash
+ubp-handbook preview --runtime codex --full > /tmp/ubp-codex-handbook.md
+ubp-handbook apply --runtime codex --full \
+  --confirm "PASTE_64_CHARACTER_TOKEN_HERE"
+```
+
+Supported runtime names are `claude`, `codex`, `opencode`, and `kimi`. The full
+preview prints its content-bound confirmation token to stderr. Both apply modes
+create a timestamped backup. Full mode preserves supported marker-delimited blocks
+owned by other providers, follows handbook symlinks, and rejects missing or stale
+confirmation. Plugin adapters never overwrite handbooks implicitly.
 
 ## 11. Verification
 

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
@@ -370,11 +368,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 +411,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)
+- User handbook projection: [`USER-HANDBOOK-CONTRACT.md`](./USER-HANDBOOK-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/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,16 @@ 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
+bin/handbook.js             ← explicit bounded or full host-native 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
+├── USER-HANDBOOK-CONTRACT.md    bounded/full CLAUDE.md / AGENTS.md 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 +107,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

@@ -73,7 +73,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` |
@@ -95,12 +95,14 @@ cannot be established. On POSIX it intentionally uses `env node` because Kimi
 |---|---|---|---|---|
 | 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` |
+| Explicit managed-block sync | `ubp-handbook apply --runtime claude` | `ubp-handbook apply --runtime opencode` | `ubp-handbook apply --runtime codex` | `ubp-handbook apply --runtime kimi` |
+| Explicit complete-handbook convergence | `--full --confirm TOKEN` | `--full --confirm TOKEN` | `--full --confirm TOKEN` | `--full --confirm TOKEN` |
 | Backup before change | FULL | FULL | FULL | FULL |
 
 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.
+do not become one irreversible mutation. Full mode is a semantic host rendering,
+not a product-name or path substitution.
 
 ## 6. Install, update, and uninstall
 
@@ -113,9 +115,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 +151,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/handbook.test.cjs` verifies bounded and full host
+  rendering, external-provider block preservation, backup, migration, and idempotency.
 - `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,