ultra-builder-pro-cli 0.22.0 → 0.24.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.22.0",
-  "description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, and Kimi Code, with project-local MCP authority and lifecycle recovery.",
+  "version": "0.24.0",
+  "description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, and Grok Build, with a project-local MCP persistence and safety kernel.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
     "ubp": "bin/install.js",
@@ -61,13 +61,19 @@
     "!**/*.pyo",
     "!**/*.test.cjs",
     "!**/tests/**",
-    "!mcp-server/test-support/**"
+    "!mcp-server/test-support/**",
+    "!mcp-server/lib/workflow-state.cjs",
+    "!mcp-server/lib/decision-dialogue.cjs",
+    "!mcp-server/lib/context-spine.cjs",
+    "!mcp-server/lib/project-breadcrumb.cjs",
+    "!mcp-server/lib/spec-learning.cjs"
   ],
   "keywords": [
     "claude-code",
     "opencode",
     "codex",
     "kimi-code",
+    "grok-build",
     "agent",
     "cli",
     "multi-runtime",
@@ -101,6 +107,7 @@
     "prepublishOnly": "npm run verify:release",
     "install:claude": "node bin/install.js --claude --local",
     "install:kimi": "node bin/install.js --kimi --local",
+    "install:grok": "node bin/install.js --grok --local",
     "install:all": "node bin/install.js --all --local"
   },
   "dependencies": {

package/skills/ultra-change/SKILL.md

@@ -3,105 +3,46 @@ name: ultra-change
 description: Capture or revise one bounded feature, fix, redesign, or incident contract against a ready Ultra baseline. Use when post-baseline work needs accepted intent before research, planning, or implementation.
 ---
 
-# Capture accepted change intent
+# Capture accepted Change intent
 
-Change is the durable unit that connects later research, plan, implementation,
-verification, review, and baseline reconciliation. Capturing a change does not start
-those workflows or compile execution context.
-
-Read `../ultra-think/references/decision-dialogue.md` before asking a material question.
+A Change is the durable unit connecting research, plan, implementation, verification,
+review, documentation, and delivery. Its draft stays editable until a semantic
+checkpoint accepts the downstream authority.
 
 ## Inspect and align
 
-1. Read `system.doctor`, `task.ledger_get`, `baseline.get`, active changes, breadcrumb
-   `accepted_intent`, decisions, and `change.breadcrumb`. Import a newer descendant
-   checkpoint before capturing intent. Stop on a typed baseline, Change, task,
-   ancestry, or active-session conflict.
-2. Resume an existing change that matches the request. Do not duplicate authority.
-3. Ordinary work requires a healthy ready baseline. An incident may use only an
-   explicit `baseline_bypass` reason and approver; urgency is not approval.
-4. Inspect the checkout and accepted baseline before asking the user. Resolve code and
-   runtime facts yourself.
-5. Convert the request into a Change Contract:
-   - observable outcome and executable acceptance;
-   - non-goals and public seams;
-   - recovery strategy and verification;
-   - unresolved material decisions;
-   - documentation impact;
-   - change kind and evidence-backed risk flags;
-   - research disposition.
-
-Recommend `quick`, `standard`, `major`, or `incident` from actual scope and risk,
-together with the research disposition. A quick change may have no material risk,
-research obligation, or more than one task. MCP may reject a profile that contradicts
-hard risk invariants; it does not choose a replacement.
-
-After `change.create` or `change.update`, read back the complete Change Contract. When
-that write applies a durable decision, complete the decision thread with the change
-reference in `applied_refs`.
-
-Ask only when a choice changes accepted product intent, scope, public behavior,
-compatibility, security, material cost, external effects, or recovery. Use the host's
-native question UI when available. Normalize clear choices already in the user's
-request. When profile or research posture remains unresolved, present the recommended
-route and credible alternatives through that same UI, then stop. The user selects,
-modifies, delegates, or defers the semantic route. The model owns reversible
-implementation detail inside the accepted contract.
-
-## Persist the contract
-
-When a durable alignment checkpoint is necessary, bind it to a compact artifact and
-pass its id as `alignment_thread_id`. Do not require a checkpoint for a complete,
-unambiguous request that already provides current authority.
-
-Call `change.create`. It records and completes exactly:
-
-1. `bind-baseline`
-2. `classify-change`
-3. `record-intent`
-
-The returned change workflow must be `completed`; research, plan, context, dev, test,
-review, and deliver remain independent capabilities. Keep every Change-owned semantic
-artifact, finding, plan, context, test result, review result, documentation update,
-and progress projection below `.ultra/changes/active/<id>/`. Incidents maintain the
-structured diagnosis artifact there as well.
-
-`change.create` and `change.update` publish the portable Change Contract to
-`.ultra/tasks/tasks.json`, even before the Change owns tasks. The tracked Change
-artifacts carry semantic bodies; the checkpoint carries normalized baseline, Change,
-and task records with digest ancestry. Never edit either generated checkpoint or
-checkout-local projection directly.
-
-Before planning a standard or major change, write the accepted specification updates
-to the Change overlay and call `change.delta` with exact baseline id, repository
-revision, specification digests, decisions, non-goals, acceptance, documentation
-impact, unknowns, and mutation before/after digests. If accepted behavior truly does
-not change baseline semantics, record an empty typed delta with a specific
-`no_semantic_change_reason`; do not manufacture a mutation. Read back the registered
-delta and deterministic `progress.md`. This records proposed authority only and must
-not edit baseline specifications.
-
-Use `change.update` when accepted intent or evidence changes. Update the Change
-Contract, classification, research disposition, and docs impact together when their
-meaning is coupled. Downstream task, context, test, or review evidence affected by that
-change must become stale and be regenerated; never keep old evidence green by prompt
-assertion.
-
-If research is required, recommend `ultra-research` with the recorded disposition. If
-the contract is sufficiently evidenced, finish the typed delta and recommend
-`ultra-plan`. Direct Build skips Research only; it never skips Plan, DB-backed task
-contracts, or fresh task context. Return and wait for an explicit user invocation; do
-not start another workflow. `change.context` is compiled only for an actual plan,
-implementation, test, or review consumer.
-
-Stable implementation discoveries use the approval-gated specification-learning
-transitions. External memory and graph providers retain their own content; Ultra stores
-metadata references only.
-
-Return the normalized contract, change id and kind, research disposition, blockers,
-and `allowed_transitions`. Recommend a semantic next action from those transitions.
-If current intent does not already select it, present the recommendation and credible
-alternatives through the interaction protocol, then wait. MCP does not encode a
-semantic next action.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+1. Call `ultra.context { stage: project, detail: full }`.
+2. Inspect or import the team checkpoint with `ultra.sync`. Stop only on a real
+   baseline, Change, task, ancestry, or active-session conflict.
+3. Reuse an existing matching Change. Do not duplicate authority.
+4. Convert the request into observable outcome, executable acceptance, non-goals,
+   public seams, recovery, verification, documentation impact, risk, and research
+   disposition.
+5. Recommend `quick`, `standard`, `major`, or `incident` from evidence. Ask only when
+   a choice changes accepted product intent, compatibility, security, material cost,
+   external effects, or recovery.
+
+Read `../ultra-think/references/interaction-boundary.md` before asking. MCP may report
+contradictory risk fields, but the model and owner choose the semantic correction.
+
+## Record the contract
+
+Use one `ultra.record` batch with `change_contract / open` or
+`change_contract / revise`, relevant `decision / accept`, and `artifact / bind` for
+an already-known typed delta. Every entry carries a stable idempotency key. Read the
+result through `ultra.context`.
+
+Keep every Change-owned semantic artifact below
+`.ultra/changes/active/<change-id>/`. Standard and major Changes require a typed delta
+before planning. A true no-semantic-change case records an explicit reason instead of
+manufacturing a mutation.
+
+Changing accepted intent creates a new accepted checkpoint revision and makes only
+genuinely dependent evidence stale. Readiness is derived, not a stored absorbing
+state. A semantic rejection returns diagnostics; repair and retry the same draft.
+Use `change_contract / cancel` only when the owner intentionally abandons the Change.
+
+Publish the durable Change contract with `ultra.sync { action: publish }` when it is a
+useful team handoff. Recommend bounded `ultra-research` for a real evidence gap or
+`ultra-plan` when the contract is sufficiently evidenced. Do not invoke the next
+capability automatically.

package/skills/ultra-deliver/SKILL.md

@@ -1,71 +1,48 @@
 ---
 name: ultra-deliver
-description: Converge a verified Ultra change, reconcile baseline specifications, and archive it with recoverable local evidence. Use when implementation, testing, and review are current.
+description: Converge a verified Ultra Change, reconcile baseline specifications, and archive it with recoverable local evidence. Use when implementation, testing, and review are current.
 ---
 
 # Converge and archive local authority
 
-Delivery closes Ultra's local change authority. It does not grant or perform commit,
-push, tag, registry publication, deployment, or another external effect.
-
-## Bind current evidence
-
-1. Read doctor, `task.ledger_get`, baseline, change, breadcrumb `accepted_intent`,
-   decisions, tasks, test, review, learning, and current checkout. Import a newer
-   descendant checkpoint before convergence; stop on any typed merge conflict.
-2. Resume or start a deliver workflow bound to the change and baseline.
-3. Require complete task evidence, a current test report, both review axes, current
-   context, and resolved material decisions. Record `bind-evidence`.
-
-Evidence from another revision, task set, or change is invalid.
-
-## Reconcile specifications
-
-Resolve every specification-learning candidate. Apply approved learning to its target
-inside the Change overlay; preserve rejection reasons. Read the current registered
-`change.delta` and verify every baseline anchor, payload digest, acceptance reference,
-and unknown.
-
-Write documentation updates below
-`.ultra/changes/active/<change-id>/documentation/`. Call
-`change.documentation_reconcile` for every Change: bind the current delta id and
-digest, exact before/after document digests, delta and acceptance references,
-verification, and each verified consumer. When no documentation changes, record an
-empty reconciliation with a specific `no_change_reason`. An unexplained orphan
-document is blocking. Record `reconcile-specifications`.
-
-Compile final convergence context and run the risk-selected candidate checks, install
-or doctor smoke when this change modifies distributed assets, public-seam verification,
-and recovery sanity. Record the immutable context under `verify-candidate`.
-
-Call `change.converge`; MCP derives readiness from durable dev, test, review,
-typed delta, documentation reconciliation, diagnosis, and current checkout evidence.
-Successful convergence publishes the current portable team checkpoint.
-Record
-`converge-authority` only when ready.
-
-Call `change.archive` with the summary. MCP preflights all target before states and
-overlay digests, applies the complete packet atomically, refreshes baseline authority,
-rebinds every registered artifact into the self-contained archive, and rolls back or
-resumes from its transaction journal after interruption. A partial success is not
-delivery. Archive publication refreshes the checkpoint with the archived Change and
-new baseline summary. Verify the refreshed baseline and archived packet, then record
-`archive-change`.
-
-Write `<archived-change-root>/delivery/<workflow-id>/report.json` with
-`ultra-delivery-report-v1`: archived change, baseline, HEAD, worktree and context
-digests, local checks, rollback notes, and timestamp. The report must not contain a
-release decision. Record it under `verify-delivery` and complete the workflow.
-
-## External effects
-
-If the user separately requests commit, push, tag, publish, or deploy, handle that as a
-host-owned effect after Ultra delivery. Confirm only missing material authority, run
-the repository's release checks, and report remote evidence separately. Never infer an
-external effect from `ultra-deliver`, and never encode it as completed Ultra delivery
-state.
-
-Return archive and baseline state, evidence digests, recovery notes, residual risks,
-and allowed transitions.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+Delivery closes local Ultra authority. It never grants commit, push, tag, registry
+publication, deployment, or another external effect.
+
+## Prepare the packet
+
+1. Call `ultra.context { stage: deliver, scope: { change_id }, detail: full }`.
+2. Import a newer team checkpoint with `ultra.sync`; stop on a real conflict.
+3. Require current task outcomes, test report, both review axes, accepted decisions,
+   typed delta, documentation reconciliation, and current checkout evidence.
+4. Resolve every specification-learning candidate. Keep updates inside the Change
+   overlay until archive.
+5. Write and register documentation reconciliation and an
+   `ultra-delivery-report-v1` report. The report binds Change, baseline, HEAD,
+   worktree/context digests, local checks, rollback guidance, and timestamp; it contains
+   no release decision.
+
+Use one typed `ultra.record` batch for `artifact / bind`, any normalized
+`decision / accept`, and bounded `event / append` facts.
+
+## Archive once
+
+Call `ultra.archive` once with the Change id, stable idempotency key, archive summary,
+reconciliation fields, delivery evidence steps, and report output. The operation
+internally:
+
+- compiles or reuses convergence context;
+- checks the deliver draft;
+- derives convergence from current dev, test, review, delta, docs, and checkout;
+- applies the overlay and archive through the recoverable filesystem/DB transaction;
+- rebinds registered artifacts into a self-contained archive;
+- accepts one immutable delivery checkpoint revision;
+- publishes the updated team checkpoint.
+
+A semantic rejection returns mutable blockers. Repair the same packet and retry. A
+hard corruption, path, concurrency, or recovery error remains fail-closed and routes to
+`ultra-doctor`.
+
+Verify the archived packet, baseline, checkpoint, and rollback state. Handle any
+separately authorized Git or release effect only after local delivery and report it as
+external evidence, not Ultra delivery authority. Do not invoke another capability
+automatically.

package/skills/ultra-dev/SKILL.md

@@ -5,102 +5,55 @@ description: Implement one authoritative Ultra task through a fresh-context, tes
 
 # Implement one task
 
-The host model owns code reasoning and edits. Ultra owns the task and workflow state,
-fresh context contract, session lease, evidence references, and recovery.
-
-## Bind and resume
-
-1. Read doctor, `task.ledger_get`, breadcrumb `accepted_intent`, active decisions, task
-   contract, dependencies, dev runs, sessions, HEAD, and worktree. Import a newer
-   descendant team checkpoint before taking a lease. Stop on a typed baseline, Change,
-   task, ancestry, or active-session conflict; do not merge authority by editing JSON.
-2. Resume the matching dev run or start one with `change_id` and `task_id`.
-3. Record `bind-task` with current authority and dependency evidence.
-4. Compile `change.context` with `role: implement` and `gate: implementation`. The
-   public seam, verification command, and context refs come from the DB-backed task
-   contract; update that contract before compilation instead of overriding it in the
-   call. Persist any changed external-provider metadata with `change.update` first.
-   Context compilation itself is read-only with respect to Change and provider
-   authority.
-5. Confirm the manifest contains the selected task, its direct dependencies, direct
-   dependents needed for integration, and relevant integration checkpoints—not the
-   entire task graph. Referenced file bodies stay lazy. The token estimate includes
-   inline Change/task authority as well as file estimates; budget overflow is
-   advisory, while a missing or stale required reference is blocking. Record the
-   immutable manifest as `compile-context`.
-6. Reuse an existing valid session. Otherwise pass admission and call `session.spawn`.
-   Work only in the returned worktree and preserve unrelated changes.
-
-Do not spawn recursively from a parent-owned worker session. Process exit is transport
-evidence, never task completion.
-
-## Focused inner loop
-
-1. Reproduce the bug, write a failing test, or establish a characterization signal
-   before a logic change. Record `establish-feedback-loop`.
-2. Mark the task `in_progress` and implement the smallest complete slice through the
-   declared public seam.
-3. Keep the loop adaptive. The model may choose implementation details inside the
-   accepted contract. If new evidence changes product intent, compatibility, security,
-   material cost, external effects, or recovery, use the host's native question UI and
-   the decision protocol; do not ask about ordinary reversible details.
-4. Record `implement-slice`, then run focused tests plus the adjacent checks justified
-   by the task risk. Record exact results under `verify-slice`.
-5. Run a task-scoped independent review on specification fidelity and relevant
-   engineering risks. Record `review-slice`. Fix blocking findings and refresh affected
-   evidence.
-6. In direct mode, update the task to `completed` only after verification and review
-   are current. This publishes the durable team ledger checkpoint. Create one
-   authorized local task commit containing code, semantic artifacts, and that
-   checkpoint. Read the resulting `HEAD`, then record it as `completion_commit`;
-   that hash remains checkout-local and must not create another Git commit. Do not
-   push, publish, tag, or deploy unless the user separately authorized that external
-   effect.
-
-The tracked team checkpoint contains durable task status and contract evidence, not
-live ownership. `in_progress`, `session_id`, leases, worktrees, telemetry, and
-`completion_commit` remain checkout-local. The local generated task view lives under
-`.ultra/.runtime/projections/` and is never committed.
-
-Treat the compiled task-context contract as the handoff boundary: purpose, why,
-constraints, non-goals, target seams/files, pattern refs, acceptance, documentation
-impact, recovery, and definition of drift. If accepted intent, the task contract, or a
-digest-bound reference changes, update the owning authority and recompile rather than
-continuing from a stale packet.
-
-Keep implementation findings and documentation candidates inside the owning Change
-root. When code changes invalidate or extend maintained documentation, update the
-Change documentation overlay and its evidence rather than editing accepted baseline
-specifications. Hooks may remind the host to reconcile documentation; they must not
-block ordinary development or choose the semantic update.
-
-Task-level tests and review belong to this inner loop. They do not replace aggregate
-change testing or review when multiple slices, integrations, or broader risks require
-those capabilities.
-
-## Complete or recover
-
-In direct mode, integrate the task commit through the repository's accepted path,
-verify ancestry and the public seam, close the session, record `record-completion`,
-and complete the dev workflow. If commit creation fails after the pre-commit
-completion checkpoint, move the still-session-owned task to `blocked`, preserve the
-worktree, and record the failure. A completion with a recorded commit remains
-terminal.
-
-Change convergence revalidates the exact latest
-`change_id + task_id + implement + implementation` snapshot for every executable
-task. A newer review, test, or plan packet cannot substitute for it.
-
-In a parent-supervised worker, record completion evidence and exit without closing the
-parent-owned lease. The primary host verifies the exact session commit, performs any
-integration, refreshes review if the reviewed checkout changed, settles the lease, and
-completes the workflow.
-
-Preserve worktrees by default. Remove one only when Git proves it is clean and
-integrated. On interruption, record the current step and task as blocked, preserve
-worktree and evidence, and resume the same run later.
-
-Return outcome, changed paths, public seam, exact checks, review axes, commit and
-session state, residual risk, and allowed transitions.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+The model owns code reasoning and edits. Ultra owns the durable task contract,
+canonical Context Envelope, execution lease, immutable Worker Packet, evidence
+references, and checkpoint.
+
+## Bind execution
+
+1. Call `ultra.context { stage: dev, scope: { change_id, task_id }, detail: full }`.
+2. Import a newer team checkpoint with `ultra.sync`; stop on a real same-record or
+   active-session conflict.
+3. Reuse a valid lease or call `ultra.session { action: acquire }`. Acquire atomically
+   performs admission, compiles or reuses the implementation Context Envelope, mints
+   the lease/worktree, and returns the immutable Worker Packet. A separate
+   `action: admission` is an optional read-only preview, not a prerequisite.
+4. Verify the returned packet digest, purpose, acceptance, dependencies, public seam,
+   exact output path/schema, verification command,
+   non-goals, recovery, and required context refs. Update the task contract before
+   implementation when accepted intent changed.
+
+## Implement adaptively
+
+Reproduce the failure, write a failing test, or establish a characterization signal
+before changing logic. Implement the smallest complete vertical slice. Ask the owner
+only when new evidence changes product intent, compatibility, security, material cost,
+external effects, or recovery.
+
+Use typed `ultra.record` entries for `task_outcome / start|block|complete`,
+`event / append`, `artifact / bind`, `decision / accept`, and corrected
+`task_contract / revise`. Every worker output must repeat the exact `packet_digest`;
+the parent registers it only after packet, output path, schema, and digest validation.
+Live ownership, `in_progress`, session ids, leases, worktrees, telemetry, and
+completion hashes remain local runtime state; durable task outcome and evidence may
+enter the team checkpoint.
+
+Run focused and adjacent risk-justified checks, then a task-scoped independent review.
+Fix blocking findings and refresh affected evidence.
+
+## Commit one semantic checkpoint
+
+Call `ultra.checkpoint` once with `stage: dev`, the exact Change/Task scope, evidence,
+and stable idempotency key. It binds the exact Context Envelope and Worker Packet and
+reports outcome diagnostics. A rejection leaves the draft mutable.
+
+After acceptance, mark the task durably completed, publish with `ultra.sync`, and
+create at most one authorized local task commit containing code and semantic
+artifacts. Record its SHA only in local state; never create a bookkeeping commit.
+
+Release the lease through `ultra.session`. Preserve a dirty or unintegrated worktree
+on interruption. Commit, push, tag, publish, deploy, or destructive cleanup require
+separate owner authority.
+
+Return changed paths, public seam, exact checks, review result, checkpoint, commit,
+session state, and residual risk. Do not invoke the next capability automatically.

package/skills/ultra-doctor/SKILL.md

@@ -1,63 +1,41 @@
 ---
 name: ultra-doctor
-description: Diagnose and mechanically recover Ultra schema, workflow, projection, session, archive, hook, and installed-asset faults. Use when authority is degraded, stale, contradictory, or unavailable.
+description: Diagnose and mechanically recover Ultra schema, projection, session, archive, hook, and installed-asset faults. Use when authority is degraded, contradictory, or unavailable.
 ---
 
 # Diagnose before repair
 
-Doctor owns deterministic health and supported recovery. It cannot decide product
-scope, invent evidence, approve a baseline, answer a user decision, or mark semantic
-work complete.
-
-## Read-only diagnosis
-
-Run `system.doctor` without repair and inspect:
-
-- SQLite integrity, schema 20 migration, required tables, and backups;
-- artifact registration, ownership, digest freshness, dependency edges, consumers,
-  and orphan or duplicate authority;
-- baseline and research provenance, gaps, digests, and Git/worktree drift;
-- workflow status, obsolete-step migration, blockers, and output freshness;
-- decisions and checkpoint artifact freshness;
-- Git team-checkpoint schema, ancestry, per-baseline, per-Change, and per-task drift,
-  plus checkout-local baseline revalidation requirements;
-- projection jobs and event cursors;
-- sessions, preserved worktrees, incidents, circuit state, and archive journals;
-- external provider boundaries.
-
-An expected workflow pause or awaiting user decision is a warning, not corruption.
-Missing or changed required evidence is an authority failure but cannot be reconstructed
-by doctor.
-
-## Recovery boundary
-
-With explicit repair authorization, `system.doctor` may:
-
-- apply backup-first supported schema migrations;
-- migrate incompatible rigid workflows into recoverable adaptive state;
-- requeue or regenerate projections from healthy DB authority;
-- reconcile orphan sessions without deleting unrelated or dirty worktrees;
-- resume supported archive journals;
-- recover missing workflow provenance as a blocked run requiring real evidence.
-
-It may not create a Git checkpoint, replace a healthy baseline, accept known failures,
-resolve decisions, regenerate semantic content, import or publish the team checkpoint,
-or edit application code. A missing or drifted valid checkpoint is a warning; invalid
-content or conflicting ancestry is degraded authority. Resolve semantic checkpoint
-state explicitly with `task.ledger_import` or `task.ledger_publish` after reviewing
-the typed conflict.
-
-Corrupt SQLite requires preservation of DB, WAL, and SHM followed by an explicit
-restore-or-rebaseline choice. Missing hook adapters or stale cache paths require
-`ubp --doctor` and adapter reinstall; never patch plugin cache contents by hand.
-A legacy task projection is never rewritten by doctor. The supported publication path
-first proves its durable task fields match SQLite and preserves its original bytes in
-the local runtime backup directory.
-
-After repair, rerun doctor read-only and verify backup paths, schema, installed hashes,
-entry points, MCP startup, and hook smoke tests as applicable.
-
-Return health first, failed checks, mechanical repairs performed, preserved recovery
-paths, unresolved owners, and allowed transitions plus any unique required transition.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+Doctor owns deterministic health and supported recovery. It cannot choose product
+scope, invent evidence, accept a baseline, resolve a user decision, or declare
+semantic work complete.
+
+## Diagnose
+
+Call `ultra.doctor { repair: false }` and inspect:
+
+- SQLite integrity, schema, backups, WAL/SHM, and migration state;
+- artifact ownership, digest freshness, edges, orphans, and duplicate authority;
+- team-checkpoint ancestry and real concurrent record conflicts;
+- projection jobs, sessions, leases, worktrees, and recovery journals;
+- installed plugin assets, MCP startup, and hook paths.
+
+An expected workflow pause, editable draft, failed semantic checkpoint, or awaiting
+owner decision is a warning, not corruption.
+
+## Repair
+
+With explicit repair authority, call `ultra.doctor { repair: true }`. It may apply
+backup-first schema migration, regenerate local projections, recover supported
+journals, reconcile orphan sessions, and repair installed mechanical assets.
+
+It may not manufacture semantic evidence, import or publish a team checkpoint, replace
+a healthy baseline, resolve decisions, edit application code, or force a draft to
+accepted. Use `ultra.sync` for reviewed checkpoint import/publish. Doctor never changes
+semantic checkpoint acceptance or Change intent.
+
+Preserve corrupt DB/WAL/SHM and dirty worktrees. Never patch plugin cache files by
+hand; reinstall through `ubp` and verify the installed manifest and hook targets.
+
+Rerun doctor read-only after repair. Report health, exact failed checks, backups,
+repairs, preserved recovery paths, and remaining owner or semantic work. Do not invoke
+another capability automatically.