ultra-builder-pro-cli 0.16.0 → 0.17.1

package/skills/ultra-init/SKILL.md

@@ -1,109 +1,82 @@
 ---
 name: ultra-init
-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.
+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.
 ---
 
-# 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
-
-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.
-
-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.
+# 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/state.db` exists, run `system.doctor` read-only and resume with
+   `task.init_project` only when its report permits it.
+3. Otherwise call `task.init_project` with `mode: "auto"`, the project name, and an
+   explicit scope only when the repository contains multiple plausible roots.
+4. Leave `git_mode` as `auto` unless the user explicitly requires a non-Git workspace.
+
+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/state.db` with a backup before schema migration;
+- install only missing scaffold assets on resume;
+- preserve existing artifacts and unrelated work;
+- preserve an existing Git repository and HEAD;
+- initialize Git and a safe `.gitignore` entry when Git is absent;
+- report an unborn repository as `initial_commit_required` without manufacturing a
+  commit, remote, tag, or push;
+- read back the created DB, classification, projection, and Git result before
+  completing the init workflow.
+
+Projection-only projects must use the exact backup-first migration command returned by
+the runtime. A migrated compatibility baseline requires a new brownfield adoption with
+`replace_migrated: true`. Replacing a healthy baseline requires explicit replacement
+authority. Corrupt DB, WAL, SHM, and backups must be preserved until the user chooses a
+documented recovery operation.
+
+## Completion and handoff
+
+Initialization is complete when the init workflow is `completed`, the current schema is
+healthy, the scaffold is readable, and repository classification and Git state are
+durable. Research status may still be `not_started`; that is not incomplete init.
+
+Read the returned `allowed_transitions` and `required_transition`:
+
+- a required transition represents a hard recovery invariant and must be followed;
+- otherwise the host model recommends among the allowed capabilities using the user's
+  goal and current evidence;
+- start `ultra-research` only when the user invoked it or the host selects it after init.
+
+Report classification, scope, schema and backup result, Git state, init workflow id,
+baseline state, and allowed transitions. Do not claim that a baseline is ready until a
+separate research/adoption workflow has recorded and converged it.

package/skills/ultra-plan/SKILL.md

@@ -1,103 +1,82 @@
 ---
 name: ultra-plan
-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.
+description: Turn an accepted Ultra Change Contract into dependency-valid, DB-backed vertical task contracts. Use when research obligations are resolved and implementation needs an executable plan.
 ---
 
-# 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.
+# 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, baseline, change, decisions, existing plan runs, tasks, and current
+   checkout.
+2. Require one mutable change with a healthy baseline or recorded incident bypass.
+3. Complete the exact change-bound research disposition before planning.
+4. Resume the matching plan run or start one bound to the change and baseline.
+
+Read `references/semantic-preflight.md` and inspect requirements, real consumers,
+state, tests, deployment, and recovery paths.
+
+## Design with model autonomy
+
+Build a candidate plan privately. Ask the user only if the plan would change accepted
+scope, public behavior, compatibility, security, material cost, external effects, or
+recovery. Use the host's native question UI when available and the interaction protocol
+in `../ultra-think/references/decision-dialogue.md`.
+
+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. `analyze-requirements`
+3. `analyze-codebase`
+4. `design-slices`
+5. `validate-dependencies`
+6. `persist-task-contracts`
+7. `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.
+
+## Persist task contracts
+
+Create each task with:
+
+- observable outcome and stable trace;
+- `slice_kind`, public seam, and exact verification command;
+- structured acceptance mapped to Change acceptance ids;
+- bounded context refs and reasons;
+- documentation impact, ownership, dependencies, and affected files when known.
+
+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 a generated projection, not authority.
+
+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
+`.ultra/execution-plan.json` with `plan.export`, read it through `plan.get`, and record
+it as the `verify-plan` output.
+
+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 task context later for the consumer that needs it.
+
+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.