ultra-builder-pro-cli 0.11.0 → 0.13.0

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

@@ -0,0 +1,93 @@
+# Brownfield adoption
+
+Execute this procedure for a detected brownfield repository, a migrated compatibility
+baseline, or an existing adoption in `adopting` or `blocked` state.
+
+## Bind the repository boundary
+
+Record the repository root, selected scope, workspace roots, branch, HEAD, dirty files,
+generated and vendored exclusions, manifests, verification commands, and public seams.
+Use `.` for a whole-repository adoption. Use selected workspace roots only when the
+user's requested ownership is narrower than the monorepo.
+
+The authoritative worktree snapshot contains only selected-scope paths. Report dirty
+files outside that scope separately as repository context, but do not include them in
+the baseline digest. Require `accept_dirty_worktree: true` only after the owner confirms
+the exact in-scope `worktree_files` returned by the server.
+
+## Build the evidence model
+
+Inspect the maintained system through its live boundaries:
+
+- product behavior, actors, entry points, and public acceptance;
+- runtime modules, consumers, data flow, persistence, and authority;
+- APIs, events, integrations, permissions, security, and failure paths;
+- build, test, lint, typecheck, deployment, migration, observability, and recovery;
+- maintained documents and every detected source-to-document conflict.
+
+Classify each material statement as `Observed`, `Verified`, `Decided`, or `Unknown`.
+Record document/source conflicts as drift. Keep provider payloads outside Ultra and
+record only bounded metadata references.
+
+## Write baseline artifacts
+
+Update `.ultra/specs/product.md` with current delivered behavior and acceptance. Update
+`.ultra/specs/architecture.md` with real boundaries, owners, writers, consumers,
+consistency rules, permissions, failures, and recovery. Use `discovery.md` for scope
+evidence, decisions, and unresolved questions.
+
+Capture current facts without redesigning the application or manufacturing product
+narratives that are absent from evidence.
+
+## Run characterization verification
+
+Run the repository's existing verification commands. Record each result as `pass`,
+`known_red`, or `not_run`. A known-red item needs evidence and a rationale; a missing
+command is not a passing result. Record a characterization gap for a critical public
+seam that has no stable verification signal; create its ordinary task only after the
+baseline is ready.
+
+## Maintain the gap ledger
+
+Record every adoption gap with a stable id, evidence references, owner, blocking flag,
+and one category:
+
+- `baseline_blocker`: prevents trustworthy adoption;
+- `documentation_drift`: maintained prose conflicts with observed behavior;
+- `known_defect`: reproducible incorrect behavior;
+- `technical_debt`: accepted maintainability or quality cost;
+- `unknown`: evidence is insufficient;
+- `future_change`: desired behavior outside the current baseline.
+
+Use `open` for unresolved gaps, `accepted` for owner-accepted non-blocking debt,
+`resolved` when evidence closes the gap, and `deferred` for explicitly postponed
+non-blocking work. Every open `baseline_blocker` remains blocking. Do not convert the
+ledger into hundreds of application tasks.
+
+## Record authority
+
+Call `baseline.record` with full replacement arrays for:
+
+- scope and repository revision;
+- repository classification;
+- product and architecture specification paths;
+- bounded source, documentation, runtime, test, deployment, or external references;
+- verification results;
+- blocking and non-blocking unknowns;
+- the complete gap ledger;
+- external provider metadata references, when supplied.
+
+Use the server-returned revision, branch, worktree digest, and specification digests.
+
+## 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.
+
+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`.

package/skills/ultra-plan/SKILL.md

@@ -13,6 +13,13 @@ Markdown are generated projections.
 
 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:
 
@@ -30,8 +37,10 @@ current evidence. A material unresolved assumption blocks persistence.
 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 returned by the current Ultra contract. Widen it only when
-   an approved slice cannot be split without losing correctness.
+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.
@@ -56,11 +65,12 @@ id when applicable.
 
 ## PRD mode
 
-1. Call `task.parse_prd` with `dry_run: true`.
+1. Call `task.parse_prd` with `dry_run: true` and the active `change_id` when
+   applicable.
 2. Show the proposed slices, topology, conflict surface, and cost estimate.
 3. Require explicit approval; rejection performs no state write.
-4. On approval, repeat with `dry_run: false`, export the plan, and verify that the
-   dry-run and persisted task identities agree.
+4. On approval, repeat with `dry_run: false` and the same change ownership, export
+   the plan, and verify that the dry-run and persisted task identities agree.
 
 ## Completion gate
 

package/skills/ultra-research/SKILL.md

@@ -10,8 +10,8 @@ decision. Do not force a fixed discovery ceremony onto a well-defined change.
 
 ## Preflight
 
-1. Require an initialized `.ultra/specs/` directory. Route to `ultra-init` when it is
-   absent.
+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.
@@ -50,7 +50,19 @@ default.
    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 and report one next action.
+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.
 
 ## Completion gate
 
@@ -59,5 +71,5 @@ material decision is recorded, required acceptance is testable, architecture res
 known constraints, and unresolved items are either blocking or explicitly outside the
 accepted scope.
 
-Route a validated baseline to `ultra-plan`. Do not create business tasks, write Ultra
-state, or maintain a second condensed specification that can drift from the baseline.
+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.

package/skills/ultra-status/SKILL.md

@@ -12,12 +12,14 @@ authoritative; reports and Markdown are evidence or projections.
 
 1. Call `system.doctor` in read-only mode. If authority is unhealthy, route only to
    `ultra-doctor` and include the blocking diagnostic.
-2. Call `change.breadcrumb` for the active change, task, role, gate, readiness,
-   blockers, staleness, and next action.
-3. Call `task.list` and `session.list` for progress and active execution details.
-4. Read test and delivery reports only when present, and mark a report stale when its
+2. Call `baseline.get` for mode, lifecycle status, repository revision, branch,
+   worktree snapshot, specification digest health, gap ledger, and adoption blockers.
+3. Call `change.breadcrumb` for the active change, task, role, gate, readiness,
+   blockers, advisory warnings, staleness, and next action.
+4. Call `task.list` and `session.list` for progress and active execution details.
+5. Read test and delivery reports only when present, and mark a report stale when its
    HEAD differs from the current checkout.
-5. Read Git branch, HEAD, and worktree status without mutation.
+6. Read Git branch, HEAD, and worktree status without mutation.
 
 If MCP task or change state is unavailable, label that panel unavailable. Never fall
 back to generated task JSON, context frontmatter, or raw SQLite.
@@ -28,7 +30,12 @@ Follow the breadcrumb's primary route and return one action, not a menu:
 
 - unhealthy authority: `ultra-doctor`;
 - missing Ultra project: `ultra-init`;
-- missing baseline evidence: `ultra-research` or `ultra-plan`, matching the gap;
+- projection-only authority conflict: run the exact supported import command from the
+  MCP error, then `ultra-init`;
+- migrated or missing baseline evidence with no active change: `ultra-init`, then
+  `ultra-research` or `ultra-plan` according to the gap;
+- baseline or context-budget warning during an active change: keep the current route
+  and surface the warning; do not turn it into a refusal;
 - blocked or stale context: the workflow named by the breadcrumb;
 - ready implementation task: `ultra-dev <task-id>`;
 - completed tasks with missing or stale test evidence: `ultra-test`;
@@ -45,7 +52,9 @@ Use a compact shape:
 ```text
 Ultra: <healthy|degraded> · <branch>@<head> · worktree <clean|dirty>
 Position: change=<id|none> task=<id|none> role=<role> gate=<gate>
+Baseline: <greenfield|brownfield|migrated>/<status> revision=<revision|none> gaps=<open>/<blocking>
 Readiness: <ready|blocked|stale> — <blockers or none>
+Warnings: <advisory conditions or none>
 Progress: <completed>/<total>; sessions=<active count>
 Evidence: tests=<fresh|stale|missing>; delivery=<fresh|stale|missing>
 Next: <one exact action>

package/spec/cli-protocol.md

@@ -100,6 +100,10 @@ as a fallback unless `ultra-tools <family> --help` lists it.
 | `session.admission_check` | `session admission`         | 4.5   | any     |
 | `session.heartbeat`       | `session heartbeat`         | 4.5   | mcp     |
 | `session.subscribe_events`| `session subscribe`         | 4.5   | any     |
+| `baseline.start`          | `baseline start`            | 11    | mcp     |
+| `baseline.record`         | `baseline record`           | 11    | mcp     |
+| `baseline.get`            | `baseline get`              | 11    | any     |
+| `baseline.converge`       | `baseline converge`         | 11    | mcp     |
 | `change.create`           | `change create`             | 9     | mcp     |
 | `change.update`           | `change update`             | 9     | mcp     |
 | `change.get`              | `change get`                | 9     | any     |
@@ -116,10 +120,20 @@ as a fallback unless `ultra-tools <family> --help` lists it.
 
 Current executable maintenance surfaces are `task init-project`,
 `session close|get|list|admission|heartbeat|subscribe|reap`, `status`, `db`,
-`migrate`, and `legacy-memory`. In particular, `task create|update|list|get`
+`migrate`, `system doctor|restore|rebaseline`, and `legacy-memory`. In particular, `task create|update|list|get`
 and all `change` lifecycle verbs are not CLI fallbacks. Change state must use
 the live MCP server; `system doctor` may additionally be exposed by the
 maintenance CLI because it is the recovery path when MCP startup is degraded.
+`task init-project --resume` preserves existing `.ultra` files and installs only
+missing current scaffold assets. Projection-only state uses the supported
+`migrate --from=4.4 --to=4.5` or `--from=4.5 --to=12.0` transition before resume.
+`system doctor --repair` applies supported schema upgrades with a pre-migration
+backup before mechanical recovery.
+`system restore` requires the exact `REPLACE_CORRUPT_ULTRA_STATE` confirmation and a
+verified database inside `.ultra/backups`; it quarantines the corrupt state before
+atomic replacement. `system rebaseline` requires the exact
+`REBASELINE_CORRUPT_ULTRA_STATE` confirmation and preserves corrupt state plus the
+legacy task projection before starting a new brownfield adoption.
 The full access policy lives in
 `docs/STATE-DB-ACCESS-POLICY.md` (Phase 2.2 / R25).