ultra-builder-pro-cli 0.26.2 → 5.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.26.2",
-  "description": "File-first Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, and Grok Build.",
+  "version": "5.0.0",
+  "description": "File-first Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, Grok Build, and ZCode.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
     "ubp": "bin/install.js"
@@ -29,6 +29,7 @@
     "hooks/README.md",
     "LICENSE",
     "CHANGELOG.md",
+    "README.zh-CN.md",
     ".ultra-template",
     "docs/PHILOSOPHY.md",
     "docs/ARCHITECTURE.md",
@@ -38,6 +39,7 @@
     "docs/DECISIONS.md",
     "docs/PLUGIN-ISOLATION-CONTRACT.md",
     "docs/RUNTIME-COMPAT-MATRIX.md",
+    "docs/evals/*.md",
     "!**/*.pyc",
     "!**/*.pyo",
     "!**/*.test.cjs",
@@ -50,6 +52,7 @@
     "codex",
     "kimi-code",
     "grok-build",
+    "zcode",
     "agent",
     "cli",
     "multi-runtime",
@@ -81,9 +84,10 @@
     "install:claude": "node bin/install.js --claude --local",
     "install:kimi": "node bin/install.js --kimi --global",
     "install:grok": "node bin/install.js --grok --global",
+    "install:zcode": "node bin/install.js --zcode --global",
     "install:all": "node bin/install.js --all --global"
   },
   "dependencies": {
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.3.1"
   }
 }

package/skills/ultra-change/SKILL.md

@@ -8,14 +8,35 @@ description: Open or reconcile one bounded unit of work by comparing specificati
 A Change connects research, plan, implementation, verification, review, and delivery.
 Reconcile first so new intent does not bury an existing specification/code conflict.
 
+## Route modes
+
+| Mode | Entry | Observable exit | Next |
+|---|---|---|---|
+| `intake` | Explicit owner request with no active Change | One stable draft `change_id` captures outcome, acceptance, non-goals, seams, trace, and Research Disposition | Stay in `ultra-change` for acceptance or move to `evidence-needed` |
+| `evidence-needed` | The draft names one load-bearing question and required exit evidence | The bounded Research Disposition is owner-visible and records its return to this Change | Recommend `ultra-research/change-scoped` |
+| `reconcile` | Explicit invocation or a valid Execution Grant for the same active Change | Research or implementation evidence is dispositioned in the same intent and any material delta is accepted | Recommend or continue to `ultra-plan/decompose` when the intent is accepted |
+| `accepted` | Explicit owner acceptance of the Change outcome and boundary | Accepted intent, current trace, satisfied Research Disposition, and resolved material decisions are read back | Recommend `ultra-plan/decompose` |
+
+Follow `../ultra-status/references/route-contract.md`. A draft may be revised in place;
+an already accepted owner decision is revised by a superseding decision record so its
+history remains recoverable. Show a Route Card before each public transition. Under a
+valid grant only the non-material `reconcile` mode may continue implicitly.
+
 ## Before you start
 
-1. List `.ultra/changes/active/`; more than one `intent.md` is a conflict, not a choice.
-   One directory name is the stable `change_id`. Read `.ultra/tasks.json`, then only its
-   unfinished `context_file` values. Update the same `change_id`; never open a second active Change.
-2. Read `.ultra/project-brief.md`, `CONTEXT.md`, relevant `.ultra/decisions/`, and
+1. If model-selected, require `reconcile` mode for the same active Change and verify a
+   live grant under `references/execution-grant.md`. Any intake, evidence-needed boundary,
+   acceptance, abandonment, reduction, or primary transfer stops and recommends current
+   explicit owner invocation; a coarse Host invocation bit cannot authorize it.
+2. Read `references/change-contract.md` and apply its **Active Change authority
+   resolution** before reading any active `intent.md`, relying on a current `change_id`,
+   or creating or writing a Change. Continue only from its positively observed stable
+   zero-or-one result; return its typed repair for any other result. With one active
+   Change, read `.ultra/tasks.json`, then only its unfinished `context_file` values.
+   Update the same `change_id`; never open a second active Change.
+3. Read `.ultra/project-brief.md`, `CONTEXT.md`, relevant `.ultra/decisions/`, and
    `.ultra/north-star.md` for raw provenance, accepted language, and direction.
-3. Grep archive and abandoned Changes that touched this area. Prefer archived
+4. Grep archive and abandoned Changes that touched this area. Prefer archived
    `delivery.md`; otherwise read `archive-summary.md`, `verification.md`, `intent.md`,
    and remaining Markdown. Read abandoned Changes as history of rejected boundaries and
    reusable evidence, never current intent. A missing `delivery.md` does not mean no history;
@@ -37,7 +58,8 @@ Test/Deliver claim for that micro change.
 
 ## Definition of done
 
-- Active `intent.md` states outcome, executable acceptance, non-goals, public seams,
+- Active `intent.md` states outcome, typed acceptance with named required evidence,
+  non-goals, public seams,
   and Research Disposition.
 - Every reconciliation bucket is empty or dispositioned with the owner's answer.
 - The draft remains editable until owner acceptance makes it authority.
@@ -78,14 +100,27 @@ whole path is unclear, recommend Research instead of manufacturing tasks.
 Record `## Research Disposition` exactly. `none` needs enough evidence to plan;
 `bounded` or `required` names one question, selected lenses, and exit evidence. After
 Research, reconcile outputs here; an unverified path or bare claim is not evidence.
-
-A quick active Change still goes through one-task `ultra-plan`; once durable intent
-exists, that minimal task is what binds development, evidence, audit, and delivery to
-the stable `change_id`.
+Record one `## North Star Trace` with resolving `FP-<n>`/`NS-<n>`/`HC-<n>` ids, causal
+evidence, the accepted revision, the current Git blob digest, and any contradiction
+requiring owner disposition. Reference IDs only; do not mirror North Star prose.
+
+When Research accepts a revision whose id or digest differs from an active Change trace,
+that active Change has a stale observation, not a semantic failure. Preserve its intent,
+tasks, review, Test, and delivery evidence; reconcile old IDs to the accepted revision,
+surface contradictions for owner disposition, and invalidate any plan-bound execution
+approval through its own contract. Never silently rewrite the North Star or infer that a
+replacement grants execution.
+
+Every active Change still goes through `ultra-plan`; once durable intent exists, the
+smallest evidence-backed task graph for its real seams binds development, review,
+audit, and delivery to the stable `change_id`. The profile never fixes task or context
+count.
 
 Output active `intent.md` under a stable id, justified specification patches, qualifying
 decision or vocabulary updates. For an evidence gap recommend `ultra-research`; when
-evidenced recommend `ultra-plan`. Invoke neither.
+evidenced recommend `ultra-plan`. Invoke neither without a covering grant; with a valid
+grant covering same-Change reconciliation and Plan, show the transition Route Card and
+allow Plan to re-verify its own entry contract.
 
 ## Abandoning a Change
 
@@ -94,15 +129,37 @@ Append the exact `## Abandonment` closure from `references/change-contract.md`,
 evidence. Future Change and Status consume this history; it is neither current intent
 nor an orphan. Abandonment is the owner's call.
 
+## When the primary writer changes Agent
+
+When the owner moves the canonical implementation authority of an active
+work package to another Agent, follow `references/primary-transfer.md` exactly:
+the sender writes current reality into the task context and its Resume Note,
+derives the OFFER from canonical files and Git, and stops writing after the
+receiver's ready ACK; the receiver stable-reads, verifies every digest, and
+becomes the sole canonical writer. A delegated worker slice is never a
+substitute — `ultra-delegate` owns the mutually exclusive bounded-worker path.
+Validate receipts with
+`scripts/validate_primary_transfer.cjs`; the report is structural observation,
+never an acceptance.
+
 ## When the owner decides
 
 Every non-empty bucket, the Change boundary, abandonment, and anything
 reconciliation turns up that shrinks a prior commitment. A change that makes no
 specification sentence false needs no permission at all.
 
+If the owner rejects the presented options or says none is adequate, preserve that
+answer as current intake and keep the intent draft or move it to `evidence-needed`.
+Gather the missing discriminating evidence or present materially different options; do
+not select the nearest rejected option, manufacture acceptance, or route to Plan.
+
 ## References
 
 - `../ultra-grilling/SKILL.md` — the loop for settling the boundary.
-- `references/change-contract.md` — exact `intent.md` structure and profile fields.
+- `references/change-contract.md` — canonical Active Change authority resolution, exact
+  `intent.md` structure, and profile fields.
+- `references/execution-grant.md` — read when the owner requests bounded workflow continuation under a session-local or durable grant.
+- `references/primary-transfer.md` — read when the owner moves the work package's canonical writer to another Agent (OFFER → ACK → RESULT).
+- `../ultra-status/references/route-contract.md` — owner-visible route, checkpoint, and recovery output.
 - `../ultra-think/references/autonomy-boundary.md` — read before removing a promise.
 - `../ultra-tdd/SKILL.md` — read for an evidenced one-slice correction.

package/skills/ultra-change/references/change-contract.md

@@ -7,6 +7,36 @@ The directory id is globally unique across active, archive, and abandoned Change
 matches `[A-Za-z0-9][A-Za-z0-9._-]*`. It is the stable `change_id`; moving the directory
 never changes it.
 
+## Active Change authority resolution
+
+Every Skill that selects a current `change_id`, reads active intent, or creates a new
+Change must first use native host filesystem checks to apply this instruction contract.
+It is not a parser, registry, or persisted state.
+A positively observed absent `.ultra` is the existing uninitialized condition:
+`ultra-status` may recommend `ultra-init`, while writers write nothing. This known
+absence is distinct from an unavailable observation. Otherwise:
+
+1. Require `.ultra`, `.ultra/changes`, and `.ultra/changes/active` to be a stable chain
+   of ordinary non-symlink directories with the same no-follow identities before and
+   after selection.
+2. Stable-list every active-root entry without following symlinks. Only `.gitkeep`,
+   when it is an ordinary regular non-symlink file, may be ignored. A `.gitkeep` of any
+   other type is malformed, is never a Change directory, and returns a typed diagnostic
+   with repair before any candidate intent is read. Every other non-directory or symlink
+   entry returns a typed diagnostic with a reachable repair before any intent read.
+3. A positively observed stable empty root, with or without that sole marker, means no
+   active Change. Active authority exists only when exactly one ordinary non-symlink
+   Change directory remains. More than one returns a typed conflict and repair; select
+   none of them.
+4. Require the selected directory's own `intent.md` to be a stable regular non-symlink
+   file opened with no-follow behavior. Capture one bounded snapshot, then recheck the
+   directory chain, active-root entries, selected directory, and intent identity before
+   consuming its contents.
+5. On any unavailable observation or changed identity, stop with a typed diagnostic and
+   reachable retry or repair. Do not read any intent, route from it, write any workflow
+   artifact, or create a new Change. Only a positively observed stable zero-directory
+   result permits `ultra-change` to create one.
+
 ## Exact `intent.md` structure
 
 ```markdown
@@ -21,7 +51,7 @@ never changes it.
 <one externally observable result>
 
 ## Acceptance
-| ID | Criterion | Verification | Trace |
+| ID | Criterion | Verification type | Required evidence |
 |---|---|---|---|
 
 ## Non-goals
@@ -43,6 +73,28 @@ never changes it.
 - Required exit evidence: <what must exist or be resolved before planning>
 - Rationale: <why this is sufficient for this Change boundary>
 
+## North Star Trace
+- First principles: <FP-<n> ids and the causal premise>
+- Serves: <NS-<n> ids and the causal contribution>
+- Touches: <HC-<n> ids, or none>
+- Evidence: <repository-relative paths and claims>
+- North Star revision: <accepted Revision field from `.ultra/north-star.md`>
+- North Star digest: <output of `git hash-object .ultra/north-star.md`>
+- Contradictions or refinements: <none, or the owner disposition still required>
+
+## Execution Grant
+
+- Grant: `session-local` (default) | `durable work-package` <grant-id>
+- Allowed workflows: <subset of research, plan, dev, test, deliver-reconcile>
+- Agent topology: <single-Agent default, or the owner-selected providers, counts, and write scopes>
+- Allowed local effects: <exact authorized local writes, tests, and bounded verification>
+- Budgets and expiry: <time, cost, tool, provider, delegation, review-round ceilings and expiry>
+- Mandatory reviews: <plan, task, and aggregate Change requirements>
+- Stop conditions: <named semantic, evidence, recovery, and budget stops>
+- Invalidation: <conditions that end the grant and return control to the owner>
+- Never granted: <new Change, baseline checkpoint, finalization/archive, external effects, cross-family provider calls>
+- Activation: <session-local: a current-session owner utterance approving this grant and the current task ledger; durable: stable verification of the recorded grant — stored text alone is inactive>
+
 ## Planning Posture
 <EXPAND | SELECTIVE | HOLD | REDUCE, rationale, and owner confirmation>
 <!-- Scope for this Change only. Not the commitment classification: REDUCE here
@@ -63,10 +115,11 @@ heading, and do not add another file that restates the same contract.
 ## Contract fields
 
 - `outcome`: one externally observable result.
-- `acceptance`: stable ids, one criterion each, and a `Verification` that is an
-  **executable command** — something with an exit code, not a description of an
-  intention. `curl -sf localhost:3000/health` qualifies; "check that the endpoint
-  responds" does not.
+- `acceptance`: stable ids, one criterion each, one verification type, and exact
+  required evidence. The supported types are `command`, `inspection`,
+  `owner-judgment`, and `external-observation`. When one outcome needs more than one
+  authority, split it into independent criteria with unique IDs and keep one
+  verification type per criterion. A row must not carry multiple verification types.
 - `non_goals`: explicit boundaries that prevent accidental scope growth.
 - `public_seams`: entry points or outputs through which acceptance is observed.
 - `recovery`: a bounded reversal or recovery strategy and its verification.
@@ -75,37 +128,50 @@ heading, and do not add another file that restates the same contract.
 Resolve every blocking decision before planning. Keep non-blocking uncertainty visible
 in the task and verification contracts.
 
-## Why verification has to be executable
-
-A criterion whose verification cannot be run is not acceptance, it is a wish. Three
-consumers downstream depend on it being runnable:
-
-- task development can treat passing acceptance as an exit condition only when
-  something can actually decide "passing";
-- the review tests lens maps each acceptance claim to executable evidence, and can
-  only report an honest gap when there is something to map onto;
-- delivery cannot otherwise separate "shipped" from "believed shipped".
-
-Writing the command is also the cheapest way to find out that a criterion is vague.
-"The feature is wired up" resists a command until it becomes "this export has a
-non-test importer", which is a `grep`.
-
-Where a criterion is genuinely a judgement call — visual polish, wording, feel — it
-does not belong in Acceptance at all. Record it as a taste decision for the owner and
-keep Acceptance to what a machine can settle. Mixing the two is what makes an
-acceptance set undecidable.
+`North Star Trace` is the Change-level semantic trace. `First principles`, `Serves`, and
+`Touches` ids must resolve in `.ultra/north-star.md`; `Evidence` explains the causal
+claim rather than merely naming the file. Revision and digest are freshness observations.
+A mismatch returns the intent to reconciliation and never mechanically declares
+alignment or contradiction. Preserve historical evidence while reconciliation maps old
+IDs, records contradictions, and obtains any material owner disposition.
+
+Every Change records an `Execution Grant`; `session-local` is the default and a
+durable grant requires an exact owner record. The exact mode behavior,
+activation, and durable-verification rules live in `execution-grant.md`. The
+grant bounds native model continuation; it is not persisted route authority.
+
+## Why verification has to name its authority
+
+Acceptance is only auditable when the observation and its authority are explicit:
+
+- `command` records the exact command, working directory, exit status, and retained raw
+  output reference;
+- `inspection` cites the exact file, revision or digest, and the observed fact;
+- `owner-judgment` cites the durable owner disposition without replacing it with a
+  machine proxy; only the owner can supply its semantic result;
+- `external-observation` records the provider or environment, run identity, observation
+  time, and retained raw result.
+
+Development, Review, Test, and Deliver may verify that the required evidence exists,
+is fresh, and is bound to the criterion. They must not turn a command exit code, regex,
+digest, or schema result into a semantic verdict for an inspection, owner judgment, or
+external observation. Missing or stale evidence returns a typed gap to the responsible
+model or owner; it never silently deletes the criterion or manufactures acceptance.
+A validator owns exact structure, identity, and provenance only; validator success is
+never a semantic pass.
 
 ## Profile
 
-- `quick`: one low-risk task, no material risk flags, and no research dependency.
-- `standard`: a bounded change with multiple tasks or ordinary integration risk.
+- `quick`: a bounded low-risk change with no material risk flags and no research dependency.
+- `standard`: a bounded change with ordinary integration risk.
 - `major`: a broad or consequential change with material contract, migration,
   authorization, security, multi-module, external-integration, or release impact.
 - `incident`: urgent diagnosis and recovery with a reproducible symptom. Baseline
   break-glass still requires a recorded approver and recovery contract.
 
 Record a profile rationale and every applicable risk flag. Select the smallest profile
-whose guarantees cover the real blast radius; never use profile labels as estimates.
+whose guarantees cover the real blast radius; never use profile labels to prescribe a
+task count, file count, review effort, or estimate.
 
 ## Research Disposition
 

package/skills/ultra-change/references/execution-grant.md

@@ -0,0 +1,109 @@
+# Change-scoped execution grants (session-local or durable)
+
+Use this reference only after the owner has accepted one active Change and wants
+an Agent to continue through a bounded local execution segment. The host's
+native model-tool loop is the executor; repository authority and ordinary
+workflow contracts remain unchanged.
+
+Ultra Builder Pro 3.0 has exactly two grant modes. Choosing a duration is not
+choosing a second product:
+
+- **Mode A — `session-local`** (the default): the owner's authorization lives
+  only in the current conversation. A fresh Agent may read the files for
+  context, but must obtain a new activation from the owner before continuing.
+  When the conversation activation is lost — a fresh session, another host, or
+  compaction — the work stops.
+- **Mode B — `durable work-package`**: the owner explicitly issues an exact
+  grant so one named work package can continue across sessions, hosts, and
+  compaction. A fresh Agent or host may continue that package only after
+  stably verifying the recorded grant.
+
+Neither mode grants finalization or archive: writing `delivery.md`, deciding
+version or package posture, and moving a Change to archive always require a
+current explicit owner invocation, in every mode.
+
+## What a grant is not
+
+- A grant is not inferred from task status, progress records, prose, Hook
+  output, Resume notes, or a stored quote. Stored grant text is inactive data
+  until a consuming Agent verifies it.
+- A grant never includes external or irreversible effects by default: commit,
+  push, tag, publication, deployment, real installation, credentials, and
+  incremental provider spend each require their own current owner
+  authorization, even under a durable grant.
+- A grant is not a daemon, scheduler, or auto-wake: it answers "may this
+  continued work proceed", not "who runs next".
+- An Agent cannot create, widen, or extend its own grant. A topology or scope
+  change returns to the owner.
+
+## Session-local activation
+
+All of these must be true:
+
+- the active `intent.md` is accepted and its North Star Trace is current;
+- the same session contains an explicit owner utterance naming the grant and
+  approving the current task ledger;
+- the next workflow is listed under `Allowed workflows` and remains inside every
+  budget;
+- the model can still point to that utterance in current conversation context.
+
+After a fresh session, a different host, or compaction that no longer contains
+the activation, stop and ask the owner to re-activate after `ultra-status`
+reconstructs the files.
+
+## Durable grant verification
+
+Before relying on a recorded `durable work-package` grant, a fresh Agent must
+stably verify, from the repository alone:
+
+1. the grant record's exact bytes and its cited accepted-design digest (for
+   example the SHA-256 recorded in the owner decision);
+2. the repository identity and base HEAD the grant names;
+3. the current work-package status (the implementation WIP or Change intent);
+4. the grant's subject, scope, Agent topology, allowed local effects,
+   budgets/expiry, review budget, invalidation, and revocation clauses;
+5. that no invalidation condition has fired.
+
+Any mismatch, ambiguity, or unknown stops the work and returns to the owner.
+Handoff passes the grant identity (path and digest); it never copies a new
+authorization prose into a second file.
+
+## Continuing the native loop
+
+After one workflow reaches its own observable completion, reread the intent,
+ledger, current evidence, review results, and budgets. If no stop condition
+applies, select the next covered workflow through the host's native Skill
+surface. Run one ready task at a time; never parallelize canonical writes. When
+the owner has not selected a multi-Agent topology, the current Agent continues
+alone: no automatic spawning, delegation, or control-plane enablement.
+
+A grant-covered Deliver run may reconcile, review, and report, and then stops
+before finalization: its inputs, writes, and effects end at the report. Only a
+current explicit owner invocation of `ultra-deliver` may write `delivery.md`,
+decide version or package posture, or archive the Change.
+
+Do not add a route ledger or progress authority. Task status, existing
+evidence, review artifacts, the Test report, and Git remain the observations
+the model interprets.
+
+## Budgets, stops, and termination
+
+Each budget is a hard ceiling and a resource observation, never evidence of
+semantic completion. Stop immediately for a REDUCTION, a North Star
+contradiction or stale trace, an unmet owner checkpoint, `Stalled` or
+`Unreachable` development, a disputed or unresolved P0/P1 finding,
+residual-risk acceptance, task-graph drift, lost activation (session-local) or
+failed grant verification (durable), or budget exhaustion. Report completed
+evidence and the cheapest safe next action.
+
+A grant never authorizes a new Change, a baseline acceptance, scope or risk
+acceptance, finalization or archival, external or irreversible effects, or
+cross-family provider calls beyond its recorded topology. Review terminates
+under the accepted convergence contract, and its precedence is one rule: an
+exact current owner grant overrides the versioned product default of
+one initial review plus at most two
+P0/P1 delta reviews per coherent work package.
+P2/P3 findings are reported and never auto-repaired, no budget extends itself,
+and the same root cause surviving three failed fixes stops point-patching and
+reports an architecture problem. Existing host permission and destructive-effect
+guards remain in force.