claude-dev-env 1.93.0 → 1.94.0

package/skills/autoconverge/reference/convergence.md

@@ -35,7 +35,8 @@ same edit → verify → commit fix flow the rounds use, landing in one verified
 commit before convergence begins. The pass is best-effort: when no case clears
 all three criteria the run proceeds straight to convergence. Whatever the reuse
 pass surfaces also joins the round findings, so the code-review lens re-checks
-any improvement that did not land.
+any improvement that did not land. The run result's `reuseNote` records what
+landed.
 
 ## The round loop
 
@@ -93,6 +94,13 @@ confirmation gates that are expected to return zero.
 6. **Zero findings on a stable HEAD** → post the CLEAN bugteam audit artifact
    for that HEAD, then move to the terminal Bugbot gate.
 
+A round whose findings are ALL code-standard violations (pure CODE_RULES/style,
+no behavioral impact) passes for convergence purposes: the workflow files a
+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.
+
 **BUGBOT** gate (terminal external confirmation):
 
 - Runs once the internal lenses are clean. When Bugbot is off for the run — the
@@ -132,6 +140,8 @@ the strongest model only where judgment is dense:
 - **opus** — the reading lenses (code-review, bug-audit, self-review,
   reuse), the terminal Bugbot gate, and the code-editing steps that fix findings
   (fix-edit, conflict-edit, repair-edit, standards-edit).
+- **haiku** — the mechanical probes: preflight, the Copilot gate, the
+  CLEAN-audit post, and the convergence check.
 
 ## Full-diff rule
 
@@ -141,27 +151,21 @@ bugbot-flagged path does not satisfy the round; its clean verdict is not a clean
 
 ## The ready definition
 
-`check_convergence.py` is the single source of truth for readiness. It re-derives
-every condition from GitHub and marks the PR ready only when all of these hold on
-the current HEAD:
-
-1. Bugbot CI check run is completed with a success or neutral conclusion
-   (bypassed when Bugbot is off for the run — the default unless
-   `CLAUDE_REVIEWS_ENABLED` lists `bugbot` — opted out via
-   `CLAUDE_REVIEWS_DISABLED`, or proved unreachable this run).
-2. The Bugbot review body on HEAD reports no findings (checked when a Bugbot
-   review is present).
-3. A CLEAN bugteam audit review sits on HEAD.
-4. The Copilot review on HEAD is clean or approved (bypassed when Copilot is down
-   or out of quota this run).
-5. Zero unresolved bot review threads anywhere on the PR — counting Cursor,
-   Claude, and Copilot authored threads. The filter is purely
-   `isResolved == false`; `isOutdated` is informational, and the fix lens
-   verifies each outdated thread against current HEAD like any other (the
-   `pr-fix-protocol` skill's unresolved-thread sweep).
-6. The PR is mergeable (`mergeable` true and `mergeable_state` clean).
-7. No requested reviewers are still pending (bypassed when Copilot is down or out
-   of quota this run).
+`check_convergence.py` (`pr-converge/scripts/check_convergence.py`) is the single
+source of truth for readiness. Ready means the script exits `0` and prints:
+
+```
+All pre-conditions met — PR is ready to mark ready.
+```
+
+The script re-derives every condition from GitHub and prints one PASS/FAIL line
+per label. The exact printed labels (script order) live in
+[`pr-converge/reference/convergence-gates.md`](../../pr-converge/reference/convergence-gates.md)
+§ (f) Mark ready and report — the seven-label block under "Exact printed labels".
+
+The script has no Claude APPROVED review gate. Agent-side checks (Claude
+reviewer presence, broader unresolved-thread sweeps) sit outside this machine
+checklist.
 
 ## Audit-trail design
 

package/skills/autoconverge/reference/headless-safety.md

@@ -0,0 +1,44 @@
+# Headless-safety preamble
+
+Every agent prompt the workflow authors carries a headless-safety preamble: the
+run is unattended, so agents never inline a destructive-command literal
+(`rm -rf`, `git reset --hard`, `dd`) into a Bash command — the
+`destructive_command_blocker` hook matches those patterns as raw text, and a
+confirmation prompt no human can answer would stall the run.
+
+## Two forms
+
+The preamble has two forms. Read-only agents — the review, verify, and utility
+spawns that edit nothing — receive a trimmed form that drops the rm-shape rules,
+since a read-only agent never runs `rm`. Edit agents — the fix and commit spawns
+— receive the full form that carries the rm-shape rules below.
+
+Agents verify destructive-blocker behavior through the committed test suite
+(`python -m pytest`) and keep scratch work in the OS temp dir.
+
+## The rm auto-allow paths (full form)
+
+The full preamble describes three auto-allow paths:
+
+1. **Standalone path** — a standalone Bash call whose target resolves inside the
+   ephemeral namespace (`/tmp`, `/temp`, the OS temp root, or the run worktree).
+   It fails closed on `$(...)` substitution and backtick subshells. It declines a
+   `$`-bearing target only when the literal path is not already under an
+   ephemeral root, so it does not by itself stop a `$VAR` that expands inside an
+   ephemeral root.
+2. **Compound path** — accepts an rm joined with benign reporting segments when
+   every rm target is an absolute ephemeral path. It fails closed on `$(...)`
+   substitution, backtick subshells, and any `$` in the target — including
+   `$CLAUDE_JOB_DIR`.
+3. **Cwd-scoped path** — matches only when the command itself declares an
+   ephemeral working directory (it `cd`s into one, or runs under one). It
+   resolves the target against the declared cwd, fails closed on `$(...)`,
+   backticks, and unknown variables, and resolves the known temporary variables
+   `TEMP`, `TMP`, `TMPDIR`, and `CLAUDE_JOB_DIR` to the OS temp root. Under a
+   declared ephemeral cwd, a bare `$CLAUDE_JOB_DIR/tmp/<name>` target and a
+   relative target after a `cd` are auto-allowed.
+
+Even so, for any cleanup whose path is variable-built or whose teardown spans
+multiple steps, agents author a Python helper file and run it as
+`python <file>.py` — keeping every destructive literal out of a Bash command
+string entirely and independent of which auto-allow path matches.

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

@@ -0,0 +1,88 @@
+# Multiple PRs
+
+The multi-PR run drives several draft PRs to ready in one launch:
+`workflow/converge_multi.mjs` fans out one `converge.mjs` child run per PR with
+`parallel()`, and every child is pinned to its own PR's worktree through the
+`repoPath` it receives, so the children never share a checkout. Each child run is
+the exact single-PR convergence loop — same rounds, same reuse pass, same Copilot
+gate, same convergence check — one per PR at once. The children share the run's
+concurrency cap, so the fan-out self-throttles rather than spawning every PR's
+lenses at the same instant.
+
+## Multi-PR pre-flight (main session)
+
+`EnterWorktree` puts the session on one branch only, so the multi-PR path gives
+each PR its own checkout with `git worktree add`. For each PR the user named:
+
+1. **Resolve PR scope** as the single-PR pre-flight step 2 in
+   [`SKILL.md`](../SKILL.md) does: capture `owner`, `repo`, `prNumber`, and
+   `headRefName`; confirm the PR is a draft, and mark it draft
+   (`gh pr ready <n> --repo <o>/<r> --undo`) when it is already ready so the
+   loop owns the ready transition.
+2. **Create a worktree on the PR's head ref** and capture its absolute path. From
+   inside the PR's repository checkout:
+   `git worktree add <abs worktree path> <headRefName>` (run `git fetch origin
+   <headRefName>` first when the ref is not local). Put each PR's worktree under a
+   path carrying its PR number so the fan-out keeps them distinct. Confirm
+   `git -C <abs worktree path> rev-parse --abbrev-ref HEAD` equals the head ref
+   and its `HEAD` equals the PR head SHA.
+3. **Verify each worktree is the PR's repo (strict pre-flight):**
+   `python "$HOME/.claude/skills/_shared/pr-loop/scripts/preflight_worktree.py" --owner <owner> --repo <repo> --mode strict`,
+   run with that worktree as the working directory. A non-zero exit prints a
+   `PREFLIGHT_OUTCOME` line and an `ABORT` line: report it and drop that PR from
+   the run rather than aborting every PR.
+4. **Grant project permissions once per repository** — the single-PR pre-flight
+   step 4 grant covers every worktree of the same repo, so run it one time for
+   the repo the PRs live in.
+5. **Copilot quota pre-check once for the whole run** — run the single-PR
+   pre-flight step 5 check one time:
+   `python "$HOME/.claude/_shared/pr-loop/scripts/copilot_quota.py"`. Every PR in
+   the run shares one account's Copilot premium-request quota, so one check covers
+   them all. Exit 0 sets `copilotDisabled: false` on every PR entry below; any
+   non-zero exit sets `copilotDisabled: true` on every entry, so each child skips
+   the Copilot gate with no agent spawned.
+
+## Launch the multi-PR workflow
+
+Call the `Workflow` tool against the fan-out script, passing the absolute path of
+`converge.mjs` and one entry per PR:
+
+```
+Workflow({
+  scriptPath: "<this skill dir>/workflow/converge_multi.mjs",
+  args: {
+    convergeScriptPath: "<this skill dir>/workflow/converge.mjs",
+    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 }
+    ]
+  }
+})
+```
+
+`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
+completion; watch live progress with `/workflows`, where each PR's child run
+appears under its own group.
+
+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)
+
+Run the single-PR Teardown in [`SKILL.md`](../SKILL.md) once per entry in
+`results`, using that PR's `owner`, `repo`, `prNumber`, and `finalSha`, and its
+own worktree as the working directory. Write one durable handoff per PR entry —
+each with that PR's own `--pr-number` — so a fresh session can resume any PR on
+its own. Build and publish a PR's closing report
+only for a PR whose `converged` is true; for a PR that returned a blocker, skip
+its report and carry the blocker into the final summary. Revoke project
+permissions once per repository after every PR's teardown. Then print one summary
+report — a line per PR as
+`#<prNumber>: <converged | blocked> — rounds <N>, final <finalSha>[, blocker <blocker>]`.

package/skills/autoconverge/reference/self-closing-loop.md

@@ -0,0 +1,84 @@
+# 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 (the session that 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-dev-env` for rules and skills both appear):
+
+1. **Check out each deferred PR.** Run the
+   [multi-PR pre-flight](multi-pr.md#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](multi-pr.md#launch-the-multi-pr-workflow) describes. Each
+   child run checks Copilot and Bugbot availability through the workflow's own
+   preflight-git probe, carried across rounds, 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.md#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.

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

@@ -6,6 +6,14 @@ skill still runs teardown (revoke permissions, final report).
 
 ## Blockers (end the run short of ready)
 
+- **Budget stop** — the workflow's `budget` API is the pacing signal: when a
+  usage target is set, `converge.mjs` checks `budget.remaining()` before each
+  round and stops at the round boundary when one full round (three parallel
+  lenses + one fix commit + re-verify) does not fit. The run returns
+  `blocker: "budget"` with the run id; resume with
+  `Workflow({scriptPath, resumeFromRunId})` — completed rounds replay from the
+  journal. The workflow never starts a round the budget cannot finish: a
+  half-run round records nothing resumable and replays dirty.
 - **Iteration cap** — 20 loop iterations pass without a full convergence-check
   pass. The iteration counter increments on every pass through any phase, so a
   convergence-check gate that no round can clear (for example a `mergeable_state`
@@ -37,19 +45,6 @@ skill still runs teardown (revoke permissions, final report).
   cannot confirm the PR left draft state (`gh pr ready` errored, or the draft
   re-query still reports true). The workflow does not report `converged: true`;
   the run ends with a `blocker` naming the failed ready transition.
-- **Clean-audit post blocked** — every review lens is clean on HEAD, but the
-  CLEAN bugteam review cannot be posted (the `post_audit_thread.py` post is
-  denied, errors, or its agent dies). The convergence gate's bugteam-review
-  check can never pass without that CLEAN review, so the run stops rather than
-  re-converge to the iteration cap. The `blocker` names the post failure and the
-  HEAD. Unblock a permission denial by allowing `post_audit_thread.py` with a
-  Bash permission rule. Unblock any other failure by creating a fresh temporary
-  file whose exact content is an empty JSON array (`[]`) and re-running the run's
-  own `post_audit_thread.py --skill bugteam --state CLEAN` command for the
-  lens-verified HEAD with that file as `--findings-json`; then re-run the
-  workflow. A CLEAN post carries an empty findings array by construction, so this
-  re-issues the run's own command for the outcome the lenses already established
-  for that HEAD.
 - **No review lens reviewed HEAD** — a round can end with no lens having reviewed
   the HEAD three ways: the preflight resolves no SHA, every lens agent dies, or
   every lens is down or disabled. A single such round retries on the next round.
@@ -61,6 +56,19 @@ skill still runs teardown (revoke permissions, final report).
 
 ## Not a blocker (the run continues)
 
+Each reviewer-down condition below skips its own convergence-check gate. The flag and the matching `CLAUDE_REVIEWS_DISABLED` token for each condition are the single flag-per-condition table in [`../../reviewer-gates/SKILL.md`](../../reviewer-gates/SKILL.md) § "Convergence-check bypass flags"; the token carries the bypass into the mark-ready blocker hook's no-flag re-check.
+
+- **Clean-audit post bypassed** — every review lens is clean on HEAD, but the
+  environment refuses the CLEAN bugteam review post (the `post_audit_thread.py`
+  post is denied, errors, or its agent never runs). The lens results already show
+  this HEAD is clean, so the CLEAN post is a record-keeping artifact, not the
+  safety-bearing gate. The run records a `cleanAuditNote` naming the HEAD and the
+  reason, logs the bypass, and proceeds to the terminal Bugbot gate — the same
+  shape as the Bugbot-down and Copilot-down paths. The convergence check runs with
+  `--bugteam-post-blocked` so its bugteam CLEAN-review gate is skipped and the run
+  closes on the remaining signals. A round where no lens actually reviewed HEAD is
+  separate: that re-converges under the no-review-lens rule above, since no lens
+  grounded a post.
 - **Terminal Bugbot gate down or disabled** — the terminal Bugbot gate runs once
   the internal lenses are clean. When Cursor Bugbot is off for the run (the
   default unless `CLAUDE_REVIEWS_ENABLED` lists `bugbot`) or opted out via

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

@@ -22,10 +22,22 @@ function moduleConstantSource(constantName) {
 }
 
 const productionModule = new Function(
-  `${functionBody('cleanAuditBlocker')}\n` + 'return { cleanAuditBlocker };',
+  `${functionBody('cleanAuditPostReason')}\n` +
+    `${functionBody('cleanAuditBypassNote')}\n` +
+    'return { cleanAuditPostReason, cleanAuditBypassNote };',
 )();
 
-const { cleanAuditBlocker } = productionModule;
+const { cleanAuditPostReason, cleanAuditBypassNote } = productionModule;
+
+function buildResolveCleanAuditNote(logStub) {
+  const factory = new Function(
+    'log',
+    'cleanAuditPostReason',
+    'cleanAuditBypassNote',
+    `${functionBody('resolveCleanAuditNote')}\n return resolveCleanAuditNote;`,
+  );
+  return factory(logStub, cleanAuditPostReason, cleanAuditBypassNote);
+}
 
 const provenanceModule = new Function(
   `const LENS_NAMES = ${moduleConstantSource('LENS_NAMES')};\n` +
@@ -79,28 +91,22 @@ function buildRunGeneralUtilityTask(convergeAgentStub) {
 
 const CONVERGED_HEAD = 'abcdef0123456789abcdef0123456789abcdef01';
 
-test('cleanAuditBlocker names the reason, the HEAD, and grounded recovery for both permission and non-permission failures without any compose-by-hand language', () => {
-  const message = cleanAuditBlocker(CONVERGED_HEAD, {
+test('cleanAuditBypassNote names the HEAD and the reason and frames a recorded bypass rather than a stop', () => {
+  const note = cleanAuditBypassNote(CONVERGED_HEAD, {
     posted: false,
     reviewUrl: '',
     reason: 'denied by the auto mode classifier',
   });
-  assert.match(message, /denied by the auto mode classifier/);
-  assert.match(message, /post_audit_thread\.py/);
-  assert.match(message, new RegExp(CONVERGED_HEAD));
-  assert.match(message, /can never pass without it/);
-  assert.match(message, /permission rule/);
-  assert.match(message, /gh auth|network|script error/);
-  assert.match(message, /re-run/);
-  assert.match(message, /empty JSON array/, 'expected a self-contained recovery that creates a fresh empty findings file');
-  assert.doesNotMatch(message, /the run's own empty findings file/, 'expected no reference to a findings file that may never have been created');
-  assert.doesNotMatch(message, /by hand/i);
-  assert.doesNotMatch(message, /compose/i);
+  assert.match(note, /denied by the auto mode classifier/);
+  assert.match(note, new RegExp(CONVERGED_HEAD));
+  assert.match(note, /could not be posted/);
+  assert.match(note, /bugteam-review gate skipped/);
+  assert.doesNotMatch(note, /the run stops/);
 });
 
-test('cleanAuditBlocker falls back to a no-result reason when the post agent died', () => {
-  const message = cleanAuditBlocker(CONVERGED_HEAD, null);
-  assert.match(message, /the post agent returned no result/);
+test('cleanAuditPostReason reads the result reason and falls back to a no-result reason when the post agent died', () => {
+  assert.equal(cleanAuditPostReason(null), 'the post agent returned no result');
+  assert.equal(cleanAuditPostReason({ posted: false, reason: 'denied by the classifier' }), 'denied by the classifier');
 });
 
 test('the post-clean-audit task in runGeneralUtilityTask returns the CLEAN_AUDIT_SCHEMA result rather than an unused transcript', () => {
@@ -524,15 +530,16 @@ test('CLEAN_AUDIT_SCHEMA requires posted, reviewUrl, and reason', () => {
   );
 });
 
-test('the standards-only call site breaks with a clean-audit blocker when the post does not land', () => {
+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) {'),
   );
   assert.match(branch, /runGeneralUtilityTask\(.*'post-clean-audit'/);
-  assert.match(branch, /if \(!auditResult\?\.posted\)/);
-  assert.match(branch, /blocker = cleanAuditBlocker\(head, auditResult\)/);
-  assert.match(branch, /\bbreak\b/);
+  assert.match(branch, /cleanAuditNote = resolveCleanAuditNote\(auditResult, head, rounds\)/);
+  assert.match(branch, /phase = 'BUGBOT'/);
+  assert.doesNotMatch(branch, /blocker = cleanAuditBlocker/);
+  assert.doesNotMatch(branch, /\bbreak\b/);
 });
 
 test('the standards-only call site relays lens provenance, the deferred standards findings, and the deferral filing state', () => {
@@ -568,7 +575,7 @@ test('every standardsDeferralNote call site passes the shared deferral state wit
     'expected the terminal-Bugbot call site to pass buildStandardsDeferral() inline',
   );
   assert.equal(
-    noteCalls.filter((eachCall) => /standardsDeferralNote\(copilotOutcome\.findings\.length, buildStandardsDeferral\(\)\)/.test(eachCall)).length,
+    noteCalls.filter((eachCall) => /standardsDeferralNote\(roundFindings\.length, buildStandardsDeferral\(\)\)/.test(eachCall)).length,
     1,
     'expected the copilot call site to pass buildStandardsDeferral() inline',
   );
@@ -578,15 +585,17 @@ test('every standardsDeferralNote call site passes the shared deferral state wit
   assert.doesNotMatch(convergeSource, /buildStandardsDeferral\(standardsOutcome\)/);
 });
 
-test('the all-clean call site breaks with a clean-audit blocker when the post does not land', () => {
+test('the all-clean call site records a clean-audit bypass and continues to BUGBOT when the post does not land, keeping the noLensRan re-converge', () => {
   const branch = convergeSource.slice(
     convergeSource.indexOf('all lenses clean on'),
     convergeSource.indexOf("if (phase === 'BUGBOT') {"),
   );
   assert.match(branch, /runGeneralUtilityTask\(.*'post-clean-audit'/);
-  assert.match(branch, /if \(!auditResult\?\.posted\)/);
-  assert.match(branch, /blocker = cleanAuditBlocker\(head, auditResult\)/);
-  assert.match(branch, /\bbreak\b/);
+  assert.match(branch, /if \(auditResult\?\.noLensRan\)/);
+  assert.match(branch, /cleanAuditNote = resolveCleanAuditNote\(auditResult, head, rounds\)/);
+  assert.match(branch, /resetNoLensRounds\(\)/);
+  assert.match(branch, /phase = 'BUGBOT'/);
+  assert.doesNotMatch(branch, /blocker = cleanAuditBlocker/);
 });
 
 test('the all-clean call site relays lens provenance into the post-clean-audit context without a postFindings field', () => {
@@ -598,3 +607,54 @@ test('the all-clean call site relays lens provenance into the post-clean-audit c
   assert.match(branch, /lensResults: allCleanNamedLenses/);
   assert.doesNotMatch(branch, /postFindings/);
 });
+
+test('runConvergenceCheck threads a --bugteam-post-blocked flag and an explanatory note when the bugteam post was bypassed', () => {
+  const body = functionBody('runConvergenceCheck');
+  assert.match(body, /const bugteamPostBlockedFlag = context\.bugteamPostBlocked \? ' --bugteam-post-blocked' : ''/);
+  assert.match(body, /context\.bugteamPostBlocked/);
+  assert.match(body, /\$\{bugteamPostBlockedFlag\}/);
+  assert.match(body, /bugteamPostBlockedNote/);
+  assert.match(body, /skips the bugteam CLEAN-review gate/);
+});
+
+test('resolveCleanAuditNote records a bypass note on a refused post and resets to null when a later round lands the post', () => {
+  const loggedLines = [];
+  const resolveCleanAuditNote = buildResolveCleanAuditNote((message) => loggedLines.push(message));
+
+  const bypassNote = resolveCleanAuditNote(
+    { posted: false, reviewUrl: '', reason: 'denied by the classifier' },
+    'abc1234def5678',
+    2,
+  );
+  assert.notEqual(bypassNote, null, 'a refused post records the bypass note');
+  assert.match(bypassNote, /denied by the classifier/);
+  assert.equal(loggedLines.length, 1, 'a refused post logs the bypass once');
+
+  const clearedNote = resolveCleanAuditNote(
+    { posted: true, reviewUrl: 'https://github.com/o/r/pull/1#pullrequestreview-9', reason: '' },
+    'abc1234def5678',
+    3,
+  );
+  assert.equal(clearedNote, null, 'a landed post in a later round resets the bypass note so FINALIZE runs the bugteam gate');
+  assert.equal(loggedLines.length, 1, 'a landed post logs no bypass line');
+});
+
+test('the finalize call derives bugteamPostBlocked from a set cleanAuditNote', () => {
+  assert.match(
+    convergeSource,
+    /runConvergenceCheck\(\{ head, bugbotDown, copilotDown, bugteamPostBlocked: cleanAuditNote !== null \}\)/,
+  );
+});
+
+test('the workflow declares cleanAuditNote and assembles it into every result via a single note-fields builder', () => {
+  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 assembleCalls = convergeSource.match(/return assembleResult\(/g) || [];
+  assert.ok(
+    assembleCalls.length >= 3,
+    'expected the user-review, converged, and iteration-cap returns to build through assembleResult',
+  );
+});

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

@@ -14,6 +14,10 @@ const skillSource = readFileSync(
   join(workflowDirectory, '..', 'SKILL.md'),
   'utf8',
 );
+const headlessSafetySource = readFileSync(
+  join(workflowDirectory, '..', 'reference', 'headless-safety.md'),
+  'utf8',
+);
 
 function lensPromptBody(builderName) {
   let builderStart = convergeSource.indexOf(`function ${builderName}(`);
@@ -272,7 +276,7 @@ test('the CONVERGE fix branch does not re-assign head from the fix before re-con
 
 test('the COPILOT fix branch does not re-assign head from the fix before re-converging', () => {
   assert.doesNotMatch(
-    fixBranchAfter('${copilotOutcome.findings.length} finding(s) — fixing and re-converging'),
+    fixBranchAfter('${roundFindings.length} finding(s) — fixing and re-converging'),
     /head\s*=\s*fixProgress/,
     'the CONVERGE pass it transitions to re-resolves HEAD from GitHub, so assigning the fix SHA here is dead',
   );
@@ -819,17 +823,43 @@ test('SKILL.md does not attribute the known-temp-var resolution to the standalon
   );
 });
 
-test('SKILL.md attributes the known-temp-var resolution to the cwd-scoped auto-allow path', () => {
-  const tempVarSentenceMatch =
-    /[^.]*\bTMPDIR\b[^.]*CLAUDE_JOB_DIR[^.]*\./i.exec(skillSource.replace(/\s+/g, ' '));
-  assert.notEqual(
-    tempVarSentenceMatch,
-    null,
+test('headless-safety.md attributes the known-temp-var resolution to the cwd-scoped auto-allow path', () => {
+  const standaloneSectionMatch =
+    /1\.\s*\*\*Standalone path\*\*[\s\S]*?(?=2\.\s*\*\*Compound path\*\*)/i.exec(
+      headlessSafetySource,
+    );
+  assert.notEqual(standaloneSectionMatch, null, 'expected numbered standalone path section');
+  assert.doesNotMatch(
+    standaloneSectionMatch[0],
+    /resolves the known temporary variables/i,
+    'standalone path must not claim the known-temp-var resolution',
+  );
+
+  const compoundSectionMatch =
+    /2\.\s*\*\*Compound path\*\*[\s\S]*?(?=3\.\s*\*\*Cwd-scoped path\*\*)/i.exec(
+      headlessSafetySource,
+    );
+  assert.notEqual(compoundSectionMatch, null, 'expected numbered compound path section');
+  assert.doesNotMatch(
+    compoundSectionMatch[0],
+    /resolves the known temporary variables/i,
+    'compound path must not claim the known-temp-var resolution',
+  );
+
+  const cwdScopedSectionMatch =
+    /3\.\s*\*\*Cwd-scoped path\*\*[\s\S]*?(?=\n\nEven so|\n## |$)/i.exec(
+      headlessSafetySource,
+    );
+  assert.notEqual(cwdScopedSectionMatch, null, 'expected numbered cwd-scoped path section');
+  const cwdScopedSection = cwdScopedSectionMatch[0].replace(/\s+/g, ' ');
+  assert.match(
+    cwdScopedSection,
+    /resolves the known temporary variables[\s\S]{0,80}\bTEMP\b[\s\S]{0,40}\bTMP\b[\s\S]{0,40}\bTMPDIR\b[\s\S]{0,40}\bCLAUDE_JOB_DIR\b/i,
     'expected a sentence describing the TEMP/TMP/TMPDIR/CLAUDE_JOB_DIR resolution',
   );
   assert.match(
-    tempVarSentenceMatch[0],
-    /declares? an ephemeral cwd|declared ephemeral cwd|ephemeral-cwd path|third (?:auto-allow )?path|cwd-scoped path/i,
+    cwdScopedSection,
+    /declares an ephemeral working directory|declared ephemeral cwd|cwd-scoped path/i,
     'expected the temp-var resolution to be tied to the cwd-scoped path that declares an ephemeral working directory, not the standalone or compound paths',
   );
 });
@@ -1204,7 +1234,7 @@ test('the FINALIZE phase drives the merged check and reads ready from its result
   const finalizeStart = convergeSource.indexOf("if (phase === 'FINALIZE') {");
   assert.notEqual(finalizeStart, -1, 'expected a FINALIZE phase block');
   const finalizeBody = convergeSource.slice(finalizeStart, finalizeStart + 1000);
-  assert.match(finalizeBody, /runConvergenceCheck\(\{ head, bugbotDown, copilotDown \}\)/);
+  assert.match(finalizeBody, /runConvergenceCheck\(\{ head, bugbotDown, copilotDown, bugteamPostBlocked: cleanAuditNote !== null \}\)/);
   assert.match(finalizeBody, /classifyReadyOutcome\(finalizeResult\)/);
   assert.doesNotMatch(
     finalizeBody,