ultra-builder-pro-cli 0.26.2 → 3.0.2

package/README.md

@@ -1,12 +1,42 @@
 # Ultra Builder Pro
 
 Ultra Builder Pro is a file-first engineering workflow for Claude Code, Codex,
-OpenCode, Kimi Code, and Grok Build. It keeps product intent, specifications, task
-contracts, evidence, decisions, and recovery notes in the repository, so a different
-session or host can continue by reading files and Git.
+OpenCode, Kimi Code, Grok Build, and ZCode. It implements the provider-neutral
+**Ultra Core Protocol**: owner–agent cognitive alignment, per-fact canonical
+authority, explicit session-local or durable work-package grants, exclusive
+verified handover between Agents, typed evidence with recovery, and review that
+terminates within an owner-visible budget. It keeps product
+intent, specifications, task contracts, evidence, decisions, and recovery notes
+in the repository, so a different session or host can continue by reading files
+and Git.
 
 The host model remains the engineer. Ultra supplies reusable methods and checkable
-artifacts; it does not replace reasoning with a workflow engine.
+artifacts; it does not replace reasoning with a workflow engine. Agent topology —
+one Agent or several, which providers — is the owner's choice at every stage; the
+default is the current Agent continuing alone, and handing the work package's
+writing authority to a different Agent requires an explicit verified transfer
+(OFFER → ACK → RESULT over the repository files and Git).
+
+## Ultra Builder Pro 3.0
+
+Version `3.0.2` is the first published release of Ultra as a cognitive-alignment harness for
+real software engineering. It is not a decentralized multi-agent platform and it
+does not prescribe one Agent topology. Instead, it keeps five promises:
+
+- establish the owner-accepted North Star before Research becomes a plan or code;
+- let the owner choose one Agent or several, and the provider, at every stage;
+- carry canonical intent, decisions, tasks, evidence, and recovery through files
+  under `.ultra/` plus Git so another session or host can resume from the same facts;
+- automate mechanically verifiable authority, permissions, external effects,
+  evidence, physical limits, and recovery while leaving meaning and strategy to the
+  model and owner; and
+- bound Review and repair so delivery converges instead of turning every observation
+  into another automatic implementation loop.
+
+The portable protocol and native installation cover Claude Code, Codex, OpenCode,
+Kimi Code, Grok Build, and ZCode. ZCode plugin installation is supported; its
+App-bundled headless delegation transport remains explicitly `experimental` until an
+official stable interface and recovery drill satisfy the support bar.
 
 ## Why it exists
 
@@ -51,14 +81,17 @@ The package installs exactly fourteen Skills in three roles.
 `ultra-status` is the single router. It infers the current route from project files,
 Git, and installation health without mutating the workflow.
 
-Public workflows are explicitly selected by the owner. One public workflow can
-recommend the next one, but does not launch it. Model-invoked disciplines remain
-available to the host model and are not separate user routes. The model selects one
-when the active task presents its trigger: incomplete intent uses grilling, competing
-terms use domain modeling, an accepted seam uses TDD, review-ready evidence uses
-review, and a consequential unresolved decision uses think. A host with native bounded
-subagents may parallelize review lenses; another host runs the same lens assets
-sequentially.
+Public workflows are explicitly selected by the owner by default. Outside a live,
+owner-activated execution grant (session-local, or a durable work-package grant), one public workflow can recommend the
+next one but does not launch it. Inside that grant, the host model may select only
+the covered Research, Plan, Dev, Test, and reconcile-only Deliver routes; Init, Change,
+Delegate, Status, final archive, and every external effect remain owner-selected.
+Model-invoked disciplines remain available to the host model and are not separate user
+routes. The model selects one when the active task presents its trigger: incomplete
+intent uses grilling, competing terms use domain modeling, an accepted seam uses TDD,
+review-ready evidence uses review, and a consequential unresolved decision uses think.
+A host with native bounded subagents may parallelize review lenses; another host runs
+the same lens assets sequentially.
 
 Inside `ultra-research`, the first six references are six semantic lenses, not six
 extra Skills: problem validation, opportunity discovery, market assessment,
@@ -70,12 +103,12 @@ map, evidence convergence, owner checkpoints, and baseline promotion.
 
 ### What happened to the original Agents
 
-v0.26 does not install a custom `agents/` projection. The old review workers became the
+Version 3.0.2 does not install a custom `agents/` projection. The old review workers became the
 six focused files under `ultra-review/references/`; review coordination and synthesis
 belong to the parent `ultra-review` Skill. The old debugger procedure lives under
 `ultra-dev/references/debugging.md`, and test execution lives under
 `ultra-tdd/references/test-execution.md`. These are assets of their Skills and therefore
-travel to all five hosts. They preserve a bounded role without pretending that every
+travel to all six hosts. They preserve a bounded role without pretending that every
 host exposes the same custom-agent API.
 
 ## Project authority
@@ -101,7 +134,7 @@ CONTEXT.md
 │   ├── active/<change-id>/{intent.md,delivery.md}
 │   ├── archive/<change-id>/{intent.md,delivery.md}
 │   └── abandoned/<change-id>/intent.md  # includes exact Abandonment closure
-├── contexts/<task-id>.md
+├── contexts/task-<task-id>.md
 ├── decisions/<decision-id>.md
 ├── evidence/<task-id>/...
 └── research/<run-id>/{brief.md,<step-id>.md}
@@ -110,7 +143,7 @@ CONTEXT.md
 The optional `brief.md` is derived navigation; the selected step reports are cited
 evidence, and promoted semantic facts live in the other canonical files. Git provides
 history, comparison, rollback, and archive moves. The following additional paths are
-derived and can be deleted or rebuilt:
+derived:
 
 ```text
 .ultra/.runtime/
@@ -118,6 +151,12 @@ derived and can be deleted or rebuilt:
 .ultra/reviews/
 ```
 
+`.ultra/.runtime/` and `.ultra/progress/` can be deleted or rebuilt from current
+authority. Retain the exact current strict review session until both Test and Deliver
+have successfully consumed it; only then may that session be garbage-collected. If it
+is lost before both consumers finish, run a fresh Review and Test and never reconstruct
+the old receipt.
+
 See [Artifact Authority](docs/ARTIFACT-AUTHORITY.md) for writer, reader, promotion,
 staleness, and recovery rules.
 
@@ -129,7 +168,7 @@ staleness, and recovery rules.
 | `ultra-research` | accepted North Star, first domain baseline, selected cited reports, reconciled specifications, and distillate | change, plan, and delivery |
 | `ultra-change` | one active `intent.md` with stable `change_id`, Research Disposition, and only the accepted baseline sections touched by that delta; or an exact Abandonment closure before an owner-authorized move | active: research through delivery; abandoned: future Change history and status |
 | `ultra-plan` | append-only `tasks.json` rows for the active `change_id`, one context per task, and Planning Posture in the active intent | dev and every resume path |
-| `ultra-dev` | source/tests, task evidence, synchronized task/context status, Completion and Resume Note | review, test, status, delivery |
+| `ultra-dev` | source/tests, typed task evidence, ledger-only task status, Completion, Task Review, and Resume Note | review, test, status, delivery |
 | `ultra-test` | the one current `test-report.json` bound to Change id, current task ids, intent digest, HEAD, and product-worktree digest | status and delivery |
 | `ultra-deliver` | first reconciled specs/docs, then after a fresh Test snapshot one `delivery.md` and the archived Change directory | owner and future Change history |
 | `ultra-status` | none | recommends the smallest explicit route from current files |
@@ -145,16 +184,17 @@ Node.js 22 or newer is required.
 
 ```bash
 # Current project, one host
-npx ultra-builder-pro-cli --claude --local
-npx ultra-builder-pro-cli --codex --local
+npx ultra-builder-pro-cli@3.0.2 --claude --local
+npx ultra-builder-pro-cli@3.0.2 --codex --local
 
 # Global installation
-npx ultra-builder-pro-cli --opencode --global
-npx ultra-builder-pro-cli --kimi --global
-npx ultra-builder-pro-cli --grok --global
+npx ultra-builder-pro-cli@3.0.2 --opencode --global
+npx ultra-builder-pro-cli@3.0.2 --kimi --global
+npx ultra-builder-pro-cli@3.0.2 --grok --global
+npx ultra-builder-pro-cli@3.0.2 --zcode --global
 
 # All supported hosts
-npx ultra-builder-pro-cli --all --global
+npx ultra-builder-pro-cli@3.0.2 --all --global
 ```
 
 Use the host's native Skill picker or invocation syntax to select an owner workflow.
@@ -167,13 +207,13 @@ Installation is managed, atomic, and provenance-checked.
 
 ```bash
 # Re-running install updates the managed artifact
-npx ultra-builder-pro-cli --codex --global
+npx ultra-builder-pro-cli@3.0.2 --codex --global
 
 # Read-only diagnosis
-npx ultra-builder-pro-cli --all --global --doctor --json
+npx ultra-builder-pro-cli@3.0.2 --all --global --doctor --json
 
 # Remove only managed Ultra assets
-npx ultra-builder-pro-cli --all --global --uninstall
+npx ultra-builder-pro-cli@3.0.2 --all --global --uninstall
 ```
 
 `--config-dir <path>` isolates both the primary config and host-owned sidecars. It is
@@ -185,9 +225,9 @@ Uninstall removes the managed plugin and prunes only empty config shells that we
 absent before the first install. Pre-existing registries, directories, symlinks, and
 any path containing owner data are preserved.
 
-Kimi Code and Grok Build currently expose user-scoped plugins only, so `--local`
+Kimi Code, Grok Build, and ZCode currently expose user-scoped plugins only, so `--local`
 rejects them before mutation. Claude Code, Codex, and OpenCode support project-local
-installation; all five support managed global installation and isolated
+installation; all six support managed global installation and isolated
 `--config-dir` verification.
 
 ## Typical workflow
@@ -203,21 +243,38 @@ installation; all five support managed global installation and isolated
    the delta touches before planning; it does not rebuild the project baseline. Its
    Research Disposition either cites sufficient evidence or names the bounded question
    and exit evidence that must return through Research. A micro edit that makes no
-   specification sentence false stays outside Ultra; an accepted quick Change still
-   receives one Plan task. While that Change remains active, reconcile its same stable
-   id; never open a second active Change for a separate request.
+   specification sentence false stays outside Ultra; every accepted Change receives the
+   smallest Plan graph justified by its real seams, evidence, review, and recovery needs.
+   A profile never fixes task count. While that Change remains active, reconcile its
+   same stable id; never open a second active Change for a separate request.
 4. Select `ultra-plan` to record public seams and produce resumable tracer-bullet tasks.
    The model owns ordinary technical seams; the owner decides only a seam that changes
    the public contract or another material trade-off.
-5. Select `ultra-dev` for one task at a time. Each task leaves a Completion entry,
-   evidence, and a closing Resume Note.
-6. Select `ultra-test` once tasks for the active Change are complete. Historical ledger
-   rows do not enter this audit. Local green tests do not substitute for wiring and E2E proof.
+5. Select `ultra-dev` for one task at a time. `.ultra/tasks.json` is the sole task-status
+   authority. Dev records typed v2 evidence and completes task review while the row is
+   still `in_progress`; only after blocking findings and affected evidence are resolved
+   does it write `completed`, add Completion, and rewrite the Resume Note.
+6. Select `ultra-test` once tasks for the active Change are completed with current v2
+   evidence and retained task-review provenance. Historical ledger rows and legacy
+   context Status fields do not enter this audit. Local green tests do not substitute
+   for wiring and E2E proof.
 7. Select `ultra-deliver` to run aggregate review and reconcile documentation. If that
    changes product or semantic files, rerun Test; re-enter Deliver on the fresh snapshot
    to write delivery metadata and archive the stable Change id. Commit, push, tag,
    publication, and deployment remain separately authorized effects.
 
+For one accepted Change, the owner may activate its exact `Execution Grant` in either
+mode. A `session-local` grant lives only in the current conversation: when that
+activation is lost — a fresh session, another host, or compaction — the work stops and
+waits for a new owner activation. A `durable work-package` grant lets a fresh Agent or
+host continue one exact work package, but only after the Agent stably verifies the
+recorded grant itself. In both modes the model may select the covered Research, Plan,
+Dev, Test, and reconcile-only Deliver routes until the next semantic stop or declared
+budget, and neither mode grants finalization or archive: writing `delivery.md`, version
+or package posture, and archiving always require a current explicit owner invocation,
+as do commit, push, publication, deployment, installation, and every other external
+effect.
+
 At any point, `ultra-status` can reconstruct the current position. A fresh session or
 different host resumes by reading `.ultra/tasks.json`, the selected `context_file`, its
 `## Resume Note`, `CONTEXT.md`, relevant decisions, the active Change, and Git. It first
@@ -249,7 +306,7 @@ Five optional hooks accelerate file reading and protect a narrow effect boundary
 | `post_edit_guard.py` | Record mechanical evidence observations after edits |
 | `block_dangerous_commands.py` | Advise on additive protected-branch publication; deny history rewrites and named destructive shell effects until the exact command is authorized |
 
-All five exit silently when `.ultra/` is absent. Details are in
+All five hooks exit silently when `.ultra/` is absent. Details are in
 [Plugin Isolation](docs/PLUGIN-ISOLATION-CONTRACT.md).
 
 ## Delegation
@@ -259,7 +316,8 @@ selected CLI in the background. Empty writable roots select native read-only mod
 declared roots select bounded write mode. The model returns one schema-constrained final
 response; the launcher extracts it from native structured output, validates the actual
 Git diff, and atomically publishes a terminal `finished`, `blocked`, or `failed` result
-beside the instruction.
+beside the instruction. The digest-bound packet is embedded in the worker prompt, so a
+strict host need not read instruction files outside its isolated worktree.
 
 ```bash
 ubp delegate run --to codex \
@@ -286,6 +344,7 @@ reachable without inventing ledger work.
 | OpenCode | 14 | 5 through native JS plugin | bundle + skill directories |
 | Kimi Code | 14 | 5 through wire adapter | managed plugin registry |
 | Grok Build | 14 | 5 through wire adapter | native plugin registration when available |
+| ZCode | 14 | 5 through wire adapter | inline plugin + local marketplace + reversible config registration |
 
 See [Runtime Compatibility](docs/RUNTIME-COMPAT-MATRIX.md) for exact paths and host
 limitations.
@@ -308,10 +367,19 @@ npm pack --dry-run --json
 
 Every changed Skill is also validated with the Codex Skill Creator validator. A changed
 Codex manifest is validated against the Plugin Creator schema. No release effect is
-implied by a green verification run.
+implied by a green verification run, and validator success establishes structural
+conformance rather than semantic acceptance.
 
 ## Documentation
 
+- [Current authority](.ultra/north-star.md) — this repository's accepted
+  North Star, revision `north-star-v2-r3`, is the canonical current authority;
+  `.ultra/tasks.json` and the stable Change under `.ultra/changes/active/` or
+  `.ultra/changes/archive/` record the current or delivered work frontier.
+- Frozen design history (immutable accepted records, not live status):
+  [3.0 North Star R3](docs/ULTRA-BUILDER-PRO-3.0-NORTH-STAR-R3.zh-CN.md) —
+  the hash-bound accepted r3 design — and
+  [3.0 design](docs/ULTRA-BUILDER-PRO-3.0.zh-CN.md), superseded by r3.
 - [Philosophy](docs/PHILOSOPHY.md)
 - [Architecture](docs/ARCHITECTURE.md)
 - [Artifact Authority](docs/ARTIFACT-AUTHORITY.md)
@@ -319,6 +387,8 @@ implied by a green verification run.
 - [Skill Authoring](docs/SKILL-AUTHORING.md)
 - [Plugin Isolation](docs/PLUGIN-ISOLATION-CONTRACT.md)
 - [Runtime Compatibility](docs/RUNTIME-COMPAT-MATRIX.md)
+- [Adversarial Review Evaluation](docs/evals/adversarial-review-2026-08-14.md)
+- [ZCode Automation Evaluation](docs/evals/zcode-automation-2026-08-14.md)
 
 ## License
 

package/adapters/_shared/host-profile.cjs

@@ -1,8 +1,28 @@
 'use strict';
 
+const fs = require('node:fs');
 const path = require('node:path');
 
 const KIMI_PROFILE_ROOT = path.join(__dirname, 'delegate-profiles');
+const ZCODE_BUNDLED_CLI = '/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs';
+
+// The ZCode app-bundled CLI is a verified-local surface, not a provider
+// stability promise: official documentation plus a full recovery drill must
+// both hold before any transport may claim 'supported'.
+const TRANSPORT_MATURITY = Object.freeze({
+  claude: 'documented+verified',
+  codex: 'documented+verified',
+  opencode: 'documented+verified',
+  kimi: 'documented+verified',
+  grok: 'documented+verified',
+  zcode: 'experimental',
+});
+
+function zcodeBinary({ platform = process.platform, exists = fs.existsSync } = {}) {
+  return platform === 'darwin' && exists(ZCODE_BUNDLED_CLI)
+    ? ZCODE_BUNDLED_CLI
+    : 'zcode';
+}
 
 function opencodePermission(writableRoots) {
   const edit = { '*': 'deny' };
@@ -39,7 +59,6 @@ const PROFILES = Object.freeze({
       '--permission-mode', options.readOnly ? 'plan' : 'acceptEdits',
       '--no-session-persistence',
       '--output-format', 'json',
-      '--json-schema', options.schemaJson,
       '--tools', options.readOnly ? 'Read,Grep,Glob' : 'Read,Write,Edit,Grep,Glob',
     ],
   }),
@@ -66,14 +85,19 @@ const PROFILES = Object.freeze({
   }),
   kimi: Object.freeze({
     binary: 'kimi',
-    delegateArgv: (prompt, _cwd, options) => [
-      '-p', prompt,
-      '--output-format', 'stream-json',
-      '--agent-file', path.join(
-        KIMI_PROFILE_ROOT,
-        options.readOnly ? 'kimi-read-only.md' : 'kimi-write.md',
-      ),
-    ],
+    supportsModelSelection: true,
+    delegateArgv: (prompt, _cwd, options) => {
+      const args = ['-p', prompt, '--output-format', 'stream-json'];
+      if (options.model) args.push('--model', options.model);
+      args.push(
+        '--agent-file',
+        path.join(
+          KIMI_PROFILE_ROOT,
+          options.readOnly ? 'kimi-read-only.md' : 'kimi-write.md',
+        ),
+      );
+      return args;
+    },
   }),
   grok: Object.freeze({
     binary: 'grok',
@@ -82,16 +106,48 @@ const PROFILES = Object.freeze({
       '--permission-mode', options.readOnly ? 'plan' : 'acceptEdits',
       '--sandbox', options.readOnly ? 'read-only' : 'workspace',
       '--no-memory', '--no-subagents', '--disable-web-search',
-      '--json-schema', options.schemaJson,
+      '--verbatim',
+      '--max-turns', '12',
       '--output-format', 'json',
     ],
   }),
+  zcode: Object.freeze({
+    binary: zcodeBinary(),
+    delegateArgv: (prompt, cwd, options) => [
+      '--cwd', cwd,
+      '--mode', options.readOnly ? 'plan' : 'edit',
+      '--json', '--no-color',
+      '--disallowedTools', options.readOnly
+        ? 'Bash Write Edit ApplyPatch Agent WebFetch WebSearch'
+        : 'Bash Agent WebFetch WebSearch',
+      '--prompt', prompt,
+    ],
+  }),
 });
 
 function hostProfile(runtime) {
   const profile = PROFILES[runtime];
   if (!profile) throw new Error(`unsupported delegate host: ${runtime}`);
-  return profile;
+  return { ...profile, transportMaturity: TRANSPORT_MATURITY[runtime] };
+}
+
+// The live delegate surface names honestly what a run actually used. The ZCode
+// headless transports are app-internal surfaces, never the documented ZCode
+// Desktop interactive primary path, so every receipt that records one says so.
+function transportSurface(runtime, binary = PROFILES[runtime] ? PROFILES[runtime].binary : undefined) {
+  if (runtime === 'zcode') {
+    const source = binary === ZCODE_BUNDLED_CLI ? 'the App-bundled headless CLI' : 'the zcode headless CLI on PATH';
+    return `${source} (experimental; not the documented ZCode Desktop interactive surface)`;
+  }
+  return 'documented non-interactive CLI';
 }
 
-module.exports = { PROFILES, hostProfile, opencodePermission };
+module.exports = {
+  PROFILES,
+  TRANSPORT_MATURITY,
+  ZCODE_BUNDLED_CLI,
+  hostProfile,
+  opencodePermission,
+  transportSurface,
+  zcodeBinary,
+};

package/adapters/_shared/plugin-core.cjs

@@ -15,7 +15,6 @@ const {
 const { parse, serialize } = require('./frontmatter.cjs');
 const provenance = require('./provenance.cjs');
 const {
-  MODEL_INVOKED_SKILLS,
   WORKFLOW_HOOK_FILES,
   skillPolicy,
   skillsForRuntime,
@@ -34,13 +33,13 @@ function skillFrontmatter(runtime, name, fm) {
     return {
       ...base,
       'user-invocable': policy.userInvocable,
-      ...(policy.userInvocable ? { 'disable-model-invocation': true } : {}),
+      ...(!policy.allowImplicitInvocation ? { 'disable-model-invocation': true } : {}),
     };
   }
   if (runtime === 'kimi') {
     return {
       ...base,
-      ...(policy.userInvocable ? { disableModelInvocation: true } : {}),
+      ...(!policy.allowImplicitInvocation ? { disableModelInvocation: true } : {}),
     };
   }
   return base;
@@ -54,7 +53,7 @@ function codexMetadata(name, description) {
     `  short_description: ${JSON.stringify(short || titleCase(name))}`,
     `  default_prompt: ${JSON.stringify(`Use $ultra-builder-pro:${name} and follow its workflow.`)}`,
     'policy:',
-    `  allow_implicit_invocation: ${MODEL_INVOKED_SKILLS.includes(name) ? 'true' : 'false'}`,
+    `  allow_implicit_invocation: ${skillPolicy(name).allowImplicitInvocation ? 'true' : 'false'}`,
     '',
   ].join('\n');
 }
@@ -99,7 +98,7 @@ function copyHooks({ runtime, repoRoot, hookRoot, hooksManifest }) {
     if (!fs.existsSync(source)) throw new Error(`missing allowlisted hook: ${name}`);
     fs.copyFileSync(source, path.join(hookRoot, name));
   }
-  if (['codex', 'kimi', 'grok'].includes(runtime)) {
+  if (['codex', 'kimi', 'grok', 'zcode'].includes(runtime)) {
     ensureDir(path.join(hookRoot, 'adapters'));
     fs.copyFileSync(
       path.join(repoRoot, 'hooks', 'adapters', `${runtime}.py`),

package/adapters/_shared/runtime-assets.cjs

@@ -27,7 +27,14 @@ const MODEL_INVOKED_SKILLS = Object.freeze([
 ]);
 
 const ROUTER_SKILLS = Object.freeze(['ultra-status']);
-const SUPPORTED_RUNTIMES = Object.freeze(['claude', 'opencode', 'codex', 'kimi', 'grok']);
+const GRANT_CONTINUABLE_SKILLS = Object.freeze([
+  'ultra-research',
+  'ultra-plan',
+  'ultra-dev',
+  'ultra-test',
+  'ultra-deliver',
+]);
+const SUPPORTED_RUNTIMES = Object.freeze(['claude', 'opencode', 'codex', 'kimi', 'grok', 'zcode']);
 
 const WORKFLOW_HOOK_FILES = Object.freeze([
   'session_context.py',
@@ -53,13 +60,15 @@ function skillPolicy(name) {
     throw new Error(`unknown packaged Ultra skill: ${name}`);
   }
   const modelInvoked = MODEL_INVOKED_SKILLS.includes(name);
+  const grantContinuable = GRANT_CONTINUABLE_SKILLS.includes(name);
   return {
     userInvocable: !modelInvoked,
-    allowImplicitInvocation: modelInvoked,
+    allowImplicitInvocation: modelInvoked || grantContinuable,
   };
 }
 
 module.exports = {
+  GRANT_CONTINUABLE_SKILLS,
   USER_INVOKED_SKILLS,
   MODEL_INVOKED_SKILLS,
   ROUTER_SKILLS,