ultra-builder-pro-cli 0.12.1 → 0.14.0

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

@@ -1,65 +1,93 @@
 # Brownfield adoption
 
-Use this procedure only after `task.init_project` selects `brownfield`, or when an
-existing baseline remains `adopting` or `blocked`.
+Execute this procedure for a detected brownfield repository, a migrated compatibility
+baseline, or an existing adoption in `adopting` or `blocked` state.
 
-## Establish the snapshot boundary
+## Bind the repository boundary
 
-Bind the repository root, current Git HEAD when available, included paths, excluded
-generated or vendored paths, project manifests, and the user-visible or public seams.
-Use the revision returned by `baseline.record`; non-Git projects receive a deterministic
-workspace revision from the recorded evidence.
+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.
 
-## Read current behavior
+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.
 
-Inspect only the evidence needed to explain the maintained system:
+## Build the evidence model
 
-- entry points and consumers;
-- persisted state and its writers;
-- external interfaces, events, permissions, and failure paths;
-- tests and their live seams;
-- deployment, migration, and recovery paths when present;
-- maintained documents and their relationship to source.
+Inspect the maintained system through its live boundaries:
 
-Classify every statement as observed, verified, decided, or unknown. Source and runtime
-evidence outrank stale prose. External memory and code-graph providers may supply
-references, but their content remains outside Ultra state.
+- 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.
 
-## Capture the baseline
+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.
 
-Update `.ultra/specs/product.md` with confirmed behavior, actors, entry points, failures,
-and acceptance. Update `.ultra/specs/architecture.md` with actual boundaries, authority,
-runtime paths, dependencies, permissions, and recovery. Use `discovery.md` only for
-evidence or decisions that affect scope.
+## Write baseline artifacts
 
-Do not redesign the project, normalize it to a preferred architecture, manufacture
-personas or alternatives, or convert every source file into documentation.
+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. Mark an unknown blocking when it can change accepted
-behavior, authority, security, data integrity, or the next implementation plan.
+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.
 
-The server computes specification digests. Do not send prompt, transcript, memory, or
-code-graph payloads.
+Use the server-returned revision, branch, worktree digest, and specification digests.
 
-## Converge
+## Obtain approval and converge
 
-Present the observed behavior, known-red verification, blocking unknowns, and material
-decisions to the project owner. After explicit approval, call `baseline.converge` with
-the recorded revision, approver, approval note, and `accept_known_red` only when the
-owner accepted those failures.
+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` and `system.doctor`
-report the baseline ready and current. Route the first new outcome to `ultra-change`, or
-route planning of already accepted work to `ultra-plan`.
+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

@@ -16,8 +16,10 @@ route to `ultra-doctor`. Never read or write `.ultra/tasks/tasks.json` as a fall
 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. Convergence still requires approved
-adoption, and archive atomically reconciles and verifies revision/spec drift.
+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:
 
@@ -63,11 +65,22 @@ id when applicable.
 
 ## PRD mode
 
-1. Call `task.parse_prd` with `dry_run: true`.
-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.
+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
 

package/skills/ultra-research/SKILL.md

@@ -51,11 +51,18 @@ default.
 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. Call `baseline.record` with the complete current specification list, bounded evidence
-   references, actual verification results, provider metadata, and explicit unknowns.
-   Use the returned repository revision for convergence.
-8. Present the baseline and any known-red verification to the owner. After explicit
-   approval, call `baseline.converge`. Resolve deterministic blockers before routing.
+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
 

package/skills/ultra-status/SKILL.md

@@ -12,8 +12,8 @@ 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 `baseline.get` for mode, lifecycle status, repository revision, specification
-   digest health, known warnings, and adoption blockers.
+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.
@@ -30,7 +30,9 @@ 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 with no active change: `ultra-init`, then
+- 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;
@@ -50,7 +52,7 @@ 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>
+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>

package/skills/ultra-verify/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: ultra-verify
-description: Run independent two-model verification with the current host as primary and a read-only external advisor, then verify and synthesize both evidence sets. Use only when the user explicitly requests cross-model verification.
+description: Run independent two-model verification with the current host as primary and one installed read-only advisor, then verify and synthesize both evidence sets. Use only when the user explicitly requests cross-model verification.
 ---
 
 # Run independent cross-model verification
 
-Claude Code writes the first analysis, verifies consequential claims, and owns the
-final answer. Codex is an untrusted read-only advisor.
+Keep the current host responsible for scope, evidence, edits, verification, and the
+final answer. Use one installed collaboration companion that invokes a different CLI;
+never recurse into the current host or treat advisor output as authority.
 
 ## Modes
 
@@ -17,36 +18,26 @@ final answer. Codex is an untrusted read-only advisor.
 
 ## Workflow
 
-1. Confirm the advisor CLI and authentication. Define the exact workspace, question,
-   evidence standard, and response shape. Exclude secrets and unrelated files.
-2. Create `.ultra/collab/<session-id>/` and write the primary host's evidence-backed
-   analysis to `claude-analysis.md` before reading advisor output.
-3. Launch Codex with the raw bounded question and evidence in a read-only sandbox. Do
-   not include the primary conclusion when independence matters:
-
-   ```bash
-   codex exec -s read-only \
-     -a never \
-     --ephemeral \
-     --ignore-user-config \
-     --ignore-rules \
-     -o "${SESSION_PATH}/codex-output.md" \
-     "<bounded prompt>" \
-     2> "${SESSION_PATH}/codex-error.log"
-   ```
-4. Run `scripts/verify_wait.py` resolved relative to this skill directory. Use a
-   yielded or asynchronous shell session and poll at bounded intervals; do not hold a
-   blocking tool call longer than one minute.
+1. Define the workspace, question, evidence standard, and response shape. Confirm the
+   selected advisor CLI and authentication. Exclude secrets and unrelated files.
+2. Create `.ultra/collab/<session-id>/` and write the current host's independent,
+   evidence-backed analysis to `host-analysis.md` before reading advisor output.
+3. Follow the installed collaboration companion's read-only invocation contract. Give
+   the advisor the same bounded question and evidence, without the primary conclusion
+   when independence matters. Store its result as `advisor-output.md` and diagnostics
+   as `advisor-error.log`.
+4. Run `scripts/verify_wait.py <session-path> --advisor advisor --output
+   advisor-output.md` from this skill directory. Use a yielded shell session and poll
+   in bounded intervals; do not hold one blocking tool call longer than one minute.
 5. Read advisor output only after the waiter reports a complete, non-empty file.
-6. Verify both analyses against the current checkout, tests, runtime, or primary
-   documentation. Explain scope, version, evidence, and assumption differences before
-   judging disagreement.
-7. Write session metadata and a synthesis artifact, then return one host-owned
-   conclusion.
+6. Verify consequential claims against the current checkout, tests, runtime, or
+   primary documentation. Explain scope, version, evidence, and assumption differences
+   before resolving disagreement.
+7. Write `metadata.json` and `synthesis.md`, then return one host-owned conclusion.
 
 Read `references/cross-verify-modes.md` for mode-specific evidence and
 `references/confidence-system.md` when confidence language is useful. Model agreement
 never overrides failing tests or authoritative runtime evidence.
 
-Advisor failure degrades to the primary analysis with a single-source warning. It does
-not block the user's underlying task.
+Advisor failure degrades to the primary analysis with a single-source warning. It
+never blocks the user's underlying task.

package/skills/ultra-verify/scripts/verify_wait.py

@@ -1,19 +1,16 @@
 #!/usr/bin/env python3
-"""File-based completion waiter for the Ultra Verify advisor.
-
-Poll the session directory until the expected output is non-empty and stable, or until timeout.
-The JSON result carries the operational status; timeout is not a process error.
-"""
+"""Wait for one named advisor output file to become non-empty and stable."""
 
+import argparse
 import json
+import re
 import sys
 import time
 from pathlib import Path
 
 POLL_INTERVAL = 3
 DEFAULT_TIMEOUT = 1200
-ADVISOR = "codex"
-OUTPUT_FILE = "codex-output.md"
+SAFE_ADVISOR = re.compile(r"^[a-zA-Z0-9_-]+$")
 
 
 def _file_size(path: Path) -> int:
@@ -23,71 +20,74 @@ def _file_size(path: Path) -> int:
         return -1
 
 
-def _check_output(session_path: Path) -> dict:
-    output = session_path / OUTPUT_FILE
+def _safe_output(value: str) -> Path:
+    result = Path(value)
+    if result.is_absolute() or len(result.parts) != 1 or result.name in {"", ".", ".."}:
+        raise argparse.ArgumentTypeError("--output must be one file name inside the session directory")
+    return result
+
+
+def _arguments():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("session_path", type=Path)
+    parser.add_argument("--advisor", default="advisor")
+    parser.add_argument("--output", type=_safe_output, default=Path("advisor-output.md"))
+    parser.add_argument("--timeout", type=int, default=DEFAULT_TIMEOUT)
+    args = parser.parse_args()
+    if not SAFE_ADVISOR.fullmatch(args.advisor):
+        parser.error("--advisor must use letters, numbers, underscore, or hyphen")
+    if args.timeout < 0:
+        parser.error("--timeout must be non-negative")
+    if not args.session_path.is_dir():
+        parser.error(f"session directory not found: {args.session_path}")
+    return args
+
+
+def _status(session_path: Path, advisor: str, output_name: Path) -> dict:
+    output = session_path / output_name
     if _file_size(output) > 0:
-        return {"name": ADVISOR, "status": "complete", "file": str(output)}
-    return {"name": ADVISOR, "status": "pending", "file": None}
+        return {"name": advisor, "status": "complete", "file": str(output)}
+    return {"name": advisor, "status": "pending", "file": None}
 
 
-def _timeout_status(session_path: Path) -> dict:
-    output = session_path / OUTPUT_FILE
-    error = session_path / f"{ADVISOR}-error.log"
+def _timeout_status(session_path: Path, advisor: str, output_name: Path) -> dict:
+    output = session_path / output_name
+    error = session_path / f"{advisor}-error.log"
     output_size = _file_size(output)
     if output_size > 0:
-        return {"name": ADVISOR, "status": "complete", "file": str(output)}
+        return {"name": advisor, "status": "complete", "file": str(output)}
     if _file_size(error) > 0:
-        return {"name": ADVISOR, "status": "failed", "file": str(error)}
+        return {"name": advisor, "status": "failed", "file": str(error)}
     if output_size == 0:
-        return {"name": ADVISOR, "status": "empty", "file": str(output)}
-    return {"name": ADVISOR, "status": "pending", "file": None}
+        return {"name": advisor, "status": "empty", "file": str(output)}
+    return {"name": advisor, "status": "pending", "file": None}
 
 
 def main() -> None:
-    if len(sys.argv) < 2:
-        print(__doc__, file=sys.stderr)
-        sys.exit(2)
-
-    session_path = Path(sys.argv[1])
-    timeout = DEFAULT_TIMEOUT
-    if "--timeout" in sys.argv:
-        idx = sys.argv.index("--timeout")
-        if idx + 1 >= len(sys.argv):
-            print("Error: --timeout requires an integer", file=sys.stderr)
-            sys.exit(2)
-        try:
-            timeout = int(sys.argv[idx + 1])
-        except ValueError:
-            print(f"Error: --timeout must be integer: {sys.argv[idx + 1]}", file=sys.stderr)
-            sys.exit(2)
-        if timeout < 0:
-            print("Error: --timeout must be non-negative", file=sys.stderr)
-            sys.exit(2)
-
-    if not session_path.is_dir():
-        print(f"Error: session directory not found: {session_path}", file=sys.stderr)
-        sys.exit(2)
-
-    deadline = time.monotonic() + timeout
-    previous_size = _file_size(session_path / OUTPUT_FILE)
+    args = _arguments()
+    output = args.session_path / args.output
+    deadline = time.monotonic() + args.timeout
+    previous_size = _file_size(output)
     while time.monotonic() < deadline:
-        current_size = _file_size(session_path / OUTPUT_FILE)
-        advisor = _check_output(session_path)
-        stable = advisor["status"] == "complete" and current_size == previous_size
-        if stable:
-            elapsed = int(timeout - (deadline - time.monotonic()))
-            print(json.dumps({"status": "complete", ADVISOR: advisor, "elapsed_seconds": elapsed}))
+        current_size = _file_size(output)
+        advisor = _status(args.session_path, args.advisor, args.output)
+        if advisor["status"] == "complete" and current_size == previous_size:
+            elapsed = int(args.timeout - (deadline - time.monotonic()))
+            print(json.dumps({
+                "status": "complete", "advisor": advisor, "elapsed_seconds": elapsed,
+            }))
             return
-
         state = "stabilizing" if advisor["status"] == "complete" else "waiting"
         remaining = max(0, int(deadline - time.monotonic()))
-        sys.stderr.write(f"\r  [0/1] {ADVISOR}:{state} ({remaining}s remaining)  ")
+        sys.stderr.write(f"\r  [0/1] {args.advisor}:{state} ({remaining}s remaining)  ")
         sys.stderr.flush()
         previous_size = current_size
         time.sleep(POLL_INTERVAL)
 
-    advisor = _timeout_status(session_path)
-    print(json.dumps({"status": "timeout", ADVISOR: advisor, "elapsed_seconds": timeout}))
+    advisor = _timeout_status(args.session_path, args.advisor, args.output)
+    print(json.dumps({
+        "status": "timeout", "advisor": advisor, "elapsed_seconds": args.timeout,
+    }))
 
 
 if __name__ == "__main__":

package/spec/cli-protocol.md

@@ -120,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).