claude-dev-env 1.75.0 → 1.76.0

package/hooks/hooks_constants/duplicate_function_body_constants.py

@@ -1,9 +1,12 @@
-"""Constants for the duplicate-function-body scan in ``code_rules_enforcer``.
+"""Constants for the duplicate-function-body scans in ``code_rules_enforcer``.
 
-The blocking scan flags a top-level function whose body is structurally identical
-to a top-level function already defined in a sibling ``.py`` module in the same
-directory. This catches the Reuse-before-create / DRY violation where a helper is
-copy-pasted across several modules instead of imported from one shared home.
+The cross-file blocking scan flags a top-level function whose body is
+structurally identical to a top-level function already defined in a sibling
+``.py`` module in the same directory. The same-file blocking scan flags a
+top-level function whose body appears verbatim as a contiguous statement block
+inside another function in the same module. Both catch the Reuse-before-create /
+DRY violation where a block of logic is copied instead of called from one shared
+home, so a fix that lands in one copy leaves the other carrying the bug.
 
 The ``CROSS_SKILL_*`` and ``SKILL*`` constants feed the non-blocking companion
 advisory: a helper copied between two skills' ``scripts`` directories, where a
@@ -12,6 +15,7 @@ skill on stderr rather than denying the write.
 """
 
 MINIMUM_DUPLICATE_BODY_STATEMENTS: int = 3
+MINIMUM_INLINE_DUPLICATE_BODY_STATEMENTS: int = 1
 MAX_DUPLICATE_BODY_ISSUES: int = 25
 DUNDER_INIT_FILENAME: str = "__init__.py"
 PYTHON_SOURCE_SUFFIX: str = ".py"
@@ -20,6 +24,18 @@ DUPLICATE_BODY_GUIDANCE: str = (
     "extract a single shared helper (for example in hooks_constants/) and "
     "import it from both modules instead of copying it (Reuse before create / DRY)"
 )
+SAME_FILE_INLINE_DUPLICATE_GUIDANCE: str = (
+    "this function body is also present inline as a contiguous statement block "
+    "inside another function in the same module; call this helper from that "
+    "function instead of repeating the block, so a single helper backs both call "
+    "sites and a fix cannot land in one copy while the other keeps the bug "
+    "(Reuse before create / DRY)"
+)
+SAME_FILE_INLINE_DUPLICATE_SPAN_SUFFIX_TEMPLATE: str = (
+    "(inline duplicate body spans: helper at line {helper_start} spanning "
+    "{helper_length} lines, enclosing at line {enclosing_start} spanning "
+    "{enclosing_length} lines)"
+)
 
 SKILLS_DIRECTORY_NAME: str = "skills"
 SKILL_SCRIPTS_DIRECTORY_NAME: str = "scripts"

package/package.json

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

package/rules/claude-md-orphan-file.md

@@ -1,24 +1,23 @@
 # Orphan File Reference in a Per-Directory CLAUDE.md
 
-**When this applies:** Any Write, Edit, or MultiEdit to a file named `CLAUDE.md` that lists files in a markdown table whose first column names each file in backticks.
+**When this applies:** Any Write, Edit, or MultiEdit to a file named `CLAUDE.md` that lists files in a markdown table whose first column names each file in backticks, or that shows run commands invoking those files inside fenced code blocks.
 
 ## Rule
 
-Every bare filename a per-directory `CLAUDE.md` table names in its first column points at a file that exists in the directory subtree the `CLAUDE.md` describes. A first-column cell naming a file that exists nowhere in that subtree points a reader at something that is not there: the listing claims a file the directory does not hold.
+Every bare filename a per-directory `CLAUDE.md` names points at a file that exists in the directory subtree the `CLAUDE.md` describes — both the filenames its table cells list and the scripts its fenced run commands invoke (`python script.py`). A table cell or a run command naming a file that exists nowhere in that subtree points a reader at something that is not there: the doc claims a file the directory does not hold.
 
-When you add a table row, the file it names already exists in this directory or a subdirectory of it. When you remove a file, drop the row that named it.
+When you add a table row or a run command, the file it names already exists in this directory or a subdirectory of it. When you remove a file, drop the row and the run command that named it.
 
 ## What the gate checks
 
 The `claude_md_orphan_file_blocker.py` hook runs on every Write, Edit, and MultiEdit whose target basename is `CLAUDE.md`. It:
 
 1. Reads the content the tool would leave on disk. For a Write that is the full `content`. For an Edit or MultiEdit it reconstructs the post-edit file — the existing on-disk file with the replacements applied — and also notes which orphans the file already held before the edit, so a pre-existing orphan on an untouched line is excluded and only an orphan the edit introduces is reported; when the existing file cannot be read, it scans the raw `new_string` fragment(s) instead.
-2. Skips any line inside a fenced code block (between a ``` or `~~~` fence pair), since an example table there is documentation, not a live listing.
-3. Takes the first column of each remaining markdown table row and keeps the cells that name a bare filename: wrapped in backticks, no path separator, not a slash-command, and ending in a known file extension (`.py`, `.md`, `.json`, `.mjs`, `.js`, `.ts`, `.ps1`, `.cmd`, `.ahk`, `.yml`, `.yaml`, `.sh`, `.txt`, `.cfg`, `.toml`, `.ini`).
-4. Blocks the write when a named file exists nowhere under the scan root — the `CLAUDE.md` directory's parent, which covers the directory, its subdirectories, and its siblings. A filesystem error that halts the whole subtree walk fails open (the write proceeds), so an unreadable tree never blocks a write.
+2. Collects two kinds of referenced filename. Table cells: the first column of each markdown table row **outside** a fenced code block, keeping cells that name a bare filename wrapped in backticks, no path separator, not a slash-command, ending in a known file extension (`.py`, `.md`, `.json`, `.mjs`, `.js`, `.ts`, `.ps1`, `.cmd`, `.ahk`, `.yml`, `.yaml`, `.sh`, `.txt`, `.cfg`, `.toml`, `.ini`). Run commands: each line **inside** a fenced code block (between a ``` or `~~~` fence pair) that invokes an interpreter (`python`, `python.exe`, `python3`, `node`, `pwsh`, `powershell`, `bash`, `sh`, `ruby`, `perl`) on a script, taking that script's basename when it ends in `.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`, `.rb`, or `.pl`. A fenced *table row* is an example, not a live listing, so it contributes no table-cell filename; a fenced *run command* is the contract a reader runs, so its script filename is checked.
+3. Blocks the write when a referenced filename — from a table cell or a fenced run command — exists nowhere under the scan root — the `CLAUDE.md` directory's parent, which covers the directory, its subdirectories, and its siblings. A filesystem error that halts the whole subtree walk fails open (the write proceeds), so an unreadable tree never blocks a write.
 
-The check stays quiet for a target that is not a `CLAUDE.md`, for a table cell that holds a path, a subdirectory ending in `/`, or a slash-command, for a table row inside a fenced code block, and for a table whose content names an explicit relative-path source (a `../` token), since that table documents files that sit outside the subtree by design.
+The check stays quiet for a target that is not a `CLAUDE.md`, for a table cell that holds a path, a subdirectory ending in `/`, or a slash-command, for a table row inside a fenced code block, for an inline `python x.py` mention outside a fence (prose, not a runnable contract), and for a table whose content names an explicit relative-path source (a `../` token), since that table documents files that sit outside the subtree by design.
 
 ## Why this is a hook, not a lint pass
 
-A table row that names an absent file reads as a contract: a reader trusts the listing to map the directory. A wrong row sends the reader looking for a file that is not there and erodes trust in every other row. Catching it as each row is written keeps the table and the directory in step.
+A table row or a run command that names an absent file reads as a contract: a reader trusts the listing to map the directory and trusts the shown command to run. A wrong row sends the reader looking for a file that is not there; a stale run command fails the moment the reader runs it. Both erode trust in every other entry. Catching them as each line is written keeps the doc and the directory in step.

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

@@ -16,6 +16,7 @@ Read the body and the docstring side by side:
 - **Suppressor / skip lists.** A body with several early returns that suppress the check names each suppressor in the prose.
 - **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. A step enumeration that names the body's linear steps also names every corrective step the body guards inside an `if`/`elif` branch (`if not await cancel_and_reinitiate_update(...): return`). The `check_docstring_step_enumeration_dispatch_coverage` gate blocks the branch-guarded-dispatch form of this drift — a step-enumeration docstring that omits a two-or-more-token dispatch step the body guards inside a branch — at Write/Edit time.
+- **JS/`.mjs` resume-task enumerations.** A `spawn<Role>Agent` JSDoc that enumerates its sibling `resume<Role>Agent`'s resume tasks in a parenthetical `resume (repair-verify, hardening-verify)` list names every `task === '<name>'` branch the resume body dispatches on. The `check_js_resume_task_enumeration_coverage` gate blocks the JavaScript form of this drift — a spawn JSDoc whose resume enumeration omits a dispatched task — at Write/Edit time. This is the `.mjs` slice of the same Category O6 standard the Python gates carry; the Python AST docstring gates never inspect JavaScript source.
 - **Returns-clause cardinality.** A `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) matches the count of keys in that family in the returned dict literal. When the dict holds one key in the family (`sheen_mid`), the noun is singular (`the sheen stop`); a plural noun there claims two or more entries the dict does not hold. The `check_docstring_returns_plural_cardinality` gate blocks the single-key-with-plural-noun form of this drift at Write/Edit time.
 - **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.
 - **Exclusion-clause distinguisher.** A docstring sentence that says a named category of input "are not" / "is not" the thing the function flags (`plain logging, screenshot, or method-on-local calls inside a branch are not dispatch steps`) keys the exclusion to the same axis the body's classification keys on. When the body decides on one axis (a call sits in an `If.test` guard versus a plain statement) but the prose excludes on a different axis (the call's receiver shape — a method on a local), the exclusion clause names a category the body still flags: a guarded method-on-local call is flagged even though the prose lists method-on-local calls as excluded. Read the body's actual branch condition, then state the exclusion on that same axis (`plain (unguarded) calls inside a branch body are not dispatch steps`), so every member the prose excludes is a member the body also excludes.

package/rules/package-inventory-stale-entry.md

@@ -8,6 +8,14 @@ A package directory that documents its own files in a `README.md` Layout table o
 
 When you create a new production file in such a directory, add an entry naming it — a row in the `README.md` table, a bullet in the `CLAUDE.md` list — in the same change. The entry names the file in backticks and says what it does.
 
+## Companion: keep the Purpose/scope sentence in step with the new responsibility
+
+The file-list entry is the deterministic slice the gate enforces. A package inventory also carries a free-prose scope sentence — a `## Purpose` paragraph in a `CLAUDE.md`, a one-line summary the parent directory's inventory gives each subdirectory — that names the responsibilities the package's modules cover. When the new module adds a responsibility the scope sentence omits, the same change broadens that sentence to name it, and updates the parent inventory's one-line summary of this subdirectory to match.
+
+Take a `files/` package whose `Purpose` reads "Holds helpers for downloading files over HTTP and extracting zip archives" and whose parent summary reads "file download, extraction, and path config helpers". Once a `force_remove.py` module that removes a directory tree sits beside the download helpers, both sentences name a narrower responsibility set than the directory holds. The required file-list bullet alone leaves that gap open. Broaden the `Purpose` sentence to name directory removal, and broaden the parent summary to match, in the same change that adds the module and its bullet.
+
+This scope-sentence slice is free prose: a hook cannot derive a module's responsibility from its filename, so the gate leaves it to judgment. It is the judgment companion to the file-list entry the gate enforces, and it belongs in the same change. This is the `category-o-docstring-vs-impl-drift` (O8) orphaned-doc-claim shape applied to a package inventory: a behavior change orphans a scope claim the prose still makes.
+
 ## What the gate checks
 
 The `package_inventory_stale_blocker.py` hook runs on every Write whose target is a new file (a path not yet on disk). It:

package/skills/anthropic-plan/CLAUDE.md

@@ -2,7 +2,7 @@
 
 **Trigger:** `/anthropic-plan`, `/plan`, "plan this first", "think before coding", "make a plan", "scope this out", "don't code yet", and non-trivial requests that need source-grounded design before build work.
 
-Creates a repo-local plan packet under `docs/plans/<slug>/` by running the `plan-packet.mjs` workflow. The packet holds context, spec, implementation steps, validation, and a handoff prompt for the build agent. The skill stops before any production code changes.
+Creates a repo-local plan packet under `docs/plans/<slug>/` by running the `plan-packet.mjs` workflow. The skill first drafts a short starting plan and gets the user's approval in plan mode (`EnterPlanMode` / `ExitPlanMode`); on approval it runs the workflow. The packet holds context, spec, implementation steps, validation, and a handoff prompt for the build agent. The skill stops before any production code changes.
 
 ## Subdirectories
 

package/skills/anthropic-plan/SKILL.md

@@ -5,9 +5,20 @@ description: Workflow-backed implementation planning that creates a deep repo-lo
 
 # Anthropic Plan
 
-Create a source-grounded plan packet through the Claude Code Workflow runtime. The output is a repo-local `docs/plans/<slug>/` folder with context, spec, implementation, validation, and handoff docs. Stop before implementation.
+Create a source-grounded plan packet through the Claude Code Workflow runtime. First draft a short starting plan and get it approved in plan mode; then the workflow builds the full repo-local `docs/plans/<slug>/` packet — context, spec, implementation, validation, and handoff docs. Stop before implementation.
 
-## Isolate first
+## Plan first (plan mode)
+
+Before any worktree or workflow, build a short starting plan in plan mode and get the user's approval. This is a cheap gate: it confirms the direction before the workflow spends tokens building the full packet.
+
+1. Enter plan mode with `EnterPlanMode` if the session is not already in it.
+2. Read the handful of files closest to the request — the entry points, the modules the change touches, the tests that cover them — enough to ground the approach in real source.
+3. Write a short plan: the goal in a sentence or two, the approach, the files the build will touch, and the main risks or open choices. Use `AskUserQuestion` for any product choice that local context cannot settle.
+4. Call `ExitPlanMode` to hand the plan to the user for approval.
+
+On approval, fold the approved scope and direction into the `task` payload at launch, then continue with the steps below. If the user revises the plan, fold the changes in and present it again. Do not isolate a worktree or launch the workflow until the starting plan is approved.
+
+## Isolate the session
 
 The workflow's background subagents write the packet into the working tree. A background session that has not isolated into a worktree cannot write a shared checkout — the background-isolation guard rejects the write. So put the session in a worktree before launching the workflow:
 
@@ -27,6 +38,8 @@ Workflow({
 })
 ```
 
+The `task` string carries the user request together with the approved starting plan, so the packet reflects the direction the user signed off on.
+
 If the Workflow tool is unavailable, say `anthropic-plan requires the Workflow tool; aborting` and stop.
 
 ## Self-healing writes

package/skills/autoconverge/workflow/converge.contract.test.mjs

@@ -294,11 +294,11 @@ test('every verify step calls buildVerdictFenceSteps, uses code-verifier, and fo
   }
 });
 
-test('resumeFixerAgent verify-commit path uses code-verifier and calls buildVerdictFenceSteps', () => {
+test('resumeFixerAgent never verifies its own session — verification belongs to the separate verifier', () => {
   const fixerBody = lensPromptBody('resumeFixerAgent');
-  assert.match(fixerBody, /buildVerdictFenceSteps\(/, 'expected resumeFixerAgent to call buildVerdictFenceSteps');
-  assert.match(fixerBody, /agentType:\s*'code-verifier'/, 'expected resumeFixerAgent to use code-verifier');
-  assert.match(fixerBody, /do no edits|make no edits|not edit|no file edits/i, 'expected resumeFixerAgent to forbid edits');
+  assert.doesNotMatch(fixerBody, /buildVerdictFenceSteps\(/, 'expected the fixer to not emit a verdict fence — the separate verifier does');
+  assert.doesNotMatch(fixerBody, /agentType:\s*'code-verifier'/, 'expected the fixer session to be clean-coder only');
+  assert.match(fixerBody, /agentType:\s*'clean-coder'/, 'expected the fixer to use clean-coder for its commit and recovery edits');
 });
 
 test('resumeVerifierAgent uses --manifest-hash-for-branch with the hardening branch and forbids edits', () => {
@@ -315,15 +315,14 @@ test('resumeVerifierAgent uses --manifest-hash-for-branch with the hardening bra
   );
 });
 
-test('resumeVerifierAgent and resumeFixerAgent pass PR coordinates to buildVerdictFenceSteps', () => {
-  for (const verifyFunctionName of ['resumeFixerAgent', 'resumeVerifierAgent']) {
-    const verifyBody = lensPromptBody(verifyFunctionName);
-    assert.match(
-      verifyBody,
-      /buildVerdictFenceSteps\(/,
-      `expected ${verifyFunctionName} to call buildVerdictFenceSteps`,
-    );
-  }
+test('resumeVerifierAgent passes PR coordinates to buildVerdictFenceSteps for the fix-verify and repair-verify tasks', () => {
+  const verifyBody = lensPromptBody('resumeVerifierAgent');
+  assert.match(verifyBody, /task === 'fix-verify'/, 'expected resumeVerifierAgent to carry the fix-path verify task');
+  assert.match(
+    verifyBody,
+    /buildVerdictFenceSteps\(input\.owner, input\.repo, input\.prNumber\)/,
+    'expected resumeVerifierAgent to pass PR coordinates to buildVerdictFenceSteps',
+  );
 });
 
 test('the commit path in resumeFixerAgent forbids further edits and uses clean-coder', () => {
@@ -663,7 +662,6 @@ const newSpawnResumeHelpers = [
   { name: 'resumeGeneralUtilityAgent', isAsync: false },
   { name: 'spawnConvergenceCheckAgent', isAsync: true },
   { name: 'resumeConvergenceCheckAgent', isAsync: false },
-  { name: 'extractVerdict', isAsync: false },
 ];
 
 for (const { name, isAsync } of newSpawnResumeHelpers) {
@@ -824,8 +822,3 @@ test('extractVerifyObjection calls parseLastVerdictFence', () => {
   const objectionBody = lensPromptBody('extractVerifyObjection');
   assert.match(objectionBody, /parseLastVerdictFence\(/, 'expected extractVerifyObjection to call the shared parser');
 });
-
-test('extractVerdict calls parseLastVerdictFence', () => {
-  const verdictBody = lensPromptBody('extractVerdict');
-  assert.match(verdictBody, /parseLastVerdictFence\(/, 'expected extractVerdict to call the shared parser');
-});

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

@@ -167,6 +167,77 @@ test('applyFixes routes through spawnFixerAgent and fixerWithRecovery', () => {
   assert.match(applyFixesBody, /fixerWithRecovery\(/, 'expected applyFixes to call fixerWithRecovery');
 });
 
+test('applyFixes spawns a separate verifier and passes both ids into fixerWithRecovery', () => {
+  const applyFixesBody = functionSource('applyFixes');
+  assert.match(
+    applyFixesBody,
+    /spawnVerifierAgent\(/,
+    'expected applyFixes to spawn a separate verifier agent so the fix-path verdict is independent of the fixer',
+  );
+  const fixerSpawnIndex = applyFixesBody.search(/spawnFixerAgent\(/);
+  const verifierSpawnIndex = applyFixesBody.search(/spawnVerifierAgent\(/);
+  assert.notEqual(fixerSpawnIndex, -1, 'expected applyFixes to spawn the fixer');
+  assert.notEqual(verifierSpawnIndex, -1, 'expected applyFixes to spawn the verifier');
+  assert.match(
+    applyFixesBody,
+    /fixerWithRecovery\(\s*fixerAgentId,\s*verifierId,/,
+    'expected applyFixes to pass both the fixer and verifier ids into fixerWithRecovery',
+  );
+});
+
+test('fixerWithRecovery runs verify on the verifier id and edits/commits on the fixer id', () => {
+  const recoveryBody = functionSource('fixerWithRecovery');
+  assert.match(
+    recoveryBody,
+    /resumeVerifierAgent\(\s*verifierId,/,
+    'expected fixerWithRecovery to resume the separate verifier for the verify step',
+  );
+  assert.match(
+    recoveryBody,
+    /resumeFixerAgent\(\s*fixerAgentId,\s*'commit'/,
+    'expected fixerWithRecovery to resume the fixer for the commit step',
+  );
+  assert.doesNotMatch(
+    recoveryBody,
+    /resumeFixerAgent\(\s*fixerAgentId,\s*'(?:verify-commit|fix-verify)'/,
+    'expected the verify step never to resume the fixer session — the verifier must grade a different session than the one that edits',
+  );
+});
+
+test('the fix-path verify resumes a different agent id than the fix-path edits, mirroring the repair path', () => {
+  const recoveryBody = functionSource('fixerWithRecovery');
+  const verifyResumeMatch = /resumeVerifierAgent\(\s*(\w+),/.exec(recoveryBody);
+  const editResumeMatch = /resumeFixerAgent\(\s*(\w+),/.exec(recoveryBody);
+  assert.ok(verifyResumeMatch, 'expected a verify resume call naming its agent id');
+  assert.ok(editResumeMatch, 'expected an edit/commit resume call naming its agent id');
+  assert.notEqual(
+    verifyResumeMatch[1],
+    editResumeMatch[1],
+    'expected the verify step to resume a different agent id than the edit/commit step',
+  );
+});
+
+test('the verifier carries a fix-verify task so the fix path verdict comes from the verifier group', () => {
+  const verifierBody = functionSource('resumeVerifierAgent');
+  assert.match(verifierBody, /task === 'fix-verify'/, 'expected resumeVerifierAgent to handle the fix-verify task');
+  assert.match(verifierBody, /buildVerdictFenceSteps\(/, 'expected the fix-verify task to emit a verdict fence');
+  assert.match(verifierBody, /agentType:\s*'code-verifier'/, 'expected the fix-verify task to run as code-verifier');
+});
+
+test('resumeFixerAgent no longer verifies its own edits — no code-verifier verify-commit task remains', () => {
+  const fixerBody = functionSource('resumeFixerAgent');
+  assert.doesNotMatch(
+    fixerBody,
+    /task === 'verify-commit'/,
+    'expected the fixer to no longer carry the verify-commit task that graded its own session',
+  );
+  assert.doesNotMatch(
+    fixerBody,
+    /agentType:\s*'code-verifier'/,
+    'expected the fixer session to be clean-coder only — a separate verifier grades the working tree',
+  );
+});
+
 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');

package/skills/autoconverge/workflow/converge.mjs

@@ -128,27 +128,32 @@ function resumeGitAgent(agentId, task, head) {
 
 /**
  * Spawn the fixer clean-coder agent for one fix batch, establishing its role and
- * the PR coordinates so each later resume (verify-commit, commit, and recovery)
- * continues the same session. The spawn makes no edits — the verify-commit resume
- * is the first step that touches the working tree. Returns the runtime agent id
- * so the resume calls target the live session; a runtime without resume support
- * returns no agent id, and each resume falls back to a fresh spawn.
+ * the PR coordinates so each later resume (commit and recovery edits) continues
+ * the same session. The fixer never verifies — a separate verifier agent grades
+ * the working tree, so the verdict comes from a different session than the one
+ * that commits and recovers, mirroring the repair and conflict paths. The spawn
+ * makes no edits — the first recovery resume is the earliest step that touches
+ * the working tree. Returns the runtime agent id so the resume calls target the
+ * live session; a runtime without resume support returns no agent id, and each
+ * resume falls back to a fresh spawn.
  * @param {string} head PR HEAD SHA
  * @param {Array<object>} findings the findings to fix
  * @param {string} sourceLabel short description of where the findings came from
- * @param {string} task initial task name
  * @returns {Promise<string|undefined>} the runtime agent id, or undefined when the runtime returns none
  */
-async function spawnFixerAgent(head, findings, sourceLabel, task) {
+async function spawnFixerAgent(head, findings, sourceLabel) {
   const result = await convergeAgent(
-    `You are the fixer agent for ${findings.length} finding(s) (${sourceLabel}) on ${prCoordinates}, HEAD ${head}. The edit step left fixes in the working tree, uncommitted. Across this session you run a sequence of steps (the first is ${task}): verify the working-tree fixes, commit and push them, and recover when a verify objection or a commit-gate block needs another edit. Make NO edits in this first turn — confirm only that the working tree is on the PR branch at HEAD ${head} with uncommitted fixes present, then wait for the verify-commit instructions. Reply READY.`,
+    `You are the fixer agent for ${findings.length} finding(s) (${sourceLabel}) on ${prCoordinates}, HEAD ${head}. The edit step left fixes in the working tree, uncommitted. Across this session you run a sequence of steps: commit and push the working-tree fixes once a separate verifier passes them, and recover when a verify objection or a commit-gate block needs another edit. A separate verifier agent grades the working tree, so you never verify your own edits. Make NO edits in this first turn — confirm only that the working tree is on the PR branch at HEAD ${head} with uncommitted fixes present, then wait for the next step's instructions. Reply READY.`,
     { label: `fixer:${sourceLabel}`, phase: 'Converge', agentType: 'clean-coder' },
   )
   return result?.agentId
 }
 
 /**
- * Resume the fixer agent for verify-commit or recovery.
+ * Resume the fixer agent for commit or recovery edits. The fixer never verifies;
+ * a separate verifier agent emits the verdict, so commit, verify-recover, and
+ * commit-recover all run on the editing session while the verdict that gates the
+ * commit comes from a different session.
  * @param {string} agentId the agent id from spawnFixerAgent
  * @param {string} task the short task name
  * @param {object} context task-specific context
@@ -156,18 +161,6 @@ async function spawnFixerAgent(head, findings, sourceLabel, task) {
  */
 function resumeFixerAgent(agentId, task, context) {
   const label = `fixer:${context.sourceLabel}`
-  if (task === 'verify-commit') {
-    const findingsBlock = renderFindingsBlock(context.findings)
-    return convergeAgent(
-      `You are the VERIFY step for ${context.findings.length} finding(s) (${context.sourceLabel}) on ${prCoordinates}, HEAD ${context.head}. The edit step left fixes in the working tree, uncommitted. Do NO edits of any kind — verification only; any edit invalidates the verdict you are about to emit.\n\n` +
-        `Findings the working-tree fixes must address:\n${findingsBlock}\n\n` +
-        `Steps:\n` +
-        `1. Resolve the worktree repo root for running tests: REPO=$(git rev-parse --show-toplevel).\n` +
-        `2. Verify the uncommitted working-tree changes resolve every finding above: run the relevant tests and the named gates against the working tree. Read the diff (git diff) and confirm each finding is fixed test-first per CODE_RULES.\n` +
-        `3. ${buildVerdictFenceSteps(input.owner, input.repo, input.prNumber)}`,
-      { label, phase: 'Converge', agentType: 'code-verifier', resume: agentId },
-    )
-  }
   if (task === 'commit') {
     return convergeAgent(
       `You are the COMMIT step for fixes (${context.sourceLabel}) on ${prCoordinates}, HEAD ${context.head}. The edit step left fixes in the working tree and the verify step passed, so a verifier verdict already binds to this exact working tree.\n\n` +
@@ -181,6 +174,20 @@ function resumeFixerAgent(agentId, task, context) {
       { label, phase: 'Converge', schema: FIX_SCHEMA, agentType: 'clean-coder', resume: agentId },
     )
   }
+  if (task === 'commit-recover') {
+    const attempt = context.attempt || 1
+    return convergeAgent(
+      `You are the COMMIT-RECOVERY fixer (attempt ${attempt}) for fixes (${context.sourceLabel}) on ${prCoordinates}, HEAD ${context.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${context.blockerDetail}\n\n` +
+        `Rules:\n` +
+        `- Confirm the working tree is on the PR branch at HEAD ${context.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.` +
+        PRE_COMMIT_GATE_STEP,
+      { label, phase: 'Converge', schema: EDIT_SCHEMA, agentType: 'clean-coder', resume: agentId },
+    )
+  }
   const objection = context.objection || VERIFY_OBJECTION_FALLBACK
   const attempt = context.attempt || 1
   return convergeAgent(
@@ -197,77 +204,41 @@ function resumeFixerAgent(agentId, task, context) {
 }
 
 /**
- * Joined fixer recovery loop: resume the fixer agent for verify+commit, extract the verdict,
- * and recover when the verdict fails or the commit is blocked.
+ * Joined fixer recovery loop: a separate verifier agent grades the working-tree
+ * fixes while the fixer session only recovers and commits, so the verdict that
+ * gates the commit comes from a different session than the one that edits and
+ * pushes — the same editor/verifier separation the repair and conflict paths
+ * use. The verify step routes through verifyWithRecovery (verify on the verifier,
+ * recover on the fixer); the commit step routes through commitWithRecovery
+ * (commit and commit-recover on the fixer, re-verify on the verifier). A failed
+ * verdict returns the unchanged HEAD so the round reads as not-progressed.
  * @param {string} fixerAgentId the fixer agent id from spawnFixerAgent
+ * @param {string} verifierId the verifier agent id from spawnVerifierAgent
  * @param {string} head PR HEAD SHA
  * @param {Array<object>} findings the findings to fix
  * @param {string} sourceLabel short description of where the findings came from
  * @returns {Promise<object>} FIX_SCHEMA result
  */
-async function fixerWithRecovery(fixerAgentId, head, findings, sourceLabel) {
-  const verifyTranscript = await resumeFixerAgent(fixerAgentId, 'verify-commit', { head, findings, sourceLabel })
-  const verdict = extractVerdict(verifyTranscript)
-  if (verdict && verdict.all_pass === true) {
-    const commitResult = await resumeFixerAgent(fixerAgentId, 'commit', { head, findings, sourceLabel })
-    if (commitNeedsCodeRecovery(commitResult)) {
-      let attempt = 0
-      let recoveryResult = commitResult
-      while (commitNeedsCodeRecovery(recoveryResult) && attempt < FIX_RECOVERY_MAX_ATTEMPTS) {
-        attempt += 1
-        const recoverEdit = await resumeFixerAgent(fixerAgentId, 'verify-recover', {
-          head, findings, sourceLabel, objection: recoveryResult.blockerDetail, attempt,
-        })
-        if (recoverEdit?.edited !== true) break
-        const reVerify = await resumeFixerAgent(fixerAgentId, 'verify-commit', { head, findings, sourceLabel })
-        const reVerdict = extractVerdict(reVerify)
-        if (!reVerdict || reVerdict.all_pass !== true) break
-        recoveryResult = await resumeFixerAgent(fixerAgentId, 'commit', { head, findings, sourceLabel })
-      }
-      return recoveryResult
-    }
-    return commitResult
-  }
-  let attempt = 0
-  let lastTranscript = verifyTranscript
-  while ((!verdict || verdict.all_pass !== true) && attempt < FIX_RECOVERY_MAX_ATTEMPTS) {
-    attempt += 1
-    const objection = extractVerifyObjection(lastTranscript)
-    const recoverEdit = await resumeFixerAgent(fixerAgentId, 'verify-recover', {
-      head, findings, sourceLabel, objection, attempt,
-    })
-    if (recoverEdit?.edited !== true) break
-    lastTranscript = await resumeFixerAgent(fixerAgentId, 'verify-commit', { head, findings, sourceLabel })
-    const freshVerdict = extractVerdict(lastTranscript)
-    if (freshVerdict && freshVerdict.all_pass === true) {
-      const commitResult = await resumeFixerAgent(fixerAgentId, 'commit', { head, findings, sourceLabel })
-      if (commitNeedsCodeRecovery(commitResult)) {
-        let commitAttempt = 0
-        let commitRecovery = commitResult
-        while (commitNeedsCodeRecovery(commitRecovery) && commitAttempt < FIX_RECOVERY_MAX_ATTEMPTS) {
-          commitAttempt += 1
-          const commitEdit = await resumeFixerAgent(fixerAgentId, 'verify-recover', {
-            head, findings, sourceLabel, objection: commitRecovery.blockerDetail, attempt: commitAttempt,
-          })
-          if (commitEdit?.edited !== true) break
-          const reVerify2 = await resumeFixerAgent(fixerAgentId, 'verify-commit', { head, findings, sourceLabel })
-          const reVerdict2 = extractVerdict(reVerify2)
-          if (!reVerdict2 || reVerdict2.all_pass !== true) break
-          commitRecovery = await resumeFixerAgent(fixerAgentId, 'commit', { head, findings, sourceLabel })
-        }
-        return commitRecovery
-      }
-      return commitResult
+async function fixerWithRecovery(fixerAgentId, verifierId, head, findings, sourceLabel) {
+  const verifyTranscript = await verifyWithRecovery({
+    runVerify: () => resumeVerifierAgent(verifierId, 'fix-verify', { head, findings, sourceLabel }),
+    runRecoverEdit: (objection, attempt) => resumeFixerAgent(fixerAgentId, 'verify-recover', { head, findings, sourceLabel, objection, attempt }),
+  })
+  if (!verdictPassed(verifyTranscript)) {
+    return {
+      newSha: head,
+      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 {
-    newSha: head,
-    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 commitWithRecovery({
+    runCommit: () => resumeFixerAgent(fixerAgentId, 'commit', { head, findings, sourceLabel }),
+    runVerify: () => resumeVerifierAgent(verifierId, 'fix-verify', { head, findings, sourceLabel }),
+    runRecoverEdit: (detail, attempt) => resumeFixerAgent(fixerAgentId, 'commit-recover', { head, findings, sourceLabel, blockerDetail: detail, attempt }),
+  })
 }
 
 /**
@@ -424,7 +395,7 @@ function resumeCodeEditorAgent(agentId, task, context) {
 
 /**
  * Spawn the verifier code-verifier agent once per converge round, establishing
- * its role so each later resume (repair-verify, hardening-verify) continues the
+ * its role so each later resume (fix-verify, repair-verify, hardening-verify) continues the
  * same session. The spawn makes no edits — verification only. Returns the runtime
  * agent id so the resume calls target the live session; a runtime without resume
  * support returns no agent id, and each resume falls back to a fresh spawn.
@@ -447,6 +418,18 @@ async function spawnVerifierAgent() {
  */
 function resumeVerifierAgent(agentId, task, context) {
   const label = `verifier:${task}`
+  if (task === 'fix-verify') {
+    const findingsBlock = renderFindingsBlock(context.findings)
+    return convergeAgent(
+      `You are the VERIFY step for ${context.findings.length} finding(s) (${context.sourceLabel}) on ${prCoordinates}, HEAD ${context.head}. The edit step left fixes in the working tree, uncommitted. Do NO edits of any kind — verification only; any edit invalidates the verdict you are about to emit.\n\n` +
+        `Findings the working-tree fixes must address:\n${findingsBlock}\n\n` +
+        `Steps:\n` +
+        `1. Resolve the worktree repo root for running tests: REPO=$(git rev-parse --show-toplevel).\n` +
+        `2. Verify the uncommitted working-tree changes resolve every finding above: run the relevant tests and the named gates against the working tree. Read the diff (git diff) and confirm each finding is fixed test-first per CODE_RULES.\n` +
+        `3. ${buildVerdictFenceSteps(input.owner, input.repo, input.prNumber)}`,
+      { label, phase: 'Converge', agentType: 'code-verifier', resume: agentId },
+    )
+  }
   if (task === 'repair-verify') {
     const failureBlock = context.failures.length
       ? context.failures.map((each, position) => `${position + 1}. ${each}`).join('\n')
@@ -929,15 +912,6 @@ function parseLastVerdictFence(transcript) {
   }
 }
 
-/**
- * Extract the full verdict object from a transcript carrying a verdict fence.
- * @param {string|null|undefined} transcript the agent transcript text
- * @returns {object|null} the parsed verdict with all_pass, findings, and manifest_sha256, or null
- */
-function extractVerdict(transcript) {
-  return parseLastVerdictFence(transcript)
-}
-
 /**
  * Decide whether a workflow code-verifier transcript ended in a passing
  * verdict. Reads the LAST ```verdict ...``` fenced JSON block via the shared
@@ -1055,7 +1029,7 @@ function commitNeedsCodeRecovery(commitResult) {
  * resolve-head agent or a malformed result yields a falsy SHA; spawning lenses
  * against it interpolates the literal string 'HEAD undefined' into their prompts
  * and produces a spurious clean verdict on a non-existent commit.
- * @param {string|null|undefined} resolvedHead the SHA from resolveHead()
+ * @param {string|null|undefined} resolvedHead the SHA from the git-utility agent resume for 'resolve-head'
  * @returns {boolean} true only when the SHA is a non-empty string
  */
 function isResolvedHeadUsable(resolvedHead) {
@@ -1068,7 +1042,7 @@ function isResolvedHeadUsable(resolvedHead) {
  * not-conflicting so the run proceeds straight to the bug checks rather than
  * force-pushing a rebase on a verdict that does not exist — a transient check
  * failure must never trigger a destructive rebase.
- * @param {object|null|undefined} mergeState the checkMergeConflicts result
+ * @param {object|null|undefined} mergeState the git-utility agent resume result for 'check-merge-conflicts'
  * @returns {boolean} true only when the check reported conflicting:true
  */
 function isMergeConflicting(mergeState) {
@@ -1357,14 +1331,16 @@ async function verifyWithRecovery({ runVerify, runRecoverEdit }) {
 }
 
 /**
- * Fix lens: edit (clean-coder, no commit) -> verify (code-verifier emits a
- * verdict fence binding the working tree) -> commit (clean-coder, one commit +
- * push, no edits). Splitting the single editing-and-committing agent lets a
- * workflow code-verifier produce the verdict the verified-commit gate requires,
- * which the SubagentStop minter cannot mint for workflow-spawned agents. When
- * verification fails (or the edit step stalled with no thread to resolve), the
- * commit step is skipped and the unchanged HEAD is returned so the round reads
- * as not-progressed.
+ * Fix lens: edit (clean-coder, no commit) -> verify (a separate code-verifier
+ * emits a verdict fence binding the working tree) -> commit (clean-coder, one
+ * commit + push, no edits). The verifier is a distinct persistent group from the
+ * fixer, so the verdict that gates the commit comes from a different session than
+ * the one that edits and pushes — the same editor/verifier separation the repair
+ * and conflict paths use, and the separation a workflow code-verifier needs to
+ * produce the verdict the verified-commit gate requires, which the SubagentStop
+ * minter cannot mint for workflow-spawned agents. When verification fails (or the
+ * edit step stalled with no thread to resolve), the commit step is skipped and the
+ * unchanged HEAD is returned so the round reads as not-progressed.
  * @param {string} head PR HEAD SHA the findings were raised against
  * @param {Array<object>} findings deduped findings across all lenses
  * @param {string} sourceLabel short description of where the findings came from
@@ -1383,8 +1359,9 @@ async function applyFixes(head, findings, sourceLabel) {
       blockerDetail: '',
     }
   }
-  const fixerAgentId = await spawnFixerAgent(head, findings, sourceLabel, 'verify-commit')
-  return fixerWithRecovery(fixerAgentId, head, findings, sourceLabel)
+  const fixerAgentId = await spawnFixerAgent(head, findings, sourceLabel)
+  const verifierId = await spawnVerifierAgent()
+  return fixerWithRecovery(fixerAgentId, verifierId, head, findings, sourceLabel)
 }
 
 /**
@@ -1561,7 +1538,7 @@ function standardsDeferralNote(findingsCount, hardeningPrOpened) {
  * @param {string} sourceLabel short description of where the findings came from
  * @returns {Promise<object>} `{ hardeningPrOpened }` — true only when the hardening PR was opened this round
  */
-async function spawnStandardsFollowUp(head, findings, sourceLabel, generalId) {
+async function spawnStandardsFollowUp(head, findings, sourceLabel) {
   const codeEditorId = await spawnCodeEditorAgent()
   const editResult = await resumeCodeEditorAgent(codeEditorId, 'standards-edit', { head, findings, sourceLabel })
   if (editResult?.hardeningEdited !== true || !editResult?.hardeningRepoPath) {
@@ -1647,7 +1624,7 @@ while (iterations < CONFIG.maxIterations) {
     if (isStandardsOnlyRound(findings)) {
       log(`Round ${rounds}: ${findings.length} code-standard-only finding(s) — deferring to follow-up PRs and treating the round as passed`)
       const generalId = await spawnGeneralUtilityAgent()
-      const standardsOutcome = await spawnStandardsFollowUp(head, findings, 'converge-round', generalId)
+      const standardsOutcome = await spawnStandardsFollowUp(head, findings, 'converge-round')
       standardsNote = standardsDeferralNote(findings.length, standardsOutcome?.hardeningPrOpened === true)
       const auditResult = await resumeGeneralUtilityAgent(generalId, 'post-clean-audit', { head })
       if (!auditResult?.posted) {
@@ -1704,8 +1681,7 @@ while (iterations < CONFIG.maxIterations) {
     if (copilotOutcome.kind === 'fix') {
       if (isStandardsOnlyRound(copilotOutcome.findings)) {
         log(`Copilot raised ${copilotOutcome.findings.length} code-standard-only finding(s) — deferring to follow-up PRs and treating the gate as passed`)
-        const copilotGeneralId = await spawnGeneralUtilityAgent()
-        const standardsOutcome = await spawnStandardsFollowUp(head, copilotOutcome.findings, 'copilot', copilotGeneralId)
+        const standardsOutcome = await spawnStandardsFollowUp(head, copilotOutcome.findings, 'copilot')
         standardsNote = standardsDeferralNote(copilotOutcome.findings.length, standardsOutcome?.hardeningPrOpened === true)
         copilotDown = false
         copilotNote = null