ultra-builder-pro-cli 0.26.1 → 3.0.2

package/skills/ultra-review/SKILL.md

@@ -1,38 +1,83 @@
 ---
 name: ultra-review
-description: Review one task diff or aggregate Change through six independent lenses, synthesize file-backed findings, and perform evidence-justified refactoring. Use when another skill needs task-level or delivery-level review without loading worker investigation into the main context.
+description: Review one task diff or aggregate Change through owner-selected independent lenses, synthesize file-backed findings, and perform evidence-justified refactoring. Use when another skill needs task-level or delivery-level review without loading worker investigation into the main context.
 ---
 
-# Review through six lenses without polluting the main context
+# Review through selected lenses without polluting the main context
 
 The parent owns scope and synthesis. Lens workers are read-only sensors. Refactoring
 happens here, after several slices make a useful structure visible, not inside TDD.
 
 ## Before you start
 
-1. Read `.ultra/tasks.json`, the scoped task's `context_file` and `## Resume Note`.
+1. Resolve the review scope first. For task or active-Change review, read
+   `../ultra-change/references/change-contract.md` and apply its **Active Change
+   authority resolution** before reading any active `intent.md`, resolving the current
+   `change_id` or task, reading context or acceptance, or creating a packet. A stable
+   zero result stops with no current review scope; any typed diagnostic, including
+   non-unique authority, stops with its repair before any `.ultra/reviews` packet write.
+   After one valid authority, read its intent and `.ultra/tasks.json`, select only
+   matching tasks, then read the scoped task's `context_file` and `## Resume Note`.
+   Historical review must name its archived Change explicitly and never infer scope
+   from unfinished status.
 2. Read `CONTEXT.md`, relevant `.ultra/decisions/`, acceptance, evidence and exact diff.
+   Task-review admission comes from the ledger `in_progress` row, task context,
+   immutable packet, and actual pre-review evidence such as retained command output,
+   inspected source, owner records, and external receipts. The first task review must
+   not require the final `ultra-task-evidence-v2` record that it helps produce. For an
+   aggregate Change review, require every completed task's current v2 record. Treat any
+   legacy context Status, Complexity, or v1 evidence as a migration diagnostic rather
+   than current completion truth. The ledger remains the sole task-status authority.
+   Resolve the scope's `FP-*`, `NS-*`, and `HC-*` IDs against the accepted North Star
+   revision; pass IDs and causal evidence, never a copied North Star prose mirror.
 3. Create `.ultra/reviews/<session>/` and one immutable packet naming HEAD, scope,
-   output path, acceptance and public seams. Follow `references/worker-packet.md`,
-   then compute the SHA-256 of the exact packet bytes and do not edit it.
+   output path, acceptance and public seams. Follow `references/worker-packet.md` and
+   record the exact ordered v2 `subject_observations` for the validated Change,
+   acceptance sources, and canonical validator decision/snapshot sources. Then compute
+   the SHA-256 of the exact packet bytes and do not edit it.
+4. Before launching a lens, run `scripts/review_wait.py <session> packet
+   --packet-digest <digest>`. A typed subject or byte mismatch requires a corrected new
+   session; never repair the frozen packet in place. Success atomically writes the
+   derived packet-bound `ADMISSION.json`; do not launch from copied stdout alone. This
+   publication is create-once: the exact existing bytes are an idempotent success, while
+   different existing bytes are an `admission_conflict` requiring a fresh session.
 
 ## Definition of done
 
 - The complete six-worker roster is dispositioned; every selected lens artifact and one
   summary exist, while skipped or failed lenses are explicit.
-- Each selected lens reports at most 12 findings, each evidence-backed. Scores never decide
-  whether an observable defect is included.
+- Each selected lens preserves every evidence-backed finding it can establish inside
+  the authorized physical resource budget. A finding or file count never decides what
+  is included, whether quality is sufficient, or whether the review has converged.
 - Findings preserve independent `spec_fidelity` and `engineering_standards` axes.
+- Every v4 finding carries `north_star_trace.first_principles`, `.serves`, and `.touches`
+  arrays preserving the applicable `FP-*`/`NS-*`/`HC-*` trace and identifies a stale or
+  contradictory trace without mechanically deciding semantic alignment.
+- `SUMMARY.json` records `execution_mode: isolated | sequential-shared-context`.
+- A task review's validated final summary precedes publication of its one canonical v2
+  evidence record; review admission never invents a second evidence or status authority.
 - Refactors are justified by observed duplication or coupling and all affected checks rerun.
 
 ## Run the lenses
 
 Use the host's native bounded subagents, in the background where available; otherwise
-run them sequentially. **All six lenses are selected by default.** Skipping one requires
-a stated reason recorded in `SUMMARY.json` — "its evidence cannot change the verdict"
-is a judgement made before seeing the evidence, and left as a default it becomes a way
-to run less work rather than a considered choice. Give each the packet path and digest,
-`references/unified-schema.md`, and exactly one lens:
+run them sequentially. The owner chooses the review topology per stage — one reviewer
+or several, which providers, which write scopes; the default is one reviewer, the
+current Agent. Lens selection follows the review kind, never a fixed count:
+
+- An **initial task review** always selects `review-spec` plus only the lenses
+  justified by the current risk and the touched seams; a major or high-risk task may
+  select the full six-lens roster only with recorded owner approval.
+- A **delta review** reruns only the lenses the exact blocking repair set can affect;
+  it never re-audits the whole task and runs only inside the active review budget.
+- An **aggregate Change review** may default to all six only when the cross-task
+  wiring justifies it; that is a selection reason, never a mandatory count or a
+  quality proxy, and it never writes non-blocking refactor findings back into a
+  completed task.
+
+Skipping a lens requires a stated reason recorded in `SUMMARY.json`; the rationale is
+evidence for the selection actually made, never a way to run less work. Give each
+worker the packet path and digest, `references/unified-schema.md`, and exactly one lens:
 
 - `references/code.md`
 - `references/design.md`
@@ -49,33 +94,162 @@ intermediate worker output or treat background notifications as completion. The
 information path is wait script to JSON artifact. These guards prevent partial results
 from becoming a semantic verdict.
 
+For v4, the waiter verifies the exact packet bytes, binds every requested stem to the
+packet worker and scope, resolves each finding trace as a packet subset, reloads all
+completed specialist artifacts in packet order, and rejects a summary that omits,
+rewrites, reorders, or injects any finding. It also verifies axis evidence refs and
+derives axis and overall verdicts from that immutable evidence. These are provenance and
+transport checks, never a replacement for a specialist's semantic judgment.
+Validator success therefore means only that the immutable transport and exact schemas
+agree. It never supplies a specialist finding, accepts an `owner-judgment`, or decides
+semantic pass.
+The `packet` command is the one admission boundary that checks current Git HEAD and
+reads current context, the exact active/archive/abandoned Change path already validated
+from `north_star_trace.path`, acceptance-source, and North Star bytes.
+It sends the already captured North Star bytes through the canonical Research
+validator's native stdin seam and requires that report to receipt the identical input;
+it does not implement a second Markdown grammar or interpret Change/acceptance prose.
+Admission atomically records those observations in `ADMISSION.json`. Strict v4 `agents`
+and `summary` require that packet-bound receipt. Every current specialist artifact and
+`SUMMARY.json` records the SHA-256 of the receipt's exact bytes as `admission_digest`
+plus its exact `subject_digest`; the waiters pin both values across every poll and final reload.
+They then reread only the exact packet and its frozen artifacts, so later task
+completion, Change archival, or North Star revision cannot erase historical review
+evidence. Packet, receipt, artifact, and canonical
+summary inputs are bounded stable regular-file snapshots; a fresh root rewalk verifies
+every recorded path-component and file identity after reading. A special file,
+replacement, oversize input, skipped admission, or invalid UTF-8/JSON returns typed
+repairable `incomplete` output rather than becoming evidence. Canonical validator stdout
+and stderr share one incremental byte ceiling; exceeding it terminates and reaps that
+attempt immediately.
+`ADMISSION.json` is derived and non-authoritative, but it is retained mechanical
+evidence until the session has completed its Test and Deliver consumption. If it is
+lost after any specialist artifact or `SUMMARY.json` exists, the strict session is
+`INCOMPLETE`; start a fresh review session instead of reconstructing or replacing the
+receipt. Before any output exists, packet mode may recreate a missing v2 receipt only
+when every packet-recorded byte length and SHA-256 still matches. A retained strict v1
+packet is read-compatible only with its exact existing receipt; packet mode never creates
+or recreates a v1 receipt. A newly published receipt is accepted only after a fresh
+canonical root rewalk confirms the session and exact receipt identity. When publication itself succeeded but
+one or more durability operations did not, packet mode returns `status: complete` with
+a typed `durability_warning`; multiple unresolved warnings are preserved together, and
+a temporary cleanup failure resolved by the final retry is not reported.
+It resolves the repository only from the canonical session path; packet paths and
+artifact file scope cannot be absolute, non-normalized, symlink-escaping, or broader
+than `diff_files`. Worker Packet v1 summaries use the packet-derived context digest and
+an explicit `worktree_digest: null` because v1 binds no exact worktree observation.
+
+Those commands require admission-contract v2 artifacts for every new session. Use `--legacy-v4`
+immediately after the packet digest only to read an immutable v4 session created before
+admission receipts and therefore lacking the current packet `admission_contract`
+marker. Use `--legacy-v3` only for an immutable historical v3 session. Either legacy
+flag rejects every packet marked strict v1 or v2; only truly historical unmarked
+packets, or packet-absent v3 history, enter compatibility mode.
+Neither flag permits new legacy artifacts, automatically falls back, or mutates history.
+
+Record `isolated` only when selected lenses had separate native contexts; otherwise
+record `sequential-shared-context`. A zero-finding artifact must cite real coverage or
+an explicit limitation; without either, record the review as `INCOMPLETE`.
+When an axis has no completed artifact, keep its exact evidence union as `[]` and mark it
+`INCOMPLETE`; never invent a placeholder artifact merely to satisfy the summary shape.
+
 ## Synthesize, repair and recheck
 
 Preserve findings unchanged in `SUMMARY.json`; group duplicates by root cause only in
-the human summary. Fix accepted P0/P1 issues and evidence-backed refactors, then rerun
-the affected lenses against the delta.
+the human summary.
+
+Verdicts are terminal for the current subject. `APPROVE` ends the current task review
+even when P2 or P3 findings are retained — they stay in the report and go to the
+owner-selected backlog, and no fresh review of the same subject may be opened after a
+current `APPROVE`. `REQUEST_CHANGES` routes only the exact current P0/P1 finding ids
+(or a P2 the owner explicitly promoted); repair them as one in-scope repair set, then
+run one affected-lens delta review of that exact repair set inside the active review
+budget. When another `REQUEST_CHANGES` would exceed the active budget — or a delta
+that returns `INCOMPLETE` on evidence the budget cannot cover — return to the owner
+checkpoint: report the exact blocking set and stop instead of starting another
+automatic repair. When evidence proves a P2 actually blocks
+acceptance, reclassify it as P1 in the current review rather than routing a P2 label
+as a blocker. A finding outside the packet's `diff_files` is a scope-change proposal:
+record it, do not edit that path, and return it to the owner or Plan as a new subject.
+
+Resource budgets — time, tools, cost, review counts — stop execution only. Budget
+exhaustion returns `owner checkpoint` / `budget_exhausted` and keeps the task
+`in_progress` without disposing findings.
+It never yields `APPROVE`, `REQUEST_CHANGES`, `INCOMPLETE`, pass, fail, accept, or
+abandon, and a round, count, or budget number never measures semantic quality.
+
+### Work-package convergence
 
-Stop when P0 + P1 does not decrease between rounds. Write a stuck report separating an
-over-tight constraint from an insufficient fix and give the owner three concrete paths.
-If one file fails three consecutive repairs, treat it as an architecture concern. If
-three or more files do so, write `UNRESOLVED.md` with `ARCHITECTURAL_CONCERN` and stop.
+Review budget precedence is one rule: an exact current owner grant for this work
+package overrides the versioned product default; the released default is one initial
+review plus at most two P0/P1 delta reviews per coherent work package. Both are
+finite, owner-visible budgets, never a semantic quality measure.
+
+Only actual P0/P1 findings — or a P2 the owner explicitly promoted as a direct North
+Star blocker — trigger a delta review; P2/P3 findings are reported and never
+auto-repair or auto-extend any budget. Zero findings is never the completion
+condition — completion is the owner accepting the real result. A finding outside the
+current subject is a scope-change proposal for the owner or a future Change, never a
+reason to enlarge this package.
+
+When the same root cause survives three failed repair attempts, stop point-patching
+and report an architecture boundary problem. A remaining blocker at budget
+exhaustion returns the choice to the owner with the exact blocking set; never open
+an automatic round beyond the active grant, and never extend a budget yourself. The
+legal terminal outcomes are: owner risk acceptance, owner scope reduction or reset,
+a new explicitly authorized work package, an external blocker, a budget stop, or
+abandonment.
+
+Stop repairing and return to the owner when three repairs expose three distinct
+root causes, the same path keeps gaining validators, counters, mirrors, or
+replays, a formal terminal verdict conflicts with Resume/Hook/Status suggestions,
+the owner-visible outcome has materially drifted, the reviewer contract and the
+reviewed subject are the same changing thing, or you cannot name the concrete
+harm the next round would remove.
+
+The parent model judges `stalled` from the actual repair/evidence history, not
+from repair rounds, finding counts, or the number of files involved. Zero findings is
+never a completion condition: a zero-finding artifact must cite real coverage or an
+explicit limitation, and convergence is judged by evidence, never by an empty findings
+array. When repair is no longer justified, preserve an unresolved report that
+separates a possibly over-tight constraint, an insufficient fix, unavailable evidence,
+and an observed shared structural root. Return the reachable repair, retry,
+owner-disposition, or abandon path.
 
 Report both axes, exact scope, checks, residual findings and any refactor performed.
 
+## Self-hosting review boundary
+
+Touching any of these paths makes the reviewed subject self-hosting:
+
+- `skills/ultra-review/**`, including `scripts/review_wait.py`;
+- review routing inside `skills/ultra-dev/**`, Review consumption inside
+  `skills/ultra-test/**`, or Review/Test bounce inside `skills/ultra-deliver/**`;
+- the Review packet, schema, and transport tests;
+- Hook route or Resume authority under `hooks/`.
+
+A self-hosting review must pin its semantic baseline — the owner-accepted contract
+digest — and use a stable external reviewer boundary instead of judging its own
+changes with the changing reviewer. During the v0.27 H0 closure that boundary is one
+read-only external manual review by the owner-named reviewer; never use the local
+changing `ultra-review` implementation to approve itself, and treat a released tag
+only as a historical behavior reference, never as the current verdict authority.
+
 ## Recheck across model families
 
 Six lenses are six angles from one model family, so they share blind spots: what all
 six miss, a seventh angle from the same family misses too. Independence comes from a
 different model, not from another lens.
 
-For a `major` Change, or one touching authorization, payments, personal data or
-migrations, recommend a cross-family recheck and wait for the owner's decision. Do not
+When concrete effects make authorization, payments, personal data, migrations, or
+another accepted risk material, recommend a cross-family recheck and wait for the
+owner's decision. A profile label alone is not a semantic risk verdict. Do not
 invoke `ultra-delegate` unless the owner has explicitly asked for another model or host
-for this review. Once that authority exists, follow `../ultra-delegate/SKILL.md`. For a
-`quick` profile, skip the recommendation and say so in the report.
+for this review. Once that authority exists, follow `../ultra-delegate/SKILL.md`.
 
-- Send the aggregated `SUMMARY.json` and the diff, **not** the raw lens artifacts. The
-  worker should form its own reading rather than grade this one.
+- For a **finding audit**, send `SUMMARY.json` plus the diff and ask which findings lack
+  support. For a **blind adversarial probe**, send the Worker Packet, North Star Trace,
+  and diff without `SUMMARY.json`, and ask what the local review missed.
 - Ask two things: which findings the evidence does not actually support, and what this
   diff gets wrong that no finding mentions. The second question is why the recheck is
   worth its cost.
@@ -91,8 +265,11 @@ Workers never edit source, task state or another lens artifact.
 
 ## References
 
+- `../ultra-change/references/change-contract.md` — canonical Active Change authority resolution.
 - `references/unified-schema.md` — JSON contract shared by all lenses.
 - `references/worker-packet.md` — exact immutable input packet and digest procedure.
 - `references/review-modes.md` — choose task, Change, full, or delta scope.
+- `references/adversarial-evaluation.md` — use before adding or removing a review lens.
+- `../ultra-plan/references/task-evidence-v2.md` — current task evidence and task-review provenance.
 - `../ultra-delegate/SKILL.md` — read after the owner authorizes a cross-family recheck.
 - `../ultra-think/references/autonomy-boundary.md` — read before a fix reduces intent.

package/skills/ultra-review/references/adversarial-evaluation.md

@@ -0,0 +1,31 @@
+# Adversarial review evaluation
+
+Use this protocol before changing the permanent lens roster. A plausible blind spot is
+a hypothesis; admit a new lens only when a blind evaluation shows unique useful coverage.
+
+## Prepare a blind fixture
+
+Create or select a small repository snapshot containing known defects across acceptance,
+premise, executable behavior, tests, recovery, design, and maintained documentation.
+Keep the seed manifest outside every Worker Packet. Record the snapshot revision,
+accepted intent, North Star Trace, public seams, and commands available to workers.
+
+## Compare equal runs
+
+Run the current six-lens roster first. Then run the candidate lens with the same packet,
+tool authority, model family, and bounded effort. Use isolated contexts where the host
+supports them and record the actual execution mode. Do not reveal seed ids, expected
+findings, earlier outputs, or the admission decision to either run.
+
+After artifacts are stable, map evidence-backed findings to the hidden seeds. Preserve
+misses, false positives, unavailable evidence, and disagreements; a vote or score does
+not decide truth. Repeat any claimed unique catch against a fresh context so leaked
+context or sampling noise is not mistaken for a durable capability.
+
+## Admission decision
+
+Add a permanent lens only when it repeatedly finds a consequential, reproducible defect
+class the current roster misses and its question cannot be folded into an existing lens
+without losing independence. Otherwise strengthen the narrowest existing lens or keep
+the candidate as an occasional blind cross-family probe. Record the fixture revision,
+raw artifact paths, mapping rationale, decision, and cheapest future retest.

package/skills/ultra-review/references/spec.md

@@ -5,6 +5,11 @@ criterion to current executable or source evidence. Check for omitted behavior,
 unintended scope, stale specification or operational documentation, and incompatible
 public contracts.
 
+Read the packet's `North Star Trace`. Verify that its ids and recorded revision resolve,
+then challenge whether the Change's claimed causal contribution has supporting evidence
+and survives the diff. A stale revision is a freshness limitation, not automatic proof
+of semantic misalignment.
+
 Report only a concrete mismatch between accepted intent and delivered behavior. Style,
 generic maintainability and a preferred architecture do not belong on this axis.
 Calibrate severity to user-visible or delivery impact. Use `axis: spec_fidelity` and

package/skills/ultra-review/references/unified-schema.md

@@ -7,12 +7,14 @@ return only a one-line acknowledgement to the parent.
 
 ```json
 {
-  "$schema": "ultra-review-findings-v2",
+  "$schema": "ultra-review-findings-v4",
   "agent": "review-code",
   "axis": "engineering_standards",
   "packet_digest": "<sha256-of-exact-worker-packet>",
+  "admission_digest": "<sha256-of-exact-admission-receipt>",
+  "subject_digest": "<subject-digest-from-admission-receipt>",
   "session": "<session-id>",
-  "timestamp": "<ISO-8601>",
+  "timestamp": "<RFC-3339-instant>",
   "scope": {
     "head": "<full-git-head>",
     "range": "<diff-range>",
@@ -33,9 +35,15 @@ return only a one-line acknowledgement to the parent.
       "trigger": "The provider times out after committing the first request.",
       "impact": "A retry can create a duplicate charge.",
       "evidence": "retryPayment calls charge() again without an idempotency key.",
-      "suggestion": "Persist and reuse one idempotency key for the operation."
+      "suggestion": "Persist and reuse one idempotency key for the operation.",
+      "north_star_trace": {
+        "first_principles": ["FP-1"],
+        "serves": ["NS-01"],
+        "touches": ["HC-2"]
+      }
     }
   ],
+  "coverage_refs": ["src/payments/retry.ts:42"],
   "positive_observations": [],
   "limitations": []
 }
@@ -44,11 +52,25 @@ return only a one-line acknowledgement to the parent.
 Use `axis: "spec_fidelity"` for the independent acceptance review and
 `axis: "engineering_standards"` for engineering specialists.
 
+For packet-bound v4 artifacts, `agent`, `axis`, `session`, `scope.head`,
+`scope.range`, and `packet_digest` exactly match the immutable packet and its canonical
+worker record. `admission_digest` equals SHA-256 over the exact retained
+`ADMISSION.json` bytes and `subject_digest` equals that receipt's field; both are
+required and exact for current strict v4. `scope.diff_only` is `true`. Every
+`scope.files_analyzed` entry and every
+finding `file` is a normalized repository-relative path contained in the packet's
+`diff_files`; a broader investigation requires a new packet rather than an expanded
+artifact. `timestamp` is a valid RFC 3339 instant with `Z` or an explicit numeric UTC
+offset; nonempty prose, impossible dates, and timezone-free local times are invalid.
+
 ## Required finding fields
 
 Every finding needs a stable id, axis, severity, category, concise title, repository-
 relative file, tight line range, triggering condition, observable impact, source
-evidence, and smallest complete remediation.
+evidence, smallest complete remediation, and one `north_star_trace` object. Its
+`first_principles`, `serves`, and `touches` arrays contain only the applicable resolving
+IDs from the immutable Worker Packet; an array may be empty when that finding does not
+touch that ID kind. Never copy North Star prose into a finding.
 
 Severity is impact-based:
 
@@ -61,30 +83,44 @@ Severity is impact-based:
 Do not report a concern without a plausible execution path. Do not encode a style
 preference as a defect. Preserve the source specialist's severity during coordination.
 
+Severity routes findings; it never decides convergence:
+
+- P0 and P1 are blocking. `REQUEST_CHANGES` routes only the exact current P0/P1
+  finding ids, or a P2 the owner explicitly promoted after the current review
+  reclassified it as P1 on evidence.
+- P2 and P3 findings are non-blocking. An `APPROVE` verdict is terminal for the
+  current task review even when P2 or P3 findings are retained: they stay in the
+  report and the owner-selected backlog, and there is no fresh review of the same
+  subject after a current `APPROVE`. Repairing a P2 inside the same task requires an
+  explicit owner selection, never an implicit promotion.
+
 ## Coordinator summary
 
 `SUMMARY.json` contains:
 
 ```json
 {
-  "$schema": "ultra-review-summary-v2",
+  "$schema": "ultra-review-summary-v4",
   "mode": "change",
+  "execution_mode": "isolated",
   "session": "<session-id>",
   "change_id": "<change-id>",
   "task_ids": ["<task-id>"],
   "head": "<full-git-head>",
-  "worktree_digest": "<sha256-of-current-worktree>",
+  "worktree_digest": null,
   "context_digest": "<sha256-of-recorded-review-context>",
   "packet_digest": "<sha256-of-coordinator-worker-packet>",
+  "admission_digest": "<sha256-of-exact-admission-receipt>",
+  "subject_digest": "<subject-digest-from-admission-receipt>",
   "status": "complete",
-  "verdict": "REQUEST_CHANGES",
+  "verdict": "APPROVE",
   "axes": {
     "spec_fidelity": {
       "verdict": "PASS",
-      "evidence_refs": ["spec-fidelity.json"]
+      "evidence_refs": ["review-spec.json"]
     },
     "engineering_standards": {
-      "verdict": "FAIL",
+      "verdict": "PASS",
       "evidence_refs": ["review-code.json", "review-tests.json"]
     }
   },
@@ -126,18 +162,65 @@ preference as a defect. Preserve the source specialist's severity during coordin
     }
   ],
   "findings": [],
+  "coverage_refs": ["review-spec.json", "review-code.json", "review-tests.json"],
   "positive_observations": [],
   "limitations": []
 }
 ```
 
-`findings` must contain every specialist finding unchanged. Group duplicates only in
+`findings` must contain every specialist v4 finding unchanged, including its
+`north_star_trace`. Group duplicates only in
 the human-readable summary; never delete or merge machine-readable records.
 
+For v4, `review_wait.py` treats this as an exact transport invariant. It verifies the
+session's immutable Worker Packet bytes, reloads and revalidates every artifact named in
+`workers.completed`, and requires `findings` to equal their packet-ordered union one
+object at a time. Omitted, edited, reordered, or coordinator-injected objects are
+invalid. Axis evidence refs are the corresponding packet outputs; each axis verdict and
+the overall verdict are derived from that verified union and the completed/failed roster.
+Human grouping never changes these machine records.
+
+For current strict v4, `admission_digest` and `subject_digest` are required and exactly
+match the retained receipt just as they do in each specialist artifact. The waiter pins
+the pair from its first receipt read through polling, specialist-union validation, and
+its final reload. A missing or changed receipt makes the session `INCOMPLETE`; recovery
+after any specialist artifact or `SUMMARY.json` exists is a fresh session, not receipt
+reconstruction. Before any output exists, packet mode may recreate a missing v2 receipt
+only when the exact packet-recorded subjects remain unchanged. It never creates or
+recreates a retained strict v1 receipt. The receipt remains derived, non-authoritative evidence, but must be retained
+through Test and Deliver. Its subject digest also binds the canonical validator's exact
+decision and snapshot `source_observations` (`role`, repository-relative `path`,
+lowercase SHA-256, and byte length).
+
+An axis `evidence_refs` array is exactly the packet-ordered completed specialist output
+union for that axis. It may be empty only when that union is empty and the derived axis
+verdict is `INCOMPLETE`, such as a spec-only packet or when every selected engineering
+worker failed. An empty array can never support `PASS` or `FAIL`; do not invent a
+placeholder reference.
+
+`context_digest` is packet-derived, not coordinator-authored. With one
+`context_files` item it equals that item's `sha256`. With zero or multiple items it is
+SHA-256 over compact UTF-8 JSON for the `{path,sha256}` items sorted by UTF-8 `path`
+bytes, with object keys sorted. `worktree_digest` is present and `null` in Worker Packet
+v1 reviews because that packet schema does not bind an exact worktree digest. A future
+packet schema may add such a fact; an unbound coordinator observation must not claim
+provenance now.
+
+`coverage_refs` names inspected source, commands, or stable artifacts supporting the
+coverage claim. Zero findings with neither a coverage reference nor an explicit
+limitation is incomplete, not an approval.
+
 `mode` is `task`, `change`, or `plan`. `worker_selection` contains each member of the
 six-worker roster exactly once with a scope-specific selected or skipped rationale.
 Its selected set equals `workers.completed` plus `workers.failed`; its skipped set
-equals `workers.skipped`. `review-spec` is always selected and completed.
+equals `workers.skipped`. `review-spec` is always selected. If it fails, the
+`spec_fidelity` evidence union is `[]`, that axis and the overall verdict are
+`INCOMPLETE`, and the historical failure remains a valid summary rather than a fabricated
+completed artifact.
+
+`execution_mode` is exactly `isolated` when every selected lens ran in a fresh native
+subagent context, or `sequential-shared-context` when the host reused one context. It
+reports independence; it does not change a finding's truth.
 
 The overall verdict is `APPROVE` only when both axes pass, artifacts are complete and
 current, and no P0 or P1 finding remains. Use `REQUEST_CHANGES` for a failed axis or
@@ -145,5 +228,57 @@ blocking finding, and `INCOMPLETE` when required evidence or workers are missing
 Each axis verdict is `PASS`, `FAIL`, or `INCOMPLETE`; the overall verdict is `APPROVE`,
 `REQUEST_CHANGES`, or `INCOMPLETE`.
 
+The ordinary summary command reads one stable canonical `SUMMARY.json` snapshot and
+returns its SHA-256 as `summary_digest`. The Review-to-Test consumer first captures the
+canonical `.ultra/test-report.json` and its repository-relative `SUMMARY.json` using one
+shared bounded stable raw-byte rule. Every managed path component below the real
+repository root is non-symlink, each final entry is a regular file inside that root, and
+each snapshot is limited to 8 MiB. An 8 MiB + 1 byte observation returns a typed
+oversize diagnostic before JSON parsing or hashing. The exact report bytes own parsing
+and subject comparisons; the exact summary bytes own parsing, SHA-256, comparisons, and
+waiter validation. A direct consumer that already owns that summary snapshot passes
+those exact bytes on stdin and invokes:
+
+```bash
+python3 scripts/review_wait.py <session> summary \
+  --packet-digest <packet-sha256> \
+  --summary-snapshot-digest <summary-sha256>
+```
+
+The waiter parses and validates only those stdin bytes, checks their supplied digest,
+requires the session's stable packet-bound `ADMISSION.json`, and returns the same digest.
+This seam prevents Review-to-Test from validating, parsing, hashing, and comparing
+different filesystem observations. The receipt proves the strict v4 packet preflight
+ran; it does not cause summary validation to reread mutable subjects.
+
+Summary validation consumes the packet's frozen subject claims. It does not reread the
+current context, Change, acceptance source, or North Star, so a task-close update or a
+later accepted revision cannot make an already completed review unreadable.
+
+Review admission and Review-to-Test are cooperative-workspace sensors. They detect
+observable path, component, identity, byte, and digest drift and never claim to defeat a
+malicious process that can exchange and restore directory entries between individual
+system calls. Use Host sandboxing or an isolated worktree for adversarial operating-
+system writers; do not add a second semantic authority or platform-specific filesystem
+engine to this portable Skill.
+
 Validate JSON before acknowledgement. Never paste full JSON or worker transcripts into
 the parent conversation.
+
+## Historical compatibility
+
+New sessions always write `ultra-review-findings-v4` and
+`ultra-review-summary-v4` from a packet carrying
+`admission_contract: ultra-review-admission-required-v2` with exact ordered
+`subject_observations`, after packet mode atomically publishes and freshly rewalks a v2
+`ADMISSION.json`.
+Immutable v4 sessions created before that receipt remain readable only by adding
+`--legacy-v4` immediately after `--packet-digest <digest>` and only when the historical
+packet lacks the admission marker.
+Immutable v3 sessions use
+`--legacy-v3` in the same position. Both flags reject packets marked strict v1 or v2;
+only truly historical unmarked packets, or packet-absent v3 sessions, use them. Retained
+strict v1 remains readable only with its exact existing receipt and cannot be admitted
+or re-admitted. These are explicit read compatibility paths, not
+automatic fallback or permission to create or rewrite legacy findings. `--legacy-v4`
+is not a recovery path for a current session whose retained receipt was lost.