ultra-builder-pro-cli 5.0.0 → 6.0.0

package/adapters/zcode.js

@@ -1,375 +0,0 @@
-'use strict';
-
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-
-const {
-  copyHooks,
-  copySkills,
-  inspectPlugin,
-  markManaged,
-  publishManagedTrees,
-  removeManaged,
-  writePluginProvenance,
-} = require('./_shared/plugin-core.cjs');
-const {
-  captureAbsent,
-  ensureDir,
-  isManaged,
-  managedMetadata,
-  pruneCreatedEmpty,
-  removeTree,
-  writeAtomic,
-} = require('./_shared/file-ops.cjs');
-const { zcodeBinary } = require('./_shared/host-profile.cjs');
-
-const PLUGIN_NAME = 'ultra-builder-pro';
-const INLINE_PLUGIN_ID = `${PLUGIN_NAME}@inline`;
-
-function resolveTarget(ctx = {}) {
-  if (ctx.configDir) return path.resolve(ctx.configDir);
-  const configured = ctx.zcodeHome || ctx.env?.ZCODE_HOME || process.env.ZCODE_HOME;
-  return configured ? path.resolve(configured) : path.join(ctx.homeDir || os.homedir(), '.zcode');
-}
-
-function resolveCliRoot(ctx = {}) {
-  return path.join(resolveTarget(ctx), 'cli');
-}
-
-function resolveConfigFile(ctx = {}) {
-  return path.join(resolveCliRoot(ctx), 'config.json');
-}
-
-function resolveMarketplaceRoot(ctx = {}) {
-  return path.join(resolveCliRoot(ctx), 'plugins', 'marketplaces', PLUGIN_NAME);
-}
-
-function resolveMarketplaceFile(ctx = {}) {
-  return path.join(resolveMarketplaceRoot(ctx), 'marketplace.json');
-}
-
-function resolvePluginRoot(ctx = {}) {
-  return path.join(resolveMarketplaceRoot(ctx), 'plugin');
-}
-
-function resolveRepoRoot(ctx = {}) {
-  return ctx.repoRoot || path.resolve(__dirname, '..');
-}
-
-function assertPluginScope(ctx = {}) {
-  if (ctx.scope === 'local' && !ctx.configDir) {
-    throw new Error('ZCode plugins are user-scoped; use global scope or an isolated configDir');
-  }
-}
-
-function hookProcess(name) {
-  return {
-    type: 'process',
-    command: 'python3',
-    args: [`\${ZCODE_PLUGIN_ROOT}/hooks/adapters/zcode.py`, name],
-    timeoutMs: 10000,
-  };
-}
-
-function buildHooksManifest() {
-  return {
-    hooks: {
-      SessionStart: [
-        { matcher: 'startup|resume|clear', hooks: [hookProcess('session_context.py')] },
-        { matcher: 'compact', hooks: [hookProcess('compact_context.py')] },
-      ],
-      PreToolUse: [
-        { matcher: 'Write|Edit|ApplyPatch|Grep', hooks: [hookProcess('mid_workflow_recall.py')] },
-        { matcher: 'Bash', hooks: [hookProcess('block_dangerous_commands.py')] },
-      ],
-      PostToolUse: [
-        { matcher: 'Write|Edit|ApplyPatch', hooks: [hookProcess('post_edit_guard.py')] },
-      ],
-    },
-  };
-}
-
-function loadConfig(file) {
-  if (!fs.existsSync(file)) return {};
-  const value = JSON.parse(fs.readFileSync(file, 'utf8'));
-  if (!value || Array.isArray(value) || typeof value !== 'object') {
-    throw new Error(`invalid ZCode config: ${file}`);
-  }
-  if (value.plugins !== undefined && (
-    !value.plugins || Array.isArray(value.plugins) || typeof value.plugins !== 'object'
-  )) throw new Error(`invalid ZCode plugins config: ${file}`);
-  if (value.plugins?.dirs !== undefined && (
-    !Array.isArray(value.plugins.dirs)
-    || !value.plugins.dirs.every((entry) => typeof entry === 'string' && entry)
-  )) throw new Error(`invalid ZCode plugins.dirs config: ${file}`);
-  if (value.plugins?.enabled !== undefined && typeof value.plugins.enabled !== 'boolean') {
-    throw new Error(`invalid ZCode plugins.enabled config: ${file}`);
-  }
-  return value;
-}
-
-function configOwnership(file, pluginRoot) {
-  const exists = fs.existsSync(file);
-  const config = loadConfig(file);
-  const plugins = config.plugins;
-  return {
-    file_created: !exists,
-    plugins_created: plugins === undefined,
-    enabled_created: plugins === undefined || !Object.hasOwn(plugins, 'enabled'),
-    enabled_previous: plugins?.enabled,
-    dirs_created: plugins === undefined || !Object.hasOwn(plugins, 'dirs'),
-    dir_preexisting: Array.isArray(plugins?.dirs) && plugins.dirs.includes(pluginRoot),
-  };
-}
-
-function registeredConfig(config, pluginRoot) {
-  const plugins = config.plugins ? { ...config.plugins } : {};
-  const dirs = Array.isArray(plugins.dirs) ? [...plugins.dirs] : [];
-  if (!dirs.includes(pluginRoot)) dirs.push(pluginRoot);
-  plugins.enabled = true;
-  plugins.dirs = dirs;
-  return { ...config, plugins };
-}
-
-function unregisteredConfig(config, pluginRoot, ownership) {
-  if (!config.plugins || Array.isArray(config.plugins) || typeof config.plugins !== 'object') {
-    throw new Error('cannot unregister Ultra from an invalid ZCode plugins config');
-  }
-  const next = { ...config, plugins: { ...config.plugins } };
-  if (!ownership.dir_preexisting && Array.isArray(next.plugins.dirs)) {
-    next.plugins.dirs = next.plugins.dirs.filter((entry) => entry !== pluginRoot);
-  }
-  if (ownership.dirs_created && next.plugins.dirs?.length === 0) delete next.plugins.dirs;
-
-  if (ownership.enabled_created) {
-    if (next.plugins.enabled === true) delete next.plugins.enabled;
-  } else if (next.plugins.enabled === true && ownership.enabled_previous !== true) {
-    next.plugins.enabled = ownership.enabled_previous;
-  }
-  if (ownership.plugins_created && Object.keys(next.plugins).length === 0) delete next.plugins;
-  return next;
-}
-
-function buildStaging(repoRoot, staging, publishedRoot) {
-  const plugin = path.join(staging, 'plugin');
-  const skills = copySkills({ runtime: 'zcode', repoRoot, skillRoot: path.join(plugin, 'skills') });
-  copyHooks({
-    runtime: 'zcode', repoRoot, hookRoot: path.join(plugin, 'hooks'),
-    hooksManifest: buildHooksManifest(),
-  });
-  const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
-  writeAtomic(path.join(plugin, '.zcode-plugin', 'plugin.json'), `${JSON.stringify({
-    name: PLUGIN_NAME,
-    version: pkg.version,
-    description: 'File-first Ultra Builder Pro workflows for ZCode.',
-    author: { name: pkg.author },
-    homepage: pkg.homepage,
-    repository: pkg.repository?.url || pkg.repository,
-    license: pkg.license,
-    skills: './skills',
-    hooks: './hooks/hooks.json',
-  }, null, 2)}\n`);
-  writeAtomic(path.join(staging, 'marketplace.json'), `${JSON.stringify({
-    name: PLUGIN_NAME,
-    plugins: [{
-      name: PLUGIN_NAME,
-      version: pkg.version,
-      description: 'File-first Ultra Builder Pro workflows for ZCode.',
-      source: './plugin',
-    }],
-  }, null, 2)}\n`);
-  markManaged(plugin, { adapter: 'zcode', plugin: PLUGIN_NAME, version: pkg.version });
-  writePluginProvenance({
-    adapter: 'zcode', repoRoot, stagingRoot: plugin, publishedRoot,
-    contracts: {
-      plugin_manifest: { root: 'plugin', path: '.zcode-plugin/plugin.json' },
-      hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
-      hook_adapter: { root: 'plugin', path: 'hooks/adapters/zcode.py' },
-    },
-  });
-  return { skills };
-}
-
-function shouldRunHostCli(ctx = {}) {
-  if (typeof ctx.runHostCli === 'boolean') return ctx.runHostCli;
-  return ctx.scope === 'global' && !ctx.configDir;
-}
-
-function zcodeCommand(ctx, args) {
-  const selected = ctx.zcodeBin || process.env.ZCODE_BIN || zcodeBinary();
-  const command = selected.endsWith('.cjs') || selected.endsWith('.js') ? process.execPath : selected;
-  const argv = command === selected ? args : [selected, ...args];
-  const result = spawnSync(command, argv, {
-    encoding: 'utf8',
-    timeout: ctx.hostCliTimeoutMs || 30000,
-    env: { ...process.env, HOME: ctx.homeDir || os.homedir() },
-  });
-  if (result.error) throw result.error;
-  if (result.status !== 0) {
-    throw new Error((result.stderr || result.stdout || '').trim() || `zcode ${args.join(' ')} failed`);
-  }
-  return result.stdout;
-}
-
-function nativePlugin(ctx) {
-  const value = JSON.parse(zcodeCommand(ctx, ['plugins', 'list', '--json']));
-  if (!Array.isArray(value.plugins)) throw new Error('zcode plugins list --json must include plugins');
-  return value.plugins.find((entry) => entry?.id === INLINE_PLUGIN_ID) || null;
-}
-
-function install(ctx = {}) {
-  assertPluginScope(ctx);
-  const target = resolveMarketplaceRoot(ctx);
-  const pluginRoot = resolvePluginRoot(ctx);
-  const configRoot = resolveTarget(ctx);
-  const configFile = resolveConfigFile(ctx);
-  const repoRoot = resolveRepoRoot(ctx);
-  if (fs.existsSync(target) && !isManaged(target)) {
-    throw new Error(`refusing to replace unmanaged ZCode marketplace: ${target}`);
-  }
-  const previousMetadata = managedMetadata(target) || {};
-  const cleanupAbsent = previousMetadata.cleanup_absent || captureAbsent(configRoot, [
-    '.', 'cli', path.join('cli', 'plugins'), path.join('cli', 'plugins', 'marketplaces'),
-    path.join('cli', 'config.json'),
-  ]);
-  const ownership = previousMetadata.config_ownership || configOwnership(configFile, pluginRoot);
-  const configExisted = fs.existsSync(configFile);
-  const configBefore = configExisted ? fs.readFileSync(configFile, 'utf8') : null;
-  const nextConfig = registeredConfig(loadConfig(configFile), pluginRoot);
-  ensureDir(path.dirname(target));
-  const staging = fs.mkdtempSync(path.join(path.dirname(target), `.${PLUGIN_NAME}-staging-`));
-  const recovery = fs.existsSync(target)
-    ? fs.mkdtempSync(path.join(path.dirname(target), `.${PLUGIN_NAME}-recovery-`))
-    : null;
-  if (recovery) fs.cpSync(target, recovery, { recursive: true });
-  try {
-    const copied = buildStaging(repoRoot, staging, pluginRoot);
-    markManaged(staging, {
-      adapter: 'zcode', plugin: PLUGIN_NAME,
-      cleanup_absent: cleanupAbsent,
-      config_ownership: ownership,
-    });
-    publishManagedTrees([{ source: staging, target, label: 'ZCode marketplace' }]);
-    writeAtomic(configFile, `${JSON.stringify(nextConfig, null, 2)}\n`);
-    if (shouldRunHostCli(ctx)) {
-      const plugin = nativePlugin(ctx);
-      if (!plugin || plugin.enabled !== true || path.resolve(plugin.rootPath) !== path.resolve(pluginRoot)) {
-        throw new Error('ZCode did not activate the managed Ultra inline plugin');
-      }
-    }
-    if (recovery) removeTree(recovery);
-    return {
-      target,
-      marketplaceRoot: target,
-      marketplaceFile: resolveMarketplaceFile(ctx),
-      pluginRoot,
-      skillRoot: path.join(pluginRoot, 'skills'),
-      hookRoot: path.join(pluginRoot, 'hooks'),
-      configFile,
-      copied,
-    };
-  } catch (error) {
-    const rollback = [];
-    try {
-      if (configExisted) writeAtomic(configFile, configBefore);
-      else if (fs.existsSync(configFile)) fs.unlinkSync(configFile);
-    } catch (rollbackError) { rollback.push(rollbackError); }
-    try {
-      if (fs.existsSync(target)) removeTree(target);
-      if (recovery) fs.renameSync(recovery, target);
-    } catch (rollbackError) { rollback.push(rollbackError); }
-    if (fs.existsSync(staging)) removeTree(staging);
-    pruneCreatedEmpty(configRoot, cleanupAbsent);
-    if (rollback.length) throw new AggregateError([error, ...rollback], 'ZCode install and rollback failed');
-    throw error;
-  }
-}
-
-function doctor(ctx = {}) {
-  assertPluginScope(ctx);
-  const pluginRoot = resolvePluginRoot(ctx);
-  const report = inspectPlugin({
-    adapter: 'zcode', repoRoot: resolveRepoRoot(ctx), pluginRoot,
-    skillRoot: path.join(pluginRoot, 'skills'), hookRoot: path.join(pluginRoot, 'hooks'),
-    manifestFile: path.join(pluginRoot, '.zcode-plugin', 'plugin.json'),
-  });
-  let marketplaceValid = false;
-  try {
-    const marketplace = JSON.parse(fs.readFileSync(resolveMarketplaceFile(ctx), 'utf8'));
-    marketplaceValid = marketplace?.name === PLUGIN_NAME
-      && Array.isArray(marketplace.plugins)
-      && marketplace.plugins.some((entry) => entry?.name === PLUGIN_NAME && entry?.source === './plugin');
-  } catch {}
-  report.checks.marketplace = { status: marketplaceValid ? 'pass' : 'fail' };
-  if (!marketplaceValid) report.issues.push({ code: 'ZCODE_MARKETPLACE_INVALID' });
-
-  let registered = false;
-  try {
-    const config = loadConfig(resolveConfigFile(ctx));
-    registered = config.plugins?.enabled !== false
-      && Array.isArray(config.plugins?.dirs)
-      && config.plugins.dirs.includes(pluginRoot);
-  } catch {}
-  report.checks.registration = { status: registered ? 'pass' : 'fail' };
-  if (!registered) report.issues.push({ code: 'ZCODE_PLUGIN_NOT_REGISTERED' });
-
-  if (shouldRunHostCli(ctx)) {
-    let discovered = false;
-    try {
-      const plugin = nativePlugin(ctx);
-      discovered = !!plugin && plugin.enabled === true
-        && path.resolve(plugin.rootPath) === path.resolve(pluginRoot)
-        && plugin.skillCount === 14;
-    } catch {}
-    report.checks.native_registry = { status: discovered ? 'pass' : 'fail' };
-    if (!discovered) report.issues.push({ code: 'ZCODE_NATIVE_DISCOVERY_FAILED' });
-  }
-  report.status = report.issues.length === 0 ? 'healthy' : 'degraded';
-  return report;
-}
-
-function uninstall(ctx = {}) {
-  assertPluginScope(ctx);
-  const target = resolveMarketplaceRoot(ctx);
-  const pluginRoot = resolvePluginRoot(ctx);
-  const configRoot = resolveTarget(ctx);
-  const metadata = managedMetadata(target) || {};
-  const ownership = metadata.config_ownership;
-  const cleanupAbsent = metadata.cleanup_absent || [];
-  if (fs.existsSync(target) && !ownership) {
-    throw new Error(`missing ZCode config ownership in ${target}`);
-  }
-  const configFile = resolveConfigFile(ctx);
-  const configBefore = fs.existsSync(configFile) ? fs.readFileSync(configFile, 'utf8') : null;
-  if (ownership) {
-    const next = unregisteredConfig(loadConfig(configFile), pluginRoot, ownership);
-    if (ownership.file_created && Object.keys(next).length === 0) fs.unlinkSync(configFile);
-    else writeAtomic(configFile, `${JSON.stringify(next, null, 2)}\n`);
-  }
-  try {
-    const removed = removeManaged(target, 'ZCode marketplace');
-    const cleaned = pruneCreatedEmpty(configRoot, cleanupAbsent);
-    return { target, marketplaceRoot: target, pluginRoot, removed: { marketplace: removed }, cleaned };
-  } catch (error) {
-    if (configBefore !== null) writeAtomic(configFile, configBefore);
-    throw error;
-  }
-}
-
-module.exports = {
-  name: 'zcode',
-  PLUGIN_NAME,
-  INLINE_PLUGIN_ID,
-  buildHooksManifest,
-  resolveTarget,
-  resolveCliRoot,
-  resolveConfigFile,
-  resolveMarketplaceRoot,
-  resolveMarketplaceFile,
-  resolvePluginRoot,
-  install,
-  doctor,
-  uninstall,
-};

package/bin/delegate-worker.cjs

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-// Compatibility surface for callers that still resolve the historical path.
-require('../skills/ultra-delegate/scripts/delegate-worker.cjs');

package/bin/delegate.cjs

@@ -1,5 +0,0 @@
-'use strict';
-
-// Compatibility surface for one release cycle. The installed Skill owns the
-// implementation used by both `ubp delegate` and direct Skill invocation.
-module.exports = require('../skills/ultra-delegate/scripts/delegate.cjs');

package/docs/ARCHITECTURE.md

@@ -1,274 +0,0 @@
-# Ultra Builder Pro architecture
-
-Ultra Builder Pro is a file-first workflow asset package for six coding-agent hosts,
-implementing the provider-neutral **Ultra Core Protocol**: cognitive alignment,
-per-fact authority, explicit work-package grants, typed evidence, bounded effects,
-checkpoints, and terminal review convergence — carried entirely by Skills,
-owner-readable files, Git, host adapters, and optional Hooks. The host model owns
-meaning and strategy; Ultra mechanizes only portable prompts, observable files,
-bounded effects, and recovery.
-
-## System boundary
-
-```text
-Owner request
-    │ explicit selection or verified execution grant (session-local / durable)
-    ▼
-Public Skill mode ───────── stops at the next owner boundary
-    │
-    ├── model-invoked disciplines (reasoning methods)
-    ├── source / tests / runtime / primary documentation
-    └── canonical project files + Git
-             │
-             ├── optional five hooks (derived context and effect guard)
-             └── optional delegation (ACP-first driver or CLI fallback)
-```
-
-Ultra has no semantic runtime supervisor. Reading the files is the recovery protocol;
-editing the files is the state transition; Git is the journal and rollback mechanism.
-
-## Four planes
-
-### Method plane
-
-Fourteen `skills/*/SKILL.md` files carry the workflow:
-
-- eight owner-invoked workflows;
-- five model-invoked reusable disciplines;
-- one read-only router.
-
-The exact allowlists and per-mode invocation map live in
-`adapters/_shared/runtime-assets.cjs`. Public modes are `explicit-entry`,
-`grant-continuable`, or read-only `router`. Under an accepted Change-scoped Execution
-Grant, change-scoped Research, same-Change reconciliation, Plan, Dev, Test, and Deliver
-reconciliation may be selected by the model only while `session-local` activation is
-live or a fresh Agent has stably verified a `durable work-package` grant. Host metadata
-does not preserve session activation: a fresh session, Host switch, or compaction stops
-`session-local` continuation until the Owner activates it again. Host metadata
-is a coarse discovery bit; each loaded Skill rechecks its mode, Change, effects, and
-material checkpoints. Stored text alone grants nothing, and neither mode grants Change
-intake/acceptance, primary transfer, Deliver finalization or archive; every external
-effect still stops. The derived Route Card makes each boundary owner-visible without
-becoming workflow state or authority. The router itself remains owner-invoked; public
-Skills derive their own cards from the shared Route Contract instead of invoking it.
-
-Research's seventeen references are workflow-owned semantic lenses. Its optional
-`wayfinding.md` maps a multi-lens question without becoming a new Skill or authority.
-The reusable mechanics remain separate: Grilling owns the interaction loop, Think owns
-one consequential decision, and Domain Modeling owns vocabulary promotion.
-
-### Authority plane
-
-Canonical semantic authority consists of:
-
-- `.ultra/project-brief.md` for raw owner intake and the initial outline;
-- `.ultra/north-star.md` for the accepted direction, outcome or metric decision, hard
-  constraints, and exclusions established by Research;
-- `.ultra/specs/*.md` for product, architecture, discovery, and research distillate;
-- `.ultra/changes/{active,archive,abandoned}/<id>/intent.md` for bounded outcomes, North
-  Star Trace, and a required Execution Grant (`session-local` and inert without current-
-  session activation by default) with one stable id across directory moves;
-- append-only `.ultra/tasks.json` v2 rows carrying `change_id` and the sole task status,
-  plus each task's status-free `context_file`;
-- `.ultra/decisions/*.md`, typed `.ultra/evidence/`, `.ultra/test-report.json`, and research;
-- repository-root `CONTEXT.md` for ubiquitous language;
-- Git for revision identity, history, moves, diff, and rollback.
-
-Each semantic fact has one canonical representation. A summary can point to authority,
-but cannot become a second authority merely because it is convenient to read.
-Task status therefore lives only in `.ultra/tasks.json`. Legacy context Status and
-Complexity fields are migration observations; readers report them and the ledger wins.
-Current task evidence uses `ultra-task-evidence-v2`, whose typed command, inspection,
-owner-judgment, and external-observation entries retain distinct authorities. Only the
-owner can supply an owner-judgment result. Structural validators report exact facts and
-never decide semantic acceptance. Command and external evidence store a safe
-repository-relative raw ref plus `raw_evidence_sha256`; structural validation does not
-open that ref. Dev binds bounded stable ordinary non-symlink receipt bytes before record
-publication, while Test, Status, and Deliver recheck the raw digest and then the exact
-record `evidence_digest`. The product-worktree digest excludes `.ultra/evidence/**`, so
-evidence publication cannot invalidate the freshness value it records.
-
-One primary host model writes this authority in a worktree. Native subagents are
-read-only sensors; delegated CLIs write isolated non-`.ultra` roots and return receipts.
-Sequential Changes share the ledger by stable id, while current readers filter by the
-one unique active Change. This keeps concurrency explicit in Git instead of adding a
-semantic lock service or workflow engine. When the canonical writer itself changes
-Agent, an owner-granted primary transfer moves the role exclusively — a derived
-OFFER binding canonical refs/hashes, HEAD, and worktree digest; a receiver ACK that
-is ready only on full stable-read match; sole-writer execution; a frozen terminal
-RESULT — with receipts under `.ultra/.runtime/handoffs/` kept as rebuildable
-observations and delegated workers never acquiring canonical write authority
-(`skills/ultra-change/references/primary-transfer.md`).
-
-Autonomous coding uses the host's existing model-tool loop, one canonical writer, and
-the same task/evidence/review files. Ultra adds no persisted route position: budgets are
-hard ceilings, while the model interprets whether acceptance and stop conditions hold.
-
-### Adaptation plane
-
-`adapters/*.js` translates the shared package into native host surfaces:
-
-- skill frontmatter and Codex `agents/openai.yaml` policy;
-- plugin manifests and host registries;
-- hook command paths and wire normalization;
-- atomic managed installation, provenance, doctor, and uninstall behavior.
-
-`adapters/_shared/plugin-core.cjs` owns the common copy, managed publication, and
-delegation-runner inventory and driver-reporting checks. The canonical six-host
-non-interactive profile lives
-beside the installed launcher at `skills/ultra-delegate/scripts/host-profile.cjs`;
-`adapters/_shared/host-profile.cjs` is a one-release compatibility re-export. Adapters
-never rewrite workflow meaning.
-
-### Why the old Agents are Skill assets now
-
-The retired custom-agent files did not own product authority. They contained reusable
-review lenses, debugging, test execution, and review coordination. v0.26 keeps those
-methods on the common surface all six hosts actually share:
-
-- six review workers map to `ultra-review/references/{code,design,errors,tests,spec,comments}.md`;
-- review coordination and the former general code reviewer map to the parent
-  `ultra-review` workflow, immutable Worker Packet, and shared schemas;
-- debugging maps to `ultra-dev/references/debugging.md`;
-- test execution maps to `ultra-tdd/references/test-execution.md`.
-
-The references are copied as assets of their parent Skill. Native bounded subagents are
-an execution option, not an installed Ultra authority. When a host has no equivalent,
-the parent model runs the same references sequentially.
-
-### Observation plane
-
-Five hooks read canonical files and emit bounded context or observations. Their output
-under `.ultra/.runtime/` and `.ultra/progress/`, and review artifacts under
-`.ultra/reviews/`, are derived rather than semantic authority. A current strict review
-session contains `WORKER-PACKET.json`, `ADMISSION.json`, every selected specialist
-artifact, and `SUMMARY.json`; retain it until aggregate Test and Deliver have both consumed it
-successfully, then it may be garbage-collected. Premature loss requires a fresh Review
-and Test; never reconstruct the old receipt. The dangerous-command hook is the only
-hard effect guard; it classifies a small named destructive set and provides an
-exact-command authorization repair.
-
-ACP `session/update` telemetry follows the same rule. The Skill-local driver stores only
-bounded redacted event metadata under the delegation directory, drops hidden thought
-chunks and raw tool payloads, and exposes the latest safe observation through status.
-The journal, session id, capability report, permission decision, and stop reason are all
-disposable execution observations; none can select a route or establish completion.
-Additive protected-branch publication remains advisory when portable host wiring cannot
-project a trusted owner-approval receipt; history rewrites and branch deletion remain
-guarded.
-
-## Completion and recovery
-
-An operation is complete only when its accepted user outcome works through the real
-public seam. Route/schema/UI shells, local unit green, or an edited ledger status are not
-end-to-end evidence by themselves. A task remains `in_progress` through its task review;
-only after blocking findings are resolved or authoritatively dispositioned and affected
-v2 evidence is refreshed may the primary model write `completed` to the ledger.
-
-Every user Skill starts by reading:
-
-1. zero or one active `change_id`, diagnosing more than one;
-2. `.ultra/tasks.json` tasks whose `change_id` matches it, treating that ledger as the
-   sole task-status authority;
-3. the matching frontier task's `context_file` and closing `## Resume Note`;
-4. `CONTEXT.md` and relevant decisions;
-5. the active Change, specifications, current v2 task evidence and retained task-review
-   provenance, and current Git state.
-
-That same sequence works after compaction, a fresh process, disabled hooks, or a host
-change. Compact snapshots can accelerate recovery but never outrank the source files.
-
-## Integration defence
-
-Three independent Skills protect the vertical path:
-
-1. `ultra-plan` records model-selected technical seams, asks the owner only for a
-   public-contract or material trade-off, and rejects horizontal feature tasks.
-2. `ultra-dev` records six separate evidence dimensions, including real persistence,
-   default-on behavior, vertical execution, and spec trace.
-3. `ultra-test` searches exports for real consumers, exercises the primary flow, and
-   binds the result to Change id, task ids, intent, HEAD, product-worktree digest, exact
-   raw receipt SHA-256 values, and the containing task-evidence digests.
-
-These are independent sensors. None rewrites a finding into product truth.
-
-## Delegation
-
-The canonical installed `ultra-delegate/scripts/delegate.cjs` validates all paths inside
-the selected project, reads a bounded instruction and permission JSON, probes the
-Skill-local Host profile, and starts the Skill-local background worker. One
-`AgentExecutionDriver` boundary selects stable ACP v1 stdio only after the exact Host's
-versioned conformance row passes with a non-empty evidence reference and the declared
-executable and bounded candidate-identity probes succeed; otherwise the same packet
-runs through `CliDriver` and records the fallback reason. Capability inspection uses
-local version commands only and does not start a provider task. The
-one-release `ubp delegate` surface imports those same functions and owns no forked
-behavior. Declared writable roots must already exist inside the delegated
-worktree; no readable-root or external-effect grant can widen the host's native
-sandbox. Empty writable roots select native read-only mode. The model returns a
-schema-constrained final response; `AcpDriver` reconstructs only agent-message text as
-that same validator input, while ACP stop reasons remain observations. It accepts a
-bounded set of creation-time session metadata that some agents emit before
-`session/new` resolves, then validates every buffered session identity before exposing
-derived events; early message/tool content and unbounded startup traffic fail closed.
-The Node worker validates `finished`, `blocked`, or
-`failed` and atomically publishes `result.json` beside the instruction. The model never
-writes its own receipt; stdout, stderr, native final output, and the launch receipt
-remain diagnostic files.
-
-`ULTRA_DELEGATE_FORCE_CLI=1` is a per-run recovery seam that selects the same bounded
-CLI validator path and records `acp_forced_cli`; it does not erase conformance evidence.
-An `acp_auth_required` error from `session/new` before `session/prompt` also selects that
-already-bound CLI path once. The terminal result retains redacted ACP fallback metadata;
-no post-prompt or other ACP failure is automatically retried.
-ZCode uses the independently installed, source-pinned `zcode-acp` bridge plus the
-digest-bound 0.16.5 runtime-preferences patch to translate stable ACP v1 to the installed
-Desktop runtime. Ultra ships only the patch, neither the bridge binary nor App bytes.
-The profile verifies an Ultra build marker on that bridge plus the exact installed
-runtime version before ACP selection.
-The Host/runtime is ZCode Desktop while provider identity remains owner-controlled; the
-verified local receipt uses domestic BigModel rather than international Z.AI OAuth. The
-headless ZCode transport remains explicitly experimental even after conformance.
-
-The instruction binds the active `change_id` and one of three semantic scopes: task
-execution/continuation, scoped Research evidence, or aggregate Change
-review/verification. Only task execution requires a task row. The read-only Research
-and aggregate scopes preserve the same process boundary without inventing work merely
-to make delegation reachable.
-
-Delegation does not grant authority or copy semantic state into another store. The
-worker reads and writes the same repository files in the specified worktree.
-
-## Optional Graph/Loop control plane
-
-Long-running, multi-Agent, cross-Host work can justify an external coordination
-layer (for example a LoopX-style kernel) that owns goal/todo identity, claims and
-leases, attention queues, quotas, human-gate records, handoff receipts, and
-append-only run/effect observations. Such a layer is **optional and currently not
-integrated**: no adapter, dependency, daemon, or scaffold for one ships in this
-package, and the Ultra Core Protocol remains fully usable on files plus Git with
-every optional layer absent.
-
-The boundary is fixed regardless of future integration: the control plane may
-observe and coordinate — it may never own the North Star, product meaning,
-acceptance, semantic severity, architecture or scope decisions, a "quality is
-sufficient" verdict, or the authority to start an unauthorized Agent. Enabling it
-requires a real coordination problem the owner accepts (multi-session parallel
-frontiers, claim/write conflicts, long external waits, explicit quotas, cross-Host
-handoff) plus an adapter with a live consumer; deleting or disabling it must always
-leave canonical project truth and human recovery intact.
-
-## Deliberate absences
-
-The architecture does not include:
-
-- an Ultra database or SQLite dependency;
-- an MCP server or tool protocol;
-- a workflow state machine or semantic validator;
-- a background orchestration daemon;
-- a resident ACP service, ACP session store, or semantic route ledger;
-- command or custom-agent prompt projections;
-- general memory, code graph, browser, deployment, or framework packages.
-
-Adding one of these requires a reproduced failure that the file-first path cannot
-repair, a named authority boundary, and a primary-path regression test.