ultra-builder-pro-cli 0.11.0 → 0.13.0

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

@@ -1,223 +1,67 @@
 # Product Specification
 
-> **Source of Truth**: This document defines WHAT the system does and WHO it's for.
-> Generated by `/ultra-research` Steps 10-22
-> Technical HOW belongs in `architecture.md`.
+This document defines accepted product behavior and scope. It is a durable contract,
+not a research transcript or a task list.
 
----
+## Scope
 
-## §1 Problem Statement
+- Product or repository boundary:
+- Intended outcome:
+- Explicit non-goals:
 
-### Core Problem
-[NEEDS CLARIFICATION] — One paragraph describing the problem, grounded in discovery.md §0
+## Observed
 
-### Who It Affects
-[NEEDS CLARIFICATION] — Brief overview connecting problem to specific user types
+Record confirmed current behavior and externally visible constraints. For an existing
+project, cite source, test, runtime, or maintained documentation evidence.
 
-### Current Impact
-- **Time cost**: [NEEDS CLARIFICATION] — Hours/week wasted on workarounds
-- **Money cost**: [NEEDS CLARIFICATION] — $ lost to inefficiency
-- **Opportunity cost**: [NEEDS CLARIFICATION] — What they can't do because of this problem
+| Behavior or constraint | Evidence reference | Status |
+|---|---|---|
+| | | |
 
----
+## Decisions
 
-## §2 User Personas
+Record accepted product decisions and the evidence or owner decision behind them.
 
-### Persona 1: [NEEDS CLARIFICATION] (Primary)
+| Decision | Rationale | Acceptance impact | Owner |
+|---|---|---|---|
+| | | | |
 
-**Role**: Job title / context
-**Context**: Where they work, team dynamics, industry
+## Unknowns
 
-**Goals**:
-1. [NEEDS CLARIFICATION] — Primary goal (what gets them promoted)
-2. Secondary goal (daily care)
-3. Tertiary goal (nice to have)
+| Unknown | Blocking | Owner | Resolution evidence |
+|---|---|---|---|
+| | | | |
 
-**Pain Points**:
-1. [NEEDS CLARIFICATION] — Connects to Opportunity O# from discovery.md §1
-2. Connects to Opportunity O#
-3. Source: URL or user quote
+## Actors and Entry Points
 
-**Current Workflow**:
-> Step-by-step description of how they solve this today
-> Tools used: List of current tools/processes
-> Time spent: X hours/week
+Include actors only when they are supported by evidence. Describe the public entry
+point through which each actor reaches the behavior.
 
-**Success Metric**: How they measure their own success
-**Adoption Trigger**: What would make them try our solution
-**Objections**: Why they might resist
+| Actor or system | Need | Entry point | Evidence |
+|---|---|---|---|
+| | | | |
 
-### Persona 2: [NEEDS CLARIFICATION] (Secondary)
+## Behavior Contracts
 
-**Role**: [NEEDS CLARIFICATION]
-**Context**: [NEEDS CLARIFICATION]
+Give each required behavior a stable identifier. State preconditions, observable
+result, failure behavior, and recovery where relevant.
 
-**Goals**:
-1. [NEEDS CLARIFICATION]
+### Behavior: pending
 
-**Pain Points**:
-1. [NEEDS CLARIFICATION]
+- Trigger:
+- Preconditions:
+- Observable result:
+- Failure behavior:
+- Recovery:
+- Evidence or decision:
 
-**Current Workflow**:
-> [NEEDS CLARIFICATION]
+## Acceptance
 
-**Success Metric**: [NEEDS CLARIFICATION]
-**Adoption Trigger**: [NEEDS CLARIFICATION]
-**Objections**: [NEEDS CLARIFICATION]
+| Behavior | Acceptance evidence | Public seam | Verification |
+|---|---|---|---|
+| | | | |
 
-### Persona Prioritization
+## Documentation Impact
 
-| Persona | Urgency | Willingness to Pay | Reachability | Priority |
-|---------|---------|-------------------|-------------|----------|
-| P1 | [NEEDS CLARIFICATION] | | | **Primary** |
-| P2 | | | | **Secondary** |
-
----
-
-## §3 User Scenarios
-
-### Scenario Overview
-
-| # | Scenario | Persona | Frequency | Pain | Value | Score |
-|---|----------|---------|-----------|------|-------|-------|
-| S1 | [NEEDS CLARIFICATION] | P1 | /5 | /5 | /5 | |
-| S2 | | | | | | |
-| S3 | | | | | | |
-
-> Priority Score = Frequency × Pain × Value
-
-### Scenario 1: [NEEDS CLARIFICATION] — Primary
-
-**Persona**: [NEEDS CLARIFICATION]
-**Frequency**: Daily / Weekly / Monthly
-
-**Trigger**: What event causes this scenario
-**Context**: Where, when, device, time pressure
-
-**Current Flow** (painful):
-1. [NEEDS CLARIFICATION] — What they do today
-2. Where friction occurs
-3. Workaround they use
-4. Outcome and time wasted
-
-**Desired Flow** (with our product):
-1. [NEEDS CLARIFICATION] — Trigger detected
-2. Streamlined action
-3. Fast resolution
-4. Outcome achieved in less time
-
-**Success Outcome**: [NEEDS CLARIFICATION] — Specific and measurable
-**Failure Outcome**: [NEEDS CLARIFICATION] — Consequences
-**Emotional Arc**: Frustration → Discovery → Relief
-
-### Scenario 2: [NEEDS CLARIFICATION]
-
-[Same structure as Scenario 1]
-
-### Scenario 3: [NEEDS CLARIFICATION]
-
-[Same structure as Scenario 1]
-
----
-
-## §4 User Stories & Features
-
-### Story Map Overview
-
-| ID | Story | Persona | Scenario | Priority | Complexity |
-|----|-------|---------|----------|----------|-----------|
-| US-01 | [NEEDS CLARIFICATION] | P1 | S1 | Must | S/M/L |
-| US-02 | | | | | |
-| US-03 | | | | | |
-
-### Must-Have Stories
-
-#### US-01: [NEEDS CLARIFICATION]
-**As a** [Persona], **I want** [action], **so that** [benefit].
-
-**Acceptance Criteria**:
-- [ ] Given [context], when [action], then [result]
-- [ ] Given [context], when [edge case], then [result]
-
-**Traces to**: Scenario S#, Opportunity O#
-**Complexity**: S/M/L
-
-### Should-Have Stories
-
-#### US-04: [NEEDS CLARIFICATION]
-[Same structure]
-
-### Could-Have Stories
-
-#### US-07: [NEEDS CLARIFICATION]
-[Same structure]
-
----
-
-## §5 Feature Scope
-
-### Features In (MVP)
-
-#### Feature 1: [NEEDS CLARIFICATION]
-- **Description**: What this feature does
-- **Stories**: US-01, US-02
-- **User value**: What user can do with this
-- **Priority**: Must-Have
-- **Complexity**: S/M/L
-
-### Features In (v2 — Planned)
-
-#### Feature 4: [NEEDS CLARIFICATION]
-- **Description**: What this feature does
-- **Stories**: US-07, US-08
-- **Rationale for deferral**: Why not MVP
-- **Trigger to build**: When to reconsider
-
-### Features Out (Explicitly Excluded)
-
-| Feature | Rationale | Reconsider When | Alternative |
-|---------|-----------|----------------|-------------|
-| [NEEDS CLARIFICATION] | Why excluded (ref strategy §4) | Condition | What users do instead |
-
-### Scope Summary
-- **MVP features**: [NEEDS CLARIFICATION] features, stories
-- **v2 features**: features, stories
-- **Excluded features**: features
-
----
-
-## §6 Success Metrics
-
-### North Star Metric
-- **Metric**: [NEEDS CLARIFICATION]
-- **Definition**: Exactly what is measured
-- **Current baseline**: Current state or industry benchmark
-- **Target**: Specific number
-- **Timeline**: When to achieve
-- **Measurement method**: How to collect this data
-
-### Business Metrics
-
-| Metric | Baseline | Target (M3) | Target (M6) | Target (M12) | How Measured |
-|--------|----------|-------------|-------------|--------------|-------------|
-| [NEEDS CLARIFICATION] | | | | | |
-
-### User Metrics
-
-| Metric | Baseline | Target | How Measured |
-|--------|----------|--------|-------------|
-| Task completion rate | [NEEDS CLARIFICATION] | | |
-| Time on task | | | |
-| User satisfaction (NPS) | | | |
-| Feature adoption | | | |
-
-### Anti-Metrics (What NOT to Optimize)
-
-| Anti-Metric | Why Not | What It Could Sacrifice |
-|------------|---------|------------------------|
-| [NEEDS CLARIFICATION] | | |
-
----
-
-**Document Status**: Draft
-**Last Updated**: [Date]
+List maintained documents that must stay consistent with this contract, or record a
+specific reason why no documentation change is required.

package/.ultra-template/tasks/contexts/TEMPLATE.md

@@ -0,0 +1,36 @@
+<!-- Body template only. The projector owns authoritative YAML frontmatter. -->
+
+# Task {id}: {title}
+
+## Outcome
+
+[Describe the observable result this task must produce.]
+
+## Required context
+
+- `[project-relative reference]` — [why it is required]
+
+## Execution contract
+
+- Public seam: [reachable entry point or observable boundary]
+- Verification command: `[exact deterministic command]`
+- Documentation impact: [required paths or a specific no-change rationale]
+
+## Constraints
+
+- [Confirmed constraint with its evidence source]
+
+## Acceptance evidence
+
+- [Expected behavior and the evidence that will verify it]
+
+## Traceability
+
+- Change: [change id or initial baseline]
+- Specification: [project-relative section reference]
+
+## Completion evidence
+
+- Commit: [verified commit when applicable]
+- Tests: [command and result]
+- Summary: [delivered behavior]

package/.ultra-template/tasks/tasks.json

@@ -0,0 +1,6 @@
+{
+  "schema_version": "4.5",
+  "generated_at": "1970-01-01T00:00:00.000Z",
+  "source": ".ultra/state.db",
+  "tasks": []
+}

package/CHANGELOG.md

@@ -7,6 +7,96 @@ 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
+
+- Fixed the published project scaffold so its task projection and neutral context
+  template are tracked on fresh checkouts instead of being hidden by a broad ignore
+  rule; the seed projection now uses the authoritative v4.5 state contract.
+
+## [0.12.0] — 2026-07-18
+
+### Added
+
+- Added schema 11.0 project baselines and four `baseline.*` MCP contracts for
+  greenfield initialization, brownfield adoption, evidence recording, explicit
+  approval, re-adoption history, and archive reconciliation.
+- Added automatic new/existing repository detection, neutral baseline templates,
+  metadata-only provider references, and cross-host baseline status/doctor output.
+
+### Changed
+
+- Reclassified file count, token estimate, and context-share limits as advisory
+  attention warnings. Necessary incident context and active work are no longer
+  rejected or repaired by arbitrarily raising a threshold.
+- Made incomplete or stale baseline state advisory during an active bounded change,
+  requiring approved adoption at `change.converge` and complete revision/spec
+  reconciliation in the atomic archive transaction.
+- Changed the Stop hook from a workflow-completion denial into a lifecycle advisory;
+  direct writes to the authoritative task projection remain blocked.
+
+### Fixed
+
+- Prevented old projects from being initialized as empty greenfield products or
+  using generated `tasks.json` as project metadata authority.
+- Updated Claude Code, Codex, OpenCode, and Kimi presentation so hooks expose
+  warnings without turning them into edit, stop, or workflow refusal gates.
+- Removed the convergence deadlock where normal HEAD or tracked-spec changes made by
+  the active change were rejected before archive could reconcile them; incomplete
+  archive declarations now fail with full state and artifact rollback.
+
 ## [0.11.0] — 2026-07-18
 
 ### Added
@@ -451,7 +541,10 @@ 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.11.0...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
 [0.10.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.8.1...v0.9.0

package/README.md

@@ -8,7 +8,7 @@ authoritative `.ultra/state.db`.
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-0.11.0-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)
@@ -27,7 +27,7 @@ authoritative `.ultra/state.db`.
   Install and uninstall are symmetric on every supported host; `ubp --doctor`
   verifies the installed asset hashes and host entry points without mutation.
 - **Shares state across runtimes.** `.ultra/state.db` (SQLite + WAL) is the
-  authoritative source for changes, tasks, sessions, events, incidents,
+  authoritative source for baselines, changes, tasks, sessions, events, incidents,
   projection jobs, and telemetry. `tasks.json` and context markdown are
   generated projections, not handwritten.
 - **Keeps memory ownership explicit.** Ultra Builder Pro does not collect
@@ -37,12 +37,17 @@ authoritative `.ultra/state.db`.
   `.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
-  references and fresh-context budget, exposes one DB-derived breadcrumb, and
+  references, reports fresh-context budget pressure as advisory warnings, exposes one DB-derived breadcrumb, and
   routes a single next action. `/ultra-deliver` requires applied specification
   learning plus docs/test/two-axis review evidence before archive. `/ultra-doctor` reports incidents,
   projection lag, orphan sessions, and backup-first mechanical recovery.
   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`
+  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.
@@ -82,6 +87,14 @@ install or update.
 See [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.md)
 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. 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
 
 | Layer | Purpose | When it's used |
@@ -93,7 +106,7 @@ for per-runtime capabilities.
 The layers share one `.ultra/state.db`, but the CLI is not a mirror of every MCP
 tool: continuous change mutations are MCP-only and fail closed. See
 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the full contract and
-[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 32 live contracts.
+[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 36 live contracts.
 Review, impact discovery, skill resolution, and user interaction stay on each
 Host's native surfaces; the generated Codex capability map documents those
 replacements without advertising non-existent MCP tools.
@@ -121,11 +134,15 @@ Full details in [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.m
 ## Typical workflow
 
 ```bash
-# 1. Initialize a project (writes .ultra/ skeleton and initializes state.db)
-ultra-tools task init-project --name myapp
+# 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. Turn a PRD into a task graph + execution plan (human-gate via dry-run)
-#    (invoked by /ultra-plan skill or via MCP task.parse_prd + plan.export)
+# 2. Record and converge the greenfield/brownfield baseline, then turn accepted
+#    behavior into a task graph (normally driven by ultra-init/research/plan)
 
 # 3. Run the plan — parallel sessions, auto-merge back to main on success
 ubp-orchestrator run
@@ -138,7 +155,7 @@ ultra-tools system doctor
 ```
 
 Or let the skills drive it. In Codex, invoke
-`$ultra-builder-pro:ultra-plan` → `$ultra-builder-pro:ultra-dev` →
+`$ultra-builder-pro:ultra-init` → `$ultra-builder-pro:ultra-plan` → `$ultra-builder-pro:ultra-dev` →
 `$ultra-builder-pro:ultra-test` → `$ultra-builder-pro:ultra-review` →
 `$ultra-builder-pro:ultra-deliver`; after the baseline is delivered, daily work
 starts with `$ultra-builder-pro:ultra-change`, while
@@ -196,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

package/adapters/_shared/codex-assets.cjs

@@ -400,7 +400,7 @@ function buildHooksManifest() {
         { hooks: [commandHook('workflow_resume.py', 10, 'Restoring Ultra workflow checkpoint')] },
       ],
       Stop: [
-        { hooks: [commandHook('pre_stop_check.py', 5, 'Checking Ultra completion gates')] },
+        { hooks: [commandHook('pre_stop_check.py', 5, 'Reporting Ultra workflow position')] },
       ],
       SubagentStart: [
         { hooks: [commandHook('subagent_tracker.py', 5, 'Tracking Ultra subagent', 'start')] },

package/adapters/_shared/handbook.cjs

@@ -59,12 +59,13 @@ function renderHandbook(runtime) {
     `- Workflow entry points: ${value.invocation}.`,
     `- 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 changes, tasks, sessions, events, incidents, projection state, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
-    '- Context Spine boundary: `change.context` compiles role/gate readiness, bounded references, fresh-context budget, public seam, verification command, and one next action. Hooks inject only the DB-derived `change.breadcrumb`; stale or blocked context must be recompiled.',
+    '- 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` 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; projection protection is always authoritative, while edit/compact/stop/subagent enforcement remains 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.',
+    '- 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. 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/tests/handbook.test.cjs

@@ -34,6 +34,10 @@ test('renders one common contract with host-native invocation syntax', () => {
     assert.match(rendered, /ultra-doctor/);
     assert.match(rendered, /metadata references/);
     assert.match(rendered, /Context Spine boundary/);
+    assert.match(rendered, /budgets are advisory attention signals/);
+    assert.match(rendered, /blocks change convergence/);
+    assert.match(rendered, /health-checked atomically at archive/);
+    assert.match(rendered, /never traps session stop/);
     assert.match(rendered, /change\.breadcrumb/);
     assert.match(rendered, /Specification learning boundary/);
     assert.doesNotMatch(rendered, /\.ultra\/memory|memory\.retain|memory\.recall/);

package/adapters/opencode.js

@@ -345,11 +345,14 @@ function findUltraContext(directory) {
           const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
           if (manifest?.change) {
             const compiledHead = manifest.git?.head ?? null;
-            const legacyContext = manifest.schema_version !== "2.0";
+            const legacyContext = manifest.schema_version !== "2.0" || !manifest.baseline;
             const headStale = Boolean(compiledHead && currentHead && compiledHead !== currentHead);
             const blockers = Array.isArray(manifest.readiness?.blockers)
               ? [...manifest.readiness.blockers]
               : [];
+            const warnings = Array.isArray(manifest.readiness?.warnings)
+              ? [...manifest.readiness.warnings]
+              : [];
             if (headStale && !blockers.includes("CONTEXT_HEAD_STALE")) blockers.push("CONTEXT_HEAD_STALE");
             if (legacyContext && !blockers.includes("CONTEXT_SNAPSHOT_UPGRADE_REQUIRED")) {
               blockers.unshift("CONTEXT_SNAPSHOT_UPGRADE_REQUIRED");
@@ -367,6 +370,8 @@ function findUltraContext(directory) {
               : (manifest.next_action ?? "Inspect Ultra status."),
             readiness: legacyContext || headStale ? "blocked" : (manifest.readiness?.status ?? "ready"),
             blockers,
+            warnings,
+            baseline: manifest.baseline ?? null,
             taskId: manifest.selected_task?.id ?? manifest.resume?.task_id ?? null,
             taskStatus: manifest.selected_task?.status ?? manifest.resume?.task_status ?? null,
             tokenEstimate: manifest.context?.token_estimate ?? 0,
@@ -411,6 +416,7 @@ function contextText(active) {
       \`Gate: \${change.gate}\`,
       \`Readiness: \${change.readiness}\`,
       ...(change.blockers.length > 0 ? [\`Blockers: \${change.blockers.join(", ")}\`] : []),
+      ...(change.warnings.length > 0 ? [\`Warnings: \${change.warnings.join(", ")}\`] : []),
       \`Next: \${change.nextAction}\`,
       \`Context manifest: \${change.manifestPath}\`,
     );
@@ -422,7 +428,7 @@ function contextText(active) {
     lines.push(
       "[Ultra baseline]",
       \`Project: \${active.root}\`,
-      "No active continuous change. Start daily work with the ultra-change workflow.",
+      "No active continuous change. Run ultra-status; resume ultra-init when the baseline is missing, incomplete, or stale, otherwise start ultra-change.",
     );
   }
   lines.push("Authority: .ultra/state.db; JSON/Markdown remain projections or evidence artifacts.");

package/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');
@@ -245,8 +246,8 @@ test('plugin declares current Codex hooks and a project-local Ultra MCP server',
     const liveSpec = yaml.load(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'mcp-tools.yaml'), 'utf8'));
     const upstreamSpec = yaml.load(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'upstream-mcp-tools.yaml'), 'utf8'));
     const capabilityMap = JSON.parse(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'codex-capability-map.json'), 'utf8'));
-    assert.equal(liveSpec.tools.length, 32);
-    assert.equal(upstreamSpec.tools.length, 32);
+    assert.equal(liveSpec.tools.length, 36);
+    assert.equal(upstreamSpec.tools.length, 36);
     assert.deepEqual(upstreamSpec.tools.map((tool) => tool.name).sort(), liveSpec.tools.map((tool) => tool.name).sort());
     assert.deepEqual(capabilityMap.live_mcp_tools.sort(), liveSpec.tools.map((tool) => tool.name).sort());
     assert.equal(Object.keys(capabilityMap.codex_native_replacements).length, 9);
@@ -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 };