claude-dev-env 1.47.0 → 1.49.0

package/hooks/hooks_constants/plain_language_blocker_constants.py

@@ -0,0 +1,295 @@
+"""Configuration constants for the plain_language_blocker PreToolUse hook."""
+
+from __future__ import annotations
+
+import re
+
+REPLACEMENT_BY_TERM: dict[str, str] = {
+    "addressees are requested": "(omit), please",
+    "under the provisions of": "under",
+    "interpose no objection": "don't object",
+    "afford an opportunity": "allow, let",
+    "has a requirement for": "needs",
+    "is in consonance with": "agrees with, follows",
+    "not later than 10 may": "by 10 May, before 11 May",
+    "provides guidance for": "guides",
+    "successfully complete": "complete, pass",
+    "with the exception of": "except for",
+    "due to the fact that": "due to, since",
+    "effect modifications": "make changes",
+    "in view of the above": "so",
+    "adversely impact on": "hurt, set back",
+    "at the present time": "at present, now",
+    "not later than 1600": "by 1600",
+    "combat environment": "combat",
+    "in a timely manner": "on time, promptly",
+    "in accordance with": "by, following, per, under",
+    "in the near future": "shortly, soon",
+    "is responsible for": "(omit) handles",
+    "on a regular basis": "(omit)",
+    "until such time as": "until",
+    "during the period": "during",
+    "in the process of": "(omit)",
+    "with reference to": "about",
+    "as prescribed by": "in, under",
+    "in the amount of": "for",
+    "is applicable to": "applies to",
+    "is authorized to": "may",
+    "state-of-the-art": "latest",
+    "close proximity": "near",
+    "for a period of": "for",
+    "in an effort to": "to",
+    "in the event of": "if",
+    "it is essential": "must, need to",
+    "it is requested": "please, we request, I request",
+    "notwithstanding": "inspite of, still",
+    "the undersigned": "I",
+    "arrive onboard": "arrive",
+    "in relation to": "about, with, to",
+    "incumbent upon": "must",
+    "limited number": "limits",
+    "take action to": "(omit)",
+    "as a means of": "to",
+    "in order that": "for, so",
+    "pertaining to": "about, of, on",
+    "provided that": "if",
+    "this activity": "us, we",
+    "advantageous": "helpful",
+    "consequently": "so",
+    "in regard to": "about, concerning, on",
+    "remuneration": "pay, payment",
+    "set forth in": "in",
+    "subsequently": "after, later, then",
+    "the month of": "(omit)",
+    "a number of": "some",
+    "accordingly": "so",
+    "adjacent to": "next to",
+    "appreciable": "many",
+    "appropriate": "(omit), proper, right",
+    "approximate": "about",
+    "by means of": "by, with",
+    "comply with": "follow",
+    "consolidate": "combine, join, merge",
+    "constitutes": "is, forms, makes up",
+    "demonstrate": "prove, show",
+    "discontinue": "drop, stop",
+    "disseminate": "give, issue, pass, send",
+    "expeditious": "fast, quick",
+    "immediately": "at once",
+    "in addition": "also, besides, too",
+    "in order to": "to",
+    "inasmuch as": "since",
+    "methodology": "method",
+    "necessitate": "cause, need",
+    "participate": "take part",
+    "practicable": "practical",
+    "proficiency": "skill",
+    "pursuant to": "by, following, per, under",
+    "relative to": "about, on",
+    "requirement": "need",
+    "substantial": "large, much",
+    "time period": "(either one)",
+    "utilization": "use",
+    "your office": "you",
+    "a and/or b": "a or b or both",
+    "accomplish": "carry out, do",
+    "additional": "added, more, other",
+    "addressees": "you",
+    "anticipate": "expect",
+    "assistance": "aid, help",
+    "be advised": "(omit)",
+    "capability": "ability",
+    "concerning": "about, on",
+    "equipments": "equipment",
+    "expiration": "end",
+    "facilitate": "ease, help",
+    "frequently": "often",
+    "heretofore": "until now",
+    "in lieu of": "instead",
+    "in view of": "since",
+    "indication": "sign",
+    "inter alia": "(omit)",
+    "it appears": "seems",
+    "parameters": "limits",
+    "previously": "before",
+    "prioritize": "rank",
+    "promulgate": "issue, publish",
+    "represents": "is",
+    "similar to": "like",
+    "subsequent": "later, next",
+    "sufficient": "enough",
+    "the use of": "(omit)",
+    "accompany": "go with",
+    "ascertain": "find out, learn",
+    "component": "part",
+    "currently": "(omit), now",
+    "designate": "appoint, choose, name",
+    "determine": "decide, figure, find",
+    "eliminate": "cut, drop, end",
+    "encounter": "meet",
+    "enumerate": "count",
+    "equitable": "fair",
+    "establish": "set up, prove, show",
+    "evidenced": "showed",
+    "expertise": "ability",
+    "failed to": "didn't",
+    "identical": "same",
+    "implement": "carry out, start",
+    "inception": "start",
+    "interface": "meet, work with",
+    "magnitude": "size",
+    "objective": "aim, goal",
+    "regarding": "about, of, on",
+    "remainder": "rest",
+    "selection": "choice",
+    "terminate": "end, stop",
+    "there are": "(omit)",
+    "therefore": "so",
+    "witnessed": "saw",
+    "accorded": "given",
+    "accurate": "correct, exact, right",
+    "aircraft": "plane",
+    "allocate": "divide",
+    "apparent": "clear, plain",
+    "combined": "joint",
+    "commence": "begin, start",
+    "comprise": "form, include, make up",
+    "contains": "has",
+    "disclose": "show",
+    "endeavor": "try",
+    "expedite": "hasten, speed up",
+    "feasible": "can be done, workable",
+    "finalize": "complete, finish",
+    "function": "act, role, work",
+    "herewith": "below, here",
+    "identify": "find, name, show",
+    "impacted": "affected, changed",
+    "indicate": "show, write down",
+    "initiate": "start",
+    "maintain": "keep, support",
+    "minimize": "decrease, method",
+    "numerous": "many",
+    "obligate": "bind, compel",
+    "preclude": "prevent",
+    "previous": "earlier",
+    "prior to": "before",
+    "purchase": "buy",
+    "relocate": "move",
+    "there is": "(omit)",
+    "transmit": "send",
+    "validate": "confirm",
+    "address": "discuss",
+    "attempt": "try",
+    "benefit": "help",
+    "command": "us, we",
+    "convene": "meet",
+    "evident": "clear",
+    "exhibit": "show",
+    "females": "women",
+    "forfeit": "give up, lose",
+    "forward": "send",
+    "furnish": "give, send",
+    "however": "but",
+    "initial": "first",
+    "liaison": "discussion",
+    "maximum": "greatest, largest, most",
+    "minimum": "least, smallest",
+    "monitor": "check, watch",
+    "observe": "see",
+    "operate": "run, use, work",
+    "optimum": "best, greatest, most",
+    "perform": "do",
+    "portion": "part",
+    "possess": "have, own",
+    "proceed": "do, go ahead, try",
+    "procure": "(omit)",
+    "provide": "give, offer, say",
+    "reflect": "say, show",
+    "request": "ask",
+    "require": "must, need",
+    "solicit": "ask for, request",
+    "subject": "the, this, your",
+    "therein": "there",
+    "thereof": "its, their",
+    "utilize": "use",
+    "warrant": "call for, permit",
+    "whereas": "because, since",
+    "accrue": "add, gain",
+    "advise": "recommend, tell",
+    "assist": "aid, help",
+    "attain": "meet",
+    "caveat": "warning",
+    "delete": "cut, drop",
+    "depart": "leave",
+    "desire": "want, wish",
+    "employ": "use",
+    "ensure": "make sure",
+    "expend": "spend",
+    "herein": "here",
+    "modify": "change",
+    "notify": "let know, tell",
+    "option": "choice, way",
+    "permit": "let",
+    "remain": "stay",
+    "render": "give, make",
+    "reside": "live",
+    "retain": "keep",
+    "submit": "give, send",
+    "timely": "prompt",
+    "viable": "practical, workable",
+    "elect": "choose, pick",
+    "it is": "(omit)",
+    "deem": "believe, consider, think",
+    "said": "the, this, that",
+    "same": "the, this, that",
+    "such": "the, this, that",
+    "type": "(omit)",
+    "vice": "instead of, versus",
+}
+
+ALL_TERM_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"\b" + re.escape(each_term) + r"\b", re.IGNORECASE), each_replacement)
+    for each_term, each_replacement in REPLACEMENT_BY_TERM.items()
+]
+
+ALL_SOFTWARE_TERMS: frozenset[str] = frozenset(
+    {
+        "command",
+        "function",
+        "address",
+        "parameters",
+        "interface",
+        "component",
+        "monitor",
+        "request",
+        "validate",
+        "however",
+        "forward",
+        "subject",
+        "same",
+        "such",
+        "said",
+        "type",
+        "it is",
+        "there is",
+        "there are",
+    }
+)
+
+FENCED_CODE_BLOCK_PATTERN: re.Pattern[str] = re.compile(r"```[\s\S]*?```", re.MULTILINE)
+INLINE_CODE_PATTERN: re.Pattern[str] = re.compile(r"`[^`]+`")
+BLOCKQUOTE_LINE_PATTERN: re.Pattern[str] = re.compile(r"^\s*>.*$", re.MULTILINE)
+URL_PATTERN: re.Pattern[str] = re.compile(r"https?://\S+", re.IGNORECASE)
+FILE_PATH_PATTERN: re.Pattern[str] = re.compile(
+    r"(?<![\w/\\])(?:[A-Za-z]:[\\/]|~?[\\/]|\.{1,2}[\\/])(?:[\w.\-]+[\\/])*[\w.\-]+"
+    r"|(?:[\w.\-]+[\\/])+[\w.\-]+\.[A-Za-z0-9]+"
+)
+
+MARKDOWN_EXTENSION: str = ".md"
+ASK_USER_QUESTION_TOOL_NAME: str = "AskUserQuestion"
+ALL_WRITE_EDIT_TOOL_NAMES: frozenset[str] = frozenset({"Write", "Edit", "MultiEdit"})
+
+USER_FACING_PLAIN_LANGUAGE_NOTICE: str = (
+    "Plain-language check: replace each flagged formal word with the simpler "
+    "word named in the reason."
+)

package/hooks/hooks_constants/pr_description_enforcer_constants.py

@@ -19,6 +19,8 @@ HEADING_LINE_PATTERN: re.Pattern[str] = re.compile(r"^#+[ \t].*$", re.MULTILINE)
 BOLD_PAIR_PATTERN: re.Pattern[str] = re.compile(r"\*\*([^*]+?)\*\*")
 BULLET_MARKER_PATTERN: re.Pattern[str] = re.compile(r"^\s*[-*+]\s+", re.MULTILINE)
 BLOCKQUOTE_MARKER_PATTERN: re.Pattern[str] = re.compile(r"^\s*>\s+", re.MULTILINE)
+BLOCKQUOTE_LINE_PATTERN: re.Pattern[str] = re.compile(r"^\s*>.*$", re.MULTILINE)
+TABLE_ROW_LINE_PATTERN: re.Pattern[str] = re.compile(r"^\s*\|.*\|.*$", re.MULTILINE)
 LINK_TEXT_PATTERN: re.Pattern[str] = re.compile(r"\[([^\]]+)\]\([^)]+\)")
 WHITESPACE_RUN_PATTERN: re.Pattern[str] = re.compile(r"\s+")
 
@@ -115,6 +117,7 @@ __all__ = [
     "ALL_HEAVY_TESTING_HEADERS",
     "ALL_READABILITY_CLI_FLAG_TOKENS",
     "ATOMIC_WRITE_TEMP_SUFFIX",
+    "BLOCKQUOTE_LINE_PATTERN",
     "BLOCKQUOTE_MARKER_PATTERN",
     "BOLD_PAIR_PATTERN",
     "BULLET_MARKER_PATTERN",
@@ -147,6 +150,7 @@ __all__ = [
     "SELF_CLOSING_REFERENCE_MESSAGE_SUFFIX",
     "SELF_REFERENCE_PATTERN_TEMPLATE",
     "STANDARD_SHAPE",
+    "TABLE_ROW_LINE_PATTERN",
     "THIS_PR_OPENING_PATTERN",
     "TRIVIAL_BODY_CHAR_THRESHOLD",
     "TRIVIAL_SHAPE",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.47.0",
+    "version": "1.49.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/confirm-implementation-forks.md

@@ -0,0 +1,48 @@
+# Confirm Implementation Forks
+
+**When this applies:** During planning or implementation, whenever two or more viable paths would satisfy the goal and the choice changes the deliverable — its scope, completeness, the work it defers, the dependencies it adds, or a contract that is hard to reverse.
+
+## Rule
+
+At a material fork, stop and ask the user which path to take through `AskUserQuestion`. Do not silently pick one path and proceed. Present each path as an option whose description states its tradeoff: what it delivers, what it defers, the follow-up cost it creates, and how reversible it is. Begin implementing only after the user chooses.
+
+A fork is **material** when any of these hold:
+
+- The paths produce different deliverables, scope, or completeness against the stated target.
+- One path defers work — a stub, placeholder, or partial wiring — that creates a follow-up task or hidden debt, while another path completes the work in the same change.
+- The paths diverge on something hard to reverse: architecture, a public API or contract, a data schema, or a newly added dependency.
+- The choice trades off something the user has a stake in: speed against completeness, a scope cut against full coverage, or a shortcut against the original plan's target.
+
+When one path quietly drops part of the requested outcome or leaves work for later, that gap is itself the fork — surface it rather than choosing the smaller deliverable on the user's behalf.
+
+## Not a fork — just proceed
+
+- Trivially reversible, internal-only choices with no deliverable impact (a local variable name, the layout of a private helper, one of two equivalent standard-library calls).
+- The codebase, the user's stated goal, or an existing rule already determines the answer — follow it (see `verify-before-asking`), and do not manufacture a choice.
+- Only one path is actually viable — implement it; a false choice wastes a round-trip.
+
+## How to ask
+
+- Write the question and every option in plain language — short, common words and concrete phrasing a non-expert grasps on first read. Spell out or drop jargon, internal names, and acronyms the user has not already used.
+- Give just enough to decide (progressive disclosure): state each path's outcome and its main tradeoff in a sentence or two, and hold deeper detail in reserve for when the user asks. Do not paste code, long file lists, or background the choice does not need — extra information raises the reader's effort without improving the decision.
+- One option per path. Keep each `label` short; put the tradeoff in the `description`.
+- Recommend the path that best meets the user's stated target and list it first, flagged as recommended (per the AskUserQuestion directive in `CLAUDE.md`).
+- Hold all edits to the forked area until the answer arrives. Continue unrelated, unambiguous work if it helps.
+
+## Examples
+
+**Wrong:** Reach a point where the feature can be completed or partially wired with a placeholder, pick the placeholder, and move on — leaving the real implementation as an unrequested follow-up.
+**Right:** Ask: "Complete the feature in this change, or land a placeholder and track the rest as a follow-up?" with each option's cost stated, and wait for the choice.
+
+**Wrong:** Add a third-party dependency to solve a problem a few lines of existing code could handle, without flagging it.
+**Right:** Ask whether to add the dependency or hand-roll the small helper, naming the maintenance and footprint tradeoff.
+
+## Why
+
+A fork is a scope-or-direction decision the user holds a stake in. Choosing silently commits their effort and tokens to a path they may not want, and a deferred-work path can hide a follow-up the user never agreed to. Surfacing the fork once, with the tradeoffs visible, costs one round-trip and avoids rework.
+
+## Relationship to other rules
+
+- **verify-before-asking** gates *whether* a question belongs to the user; a material fork is a judgment or scope call that always does. Resolve anything the codebase can answer first, then ask only about the genuine choice.
+- **conservative-action** governs *whether* to act when intent is ambiguous; this rule names a specific trigger — divergent viable paths — that demands a choice before acting.
+- **ask-user-question-required** governs *how* to ask: route the fork through `AskUserQuestion`, never a plain-text question.

package/rules/plain-language.md

@@ -0,0 +1,44 @@
+# Plain Language
+
+**When this applies:** All prose you write — chat responses, `AskUserQuestion` questions and options, documentation and Markdown, PR and issue bodies, and commit messages. Anything a person reads.
+
+**Hook enforcement:** `plain_language_blocker` (PreToolUse on `AskUserQuestion` and on Write|Edit|MultiEdit of `.md` targets) blocks a heavy word and names the everyday word to swap in. Code fences, inline code, blockquotes, URLs, and file paths are skipped so exact identifiers stay untouched. See `hooks.json` for registration.
+
+## Rule
+
+Write so the reader understands it on the first pass, without hunting for extra context and without wading through more than the point requires. Favor everyday words, short sentences, and concrete phrasing. This is **plain language** (ISO 24495-1:2023; U.S. Plain Writing Act of 2010) — clear writing, not dumbed-down writing.
+
+Plain language does not mean dropping technical terms. It means:
+
+- **Common word first.** Reach for the plain word when one carries the meaning (`use` over `utilize`, `start` over `initiate`, `enough` over `sufficient`). Keep a technical term when it is the precise name for the thing.
+- **Define jargon and acronyms on first use** — unless the reader has already used them or they are core to the domain you share.
+- **Short sentences, active voice.** One idea per sentence. Name the actor (`the hook blocks the write`, not `the write is blocked by the hook`).
+- **Lead with the answer.** State the conclusion or recommendation first; supporting detail follows.
+
+## Give only what's needed (progressive disclosure)
+
+Match the amount of information to what the reader needs to act, and hold the rest in reserve until they ask. Surplus detail raises the reader's **cognitive load** without improving the decision.
+
+- Answer the question that was asked; do not also explain three adjacent things.
+- Put the essential point in the first sentence or two; offer or link depth rather than front-loading it.
+- In an `AskUserQuestion`, state each option's outcome and main tradeoff in a sentence; skip code dumps and long file lists.
+- Cut preamble and recap. Do not restate the task back before answering it.
+
+## Readability check
+
+Before sending, reread as the recipient: does every sentence land on first read, with no term they must look up and no detail they did not need? If a sentence only makes sense to someone who already knows the backstory, rewrite or cut it. Aim for wording a non-specialist in that area can follow (roughly an 8th–10th grade reading level for general prose; technical reference may sit higher where the terms are unavoidable).
+
+## Not in scope
+
+- **Necessary technical precision.** Exact identifiers, file paths, API names, and domain terms stay exact — plain language sharpens the words around them, it does not blur the terms themselves.
+- **Code.** Naming and structure follow the code standards; this rule governs prose.
+
+## Why
+
+The reader is short on time and attention, and the first pass is often the only pass. Plain wording and right-sized detail carry the point across in that one pass, while dense or padded text forces the reader to do work the writer should have done. Clear writing also exposes unclear thinking: if an idea is hard to say plainly, it may not be settled yet.
+
+## Relationship to other rules
+
+- **confirm-implementation-forks** ("How to ask") applies this rule to fork questions: plain wording, only the detail needed to choose.
+- **self-contained-docs** and **no-historical-clutter** keep a document understandable without outside context; plain language keeps the sentences themselves easy to read.
+- **ask-user-question-required** routes questions through `AskUserQuestion`; this rule governs how those questions are worded.

package/rules/vault-context.md

@@ -10,7 +10,7 @@ An Obsidian vault stores session reports, decisions, and research documents acro
 
 ## Vault Structure
 
-- `sessions/` -- session reports with frontmatter: `type: session-report`, `project`, `session`, `date`, `status`, `blocked`, `vault_context_retrieved`, `tags`
+- `sessions/` -- session reports with frontmatter: `type: session-report`, `project`, `session`, `session_id`, `date`, `status`, `blocked`, `vault_context_retrieved`, `tags`
 - `decisions/` -- decision notes with frontmatter: `type: decision|procedural|fact|gotcha`, `project`, `date`, `status: Active|Superseded`, `tags`
 - `Research/` -- deep research documents
 
@@ -31,4 +31,6 @@ At the end of substantive sessions, offer to run `/session-log` if not already i
 
 When running `/session-log`, include `vault_context_retrieved: true|false` in frontmatter based on whether vault MCP tools were used this session.
 
+Also include `session_id` in frontmatter — the session ID of the agent authoring the log, read from the `CLAUDE_CODE_SESSION_ID` environment variable. This UUID names the authoring agent's own transcript file (`<session-id>.jsonl`), so the report points back to the session that produced it; use the literal `unknown` when the variable is unset.
+
 After writing a session log, ALWAYS output a `/rename` command with a descriptive session name based on the session's primary outcome. Format: `/rename [Project] - [Primary Outcome]`. This is a mandatory output requirement, not optional.

package/skills/pr-converge/SKILL.md

@@ -2,9 +2,10 @@
 name: pr-converge
 description: >-
   Drives the current PR to convergence by looping Cursor Bugbot, a
-  second-opinion bug audit, and Copilot — applying TDD fixes, posting
-  inline replies, and re-triggering reviewers each tick until all three
-  reviewers are clean on the same HEAD. Use when the user says
+  code-review pass, a second-opinion bug audit, and Copilot — applying
+  TDD fixes, posting inline replies, and re-triggering reviewers each
+  tick until all reviewers are clean on the same HEAD. Use when the user
+  says
   '/pr-converge', 'drive PR to convergence', 'loop bugbot and bugteam',
   'babysit bugbot and bugteam', 'until both are clean', or 'converge this
   PR'.
@@ -12,8 +13,8 @@ description: >-
 
 # PR Converge
 
-One tick per invocation. Bugbot ↔ bugteam ↔ Copilot loop on a draft PR
-until all three are clean on the same `HEAD` and mergeable.
+One tick per invocation. Bugbot ↔ code-review ↔ bugteam ↔ Copilot loop on
+a draft PR until all are clean on the same `HEAD` and mergeable.
 
 ## Pre-flight
 
@@ -37,9 +38,10 @@ On tick entry, read this file if it exists to restore phase, tick_count, and
 clean-at SHAs. On tick exit, write updated state before calling ScheduleWakeup
 so the next tick resumes with accurate state.
 
-Fields: `phase`, `tick_count`, `bugbot_clean_at`, `bugteam_clean_at`,
-`copilot_clean_at`, `current_head`, `bugbot_acknowledged_at`, `bugbot_down`,
-`bugteam_skill_invoked_at_head`, `bugteam_skill_invoked_at_tick`.
+Fields: `phase`, `tick_count`, `bugbot_clean_at`, `code_review_clean_at`,
+`bugteam_clean_at`, `copilot_clean_at`, `current_head`,
+`bugbot_acknowledged_at`, `bugbot_down`, `bugteam_skill_invoked_at_head`,
+`bugteam_skill_invoked_at_tick`.
 
 ## Gotchas
 
@@ -85,7 +87,8 @@ post a fresh PR in a fresh branch based on origin main to the user.
 
 ## Progress checklist
 
-State variables (`phase`, `bugbot_clean_at`, `copilot_clean_at`, counters) are
+State variables (`phase`, `bugbot_clean_at`, `code_review_clean_at`,
+`copilot_clean_at`, counters) are
 defined in [`reference/state-schema.md`](reference/state-schema.md). Ground rules
 in [`reference/ground-rules.md`](reference/ground-rules.md).
 
@@ -127,7 +130,7 @@ no longer applies.
 
       - [ ] **Opt-out gate (runs first, every BUGBOT entry).**
             `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugbot`
-            - [ ] Exit 0 (`CLAUDE_REVIEWS_DISABLED` lists `bugbot`) → set `bugbot_down = true`, `phase = BUGTEAM`, advance to Step 5 (bypass). Cursor Bugbot is skipped for the entire run.
+            - [ ] Exit 0 (`CLAUDE_REVIEWS_DISABLED` lists `bugbot`) → set `bugbot_down = true`, `phase = CODE_REVIEW`, advance to Step 5 (bypass). Cursor Bugbot is skipped for the entire run.
             - [ ] Exit 1 → continue below.
 
       Fetch bugbot reviews + inline comments on `current_head`.
@@ -140,23 +143,45 @@ no longer applies.
       - [ ] **clean** (no findings on `current_head`) →
             - [ ] Count ALL unresolved threads on PR (`is_resolved == false`) → zero? advance; >0? fix + resolve first
             - [ ] `bugbot_clean_at = current_head`
+            - [ ] `phase = CODE_REVIEW`
             - [ ] Advance to Step 5
       - [ ] **no review yet / commit_id mismatch** →
             - [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --check-clean --sha <current_head>`
-            - [ ] Exit 0 (bugbot CI completed with success/neutral conclusion and no review = silent pass) → `bugbot_clean_at = current_head` → advance to Step 5
+            - [ ] Exit 0 (bugbot CI completed with success/neutral conclusion and no review = silent pass) → `bugbot_clean_at = current_head` → `phase = CODE_REVIEW` → advance to Step 5
             - [ ] Exit 1 (not a silent pass) or Exit 2 (gh CLI error — silent pass not confirmable) → Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --check-active --sha <current_head>`
             - [ ] Exit 0 (already queued) → schedule 360s wakeup → return to Step 4 next tick
             - [ ] Exit 1 → post exactly `bugbot run` via `add_issue_comment` (no `@cursor[bot]` mention, no other text), wait 8s
             - [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --sha <current_head>`
-            - [ ] Exit non-zero → `bugbot_down = true` → advance to Step 5 (bypass)
+            - [ ] Exit non-zero → `bugbot_down = true` → `phase = CODE_REVIEW` → advance to Step 5 (bypass)
             - [ ] Exit 0 → record `bugbot_acknowledged_at`, schedule 360s wakeup → return to Step 4
-- [ ] **Step 5: BUGTEAM — run, decide, fix, reply, resolve**
+- [ ] **Step 5: CODE-REVIEW — run, fix, reset, advance**
+      See: [`reference/per-tick.md` § Step 2 CODE_REVIEW](reference/per-tick.md)
+
+      Pre-condition: `bugbot_clean_at == current_head` (or `bugbot_down == true`).
+
+      Run Claude Code's built-in `/code-review --fix` on the current diff —
+      the [local diff review](https://code.claude.com/docs/en/code-review#review-a-diff-locally)
+      — so it reviews the diff and applies its findings to the working
+      tree. Pass no effort argument, so the review uses the session's
+      current effort.
+
+      - [ ] **fixes applied** (working tree changed) →
+            - [ ] Commit the applied fixes (one commit) → push
+            - [ ] reset `bugbot_clean_at = null`, `code_review_clean_at = null`
+            - [ ] Re-trigger bugbot (Step 4 "no review yet" checklist)
+            - [ ] `phase = BUGBOT` → schedule 360s wakeup → return to Step 4
+      - [ ] **clean** (no changes applied) →
+            - [ ] Count ALL unresolved threads on PR (`is_resolved == false`) → zero? advance; >0? fix + resolve first
+            - [ ] `code_review_clean_at = current_head`
+            - [ ] `phase = BUGTEAM` → advance to Step 6
+
+- [ ] **Step 6: BUGTEAM — run, decide, fix, reply, resolve**
       See: [`reference/per-tick.md` § Step 2 BUGTEAM](reference/per-tick.md);
       [`../../bugteam/SKILL.md`](../../bugteam/SKILL.md)
 
-      Pre-condition: `bugbot_clean_at == current_head` (or `bugbot_down == true`).
+      Pre-condition: `code_review_clean_at == current_head`.
 
-      Step 5 advances ONLY after `Skill({skill: "bugteam", args: "<PR URL>"})`
+      Step 6 advances ONLY after `Skill({skill: "bugteam", args: "<PR URL>"})`
       fires this tick. Substituting an `Agent({subagent_type: "clean-coder"})`
       audit call for the formal Skill invocation is a protocol violation — the
       `pr_converge_bugteam_enforcer` hook blocks it. `qbug` is NOT an accepted
@@ -170,7 +195,7 @@ no longer applies.
             - [ ] `phase = BUGBOT` → schedule 360s wakeup → return to Step 4
       - [ ] **converged (zero findings) + `bugbot_clean_at == current_head`** →
             - [ ] Count ALL unresolved threads on PR (`is_resolved == false`) → zero? advance; >0? fix + resolve first
-            - [ ] Advance to Step 6
+            - [ ] Advance to Step 7
       - [ ] **converged + `bugbot_clean_at ≠ current_head`** →
             `phase = BUGBOT` → schedule 360s wakeup → return to Step 4
       - [ ] **findings without committed fixes** →
@@ -179,10 +204,10 @@ no longer applies.
             - [ ] Resolve each addressed thread via `pull_request_review_write(method="resolve_thread")`
             - [ ] Push → `phase = BUGBOT` → return to Step 4
 
-- [ ] **Step 6: Convergence gates**
+- [ ] **Step 7: Convergence gates**
       See: [`reference/convergence-gates.md`](reference/convergence-gates.md)
 
-      Pre-condition: Step 5 converged AND `bugbot_clean_at == current_head`.
+      Pre-condition: Step 6 converged AND `bugbot_clean_at == current_head`.
       Count unresolved threads before each gate.
 
       **(a) Universal unresolved-thread sweep**
@@ -221,7 +246,7 @@ no longer applies.
             gh api --method POST repos/<O>/<R>/pulls/<N>/requested_reviewers \
               -f 'reviewers[]=copilot-pull-request-reviewer[bot]'
             ```
-      - [ ] `phase = COPILOT_WAIT` → schedule 360s wakeup → return to Step 6a next tick
+      - [ ] `phase = COPILOT_WAIT` → schedule 360s wakeup → return to Step 7a next tick
 
       **(d) Thread resolution — author-agnostic, outdated-agnostic**
       ```
@@ -240,17 +265,17 @@ no longer applies.
             python $HOME/.claude/skills/pr-converge/scripts/check_convergence.py \
               --owner <O> --repo <R> --pr-number <N>
             ```
-      - [ ] Exit 0 (all pass) → `update_pull_request(draft=false)` → advance to Step 7
+      - [ ] Exit 0 (all pass) → `update_pull_request(draft=false)` → advance to Step 8
       - [ ] Exit 1 (FAIL lines) → address each failure → return to Step 4
       - [ ] Exit 2 (gh error) → retry once; persistent → stop
 
-- [ ] **Step 6a: COPILOT_WAIT — fetch Copilot, decide**
+- [ ] **Step 7a: COPILOT_WAIT — fetch Copilot, decide**
       See: [`reference/per-tick.md` § Step 2 COPILOT_WAIT](reference/per-tick.md)
 
       Fetch Copilot reviews + inline comments on `current_head`.
 
       - [ ] **clean (no findings)** →
-            `copilot_clean_at = current_head` → return to Step 6 (re-validate gates b, d, e)
+            `copilot_clean_at = current_head` → return to Step 7 (re-validate gates b, d, e)
       - [ ] **dirty (findings present)** →
             - [ ] Fix each finding (spawn `clean-coder`)
             - [ ] Reply to each finding comment via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py`
@@ -258,18 +283,18 @@ no longer applies.
             - [ ] Push → `phase = BUGBOT` → return to Step 4
       - [ ] **no review yet** →
             increment `copilot_wait_count` → ≥ 3 = hard blocker → stop
-            schedule 360s wakeup → return to Step 6a next tick
+            schedule 360s wakeup → return to Step 7a next tick
 
-- [ ] **Step 7: Clean working tree**
+- [ ] **Step 8: Clean working tree**
       See: [`bugteam/reference/teardown-publish-permissions.md` § Step 4](../../bugteam/reference/teardown-publish-permissions.md)
 
-- [ ] **Step 8: Rewrite PR description**
+- [ ] **Step 9: Rewrite PR description**
       See: [`bugteam/reference/teardown-publish-permissions.md` § Step 4.5](../../bugteam/reference/teardown-publish-permissions.md)
 
-- [ ] **Step 9: Revoke project permissions**
+- [ ] **Step 10: Revoke project permissions**
       `python "$HOME/.claude/skills/bugteam/scripts/revoke_project_claude_permissions.py"`
 
-- [ ] **Step 10: Print final report**
+- [ ] **Step 11: Print final report**
       ```
       /pr-converge exit: converged
       Loops: <N>

package/skills/pr-converge/reference/examples.md

@@ -20,8 +20,19 @@ convergence or stop]
 </example>
 
 <example> BUGBOT tick, bugbot clean against HEAD. Claude: [sets
-`bugbot_clean_at = HEAD`, `phase = BUGTEAM`, runs `Skill({skill: "bugteam",
-...})` in same tick]
+`bugbot_clean_at = HEAD`, `phase = CODE_REVIEW`, runs `/code-review --fix`
+in same tick]
+</example>
+
+<example> CODE_REVIEW tick, `/code-review --fix` applies fixes to the
+working tree. Claude: [commits the applied fixes in one commit, pushes,
+resets `bugbot_clean_at = null` and `code_review_clean_at = null`, posts
+`bugbot run`, `phase = BUGBOT`, Step 4 at 270s, returns]
+</example>
+
+<example> CODE_REVIEW tick, `/code-review --fix` clean (no changes
+applied). Claude: [sets `code_review_clean_at = HEAD`, `phase = BUGTEAM`,
+runs `Skill({skill: "bugteam", ...})` in same tick]
 </example>
 
 <example> BUGTEAM phase, bugteam reports convergence and `bugbot_clean_at