ultra-builder-pro-cli 0.26.2 → 3.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/.ultra-template/contexts/TEMPLATE.md +64 -29
  2. package/.ultra-template/north-star.md +35 -18
  3. package/.ultra-template/tasks.json +1 -0
  4. package/.ultra-template/test-report.json +17 -1
  5. package/CHANGELOG.md +163 -1
  6. package/README.md +108 -38
  7. package/adapters/_shared/host-profile.cjs +68 -12
  8. package/adapters/_shared/plugin-core.cjs +4 -5
  9. package/adapters/_shared/runtime-assets.cjs +11 -2
  10. package/adapters/zcode.js +375 -0
  11. package/bin/delegate-worker.cjs +20 -0
  12. package/bin/delegate.cjs +94 -25
  13. package/bin/install.js +11 -6
  14. package/docs/ARCHITECTURE.md +84 -23
  15. package/docs/ARTIFACT-AUTHORITY.md +167 -22
  16. package/docs/DECISIONS.md +131 -17
  17. package/docs/PHILOSOPHY.md +58 -7
  18. package/docs/PLUGIN-ISOLATION-CONTRACT.md +6 -0
  19. package/docs/RUNTIME-COMPAT-MATRIX.md +106 -13
  20. package/docs/SKILL-AUTHORING.md +4 -3
  21. package/docs/WORKFLOW-LIFECYCLE.md +126 -28
  22. package/docs/evals/adversarial-review-2026-08-14.md +84 -0
  23. package/docs/evals/zcode-automation-2026-08-14.md +103 -0
  24. package/hooks/README.md +27 -4
  25. package/hooks/_common.py +1678 -61
  26. package/hooks/adapters/zcode.py +227 -0
  27. package/hooks/compact_context.py +176 -17
  28. package/hooks/mid_workflow_recall.py +27 -5
  29. package/hooks/post_edit_guard.py +133 -23
  30. package/hooks/session_context.py +707 -22
  31. package/package.json +6 -3
  32. package/skills/ultra-change/SKILL.md +40 -9
  33. package/skills/ultra-change/references/change-contract.md +93 -27
  34. package/skills/ultra-change/references/execution-grant.md +109 -0
  35. package/skills/ultra-change/references/primary-transfer.md +273 -0
  36. package/skills/ultra-change/scripts/validate_primary_transfer.cjs +1928 -0
  37. package/skills/ultra-delegate/SKILL.md +24 -2
  38. package/skills/ultra-delegate/references/delegation-contract.md +21 -1
  39. package/skills/ultra-deliver/SKILL.md +85 -11
  40. package/skills/ultra-dev/SKILL.md +171 -41
  41. package/skills/ultra-grilling/SKILL.md +10 -7
  42. package/skills/ultra-grilling/references/reframing.md +7 -3
  43. package/skills/ultra-init/SKILL.md +44 -7
  44. package/skills/ultra-init/scripts/init_project.cjs +968 -21
  45. package/skills/ultra-plan/SKILL.md +70 -44
  46. package/skills/ultra-plan/references/task-evidence-v2.md +300 -0
  47. package/skills/ultra-plan/scripts/validate_task_evidence.cjs +859 -0
  48. package/skills/ultra-research/SKILL.md +38 -10
  49. package/skills/ultra-research/references/04-product-strategy.md +11 -2
  50. package/skills/ultra-research/references/21-features-scope.md +8 -0
  51. package/skills/ultra-research/references/22-success-metrics.md +4 -3
  52. package/skills/ultra-research/references/99-synthesis.md +19 -2
  53. package/skills/ultra-research/references/north-star-v2.md +168 -0
  54. package/skills/ultra-research/references/wayfinding.md +8 -0
  55. package/skills/ultra-research/scripts/validate_north_star.cjs +1174 -0
  56. package/skills/ultra-review/SKILL.md +201 -27
  57. package/skills/ultra-review/references/adversarial-evaluation.md +31 -0
  58. package/skills/ultra-review/references/spec.md +5 -0
  59. package/skills/ultra-review/references/unified-schema.md +146 -11
  60. package/skills/ultra-review/references/worker-packet.md +151 -8
  61. package/skills/ultra-review/scripts/review_wait.py +2653 -63
  62. package/skills/ultra-status/SKILL.md +95 -11
  63. package/skills/ultra-tdd/SKILL.md +11 -4
  64. package/skills/ultra-tdd/references/test-execution.md +6 -1
  65. package/skills/ultra-test/SKILL.md +145 -17
  66. package/skills/ultra-test/scripts/validate_review_transport.cjs +549 -0
  67. package/skills/ultra-test/scripts/worktree_digest.cjs +518 -30
@@ -11,15 +11,28 @@ persists a workflow-position field.
11
11
 
12
12
  ## Before you start
13
13
 
14
- 1. List directories containing `.ultra/changes/active/*/intent.md`. If exactly one
15
- exists, its directory name is the current `change_id`. Read `.ultra/tasks.json`,
16
- then tasks whose `change_id` matches it and the frontier task's `context_file` and
17
- `## Resume Note`. Historical and abandoned tasks never define the frontier.
14
+ 1. Read `../ultra-change/references/change-contract.md` and apply its **Active Change
15
+ authority resolution** before reading any active `intent.md` or relying on a current
16
+ `change_id`. A positively observed absent `.ultra` uses the existing `ultra-init`
17
+ route. Otherwise continue only from the rule's stable zero-or-one result; any typed
18
+ diagnostic stops routing until its stated repair or retry succeeds. With one active
19
+ Change, read `.ultra/tasks.json`, then tasks whose `change_id` matches it and the
20
+ frontier task's `context_file` and `## Resume Note`. `.ultra/tasks.json` is the sole
21
+ task-status authority. A Status or Complexity header in a legacy context is a
22
+ migration diagnostic; the ledger wins. Historical and abandoned tasks never define
23
+ the frontier.
18
24
  2. Read `.ultra/project-brief.md`, `.ultra/north-star.md`, `CONTEXT.md`, relevant
19
25
  `.ultra/decisions/`, specifications, active, archived, or abandoned Changes, and
20
26
  evidence. An abandoned Change supplies historical boundary and recovery context;
21
27
  it never defines the current route.
22
28
  3. Inspect Git `HEAD`, worktree status, and installed host manifests without repair.
29
+ 4. When the active Change records a `durable work-package` Execution Grant, report it
30
+ as recorded authorization data — grant id, cited decision, and its recorded
31
+ subject, scope, topology, allowed effects, budgets, and invalidation — and state
32
+ plainly that stored grant text is inactive until a consuming Agent stably
33
+ verifies it per `../ultra-change/references/execution-grant.md`. Status itself
34
+ neither activates nor continues the grant; a `session-local` grant is reported as
35
+ requiring fresh owner activation.
23
36
 
24
37
  ## Definition of done
25
38
 
@@ -35,15 +48,21 @@ persists a workflow-position field.
35
48
  |---|---|
36
49
  | No `.ultra/` | `ultra-init` |
37
50
  | Project Brief has no usable one-line and no legacy `## One-line` exists | `ultra-init` |
38
- | Project Brief or legacy seed exists but no accepted North Star supports the current boundary | `ultra-research` |
51
+ | Project Brief or legacy seed exists and North Star status is `unresearched`, legacy, invalid, or not accepted for the current boundary | `ultra-research` |
39
52
  | A new request exists and no active Change exists | `ultra-change` |
40
53
  | More than one active Change exists | Diagnose the conflicting directories and ask the owner which one remains active; do not route or move either automatically |
54
+ | A primary-transfer handoff directory exists under `.ultra/.runtime/handoffs/` | Report its protocol state read-only (`offered`, `blocked`, `active`, or a terminal state) from `OFFER.json`/`ACK.json`/`RESULT.json`, verified with `node <ultra-change-skill-dir>/scripts/validate_primary_transfer.cjs <repository-root>`; receipts are derived observations, never authority |
55
+ | An ACK-ready handoff has no terminal RESULT | The accepted receiver is the sole canonical writer for that work package; report the in-flight transfer and never route canonical writes to another Agent |
56
+ | A handoff is `blocked` or its live re-verification is stale | Report the mismatched observation and the recovery path (fresh handoff id after owner re-confirmation); do not repair receipts |
41
57
  | The active intent is `draft` or has a blocking unresolved decision | `ultra-change` to finish and accept the contract |
42
58
  | The active `Research Disposition` names required exit evidence that is not satisfied | `ultra-research` for the named question and selected lenses |
43
59
  | Research evidence exists but the accepted intent has not reconciled it | `ultra-change` to update the bounded contract |
60
+ | The accepted North Star revision or digest differs from the active intent trace | `ultra-change`; report the stale observation, preserve old evidence, and reconcile IDs before execution |
44
61
  | An active Change exists and `.ultra/tasks.json` has no tasks whose `change_id` matches it | `ultra-plan` |
45
- | A matching task is pending or in progress with same-Change dependencies satisfied | `ultra-dev`, naming that task |
46
- | All matching tasks are completed and no current report matches this Change | `ultra-test` |
62
+ | The Change has exactly one `in_progress` task | `ultra-dev`, naming that task |
63
+ | Only `pending` tasks remain (the frontier) | Report them as frontier candidates with their unresolved dependencies and recommend one exact task id for an explicit owner invocation of `ultra-dev`; a pending row is not active work and never auto-selects a route |
64
+ | A ledger row says `completed` but its current `ultra-task-evidence-v2` record or task-review binding is missing, stale, or structurally invalid | `ultra-dev` to repair evidence and completion provenance; do not infer a context status or silently demote the row |
65
+ | All matching tasks are completed, each has current `ultra-task-evidence-v2` plus a consumed task review, and no current report matches this Change | `ultra-test` |
47
66
  | A current false report has implementation, test, or wiring findings selected for repair | `ultra-dev` after owner disposition |
48
67
  | A current false report has missing external or product evidence selected for collection | `ultra-research` after owner disposition |
49
68
  | A current false report has an acceptance, scope, or existing-promise change selected for reconciliation | `ultra-change` after owner disposition; use `ultra-think` internally for one consequential trade-off |
@@ -61,22 +80,86 @@ differs from `HEAD`, or its `worktree.diff_digest` or `intent_digest` differs fr
61
80
  running
62
81
  `node <ultra-test-skill-dir>/scripts/worktree_digest.cjs --project <repository-root> --change-id <change_id>`.
63
82
  A dirty worktree is a warning, not evidence of failure.
83
+ The product-worktree digest has one fixed boundary: it excludes `.ultra/evidence/**`,
84
+ whose command and external-observation entries bind raw bytes as
85
+ `raw_evidence_sha256` before stable exact record bytes are bound as `evidence_digest`.
86
+ Status must therefore use the exact ordered `task_evidence` projection and strict receipt
87
+ consumers below for evidence provenance; it never adds another exclusion or treats
88
+ excluded publication bytes as absent evidence.
89
+
90
+ Freshness also requires the exact ordered `task_evidence` projection. Its
91
+ `evidence_digest`, `task_review_session`, and `task_review_summary_digest` must match the
92
+ current record and retained review — or, for an `external-manual` record, its
93
+ `task_review_receipt_ref` and `task_review_receipt_digest` must match the current
94
+ record and the bounded stable receipt bytes reverified through the sensor's
95
+ `--verify-external-receipt` mode, and take its `--projection` output verbatim.
96
+ Recheck whichever branch the record declares and never rewrite one branch into the
97
+ other. For each item, take every command and
98
+ external-observation `raw_evidence_ref` to bounded stable
99
+ repository-contained bytes from an ordinary regular non-symlink file opened nonblocking
100
+ and no-follow, with an 8 MiB ceiling and path/descriptor identity checks around the read.
101
+ Recompute `raw_evidence_sha256` from that one snapshot and require an exact match, then
102
+ recompute the stable exact `evidence.json` bytes as `evidence_digest` before comparing
103
+ the projection. A raw or record mismatch routes to the owning task's explicit Dev repair.
104
+ Run
105
+ `node <ultra-plan-skill-dir>/scripts/validate_task_evidence.cjs <evidence-ref>`, and
106
+ compare `task_id`, `schema`, `evidence_ref`, `task_review_session`, and
107
+ `task_review_summary_digest` with the current ledger row, final evidence record, and
108
+ retained strict task-review summary. The task evidence `subject` is an independently
109
+ captured completion-snapshot freshness observation made after validated task Review and
110
+ immediately before evidence publication. Its `task_review` separately binds the retained strict summary; neither Worker Packet v1 nor its nullable summary worktree digest proves
111
+ the subject. Do not require that earlier observation to equal the report's later
112
+ aggregate worktree digest. Recheck current Acceptance, criterion and verification type,
113
+ owner record, review summary, and cited affected artifacts independently.
114
+
115
+ Replay the report's strict aggregate review summary with the existing Review summary
116
+ waiter, then run
117
+ `node <ultra-test-skill-dir>/scripts/validate_review_transport.cjs --summary <summary-path> --report .ultra/test-report.json`.
118
+ Require the exact `packet_digest`, `admission_digest`, `subject_digest`, and `summary_digest` bindings, plus session, summary path, execution mode, ordered findings, and report root subject.
119
+ Each structural validator or sensor reports identity and provenance observations and never decides semantic acceptance, review quality, or `passed`.
120
+ Any mismatch makes the report stale and routes repair to the responsible workflow.
64
121
 
65
122
  `passed: false` does not itself select a repair. Preserve each finding, ask for owner
66
123
  disposition where scope or risk changes, then route by the accepted response above.
67
- Likewise, task completion is necessary for `passed: true` but never sufficient to
68
- manufacture it.
124
+ For a current task-review `REQUEST_CHANGES`, consume the exact validated current
125
+ `SUMMARY.json.findings` array and preserve every finding id. Route every current P0/P1
126
+ to resolution or authoritative disposition and refresh its affected evidence; never
127
+ reuse a finding count or list from an older summary. P2 and P3 findings remain report
128
+ entries or owner-selected backlog and never re-open a task on their own.
129
+ Likewise, ledger completion and structurally valid v2 evidence are necessary for a
130
+ current Test claim but never sufficient to manufacture `passed: true`. A validator
131
+ reports schema, identity, provenance, and freshness observations only. It cannot decide
132
+ whether an inspection supports a criterion, supply an `owner-judgment`, or turn an
133
+ external receipt into product truth.
134
+
135
+ Status remains read-only when later work invalidates a completed task. It names the
136
+ affected criterion IDs and reason and recommends Dev. Dev records both in the context
137
+ Change Log and Resume Note before the ledger-authoritative `completed` to `in_progress`
138
+ transition; Status never silently demotes a task.
139
+
140
+ A budget stop or `owner checkpoint` is displayed as-is: report the exhausted budget,
141
+ the in-progress task it stopped, and the reachable owner decision (extend, retry,
142
+ cancel, or abandon). Status never infers continuation, extension, or any semantic
143
+ verdict from a budget stop, and never treats a pending frontier row as the active
144
+ task behind one.
69
145
 
70
146
  The repository has one primary writer for canonical `.ultra` files. Native review
71
147
  workers and delegated CLIs may inspect or write isolated source roots, but their results
72
148
  return to that writer. Concurrent canonical writes require separate worktrees and
73
149
  explicit integration; this router does not invent locks or silently merge ledgers.
74
150
 
151
+ Report the accepted North Star revision and digest, every active Change trace mismatch,
152
+ and unresolved `FP-*`/`NS-*`/`HC-*` reference. A mismatch is stale evidence, never a
153
+ mechanical verdict about truth or permission; supersession does not delete prior task,
154
+ review, Test, or delivery evidence.
155
+
75
156
  ## Surface risk and installation health
76
157
 
77
158
  List unmet task dependencies, more than one matching `in_progress` task under the
78
- single-writer contract, any `in_progress` task older than 3 days, complexity
79
- concentration, and broken `trace_to` or `context_file` paths. These are sensors.
159
+ single-writer contract, broken `trace_to` or `context_file` paths, stale subject or
160
+ acceptance identities, unresolved task-review findings, and concrete evidence that a
161
+ task can no longer resume reliably. A timestamp, complexity value, file count, or task
162
+ count is context for the model, never a staleness or quality verdict.
80
163
 
81
164
  Compare the selected host's plugin path, skill inventory, version, provenance, and hook
82
165
  manifest with installed files. Recommend `ubp install` or `ubp update` as the repair;
@@ -89,6 +172,7 @@ Contradictory facts remain visible instead of being resolved by routing heuristi
89
172
 
90
173
  ## References
91
174
 
175
+ - `../ultra-change/references/change-contract.md` — canonical Active Change authority resolution.
92
176
  - `../ultra-think/SKILL.md` — read only when contradictory evidence creates one real
93
177
  decision rather than a mechanical repair.
94
178
  - `../ultra-think/references/autonomy-boundary.md` — read before recommending a route
@@ -10,8 +10,14 @@ the loop that supplies it, and it serves Goal 3, Production-Ready.
10
10
 
11
11
  ## Before you start
12
12
 
13
- 1. When called from a planned Change, resolve the unique active `change_id` and read the
14
- matching current task context for the seams already confirmed during planning. For a
13
+ 1. When called from a planned Change, read
14
+ `../ultra-change/references/change-contract.md` and apply its **Active Change
15
+ authority resolution** before reading any active `intent.md`, resolving the current
16
+ `change_id` or task, reading its context, running the baseline, or executing red-green
17
+ product edits. A stable zero result stops with no current task; any typed diagnostic,
18
+ including non-unique authority, stops with its repair before the baseline, red-green,
19
+ or any product write. After one valid authority, read its intent, `.ultra/tasks.json`,
20
+ and the matching current task context for the seams confirmed during planning. For a
15
21
  micro edit outside the Ultra lifecycle, no active task context is required; use the
16
22
  accepted request, maintained specification, and an existing repository seam, and
17
23
  create no Ultra task or delivery claim.
@@ -43,8 +49,8 @@ Write the failing test first and run it, so that red is observed rather than
43
49
  assumed. Then write the smallest code that turns it green. Predict no later
44
50
  tests and add no speculative capability. Then take the next slice.
45
51
 
46
- Refactoring is not part of this loop; `ultra-review` owns it, because the
47
- restructuring worth doing only becomes visible after three or four slices.
52
+ Refactoring is not part of this loop; `ultra-review` owns it when observed duplication,
53
+ coupling, or a boundary defect supplies evidence that restructuring is worthwhile.
48
54
 
49
55
  ## Three patterns that produce tests worth deleting
50
56
 
@@ -77,6 +83,7 @@ goes to the owner as one.
77
83
 
78
84
  ## References
79
85
 
86
+ - `../ultra-change/references/change-contract.md` — canonical Active Change authority resolution.
80
87
  - `../ultra-think/references/autonomy-boundary.md` — read before replacing a real
81
88
  dependency with a fake, or when a test stands between the work and green.
82
89
  - `references/templates/README.md` — read when choosing which enabling template
@@ -11,8 +11,13 @@ For every baseline, red, and green run record:
11
11
  - runner-reported pass, fail, skip, and coverage counts when available;
12
12
  - first useful failure with tight source or test location;
13
13
  - whether it reproduces and whether it is product, test, environment, or flaky evidence;
14
- - raw output path under `.ultra/evidence/<task-id>/` when the output matters.
14
+ - raw output path under `.ultra/evidence/<task-id>/` and the lowercase SHA-256 of its
15
+ exact bounded stable bytes when the output matters.
15
16
 
16
17
  Do not weaken flags, skip a relevant failure, edit test configuration to obtain green,
17
18
  or claim success when the command did not finish with exit zero. A concise evidence
18
19
  record may cite the raw log; it must not copy an entire transcript into task context.
20
+ Before citing one, require a repository-contained ordinary regular non-symlink file,
21
+ opened nonblocking and no-follow with an 8 MiB ceiling and unchanged path/descriptor
22
+ identity around the read. Hash that one snapshot; a missing, escaped, special, symlinked,
23
+ oversized, or replaced receipt is a typed evidence gap, not a successful run record.
@@ -11,20 +11,40 @@ the owner decides what to fix or accept.
11
11
 
12
12
  ## Before you start
13
13
 
14
- 1. Resolve exactly one `.ultra/changes/active/<change_id>/intent.md`. Read
15
- `.ultra/tasks.json` and only tasks whose `change_id` matches the active Change. Every
16
- matching task must be complete; read each task's `context_file` Acceptance, Completion and
17
- closing `## Resume Note`. Historical tasks are not part of this audit snapshot.
18
- 2. Read `CONTEXT.md` for vocabulary and the relevant `.ultra/decisions/` entries.
19
- 3. Read the active Change intent, the task evidence directories and the current Git
14
+ 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.
15
+ 2. Read `../ultra-change/references/change-contract.md` and apply its **Active Change
16
+ authority resolution** before reading any active `intent.md` or resolving a current
17
+ `change_id`. This workflow requires its one valid active authority; any zero result
18
+ or typed diagnostic stops before audit input is read until the stated repair or retry
19
+ succeeds. Read `.ultra/tasks.json` and only tasks whose `change_id` matches the active
20
+ Change. Every matching task must be `completed` in that sole task-status authority.
21
+ Read each task's `context_file` Acceptance, Completion, Task Review and closing
22
+ `## Resume Note`.
23
+ Historical tasks are not part of this audit snapshot. For every current Change task,
24
+ require a current `ultra-task-evidence-v2` record whose context, subject, acceptance,
25
+ and task-review bindings satisfy `../ultra-plan/references/task-evidence-v2.md`.
26
+ A legacy context Status or Complexity header and v1 evidence remain migration
27
+ diagnostics only; recommend Dev repair rather than treating them as current Test input.
28
+ 3. Read `CONTEXT.md` for vocabulary and the relevant `.ultra/decisions/` entries.
29
+ 4. Read the active Change intent, the task evidence directories and the current Git
20
30
  `HEAD`; old output is evidence only for the commit it names.
21
- 4. Resolve this loaded Skill's directory and run
31
+ Resolve Change and task `FP-*`, `NS-*`, and `HC-*` IDs against the accepted North
32
+ Star revision. A stale trace is an explicit finding requiring reconciliation, not a
33
+ silent rewrite or automatic failure verdict.
34
+ 5. Resolve this loaded Skill's directory and run
22
35
  `node <ultra-test-skill-dir>/scripts/worktree_digest.cjs --project <repository-root> --change-id <change_id>`
23
36
  before and after the audit. It returns the stable Change id, exact intent SHA-256,
24
- HEAD, and product-worktree digest. The product digest excludes the report and all
25
- active/archive/abandoned Change-directory metadata; intent freshness is checked
26
- separately, so writing delivery metadata or moving the same Change cannot invalidate
27
- its tested product snapshot.
37
+ HEAD, and product-worktree digest. The product-worktree digest has one fixed boundary:
38
+ it excludes `.ultra/evidence/**`, whose command and external-observation entries bind
39
+ raw bytes as `raw_evidence_sha256` before stable exact record bytes are bound as
40
+ `evidence_digest`. It also excludes the report and
41
+ all active/archive/abandoned Change-directory metadata. Intent freshness is checked
42
+ separately, so publishing or refreshing evidence, writing delivery metadata, or moving
43
+ the same Change cannot self-invalidate its tested product snapshot. Exact task-evidence
44
+ and review-receipt digests remain mandatory through their existing consumers; this is
45
+ not a caller-configurable exclusion. This digest defines the aggregate Change subject
46
+ for the current whole Change; it is distinct from each task's earlier
47
+ completion-snapshot freshness observation.
28
48
 
29
49
  ## Definition of done
30
50
 
@@ -34,6 +54,15 @@ the owner decides what to fix or accept.
34
54
  - `.ultra/test-report.json` records `change_id`, the exact current-Change `task_ids`,
35
55
  `intent_digest`, `git_commit`, commands, findings, omissions and the owner's
36
56
  disposition without rewriting a finding into a pass.
57
+ - Every current task's v2 evidence and retained task-review summary is consumed; blocking
58
+ findings, resolutions, disagreements, and refresh references remain attributable.
59
+ - One current aggregate Change review is referenced by session, packet digest, exact
60
+ admission and subject digests, execution mode, coverage, summary path, exact summary
61
+ SHA-256, and verdict.
62
+ - The report names `ultra-review-findings-v4` and copies every review finding unchanged,
63
+ including `north_star_trace.first_principles`, `.serves`, and `.touches`, so each
64
+ finding carries its resolving `FP-*`/`NS-*`/`HC-*` IDs and Deliver can
65
+ test evidence against outcome without copying the North Star prose.
37
66
 
38
67
  ## Audit six areas
39
68
 
@@ -59,6 +88,95 @@ file is how a report loses findings.
59
88
  Read `references/export-syntax.md` before collecting exports. The table finds
60
89
  candidates; repository conventions and real consumers decide what is public.
61
90
 
91
+ After the six areas, follow `../ultra-review/SKILL.md` for an aggregate Change review.
92
+ Read only its validated summary, preserve its findings, and carry the review session,
93
+ packet digest, admission digest, subject digest, execution mode, coverage refs, summary
94
+ ref, verdict, and limitations into the report. Record
95
+ `review.finding_schema: "ultra-review-findings-v4"`; copy each finding
96
+ object unchanged from the v4 summary, including `north_star_trace`. An incomplete review
97
+ stays an omission; it never becomes a silent pass. Historical v3 review is evidence only:
98
+ run a fresh v4 aggregate review before a current Test claim.
99
+
100
+ Before accepting copied review metadata or findings, replay the exact frozen
101
+ `SUMMARY.json` through the sibling `ultra-review/scripts/review_wait.py` v4 summary
102
+ validator. Strict v4 replay is the default and requires the same session's valid
103
+ `ADMISSION.json`; `--legacy-v4` is an explicit read mode only for immutable historical
104
+ pre-admission evidence and cannot support a current Test claim. Then bind its
105
+ `change_id`, ordered `task_ids`, `head`, `admission_digest`, `subject_digest`,
106
+ `context_digest`, and
107
+ honest nullable `worktree_digest` to the Test report's root identity and `review`
108
+ provenance fields. The transport sensor accepts only canonical
109
+ `.ultra/test-report.json` and the normalized repository-relative
110
+ `.ultra/reviews/<session>/SUMMARY.json` it names. Both use the same bounded stable
111
+ raw-byte snapshot rule: every managed path component below the real repository root is
112
+ non-symlink, the final entry is a repository-contained regular file, and an 8 MiB + 1
113
+ byte observation returns a typed oversize diagnostic before JSON parsing or hashing.
114
+ The final file is opened with `O_NONBLOCK` and `O_NOFOLLOW`; its descriptor is
115
+ immediately required to be a regular file with the inspected path identity. A type or
116
+ identity replacement returns the existing retryable snapshot diagnostic instead of
117
+ waiting on a special file.
118
+ The sensor uses one report snapshot for report parsing and subject comparisons, and one
119
+ summary snapshot for summary parsing, SHA-256, comparisons, and the waiter's stdin
120
+ validation. After writing those exact values and findings, run
121
+ `node <ultra-test-skill-dir>/scripts/validate_review_transport.cjs --summary <validated-summary-path> --report .ultra/test-report.json`.
122
+ Record that exact command, exit code, and evidence reference in `commands`. A nonzero
123
+ result is a typed transport observation: repair the report copy and rerun it; never drop,
124
+ merge, inject, or rewrite a finding to obtain a pass. This sensor compares exact summary
125
+ bytes, review metadata, and finding objects only. It does not reinterpret a finding or
126
+ decide the audit verdict.
127
+
128
+ Validate each task evidence record with the shipped v2 structural sensor before using
129
+ it. For every record whose `task_review.review_mode` is `external-manual`, rerun the
130
+ sensor with `--verify-external-receipt` and recheck the declared receipt branch — the
131
+ bounded stable receipt bytes, its recorded SHA-256, and its task/change/subject
132
+ identity — instead of replaying a strict summary; strict-v4 records keep their exact
133
+ waiter and transport replay. A task's declared branch is preserved as-is in the
134
+ ordered `task_evidence` projection, consuming each item from the sensor's
135
+ `--projection` output verbatim: an external-manual item carries `task_review_mode`,
136
+ `task_review_receipt_ref`, and `task_review_receipt_digest` where a strict item
137
+ carries its session and summary digest. Never rewrite one branch into the other. The CLI establishes only JSON shape, token syntax, and
138
+ authority designation; it does not prove current identity, provenance, freshness,
139
+ or semantic acceptance. Test
140
+ takes each command and external-observation `raw_evidence_ref` to bounded stable
141
+ repository-contained bytes from an ordinary regular non-symlink file opened nonblocking
142
+ and no-follow, with an 8 MiB ceiling and path/descriptor identity checks around the read.
143
+ Recompute `raw_evidence_sha256` from that one snapshot and require an exact match. Then
144
+ recompute the stable exact `evidence.json` bytes as `evidence_digest` before copying the
145
+ ordered `task_evidence` projection; a raw or record mismatch is an evidence gap returned
146
+ to Dev.
147
+ Test
148
+ takes stable bytes independently, then rechecks and recomputes the current Acceptance-section SHA-256, aligns exact criterion IDs and verification types with the current context, and aligns the task-review session and summary digest with the retained strict summary. For `owner-judgment`, require that the durable owner record exists with its cited statement and disposition readable before rechecking all cited affected artifacts.
149
+ The `subject` is an independently captured completion-snapshot freshness observation made after the final strict task Review validates and immediately before evidence publication; `task_review` separately binds the retained strict summary. Worker Packet v1 carries no task worktree digest and its summary records `worktree_digest: null`, so Test never claims that those review artifacts prove or cryptographically bind `subject.worktree_digest`. It also never replaces that earlier observation with the later aggregate Change digest.
150
+ The owner alone supplies an owner-judgment result. A later task may change the aggregate
151
+ worktree without invalidating an earlier task, but any changed acceptance, owner record,
152
+ review binding, or cited artifact that no longer supports its criterion is a mismatch.
153
+ Any mismatch is an evidence gap: return the affected task and criterion IDs to Dev, or
154
+ return a missing owner judgment to the owner. Test never edits task status. Dev records the reason and performs
155
+ the explicit ledger `completed` to `in_progress` reopen; no silent demotion is allowed.
156
+ Never turn structural sensor success into any of those consumer conclusions.
157
+
158
+ This is a cooperative-workspace drift sensor, not an operating-system isolation
159
+ primitive. Use one fixed closing protocol: one complete primary observation followed by
160
+ one terminal seal. A persistent mismatch observed inside or before that terminal seal
161
+ returns typed `ULTRA_SNAPSHOT_CHANGED_DURING_OBSERVATION` recovery instead of publishing
162
+ the tuple. A cooperative write after the completed terminal seal belongs to the next
163
+ consumer, which must perform a fresh recapture before using the tuple. Hostile writers or
164
+ interleavings require a native Host sandbox or an isolated worktree. Never add an
165
+ unbounded success-seeking replay.
166
+
167
+ Aggregate finding disposition is bounded: P2 and P3 findings are recorded as backlog or
168
+ residual risk and never automatically returned to Dev, and this audit writes
169
+ non-blocking refactor observations into the report instead of reopening a completed
170
+ task. An implementation P0/P1 found here returns to Dev as at most one new
171
+ owner-approved repair task; there is no unbounded Test ↔ Deliver bounce, and any
172
+ re-entry through Test after a report is consumed requires an explicit owner
173
+ disposition.
174
+
175
+ The receipt is non-authoritative derived evidence, but retain it until both Test and
176
+ Deliver have consumed the review. If it is missing, the current session and Test claim
177
+ are `INCOMPLETE`; start a fresh review session. Do not reconstruct it or use
178
+ `--legacy-v4` to bypass loss from a current strict session.
179
+
62
180
  ## Detect substantive stubs
63
181
 
64
182
  Report an empty return with no IO, a log-only function, a handler that only prevents
@@ -73,15 +191,21 @@ findings with paths, verified seams, material omissions, residual risk, and `pas
73
191
  the model's evidence-derived summary in the one canonical
74
192
  `.ultra/test-report.json`. Each command records `command`, `exit_code`, and an
75
193
  `evidence_ref`; each area records `status`, `evidence_refs`, and `omissions`. Copy the
76
- script's `head`, `dirty`, `diff_digest`, and `intent_digest` into the report. A stale
194
+ worktree script's `head`, `dirty`, `diff_digest`, and `intent_digest` into the report.
195
+ That worktree identity binds the current whole Change, while ordered `task_evidence`
196
+ items preserve each task's distinct completion-snapshot freshness observation and
197
+ separate task-review identity.
198
+ Copy the validated review summary's exact SHA-256 into `review.summary_digest`; the
199
+ transport validator recomputes it before the report can be current evidence. A stale
77
200
  commit, product digest, intent digest, Change id, or task-id snapshot is labelled stale;
78
201
  it is never reused as current proof.
79
202
 
80
- `passed` is a one-way claim: `true` requires every current-Change task complete and no
81
- required area left `not_run`. Completed tasks do not force `passed: true`; findings,
82
- omitted evidence, or a failed command may keep it false, while an explicitly
83
- dispositioned gap remains visible even if the model's evidence summary passes. Preserve
84
- the finding and the owner's disposition as separate fields.
203
+ `passed` is a one-way claim: `true` requires every current-Change task completed in the
204
+ ledger, current v2 task evidence and task-review provenance, and no required area left
205
+ `not_run`. Completed rows do not force `passed: true`; findings, omitted evidence, or a
206
+ failed command may keep it false, while an explicitly dispositioned gap remains visible
207
+ even if the model's evidence summary passes. Preserve the finding and the owner's
208
+ disposition as separate fields. No validator result is itself semantic acceptance.
85
209
 
86
210
  Present the findings by consequence and recommend the highest-leverage response. The
87
211
  owner may fix all, fix selected findings, accept recorded risk, or reduce scope through
@@ -94,8 +218,12 @@ an observation, not permission to auto-fix, weaken a test or silently change sco
94
218
 
95
219
  ## References
96
220
 
221
+ - `../ultra-change/references/change-contract.md` — canonical Active Change authority resolution.
97
222
  - `references/export-syntax.md` — read during Wiring Verification to find exported
98
223
  symbol candidates in TypeScript/JavaScript, Python, Go, Rust and Java.
99
224
  - `scripts/worktree_digest.cjs` — deterministic HEAD plus worktree evidence identity.
225
+ - `../ultra-review/SKILL.md` — read for aggregate Change review after the six-area audit.
226
+ - `../ultra-plan/references/task-evidence-v2.md` — canonical current task evidence and task-review contract.
227
+ - `../ultra-change/references/execution-grant.md` — read only for grant-activated continuation.
100
228
  - `../ultra-think/references/autonomy-boundary.md` — read when a proposed response
101
229
  would make an existing specification commitment stop holding.