ultra-builder-pro-cli 0.26.1 → 3.0.2

package/skills/ultra-delegate/SKILL.md

@@ -8,9 +8,24 @@ description: Delegate one bounded workflow segment to another installed CLI in a
 Delegation is an execution mode, not another workflow stage. The primary host keeps
 semantic synthesis and remains the only writer of `.ultra/tasks.json`.
 
+Delegation is also not a primary transfer. A delegated worker never becomes the
+work package's canonical writer, whatever its result says; moving that role to
+another Agent requires the owner-directed OFFER → ACK → RESULT protocol in
+`../ultra-change/references/primary-transfer.md`, which stays mutually exclusive
+with this bounded-worker path.
+
 ## Before you start
 
-1. Read `.ultra/tasks.json`, the delegated task's `context_file` and `## Resume Note`.
+1. Resolve exactly one active `change_id`, then select one scope and name it in
+   `instruction.md`:
+   - **task execution or continuation** — select one matching task and read its full
+     `context_file` and `## Resume Note`;
+   - **scoped Research evidence** — read the active intent's Research Disposition,
+     named question, sources, and required exit evidence;
+   - **aggregate Change review or verification** — read the exact matching task ids,
+     relevant contexts, current report or review summary, and Change diff.
+   Research and aggregate read-only scopes do not require a task. An archived or
+   abandoned task cannot be delegated as current work.
 2. Read `CONTEXT.md`, relevant `.ultra/decisions/`, acceptance and current evidence.
 3. Define one bounded instruction, permission set, clean Git worktree and result.
 4. Read `references/delegation-contract.md` before writing either JSON artifact.
@@ -24,13 +39,15 @@ semantic synthesis and remains the only writer of `.ultra/tasks.json`.
 - No `writable_roots` entry is `.ultra/` or sits under it, and the actual diff touches
   nothing there.
 - Timeout and cancellation reach a terminal failed result and release `run.lock`.
-- The primary host verifies the result against the delegated workflow's acceptance.
+- The primary host verifies the result against the selected scope's task acceptance,
+  Research exit evidence, or aggregate review/verification question.
 
 ## Prepare and run
 
 Write under `.ultra/.runtime/delegations/<id>/`:
 
-- `instruction.md`: bounded goal, sources, acceptance and forbidden effects;
+- `instruction.md`: scope type, stable `change_id`, optional task id, bounded goal,
+  sources, acceptance or exit evidence, and forbidden effects;
 - `permission.json`: the exact file-local boundary in the contract reference;
 - `result.json`: launcher-published terminal artifact only.
 
@@ -43,7 +60,7 @@ worktrees collide in the very files every later session reads to resume. Worker
 and state changes travel back in `result.json` and are applied by the primary host.
 `external_effects` must be empty in this portable launcher: commit, push, publish,
 deployment and other effects stay with the primary host. There is no `readable_roots`
-claim because the five host sandboxes do not share one mechanically enforceable read
+claim because the six host sandboxes do not share one mechanically enforceable read
 policy.
 
 Create `.ultra/.runtime/worktrees/<id>` as a real Git worktree and run:
@@ -52,6 +69,20 @@ Create `.ultra/.runtime/worktrees/<id>` as a real Git worktree and run:
 ubp delegate run --to <host> --instruction <file> --permission <file> --worktree <dir> --timeout <seconds>
 ```
 
+`<host>` is `claude`, `codex`, `opencode`, `kimi`, `grok`, or `zcode`. Kimi accepts an
+optional `--model <id>` when its account has no default headless model. A ZCode primary
+host uses this same command to delegate to any other installed CLI; a different primary
+host can select `--to zcode` through the ZCode headless profile.
+
+The ZCode headless transport is `experimental`: it is an App-internal or PATH CLI with
+no public stability contract, and it is **not** the documented ZCode Desktop
+interactive surface. `delegate run --to zcode` refuses to launch until the invocation
+explicitly carries `--ack-experimental`; every launch then prints a stderr warning and
+records `transport_maturity: "experimental"`, the exact `transport_surface` wording,
+and `experimental_ack: true` in the receipt, the worker spec, and the terminal result
+(including failure and timeout recovery results), so no receipt can imply a documented
+Desktop session. Promotion requires official documentation plus a full recovery drill.
+
 The command returns a receipt. Immediately run `scripts/delegate_wait.py`; read no
 intermediate output. Use `ubp delegate status --delegation <dir>` for a read-only state
 and `ubp delegate cancel --delegation <dir>` to request termination. Never delete a lock
@@ -60,7 +91,9 @@ to manufacture completion.
 The worker returns one schema-constrained JSON final response. The launcher extracts it
 from the host's native structured output, validates digests, process exit, exact schema,
 actual base-HEAD diff and writable roots, then atomically publishes `result.json`. The
-model never writes its own receipt. If owner input is needed, the worker terminates
+launcher embeds the exact digest-bound instruction and permission packet in the prompt,
+so a host that denies external-directory reads never needs authority outside the
+worktree. The model never writes its own receipt. If owner input is needed, the worker terminates
 `blocked` with questions and evidence; start a new id and fresh packet after obtaining
 the answer.
 

package/skills/ultra-delegate/references/delegation-contract.md

@@ -23,6 +23,13 @@ reads to resume. Enforced twice: the launcher rejects a `.ultra` root before the
 delegation starts, and the worker fails an actual diff that touches it with
 `unauthorized_write`.
 
+This boundary also separates delegation from a primary transfer: a delegation result
+is a bounded observation returned to the primary host, and no delegation receipt can
+serve as, upgrade into, or substitute for the OFFER/ACK/RESULT receipts of a primary
+transfer (`../ultra-change/references/primary-transfer.md`). Widening a worker to write
+`.ultra` in order to simulate a transfer is a contract violation, not an integration
+shortcut.
+
 ## Model final response
 
 ```json
@@ -43,12 +50,25 @@ delegation starts, and the worker fails an actual diff that touches it with
 Fields are exact. Status is `finished`, `blocked`, or `failed`; `blocked` requires a
 question. Check status is `passed`, `failed`, or `not_run`. Changed files are unique,
 normalized repository-relative paths and must exactly equal the launcher's Git diff.
+`output_ref` is requested for every check and required in the native schema projection
+used by hosts that accept one. The launcher remains compatible with hosts that return
+the otherwise exact check without that optional evidence pointer.
 
-The launcher extracts this object from native structured output and adds
+The launcher embeds the exact instruction and permission sources with their digests in
+the host prompt, extracts this object from native structured output, and adds
 `delegation_id`, `host`, instruction, permission, and output-schema digests,
 `read_only`, `base_head`, `final_head`, timestamps, `exit_code`, and signal. Launcher
 failures also add `failure_type`. A nonzero process cannot publish `finished`.
 
+Every receipt, worker spec, and terminal result also records the transport truth:
+`transport_maturity` (from the shared host profile) and the exact `transport_surface`
+wording. The ZCode headless transport is `experimental` with no public stability
+contract and is not the documented ZCode Desktop interactive surface; launching it
+requires the explicit `--ack-experimental` flag, prints a stderr warning, and stamps
+`experimental_ack: true` on the receipt, so no delegation record can misrepresent an
+internal CLI run as a documented Desktop session — including failure, cancellation,
+and timeout recovery results.
+
 ## Recovery
 
 - `status` distinguishes running, cancelling, stalled, and terminal artifacts.

package/skills/ultra-deliver/SKILL.md

@@ -1,58 +1,137 @@
 ---
 name: ultra-deliver
-description: Reconcile one completed Change, run aggregate review and refactoring, refresh release documentation, and archive the local workflow record. Use when the task ledger is complete and the owner wants a delivery handoff or separately authorized release effects.
+description: Reconcile one Change whose matching tasks are complete, run aggregate review and refactoring, and report the delivery handoff. Use when the owner wants delivery reconciliation and reporting, or — by current explicit owner invocation only — the separately gated finalization that writes delivery.md, fixes version and package posture, and archives the local workflow record.
 ---
 
 # Turn current evidence into a recoverable delivery handoff
 
-Delivery closes the local Change. Commit, push, tag, publication and deployment remain
-separate effects; local readiness grants none of them automatically.
+Delivery closes the local Change; readiness grants no commit, push, tag, publish, or deploy authority.
 
 ## Before you start
 
-1. Read `.ultra/tasks.json` and each completed task's `context_file`, Completion and
-   closing `## Resume Note`.
-2. Read `CONTEXT.md`, relevant `.ultra/decisions/`, active Change intent and evidence.
-3. Read `.ultra/test-report.json` and current `HEAD`. If `git_commit` differs from HEAD,
-   label the report stale and obtain current evidence before a release recommendation.
+1. If model-selected, verify the live execution grant in `../ultra-change/references/execution-grant.md` — a current session-local activation or a stably verified durable work-package grant; without either, stop. A model-selected Deliver run under that grant may reconcile, review, and report, and then MUST stop before finalization: its inputs, writes, and effects end at the report. Only a current explicit owner invocation of `ultra-deliver` may finalize — writing `delivery.md`, deciding the version decision and package posture, and archiving the stable Change id with `git mv` are owner-invocation-only in every grant mode, and a grant never covers them.
+2. Read `../ultra-change/references/change-contract.md` and apply its **Active Change
+   authority resolution** before reading any active `intent.md` or resolving a current
+   `change_id`. This workflow requires its one valid active authority; any zero result
+   or typed diagnostic stops before finalization input is read until the stated repair
+   or retry succeeds. Read `.ultra/tasks.json`; every matching task must be `completed`
+   in that sole task-status authority. Read each `context_file`'s Completion, Task
+   Review, and closing Resume Note. For every current Change task,
+   require current `ultra-task-evidence-v2` and task-review provenance under
+   `../ultra-plan/references/task-evidence-v2.md`, already consumed by the current Test
+   report. A legacy context Status or Complexity header and v1 evidence are migration
+   diagnostics only and cannot support current delivery.
+3. Read `CONTEXT.md`, relevant `.ultra/decisions/`, active Change intent and evidence.
+   Validate `.ultra/north-star.md`; resolve every recorded `FP-*`, `NS-*`, and `HC-*`
+   for the delivered Change, tasks, findings, and dispositions against that accepted
+   authority. Compare the active Change's recorded **North Star revision** and
+   **North Star digest** with the accepted file's revision and current Git blob digest. Any
+   missing ID or mismatch stops finalization and recommends explicit owner invocation of
+   `ultra-change` for reconciliation; delivery never silently rewrites the trace.
+4. Read `.ultra/test-report.json`, then run the Test Skill's `worktree_digest.cjs` with
+   project root and `--change-id`. Require report `task_ids` for the current Change plus
+   matching `change_id`, `git_commit`, worktree digest, intent digest, and review
+   `admission_digest`, `subject_digest`, and `summary_digest`; otherwise stop. Recheck
+   each projected task's declared review branch as recorded: strict-v4 items keep their
+   strict receipt and transport bindings, while `external-manual` items reverify their
+   receipt bytes and digest through the task-evidence sensor's
+   `--verify-external-receipt` mode and take the sensor's `--projection` output
+   verbatim — a strict SUMMARY never substitutes for an external receipt and neither
+   branch is rewritten into the other.
+   The product-worktree digest has one fixed boundary: it excludes `.ultra/evidence/**`,
+   whose command and external-observation entries bind raw bytes as
+   `raw_evidence_sha256` before stable exact record bytes are bound as `evidence_digest`
+   through the report's ordered `task_evidence` projection. For each projected record,
+   take every `raw_evidence_ref` to bounded stable repository-contained bytes from an
+   ordinary regular non-symlink file opened nonblocking and no-follow, with an 8 MiB
+   ceiling and path/descriptor identity checks around the read. Recompute
+   `raw_evidence_sha256` and require an exact match, then recompute the stable exact
+   `evidence.json` bytes as `evidence_digest` before comparing the projection. Recheck
+   the exact review receipts separately; never treat the product exclusion as permission
+   to ignore evidence drift or add another exclusion.
+   An intent digest changed by North Star reconciliation or any other intent edit always
+   requires a fresh `ultra-test` before Deliver can finalize, even if product bytes did
+   not change.
+5. Preserve every typed acceptance authority. The owner alone supplies the semantic
+   result for `owner-judgment`; Deliver may verify its cited source and freshness but no
+   model, command, digest, schema, or validator may replace it.
 
 ## Definition of done
 
-- Actual outcome, specifications, docs, tests and aggregate review have been reconciled,
-  with every documentation file checked against the actual diff rather than from memory.
+- Outcome, specs, tests, aggregate review, and every document match the actual diff.
 - Every changed export has a non-test consumer or a recorded owner disposition.
 - Every omitted stage is explicitly recorded with its evidence-based rationale.
+- Delivery explains whether evidence realizes the traced first principles and outcome,
+  and preserves contradictions or stale trace as findings instead of mirroring or
+  silently revising North Star prose.
 - Build and release checks have exact commands and real results.
 - The Change is archived with `git mv`, and rollback remains a normal Git operation.
 
 ## Review and refactor
 
-Follow `../ultra-review/SKILL.md` across the aggregate Change. This is where useful
-refactoring occurs: several completed slices now reveal real duplication, coupling and
-deep-module boundaries. Rerun every check affected by a refactor and refresh the report
-against the resulting HEAD.
+Follow `../ultra-review/SKILL.md` across the aggregate Change; refactor only observed
+duplication, coupling, or boundary defects. Rerun affected checks and refresh the report.
+After the aggregate review and the current Test report are consumed, Deliver does not
+refactor product source: it reconciles delivery artifacts and documentation only. A
+post-approval implementation issue routes as at most one new owner-approved Dev task
+for a P0/P1, or as recorded backlog and residual risk for P2/P3; an unbounded
+Test ↔ Deliver bounce is not a valid recovery path, and any re-entry through Test
+requires an explicit owner disposition.
 
 ## Reconcile the handoff
 
 1. Compare accepted intent and task traces with delivered behavior.
 2. Apply justified specification corrections; route any REDUCTION to the owner.
-3. Reconcile every document against the actual diff, not only the ones you remember
-   touching. List the repository's documentation files, read the Change's full diff, and
-   repair each place a document now describes behavior that no longer exists. CHANGELOG
-   and README are the usual ones, but a stale example in a guide, a renamed flag in a
-   runbook and an obsolete field in an API note drift the same way and are found the
-   same way. Record bounded debt only in the active Change `delivery.md` under
-   `## Technical Debt`.
-4. Run the repository's build and packaging checks.
-5. Determine the version impact from the public contract and project convention.
-6. Follow `references/baseline-reconciliation.md` and write the one canonical active
-   Change `delivery.md` with exact checks, residual risks, omissions and rollback.
-
-Step 3 is the **exit** reconciliation and does not duplicate `ultra-change`'s entry
-reconciliation. Entry asks whether the specifications already disagreed with the code
-before this Change was written; exit asks which documents this Change just made wrong.
-One keeps the intent from inheriting drift, the other keeps the Change from leaving new
-drift behind.
+3. List documentation, compare every file with the full Change diff, and repair stale
+   behavior, examples, flags, or fields. Record bounded debt only in active
+   `delivery.md` under `## Technical Debt`.
+4. Defer build, non-publishing package inspection, version selection, and the canonical
+   `delivery.md` until the fresh-snapshot finalization pass below. Reconciliation that
+   changed files must return through Test first.
+
+Entry reconciliation prevents inherited drift; this exit reconciliation prevents the
+Change from leaving new document drift.
+
+## Reconcile, then finalize on a fresh snapshot
+
+Delivery has two observable passes, not a hidden state machine:
+
+1. Reconcile and review. If this pass changes source, tests, task/context/evidence,
+   specifications, maintained documentation, or `intent.md`, stop after writing the
+   reconciled files. The existing report is stale; recommend `ultra-test` and make no
+   delivery or release claim.
+2. After an unchanged pass or fresh Test, resolve the report's canonical
+   `review.summary_ref` as `<validated-summary-path>` and run the current strict transport
+   consumer against the current report:
+
+   `node <ultra-test-skill-dir>/scripts/validate_review_transport.cjs --summary <validated-summary-path> --report .ultra/test-report.json`
+
+   Require exit 0 and a JSON `"valid": true` field. This one existing consumer verifies
+   the exact
+   retained `ADMISSION.json` and `SUMMARY.json`, then binds the report's
+   `admission_digest`, `subject_digest`, and `summary_digest` to those bytes. A missing or
+   invalid receipt, summary, or binding makes the current Test claim `INCOMPLETE`: start
+   a fresh Review and Test. Do not write `delivery.md`, archive the Change, create a
+   release package, or make a delivery claim while that receipt evidence is missing or
+   invalid. Never use `--legacy-v4` for this current-session check; v3 and pre-admission
+   v4 are read-only historical evidence, not current Test or Deliver evidence.
+
+   After the transport succeeds, recheck Change/task/HEAD/product/intent identities.
+   Apply the gate, run build and non-publishing package inspection, determine version
+   impact, and use `references/baseline-reconciliation.md` for canonical `delivery.md`.
+   Archive the Change. Excluded delivery metadata and the directory move cannot
+   self-invalidate the product digest; intent stays independently bound. Retain the
+   review session through this successful Deliver consumption; only then may its derived
+   artifacts be garbage-collected.
+
+   Transport and task-evidence validators establish exact structural, identity,
+   provenance, and freshness facts only. Their success never means that the Change is
+   semantically accepted or that its outcome is ready to describe as delivered.
+
+Do not draft a success narrative around stale evidence. A current `passed: false`
+report may still reach finalization only after every finding has an explicit owner
+disposition and the one hard gate below is clear; `passed` is evidence summary, not a
+second mechanical release gate.
 
 ## The one delivery gate
 
@@ -62,27 +141,24 @@ attach itself to ordinary repository packaging outside this workflow.
 Everything else in this workflow reports and hands over. This is the exception, and it
 is deliberately narrow:
 
-**Do not package while an export this Change added or changed has no non-test consumer
-and no recorded owner disposition.**
+**Do not produce a release package while an export this Change added or changed has no
+non-test consumer and no recorded owner disposition.**
 
 | | |
 |---|---|
 | Invariant | Every changed export is either reachable from a non-test caller or explicitly declared internal |
-| Fact source | The Wiring Verification results in `.ultra/test-report.json`, bound to the current HEAD — the audit already found these; this is not a fresh opinion |
-| Blocked effect | Packaging and the release effects after it. Local commit and archival are untouched |
-| Repair | Wire the export to its caller, or record the owner's disposition in `delivery.md` naming it internal-only and why. Either one clears the gate |
+| Fact source | The Wiring Verification finding and its owner disposition in `.ultra/test-report.json`, bound to the current Change id, task ids, intent, HEAD, and product-worktree digest — the audit already found these; this is not a fresh opinion |
+| Blocked effect | Release-package creation and the separately authorized release effects after it. A non-publishing package inspection is diagnostic; local commit and archival are untouched |
+| Repair | Wire the export to its caller, or record the owner's disposition on the finding in `.ultra/test-report.json`, then carry it into `delivery.md`. Either one clears the gate |
 
-"Written but never connected" is the single defect that passes every other check: tests
-green, review clean, evidence complete, feature absent. An advisory here would be
-ignored exactly when it matters, because everything else already reads as done. The gate
-sits at the last step rather than at edit time on purpose — a gate early in the loop
-gets escaped by damaging the work.
+"Written but never connected" can leave tests and review green while the feature is
+absent. Keep this gate at finalization, after the audit can distinguish unfinished work.
 
 ## Archive locally
 
-Move `.ultra/changes/active/<id>` to `.ultra/changes/archive/<id>` with `git mv` only
-after local reconciliation. Do not create a second standalone delivery report: archived
-`delivery.md`, test report, evidence and Git history are the handoff.
+After the fresh check, `git mv` active `<id>` to archive. The id stays stable in task
+rows; never store a movable intent path or create a second delivery summary. Archived
+delivery, test report, evidence, and Git history are the handoff.
 
 For separately authorized effects, perform and verify each independently. Ask for
 authority at the point of effect: commit, then push, then tag, package publication and
@@ -95,8 +171,11 @@ Without release authority, stop after the recoverable local archive and report i
 
 ## References
 
+- `../ultra-change/references/change-contract.md` — canonical Active Change authority resolution.
 - `../ultra-review/SKILL.md` — read before aggregate review and refactoring.
+- `../ultra-plan/references/task-evidence-v2.md` — canonical current task evidence and task-review contract.
 - `../ultra-think/SKILL.md` — read when version or release posture is a consequential
   trade-off rather than an established repository rule.
 - `../ultra-think/references/autonomy-boundary.md` — read before scope or evidence shrinks.
+- `../ultra-change/references/execution-grant.md` — read only for grant-activated continuation.
 - `references/baseline-reconciliation.md` — exact `delivery.md` reconciliation contract.

package/skills/ultra-deliver/references/baseline-reconciliation.md

@@ -34,6 +34,8 @@ the Change is active and moves with the directory when archived.
 
 Every semantic update cites a repository-relative `path#anchor`. A reduction requires
 the owner decision before the affected specification changes. Exact command evidence
-must match the checkout identified by `.ultra/test-report.json`; stale results stay
-visible and never become a pass. Do not create a second JSON or Markdown delivery
-summary.
+must match the stable Change id, exact current task ids, intent digest, HEAD, and
+product-worktree digest identified by `.ultra/test-report.json`; stale results stay
+visible and never become a pass. Reconcile before finalizing. If reconciliation changes
+semantic or product files, obtain a fresh Test snapshot before writing final delivery
+metadata or archiving. Do not create a second JSON or Markdown delivery summary.