ultra-builder-pro-cli 0.25.1 → 0.26.0

package/skills/ultra-research/SKILL.md

@@ -1,68 +1,82 @@
 ---
 name: ultra-research
-description: Build or refresh an evidence-backed product and architecture baseline through recommended, user-selected semantic coverage. Use when initialization, brownfield adoption, or an active Change has a real evidence gap.
+description: Turn owner claims and specification gaps into cited product and architecture evidence, then refresh the canonical specifications and research distillate. Use when initialization, brownfield adoption, or an active Change contains claims that must be verified before planning.
 ---
 
-# Research with adaptive coverage
+# Verify claims and fill the specification gaps they control
 
-The model owns investigation and synthesis. The owner controls material scope and
-deferrals. MCP records the accepted draft and commits one durable checkpoint; it is
-not a questionnaire or a step-by-step supervisor.
+Research owns evidence and synthesis. The owner chooses material scope and accepts the
+three conclusions that change what later research does. Files are written immediately,
+so interruption loses no completed investigation.
 
-## Bind current context
+## Before you start
 
-1. Call `ultra.context { stage: research, detail: full }`.
-2. If the team checkpoint is newer, call `ultra.sync { action: import }`. Stop only
-   on a real ancestry or same-record conflict.
-3. Inspect code, docs, tests, runtime, accepted intent, decisions, and existing
-   research. Reuse current evidence and the matching mutable draft.
-4. Recommend the smallest sufficient coverage. Offer the adaptive set, the full
-   catalog, and a focused Change-bound set only when all are credible.
-5. Use the host-native question surface only for a material unresolved route. Reuse an
-   explicit owner choice without asking again.
+1. Read `.ultra/tasks.json`; if it names unfinished work, read its `context_file` and
+   closing `## Resume Note` before choosing research scope.
+2. Read `CONTEXT.md` for vocabulary and relevant `.ultra/decisions/` entries.
+3. Read `.ultra/north-star.md`, the active Change intent if any, and specification
+   sections carrying `[NEEDS CLARIFICATION]`.
 
-Read `../ultra-think/references/interaction-boundary.md` before asking. Load only the
-reference files for research areas that actually apply.
+## Definition of done
 
-## Investigate
+- Every selected area has a cited report under `.ultra/research/<run-id>/` and its
+  mapped specification section reflects the current conclusion.
+- `99-synthesis.md` states what entered a specification or decision, and what remains
+  unknown or deferred.
+- `.ultra/specs/research-distillate.md` records the Git blob hash of each specification
+  it summarizes; a hash mismatch makes the distillate stale, never authoritative.
+- Material omissions and `[UNVERIFIED: no web access]` findings stay visible.
+
+## Select the coverage once
+
+Scan unresolved specification headings, map them to the seventeen focused references,
+and recommend the smallest sufficient profile: Full, Product Only, Feature Only,
+Architecture Change, or Custom. Confirm the list once with the owner. Load one reference
+at a time; holding several step prompts together defeats progressive disclosure.
+
+The three checkpoints are `04-product-strategy`, `21-features-scope`, and
+`99-synthesis`: each conclusion changes what comes next. Present its evidence and
+recommendation, wait for the owner's decision, then continue. Other areas write their
+report and mapped section immediately without another ceremony.
+
+## Investigate and write
 
 For each selected area:
 
-- separate `Observed`, `Verified`, `Decided`, and `Unknown`;
-- resolve observable facts yourself and use primary sources where needed;
-- update the smallest baseline or Change-owned research artifact;
-- never store transcripts, hidden reasoning, raw provider payloads, or copied prompts;
-- record evidence, specification updates, decisions, deferrals, and consequences.
+1. Search current primary sources and inspect relevant source, tests, runtime and docs.
+2. Separate Observed, Evidence, Inference and Unknowns; cite every external claim.
+3. For solution strategy and building blocks, cite at least one real implementation in
+   a comparable maintained project, not only an opinion article.
+4. Write `.ultra/research/<run-id>/<area>.md`, then replace the mapped specification
+   section rather than appending a second version. Git keeps the history.
+5. Follow `../ultra-domain-modeling/SKILL.md` when evidence settles a domain term. Use
+   `../ultra-think/SKILL.md` when a consequential trade-off meets the decision criteria.
 
-Use one `ultra.record` batch for typed durable facts:
+If web search is unavailable, write `[UNVERIFIED: no web access]` and continue. Lack of
+a tool lowers confidence; it does not create a dead end.
 
-- `artifact / bind` for a managed research or specification artifact;
-- `decision / accept` for normalized owner intent;
-- `baseline / observe` or `baseline / accept` for baseline authority;
-- `change_contract / revise` for Change-bound findings.
+## Synthesize
 
-Every entry needs a stable idempotency key. Structural or authority conflicts require
-repair; semantic warnings remain visible but do not decide whether the research is
-sufficient.
+Load `references/99-synthesis.md` after the selected reports are on disk. Write which
+claims were confirmed, overturned, deferred, or converted into decisions. Update the
+specification balances, then write the distillate and its three source blob hashes.
+Read all changed files back and report the exact unresolved headings.
 
-## Commit one research checkpoint
+Recommend the next explicit capability from the resulting files; do not invoke it.
 
-Call exactly one `ultra.checkpoint` with `stage: research`. Put the selected research areas
-and their report outputs in `payload.steps`; include only work actually performed,
-verified, reused, deferred with owner authority, or proved not applicable. Synthesis
-must always be present.
+## When the owner decides
 
-For baseline research, update and accept the baseline through typed `ultra.record`
-entries, then publish the team checkpoint with `ultra.sync { action: publish }`.
-For Change-bound research, keep all findings and delta artifacts below the Change
-root and never edit accepted baseline specs directly.
+The owner chooses coverage, resolves the three checkpoints, and accepts any material
+deferral. Evidence facts are yours to establish. A conclusion that removes an existing
+commitment follows the REDUCTION boundary and waits for explicit authority.
 
-The model decides whether the selected coverage and synthesis are sufficient, and
-states omissions or deferred areas in the payload. MCP validates declared evidence
-bytes and records that conclusion; its semantic diagnostics are advisory. If it
-returns `accepted: false`, repair the reported structural, digest, path, or concurrency
-conflict and retry the same draft.
+## References
 
-Return coverage, decisive evidence, remaining gaps, durable artifact paths, and a
-model recommendation for the next explicit capability, such as `ultra-change` after a
-ready baseline. Never invoke it automatically.
+- `references/00-problem-validation.md` through `references/05-assumptions-validation.md`
+  — product premise and strategy; load only a selected area.
+- `references/10-user-personas.md` through `references/22-success-metrics.md` — users,
+  stories, scope and measurable outcomes; load only a selected area.
+- `references/30-architecture-context.md` through `references/41-quality-risks.md` —
+  system boundary, implementation evidence, deployment and risk.
+- `references/99-synthesis.md` — load last, after selected reports exist.
+- `../ultra-think/references/autonomy-boundary.md` — read before a specification shrinks.

package/skills/ultra-research/references/00-problem-validation.md

@@ -26,11 +26,11 @@ Update `discovery.md` with `Observed`, `Verified`, `Decided`, and `Unknown` entr
 - the narrowest owner-approved problem boundary;
 - unresolved validation needs.
 
-Link the updated specification anchor from the immutable step report required by the
-orchestrator. A missing load-bearing fact becomes a blocker or baseline gap, not a
+Link the updated specification anchor from the bounded area report written for this
+research run. A missing load-bearing fact becomes a blocker or baseline gap, not a
 guessed answer.
 
-## Semantic record
+## Report trace
 
-Use kind `problem`. Record `actor`, `current_workaround`, `consequence`, and
-`evidence_status`.
+In the area report, record `actor`, `current_workaround`, `consequence`, and
+`evidence_status`, then link the updated specification anchor.

package/skills/ultra-research/references/01-opportunity-discovery.md

@@ -27,7 +27,7 @@ Update `discovery.md` with:
 
 Complete the step with the evidence used and the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `opportunity`. Record `actor`, `desired_outcome`, and `evidence_status`. Link
-the record to its problem when that relation is established.
+In the area report, record `actor`, `desired_outcome`, and `evidence_status`. Link the
+conclusion to its problem anchor when that relation is established.

package/skills/ultra-research/references/02-market-assessment.md

@@ -22,9 +22,10 @@ Update `discovery.md` with relevant segment boundaries, commercial or operationa
 constraints, source-backed measurements, assumptions, and unknowns. Include a sizing
 model only when the decision genuinely depends on one and the inputs are defensible.
 
-Link source references and the updated specification anchor from the immutable step
-report required by the orchestrator.
+Link source references and the updated specification anchor from the bounded area
+report written for this research run.
 
-## Semantic record
+## Report trace
 
-Use kind `market_constraint`. Record `constraint`, `decision_impact`, and `freshness`.
+In the area report, record `constraint`, `decision_impact`, and `freshness`, then link
+the updated discovery anchor.

package/skills/ultra-research/references/03-competitive-landscape.md

@@ -25,7 +25,7 @@ credible alternative cannot be verified.
 
 Complete the step with evidence references and the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `alternative`. Record `category`, `switching_constraint`, and
-`strategy_implication`.
+In the area report, record `category`, `switching_constraint`, and
+`strategy_implication`, then link the updated discovery anchor.

package/skills/ultra-research/references/04-product-strategy.md

@@ -26,7 +26,7 @@ Update `discovery.md` with:
 
 Complete the step with decision and evidence references plus the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `strategy_decision`. Record `tradeoff` and `rationale`, then link the decision
-to the problems, opportunities, or constraints that support it.
+In the area report, record `tradeoff` and `rationale`, then link the decision file or
+specification anchor to the problems, opportunities, or constraints that support it.

package/skills/ultra-research/references/05-assumptions-validation.md

@@ -22,10 +22,10 @@ Update `discovery.md` with the assumption ledger and validation state. Map unres
 load-bearing assumptions to blocking unknowns or gaps. Keep non-blocking future work
 out of the implementation task graph until the owner selects it.
 
-Link evidence and the updated specification anchor from the immutable step report
-required by the orchestrator.
+Link evidence and the updated specification anchor from the bounded area report written
+for this research run.
 
-## Semantic record
+## Report trace
 
-Use kind `assumption`. Record `category`, `consequence`, `validation_signal`,
-`success_rule`, `failure_rule`, and `ambiguous_rule`.
+In the area report, record `category`, `consequence`, `validation_signal`,
+`success_rule`, `failure_rule`, and `ambiguous_rule`, then link the discovery anchor.

package/skills/ultra-research/references/10-user-personas.md

@@ -24,6 +24,7 @@ constraints, and evidence. Record priority only when it is an accepted decision.
 
 Complete the step with evidence references and the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `actor`. Record `job`, `current_workflow`, `goal`, and `constraint`.
+In the area report, record `job`, `current_workflow`, `goal`, and `constraint`, then
+link the actor heading in `product.md`.

package/skills/ultra-research/references/11-user-scenarios.md

@@ -22,7 +22,7 @@ behavior and documentation disagree.
 
 Complete the step with evidence references and the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `scenario`. Record `actor_id`, `trigger`, `preconditions`, `flow`, `success`,
-`failure`, and `recovery`.
+In the area report, record `actor_id`, `trigger`, `preconditions`, `flow`, `success`,
+`failure`, and `recovery`, then link the scenario heading in `product.md`.

package/skills/ultra-research/references/20-user-stories.md

@@ -24,7 +24,8 @@ writing vague acceptance.
 
 Complete the step with evidence references and the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `requirement`. Record `preconditions`, `action`, `observable_result`,
-`error_recovery`, and `verification`. Link it to its accepted scenario or decision.
+In the area report, record `preconditions`, `action`, `observable_result`,
+`error_recovery`, and `verification`. Link the requirement heading to its accepted
+scenario or decision.

package/skills/ultra-research/references/21-features-scope.md

@@ -24,6 +24,7 @@ exclusions and rationale, dependencies, and unresolved scope decisions.
 
 Complete the step with decision evidence and the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `capability`. Record `requirement_ids`, `scope_status`, and `rationale`.
+In the area report, record `requirement_ids`, `scope_status`, and `rationale`, then link
+the capability heading in `product.md`.

package/skills/ultra-research/references/22-success-metrics.md

@@ -22,7 +22,7 @@ must be recorded as a gap or explicit future change.
 
 Complete the step with evidence references and the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `metric`. Record `definition`, `source`, `window`, `owner`, and
-`decision_use`.
+In the area report, record `definition`, `source`, `window`, `owner`, and
+`decision_use`, then link the metric heading in `product.md`.

package/skills/ultra-research/references/30-architecture-context.md

@@ -24,7 +24,7 @@ the current checkout contradicts an existing diagram or claim.
 
 Complete the step with source or runtime evidence and the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `architecture_context`. Record `boundary`, `inputs_outputs`,
-`trust_authority`, and `consumers`.
+In the area report, record `boundary`, `inputs_outputs`, `trust_authority`, and
+`consumers`, then link the architecture heading.

package/skills/ultra-research/references/31-solution-strategy.md

@@ -22,7 +22,7 @@ unresolved decisions as blockers rather than selecting on the owner's behalf.
 
 Complete the step with decision evidence and the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `architecture_decision`. Record `drivers`, `direction`, `consequences`,
-`compatibility`, and `recovery`.
+In the area report, record `drivers`, `direction`, `consequences`, `compatibility`, and
+`recovery`, then link the decision file or architecture heading.

package/skills/ultra-research/references/32-building-blocks.md

@@ -22,7 +22,7 @@ runtime paths, error paths, and evidence. Link each proposed block to a consumer
 
 Complete the step with source evidence and the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `runtime_path`. Record `entry_point`, `state_side_effects`,
-`observable_result`, `failure_recovery`, and `consumers`.
+In the area report, record `entry_point`, `state_side_effects`, `observable_result`,
+`failure_recovery`, and `consumers`, then link the architecture heading.

package/skills/ultra-research/references/40-deployment.md

@@ -23,7 +23,7 @@ unknowns.
 
 Complete the step with file, runtime, or provider evidence and the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `deployment`. Record `environment`, `entry_point`, `config_migration`,
-`observation`, and `rollback_recovery`.
+In the area report, record `environment`, `entry_point`, `config_migration`,
+`observation`, and `rollback_recovery`, then link the architecture heading.

package/skills/ultra-research/references/41-quality-risks.md

@@ -22,7 +22,7 @@ verification, recovery, technical debt, and architecture decisions where needed.
 
 Complete the step with evidence references and the updated output path.
 
-## Semantic record
+## Report trace
 
-Use kind `risk`. Record `trigger_condition`, `expected_response`, `measurement`,
-`mitigation`, `recovery`, and `owner`.
+In the area report, record `trigger_condition`, `expected_response`, `measurement`,
+`mitigation`, `recovery`, and `owner`, then link the risk heading or decision file.

package/skills/ultra-research/references/99-synthesis.md

@@ -24,12 +24,12 @@ Write `research-distillate.md` as a navigation and traceability artifact contain
 baseline ids, source document anchors, accepted decisions, blockers, gaps, verification
 evidence, and the exact planning entry. Do not duplicate the specifications' prose.
 
-Write the immutable `99-synthesis` step report, then complete the step with that report,
-all three baseline specification paths, the distillate path, and the evidence used for
-the synthesis. Read the completed workflow back before baseline convergence.
+Write the final `99-synthesis.md` report, link all three specification paths, the
+distillate path, and the evidence used for synthesis. Read those files back before
+reporting convergence.
 
-## Semantic record
+## Report trace
 
-Use kind `synthesis_trace`. Record one verified chain through `problem_id`,
-`scenario_id`, `requirement_ids`, `architecture_path_ids`, and `verification_refs`.
-Every referenced id must exist in an earlier selected step.
+Record one verified chain through `problem_id`, `scenario_id`, `requirement_ids`,
+`architecture_path_ids`, and `verification_refs`. Every referenced id must exist in an
+earlier selected area report or specification heading.

package/skills/ultra-review/SKILL.md

@@ -1,46 +1,73 @@
 ---
 name: ultra-review
-description: Independently review one current Ultra plan, task diff, or aggregate Change on specification fidelity and engineering standards. Use when current evidence needs review or focused risk analysis.
+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.
 ---
 
-# Review one bounded scope
+# Review through six lenses without polluting the main context
 
-Keep two independent verdict axes:
+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.
 
-- `spec_fidelity`: accepted intent, behavior, docs, and public seams;
-- `engineering_standards`: correctness, safety, tests, integration,
-  maintainability, observability, and recovery.
+## Before you start
 
-## Bind and review
+1. Read `.ultra/tasks.json`, the scoped task's `context_file` and `## Resume Note`.
+2. Read `CONTEXT.md`, relevant `.ultra/decisions/`, acceptance, evidence and exact diff.
+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.
 
-1. Read `references/review-modes.md`.
-2. Call `ultra.context { stage: review, scope: { change_id, task_id? }, detail: full }`.
-3. Import a newer team checkpoint with `ultra.sync`; stop on a real conflict.
-4. Bind one explicit diff or Plan, full HEAD, worktree digest, task set, acceptance,
-   decisions, and current evidence. Empty or stale scope cannot pass.
-5. Always run `review-spec`. Select the smallest engineering worker set that covers
-   actual risk; record selected and excluded roles with rationale.
+## Definition of done
 
-Use the current host's native bounded-worker mechanism. Workers are read-only and
-receive one immutable Worker Packet containing the exact Context Envelope, HEAD/diff,
-decisions, acceptance, output path/schema, and `packet_digest`. Validate their artifacts with `scripts/review_wait.py` and
-`references/unified-schema.md`; reject any output that does not echo the exact packet
-digest. Preserve every finding unchanged in `SUMMARY.json`; group duplicates only in
-the human summary.
+- 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.
+- Findings preserve independent `spec_fidelity` and `engineering_standards` axes.
+- Refactors are justified by observed duplication or coupling and all affected checks rerun.
 
-Register specialist and summary artifacts through one `ultra.record` batch using
-`artifact / bind`.
+## Run the lenses
 
-## Checkpoint
+Use the host's native bounded subagents, in the background where available; otherwise
+run them sequentially. `review-spec` is always selected; select other lenses only when
+their evidence can change a verdict. Give each the packet path and digest,
+`references/unified-schema.md`, and exactly one lens:
 
-Call `ultra.checkpoint` once with `stage: review`, exact scope, evidence, and outputs
-tagged `spec_review`, `engineering_review`, or summary. The model and bounded review
-agents own both evidence-derived axes. The checkpoint compiles or reuses review
-context, verifies declared artifact bytes and digests, and records the supplied axes
-without overriding findings.
+- `references/code.md`
+- `references/design.md`
+- `references/errors.md`
+- `references/tests.md`
+- `references/spec.md`
+- `references/comments.md`
 
-A rejected checkpoint leaves the draft mutable. Fix the structural, digest, path, or
-concurrency fault and retry; do not open a replacement run or suppress a finding.
+Apply **Zero Context Pollution**: start the workers, immediately run
+`scripts/review_wait.py <session> agents --packet-digest <digest> <selected-stems>`,
+then read only the stable JSON files it returns. Validate `SUMMARY.json` with
+`scripts/review_wait.py <session> summary --packet-digest <digest>`. Do not read
+intermediate worker output or treat background notifications as completion. The sole
+information path is wait script to JSON artifact. These guards prevent partial results
+from becoming a semantic verdict.
 
-Return both axes, findings, reviewed scope, worker rationale, digests, and the model's
-recommended next explicit capability. Do not invoke it automatically.
+## 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.
+
+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.
+
+Report both axes, exact scope, checks, residual findings and any refactor performed.
+
+## When the owner decides
+
+The owner chooses risk acceptance, a scope reduction, or which stuck path to take.
+Workers never edit source, task state or another lens artifact.
+
+## References
+
+- `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.
+- `../ultra-think/references/autonomy-boundary.md` — read before a fix reduces intent.

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

@@ -0,0 +1,17 @@
+# Code lens
+
+Review the exact diff plus only the callers, contracts, tests and configuration needed
+to establish a finding. Trace changed behavior from a production entry point to its
+consumer. Check correctness, trust boundaries, state consistency, recovery,
+observability, compatibility and reachability.
+
+Resolve the exact HEAD, range, intended outcome, and repository guidance from the
+Worker Packet. Report an empty or ambiguous scope instead of expanding it silently.
+Trace each candidate through entry point, state, side effect, failure and real consumer;
+discard it if no plausible trigger and observable impact survive that trace.
+
+Report only evidence-backed defects with a plausible trigger and concrete impact.
+Deduplicate by root cause, keep line ranges tight, and propose the smallest complete
+repair. Use `axis: engineering_standards` and the shared findings schema.
+
+The worker is read-only. Its only write is the assigned JSON artifact.

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

@@ -0,0 +1,12 @@
+# Comments lens
+
+Inspect changed comments, docstrings, examples, annotations and API documentation
+against the associated implementation and public contract. Report factual
+contradictions, stale names or behavior, unsafe operational advice, and an omission
+only when it makes a public or non-obvious contract materially misleading.
+
+TODO, FIXME, HACK and implementation narration are evidence to investigate, not
+automatic defects. Ignore wording preferences and harmless redundancy. Use `axis:
+engineering_standards`, category `comments`, and the shared findings schema.
+
+The worker is read-only. Its only write is the assigned JSON artifact.

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

@@ -0,0 +1,12 @@
+# Design lens
+
+Trace changed types and modules through constructors, callers, state, side effects and
+consumers. Look for bypassable invariants, ambiguous ownership, leaking boundaries and
+coupling that makes an accepted change unsafe.
+
+Treat length, nesting, parameter count and primitive data as investigation signals,
+not defects. Report complexity only when it creates a concrete correctness, testing,
+recovery or maintenance cost. Prefer a focused before/after repair over a speculative
+framework. Use `axis: engineering_standards` and the shared findings schema.
+
+The worker is read-only. Its only write is the assigned JSON artifact.

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

@@ -0,0 +1,13 @@
+# Error lens
+
+Trace changed exceptions, error results, retries, fallbacks, cancellation, timeouts and
+asynchronous work from trigger to caller-visible state. Find swallowed required
+failures, false success, lost diagnostic context, unsafe retry, sensitive detail leaks
+and inconsistent recovery state.
+
+Confirm the language and framework propagation contract before reporting. Empty
+catches, null fallbacks, optional chaining, fire-and-forget work and generic messages
+are signals only. Severity follows reachable impact. Use `axis:
+engineering_standards` and the shared findings schema.
+
+The worker is read-only. Its only write is the assigned JSON artifact.

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

@@ -0,0 +1,13 @@
+# Specification lens
+
+Keep this axis independent from general engineering quality. Map every accepted
+criterion to current executable or source evidence. Check for omitted behavior,
+unintended scope, stale specification or operational documentation, and incompatible
+public contracts.
+
+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
+the shared findings schema.
+
+The worker is read-only. Its only write is the assigned JSON artifact.

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

@@ -0,0 +1,12 @@
+# Test lens
+
+Map each changed behavior and acceptance claim to executable evidence. Check the
+functional, persistence, protocol, UI and failure boundaries material to this diff.
+Inspect doubles for contract fidelity: report one only when it bypasses the behavior
+under review or diverges from production semantics.
+
+Find missing state transitions, ineffective assertions, hidden skips, flaky
+assumptions and tests that never reach changed code. Calibrate severity to escaped
+product risk. Use `axis: engineering_standards` and the shared findings schema.
+
+The worker is read-only. Its only write is the assigned JSON artifact.

package/skills/ultra-review/references/worker-packet.md

@@ -0,0 +1,40 @@
+# Immutable Worker Packet
+
+Create `.ultra/reviews/<session>/WORKER-PACKET.json` once, before starting any lens.
+Serialize it as UTF-8 JSON with a trailing newline, compute SHA-256 over those exact
+bytes, and never edit the file. A changed scope requires a new session and packet.
+
+```json
+{
+  "$schema": "ultra-review-worker-packet-v1",
+  "session": "<session-id>",
+  "mode": "task | change | plan",
+  "created_at": "<ISO-8601>",
+  "head": "<full-git-head>",
+  "range": "<exact-diff-range>",
+  "change_id": "<active-change-id>",
+  "task_ids": ["<task-id>"],
+  "acceptance": ["<criterion with source path and heading>"],
+  "public_seams": ["<entry point or behavior>"],
+  "context_files": [
+    {"path": ".ultra/contexts/<task-id>.md", "sha256": "<digest>"}
+  ],
+  "diff_files": ["src/example.ts"],
+  "output_directory": ".ultra/reviews/<session>"
+}
+```
+
+All paths are repository-relative. `mode`, `head`, `range`, `change_id`, `task_ids`,
+`acceptance`, `public_seams`, `context_files`, `diff_files`, and `output_directory` are
+required. Arrays may be empty only when the selected mode makes the absence explicit
+in the packet.
+
+Give a selected worker only:
+
+1. this packet path and exact digest;
+2. `unified-schema.md`;
+3. its one lens reference.
+
+The worker writes only its assigned JSON artifact. Its `packet_digest` must equal the
+expected digest passed to `review_wait.py`; a merely well-formed digest is insufficient.
+The coordinator owns worker selection, synthesis, repair, and the summary.