claude-dev-env 1.64.3 → 1.65.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.64.3",
+    "version": "1.65.0",
     "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,178 @@
+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/);
+});
+
+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',
+  );
+});
+
+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 = 4
+
+/**
+ * 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 +
@@ -791,7 +869,11 @@ async function applyFixes(head, findings, sourceLabel) {
       summary: `verify step did not pass the working-tree fixes for ${findings.length} finding(s) — not committing`,
     }
   }
-  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 +1060,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' },
   )
 }
@@ -1017,7 +1102,12 @@ async function repairConvergence(head, failures) {
       summary: `repair verify step did not pass the working-tree repair on HEAD ${head} — not pushing`,
     }
   }
-  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),
+  })
 }
 
 /**