ultra-builder-pro-cli 0.12.1 → 0.14.0

package/mcp-server/tests/state-db.test.cjs

@@ -59,7 +59,9 @@ test('initStateDb upgrades a pre-10.0 database through Context Spine into baseli
     assert.ok(columns.includes('change_id'));
     const eventColumns = upgraded.db.prepare('PRAGMA table_info(events)').all().map((row) => row.name);
     assert.ok(eventColumns.includes('change_id'));
-    assert.equal(upgraded.schema_version, '11.0');
+    assert.equal(upgraded.schema_version, '12.0');
+    assert.ok(upgraded.backup_path);
+    assert.ok(fs.existsSync(upgraded.backup_path));
     assert.ok(upgraded.db.prepare("SELECT 1 FROM schema_version WHERE version = '10.0'").get());
     const contextColumns = upgraded.db.prepare('PRAGMA table_info(context_snapshots)').all()
       .map((row) => row.name);
@@ -72,7 +74,7 @@ test('initStateDb upgrades a pre-10.0 database through Context Spine into baseli
     const baseline = upgraded.db.prepare(
       "SELECT mode, status FROM baselines WHERE id = 'migrated-baseline'",
     ).get();
-    assert.deepEqual(baseline, { mode: 'migrated', status: 'ready' });
+    assert.deepEqual(baseline, { mode: 'migrated', status: 'adopting' });
     const contextMigration = upgraded.db.prepare(
       "SELECT from_version, to_version, notes FROM migration_history WHERE to_version = '10.0' ORDER BY id DESC LIMIT 1",
     ).get();
@@ -84,6 +86,16 @@ test('initStateDb upgrades a pre-10.0 database through Context Spine into baseli
     ).get();
     assert.equal(baselineMigration.from_version, '10.0');
     assert.match(baselineMigration.notes, /baseline adoption/i);
+    const adoptionMigration = upgraded.db.prepare(
+      "SELECT from_version, to_version, notes FROM migration_history WHERE to_version = '12.0' ORDER BY id DESC LIMIT 1",
+    ).get();
+    assert.equal(adoptionMigration.from_version, '11.0');
+    assert.match(adoptionMigration.notes, /gap ledger|re-adoption/i);
+    const migrated = upgraded.db.prepare(
+      "SELECT gaps_json, worktree_state FROM baselines WHERE id = 'migrated-baseline'",
+    ).get();
+    assert.equal(migrated.worktree_state, 'unavailable');
+    assert.equal(JSON.parse(migrated.gaps_json)[0].category, 'baseline_blocker');
     assert.ok(upgraded.db.prepare(
       "SELECT 1 FROM migration_history WHERE from_version = '8A.1' AND to_version = '9.1' AND notes LIKE '%Kimi%'",
     ).get());

package/mcp-server/tests/state-ops.test.cjs

@@ -20,6 +20,13 @@ function freshDb() {
   return { ...t, db: init.db };
 }
 
+function seedChange(db, id, status = 'active') {
+  db.prepare(
+    `INSERT INTO changes (id, title, kind, status, intent, artifact_root)
+     VALUES (?, ?, 'quick', ?, ?, ?)`,
+  ).run(id, `Change ${id}`, status, `Intent for ${id}.`, `.ultra/changes/active/${id}`);
+}
+
 test('createTask inserts a row, preserves estimated_days, defaults status=pending, emits task_created', () => {
   const { dir, db } = freshDb();
   try {
@@ -65,6 +72,107 @@ test('createTask rejects duplicates with DUPLICATE_TASK_ID', () => {
   }
 });
 
+test('createTask preserves parent change ownership and rejects terminal change targets', () => {
+  const { dir, db } = freshDb();
+  try {
+    seedChange(db, 'change-a');
+    seedChange(db, 'change-b');
+    seedChange(db, 'change-closed', 'archived');
+    ops.createTask(db, {
+      id: 'parent-owned', title: 'owned parent', type: 'feature', priority: 'P1',
+      change_id: 'change-a',
+    });
+    const inherited = ops.createTask(db, {
+      id: 'child-inherited', title: 'inherited child', type: 'feature', priority: 'P1',
+      parent_id: 'parent-owned',
+    });
+    assert.equal(inherited.change_id, 'change-a');
+    assert.throws(
+      () => ops.createTask(db, {
+        id: 'child-mismatch', title: 'mismatched child', type: 'feature', priority: 'P1',
+        parent_id: 'parent-owned', change_id: 'change-b',
+      }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    assert.throws(
+      () => ops.createTask(db, {
+        id: 'child-orphan', title: 'orphan child', type: 'feature', priority: 'P1',
+        parent_id: 'missing-parent',
+      }),
+      (error) => error.code === 'TASK_NOT_FOUND',
+    );
+    assert.throws(
+      () => ops.createTask(db, {
+        id: 'closed-change-task', title: 'closed change task', type: 'feature', priority: 'P1',
+        change_id: 'change-closed',
+      }),
+      (error) => error.code === 'CHANGE_NOT_MUTABLE',
+    );
+  } finally {
+    closeStateDb(db);
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('patchTask keeps established ownership immutable and rejects terminal-change writes', () => {
+  const { dir, db } = freshDb();
+  try {
+    seedChange(db, 'change-a');
+    seedChange(db, 'change-b');
+    seedChange(db, 'change-ready', 'ready');
+    ops.createTask(db, {
+      id: 'patch-parent', title: 'patch parent', type: 'feature', priority: 'P1',
+      change_id: 'change-a',
+    });
+    ops.createTask(db, {
+      id: 'patch-child', title: 'patch child', type: 'feature', priority: 'P1',
+      parent_id: 'patch-parent',
+    });
+    assert.throws(
+      () => ops.patchTask(db, 'patch-child', { change_id: null }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    assert.throws(
+      () => ops.patchTask(db, 'patch-child', { change_id: 'change-b' }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    assert.throws(
+      () => ops.patchTask(db, 'patch-parent', { change_id: 'change-b' }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    const root = ops.createTask(db, {
+      id: 'patch-root', title: 'owned root', type: 'feature', priority: 'P1',
+      change_id: 'change-a',
+    });
+    assert.equal(root.change_id, 'change-a');
+    assert.throws(
+      () => ops.patchTask(db, 'patch-root', { change_id: null }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    assert.throws(
+      () => ops.patchTask(db, 'patch-root', { change_id: 'change-b' }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    const standalone = ops.createTask(db, {
+      id: 'patch-standalone', title: 'patch standalone', type: 'feature', priority: 'P1',
+    });
+    assert.equal(standalone.change_id, null);
+    assert.equal(ops.patchTask(db, 'patch-standalone', { change_id: 'change-b' }).change_id, 'change-b');
+    assert.throws(
+      () => ops.patchTask(db, 'patch-root', { change_id: 'change-ready' }),
+      (error) => error.code === 'TASK_CHANGE_OWNERSHIP_MISMATCH',
+    );
+    db.prepare("UPDATE changes SET status = 'archived' WHERE id = 'change-a'").run();
+    assert.throws(
+      () => ops.patchTask(db, 'patch-root', { priority: 'P0' }),
+      (error) => error.code === 'CHANGE_NOT_MUTABLE',
+    );
+  } finally {
+    closeStateDb(db);
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('updateTaskStatus enforces the legal transition graph', () => {
   const { dir, db } = freshDb();
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "Multi-runtime installer for the Ultra Builder Pro agent engineering system — deploys commands, agents, skills, hooks, and MCP server to Claude Code, OpenCode, Codex CLI, and Kimi Code.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
@@ -98,13 +98,11 @@
     "install:all": "node bin/install.js --all --local"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.111.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@vercel/ncc": "0.38.4",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "better-sqlite3": "^11.5.0",
-    "js-yaml": "^4.1.0",
-    "openai": "^6.34.0"
+    "js-yaml": "^4.1.0"
   }
 }

package/skills/cc-collab/SKILL.md

@@ -5,8 +5,8 @@ description: Ask Claude Code for an independent read-only analysis of a bounded
 
 # Consult Claude Code read-only
 
-Treat Claude Code as an untrusted advisor. The current host owns scope, evidence,
-decisions, edits, and final verification.
+Treat Claude Code as an untrusted advisor. Keep the current host responsible for
+scope, evidence, decisions, edits, and final verification.
 
 ## Preconditions
 

package/skills/codex-collab/SKILL.md

@@ -5,8 +5,8 @@ description: Ask Codex CLI for an independent read-only analysis of a bounded ar
 
 # Consult Codex read-only
 
-Treat Codex as an untrusted advisor. The current host owns scope, evidence, edits,
-verification, and the final answer.
+Treat Codex as an untrusted advisor. Keep the current host responsible for scope,
+evidence, edits, verification, and the final answer.
 
 ## Preconditions
 
@@ -23,7 +23,6 @@ Create a session directory under `.ultra/collab/`, then run in a read-only sandb
 SESSION_PATH=".ultra/collab/$(date +%Y%m%d-%H%M%S)-codex"
 mkdir -p "${SESSION_PATH}"
 codex exec -s read-only \
-  -a never \
   --ephemeral \
   --ignore-user-config \
   --ignore-rules \

package/skills/ultra-change/SKILL.md

@@ -16,11 +16,13 @@ own their payloads; Ultra stores only provider references supplied by the user o
 
 ## Workflow
 
-1. Call `baseline.get`. State integrity failure routes to `ultra-doctor`. When no
-   change is active, a missing, incomplete, or stale baseline routes to `ultra-init`.
-   An urgent or already active bounded change may proceed with that condition recorded
-   as a warning. `change.converge` requires an approved `ready` baseline; repository
-   revision and tracked-spec drift created by the change are reconciled at archive.
+1. Call `baseline.get`. State integrity failure routes to `ultra-doctor`.
+   - Create ordinary work only when the baseline is healthy and `ready`.
+   - Resume a change that was already active when baseline drift appears; record the
+     condition as a warning and restore baseline readiness before ordinary convergence.
+   - Create an `incident` on an unhealthy baseline only with an explicit
+     `baseline_bypass` containing the reason and approver.
+   - Route every other missing, migrated, incomplete, or stale baseline to `ultra-init`.
 2. Call `change.list` and `change.breadcrumb`.
    - Resume the single change that matches the requested outcome.
    - Require an explicit id when several changes could match.
@@ -30,6 +32,8 @@ own their payloads; Ultra stores only provider references supplied by the user o
 4. Classify the change as `quick`, `standard`, `major`, or `incident`. Ask only for a
    material product, risk, or recovery decision that repository evidence cannot answer.
 5. Call `change.create` with a stable kebab-case id, or `change.update` when resuming.
+   For incident break-glass, persist the approved reason in `baseline_bypass`; never
+   infer approval from urgency.
 6. Write the minimum artifact set required by the classification:
 
    ```text
@@ -69,8 +73,12 @@ verified.
 ## Completion gate
 
 Do not claim alignment while a material decision is unresolved, documentation impact
-is unknown, context is stale, or the next task is not executable. `change.converge`
-also requires a `ready` baseline, so incomplete adoption must be resolved before
-convergence. Normal HEAD or tracked-spec drift caused by the active change is not a
-convergence blocker. Declare every baseline update at archive; archive fails and rolls
-back when revision or digest health remains stale after reconciliation.
+is unknown, context is stale, or the next task is not executable. Ordinary change
+convergence requires a non-migrated `ready` baseline. Normal HEAD or tracked-spec drift
+caused by the active change is reconciled at archive.
+
+An approved break-glass incident may converge and archive while baseline adoption is
+incomplete. Its archive must add an open `baseline_blocker` reconciliation gap owned by
+the recorded approver. Report the incident as closed and the project baseline as not
+ready until that gap is resolved. Every archive declares baseline updates or an exact
+no-change reason; failed ordinary reconciliation rolls back state and artifacts.

package/skills/ultra-deliver/SKILL.md

@@ -12,10 +12,10 @@ review, and delivery reports are evidence artifacts.
 
 1. Call `baseline.get`, then `change.list`. Bind exactly one relevant change, or the
    current draft/adopting baseline when this is the initial delivery.
-2. Call `change.breadcrumb`. Context-size warnings are advisory, but delivery blocks
-   on incomplete baseline adoption, stale execution context, incomplete linked tasks,
-   or unresolved readiness. HEAD and tracked-spec drift caused by the current change
-   remain visible warnings until archive reconciliation.
+2. Call `change.breadcrumb`. Context-size warnings are advisory. Ordinary delivery
+   blocks on incomplete baseline adoption, stale execution context, incomplete linked
+   tasks, or unresolved readiness. An explicitly approved break-glass incident may
+   continue while baseline adoption is incomplete.
 3. Require a passing test report for the current full HEAD and at least one declared
    public seam.
 4. Require current independent `spec_fidelity` and `engineering_standards` review
@@ -59,11 +59,15 @@ delta, documentation, both independent review axes, and incident diagnosis when
 applicable. Do not collapse review axes or replace exact signal fields with prose.
 
 Resolve named blockers, rerun invalidated gates, then call `change.archive` with the
-summary and baseline updates. Archive reconciliation refreshes the authoritative
-baseline revision and digests. The archive transaction rechecks baseline health and
-rolls back the state row, artifacts, and reconciliation events if any tracked digest
-or repository revision remains stale. Verify the result with `baseline.get` before
-release.
+summary and baseline updates or an exact no-change reason. Ordinary archive
+reconciliation refreshes the authoritative baseline revision and digests, rechecks
+health, and rolls back state and artifacts when any tracked digest or revision remains
+stale.
+
+For a break-glass incident, verify that archive returned `baseline_bypass: true` and
+created the open reconciliation gap on the current baseline. Report incident delivery
+separately from project baseline readiness. Resolve that gap through `ultra-init`
+before starting ordinary work.
 
 ## Optional release
 

package/skills/ultra-dev/SKILL.md

@@ -17,8 +17,10 @@ Read `change.breadcrumb` when a change is active. Stale context, blocked readine
 unknown documentation impact, or a HEAD mismatch blocks implementation.
 Baseline-adoption and context-size warnings do not block an active slice. Address
 them when practical without dropping required evidence or arbitrarily changing a
-threshold. Approved baseline availability is enforced at convergence; revision and
-tracked-spec health are reconciled and verified at archive.
+threshold. Ordinary convergence requires approved baseline availability; revision
+and tracked-spec health are reconciled and verified at archive. An approved
+break-glass incident may finish recovery first and must leave a blocking baseline
+reconciliation gap.
 
 ## Workflow
 
@@ -40,8 +42,8 @@ tracked-spec health are reconciled and verified at archive.
    utilities, keep IO at boundaries, include required errors and recovery, and preserve
    unrelated worktree changes.
 7. If the work reveals a stable requirement or public behavior absent from the
-   baseline, call `change.learning_propose`. Do not edit the baseline silently or store
-   the discovery as private Ultra memory.
+   baseline, call `change.learning_propose`. Do not edit the baseline silently or keep
+   the discovery only in transient conversation context.
 8. Verify in this order:
    - the original feedback-loop command;
    - adjacent focused tests;

package/skills/ultra-doctor/SKILL.md

@@ -15,6 +15,7 @@ Call `system.doctor` with `{ "repair": false }` and inspect:
 - open structured incidents;
 - event and projection cursor lag;
 - failed or interrupted projection jobs;
+- interrupted archive journals;
 - orphan sessions;
 - missing active-change artifact roots;
 - missing, incomplete, or stale project baseline readiness and specification digests;
@@ -36,17 +37,31 @@ delete artifacts, or collect memory during diagnosis.
   not approve a baseline, accept known-red verification, or invent adoption evidence.
   Baseline readiness is an advisory workflow check, not state-database corruption and
   not a reason for doctor repair.
+- A compatibility `migrated` baseline requires explicit brownfield re-adoption and
+  cannot authorize ordinary changes.
+- A corrupt SQLite file requires preserving the file, locating a verified backup, and
+  an explicit restore-or-rebaseline decision.
 
 ## Explicit repair
 
 After authorization, call `system.doctor` with `{ "repair": true }` or use the
-installed `ultra-tools system doctor --repair` fallback. The runtime must create a
-timestamped state database backup before any mechanical repair.
-
-Repair is limited to documented recovery operations such as reconciling orphan
-sessions, consuming staleness events, requeueing interrupted or failed projections,
-and regenerating projections from authoritative state. If backup fails, stop. Always
-inspect the post-repair report; a completed repair action does not imply healthy state.
+installed `ultra-tools system doctor --repair` fallback. The CLI applies supported
+schema upgrades to the packaged current schema and reports a pre-migration backup path. Doctor then
+creates a second timestamped backup before runtime recovery.
+
+Repair is limited to documented schema upgrades, archive-journal completion,
+reconciling orphan sessions, consuming staleness events, requeueing interrupted or
+failed projections, and regenerating projections from authoritative state. If either
+backup fails, stop. Always inspect the post-repair report; a completed repair action
+does not imply healthy state.
+
+If SQLite integrity prevents doctor from opening authority, preserve the original
+database, WAL, and SHM. After the owner chooses a recovery path, either run
+`ultra-tools system restore --backup <managed-backup> --confirm
+REPLACE_CORRUPT_ULTRA_STATE` or run `ultra-tools system rebaseline --project-name
+<name> [--scope <path>] --confirm REBASELINE_CORRUPT_ULTRA_STATE`. Both commands
+must report the recovery backup directory. A failed command must restore the
+original authority, sidecars, and task projection before returning an error.
 
 ## Installed-plugin failures
 

package/skills/ultra-init/SKILL.md

@@ -1,66 +1,111 @@
 ---
 name: ultra-init
-description: Initialize Ultra Builder Pro or resume greenfield and brownfield baseline adoption. Use when a repository lacks Ultra state or its project baseline is missing, draft, adopting, or blocked.
+description: Initialize a new repository, adopt an existing codebase, or upgrade prior Ultra state into an evidence-backed project baseline. Use when `.ultra` is absent, baseline readiness is incomplete, or legacy project state must be migrated.
 ---
 
-# Initialize or adopt a project
-
-Create project-local Ultra state, then route the repository according to its actual
-baseline status. Do not treat an existing codebase as a new product.
-
-## Preflight
-
-Use the current working directory unless the user names another target. Inspect the
-root, project manifests, Git state, and `.ultra/` without mutation.
-
-If `.ultra/` exists, call `baseline.get` and `system.doctor`:
-
-- a healthy `ready` baseline routes to `ultra-change` or `ultra-status`;
-- `draft`, `adopting`, or baseline-blocked state resumes this workflow;
-- state integrity or migration failure routes to `ultra-doctor`;
-- recreation requires explicit authorization and must preserve the returned backup.
-
-Never overwrite `.ultra/` merely because the repository is old or its documents are
-incomplete.
+# Establish the project baseline
+
+Create or recover project-local Ultra authority, classify the repository, and finish
+the applicable baseline workflow. Keep application source unchanged during adoption.
+
+## Authority rules
+
+- Treat `.ultra/state.db` as the only durable Ultra authority.
+- Preserve every existing `.ultra/` tree and migration backup.
+- Require explicit authorization before replacing a healthy baseline or discarding a
+  corrupt database.
+- Store only metadata references for external memory and code-graph providers.
+- Create ordinary tasks only after the baseline is ready. Record characterization
+  needs and adoption gaps in the gap ledger until convergence.
+
+## Inspect and route
+
+1. Bind the repository root, Git branch and HEAD, worktree status, manifests, package
+   scripts, workspace markers, deployment files, and existing `.ultra/` assets.
+2. When `.ultra/` is absent, run **Bootstrap**.
+3. When `.ultra/tasks/tasks.json` contains tasks but `state.db` is absent or has no
+   tasks, run **Import projection-only state** before ordinary state-backed work.
+4. When `state.db` exists, run read-only project doctor first. Call `baseline.get`
+   only when doctor confirms that the current schema authority is readable. Route an
+   old schema to repair and a corrupt database to recovery without another DB read.
+5. After current authority is readable, call `task.init_project` with `resume: true` to install
+   only missing current scaffold files. Verify that existing artifacts were preserved.
+6. Route the result:
+   - healthy `ready` baseline: return `ultra-change` or `ultra-status`;
+   - `draft`, `adopting`, or baseline-blocked: resume the matching baseline;
+   - `migrated`: start evidence-backed brownfield re-adoption;
+   - old schema: run backup-first schema repair;
+   - corrupt database: preserve it and stop at the restore-or-rebaseline decision.
 
 ## Bootstrap
 
-When `.ultra/` is absent, derive project name, type, and stack from repository evidence,
-then call `task.init_project` with `mode: "auto"`. Use an explicit `greenfield` or
-`brownfield` mode only when the user has made that classification authoritative.
-
-Verify the returned mode, baseline id and status, state database path, initial
-projection, and copied specification files.
-
-## Route by mode
-
-### Greenfield
-
-The new baseline begins as `draft`. Route unresolved product or architecture intent to
-`ultra-research`. That workflow records evidence and converges the baseline before
-planning. Do not create implementation tasks during initialization.
-
-### Brownfield
-
-Read `references/brownfield-adoption.md` completely. Adopt current behavior from the
-checkout, tests, maintained documentation, and runtime evidence. Use `baseline.record`
-for the bounded snapshot and `baseline.converge` only after the owner approves the
-captured baseline and any accepted known-red verification.
-
-## Failure handling
-
-- `ULTRA_DIR_EXISTS`: inspect and resume; do not retry with overwrite automatically.
-- `BASELINE_EXISTS`: keep the ready baseline unless explicit re-adoption is required.
-- `BASELINE_IN_PROGRESS`: resume the named baseline rather than creating another.
-- `TEMPLATE_MISSING`: report a package-integrity failure and route to installer doctor.
-- `TARGET_NOT_DIR`, `VALIDATION_ERROR`, or `IO_ERROR`: correct only the evidenced input;
-  preserve any backup and partial diagnostic.
-
-## Output
-
-Report target path, detected mode, baseline id/status/revision, state health, known-red
-verification, blocking unknowns, and one next action. `.ultra/state.db` is authoritative;
-JSON and Markdown projections do not create state.
-
-Do not browse by default, invent missing behavior, rewrite application code, create
-business tasks, stage files, or commit as part of initialization.
+Derive project metadata from repository evidence. Call `task.init_project` with
+`mode: "auto"`. Pass `scope` when the user selected a monorepo boundary; otherwise use
+the repository root. Use an explicit mode only when the user supplied an authoritative
+classification.
+
+Verify `repository_profile`, selected scope, detected mode, baseline lifecycle, schema
+version, copied templates, initial projection, and `project_initialized` event.
+
+## Import projection-only state
+
+Call `task.init_project` with `resume: true` as the single authority check and run the
+exact supported backup-first import command returned in its structured error. Do not
+infer an import path or edit the projection manually.
+
+Verify imported task and event counts, backup path, current schema state, projection
+parity, and the `migrated/adopting` compatibility baseline. Then call `baseline.start` with a
+new id, `mode: "brownfield"`, `replace_migrated: true`, the selected scope, current
+revision, and repository classification. Never treat the compatibility row as owner
+approval.
+
+For an older database schema, run `ultra-tools system doctor --repair`; verify both the
+pre-migration backup and post-repair backup plus the current schema before continuing.
+Then resume initialization to merge missing scaffold assets without overwriting the
+project's existing baseline documents.
+
+## Complete the selected mode
+
+For `brownfield`, `migrated`, or an incomplete existing adoption, read
+`references/brownfield-adoption.md` completely and execute it through owner approval.
+
+For `greenfield`, keep the baseline in `draft` until product and architecture intent is
+evidence-backed. Route unresolved intent through `ultra-research`, record the complete
+baseline snapshot, obtain owner approval, and converge it before planning.
+
+## Recovery handling
+
+- `ULTRA_DIR_EXISTS`: inspect and resume the existing state.
+- `LEGACY_STATE_MIGRATION_REQUIRED`: execute the returned migration command.
+- `BASELINE_IN_PROGRESS`: resume the named row; never create a parallel authority.
+- `BASELINE_EXISTS`: return the healthy route. Replacing a ready baseline is outside
+  ordinary initialization; stop for owner authorization before calling
+  `baseline.start` with a new id, `replace_ready: true`, and
+  `replacement_authorization: { approved_by, reason }`. The approval identity and
+  rationale must be persisted in the `baseline_started` event.
+- `BASELINE_SCOPE_MISSING`: correct the selected monorepo boundary.
+- `TEMPLATE_MISSING`: run installer doctor and reinstall through the host adapter.
+- `STATE_DB_CORRUPT`: retain the database, inspect `.ultra/backups`, and obtain the
+  restore-or-rebaseline decision. Restore only a verified managed backup with
+  `ultra-tools system restore --backup <path> --confirm REPLACE_CORRUPT_ULTRA_STATE`.
+  When no valid backup exists and the owner explicitly accepts rebuilding authority,
+  run `ultra-tools system rebaseline --project-name <name> [--scope <path>] --confirm
+  REBASELINE_CORRUPT_ULTRA_STATE`; verify the quarantined database and legacy
+  projection paths before continuing adoption.
+- `IO_ERROR`: verify rollback restoration and preserve every reported backup path.
+
+## Completion
+
+Initialization is complete only when:
+
+- current schema authority is readable;
+- repository classification and scope are recorded;
+- product and architecture baseline files exist;
+- verification, unknowns, gaps, evidence, and provider references are recorded;
+- explicit owner approval has converged the baseline to `ready`;
+- `baseline.get` reports current health and project doctor has no authority failure.
+
+Report the target, classification evidence, migration and backup paths, baseline id,
+mode, status, revision, branch, worktree snapshot, verification results, gap summary,
+approval state, and one exact next action. Stop at the approval step when owner consent
+has not yet been provided.