ultra-builder-pro-cli 0.26.2 → 5.0.0

package/skills/ultra-delegate/scripts/host-profile.cjs

@@ -0,0 +1,267 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const KIMI_PROFILE_ROOT = path.join(__dirname, 'delegate-profiles');
+const ZCODE_BUNDLED_CLI = '/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs';
+const CLAUDE_ACP_PACKAGE = '@agentclientprotocol/claude-agent-acp@0.70.0';
+const CODEX_ACP_PACKAGE = '@agentclientprotocol/codex-acp@1.6.2';
+const ZCODE_ACP_SOURCE = Object.freeze({
+  repository: 'https://github.com/jpalmae/zcode-acp',
+  version: '0.1.0',
+  commit: '42fe149d4b501469343c01f23ba3801832306d53',
+  buildMarker: 'zcode-acp 0.1.0+ultra.zcode.0.16.5',
+  runtimeVersion: '0.16.5',
+  patch: Object.freeze({
+    path: 'skills/ultra-delegate/patches/zcode-acp-0.1.0-zcode-0.16.5.patch',
+    sha256: '174dfd0feafe84320556a84b5ae08b10e44c5515fea4992fd1d58af54cee4e3d',
+    compatibility: 'ZCode CLI 0.16.5 runtime-preferences handshake',
+  }),
+});
+
+// The ZCode app-bundled CLI is a verified-local surface, not a provider
+// stability promise: official documentation plus a full recovery drill must
+// both hold before any transport may claim 'supported'.
+const TRANSPORT_MATURITY = Object.freeze({
+  claude: 'documented+verified',
+  codex: 'documented+verified',
+  opencode: 'documented+verified',
+  kimi: 'documented+verified',
+  grok: 'documented+verified',
+  zcode: 'experimental',
+});
+
+const ACP_CONFORMANCE = Object.freeze({
+  claude: Object.freeze({
+    status: 'passed',
+    evidence: 'docs/evals/ultra-5-0-live-acp-conformance.md#claude-code',
+    receiptSha256: '9b1d88cbd5e5b66a56e0cf19f34e7f2107f9e4b8fde9d80b9eadcdfc8f4a25e3',
+  }),
+  codex: Object.freeze({
+    status: 'passed',
+    evidence: 'docs/evals/ultra-5-0-live-acp-conformance.md#codex',
+    receiptSha256: 'e82287609397807fb6968dff104d7f6569499b53c77be6a186aa33939a4c629e',
+  }),
+  opencode: Object.freeze({
+    status: 'passed',
+    evidence: 'docs/evals/ultra-5-0-live-acp-conformance.md#opencode',
+    receiptSha256: '3575b148f6feb8c9f1472add705390e6d47b87be080403ec7006b66a29f7873b',
+  }),
+  kimi: Object.freeze({
+    status: 'passed',
+    evidence: 'docs/evals/ultra-5-0-live-acp-conformance.md#kimi-code',
+    receiptSha256: '30d8adec2877f80fadf0b20c3cb7fa6b732dea3598d7484c143f9835770301fe',
+  }),
+  grok: Object.freeze({
+    status: 'passed',
+    evidence: 'docs/evals/ultra-5-0-live-acp-conformance.md#grok-build',
+    receiptSha256: '370eeae12d63443188d519825ed8040fd8bba9b27fddb82e499d9cb590f4a33d',
+  }),
+  zcode: Object.freeze({
+    status: 'passed',
+    evidence: 'docs/evals/ultra-5-0-live-acp-conformance.md#zcode',
+    receiptSha256: '156080f88ed84a013fb26d93e5138230732d2ef0e2b5b10a7c3deb501d3548e9',
+  }),
+});
+
+function zcodeBinary({ platform = process.platform, exists = fs.existsSync } = {}) {
+  return platform === 'darwin' && exists(ZCODE_BUNDLED_CLI)
+    ? ZCODE_BUNDLED_CLI
+    : 'zcode';
+}
+
+function opencodePermission(writableRoots) {
+  const edit = { '*': 'deny' };
+  for (const root of writableRoots) {
+    if (root === '.') edit['*'] = 'allow';
+    else edit[`${root}/**`] = 'allow';
+  }
+  return JSON.stringify({
+    share: 'disabled',
+    permission: {
+      '*': 'deny',
+      read: 'allow',
+      glob: 'allow',
+      grep: 'allow',
+      list: 'allow',
+      lsp: 'allow',
+      edit,
+      external_directory: 'deny',
+      bash: 'deny',
+      task: 'deny',
+      webfetch: 'deny',
+      websearch: 'deny',
+      question: 'deny',
+      skill: 'deny',
+    },
+  });
+}
+
+const PROFILES = Object.freeze({
+  claude: Object.freeze({
+    binary: 'claude',
+    acp: Object.freeze({
+      surface: `official ${CLAUDE_ACP_PACKAGE} stdio adapter`,
+      transport: 'stdio',
+      protocolVersions: [1],
+      conformance: ACP_CONFORMANCE.claude,
+      command: () => 'npx',
+      argv: () => ['--yes', CLAUDE_ACP_PACKAGE],
+    }),
+    delegateArgv: (prompt, _cwd, options) => [
+      '-p', prompt,
+      '--permission-mode', options.readOnly ? 'plan' : 'acceptEdits',
+      '--no-session-persistence',
+      '--output-format', 'json',
+      '--tools', options.readOnly ? 'Read,Grep,Glob' : 'Read,Write,Edit,Grep,Glob',
+    ],
+  }),
+  codex: Object.freeze({
+    binary: 'codex',
+    acp: Object.freeze({
+      surface: `official ${CODEX_ACP_PACKAGE} stdio adapter`,
+      transport: 'stdio',
+      protocolVersions: [1],
+      conformance: ACP_CONFORMANCE.codex,
+      command: () => 'npx',
+      argv: () => ['--yes', CODEX_ACP_PACKAGE],
+    }),
+    delegateArgv: (prompt, cwd, options) => [
+      'exec', '--ephemeral', '--ignore-user-config',
+      '--sandbox', options.readOnly ? 'read-only' : 'workspace-write',
+      '--cd', cwd,
+      '--config', 'sandbox_workspace_write.network_access=false',
+      '--output-schema', options.schemaFile,
+      '--output-last-message', options.hostOutput,
+      '--json', prompt,
+    ],
+  }),
+  opencode: Object.freeze({
+    binary: 'opencode',
+    acp: Object.freeze({
+      surface: 'native OpenCode ACP stdio server',
+      transport: 'stdio',
+      protocolVersions: [1],
+      conformance: ACP_CONFORMANCE.opencode,
+      command: ({ cliCommand }) => cliCommand,
+      argv: () => ['acp'],
+    }),
+    delegateArgv: (prompt, cwd) => [
+      'run', '--dir', cwd, '--format', 'json', '--auto', prompt,
+    ],
+    delegateEnv: (options) => ({
+      OPENCODE_CONFIG_CONTENT: opencodePermission(options.writableRoots),
+    }),
+  }),
+  kimi: Object.freeze({
+    binary: 'kimi',
+    supportsModelSelection: true,
+    acp: Object.freeze({
+      surface: 'Kimi Code ACP stdio server',
+      transport: 'stdio',
+      protocolVersions: [1],
+      conformance: ACP_CONFORMANCE.kimi,
+      command: ({ cliCommand }) => cliCommand,
+      argv: () => ['acp'],
+    }),
+    delegateArgv: (prompt, _cwd, options) => {
+      const args = ['-p', prompt, '--output-format', 'stream-json'];
+      if (options.model) args.push('--model', options.model);
+      args.push(
+        '--agent-file',
+        path.join(
+          KIMI_PROFILE_ROOT,
+          options.readOnly ? 'kimi-read-only.md' : 'kimi-write.md',
+        ),
+      );
+      return args;
+    },
+  }),
+  grok: Object.freeze({
+    binary: 'grok',
+    acp: Object.freeze({
+      surface: 'Grok agent stdio candidate',
+      transport: 'stdio',
+      protocolVersions: [1],
+      conformance: ACP_CONFORMANCE.grok,
+      command: ({ cliCommand }) => cliCommand,
+      argv: () => ['agent', 'stdio'],
+    }),
+    delegateArgv: (prompt, cwd, options) => [
+      '--cwd', cwd, '--single', prompt,
+      '--permission-mode', options.readOnly ? 'plan' : 'acceptEdits',
+      '--sandbox', options.readOnly ? 'read-only' : 'workspace',
+      '--no-memory', '--no-subagents', '--disable-web-search',
+      '--verbatim',
+      '--max-turns', '12',
+      '--output-format', 'json',
+    ],
+  }),
+  zcode: Object.freeze({
+    binary: zcodeBinary(),
+    installedRuntimeOnly: true,
+    acp: Object.freeze({
+      surface: `installed ZCode Desktop runtime through zcode-acp ${ZCODE_ACP_SOURCE.version}`,
+      transport: 'stdio',
+      protocolVersions: [1],
+      conformance: ACP_CONFORMANCE.zcode,
+      command: ({ env }) => env.ULTRA_ZCODE_ACP_COMMAND || 'zcode-acp',
+      argv: ({ cliCommand }) => ['--zcode-path', cliCommand, '--no-browser'],
+      identityProbes: ({ command, cliCommand }) => [
+        {
+          label: 'zcode_bridge',
+          command,
+          args: ['--version'],
+          expectedStdout: ZCODE_ACP_SOURCE.buildMarker,
+        },
+        {
+          label: 'zcode_runtime',
+          command: cliCommand.endsWith('.cjs') ? process.execPath : cliCommand,
+          args: cliCommand.endsWith('.cjs') ? [cliCommand, '--version'] : ['--version'],
+          expectedStdout: ZCODE_ACP_SOURCE.runtimeVersion,
+        },
+      ],
+    }),
+    delegateArgv: (prompt, cwd, options) => [
+      '--cwd', cwd,
+      '--mode', options.readOnly ? 'plan' : 'edit',
+      '--json', '--no-color',
+      '--disallowedTools', options.readOnly
+        ? 'Bash Write Edit ApplyPatch Agent WebFetch WebSearch'
+        : 'Bash Agent WebFetch WebSearch',
+      '--prompt', prompt,
+    ],
+  }),
+});
+
+function hostProfile(runtime) {
+  const profile = PROFILES[runtime];
+  if (!profile) throw new Error(`unsupported delegate host: ${runtime}`);
+  return { ...profile, transportMaturity: TRANSPORT_MATURITY[runtime] };
+}
+
+// The live delegate surface names honestly what a run actually used. The ZCode
+// headless transports are app-internal surfaces, never the documented ZCode
+// Desktop interactive primary path, so every receipt that records one says so.
+function transportSurface(runtime, binary = PROFILES[runtime] ? PROFILES[runtime].binary : undefined) {
+  if (runtime === 'zcode') {
+    const source = binary === ZCODE_BUNDLED_CLI ? 'the App-bundled headless CLI' : 'the zcode headless CLI on PATH';
+    return `${source} (experimental; not the documented ZCode Desktop interactive surface)`;
+  }
+  return 'documented non-interactive CLI';
+}
+
+module.exports = {
+  ACP_CONFORMANCE,
+  CLAUDE_ACP_PACKAGE,
+  CODEX_ACP_PACKAGE,
+  PROFILES,
+  TRANSPORT_MATURITY,
+  ZCODE_BUNDLED_CLI,
+  ZCODE_ACP_SOURCE,
+  hostProfile,
+  opencodePermission,
+  transportSurface,
+  zcodeBinary,
+};

package/skills/ultra-deliver/SKILL.md

@@ -1,26 +1,81 @@
 ---
 name: ultra-deliver
-description: Reconcile one Change whose matching tasks are complete, run aggregate review and refactoring, refresh release documentation, and archive the local workflow record. Use when the owner wants a delivery handoff or separately authorized release effects for the active Change.
+description: Reconcile one Change whose matching tasks are complete, run aggregate review and refactoring, and report the delivery handoff. Use when the owner wants delivery reconciliation and reporting, or — by current explicit owner invocation only — the separately gated finalization that writes delivery.md, fixes version and package posture, and archives the local workflow record.
 ---
 
 # Turn current evidence into a recoverable delivery handoff
 
 Delivery closes the local Change; readiness grants no commit, push, tag, publish, or deploy authority.
 
+## Route modes
+
+| Mode | Entry | Observable exit | Next |
+|---|---|---|---|
+| `reconcile` | Explicit invocation or a valid Execution Grant for a tested active Change | Intent, implementation, specifications, documentation, evidence, and report agree, or changed files make the exact stale evidence visible | Recommend `ultra-test/reaudit` after changes, otherwise recommend explicit `ultra-deliver/finalize` |
+| `finalize` | Current explicit owner invocation only | Fresh transport/evidence checks pass, version and package posture are owner-set, `delivery.md` is written, and the Change is locally archived | Report `idle` plus every separately authorized or unfinished release effect |
+
+Follow `../ultra-status/references/route-contract.md`. Show a Route Card at entry, after
+reconciliation, before the finalization checkpoint, and after archive or any stop.
+Grant-aware continuation ends with `reconcile`; no Host metadata bit, report, or grant
+turns `finalize` into an implicit mode.
+
 ## Before you start
 
-1. Resolve exactly one active `change_id`. Read `.ultra/tasks.json`; every matching task
-   must be complete. Read each `context_file`'s Completion and closing Resume Note.
-2. Read `CONTEXT.md`, relevant `.ultra/decisions/`, active Change intent and evidence.
-3. Read `.ultra/test-report.json`, then run the Test Skill's `worktree_digest.cjs` with
+1. If model-selected, verify the live execution grant in `../ultra-change/references/execution-grant.md` — a current session-local activation or a stably verified durable work-package grant; without either, stop. A model-selected Deliver run under that grant may reconcile, review, and report, and then MUST stop before finalization: its inputs, writes, and effects end at the report. Only a current explicit owner invocation of `ultra-deliver` may finalize — writing `delivery.md`, deciding the version decision and package posture, and archiving the stable Change id with `git mv` are owner-invocation-only in every grant mode, and a grant never covers them.
+2. Read `../ultra-change/references/change-contract.md` and apply its **Active Change
+   authority resolution** before reading any active `intent.md` or resolving a current
+   `change_id`. This workflow requires its one valid active authority; any zero result
+   or typed diagnostic stops before finalization input is read until the stated repair
+   or retry succeeds. Read `.ultra/tasks.json`; every matching task must be `completed`
+   in that sole task-status authority. Read each `context_file`'s Completion, Task
+   Review, and closing Resume Note. For every current Change task,
+   require current `ultra-task-evidence-v2` and task-review provenance under
+   `../ultra-plan/references/task-evidence-v2.md`, already consumed by the current Test
+   report. A legacy context Status or Complexity header and v1 evidence are migration
+   diagnostics only and cannot support current delivery.
+3. Read `CONTEXT.md`, relevant `.ultra/decisions/`, active Change intent and evidence.
+   Validate `.ultra/north-star.md`; resolve every recorded `FP-*`, `NS-*`, and `HC-*`
+   for the delivered Change, tasks, findings, and dispositions against that accepted
+   authority. Compare the active Change's recorded **North Star revision** and
+   **North Star digest** with the accepted file's revision and current Git blob digest. Any
+   missing ID or mismatch stops finalization and recommends explicit owner invocation of
+   `ultra-change` for reconciliation; delivery never silently rewrites the trace.
+4. Read `.ultra/test-report.json`, then run the Test Skill's `worktree_digest.cjs` with
    project root and `--change-id`. Require report `task_ids` for the current Change plus
-   matching `change_id`, `git_commit`, worktree digest, and intent digest; otherwise stop.
+   matching `change_id`, `git_commit`, worktree digest, intent digest, and review
+   `admission_digest`, `subject_digest`, and `summary_digest`; otherwise stop. Recheck
+   each projected task's declared review branch as recorded: strict-v4 items keep their
+   strict receipt and transport bindings, while `external-manual` items reverify their
+   receipt bytes and digest through the task-evidence sensor's
+   `--verify-external-receipt` mode and take the sensor's `--projection` output
+   verbatim — a strict SUMMARY never substitutes for an external receipt and neither
+   branch is rewritten into the other.
+   The product-worktree digest has one fixed boundary: it excludes `.ultra/evidence/**`,
+   whose command and external-observation entries bind raw bytes as
+   `raw_evidence_sha256` before stable exact record bytes are bound as `evidence_digest`
+   through the report's ordered `task_evidence` projection. For each projected record,
+   take every `raw_evidence_ref` to bounded stable repository-contained bytes from an
+   ordinary regular non-symlink file opened nonblocking and no-follow, with an 8 MiB
+   ceiling and path/descriptor identity checks around the read. Recompute
+   `raw_evidence_sha256` and require an exact match, then recompute the stable exact
+   `evidence.json` bytes as `evidence_digest` before comparing the projection. Recheck
+   the exact review receipts separately; never treat the product exclusion as permission
+   to ignore evidence drift or add another exclusion.
+   An intent digest changed by North Star reconciliation or any other intent edit always
+   requires a fresh `ultra-test` before Deliver can finalize, even if product bytes did
+   not change.
+5. Preserve every typed acceptance authority. The owner alone supplies the semantic
+   result for `owner-judgment`; Deliver may verify its cited source and freshness but no
+   model, command, digest, schema, or validator may replace it.
 
 ## Definition of done
 
 - Outcome, specs, tests, aggregate review, and every document match the actual diff.
 - Every changed export has a non-test consumer or a recorded owner disposition.
 - Every omitted stage is explicitly recorded with its evidence-based rationale.
+- Delivery explains whether evidence realizes the traced first principles and outcome,
+  and preserves contradictions or stale trace as findings instead of mirroring or
+  silently revising North Star prose.
 - Build and release checks have exact commands and real results.
 - The Change is archived with `git mv`, and rollback remains a normal Git operation.
 
@@ -28,6 +83,12 @@ Delivery closes the local Change; readiness grants no commit, push, tag, publish
 
 Follow `../ultra-review/SKILL.md` across the aggregate Change; refactor only observed
 duplication, coupling, or boundary defects. Rerun affected checks and refresh the report.
+After the aggregate review and the current Test report are consumed, Deliver does not
+refactor product source: it reconciles delivery artifacts and documentation only. A
+post-approval implementation issue routes as at most one new owner-approved Dev task
+for a P0/P1, or as recorded backlog and residual risk for P2/P3; an unbounded
+Test ↔ Deliver bounce is not a valid recovery path, and any re-entry through Test
+requires an explicit owner disposition.
 
 ## Reconcile the handoff
 
@@ -51,11 +112,33 @@ Delivery has two observable passes, not a hidden state machine:
    specifications, maintained documentation, or `intent.md`, stop after writing the
    reconciled files. The existing report is stale; recommend `ultra-test` and make no
    delivery or release claim.
-2. After an unchanged pass or fresh Test, recheck Change/task/HEAD/product/intent
-   identities. Apply the gate, run build and non-publishing package inspection, determine
-   version impact, and use `references/baseline-reconciliation.md` for canonical
-   `delivery.md`. Archive the Change. Excluded delivery metadata and the directory move
-   cannot self-invalidate the product digest; intent stays independently bound.
+2. After an unchanged pass or fresh Test, resolve the report's canonical
+   `review.summary_ref` as `<validated-summary-path>` and run the current strict transport
+   consumer against the current report:
+
+   `node <ultra-test-skill-dir>/scripts/validate_review_transport.cjs --summary <validated-summary-path> --report .ultra/test-report.json`
+
+   Require exit 0 and a JSON `"valid": true` field. This one existing consumer verifies
+   the exact
+   retained `ADMISSION.json` and `SUMMARY.json`, then binds the report's
+   `admission_digest`, `subject_digest`, and `summary_digest` to those bytes. A missing or
+   invalid receipt, summary, or binding makes the current Test claim `INCOMPLETE`: start
+   a fresh Review and Test. Do not write `delivery.md`, archive the Change, create a
+   release package, or make a delivery claim while that receipt evidence is missing or
+   invalid. Never use `--legacy-v4` for this current-session check; v3 and pre-admission
+   v4 are read-only historical evidence, not current Test or Deliver evidence.
+
+   After the transport succeeds, recheck Change/task/HEAD/product/intent identities.
+   Apply the gate, run build and non-publishing package inspection, determine version
+   impact, and use `references/baseline-reconciliation.md` for canonical `delivery.md`.
+   Archive the Change. Excluded delivery metadata and the directory move cannot
+   self-invalidate the product digest; intent stays independently bound. Retain the
+   review session through this successful Deliver consumption; only then may its derived
+   artifacts be garbage-collected.
+
+   Transport and task-evidence validators establish exact structural, identity,
+   provenance, and freshness facts only. Their success never means that the Change is
+   semantically accepted or that its outcome is ready to describe as delivered.
 
 Do not draft a success narrative around stale evidence. A current `passed: false`
 report may still reach finalization only after every finding has an explicit owner
@@ -100,8 +183,12 @@ Without release authority, stop after the recoverable local archive and report i
 
 ## References
 
+- `../ultra-change/references/change-contract.md` — canonical Active Change authority resolution.
 - `../ultra-review/SKILL.md` — read before aggregate review and refactoring.
+- `../ultra-plan/references/task-evidence-v2.md` — canonical current task evidence and task-review contract.
 - `../ultra-think/SKILL.md` — read when version or release posture is a consequential
   trade-off rather than an established repository rule.
 - `../ultra-think/references/autonomy-boundary.md` — read before scope or evidence shrinks.
+- `../ultra-change/references/execution-grant.md` — read only for grant-activated continuation.
+- `../ultra-status/references/route-contract.md` — owner-visible route, checkpoint, and recovery output.
 - `references/baseline-reconciliation.md` — exact `delivery.md` reconciliation contract.