ultra-builder-pro-cli 0.21.1 → 0.23.0

package/skills/ultra-change/SKILL.md

@@ -3,97 +3,45 @@ 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`, `baseline.get`, active changes, breadcrumb `accepted_intent`,
-   decisions, and `change.breadcrumb`.
-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.
-
-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/decision-dialogue.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 for `change.create` or `change.update`, relevant
+`decision.*`, and `change.delta` when the delta is already known. 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 reopens the draft and makes only genuinely dependent evidence
+stale. `ready` is not an absorbing state. A semantic rejection returns diagnostics;
+repair and retry the same draft. Use `workflow.abandon` only to preserve and cancel an
+attempt intentionally.
+
+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,68 +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, baseline, change, breadcrumb `accepted_intent`, decisions, tasks, test,
-   review, learning, and current checkout.
-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.
-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. 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 `ultra.record` batch for the reconciliation, report artifact, learning
+resolutions, and other durable 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;
+- completes the durable delivery checkpoint;
+- 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,87 +5,48 @@ 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.
+The model owns code reasoning and edits. Ultra owns the durable task contract, current
+Context Manifest, execution lease, evidence references, and checkpoint.
 
-## Bind and resume
+## Bind execution
 
-1. Read doctor, breadcrumb `accepted_intent`, active decisions, task contract,
-   dependencies, dev runs, sessions, HEAD, and worktree.
-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.
+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: admission }`, then
+   `ultra.session { action: acquire }`. Work only in the returned worktree.
+4. Confirm purpose, acceptance, dependencies, public seam, verification command,
+   non-goals, recovery, and required context refs. Update the task contract before
+   implementation when accepted intent changed.
 
-Do not spawn recursively from a parent-owned worker session. Process exit is transport
-evidence, never task completion.
+## Implement adaptively
 
-## Focused inner loop
+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.
 
-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. Create the authorized local task commit. Do not push, publish, tag, or deploy unless
-   the user separately authorized that external effect.
+Use `ultra.record` batches for task status, bounded events, artifacts, decisions, and
+documentation candidates. 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.
 
-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.
+Run focused and adjacent risk-justified checks, then a task-scoped independent review.
+Fix blocking findings and refresh affected evidence.
 
-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.
+## Commit one semantic checkpoint
 
-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.
+Call `ultra.checkpoint` once with `stage: dev`, the exact Change/Task scope, evidence,
+and stable idempotency key. It compiles or reuses the implementation Context Manifest
+and validates the durable outcome. A rejection leaves the draft mutable.
 
-## Complete or recover
+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.
 
-In direct mode, integrate the task commit through the repository's accepted path,
-verify ancestry and the public seam, close the session, update the task to `completed`,
-record `record-completion`, and complete the dev workflow.
+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.
 
-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.
+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,54 +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.
+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.
 
-## Read-only diagnosis
+## Diagnose
 
-Run `system.doctor` without repair and inspect:
+Call `ultra.doctor { repair: false }` 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;
-- projection jobs and event cursors;
-- sessions, preserved worktrees, incidents, circuit state, and archive journals;
-- external provider boundaries.
+- 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 or awaiting user decision is a warning, not corruption.
-Missing or changed required evidence is an authority failure but cannot be reconstructed
-by doctor.
+An expected workflow pause, editable draft, failed semantic checkpoint, or awaiting
+owner decision is a warning, not corruption.
 
-## Recovery boundary
+## Repair
 
-With explicit repair authorization, `system.doctor` may:
+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.
 
-- 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 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 and
+`workflow.abandon` through `ultra.record` for intentional draft cancellation.
 
-It may not create a Git checkpoint, replace a healthy baseline, accept known failures,
-resolve decisions, regenerate semantic content, or edit application code.
+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.
 
-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.
-
-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.
+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.

package/skills/ultra-init/SKILL.md

@@ -1,85 +1,53 @@
 ---
 name: ultra-init
-description: Create or recover Ultra project authority for a new repository, an existing codebase, or an older Ultra installation. Use when `.ultra` is absent, initialization is incomplete, or doctor reports a migration or initialization fault.
+description: Create or recover Ultra project authority for a new repository, an existing codebase, or an older Ultra installation. Use when `.ultra` is absent, initialization is incomplete, or doctor reports a migration fault.
 ---
 
 # Initialize project authority
 
-Initialization is a bounded setup capability. It creates or repairs the repository and
-Ultra authority; it does not perform product research, approve a baseline, or choose
-the next semantic workflow.
+Initialization creates the repository-local Ultra authority. It does not perform
+research, accept a product baseline, choose a Change, or start another public
+capability.
 
-## Inspect before mutation
+## Inspect and align
 
-1. Identify the repository root, existing `.ultra` state, Git state, meaningful source,
-   monorepo boundaries, and current owner request.
-2. If `.ultra/.runtime/state.db` exists, run `system.doctor` read-only and resume with
-   `task.init_project` only when its report permits it.
-3. Otherwise call `task.init_project` with `mode: "auto"`, the project name, and an
-   explicit scope only when the repository contains multiple plausible roots.
-4. Leave `git_mode` as `auto` unless the user explicitly requires a non-Git workspace.
+1. Inspect the repository root, Git state, meaningful source, existing `.ultra`,
+   monorepo boundaries, and the current request.
+2. When authority already exists, call `ultra.doctor { repair: false }` and preserve
+   healthy state. Never replace or delete it merely to obtain a clean init.
+3. Classify the repository from evidence:
+   - `greenfield`: no meaningful delivered behavior exists;
+   - `brownfield`: source, runtime, API, data, deployment, or tests describe an
+     existing maintained system;
+   - `migrated`: older Ultra authority was preserved but is not yet a trusted baseline.
+4. Ask the owner only when scope, healthy-authority replacement, destructive recovery,
+   or another material choice cannot be derived. Reuse explicit intent.
 
-Use repository evidence to classify:
+Read `../ultra-think/references/decision-dialogue.md` before asking a material
+question.
 
-- `greenfield`: no meaningful delivered application behavior is present;
-- `brownfield`: source, runtime, API, data, deployment, or tests describe an existing
-  maintained system;
-- `migrated`: older Ultra authority was preserved but is not a trusted baseline.
+## Initialize once
 
-The model may override an automatic classification only with evidence or an explicit
-user decision. Classification must not infer product scope, an MVP, or a release plan.
+Call `ultra.record` with one entry:
 
-## Interaction boundary
+```text
+operation: task.init_project
+data: target_dir, project_name, mode=auto, git_mode=auto, optional scope
+idempotency_key: stable init attempt id
+```
 
-Read `../ultra-think/references/decision-dialogue.md` before asking a material question.
-Inspect observable facts yourself. Use the host's native question UI when available and
-plain direct interaction otherwise. Ask only when repository scope, replacement of
-healthy authority, destructive recovery, or another material owner decision is truly
-unresolved. Normalize clear intent already present in the request without asking again.
+This stateless bootstrap is the only `ultra.record` operation allowed before
+`state.db` exists. It must create or migrate `.ultra/.runtime/state.db`, preserve
+existing artifacts and Git history, install only missing scaffold assets on resume,
+validate or safely upgrade a legacy task ledger, and read back the result.
 
-## Deterministic initialization contract
+An unborn Git repository may require a local initial commit, but init never creates a
+remote, tag, push, publish, or deployment. Corrupt DB/WAL/SHM and backups remain
+preserved until an explicit recovery choice is made.
 
-`task.init_project` owns these steps:
+## Return control
 
-1. `inspect-authority`
-2. `classify-repository`
-3. `scaffold-authority`
-4. `verify-initialization`
-
-The operation must:
-
-- create or migrate `.ultra/.runtime/state.db` with a backup before schema migration;
-- install only missing scaffold assets on resume;
-- preserve existing artifacts and unrelated work;
-- preserve an existing Git repository and HEAD;
-- initialize Git and a safe `.gitignore` entry when Git is absent;
-- report an unborn repository as `initial_commit_required` without manufacturing a
-  commit, remote, tag, or push;
-- read back the created DB, classification, projection, and Git result before
-  completing the init workflow.
-
-Projection-only projects must use the exact backup-first migration command returned by
-the runtime. A migrated compatibility baseline requires a new brownfield adoption with
-`replace_migrated: true`. Replacing a healthy baseline requires explicit replacement
-authority. Corrupt DB, WAL, SHM, and backups must be preserved until the user chooses a
-documented recovery operation.
-
-## Completion and handoff
-
-Initialization is complete when the init workflow is `completed`, the current schema is
-healthy, the scaffold is readable, and repository classification and Git state are
-durable. Research status may still be `not_started`; that is not incomplete init.
-
-Read the returned `allowed_transitions` and `required_transition`:
-
-- a required transition represents a hard recovery invariant and must be followed;
-- otherwise the host model recommends among the allowed capabilities using the user's
-  goal and current evidence;
-- never invoke another public Ultra workflow automatically; recommend the best allowed
-  capability and wait for an explicit user invocation.
-
-Report classification, scope, schema and backup result, Git state, init workflow id,
-baseline state, and allowed transitions. Do not claim that a baseline is ready until a
-separate research/adoption workflow has recorded and converged it.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+Report classification, scope, schema and backup result, Git state, imported team
+checkpoint state, and any mechanical blocker. Recommend the next useful capability
+from current evidence, usually `ultra-research`, `ultra-change`, `ultra-status`, or
+`ultra-doctor`; do not invoke it automatically.