claude-dev-env 1.46.0 → 1.48.0

package/CLAUDE.md

@@ -1,10 +1,16 @@
 # Claude Development Assistant
 
+The user is short on time and tokens. When you reply, always assume they'll only read your first few sentences and final sentences. Anything else is skimmed at best. Frame your replies accordingly.
+
+The user is short on tokens; whenever a task can be achieved cleanly and effectively, optimize to save the user $$ and token usage.
+
 The user delegates execution to you and expects zero manual steps unless strictly necessary. Execute every command you can directly. Only instruct the user to do something manually when you are technically unable to do it yourself. When a task involves credentials or other sensitive input, display a minimal secure UI (e.g., a password dialog) to collect it rather than asking the user to paste it into chat or run the command themselves. When direction is ambiguous, use AskUserQuestion to clarify before acting.
 
 ## Code Rules
 @~/.claude/docs/CODE_RULES.md
 
+When an edit deletes or rewrites code, delete everything it orphans in the same edit — unused variables, uncalled functions, unpassed parameters, dead branches, unused imports — once Serena's `find_referencing_symbols` (plus a text search for dynamic lookups) confirms they're unreachable from any live entry point, not merely unreferenced; when liveness is uncertain, ask via AskUserQuestion rather than risk deleting live code (CODE_RULES.md §9.8).
+
 ALWAYS call the AskUserQuestion tool if you have a question for the user. Provide content-appropriate default options, with a flag for the recommended one.
 
 ## Timeless Documentation (all `.md` files)
@@ -18,7 +24,10 @@ Full banned-pattern set + enforcement: `~/.claude/rules/no-historical-clutter.md
 
 ## GOTCHAS
 When making code changes, make sure you are working in the proper worktree path for the task at hand.
-When writing to an existing file, you must either EDIT the file, or remove it and THEN re-write it if it's truly a full re-write.
+
+## Choosing Edit vs Write
+
+`Edit` changes existing files; `Write` creates new ones. Default to `Edit` — reach for `Write` only for a genuinely new path. For a true full rewrite, delete the file first, then `Write`.
 
 ## File-Global Constants
 
@@ -43,3 +52,4 @@ Reserve `Read`/`Grep`/`Glob` for files you will actually touch this turn. Compos
 ## Additional Non-overlapping Rules
 
 - **task_scope:** Match every action to what was explicitly requested. When intent is ambiguous, research official docs and present options via AskUserQuestion before making any changes. Proceed with edits only on explicit instruction.
+- **confirm_implementation_forks:** When two or more viable paths would satisfy the goal and the choice changes the deliverable — its scope, completeness, deferred work, dependencies, or a hard-to-reverse contract — stop and ask which path via AskUserQuestion before implementing. A path that defers work or leaves a placeholder creating a follow-up task is itself a fork to surface, not a default to take silently. Phrase the question in plain language with only the detail needed to decide. See [`confirm-implementation-forks`](rules/confirm-implementation-forks.md).

package/docs/CODE_RULES.md

@@ -288,6 +288,31 @@ Fallback values mask programming errors (KeyError vs RuntimeError vs AttributeEr
 
 ---
 
+## 9.8 REMOVE CODE YOU ORPHAN (Dead Code Elimination)
+
+When an edit deletes or rewrites code, it must also remove everything that edit makes dead. The change is not complete while orphans remain.
+
+After deleting or rewriting code, trace what it referenced and remove whatever is unreachable as a result:
+
+- **Variables** with no remaining readers after the change
+- **Functions / methods** with no remaining call sites
+- **Parameters** that no caller passes
+- **Branches** made unreachable (dead `if`/`else`, conditions that are always true or always false)
+- **Imports** left unused (also caught by the unused-import hook)
+- **Helper files** whose only consumer you just deleted
+
+**Confirm the orphan is truly unreferenced first.** "No remaining call sites" means none *anywhere in the codebase*, not just in the file you edited. Before removing a function, method, class, or module-level name, run Serena's `find_referencing_symbols` on it: the language server resolves call sites, `import` statements, and re-exports across files far more reliably and cheaply than a text sweep. Back it with a plain text search for string-based dynamic lookups (`getattr`, entry-point names) that the language server cannot see. A reference is not proof of life — the referrer can be dead too. The symbol is live only when some chain of references reaches a live entry point: a CLI command, route, public API, test, or any caller outside the code you are removing. Trace the referrers upward. If every chain dead-ends in code that is itself unreferenced, the whole cluster is dead — remove it together in the same commit (§9.6). If any chain reaches a live entry point, the symbol is in use; leave it. Deleting something still reachable breaks its importers; treating a self-referential dead cluster as alive leaves litter.
+
+**When liveness is uncertain, ask — never guess.** A tool cannot always tell what is live: a chain may leave the repository (a public API, plugin hook, or module other projects import), or run through dynamic or reflective dispatch that no search resolves. If you cannot conclusively prove a symbol is unreachable, do not delete it. Surface the specific ambiguity to the user through AskUserQuestion and let them decide. Removing live production code is never an acceptable risk — when in doubt, keep it and ask.
+
+This is the inverse of comment preservation: existing **comments** are sacred and never removed, but dead **code** is removed in the same edit that orphans it. A function left with no callers is not "preserved" — it is litter.
+
+> **See also:** §9.6 (a renamed alias is dead code by another name), the `file_global_constants_use_count` rule (zero references → delete), and the unused-import hook check — each enforces a specific slice of this principle automatically.
+
+> **Standard terms (shorthand for this section):** the mechanical part is *dead code elimination* (compilers; Aho et al., *Compilers: Principles, Techniques, and Tools*) and *tree-shaking* (bundlers like Rollup/Webpack) — retain only what is reachable from a live entry point. The ask-when-uncertain overlay guards against the *Lava Flow* anti-pattern — dead code kept because removing it feels risky (Brown et al., *AntiPatterns*, 1998). Compare Fowler's "Remove Dead Code" refactoring (*Refactoring*, 2nd ed., 2018). Direct source links: [`references/dead-code-elimination.md`](references/dead-code-elimination.md).
+
+---
+
 ## 10. NO REDUNDANT DATA FETCHES
 
 If you already have data, don't fetch again.
@@ -384,5 +409,6 @@ Manual check:
 [ ] OCP/LSP/ISP/DIP only applied where abstractions already earn their keep (see §7.5)?
 [ ] No backwards-compatibility shims (§9.6)?
 [ ] No fallback/best-effort wrappers (§9.7)?
+[ ] No code orphaned by an edit (§9.8 — dead vars, uncalled functions, unused imports, dead branches)?
 [ ] Readability: /check
 ```

package/docs/references/dead-code-elimination.md

@@ -0,0 +1,17 @@
+# Dead Code Elimination — Reference
+
+External sources and standard terminology behind [CODE_RULES §9.8](../CODE_RULES.md#98-remove-code-you-orphan-dead-code-elimination). Each entry names the concept, gives a one-line definition, and links a direct source.
+
+## The mechanic — removing code that cannot affect results
+
+- **Dead-code elimination (DCE)** — a compiler optimization that removes code which does not affect program results, reducing program size, resource use, and execution time. Foundational treatment: Aho, Lam, Sethi & Ullman, *Compilers: Principles, Techniques, and Tools* (the "Dragon Book"). <https://en.wikipedia.org/wiki/Dead-code_elimination>
+- **Tree shaking** — dead-code elimination driven by `import`/`export` structure: keep only the exports reachable from an entry point and drop the rest. MDN glossary: <https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking>. Webpack guide: <https://webpack.js.org/guides/tree-shaking/>
+- **Remove Dead Code** — the named refactoring for eliminating unreachable or unused segments to improve clarity and maintainability. Martin Fowler, *Refactoring* (2nd ed., 2018): <https://refactoring.com/catalog/removeDeadCode.html>
+
+## The liveness test — reachability, not mere reference
+
+- **Unreachable code / reachability analysis** — code with no control-flow path from the rest of the program; detecting it is a form of control-flow analysis. This is the basis for §9.8 testing reachability from a live entry point rather than the bare presence of a reference. <https://en.wikipedia.org/wiki/Unreachable_code>
+
+## The safety overlay — why uncertain deletions escalate
+
+- **Lava Flow anti-pattern** — suboptimal code that survives in production because accumulated dependencies and backward-compatibility fears make removal feel risky. Brown, Malveau, McCormick & Mowbray, *AntiPatterns* (1998). The §9.8 "ask when uncertain, never guess-delete" clause guards against blind risky removals. <https://en.wikipedia.org/wiki/Lava_flow_(programming)>

package/hooks/blocking/content_search_zoekt_redirect_guidance.py

@@ -32,6 +32,14 @@ def get_zoekt_redirect_guidance() -> str:
         "positively, e.g. mcp__zoekt__search(query=\"your pattern file:"
         + worktree_filter_fragment
         + "<branch>/\").\n\n"
+        "INDEX FRESHNESS: the index trails just-written code — recent or unpushed commits sync and reindex "
+        "on a short delay, so a symbol you just added can be missing from Zoekt for a few minutes even though "
+        "it is on disk. Worktrees are fully indexed and retrievable with the positive 'file:"
+        + worktree_filter_fragment
+        + "<branch>/' filter above, but that same lag applies to anything freshly edited. When a Zoekt search "
+        "returns nothing for code you know exists on disk, do not treat it as absent: Grep a specific file "
+        "(a path ending in a file extension is exempt from this redirect) or read the file directly to confirm "
+        "current contents.\n\n"
         "INDEX ROOTS (when Grep/Search in a tree is redirected): set ZOEKT_REDIRECT_INDEXED_ROOTS to a JSON array "
         "of absolute paths, or ~/.claude/zoekt-indexed-roots.json as {\"roots\": [\"/abs/path/to/repo/\", ...]}. "
         "Optional ZOEKT_REDIRECT_INDEXED_ROOTS_FILE points to a different JSON file. "

package/hooks/blocking/test_content_search_to_zoekt_redirector_unit.py

@@ -81,6 +81,12 @@ class RedirectGuidanceWorktreeTests(unittest.TestCase):
     def test_worktree_display_fragment_is_the_unescaped_path(self) -> None:
         self.assertEqual(worktree_path_display_fragment(), ".claude/worktrees/")
 
+    def test_guidance_documents_index_freshness_escape_hatch(self) -> None:
+        guidance = get_zoekt_redirect_guidance()
+        self.assertIn("INDEX FRESHNESS:", guidance)
+        self.assertIn("exempt from this redirect", guidance)
+        self.assertIn("read the file directly", guidance)
+
 
 if __name__ == "__main__":
     unittest.main()

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.46.0",
+    "version": "1.48.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,42 @@
+# 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.
+
+## 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

package/skills/pr-converge/reference/ground-rules.md

@@ -6,10 +6,12 @@
 - **All `*_clean_at`, `merge_state_status`, and `bugbot_down` reset on every push.**
 - **`bugbot run` comment is load-bearing.** Literal phrase exactly —
   empirically the only re-trigger Cursor Bugbot recognizes.
-- **All production edits go through `clean-coder`.** The lead never edits
-  production files directly. Every fix — bugbot, bugteam, Copilot, or
-  Claude finding — spawns `Agent(subagent_type="clean-coder")` to
-  implement. No exceptions.
+- **Production edits go through `clean-coder`, except `/code-review --fix`.**
+  The lead never hand-edits production files. Every bugbot, bugteam,
+  Copilot, or Claude finding spawns `Agent(subagent_type="clean-coder")` to
+  implement the fix. The CODE_REVIEW phase is the one exception: `/code-review
+  --fix` applies its own findings to the working tree, which the next
+  BUGBOT/BUGTEAM cycle re-reviews after the loop resets.
 - **Adapt when reality contradicts on-disk state.** If `state.json`,
   `git`, or `gh` disagree with live PR, escalate as hard blocker per
   [stop-conditions.md](stop-conditions.md).

package/skills/pr-converge/reference/per-tick.md

@@ -53,7 +53,7 @@ Capture `number`, `head.sha` (= `current_head`), owner/repo, branch.
 `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`, continue BUGTEAM in the same tick; skip steps a–c below.
+  `phase = CODE_REVIEW`, continue CODE_REVIEW in the same tick; skip steps a–c below.
 - Exit 1 → proceed to step a.
 
 Because `bugbot_down` resets on every push, this gate re-runs on every
@@ -99,9 +99,9 @@ c. Decide (four branches; match first whose predicate holds):
      null`, reset `inline_lag_streak = 0`, schedule next wakeup, return.
    - **`commit_id == current_head` AND zero unaddressed inline AND review
      body clean:** Set `bugbot_clean_at = current_head`, reset
-     `inline_lag_streak = 0`, `phase = BUGTEAM`. Continue BUGTEAM in same
-     tick — back-to-back convergence requires bugteam on same HEAD
-     before next wakeup.
+     `inline_lag_streak = 0`, `phase = CODE_REVIEW`. Continue CODE_REVIEW
+     in same tick — back-to-back convergence requires code-review then
+     bugteam on same HEAD before next wakeup.
    - **`commit_id == current_head` with unaddressed inline findings:**
      Apply **Fix protocol**. Reset `inline_lag_streak = 0`. With
      `state.json`: clean-coder teammate pushes, replies inline, writes
@@ -113,6 +113,33 @@ c. Decide (four branches; match first whose predicate holds):
      full contract).
      Schedule next wakeup, return.
 
+### `phase == CODE_REVIEW`
+
+Local correctness/quality pass between BUGBOT clean and BUGTEAM. Enters
+after BUGBOT reports clean on `current_head` (or `bugbot_down == true`).
+Runs Claude Code's built-in `/code-review --fix` on the current diff; it
+produces no GitHub review artifact, so there are no code-review threads to
+resolve.
+
+a. 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).
+   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.
+
+b. Decide (two branches; match first whose predicate holds):
+
+   - **`/code-review` applied fixes (working tree changed):** Commit the
+     applied fixes in one commit → push, following [Single-PR fix
+     workflow](fix-protocol.md#single-pr-fix-workflow). Reset
+     `bugbot_clean_at = null` AND `code_review_clean_at = null`. Re-trigger
+     bugbot (Step 3) so the new HEAD enters the queue. Set `phase = BUGBOT`,
+     schedule next wakeup, return. A code-review fix push requires a full
+     back-to-back-clean cycle on the new HEAD.
+   - **Clean (no changes applied):** Set
+     `code_review_clean_at = current_head`, `phase = BUGTEAM`. Continue
+     BUGTEAM in same tick — back-to-back convergence requires bugbot,
+     code-review, and bugteam all clean on the same HEAD.
+
 ### `phase == BUGTEAM`
 
 a. Run **bugteam** on current PR.
@@ -222,14 +249,14 @@ BUGBOT.
   `bugbot_down = true` and routes to BUGTEAM before any trigger flow runs,
   so the checks below are skipped.
 - [ ] **Silent-pass pre-check.** Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --check-clean --owner <O> --repo <R> --sha <current_head>`
-- [ ] Exit 0 → bugbot CI completed clean with no review (silent pass); set `bugbot_clean_at = current_head`, `phase = BUGTEAM`, continue BUGTEAM same tick
+- [ ] Exit 0 → bugbot CI completed clean with no review (silent pass); set `bugbot_clean_at = current_head`, `phase = CODE_REVIEW`, continue CODE_REVIEW same tick
 - [ ] Exit 1 (not a silent pass) or Exit 2 (gh CLI error — silent pass not confirmable) → continue with the trigger flow below
 - [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --check-active --owner <O> --repo <R> --sha <current_head>`
 - [ ] Exit 0 → bugbot already queued on this commit; skip posting, wait for completion
 - [ ] Exit 1 → post trigger via `add_issue_comment(owner="OWNER", repo="REPO", issueNumber=NUMBER, body="bugbot run")`
 - [ ] Wait 8s
 - [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --sha <current_head>`
-- [ ] Exit non-zero → bugbot is down; set `bugbot_down = true`, `phase = BUGTEAM`, continue BUGTEAM same tick
+- [ ] Exit non-zero → bugbot is down; set `bugbot_down = true`, `phase = CODE_REVIEW`, continue CODE_REVIEW same tick
 - [ ] Exit 0 (check run present) → record `bugbot_acknowledged_at = <now ISO 8601>`, proceed to Step 4
 
 The silent-pass pre-check fires FIRST so we never re-trigger a bot that

package/skills/pr-converge/reference/state-schema.md

@@ -9,9 +9,13 @@ across PRs. Both files share most of the fields below; the
 live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
 (see those field entries below for details).
 
-- `phase`: `BUGBOT`, `BUGTEAM`, or `COPILOT_WAIT`. Start `BUGBOT` on first tick.
+- `phase`: `BUGBOT`, `CODE_REVIEW`, `BUGTEAM`, or `COPILOT_WAIT`. Start
+  `BUGBOT` on first tick.
 - `bugbot_clean_at`: HEAD SHA where bugbot last reported clean, or `null`.
   Reset to `null` on every push.
+- `code_review_clean_at`: HEAD SHA where the `/code-review` pass last
+  reported clean (no validated findings), or `null`. Reset to `null` on
+  every push.
 - `copilot_clean_at`: HEAD SHA where Copilot last reported clean, or `null`.
   Reset to `null` on every push.
 - `copilot_wait_count`: integer, init `0`. Consecutive COPILOT_WAIT ticks

package/skills/pr-converge/workflows/schedule-wakeup-loop.md

@@ -6,8 +6,9 @@ guarantees `ScheduleWakeup` is available before any tick runs. Shared bugbot
 
 ## Calling ScheduleWakeup
 
-At end of every tick — across all phases (BUGBOT, BUGTEAM, COPILOT_WAIT)
-without distinction — call `ScheduleWakeup` unless convergence or another
+At end of every tick — across all phases (BUGBOT, CODE_REVIEW, BUGTEAM,
+COPILOT_WAIT) without distinction — call `ScheduleWakeup` unless convergence
+or another
 stop condition already omitted pacing:
 
 - `delaySeconds: 360` — default wakeup interval. Keeps the loop advancing

package/skills/pre-compact/SKILL.md

@@ -5,8 +5,10 @@ description: >-
   `/compact <directive>` string to the operator's clipboard so the next prompt
   is a single paste. The directive pins the session's load-bearing identifiers
   (branch, PR, HEAD, worktree, in-flight work, decisions, blockers, files in
-  play, follow-ups) and lists the redundant tool outputs the summarizer should
-  drop. Use when the user says `/pre-compact`, asks to prep for compaction, or
+  play, follow-ups) the next steps depend on, so the summarizer keeps them with
+  high fidelity. It confirms the operator's intent for the next chat through a
+  structured question first, then validates each identifier against its live
+  source before stating it. Use when the user says `/pre-compact`, asks to prep for compaction, or
   asks to compose a focus directive for `/compact`.
 disable-model-invocation: true
 ---
@@ -20,16 +22,35 @@ string to the operator's clipboard.
 
 **Announce at start:** "I'm composing your compact focus directive."
 
-## Step 1 — Read the live session
-
-Pull the load-bearing identifiers from the current conversation. Run
-`git status`, `git rev-parse --short HEAD`, or `gh pr view` when values are
-not already in context.
+## Step 1 — Confirm the next-session intent
+
+Before composing anything, ask the operator what they intend to work on in
+the next chat. Do not infer it silently from the conversation, and do not
+ask it raw — use `AskUserQuestion` with two to four options drawn from the
+session context (the threads left open, the obvious next actions, the task
+the operator last steered toward); the tool's free-text fallback covers
+anything unlisted. The selected intent is the directive's forward task:
+Step 2 scopes every field to what that intent needs, and the rendered
+`In-flight` line states it.
+
+## Step 2 — Read and validate the live session
+
+Validate every identifier directly before stating it. Conversation context
+goes stale within a session — a PR merges, HEAD advances, a worktree
+advances to a newer commit — so confirm each value against its live source
+at compose time rather than carrying it from memory. Run the command in
+each field's Source column; for a PR, capture its merge state
+(`gh pr view --json state,mergedAt`) and state `merged` or `open` from that
+result, never from recollection. A value that cannot be confirmed against a
+live source is not dropped silently — surface it to the operator via
+`AskUserQuestion` to clarify (offer the candidate values found plus the
+free-text fallback) and use the answer. Omit it only when the operator
+chooses to skip it.
 
 | Field | What to capture | Source |
 |---|---|---|
 | `branch` | Active branch name | `git branch --show-current` |
-| `pr` | Active PR number, when one exists | `gh pr view --json number` |
+| `pr` | Active PR number and its merge state (open / merged), when one exists | `gh pr view --json number,state,mergedAt` |
 | `head` | Short HEAD SHA (whatever `git rev-parse --short` outputs) | `git rev-parse --short HEAD` |
 | `worktree` | Absolute path to the working directory | `pwd` |
 | `in_flight` | One sentence describing what is being worked on right now | conversation |
@@ -41,7 +62,15 @@ not already in context.
 A field whose value cannot be stated as a concrete identifier is omitted
 from the directive.
 
-## Step 2 — Render the directive
+Scope every field to what the Step 1 intent needs next. Compaction carries
+forward the slice of session history the remaining work needs: capture a
+`decision`, `blocker`, or `in_flight` detail when a next step relies on
+it, and leave a detail the next steps do not touch (a settled question, a
+resolved blocker, a path not taken) out by simply not listing it. When a
+settled decision still constrains the next step, list its outcome as one
+line, not the deliberation behind it.
+
+## Step 3 — Render the directive
 
 Render this exact shape, populating only the fields with concrete values:
 
@@ -56,25 +85,21 @@ Preserve:
 - Blockers: <bullet per blocker>
 - Files: <path>, <path>, <path>
 - Follow-ups: <bullet per follow-up>
-
-Drop:
-- Tool outputs already applied to files
-- Per-tick progress narration
-- Resolved findings and superseded SHAs
-- Listing/grep output whose conclusion appears above
 ```
 
-The `Preserve:` block leads so the summarizer maximizes recall first. The
-`Drop:` block lists the lightest-touch removals — raw tool outputs are the
-safest content to drop because the work they produced lives in the files
-and commits.
+The directive lists only what the next steps consume, so the summarizer
+preserves that with high fidelity and compresses the rest of the trace on
+its own — naming what to keep is a clearer instruction than enumerating
+what to cut. Keep the list tight: a `Preserve:` block padded with finished
+or out-of-scope context dilutes the summarizer's focus on what happens
+next.
 
 Source: [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
 — "start by maximizing recall to ensure your compaction prompt captures
 every relevant piece of information from the trace, then iterate to improve
 precision by eliminating superfluous content."
 
-## Step 3 — Copy `/compact <directive>` to the clipboard
+## Step 4 — Copy `/compact <directive>` to the clipboard
 
 Write the full `/compact <directive>` string to a temporary file via the
 Write tool, then copy the file contents to the clipboard with PowerShell:
@@ -91,7 +116,7 @@ unmodified regardless of which characters it contains.
 A reasonable temp path under `$env:TEMP` (Windows) or `$TMPDIR` (POSIX)
 works; clean it up after the `Set-Clipboard` call returns.
 
-## Step 4 — Hand off
+## Step 5 — Hand off
 
 Print this confirmation line to the operator:
 
@@ -99,8 +124,8 @@ Print this confirmation line to the operator:
 > compact this conversation with focus.
 
 Then list up to the first three `Preserve:` bullets (or fewer when the
-directive omits fields) and the first `Drop:` bullet inline so the
-operator can spot-check before pasting.
+directive omits fields) inline so the operator can spot-check before
+pasting.
 
 ---
 

package/skills/session-log/SKILL.md

@@ -65,6 +65,7 @@ Resolve the metadata used by the frontmatter and the vault path:
 
 - **Project name:** infer from conversation context
 - **Session number:** from backend detection above
+- **Session ID:** the session ID of the agent authoring this log, read from the `CLAUDE_CODE_SESSION_ID` environment variable (PowerShell: `$env:CLAUDE_CODE_SESSION_ID`). This UUID names the authoring agent's own transcript file (`<session-id>.jsonl`), so the saved report points back to the exact session that produced it. When the variable is unset, use the literal `unknown`.
 - **Date:** today's date
 - **Title:** a 2–5 word summary of the session's primary outcome. Examples: "Amazon Auth Migration", "Source Loading Fix", "PR 475 Convergence". Avoid generic titles like "Bug Fixes".
 
@@ -75,6 +76,7 @@ The frontmatter contract every session report carries (inside an HTML comment, a
 type: session-report
 project: [name]
 session: [N]
+session_id: [uuid]
 date: [YYYY-MM-DD]
 status: completed|in-progress|blocked
 blocked: true|false
@@ -83,7 +85,7 @@ tags: [session, [project-tag], [topic-tags]]
 -->
 ```
 
-Every session report carries this metadata block verbatim so vault search and the tidy step in step 5 work. **Initial values for Step 2's Write:** substitute concrete values for every placeholder — for `vault_context_retrieved`, write the literal value `false` (the safe default before Step 3's vault-MCP-tool scan completes). Step 3 then Edits this to `true` if any of the three vault MCP tools fired this session.
+Every session report carries this metadata block verbatim so vault search and the tidy step in step 5 work. **Initial values for Step 2's Write:** substitute concrete values for every placeholder — for `session_id`, write the value read from `CLAUDE_CODE_SESSION_ID` in step 1 (or `unknown` when the variable is unset); for `vault_context_retrieved`, write the literal value `false` (the safe default before Step 3's vault-MCP-tool scan completes). Step 3 then Edits `vault_context_retrieved` to `true` if any of the three vault MCP tools fired this session.
 
 ## Step 2: Compose the HTML via doc-gist's shape principles
 
@@ -191,6 +193,7 @@ The primary outcome comes from the session title resolved in step 1.
 - [ ] HTML composed via doc-gist's shape principles (gallery-anchored)
 - [ ] `<!-- @publish-as-gist -->` marker present somewhere in the HTML
 - [ ] Frontmatter HTML comment present at top of `<body>`
+- [ ] `session_id` frontmatter field set from `CLAUDE_CODE_SESSION_ID` (the authoring agent's own session), or `unknown` when the variable is unset
 - [ ] Opening section answers "what shipped / why / impact" for a cold reader
 - [ ] Self-contained HTML (no relative-path asset refs; avoid external dependencies)
 - [ ] Auto-publish URLs captured from step 2 and step 3 (or HTML emitted to chat when step 2 Write failed)