claude-dev-env 2.3.0 → 2.5.0

package/skills/autoconverge/reference/convergence.md

@@ -106,6 +106,18 @@ follow-up issue listing the findings, opens a draft environment-hardening PR
 (hooks/rules that block those violation classes at Write/Edit time), resolves
 any bot threads with a deferral note, and reports the deferral in
 `standardsNote`. The hardening PRs land in the run result's `deferredPrs` list.
+Standards-only deferral still takes precedence when every finding is category
+`code-standard`.
+
+When the already-deduped findings for a phase are all severity P2 (and not
+standards-only), the phase still applies the fixes once. If the fix does **not**
+move HEAD (for example `resolvedWithoutCommit`), the phase treats that HEAD as
+clean and advances forward. If the fix **does** move HEAD, the run re-enters
+CONVERGE on the fixed SHA so HEAD-bound CLEAN/review stamps rebuild before
+FINALIZE — those stamps are SHA-specific. The three CONVERGE reading lenses stay
+parallel; the P2-only decision is a routing branch on the deduped set after
+`resolveRoundOutcome` / gate classification. Mixed P0/P1 findings keep the
+existing fix + re-converge path.
 
 **BUGBOT** gate (terminal external confirmation):
 
@@ -115,7 +127,10 @@ any bot threads with a deferral note, and reports the deferral in
   to the Copilot gate with `bugbotDown` set.
 - Otherwise drive Cursor Bugbot to a verdict on HEAD (trigger and poll its CI
   check run when needed).
-- Bugbot findings → fix them and return to CONVERGE on the new HEAD.
+- Bugbot findings that are not standards-only and not P2-only → fix them and
+  return to CONVERGE on the new HEAD.
+- Bugbot P2-only findings → fix once; advance to Copilot only when HEAD is
+  unchanged, otherwise re-converge on the fixed HEAD.
 - Bugbot clean or approved → move to the Copilot gate.
 - Bugbot down after the poll cap → move to the Copilot gate with `bugbotDown` set.
 
@@ -123,7 +138,10 @@ any bot threads with a deferral note, and reports the deferral in
 
 - Request a Copilot review on HEAD (skipping a duplicate request), then poll up
   to the configured cap, 360 seconds apart.
-- Copilot findings → fix them and return to CONVERGE on the new HEAD.
+- Copilot findings that are not standards-only and not P2-only → fix them and
+  return to CONVERGE on the new HEAD.
+- Copilot P2-only findings → fix once; advance to Codex only when HEAD is
+  unchanged, otherwise re-converge on the fixed HEAD.
 - Copilot clean or approved → move to the Codex gate.
 - Copilot down or out of quota (an out-of-usage notice, or no review after the
   configured cap) → log a notice and move to the Codex gate with the Copilot gate
@@ -135,11 +153,15 @@ any bot threads with a deferral note, and reports the deferral in
   the weekly usage probe via `is_codex_review_required` (shared threshold
   constant — no inline percent), and the wrapper's `codex_down` class.
 - Opt-out token or `codex_down` → set `codexDown`, no stamp, move to the
-  convergence check with `--codex-down`.
+  convergence check with `--codex-down`. A `codex_down` classification also
+  records a `codexNote` so the skip stays visible in the final report.
 - Usage at/below threshold or null → skip with no stamp; the machine checklist
   applies the same rule.
 - Above threshold → run the codex-review wrapper against the PR base branch.
-  Non–code-standard findings → fix and return to CONVERGE.
+  Non–code-standard, non–P2-only findings → fix and return to CONVERGE.
+  P2-only findings → fix once; when HEAD is unchanged, stamp `codexCleanAt` and
+  move to the convergence check (no re-converge), otherwise re-converge on the
+  fixed HEAD.
   Standards-only findings → defer a follow-up, stamp `codexCleanAt`, and move to the
   convergence check (no fix push).
   Clean → stamp `codexCleanAt` and pass `--codex-clean-at` into the convergence check.

package/skills/autoconverge/reference/multi-pr.md

@@ -72,6 +72,7 @@ Workflow({
   scriptPath: "<this skill dir>/workflow/converge_multi.mjs",
   args: {
     convergeScriptPath: "<this skill dir>/workflow/converge.mjs",
+    homeDirectory: "<HOME>",
     prs: [
       { owner: "<O>", repo: "<R>", prNumber: <N1>, repoPath: "<abs worktree 1>", bugbotDisabled: false, copilotDisabled: false },
       { owner: "<O>", repo: "<R>", prNumber: <N2>, repoPath: "<abs worktree 2>", bugbotDisabled: false, copilotDisabled: false }
@@ -82,7 +83,11 @@ Workflow({
 
 `convergeScriptPath` is the absolute path to `workflow/converge.mjs` in this same
 skill directory; each `repoPath` is the absolute path of the worktree that PR is
-checked out in. The workflow runs in the background and notifies the session on
+checked out in. `homeDirectory` is the absolute path to the directory that holds
+`.claude` (resolve it once from `$HOME`, or `$env:USERPROFILE` on Windows, with
+forward slashes); the fan-out forwards it to every child run, which needs it to
+build the codex-review scripts path because the workflow sandbox has no access to
+environment variables. The workflow runs in the background and notifies the session on
 completion; watch live progress with `/workflows`, where each PR's child run
 appears under its own group.
 

package/skills/autoconverge/reference/stop-conditions.md

@@ -88,16 +88,22 @@ Each reviewer-down condition below skips its own convergence-check gate. The fla
   `--copilot-down` (the Copilot review gate and the pending-requested-reviews
   gate bypassed), then mark-ready. `copilotNote` records the bypass for the
   final report.
-- **Terminal Codex gate skipped or down** — the conditional-required Codex gate
-  runs after Bugbot and Copilot. When `CLAUDE_REVIEWS_DISABLED` lists `codex`
-  (`reviews_disabled.py --reviewer codex` exit 0), the gate sets `codexDown` and
-  advances with no review. When the weekly usage probe reports `percent_left`
-  null or at/below the shared threshold (`is_codex_review_required` false), the
-  gate skips without a stamp; the convergence check applies the same rule. When
-  the wrapper classifies `codex_down`, the gate sets `codexDown` and advances.
-  A clean required run stamps `codexCleanAt` for `--codex-clean-at`. Non-code-standard
-  findings re-enter CONVERGE through the existing fix path. Standards-only findings
-  defer a follow-up, stamp `codexCleanAt`, and advance to FINALIZE (no fix push).
+- **Terminal Codex gate skipped (opt-out, usage, or `codex_down`)** — the
+  conditional-required Codex gate runs after Bugbot and Copilot. When
+  `CLAUDE_REVIEWS_DISABLED` lists `codex` (`reviews_disabled.py --reviewer codex`
+  exit 0), the gate sets `codexDown` and advances with no review. When the weekly
+  usage probe reports `percent_left` null or at/below the shared threshold
+  (`is_codex_review_required` false), the gate skips without a stamp; the
+  convergence check applies the same rule. When the codex-review wrapper
+  classifies `codex_down` — a Codex CLI error, or a review that ran past its
+  `CONFIG.codexReviewTimeoutSeconds` budget — the gate skips the same way: it sets
+  `codexDown`, records a `codexNote` so the skip stays visible in the final
+  report, clears `codexCleanAt`, and advances to `FINALIZE` (mark-ready with the
+  gate bypassed) so a Codex outage does not block convergence; Codex runs again on
+  the next convergence. A clean required run stamps `codexCleanAt` for
+  `--codex-clean-at`. Non-code-standard findings re-enter `CONVERGE` through the
+  existing fix path. Standards-only findings defer a follow-up, stamp
+  `codexCleanAt`, and advance to `FINALIZE` (no fix push).
 - **A lens agent dies** — when one parallel reading lens returns null (a terminal
   agent failure), the round proceeds on the surviving lenses. A real defect it
   would have caught surfaces in a later round or at the convergence check. A dead

package/skills/autoconverge/workflow/CLAUDE.md

@@ -18,6 +18,7 @@ Workflow scripts and report utilities for the `autoconverge` skill.
 | `converge.precatch.test.mjs` | Tests the pre-catch stage: static-sweep ordering and gate coverage, the adversarial second pass, the self-review lens, the terminal Bugbot gate, the read-only/edit preamble split, and the commit-recovery cap. |
 | `converge.fix-progress.test.mjs` | Tests fix-progress tracking across rounds. |
 | `converge.fix-recovery.test.mjs` | Tests recovery when a fix commit fails. |
+| `converge.p2-advance.test.mjs` | Tests P2-only fix-then-advance helpers and phase routing. |
 | `converge.run-input.test.mjs` | Tests workflow input validation. |
 | `test_aggregate_runs.py` | Tests for `aggregate_runs.py`. |
 | `test_convergence_summary.py` | Tests for `convergence_summary.py`. |

package/skills/autoconverge/workflow/converge.clean-audit.test.mjs

@@ -215,7 +215,7 @@ test('every no-lens-reviewed round registers one shared counter and every lens-r
   const registerSites = loopBody.match(/registerNoLensRound\(/g) || [];
   assert.equal(registerSites.length, 3, 'expected the preflight-no-SHA, all-lenses-dead, and no-lens-ran rounds to register');
   const resetSites = loopBody.match(/resetNoLensRounds\(\)/g) || [];
-  assert.equal(resetSites.length, 5, 'expected a reset on the static-sweep, standards, findings, not-clean, and posted lens-ran rounds');
+  assert.equal(resetSites.length, 6, 'expected a reset on the static-sweep, standards, P2-only, findings, not-clean, and posted lens-ran rounds');
   const deadBranch = convergeSource.slice(
     convergeSource.indexOf('if (roundOutcome.allLensesDead) {'),
     convergeSource.indexOf('const findings = roundOutcome.findings'),
@@ -533,7 +533,7 @@ test('CLEAN_AUDIT_SCHEMA requires posted, reviewUrl, and reason', () => {
 test('the standards-only call site records a clean-audit bypass and continues to BUGBOT when the post does not land', () => {
   const branch = convergeSource.slice(
     convergeSource.indexOf('if (isStandardsOnlyRound(findings)) {'),
-    convergeSource.indexOf('if (findings.length > 0) {'),
+    convergeSource.indexOf('if (isP2OnlyFindings(findings)) {'),
   );
   assert.match(branch, /runGeneralUtilityTask\(.*'post-clean-audit'/);
   assert.match(branch, /cleanAuditNote = resolveCleanAuditNote\(auditResult, head, rounds\)/);
@@ -545,7 +545,7 @@ test('the standards-only call site records a clean-audit bypass and continues to
 test('the standards-only call site relays lens provenance, the deferred standards findings, and the deferral filing state', () => {
   const branch = convergeSource.slice(
     convergeSource.indexOf('if (isStandardsOnlyRound(findings)) {'),
-    convergeSource.indexOf('if (findings.length > 0) {'),
+    convergeSource.indexOf('if (isP2OnlyFindings(findings)) {'),
   );
   assert.match(branch, /const namedLenses = nameLensResults\(lenses\)/);
   assert.match(branch, /lensResults: namedLenses/);
@@ -655,7 +655,7 @@ test('the workflow declares cleanAuditNote and assembles it into every result vi
   assert.match(convergeSource, /let cleanAuditNote = null/);
   assert.match(
     convergeSource,
-    /const assembleResult = \(outcomeFields\) => \(\{\n\s*\.\.\.outcomeFields,\n\s*standardsNote,\n\s*copilotNote,\n\s*cleanAuditNote,\n\s*reuseNote,\n\s*deferredPrs,\n\s*\}\)/,
+    /const assembleResult = \(outcomeFields\) => \(\{\n\s*\.\.\.outcomeFields,\n\s*standardsNote,\n\s*copilotNote,\n\s*codexNote,\n\s*cleanAuditNote,\n\s*reuseNote,\n\s*deferredPrs,\n\s*\}\)/,
   );
   const assembleCalls = convergeSource.match(/return assembleResult\(/g) || [];
   assert.ok(

package/skills/autoconverge/workflow/converge.codex-gate.test.mjs

@@ -178,7 +178,118 @@ test('the Codex gate prompt runs the review wrapper against the PR base branch',
   assert.match(codexPrompt, /parse_codex_findings/, 'expected findings to come from the shared parser');
 });
 
-test('the CODEX phase stamps codexCleanAt on clean and clears it on skip/down', () => {
+test('the Codex gate prompt passes an explicit generous timeout so a slow-but-healthy review is not cut short', () => {
+  const codexPrompt = functionBody('runCodexGate');
+  assert.match(
+    codexPrompt,
+    /timeout_seconds=\$\{CONFIG\.codexReviewTimeoutSeconds\}/,
+    'expected the driver to pass CONFIG.codexReviewTimeoutSeconds, overriding the too-small wrapper default',
+  );
+});
+
+test('CONFIG.codexReviewTimeoutSeconds exceeds the observed real Codex runtime', () => {
+  const match = convergeSource.match(/codexReviewTimeoutSeconds:\s*(\d+)/);
+  assert.notEqual(match, null, 'expected CONFIG.codexReviewTimeoutSeconds to be defined');
+  const budgetSeconds = Number(match[1]);
+  assert.ok(
+    budgetSeconds >= 900,
+    `expected a budget comfortably above the ~683s measured Codex runtime, got ${budgetSeconds}`,
+  );
+});
+
+test('the Codex gate prompt runs the review in the background rather than the default foreground timeout', () => {
+  const codexPrompt = functionBody('runCodexGate');
+  assert.match(
+    codexPrompt,
+    /run_in_background/i,
+    'expected the review driver to run in the background — the foreground tool timeout caps below the review runtime and would kill a healthy review',
+  );
+  assert.match(
+    codexPrompt,
+    /result file/i,
+    'expected the driver to persist its outcome to a result file the agent reads once the background run finishes',
+  );
+});
+
+test('the Codex gate prompt waits for the background review inside the same turn with a bounded Monitor loop', () => {
+  const codexPrompt = functionBody('runCodexGate');
+  assert.match(codexPrompt, /Monitor tool/, 'expected a same-turn Monitor wait for the background review');
+  assert.match(codexPrompt, /until-loop/, 'expected a bounded until-loop that re-checks the result file');
+  assert.match(codexPrompt, /codexReviewPollIntervalSeconds/, 'expected a named poll interval in the wait protocol');
+  assert.match(codexPrompt, /codexReviewMaxPolls/, 'expected a named attempt budget in the wait protocol');
+  assert.match(
+    codexPrompt,
+    /Do NOT end this turn/i,
+    'expected an explicit instruction against ending the schema-bearing turn to await the background run',
+  );
+});
+
+test('the Codex background-review poll budget covers the review timeout', () => {
+  const intervalMatch = convergeSource.match(/codexReviewPollIntervalSeconds:\s*(\d+)/);
+  const pollsMatch = convergeSource.match(/codexReviewMaxPolls:\s*(\d+)/);
+  const timeoutMatch = convergeSource.match(/codexReviewTimeoutSeconds:\s*(\d+)/);
+  assert.notEqual(intervalMatch, null, 'expected codexReviewPollIntervalSeconds in CONFIG');
+  assert.notEqual(pollsMatch, null, 'expected codexReviewMaxPolls in CONFIG');
+  assert.notEqual(timeoutMatch, null, 'expected codexReviewTimeoutSeconds in CONFIG');
+  const intervalSeconds = Number(intervalMatch[1]);
+  const maxPolls = Number(pollsMatch[1]);
+  const timeoutSeconds = Number(timeoutMatch[1]);
+  assert.ok(
+    intervalSeconds * maxPolls >= timeoutSeconds,
+    `expected the poll budget ${intervalSeconds * maxPolls}s to cover the ${timeoutSeconds}s review timeout`,
+  );
+});
+
+test('the Codex gate prompt returns codex_down when the background poll budget is spent', () => {
+  const codexPrompt = functionBody('runCodexGate');
+  assert.match(
+    codexPrompt,
+    /full poll budget is spent with no result file[\s\S]*?down:true/,
+    'expected a spent-budget branch that returns the codex_down schema shape',
+  );
+});
+
+test('meta Codex gate phase describes codex_down as a non-blocking skip that logs a note', () => {
+  const phaseStart = convergeSource.indexOf("title: 'Codex gate'");
+  const phaseEnd = convergeSource.indexOf("title: 'Finalize'");
+  assert.notEqual(phaseStart, -1, 'expected a Codex gate phase in meta');
+  const codexPhaseDetail = convergeSource.slice(phaseStart, phaseEnd);
+  assert.match(codexPhaseDetail, /codex_down/, 'expected the phase detail to name codex_down');
+  assert.match(
+    codexPhaseDetail,
+    /codex_down, the gate skips without blocking/,
+    'expected codex_down to be described as a non-blocking skip',
+  );
+  assert.match(
+    codexPhaseDetail,
+    /logged as a note/,
+    'expected the codex_down skip to be logged as a note so the bypass stays visible',
+  );
+  assert.doesNotMatch(
+    codexPhaseDetail,
+    /holds the PR as a draft with a codex-down blocker/,
+    'codex_down must not be described as holding the PR draft with a blocker',
+  );
+});
+
+test('CODEX_SCHEMA down.description describes codex_down as a skipped, bypassed gate recorded as a note', () => {
+  const schemaStart = convergeSource.indexOf('const CODEX_SCHEMA =');
+  const schemaEnd = convergeSource.indexOf('const COPILOT_VERIFY_VERDICTS =');
+  assert.notEqual(schemaStart, -1, 'expected CODEX_SCHEMA to exist');
+  const schemaSource = convergeSource.slice(schemaStart, schemaEnd);
+  const downLineStart = schemaSource.indexOf('down: {');
+  const downLine = schemaSource.slice(downLineStart, schemaSource.indexOf('\n', downLineStart));
+  assert.match(downLine, /codex_down/, 'expected the down description to name codex_down');
+  assert.match(downLine, /skipped and bypassed/, 'expected codex_down to be described as a skipped, bypassed gate');
+  assert.match(downLine, /recorded as a note/, 'expected codex_down to be recorded as a note');
+  assert.doesNotMatch(
+    downLine,
+    /holds the PR as a draft with a codex-down blocker/,
+    'the down description must not claim codex_down holds the PR draft as a blocker',
+  );
+});
+
+test('the CODEX phase stamps codexCleanAt on clean and clears it on an opt-out, usage, or down skip', () => {
   const codexPhaseStart = convergeSource.indexOf("if (phase === 'CODEX') {");
   const finalizePhaseStart = convergeSource.indexOf("if (phase === 'FINALIZE') {", codexPhaseStart);
   assert.notEqual(codexPhaseStart, -1, 'expected a CODEX phase block');
@@ -192,6 +303,36 @@ test('the CODEX phase stamps codexCleanAt on clean and clears it on skip/down',
   assert.match(codexPhase, /kind === 'down'[\s\S]*codexDown = true[\s\S]*codexCleanAt = null/);
 });
 
+test('the CODEX phase skips a genuine codex_down gracefully, recording a note and advancing to mark-ready', () => {
+  const codexPhaseStart = convergeSource.indexOf("if (phase === 'CODEX') {");
+  const finalizePhaseStart = convergeSource.indexOf("if (phase === 'FINALIZE') {", codexPhaseStart);
+  const codexPhase = convergeSource.slice(codexPhaseStart, finalizePhaseStart);
+  const downBranchStart = codexPhase.indexOf("codexOutcome.kind === 'down'");
+  const downBranchEnd = codexPhase.indexOf("codexOutcome.kind === 'fix'", downBranchStart);
+  assert.notEqual(downBranchStart, -1, 'expected a codex_down branch in the CODEX phase');
+  assert.notEqual(downBranchEnd, -1, 'expected a fix branch after the down branch');
+  const downBranch = codexPhase.slice(downBranchStart, downBranchEnd);
+  assert.match(downBranch, /codexNote =/, 'a genuine codex_down records a transparent note');
+  assert.match(downBranch, /codexDown = true/, 'the down branch sets the bypass flag so mark-ready skips the required Codex gate');
+  assert.match(downBranch, /codexCleanAt = null/, 'the down branch clears any codex-clean stamp');
+  assert.match(
+    downBranch,
+    /phase = 'FINALIZE'/,
+    'a genuine codex_down advances to mark-ready with the gate bypassed rather than blocking the run',
+  );
+  assert.doesNotMatch(downBranch, /blocker =/, 'a genuine codex_down must not record a blocker');
+  assert.doesNotMatch(downBranch, /\bbreak\b/, 'the down branch continues rather than breaking the loop');
+});
+
+test('the workflow return object includes codexNote so the final report surfaces the Codex skip', () => {
+  const assembleStart = convergeSource.indexOf('const assembleResult =');
+  assert.notEqual(assembleStart, -1, 'expected assembleResult to exist');
+  const assembleEnd = convergeSource.indexOf('})', assembleStart);
+  assert.notEqual(assembleEnd, -1, 'expected the assembleResult object to close');
+  const assembleSource = convergeSource.slice(assembleStart, assembleEnd);
+  assert.match(assembleSource, /codexNote,/, 'expected codexNote among the returned notes');
+});
+
 test('the CODEX phase routes findings through applyFixes and re-enters CONVERGE', () => {
   const codexPhaseStart = convergeSource.indexOf("if (phase === 'CODEX') {");
   const finalizePhaseStart = convergeSource.indexOf("if (phase === 'FINALIZE') {", codexPhaseStart);
@@ -267,8 +408,8 @@ test('runConvergenceCheck tells the finalize agent to persist codex_clean_at for
 test('CONFIG expands home for the codex-review scripts directory', () => {
   assert.match(
     convergeSource,
-    /const homeDirectory = \(process\.env\.HOME \|\| process\.env\.USERPROFILE/,
-    'expected home to be resolved from process.env before CONFIG path use',
+    /const homeDirectory = \([\s\S]*?homeDirectoryPayload\.homeDirectory/,
+    'expected home to be sourced from the workflow args payload (the sandbox exposes no process)',
   );
   assert.match(
     convergeSource,
@@ -282,6 +423,25 @@ test('CONFIG expands home for the codex-review scripts directory', () => {
   );
 });
 
+test('no process global is read unguarded (the workflow sandbox exposes no process)', () => {
+  const unguardedProcessLines = convergeSource
+    .split('\n')
+    .filter((sourceLine) => sourceLine.includes('process.') && !sourceLine.includes('typeof process'));
+  assert.deepEqual(
+    unguardedProcessLines,
+    [],
+    'every process.* read must sit on a line guarded by typeof process; the Bun workflow sandbox has no process global',
+  );
+});
+
+test('the home directory is sourced from the workflow args payload', () => {
+  assert.match(
+    convergeSource,
+    /const homeDirectoryPayload = normalizeRunInput\(args\)/,
+    'expected homeDirectory to read args (the only channel into the process-less sandbox), parsed via normalizeRunInput',
+  );
+});
+
 test('meta lists the Codex gate phase between Copilot and Finalize', () => {
   const copilotPhaseIndex = convergeSource.indexOf("title: 'Copilot gate'");
   const codexPhaseIndex = convergeSource.indexOf("title: 'Codex gate'");
@@ -294,6 +454,18 @@ test('SKILL.md names Codex among the terminal confirmation gates', () => {
   assert.match(skillSource, /Codex/i);
 });
 
+test('SKILL.md documents codexNote in the workflow return shape', () => {
+  const returnShapeMatch = skillSource.match(/`\{ converged, rounds, finalSha, blocker,[^`]*\}`/);
+  assert.ok(returnShapeMatch, 'expected the documented return shape literal in SKILL.md');
+  assert.match(returnShapeMatch[0], /codexNote/);
+});
+
+test('SKILL.md final-report template surfaces the codexNote so a bypassed Codex gate stays visible', () => {
+  const reportBlockMatch = skillSource.match(/\/autoconverge exit:[\s\S]*?```/);
+  assert.ok(reportBlockMatch, 'expected the final-report template block in SKILL.md');
+  assert.match(reportBlockMatch[0], /Codex: <codexNote>/);
+});
+
 test('stop-conditions.md documents the Codex gate skip paths as non-blockers', () => {
   assert.match(stopConditionsSource, /Codex/i);
   assert.match(stopConditionsSource, /codex/i);