claude-dev-env 1.58.0 → 1.59.0

package/hooks/hooks_constants/hook_prose_detector_consistency_constants.py

@@ -0,0 +1,30 @@
+"""Configuration constants for the hook_prose_detector_consistency PreToolUse hook."""
+
+WRITE_TOOL_NAME: str = "Write"
+EDIT_TOOL_NAME: str = "Edit"
+
+HOOK_MODULE_PATH_SEGMENT: str = "/hooks/"
+PYTHON_FILE_SUFFIX: str = ".py"
+CONSTANTS_MODULE_SUFFIX: str = "_constants.py"
+TEST_MODULE_PREFIX: str = "test_"
+
+PATH_SEPARATOR_CLASS_PATTERN: str = (
+    r"\[[^\]/]*\\\\[^\]/]*\]|\[[^\]]*\\\\?/[^\]]*\]|\[[^\]]*/\\\\?[^\]]*\]"
+)
+OVERSTATED_OUTPUT_KEY_PHRASE_PATTERN: str = r"output[- ]key\s+segment"
+
+CORRECTIVE_MESSAGE: str = (
+    "BLOCKED [hook-prose-detector-consistency]: A hook module's user-facing prose "
+    "(its docstring lead narrative or CORRECTIVE_MESSAGE) claims the hook blocks an "
+    "'output-key segment', but the module's detector keys off a path separator only "
+    "(it matches a token next to `\\` or `/`). A quoted structured-output key alone "
+    "never triggers a block, so the prose overstates the contract: an author whose "
+    "only per-iteration token is an output key would never see this message, and an "
+    "author who does see it is told an output key caused a block it cannot cause.\n\n"
+    "Describe only the trigger the detector implements: a per-iteration path segment "
+    "next to a path separator. Drop 'or output-key segment' (or restate it as 'a "
+    "per-iteration path segment') so the message and docstring match what the regex "
+    "catches.\n\n"
+    "Invariant: a hook's docstring and corrective message describe exactly the shapes "
+    "its detector flags -- no broader trigger surface than the regex enforces."
+)

package/hooks/hooks_constants/subprocess_budget_completeness_constants.py

@@ -0,0 +1,5 @@
+"""Configuration constants for the subprocess_budget_completeness PreToolUse hook."""
+
+ALL_BUDGET_NAME_MARKERS: tuple[str, ...] = ("worst_case", "_budget", "budget_seconds")
+SUBPROCESS_TIMEOUT_KEYWORD: str = "timeout"
+BUDGET_ENTRY_POINT_FUNCTION_NAME: str = "main"

package/hooks/hooks_constants/workflow_substitution_slot_blocker_constants.py

@@ -0,0 +1,22 @@
+"""Configuration constants for the workflow_substitution_slot_blocker PreToolUse hook."""
+
+WRITE_TOOL_NAME: str = "Write"
+EDIT_TOOL_NAME: str = "Edit"
+MULTI_EDIT_TOOL_NAME: str = "MultiEdit"
+
+WORKFLOW_FILE_SUFFIX: str = ".workflow.js"
+
+CORRECTIVE_MESSAGE: str = (
+    "BLOCKED [workflow-substitution-slot]: A bare per-iteration index token "
+    "(for example `cand_i`) appears as a per-iteration path segment inside a "
+    ".workflow.js agent-prompt block that loops over an index. A bare `_i` "
+    "token reads as a fixed literal, so an agent can create one literal "
+    "directory and overwrite it across every iteration -- collapsing an "
+    "N-iteration gate into one.\n\n"
+    "Mark the index as a substitution slot with the angle-bracket convention "
+    "this template already uses for per-call values (`<plate.svg>`, `<glow_hex>`): "
+    "write `cand_<i>` instead of `cand_i`, or spell out 'replace <i> with the "
+    "iteration index 0, 1, 2' in the step text.\n\n"
+    "Convention: every per-call substitution slot in a .workflow.js template is "
+    "marked with angle brackets, so an agent fills in a fresh value per call."
+)

package/package.json

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

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

@@ -0,0 +1,43 @@
+# Docstring Prose Matches Implementation
+
+**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps.
+
+## Rule
+
+When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
+
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"` — has no signature to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose. It carries documented-but-pending hook coverage; the audit lane below is the enforcement until a deterministic gate check exists.
+
+## What to check before you write the docstring
+
+Read the body and the docstring side by side:
+
+- **Read-source / match-source unions.** A body that computes `read_names = a | b | c` (or any union of "what counts") names each union member in the prose enumeration. A union member the code applies but the prose omits is a gap.
+- **Suppressor / skip lists.** A body with several early returns that suppress the check names each suppressor in the prose.
+- **Step order.** A docstring that says `A then B then C` matches the call order in the body.
+- **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
+
+When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
+
+## Worked example
+
+A `@dataclass` dead-field check builds its set of "field counts as read" sources by union:
+
+```python
+read_names = (
+    attribute_read_names
+    | dynamic_literal_names
+    | _match_pattern_attribute_names(tree)
+    | _exported_names(tree)
+)
+```
+
+A docstring that enumerates "attribute read, augmented-assignment target, class-pattern keyword, literal `getattr`/`attrgetter`" but omits the `__all__` source (`_exported_names`) is drifted: a field whose name appears in `__all__` is treated as read, and the prose hides that. The fix adds the missing source to the enumeration so the list matches the union.
+
+## Enforcement (audit lane)
+
+This drift class is sub-bucket **O6** in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` (free-form `Note:` / `Returns:` / responsibility-list claims). The audit teammate lists every prose enumeration in a changed docstring and verifies each item against the body, and lists every union member / suppressor / step in the body and verifies each appears in the prose. A union member or suppressor in the body that the prose omits is an O6 finding.
+
+## Why
+
+A docstring enumeration earns its place by being trustworthy. A complete list lets a reader reason about the function without scanning the body; a list missing one item is worse than no list, because it asserts completeness it does not have. Naming this standard makes the gap a first-class finding at write time and at audit, rather than a surprise a reader hits months later.

package/rules/hook-prose-matches-detector.md

@@ -0,0 +1,26 @@
+---
+paths: **/hooks/**/*.py
+---
+
+# Hook Prose Matches Its Detector
+
+**When this applies:** Any Write or Edit to a hook module (`.py` under `hooks/`) or its `*_constants.py` companion.
+
+**Hook enforcement:** `hook-prose-detector-consistency` (PreToolUse on Write|Edit) blocks a hook whose user-facing prose claims a trigger its detector never fires on. See `hooks.json` for registration.
+
+## Rule
+
+A hook's docstring lead narrative and its `CORRECTIVE_MESSAGE` describe exactly the shapes the detector flags — no broader trigger surface than the regex enforces. An author reads the corrective message to learn what they did wrong; an author reads the docstring to learn what the hook guards. When either claims a trigger the detector cannot fire on, both audiences are misled: an author whose only token is that shape never sees the block, and an author who does see the block is told the wrong cause.
+
+## The path-shape blocker case
+
+A path-shape blocker detects a per-iteration token only when the token sits next to a path separator (its detection regex keys off a `[\\/]`-style character class). Such a hook must not claim it blocks an "output-key segment": a quoted structured-output key alone, with no looped path, is never flagged. The `*_constants.py` companion holds the corrective message and not the detector, so the phrase "output-key segment" describing a blocked trigger is itself the violation there, regardless of which file holds the regex.
+
+| Prohibited claim | Why it overstates | Correct phrasing |
+|---|---|---|
+| "appears as a path or output-key segment" | the detector keys off a path separator only | "appears as a per-iteration path segment" |
+| docstring: "blocks a bare token like `cand_i`" | a bare prose token next to no separator is not flagged | "blocks a per-iteration path like `${work}\cand_i\plate.svg`" |
+
+## The test
+
+After writing a hook, ask: **would a token that matches every word of this message actually trip the detector?** When the message names a shape the regex skips, rewrite the message to name only what the regex catches.

package/rules/no-inline-destructive-literals.md

@@ -0,0 +1,11 @@
+# No Inline Destructive-Command Literals in Bash
+
+The `destructive_command_blocker` PreToolUse hook matches destructive patterns (`rm -rf`, `git reset --hard`, `dd`, `mkfs`, `chmod -R`, fork bombs) as raw text anywhere in a Bash-tool command, with no quote-awareness — so a destructive literal carried only as DATA (a commit message, a PR/issue/review-comment body, an echoed string, a `python -c`/`node -e`/`awk` argument, a heredoc) trips the confirmation prompt even though the shell never executes it. In a background or auto-mode run no human can answer that prompt, so the call stalls.
+
+Keep destructive literals out of the Bash command string:
+
+- Commit messages and PR/issue/review-comment bodies that describe destructive-command behavior go in a file passed by path — `git commit -F <file>`, `gh ... --body-file <file>` (see [`gh-body-file`](gh-body-file.md)) — never `git commit -m` / `gh ... -b`.
+- To exercise or verify `destructive_command_blocker` (or any hook) behavior, run the committed test suite (`python -m pytest <test_file>`), which passes the command strings as in-language data, not as a shell command — never an inline `python -c` harness.
+- Genuine cleanup targets the OS temp dir or `$CLAUDE_JOB_DIR/tmp` (auto-allowed as ephemeral), never a repository or worktree path.
+
+The `destructive_command_blocker` hook is the enforcement surface; this rule is how to keep a non-executing mention from tripping it.

package/rules/workflow-substitution-slots.md

@@ -0,0 +1,7 @@
+# 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.
+
+When a loop builds a per-iteration path or output key, write the index as a slot — `cand_<i>` — or spell out `replace <i> with the iteration index 0, 1, 2` in the step text. Every per-call value in a `.workflow.js` template carries angle brackets so an agent fills in a fresh value per call.
+
+`workflow_substitution_slot_blocker.py` (PreToolUse on Write/Edit) blocks a `.workflow.js` write whose looped content carries a bare `<word>_<i|j|k>` token as a per-iteration path segment, and returns the corrective message.

package/skills/autoconverge/SKILL.md

@@ -66,7 +66,7 @@ own. 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 }`.
+`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote }`.
 
 ## Budget-aware round boundaries
 
@@ -146,6 +146,7 @@ round records nothing resumable and replays dirty.
    Final commit: <finalSha>
    Blocker: <blocker>        # only when blocked
    Standards: <standardsNote> # only when a round deferred code-standard findings
+   Copilot: <copilotNote>     # only when Copilot was down or out of quota
    ```
 
 ## What the workflow does each round
@@ -156,6 +157,13 @@ shape and the exact convergence definition, and
 run ends short of ready. Hard-won failure lessons live in
 [`reference/gotchas.md`](reference/gotchas.md).
 
+Every agent prompt 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. Agents verify destructive-blocker behavior through the committed test
+suite (`python -m pytest`) and keep scratch work in ephemeral temp dirs.
+
 - **Converge:** `parallel([Bugbot lens, code-review lens, bug-audit lens])` on
   the current HEAD, full `origin/main...HEAD` diff. Dedup findings; one
   `clean-coder` applies all fixes in a single commit, pushes, replies to and
@@ -168,7 +176,10 @@ run ends short of ready. Hard-won failure lessons live in
   any bot threads with a deferral note, and reports the deferral in
   `standardsNote`.
 - **Copilot gate:** request a Copilot review, poll up to three times; findings
-  route back into Converge, a no-show after the cap is a blocker.
+  route back into Converge. When Copilot is down or out of quota — it posts an
+  out-of-usage notice (the requester hit their quota) on the HEAD, or surfaces no
+  review at all after the cap — the gate logs a notice and the run marks the PR
+  ready with the Copilot gate bypassed. `copilotNote` records the bypass.
 - **Convergence check:** `check_convergence.py` is the authoritative gate; on a
   full pass the workflow marks `draft=false`.
 

package/skills/autoconverge/reference/convergence.md

@@ -42,7 +42,9 @@ tracks CONVERGE passes only and is never the cap.
   to three times, 360 seconds apart.
 - Copilot findings → fix them and return to CONVERGE on the new HEAD.
 - Copilot clean or approved → move to the convergence check.
-- No review after three polls → blocker.
+- Copilot down or out of quota (an out-of-usage notice, or no review after three
+  polls) → log a notice and move to the convergence check with the Copilot gate
+  bypassed.
 
 **Convergence check**:
 
@@ -67,13 +69,15 @@ the current HEAD:
 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.
+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 where `isResolved` is false (`isOutdated`
    threads are excluded by the gate, but the fix lens still verifies and resolves
    them during the round).
 6. The PR is mergeable (`mergeable` true and `mergeable_state` clean).
-7. No requested reviewers are still pending.
+7. No requested reviewers are still pending (bypassed when Copilot is down or out
+   of quota this run).
 
 ## Audit-trail design
 

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

@@ -6,8 +6,6 @@ skill still runs teardown (revoke permissions, final report).
 
 ## Blockers (end the run short of ready)
 
-- **Copilot no-show** — Copilot surfaces no review on the current HEAD after
-  three polls (360 seconds apart). `blocker` names the Copilot timeout.
 - **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`
@@ -40,6 +38,13 @@ skill still runs teardown (revoke permissions, final report).
   run or review after the lens poll budget, the Bugbot lens returns `down: true`.
   The run continues, and the convergence check runs with `--bugbot-down` so its
   Bugbot gate is bypassed.
+- **Copilot down or out of quota** — when Copilot posts an out-of-usage notice on
+  the current HEAD (the user who requested the review reached their quota limit)
+  rather than a code review, or surfaces no review at all after three polls, the
+  Copilot gate returns `down: true`. The run logs a notice, runs the convergence
+  check with `--copilot-down` (the Copilot review gate and the
+  pending-requested-reviews gate bypassed), and marks the PR ready. `copilotNote`
+  records the bypass for the final report.
 - **A lens agent dies** — when one parallel 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/converge.copilot-gate.test.mjs

@@ -0,0 +1,265 @@
+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 functionBody(functionName) {
+  const functionStart = convergeSource.indexOf(`function ${functionName}(`);
+  assert.notEqual(functionStart, -1, `expected ${functionName} to exist`);
+  const nextFunctionStart = convergeSource.indexOf('\nfunction ', functionStart + 1);
+  const functionEnd = nextFunctionStart === -1 ? convergeSource.length : nextFunctionStart;
+  return convergeSource.slice(functionStart, functionEnd);
+}
+
+const productionModule = new Function(
+  `${functionBody('classifyCopilotOutcome')}\n` +
+    `${functionBody('resolveCopilotDown')}\n` +
+    'return { classifyCopilotOutcome, resolveCopilotDown };',
+)();
+const { classifyCopilotOutcome, resolveCopilotDown } = productionModule;
+
+function copilotResult(overrides) {
+  return {
+    sha: 'abcdef0',
+    clean: false,
+    down: false,
+    findings: [],
+    ...overrides,
+  };
+}
+
+test('an out-of-usage Copilot result (down) routes to the down kind', () => {
+  const outcome = classifyCopilotOutcome(copilotResult({ clean: true, down: true }));
+  assert.equal(outcome.kind, 'down');
+});
+
+test('a down Copilot result routes to down even when clean is false', () => {
+  const outcome = classifyCopilotOutcome(copilotResult({ clean: false, down: true }));
+  assert.equal(outcome.kind, 'down');
+});
+
+test('a dead Copilot gate agent retries rather than passing', () => {
+  assert.equal(classifyCopilotOutcome(null).kind, 'retry');
+});
+
+test('a reachable Copilot gate with no findings and no clean verdict retries', () => {
+  const outcome = classifyCopilotOutcome(copilotResult({ clean: false, down: false }));
+  assert.equal(outcome.kind, 'retry');
+});
+
+test('Copilot findings route to a fix when Copilot is reachable and not down', () => {
+  const outcome = classifyCopilotOutcome(
+    copilotResult({
+      findings: [
+        {
+          file: 'a.py',
+          line: 1,
+          severity: 'P1',
+          category: 'bug',
+          title: 't',
+          detail: 'd',
+          replyToCommentId: null,
+        },
+      ],
+    }),
+  );
+  assert.equal(outcome.kind, 'fix');
+});
+
+test('COPILOT_SCHEMA carries a required down field', () => {
+  const schemaStart = convergeSource.indexOf('const COPILOT_SCHEMA =');
+  const schemaEnd = convergeSource.indexOf('const HEAD_SCHEMA =');
+  assert.notEqual(schemaStart, -1, 'expected COPILOT_SCHEMA to exist');
+  const schemaSource = convergeSource.slice(schemaStart, schemaEnd);
+  assert.match(schemaSource, /down:\s*\{\s*type:\s*'boolean'/);
+  assert.match(schemaSource, /required:\s*\[[^\]]*'down'[^\]]*\]/);
+  assert.doesNotMatch(
+    schemaSource,
+    /blocker:/,
+    'the Copilot gate no longer surfaces a blocker; a down result carries the outage',
+  );
+});
+
+test('the Copilot gate prompt detects an out-of-usage notice and returns a down result', () => {
+  const copilotPrompt = functionBody('runCopilotGate');
+  assert.match(
+    copilotPrompt,
+    /quota|out of usage|out-of-usage/i,
+    'expected the gate to name the out-of-usage / quota signal',
+  );
+  assert.match(
+    copilotPrompt,
+    /down:\s*true/,
+    'expected the gate to return down:true on an out-of-usage notice',
+  );
+});
+
+test('the step-1 out-of-usage down-detection requires the notice commit_id to start with HEAD', () => {
+  const copilotPrompt = functionBody('runCopilotGate');
+  const stepOneStart = copilotPrompt.indexOf('`1.');
+  assert.notEqual(stepOneStart, -1, 'expected a step-1 instruction in the gate prompt');
+  const stepTwoStart = copilotPrompt.indexOf('`2.', stepOneStart);
+  assert.notEqual(stepTwoStart, -1, 'expected a step-2 instruction in the gate prompt');
+  const stepOneText = copilotPrompt.slice(stepOneStart, stepTwoStart);
+  assert.match(
+    stepOneText,
+    /commit_id starts with \$\{head\}/,
+    'expected step 1 to scope the out-of-usage notice to reviews whose commit_id starts with HEAD, matching step 2 and the convergence gate',
+  );
+});
+
+test('a Copilot no-show after the poll cap returns a down result rather than a blocker', () => {
+  const copilotPrompt = functionBody('runCopilotGate');
+  const noReviewStart = copilotPrompt.indexOf('No review after');
+  assert.notEqual(noReviewStart, -1, 'expected a no-show branch in the gate prompt');
+  const noReviewBranch = copilotPrompt.slice(noReviewStart, noReviewStart + 200);
+  assert.match(
+    noReviewBranch,
+    /down:\s*true/,
+    'expected a Copilot no-show after the poll cap to return down:true',
+  );
+  assert.doesNotMatch(
+    noReviewBranch,
+    /blocker:/,
+    'expected the no-show branch to carry a down result, not a blocker',
+  );
+});
+
+test('checkConvergence wires the --copilot-down flag from a copilotDown argument', () => {
+  const checkConvergenceBody = functionBody('checkConvergence');
+  assert.match(
+    checkConvergenceBody,
+    /copilotDown \? ' --copilot-down' : ''/,
+    'expected checkConvergence to append --copilot-down when copilotDown is set',
+  );
+  assert.match(
+    checkConvergenceBody,
+    /\$\{copilotDownFlag\}/,
+    'expected the --copilot-down flag to be interpolated into the script invocation',
+  );
+});
+
+test('the COPILOT phase routes a down outcome to FINALIZE with the gate bypassed', () => {
+  const copilotPhaseStart = convergeSource.indexOf("if (phase === 'COPILOT') {");
+  assert.notEqual(copilotPhaseStart, -1, 'expected a COPILOT phase block');
+  const downBranchStart = convergeSource.indexOf("copilotOutcome.kind === 'down'", copilotPhaseStart);
+  assert.notEqual(downBranchStart, -1, 'expected the COPILOT phase to handle a down outcome');
+  const downBranch = convergeSource.slice(downBranchStart, downBranchStart + 400);
+  assert.match(downBranch, /copilotDown = true/);
+  assert.match(downBranch, /copilotNote =/);
+  assert.match(downBranch, /phase = 'FINALIZE'/);
+});
+
+test('resolveCopilotDown reports down only for a down outcome', () => {
+  assert.equal(resolveCopilotDown({ kind: 'down' }), true);
+});
+
+test('resolveCopilotDown clears the bypass for an approved outcome', () => {
+  assert.equal(resolveCopilotDown({ kind: 'approved' }), false);
+});
+
+test('resolveCopilotDown clears the bypass for a fix outcome carrying findings', () => {
+  assert.equal(
+    resolveCopilotDown({
+      kind: 'fix',
+      findings: [
+        {
+          file: 'a.py',
+          line: 1,
+          severity: 'P1',
+          category: 'bug',
+          title: 't',
+          detail: 'd',
+          replyToCommentId: null,
+        },
+      ],
+    }),
+    false,
+  );
+});
+
+test('resolveCopilotDown clears the bypass for a retry outcome', () => {
+  assert.equal(resolveCopilotDown({ kind: 'retry' }), false);
+});
+
+test('the standards-only Copilot sub-path resets copilotDown before FINALIZE', () => {
+  const standardsBranchStart = convergeSource.indexOf(
+    'isStandardsOnlyRound(copilotOutcome.findings)',
+  );
+  assert.notEqual(
+    standardsBranchStart,
+    -1,
+    'expected the COPILOT phase to handle a standards-only Copilot fix outcome',
+  );
+  const standardsBranch = convergeSource.slice(standardsBranchStart, standardsBranchStart + 600);
+  const resetIndex = standardsBranch.indexOf('copilotDown = false');
+  const finalizeIndex = standardsBranch.indexOf("phase = 'FINALIZE'");
+  assert.notEqual(
+    resetIndex,
+    -1,
+    'expected the standards-only sub-path to reset copilotDown so a recovered Copilot is not bypassed',
+  );
+  assert.notEqual(finalizeIndex, -1, 'expected the standards-only sub-path to reach FINALIZE');
+  assert.ok(
+    resetIndex < finalizeIndex,
+    'expected copilotDown to be cleared before the transition to FINALIZE',
+  );
+  assert.match(
+    standardsBranch.slice(0, finalizeIndex),
+    /copilotNote = null/,
+    'expected the standards-only sub-path to clear the stale copilotNote alongside copilotDown',
+  );
+});
+
+test('the COPILOT phase recomputes copilotDown from each gate outcome via resolveCopilotDown', () => {
+  const copilotPhaseStart = convergeSource.indexOf("if (phase === 'COPILOT') {");
+  assert.notEqual(copilotPhaseStart, -1, 'expected a COPILOT phase block');
+  const finalizePhaseStart = convergeSource.indexOf(
+    "if (phase === 'FINALIZE') {",
+    copilotPhaseStart,
+  );
+  assert.notEqual(finalizePhaseStart, -1, 'expected a FINALIZE phase block after COPILOT');
+  const copilotPhase = convergeSource.slice(copilotPhaseStart, finalizePhaseStart);
+  assert.match(
+    copilotPhase,
+    /copilotDown = resolveCopilotDown\(copilotOutcome\)/,
+    'expected the COPILOT phase to recompute copilotDown from the current outcome so a recovered Copilot is never bypassed',
+  );
+});
+
+test('markReady receives copilotDown so it can opt the unflagged hook out of the Copilot gate', () => {
+  const finalizeStart = convergeSource.indexOf("if (phase === 'FINALIZE') {");
+  assert.notEqual(finalizeStart, -1, 'expected a FINALIZE phase block');
+  const markReadyCall = convergeSource.indexOf('await markReady(', finalizeStart);
+  assert.notEqual(markReadyCall, -1, 'expected the FINALIZE phase to call markReady');
+  const callSlice = convergeSource.slice(markReadyCall, markReadyCall + 40);
+  assert.match(
+    callSlice,
+    /markReady\(head,\s*copilotDown\)/,
+    'expected markReady to receive copilotDown so the mark-ready agent can opt the unflagged hook out of the Copilot gate',
+  );
+});
+
+test('the markReady prompt opts the unflagged convergence hook out of Copilot when copilotDown', () => {
+  const markReadyBody = functionBody('markReady');
+  assert.match(
+    markReadyBody,
+    /copilotDown/,
+    'expected markReady to branch on copilotDown',
+  );
+  assert.match(
+    markReadyBody,
+    /CLAUDE_REVIEWS_DISABLED/,
+    'expected the markReady prompt to set CLAUDE_REVIEWS_DISABLED so the unflagged hook re-derives the Copilot bypass',
+  );
+  assert.match(
+    markReadyBody,
+    /copilot/,
+    'expected the markReady opt-out to name the copilot token',
+  );
+});
+