ultra-builder-pro-cli 0.22.0 → 0.24.0

package/skills/ultra-review/SKILL.md

@@ -1,62 +1,44 @@
 ---
 name: ultra-review
-description: Independently review one current Ultra plan, task diff, or aggregate change on specification fidelity and engineering standards. Use when current evidence needs a review gate or focused risk analysis.
+description: Independently review one current Ultra plan, task diff, or aggregate Change on specification fidelity and engineering standards. Use when current evidence needs review or focused risk analysis.
 ---
 
 # Review one bounded scope
 
 Keep two independent verdict axes:
 
-- `spec_fidelity`: accepted intent, behavior, documentation impact, and public seams;
-- `engineering_standards`: correctness, safety, tests, integration, maintainability,
-  observability, and recovery.
+- `spec_fidelity`: accepted intent, behavior, docs, and public seams;
+- `engineering_standards`: correctness, safety, tests, integration,
+  maintainability, observability, and recovery.
 
-Neither axis can compensate for the other.
+## Bind and review
 
-## Bind evidence
+1. Read `references/review-modes.md`.
+2. Call `ultra.context { stage: review, scope: { change_id, task_id? }, detail: full }`.
+3. Import a newer team checkpoint with `ultra.sync`; stop on a real conflict.
+4. Bind one explicit diff or Plan, full HEAD, worktree digest, task set, acceptance,
+   decisions, and current evidence. Empty or stale scope cannot pass.
+5. Always run `review-spec`. Select the smallest engineering worker set that covers
+   actual risk; record selected and excluded roles with rationale.
 
-1. Read `references/review-modes.md` and select `plan`, `task`, or `change` from the
-   actual review request.
-2. Read doctor and `task.ledger_get`. Import a newer descendant checkpoint before
-   binding the review scope; stop on a typed merge conflict.
-3. Bind one explicit diff or plan artifact, full HEAD, worktree digest, task set,
-   acceptance, breadcrumb `accepted_intent`, and current decision state.
-4. Resume or start the review workflow and record `bind-diff`.
-5. Compile `change.context` for `review` and record the immutable manifest under
-   `compile-context`.
+Use the current host's native bounded-worker mechanism. Workers are read-only and
+receive one immutable Worker Packet containing the exact Context Envelope, HEAD/diff,
+decisions, acceptance, output path/schema, and `packet_digest`. Validate their artifacts with `scripts/review_wait.py` and
+`references/unified-schema.md`; reject any output that does not echo the exact packet
+digest. Preserve every finding unchanged in `SUMMARY.json`; group duplicates only in
+the human summary.
 
-An empty, ambiguous, or stale scope cannot pass.
+Register specialist and summary artifacts through one `ultra.record` batch using
+`artifact / bind`.
 
-## Select workers by risk
+## Checkpoint
 
-Always run `review-spec`. Select the smallest engineering worker set that covers the
-actual diff and risk. Record every selected and excluded worker with a specific
-rationale; do not run every specialist ceremonially.
+Call `ultra.checkpoint` once with `stage: review`, exact scope, evidence, and outputs
+tagged `spec_review`, `engineering_review`, or summary. The checkpoint compiles or
+reuses review context and derives both axes from registered artifacts.
 
-Invoke workers through the current host's native bounded-worker mechanism and pass
-only their role, current scope, and relevant evidence. Workers are read-only and may
-not decide owner choices or edit source.
+A rejected checkpoint leaves the draft mutable. Fix stale scope or evidence and retry;
+do not open a replacement run or suppress a finding.
 
-Resolve `references/unified-schema.md` from this Skill directory and pass its absolute
-path as `SCHEMA_PATH`. Validate specialist artifacts with
-`scripts/review_wait.py`. Store all specialist artifacts and `SUMMARY.json` below
-`.ultra/changes/active/<change-id>/review/<workflow-id>/`. Record outputs under
-`review-specification`, `review-engineering`, and `coordinate-findings`.
-
-The coordinator preserves every finding unchanged in `SUMMARY.json`; it may group
-duplicate root causes only in the human summary. A new material owner choice remains a
-finding and routes to the interaction protocol.
-
-## Complete
-
-Recheck HEAD, worktree, context digest, diff, task set, acceptance, artifact schemas,
-and both axes. Record `verify-review-gate`, then call `workflow.complete`. MCP derives
-the durable verdict and rejects missing specialists, lossy coordination, stale
-artifacts, or prompt-supplied conclusions.
-
-Any relevant code, test, specification, or contract edit invalidates the affected
-review evidence through registered provenance edges; unrelated evidence remains
-current. Return both verdict axes, blocking findings, reviewed scope, worker selection
-rationale, artifact digests, and allowed transitions.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+Return both axes, findings, reviewed scope, worker rationale, digests, and the model's
+recommended next explicit capability. Do not invoke it automatically.

package/skills/ultra-review/references/unified-schema.md

@@ -10,6 +10,7 @@ return only a one-line acknowledgement to the parent.
   "$schema": "ultra-review-findings-v2",
   "agent": "review-code",
   "axis": "engineering_standards",
+  "packet_digest": "<sha256-of-exact-worker-packet>",
   "session": "<session-id>",
   "timestamp": "<ISO-8601>",
   "scope": {
@@ -74,6 +75,7 @@ preference as a defect. Preserve the source specialist's severity during coordin
   "head": "<full-git-head>",
   "worktree_digest": "<sha256-of-current-worktree>",
   "context_digest": "<sha256-of-recorded-review-context>",
+  "packet_digest": "<sha256-of-coordinator-worker-packet>",
   "status": "complete",
   "verdict": "REQUEST_CHANGES",
   "axes": {

package/skills/ultra-review/scripts/review_wait.py

@@ -66,6 +66,10 @@ def nonempty_string(value) -> bool:
     return isinstance(value, str) and bool(value.strip())
 
 
+def digest_string(value) -> bool:
+    return isinstance(value, str) and re.fullmatch(r"[0-9a-f]{64}", value) is not None
+
+
 def validate_finding(finding, artifact_axis: str, seen_ids):
     if not isinstance(finding, dict):
         return "finding must be an object"
@@ -97,6 +101,8 @@ def validate_specialist(data):
         return f"$schema must be {FINDINGS_SCHEMA}"
     if not nonempty_string(data.get("agent")):
         return "agent must be a non-empty string"
+    if not digest_string(data.get("packet_digest")):
+        return "packet_digest must be a lowercase SHA-256 digest"
     axis = data.get("axis")
     if axis not in AXES:
         return "axis must be spec_fidelity or engineering_standards"
@@ -197,6 +203,8 @@ def validate_summary(data):
     for field in ["session", "change_id", "head", "context_digest"]:
         if not nonempty_string(data.get(field)):
             return f"{field} must be a non-empty string"
+    if not digest_string(data.get("packet_digest")):
+        return "packet_digest must be a lowercase SHA-256 digest"
     if data.get("worktree_digest") is not None and not nonempty_string(data.get("worktree_digest")):
         return "worktree_digest must be null or a non-empty string"
     task_ids = data.get("task_ids")

package/skills/ultra-status/SKILL.md

@@ -1,63 +1,40 @@
 ---
 name: ultra-status
-description: Read authoritative Ultra health, workflows, decisions, changes, tasks, evidence freshness, and valid transitions. Use when the user asks what is complete, blocked, stale, or currently possible.
+description: Read authoritative Ultra health, workflows, decisions, changes, tasks, evidence freshness, and team checkpoint state. Use when the user asks what is complete, blocked, stale, or currently possible.
 ---
 
 # Report authoritative state
 
-This Skill is read-only. Never fall back to the Git team checkpoint, generated task
-JSON, prose, or context frontmatter when checkout-local DB authority is missing or
-degraded.
+This Skill is read-only.
 
 ## Read
 
-1. Run `system.doctor` without repair.
-2. Run `task.ledger_get`. Report `current`, `drifted`, `revalidation_required`,
-   `missing`, or a typed invalid/conflict state; do not import or publish from status.
-3. Read baseline classification, revision, worktree, research provenance, gaps, and
-   health.
-4. Read current decision state and breadcrumb `accepted_intent` without exposing hidden
-   future questions.
-5. Read active, blocked, and ready workflows and their current steps.
-6. Read the active Change root, typed delta, plan, deterministic progress projection,
-   documentation reconciliation, findings, tasks, sessions, and current Git state.
-7. Read test, review, and delivery artifacts only through DB references and verify
-   their digests and revisions.
-
-If authority is unreadable, report the unavailable panel and the required doctor or
-init transition. Do not mutate, compile context, repair, or release.
-
-## Interpret transitions
-
-MCP reports:
-
-- `allowed_transitions`: mechanically valid capabilities;
-- `required_transition`: the sole recovery route only when a hard invariant permits no
-  safe alternative.
-
-The host model recommends among allowed transitions using the user's current goal,
-workflow evidence, and cost of interruption. Do not present the recommendation as DB
-authority. A healthy project may validly allow research, change, thinking, or status at
-the same time.
+Call `ultra.context { stage: project, detail: full }`. Use `ultra.sync { action:
+inspect }` only when the user needs team-checkpoint detail. Do not import, publish,
+repair, compile context, or mutate state.
+Never fall back to the Git team checkpoint, generated task JSON, or report files as
+live authority when `ultra.context` reports missing or unhealthy local state.
 
 Report:
 
 ```text
-Ultra: <healthy|degraded> · <branch>@<head|unborn|non-git> · worktree <state>
-Baseline: <mode>/<status> · research=<run/status> · gaps=<open>/<blocking>
-Workflow: <kind/id/status> · step=<current|complete> · outputs=<fresh|stale>
-Decision: <current|checkpoint|none>
-Change: <id/status|none> · delta=<fresh|stale|missing> · docs=<fresh|stale|missing>
+Ultra: <healthy|degraded> · <branch>@<head|unborn|non-git>
+Baseline: <mode>/<status> · gaps=<open>/<blocking>
+Stage checkpoints: drafts=<count> · accepted=<current|stale|none>
+Change: <id/status|none> · delta/docs=<state>
 Task: <id/status|none> · Sessions: <active>
 Evidence: plan=<state> · test=<state> · review=<axes> · delivery=<state>
-Team checkpoint: <current|drifted|revalidation_required|missing|invalid> · generation=<n>
-Blockers: <codes or none>
-Warnings: <codes or none>
-Allowed transitions: <capabilities>
-Required transition: <capability or none>
-Host recommendation: <capability and concise rationale>
+Team checkpoint: <current|drifted|revalidation_required|missing|invalid>
+Blockers: <hard mechanical blockers or none>
+Warnings: <advisory semantic diagnostics or none>
+Model recommendation: <capability and concise rationale>
 ```
 
-Separate verified facts, host inference, and unavailable evidence.
+Treat warnings and failed draft checks as information, not mechanical orders. Only
+corruption, unsafe paths, real concurrency conflicts, permissions, or irreversible
+external effects are hard blockers.
 
-Never invoke the recommended capability here; wait for an explicit user invocation.
+The host model recommends the next useful capability from accepted intent, current
+evidence, cost of interruption, and owner goal. SQLite does not choose the route.
+Separate verified facts, model inference, and unavailable evidence. Never invoke the
+recommendation automatically.

package/skills/ultra-test/SKILL.md

@@ -1,74 +1,40 @@
 ---
 name: ultra-test
-description: Independently verify an Ultra task set or change with an evidence-backed, risk-selected test profile. Use when implementation or current acceptance and recovery evidence needs independent verification.
+description: Independently verify an Ultra task set or Change with an evidence-backed, risk-selected test profile. Use when implementation or current acceptance and recovery evidence needs independent verification.
 ---
 
 # Verify current behavior
 
-Testing is independent checking. Do not reuse implementation conclusions or generated
-projections as proof.
+Testing independently checks the current checkout. Implementation conclusions and
+generated projections are not evidence.
 
-## Bind scope
+## Bind and execute
 
-1. Read doctor, `task.ledger_get`, change, breadcrumb `accepted_intent`, decisions,
-   task and dev evidence, current checkout, and prior report freshness. Import a newer
-   descendant checkpoint before binding the task set; stop on a typed merge conflict.
-2. Resume or start a test workflow bound to the exact change and optional task.
-3. Record `bind-scope`, then compile `change.context` for `check` and record its
-   immutable manifest under `compile-context`.
-4. Record `map-acceptance` after mapping every accepted claim to an executable check
-   or bounded observable seam.
+1. Call `ultra.context { stage: test, scope: { change_id, task_id? }, detail: full }`.
+2. Import a newer team checkpoint with `ultra.sync`; stop on a real conflict.
+3. Bind exact acceptance, task set, HEAD, worktree, decisions, dev evidence, and public
+   seams.
+4. Select a risk-based profile from acceptance, regression, integration, static
+   analysis, build, performance, security, and recovery. Acceptance is mandatory;
+   explain every material exclusion.
+5. Run repository-native commands and real boundaries. A bug or incident needs one
+   deterministic red-to-green regression signal.
 
-## Select verification by risk
+When delegated, use the immutable Worker Packet supplied by the parent and echo its
+`packet_digest` in the report. Write an `ultra-test-report-v1` report below the owning
+Change. Bind exact acceptance
+ids, task ids, HEAD, worktree/context digests, commands, seams, failures, recovery,
+profile, timestamp, blockers, and evidence-derived verdict. Register it with
+`ultra.record` using `artifact / bind`.
 
-The model selects from:
+## Checkpoint
 
-- acceptance;
-- regression;
-- integration;
-- static analysis;
-- build;
-- performance;
-- security;
-- recovery.
+Call `ultra.checkpoint` once with `stage: test`, exact scope, evidence, and an output
+for the report (`kind: test-report`). The checkpoint compiles or reuses checking
+context and derives the verdict from the registered report.
 
-Acceptance is always selected. Select other dimensions when the change, repository, or
-failure mode makes them material. Record excluded dimensions and concrete rationales in
-`verification_profile`; omission without a rationale is invalid. A selected dimension
-must be `pass`, `fail`, or `not_run`; `not_run` cannot support a passing gate.
+If rejected, keep the same draft, repair evidence, and retry. Never weaken an
+assertion, hide a skip, or turn a warning into proof.
 
-Run repository-native commands and real boundaries where practical. Test doubles are
-acceptable only at costly or nondeterministic external boundaries when the report
-explains the preserved contract. Do not weaken assertions, hide skips, or validate
-unconsumed code.
-
-For an incident or bugfix, record one deterministic red-to-green `regression_signal`.
-When evidence reveals a material product or recovery choice, use the host's native
-question UI and decision protocol; testing must not choose the desired outcome.
-
-## Report
-
-Write
-`.ultra/changes/active/<change-id>/test/<workflow-id>/report.json` with
-`ultra-test-report-v1`, binding:
-
-- change, exact task ids, current Change acceptance ids, HEAD, worktree digest, and
-  checking-context digest;
-- acceptance mapping, commands, public seams, failures, and recovery evidence;
-- `verification_profile` and the selected `verification_dimensions`;
-- regression signal when required;
-- run count, timestamp, blockers, and evidence-derived `passed`.
-
-Record `execute-checks`, `verify-public-seam`, and `write-report`, then re-read the
-report and current checkout before `verify-test-gate`. `workflow.complete` derives its
-summary from the report and rejects stale, malformed, contradictory, out-of-Change,
-or acceptance-incomplete evidence.
-
-Return the profile, exact results, verified seams, blockers, report digest, workflow
-state, and allowed transitions. Recommend broader review, more implementation, or
-delivery from those transitions. If current intent does not already select the
-semantic next action, use
-`../ultra-think/references/decision-dialogue.md` and wait for the user to select,
-modify, delegate, or defer it.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+Return the profile, exact results, verified seams, blockers, report digest, and the
+model's recommended next explicit capability. Do not invoke it automatically.

package/skills/ultra-think/SKILL.md

@@ -3,55 +3,36 @@ name: ultra-think
 description: Resolve a consequential product, architecture, or recovery question through evidence-first reasoning and adaptive user alignment. Use when a material decision cannot be derived safely from accepted intent and current evidence.
 ---
 
-# Align without suppressing model judgment
+# Align without suppressing judgment
 
-Thinking is an optional reasoning capability, not a mandatory stage. Answer
-self-contained questions directly. Use durable decision state only when a
-project-bound choice must survive interruption or gate later work.
+Thinking is optional. Answer self-contained questions directly. Persist only a
+project-bound decision that must survive interruption or control later work.
 
-## Reason first
+## Reason and interact
 
-1. Define the actual decision or disputed claim and the constraints that can change
-   its answer.
-2. Inspect current authority, source, runtime, tests, and primary documentation before
-   asking the user for facts.
-3. Separate verified fact, evidence-backed inference, accepted intent, delegated
+1. Call `ultra.context` for the relevant project or Change scope.
+2. Define the real decision and the constraints that can change its answer.
+3. Inspect source, runtime, tests, accepted artifacts, and primary documentation
+   before asking the owner for facts.
+4. Separate verified fact, evidence-backed inference, accepted intent, delegated
    implementation judgment, and unresolved owner choice.
-4. Form credible alternatives only when alternatives materially help the decision.
-   Evaluate them against the real constraints; do not impose a fixed option count,
-   scoring system, or confidence percentage.
-5. Stress-test the leading answer with its strongest counterexample, likely failure
-   path, recovery, and load-bearing assumption.
-
-## Interact adaptively
-
-Read `references/decision-dialogue.md`. If the user already gave a clear decision,
-normalize and use it without asking for confirmation. If the decision is reversible
-and delegated by the accepted contract, decide it and explain the reasoning.
-
-When owner authority is required, use the host's native question UI when available.
-Ask the earliest dependent decision with a recommendation, decisive evidence, and the
-effect of the answer. Keep cognitive load small; group only independent, simple facts.
-Do not expose the hidden decision queue.
-
-For durable project decisions, use `decision.thread_start`, `decision.open`, and the
-appropriate resolve, delegate, defer, or supersede transition. Store normalized
-decisions and artifact references, never transcripts or internal reasoning.
-Apply any resulting change through its owning baseline, change, workflow, task, or
-semantic artifact operation, read it back, and pass typed `applied_refs` to
-`decision.complete`. If the decision record itself is the complete durable authority,
-the list may be empty. Completion is not another owner approval.
-
-Prepare and confirm a checkpoint only when the decision changes a durable contract or
-artifact and a checkpoint is needed for recovery. Do not add a ceremonial approval
-gate to an already explicit user instruction or a reversible implementation detail.
-
-## Return control
-
-Return the conclusion, decisive evidence, material uncertainty, and affected
-contracts. Re-read the invoking workflow or breadcrumb and recommend one of its
-`allowed_transitions`; follow `required_transition` only when a hard invariant leaves
-no alternative. Thinking does not implement code, mutate unrelated state, or invent a
-canonical next action.
-
-Never invoke the recommended capability here; wait for an explicit user invocation.
+5. Stress-test the leading answer with its strongest failure path and recovery.
+
+Read `references/interaction-boundary.md`. Reuse a clear decision already present in the
+request. Decide reversible delegated implementation details yourself. When owner
+authority is necessary, ask one dependent decision through the host-native question
+surface with a recommendation, decisive evidence, and the effect of the answer.
+
+## Persist only the normalized result
+
+Use one `ultra.record` batch with `decision / accept` and, when required,
+`artifact / bind` for the owning semantic document. A revised answer carries
+`supersedes_id`; accepted records remain immutable history. Store normalized decisions
+and artifact references, never transcripts or internal reasoning.
+
+A semantic rejection remains a mutable diagnostic. Correct the record; do not invent a
+new decision merely to satisfy a state machine.
+
+Return the conclusion, decisive evidence, uncertainty, affected authority, and the
+model's recommended next explicit capability. Thinking never performs unrelated
+implementation or an external effect. Do not invoke the next capability automatically.

package/skills/ultra-think/references/interaction-boundary.md

@@ -0,0 +1,56 @@
+# Owner interaction boundary
+
+Use this reference only when a material choice remains after inspecting current
+authority and observable facts. Ultra does not require a ceremonial question before
+every write.
+
+## Responsibility split
+
+- The owner controls product intent, acceptance, non-goals, material tradeoffs, risk
+  acceptance, irreversible actions, external effects, and real-money commitments.
+- The host model investigates facts, recommends a direction, makes reversible
+  implementation judgments, and explains uncertainty.
+- Use the host-native question surface declared by the installed interaction contract;
+  prefer its structured form when the host exposes one.
+- `ultra.record` persists only the normalized result and its provenance.
+- MCP validates structure, identity, digests, CAS, leases, paths, and recovery. It does
+  not decide whether a product answer is good.
+
+## Interaction sequence
+
+1. Read `ultra.context` for the relevant scope.
+2. Inspect source, runtime, tests, accepted artifacts, and primary documentation.
+3. Reuse an explicit choice already present in the current request or an accepted
+   Decision Record.
+4. Decide a reversible delegated detail without asking.
+5. When owner authority is still required, ask one unresolved owner choice at a time
+   with:
+   - the recommendation;
+   - the discriminating evidence;
+   - the meaningful cost or failure mode;
+   - what changes when the answer changes.
+6. Normalize the answer into a deterministic Decision Record and persist it with
+   `ultra.record` using `kind: decision`, `action: accept`.
+7. Read `ultra.context` back and verify that the accepted decision is visible before
+   relying on it.
+
+## Decision Record
+
+Persist only:
+
+- normalized question;
+- recommendation and selected answer;
+- effects and non-goals;
+- owner, source, and bounded provenance;
+- applied artifact references;
+- supersession link when revising an earlier answer.
+
+Never persist raw transcripts, hidden reasoning, full prompts, UI receipts, or copied
+memory-provider payloads.
+
+## Revisions and interruptions
+
+Accepted decisions are immutable history. A changed answer creates a new Decision
+Record that supersedes the prior record. A cancelled question writes nothing. If a
+decision cannot be obtained, preserve the unresolved issue as a diagnostic or bounded
+event; do not invent an answer or block unrelated work.