ultra-builder-pro-cli 0.26.2 → 3.0.2

package/docs/DECISIONS.md

@@ -1,8 +1,53 @@
-# Ultra Builder Pro v0.26 decisions
+# Ultra Builder Pro decisions
 
 This file records durable product-level decisions that explain the current source tree.
 Project decisions created by Ultra belong in each project's `.ultra/decisions/`.
 
+## Ultra Core Protocol (3.0, accepted 2026-08-17; r3 revision same day)
+
+The owner accepted `docs/ULTRA-BUILDER-PRO-3.0.zh-CN.md` and projected it as North
+Star revision `north-star-v2-r2`
+(`.ultra/decisions/2026-08-17-ultra-3-0-north-star-r2.md`), then converged the
+constitution with the owner-directed r3 design
+(`docs/ULTRA-BUILDER-PRO-3.0-NORTH-STAR-R3.zh-CN.md`) as revision
+`north-star-v2-r3`
+(`.ultra/decisions/2026-08-17-ultra-3-0-north-star-r3.md`). Ultra Builder Pro is
+the file-first, provider-neutral Ultra Core Protocol: cognitive alignment through
+checkpoints, per-fact canonical authority, explicit dual-mode authorization, typed
+evidence with recovery, exclusive verified Agent handover, and review convergence
+bounded by an owner-visible budget. The constitution itself stays count-free —
+agent counts and topology detail, Host and Skill counts, provider names, and
+exact review-round numbers live in the versioned product contract and exact
+work-package grants. Authorization has two
+modes — `session-local` by default, `durable work-package` when the owner issues an
+exact grant (see `.ultra/decisions/2026-08-17-ultra-builder-pro-3.0-mode-b.md`); no
+file, status, Hook, or Resume note ever implies activation. Optional Graph/Loop
+coordination layers own observations only and none is integrated.
+
+## Primary transfer between Agents (r3, accepted 2026-08-17)
+
+A work package's canonical writer moves to another Agent only through an
+owner-granted primary transfer: the sender writes current reality into the task
+context and Resume Note, derives an OFFER binding canonical refs/hashes, HEAD,
+and the worktree digest, and stops writing after the receiver's ready ACK; the
+receiver stable-reads, verifies every digest, becomes the sole canonical writer,
+and freezes a terminal RESULT. Receipts under `.ultra/.runtime/handoffs/` are
+derived and rebuildable, never authority; mismatches block instead of
+auto-repairing; delegated workers stay mutually exclusive with this path and
+never write canonical `.ultra`
+(`.ultra/decisions/2026-08-17-ultra-3-0-r3-primary-handoff.md`,
+`skills/ultra-change/references/primary-transfer.md`).
+
+## ZCode headless transport stays experimental (r3, accepted 2026-08-17)
+
+The ZCode app-bundled CLI is a verified-local surface — it exists, launches, and
+passed local drills — but the provider publishes no headless CLI, SDK, or
+protocol stability contract. Its transport maturity is recorded `experimental`
+in the shared host profile and compatibility matrix; promotion to `supported`
+requires both official documentation and a full recovery drill. Interactive
+Desktop use and the documented plugin surface are unaffected, and no adapter may
+pass an app-internal binary off as an official stable interface.
+
 ## File-first authority
 
 Owner-readable repository files and Git are the complete semantic authority. Ultra
@@ -13,14 +58,58 @@ ownership of route and meaning.
 
 ## Three Skill roles
 
-The product exposes eight owner-invoked workflows, five model-invoked disciplines, and
-one router. Public workflows require explicit owner selection. A public workflow may
-recommend but never launch another public workflow. A model discipline needs at least
-two canonical callers or it is inlined.
+The product exposes eight user workflows, five model-invoked disciplines, and one
+router. Public workflows require explicit owner selection by default. Research, Plan,
+Dev, Test, and Deliver reconciliation have one narrow exception: an activated
+Change-scoped execution grant may let the model select the next covered workflow —
+session-local activation in the current conversation, or a stably verified durable
+work-package grant. A model discipline needs at least two canonical callers or it is
+inlined.
 
 This keeps reusable reasoning in one place without turning it into another user-facing
 route or custom-agent registry.
 
+## Bounded same-session continuation
+
+The stored grant text is descriptive authority, not an executable grant. Session-local
+activation is a current owner utterance approving the exact grant and current task
+ledger; a durable work-package grant is executable only after a fresh Agent stably
+verifies its recorded subject, scope, topology, effects, budgets, expiry, revocation,
+and invalidation. A fresh session without a durable grant, host change, lost
+activation context, semantic stop, or budget ceiling pauses
+the loop. Plan, task, and aggregate reviews remain mandatory. Delivery continuation is
+reconcile-only; finalization, archive, authenticated providers, install, commit, push,
+publish, and deploy remain separately authorized.
+
+The native host model-tool loop performs the work. Existing files and Git carry
+recovery; no route position, daemon, or extra semantic store is introduced.
+
+## Review topology is owner-selected
+
+The owner chooses reviewer and provider count for each stage. The default is one reviewer:
+the current Agent. An initial task review selects `review-spec` plus the
+lenses justified by risk and touched seams; a delta review reruns only affected
+lenses; an aggregate Change review may default to the full roster only when cross-task
+wiring justifies it — never as a mandatory count or a quality proxy. Specification
+fidelity owns both accepted-behavior mapping and the challenge to a Change's claimed
+North Star contribution, with actual execution mode and coverage recorded. When
+another model family is available, a blind premise challenger is an additional probe
+rather than a voting lens.
+
+The seeded 2026-08-14 evaluation found no consequential defect class uniquely caught
+by a permanent premise lens: the strengthened specification lens, the six-concern Kimi
+probe, and the ZCode specification probe each found all five hidden classes. Grok's
+malformed terminal output was rejected and was not counted as semantic evidence. See
+`docs/evals/adversarial-review-2026-08-14.md`.
+
+## ZCode activation uses documented plugin directories
+
+ZCode receives a managed local marketplace for importability and a documented
+`plugins.dirs` entry for immediate native discovery. Ultra owns only the entry it adds,
+so reinstall is idempotent and uninstall preserves unrelated user configuration. It
+does not write ZCode's private plugin cache or copy desktop provider credentials into
+headless CLI configuration.
+
 ## Intake, baseline, and delta
 
 Init preserves raw owner intake in the Project Brief; Research establishes the accepted North Star, domain language, and specification baseline; Change reconciles only the sections touched by one requested delta.
@@ -47,14 +136,36 @@ Directory position and explicit fields record mechanically checkable facts. The
 model reads those facts and chooses the next route. There is no persisted “current
 workflow stage” whose value can override the actual files.
 
-Task status is written to both the ledger and context, then read back. Tasks retain a
-stable `change_id` in an append-only ledger; current readers select only rows matching
-the one active Change. Archive or abandonment is a `git mv`. Test-report freshness
-compares Change id, current task ids, intent digest, `git_commit`, and product-worktree
-digest with the current checkout. Deliver reconciles first and finalizes only while
-that complete snapshot remains current. A separate request cannot create a second
-active Change; it waits, exits the current Change, or is explicitly reconciled into the
-same id.
+Task status lives only in the `ultra-task-ledger-v2` row and is read back there. New task
+contexts do not duplicate it; legacy context Status and Complexity fields remain
+migration diagnostics and the ledger wins. Tasks retain a stable `change_id` in the
+append-only ledger; current readers select only rows matching the one active Change.
+Archive or abandonment is a `git mv`. Test-report freshness is governed normatively by the complete v2 rule in [Artifact Authority](ARTIFACT-AUTHORITY.md#evidence-promotion).
+That authority binds the current Change snapshot, ordered v2 task-evidence identities,
+and strict aggregate-review packet, admission, subject, and summary bindings. This
+decision intentionally does not maintain a second field mirror. Deliver reconciles
+first and finalizes only while that complete snapshot remains current. A separate
+request cannot create a second active Change; it waits, exits the current Change, or is
+explicitly reconciled into the same id.
+
+## Typed task evidence and completion ordering
+
+Current work uses `ultra-task-evidence-v2`. Command, inspection, owner-judgment, and
+external-observation evidence retain distinct authorities; the owner alone can supply
+an owner-judgment result. Structural validators report exact fields, identities,
+digests, provenance, and freshness, never semantic acceptance. A task remains
+`in_progress` through its task review. Blocking findings and their dispositions are
+recorded and affected evidence is refreshed before the primary model writes
+`completed` to the ledger. Historical v1 evidence remains readable but cannot satisfy a
+current Change's Test or Deliver input without migration.
+
+## Counts are observations, not semantic gates
+
+Task, file, line, context, question, finding, repair-round, and complexity counts do not
+decide plan quality, review convergence, staleness, or completion. The model interprets
+concrete coupling, evidence, risk, and recovery facts. Explicit physical ceilings such
+as time, bytes, cost, provider spend, or bounded process resources still stop resource
+consumption and return a typed recovery path; exhaustion never dispositions a finding.
 
 ## Three independent integration defences
 
@@ -76,10 +187,13 @@ their repair is authorization scoped to the exact command digest.
 ## Delegation is a process boundary
 
 `ubp delegate run` starts a supported CLI with an immutable instruction, explicit
-permission JSON, and named worktree. Files are the cross-host state. The parent reads a
-stable terminal result instead of worker chatter. Delegation adds no semantic store and
-no authority. The instruction selects task execution, scoped Research evidence, or
-aggregate Change review/verification; only task execution requires a task row.
+permission JSON, and named worktree. Their exact digest-bound sources are embedded in
+the worker prompt because some native sandboxes correctly deny reads outside the
+worktree. Files remain the cross-host state; the embedded copy is transport, not another
+authority. The parent reads a stable terminal result instead of worker chatter.
+Delegation adds no semantic store and no authority. The instruction selects task
+execution, scoped Research evidence, or aggregate Change review/verification; only task
+execution requires a task row.
 
 ## Installation isolation
 

package/docs/PHILOSOPHY.md

@@ -45,10 +45,36 @@ one or more.
 
 The agent never stops seeing the current steering contract. Before Research accepts a
 baseline, the session Hook injects the raw Project Brief fallback. After Research, it
-injects the accepted North Star: Project Direction, any settled North Star Outcome, and
-Hard Constraints. Current task acceptance is appended in both cases. The cost of
+requires the exact field ``- Status: `accepted``` and injects the accepted North Star v2 `## Problem Reality`,
+`## First-Principle Propositions`, `## North Star Outcomes`, and `## Hard Constraints`.
+The complete selected sections have a 32 KiB SessionStart ceiling. Above it, the Hook
+uses a reference-only fallback containing the canonical path, immutable accepted snapshot
+path, revision, status, exact validated SHA-256 and byte length, and a direct-read
+instruction that rejects different bytes as authority; semantic truncation is forbidden.
+Brownfield fallback still reads the actual v0.26 `## Project Direction`, `## North Star
+Outcome`, and `## Hard Constraints` shape, or the older `## One-line` shape, without
+misreporting either as v2. Current task acceptance is appended in every case. The cost of
 repetition is always less than the cost of drift.
 
+The publication choice is exact: inject a mechanically bound accepted North Star, otherwise use the Project Brief fallback or a recognized legacy shape.
+When selected accepted sections exceed 32 KiB, use the reference-only path instead of
+semantic truncation. A v2 file whose decision, digest, or immutable snapshot binding is
+invalid is never labelled accepted session authority.
+The Hook does not maintain a second accepted-publication grammar. It safely locates the
+installed sibling Research validator and invokes that one JavaScript report through a
+bounded argv-only subprocess. Missing Node.js, a missing validator, timeout, malformed or
+oversized output, invalid UTF-8, and repository path escape all produce a typed repair
+fallback rather than accepted authority. The report checks the complete mechanical
+structure; it does not decide whether the accepted semantics are true or valuable.
+North Star and Project Brief ingress share one bounded 8 MiB regular-file snapshot:
+repository root, parent components, and file identity are recorded, symlink components
+are rejected, and the canonical root-to-file chain is freshly reopened after the read.
+Every accepted, reference-only, legacy, or Project Brief publication consumes only those
+captured bytes. An unavailable Project Brief produces a typed repair note and is never
+reread through an unbounded path API. This detects ordinary cooperative-workspace drift;
+it is not a claim that a process can prevent malicious operating-system-level replacement.
+The v0.26 legacy branch recognizes headings `## Project Direction`, `## North Star Outcome`, `## Hard Constraints` exactly.
+
 > **Test**: pick a random in-progress task, ask the agent "what's the acceptance criteria?" — if
 > it cannot answer in one sentence, this commandment is broken.
 
@@ -90,6 +116,30 @@ The agent always knows "how far from done." Each edit updates `.ultra/progress/<
 with evidence completeness across six dimensions. Final-gate audits are forbidden — if a gap
 matters at the end, it matters mid-flight.
 
+Canonical task evidence uses `ultra-task-evidence-v2`: command, inspection,
+owner-judgment, and external-observation retain distinct authorities, while the six
+dimensions remain independent observations. The owner alone supplies an
+owner-judgment result. Validators may check structure, identity, provenance, freshness,
+and exact references; they never decide semantic acceptance. `.ultra/tasks.json` is the
+sole task-status authority. A task remains `in_progress` through task review and becomes
+`completed` only after blocking findings are resolved or authoritatively dispositioned
+and affected evidence is refreshed. First-review admission uses the ledger, task
+context, immutable packet, and actual pre-review evidence; the one final v2 record is
+published only after its final review summary validates. Its `subject` is an independently
+captured completion-snapshot freshness observation made after that validation and
+immediately before evidence publication. Its `task_review` separately binds the retained strict summary; the summary does not prove the subject worktree digest. Aggregate Test
+recomputes each command or external receipt's bounded stable bytes against
+`raw_evidence_sha256`, then recomputes the exact record `evidence_digest`. The
+product-worktree digest excludes `.ultra/evidence/**`; these separate raw and record
+bindings make publication non-self-referential without making it invisible.
+Aggregate Test
+separately binds the current whole Change and rechecks current Acceptance, criterion and
+verification type, review summary, owner record, and cited-artifact evidence. If later work
+invalidates a completed task, Dev records affected criteria and reason in Change Log
+and Resume Note before the explicit ledger `completed` to `in_progress` transition;
+there is no silent demotion. Legacy context Status/Complexity and v1 evidence remain
+honest migration diagnostics, not alternative truth.
+
 > **Scoped exception**: whole-system wiring audit (`ultra-test`) is necessarily terminal, because
 > "this export has no non-test importer" cannot be evaluated while later tasks are still pending.
 > It is a terminal **sensor**, never a gate: it reports and hands the trade-off to the owner.
@@ -187,15 +237,16 @@ Skill instruction. Do not touch it casually.
 
 | Consumer | Reads | Source of truth | Failure mode if drifted |
 |---|---|---|---|
-| `session_context` | North Star headings `## Project Direction`, `## North Star Outcome`, `## Hard Constraints`; Project Brief `## One-line`, or legacy North Star `## One-line` | `.ultra-template/north-star.md`, `.ultra-template/project-brief.md`, and the Hook's legacy-read branch | SessionStart shows no accepted North Star or Project Brief fallback; C1 dies |
-| `session_context` | unique active `change_id` → one matching `in_progress` task, else first dependency-ready `pending` task → its context | active Change directory plus `tasks.json[].change_id`, dependencies, status, and `context_file` | abandoned or blocked acceptance is injected, or current acceptance never surfaces |
+| `session_context` | the canonical JavaScript North Star validation report; bound accepted v2 sections or the 32 KiB immutable-snapshot reference with exact validated SHA-256 and byte length, without semantic truncation; Project Brief `## One-line`; actual v0.26 `## Project Direction` / `## North Star Outcome` / `## Hard Constraints`; or older North Star `## One-line` | `skills/ultra-research/scripts/validate_north_star.cjs`, `.ultra-template/north-star.md`, `.ultra-template/project-brief.md`, accepted `.ultra/north-star.md`, its owner decision and immutable snapshot, and the validator's two legacy-read shapes | Python and JavaScript publication grammars diverge, SessionStart labels unbound or different bytes accepted, truncates steering semantics, or shows no honest Project Brief/legacy fallback; C1 dies |
+| `session_context` | unique active `change_id` → one matching ledger `in_progress` task, else first dependency-ready ledger `pending` task → its context; legacy context Status/Complexity are diagnostics only | active Change directory plus `tasks.json[].change_id`, dependencies, sole status, and `context_file` | abandoned or blocked acceptance is injected, a legacy context overrides the ledger, or current acceptance never surfaces |
 | `mid_workflow_recall` | heading `## Acceptance Criteria` | `.ultra-template/contexts/TEMPLATE.md` | hook injects nothing; C1 dies silently |
 | `ultra-tdd` | path `references/templates/*` | `skills/ultra-tdd/references/templates/` | guidance points at a missing runnable alternative; C2 dies |
-| `post_edit_guard` | writes `.ultra/progress/<task-id>.json` for the active Change's current task | active Change directory plus `tasks.json[].change_id` and `id`, created on demand | historical work receives current observations; C4 weakens |
-| `ultra-dev` and `post_edit_guard` | 6 keys: `tests_written`, `tests_passed`, `persistence_real`, `feature_flags_audit`, `vertical_slice`, `spec_trace` | the six-dimension table in `skills/ultra-dev/SKILL.md` | sensor and workflow report different evidence |
+| `post_edit_guard` | writes `.ultra/progress/<task-id>.json` for the active Change's current ledger task | active Change directory plus `tasks.json[].change_id`, `id`, and sole `status`, created on demand | historical work receives current observations or a Hook invents completion; C4 weakens |
+| `ultra-dev` and `post_edit_guard` | 6 keys: `tests_written`, `tests_passed`, `persistence_real`, `feature_flags_audit`, `vertical_slice`, `spec_trace` | the six-dimension table in `skills/ultra-dev/SKILL.md` and typed evidence contract in `skills/ultra-plan/references/task-evidence-v2.md` | sensor and workflow report different evidence or a progress observation becomes semantic acceptance |
+| plan/dev/review/test/deliver | ledger status; actual pre-review inputs; one final `ultra-task-evidence-v2` carrying an independent completion-snapshot freshness observation and separate task-review provenance; aggregate Test identity | `.ultra/tasks.json`, task context, immutable Review artifacts, and `skills/ultra-plan/references/task-evidence-v2.md` | first review requires its own final output, context becomes a second status authority, review provenance is claimed to prove the independent subject, task subject is rebound to a later aggregate worktree, or invalid evidence is silently demoted |
 | planning and status | marker `[NEEDS CLARIFICATION]` | `.ultra-template/specs/*.md` | unresolved product truth is hidden |
 | `ultra-plan` / `ultra-dev` / hooks | `trace_to` form `.ultra/specs/file.md#anchor` | `tasks.json[].trace_to` + GFM heading slugify | traces appear resolved when their heading is absent |
-| `ultra-deliver` / `ultra-status` | fields `change_id`, `task_ids`, `intent_digest`, `git_commit`, and `worktree.diff_digest` | `.ultra/test-report.json` plus `worktree_digest.cjs` | stale Change, intent, task set, or product results pass as current |
+| `ultra-deliver` / `ultra-status` | root Change identity, ordered v2 task-evidence/review identities, and strict aggregate Review packet/admission/subject/summary bindings | `.ultra/test-report.json`, retained task evidence and Review artifacts, `worktree_digest.cjs`, and existing structural validators | stale Change, intent, task set, task evidence, Review transport, or product results pass as current |
 | `compact_context` | `.ultra/.runtime/compact-snapshot.md` | derived from canonical files and Git | compact recovery loses acceleration, not authority |
 | every hook | existence of `.ultra/` | the project directory | Ultra taxes projects that never opted in (see `docs/PLUGIN-ISOLATION-CONTRACT.md`) |
 | `ultra-init` | the project data skeleton | `.ultra-template/` and the exact file list in its Skill | later Skills read missing authority paths; C1 dies |

package/docs/PLUGIN-ISOLATION-CONTRACT.md

@@ -55,6 +55,12 @@ non-empty, modified, symlinked, or unowned path. Codex marketplace and Kimi regi
 files additionally remember whether Ultra created the registry itself, so an empty
 registry that existed before installation is retained.
 
+ZCode publishes one managed local marketplace whose nested plugin is activated through
+the host's documented `plugins.dirs` configuration. Install preserves unrelated ZCode
+configuration, and uninstall removes only Ultra's exact directory entry and restores
+the pre-install `plugins.enabled` value when that value has not since been changed by
+the owner.
+
 ## Activation
 
 Owner-invoked Skills activate only through the host's explicit Skill surface.

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -1,6 +1,6 @@
 # Runtime compatibility matrix
 
-Ultra Builder Pro adapts one fourteen-Skill, five-hook contract to five native hosts.
+Ultra Builder Pro adapts one fourteen-Skill, five-hook contract to six native hosts.
 This document records the differences that belong in adapters rather than shared
 Skills.
 
@@ -13,6 +13,7 @@ Skills.
 | OpenCode | `<config>/.ultra-builder-pro` plus `<config>/plugins/ultra-builder-pro.js` | managed `<config>/skills/<name>` | native JS events call shared Python scripts |
 | Kimi Code | `<config>/plugins/managed/ultra-builder-pro` plus `installed.json` | nested `skills/<name>` | `hooks/adapters/kimi.py` |
 | Grok Build | `<GROK_HOME>/.ubp/plugin-sources/ultra-builder-pro` | nested `skills/<name>` | `hooks/adapters/grok.py` |
+| ZCode | `~/.zcode/cli/plugins/marketplaces/ultra-builder-pro/plugin` plus managed local marketplace and `plugins.dirs` entry | nested `skills/<name>` | `hooks/adapters/zcode.py` |
 
 Every host receives the same eight owner workflows, five model disciplines, and one
 router. Codex alone needs generated `agents/openai.yaml` files to express display data
@@ -27,12 +28,13 @@ and implicit-invocation policy; those are host metadata, not custom agents.
 | OpenCode | `${XDG_CONFIG_HOME:-~/.config}/opencode` | `<cwd>/.opencode` | `OPENCODE_CONFIG_DIR` or `OPENCODE_CONFIG` |
 | Kimi Code | `~/.kimi-code` | no project plugin scope | `KIMI_CODE_HOME` |
 | Grok Build | `~/.grok` | no project plugin scope | `GROK_HOME` |
+| ZCode | `~/.zcode` | no project plugin scope | adapter `ZCODE_HOME` override |
 
 An explicit `--config-dir` wins over all defaults and becomes the home for any
 host-owned sidecar as well. This rule makes isolated installation tests trustworthy.
 With multiple selected runtimes, the CLI passes `<config-dir>/<runtime>` to each adapter
 instead of merging incompatible host layouts.
-Kimi and Grok currently expose user-scoped plugin installation only. `--local` rejects
+Kimi, Grok, and ZCode currently expose user-scoped plugin installation only. `--local` rejects
 them before mutating another host; an explicit `--config-dir` remains available for an
 isolated user-scope installation test.
 
@@ -50,17 +52,19 @@ Kimi receives its native equivalent. Codex receives
 source frontmatter and native discovery, but its current Skill schema has no equivalent
 owner/model routing bit: all fourteen Skills remain discoverable and their descriptions
 guide model selection. Ultra does not add a semantic interception hook to imitate a
-host feature OpenCode does not expose.
+host feature OpenCode does not expose. ZCode likewise discovers all plugin Skills and
+relies on their portable descriptions plus the Change-scoped execution grant rather
+than a fabricated routing flag.
 
 ## Hook compatibility
 
-| Hook | Claude | Codex | OpenCode | Kimi | Grok |
-|---|---:|---:|---:|---:|---:|
-| session context | yes | normalized | native bridge | normalized to message | executed; host stdout limits apply |
-| mid-workflow recall | yes | handles `apply_patch` | native bridge | normalized | executed |
-| compact context | pre/start | pre/post | native compact event | pre/post | pre-compact |
-| post-edit observation | Write/Edit | Write/Edit/`apply_patch` | write/edit/patch | Write/Edit | Write/Edit/patch |
-| dangerous command guard | Bash advisory/deny | Bash advisory/deny | bash advisory/deny | Bash advisory/deny | Bash allow/deny mapping |
+| Hook | Claude | Codex | OpenCode | Kimi | Grok | ZCode |
+|---|---:|---:|---:|---:|---:|---:|
+| session context | yes | normalized | native bridge | normalized to message | executed; host stdout limits apply | normalized |
+| mid-workflow recall | yes | handles `apply_patch` | native bridge | normalized | executed | handles `ApplyPatch` aliases |
+| compact context | pre/start | pre/post | native compact event | pre/post | pre-compact | `SessionStart: compact` |
+| post-edit observation | Write/Edit | Write/Edit/`apply_patch` | write/edit/patch | Write/Edit | Write/Edit/patch | Write/Edit/ApplyPatch |
+| dangerous command guard | Bash advisory/deny | Bash advisory/deny | bash advisory/deny | Bash advisory/deny | Bash allow/deny mapping | Bash advisory/deny |
 
 All hooks share the same `.ultra/` idle guard. Wire adapters normalize payload and
 output fields only; they do not change semantic policy. Codex installation health and
@@ -81,14 +85,101 @@ until the user reviews and trusts the current definition, so Doctor reports
 - Kimi prompt mode with a launch-only read or write agent profile that exposes only
   file tools and no Bash, web, MCP, Skills or subagents;
 - Grok single-turn mode with `read-only` or `workspace` OS sandbox, structured output,
-  no memory, web search or subagents.
+  no memory, web search or subagents, and a twelve-turn ceiling;
+- ZCode headless prompt mode with native `plan` or `edit`; the current CLI accepts the
+  camel-case `--disallowedTools` surface used to deny Bash, web, subagents, and (in
+  read-only mode) write tools. The launcher's timeout remains the execution bound.
+
+ZCode 0.16.3 advertises `--max-turns`, `--allowed-tools`, and `--settings` in help but
+rejects them at the live root parser. Ultra therefore does not pass those flags. ZCode
+headless delegation also requires an explicit CLI model provider; desktop provider
+state is not silently copied into `~/.zcode/cli/config.json` because provider choice and
+credentials remain owner-controlled.
+
+On macOS, the shared host profile uses
+`/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs` when that App-bundled CLI
+exists, then falls back to `zcode` on `PATH`. `UBP_DELEGATE_ZCODE_BIN` remains an explicit
+test or operator override; the normal source-to-ZCode path does not require it.
+
+**ZCode transport maturity is `experimental`** (recorded in
+`adapters/_shared/host-profile.cjs`): the App-bundled CLI is a verified-local
+surface — it exists, launches, and passed the 2026-08-14 conformance drills — but
+the provider publishes no headless CLI, SDK, A2A, or ZCode Protocol stability
+contract. Promotion to `supported` requires both official documentation and a
+full recovery drill; a binary's existence, working help, or zero exit status is
+never sufficient. The other five delegate transports are documented and locally
+verified through the same launcher. The maturity is live-enforced, not just
+recorded: `delegate run --to zcode` refuses to launch without the explicit
+`--ack-experimental` flag, prints a stderr warning, and stamps
+`transport_maturity`, the exact `transport_surface` wording, and
+`experimental_ack: true` onto the receipt, worker spec, and every terminal
+result (including failure, cancellation, and timeout), so no delegation record
+can present an internal CLI run as the documented ZCode Desktop interactive
+surface. The documented interactive primary path for ZCode is the Desktop task
+surface itself, not this headless transport.
+
+### ZCode Desktop Workspace Memory (post-turn host effect)
+
+ZCode Desktop ships an optional Workspace Memory feature that extracts project
+memory after a completed turn into provider-local files under
+`~/.zcode/cli/memories/projects/<project>/memory`. Corrected facts
+(2026-08-17):
+
+- the feature is operator-controlled through the documented Workspace Memory
+  setting (`memoryEnabled` in `~/.zcode/v2/setting.json`); it is not always
+  default-off — it was observed enabled on this machine, and a fresh task
+  inherits the operator's current selection;
+- `memoryEnabled=false` is the single effective master gate: the App runtime
+  injects `memory:{enabled:false}`, and every recall, root access, and
+  post-turn extraction path resolves through one enabled-root resolver that
+  returns no root while it is false. The logged `memoryExtractionEnabled` and
+  `memoryUse` values are absent-key, disable-only defaults, not independent
+  owner-facing gates;
+- the extracted files are ordinary local files outside the repository that the
+  operator can browse and clear directly; they are non-authoritative and
+  non-portable — never Git content, never shared authority, never Ultra
+  evidence;
+- when the feature is enabled, the post-turn extraction is a Host external
+  effect: an owner-authorized transfer must allow it in the OFFER `effects`
+  and disclose it in the RESULT `external_effects`
+  (`skills/ultra-change/references/primary-transfer.md`); a strict
+  zero-external-effect pass requires a fresh task with the master setting off
+  plus an independent reviewer postflight;
+- Ultra never parses or mutates the provider setting.
+
+The accepted r3 design document's section 7.1 local-memory snapshot
+("local-only, default-off, cannot be browsed or cleared") is superseded by the
+current documented UI and the observed runtime behavior above; the frozen
+design bytes stay unedited.
 
 The launcher accepts no external-effect authority. It binds instruction, permission and
 output-schema digests, a clean Git worktree, allowed write roots, actual changed paths,
 strict result schema, timeout and cancellation. Empty roots select read-only mode. The
 model returns structured output and never authors the receipt. Host-native permissions
 are the execution boundary; the primary host still inspects and integrates the isolated
-diff.
+diff. The launcher embeds the digest-bound packet in the prompt because OpenCode's
+correct `external_directory: deny` policy prevents reading packet paths beside the
+worktree. Codex receives a native-schema-compatible projection; the launcher separately
+enforces non-empty strings, normalized unique paths, exact fields, and the observed diff.
+
+### Authenticated delegation conformance — 2026-08-14
+
+One clean, read-only seeded repository was used to exercise the current launcher against
+all six installed CLIs. Claude Code, Codex, OpenCode, Kimi Code, and ZCode each produced
+a validated `finished` result with an empty diff and found the seeded consequential
+defect. Grok Build 1.0.3 exited zero but repeatedly emitted truncated or malformed
+structured output; the launcher correctly published `failed/missing_result` and did not
+count partial text as evidence. This is a current host-result conformance ceiling, not a
+permission bypass or a semantic review result.
+
+ZCode was also exercised as the source host: one ZCode session invoked
+`ubp delegate run --to claude`, waited for the terminal artifact, and reported Claude's
+digest-bound read-only result without changing the worktree. Separately, one bounded
+ZCode Autonomy Envelope completed Plan, Plan review, TDD, task review, Test, and aggregate
+review for one task, then stopped before ungranted delivery and Git effects. Exact
+fixtures, session boundaries, checks, and residual risks are recorded in
+`docs/evals/adversarial-review-2026-08-14.md` and
+`docs/evals/zcode-automation-2026-08-14.md`.
 
 ## Lifecycle verification
 
@@ -96,7 +187,9 @@ Each adapter must pass isolated install, doctor, reinstall, and uninstall tests.
 global doctor additionally asks the native host where supported, but never repairs or
 installs. Codex still performs native registration under `--config-dir`; its host process
 inherits the same isolated `HOME` and `CODEX_HOME`. Grok native registration is skipped
-only in explicit isolated test mode. Lifecycle tests also require the isolated config
+only in explicit isolated test mode. ZCode uses its documented inline-plugin directory
+configuration for immediate activation while also publishing an importable local
+marketplace; real global Doctor verifies the native plugin inventory. Lifecycle tests also require the isolated config
 and fake HOME to contain zero children after uninstall, while separate ownership tests
 prove that pre-existing empty Codex and Kimi registries survive.
 

package/docs/SKILL-AUTHORING.md

@@ -25,7 +25,8 @@ description: What this produces and the concrete situations that trigger it.
 ---
 ```
 
-Adapters generate Claude/Grok/Kimi invocation flags and Codex `agents/openai.yaml`.
+Adapters generate Claude/Grok/Kimi invocation flags, Codex `agents/openai.yaml`, and
+ZCode-native plugin metadata.
 Do not put host paths, dependency declarations, plugin policy, or release history in
 source frontmatter.
 
@@ -72,7 +73,7 @@ wholesale into project authority.
 ## Language and host neutrality
 
 Model-facing Skills, references, scripts, comments, and identifiers are English.
-Shared Skills never mention `.claude`, `.codex`, `.opencode`, `.kimi`, `.grok`, or a
+Shared Skills never mention `.claude`, `.codex`, `.opencode`, `.kimi`, `.grok`, `.zcode`, or a
 host-only question surface. Use “host-native question surface” and put the translation
 in the adapter.
 
@@ -92,7 +93,7 @@ For every changed Skill:
 
 1. run the Skill Creator validator;
 2. resolve every relative reference in the source and installed artifact;
-3. verify its role metadata on all five hosts;
+3. verify its role metadata on all six hosts;
 4. test the accepted workflow with representative valid and adversarial inputs;
 5. confirm no retired runtime vocabulary or host-specific path entered portable text.