ultra-builder-pro-cli 0.12.1 → 0.14.0

package/.ultra-template/docs/research/README.md

@@ -1,53 +1,30 @@
-# Research Reports
+# Research Evidence
 
-This directory contains research reports generated by `/ultra-research` step-file architecture.
+Store durable research evidence here only when it is too detailed for the baseline
+specification. Baseline decisions and accepted behavior remain in `.ultra/specs/`.
 
-## Structure
+## When to create a report
 
-Each round generates a report with quality metadata:
+Create a report for external facts, repository investigations, experiments, runtime
+observations, or decision evidence that must remain inspectable. Use a descriptive
+file name and include the observation date when freshness matters.
 
-| Steps | Round | Report File |
-|-------|-------|-------------|
-| 00-05 | R0: Product Discovery | `product-discovery-{date}.md` |
-| 10-11 | R1: User & Scenario | `user-scenario-{date}.md` |
-| 20-22 | R2: Feature Definition | `feature-definition-{date}.md` |
-| 30-32 | R3: Architecture Design | `architecture-design-{date}.md` |
-| 40-41 | R4: Quality & Deployment | `quality-deployment-{date}.md` |
+## Report contract
 
-## Report Format
+Record:
 
-Each report includes quality tracking in header:
+- scope and the decision the evidence informs;
+- observed facts with source references and dates;
+- verification commands or runtime evidence;
+- accepted decisions and their owner;
+- unresolved unknowns and whether they block the baseline;
+- links to the product or architecture sections updated from the evidence.
 
-```markdown
-# Round {N}: {Round Name}
+Keep inference distinct from observation. Link to external provider content instead of
+copying memory, code-graph payloads, or large source material into Ultra.
 
-> **Confidence**: 92%
-> **Steps completed**: {list}
-> **Completed**: {date}
+## Completion
 
-## Key Findings
-[3-5 bullet points]
-
-## Decisions Made
-[Choices and rationale]
-
-## Open Questions
-[What remains uncertain]
-```
-
-## Quality Gate
-
-- Each step uses [C] Continue user gate — user confirms before proceeding
-- Per-step SUCCESS METRICS and FAILURE MODES enforce output quality
-- Step 99 (Synthesis) validates field-level completeness of all spec files
-
-## Research Distillate
-
-After all steps complete, `step-99-synthesis` generates:
-- `.ultra/specs/research-distillate.md` — Token-efficient summary (<2000 tokens) for `/ultra-plan` consumption
-
-## Integration
-
-- Reports are referenced in `specs/` for technology decisions
-- Research distillate is the primary input for `/ultra-plan`
-- Quality summary displayed at end of `/ultra-research`
+Update the affected baseline specification, include the report in `baseline.record`
+evidence when material, and record unresolved work in the authoritative gap ledger.
+Do not create a condensed duplicate of the baseline.

package/.ultra-template/specs/discovery.md

@@ -36,6 +36,16 @@ Separate blocking unknowns from questions that are outside the accepted scope.
 |---|---|---|---|
 | | | | |
 
+## Baseline Gaps
+
+Reference the authoritative gap ids recorded in `.ultra/state.db`. Use one of
+`baseline_blocker`, `documentation_drift`, `known_defect`, `technical_debt`,
+`unknown`, or `future_change`.
+
+| Gap id | Category | Status | Evidence reference | Owner |
+|---|---|---|---|---|
+| | | | | |
+
 ## Current Behavior Notes
 
 For an existing project, describe only behavior confirmed from source, tests, runtime,

package/CHANGELOG.md

@@ -7,6 +7,98 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] — 2026-07-19
+
+### Added
+
+- Added one read-only JavaScript Context Spine reader and renderer for the
+  authoritative `.ultra/state.db`, plus a packaged breadcrumb CLI shared by
+  Claude Code, Codex, OpenCode, Kimi Code, and the MCP server.
+- Added cross-host regression coverage proving stale JSON projections and
+  context manifests cannot override the active database change or task.
+
+### Changed
+
+- Changed `task.parse_prd` and `task.expand` to validate and atomically persist
+  task objects derived by the active host model. Ultra MCP no longer starts a
+  second model client or requires an Anthropic, OpenAI, or other provider key.
+- Reduced Python lifecycle hooks and the generated OpenCode plugin to thin
+  adapters over the canonical breadcrumb reader. Checkpoint and resume data is
+  advisory recovery evidence rather than a second workflow authority.
+- Made collaboration and verification Skills host-neutral, kept the current
+  host responsible for delivery, and generated Codex metadata from the source
+  Skill instead of maintaining duplicated prompt bodies.
+
+### Fixed
+
+- Fixed authoritative-state and injected-prompt divergence caused by hooks
+  reading `.ultra/workflow-state.json` or context manifests after
+  `.ultra/state.db` had advanced.
+- Fixed stale or incomplete state routing: missing projects route to
+  `ultra-init`, prior schemas route to migration, and corrupt current schemas
+  route to `ultra-doctor` without fabricating active workflow context.
+- Fixed installed OpenCode context injection so it reads the bundled runtime
+  with the installer-selected Node executable and remains portable outside the
+  source checkout.
+- Fixed Codex collaboration invocation and generated metadata quoting while
+  preserving the bounded read-only advisor contract.
+
+### Removed
+
+- Removed the private LLM client, planner prompt builders, and the
+  `@anthropic-ai/sdk` and `openai` runtime dependencies.
+
+## [0.13.0] — 2026-07-18
+
+### Added
+
+- Added schema 12 repository snapshots, branch and dirty-worktree evidence,
+  classification metadata, and a categorized baseline gap ledger with explicit
+  blocker, ownership, acceptance, and resolution state.
+- Added safe `task.init_project` resume semantics, bounded monorepo scope
+  detection, projection-only import routing, explicit migrated-baseline
+  replacement, and backup-first recovery for old state databases.
+- Added explicit corrupt-state restore and rebaseline commands that quarantine
+  the original database, WAL, SHM, and task projection and restore every moved
+  artifact when recovery fails.
+- Added approved incident break-glass records and mandatory post-incident
+  baseline reconciliation gaps, plus durable archive-journal crash recovery.
+
+### Changed
+
+- Made `ultra-init` the single route for empty repositories, existing
+  codebases, healthy installations, incomplete adoptions, prior Ultra state,
+  and corrupt databases. Existing application and baseline files are preserved;
+  resume installs only missing current scaffold assets.
+- New ordinary changes now require a healthy ready baseline. Already-active
+  work remains executable with visible drift warnings, while convergence still
+  requires current approved authority.
+- Ready-baseline replacement now requires durable owner identity and rationale;
+  a bare `replace_ready` boolean is rejected and cannot erase provenance.
+- Reworked baseline templates and host-neutral Skills around
+  `Observed`/`Verified`/`Decided`/`Unknown` evidence, characterization results,
+  owner approval, and one deterministic next action.
+
+### Fixed
+
+- Prevented prior-version projects from being treated as approved after a
+  schema upgrade; compatibility baselines remain `migrated/adopting` until an
+  evidence-backed brownfield replacement is approved.
+- Made status and doctor report old or corrupt state as structured recovery
+  guidance, retain pre-migration backup paths on failure, and close failed
+  database handles safely.
+- Prevented maintenance CLI telemetry from opening corrupt authority before
+  evidence-preserving recovery checks, and made task creation enforce the same
+  baseline boundary as change creation.
+- Closed bulk-parse and task-expansion task-creation bypasses; persisted PRD
+  tasks now carry their active change id, and expanded children inherit the
+  parent task's authorized change ownership.
+- Rejected task writes against missing or terminal changes even when the
+  baseline is healthy, and enforced parent-child change ownership for generic
+  task creation and reassignment paths.
+- Fixed installed npm tarballs so direct `ultra-tools task init-project` calls
+  can locate the packaged scaffold outside a source checkout.
+
 ## [0.12.1] — 2026-07-18
 
 ### Fixed
@@ -490,7 +582,9 @@ 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.12.1...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.14.0...HEAD
+[0.14.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.13.0...v0.14.0
+[0.13.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.12.1...v0.13.0
 [0.12.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.10.0...v0.11.0

package/README.md

@@ -8,7 +8,7 @@ authoritative `.ultra/state.db`.
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-0.12.1-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.14.0-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)
@@ -17,8 +17,6 @@ authoritative `.ultra/state.db`.
 
 ---
 
-> *(30-second demo GIF placeholder — to be added before v1.0)*
-
 ## What it does
 
 - **Builds host-native plugins from one allowlist.** Claude Code, OpenCode,
@@ -33,7 +31,8 @@ authoritative `.ultra/state.db`.
 - **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 →
+- **Runs real PRDs end-to-end without a second model credential.** The current
+  host derives task objects; `task.parse_prd` validates them → `lib/topo.cjs` waves →
   `.ultra/execution-plan.json` → parallel worktree sessions → auto-merge back.
 - **Keeps daily work convergent.** `/ultra-change` creates a bounded delta and
   Context Manifest v2; the Context Spine assigns a role/gate, verifies required
@@ -44,9 +43,10 @@ authoritative `.ultra/state.db`.
   Incident changes additionally require a five-section `diagnosis.md` covering
   reproduction, hypotheses, root cause, regression test, and recovery.
 - **Adopts existing repositories without pretending they are new.** `ultra-init`
-  auto-detects greenfield versus brownfield work. Brownfield adoption records
-  current specifications, repository/runtime evidence, known-red verification,
-  unknowns, and explicit approval without rewriting application code.
+  classifies greenfield, brownfield, and monorepo scope. Brownfield adoption records
+  current specifications, repository/runtime evidence, worktree snapshot, known-red
+  verification, categorized gaps, unknowns, and explicit approval without rewriting
+  application code. v4.4 and v4.5 projection-only projects have backup-first imports.
 - **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.
@@ -89,10 +89,10 @@ for per-runtime capabilities.
 Start with `ultra-init` in both new and existing projects. An empty project opens
 a `draft` greenfield baseline. An existing codebase opens an `adopting`
 brownfield baseline; inspect current behavior, call `baseline.record`, then
-approve it through `baseline.converge` before normal planning or delivery. An
-urgent active fix may continue while adoption or context-size warnings are
-visible. `change.converge` requires approved adoption, while normal HEAD/spec drift
-from that change is declared and health-checked atomically by `change.archive`.
+approve it through `baseline.converge` before normal planning or delivery. Existing
+active work may continue while adoption drift is visible. A new incident requires an
+explicit break-glass approver and leaves a blocking reconciliation gap at archive;
+new ordinary work always requires a healthy ready baseline.
 
 ## Three-layer architecture
 
@@ -133,9 +133,13 @@ Full details in [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.m
 ## Typical workflow
 
 ```bash
-# 1. Initialize a new project or adopt an existing repository automatically
+# 1. Bootstrap project state (the ultra-init skill completes adoption and approval)
 ultra-tools task init-project --project-name myapp --mode auto
 
+# Projection-only projects from prior releases use one backup-first import:
+ultra-tools migrate --from=4.4 --to=4.5 --source-dir .
+ultra-tools migrate --from=4.5 --to=12.0 --source-dir .
+
 # 2. Record and converge the greenfield/brownfield baseline, then turn accepted
 #    behavior into a task graph (normally driven by ultra-init/research/plan)
 
@@ -208,14 +212,25 @@ Individual suites: `test:state`, `test:orch`, `test:spec`, `test:rest`.
   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.
+- **Projection tasks exist but state.db has no tasks**: run the exact v4.4 or v4.5
+  `ultra-tools migrate` command returned by MCP, verify the backup and imported counts,
+  then run `ultra-init` to replace the compatibility row with a reviewed brownfield
+  baseline.
+- **Old or corrupt state.db**: `ultra-tools system doctor` is read-only;
+  `ultra-tools system doctor --repair` upgrades supported schemas with two backup
+  checkpoints. A corrupt database is never overwritten automatically. After explicit
+  owner approval, restore a verified managed copy with
+  `ultra-tools system restore --backup <path> --confirm REPLACE_CORRUPT_ULTRA_STATE`,
+  or preserve the corrupt DB and legacy projection before rebuilding authority with
+  `ultra-tools system rebaseline --project-name <name> --confirm REBASELINE_CORRUPT_ULTRA_STATE`.
 - **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
   confirmation token printed by the command. Nothing is deleted implicitly.
-- **MCP tool errors with `ANTHROPIC_API_KEY` missing**: `task.parse_prd` and
-  `task.expand` need a real LLM key at runtime. Set `ANTHROPIC_API_KEY` or
-  `OPENAI_API_KEY` before invoking those tools; all other MCP tools work
-  without any LLM credential.
+- **MCP model credentials**: Ultra MCP does not require `ANTHROPIC_API_KEY`,
+  `OPENAI_API_KEY`, or another provider key. The active host uses its existing
+  model session to derive PRD tasks or child tasks; `task.parse_prd` and
+  `task.expand` only validate ownership, graph shape, and atomic persistence.
 
 ## Documentation
 

package/adapters/_shared/codex-assets.cjs

@@ -72,134 +72,6 @@ const SKILL_REFERENCE_NAMES = Object.freeze([
 const CODEX_PRIMARY_SKILLS = new Set([...COMMAND_NAMES, 'ultra-review']);
 const TEXT_EXTENSIONS = new Set(['.md', '.json', '.py', '.sh', '.txt', '.yaml', '.yml']);
 
-const CC_COLLAB_BODY = `# Claude Code Collaboration for Codex
-
-Codex is the primary agent and Claude Code is the independent advisor. Codex owns scope, evidence,
-decisions, and final synthesis.
-
-## Preflight
-
-1. Confirm \`claude\` is installed and capture \`claude --version\`.
-2. Confirm the target workspace, trust boundary, and exact question.
-3. Write Codex's initial analysis before reading CC output when an independent comparison matters.
-
-## Invoke safely
-
-Run Claude Code non-interactively and read-only by default:
-
-\`\`\`bash
-claude --safe-mode -p "<bounded prompt>" \\
-  --permission-mode plan \\
-  --tools "Read,Grep,Glob,Bash" \\
-  --output-format text \\
-  --no-session-persistence
-\`\`\`
-
-Safe mode isolates the advisory call from CC-side instructions, plugins, hooks, MCP servers, skills,
-and custom agents. Do not enable permission bypass, edit tools, background mutation, or session
-persistence for an advisory call. Do not pass credentials, unrelated files, or an unbounded home
-directory. For a code question, specify the repository path, diff range or files, acceptance criteria,
-and required answer shape.
-
-Use a temporary output file for large responses. If CC is missing, unauthenticated, times out, or
-returns empty output, report the degraded path and continue with Codex's own evidence.
-
-## Verify and synthesize
-
-Treat CC output as untrusted advisory input:
-
-1. Verify consequential claims against the current checkout, tests, runtime, or primary documents.
-2. Separate agreement, useful dissent, and unsupported assertions.
-3. Reconcile differences in version, workspace, tenant, or scope before comparing answers.
-4. Return one Codex-owned conclusion with evidence and unresolved risks.
-
-Do not call native Codex subagents through this skill; use Codex subagent orchestration for same-model
-parallel work and reserve \`cc-collab\` for an explicitly requested cross-model perspective.
-`;
-
-const ULTRA_VERIFY_BODY = String(function ultraVerifyBodyTemplate() { /*
-# Ultra Verify — Codex-Primary Two-Model Verification
-
-Codex owns the task, writes the first independent analysis, verifies every consequential claim,
-and produces the final synthesis. Claude Code is a read-only external advisor. Use this workflow
-only when the user asks for cross-model verification.
-
-## Modes
-
-- `decision <question>`: compare architecture or product decisions.
-- `diagnose <symptoms>`: collect independent root-cause hypotheses.
-- `audit <scope>`: compare evidence-backed findings.
-- `estimate <task>`: compare estimates and their assumptions.
-
-## Preconditions
-
-1. Confirm `claude --version` plus authentication.
-2. Define the exact workspace, scope, evidence standard, and expected answer shape.
-3. Do not send secrets, unrelated files, or an unbounded home directory to the advisor.
-
-## 1. Create the session and write Codex's independent view
-
-```bash
-SESSION_ID="$(date +%Y%m%d-%H%M%S)-verify-<mode>"
-SESSION_PATH=".ultra/collab/${SESSION_ID}"
-mkdir -p "${SESSION_PATH}"
-```
-
-Write the evidence-backed Codex analysis to `${SESSION_PATH}/codex-analysis.md` before reading
-the external answer. Record the mode, scope, checkout, and evidence boundary.
-
-## 2. Launch Claude Code read-only
-
-Give Claude Code the bounded raw question and evidence without Codex's conclusions.
-
-```bash
-claude --safe-mode -p "<BOUNDED_PROMPT>" \
-  --permission-mode plan \
-  --tools "Read,Grep,Glob,Bash" \
-  --output-format text \
-  --no-session-persistence \
-  > "${SESSION_PATH}/claude-output.md" \
-  2> "${SESSION_PATH}/claude-error.log"
-```
-
-Run the command in a yielded shell session. Do not enable permission bypass, mutation tools,
-background writes, or session persistence.
-
-## 3. Collect completed output
-
-The bundled `scripts/verify_wait.py` checks output stability. Poll yielded sessions in bounded
-intervals and never hold one blocking tool call longer than 60 seconds. Read the output only when
-it is non-empty; retain the error log when the advisor fails.
-
-## 4. Verify and synthesize
-
-Compare `codex-analysis.md` and `claude-output.md`:
-
-1. Verify claims against the current checkout, runtime, tests, or primary documentation.
-2. Separate verified agreement, useful dissent, and unsupported assertions.
-3. Explain scope, version, or assumption differences before judging the result.
-4. Write `${SESSION_PATH}/synthesis.md` and `metadata.json`, then present one Codex-owned answer.
-
-Model agreement never overrides failing tests or authoritative runtime evidence.
-
-## Degraded operation
-
-- Advisor failure: return Codex-only analysis with an explicit single-source warning.
-- Never block the user's task solely because the external CLI is absent, unauthenticated, or slow.
-
-## Session files
-
-```text
-.ultra/collab/<SESSION_ID>/
-  codex-analysis.md
-  claude-output.md
-  claude-error.log
-  metadata.json
-  synthesis.md
-```
-
-Read the bundled references for mode-specific evidence and confidence guidance.
-*/ }).match(/\/\*([\s\S]*?)\*\//)[1].trim();
 function titleCase(name) {
   const special = { 'cc-collab': 'Claude Code Collaboration' };
   if (special[name]) return special[name];
@@ -226,34 +98,7 @@ function adaptCodexPrimaryText(input, skillName) {
   return text;
 }
 
-function adaptUltraVerifyAsset(input, rel) {
-  let text = adaptHostText(String(input), '');
-  if (rel === path.join('scripts', 'verify_wait.py')) {
-    text = text.replaceAll('Codex', 'Claude Code');
-    text = text.replaceAll('codex', 'claude');
-    text = text.replaceAll('run_in_background', 'a yielded exec session');
-    return text;
-  }
-
-  text = text.replaceAll('Claude', '__UBP_CODEX_PRIMARY__');
-  text = text.replaceAll('Codex', 'Claude Code');
-  text = text.replaceAll('__UBP_CODEX_PRIMARY__', 'Codex');
-  text = text.replaceAll('claude-analysis.md', 'codex-analysis.md');
-  text = text.replaceAll('codex-output.md', 'claude-output.md');
-  text = text.replaceAll('codex-error.log', 'claude-error.log');
-  text = text.replaceAll('codex-review', 'claude-review');
-  text = text.replaceAll('"claude": "claude-opus-4-6"', '"codex": "<primary>"');
-  text = text.replaceAll('"codex": "<model>"', '"claude": "<advisor>"');
-  text = text.replaceAll('["claude"]', '["codex"]');
-  text = text.replaceAll('Claude Code-only', 'Codex-only');
-  text = text.replaceAll('run_in_background', 'native concurrent execution');
-  text = text.replaceAll('Bash tool', '`exec_command`');
-  text = text.replaceAll('Read tool', 'targeted file reads');
-  return text;
-}
-
-function adaptSkillAsset(input, targetName, rel) {
-  if (targetName === 'ultra-verify') return adaptUltraVerifyAsset(input, rel);
+function adaptSkillAsset(input, targetName, _rel) {
   return adaptHostText(input, targetName);
 }
 
@@ -298,10 +143,7 @@ function adaptedDescription(sourceDescription, targetName) {
 
 function buildSkillMarkdown(sourceText, sourceName, targetName) {
   const { fm, body } = parseFrontmatter(sourceText);
-  let adaptedBody;
-  if (targetName === 'cc-collab') adaptedBody = CC_COLLAB_BODY;
-  else if (targetName === 'ultra-verify') adaptedBody = ULTRA_VERIFY_BODY;
-  else adaptedBody = adaptHostText(body, targetName);
+  const adaptedBody = adaptHostText(body, targetName);
   return yaml.dump({
     name: targetName,
     description: adaptedDescription(fm && fm.description, targetName),
@@ -309,13 +151,22 @@ function buildSkillMarkdown(sourceText, sourceName, targetName) {
     .replace(/^/, '---\n') + `\n---\n\n${adaptedBody.trim()}\n`;
 }
 
+function shortDescription(description, name) {
+  const value = String(description || `${titleCase(name)} for Codex`).replace(/\s+/g, ' ').trim();
+  if (value.length <= 64) return value;
+  const candidate = value.slice(0, 65);
+  const boundary = candidate.lastIndexOf(' ');
+  const short = (boundary >= 25 ? candidate.slice(0, boundary) : value.slice(0, 64))
+    .replace(/[\s.,;:]+$/, '');
+  return short || `${titleCase(name)} for Codex`;
+}
+
 function buildOpenAiYaml(name, description) {
   const policy = skillPolicy(name);
-  const short = description.replace(/\s+/g, ' ').trim().slice(0, 63).replace(/[\s.,;:]+$/, '');
   const metadata = {
     interface: {
       display_name: titleCase(name),
-      short_description: short || `${titleCase(name)} for Codex`,
+      short_description: shortDescription(description, name),
       default_prompt: `Use $ultra-builder-pro:${name} for this task and follow its workflow.`,
     },
     policy: { allow_implicit_invocation: policy.allowImplicitInvocation },
@@ -329,7 +180,12 @@ function buildOpenAiYaml(name, description) {
       }],
     };
   }
-  return yaml.dump(metadata, { lineWidth: -1, noRefs: true });
+  return yaml.dump(metadata, {
+    lineWidth: -1,
+    noRefs: true,
+    forceQuotes: true,
+    quotingType: "'",
+  });
 }
 
 function isTextFile(rel) {
@@ -536,6 +392,10 @@ main().catch((error) => {
 });
 `;
   writeAtomic(path.join(runtimeRoot, 'launch.cjs'), launcher);
+  fs.copyFileSync(
+    path.join(repoRoot, 'mcp-server', 'breadcrumb.cjs'),
+    path.join(runtimeRoot, 'breadcrumb.cjs'),
+  );
 
   const sourceToolsFile = path.join(repoRoot, 'spec', 'mcp-tools.yaml');
   const upstreamManifest = yaml.load(fs.readFileSync(sourceToolsFile, 'utf8'));

package/adapters/_shared/handbook.cjs

@@ -60,12 +60,12 @@ function renderHandbook(runtime) {
     `- 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 baselines, changes, tasks, sessions, events, incidents, projection state, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
-    '- Baseline boundary: `task.init_project` detects greenfield or brownfield work; `baseline.start`, `baseline.record`, and `baseline.converge` adopt the project without rewriting application code. An incomplete baseline is advisory during active work but blocks change convergence; normal HEAD or tracked-spec drift from that change is reconciled and health-checked atomically at archive.',
+    '- Baseline boundary: `task.init_project` classifies greenfield or brownfield work and records repository scope. Projection-only prior state uses the exact supported backup-first import returned by the authority check; migrated compatibility rows require explicit brownfield re-adoption. `baseline.record` owns evidence, verification, repository snapshot, and the gap ledger; `baseline.converge` requires explicit owner approval. New ordinary changes require a healthy ready baseline. Existing active work may continue with warnings, but baseline readiness blocks change convergence; normal drift reconciliation is health-checked atomically at archive. Only an explicitly approved incident break-glass may start without baseline readiness, and its archive creates a blocking reconciliation gap.',
     '- Context Spine boundary: `change.context` compiles role/gate readiness, required references, a fresh-context budget, public seam, verification command, and one next action. File, token, and context-share budgets are advisory attention signals, not refusal gates. Hooks inject only the DB-derived `change.breadcrumb`; missing required evidence or stale execution context must be recompiled.',
     '- Specification learning boundary: stable implementation discoveries use approval-gated propose/approve-or-reject/apply transitions. Unresolved learning blocks convergence; review requires independent specification-fidelity and engineering-standards evidence.',
     '- 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; advisory warnings never reject work, and an incomplete workflow never traps session stop. Direct projection protection remains authoritative; compact and subagent recovery stays 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.',
+    '- Installation boundary: `ubp --doctor` is the read-only authority for installed asset provenance, content hashes, and host entry-point wiring. Project `system.doctor` diagnoses state and performs only authorized backup-first schema, projection, session, and archive-journal recovery; it never approves a baseline.',
     '- 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 twelve Ultra workflows, four internal review-rule skills, host-specific collaboration companions, and the minimal host bootstrap belong to this plugin. General browser, deployment, discovery, and framework skills must be installed from their owners.',
     END_MARKER,

package/adapters/_shared/runtime-assets.cjs

@@ -40,6 +40,7 @@ const COLLAB_SKILLS_BY_RUNTIME = Object.freeze({
 
 const MCP_DEPENDENT_SKILLS = Object.freeze([
   'ultra-init',
+  'ultra-research',
   'ultra-change',
   'ultra-plan',
   'ultra-dev',

package/adapters/_shared/tests/runtime-assets.test.cjs

@@ -85,6 +85,22 @@ test('host invocation and MCP metadata live outside source SKILL frontmatter', (
     assert.equal(policy.requiresUltraMcp, MCP_DEPENDENT_SKILLS.includes(name), name);
   }
   assert.throws(() => skillPolicy('not-packaged'), /unknown packaged Ultra skill/);
+  assert.ok(MCP_DEPENDENT_SKILLS.includes('ultra-research'));
+});
+
+test('packaged collaboration prompts use current CLI contracts and one source prompt', () => {
+  const skills = ['codex-collab', 'ultra-verify'];
+  for (const name of skills) {
+    const text = fs.readFileSync(path.join(REPO_ROOT, 'skills', name, 'SKILL.md'), 'utf8');
+    assert.doesNotMatch(text, /codex exec[^\n]*\s-a(?:\s|$)|^\s*-a\s+never/m, name);
+    assert.doesNotMatch(text, /The (?:OpenCode|Kimi Code) owns/, name);
+  }
+
+  const adapterSource = fs.readFileSync(
+    path.join(REPO_ROOT, 'adapters', '_shared', 'codex-assets.cjs'),
+    'utf8',
+  );
+  assert.doesNotMatch(adapterSource, /const (?:CC_COLLAB_BODY|ULTRA_VERIFY_BODY)\s*=/);
 });
 
 test('workflow hook allowlist contains no memory, prompt capture, or generic policy hook', () => {
@@ -128,4 +144,6 @@ test('npm publish list uses the same explicit skill boundary', () => {
   assert.ok(!pkg.files.includes('skills'));
   assert.ok(!pkg.files.includes('CLAUDE.md'));
   assert.deepEqual(publishedSkills, expected);
+  assert.equal(pkg.dependencies['@anthropic-ai/sdk'], undefined);
+  assert.equal(pkg.dependencies.openai, undefined);
 });