review-tests

Review test case completeness against source code via Codex (round-continuing under the 2+1 cap: address gaps and re-run).

Procedure

Note: the Stop-guard silence during dispatch is automatic (PostToolUse marks the step in_progress). Do not emit NEXT_STEP_PAUSE.

Read rules/shell-commands.md before the first Bash command, or before writing a file — defensive measure: RT-2's incident showed the rule content was not effectively available at Bash-issuance time in this context: fork execution. Follow the rules/shell-commands.md Subagent Dispatch Prompts section as if this fork were a dispatched subagent, including its Command-form deviations report.

RT-0. Resolve the session-bound linked worktree path in two separate standalone Bash commands — never combined with variable-capture syntax on the Bash tool's own command line, per rules/shell-commands.md. RT-0 session-id call: run bash "$AGENTS_MAIN_ROOT/bin/resolve-session-id"; its stdout is the CC session id. RT-0 session-id call exit 2 (stdout empty, stderr session id unresolvable): omit --session and run the worktree-path call anyway. RT-0 session-id call any other non-zero exit (3 = resolver fault, 127 = node absent): HALT and surface its stderr; do not run the worktree-path call — rc 3 is a fault, not "no session". RT-0 worktree-path call: run bash "$AGENTS_MAIN_ROOT/bin/resolve-worktree-path" --session <value from the session-id call>; its stdout is WORKTREE for later steps. RT-0 worktree-path call exit 2 (malformed --session value — a transcription error): HALT; never fall through to a different session. If the worktree-path call's stdout is empty after an omitted --session, RT-0 skips: the review target cannot be identified. If WORKTREE == "NOSTATE", treat WORKTREE as empty — the internal scripts handle the CWD-fallback path for that case. Pass each script path to bash as its argument, keeping bash itself in execution position — a bare quoted path there is a shell variable in execution position, the shape the permission engine's allow rules never match. Pass it no arguments other than --session <value>. Use no environment-variable prefix on either invocation. Use no command chaining: no &&, no ; and no | on those command lines — per rules/shell-commands.md. Inspect an exit code, if needed, in a separate, subsequent command. RT-0a. Read:

• rules/core-principles.md
• rules/test.md — on-demand-only; never auto-injected, so this Read is mandatory
• skills/_shared/test-design.md
• skills/_shared/test-design/protection-fix-tests.md — additionally, for security / guard / classifier fix targets
• skills/_shared/test-design/parser-regex-tests.md — additionally, for parser / regex / allowlist targets RT-1. Identify staged test file(s) and source file(s):
• Run bash "$AGENTS_MAIN_ROOT/skills/review-tests/scripts/select-staged-files.sh" (Bash, single standalone command); its stdout is STAGED.
• If exit 3 (linked worktree unresolvable): do NOT fall back to cwd; present "Could not identify the linked worktree. Re-run /review-tests from the linked worktree, or specify the test and source files manually." and ask the user for the files.
• If exit 4 (bin/resolve-session-id faulted): HALT, surface the script's stderr, and do NOT ask for a manual file.
• Select test file(s) and source file(s) from $STAGED or from the user's manual input. RT-1a. Check each newly added test file for a missed append target:
• Run bash "$AGENTS_MAIN_ROOT/skills/review-tests/scripts/select-staged-files.sh" --added-only (Bash, single standalone command); its stdout is ADDED. Exit 3 / exit 4 are handled exactly as in RT-1.
• Collect every ADDED entry under tests/ and pass them all to one call of bash "$AGENTS_MAIN_ROOT/bin/find-tests-for-source.sh" --with-language --test-file <path> --root <WORKTREE>, repeating --test-file per entry (Bash, standalone command with timeout 600000; split rule and language columns in skills/_shared/test-design/append-vs-new.md; omit --root when WORKTREE is empty). On exit 4 or a tool timeout, HALT and surface the stderr. The helper itself returns skipped/not-top-level for nested part files — do not pre-filter by eye.
• The gap predicate is the row's viable column alone, never the verdict column: a non-- viable column means an append target under the HARD limit existed for this file's # Tests: set.
• A non-- viable column is a high-tier gap "append candidate existed but a new file was created". A # Tags: dup-group-keep:size-hard-limit does NOT waive it — the same row disproves the tag by showing a sub-HARD target. No dup-group-keep:<reason> value waives anything; the only escape is the WARNINGS_ACCEPTED sentinel.
• Validate the tag's claim, not its presence: when the file's # Tags: carries dup-group-keep:size-hard-limit, the row corroborates it only if excluded is non-- and reason is size-hard-limit. A tag on a row with excluded = - (reason=no-candidate — no append candidate ever existed) is an unvalidated opt-out: report it at the same high tier as a missed append target.
• Feed the gaps into RT-3's review input and count them in RT-5c. RT-1b. Check new test files for missing case markers (deterministic gate, no codex review needed):
• For each file in ADDED that lives under tests/, run bash "$AGENTS_MAIN_ROOT/bin/check-case-markers.sh" <file> (Bash, one standalone command per file).
• Any HIGH: output line is a high-tier gap "multi-path Tests: header with missing or malformed case markers" (notation: the language's registry notationDoc).
• These gaps are deterministic — do not feed them into RT-3 codex input. Count them directly in RT-5c.
• If any RT-1b violations exist, RT-5 must emit WARNINGS regardless of codex exit code. RT-2. Select the review scope: run node "$AGENTS_MAIN_ROOT/bin/select-review-scope.js" --session <CC session id> --worktree <WORKTREE-or-empty> as one standalone command; exit 4 → HALT and surface its stderr. Assemble review input via the Write tool only into <PLANS_DIR>/<session-id>-test-review.md as four separate sections: ## Review targets (each REVIEW absolute path with its contents), ## Deleted tests (paths only, do not Read) (DELETED), ## Test inventory (paths only) (INVENTORY), ## Sources (SOURCE contents). Do not substitute Bash-based assembly for the Write tool call in RT-2 — see rules/shell-commands.md Tool Selection Priority for what counts as shell-based writing. Resolve <PLANS_DIR> via skills/_shared/resolve-plans-dir.md. Initialize EXTENSIONS_USED=0. Show the user SCOPE and REASON in one line. RT-3. Invoke "$AGENTS_MAIN_ROOT/skills/review-tests/scripts/run-codex-review-loop.sh" (Bash), exporting AGENTS_MAIN_ROOT, SESSION_ID (plan-artifact prefix), PLANS_DIR, EXTENSIONS_USED. The wrapper auto-adds --context test-design.md. CTX_CONCERNS_LOG is auto-generated by the wrapper from the ledger (concern-ledger render-concerns-log, format test-review) and auto-exported when non-empty — do not set it manually (#2185). Exit-code handling (SSOT: skills/_shared/codex-review-loop.md; round-continuing under the 2+1 cap):
• exit 0 APPROVED → RT-5 COMPLETE.
• exit 1 NEEDS_REVISION → save stdout to <PLANS_DIR>/<session-id>-test-review-codex-round-<N>-raw.md (<N> from <CONTROL_DIR>/test-review-last-round.txt, <CONTROL_DIR> = node "$AGENTS_MAIN_ROOT/bin/workflow-control-dir" --session <session-id>); present gaps; suggest specific test cases → RT-5 WARNINGS. WARNINGS is blocking: address the gaps, re-stage tests, and re-run /review-tests — the round counter survives, so the re-run is counted as the next round.
• exit 2 ESCALATE → run review-loop-summarize-concerns --budget-remaining 0; present summary → RT-5 WARNINGS.
• exit 6 HIGH_UNRESOLVED → save stdout to <PLANS_DIR>/<session-id>-test-review-codex-round-<N>-raw.md (<N> from <CONTROL_DIR>/test-review-last-round.txt); run review-loop-summarize-concerns --budget-remaining 0; present unresolved HIGH concerns → RT-5 WARNINGS (do not emit WORKFLOW_REVIEW_TESTS_COMPLETE). Re-run only after accepting per exit-codes.md "Escalation by format".
• Exits 2 and 6 are terminal: after RT-5 WARNINGS, do NOT re-invoke write-tests or re-run /review-tests — accept remaining gaps via echo "<<WORKFLOW_REVIEW_TESTS_WARNINGS_ACCEPTED: {reason}>>" or address them in a new session.
• After a terminal exit (rc 2 or 6), WORKFLOW_REVIEW_TESTS_WARNINGS_ACCEPTED also restores an in_progress review_tests to complete.
• exit 8 → terminal guard was previously armed (review scope unchanged since last terminal); HALT.
• exit 9 → HALT; accept per exit-codes.md "Escalation by format" (sentinel = write-code unblock + guard clear + in_progress terminal record restored to complete; bin/accept-exit6-residual = guard clear only), then re-run.
• exit 3 → silently launch test-reviewer subagent with model: = the model= line of node "$AGENTS_MAIN_ROOT/bin/resolve-role-model" --role reviewer; its dispatch prompt says: Read and follow rules/shell-commands.md before the first Bash command. APPROVED → RT-5 COMPLETE; NEEDS_REVISION → RT-5 WARNINGS. That prompt also carries the canonical line of the rules/shell-commands.md Subagent Dispatch Prompts section. Save the subagent output via the Write tool to <PLANS_DIR>/<session-id>-test-review-fallback-raw.md, then run bash "$AGENTS_MAIN_ROOT/skills/review-tests/scripts/detect-input-error.sh" <that file> as one standalone command; exit 4 (INPUT_ERROR <path>) → HALT like exit 4, emit no sentinel.
• exit 4 → HALT with blocking error; surface wrapper stderr; do NOT launch fallback; do NOT emit sentinel.
• exit 5 AUTO_EXTEND → same as exit 1 (gaps remain within the extension budget): present gaps → RT-5 WARNINGS; address and re-run.
• exit 7 FINALIZE_FAILED → <CONTROL_DIR>/test-review-unresolved-concerns.json could not be written; HALT, surface the ## Concern Ledger: FINALIZE-FAILED line, launch no fallback, emit no sentinel. After an ESCALATE, confirm the artifact with bash "$AGENTS_MAIN_ROOT/bin/concern-ledger" check-finalized --plans-dir <PLANS_DIR> --session-id <session-id> --format test-review before RT-5. RT-4. Triage the concerns against skills/_shared/priority-hierarchy.md before emitting the sentinel: a concern that contradicts an approved intent.md / outline.md / detail.md decision — including a documented TL3 gap or a deferral to manual verification — is rejected, not a gap. State each rejection and the decision it rests on, and exclude it from the RT-5c warnings count. Skip on exit 0 (no concerns). For each rejected concern, record the verdict durably so it does not re-surface next round: bash "$AGENTS_MAIN_ROOT/bin/concern-ledger" reject --plans-dir <PLANS_DIR> --session-id <session-id> --format test-review --id C<N> --reason "<cited decision>" (#2185). RT-5. Emit workflow sentinel — two separate Bash calls, not chained: RT-5a. Run node "$AGENTS_MAIN_ROOT/bin/compute-review-scope-fingerprint.js" "<WORKTREE-or-empty>" (Bash, single standalone command, <WORKTREE-or-empty> substituted with RT-0's resolved value); its stdout is FINGERPRINT. Non-zero exit → HALT, surface its stderr, emit no sentinel.
• RT-5b. (adequate) echo "<<WORKFLOW_REVIEW_TESTS_COMPLETE: fingerprint=${FINGERPRINT}>>"
• RT-5c. (gaps/warnings) echo "<<WORKFLOW_REVIEW_TESTS_WARNINGS: fingerprint=${FINGERPRINT} warnings=N — blocking: /write-code stays blocked until the gaps are addressed and /review-tests is re-run>>"
• RT-5d. Skip when WORKFLOW_WRITE_TESTS_NOT_NEEDED was emitted (propagated skip).