claude-dev-env 1.64.3 → 1.65.1

package/hooks/blocking/code_rules_dead_module_constant.py

@@ -6,8 +6,10 @@ project, so a constant defined there is never proven dead by a single-file scan
 alone. This check resolves the enclosing package tree — the scan root — and
 flags an UPPER_SNAKE constant defined in the written module whose name appears
 in no ``.py`` module anywhere under that root: not as an imported name, not as a
-read, not as a re-export. That is the ``MEDIUM_TEXT``-style dead constant the
-CODE_RULES §9.8 dead-code rule targets, caught at Write/Edit time before the
+read, not as a re-export. When a constant looks dead in the package tree, the
+scan widens to the whole repository so a consumer in a sibling tree counts
+before the constant is flagged. That is the ``MEDIUM_TEXT``-style dead constant
+the CODE_RULES §9.8 dead-code rule targets, caught at Write/Edit time before the
 unused constant lands.
 
 The scan is deliberately conservative to keep false positives near zero:
@@ -18,11 +20,19 @@ The scan is deliberately conservative to keep false positives near zero:
   surface explicitly, so a name listed there is live by declaration and a name
   absent there is the author's stated intent, neither of which this check second
   guesses.
-- A constant is live when its name appears anywhere under the scan root —
+- A constant is live when its name appears anywhere the scan reaches —
   imported, read, listed in ``__all__``, or referenced in a string annotation —
   in any ``.py`` module, including the constants module itself.
-- Test modules under the scan root still count as references, so a constant used
-  only by a test stays live.
+- When the package-tree scan leaves a constant unreferenced, the scan widens to
+  the repository root (the nearest ``.git`` ancestor) so a consumer in a sibling
+  tree of the same repository counts; a module outside any repository is judged
+  on the package-tree scan alone. The widened pass skips the package subtree the
+  first pass already covered, so no file is read twice.
+- The combined file count of the package-tree and widened passes is bounded by a
+  cap, so a write under an unexpectedly large tree cannot stall the hook; a write
+  whose scan hits the cap is treated as "cannot prove dead" and flags nothing.
+- Test modules under the scanned tree still count as references, so a constant
+  used only by a test stays live.
 """
 
 import ast
@@ -48,6 +58,7 @@ from hooks_constants.dead_module_constant_constants import (  # noqa: E402
     DEAD_MODULE_CONSTANT_GUIDANCE,
     DUNDER_ALL_NAME,
     DUNDER_INIT_FILENAME,
+    GIT_DIRECTORY_NAME,
     MAX_DEAD_MODULE_CONSTANT_ISSUES,
     MAX_SCAN_ROOT_FILE_COUNT,
     MINIMUM_UPPER_SNAKE_LENGTH,
@@ -197,46 +208,100 @@ def _scan_root_for_constants_module(file_path: str) -> Path:
     return enclosing_directory
 
 
+def _is_under_directory(candidate_path: Path, ancestor_directory: Path) -> bool:
+    """Return whether a resolved path lies inside a resolved ancestor directory.
+
+    Args:
+        candidate_path: The resolved file path to test.
+        ancestor_directory: The resolved directory that may contain the path.
+
+    Returns:
+        True when ``candidate_path`` is the ancestor directory itself or a
+        descendant of it, False otherwise.
+    """
+    try:
+        candidate_path.relative_to(ancestor_directory)
+    except ValueError:
+        return False
+    return True
+
+
 def _all_referenced_names_under_root(
     scan_root: Path,
     written_path: Path,
     written_content: str,
-) -> tuple[set[str], bool]:
-    """Return referenced names under the scan root and whether the file cap was hit.
+    already_scanned_count: int = 0,
+    excluded_subtree: Path | None = None,
+) -> tuple[set[str], int, bool]:
+    """Return referenced names under the scan root, the running count, and a cap flag.
 
     The written module's on-disk text is replaced by ``written_content`` so the
-    post-edit view is judged, never the stale disk copy. Sibling modules are
-    read from disk. Reading stops after the configured file cap so a write under
-    an unexpectedly large tree cannot stall the hook; the boolean signals the
-    caller to treat that case as "cannot prove dead".
+    post-edit view is judged, never the stale disk copy. Sibling modules are read
+    from disk. Reading stops once the running file count exceeds the configured
+    cap so a write under an unexpectedly large tree cannot stall the hook; the
+    boolean signals the caller to treat that case as "cannot prove dead". When
+    ``excluded_subtree`` is supplied, every ``.py`` module under that directory is
+    skipped, so the widened repository scan never re-reads a file the
+    package-tree scan already covered.
 
     Args:
         scan_root: The directory tree to scan.
         written_path: The resolved path of the module being written.
         written_content: The post-edit text of the written module.
+        already_scanned_count: The file count accumulated by a prior pass, so the
+            cap bounds the combined work of the package-tree and widened passes.
+        excluded_subtree: A resolved directory whose ``.py`` modules are skipped,
+            or None to scan every file under the root.
 
     Returns:
-        A (referenced_names, cap_was_hit) pair. The name set is the union across
-        every scanned module; cap_was_hit is True when the scan stopped at the
-        configured file cap before scanning the whole tree.
+        A (referenced_names, running_count, cap_was_hit) triple. The name set is
+        the union across every scanned module, unioned with the names the written
+        module itself references; running_count is the cumulative file count
+        including ``already_scanned_count``; cap_was_hit is True when the scan
+        stopped at the configured file cap before scanning the whole tree.
     """
     all_referenced_names = _referenced_names_in_source(written_content, load_only=True)
     written_path_key = os.path.normcase(str(written_path))
-    scanned_file_count = 1
+    scanned_file_count = already_scanned_count
     for each_path in scan_root.rglob("*" + PYTHON_SOURCE_SUFFIX):
         if not each_path.is_file():
             continue
-        if os.path.normcase(str(each_path.resolve())) == written_path_key:
+        resolved_path = each_path.resolve()
+        if os.path.normcase(str(resolved_path)) == written_path_key:
+            continue
+        if excluded_subtree is not None and _is_under_directory(resolved_path, excluded_subtree):
             continue
         scanned_file_count += 1
         if scanned_file_count > MAX_SCAN_ROOT_FILE_COUNT:
-            return all_referenced_names, True
+            return all_referenced_names, scanned_file_count, True
         try:
             sibling_source = each_path.read_text(encoding="utf-8")
         except (OSError, UnicodeDecodeError):
             continue
         all_referenced_names |= _referenced_names_in_source(sibling_source)
-    return all_referenced_names, False
+    return all_referenced_names, scanned_file_count, False
+
+
+def _repository_root_for(written_path: Path) -> Path | None:
+    """Return the nearest ancestor directory that holds a ``.git`` entry.
+
+    Walks upward from the written module toward the filesystem root. A normal
+    checkout carries a ``.git`` directory and a git worktree carries a ``.git``
+    file; both satisfy ``exists()``. The repository root bounds the widened
+    cross-tree reference scan.
+
+    Args:
+        written_path: The resolved path of the constants module being written.
+
+    Returns:
+        The repository root directory, or ``None`` when no ancestor carries a
+        ``.git`` entry, so a module outside any repository triggers no widened
+        scan.
+    """
+    for each_ancestor in written_path.parents:
+        if (each_ancestor / GIT_DIRECTORY_NAME).exists():
+            return each_ancestor
+    return None
 
 
 def _module_is_exempt_from_constant_check(file_path: str) -> bool:
@@ -269,10 +334,14 @@ def check_dead_module_constants(
     Runs only on a dedicated constants module (``*_constants.py`` or a module
     under ``config/``); every other production module's file-global constants
     are governed by the use-count rule instead. A constant is dead when its name
-    appears in no ``.py`` module anywhere under the enclosing package tree — not
-    imported, not read, not listed in an ``__all__`` literal, not named in a
-    string annotation. A module declaring its own ``__all__`` is skipped so the
-    author's explicit export surface is never second-guessed. Whole-file
+    appears in no ``.py`` module under the enclosing package tree, nor anywhere
+    in the repository the scan widens to when the package-tree scan leaves the
+    constant unreferenced — not imported, not read, not listed in an ``__all__``
+    literal, not named in a string annotation. A module declaring its own
+    ``__all__`` is skipped so the author's explicit export surface is never
+    second-guessed. A scan whose combined package-tree and widened file count
+    exceeds the configured cap returns ``[]`` (cannot prove dead), bounding the
+    work so the blocking hook cannot stall under a large tree. Whole-file
     analysis runs against ``full_file_content`` when supplied so an Edit fragment
     is judged against the reconstructed post-edit file.
 
@@ -285,7 +354,9 @@ def check_dead_module_constants(
 
     Returns:
         One violation message per dead module-level constant, capped at the
-        configured maximum.
+        configured maximum. Returns an empty list when the file is exempt, no
+        constant is defined, the module declares ``__all__``, the scan exceeds the
+        file cap, or a SyntaxError prevents parsing.
     """
     if _module_is_exempt_from_constant_check(file_path):
         return []
@@ -301,13 +372,29 @@ def check_dead_module_constants(
         return []
     scan_root = _scan_root_for_constants_module(file_path)
     written_path = Path(file_path).resolve()
-    all_referenced_names, cap_was_hit = _all_referenced_names_under_root(
+    all_referenced_names, scanned_file_count, cap_was_hit = _all_referenced_names_under_root(
         scan_root,
         written_path,
         effective_content,
     )
     if cap_was_hit:
         return []
+    has_unreferenced_constant = any(
+        each_name not in all_referenced_names for each_name, _ in constant_definitions
+    )
+    if has_unreferenced_constant:
+        repository_root = _repository_root_for(written_path)
+        if repository_root is not None and repository_root != scan_root:
+            widened_names, _widened_count, widened_cap_was_hit = _all_referenced_names_under_root(
+                repository_root,
+                written_path,
+                effective_content,
+                already_scanned_count=scanned_file_count,
+                excluded_subtree=scan_root,
+            )
+            if widened_cap_was_hit:
+                return []
+            all_referenced_names |= widened_names
     issues: list[str] = []
     for each_name, each_line in constant_definitions:
         if each_name in all_referenced_names:

package/hooks/blocking/test_code_rules_enforcer_dead_module_constant.py

@@ -39,8 +39,13 @@ def neutral_root() -> Iterator[Path]:
     own ``tmp_path`` directory name embeds the test name, which would make every
     synthetic constants path look like a test file. A neutral ``mkdtemp`` root
     mirrors how a production constants module path looks.
+
+    A ``.git`` marker is planted at the root so the cross-tree widening resolves
+    the repository root to this synthetic tree, never an enclosing real
+    checkout, keeping every test bounded and deterministic.
     """
     neutral_directory = Path(tempfile.mkdtemp(prefix="deadconst-")).resolve()
+    (neutral_directory / ".git").mkdir()
     try:
         yield neutral_directory
     finally:
@@ -186,3 +191,86 @@ def test_is_skipped_on_a_constants_test_file(neutral_root: Path) -> None:
     test_constants_path.write_text(body, encoding="utf-8")
     issues = _check(body, str(test_constants_path))
     assert issues == [], f"Test files are exempt, got: {issues}"
+
+
+def _build_cross_tree_repository(
+    repository_root: Path,
+    constants_body: str,
+    sibling_consumer_body: str,
+) -> Path:
+    config_directory = repository_root / "shared" / "theme_db" / "config"
+    config_directory.mkdir(parents=True)
+    constants_path = config_directory / "constants.py"
+    constants_path.write_text(constants_body, encoding="utf-8")
+    sibling_directory = repository_root / "cdp"
+    sibling_directory.mkdir(parents=True)
+    (sibling_directory / "tally.py").write_text(sibling_consumer_body, encoding="utf-8")
+    return constants_path
+
+
+def test_does_not_flag_constant_used_only_in_a_sibling_tree(neutral_root: Path) -> None:
+    constants_body = 'CROSS_TREE_CONSTANT = "cross"\nLOCALLY_DEAD_CONSTANT = "dead"\n'
+    sibling_consumer_body = (
+        "from shared.theme_db.config.constants import CROSS_TREE_CONSTANT\n"
+        "\n"
+        "def tally() -> str:\n"
+        "    return CROSS_TREE_CONSTANT\n"
+    )
+    constants_path = _build_cross_tree_repository(
+        neutral_root, constants_body, sibling_consumer_body
+    )
+    issues = _check(constants_body, str(constants_path))
+    assert not any("CROSS_TREE_CONSTANT" in each_issue for each_issue in issues), (
+        f"A constant consumed by a sibling tree in the repository must not be flagged, got: {issues}"
+    )
+    assert any("LOCALLY_DEAD_CONSTANT" in each_issue for each_issue in issues), (
+        f"A constant referenced nowhere in the repository stays flagged, got: {issues}"
+    )
+
+
+def test_returns_empty_list_at_file_cap(
+    neutral_root: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr("code_rules_dead_module_constant.MAX_SCAN_ROOT_FILE_COUNT", 0)
+    constants_path = _build_constants_package(
+        neutral_root / "workflow",
+        CONSTANTS_BODY,
+        "def noop() -> None:\n    pass\n",
+    )
+    issues = _check(CONSTANTS_BODY, str(constants_path))
+    assert issues == [], f"File cap hit must return [] (cannot prove dead), got: {issues}"
+
+
+def test_widened_scan_reads_each_file_at_most_once(
+    neutral_root: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    constants_body = 'CROSS_TREE_CONSTANT = "cross"\nLOCALLY_DEAD_CONSTANT = "dead"\n'
+    sibling_consumer_body = (
+        "from shared.theme_db.config.constants import CROSS_TREE_CONSTANT\n"
+        "\n"
+        "def tally() -> str:\n"
+        "    return CROSS_TREE_CONSTANT\n"
+    )
+    constants_path = _build_cross_tree_repository(
+        neutral_root, constants_body, sibling_consumer_body
+    )
+    package_tree_neighbor = constants_path.parent.parent / "neighbor.py"
+    package_tree_neighbor.write_text(
+        "def neighbor() -> int:\n    return 1\n", encoding="utf-8"
+    )
+    read_counts: dict[str, int] = {}
+    original_read_text = Path.read_text
+
+    def counting_read_text(self: Path, *positional: object, **keyword: object) -> str:
+        normalized_key = os.path.normcase(str(self.resolve()))
+        read_counts[normalized_key] = read_counts.get(normalized_key, 0) + 1
+        return original_read_text(self, *positional, **keyword)  # type: ignore[arg-type]  # forwards args
+
+    monkeypatch.setattr(Path, "read_text", counting_read_text)
+    _check(constants_body, str(constants_path))
+    over_read_paths = {
+        each_path: each_count for each_path, each_count in read_counts.items() if each_count > 1
+    }
+    assert not over_read_paths, (
+        f"Widening must read each .py file at most once, got over-reads: {over_read_paths}"
+    )

package/hooks/hooks_constants/dead_module_constant_constants.py

@@ -10,6 +10,7 @@ DUNDER_INIT_FILENAME: str = "__init__.py"
 CONSTANTS_MODULE_SUFFIX: str = "_constants.py"
 CONFIG_DIRECTORY_SEGMENT: str = "config"
 DUNDER_ALL_NAME: str = "__all__"
+GIT_DIRECTORY_NAME: str = ".git"
 MINIMUM_UPPER_SNAKE_LENGTH: int = 2
 MAX_DEAD_MODULE_CONSTANT_ISSUES: int = 25
 MAX_SCAN_ROOT_FILE_COUNT: int = 2000

package/package.json

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

package/skills/autoconverge/workflow/converge.fix-recovery.test.mjs

@@ -0,0 +1,185 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const workflowDirectory = dirname(fileURLToPath(import.meta.url));
+const convergeSource = readFileSync(join(workflowDirectory, 'converge.mjs'), 'utf8');
+
+function functionSource(functionName) {
+  const functionStart = convergeSource.indexOf(`function ${functionName}(`);
+  assert.notEqual(functionStart, -1, `expected ${functionName} to exist`);
+  const nextMatch = /\n(?:async )?function /.exec(convergeSource.slice(functionStart + 1));
+  const functionEnd =
+    nextMatch === null ? convergeSource.length : functionStart + 1 + nextMatch.index;
+  return convergeSource.slice(functionStart, functionEnd);
+}
+
+function constantLine(constantName) {
+  const matchedLine = convergeSource
+    .split('\n')
+    .find((eachLine) => eachLine.trimStart().startsWith(`const ${constantName} =`));
+  assert.ok(matchedLine, `expected ${constantName} to be declared`);
+  return matchedLine;
+}
+
+function schemaSource(schemaName, nextDeclaration) {
+  const schemaStart = convergeSource.indexOf(`const ${schemaName} = {`);
+  assert.notEqual(schemaStart, -1, `expected ${schemaName} to exist`);
+  const schemaEnd = convergeSource.indexOf(`const ${nextDeclaration}`, schemaStart);
+  assert.notEqual(schemaEnd, -1, `expected ${nextDeclaration} to follow ${schemaName}`);
+  return convergeSource.slice(schemaStart, schemaEnd);
+}
+
+const pureModule = new Function(
+  `${functionSource('commitNeedsCodeRecovery')}\n` + 'return { commitNeedsCodeRecovery };',
+)();
+
+const { commitNeedsCodeRecovery } = pureModule;
+
+test('a dead commit agent (null result) does not need code recovery', () => {
+  assert.equal(commitNeedsCodeRecovery(null), false);
+});
+
+test('a pushed commit does not need code recovery even with the flag and detail set', () => {
+  assert.equal(
+    commitNeedsCodeRecovery({ pushed: true, blockedNeedingEdit: true, blockerDetail: 'CODE_RULES' }),
+    false,
+  );
+});
+
+test('a transient failure (flag false, empty detail) does not need code recovery', () => {
+  assert.equal(
+    commitNeedsCodeRecovery({ pushed: false, blockedNeedingEdit: false, blockerDetail: '' }),
+    false,
+  );
+});
+
+test('a code-edit block (flag true, concrete detail) needs code recovery', () => {
+  assert.equal(
+    commitNeedsCodeRecovery({
+      pushed: false,
+      blockedNeedingEdit: true,
+      blockerDetail: 'BLOCKED [code-rules]: collection param needs all_ prefix',
+    }),
+    true,
+  );
+});
+
+test('a flagged block with an empty detail does not need code recovery', () => {
+  assert.equal(
+    commitNeedsCodeRecovery({ pushed: false, blockedNeedingEdit: true, blockerDetail: '' }),
+    false,
+  );
+});
+
+test('a detail without the flag does not need code recovery', () => {
+  assert.equal(
+    commitNeedsCodeRecovery({ pushed: false, blockedNeedingEdit: false, blockerDetail: 'some text' }),
+    false,
+  );
+});
+
+test('FIX_SCHEMA declares blockedNeedingEdit and blockerDetail as properties', () => {
+  const fixSchema = schemaSource('FIX_SCHEMA', 'EDIT_SCHEMA');
+  assert.match(fixSchema, /blockedNeedingEdit:\s*\{[\s\S]*?type:\s*'boolean'/);
+  assert.match(fixSchema, /blockerDetail:\s*\{[\s\S]*?type:\s*'string'/);
+});
+
+test('FIX_SCHEMA requires blockedNeedingEdit and blockerDetail', () => {
+  const fixSchema = schemaSource('FIX_SCHEMA', 'EDIT_SCHEMA');
+  const requiredMatch = /required:\s*\[([^\]]*)\]/.exec(fixSchema);
+  assert.ok(requiredMatch, 'expected FIX_SCHEMA to carry a required array');
+  assert.match(requiredMatch[1], /blockedNeedingEdit/);
+  assert.match(requiredMatch[1], /blockerDetail/);
+});
+
+test('FIX_RECOVERY_MAX_ATTEMPTS is declared and bounds the recovery loop at 2', () => {
+  assert.match(constantLine('FIX_RECOVERY_MAX_ATTEMPTS'), /=\s*2\s*$/);
+});
+
+for (const commitFunctionName of ['commitVerifiedFixes', 'commitRepairFixes']) {
+  test(`${commitFunctionName} prompt separates an edit-requiring block from a transient failure`, () => {
+    const commitBody = functionSource(commitFunctionName);
+    assert.match(commitBody, /blockedNeedingEdit/, 'expected the edit-block flag to be set in the prompt');
+    assert.match(commitBody, /blockerDetail/, 'expected the verbatim blocker detail to be requested');
+    assert.match(
+      commitBody,
+      /code_rules_gate|CODE_RULES/,
+      'expected the commit prompt to name the CODE_RULES commit gate as an edit-requiring block',
+    );
+    assert.match(
+      commitBody,
+      /transient/i,
+      'expected the commit prompt to name the transient (non-code) failure case',
+    );
+  });
+}
+
+test('recoverCommitBlockEdit is a clean-coder edit step bound to the blocker detail and leaves changes uncommitted', () => {
+  const recoverBody = functionSource('recoverCommitBlockEdit');
+  assert.match(recoverBody, /agentType:\s*'clean-coder'/, 'expected the fixer to use clean-coder');
+  assert.match(recoverBody, /schema:\s*EDIT_SCHEMA/, 'expected the fixer to reuse EDIT_SCHEMA');
+  assert.match(recoverBody, /label:\s*`fix-recover:/, 'expected the fix-recover label');
+  assert.match(recoverBody, /blockerDetail/, 'expected the fixer prompt to consume the blocker detail');
+  assert.match(
+    recoverBody,
+    /only the (?:violation|finding|block)/i,
+    'expected the fixer to be scoped to only the blocking violation',
+  );
+  assert.match(
+    recoverBody,
+    /do not commit and do not push|NO commit and NO push|Do NOT commit|leave .*uncommitted|uncommitted/i,
+    'expected the fixer to leave its fix uncommitted for the re-verify and retry commit',
+  );
+});
+
+test('commitWithRecovery bounds the loop, re-verifies, and retries the commit on a code block', () => {
+  const recoveryBody = functionSource('commitWithRecovery');
+  assert.match(recoveryBody, /commitNeedsCodeRecovery\(/, 'expected the loop guard to call commitNeedsCodeRecovery');
+  assert.match(
+    recoveryBody,
+    /attempt\s*<\s*FIX_RECOVERY_MAX_ATTEMPTS/,
+    'expected the loop to be bounded by FIX_RECOVERY_MAX_ATTEMPTS',
+  );
+  assert.match(recoveryBody, /runRecoverEdit\(/, 'expected the loop to spawn the recover-edit fixer');
+  assert.match(recoveryBody, /runVerify\(/, 'expected the loop to re-verify after the fixer edit');
+  assert.match(recoveryBody, /verdictPassed\(/, 'expected a fresh verdict to gate the retry commit');
+  assert.match(recoveryBody, /runCommit\(/, 'expected the loop to retry the commit');
+  const editGuardIndex = recoveryBody.search(/edited\s*!==\s*true/);
+  const verifyGateIndex = recoveryBody.search(/verdictPassed\(/);
+  assert.notEqual(editGuardIndex, -1, 'expected an early break when the fixer made no edit');
+  assert.ok(
+    editGuardIndex < verifyGateIndex,
+    'expected the no-edit break to precede the re-verify gate',
+  );
+  const recoverEditIndex = recoveryBody.search(/runRecoverEdit\(/);
+  const reverifyIndex = recoveryBody.search(/runVerify\(/);
+  const retryCommitIndex = recoveryBody.lastIndexOf('runCommit(');
+  assert.ok(
+    recoverEditIndex < reverifyIndex && reverifyIndex < retryCommitIndex,
+    'expected order recover-edit -> re-verify -> retry commit, so a verify/commit swap fails',
+  );
+});
+
+test('applyFixes routes its commit through commitWithRecovery wired to the fix-path steps', () => {
+  const applyFixesBody = functionSource('applyFixes');
+  assert.match(applyFixesBody, /commitWithRecovery\(/, 'expected applyFixes to call commitWithRecovery');
+  assert.match(applyFixesBody, /runCommit:\s*\(\)\s*=>\s*commitVerifiedFixes\(/);
+  assert.match(applyFixesBody, /runVerify:\s*\(\)\s*=>\s*verifyFixesInWorkingTree\(/);
+  assert.match(applyFixesBody, /runRecoverEdit:[\s\S]*?recoverCommitBlockEdit\(/);
+});
+
+test('repairConvergence routes its commit through commitWithRecovery wired to the repair-path steps', () => {
+  const repairBody = functionSource('repairConvergence');
+  assert.match(repairBody, /commitWithRecovery\(/, 'expected repairConvergence to call commitWithRecovery');
+  assert.match(repairBody, /runCommit:\s*\(\)\s*=>\s*commitRepairFixes\(/);
+  assert.match(repairBody, /runVerify:\s*\(\)\s*=>\s*verifyRepairChanges\(/);
+  assert.match(repairBody, /runRecoverEdit:[\s\S]*?recoverCommitBlockEdit\(/);
+});
+
+test('the round-loop fix-stalled blockers survive the recovery wiring', () => {
+  assert.match(convergeSource, /fix lens landed no push for/);
+  assert.match(convergeSource, /copilot fix lens landed no push for/);
+});

package/skills/autoconverge/workflow/converge.mjs

@@ -101,8 +101,10 @@ const FIX_SCHEMA = {
     pushed: { type: 'boolean' },
     resolvedWithoutCommit: { type: 'boolean', description: 'true when every finding was already addressed so no code change was made, yet each finding thread was still resolved — the round advances rather than stalling' },
     summary: { type: 'string' },
+    blockedNeedingEdit: { type: 'boolean', description: 'true only when the commit or push was rejected by a commit-time hook or gate whose message requires a code change (for example a CODE_RULES violation the fix introduced), not a transient or auth failure' },
+    blockerDetail: { type: 'string', description: 'verbatim hook or gate rejection text naming the file and rule that must change, or an empty string when no edit-requiring block occurred' },
   },
-  required: ['newSha', 'pushed', 'resolvedWithoutCommit', 'summary'],
+  required: ['newSha', 'pushed', 'resolvedWithoutCommit', 'summary', 'blockedNeedingEdit', 'blockerDetail'],
 }
 
 const EDIT_SCHEMA = {
@@ -434,6 +436,25 @@ function detectFixProgress(fixResult, priorHead, hadThreadBearingFinding) {
   return { progressed, newSha }
 }
 
+/**
+ * Decide whether a commit step was blocked by a commit-time hook or gate that
+ * requires a code change, so the recovery loop should route back to a fixer. A
+ * null result, a successful push, a transient failure (blockedNeedingEdit
+ * false), or a flagged block carrying no detail all read as not-needing-recovery,
+ * so only a flagged block with a concrete message routes to the fixer.
+ * @param {object|null} commitResult the FIX_SCHEMA result, or null on agent failure
+ * @returns {boolean} true only when the commit needs a code-edit recovery pass
+ */
+function commitNeedsCodeRecovery(commitResult) {
+  if (commitResult == null) return false
+  if (commitResult.pushed === true) return false
+  return (
+    commitResult.blockedNeedingEdit === true &&
+    typeof commitResult.blockerDetail === 'string' &&
+    commitResult.blockerDetail.length > 0
+  )
+}
+
 /**
  * Decide whether a resolved HEAD SHA is safe to spawn lenses against. A dead
  * resolve-head agent or a malformed result yields a falsy SHA; spawning lenses
@@ -753,11 +774,68 @@ function commitVerifiedFixes(head, sourceLabel) {
       `Rules:\n` +
       `- Make NO further file edits of any kind. Any edit changes the surface and invalidates the verdict that unlocks the commit gate, so the commit would be blocked. Do not run a formatter, do not touch a test, do not re-fix anything — only commit and push what is already there.\n` +
       `- Make ONE commit for all the working-tree fixes, then push to the PR branch.\n\n` +
-      `Return values: newSha=the new HEAD SHA after your push, pushed=true, resolvedWithoutCommit=false, and a one-line summary. If the commit or push is blocked or fails, return newSha=${head}, pushed=false, resolvedWithoutCommit=false, and a summary naming the failure.`,
+      `Return values:\n` +
+      `- On a successful push: newSha=the new HEAD SHA after your push, pushed=true, resolvedWithoutCommit=false, blockedNeedingEdit=false, blockerDetail="", and a one-line summary.\n` +
+      `- When a commit-time hook or gate (for example code_rules_gate, the CODE_RULES commit gate) rejects the commit because the fix needs a code change: keep the no-edit rule, return newSha=${head}, pushed=false, resolvedWithoutCommit=false, blockedNeedingEdit=true, blockerDetail=<the verbatim hook message naming the file and rule>, and a summary. A recovery fixer runs after you to clear it.\n` +
+      `- On a transient or non-code failure (auth, network, a non-fast-forward, a lock): newSha=${head}, pushed=false, resolvedWithoutCommit=false, blockedNeedingEdit=false, blockerDetail="", and a summary naming the failure.`,
     { label: `fix-commit:${sourceLabel}`, phase: 'Converge', schema: FIX_SCHEMA, agentType: 'clean-coder' },
   )
 }
 
+/**
+ * Commit-recovery fixer: when a commit step is blocked by a commit-time hook or
+ * gate that requires a code change, one clean-coder fixes only that blocking
+ * violation test-first in the working tree and leaves it uncommitted, so the
+ * re-verify step can bind a fresh verdict and the retry commit can push. It does
+ * not re-open the original findings or touch GitHub threads — the edit step
+ * already handled those.
+ * @param {string} head PR HEAD SHA the fixes were raised against
+ * @param {string} blockerDetail verbatim hook/gate message naming the file and rule to change
+ * @param {string} sourceLabel short description of where the findings came from
+ * @param {number} attempt the 1-based recovery attempt number
+ * @returns {Promise<object>} EDIT_SCHEMA result
+ */
+function recoverCommitBlockEdit(head, blockerDetail, sourceLabel, attempt) {
+  return convergeAgent(
+    `You are the COMMIT-RECOVERY fixer (attempt ${attempt}) for fixes (${sourceLabel}) on ${prCoordinates}, HEAD ${head}. A prior commit step was blocked by a commit-time hook or gate that requires a code change. A separate verify step then a separate commit step run after you.\n\n` +
+      `The blocking hook or gate said:\n${blockerDetail}\n\n` +
+      `Rules:\n` +
+      `- Confirm the working tree is on the PR branch at HEAD ${head} with the prior fixes still present.\n` +
+      `- Fix ONLY the violation named above, test-first (failing test, then minimum code to pass) per CODE_RULES. Do not re-open the original findings, and do not touch GitHub review threads — the edit step already handled those.\n` +
+      `- Leave the corrected fixes in the working tree. Do NOT commit and do NOT push — the verify step re-binds a verdict and the commit step pushes after you.\n\n` +
+      `Return values: edited=true with a one-line summary when you changed code to clear the block; edited=false, resolvedWithoutCommit=false when the block cannot be cleared with a code change.`,
+    { label: `fix-recover:${sourceLabel}`, phase: 'Converge', schema: EDIT_SCHEMA, agentType: 'clean-coder' },
+  )
+}
+
+const FIX_RECOVERY_MAX_ATTEMPTS = 2
+
+/**
+ * Run a commit step and, when it is blocked by a commit-time hook or gate that
+ * requires a code change, route back to a fixer: fix the blocking violation,
+ * re-verify so a fresh verdict binds the corrected surface, then retry the
+ * commit — bounded by FIX_RECOVERY_MAX_ATTEMPTS. The loop breaks early when the
+ * fixer makes no edit or the re-verify does not pass, returning the last commit
+ * result so the caller's existing no-push handling still applies. A transient
+ * failure never enters the loop (commitNeedsCodeRecovery is false), so an auth or
+ * network failure keeps the existing blocker path.
+ * @param {{runCommit: function, runVerify: function, runRecoverEdit: function}} steps the commit, re-verify, and recover-edit thunks
+ * @returns {Promise<object>} the final FIX_SCHEMA result
+ */
+async function commitWithRecovery({ runCommit, runVerify, runRecoverEdit }) {
+  let commitResult = await runCommit()
+  let attempt = 0
+  while (commitNeedsCodeRecovery(commitResult) && attempt < FIX_RECOVERY_MAX_ATTEMPTS) {
+    attempt += 1
+    const recoverEdit = await runRecoverEdit(commitResult.blockerDetail, attempt)
+    if (recoverEdit?.edited !== true) break
+    const verifyTranscript = await runVerify()
+    if (!verdictPassed(verifyTranscript)) break
+    commitResult = await runCommit()
+  }
+  return commitResult
+}
+
 /**
  * Fix lens: edit (clean-coder, no commit) -> verify (code-verifier emits a
  * verdict fence binding the working tree) -> commit (clean-coder, one commit +
@@ -780,6 +858,8 @@ async function applyFixes(head, findings, sourceLabel) {
       pushed: false,
       resolvedWithoutCommit: true,
       summary: editResult?.summary || 'fixes resolved without a code change',
+      blockedNeedingEdit: false,
+      blockerDetail: '',
     }
   }
   const verifyTranscript = await verifyFixesInWorkingTree(head, findings, sourceLabel)
@@ -789,9 +869,15 @@ async function applyFixes(head, findings, sourceLabel) {
       pushed: false,
       resolvedWithoutCommit: false,
       summary: `verify step did not pass the working-tree fixes for ${findings.length} finding(s) — not committing`,
+      blockedNeedingEdit: false,
+      blockerDetail: '',
     }
   }
-  return commitVerifiedFixes(head, sourceLabel)
+  return commitWithRecovery({
+    runCommit: () => commitVerifiedFixes(head, sourceLabel),
+    runVerify: () => verifyFixesInWorkingTree(head, findings, sourceLabel),
+    runRecoverEdit: (detail, attempt) => recoverCommitBlockEdit(head, detail, sourceLabel, attempt),
+  })
 }
 
 /**
@@ -978,7 +1064,10 @@ function commitRepairFixes(head, wasRebased) {
       `Rules:\n` +
       `- Make NO further file edits of any kind. Any edit changes the surface and invalidates the verdict that unlocks the commit gate, so the push would be blocked. Do not run a formatter, do not re-fix anything — only commit and push what is already there.\n` +
       `- Commit any uncommitted bot-thread fix in ONE commit (skip the commit when the working tree carries only already-committed rebase results). ${pushInstruction}\n\n` +
-      `Return values: newSha=the new HEAD SHA after your push, pushed=true, resolvedWithoutCommit=false, and a one-line summary. If the commit or push is blocked or fails, return newSha=${head}, pushed=false, resolvedWithoutCommit=false, and a summary naming the failure.`,
+      `Return values:\n` +
+      `- On a successful push: newSha=the new HEAD SHA after your push, pushed=true, resolvedWithoutCommit=false, blockedNeedingEdit=false, blockerDetail="", and a one-line summary.\n` +
+      `- When a commit-time hook or gate (for example code_rules_gate, the CODE_RULES commit gate) rejects the commit because the fix needs a code change: keep the no-edit rule, return newSha=${head}, pushed=false, resolvedWithoutCommit=false, blockedNeedingEdit=true, blockerDetail=<the verbatim hook message naming the file and rule>, and a summary. A recovery fixer runs after you to clear it.\n` +
+      `- On a transient or non-code failure (auth, network, a non-fast-forward, a lock): newSha=${head}, pushed=false, resolvedWithoutCommit=false, blockedNeedingEdit=false, blockerDetail="", and a summary naming the failure.`,
     { label: 'repair-commit', phase: 'Finalize', schema: FIX_SCHEMA, agentType: 'clean-coder' },
   )
 }
@@ -1006,6 +1095,8 @@ async function repairConvergence(head, failures) {
       pushed: false,
       resolvedWithoutCommit: true,
       summary: editResult?.summary || 'convergence gates resolved without a code change or rebase',
+      blockedNeedingEdit: false,
+      blockerDetail: '',
     }
   }
   const verifyTranscript = await verifyRepairChanges(head, failures)
@@ -1015,9 +1106,16 @@ async function repairConvergence(head, failures) {
       pushed: false,
       resolvedWithoutCommit: false,
       summary: `repair verify step did not pass the working-tree repair on HEAD ${head} — not pushing`,
+      blockedNeedingEdit: false,
+      blockerDetail: '',
     }
   }
-  return commitRepairFixes(head, editResult?.rebased === true)
+  const wasRebased = editResult?.rebased === true
+  return commitWithRecovery({
+    runCommit: () => commitRepairFixes(head, wasRebased),
+    runVerify: () => verifyRepairChanges(head, failures),
+    runRecoverEdit: (detail, attempt) => recoverCommitBlockEdit(head, detail, 'repair', attempt),
+  })
 }
 
 /**