claude-dev-env 2.7.1 → 2.9.0

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.

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

@@ -9,8 +9,15 @@ Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
 if there's no upstream) to get the unified diff under review. If there are
 uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
 include the working-tree changes in scope — the review often runs before the
-commit. If a PR number, branch name, or file path was passed as an argument,
-review that target instead. Treat this diff as the review scope.
+commit. If a target was passed as an argument, review that target instead. A
+target names one or more items, each a PR number, a branch name, a file path, or
+`default-range` — the diff this phase gathers 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, gather each item's diff and take their
+union — a shared hunk counted once, an empty one adding nothing — as the
+target's diff. Treat this diff as the review scope.
 
 ## Phase 1 — Find candidates (3 correctness angles + 3 cleanup angles + 1 altitude angle + 1 conventions angle)
 
@@ -116,23 +123,41 @@ Keep candidates where the vote is CONFIRMED or PLAUSIBLE.
 
 Report this review's results — `{level, findings}` — through the structured
 findings-report call: the mechanism that renders a review's results as a typed
-list in the host UI, ranked most-severe first. Each entry has `file`, `line`,
-`summary`, `short_summary` — the claim compressed to ≤60 characters, no
-rationale or consequence clause — `failure_scenario`, and `category` — a short
-kebab-case slug for the angle that produced it (`correctness`,
-`simplification`, `efficiency`, `reuse`, `altitude`, `conventions`, or a more
-specific slug like `test-coverage` when one fits better) — plus `verdict` when
-a verify pass produced one. If nothing survives verification, make that call
-with an empty array. Do not also print the findings as text, and do not create
-or publish an artifact of the review — the structured call is the report.
+list in the host UI, ranked most-severe first. Each **retained** entry carries
+every field below. Drop REFUTED candidates before this report; do not emit a
+finding that lacks `severity` or `verdict`.
+
+| Field | Required | Value |
+|---|---|---|
+| `file` | yes | path under review |
+| `line` | yes | 1-based line number |
+| `summary` | yes | full claim |
+| `short_summary` | yes | claim compressed to ≤60 characters, no rationale or consequence clause |
+| `failure_scenario` | yes | concrete trigger and wrong outcome, or concrete cost for cleanup |
+| `category` | yes | short kebab-case slug for the angle (`correctness`, `simplification`, `efficiency`, `reuse`, `altitude`, `conventions`, or a tighter slug like `test-coverage`) |
+| `severity` | yes | one of `blocker`, `high`, `medium`, `low`, `nit` |
+| `verdict` | yes | `CONFIRMED` or `PLAUSIBLE` from Phase 2 |
+
+**Severity rules.** Assign exactly one token from the frozen set above. Use
+`nit` only when all five hold: the change is localized clarity, formatting, or
+a typo; correctness, security, data, and API behavior stay identical; test
+coverage and operability stay identical; dependencies and rollout stay
+identical; the fix is mechanical and bounded. Any other retained finding is
+`low` or higher. Correctness bugs outrank cleanup, altitude, and conventions.
+
+If nothing survives verification, make that call with an empty array. Do not
+also print the findings as text, and do not create or publish an artifact of
+the review — the structured call is the report.
 
 ## 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
 
@@ -146,8 +171,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 Phases 0–2, Output, 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 Output.
+skill's folder) for how to re-run Phases 0–2 and Output 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 Output.
+
+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 Output 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.

package/skills/e-code-review/reference/runner-selection.md

@@ -0,0 +1,40 @@
+# Runner selection (medium review)
+
+How `/e-code-review medium` (and loop) should pick a **harness runner** for
+finder/verify work. This file is the map; `SKILL.md` only points here.
+
+## What lives here
+
+| Topic | Content |
+|---|---|
+| Goal | One skill surface; many possible runners (Grok, Codex, Claude headless, …) |
+| Today | `scripts/grok_code_review.py` is the Grok medium orchestration module |
+| Target | A thin selector chooses a runner by availability and task flags |
+| Non-goals | Reimplementing every harness inside this skill |
+
+## Today
+
+- Medium procedure: `reference/medium.md` (angles, verify, output fields).
+- Grok orchestration API: `scripts/grok_code_review.py` (discovery, dedupe,
+  retain, head-drift).
+- Constants: `scripts/e_code_review_scripts_constants/`.
+
+## Target shape (tracked separately)
+
+1. **Runner protocol** — shared inputs (diff base, head, angles) and outputs
+   (candidates, verdicts, severities).
+2. **Detection** — which runners are installed/configured (PATH, skills,
+   account chain).
+3. **Selection** — pick one runner without baking a single vendor into
+   `SKILL.md` process steps.
+4. **Adapters** — thin wrappers: Grok (current module), Codex, Claude, …
+
+Open issue for implementation work should link this file and keep PRs small
+(Google small-CL practice: one concern per PR).
+
+## Related always-on docs
+
+- Skill hub: `../SKILL.md` (levels, fix, loop — not runner internals).
+- Medium procedure: `medium.md`.
+- Shared worker spawn (when applicable):
+  `packages/claude-dev-env/_shared/pr-loop/worker-spawn.md` in the package tree.

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

@@ -10,8 +10,15 @@ Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
 if there's no upstream) to get the unified diff under review. If there are
 uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
 include the working-tree changes in scope — the review often runs before the
-commit. If a PR number, branch name, or file path was passed as an argument,
-review that target instead. Treat this diff as the review scope.
+commit. If a target was passed as an argument, review that target instead. A
+target names one or more items, each a PR number, a branch name, a file path, or
+`default-range` — the diff this phase gathers 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, gather each item's diff and take their
+union — a shared hunk counted once, an empty one adding nothing — as the
+target's diff. Treat this diff as the review scope.
 
 ## Phase 1 — Find candidates (5 correctness angles + 3 cleanup angles + 1 altitude angle + 1 conventions angle)
 
@@ -157,11 +164,13 @@ or publish an artifact of the review — the structured call is the report.
 
 ## 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
 
@@ -175,8 +184,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 Phases 0–3, Output, 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 Output.
+skill's folder) for how to re-run Phases 0–3 and Output 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 Output.
+
+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 Output 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.

package/skills/e-code-review/scripts/e_code_review_scripts_constants/__init__.py

@@ -0,0 +1 @@
+"""Constants package for e-code-review scripts."""

package/skills/e-code-review/scripts/e_code_review_scripts_constants/grok_code_review_constants.py

@@ -0,0 +1,55 @@
+"""Named constants for Grok medium-review discovery and verification."""
+
+from __future__ import annotations
+
+MEDIUM_REVIEW_SCHEMA_VERSION: str = "1.0.0"
+"""Schema version for medium-review run documents."""
+
+MEDIUM_REVIEW_FINDER_COUNT: int = 8
+"""Exactly eight finder angles execute per medium review head."""
+
+ALL_MEDIUM_FINDER_ANGLES: tuple[str, ...] = (
+    "correctness",
+    "security",
+    "code_rules",
+    "tests",
+    "docs",
+    "concurrency",
+    "api_contracts",
+    "regressions",
+)
+"""Named finder angles for one medium-review discovery batch."""
+
+VERDICT_CONFIRMED: str = "CONFIRMED"
+"""Verification retained a concrete failure scenario."""
+
+VERDICT_PLAUSIBLE: str = "PLAUSIBLE"
+"""Verification could not refute the finding."""
+
+VERDICT_REFUTED: str = "REFUTED"
+"""Verification rejected the finding."""
+
+ALL_VERIFICATION_VERDICTS: frozenset[str] = frozenset(
+    {VERDICT_CONFIRMED, VERDICT_PLAUSIBLE, VERDICT_REFUTED}
+)
+"""Legal verification verdict tokens."""
+
+SEVERITY_BLOCKER: str = "blocker"
+SEVERITY_HIGH: str = "high"
+SEVERITY_MEDIUM: str = "medium"
+SEVERITY_LOW: str = "low"
+SEVERITY_NIT: str = "nit"
+
+ALL_SEVERITIES: frozenset[str] = frozenset(
+    {
+        SEVERITY_BLOCKER,
+        SEVERITY_HIGH,
+        SEVERITY_MEDIUM,
+        SEVERITY_LOW,
+        SEVERITY_NIT,
+    }
+)
+"""Legal severity tokens on retained findings."""
+
+UTF8_ENCODING: str = "utf-8"
+"""Text encoding for review artifacts."""