ultra-builder-pro-cli 0.14.0 → 0.16.0

package/skills/ultra-doctor/SKILL.md

@@ -1,86 +1,65 @@
 ---
 name: ultra-doctor
-description: Diagnose Ultra state, projection, session, incident, change-artifact, and installed-plugin health with bounded recovery. Use when Ultra state appears missing, projections disagree, hooks fail, or MCP operations report degraded health.
+description: Diagnose and recover Ultra DB schema, workflow outputs, projections, sessions, incidents, change artifacts, archives, hooks, and installed host assets. Use when authority is degraded, workflow state disagrees with prompts, outputs are stale, hooks fail, or MCP operations cannot proceed.
 ---
 
-# Diagnose and recover the Ultra runtime
-
-Default to read-only diagnosis. Repair only after the user explicitly authorizes it.
-
-## Project-state diagnosis
-
-Call `system.doctor` with `{ "repair": false }` and inspect:
-
-- SQLite integrity and required tables;
-- open structured incidents;
-- event and projection cursor lag;
-- failed or interrupted projection jobs;
-- interrupted archive journals;
-- orphan sessions;
-- missing active-change artifact roots;
-- missing, incomplete, or stale project baseline readiness and specification digests;
-- the boundary to separately installed memory and code-graph providers.
-
-Do not infer health from generated task JSON. Do not mutate external provider state,
-delete artifacts, or collect memory during diagnosis.
-
-## Interpret failures
-
-- State integrity failure blocks ordinary workflows and requires preserving database
-  evidence before recovery.
-- An open incident requires its code, source, retryability, and evidence.
-- Projection lag may be mechanically repairable when authority is healthy.
-- An orphan session may be reconciled; never kill unrelated processes blindly.
-- A missing change artifact requires version-control, backup, or deliberate recreation
-  evidence rather than silent regeneration.
-- Missing or incomplete baseline evidence routes to `ultra-init`. Doctor repair does
-  not approve a baseline, accept known-red verification, or invent adoption evidence.
-  Baseline readiness is an advisory workflow check, not state-database corruption and
-  not a reason for doctor repair.
-- A compatibility `migrated` baseline requires explicit brownfield re-adoption and
-  cannot authorize ordinary changes.
-- A corrupt SQLite file requires preserving the file, locating a verified backup, and
-  an explicit restore-or-rebaseline decision.
-
-## Explicit repair
-
-After authorization, call `system.doctor` with `{ "repair": true }` or use the
-installed `ultra-tools system doctor --repair` fallback. The CLI applies supported
-schema upgrades to the packaged current schema and reports a pre-migration backup path. Doctor then
-creates a second timestamped backup before runtime recovery.
-
-Repair is limited to documented schema upgrades, archive-journal completion,
-reconciling orphan sessions, consuming staleness events, requeueing interrupted or
-failed projections, and regenerating projections from authoritative state. If either
-backup fails, stop. Always inspect the post-repair report; a completed repair action
-does not imply healthy state.
-
-If SQLite integrity prevents doctor from opening authority, preserve the original
-database, WAL, and SHM. After the owner chooses a recovery path, either run
-`ultra-tools system restore --backup <managed-backup> --confirm
-REPLACE_CORRUPT_ULTRA_STATE` or run `ultra-tools system rebaseline --project-name
-<name> [--scope <path>] --confirm REBASELINE_CORRUPT_ULTRA_STATE`. Both commands
-must report the recovery backup directory. A failed command must restore the
-original authority, sidecars, and task projection before returning an error.
-
-## Installed-plugin failures
-
-When a hook points to a missing installed file:
-
-1. Capture the hook manifest path and missing target.
-2. Run the installer doctor for the actual host and install scope.
-3. Preserve provenance, asset-hash, and host-contract findings.
-4. Reinstall through the host adapter rather than patching a cache directory.
-5. Rerun installer doctor, `system.doctor`, and a host hook smoke test.
-
-Project doctor covers `.ultra/state.db`; installer doctor covers packaged files and
-host wiring. Neither substitutes for the other.
-
-## Output
-
-Lead with `healthy` or `degraded`. List failing authority checks separately from
-baseline warnings, incident identifiers, cursor lag, whether repair ran, the backup
-path, and each unresolved action with its owner.
-
-Do not fix application code, delete state, reset Git, close healthy sessions, or
-install and repair external providers through this workflow.
+# Diagnose before repair
+
+Default to read-only diagnosis. Call `system.doctor` with repair disabled and inspect:
+
+- SQLite integrity, schema version, required tables, and migration provenance;
+- baseline classification/readiness, research provenance, spec/evidence digests, gaps,
+  and revision/worktree drift;
+- active, blocked, and ready workflow runs, current steps, blockers, and output health;
+- active decision threads, the sole current question, blocking deferrals, checkpoint
+  state, and current checkpoint artifact digests;
+- event/projection cursor lag and failed or interrupted projection jobs;
+- sessions, incidents, circuit state, active-change artifacts, and archive journals;
+- external provider ownership boundaries.
+
+An expected blocked workflow is a workflow warning, not DB corruption. A stale or
+missing recorded output is an authority failure for that run. Doctor cannot invent
+evidence, complete a step, accept a failure, approve a baseline, or change product
+scope.
+An awaiting owner decision is also a recoverable warning, not corruption. A missing or
+changed artifact bound to a current confirmed checkpoint is an authority failure;
+doctor may report it but cannot reconstruct the decision or approval.
+
+## Route failures
+
+- Missing or migrated baseline evidence: `ultra-init` and the exact research step.
+- Stale workflow output: restore or regenerate the artifact from accepted evidence,
+  then record the affected step again and re-run completion.
+- Projection lag with healthy authority: eligible for mechanical regeneration.
+- Orphan session: reconcile the recorded lease; do not kill unrelated processes.
+- Missing change artifact: recover from version control, backup, or explicit owner
+  decision rather than silently recreating it.
+- Open decision: resume its exact question through `ultra-think`; checkpoint-ready
+  state requires owner confirmation, not mechanical repair.
+- Stale decision artifact: restore or update the artifact from accepted authority,
+  then reprepare and reconfirm the same checkpoint through `ultra-think`; do not
+  rewrite the owner decision or mark the failure healthy mechanically.
+- Corrupt SQLite: preserve DB/WAL/SHM and obtain a restore-or-rebaseline decision.
+
+## Explicit project repair
+
+After authorization, call `system.doctor` with repair enabled. Repair is limited to
+supported schema upgrades, backup-first archive recovery, orphan reconciliation,
+staleness consumption, projection requeue, and projection regeneration. Verify the
+pre-migration and repair backup paths and rerun the read-only report. A completed repair
+action does not imply healthy workflow evidence.
+
+When integrity prevents opening the DB, use only the documented restore or rebaseline
+command with its explicit confirmation token. Both must quarantine or back up prior
+authority and roll back on failure.
+
+## Installed host failures
+
+For a missing hook adapter or stale plugin path, capture the manifest and missing
+target, run `ubp --doctor` for the actual host, reinstall through the adapter rather
+than patching cache contents, and verify provenance, hashes, entry points, MCP startup,
+and a hook smoke test. Project doctor and installer doctor are separate authorities.
+
+Return health first, failing authority checks, workflow warnings, backup/recovery
+paths, whether repair ran, unresolved owners, and one exact next action. Do not edit
+application code or external memory/graph providers through this Skill.

package/skills/ultra-init/SKILL.md

@@ -1,111 +1,109 @@
 ---
 name: ultra-init
-description: Initialize a new repository, adopt an existing codebase, or upgrade prior Ultra state into an evidence-backed project baseline. Use when `.ultra` is absent, baseline readiness is incomplete, or legacy project state must be migrated.
+description: Initialize a new repository, adopt an existing codebase, or migrate prior Ultra authority into a verified project baseline. Use when `.ultra` is absent, initialization is incomplete, baseline readiness is blocked, or a legacy Ultra project must be resumed.
 ---
 
-# Establish the project baseline
-
-Create or recover project-local Ultra authority, classify the repository, and finish
-the applicable baseline workflow. Keep application source unchanged during adoption.
-
-## Authority rules
-
-- Treat `.ultra/state.db` as the only durable Ultra authority.
-- Preserve every existing `.ultra/` tree and migration backup.
-- Require explicit authorization before replacing a healthy baseline or discarding a
-  corrupt database.
-- Store only metadata references for external memory and code-graph providers.
-- Create ordinary tasks only after the baseline is ready. Record characterization
-  needs and adoption gaps in the gap ledger until convergence.
-
-## Inspect and route
-
-1. Bind the repository root, Git branch and HEAD, worktree status, manifests, package
-   scripts, workspace markers, deployment files, and existing `.ultra/` assets.
-2. When `.ultra/` is absent, run **Bootstrap**.
-3. When `.ultra/tasks/tasks.json` contains tasks but `state.db` is absent or has no
-   tasks, run **Import projection-only state** before ordinary state-backed work.
-4. When `state.db` exists, run read-only project doctor first. Call `baseline.get`
-   only when doctor confirms that the current schema authority is readable. Route an
-   old schema to repair and a corrupt database to recovery without another DB read.
-5. After current authority is readable, call `task.init_project` with `resume: true` to install
-   only missing current scaffold files. Verify that existing artifacts were preserved.
-6. Route the result:
-   - healthy `ready` baseline: return `ultra-change` or `ultra-status`;
-   - `draft`, `adopting`, or baseline-blocked: resume the matching baseline;
-   - `migrated`: start evidence-backed brownfield re-adoption;
-   - old schema: run backup-first schema repair;
-   - corrupt database: preserve it and stop at the restore-or-rebaseline decision.
-
-## Bootstrap
-
-Derive project metadata from repository evidence. Call `task.init_project` with
-`mode: "auto"`. Pass `scope` when the user selected a monorepo boundary; otherwise use
-the repository root. Use an explicit mode only when the user supplied an authoritative
-classification.
-
-Verify `repository_profile`, selected scope, detected mode, baseline lifecycle, schema
-version, copied templates, initial projection, and `project_initialized` event.
-
-## Import projection-only state
-
-Call `task.init_project` with `resume: true` as the single authority check and run the
-exact supported backup-first import command returned in its structured error. Do not
-infer an import path or edit the projection manually.
-
-Verify imported task and event counts, backup path, current schema state, projection
-parity, and the `migrated/adopting` compatibility baseline. Then call `baseline.start` with a
-new id, `mode: "brownfield"`, `replace_migrated: true`, the selected scope, current
-revision, and repository classification. Never treat the compatibility row as owner
-approval.
-
-For an older database schema, run `ultra-tools system doctor --repair`; verify both the
-pre-migration backup and post-repair backup plus the current schema before continuing.
-Then resume initialization to merge missing scaffold assets without overwriting the
-project's existing baseline documents.
-
-## Complete the selected mode
-
-For `brownfield`, `migrated`, or an incomplete existing adoption, read
-`references/brownfield-adoption.md` completely and execute it through owner approval.
-
-For `greenfield`, keep the baseline in `draft` until product and architecture intent is
-evidence-backed. Route unresolved intent through `ultra-research`, record the complete
-baseline snapshot, obtain owner approval, and converge it before planning.
-
-## Recovery handling
-
-- `ULTRA_DIR_EXISTS`: inspect and resume the existing state.
-- `LEGACY_STATE_MIGRATION_REQUIRED`: execute the returned migration command.
-- `BASELINE_IN_PROGRESS`: resume the named row; never create a parallel authority.
-- `BASELINE_EXISTS`: return the healthy route. Replacing a ready baseline is outside
-  ordinary initialization; stop for owner authorization before calling
-  `baseline.start` with a new id, `replace_ready: true`, and
-  `replacement_authorization: { approved_by, reason }`. The approval identity and
-  rationale must be persisted in the `baseline_started` event.
-- `BASELINE_SCOPE_MISSING`: correct the selected monorepo boundary.
-- `TEMPLATE_MISSING`: run installer doctor and reinstall through the host adapter.
-- `STATE_DB_CORRUPT`: retain the database, inspect `.ultra/backups`, and obtain the
-  restore-or-rebaseline decision. Restore only a verified managed backup with
-  `ultra-tools system restore --backup <path> --confirm REPLACE_CORRUPT_ULTRA_STATE`.
-  When no valid backup exists and the owner explicitly accepts rebuilding authority,
-  run `ultra-tools system rebaseline --project-name <name> [--scope <path>] --confirm
-  REBASELINE_CORRUPT_ULTRA_STATE`; verify the quarantined database and legacy
-  projection paths before continuing adoption.
-- `IO_ERROR`: verify rollback restoration and preserve every reported backup path.
+# Establish project authority
+
+Use host reasoning to inspect repository evidence and prepare baseline content. Use
+Ultra MCP for classification records, schema migration, workflow state, evidence
+digests, approval, and convergence. Never treat generated Markdown or JSON as state.
+Read `../ultra-think/references/decision-dialogue.md` before asking about repository
+scope, replacement authority, or another load-bearing owner choice.
+
+## Classify without guessing product scope
+
+Run `system.doctor` read-only when `.ultra/state.db` exists. Otherwise call
+`task.init_project` with `mode: "auto"`, the repository root, project name, and an
+owner-selected monorepo scope when applicable.
+
+Interpret classification independently from readiness:
+
+- `greenfield`: no meaningful delivered application behavior exists outside docs,
+  generated output, or a starter skeleton;
+- `brownfield`: source, runtime, deployment, API, schema, or test evidence shows an
+  existing maintained system;
+- `migrated`: older DB or projection-only authority was preserved and must be
+  replaced by an evidence-backed brownfield baseline.
+
+The presence of `.ultra/`, a manifest, or a Git repository does not make a baseline
+ready. Classification never chooses an MVP, reduced scope, or delivery posture.
+Report the detected project type, technology signals, verification commands, and
+monorepo roots. Pass an explicit `project_type` or `stack` only when repository evidence
+or an owner decision supports the override; MCP preserves both detection and selection.
+Inspect first and ask only one unresolved scope or replacement decision at a time. Do
+not request a complete project questionnaire during initialization.
+
+## Resume safely
+
+When `.ultra/` exists, call `task.init_project` with `resume: true`. It must preserve
+existing artifacts, create a pre-migration backup when needed, upgrade the schema,
+install only missing assets, and return the durable workflow ids and exact route.
+
+For projection-only state, execute only the backup-first migration command returned by
+the structured error. For a `migrated` compatibility row, call `baseline.start` with a
+new brownfield id and `replace_migrated: true`; never treat migration as owner approval.
+
+Replacing a healthy baseline requires a new id plus `replace_ready: true` and explicit
+`replacement_authorization`. Preserve corrupt DB, WAL, SHM, and backups; use the
+documented restore or rebaseline command only after the owner selects that destructive
+recovery path.
+
+## Follow durable initialization state
+
+Read the returned init and research runs with `workflow.get`.
+
+- `inspect-authority`: `task.init_project` records the bounded repository and existing
+  Ultra evidence it inspected.
+- `classify-repository`: `task.init_project` records classification, detected signals,
+  selected scope, and supported overrides.
+- `scaffold-authority`: `task.init_project` creates or resumes DB authority and installs
+  only missing scaffold assets.
+- `establish-baseline`: research completion, `baseline.record`, and owner-approved
+  `baseline.converge` establish the evidence-backed authority.
+- `verify-initialization`: convergence re-reads baseline, init, research, repository,
+  verification, and output health before completing initialization.
+
+The first three steps are deterministic writes owned by `task.init_project`; the final
+two are completed atomically by successful baseline convergence. Do not mark or emulate
+these transitions in Prompt text or projection files.
+
+- Greenfield starts a `full` research run.
+- Brownfield starts an `adoption` research run.
+- Both modes require all seventeen research steps before baseline convergence.
+- A migrated project remains routed to re-adoption before research can authorize work.
+
+Continue through `ultra-research`. Research completion records output digests; then
+`baseline.record` captures current scope, revision, discovery/product/architecture
+specs, source and runtime evidence, actual verification, unknowns, gaps,
+classification, and external provider metadata references.
+
+Call `baseline.converge` only after the compact research checkpoint receives explicit
+owner approval; do not ask for the same approval twice. The MCP rejects missing
+research, missing discovery/product/architecture refs, stale evidence, revision or
+worktree drift, unaccepted known failures, blocking unknowns, and blocking gaps. A
+successful convergence atomically marks the baseline ready and completes the init run.
+
+## Recovery
+
+- Record deterministic blockers on the current workflow; never create a parallel run.
+- Use `system.doctor` repair only for supported schema, projection, session, incident,
+  archive, or legacy workflow-provenance recovery. A recovered legacy change workflow
+  remains blocked for real baseline evidence; repair cannot invent research or approve
+  a baseline.
+- Treat context budgets as advisory. Missing authority, evidence, output, or approval
+  is blocking.
+- Store only references to external memory and code-graph providers.
 
 ## Completion
 
-Initialization is complete only when:
+Read `baseline.get`, `workflow.get`, and `system.doctor` after convergence. Report
+classification evidence, scope, revision, worktree snapshot, migration backups,
+research run and output health, verification, gaps, approval, and one route.
 
-- current schema authority is readable;
-- repository classification and scope are recorded;
-- product and architecture baseline files exist;
-- verification, unknowns, gaps, evidence, and provider references are recorded;
-- explicit owner approval has converged the baseline to `ready`;
-- `baseline.get` reports current health and project doctor has no authority failure.
-
-Report the target, classification evidence, migration and backup paths, baseline id,
-mode, status, revision, branch, worktree snapshot, verification results, gap summary,
-approval state, and one exact next action. Stop at the approval step when owner consent
-has not yet been provided.
+Initialization is complete only when the baseline is `ready`, the init workflow is
+`completed`, the research workflow is `completed`, and
+`baseline.research_run_id` names that exact research run with healthy outputs. Route
+every newly converged or already initialized baseline through `ultra-change`; planning
+starts only after that command persists a complete Change Contract, profile, and
+research disposition. Otherwise return the exact current workflow step or blocker.

package/skills/ultra-init/references/brownfield-adoption.md

@@ -89,5 +89,5 @@ items the owner accepted.
 Resolve returned blockers through evidence or an owner decision, record the replacement
 snapshot, and retry. Adoption is complete only when `baseline.get` is `ready` and
 current, the gap ledger has no open blocker, and project doctor has no authority
-failure. Route new work through `ultra-change`; route already accepted planned work
-through `ultra-plan`.
+failure. Route all selected work through `ultra-change`, including work described by a
+legacy plan. Import its accepted intent into a current Change Contract before planning.

package/skills/ultra-plan/SKILL.md

@@ -1,89 +1,103 @@
 ---
 name: ultra-plan
-description: Convert a validated baseline, active delta, or approved PRD into dependency-valid vertical slices with bounded context and exact verification. Use when requirements are ready to become authoritative Ultra tasks.
+description: Convert a ready Ultra baseline or approved active-change delta into dependency-valid, DB-backed execution contracts and fresh-context vertical slices. Use when accepted requirements are ready for implementation planning or an existing plan must be resumed and verified.
 ---
 
-# Plan fresh-context execution
-
-Produce a task graph whose slices can be completed independently and verified through
-live product seams. `.ultra/state.db` remains authoritative; task JSON and context
-Markdown are generated projections.
-
-## Entry gate
-
-Start with a state-backed MCP read. If state or schema health blocks access, stop and
-route to `ultra-doctor`. Never read or write `.ultra/tasks/tasks.json` as a fallback.
-Call `baseline.get`. Initial product planning is blocked until the baseline is
-`ready` and current; route its missing, adopting, blocked, or stale state to
-`ultra-init`. Planning an already active bounded change may continue with the
-baseline condition recorded as a warning. Ordinary convergence still requires
-approved adoption, and archive atomically reconciles revision and specification
-drift. An approved break-glass incident follows its recorded recovery contract and
-creates a blocking reconciliation gap at archive.
-
-Choose one input:
-
-- validated baseline specifications;
-- one active change packet;
-- a raw PRD through the approval-gated mode below.
-
-Ask only for product, scope, cost, or risk decisions that cannot be derived from
-current evidence. A material unresolved assumption blocks persistence.
-
-## Planning rules
-
-1. Trace acceptance through an entry point, domain behavior, side effects, and a
-   user-observable or public seam.
-2. Prefer a walking skeleton or `tracer_bullet` before horizontal layers.
-3. Give each task one outcome, bounded ownership, explicit dependencies, required
-   references, and one deterministic verification command.
-4. Use the context budget as an attention signal. Prefer bounded excerpts, direct
-   reads, or a smaller slice, but keep necessary files when correctness requires them.
-   Budget overflow is a warning, never a reason to inflate a threshold or manufacture
-   a smaller but incomplete contract.
-5. Add integration checkpoints at actual boundaries, not after arbitrary task counts.
-6. Put validation, errors, recovery, documentation, and migrations in the task that
-   owns the behavior.
-7. Reject scaffolding with no reachable consumer.
-
-Every persisted task must include its slice kind, public seam, verification command,
-acceptance evidence, ownership, dependencies, documentation impact, and linked change
-id when applicable.
-
-## Baseline or change mode
-
-1. Read the smallest authoritative references that define acceptance.
-2. Build the task DAG in memory and check dependency and ownership conflicts.
-3. Present the proposed outcome, execution order, risk concentration, and first live
-   seam. Obtain approval if scope, cost, or delivery semantics change materially.
-4. Persist approved tasks with `task.create`.
-5. For change-linked tasks, compile `change.context` with the planning role and gate.
-   Resolve every readiness blocker before calling a task executable.
-6. Call `task.dependency_topo`; cycles and missing dependencies block completion.
-7. Call `plan.export`, then verify the persisted result with `plan.get`.
-8. Call `change.breadcrumb` when a change is active and return one next action.
-
-## PRD mode
-
-1. Read the approved PRD with the current host model and derive the proposed task
-   objects using the `task.parse_prd` input schema. Do not invoke a second model or
-   require a provider API key inside Ultra MCP.
-2. Call `task.parse_prd` with those `tasks`, `dry_run: true`, and the active
-   `change_id` when applicable. The MCP validates the graph but does not supply
-   product judgment.
-3. Show the proposed slices, topology, conflict surface, and cost estimate.
-4. Require explicit approval; rejection performs no state write.
-5. On approval, repeat with `dry_run: false`, the identical task objects, and the
-   same change ownership; export
-   the plan, and verify that the dry-run and persisted task identities agree.
-
-When one approved task is still too broad, derive its complete child graph with the
-current host model and call `task.expand` with the parent `id` and validated
-`children`. The MCP assigns parent, tag, and change ownership atomically. Never ask
-the MCP runtime to generate child content.
-
-## Completion gate
-
-Planning is complete only when the DAG is valid, each task reaches a public seam, each
-verification command is executable, every change-linked context is ready, and no
-required documentation or decision remains unknown.
+# Review and persist an executable plan
+
+Use host reasoning for decomposition, tradeoffs, and approval. Use Ultra MCP for
+workflow position, decision authority, task contracts, graph validation, projection,
+and recovery. Read `../ultra-think/references/decision-dialogue.md` before presenting a
+planning choice.
+
+## Bind authority
+
+1. Call `system.doctor`, `baseline.get`, `change.list`, and `change.breadcrumb`.
+2. Require a current ready baseline for new ordinary work. Resume an already-authorized
+   active change when appropriate; an incident uses only its recorded break-glass
+   authority.
+3. Ensure exactly one active change owns the plan. For initial implementation, open a
+   standard or major change from the accepted baseline before creating tasks.
+4. Read `references/semantic-preflight.md`. Resolve every blocking Change decision and
+   complete the exact recorded bounded research selection before starting the plan.
+5. Resume the active `plan` workflow from `workflow.list`, or call `workflow.start`
+   with its `baseline_id`, `change_id`, subject, and source refs.
+
+## Build a candidate before writing authority
+
+Inspect requirements, source, consumers, state, tests, deployment, and recovery before
+drafting slices. Build the candidate plan privately. Separate evidence-backed design
+detail from choices that change accepted scope, public behavior, compatibility, cost,
+risk, delivery semantics, or recovery.
+
+When a material planning decision remains, start or resume a decision thread bound to
+the plan workflow. Present exactly one decision with the recommendation, credible
+alternatives, and the tasks or contracts it changes, then STOP. The plan document is
+the result of this review; never use a large plan dump as a substitute for interaction.
+
+After all blocking choices are resolved, prepare one checkpoint. Present the compact
+topology, public seams, recovery, and material tradeoffs for approval. After approval,
+write the evidence-linked `plan.md`, confirm the checkpoint with its digest, and reuse
+that same approval for the durable `approve-plan` and workflow completion gates.
+
+## Record the durable steps
+
+Record each completed step with `workflow.step`:
+
+1. `validate-baseline`: verify baseline and completed research provenance.
+2. `select-posture`: preserve the owner-approved scope and delivery posture. Never
+   infer an MVP, reduction, phase, or exclusion. Ask only when a proposed plan changes
+   accepted scope, cost, risk, compatibility, or delivery semantics.
+3. `analyze-requirements`: trace stable requirement ids to acceptance and public seams.
+4. `analyze-codebase`: inspect current entry points, consumers, patterns, state
+   authority, tests, deployment, and recovery paths before designing new structure.
+5. `design-slices`: design a walking skeleton and subsequent vertical slices. Every
+   slice must reach a real consumer; include validation, side effects, errors,
+   documentation, migration, observability, and recovery in the owning slice.
+6. `validate-dependencies`: validate ownership, missing dependencies, cycles, conflict
+   surfaces, and meaningful integration checkpoints.
+7. `approve-plan`: persist the already obtained checkpoint approval; do not ask again.
+
+## Persist complete task contracts
+
+Only after the plan checkpoint is confirmed, call `task.create` for each approved task
+with:
+
+- one observable `outcome` and stable `trace_to`;
+- `slice_kind`, `public_seam`, and exact `verification_command`;
+- structured `acceptance` items with their verification;
+- bounded `context_refs` with reasons;
+- resolved `docs_impact` and durable `ownership`;
+- dependencies, affected files when known, estimates only when evidence supports them,
+  and the owning `change_id`.
+
+Copy each Change acceptance id into at least one task acceptance item without changing
+its meaning. Set `trace_to` to that accepted id, a current research semantic id, or a
+real project-relative Markdown `path#anchor`. A quick profile has exactly one task.
+The MCP derives the coverage matrix and rejects uncovered acceptance, orphan tasks,
+stale research, and oversized quick plans.
+
+Never read or write `.ultra/tasks.json` or generated context Markdown as authority.
+The DB owns the task contract and the projector regenerates both views.
+`persist-task-contracts` completes only after `task.get` reads every field back without
+a contract blocker.
+
+Call `task.dependency_topo` with the current `change_id`, then call
+`plan.export` with `change_id`, `format: "json"`, and
+`out_path: ".ultra/execution-plan.json"`. Export records `plan_exported`; it does
+not approve the plan. Read the same change back with `plan.get`.
+The exported artifact is change-bound and may not include tasks from another active
+or historical change. Recompile `change.context`
+for the first task; it derives its execution contract and context refs from DB and
+rejects a conflicting prompt override. Missing required refs block readiness; context
+size is advisory.
+
+Record `verify-plan` with `.ultra/execution-plan.json` as its sole output, then call
+`workflow.complete` with
+`approval.approved_by` and `approval.approval_note`. Do not send a task summary: MCP
+derives the complete task set from every task owned by the change. Completion
+revalidates every task contract, change ownership, dependency existence, graph cycles,
+the exact exported topology, approval, and current output digests; it also advances
+the linked change workflow to context compilation.
+Return the persisted topology, first task/public seam,
+approval evidence, plan workflow id, and one `ultra-dev` route.