ultra-builder-pro-cli 0.14.0 → 0.15.0

package/skills/ultra-init/SKILL.md

@@ -1,111 +1,104 @@
 ---
 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.
+
+## 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.
+
+## 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 explicit owner approval. 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,83 @@
 ---
 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.
+# Persist an executable plan
+
+Use host reasoning for decomposition, tradeoffs, and approval. Use Ultra MCP for
+workflow position, task contracts, graph validation, projection, and recovery.
+
+## 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.
+
+## Plan through 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 owner approval when the plan makes a material decision.
+
+## Persist complete task contracts
+
+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.

package/skills/ultra-plan/references/semantic-preflight.md

@@ -0,0 +1,18 @@
+# Semantic planning preflight
+
+Before task decomposition, read the normalized Change Contract and the current
+change-bound research records.
+
+1. Resolve every blocking `unresolved_decision` or return to `ultra-change`.
+2. When research is recorded, verify one completed run has the same mode and selected
+   step set. Re-run stale or missing evidence through `ultra-research`.
+3. Build a coverage ledger from Change acceptance ids to task acceptance ids.
+4. Bind every task to an accepted id, semantic record id, semantic source ref, or real
+   Markdown anchor through `trace_to`.
+5. Check that every task reaches a public consumer and owns its error, documentation,
+   verification, and recovery obligations.
+6. Validate dependencies and ensure a quick profile contains exactly one task.
+
+Treat the MCP completion result as the final planning gate. It derives the coverage
+matrix from durable records and rejects unresolved decisions, missing research,
+uncovered acceptance, orphan tasks, incomplete contracts, or invalid topology.

package/skills/ultra-research/SKILL.md

@@ -1,75 +1,102 @@
 ---
 name: ultra-research
-description: Turn uncertain product or architecture intent into evidence-backed baseline specifications with explicit decisions and traceable acceptance. Use when an Ultra project has unresolved requirements that are not ready for planning.
+description: Establish or extend an evidence-backed Ultra product and architecture baseline through the complete semantic research workflow, with resumable step state and traceable outputs. Use when initialization routes to research, baseline evidence is incomplete, or the owner explicitly requests bounded research for an active change.
 ---
 
-# Build a validated baseline
+# Establish research authority
 
-Research only the uncertainty that blocks a durable product, architecture, or delivery
-decision. Do not force a fixed discovery ceremony onto a well-defined change.
+Use host reasoning for evidence gathering, product judgment, questions, and artifact
+content. Use Ultra MCP for run selection, state transitions, output digests, blockers,
+and baseline convergence. Never ask MCP to generate research content.
 
-## Preflight
+## Bind the run
 
-1. Require an initialized `.ultra/specs/` directory and call `baseline.get`. Route to
-   `ultra-init` when state or the baseline is absent. Preserve its mode and id.
-2. Read the current specification files and repository evidence before asking the
-   user to repeat known facts.
-3. Define the intended deliverable, unresolved decisions, and evidence standard.
-4. Select only the research lanes that the uncertainty requires:
-   - problem and product: `references/problem-product.md`;
-   - users and scope: `references/users-scope.md`;
-   - architecture: `references/architecture.md`;
-   - quality and delivery: `references/quality-delivery.md`;
-   - final traceability: `references/synthesis.md`.
+1. Call `baseline.get`. Route absent, migrated, unreadable, or corrupt authority to
+   `ultra-init` or `ultra-doctor` as reported.
+2. Call `workflow.list` for `kind: "research"` and the bound baseline or change. Resume
+   the active, blocked, or ready run; use `workflow.get` before doing more work.
+3. When no run exists:
+   - start `full` for an initial greenfield baseline;
+   - start `adoption` for a brownfield baseline;
+   - use `product`, `feature`, `architecture`, or `custom` only when the owner
+     explicitly selected that bounded scope for an active change.
 
-Read a reference completely only when its lane is selected. Do not load all lanes by
-default.
+Never infer an MVP, reduced product posture, skipped step, or release phase. Full and
+adoption modes execute all seventeen semantic steps. A custom run records every
+excluded step and its selection reason in DB.
 
-## Evidence discipline
+## Execute one recoverable step at a time
 
-- Prefer the current checkout and existing project artifacts for repository facts.
-- Browse only when a claim is external, unstable, or requires primary-source support.
-- Prefer official and primary sources; cite each consequential external claim near the
-  statement it supports.
-- Separate observed facts, evidence-backed inferences, user decisions, and unresolved
-  assumptions.
-- Do not manufacture confidence percentages, market numbers, personas, competitors,
-  or options when evidence does not support them.
+Read only the reference matching `workflow.next_step.step_id`:
 
-## Workflow
+| Step | 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` |
 
-1. Build a short research agenda from the selected lanes and the decisions they must
-   unlock.
-2. Gather evidence before recommending a direction. Ask one concise question when a
-   user decision is load-bearing; batch independent low-impact questions only when it
-   improves flow.
-3. Present material tradeoffs before recording a decision. Comparisons are appropriate
-   only when real alternatives share meaningful criteria.
-4. Update the relevant baseline specification sections. Preserve source links,
-   decisions, rejected alternatives when useful, acceptance criteria, and explicit
-   open questions. Do not duplicate the same narrative across several files.
-5. Validate cross-document consistency and trace each required behavior from problem
-   or constraint to acceptance and architecture.
-6. Use `references/synthesis.md` for the completion check.
-7. Record unresolved evidence as the baseline gap ledger: `baseline_blocker`,
-   `documentation_drift`, `known_defect`, `technical_debt`, `unknown`, or
-   `future_change`. Keep accepted non-blocking work out of the implementation backlog
-   until the owner selects it.
-8. Call `baseline.record` with the complete current specification list, bounded evidence
-   references, actual verification results, provider metadata, explicit unknowns,
-   classification, and the full gap ledger. Use the returned repository revision for
-   convergence.
-9. Present the baseline, open gaps, dirty-worktree state, and any known-red verification
-   to the owner. After explicit approval, call `baseline.converge`, setting acceptance
-   flags only for the exact known-red or dirty snapshot approved by the owner. Resolve
-   deterministic blockers before routing.
+For each selected step:
 
-## Completion gate
+1. Inspect current repository and specification evidence before asking the owner to
+   repeat known facts. Browse only for unstable or external claims, using primary
+   sources where possible.
+2. Separate `Observed`, `Verified`, `Decided`, and `Unknown`. Ask one concise question
+   only when the answer changes scope, product intent, security, cost, or another
+   load-bearing decision.
+3. Update the relevant baseline specification or active change research artifact.
+   Preserve citations, decisions, drift, and unresolved gaps without duplicating prose.
+4. Write one immutable step report at
+   `.ultra/docs/research/<workflow-id>/<step-id>.md`. It must have a title and the
+   sections `Evidence`, `Specification updates`, and `Decisions and unknowns`. Link
+   specification anchors and external sources; do not copy transcripts or provider
+   payloads.
+5. Call `workflow.step` with `completed`, bounded evidence references, that step report
+   as `research-step-report`, material decisions, and one or more `semantic_records`.
+   Each record has a stable `id`, the step-specific `kind` and `attributes` named in
+   its reference, a status (`observed`, `verified`, `decided`, `accepted`, `unknown`,
+   or `not_applicable`), a concise summary, evidence refs, optional typed links, and a
+   project-relative `source_ref` using `path#anchor`. Use the immutable step report as
+   the source when later edits could change a shared specification. MCP verifies the
+   anchor and stores its digest; `not_applicable` requires an evidence-backed rationale.
+6. For `99-synthesis` in `full` or `adoption` mode, also bind the current
+   `discovery.md`, `product.md`, `architecture.md`, and `research-distillate.md` as
+   outputs. This freezes the exact researched baseline without making the reports a
+   second specification authority.
+7. If evidence or owner authority is missing, call `workflow.step` with `blocked` and
+   specific blocker codes. Resume that same step after resolution; never skip a
+   required step to obtain a ready state.
 
-Research is complete when the selected scope has enough evidence for planning, every
-material decision is recorded, required acceptance is testable, architecture respects
-known constraints, and unresolved items are either blocking or explicitly outside the
-accepted scope.
+## Converge
 
-Route a converged baseline to `ultra-plan`. Do not create business tasks, write raw
-SQLite, or maintain a second condensed specification that can drift from the baseline.
+When all selected steps are ready, call `workflow.complete` and read the completed run
+back. Missing or stale output blocks completion.
+
+For initial or adoption research, call `baseline.record` with discovery, product, and
+architecture specification refs; current repository revision and scope; bounded source,
+docs, runtime, test, deployment, and external evidence; actual verification commands
+and results; unknowns; the complete gap ledger; classification; and external provider
+metadata references. Do not store prompts, transcripts, memory, or graph content.
+
+Present the recorded revision, worktree snapshot, known failures, blockers, and gaps.
+Only after explicit owner approval call `baseline.converge`. Accept known-red or a
+dirty worktree only when that exact snapshot was approved. Convergence must verify the
+completed full/adoption research run and current output digests.
+
+Return the workflow id, all seventeen step-report paths for full/adoption research,
+the four synthesis artifacts, baseline status, open gaps, approval state, and one exact
+next route. A ready initial baseline routes to `ultra-change`; bounded change research
+returns to its change breadcrumb and then `ultra-plan` when the research gate is ready.