feat: complete recoverable project adoption

Ultra initialization previously created only a scaffold for existing repositories, could leave migrated or corrupt authority ambiguous, and allowed some task writers to bypass baseline and change ownership. Context limits and hook presentation could also obstruct legitimate incident work instead of providing recoverable guidance.

Complete the greenfield, brownfield, prior-version, and corrupt-state lifecycle in one route. Add schema 12 repository, scope, branch, worktree, evidence, classification, and gap-ledger authority; safe resume and migration routing; explicit ready-baseline replacement approval; backup-first restore and rebaseline; durable archive-journal recovery; incident break-glass with mandatory reconciliation; and advisory context budgets.

Rework Ultra skills and baseline templates around Observed, Verified, Decided, and Unknown evidence. Keep memory and code graph external, preserve host-neutral English prompt surfaces, and keep Claude Code, Codex, OpenCode, and Kimi installation contracts aligned.

Close task authority bypasses across direct create, PRD parse, expansion, and update paths. Tasks now require a healthy baseline or authorized active change, children inherit parent ownership, established ownership cannot detach or cross changes, and terminal-change tasks are immutable.

Verification: uv run --with pytest npm run verify:release passed all state/MCP, orchestrator, specification, four-host installation, npm tarball, and 24 hook tests; npm audit reported 0 vulnerabilities. Skill Creator quick validation passed 19/19 skills, prompt-authoring tests passed 11/11, MCP fixtures passed 69/69, npm pack dry-run contained 215 entries, and final forward ownership audit passed.

Recovery remains explicit and backup-first; no project state is overwritten without the documented confirmation token. Persistent memory and code graph remain intentional external-provider exclusions. The unrelated untracked AGENTS.md was not staged.

Author: rocky2431

.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.

.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,

CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +541,8 @@ 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.13.0...HEAD
+[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

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.13.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)
@@ -44,9 +44,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 +90,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 +134,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,6 +213,17 @@ 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

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,

adapters/tests/codex.test.cjs

@@ -9,6 +9,7 @@ const { spawnSync } = require('node:child_process');
 const yaml = require('js-yaml');
 const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
 const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
+const { initStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
 
 const codex = require('../codex.js');
 const { parse: parseFrontmatter } = require('../_shared/frontmatter.cjs');
@@ -263,6 +264,13 @@ test('bundled plugin MCP runs outside the source checkout and keeps state in the
   let client;
   try {
     install(layout);
+    const seededState = initStateDb(path.join(projectDir, '.ultra', 'state.db'));
+    seededState.db.prepare(
+      `INSERT INTO baselines
+       (id, project_name, mode, status, approved_by, approval_note, converged_at)
+       VALUES ('test-baseline', 'codex-bundle', 'greenfield', 'ready', 'test', 'smoke fixture', ?)`,
+    ).run(new Date().toISOString());
+    closeStateDb(seededState.db);
     const mcp = JSON.parse(fs.readFileSync(path.join(layout.pluginRoot, '.mcp.json'), 'utf8'));
     const server = mcp.mcpServers['ultra-builder-pro'];
     const env = { ...process.env };

commands/ultra-init.md

@@ -1,6 +1,6 @@
 ---
 description: Initialize a new project or adopt an existing repository into authoritative Ultra baseline state
-argument-hint: "[name] [type] [stack] [auto|greenfield|brownfield]"
+argument-hint: "[name] [type] [stack] [auto|greenfield|brownfield] [--scope <path>]"
 workflow-ref: "@skills/ultra-init/SKILL.md"
 ---
 

docs/AGENT-CONTEXT.md

@@ -78,9 +78,10 @@ necessary context when they do not.
 role, gate, readiness, blockers, and one next action. They must not inject intent
 bodies, transcripts, external memory, or graph payloads. Missing references,
 digest drift, HEAD drift, or a missing execution seam blocks readiness. Context
-size and an incomplete baseline are advisory during an active bounded change;
-baseline adoption becomes a hard gate at convergence; revision and tracked-spec
-integrity are reconciled and rechecked atomically at archive.
+size and baseline drift are advisory for a change that is already active. New ordinary
+work requires a healthy baseline. Only an explicitly approved incident break-glass may
+start without it; incident archive records a blocking reconciliation gap. Revision and
+tracked-spec integrity are reconciled and rechecked atomically for ordinary archive.
 
 Stable discoveries use `change.learning_propose`; they reach the baseline only
 through approve/reject/apply transitions in `change.learning_resolve`. Unresolved