Workflow Review Changes

Codex compatibility note:

• Invoke repository skills with $skill-name in Codex; this mirrored copy rewrites legacy Claude /skill-name references.
• Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
• User-question prompts mean to ask the user directly in Codex.
• Ignore Claude-specific mode-switch instructions when they appear.
• Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
• For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
• If a required step/tool cannot run in this environment, stop and ask the user before adapting.

Codex Project-Reference Loading (No Hooks)

Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.

Always read:

• docs/project-config.json (project-specific paths, commands, modules, and workflow/test settings)
• docs/project-reference/docs-index-reference.md (routes to the full docs/project-reference/* catalog)
• docs/project-reference/lessons.md (always-on guardrails and anti-patterns)

Missing/stale context route: If docs/project-config.json, the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any task-required reference doc is missing or stale, auto-run $project-init or the narrow setup route ($project-config, $docs-init, $scan-all, $scan --target=<key>, $claude-md-init) before ordinary project-specific work. If Codex mirrors or AGENTS.md are missing/stale, ask the user to run $sync-codex; do not auto-run it.

Situation-based docs:

• Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): project-structure-reference.md
• Backend/CQRS/API/domain/entity changes: backend-patterns-reference.md, domain-entities-reference.md
• Frontend/UI/styling/design-system: frontend-patterns-reference.md, scss-styling-guide.md, design-system/README.md
• Spec authoring, docs/specs/ pathing, or TC format: feature-spec-reference.md, spec-system-reference.md, spec-principles.md
• Behavior/public-contract changes or spec-test-code sync: workflow-spec-test-code-cycle-reference.md plus the spec docs above
• Derived spec indexes/ERDs/reimplementation guides: spec-system-reference.md and source Feature Specs under docs/specs/
• Integration test implementation/review: integration-test-reference.md
• E2E test implementation/review: e2e-test-reference.md
• Code review/audit work: code-review-rules.md plus domain docs above based on changed files

Do not read all docs blindly. Start from docs-index-reference.md, then open only relevant files for the task.

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Quick Summary

Goal: Ensure changed work reaches clean review through an initial whole-target adversarial pass run in parallel with dimensional review, validated findings, verified fixes, full re-review, and synchronized docs/tests — review all uncommitted changes, fix only validated findings, then repeat the plan→plan-execute→changes-review loop until a complete pass is clean.

Summary:

• Step 0 (FIRST ACTION, pre-sequence): bind the self-recursive review loop — an always-on protocol loop you self-drive (the BINDING mechanism, hook/command-independent) PLUS, when available, a /goal Stop-hook gate as an optional accelerator — so the review→self-fix→whole-diff-re-review loop is unabandonable until it converges to a clean pass at that round's bar (zero findings in rounds 1-2; zero CRITICAL/HIGH/MEDIUM from round 3) — why: a soft "loop until clean" directive gets rationalized away after one fix cycle, and the protocol loop holds even where /goal is absent. Session-level wrapper, NOT one of the 20 canonical steps. ALWAYS runs — including as a step inside a parent workflow — because this workflow always runs INLINE in the main session (never a sub-agent), so it owns the loop directly in every case.
• Initial parallel phase (steps 1–2, all-return barrier): launch step 2 $why-review --target=whole-review-target as a fresh read-only code-reviewer sub-agent, then immediately run step 1 $changes-review INLINE while it is active. Step 1 owns the dimensional baseline (surface analysis, integration-test/translation/spec-drift gaps, internal UI review); step 2 independently reviews the WHOLE review target + current changes in FULL mode. Neither consumes the other's output. Advance only after BOTH return, then consolidate both reports.
• Step 3 $why-review validates the step-1 $changes-review findings to drop false positives BEFORE the specialist batch fires. The initial whole-target step 2 already validates its own findings through $why-review's full-mode closing gate.
• Steps 4–10 ($architecture-review, $domain-entities-review [if entity files], $performance-review, $integration-test-review, $security-review, $production-readiness-review, $ui-review [if frontend files]) are read-only sub-agents: spawn ALL in ONE message and advance ONLY after every member returns (all-return barrier); the mutating $code-simplifier (step 11) waits until the barrier clears and self-reviews its own changes via $code-review. ($ui-review runs here as a DEDICATED conditional batch member AND still runs internally inside step 1's $changes-review — both by design; see the UI-review note below.)
• Fix cycle (steps 12–15 $plan→$plan-review→$plan-execute→$changes-review) runs ONLY when validated findings exist; the step-15 re-review runs ONLY if $plan-execute changed files, re-reading the full diff from scratch INLINE to counter orchestrator confirmation bias, and loops until the round's exit bar is clear — zero findings in rounds 1-2, zero CRITICAL/HIGH/MEDIUM from round 3 (a LOW-only round ENDS the loop, deferred not fixed) — bounded at 3 rounds MAX (escalate by asking the user directly at whichever trips first: 2 no-progress repeats of the same blocker, or round 3 completing with CRITICAL/HIGH/MEDIUM still open — cap exhaustion escalates, never PASSes).
• Step 16 $why-review (ALWAYS runs, FULL mode, standalone) — near-final HOLISTIC review of the settled WHOLE target + current changes as ONE artifact. It remains mandatory even though step 2 uses the same lens at startup: step 2 finds whole-package risks early; step 16 proves the final post-fix state. On findings → re-enter $plan→$plan-execute→$changes-review, then re-run step 16 until a full-mode pass finds zero new findings (bounded by $why-review's own review loop: max 2 re-dos / 3-repeat-blocker → escalate).
• $docs-update (step 18) ALWAYS runs and triages internally; SPEC-STALE drift verdicts from step 1 flow here to update the Feature Spec first — the workflow is NOT clean while any behavior-vs-spec divergence stays unadjudicated (green tests do not normalize drift).

Sequence: (Step 0 pre-sequence: bind self-recursive review loop — protocol loop always, /goal accelerator when available) → [initial parallel phase] $changes-review (INLINE; owns dimensional/UI baseline) + $why-review --target=whole-review-target (fresh read-only sub-agent; FULL mode over the whole target) → $why-review (validate step-1 findings) → [specialist parallel batch] $architecture-review + $domain-entities-review (if entity changes) + $performance-review + $integration-test-review + $security-review + $production-readiness-review + $ui-review (if frontend changes) → $code-simplifier → $plan → $plan-review → $plan-execute → $changes-review (conditional inline re-review) → **$why-review (final HOLISTIC full-mode review of the settled WHOLE target)** → $scan --target=domain-entities → $docs-update → $workflow-end → $watzup

Key Rules:

• MUST ATTENTION define success criteria before execution and loop until observable verification passes.

• MUST ATTENTION when creating/reviewing specs or tests, name Business Intent / Invariant Guarded or the protected business intent/invariant and ensure the test would fail if that intent breaks.

• MUST ATTENTION carry every unresolved finding or unaccepted risk into validation/fix planning; do not close until fixed or explicitly accepted.

• MUST ATTENTION include unresolved risk register, generated mirror drift, and spec/test/docs drift in the fresh review prompt when relevant.

• MUST ATTENTION launch the whole-target full-mode $why-review sub-agent before starting step 1 inline, then advance only after BOTH initial-phase members return; run step 3 $why-review --validate-findings on the step-1 findings before spawning the specialist reviewers.

• After $plan-execute applies validated fixes (and ONLY if $plan-execute changed files) → re-run $changes-review INLINE over the current full diff from the first phase; re-read the diff from scratch to counter orchestrator confirmation bias

• Main-agent re-review (with knowledge of its own fixes) is NOT sufficient — orchestrator-level confirmation bias

• PASS = one complete review pass finds zero blocking issues after all validated fixes and verification are included

• Repeated blockers are tracked in conversation context; stop after 2 no-progress full invocations of the same blocker

First Principle — Easy to Change

The success metric of every coding decision is future change cost. DRY, SRP, abstraction, design patterns, naming, layering, tests — every technique exists to serve one goal: making the next change cheaper.

When evaluating code, a refactor, a test, or an abstraction, ask: does this make the next change cheaper or more expensive?

• Reject "best practices" that raise change cost (premature abstraction, speculative generality, leaky indirection, ceremony without payoff).
• Name the real enemies in findings: coupling, hidden state, duplicated knowledge, unclear intent, irreversible decisions exposed too early.
• A simpler design that is easy to change beats a sophisticated design that isn't.

Apply this lens before invoking any specific rule, pattern, or checklist below — if a downstream rule would raise change cost, this principle wins.

Step 0 — Bind the Self-Recursive Review Loop (FIRST ACTION — pre-sequence; protocol-first, /goal optional)

MUST ATTENTION: Before creating the 20 step tasks below, the VERY FIRST action is to BIND the self-recursive review loop so the session cannot end until the whole workflow loop converges to a clean zero-finding pass. Binding has TWO layers: (1) an always-on protocol loop you self-drive — the BINDING mechanism, hook/command-independent, in force on every host; and (2) an optional /goal accelerator — a mechanical Stop-hook block installed only WHEN the command is available. This is a session-level enforcement WRAPPER — NOT one of the 20 canonical workflows.json sequence steps, so it does NOT change the step count or the sequence; it makes the existing loop unabandonable.

Entry gate:

• ALWAYS run — whether this workflow is the top-level invocation (user ran $start-workflow workflow-review-changes or $changes-review routed here directly) OR a step inside a parent workflow (e.g. workflow-feature, workflow-bugfix, workflow-refactor). Because this workflow always runs INLINE in the main session (never as a sub-agent — see the WORKFLOW-IN-WORKFLOW note), it owns the session Stop hook directly in every case, so the loop binds and enforces identically. There is no "deferred to parent" case.

Procedure:

1. Protocol loop — ALWAYS binding (hook/command-independent). This is the mechanism that actually holds the loop shut; it binds Claude, Codex, and Copilot equally, whether or not /goal exists. You yourself MUST NOT stop until the condition below holds:

Run the initial parallel phase ($changes-review INLINE + $why-review --target=whole-review-target in a fresh sub-agent) to its all-return barrier → validate step-1 findings → run the specialist parallel reviewers + $code-simplifier → if validated findings exist, $plan → $plan-execute SELF-FIXES them → re-run $changes-review INLINE over the WHOLE current diff → loop until one complete pass clears the round's bar (rounds 1-2: zero findings; round 3+: zero CRITICAL/HIGH/MEDIUM, LOW-only ENDS the loop with the LOWs deferred) → run the final full-mode $why-review over the settled whole target → only then $docs-update → $workflow-end. Stop only when all required review passes are clean (or the same blocker repeats 3× with no progress → escalate by asking the user directly).

2. /goal command — invoke as an accelerator WHEN AVAILABLE. If /goal is registered and permitted on this host, invoke it (the actual built-in command) with the same condition to add a mechanical Stop-hook block on top of the protocol loop:

/goal workflow-review-changes self-recursive loop: run the initial parallel phase ($changes-review INLINE + $why-review --target=whole-review-target in a fresh sub-agent) to its all-return barrier → validate step-1 findings → run the specialist parallel reviewers + $code-simplifier → if validated findings exist, $plan → $plan-execute SELF-FIXES them → re-run $changes-review INLINE over the WHOLE current diff → loop until one complete pass clears the round's bar (rounds 1-2: zero findings; round 3+: zero CRITICAL/HIGH/MEDIUM, a LOW-only round ENDS the loop with the LOWs recorded as deferred) → run the final full-mode $why-review over the settled whole target → only then $docs-update → $workflow-end. Stop only when all required review passes are clean (or the same blocker repeats 3× with no progress → escalate by asking the user directly).

The /goal Stop hook then blocks stopping until the condition holds and auto-clears when met — do not tell the user to clear it.

If /goal is unavailable, unregistered, or not permitted — record ONE line and proceed under the protocol loop (step 1), which is already binding; NEVER error, block, or fake a gate on its absence:

/goal accelerator unavailable — review loop bound by protocol (Step 0 step 1)

3. Then proceed to create the 20 step tasks below and run the sequence.

Why bind the loop on top of the loop prose: the conditional re-review (step 15) and the "loop until clean" rules are soft directives an orchestrator can rationalize away after one fix cycle. The protocol loop converts them into a self-enforced invariant on every host; the optional /goal Stop hook adds a mechanical block, but correctness never depends on it.

Mandatory Task Creation (ZERO TOLERANCE)

Step 0 first: bind the Step 0 self-recursive review loop (above — protocol loop always, /goal accelerator when available) BEFORE creating these tasks — always, including when this workflow is a step inside a parent workflow, since it always runs inline in the main session and owns the loop directly.

Create one task per row in the table below — source of truth is workflows.json → workflow-review-changes.sequence (currently 20 steps; verify count matches if you suspect drift). The Step 0 loop binding is a pre-sequence wrapper and is NOT counted among these 20:

UI review runs in TWO places by design (keep both). $ui-review runs BOTH (a) INTERNALLY inside step 1 ($changes-review invokes it as its UI dimension) AND (b) as a DEDICATED conditional specialist-batch member (step 10, ui-ux-designer sub-agent). Both are gated on the same trigger — frontend/UI files in the diff — so both are skipped when no frontend files changed. Create the step-10 [Workflow] $ui-review task (conditional) AND keep step 1's internal UI dimension; do NOT collapse them into one.

NEVER consolidate, rename, or omit steps. If reviews PASS, mark conditional tasks completed with note "Skipped — all reviews passed".

Integration Test Sync: The $changes-review skill (task #1) includes a mandatory integration test coverage check for changed command/query/handler files. When gaps are found, the skill uses ask the user directly to surface them — NOT purely advisory. The user must explicitly choose to run $integration-test or confirm tests are already written. No silent skip.

Translation Sync: The $changes-review skill (task #1) includes a mandatory multilingual UI translation-sync check. When UI text changes in multilingual projects without locale updates, the skill uses ask the user directly for an explicit user decision — NOT purely advisory.

Docs Update: $docs-update (step 18) MUST run after EVERY review — it performs Phase 0 triage and fast-exits automatically when only non-business-code files changed (.claude/**, config). When business code is in the changeset, it WILL invoke: Phase 2 $spec (business feature doc update), Phase 2.5 $spec-index [mode=index] (derived bucket INDEX/ERD refresh — if docs/specs/ bucket maintains a derived index; note: dirs may be app buckets or flat system folders — probe ls docs/specs/{name}/ to find a specific service), Phase 2.6 $tech-spec when the derived technical view is affected, Phase 3 $spec [mode=tests] (test spec sync), Phase 4 $spec [mode=sync] (§8 TCs ↔ executing test code). Never skip based on review PASS status alone.

Spec Drift Adjudication: The $changes-review skill (task #1) runs a mandatory spec-drift adjudication (SYNC:spec-drift-adjudication, per shared/sdd-artifact-contract.md → Drift Gates) for every behavior-changing file: it classifies each divergence between changed behavior and the canonical Feature Spec as CODE-WRONG (BLOCKING — fix the code/test against intended behavior), SPEC-STALE (the change is the new intent — the spec documents the old behavior), or AMBIGUOUS (escalate). The reviewer never silently picks a side. A SPEC-STALE verdict flows downstream: $docs-update (step 18) updates the Feature Spec FIRST via $spec [update], then re-syncs $spec [mode=tests]. The workflow is NOT clean while any behavior-vs-spec divergence remains unadjudicated — green tests do not normalize drift (green can encode the drift itself).

Spec enrichment per cycle (MANDATORY — closes the feedback loop): Every confirmed finding fixed in the loop (steps 12–15) that changed observable behavior MUST produce a new or updated §8 regression/preservation TC via $spec [mode=tests] before the workflow is clean — a code-only fix with no covering §8 TC is an INCOMPLETE cycle, not a clean pass. This applies to EVERY confirmed behavior-changing fix, not only SPEC-STALE drift verdicts or bugfix-workflow paths: a CODE-WRONG fix owes a regression TC describing the now-correct behavior; a behavior change owes a preservation/regression TC guarding the new behavior. So each recursive cycle ENRICHES the spec rather than only mutating code — the inline re-review (step 15) and the $workflow-end spec ↔ TDD-test sync gate both treat a behavior-changing fix that left no §8 TC as an open finding.

Initial Parallel Phase (Steps 1–2) — EXECUTION PROTOCOL

Steps 1 and 2 are independent, read-only review lanes over the same starting state:

1. Launch $why-review --target=whole-review-target as a fresh code-reviewer sub-agent in FULL mode. Its target is the whole review target combined with the current changes — the complete changeset plus surrounding code/spec/docs — and it writes its report incrementally under plans/reports/.
2. Immediately run $changes-review INLINE in the main session while that sub-agent is active. It owns surface detection, dimensional review, the internal UI dimension, and integration/translation/spec-drift gates.
3. Treat the pair as one declared all-return barrier. Neither lane consumes or waits on the other's partial output. Advance only after BOTH return; then mark both tasks complete and consolidate both reports.
4. Run step 3 $why-review --validate-findings against the step-1 findings. Do not revalidate step 2's findings here because full-mode $why-review already owns its closing findings-validation gate.

This phase intentionally mixes one inline member with one sub-agent member: dispatch the sub-agent first, start the inline member immediately, and do not advance past the phase until both complete. The unique sequence token why-review --target=whole-review-target prevents the initial occurrence from being confused with the final plain why-review occurrence by workflow barrier renderers.

Specialist Parallel Review Phase (Steps 4–10) — EXECUTION PROTOCOL

Note: Steps 4–10 are the specialist reviewers — architecture compliance, DDD entities, performance, integration test quality, security vulnerabilities, production readiness, and UI/frontend quality ($ui-review, conditional on frontend files). They run as workflow-level parallel sub-agents, separate from the DIMENSIONAL review (BE/FE/SCSS/Synthesis + UI dimension) that runs INSIDE Step 1 ($changes-review). $ui-review runs in TWO places by design (keep both): (a) INTERNALLY inside Step 1 as $changes-review's UI dimension, AND (b) here as the DEDICATED step-10 batch member (ui-ux-designer sub-agent). Both fire only when the diff has files matching the project's configured frontend/UI file patterns; both are skipped otherwise.

Steps 4–10 ($architecture-review, $domain-entities-review, $performance-review, $integration-test-review, $security-review, $production-readiness-review, $ui-review) are read-only and independent — no shared mutable state, no ordering dependency between them. Run them as parallel sub-agents to preserve main session context budget and reduce wall-clock time.

Why parallel?

Each reviewer reads the git diff independently and analyzes one concern. Sequential execution would burn 50K+ tokens in the main session absorbing all seven inline. The stepMeta in workflows.json marks all seven as executionMode: subagent, contextBudget: high — dispatch each as a sub-agent per the model-driven advancement rule (no hook emits a 💡 [SUB-AGENT RECOMMENDED] hint).

UI review runs in TWO places by design (keep both). $changes-review (step 1) invokes $ui-review internally as its dimensional-batch UI dimension when frontend files changed, AND step 10 spawns $ui-review again as a DEDICATED conditional member of THIS specialist phase. Both fire only when frontend/UI files are in the diff; both are skipped otherwise.

Execution: spawn in one message

After the initial steps 1–2 barrier clears and step 3 validates the step-1 findings, spawn all active specialist reviewers in a single response with multiple spawn_agent tool calls:

spawn_agent(architecture-review, agent_type="architect", ...)           ← all in ONE message
spawn_agent(domain-entities-review, agent_type="code-reviewer", ...)    ← only if entity files in diff
spawn_agent(performance-review, agent_type="performance-optimizer", ...)
spawn_agent(integration-test-review, agent_type="integration-tester", ...)
spawn_agent(security-review, agent_type="security-auditor", ...)
spawn_agent(production-readiness-review, agent_type="code-reviewer", ...)  ← read-only SRE findings/score mode
spawn_agent(ui-review, agent_type="ui-ux-designer", ...)                ← only if frontend/UI files in diff

Each sub-agent receives:

• The baseline summary from step 1 (what changed, integration test gaps found)
• Instruction to write report to plans/reports/{skill}-{date}-{slug}.md
• Full review protocols per SYNC:review-protocol-injection (verbatim in prompt — never by file reference)

State advancement after parallel batch (model-driven — PRIMARY)

Advancement here is model-driven — your responsibility against the task list, NOT a hook/tool signal. This is the same rule the universal context files carry ("Workflow Step Advancement & Parallel Phases" in CLAUDE.md / AGENTS.md), so the batch advances identically under Claude and Codex. The shared kernel is the canonical SYNC:parallel-phase-advancement block consolidated at the end of this skill — its barrier rule governs this batch: declare the group up-front; spawn ALL members in ONE message; advance ONLY after EVERY member returns (a skipped conditional member counts as "returned"); a sub-agent return advances a step IDENTICALLY to an inline call; defer the mutating $code-simplifier step until the barrier clears; hooks are accelerators only.

Applied to this workflow's specialist batch — after ALL parallel reviewers (steps 4–10) have returned:

1. TaskUpdate step 4 → completed
2. TaskUpdate step 5 → completed (or "Skipped — no entity files" if the conditional domain-entities-review member did not run — a skipped conditional counts as "returned")
3. TaskUpdate step 6 → completed
4. TaskUpdate step 7 → completed
5. TaskUpdate step 8 → completed
6. TaskUpdate step 9 ($production-readiness-review) → completed
7. TaskUpdate step 10 ($ui-review) → completed (or "Skipped — no frontend/UI files" if the conditional ui-review member did not run — a skipped conditional counts as "returned")
8. Read all sub-agent report files; synthesize findings into a combined review summary
9. Proceed to step 11 ($code-simplifier) sequentially — only after the barrier above (it is a code-mutating step and must see the complete review snapshot)

Advancement here is model-driven. This sub-agent batch advances only after every member returns (the all-return barrier) — no step-tracking hook advances it. Claude and Codex both rely entirely on this rule.

Consolidation before $code-simplifier

Before running $code-simplifier, synthesize all parallel sub-agent findings:

• List all Critical/High/Medium/Low findings across all 7 reports (plus the UI-dimension findings folded into step 1's report when frontend files changed)
• Note any conflicts between reviewers (same file, different concerns)
• Pass this summary to $code-simplifier as context so simplification is informed by review findings

Surface Analysis from Step 1:

Step 1 ($changes-review) now emits a surface analysis summary in its report:

## Change Surface Analysis
BE files: {N}
FE-Logic files: {M}
SCSS files: {P}
Review Mode: [DIMENSIONAL | BE-ONLY | FE-ONLY | FE-SPLIT | TOOLING]

Include this surface analysis in the consolidation summary passed to $code-simplifier. This lets the simplifier focus attention on the dominant surface without re-analyzing the diff.

Dimensional agent reports (if mode = DIMENSIONAL):

• plans/reports/review-be-{date}.md — BE findings
• plans/reports/review-fe-logic-{date}.md — FE-Logic findings
• plans/reports/review-scss-{date}.md — SCSS findings (if spawned)
• plans/reports/synthesis-review-{date}.md — Cross-boundary findings

All four (plus the UI-dimension $ui-review findings when frontend files changed) feed into the consolidation summary alongside the step-2 whole-target report and steps 4–10 specialist findings (including the dedicated step-10 $ui-review pass).

What runs sequentially (never parallelize)

Conditional Inline Re-Review Protocol (CRITICAL)

Decision Logic

Reviews (steps 1-11) → ALL PASS (no findings)?
  YES → skip steps 12-15 ($plan → $plan-review → $plan-execute → $changes-review), proceed to final $why-review HOLISTIC full-mode pass (step 16) → $scan --target=domain-entities (step 17, conditional — run on entity/DTO/schema changes, else complete with a cited skip reason) → $docs-update (step 18) → $workflow-end → $watzup → DONE
  NO (findings exist) → $plan → $plan-review → $plan-execute → (if $plan-execute changed files) $changes-review INLINE re-review (step 15) → loop until clean at the round's bar (rounds 1-2: zero findings; round 3+: zero CRITICAL/HIGH/MEDIUM) → final $why-review HOLISTIC full-mode pass (step 16)
Step 16 (ALWAYS): $why-review FULL mode over the settled WHOLE target + changes. If it finds new BLOCKING findings → re-enter $plan → $plan-execute → $changes-review, then re-run step 16; loop until clean at the round's bar (round 3+ ignores LOW-only) → $scan --target=domain-entities (step 17, conditional) → $docs-update (step 18).
Note: $code-simplifier (step 11) self-reviews the code it changes via $code-review before returning.
Note: $why-review has three workflow occurrences: step 2 FULL mode on the whole starting target in parallel with step 1; step 3 `--validate-findings` mode over step-1 findings; step 16 FULL mode over the settled post-fix target. Steps 2 and 16 share a lens but observe different states, while step 3 is a terminal findings-validation gate.

Conditional Inline Re-Review Gate (Step 15) — After $plan-execute Applies Fixes

1. CONDITION (run only if $plan-execute changed files): Step 15 runs ONLY when $plan-execute actually modified files. If $plan-execute made no file changes, SKIP step 15 and proceed to the step-16 holistic $why-review, then $docs-update.
2. DO re-run the $changes-review protocol INLINE in the main session over the current full diff. Create a fresh task breakdown, rerun blast radius, risk detection, surface categorization, diff collection, dimensional reviews, synthesis, and validation gates. (Inline by design for this workflow — cheaper than spawning a fresh sub-agent; accept the mild orchestrator-confirmation-bias tradeoff, and counter it by re-reading the diff from scratch.)
3. DO track re-review invocation count and repeated blockers in conversation context
4. DO integrate the inline $changes-review findings — MUST NOT filter, reinterpret, or override
5. IF the inline re-review clears the round's bar — PASS with zero findings (rounds 1-2), or zero CRITICAL/HIGH/MEDIUM with only LOW findings left (round 3+, recorded as deferred) → confirm every behavior-changing fix has its required §8 regression/preservation TC, then proceed to t

…(truncated)