ultra-builder-pro-cli 5.0.0 → 6.0.0

package/docs/PHILOSOPHY.md

@@ -1,261 +0,0 @@
-# Ultra Builder PHILOSOPHY (v0.26)
-
-**Authority**: This document defines the harness design philosophy. Every hook, Skill, template,
-and CLI behavior must be justifiable by these principles. Conflicts → cite the principle, not the
-rule.
-
-**Provenance**: Goals 1–4 and Commandments C1–C5 are carried forward unchanged in substance from
-Ultra Builder Pro v7.0, where they were derived from a 2026-04-30 system audit of real failures.
-Do not weaken any of them without a reproduced failure case.
-
-**Why exactly four goals and five commandments** — the counts are not sacred, the derivation
-rules are:
-
-- A **goal** is a class of systemic failure that has actually recurred, stated positively.
-  A fifth goal requires naming a fifth recurring failure class that none of these four covers.
-- A **commandment** is a rule the model must cite to resolve a semantic conflict. If the model
-  will never face a moment where it needs to invoke the rule, the rule is not a commandment —
-  it is either a code invariant (enforce and test it) or dead weight (delete it).
-
-By that second rule, "stay silent in repositories that never opted in" is **not** a commandment:
-it is `if not exists('.ultra'): exit(0)`, a mechanical invariant the model never reasons about.
-It lives in `docs/PLUGIN-ISOLATION-CONTRACT.md` and is verified by test, not by citation.
-
----
-
-## 4 Core Goals
-
-The harness exists to serve these — every constraint derives its legitimacy from contributing to
-one or more.
-
-1. **Intent Fidelity** — what the user said they wanted is what gets built. No silent
-   reinterpretation, no scope creep, no convenient shortcuts that drift from the original ask.
-2. **Long-term Evolvability** — iteration #5 is as easy as iteration #1. Cognitive debt cannot
-   accumulate; spec / task / code / doc must stay coherent.
-3. **Production-Ready** — real persistence, real tests, real integration. No in-memory facades,
-   no `default off` to dodge integration, no `it.skip` to dodge failures.
-4. **Cognitive Coherence** — agent and user share the same picture of "what is currently true."
-   Spec changes propagate. Doc rot is detected. Orphan code surfaces.
-
----
-
-## 5 Commandments
-
-### C1 — Goal-Always-Present
-
-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
-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.
-
-### C2 — Enabling > Defensive
-
-Every prohibition ships with a runnable alternative. Prohibitions without an enabling path force
-agents to find loopholes (rename `mock` to `stub`, etc.). The cheaper path must be the right path.
-
-> **Test**: scan every prohibition in every Skill; each must reference a template that exists
-> under that Skill's `references/templates/` and can be copied as-is. The templates are rules,
-> so they ship with the package rather than being copied into each project.
-
-### C3 — Sensors not Blockers
-
-Hooks emit signal; agents and users decide. Block only the **truly irreversible or
-privileged destructive** effects for which the hook has an exact repair:
-
-- Funds transfer / on-chain transactions
-- Protected-branch history rewrite or deletion
-- `DROP` / `TRUNCATE`
-- Hardcoded secret commit
-- Arbitrary code execution driven by user input
-
-Additive protected-branch publication and database migrations are advisory: the former
-remains recoverable through Git and the portable hook cannot receive every host's
-trusted approval receipt; the latter is not mechanically classifiable as reversible or
-irreversible. The work stands, the signal is delivered, and the agent proceeds inside
-the owner's authorized frame.
-
-> **Why this is absolute**: hard final gates and hard pre-commit gates each produced the same
-> over-correction loop in v7 — the agent weakened tests to escape the gate and drifted from the
-> spec. A gate that can be escaped by damaging the work is worse than no gate.
-
-> **Test**: count blocking outputs across all hooks; they must map 1:1 to the irreversible list.
-
-### C4 — Incremental Validation
-
-The agent always knows "how far from done." Each edit updates `.ultra/progress/<task-id>.json`
-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.
-> This is the only permitted end-of-flow audit.
-
-> **Test**: at any point in a task, reading `.ultra/progress/<task-id>.json` answers "what's left."
-
-### C5 — Bounded Autonomy
-
-Autonomy is defined by goals, not rules. Inside the boundary the agent picks freely; crossing the
-boundary surfaces to the user.
-
-- **Inside**: choosing libraries, naming, file layout, internal abstractions, decomposition
-  strategy, evidence interpretation, prioritization, final expression
-- **Crossing**: weakening test assertions, modifying spec to match implementation, default-off
-  feature flags, in-memory replacing real persistence, scope reduction, external or irreversible
-  effects
-
-**Which decisions reach the owner.** Inside/Crossing above sorts actions. Read from the owner's
-side, the same boundary sorts decisions into three:
-
-| Type | Definition | Handling |
-|---|---|---|
-| taste | no objectively correct answer; only the owner's preference settles it | always ask |
-| crossing | objectively decidable, but the consequence is irreversible | always ask |
-| everything else | has an objective answer, or is cheap to reverse | decide and proceed; asking is the error |
-
-How much lands in the third row is a function of how sharp the north star is. With constraints
-that can veto a concrete decision, most execution-time questions are answered by reading them.
-With vague ones, "does this cross a boundary?" cannot be decided at all, so every question
-degrades into taste and reaches the owner. **Interrupt frequency measures the north star, not
-the work.** Frequent interruptions mean going back to sharpen constraints, not asking faster.
-
-**Boundaries grow; they do not change.** Adding a hard constraint or a non-goal mid-flight is
-routine and needs no permission — the frame got sharper and no prior promise broke. Editing or
-deleting one is a REDUCTION under the test below. This is what makes iteration five cheaper than
-iteration one: the frame accumulates, and the share of decisions the model settles alone rises
-with it.
-
-**Operational test for spec changes.** When implementation and spec disagree, classify the change
-before touching the spec. Do not classify by intent — classify by asking one question that can be
-checked against the file:
-
-> **Does every commitment the spec already made still hold after this change?**
-
-| Answer | Classification | Action |
-|---|---|---|
-| Yes, and it now commits to more | EXPANSION | write it, log it |
-| Yes, the commitment is unchanged but stated correctly | CORRECTION | write it, log it |
-| **No — at least one prior commitment no longer holds** | **REDUCTION** | **stop and ask the owner** |
-
-The classification follows from the outcome, never from the reason. A well-argued rationale does
-not convert a REDUCTION into a CORRECTION; the rationale goes into the question put to the owner.
-This is the mechanism by which specs shrink silently, so it is the one place the model must not
-be allowed to self-certify.
-
-**Not to be confused with Planning Posture.** A Change's `## Planning Posture` uses
-EXPAND / SELECTIVE / HOLD / REDUCE to say how much work to plan right now. That is a scope
-decision about the future and is freely reversible. The classification above is about the past:
-whether a promise already made still holds. `REDUCE` the plan is routine; a `REDUCTION` of
-commitments stops the work and goes to the owner.
-
-> **Test**: any boundary-crossing action must trigger an owner question, an active task
-> `## Change Log` entry, or an accepted `.ultra/decisions/<id>.md`.
-
----
-
-## When commandments conflict
-
-Goals override commandments. Commandments override rules. Cite the higher level:
-
-- `C2 overrides rule "no mock" → use the testcontainer template`
-- `goal Intent-Fidelity overrides C5 → ask the owner before reducing scope`
-
----
-
-## Modifying this file
-
-Changes to PHILOSOPHY require:
-
-1. A concrete failure case the change addresses, linked in the active Change or evidence
-2. An impact assessment on every dependent hook and Skill
-3. Migration of any dependent constraint
-
-PHILOSOPHY is the only file whose changes propagate to every prohibition, template reference, and
-Skill instruction. Do not touch it casually.
-
----
-
-## Contract Table
-
-> Each row is a hardcoded contract between two parts of the system. Changing one side **without**
-> the other was the v7 audit's #1 cause of silently broken Goal-Always-Present injection. Update
-> this table BEFORE editing either side.
-
-| Consumer | Reads | Source of truth | Failure mode if drifted |
-|---|---|---|---|
-| `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 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` | 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 |
-
-### Maintenance protocol
-
-Before editing any row's source of truth:
-
-1. Find every consumer in this table
-2. Update consumer and source together in one change
-3. Re-run the end-to-end injection check
-4. Update this table if the contract surface changed

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -1,315 +0,0 @@
-# Runtime compatibility matrix
-
-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.
-
-## Installed surface
-
-| Host | Managed plugin or bundle | Skills | Hook bridge |
-|---|---|---:|---|
-| Claude Code | `<config>/skills/ultra-builder-pro` | nested `skills/<name>` | direct Python commands in `hooks/hooks.json` |
-| Codex | `<home>/plugins/ultra-builder-pro` plus personal marketplace entry | nested `skills/<name>` with `agents/openai.yaml` | `hooks/adapters/codex.py` |
-| 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
-and implicit-invocation policy; those are host metadata, not custom agents.
-
-## Scope resolution
-
-| Host | Global default | Local default | Environment override |
-|---|---|---|---|
-| Claude Code | `~/.claude` | `<cwd>/.claude` | `CLAUDE_CONFIG_DIR` |
-| Codex | `~/.codex` for config; `~/plugins` and `~/.agents` for sidecars | `<cwd>/.codex` plus home-scoped plugin surface | `CODEX_HOME` |
-| 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, 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.
-
-## Invocation policy
-
-| Invocation class | Owner can route directly | Model can select implicitly |
-|---|---:|---:|
-| `explicit-entry` public mode | yes | no |
-| `grant-continuable` public mode | yes | only under a valid Execution Grant covering that mode |
-| five `model-discipline` Skills | no | as an internal method of a covered workflow |
-| `ultra-status` `router` modes | yes | no; other Skills derive their cards directly from the shared contract |
-
-The canonical per-mode map is `PUBLIC_SKILL_INVOCATION_MODES` in
-`adapters/_shared/runtime-assets.cjs`. Init and Delegate are explicit-only. Research has
-explicit `baseline` and grant-continuable `change-scoped`; Change has explicit
-intake/evidence/acceptance and grant-continuable same-Change reconciliation; Deliver has
-grant-continuable reconciliation and explicit finalization. Plan, Dev, and Test modes
-are grant-continuable. Every public mode remains directly owner-invocable.
-
-Claude and Grok receive `user-invocable` / `disable-model-invocation` frontmatter.
-Kimi receives its native equivalent. Codex receives
-`policy.allow_implicit_invocation` in `agents/openai.yaml`. Those Hosts expose only a
-coarse Skill-level bit, so a Skill with any grant-continuable mode is discoverable to the
-model; the loaded Skill must still verify the selected mode, same active `change_id`,
-grant, effects, and material checkpoints. In particular, the coarse bit does not permit
-baseline Research, Change intake/acceptance, or Deliver finalization.
-
-OpenCode uses portable 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 plus the same in-Skill guard guide selection. Ultra
-does not add a semantic interception hook to imitate a Host feature OpenCode does not
-expose. ZCode likewise discovers all plugin Skills and relies on their portable
-descriptions and runtime guard rather than a fabricated routing flag.
-
-## Hook compatibility
-
-| 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
-hook activation are distinct: Codex skips newly installed non-managed plugin hooks
-until the user reviews and trusts the current definition, so Doctor reports
-`hook_activation: user_review_required` without pretending the hook already ran.
-
-## Agent execution driver selection
-
-| Host | ACP candidate observed locally | Versioned conformance | 5.0 active driver | Fallback reason |
-|---|---|---|---|---|
-| Claude Code | pinned `@agentclientprotocol/claude-agent-acp@0.70.0` stdio adapter | PASS, real provider receipt | ACP when `npx` exists | `acp_command_unavailable` when absent |
-| Codex | pinned `@agentclientprotocol/codex-acp@1.6.2` stdio adapter | PASS, real provider receipt | ACP when `npx` exists | `acp_command_unavailable` when absent |
-| OpenCode | native `opencode acp` stdio server | PASS, real provider receipt | ACP when executable exists | `acp_command_unavailable` when absent |
-| Kimi Code | documented [`kimi acp`](https://moonshotai.github.io/kimi-code/en/reference/kimi-acp.html) stdio server | PASS, real provider receipt | ACP when executable exists | `acp_command_unavailable` when absent |
-| Grok Build | documented [`grok agent stdio`](https://docs.x.ai/build/cli/headless-scripting) | PASS, real provider receipt | ACP when executable exists | `acp_command_unavailable` when absent |
-| ZCode | source-pinned `zcode-acp` v0.1.0 plus digest-bound 0.16.5 patch translating to installed `app-server` | PASS, domestic BigModel provider receipt | ACP when bridge exists and `--ack-experimental` is supplied | `acp_command_unavailable` when absent |
-
-Selection is ACP-first only after the exact Host row is `passed` and names a non-empty
-evidence reference: stable protocol v1, stdio, executable availability, read-only,
-bounded write, permission denial,
-cancellation/no-orphan, cwd/diff parity, result parity, and credential/event redaction
-must all hold. Static capability inspection never starts the provider. A candidate,
-binary, help output, SDK version, or successful fake-agent suite alone cannot promote a
-Host. The stable wire contract follows the official
-[ACP v1 schema](https://github.com/agentclientprotocol/agent-client-protocol/blob/main/schema/v1/schema.json);
-unstable v2 features are outside the 5.0 required path.
-
-All Driver receipts and terminal results expose the selected driver, ACP capability,
-and fallback reason. Doctor reports the same facts separately from installation health.
-`AcpDriver` stores a bounded redacted `events.jsonl`, never raw protocol messages or
-hidden reasoning. Status re-projects every displayed latest event through that fixed
-safe shape and treats a corrupted journal as unavailable. `CliDriver` bounds
-stdout/stderr while retaining the output tail so the existing exact Ultra result
-extractor remains compatible.
-
-During `session/new`, `AcpDriver` may temporarily buffer only the bounded creation-time
-metadata updates emitted by some conforming agents. It rejects message/tool content,
-wrong session identities, more than 32 updates, or more than 256 KiB before the response;
-accepted metadata is exposed only after every buffered `sessionId` matches the created
-session. `ULTRA_DELEGATE_FORCE_CLI=1` is an explicit per-run recovery seam: it selects
-the same bounded CLI result path and records `acp_forced_cli` without changing the
-Host's stored conformance status.
-
-## CLI fallback argv
-
-`skills/ultra-delegate/scripts/host-profile.cjs` records current non-interactive
-invocation for:
-
-- Claude print mode with structured output and an explicit file-tool allowlist; read-only
-  uses `plan`, while bounded write uses `acceptEdits` without Bash or web tools;
-- Codex ephemeral `exec` with user config ignored, project rules preserved, native
-  `read-only` or `workspace-write`, network disabled, and an output schema;
-- OpenCode `run --auto` only after an inline config explicitly denies Bash, web,
-  subagents, external directories, Skills and undeclared edit roots;
-- 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, 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.
-
-The installed ZCode 0.16.5 runtime 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. Host/runtime identity and provider identity remain separate: the verified
-local path uses ZCode Desktop with the Owner's domestic BigModel Coding Plan provider,
-not international Z.AI OAuth. Ultra's package does not silently copy Desktop credentials;
-the user controls the provider entry in `~/.zcode/cli/config.json`.
-
-On macOS, the Skill-local 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.
-
-The ACP bridge is independently installed from `jpalmae/zcode-acp` v0.1.0 at source
-revision `42fe149d4b501469343c01f23ba3801832306d53`, then patched by the shipped
-`zcode-acp-0.1.0-zcode-0.16.5.patch` with SHA-256
-`174dfd0feafe84320556a84b5ae08b10e44c5515fea4992fd1d58af54cee4e3d`. The patch
-answers the `session/requestRuntimePreferences` server request introduced by ZCode
-0.16.5 before and after session creation. The pinned source plus patch passes the locked
-Rust tests, reproduced RED, patched fake App-server E2E, release build, and real provider
-session before use. It stamps the bridge as
-`zcode-acp 0.1.0+ultra.zcode.0.16.5`; selection requires that marker and an installed
-runtime reporting `0.16.5`. Ultra records both source inputs and ships only the patch; it
-redistributes neither the bridge binary nor any ZCode Desktop bytes.
-
-**ZCode transport maturity is `experimental`** (recorded in
-`skills/ultra-delegate/scripts/host-profile.cjs`): the App-bundled CLI is a verified-local
-surface — it exists, launches, and passed the 2026-08-26 conformance drill — 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.
-
-## Installed delegation runner
-
-Every managed plugin contains `ultra-delegate/scripts/delegate.cjs`, its worker, the
-canonical Host profile, all three driver modules, and the Kimi launch-only profiles.
-The loaded Skill resolves
-that directory and invokes Node directly, so a clean plugin install does not require a
-persisted Ultra package binary on `PATH` and never uses `npx` to rediscover Ultra.
-The source-pinned Claude and Codex ACP adapters may themselves run through their exact
-`npx --yes <package>@<version>` profiles. Doctor
-reports `delegation_runner`, `acp_capability`, `agent_execution_driver`, its fallback
-reason, and ZCode maturity separately from Skill discovery and Hooks. The package
-`ubp delegate` surface remains a thin one-release compatibility wrapper around the same
-functions; receipts and recovery commands point to the canonical Skill-local entrypoint.
-
-### 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. 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
-
-Each adapter must pass isolated install, doctor, reinstall, and uninstall tests. Real
-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. 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.
-
-## Authenticated cross-host continuation evidence
-
-On 2026-08-03, one deliberately narrow task was run in an isolated Git repository to
-test the product's central recovery claim with real authenticated models. This was a
-continuation drill, not a full project workflow or a delegation receipt test.
-
-Both hosts used globally installed artifacts from the same clean source candidate:
-
-- source commit: `c473a248bde2afce77591f2ba382246d420b5c72`;
-- worktree digest: `e83bdcbe2905cf02cb06cb0219127f6ce0400484331a6e9fc95622bbe24b44bd`;
-- Doctor: Claude healthy with 83 assets and zero issues; Codex healthy with 99 assets
-  and zero issues, with optional hooks still `user_review_required`.
-
-The seed repository had one passing smoke test, one pending task, one mapped Change
-acceptance ID, and seed HEAD `cf27d62aeeae353e0650413de6d9a118b89a0406`.
-
-| Phase | Execution boundary | Observed result |
-|---|---|---|
-| Claude | One print-mode call, `acceptEdits`, no persistent session, empty MCP config, explicit file and local-test tools, USD 1.00 cap | Exit 0 at USD 0.741367 with zero web requests. It changed only the task ledger/context, added `test/slug.test.cjs`, and allowed the hook to write disposable progress. `src/slug.cjs` and completion evidence remained untouched. The task test exited 1 with actual `hello,-world!` versus expected `hello-world`; both task surfaces read `in_progress`, and the Resume Note named the exact next action. |
-| Codex | One ephemeral `workspace-write` call with sandbox network disabled and no conversation from Claude | Exit 0. It found and read the installed `ultra-dev` Skill, recovered the single task from Git and `.ultra/`, reproduced the same red, changed only the intended implementation, then passed the task test 1/1 and `npm test` 2/2. It wrote the three-command canonical evidence record and logs, completed both task status surfaces, and filled Completion and the final Resume Note. |
-| Independent check | Local commands after both model calls | `node --test test/slug.test.cjs` passed 1/1, `npm test` passed 2/2, `git diff --check` passed, and a structural check confirmed one completed task, six evidence dimensions, three existing command-log references, and matching ledger/context state. |
-
-The Codex process emitted non-blocking diagnostics for an older local model-cache
-schema and an unauthenticated user-config MCP startup. No MCP result was consumed and
-no external effect occurred; all task actions used local file and shell tools. This
-means the drill proves file-backed Claude-to-Codex continuation even while Codex hooks
-remain untrusted, but it does not claim that arbitrary user configuration starts
-without unrelated host diagnostics.
-
-The result establishes one real end-to-end example of cross-host resume without a
-shared conversation, database, MCP authority, daemon, or generated prompt projection.
-It does not establish output quality for every model, host, repository, or task shape.
-Task-level `ultra-review` and commits were intentionally excluded from the drill so the
-two host calls tested only the handoff boundary.
-
-Two older `.ultra` evidence snapshots originally named the completed WIP by its former
-path. The current-path artifact contract requires every reference to resolve in the
-checkout, so those two references now point here while their 2026-08-01 status and
-limitations remain explicitly historical. The original WIP is still recoverable from
-their pinned source commit `3f99189bc68697262cd90444685ac2d4857139c4` with
-`git show`; the live `docs/wip/` directory contains no unfinished document.