claude-dev-env 2.7.1 → 2.8.0

package/skills/codex-review/scripts/test_codex_usage_probe.py

@@ -34,9 +34,6 @@ from codex_review_scripts_constants.codex_usage_probe_constants import (
     USAGE_REPORT_KEY_WINDOW_RESET,
     WEEKLY_USAGE_GATE_THRESHOLD_PERCENT,
     WEEKLY_WINDOW_DURATION_MINUTES,
-    WINDOWS_OS_NAME,
-    WINDOWS_TASKKILL_COMMAND,
-    WINDOWS_TASKKILL_TREE_FLAG,
 )
 
 PROBE_PATH = SCRIPTS_DIRECTORY / "codex_usage_probe.py"
@@ -300,58 +297,66 @@ class TestParseTextStatus:
 
 
 class TestProcessTreeTeardown:
-    def should_run_taskkill_tree_when_os_name_is_windows(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-    ) -> None:
+    def should_end_a_running_app_server_and_reap_it(self) -> None:
+        """A real sleeping child is gone once teardown returns, on any platform."""
         probe = load_probe_module()
-        all_taskkill_commands: list[list[str]] = []
-        fake_process = subprocess.Popen(
+        sleeping_process = subprocess.Popen(
             [sys.executable, "-c", "import time; time.sleep(30)"],
             stdout=subprocess.DEVNULL,
             stderr=subprocess.DEVNULL,
+            start_new_session=probe.should_start_new_session(),
         )
         try:
-            monkeypatch.setattr(probe.os, "name", WINDOWS_OS_NAME)
-
-            def capture_run(
-                command: list[str],
-                **_kwargs: object,
-            ) -> subprocess.CompletedProcess[str]:
-                all_taskkill_commands.append(list(command))
-                fake_process.kill()
-                fake_process.wait(timeout=PROCESS_TREE_WAIT_SECONDS)
-                return subprocess.CompletedProcess(command, 0)
-
-            monkeypatch.setattr(probe.subprocess, "run", capture_run)
-            probe._terminate_process_tree(fake_process)
+            probe._terminate_process_tree(sleeping_process)
+            assert sleeping_process.poll() is not None
         finally:
-            if fake_process.poll() is None:
-                fake_process.kill()
-                fake_process.wait(timeout=PROCESS_TREE_WAIT_SECONDS)
-        assert len(all_taskkill_commands) == 1
-        assert all_taskkill_commands[0][0] == WINDOWS_TASKKILL_COMMAND
-        assert WINDOWS_TASKKILL_TREE_FLAG in all_taskkill_commands[0]
-        assert str(fake_process.pid) in all_taskkill_commands[0]
-
-    def should_kill_process_directly_when_os_name_is_not_windows(
+            if sleeping_process.poll() is None:
+                sleeping_process.kill()
+                sleeping_process.wait(timeout=PROCESS_TREE_WAIT_SECONDS)
+
+    def should_hand_the_whole_tree_to_the_shared_kill(
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        """Teardown routes the server process through the shared tree kill.
+
+        ::
+
+            shared tree kill  ok:   the cmd.exe shim's app-server child dies too
+            Popen.kill()      flag: the app-server grandchild holds stdout open
+        """
         probe = load_probe_module()
-        fake_process = subprocess.Popen(
-            [sys.executable, "-c", "import time; time.sleep(30)"],
+        all_killed_processes: list[object] = []
+        finished_process = subprocess.Popen(
+            [sys.executable, "-c", ""],
             stdout=subprocess.DEVNULL,
             stderr=subprocess.DEVNULL,
         )
-        try:
-            monkeypatch.setattr(probe.os, "name", "posix")
-            probe._terminate_process_tree(fake_process)
-            assert fake_process.poll() is not None
-        finally:
-            if fake_process.poll() is None:
-                fake_process.kill()
-                fake_process.wait(timeout=PROCESS_TREE_WAIT_SECONDS)
+        finished_process.wait(timeout=PROCESS_TREE_WAIT_SECONDS)
+        monkeypatch.setattr(
+            probe,
+            "terminate_process_tree",
+            lambda target_process: all_killed_processes.append(target_process),
+        )
+
+        probe._terminate_process_tree(finished_process)
+
+        assert all_killed_processes == [finished_process]
+
+    def should_return_when_a_killed_child_never_reaps(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """A child that outlives its grace window ends teardown, never hangs it."""
+        probe = load_probe_module()
+
+        class _UnreapableProcess:
+            def wait(self, timeout: float | None = None) -> int:
+                raise subprocess.TimeoutExpired(cmd="codex", timeout=timeout or 0)
+
+        monkeypatch.setattr(probe, "terminate_process_tree", lambda _process: None)
+
+        probe._terminate_process_tree(_UnreapableProcess())
 
 
 class TestReaderThreadLifecycle:

package/skills/codex-review/scripts/test_run_codex_review.py

@@ -890,38 +890,6 @@ def test_run_command_kills_grandchild_tree_on_timeout_without_hanging(
     assert _wait_until_process_stops(grandchild_identifier, wall_clock_ceiling_seconds)
 
 
-def test_windows_process_tree_kill_builds_taskkill_argv(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    """The Windows kill path issues taskkill /T /F /PID for the given process id."""
-    target_process_identifier = 4242
-    recorded_argv: list[list[str]] = []
-
-    def record_argv(all_arguments: list[str], **_keywords: object) -> None:
-        recorded_argv.append(all_arguments)
-
-    monkeypatch.setattr(wrapper.subprocess, "run", record_argv)
-    wrapper._kill_windows_process_tree(target_process_identifier)
-
-    assert recorded_argv == [
-        ["taskkill", "/T", "/F", "/PID", str(target_process_identifier)]
-    ]
-
-
-def test_windows_process_tree_kill_swallows_taskkill_timeout(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    """A hung taskkill must not raise — caller falls back to Popen.kill + drain."""
-
-    def raise_taskkill_timeout(
-        _all_arguments: list[str], **_keywords: object
-    ) -> None:
-        raise subprocess.TimeoutExpired(cmd="taskkill", timeout=1)
-
-    monkeypatch.setattr(wrapper.subprocess, "run", raise_taskkill_timeout)
-    wrapper._kill_windows_process_tree(4242)
-
-
 def test_drain_joins_pipes_when_direct_kill_raises_process_lookup_error() -> None:
     """Even when the process is already gone, drain still joins pipe readers."""
     all_communicate_timeouts: list[float | None] = []
@@ -990,7 +958,7 @@ def test_run_command_surfaces_timeout_when_tree_kill_is_noop(
     def leave_process_alive(_review_process: object) -> None:
         return None
 
-    monkeypatch.setattr(wrapper, "_terminate_process_tree", leave_process_alive)
+    monkeypatch.setattr(wrapper, "terminate_process_tree", leave_process_alive)
     start_time = time.monotonic()
     with pytest.raises(subprocess.TimeoutExpired):
         wrapper._run_command(

package/skills/e-code-review/SKILL.md

@@ -13,11 +13,12 @@ description: >-
 
 ## Gotchas
 
-- **`low` stays single-pass.** Do not spawn subagents. One diff read, one findings pass.
+- **`low` stays single-pass.** No subagents, no full-file reads: one read pass per target item, one findings pass.
 - **`medium` favors precision, `xhigh` favors recall.** At `medium` (8 angles) surface only findings a maintainer would act on. At `xhigh` (10 angles plus a gap sweep) a single non-REFUTED vote carries the finding; do not drop on uncertainty.
-- **`--fix` applies findings once.** Load `reference/fix.md` and follow it — it owns the fix agent, the commit gate, skip logging, and outcome reporting.
-- **`loop` never asks.** After findings, fix nits or stop on bugs. Load `reference/loop.md` and follow it.
-- **`--fix` and `loop` combine.** With both, each loop round runs the level file, then `reference/fix.md`, then re-reviews.
+- **Every retained finding carries `severity` and `verdict`.** Severity is one of `blocker`, `high`, `medium`, `low`, `nit`. Verdict is `CONFIRMED` or `PLAUSIBLE`. Drop REFUTED candidates; never emit an unclassified retained finding.
+- **`--fix` applies findings once.** Load `reference/fix.md` and follow it — it owns the fix agent, the code-rules gate, skip logging, and outcome reporting. Commits are lead-owned; fix agents never commit or push.
+- **`loop` never asks.** A round with bug findings validates them with an advisor, fixes, and re-reviews. Terminals are exactly `clean`, `nits_fixed`, and `advisor_blocked`. There is no reviewed-head count limit; a new head increments the count once, a re-review of the same head does not. Load `reference/loop.md` and follow it.
+- **`--fix` and `loop` combine.** With both, each loop round runs the level file, and the round's fixing happens inside `reference/loop.md`'s gate sequence, which loads `reference/fix.md` for the mechanics. There is no separate fix pass around the round.
 
 ## When this skill applies
 
@@ -31,8 +32,8 @@ Triggers: `/e-code-review <level> [--fix] [loop]`. `<level>` is `low`, `medium`,
 
 1. Read `<level>` and the optional `--fix` and `loop` flags. Apply the refusal first.
 2. Load `reference/low.md`, `reference/medium.md`, or `reference/xhigh.md`. Run that file as one review cycle, ending in its structured findings report.
-3. If `--fix` is set, load `reference/fix.md` and apply it to that cycle's findings.
-4. If `loop` is set, load `reference/loop.md` and follow it. Each round re-runs the same level file from step 2, plus step 3 when `--fix` is set.
+3. If `--fix` is set and `loop` is not set, load `reference/fix.md` and apply it to that cycle's findings. This path has no commit step: the fixes stay uncommitted in the working tree for the user to review and commit.
+4. If `loop` is set, load `reference/loop.md` and follow it with that cycle's findings still unfixed. Round 1's findings are the ones step 2 already produced; from the second round on, the round re-runs that same level file end to end. End to end means the level file's review phases, up to and including its findings report — not its *Looping* section, which hands control to `loop.md` and would re-enter the loop the round is already inside. `loop.md`'s gate sequence owns when the round fixes.
 5. Without `--fix` or `loop`, return the cycle findings and stop.
 
 ## File index
@@ -40,10 +41,10 @@ Triggers: `/e-code-review <level> [--fix] [loop]`. `<level>` is `low`, `medium`,
 | File | Purpose |
 |---|---|
 | `SKILL.md` | Route by level; dispatch `--fix` and `loop` |
-| `reference/low.md` | low review procedure — 1 diff pass, no verify |
+| `reference/low.md` | low review procedure — 1 diff pass per target item, no verify |
 | `reference/medium.md` | medium review procedure — 8 angles, 1-vote verify |
 | `reference/xhigh.md` | xhigh review procedure — 10 angles, 1-vote verify, gap sweep |
-| `reference/fix.md` | Fix application, commit gate, skip logging, outcome reporting |
+| `reference/fix.md` | Fix application, code-rules gate, skip logging, outcome reporting |
 | `reference/loop.md` | Repeat review/fix rounds until clean |
 
 ## Folder map

package/skills/e-code-review/reference/fix.md

@@ -12,16 +12,38 @@ At `low` — and any time the Agent tool is unavailable — no finder agent exis
 to resume. Apply the fixes yourself, sequentially, in this context, holding to
 every rule below.
 
-## Commit gate
+## Code-rules gate
 
-Before returning, the resumed agent attempts a commit on its own change:
+Before returning, the resumed agent runs the code-rules gate with the same bare
+call every other surface in this skill uses:
 
 1. Run `~/.claude/_shared/pr-loop/scripts/code_rules_gate.py --repo-root <repo
-   root> <changed/added files>` against every file it changed or added.
-2. If the gate reports violations, fix them and re-run the exact same command.
-3. Repeat until the gate returns clean.
-4. Only after a clean gate result does the agent return control and report
-   its outcome.
+   root>` with no file paths and no `--only-under` prefix.
+2. If the gate reports violations **on lines this fix already owns** (the files
+   and added lines the fix changed), fix them and re-run the exact same command.
+3. A violation on a path or added line outside this fix's own work is reported
+   or skipped — it is not force-fixed into unrelated files. Log each skip with
+   the path and reason, then continue.
+4. Repeat until every violation on this fix's own work is clean (or skipped with
+   a logged reason for out-of-scope hits).
+5. Only after that result does the agent return control and report its outcome.
+
+A file path named on the command line puts the gate in whole-file scope and can
+churn on untouched lines; keep the call bare.
+
+This gate commits nothing. The fix lands in the working tree and stays
+uncommitted. **Commit ownership is lead-only:** a fix agent, patch worker, or
+resumed finding agent never runs `git commit` or `git push`. The lead that owns
+the branch creates the commit after gates pass. The bare code-rules call covers
+the merge-base surface and staged added lines only — working-tree-only lines
+enter that scope after the lead stages or commits them.
+
+Under a bare `--fix` — this document invoked without `loop` — nothing
+downstream commits either, and that is the intended outcome: a one-shot fix
+pass leaves its fixes uncommitted in the working tree for the lead to review
+and commit (stage first if you re-run the gate on those lines). Under `loop`,
+the round tail in `reference\loop.md` stages and runs required checks; the lead
+still owns the commit and push.
 
 ## Skip candidates
 

package/skills/e-code-review/reference/loop.md

@@ -2,7 +2,7 @@
 
 ## Act
 
-`loop` on the hub command authorizes the full cycle. After the effort level procedure returns findings, take the matching branch below immediately.
+`loop` on the hub command authorizes the full cycle. After the effort level procedure returns findings, run the gate sequence below immediately.
 
 Do not ask whether to fix, which nits to keep, whether to commit or push, or whether to re-review. Do not open a plan fork. Do not end the turn on a recommendation.
 
@@ -10,11 +10,18 @@ Report progress while you work. Stop for the user only on a terminal outcome bel
 
 ## Where fixes come from
 
-When `--fix` is also set, each round's fix pass runs `reference\fix.md`
-(relative to this skill's folder) — it owns which agent applies each fix, the
-commit gate, skip logging, and outcome reporting. Apply the branch rules below
-on top of it: they decide whether a round fixes, commits, pushes, and
-re-reviews.
+A round fixes whether or not `--fix` is set. Gate 2 below applies the round's
+fixes on every run, and its three cases read the same way with the flag and
+without it. What `--fix` adds is `fix.md`'s mechanics, not permission to fix:
+the flag decides where the mechanics come from, never whether a round fixes at
+all.
+
+When `--fix` is also set, the round's fixing happens inside the gate sequence
+below. Gate 2 is the only place a round applies a fix, and there is no separate
+fix pass sitting around the round. Gate 2 loads `reference\fix.md` (relative to
+this skill's folder) for the mechanics — which agent applies each fix, agent
+resume, the code-rules gate, skip logging, and outcome reporting — while the
+gate sequence decides whether a round fixes, commits, pushes, and re-reviews.
 
 ## Scope stays narrow
 
@@ -22,22 +29,231 @@ Auto-fix only verified findings on the review target. Leave deferred PR-body fol
 
 ## How to class each finding
 
-Use the finding's verified `severity` when the level emits one.
+Every retained finding carries a verified `severity` and a verification
+`verdict` (`CONFIRMED` or `PLAUSIBLE`). The frozen severity set is exactly
+`blocker`, `high`, `medium`, `low`, `nit`.
+
+A finding is a `nit` only when that severity is `nit`. Runtime-correctness,
+security, data-loss, compatibility, and every other non-nit finding is a
+`bug`.
 
-A finding is a `nit` only when that severity is `nit`. Runtime-correctness, security, data-loss, compatibility, and every other non-nit finding is a `bug`.
+A finding that lacks severity is **unclassified**. Consult the assigned
+advisor to classify it before Gate 2. When that advisor is unreachable,
+terminate with `advisor_blocked` and preserve draft state.
 
-If the level emits no severity (for example untagged `low` lines), consult your advisor to determine classification.
+A finding this document has already classed keeps that class at every level. An
+on-target shape-reader break is `bug` under *A shape change names its readers*;
+no advisor call reopens that.
 
 ## Required checks
 
-"Run required checks" means: run `~/.claude/_shared/pr-loop/scripts/code_rules_gate.py --repo-root <repo root> <changed/added files>` against every file changed or added in the round. On any violation, fix it and re-run the exact same command again — repeat until it reports clean.
+"Run required checks" means: run
+`~/.claude/_shared/pr-loop/scripts/code_rules_gate.py --repo-root <repo root>`
+with no file paths and no `--only-under` prefix. On a violation on lines this
+round already owns, fix it and re-run the exact same command until clean. A
+violation outside the review target is reported or skipped — not force-fixed into
+unrelated files — and the skip is logged with path and reason.
+
+That bare call gates the git diff since the merge-base (and any staged added
+lines the gate already includes). Working-tree lines that are neither staged
+nor committed sit outside that scope until they are staged or committed. Gate 2
+leaves its edits uncommitted, so the round tail stages those edits before
+required checks when this round produced edits.
+
+Two failure scenarios keep the call bare. A file path named on the command line
+puts the gate in whole-file scope on that file: a CODE_RULES violation on a line
+this round never touched fails the round and churns the loop. An `--only-under`
+prefix that matches nothing in the diff leaves the gate zero files to inspect and
+exits clean, so a run that inspected nothing reads as a pass.
+
+## Each round reviews new code
+
+A repair diff is new code. From the second round on, the round runs the level
+file end to end at the new head. End to end means that file's review phases, up
+to and including its findings report; the round stops there and brings those
+findings back to the gate sequence below. It does not run the level file's
+*Looping* section — that section hands control to this document, and the round
+is already inside it. The round's scope is the level's own review
+target — the diff or path the level gathers up front, called Phase 0 in
+`medium.md` and `xhigh.md` — taken against that target's base. A repair edit
+landing outside that target widens the next round's scope to cover it: the next
+round's review target is the original target **plus** that path, and the round
+reviews both. A later widening adds to that target the same way.
+
+The widened target is what the round hands the level file. When a round runs the
+level file end to end, it passes the current review target — the original target
+plus every path a widening has since added — as that run's target argument, in
+place of the argument the first round was given. When the first round was given
+no target argument, the original target is the item `default-range` — the level
+file's own default gather — so the widened target is `default-range` plus every
+added path, and the range the first round reviewed stays in scope. The level
+file gathers what the round hands it, so a widened path is gathered and reviewed
+like any other part of the target.
+
+## Dangerous diffs take two full rounds
+
+A diff is dangerous when it touches deletion paths, locks or other concurrency
+control, or shared mutable state. A deletion path is a runtime path that removes
+data or files; a dead-code cleanup is not one. Each round names whether the diff
+it reviewed is dangerous. A dangerous diff holds the loop open until two full
+rounds have reviewed it. A repair that rewrites the dangerous surface restarts
+the two-round count at the first round that reviews the rewritten surface.
+
+The round's progress report is where both facts are recorded: the dangerous
+classification, and the dangerous-round count written as `N of M`.
+
+## A shape change names its readers
+
+When a repair changes a key, an identifier format, or a data shape, list every
+reader of the shape it changed and state how each one reads the new shape. The
+list goes in the round's progress report.
+
+The round that follows a posted list checks each reader on that list against the
+new shape and names each reader with its result in that round's progress report.
+
+Discharge then turns on where the reader sits.
+
+- An **off-target** reader discharges once it is named with a result. This
+  branch cannot repair it.
+- An **on-target** reader that reads the new shape correctly discharges on that
+  result.
+- An **on-target** reader that reads the new shape wrong is a bug-severity
+  finding of the round that checked it. It joins that round's findings, and it
+  discharges on exactly one of three results, each of them an outcome gate 2
+  already produces: it is repaired, it is recorded as a skipped finding, or the
+  advisor refutes it. Naming the break discharges nothing on its own, and
+  neither does a further round merely happening.
+
+The list discharges once every reader on it has discharged.
+
+A broken reader outside the review target does not block the loop and does not
+widen scope. Hand it off as a reported finding. Two separate things are owed for
+that hand-off, and they land at different times:
+
+- **The round-scoped record** — what a round produces. Check the reader, record
+  its result, and name it in that round's progress report. All three are done
+  inside the round that checks the reader, and nothing outside that round is
+  needed to complete them. This is the record gate 2 reads.
+- **The termination-time disclosure** — what terminating requires. The
+  ready-for-review message names every broken off-target reader and every
+  skipped finding that still exists, and the pull request body carries the same
+  names when the target is a pull request. A target with no pull request owes
+  the ready message alone. Gate 3 enforces this at the moment the loop
+  terminates; no earlier round owes it.
 
 ## Terminal outcomes
 
-Repeat the same-level review/fix cycle until one of these holds:
+The loop emits exactly one of these terminals when it stops:
+
+| Terminal | When |
+|---|---|
+| `clean` | Zero retained findings on the current head, and required checks pass |
+| `nits_fixed` | Every retained finding is a nit with severity and a retained verdict, every nit is fixed, and required checks pass |
+| `advisor_blocked` | Classification needs the assigned advisor and that advisor is unreachable |
+
+Every round does this round's own work first, then runs the three gates below,
+in order: gate 1, then gate 2, then gate 3.
+
+**This round's work — before the gates.** Record this round's dangerous
+classification and the dangerous-round count as `N of M`; and when a shape-change
+list is open, check each reader on that list and name each reader with its
+result, adding any on-target reader that reads the new shape wrong to this
+round's findings as *A shape change names its readers* directs. Then run the
+gates.
+
+**Gate 1 — obligations.** Gate 1 is evaluated first in the sequence, and its
+answer turns on the round's open obligations alone — the findings are in hand by
+now, and no content they carry changes it. Ask only: does any obligation remain
+open? Two kinds exist.
+
+- A dangerous diff that has had fewer than two full rounds.
+- A posted shape-change list that no round has discharged.
+
+Gate 1 states its answer and stops there: an obligation remains open, or none
+does. It states no re-entry, no continuation, and no routing. Gate 3 is the sole
+router — every path out of a round passes through it.
+
+**Gate 2 — findings.** When `--fix` is set, load `reference\fix.md` here and
+follow it for the mechanics of every fix this gate applies — the fix agent,
+agent resume, the code-rules gate, skip logging, and outcome reporting. When `--fix` is
+absent, apply each fix in this session yourself, and log each skip in this
+round's progress report. Then take the one case that matches the round's
+findings.
+
+- Any bug-severity finding: validate each bug with an advisor before touching
+  code — confirm it's real and confirm the intended fix — then fix every
+  validated bug and every nit on the review target. A refuted bug removes only
+  itself from the round's work; the nits are fixed either way.
+- Nits only, with at least one nit present: fix all of them on the review
+  target.
+- No findings at all: make no edits.
+
+Gate 2 then ends by stating one of exactly two outcomes: unresolved findings
+remain, or none remain. A refuted bug is resolved. A fixed nit is resolved. A
+fixed validated bug is resolved. A handed-off off-target finding is resolved once
+this round has made its round-scoped record as *A shape change names its readers*
+defines that record — checked, result recorded, named in this round's progress
+report — whether or not the problem behind it is solved. Gate 2 reads the record
+and nothing else; the termination-time disclosure belongs to gate 3.
+
+A skipped finding — a finding deliberately not applied, because fixing it would
+change intended behavior, would reach beyond the review target, or the finding
+itself is judged a false positive — is resolved once its skip is logged in this
+round's progress report, naming the finding and the reason it was skipped. That
+report is the sink every run has, with or without `--fix`. When `--fix` is set,
+the skip handling `fix.md` carries runs inside this gate and adds to this log
+rather than replacing it.
+
+Gate 3 reads that stated outcome, never a case label.
+
+**Gate 3 — exit test.** Resolve the terminal from the table above, then stop or
+continue:
+
+- zero retained findings and required checks pass → `clean`;
+- nits only (each with severity and a retained verdict), all fixed, required checks pass → `nits_fixed`;
+- advisor needed for classification and unreachable → `advisor_blocked`;
+- otherwise continue.
+
+Also require, for `clean` and `nits_fixed`:
+
+- gate 1 shows no open obligation;
+- gate 2 states no unresolved findings remain;
+- this round produced no edits after the gates settled.
+
+Any other combination runs the round tail and re-enters the loop.
+
+Terminating with `clean` or `nits_fixed` carries one further condition — the
+termination-time disclosure: the ready-for-review message names every broken
+off-target reader and every skipped finding that still exists. When the target
+is a pull request, the pull request body carries the same names; a target with
+no pull request owes the ready message alone. Every surface this condition
+names is written at termination — the ready message always, the pull request
+body too when the target is a pull request — so each one is available to the
+terminating round. A round that cannot name them does not terminate; it runs
+the round tail and re-enters the loop, the same as any other non-terminating
+round. With that condition met, post the proof-of-work PR comment when the
+target is a PR, then run `gh pr ready` for a draft PR, or state ready
+otherwise.
+
+`advisor_blocked` keeps the pull request draft. It does
+not run `gh pr ready`. It reports every surviving structured finding.
+
+Gate 3 points at gate 1 for the obligation answer. It does not restate the
+two-round rule or the shape-reader rule; each of those keeps its one home in its
+own section above.
+
+**The round tail.** Every round runs required checks here, in the one form
+*Required checks* gives: the bare command, no file paths. When this round
+produced edits, stage those edits first so they enter the bare gate's scope,
+then run the checks. When this round produced no edits, run the same checks.
+Should those checks produce repairs, this round has produced edits — stage
+them and re-run the checks.
 
-- **Clean.** Findings are `[]` or `(none)`. Post the proof-of-work PR comment when the target is a PR. Run `gh pr ready` for a draft PR; otherwise state ready.
-- **Nits only.** Every surviving finding is severity `nit`. Fix all of them on the review target. Run required checks. Commit once per loop round. Push. Consider this clean — post the proof-of-work PR comment and mark ready as in the Clean branch above.
-- **Any bug.** Validate each bug-severity finding with an advisor before touching code — confirm it's real and confirm the intended fix. Then fix all validated findings (bugs and nits) on the review target. Run required checks. Commit once per loop round. Push. Run the same effort level on the new head. Repeat until clean, then mark ready as above.
+**Commit and push are lead-owned.** Gate 2 and the round tail leave every fix
+unstaged-or-staged in the working tree for the lead that owns the branch. A
+fix agent, patch worker, or resumed finding agent never creates the commit and
+never pushes. The lead stages, commits once per review round, and pushes after
+the gates pass. Start the next round under *Each round reviews new code* only
+after that lead commit lands a new head.
 
 Do not drop findings to force ready. Without `loop`, run one review at the selected level, fix, and return every validated finding.

package/skills/e-code-review/reference/low.md

@@ -1,13 +1,20 @@
-`low effort → 1 diff pass → no verify → ≥min(files,4) findings`
+`low effort → 1 diff pass per target item → no verify → ≥min(files,4) findings`
 
 ## Turn 1 — read
 
-One tool call: read the unified diff (`git diff @{upstream}...HEAD; git diff HEAD`
+Read the unified diff (`git diff @{upstream}...HEAD; git diff HEAD`
 to cover both committed and uncommitted changes, or `git diff main...HEAD` /
-the target passed as an argument). Skip test/fixture
-hunks (`test/`, `spec/`, `__tests__/`, `*_test.*`, `*.test.*`,
+the target passed as an argument). A target names one or more items, each a PR
+number, a branch name, a file path, or `default-range` — the default `git diff`
+read named above, which is what this step reads when no target is passed — and
+it may mix those forms. A loop round widens a target by adding a path to whatever it
+started as, and it names `default-range` as an item whenever the round it
+widened was given no target argument, so the original scope stays under review.
+When a target names more than one item, read each item's diff and review their
+union — a shared hunk counted once, an empty one adding nothing. Skip
+test/fixture hunks (`test/`, `spec/`, `__tests__/`, `*_test.*`, `*.test.*`,
 `fixtures/`, `testdata/`) — test-file changes are not reviewed at this level.
-No subagents, no full-file reads.
+One read pass per target item, and no more: no subagents, no full-file reads.
 
 ## Turn 2 — findings
 
@@ -32,11 +39,13 @@ also print the findings as text.
 
 ## Applying fixes (--fix)
 
-The `--fix` flag was passed. Follow `reference\fix.md` (relative to this
-skill's folder) for the exact fix, commit-gate, and skip-handling behavior —
-it governs which agent applies each fix, how a fix gets committed, how a skip
-is logged, and how outcomes get reported. Do not repeat the findings as text;
-follow that document's reporting rules once fixes land.
+The `--fix` flag was passed. Follow `reference\fix.md` (relative
+to this skill's folder) for the exact fix, code-rules-gate, and skip-handling
+behavior — it governs which agent applies each fix, how the code-rules gate
+runs, how a skip is logged, and how outcomes get reported. Do not repeat the
+findings as text; follow that document's reporting rules once fixes land.
+
+When `loop` is also set, skip this section.
 
 ## If findings are fixed later
 
@@ -50,8 +59,17 @@ summary; the host UI's per-finding status updates only from that call.
 ## Looping (`loop`)
 
 The `loop` arg was passed. Follow `reference\loop.md` (relative to this
-skill's folder) for how to re-run Turn 1 (read), Turn 2 (findings), and (if
-`--fix` is also present) `reference\fix.md`'s fix pass, repeatedly —
-including its exit condition, iteration cap, and re-invocation rules. Do not
-treat a single pass through this document as complete while `loop` is active;
-hand control to that document instead of stopping at Turn 2.
+skill's folder) for how to re-run Turn 1 (read) and Turn 2 (findings)
+repeatedly — including its exit condition and re-invocation rules. Schedule no
+fix pass of your own here: when `--fix` is also present, `reference\loop.md`'s
+gate sequence owns the round's fixing and loads `reference\fix.md` for the
+mechanics. Do not treat a single pass through this document as complete while
+`loop` is active; hand control to that document, and do not stop at Turn 2.
+
+That hand-off applies when this document is entered directly. When a loop round
+is already running and has handed this document its target, the round owns the
+loop: end at Turn 2 with the findings report and return those findings to
+`reference\loop.md`'s gate sequence, rather than handing control to that
+document again from here.
+
+When `loop` was not passed, skip this section.