claude-dev-env 1.70.0 → 1.72.0

package/hooks/git-hooks/pre_push.py

@@ -1,20 +1,30 @@
 #!/usr/bin/env python3
-"""Git pre-push hook: run the CODE_RULES gate over commits about to be pushed.
+"""Git pre-push hook: guard the push destination, then run the CODE_RULES gate.
 
 Installed to the user's shared git-hooks directory via the claude-dev-env
 installer; git invokes this file as `pre-push` (the installer strips the
 `_` and `.py` suffix when copying into the live hooks path).
 
 Protocol: git pre-push provides remote name and URL as argv, then writes
-`<local-ref> <local-sha> <remote-ref> <remote-sha>` lines on stdin. The
-first non-zero remote-sha is used as the gate `--base`, so violations are
-scoped to commits that are not already on the remote. When every remote
-object name is zero (new branch) or stdin is empty, the gate falls back
-to the remote's default branch symbolic ref.
+`<local-ref> <local-sha> <remote-ref> <remote-sha>` lines on stdin.
+
+Destination guard: any line that pushes a local branch onto a protected
+remote branch (`main` or `master`) whose name differs from the local
+branch is blocked before the gate runs. This catches a branch that tracks
+`origin/main` under `push.default=upstream`, where a bare `git push`
+resolves to `main`. The guard runs whether or not the CODE_RULES gate is
+installed; deletions and same-name pushes pass.
+
+Gate base: the first non-zero remote-sha is used as the gate `--base`, so
+violations are scoped to commits that are not already on the remote. When
+every remote object name is zero (new branch) or stdin is empty, the gate
+falls back to the remote's default branch symbolic ref.
 
 Exit codes:
-  0 - commits to be pushed pass the gate (or the gate is not installed).
-  1 - one or more commits introduce blocking violations.
+  0 - the push destination is allowed and its commits pass the gate (or
+      the gate is not installed).
+  1 - the push would land a non-protected local branch onto a protected
+      remote branch, or a commit introduces a blocking violation.
   2 - unexpected invocation failure (e.g., subprocess could not launch).
 """
 
@@ -25,16 +35,22 @@ import sys
 from pathlib import Path
 
 from git_hooks_constants import (
+    ALL_PROTECTED_BRANCH_PUSH_NAMES,
     ALL_ZEROS_OBJECT_NAME_CHARACTER,
     BASE_REFERENCE_ARGUMENT,
     DEFAULT_REMOTE_BASE_REFERENCE,
     GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE,
     INVOKE_GATE_FAILURE_MESSAGE,
+    LOCAL_BRANCH_REFERENCE_PREFIX,
+    LOCAL_REFERENCE_FIELD_INDEX,
     LOCAL_SHA_FIELD_INDEX,
     MALFORMED_STDIN_LINE_MESSAGE,
     NO_PARSEABLE_STDIN_LINES_MESSAGE,
     NO_PARSEABLE_STDIN_LINES_SENTINEL,
     PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE,
+    PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE,
+    PROTECTED_BRANCH_PUSH_BLOCK_MESSAGE,
+    REMOTE_REFERENCE_FIELD_INDEX,
     STDIN_LINE_FIELD_COUNT,
     STDIN_READ_FAILURE_MESSAGE,
     STDIN_REMOTE_OBJECT_FIELD_INDEX,
@@ -88,6 +104,36 @@ def resolve_base_reference_from_stdin(stdin_text: str) -> str | None:
     return default_remote_base_reference
 
 
+def find_protected_branch_push_violation(stdin_text: str) -> tuple[str, str] | None:
+    stdin_line_field_count = STDIN_LINE_FIELD_COUNT
+    local_reference_field_index = LOCAL_REFERENCE_FIELD_INDEX
+    local_sha_field_index = LOCAL_SHA_FIELD_INDEX
+    remote_reference_field_index = REMOTE_REFERENCE_FIELD_INDEX
+    local_branch_reference_prefix = LOCAL_BRANCH_REFERENCE_PREFIX
+    protected_branch_push_names = ALL_PROTECTED_BRANCH_PUSH_NAMES
+    for each_line in stdin_text.splitlines():
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        fields = stripped_line.split()
+        if len(fields) < stdin_line_field_count:
+            continue
+        if is_all_zeros_object_name(fields[local_sha_field_index]):
+            continue
+        local_branch_name = fields[local_reference_field_index].removeprefix(
+            local_branch_reference_prefix
+        )
+        remote_branch_name = fields[remote_reference_field_index].removeprefix(
+            local_branch_reference_prefix
+        )
+        if (
+            remote_branch_name in protected_branch_push_names
+            and local_branch_name != remote_branch_name
+        ):
+            return (local_branch_name, remote_branch_name)
+    return None
+
+
 def invoke_gate(gate_script_path: Path, base_reference: str) -> int:
     base_reference_argument = BASE_REFERENCE_ARGUMENT
     invoke_gate_failure_message = INVOKE_GATE_FAILURE_MESSAGE
@@ -118,13 +164,8 @@ def main() -> int:
     pre_push_gate_script_not_found_message = PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE
     no_parseable_stdin_lines_message = NO_PARSEABLE_STDIN_LINES_MESSAGE
     no_parseable_stdin_lines_sentinel = NO_PARSEABLE_STDIN_LINES_SENTINEL
-    gate_script_path, exact_allowed_path = resolve_gate_script_path()
-    if not is_safe_regular_file(gate_script_path, exact_allowed_path):
-        print(
-            pre_push_gate_script_not_found_message.format(path=gate_script_path),
-            file=sys.stderr,
-        )
-        return 0
+    protected_branch_push_block_message = PROTECTED_BRANCH_PUSH_BLOCK_MESSAGE
+    protected_branch_push_block_exit_code = PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE
     try:
         stdin_text = sys.stdin.read()
     except OSError as read_error:
@@ -133,6 +174,24 @@ def main() -> int:
             file=sys.stderr,
         )
         return gate_infrastructure_failure_exit_code
+    protected_branch_push_violation = find_protected_branch_push_violation(stdin_text)
+    if protected_branch_push_violation is not None:
+        local_branch_name, remote_branch_name = protected_branch_push_violation
+        print(
+            protected_branch_push_block_message.format(
+                local_branch=local_branch_name,
+                remote_branch=remote_branch_name,
+            ),
+            file=sys.stderr,
+        )
+        return protected_branch_push_block_exit_code
+    gate_script_path, exact_allowed_path = resolve_gate_script_path()
+    if not is_safe_regular_file(gate_script_path, exact_allowed_path):
+        print(
+            pre_push_gate_script_not_found_message.format(path=gate_script_path),
+            file=sys.stderr,
+        )
+        return 0
     base_reference = resolve_base_reference_from_stdin(stdin_text)
     if base_reference is None:
         return 0

package/hooks/git-hooks/test_pre_push.py

@@ -321,3 +321,121 @@ def test_invoke_gate_uses_resolved_path(
     assert exit_code == 0
     executed_path = recorded_path_file.read_text(encoding="utf-8")
     assert executed_path == str(resolved_path)
+
+
+def test_find_protected_branch_push_violation_flags_feature_branch_to_main() -> None:
+    stdin_text = (
+        f"refs/heads/feat/example {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation == ("feat/example", "main")
+
+
+def test_find_protected_branch_push_violation_flags_feature_branch_to_master() -> None:
+    stdin_text = (
+        f"refs/heads/topic {NON_ZERO_LOCAL_SHA} refs/heads/master {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation == ("topic", "master")
+
+
+def test_find_protected_branch_push_violation_allows_main_onto_main() -> None:
+    stdin_text = (
+        f"refs/heads/main {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation is None
+
+
+def test_find_protected_branch_push_violation_allows_feature_onto_own_ref() -> None:
+    stdin_text = (
+        f"refs/heads/feat/example {NON_ZERO_LOCAL_SHA} refs/heads/feat/example {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation is None
+
+
+def test_find_protected_branch_push_violation_ignores_deletion_of_main() -> None:
+    stdin_text = (
+        f"(delete) {ALL_ZEROS_OBJECT_NAME} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation is None
+
+
+def test_main_blocks_feature_branch_push_onto_main(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    passing_gate_path = tmp_path / "gate.py"
+    passing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(passing_gate_path))
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(
+            f"refs/heads/feat/example {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+        ),
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == git_hooks_constants.PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE
+    captured = capsys.readouterr()
+    assert "feat/example" in captured.err
+    assert "main" in captured.err
+
+
+def test_main_blocks_protected_push_even_when_gate_script_missing(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setenv(
+        "CODE_RULES_GATE_PATH",
+        str(tmp_path / "does_not_exist.py"),
+    )
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(
+            f"refs/heads/feat/example {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+        ),
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == git_hooks_constants.PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE
+    captured = capsys.readouterr()
+    assert "feat/example" in captured.err
+
+
+def test_main_allows_main_onto_main_push(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    passing_gate_path = tmp_path / "gate.py"
+    passing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(passing_gate_path))
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(
+            f"refs/heads/main {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+        ),
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0

package/hooks/hooks_constants/blocking_check_limits.py

@@ -29,6 +29,20 @@ MAX_E2E_TEST_NAMING_ISSUES: int = 3
 DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT: int = 3
 MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES: int = 3
 DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT: int = 2
+MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES: int = 3
+MAX_STALE_TEST_NAME_TARGET_ISSUES: int = 3
+STALE_TEST_NAME_MINIMUM_SHARED_TOKEN_COUNT: int = 2
+
+ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES: tuple[str, ...] = (
+    "no consumer reads",
+    "no consumer yet",
+    "no submission-run consumer reads",
+    "producer-only artifact",
+    "no reader consumes",
+    "nothing reads it yet",
+    "no one reads it yet",
+    "not yet read by any consumer",
+)
 
 ALL_DOCSTRING_EXCLUSIVE_SCOPE_PHRASES: tuple[str, ...] = (
     "only when",

package/hooks/hooks_constants/claude_md_orphan_file_blocker_constants.py

@@ -8,8 +8,8 @@ subdirectories, and its siblings), the table points a reader at a file that is
 not there. This module holds the patterns that find those cells, the filename
 extensions that mark a cell as a file reference, the region-boundary marker that
 scopes a prose region to one section, the relative-path marker that exempts a
-cross-directory table block, the subtree scan budget, and the block-message text
-the hook emits.
+cross-directory table block, the directory names the subtree walk prunes, the
+subtree scan budget, and the block-message text the hook emits.
 """
 
 import re
@@ -23,6 +23,7 @@ __all__ = [
     "REGION_BOUNDARY_PATTERN",
     "RELATIVE_PATH_SOURCE_PATTERN",
     "ALL_REFERENCED_FILE_EXTENSIONS",
+    "ALL_NOISE_DIRECTORY_NAMES",
     "MAX_SUBTREE_FILES_SCANNED",
     "MAX_ORPHAN_FILE_ISSUES",
     "ORPHAN_FILE_MESSAGE_TEMPLATE",
@@ -65,6 +66,16 @@ ALL_REFERENCED_FILE_EXTENSIONS: frozenset[str] = frozenset(
     }
 )
 
+ALL_NOISE_DIRECTORY_NAMES: frozenset[str] = frozenset(
+    {
+        ".git",
+        "__pycache__",
+        "node_modules",
+        ".pytest_cache",
+        ".ruff_cache",
+    }
+)
+
 MAX_SUBTREE_FILES_SCANNED: int = 5000
 
 MAX_ORPHAN_FILE_ISSUES: int = 20

package/hooks/hooks_constants/precommit_code_rules_gate_constants.py

@@ -8,7 +8,7 @@ from pathlib import Path
 
 GIT_DASH_C_COMMIT_PATTERN: str = r"git\s+-C\s+[\"']?[^\"';&|]+?[\"']?\s+commit\b"
 GIT_COMMAND_TIMEOUT_SECONDS: int = 5
-GATE_TIMEOUT_SECONDS: int = 120
+GATE_TIMEOUT_SECONDS: int = 240
 GATE_RELATIVE_PATH: Path = Path("_shared") / "pr-loop" / "scripts" / "code_rules_gate.py"
 ALL_STAGED_PYTHON_FILES_COMMAND: tuple[str, ...] = (
     "git",

package/package.json

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

package/rules/docstring-prose-matches-implementation.md

@@ -1,12 +1,12 @@
 # Docstring Prose Matches Implementation
 
-**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps.
+**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps. It applies equally to a skill's companion `SKILL.md` (or any sibling `.md`) that describes a producer the skill's `scripts/` carry out: a doc sentence that claims a produced artifact's ordering or content is the prose this rule governs, and it tracks the producer function's own docstring and body.
 
 ## Rule
 
 When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
 
-The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Two more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and module-level responsibility paragraphs — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the three gated slices.
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Three more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and module-level responsibility paragraphs — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the four gated slices.
 
 ## What to check before you write the docstring
 
@@ -17,6 +17,7 @@ Read the body and the docstring side by side:
 - **Shared fallback routes.** A summary that scopes a fallback call to one condition names every condition that reaches that call. When the body routes to the same fallback from two or more early-return guards (`if a is None: fallback(); return` and `if random() < p: fallback(); return`), the prose enumerates both guards. The `check_docstring_fallback_branch_coverage` gate blocks the single-condition form of this drift at Write/Edit time.
 - **Step order.** A docstring that says `A then B then C` matches the call order in the body.
 - **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
+- **Companion-doc ordering and content claims.** A `SKILL.md` (or sibling `.md`) sentence that names a produced artifact and claims its order (`sorted`, `alphabetical`, `in sorted order`) or its content (`the at-risk names`, `just the current set`) matches the producer function's docstring and body for that same artifact. A producer that builds the artifact by merging stored names with new names and appending — preserving file order, not re-sorting the union — leaves a doc that still says `sorted` drifted on both counts: the order claim is wrong, and the content claim hides the merged-in prior entries. When the producer's ordering or union changes, the same change updates the companion doc. The two move together in one commit, even when the producer edit does not touch the `.md` file.
 
 When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
 
@@ -39,6 +40,8 @@ A docstring that enumerates "attribute read, augmented-assignment target, class-
 
 This drift class is sub-bucket **O6** in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` (free-form `Note:` / `Returns:` / responsibility-list claims). The audit teammate lists every prose enumeration in a changed docstring and verifies each item against the body, and lists every union member / suppressor / step in the body and verifies each appears in the prose. A union member or suppressor in the body that the prose omits is an O6 finding. The single-condition shared-fallback shape of this drift is gated deterministically by `check_docstring_fallback_branch_coverage` (`packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py`); the audit lane covers every O6 shape the gate cannot match.
 
+When a changed PR touches a producer function whose ordering or union shifts, the O8 audit lane also reads that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact. A doc sentence that claims the artifact is `sorted` or holds `just the at-risk names` while the producer merges prior names and appends without re-sorting is an O8 finding, even when the PR diff never touched the `.md` file — the behavior change orphaned the doc claim.
+
 ## Why
 
 A docstring enumeration earns its place by being trustworthy. A complete list lets a reader reason about the function without scanning the body; a list missing one item is worse than no list, because it asserts completeness it does not have. Naming this standard makes the gap a first-class finding at write time and at audit, rather than a surprise a reader hits months later.

package/scripts/CLAUDE.md

@@ -18,6 +18,7 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 | `Migrate-ShellPolicy.ps1` | Applies automated fixes for common shell-policy violations found by the audit script |
 | `Install-SweepEmptyDirs.ps1` | Registers `sweep_empty_dirs.py` as a scheduled task on Windows |
 | `check.ps1` | Runs the full code-quality check suite |
+| `Show-Asset.ps1` | Opens files on screen, sizing each image window to the image's pixel dimensions (scaled to fit the screen); non-image files open in their default application |
 
 ## Subdirectories
 

package/scripts/Show-Asset.ps1

@@ -0,0 +1,106 @@
+<#
+.SYNOPSIS
+Opens files on screen, sizing each image window to the image's own dimensions.
+
+.DESCRIPTION
+For every path given, an image opens in a window whose client area matches the
+image's pixel size, scaled down to fit the primary screen's working area when the
+image is larger than the screen. A small image gets a usable minimum window with
+the picture centered at native size. Non-image files open in their registered
+default application, and any file that cannot be loaded as an image falls back to
+that default application too. Escape or the close button dismisses a window; the
+process exits once every window is closed.
+
+.PARAMETER Paths
+One or more file paths to open.
+#>
+param(
+    [Parameter(ValueFromRemainingArguments = $true)]
+    [string[]]$Paths
+)
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+try {
+    [System.Windows.Forms.Application]::SetHighDpiMode([System.Windows.Forms.HighDpiMode]::PerMonitorV2) | Out-Null
+}
+catch {
+    $null = $_
+}
+[System.Windows.Forms.Application]::EnableVisualStyles()
+
+$imageExtensions = @('.png', '.jpg', '.jpeg', '.gif', '.bmp', '.webp', '.tif', '.tiff', '.ico')
+$screenMargin = 80
+$minimumClientWidth = 220
+$minimumClientHeight = 160
+$openWindowCount = 0
+
+foreach ($path in $Paths) {
+    if (-not (Test-Path -LiteralPath $path)) { continue }
+    $fullPath = (Resolve-Path -LiteralPath $path).Path
+    $extension = [System.IO.Path]::GetExtension($fullPath).ToLowerInvariant()
+
+    if ($imageExtensions -notcontains $extension) {
+        Invoke-Item -LiteralPath $fullPath
+        continue
+    }
+
+    try {
+        $imageBytes = [System.IO.File]::ReadAllBytes($fullPath)
+        $imageStream = New-Object System.IO.MemoryStream(, $imageBytes)
+        $loadedImage = [System.Drawing.Image]::FromStream($imageStream)
+        $image = New-Object System.Drawing.Bitmap($loadedImage)
+        $loadedImage.Dispose()
+        $imageStream.Dispose()
+    }
+    catch {
+        Invoke-Item -LiteralPath $fullPath
+        continue
+    }
+
+    $workingArea = [System.Windows.Forms.Screen]::PrimaryScreen.WorkingArea
+    $maximumWidth = $workingArea.Width - $screenMargin
+    $maximumHeight = $workingArea.Height - $screenMargin
+    $scale = [Math]::Min(1.0, [Math]::Min($maximumWidth / $image.Width, $maximumHeight / $image.Height))
+
+    $pictureBox = New-Object System.Windows.Forms.PictureBox
+    $pictureBox.Dock = [System.Windows.Forms.DockStyle]::Fill
+    $pictureBox.Image = $image
+
+    if ($scale -lt 1.0) {
+        $pictureBox.SizeMode = [System.Windows.Forms.PictureBoxSizeMode]::Zoom
+        $clientWidth = [int][Math]::Round($image.Width * $scale)
+        $clientHeight = [int][Math]::Round($image.Height * $scale)
+    }
+    else {
+        $pictureBox.SizeMode = [System.Windows.Forms.PictureBoxSizeMode]::CenterImage
+        $clientWidth = [Math]::Max($minimumClientWidth, $image.Width)
+        $clientHeight = [Math]::Max($minimumClientHeight, $image.Height)
+    }
+
+    $form = New-Object System.Windows.Forms.Form
+    $form.Text = [System.IO.Path]::GetFileName($fullPath)
+    $form.AutoScaleMode = [System.Windows.Forms.AutoScaleMode]::None
+    $form.StartPosition = [System.Windows.Forms.FormStartPosition]::CenterScreen
+    $form.ClientSize = New-Object System.Drawing.Size($clientWidth, $clientHeight)
+    $form.KeyPreview = $true
+    $form.BackColor = [System.Drawing.Color]::FromArgb(24, 24, 24)
+    $form.Controls.Add($pictureBox)
+
+    $form.Add_KeyDown({
+            param($sender, $eventArguments)
+            if ($eventArguments.KeyCode -eq [System.Windows.Forms.Keys]::Escape) { $sender.Close() }
+        })
+    $form.Add_FormClosed({
+            $script:openWindowCount--
+            if ($script:openWindowCount -le 0) { [System.Windows.Forms.Application]::Exit() }
+        })
+
+    $openWindowCount++
+    $form.Show()
+}
+
+if ($openWindowCount -gt 0) {
+    [System.Windows.Forms.Application]::Run()
+}

package/skills/autoconverge/SKILL.md

@@ -101,7 +101,7 @@ own. The workflow runs in the background and notifies this session on
 completion. Watch live progress with `/workflows`.
 
 The workflow returns
-`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote }`.
+`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, reuseNote }`.
 
 ## Budget-aware round boundaries
 
@@ -207,8 +207,31 @@ round records nothing resumable and replays dirty.
    Blocker: <blocker>        # only when blocked
    Standards: <standardsNote> # only when a round deferred code-standard findings
    Copilot: <copilotNote>     # only when Copilot was down or out of quota
+   Reuse: <reuseNote>         # only when the reuse pass identified an improvement
    ```
 
+## Reuse pass (before convergence)
+
+Before the first round, one reuse lens (`code-quality-agent`) scans the full
+`origin/main...HEAD` diff for places the PR re-implements behavior the codebase
+already provides. It reports a reuse improvement only when all three criteria
+hold, and drops any case where even one is in doubt:
+
+- **Certain** — an existing symbol or module unquestionably covers the new
+  code's behavior, cited at `file:line`.
+- **Behaviorally identical** — swapping the new code for the existing one
+  changes no observable behavior: same inputs, outputs, side effects, and error
+  handling.
+- **Autonomously implementable** — the replacement is a mechanical edit (import
+  and call the existing symbol, delete the duplicate) needing no product
+  decision and no human judgment.
+
+The reuse lens reports without editing. Qualifying improvements then run through
+the same edit → verify → commit fix flow the rounds use, so they land in one
+verified commit before convergence starts. The pass is best-effort: when no case
+clears all three criteria, the run proceeds straight to convergence, and
+`reuseNote` records what landed.
+
 ## What the workflow does each round
 
 See [`reference/convergence.md`](reference/convergence.md) for the full round
@@ -227,8 +250,12 @@ suite (`python -m pytest`) and keep scratch work in ephemeral temp dirs.
 - **Converge:** `parallel([Bugbot lens, code-review lens, bug-audit lens])` on
   the current HEAD, full `origin/main...HEAD` diff. Dedup findings; one
   `clean-coder` applies all fixes in a single commit, pushes, replies to and
-  resolves any bot threads; re-verify next round on the new HEAD. When all
-  three are clean on a stable HEAD, post the CLEAN bugteam audit artifact.
+  resolves any bot threads; re-verify next round on the new HEAD. Every edit
+  step ends with a pre-commit gate check: before its turn ends, the fixer
+  dry-runs the CODE_RULES commit gate (`code_rules_gate.py --staged`) and keeps
+  fixing until that gate would accept the commit — it makes no commit itself.
+  When all three are clean on a stable HEAD, post the CLEAN bugteam audit
+  artifact.
   A round whose findings are ALL code-standard violations (pure CODE_RULES/style,
   no behavioral impact) passes for convergence purposes: the workflow files a
   follow-up issue listing the findings, opens a draft environment-hardening PR

package/skills/autoconverge/reference/convergence.md

@@ -1,5 +1,42 @@
 # Convergence — round shape and the ready definition
 
+## Pre-flight: clear merge conflicts
+
+Before the first round, the workflow checks once whether the PR branch conflicts
+with `origin/main`. When GitHub reports a conflict (`mergeable` false or
+`mergeable_state` dirty), one `clean-coder` rebases the branch onto `origin/main`
+and resolves every conflict — gated the same way as every other code change: the
+edit leaves the rebase in the working tree, a `code-verifier` binds a verdict to
+it, and the commit step force-pushes with lease. The bug checks then run on a
+conflict-free diff.
+
+A PR that merges cleanly skips the rebase. A conflict that surfaces mid-run, when
+`origin/main` advances during a later round, is caught by the convergence repair
+at the end of the loop, which also rebases.
+
+## Reuse pass (runs after the conflict pre-flight, before convergence)
+
+One reuse lens (`code-quality-agent`) reviews the full `origin/main...HEAD` diff
+for code that re-implements behavior the repository already provides. It reports a
+reuse improvement only when all three criteria hold together, and omits any case
+where even one is in doubt:
+
+1. **Certain** — an existing symbol or module unquestionably covers the new
+   code's behavior, cited at `file:line`.
+2. **Behaviorally the same** — swapping the new code for the existing one
+   changes no observable behavior: same inputs, outputs, side effects, and
+   error handling.
+3. **Autonomously implementable** — the replacement is a mechanical edit (import
+   and call the existing symbol, drop the duplicate) needing no product
+   decision and no human judgment.
+
+The lens reports without editing. Each qualifying improvement runs through the
+same edit → verify → commit fix flow the rounds use, landing in one verified
+commit before convergence begins. The pass is best-effort: when no case clears
+all three criteria the run proceeds straight to convergence. Whatever the reuse
+pass surfaces also joins the round findings, so the code-review lens re-checks
+any improvement that did not land.
+
 ## The round loop
 
 The workflow holds three states and moves between them until the PR is ready or
@@ -26,7 +63,10 @@ tracks CONVERGE passes only and is never the cap.
    colliding threads.
 4. **Any findings** → one `clean-coder` applies every fix in a single test-first
    commit, pushes, then replies to and resolves each finding that carries a
-   GitHub review thread. A round progresses when the fix lens lands a push that
+   GitHub review thread. Before its turn ends, the edit step dry-runs the
+   CODE_RULES commit gate (`code_rules_gate.py --staged`) over its staged
+   changes and keeps fixing until that gate would accept the commit, so the
+   later commit step never hits a gate rejection. A round progresses when the fix lens lands a push that
    moves HEAD, or when every finding was already addressed so no code change is
    needed yet each finding thread is still resolved (the fix lens reports
    `resolvedWithoutCommit` and the run re-converges on the unchanged HEAD). A