claude-dev-env 1.81.0 → 1.83.0

package/rules/workflow-substitution-slots.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "**/*.workflow.js"
+---
+
 # Workflow Substitution Slot Rule
 
 In a `.workflow.js` agent-prompt template, every per-call or per-iteration value an agent must fill in is marked with the angle-bracket convention — `<plate.svg>`, `<object.svg>`, `<glow_hex>`, `cand_<i>`. A bare token such as `cand_i` reads as a fixed literal, so an agent can create one literal directory named `cand_i` and overwrite it across every iteration of a loop, collapsing an N-iteration gate into a single run.

package/skills/CLAUDE.md

@@ -42,7 +42,7 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `research-mode` — activates anti-hallucination discipline for a session
 - `recall` — retrieves facts from memory files
 - `remember` — saves a decision, gotcha, or architectural choice to the Obsidian vault
-- `everything-search` — file-system search via the Everything MCP tool
+- `everything-search` — file-system search via the Everything `es.exe` CLI
 - `caveman` — trims noise from a draft artifact
 
 **Session and workflow management**

package/skills/autoconverge/SKILL.md

@@ -131,7 +131,12 @@ no agent spawned. The workflow runs in the background and notifies this session
 on completion. Watch live progress with `/workflows`.
 
 The workflow returns
-`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, reuseNote }`.
+`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, reuseNote, deferredPrs }`.
+`deferredPrs` is the list of draft environment-hardening PRs the standards-deferral
+path opened this run, each as `{ owner, repo, prNumber, copilotDisabled, bugbotDisabled }`.
+The two flags carry this run's Copilot and Bugbot availability, so the next generation
+skips a reviewer that is down or out of quota without re-probing. This list is the seed the
+[self-closing loop](#self-closing-loop-converge-the-deferred-prs) converges next.
 
 ## Budget-aware round boundaries
 
@@ -387,10 +392,13 @@ checked out in. The workflow runs in the background and notifies this session on
 completion; watch live progress with `/workflows`, where each PR's child run
 appears under its own group.
 
-The workflow returns `{ converged, prCount, convergedCount, results, blocker }`,
-where `results` is one record per PR carrying
-`{ owner, repo, prNumber, converged, rounds, finalSha, blocker }`. The top-level
-`converged` is true only when every PR converged.
+The workflow returns
+`{ converged, prCount, convergedCount, results, allDeferredPrs, blocker }`, where
+`results` is one record per PR carrying
+`{ owner, repo, prNumber, converged, rounds, finalSha, blocker, deferredPrs }`.
+Each record's `deferredPrs` is that PR's own list of draft hardening PRs, and
+`allDeferredPrs` is every record's `deferredPrs` flattened into one list. The
+top-level `converged` is true only when every PR converged.
 
 ### Multi-PR teardown (on workflow completion)
 
@@ -403,6 +411,89 @@ permissions once per repository after every PR's teardown. Then print one summar
 report — a line per PR as
 `#<prNumber>: <converged | blocked> — rounds <N>, final <finalSha>[, blocker <blocker>]`.
 
+## Self-closing loop: converge the deferred PRs
+
+Every run leaves work behind. When a round holds only code-standard findings, the
+standards-deferral path opens a draft environment-hardening PR and reports it in
+`deferredPrs`. That PR is itself a draft that needs to reach ready, and its own
+convergence can defer more standard findings, opening more hardening PRs. The
+self-closing loop drives that chain to the ground: after teardown, the
+orchestrator (this session, which launched the workflow) converges the deferred
+PRs, then the PRs their runs defer, and so on until a generation opens none.
+
+This loop runs by default at the end of every autoconverge run — single-PR and
+multi-PR alike. It stops only when a generation's deferred-PR list comes back
+empty.
+
+### Seed the loop
+
+Collect the first generation of deferred PRs from the run that just finished:
+
+- A single-PR run seeds from its `deferredPrs`.
+- A multi-PR run seeds from its `allDeferredPrs`.
+
+When the seed list is empty, the loop is already done — the run deferred nothing,
+so there is nothing to converge. Report that and stop.
+
+### Each generation
+
+Given a non-empty list of deferred PRs `{ owner, repo, prNumber, copilotDisabled, bugbotDisabled }`
+(a generation may span more than one repository — a hardening PR lands in whichever repo owns
+the surface that blocks the deferred class, so `JonEcho/llm-settings` for hooks
+and `jl-cmd/claude-code-config` for rules and skills both appear):
+
+1. **Check out each deferred PR.** Run the
+   [Multi-PR pre-flight](#multi-pr-pre-flight-main-session) once per deferred PR.
+   Because a deferred PR can live in a repo the first run never touched, first
+   find a local checkout of that PR's repo; when none exists, clone it under the
+   session temp dir, then add the per-PR worktree on the PR's head ref. Drop any
+   PR whose strict pre-flight fails rather than stopping the whole generation.
+   Grant project permissions once per repository the generation spans.
+2. **Converge the generation.** Launch `workflow/converge_multi.mjs` with one
+   entry per checked-out deferred PR, exactly as the
+   [multi-PR launch](#launch-the-multi-pr-workflow) describes. Each child run
+   re-checks Copilot and Bugbot availability every round through the workflow's own
+   pre-spawn probe, so a reviewer that is down or out of quota is never spawned in any
+   generation; the `copilotDisabled`/`bugbotDisabled` flags each deferred PR carries
+   seed that check for the first round.
+3. **Tear down.** Run the [multi-PR teardown](#multi-pr-teardown-on-workflow-completion)
+   over the generation's `results`, and revoke project permissions once per
+   repository.
+4. **Take the next seed.** The generation's `allDeferredPrs` is the next
+   generation's seed list. When it is empty, the loop is done.
+
+Repeat from step 1 with each new seed. The depth is unbounded: the loop keeps
+opening generations until one converges every deferred PR without deferring
+anything new.
+
+### Report each generation
+
+Log one line as each generation finishes, so a watcher sees the chain close:
+
+```
+Self-closing generation <k>: <converged>/<total> deferred PR(s) converged, <new> new deferred PR(s) opened
+```
+
+When the loop ends, print a final line naming the generation count and the total
+deferred PRs converged across every generation.
+
+### Conventional titles on deferred PRs
+
+Each hardening PR the loop opens targets a repo whose CI validates the PR title
+as a Conventional Commit. The commit step's prompt directs the agent to title
+the hardening PR as a Conventional Commit — a type prefix, an optional scope,
+then a colon and a short summary — so a deferred PR carries a conforming title
+(`feat(hooks): …`, `chore(rules): …`) before it exists. That prompt is where the
+conforming title is enforced.
+
+The `conventional_pr_title_gate` hook is a best-effort backstop on that title,
+not the guarantee. It blocks a `gh pr create` with a non-conforming `--title`
+only for a repo whose semantic-pull-request workflow leaves the action's
+`types:` input at the default Conventional Commits list. For a repo that pins
+its own explicit `types:` list — which the main target repo does in
+`.github/workflows/pr-check.yml` — the hook fails open and lets the title
+through, and the CI title check on GitHub has the final say.
+
 ## Folder map
 
 - `SKILL.md` — this hub.

package/skills/autoconverge/reference/gotchas.md

@@ -3,11 +3,11 @@
 Hard-won lessons for the autoconverge workflow. Append a bullet each time a run
 fails in a new way.
 
-- **The workflow script cannot sleep.** `Date.now`, `Math.random`, and timers
-  are unavailable in the script body, and a foreground sleep is blocked. Every
-  reviewer wait lives inside an `agent`'s own poll loop — a shell-agnostic `sleep`
-  loop (PowerShell `Start-Sleep` is an allowed alternative), or `gh` check
-  polling. Never try to wait in the script itself.
+- **The workflow script cannot sleep, and neither can an agent's foreground shell.** `Date.now`, `Math.random`, and timers
+  are unavailable in the script body, and a foreground `sleep` / `Start-Sleep` is blocked in the headless harness. Every
+  reviewer wait lives inside an `agent`'s own poll loop, and that loop waits with the Monitor tool inside the same turn —
+  never a foreground sleep, and never backgrounding a wait and ending the turn to await it, which
+  leaves a schema-bearing agent with no `StructuredOutput` call. Never try to wait in the script itself.
 
 - **Workflow agents start blank.** Spawned agents do not inherit CLAUDE.md,
   rules, or this skill's context. Each agent prompt is self-contained: it names

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

@@ -56,6 +56,75 @@ test('a single round-level prefetch step fetches origin/main before the parallel
   );
 });
 
+test('the CONVERGE round spawns a single shared reviewer-availability probe before the parallel lenses', () => {
+  const prefetchCallIndex = convergeSource.indexOf("runGitTask('prefetch-main')");
+  const probeCallIndex = convergeSource.indexOf('reviewerAvailability = await runReviewerAvailabilityCheck()');
+  const parallelLensIndex = convergeSource.indexOf('const lenses = await parallel(');
+  assert.notEqual(probeCallIndex, -1, 'expected the CONVERGE round to spawn the shared reviewer-availability probe');
+  assert.ok(
+    prefetchCallIndex < probeCallIndex && probeCallIndex < parallelLensIndex,
+    'expected the probe to run after the round prefetch and before the parallel lenses spawn',
+  );
+  const probeBody = functionSource('runReviewerAvailabilityCheck');
+  assert.match(probeBody, /reviewer_availability\.py/);
+  assert.match(probeBody, /--reviewer copilot/);
+  assert.match(probeBody, /--reviewer bugbot/);
+  assert.match(probeBody, /schema:\s*REVIEWER_AVAILABILITY_SCHEMA/);
+});
+
+test('the Bugbot lens is not spawned pre-spawn when the shared gate reports Bugbot down', () => {
+  const parallelLensIndex = convergeSource.indexOf('const lenses = await parallel(');
+  assert.notEqual(parallelLensIndex, -1, 'expected the parallel lens block to exist');
+  const isBugbotDownPreSpawnIndex = convergeSource.indexOf('const isBugbotDownPreSpawn = resolveReviewerDown(');
+  assert.notEqual(isBugbotDownPreSpawnIndex, -1, 'expected a pre-spawn Bugbot-down decision computed before the lens array');
+  assert.ok(
+    isBugbotDownPreSpawnIndex < parallelLensIndex,
+    'expected the pre-spawn Bugbot-down decision to be computed before the parallel lens array',
+  );
+  const lensArrayEnd = convergeSource.indexOf('])', parallelLensIndex);
+  const lensArray = convergeSource.slice(parallelLensIndex, lensArrayEnd);
+  assert.match(
+    lensArray,
+    /isBugbotDownPreSpawn \? Promise\.resolve\(\{ sha: head, clean: true, down: true, findings: \[\] \}\) : runBugbotLens\(head\)/,
+    'expected the Bugbot lens slot to substitute a resolved down placeholder instead of spawning runBugbotLens when isBugbotDownPreSpawn is true',
+  );
+});
+
+test('the post-round bugbotDown verdict treats a dead Bugbot lens as down, not fail-open', () => {
+  const parallelLensIndex = convergeSource.indexOf('const lenses = await parallel(');
+  assert.notEqual(parallelLensIndex, -1, 'expected the parallel lens block to exist');
+  const lensArrayEnd = convergeSource.indexOf('])', parallelLensIndex);
+  const bugbotDownAssignIndex = convergeSource.indexOf('bugbotDown = ', lensArrayEnd);
+  assert.notEqual(bugbotDownAssignIndex, -1, 'expected the post-round bugbotDown assignment after the lens array');
+  const bugbotDownAssignLineEnd = convergeSource.indexOf('\n', bugbotDownAssignIndex);
+  const bugbotDownAssignLine = convergeSource.slice(bugbotDownAssignIndex, bugbotDownAssignLineEnd);
+  assert.match(
+    bugbotDownAssignLine,
+    /bugbotDown = lenses\[0\] == null \? true : resolveReviewerDown\(lenses\[0\], input\.bugbotDisabled \|\| false\)/,
+    'expected a dead (null) Bugbot lens result to report bugbotDown:true — resolveReviewerDown alone is fail-open on null, which would wrongly report bugbotDown:false for a lens agent that actually spawned and died, leaving check_convergence.py to look for a bugbot review that was never posted',
+  );
+});
+
+test('both reviewer trigger commands carry the CLAUDE_REVIEWER_GATE=autoconverge sentinel', () => {
+  assert.match(
+    convergeSource,
+    /const REVIEWER_GATE_SENTINEL = 'CLAUDE_REVIEWER_GATE=autoconverge '/,
+    'expected the shared sentinel constant to exist',
+  );
+  const copilotPrompt = lensPromptBody('runCopilotGate');
+  assert.match(
+    copilotPrompt,
+    /\$\{REVIEWER_GATE_SENTINEL\}gh api --method POST[^\n]*requested_reviewers/,
+    'expected the Copilot requested_reviewers trigger to carry the sentinel prefix',
+  );
+  const bugbotPrompt = lensPromptBody('runBugbotLens');
+  assert.match(
+    bugbotPrompt,
+    /\$\{REVIEWER_GATE_SENTINEL\}python "\$\{CONFIG\.sharedScripts\}\/post_fix_reply\.py"[^\n]*--body "bugbot run"/,
+    'expected the Bugbot rerun-comment trigger to carry the sentinel prefix',
+  );
+});
+
 test('bugbot lens preamble does not blanket-instruct passing --owner/--repo to every script', () => {
   const bugbotPrompt = lensPromptBody('runBugbotLens');
   assert.doesNotMatch(
@@ -107,42 +176,28 @@ test('repair-convergence edit step no longer instructs resolving every unresolve
   );
 });
 
-test('bugbot lens delay instructions are shell-agnostic with PowerShell as an alternative', () => {
+test('the bugbot lens waits through the Monitor tool, not a foreground sleep', () => {
   const bugbotPrompt = lensPromptBody('runBugbotLens');
-  assert.match(bugbotPrompt, /sleep 60/, 'expected a shell-agnostic 60-second poll delay');
-  assert.match(bugbotPrompt, /sleep 8/, 'expected a concrete 8-second delay command');
-  assert.match(
-    bugbotPrompt,
-    /Start-Sleep[\s\S]*alternative|alternative[\s\S]*Start-Sleep/i,
-    'expected PowerShell to be named only as an allowed alternative',
-  );
+  assert.match(bugbotPrompt, /Monitor tool/, 'expected the bugbot poll to wait via the Monitor tool');
   assert.doesNotMatch(
     bugbotPrompt,
-    /wait 8 seconds(?!,)/,
-    'the vague "wait 8 seconds" phrasing must carry a concrete command',
+    /sleep 60|sleep 8|Start-Sleep/,
+    'expected no foreground sleep in the bugbot poll delays',
   );
 });
 
-test('copilot gate delay instruction is shell-agnostic with PowerShell as an alternative', () => {
+test('the copilot gate waits through the Monitor tool, not a foreground sleep', () => {
   const copilotPrompt = lensPromptBody('runCopilotGate');
-  assert.match(copilotPrompt, /sleep 360/, 'expected a shell-agnostic 360-second poll delay');
-  assert.match(
-    copilotPrompt,
-    /Start-Sleep[\s\S]*alternative|alternative[\s\S]*Start-Sleep/i,
-    'expected PowerShell to be named only as an allowed alternative',
-  );
+  assert.match(copilotPrompt, /Monitor tool/, 'expected the copilot poll to wait via the Monitor tool');
+  assert.doesNotMatch(copilotPrompt, /sleep 360|Start-Sleep/, 'expected no foreground sleep in the copilot poll delay');
 });
 
-test('gotchas doc describes the reviewer wait as shell-agnostic', () => {
-  assert.match(
-    gotchasSource,
-    /\bsleep\b/i,
-    'expected the wait guidance to name a shell-agnostic sleep',
-  );
+test('gotchas doc describes the reviewer wait as a Monitor poll, not a foreground sleep', () => {
+  assert.match(gotchasSource, /Monitor tool/, 'expected the gotcha to name the Monitor-based reviewer wait');
   assert.doesNotMatch(
     gotchasSource,
-    /a single PowerShell\s*`?Start-Sleep`?\s*loop/i,
-    'PowerShell Start-Sleep must be an alternative, not the sole mechanism',
+    /shell-agnostic/i,
+    'the reviewer wait is a Monitor poll, not a shell-agnostic sleep loop',
   );
 });
 
@@ -390,8 +445,40 @@ test('spawnStandardsFollowUp reports whether a hardening PR opened on every path
   );
   assert.match(
     body,
-    /hardeningPrOpened:\s*true/,
-    'expected the commit path to return hardeningPrOpened:true',
+    /const hardeningPrOpened =\s*typeof commitResult\?\.hardeningPrUrl === 'string' && commitResult\.hardeningPrUrl\.length > 0/,
+    'expected the commit path to derive hardeningPrOpened from a non-empty hardeningPrUrl, so a PR that opened with an unparseable URL still latches the guard while an empty URL (no PR opened) leaves it clear to retry',
+  );
+});
+
+test('spawnStandardsFollowUp reports the deferred PR identity on every path', () => {
+  const body = lensPromptBody('spawnStandardsFollowUp');
+  const nullDeferred = body.match(/deferredPr:\s*null/g) || [];
+  assert.ok(
+    nullDeferred.length >= 2,
+    'expected both skip paths (no hardening staged, verify failed) to return deferredPr:null',
+  );
+  assert.match(
+    body,
+    /parseDeferredPr\(commitResult\?\.hardeningPrUrl\)/,
+    'expected the commit path to parse the deferred PR identity from the commit step hardeningPrUrl',
+  );
+  assert.doesNotMatch(
+    body,
+    /hardeningPrOpened:\s*deferredPr !== null/,
+    'expected the commit path to keep hardeningPrOpened separate from the parsed deferredPr so an unparseable URL still latches the guard',
+  );
+});
+
+test('the workflow return objects carry the accumulated deferredPrs list', () => {
+  const converged = convergeSource.match(/deferredPrs/g) || [];
+  assert.ok(
+    converged.length >= 4,
+    'expected deferredPrs to be declared, pushed at both deferral call sites, and returned',
+  );
+  assert.match(
+    convergeSource,
+    /if \(standardsOutcome\?\.deferredPr\) deferredPrs\.push\(standardsOutcome\.deferredPr\)/,
+    'expected each deferral call site to accumulate the deferred PR into deferredPrs',
   );
 });
 
@@ -758,3 +845,117 @@ test('extractVerifyObjection calls parseLastVerdictFence', () => {
   const objectionBody = lensPromptBody('extractVerifyObjection');
   assert.match(objectionBody, /parseLastVerdictFence\(/, 'expected extractVerifyObjection to call the shared parser');
 });
+
+test('the headless preamble routes waits through the Monitor tool and forbids ending a turn to await work', () => {
+  const preambleStart = convergeSource.indexOf('const HEADLESS_SAFETY_PREAMBLE =');
+  assert.notEqual(preambleStart, -1, 'expected a HEADLESS_SAFETY_PREAMBLE definition');
+  const preambleEnd = convergeSource.indexOf('\n\nlet activeRepoPath', preambleStart);
+  assert.notEqual(preambleEnd, -1, 'expected the preamble to end before activeRepoPath');
+  const preamble = convergeSource.slice(preambleStart, preambleEnd);
+  assert.match(preamble, /foreground sleep is blocked/i, 'expected the preamble to state foreground sleep is blocked');
+  assert.match(preamble, /Monitor tool/, 'expected the preamble to route waits through the Monitor tool');
+  assert.match(preamble, /StructuredOutput/, 'expected the preamble to require a schema agent to always call StructuredOutput');
+  assert.match(preamble, /never end your turn to wait/i, 'expected the preamble to forbid ending a turn to await background work');
+});
+
+test('the preamble describes the Monitor wait by its real contract: a bounded until-loop consuming notifications as they arrive, rather than an in-turn synchronous return', () => {
+  const blockStart = convergeSource.indexOf('const HEADLESS_SAFETY_PREAMBLE =');
+  assert.ok(blockStart !== -1, 'expected a wait-safety preamble to exist');
+  const blockEnd = convergeSource.indexOf('\n\nlet activeRepoPath', blockStart);
+  assert.ok(blockEnd !== -1, 'expected the preamble to end before activeRepoPath');
+  const preamble = convergeSource.slice(blockStart, blockEnd);
+  assert.doesNotMatch(
+    preamble,
+    /never move a wait to a background process/i,
+    'the Monitor tool is itself a background monitor, so the preamble must avoid forbidding a wait that moves to a background process',
+  );
+  assert.doesNotMatch(
+    preamble,
+    /return to you when the condition holds/i,
+    'the Monitor tool streams notifications across turns rather than returning in-turn, so the preamble must avoid describing an in-turn synchronous return',
+  );
+  assert.match(
+    preamble,
+    /until-loop/i,
+    'expected the preamble to describe the wait as a bounded until-loop paired with the Monitor tool',
+  );
+  assert.match(
+    preamble,
+    /notifications? as they arrive/i,
+    'expected the preamble to say Monitor notifications are consumed as they arrive',
+  );
+});
+
+test('the background-wait clause gives "await" an explicit object, not a dangling "await never resumes"', () => {
+  const text = preambleText();
+  assert.doesNotMatch(
+    text,
+    /end your turn to await never resumes/i,
+    'expected the background-wait clause to name what is awaited, not read as "await never resumes" with no object',
+  );
+  assert.match(
+    text,
+    /end your turn to await it/i,
+    'expected the background-wait clause to name the wait as the object of "await"',
+  );
+});
+
+test('the wait guidance names the full down-result schema, not a bare down flag', () => {
+  const text = preambleText();
+  assert.doesNotMatch(
+    text,
+    /Copilot gate, down: true\)/,
+    'expected the down signal to name the full schema, not a bare down flag that reads as a partial object',
+  );
+  assert.match(
+    text,
+    /down:true, findings:\[\]/,
+    'expected the wait guidance to name the full down-result fields',
+  );
+});
+
+test('no agent prompt instructs a foreground sleep as the poll delay', () => {
+  assert.doesNotMatch(
+    convergeSource,
+    /delay each (?:attempt|iteration|retry) with "sleep/,
+    'expected no poll directive to instruct a foreground sleep as the between-attempt delay',
+  );
+  assert.doesNotMatch(
+    convergeSource,
+    /Start-Sleep -Seconds/,
+    'expected no agent prompt to instruct a foreground PowerShell Start-Sleep',
+  );
+});
+
+test('the wait guidance sizes the Monitor timeout_ms above the 300s default', () => {
+  const text = preambleText();
+  assert.match(text, /timeout_ms/, 'names the timeout_ms parameter the wait rule tells the agent to set');
+  assert.match(text, /persistent/, 'offers persistent as an alternative to a sized timeout_ms');
+  assert.match(text, /300000|300 second/, 'names the 300000 default that truncates a long wait');
+  assert.match(
+    text,
+    /interval[\s\S]{0,60}attempt|interval-times-attempts/i,
+    'sizes timeout_ms to the interval-times-attempts span the step names',
+  );
+});
+
+test('the Monitor ceiling the guidance names covers the longest interval-times-attempts wait the steps prescribe', () => {
+  const cap = /(\d{7})\s*(?:ms|millisecond)/i.exec(preambleText());
+  assert.ok(cap !== null, 'the guidance names a seven-digit Monitor ceiling in milliseconds');
+  const ceiling = Number(cap[1]);
+
+  const copilot = lensPromptBody('runCopilotGate');
+  const bugbot = lensPromptBody('runBugbotLens');
+  const apart = Number(/(\d+)\s*seconds apart/.exec(copilot)[1]);
+  const polls = Number(/copilotMaxPolls:\s*(\d+)/.exec(convergeSource)[1]);
+  const seconds = Number(/every\s*(\d+)\s*seconds/.exec(bugbot)[1]);
+  const iterations = Number(/up to\s*(\d+)\s*iterations/.exec(bugbot)[1]);
+  const spans = [apart * polls * 1000, seconds * iterations * 1000];
+
+  for (const span of spans) {
+    assert.ok(
+      span <= ceiling,
+      `a ${span}ms wait span exceeds the ${ceiling}ms Monitor ceiling the guidance names`,
+    );
+  }
+});