ultra-builder-pro-cli 0.26.2 → 3.0.2

package/.ultra-template/contexts/TEMPLATE.md

@@ -1,10 +1,5 @@
 # Task {id}: {title}
 
-> **Status**: pending | **Priority**: {priority} | **Complexity**: {complexity}
-
-<!-- Status here and in tasks.json must always match. Both are written together, then both
-     are read back to confirm. A single-sided write breaks cross-host resume. -->
-
 ## Context
 
 **What**: [what to build or change]
@@ -17,30 +12,48 @@
 
 ## Implementation
 
-**Target Files**:
-- `path/to/file.ts` (create)
-- `path/to/existing.ts` (modify: description)
-
-**Layers touched**: [entry point / use case / domain / persistence — must be ≥2]
+**Layers touched**: [entry point / use case / domain / persistence]
 
 **Pattern**: [existing code to follow]
 
 **Tech Notes**: [framework or library specifics]
 
+## Planned Path Inventory
+
+`MODIFY`:
+
+- `path/to/existing.ts`
+
+`CREATE`:
+
+- `path/to/file.ts`
+
+Any later addition, removal, or rename in this inventory or the Public Seams below is
+plan-critical and requires a rebuilt Execution Packet plus owner reapproval before
+implementation continues.
+
+## Public Seams
+
+- `[entry point, schema, file contract, or other externally observable seam]`
+
+## Narrow Verification
+
+- `exact command for the smallest relevant contract suite`
+- `[inspection, owner record, or external observation required by the typed criteria]`
+
 ## Acceptance Criteria
 
-<!-- The verifiable definition of done. Read by mid_workflow_recall and session_context, and
-     injected into agent context — keep every line testable and keep noise out. -->
+<!-- The typed definition of done. Readers inject this section into agent context; keep
+     every criterion observable and keep noise out. The ledger is the sole Status source. -->
 
 **Change Acceptance IDs**: [`AC-1`, `AC-3`, or `none` for task-local-only work]
 
-- [ ] `exact test command`
-- [ ] Pass: [scenario 1]
-- [ ] Pass: [scenario 2]
-- [ ] Integration: [the one test proving this connects to its upstream/downstream boundary]
-
-<!-- Manual verification, deliberately outside the injected section:
-     curl -X POST localhost:3000/api/example -->
+| ID | Criterion | Verification type | Required evidence |
+|---|---|---|---|
+| A-01 | [observable criterion] | `command` | exact command, cwd, exit code, raw evidence ref, and freshness identity |
+| A-02 | [observable criterion] | `inspection` | source/path, observed fact, and revision |
+| A-03 | [owner decision when genuinely required] | `owner-judgment` | durable owner statement or explicit disposition |
+| A-04 | [external fact when genuinely required] | `external-observation` | provider, run id, timestamp, raw evidence ref, and observation |
 
 ## Definition of Drift
 
@@ -53,10 +66,17 @@
 
 **Source**: `.ultra/specs/product.md#section-id`
 
-**Hard Constraints**: [`HC-1`, `HC-3`, or `none` — the north-star constraints this
-task could plausibly violate. Read them before the first edit and again before
-marking complete. Crossing one stops the work and goes to the owner, however good
-the argument.]
+**First principles**: [`FP-1`, or every accepted principle this task relies on]
+
+**Serves**: [`NS-1`, or every accepted outcome this task causally advances]
+
+**Causal contribution**: [one task-local sentence connecting the planned seam to the
+listed outcome through the listed principles; reference IDs and do not copy North Star
+prose]
+
+**Hard constraints**: [`HC-1`, `HC-3`, or `none` — the accepted constraints this task
+could plausibly violate. Read them before the first edit and again before marking
+complete. Crossing one stops the work and goes to the owner, however good the argument.]
 
 **Decisions**: [relevant `.ultra/decisions/<id>.md` entries, or `none`]
 
@@ -77,18 +97,33 @@ the argument.]
 
 ## Resume Note
 
-<!-- The single most important line for cross-session and cross-host continuation.
-     Overwrite it whenever work pauses. Say where to pick up, not what was done. -->
+<!-- Navigational state only: the current checkpoint, the next action a higher
+     authority has already allowed, unresolved prerequisites, and the cheapest
+     safe resume command or path. It cannot override current owner authority,
+     approved scope/budget, task acceptance, or a validated Review verdict, it
+     cannot promote P2/P3 findings into blockers, and it never requires a fresh
+     zero-finding review after a current APPROVE. It never carries or re-issues
+     an execution grant: continuing under a durable work-package grant requires
+     the consuming Agent to re-verify the recorded grant itself. Overwrite it
+     whenever work pauses. Say where to pick up, not what was done. When the
+     pause is owner-facing, the note answers the checkpoint semantics: why,
+     outcome, accepted boundary, delta, reality, decision needed, next bounded
+     action, and not-done. -->
 
 _(not started)_
 
 ## Completion
 
-> _Fill when the task is complete._
+_Not completed._
+
+## Task Review
 
-- **Completed**: {date}
-- **Commit**: {hash}
-- **Summary**: {what was delivered}
+- Execution Packet state/digest/limitation: `not_run`
+- Review session identity and summary digest: `not_run`
+- Blocking findings with resolution/disposition/evidence refresh refs: `not_run`
+- Retention: retain the current strict review session until both aggregate Test and
+  Deliver consume it. Premature loss requires a fresh Review and Test; never reconstruct
+  the old receipt.
 
 ---
 *Generated by ultra-plan*

package/.ultra-template/north-star.md

@@ -1,35 +1,52 @@
 # Project North Star
 
-> **Authority**: the accepted steering contract established by `ultra-research` from
-> owner decisions and cited evidence. Every Change and task must serve this contract.
+> **Authority**: `ultra-research` is the first semantic writer. This placeholder is
+> owner-readable structure only; it is not an accepted direction, metric, or boundary.
 >
-> **Scope**: this file owns the project direction, the one North Star outcome or metric
-> when one is justified, hard constraints, and explicit exclusions. Product requirements,
-> supporting measurements, actors, and scenarios stay in `specs/product.md`.
+> **Adoption**: Init creates this file with status `unresearched` and no semantic IDs.
+> Research replaces it only after evidence collection and explicit owner acceptance.
 
-## Project Direction
+## Acceptance and Revision
 
-[NEEDS CLARIFICATION]
+- Schema: `north-star-v2`
+- Status: `unresearched`
+- Revision: `none`
+- Owner acceptance source: `none`
+- Acceptance time: `not-recorded`
+- Supersedes: `none`
 
-## North Star Outcome
+## Problem Reality
 
-- `NS-01` outcome: [NEEDS CLARIFICATION]
-- Metric or observation contract: [NEEDS CLARIFICATION]
-- Why it represents delivered value: [NEEDS CLARIFICATION]
+- Reality: [NEEDS RESEARCH]
+- Evidence: [NEEDS RESEARCH]
+- Unknowns: [NEEDS RESEARCH]
 
-A single metric is optional. When one would distort the product, record that decision and
-use an observable outcome plus guardrails instead of inventing numeric precision.
+## First-Principle Propositions
+
+[NEEDS RESEARCH: Research creates stable proposition IDs only after owner acceptance.]
+
+## Value Causal Chain
+
+[NEEDS RESEARCH: map accepted principles through capability and behavior to outcomes.]
+
+## North Star Outcomes
+
+[NEEDS RESEARCH: do not create an outcome ID or metric during Init.]
 
 ## Hard Constraints
 
-- `HC-1`: [NEEDS CLARIFICATION]
+[NEEDS RESEARCH: do not create a constraint ID during Init.]
 
 ## Explicit Exclusions
 
-- [NEEDS CLARIFICATION]
+- [NEEDS RESEARCH]
+
+## Uncertainties and Revisit Triggers
+
+- [NEEDS RESEARCH]
 
 ## Research Trace
 
-- Project brief: `project-brief.md`
-- Accepted research run: [NEEDS CLARIFICATION]
-- Decision references: [NEEDS CLARIFICATION]
+- Project Brief: `project-brief.md`
+- Research runs: none
+- Sources and decisions: none

package/.ultra-template/tasks.json

@@ -1,3 +1,4 @@
 {
+  "$schema": "ultra-task-ledger-v2",
   "tasks": []
 }

package/.ultra-template/test-report.json

@@ -1,7 +1,8 @@
 {
-  "$schema": "ultra-test-report-v1",
+  "$schema": "ultra-test-report-v2",
   "change_id": null,
   "task_ids": [],
+  "task_evidence": [],
   "git_commit": null,
   "intent_digest": null,
   "worktree": {
@@ -17,6 +18,21 @@
     "performance": {"status": "not_run", "evidence_refs": [], "omissions": ["Not yet run"]},
     "security": {"status": "not_run", "evidence_refs": [], "omissions": ["Not yet run"]}
   },
+  "review": {
+    "session": null,
+    "packet_digest": null,
+    "admission_digest": null,
+    "subject_digest": null,
+    "execution_mode": null,
+    "finding_schema": "ultra-review-findings-v4",
+    "summary_ref": null,
+    "summary_digest": null,
+    "context_digest": null,
+    "worktree_digest": null,
+    "verdict": "INCOMPLETE",
+    "coverage_refs": [],
+    "limitations": ["Not yet run"]
+  },
   "verified_seams": [],
   "findings": [],
   "omissions": ["Not yet run"],

package/CHANGELOG.md

@@ -7,6 +7,166 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.2] — 2026-08-18
+
+### Added
+
+- Implemented the r3 North Star projection under a verified primary transfer:
+  North Star revision `north-star-v2-r3` with the new `FP-8` (Agent handover is
+  exclusive, verified, and recoverable), a new acceptance decision and immutable
+  snapshot, and the exact ZCode sole-writer durable grant
+  `ubp3-r3-zcode-2026-08-17` recorded in `.ultra/decisions/`.
+- Added the primary-transfer contract between Agents
+  (`skills/ultra-change/references/primary-transfer.md`): an owner-granted
+  OFFER → verified ACK → sole-writer execution → frozen terminal RESULT protocol
+  over canonical files and Git, mutually exclusive with delegated workers,
+  with derived receipts under `.ultra/.runtime/handoffs/` and a mechanical
+  validator (`skills/ultra-change/scripts/validate_primary_transfer.cjs`) plus
+  authority, permission, effect, stale/revoke/interrupt/resume/cancel, and
+  missing-receipt recovery regressions (`tests/primary-transfer.test.cjs`).
+  `ultra-change`, `ultra-status`, and `ultra-delegate` consume the contract.
+- Added the versioned closeout-transition contract
+  (`ultra-primary-transfer-closeout-v1` in
+  `skills/ultra-change/references/primary-transfer.md`): the immutable
+  reviewed subject of a newest completed v2 RESULT is separated from exactly
+  one uncommitted prescribed post-review closeout (final evidence record,
+  task-context closeout sections, ledger `completed`) through a CLOSEOUT
+  receipt that starts no review or handoff and never commits, while
+  implementation, Acceptance, PPI, pre-review-evidence, and unrelated-ledger
+  drift stays typed-stale; owner-authorized continuations between freeze and
+  closeout are recorded, bounded, and pinned. The closed task's ledger row is
+  bound ex-status (unique, `in_progress` → `completed`, every other field
+  structure-equivalent, re-read live), and `authorized_by` binds the existing
+  `ultra-external-review-receipt-v1` semantics (read-only reviewer, exact
+  task/change identity, authority and reviewed-contract refs by stable bytes,
+  subject equal to the closeout start, `approve` with no P0/P1). Regressions
+  cover the terminal
+  green path without RESULT edit or commit, structural and citation
+  rejections, drift during/after closeout (including current-row field drift),
+  continuation bounds, and preserved
+  history (`tests/primary-transfer.test.cjs`).
+- Repaired the contract in the owner-authorized Round 1 pass
+  (`ubp3-r3-zcode-desktop-r1`): transfer validation is now phase-correct (an
+  ACK is a pre-write boundary record, so expected receiver edits never
+  self-invalidate an active or completed transfer; a superseded or v1 terminal
+  receipt stays historical), all receipt and bound-input reads are bounded
+  ordinary-file no-follow identity-checked reads (typed rejection for symlinks,
+  FIFOs, directories, oversize, and replacement), and a v2 terminal RESULT
+  binds the recomputed final HEAD, product worktree digest, exact full product
+  path inventory, and final frozen-input digests. Review-budget precedence is
+  one rule — an exact current owner grant overrides the versioned product
+  default (one initial review plus at most two P0/P1 delta reviews); P2/P3
+  never auto-extend, and the same root surviving three failed fixes stops
+  point-patching as an architecture problem. The ZCode delegate transport now
+  requires visible `--ack-experimental` acknowledgment and stamps
+  `transport_maturity`/`transport_surface` truth on every receipt and result,
+  so an app-internal CLI run can never be presented as the documented ZCode
+  Desktop interactive surface.
+- Closed the two Round 2 misses on the same roots: transfer validation is now
+  fail-closed (an unobservable HEAD/Git is a typed `git_unavailable` error
+  instead of a green warning) and every read goes through the worktree-digest
+  tool's one shared stable snapshot primitive with parent-chain walks, exact
+  handoff-directory replay, same-subject supersession, and one finite coherent
+  digest×manifest terminal observation; every delegated ZCode terminal result
+  (finished, failed, cancelled, interrupted) now mechanically carries
+  `experimental_ack: true` when `--ack-experimental` authorized the run.
+- Closed the final Round 3 miss on the same root: repo-wide handoff-root
+  discovery reuses the one stable directory observation — a symlinked,
+  unreadable, malformed, drifting, or oversize handoffs root (or entry) fails
+  typed and closed instead of silently reading as zero handoffs with
+  `valid: true`, while an absent root still legitimately means no transfers.
+- Implemented the accepted Ultra Builder Pro 3.0 design as one Mode B durable
+  work-package projection: North Star revision `north-star-v2-r2` with seven first
+  principles, five observable outcomes (`NS-01`-`NS-05`), and eight hard constraints;
+  the provider-neutral Ultra Core Protocol naming across public docs; the
+  owner-facing checkpoint contract (why, outcome, accepted boundary, delta, reality,
+  decision needed, next bounded action, not-done); the per-fact artifact-authority
+  matrix with an explicit Execution Grant row and four effect classes; and the
+  optional Graph/Loop control-plane boundary documented as not integrated.
+- Added dual-mode execution grants: session-local by default, `durable work-package`
+  by exact owner record, with stable verification, invalidation, and portable
+  handoff semantics in `skills/ultra-change/references/execution-grant.md`;
+  Status reports a recorded durable grant as inactive data awaiting verification.
+- Added work-package review convergence bounded by an owner-visible budget: the
+  released default is at most one initial Review plus two P0/P1 delta Reviews per
+  coherent package, with explicit terminal outcomes, no self-extended budget, and
+  mandatory stop signals when repairs expose distinct root causes. Exact defaults
+  live in the versioned product contract; exact overrides in owner grants.
+- Added ZCode as a sixth native host with fourteen Skills, five hook registrations, a
+  managed local marketplace, inline-plugin activation, Doctor, update, uninstall, and
+  bounded source/target delegation profiles. The App-bundled headless CLI transport
+  is recorded `experimental` in the shared host profile until official documentation
+  plus a full recovery drill meet the support bar.
+- Added canonical North Star traces from Research through Change, Plan, review, Test,
+  and delivery, plus adversarial challenges at Research checkpoints 04, 21, and 99.
+- Added review coverage references, recorded isolated-versus-sequential execution mode,
+  mandatory Plan and aggregate Test reviews, blind cross-family probes, and a seeded
+  adversarial evaluation fixture.
+
+### Changed
+
+- Made review topology owner-selected per stage with a one-reviewer default: initial
+  task review selects `review-spec` plus risk/touched-seam lenses, delta reviews rerun
+  only affected lenses, and the aggregate full-roster default applies only when
+  cross-task wiring justifies it — never a mandatory count or a quality proxy.
+- Split `ultra-deliver` entry by invocation kind: a model-selected Deliver run under a
+  grant may reconcile, review, and report, then stops before finalization; writing
+  `delivery.md`, version/package posture, and archiving require a current explicit
+  owner invocation in every grant mode.
+- Replaced the Change-scoped same-session Autonomy Envelope (superseded name,
+  historical) with the dual-mode
+  Execution Grant contract (`## Execution Grant` in every intent, `session-local`
+  default); renamed `AUTONOMY_CONTINUABLE_SKILLS` to `GRANT_CONTINUABLE_SKILLS` and
+  removed the unused `requiresAutonomyEnvelope` policy field.
+- Closed the superseded `chg-v027-lifecycle-closure` Change with an exact
+  abandonment record citing the Mode B grant and successor `chg-ultra-3-0-mode-b`;
+  its pending v0.27 task rows remain inert append-only history.
+- Made `validate_repo_path` in the review waiter reject symlink and non-directory
+  path components at validation time (Python 3.13 `resolve(strict=False)` no longer
+  raises on symlink loops).
+- Made the task-evidence audit and review-wait fixtures derive the repository
+  North Star decision, snapshot, revision, and trace IDs dynamically instead of
+  locking revision r1.
+- Raised the Grok delegation turn ceiling to twelve and retained launcher-side strict
+  result validation; Kimi delegation can now select a model explicitly.
+- Made Claude delegation rely on strict launcher validation instead of a native schema
+  option rejected by current Claude Code.
+- Embedded each digest-bound instruction and permission packet in the worker prompt so
+  OpenCode can keep external-directory access denied, and projected a Codex-compatible
+  native result schema while retaining stronger launcher validation.
+
+### Fixed
+
+- Replaced the release gate's load-sensitive fixed delay for strict Review
+  admission pinning with an explicit subprocess read handshake, so a slow clean
+  CI checkout cannot capture the already-mutated receipt and falsely pass the
+  polling invariant.
+- Made the release gate reproducible from a clean checkout: installer integration
+  tests use an isolated Codex CLI fixture, and completed-task audits consume canonical
+  evidence after Review and Handoff receipts have reached their documented GC boundary.
+- Made no-op ZCode hook adapters emit an actually empty stdout response, matching the
+  host's strict hook parser instead of intermittently failing a benign tool call on `{}`.
+- Shared the macOS App-bundled ZCode CLI fallback between native plugin lifecycle
+  checks and delegated target launches when `zcode` is not available on `PATH`.
+- Removed a delegated-result prompt contradiction by listing `$schema` in the exact
+  required field set, matching the launcher's fail-closed result validator.
+- Added a resident entry guard to every implicitly discoverable public workflow so a
+  missing live execution grant stops before workflow work begins: a session-local grant
+  requires current conversation activation, and a durable work-package grant requires
+  stable verification by the consuming Agent.
+- Raised the direct `js-yaml` floor to 4.3.1 so the release dependency audit no longer
+  includes the high-severity `!!omap` quadratic-consumption advisory.
+
+### Verified
+
+- Completed authenticated read-only target delegation with Claude Code, Codex,
+  OpenCode, Kimi Code, and ZCode; Grok Build's malformed terminal output failed closed.
+- Re-ran ZCode target delegation without a binary override on a machine where `zcode`
+  is absent from `PATH`; the App-bundled fallback returned a validated empty-diff result.
+- Completed one bounded ZCode automatic-coding run through Plan, adversarial reviews,
+  TDD, and Test with 3/3 tests passing, then stopped before ungranted delivery, commit,
+  push, publication, or deployment.
+
 ## [0.26.2] — 2026-08-04
 
 ### Added
@@ -1286,7 +1446,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   skill manifest, CLI protocol + mapping table; 5 spec validators.
 - **Phase 0 — skeleton**: multi-runtime installer scaffolding.
 
-[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.26.1...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v3.0.2...HEAD
+[3.0.2]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.26.2...v3.0.2
+[0.26.2]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.26.1...v0.26.2
 [0.26.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.26.0...v0.26.1
 [0.26.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.25.1...v0.26.0
 [0.25.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.25.0...v0.25.1