ultra-builder-pro-cli 0.11.0 → 0.13.0

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

@@ -8,7 +8,7 @@ const path = require('node:path');
 
 const stateDb = require('../lib/state-db.cjs');
 
-test('initStateDb upgrades a pre-10.0 database in place with Context Spine state', () => {
+test('initStateDb upgrades a pre-10.0 database through Context Spine into baseline authority', () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-db-upgrade-'));
   const file = path.join(dir, 'state.db');
   try {
@@ -59,7 +59,9 @@ test('initStateDb upgrades a pre-10.0 database in place with Context Spine state
     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, '10.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);
@@ -69,12 +71,31 @@ test('initStateDb upgrades a pre-10.0 database in place with Context Spine state
     assert.ok(upgraded.db.prepare(
       "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'spec_learning_candidates'",
     ).get());
+    const baseline = upgraded.db.prepare(
+      "SELECT mode, status FROM baselines WHERE id = 'migrated-baseline'",
+    ).get();
+    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();
     assert.equal(contextMigration.from_version, '9.1');
     assert.equal(contextMigration.to_version, '10.0');
     assert.match(contextMigration.notes, /Context Spine/);
+    const baselineMigration = upgraded.db.prepare(
+      "SELECT from_version, to_version, notes FROM migration_history WHERE to_version = '11.0' ORDER BY id DESC LIMIT 1",
+    ).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.11.0",
+  "version": "0.13.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",

package/skills/ultra-change/SKILL.md

@@ -16,16 +16,25 @@ own their payloads; Ultra stores only provider references supplied by the user o
 
 ## Workflow
 
-1. Call `change.list` and `change.breadcrumb`.
+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.
    - Create a new change only when no existing packet represents the same outcome.
-2. Capture the observable outcome, acceptance, non-goals, affected public seam,
+3. Capture the observable outcome, acceptance, non-goals, affected public seam,
    documentation impact, and unresolved decisions.
-3. Classify the change as `quick`, `standard`, `major`, or `incident`. Ask only for a
+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.
-4. Call `change.create` with a stable kebab-case id, or `change.update` when resuming.
-5. Write the minimum artifact set required by the classification:
+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
    .ultra/changes/active/<change-id>/
@@ -41,14 +50,17 @@ own their payloads; Ultra stores only provider references supplied by the user o
    Delta files describe differences from the baseline, not a second copy of it.
    Incident diagnosis records the symptom, earliest bad state, falsifiable
    hypotheses, evidence, root cause, and recovery boundary.
-6. Create the smallest executable vertical slice with `task.create`. Each task needs
+7. Create the smallest executable vertical slice with `task.create`. Each task needs
    one outcome, bounded ownership, dependencies, a live public seam, an exact
    verification command, and documentation impact.
-7. Compile `change.context` for the next role and gate. Include only required
-   references and the task execution contract. Treat missing references, digest or
-   HEAD drift, an exceeded context budget, and unknown documentation impact as
-   blockers.
-8. Call `change.breadcrumb` and return its single next action.
+8. Compile `change.context` for the next role and gate. Include only required
+   references and the task execution contract. Missing required references, digest or
+   HEAD drift, an absent public seam or verification command, and unknown
+   documentation impact are blockers. File count, token estimate, and context-share
+   thresholds are advisory warnings: narrow reads or split the slice when useful, but
+   never raise a threshold merely to make the warning disappear or refuse necessary
+   incident context.
+9. Call `change.breadcrumb` and return its single next action.
 
 ## Specification learning
 
@@ -61,5 +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 from a bounded fresh
-context.
+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

@@ -10,10 +10,12 @@ review, and delivery reports are evidence artifacts.
 
 ## Bind current evidence
 
-1. Call `change.list` and bind exactly one relevant change, or a null change id for an
-   initial baseline.
-2. Call `change.breadcrumb`. Block on stale context, incomplete linked tasks, or
-   unresolved readiness.
+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. 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
@@ -33,6 +35,10 @@ Reconcile accepted delta content and documentation impact into baseline document
 Record updated paths or a specific no-change reason. Unknown documentation impact,
 unresolved placeholders, and behavior that exists only in the delta block convergence.
 
+For an initial baseline without a change, call `baseline.record`, obtain explicit owner
+approval, and call `baseline.converge`. Do not simulate initial delivery through a null
+change record.
+
 ## Verify the release candidate
 
 Use a clean, reviewed release commit. Show any remaining diff and obtain explicit
@@ -53,7 +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.
+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

@@ -15,6 +15,12 @@ projected status fields. If task MCP access fails, stop and route state health t
 
 Read `change.breadcrumb` when a change is active. Stale context, blocked readiness,
 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. 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
 
@@ -36,8 +42,8 @@ unknown documentation impact, or a HEAD mismatch blocks implementation.
    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,8 +15,10 @@ 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;
 - the boundary to separately installed memory and code-graph providers.
 
 Do not infer health from generated task JSON. Do not mutate external provider state,
@@ -31,17 +33,35 @@ delete artifacts, or collect memory during diagnosis.
 - An orphan session may be reconciled; never kill unrelated processes blindly.
 - A missing change artifact requires version-control, backup, or deliberate recreation
   evidence rather than silent regeneration.
+- Missing or incomplete baseline evidence routes to `ultra-init`. Doctor repair does
+  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
 
@@ -58,8 +78,9 @@ host wiring. Neither substitutes for the other.
 
 ## Output
 
-Lead with `healthy` or `degraded`. List failing checks, incident identifiers, cursor
-lag, whether repair ran, the backup path, and each unresolved action with its owner.
+Lead with `healthy` or `degraded`. List failing authority checks separately from
+baseline warnings, incident identifiers, cursor lag, whether repair ran, the backup
+path, and each unresolved action with its owner.
 
 Do not fix application code, delete state, reset Git, close healthy sessions, or
 install and repair external providers through this workflow.

package/skills/ultra-init/SKILL.md

@@ -1,70 +1,111 @@
 ---
 name: ultra-init
-description: Initialize an Ultra Builder Pro project with authoritative state, baseline specification files, and optional Git setup. Use when a repository has not yet been initialized for the Ultra workflow.
+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 an Ultra project
-
-Create the project-local Ultra runtime without inventing product requirements or
-business tasks.
-
-## Inputs
-
-Use the current working directory unless the user names another target. Inspect
-existing project manifests to infer:
-
-- project name;
-- project type;
-- primary technologies;
-- whether Git and `.ultra/` already exist.
-
-Ask only about unresolved ambiguity, optional Git initialization, or permission to
-replace an existing `.ultra/` directory. Never infer permission to overwrite it.
-
-## Workflow
-
-1. Resolve the absolute target directory and verify that it exists.
-2. Derive the project metadata from repository evidence. Treat user-provided values
-   as authoritative when they conflict with inference.
-3. If `.ultra/` exists, stop and ask whether to keep it, cancel, or recreate it with
-   `overwrite: true`. Explain that recreation first preserves a timestamped backup.
-4. Call `task.init_project` with the smallest complete input:
-
-   ```json
-   {
-     "target_dir": "/absolute/project/path",
-     "project_name": "example",
-     "project_type": "fullstack",
-     "stack": "react,node,postgres",
-     "overwrite": false
-   }
-   ```
-
-5. Verify the returned `.ultra` path, `state_db_path`, status, and copied-file list.
-   Confirm that the returned state database and baseline specification files exist.
-6. If the user requested Git setup, initialize Git only when needed and add narrowly
-   scoped ignore rules. Do not stage or commit without explicit authorization.
-
-If the MCP server cannot start, use the installed
-`ultra-tools task init-project` command only when it is available. The CLI and MCP
-must use the same initializer. Do not simulate initialization by creating projection
-files manually.
-
-## Failure handling
-
-- `ULTRA_DIR_EXISTS`: return to the overwrite decision; do not retry automatically.
-- `TEMPLATE_MISSING`: stop and report an installation/package integrity failure.
-- `TARGET_NOT_DIR` or `VALIDATION_ERROR`: correct the input and retry once.
-- `IO_ERROR`: report the affected path and preserve any backup or partial evidence.
-
-## Authority and output
-
-`.ultra/state.db` is the durable Ultra authority. Generated JSON and Markdown are
-projections or workflow artifacts and must not be edited to create state.
-
-Report the initialized path, state database path, backup path when present, Git
-action, and one next action. Route incomplete product intent to `ultra-research`;
-route an already validated baseline to `ultra-plan`.
-
-Do not create business tasks, browse the web, or rewrite an existing README as part
-of initialization.
+# 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
+
+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.