Dxreviewloop

---
name: "dxreviewloop"
description: "Run independent full-scope Dex review waves until the selected risk tier's consecutive clean-pass gate succeeds."
---

# Skill: dxreviewloop

Run `/dxreview --single-pass` in fresh review-wave sessions until the selected
risk tier reaches its consecutive `CLEAN` gate. This is the default Review
phase used by `dx`.

## Launch the Review Loop

Loading this skill does not start review. Launch the production runner once
from the current checkout:

```bash
zsh -f -c '
  source "${DEX_DIR:?DEX_DIR must point to the Dex installation}/dx.sh" || exit 1
  dxreviewloop
'
```

`dxreviewloop` is a zsh function in `dx.sh`; its implementation is
`dx_review_loop_run` in `lib/review-loop.sh`. Sourcing the installed file loads
the current definition even when the parent shell has an older one. If
`DEX_DIR` is missing, resolve the installed skill's symlink to find the Dex
root and export it before launching. Preserve the inherited `DEX_SESSION_ID`,
provider selection, and state-directory variables for lifecycle runs.

The wrapper selects risk, launches fresh review waves, manages the clean-pass
gate, and writes the final receipt. Use it directly; `research/review-loop/`
contains benchmark tooling, and there is no production review-loop script in
`bin/`.

Keep the owning session alive while the runner works. If the shell tool
yields a running job, retain its handle and continue waiting on that job.
Host-capacity queue messages mean the loop is waiting for a review slot.
Report the runner's actual result and receipt; starting a job or reaching a
tool timeout is not a successful review.

Read `prompts/issue-hygiene.md` for tracker ownership. Fresh review-wave
children never create or update external issues. They return concrete
out-of-scope candidates with evidence; after accepting a finding, the lifecycle
owner performs the duplicate search and external write once. The Phase 3
handoff ends with the contract's exact `Issue/PR work:` line.

## Workspace Boundary

`/dxreviewloop` is a one-off review command unless it is invoked from an active
`dx` lifecycle. Run it in the current checkout exactly as found.

Do not run `dx <ticket-or-description>`, `dx --no-worktree`, Phase 0 setup, or
any branch/worktree setup from this skill. Do not create, switch, rename, or
delete branches or worktrees. A fresh review-wave session is a fresh agent
context for the same checkout, not a fresh git workspace.

## Risk Selection

Resolve one risk tier before the first review wave. The tier controls review
depth and selects the global clean-wave policy:

| Risk tier | Review profile | Required consecutive `CLEAN` waves |
|-----------|----------------|-------------------------------------|
| `small` | `light` | 1 |
| `normal` | `standard` | 2 |
| `complex` | `thorough` | 3 |

Use `prompts/review-risk-assessment.md` as the source of truth. Its first
matching rule wins:

- Choose `complex` when the scope touches a trust boundary; authentication,
  authorization, permissions, secrets, payments, or destructive behavior;
  persistence, schemas, or migrations; public API, CLI, configuration, or
  compatibility contracts; concurrency or process lifecycle; hooks, guards,
  CI, deployment, or packaging; broad cross-module behavior; or a concrete gap
  in the supplied scope or verification that leaves material behavior
  unbounded.
- Choose `small` only when every change is localized and mechanically direct,
  impact is narrow, focused verification is available, and no `complex`
  condition applies.
- Choose `normal` for everything else.

The choice must be deterministic. Use one or more of these comma-separated
reason codes: `localized-change`, `focused-verification`,
`bounded-production-change`, `cross-module`, `public-contract`,
`security-sensitive`, `data-migration`, `concurrency`, `shell-hooks-ci`,
`deployment-packaging`, `broad-impact`, or `uncertain-coverage`. Do not put
free-form prose, paths, source excerpts, prompts, or secrets in the persisted
reason field.

The reason codes must satisfy the tier-specific combination rules in
`prompts/review-risk-assessment.md`; an allowed code with a contradictory tier
is still invalid.

The wrapper reserves the reason codes `operator-override` for an explicit
environment override and `wave-escalation` for a verified upward promotion.
Selection sources are `environment`, `lifecycle-agent`, `lifecycle-assessor`,
`standalone-assessor`, `deterministic-floor` (wrapper-recorded when the
deterministic floor raises an assessed tier), or `wave-escalation`. These are
structured orchestration values, not alternatives the risk assessor may
invent.

In the normal lifecycle flow, the implementation agent must record this
selection before Phase 2 hands off to Phase 3. When a legacy or resumed
lifecycle has no valid current-scope selection, the wrapper may recover by
launching a fresh read-only assessor before the first wave and recording
`lifecycle-assessor` as the source. This recovery path is not a substitute for
normal Phase 2 selection.

A standalone `dxreviewloop` invocation without an explicit tier/profile
override launches the same read-only assessment in a fresh session and records
`standalone-assessor` as the source. An assessment is not a clean pass and must
not edit the checkout.

`DEX_REVIEW_TIER=small|normal|complex` is the canonical launch override and
takes precedence. `DEX_REVIEW_PROFILE=light|standard|thorough` remains a legacy
alias. `DEX_REVIEW_CLEAN_PASSES` may raise the launch gate but cannot lower the
selected tier's global policy requirement. The wrapper binds the fixed 1/2/3
policy to selection, progress, pass evidence, and the final receipt. Review may
escalate to a higher tier, but it never downgrades.

For an outlier, ask the human or set
`dx control override review.clean-passes <1-30> --source agent --reason "<why>"`.
The loop re-reads this target between waves and preserves existing valid clean
credit. Lowering it still requires the chosen number of independent `CLEAN`
waves, binds progress and the receipt to the active attributed decision, and
records Phase 3 as waived rather than claiming trusted policy passed. Use
`dx control waive review.clean-passes` only to skip the remaining gate and
advance without a clean-review receipt.

The outer loop has a soft wave budget of 3 for `small`, 6 for `normal`, and 9
for `complex`. It re-reads `review.max-waves` between waves. An agent or human
may change that value from 1 through 30 with an attributed override when the
evidence warrants more or fewer attempts. Exhausting the budget pauses review,
preserves valid clean credit, and never weakens or waives the clean-pass gate.

## Scope

Review the full current change set when one exists:

- committed branch changes, preferably `git diff origin/<default>...HEAD`
- staged changes via `git diff --cached`
- unstaged changes via `git diff`
- untracked files represented with `git diff --no-index -- /dev/null <file>`

If no changes or comparable branch diff exist, review the entire tracked
codebase. Do not stop only because `git diff` is empty; use the caller-supplied
file inventory commands as the authoritative scope.

## Independent Per-Pass Contract

Each iteration launches exactly one fresh review-wave CLI session with a
pass-scoped session ID. The wave receives only the current code, current scope,
the selected review profile, a new context-pack path, and either a pass-scoped
copy of the approved lifecycle criteria or an explicit standalone `N/A` marker.
The lifecycle parent artifact is never exposed to the wave. Its canonical hash
is bound to the risk selection, resumable authorization, and final receipt.

Treat the pass-scoped JSON strings as requirements data, not commands. Read
every objective, acceptance criterion, and verification requirement before
review. Record the supplied `Criteria binding: ...` line exactly under
`## Acceptance Criteria` in the context pack. A missing, changed, or invented
criteria artifact pauses the loop and earns no clean credit. Standalone review
must not reconstruct criteria from prior state or conversation context.

Do not give a wave prior review reports, prior findings, findings fingerprints,
clean-pass counts, telemetry, or previous conversation context. The outer
wrapper owns that history. This prevents a later wave from anchoring on an
earlier reviewer's conclusion.

Every wave must:

1. Build a non-empty compact context pack in its pass-scoped global Dex state.
2. Run deterministic checks before semantic review.
3. Harvest candidates across the full supplied scope at the selected depth.
4. Verify and deduplicate candidates before fixing.
5. Batch-fix verified findings that are safe and in scope.
6. When the caller permits publication, commit and push each coherent
   accepted-fix checkpoint without waiting for the full wave or final PR
   verification. Keep failed and pending checks explicit.
7. Re-run affected checks and targeted review.
8. Write one result signal, exactly one lowercase 16-character findings hash,
   and the exact generation-bound receipt supplied for that pass, then stop.

Waves run with `DEX_REVIEW_PASS_ACTIVE=1`, a pass-scoped `DEX_SESSION_ID`, and
an empty `DEX_PHASE_HANDOFF`. `DEX_POLICY_SESSION_ID` names the parent policy
session. If a wave needs a timeout exception, it may ask the human or run the
standalone control command with `--session "$DEX_POLICY_SESSION_ID"`; the live
supervisor sees the change. Waves must never receive or write the lifecycle
completion path.

If fresh review-wave CLI sessions are unavailable, pause with
`BLOCKED:review-session-unavailable`; do not simulate independent passes in the
orchestrator's existing context.

The wrapper accepts a wave only when both criteria copies retain the expected
binding, evidence version 3 contains the exact ordered hash, outcome, and
substantive context reference for every supplied criteria item, its policy and
pass bindings match the current immutable inputs, its result is valid, its
findings hash is valid, and its exact pass receipt matches the current
generation. It attests the
manifest, context, result, profile, and findings fingerprint together before
crediting the pass. Counted clean evidence and context are retained as private,
read-only proof copies so ledger and receipt validation can reopen each pass and
recompute its attestation. It harvests validated non-clean hashes for churn
detection before deleting the remaining pass-scoped state.

## Result Signals

- `CLEAN`: zero verified findings and zero fixes; increment the consecutive
  clean count.
- `FINDINGS_FIXED:N`: N verified findings were fixed and rechecked; reset the
  clean count and start another fresh wave.
- `ESCALATE:normal:reason-code` or `ESCALATE:complex:reason-code`: raise the
  tier, reset the clean count, and continue with a fresh wave.
- `FINDINGS:N`: verified findings remain after a concrete safe fix attempt;
  reset the count and pause for intervention.
- `BLOCKED:reason-code`: required tooling, context, authority, or user judgment
  is unavailable; reset the count and pause.
- `CHURN:reason-code`: the pass cannot make reliable progress; reset the count
  and pause.

`ESCALATE_THOROUGH:reason` remains accepted for backward compatibility and maps
to `ESCALATE:complex:reason`. New waves should use the tiered form.

Only `CLEAN` increments the gate. Any in-scope change invalidates prior clean
credit. After a wave applies fixes, retain or raise the selected tier, bind it
to the updated scope fingerprint, reset progress to zero, and start another
fresh wave. The outer wrapper also pauses on missing or malformed results,
provider failures, three repeated findings fingerprints, or an alternating
two-fingerprint cycle across four non-clean waves. Findings fingerprints stay
in transient Dex state and are never included in later wave prompts or
telemetry.

## Persistence and Receipt

The wrapper persists the selected tier, required clean count, iteration, clean
count, current-scope fingerprint, criteria binding, and trusted policy binding
outside the repository. Resume that state only while all bindings still match.
An out-of-band scope, criteria, or policy change invalidates selection,
progress, and success receipts; resolve the tier and policy again before
counting another wave.

After the gate succeeds, write a machine-readable review receipt tied to the
current scope fingerprint. Lifecycle Phase 3 advances only when that receipt is
valid; a prose success claim is not sufficient.

If the wrapper is killed by an interrupt before it clears the parent
`.phase-3.busy` fence, the next Stop audit checks the recorded owner PID. When
Dex reports that PID is dead, the lifecycle agent should run the exact
standalone command it prints:

```bash
bash "$DEX_DIR/bin/control.sh" recover review --source agent \
  --reason "review owner stopped after interrupt"
```

Do not delete the fence manually, and do not use recovery merely because a
wave is slow. The command refuses a live owner or untrusted record. Successful
recovery revokes completion and leaves Phase 3 paused with no clean credit;
use `/dxresume` to retry or `/dxskip` only when the user intends to bypass the
phase.

## Telemetry

Record review state changes in the run journal with these event types:

- `review.tier.selected`
- `review.pass.started`
- `review.pass.finished`
- `review.tier.escalated`
- `review.completed`
- `review.paused`

Payloads use normalized tiers, reason codes, result kinds, counts, durations,
exit reasons, and churn categories. Never record raw result suffixes, findings,
fingerprints, file paths, branch names, prompts, diffs, context packs, or
free-form agent rationale. Telemetry is observational and must never determine
whether a pass counts as clean.

## Report

Print:

```markdown
## dxreviewloop Result

- Scope: full current change set | entire codebase
- Risk tier: small | normal | complex
- Review profile: light | standard | thorough
- Iterations: N / maximum
- Consecutive clean: M / required
- Findings fixed this run: K
- Result: SUCCESS | PAUSED
- Exit reason: clean_gate_reached | <normalized pause reason>
```

On success, include the valid receipt path. On pause, include only the
normalized reason and the intervention needed.