ultra-builder-pro-cli 0.22.0 → 0.24.0

package/skills/ultra-init/SKILL.md

@@ -1,94 +1,54 @@
 ---
 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.
-
-## Inspect before mutation
-
-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. Read the Git-facing team checkpoint when present. Never parse a legacy
-   `.ultra/tasks/tasks.json` as current authority or edit it directly.
-4. Otherwise call `task.init_project` with `mode: "auto"`, the project name, and an
-   explicit scope only when the repository contains multiple plausible roots.
-5. Leave `git_mode` as `auto` unless the user explicitly requires a non-Git workspace.
-
-Use repository evidence to classify:
-
-- `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.
-
-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.
-
-## Interaction boundary
-
-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.
-
-## Deterministic initialization contract
-
-`task.init_project` owns these steps:
-
-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;
-- create an empty `.ultra/tasks/tasks.json` team checkpoint for a new project;
-- import a validated team checkpoint on clone or resume, while requiring
-  checkout-local revalidation before an imported ready baseline can authorize work;
-- 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, local runtime projection, team checkpoint,
-  and Git result before completing the init workflow.
-
-Projection-only projects must use the exact backup-first migration command returned by
-the runtime. On the first supported team-checkpoint publication, a matching legacy
-task projection is copied byte-for-byte into `.ultra/.runtime/backups/task-ledger/`
-before replacement; any task-id or durable-field mismatch stops with a typed conflict.
-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,
-team-checkpoint import or revalidation state, baseline state, and allowed transitions.
-Do not claim that a baseline is ready until a separate research/adoption workflow has
-recorded and converged it in the current checkout.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+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 and align
+
+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.
+
+Read `../ultra-think/references/interaction-boundary.md` before asking a material
+question.
+
+## Initialize once
+
+Call `ultra.record` with one typed entry:
+
+```text
+kind: baseline
+action: initialize
+data: { target_dir, project_name, mode=auto, git_mode=auto, optional scope }
+idempotency_key: <stable init attempt id>
+```
+
+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.
+
+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.
+
+## Return control
+
+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.

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

@@ -66,7 +66,8 @@ ledger into hundreds of application tasks.
 
 ## Record authority
 
-Call `baseline.record` with full replacement arrays for:
+Use `ultra.record` with `kind: baseline`, `action: observe`, and full replacement
+arrays for:
 
 - scope and repository revision;
 - repository classification;
@@ -82,12 +83,14 @@ Use the server-returned revision, branch, worktree digest, and specification dig
 ## Obtain approval and converge
 
 Present scope, observed behavior, drift, known-red verification, unknowns, gaps, dirty
-worktree state, and material decisions to the owner. Call `baseline.converge` only after
-explicit approval. Set `accept_known_red` and `accept_dirty_worktree` only for the exact
-items the owner accepted.
+worktree state, and material decisions to the owner. Use `ultra.record` with
+`kind: baseline`, `action: accept` only after explicit approval. Set
+`accept_known_red` and `accept_dirty_worktree` only for the exact 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 all selected work through `ultra-change`, including work described by a
-legacy plan. Import its accepted intent into a current Change Contract before planning.
+snapshot, and retry. Adoption is complete only when `ultra.context` reports a current
+accepted baseline, the gap ledger has no open blocker, and project doctor has no
+authority 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

@@ -5,135 +5,57 @@ description: Turn an accepted Ultra Change Contract into dependency-valid, DB-ba
 
 # Build an executable plan
 
-The model owns decomposition and technical design. MCP owns plan state, task contracts,
-dependency integrity, output digests, and recovery. Planning must stay inside the
-accepted Change Contract without adding ceremonial approval.
-
-## Bind current authority
-
-1. Read doctor, `task.ledger_get`, baseline, change, breadcrumb `accepted_intent`,
-   decisions, existing plan runs, tasks, and current checkout. If a new Git checkpoint
-   arrived after this MCP process started, call `task.ledger_import` before planning.
-   Stop on a typed baseline, Change, task, ancestry, or active-session conflict; never
-   choose one side by editing the ledger.
-2. Require one mutable change with a healthy baseline or recorded incident bypass.
-   For the first delivery of a greenfield project, an accepted ready baseline may
-   already contain the complete delivery outcome. When no matching Change exists,
-   materialize one `change.create` contract from that accepted intent and read it back
-   without asking the owner to repeat the same choice. Do not invent scope, expand an
-   incomplete baseline, or use this shortcut for a later change.
-3. Complete the exact change-bound research disposition before planning.
-4. For a standard or major Change, read the current registered `change.delta` and
-   verify its baseline anchors and digest. A Direct Build route supplies the delta
-   directly from accepted intent; it skips Research, not this authority boundary.
-5. Resume the matching plan run. Do not start a new run until planning posture is
-   accepted.
-
-Read `references/semantic-preflight.md` and inspect requirements, real consumers,
-state, tests, deployment, and recovery paths.
-
-## Align planning posture
-
-Use the interaction protocol in `../ultra-think/references/decision-dialogue.md`.
-Normalize a posture already explicit in current intent. Otherwise recommend one based
-on the Change Contract, explain its scope effect, and use the host's native question
-surface:
-
-- `EXPAND`: surface evidence-backed opportunities beyond accepted scope;
-- `SELECTIVE`: hold accepted scope and offer optional expansions individually;
-- `HOLD`: preserve scope and strengthen completeness, failure handling, and recovery;
-- `REDUCE`: propose the smallest outcome that still satisfies revised acceptance.
-
-The user may select, modify, delegate, or defer the posture. Stop on an unanswered
-choice. Start `workflow.start` only after alignment and store `planning_posture` plus
-its rationale in workflow metadata. This is a scope boundary, not approval of the
-eventual technical design.
-
-## Design with model autonomy
-
-Build a candidate plan from the Change Contract, current typed delta, and any selected
-research. Ask the user only if the plan would change accepted
-scope, public behavior, compatibility, security, material cost, external effects, or
-recovery. Use the same host-native interaction protocol.
-
-When the candidate remains inside the accepted Change Contract, proceed without a
-second approval. A user may still request a plan review before persistence; that is an
-interaction preference, not a runtime invariant.
-
-Record:
-
-1. `validate-baseline`
-2. `compile-context`
-3. `analyze-requirements`
-4. `analyze-codebase`
-5. `design-slices`
-6. `validate-dependencies`
-7. `persist-task-contracts`
-8. `verify-plan`
-
-Design a walking skeleton and subsequent vertical slices. Every slice reaches a real
-consumer and owns its validation, side effects, errors, documentation, migration,
-observability, and recovery obligations. Avoid unconsumed horizontal scaffolding.
-
-After starting or resuming the workflow, compile `change.context` with `role: plan`
-and `gate: planning`. Record its immutable manifest as the `compile-context` output.
-The packet is the accepted planning input, not a mutable plan draft. `change.context`
-must not update Change provider references; persist new provider metadata with
-`change.update` before recompiling.
-
-## Persist task contracts
-
-Create each task with:
-
-- observable outcome (`purpose`) and stable trace (`why`);
-- `slice_kind`, public seam, and exact verification command;
-- structured acceptance mapped to Change acceptance ids;
-- target seams and affected files when known;
-- bounded pattern/context refs with a reason, optional anchor and scope, and an
-  explicit freshness policy;
-- documentation impact, ownership, and dependencies.
-
-Use `digest` freshness with `expected_digest` for accepted inputs that must remain
-byte-current. Use `existence` for source targets expected to change during
-implementation. Use `advisory` only when drift should be visible but non-blocking.
-The compiled task context restores constraints and non-goals from the Change Contract,
-plus acceptance, recovery, documentation impact, and the definition of drift. Keep
-large referenced files lazy; do not paste their bodies into the plan packet.
-
-Use estimates only when evidence supports them. A quick change has exactly one task.
-Read every task back from DB. Never read or write `.ultra/tasks/tasks.json` directly.
-It is the MCP-published Git team checkpoint, while
-`.ultra/.runtime/projections/tasks.json` is the generated checkout-local view.
-
-If a semantic `change.update` invalidated existing tasks, reconcile every affected
-task contract against the current intent, acceptance, decisions, and research
-evidence. Rebind the complete execution contract while clearing `stale` through
-`task.update`; MCP rejects a marker-only clear, validates the read-back, and records
-the current Change authority digest. Never clear staleness merely to pass a gate.
-
-Validate the change-scoped graph with `task.dependency_topo`. Export
-the deterministic `<artifact_root>/plan.json` and `<artifact_root>/plan.md` pair with
-`plan.export { change_id }`. The JSON binds the exact planning context snapshot and
-manifest digest; the Markdown is a deterministic human view of the same task graph.
-An accepted export also publishes the portable baseline, Change, task contracts,
-dependencies, and durable statuses to the team checkpoint. Local sessions, leases,
-`in_progress` ownership, telemetry, and completion hashes remain in `.ultra/.runtime`.
-Read the JSON through `plan.get` and record it as the `verify-plan` output. Do not
-choose an arbitrary output path or overwrite another Change's plan. A legacy global
-`.ultra/execution-plan.json` may be read for migration diagnosis only and is never a
-current write target.
-
-Call `workflow.complete`. `approval` is optional: include it only when a material plan
-decision actually required and received user approval. MCP derives task coverage and
-topology from DB and must reject incomplete contracts, uncovered acceptance, cycles,
-cross-change tasks, stale research, or a mismatched export.
-
-Do not advance or complete the Change workflow; change capture is already complete.
-Compile a separate task context later for each consumer that needs it. Planning,
-implementation, testing, review, and convergence snapshots are not interchangeable.
-
-Return topology, first executable slices, public seams, verification commands, plan
-workflow id, and allowed transitions. The host may recommend parallel or sequential
-execution based on dependency and conflict evidence.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+The model owns decomposition and technical design. MCP commits the accepted task graph,
+digests, context, and team checkpoint in one semantic operation.
+
+## Bind and design
+
+1. Call `ultra.context { stage: plan, scope: { change_id }, detail: full }`.
+2. Inspect or import the team checkpoint with `ultra.sync`. Resolve real concurrent
+   record conflicts; do not merge authority by editing JSON.
+3. Require an accepted Change contract and its current typed delta. Direct Build skips
+   extra research, never Plan or task contracts.
+4. Read `references/semantic-preflight.md`; inspect real consumers, source, tests,
+   deployment, and recovery.
+5. Recommend `EXPAND`, `SELECTIVE`, `HOLD`, or `REDUCE` only when posture changes
+   accepted scope. Reuse an explicit posture and ask through the host-native UI only
+   for a material unresolved choice.
+6. Design a walking skeleton and vertical slices. Each task owns an observable outcome,
+   public seam, verification command, acceptance mapping, target seams, bounded
+   context refs, documentation impact, recovery, owner, and dependencies.
+
+Large sources stay lazy. Use digest freshness for accepted inputs that must remain
+byte-current, existence for expected implementation targets, and advisory only when
+drift must be visible without blocking.
+
+Read `../ultra-think/references/interaction-boundary.md` before asking a material
+question.
+
+## Record and checkpoint
+
+Use one `ultra.record` batch with `task_contract / define` for new tasks and
+`task_contract / revise` for corrected contracts. Read back the draft with
+`ultra.context`.
+Never read or write `.ultra/tasks/tasks.json`; use `ultra.sync` for the Git team
+checkpoint, and never edit the local runtime projection directly.
+
+Call exactly one `ultra.checkpoint`:
+
+```text
+stage: plan
+scope: { change_id }
+payload: planning posture, optional approval already obtained, context budget/refs
+idempotency_key: stable semantic Plan checkpoint id
+```
+
+The checkpoint compiles or reuses the content-addressed Context Envelope, derives
+coverage diagnostics, exports `plan.json` and `plan.md` inside the same recoverable
+publication, accepts one Plan revision, and publishes the team checkpoint. Do not
+export separately.
+
+If rejected, the same Plan draft stays mutable. Fix task contracts or evidence and
+retry. To replace an accepted Plan, submit a new checkpoint revision; never edit
+SQLite or open a parallel run to escape a diagnostic.
+
+Return topology, executable slices, public seams, exact checks, checkpoint result, and
+the model's recommended execution order. Do not invoke `ultra-dev` automatically.

package/skills/ultra-research/SKILL.md

@@ -1,118 +1,64 @@
 ---
 name: ultra-research
-description: Build or refresh an evidence-backed product and architecture baseline through recommended, user-selected semantic coverage and low-load alignment. Use when initialization, brownfield adoption, or an active change has a real evidence gap.
+description: Build or refresh an evidence-backed product and architecture baseline through recommended, user-selected semantic coverage. Use when initialization, brownfield adoption, or an active Change has a real evidence gap.
 ---
 
 # Research with adaptive coverage
 
-The model owns investigation, synthesis, and coverage recommendations; the user owns the accepted semantic route and material deferrals.
-MCP owns run state, evidence, semantic records, digests, freshness, and convergence, not a questionnaire.
-
-Read `../ultra-think/references/decision-dialogue.md` before asking a material question.
-
-## Bind authority
-
-1. Read `system.doctor`, `task.ledger_get`, `baseline.get`, breadcrumb
-   `accepted_intent`, active decisions, and existing research runs. Import a newer
-   descendant team checkpoint before binding coverage; stop on a typed merge conflict.
-2. Resume the matching active, blocked, or ready run. Do not create parallel authority.
-3. If none exists, use `full` for greenfield, `adoption` for brownfield, or a bounded
-   mode only for a recorded active-Change disposition. Focused baseline coverage
-   remains `full` or `adoption`; `custom` is Change-bound only.
-4. Before `workflow.start`, inspect current code, docs, tests, runtime, and prior
-   artifacts. Recommend the smallest sufficient set of applicable catalog areas.
-   Explain the net effect without dumping all 17 areas. Offer at most three credible
-   routes: the recommended adaptive set, the full catalog, and a focused or custom set.
-5. If current user intent does not already select a route, use the host's native
-   structured question surface. The user selects, modifies, delegates, or defers.
-   Treat a dismissal as unanswered, stop, and perform no route-dependent write.
-6. Normalize the answer and persist the accepted coverage through `workflow.start`.
-   Use `execute` for fresh evidence, `verify_existing` for source validation, `reuse`
-   for current evidence, `not_applicable` with evidence and rationale, or `deferred`
-   with consequence and owner acceptance when scope or material risk changes.
-7. Pass the evidence-based coverage rationale as `metadata.selection_reason`. Omitted
-   catalog areas create no DB step and need no ceremonial disposition.
-8. Read back the created workflow and accepted coverage. When a durable decision thread
-   recorded the route, complete it with the workflow reference in `applied_refs`.
-
-`99-synthesis` must execute, verify, or reuse. A missing disposition is a coverage error only for an included area; a recorded exclusion with evidence is not incomplete.
-
-## Coverage catalog
-
-Load only the reference for a step that must execute, verify, or reuse:
-
-| Area | Reference | Area | Reference |
-|---|---|---|---|
-| `00-problem-validation` | `references/00-problem-validation.md` | `01-opportunity-discovery` | `references/01-opportunity-discovery.md` |
-| `02-market-assessment` | `references/02-market-assessment.md` | `03-competitive-landscape` | `references/03-competitive-landscape.md` |
-| `04-product-strategy` | `references/04-product-strategy.md` | `05-assumptions-validation` | `references/05-assumptions-validation.md` |
-| `10-user-personas` | `references/10-user-personas.md` | `11-user-scenarios` | `references/11-user-scenarios.md` |
-| `20-user-stories` | `references/20-user-stories.md` | `21-features-scope` | `references/21-features-scope.md` |
-| `22-success-metrics` | `references/22-success-metrics.md` | `30-architecture-context` | `references/30-architecture-context.md` |
-| `31-solution-strategy` | `references/31-solution-strategy.md` | `32-building-blocks` | `references/32-building-blocks.md` |
-| `40-deployment` | `references/40-deployment.md` | `41-quality-risks` | `references/41-quality-risks.md` |
-| `99-synthesis` | `references/99-synthesis.md` |  |  |
-
-## Investigate and interact
-
-For each active area:
-
-1. Resolve observable facts from the checkout, runtime, tests, existing specifications,
-   and primary sources. Separate `Observed`, `Verified`, `Decided`, and `Unknown`.
-2. Ask the user only for a material intent, scope, compatibility, risk, or recovery
-   decision that evidence cannot answer. Use the host's native question UI when
-   available. Present the recommendation and effect; avoid a questionnaire or a dump
-   of the hidden research queue.
-3. Process dependent decisions one at a time. A small group of independent,
-   low-cognitive-load facts may be asked together when the host UI supports it.
-4. Normalize explicit user intent without redundant confirmation. Create durable
-   decision state only when a project-bound decision must survive interruption.
-5. Update the smallest relevant baseline specification or active-change research
-   artifact. Do not copy prompts, transcripts, provider payloads, or internal chain of
-   thought.
-
-Every required step writes `Evidence`, `Specification updates`, and `Decisions and
-unknowns` to `.ultra/docs/research/<workflow-id>/<step-id>.md` for a baseline, or
-`<change-root>/research/<workflow-id>/<step-id>.md` for an active Change.
-
-Call `workflow.step` with bounded evidence, the report output, and typed semantic
-records. Reused or verified evidence must still produce a current report and digest.
-Block the same step when required evidence or owner authority is missing. For Change
-research, keep `findings.md` and every semantic output inside the same Change root and
-register them through workflow outputs; do not write baseline specifications.
-
-At synthesis, bind the current `discovery.md`, `product.md`, `architecture.md`, and
-`research-distillate.md` only for initial/adoption research. Change-bound synthesis
-updates the Change findings and specification overlay, then records or refreshes
-`change.delta`. It never mutates the accepted baseline.
-
-## Baseline convergence
-
-After `workflow.complete`, initial or adoption research calls `baseline.record` with
-the current repository scope and revision, specification refs, evidence, real
-verification results, unknowns, gap ledger, classification, and external provider
-metadata references.
-
-If Git is initialized but unborn, present the exact local checkpoint paths and purpose
-for user authorization, then create only that local commit. Never create a remote,
-tag, or push through research. If authorization or identity is missing, preserve the
-run as blocked with `BASELINE_GIT_HEAD_REQUIRED`.
-
-Call `baseline.converge` only when the user has accepted the exact baseline snapshot,
-known failures, blocking gaps, and scope. Reuse an unambiguous current approval; do not
-ask twice. MCP must reject stale research, drift, missing evidence, and unaccepted
-failures. Successful convergence publishes the portable baseline, Changes, and tasks
-to the Git team checkpoint; the receiving checkout must still revalidate a ready
-baseline against its own HEAD and files.
-
-Reuse the final research acceptance or current artifact checkpoint during baseline
-convergence; do not ask for an equivalent approval again. After initial or adoption
-convergence, `ultra-change` becomes an available transition. Bounded change research
-returns to its owning Change authority; the next route is still `ultra-plan`, never
-direct implementation.
-
-Return a compact coverage summary by disposition, current evidence or decision blocker, baseline state, gaps, 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 supplies only valid and required transitions.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+The model owns investigation and synthesis. The owner controls material scope and
+deferrals. MCP records the accepted draft and commits one durable checkpoint; it is
+not a questionnaire or a step-by-step supervisor.
+
+## Bind current context
+
+1. Call `ultra.context { stage: research, detail: full }`.
+2. If the team checkpoint is newer, call `ultra.sync { action: import }`. Stop only
+   on a real ancestry or same-record conflict.
+3. Inspect code, docs, tests, runtime, accepted intent, decisions, and existing
+   research. Reuse current evidence and the matching mutable draft.
+4. Recommend the smallest sufficient coverage. Offer the adaptive set, the full
+   catalog, and a focused Change-bound set only when all are credible.
+5. Use the host-native question surface only for a material unresolved route. Reuse an
+   explicit owner choice without asking again.
+
+Read `../ultra-think/references/interaction-boundary.md` before asking. Load only the
+reference files for research areas that actually apply.
+
+## Investigate
+
+For each selected area:
+
+- separate `Observed`, `Verified`, `Decided`, and `Unknown`;
+- resolve observable facts yourself and use primary sources where needed;
+- update the smallest baseline or Change-owned research artifact;
+- never store transcripts, hidden reasoning, raw provider payloads, or copied prompts;
+- record evidence, specification updates, decisions, deferrals, and consequences.
+
+Use one `ultra.record` batch for typed durable facts:
+
+- `artifact / bind` for a managed research or specification artifact;
+- `decision / accept` for normalized owner intent;
+- `baseline / observe` or `baseline / accept` for baseline authority;
+- `change_contract / revise` for Change-bound findings.
+
+Every entry needs a stable idempotency key. A semantic rejection is a mutable
+diagnostic: correct the same draft and retry.
+
+## Commit one research checkpoint
+
+Call exactly one `ultra.checkpoint` with `stage: research`. Put the selected research areas
+and their report outputs in `payload.steps`; include only work actually performed,
+verified, reused, deferred with owner authority, or proved not applicable. Synthesis
+must always be present.
+
+For baseline research, update and accept the baseline through typed `ultra.record`
+entries, then publish the team checkpoint with `ultra.sync { action: publish }`.
+For Change-bound research, keep all findings and delta artifacts below the Change
+root and never edit accepted baseline specs directly.
+
+If the checkpoint returns `accepted: false`, keep the same draft mutable, repair the
+reported evidence, and retry. Do not manufacture evidence or open a replacement run.
+
+Return coverage, decisive evidence, remaining gaps, durable artifact paths, and a
+model recommendation for the next explicit capability, such as `ultra-change` after a
+ready baseline. Never invoke it automatically.