claude-dev-env 1.71.0 → 1.72.0

package/skills/autoconverge/workflow/converge.mjs

@@ -14,6 +14,7 @@ export const meta = {
   description: 'Drive one draft PR to convergence in a single autonomous run: parallel Bugbot + code-review + bug-audit lenses on the same HEAD each round, dedup findings, fix once, re-verify, then a Copilot wait-gate and a final convergence check that marks the PR ready.',
   whenToUse: 'Launched by the /autoconverge skill after it resolves PR scope, enters a worktree, and grants project .claude permissions.',
   phases: [
+    { title: 'Reuse', detail: 'Before convergence, one reuse lens scans the full diff for reuse improvements that are certain, behaviorally identical, and autonomously implementable, and applies the qualifying ones in one commit' },
     { title: 'Converge', detail: 'Bugbot + code-review + bug-audit in parallel each round; one clean-coder applies all fixes; loop until all three are clean on a stable HEAD' },
     { title: 'Copilot gate', detail: 'Request Copilot review and poll up to three times; route findings back into Converge; when Copilot is down or out of quota, log a notice and mark the PR ready with the gate bypassed' },
     { title: 'Finalize', detail: 'Run check_convergence.py; mark draft=false on a full pass' },
@@ -46,6 +47,11 @@ const HEADLESS_SAFETY_PREAMBLE =
 const convergeAgent = (prompt, options) =>
   agent(`${HEADLESS_SAFETY_PREAMBLE}${prompt}`, options)
 
+const PRE_COMMIT_GATE_STEP =
+  `\n\nFINAL STEP — pre-commit gate check (do NOT commit): before your turn ends, prove your working-tree changes CAN be committed by dry-running the CODE_RULES commit gate that gates git commit (precommit_code_rules_gate). From inside the checkout that holds your changes, resolve its root with git rev-parse --show-toplevel, stage your changes with git add -A, then run exactly:\n` +
+  `   python "${CONFIG.prLoopScripts}/code_rules_gate.py" --repo-root "<that root>" --staged\n` +
+  `Exit 0 means the commit gate would accept the commit. On any non-zero exit, read every violation it prints, fix each one test-first per CODE_RULES, and re-run the gate until it exits 0. Then unstage with git restore --staged . so the verify step reads the working-tree diff. Make NO git commit and NO git push here — this is a dry committability check; the separate verify and commit steps run after you, and the verified-commit gate is their job, not yours. Your turn does not end while the commit gate would reject the commit.`
+
 const LENS_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -130,6 +136,28 @@ const REPAIR_EDIT_SCHEMA = {
   required: ['edited', 'rebased', 'resolvedWithoutCommit', 'summary'],
 }
 
+const MERGE_CONFLICT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    conflicting: {
+      type: 'boolean',
+      description: 'true only when GitHub reports the PR branch conflicts with its base (mergeable:false or mergeable_state:dirty); false when it merges cleanly or mergeability could not be computed',
+    },
+  },
+  required: ['conflicting'],
+}
+
+const CONFLICT_EDIT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    rebased: { type: 'boolean', description: 'true when the branch was rebased onto origin/main and every conflict resolved in the working tree' },
+    summary: { type: 'string' },
+  },
+  required: ['rebased', 'summary'],
+}
+
 const STANDARDS_EDIT_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -529,6 +557,19 @@ function isResolvedHeadUsable(resolvedHead) {
   return typeof resolvedHead === 'string' && resolvedHead.length > 0
 }
 
+/**
+ * Decide whether the pre-flight merge-conflict check found the PR branch in
+ * conflict with its base. A dead check agent (null/undefined result) reports
+ * not-conflicting so the run proceeds straight to the bug checks rather than
+ * force-pushing a rebase on a verdict that does not exist — a transient check
+ * failure must never trigger a destructive rebase.
+ * @param {object|null|undefined} mergeState the checkMergeConflicts result
+ * @returns {boolean} true only when the check reported conflicting:true
+ */
+function isMergeConflicting(mergeState) {
+  return mergeState != null && mergeState.conflicting === true
+}
+
 /**
  * Decide whether the mark-ready step actually cleared the draft state. The run
  * reports converged only when the mark-ready agent confirms ready:true; a dead
@@ -749,6 +790,29 @@ function runAuditLens(head) {
   )
 }
 
+/**
+ * Reuse lens: a one-time pre-convergence pass that scans the full diff for
+ * places the PR re-implements behavior the codebase already provides, and
+ * returns only the reuse improvements that are certain, behaviorally identical,
+ * and autonomously implementable. It reports findings without editing; the
+ * reuse pass routes the qualifying findings through applyFixes so they are
+ * implemented in one commit before the convergence rounds begin.
+ * @param {string} head PR HEAD SHA to evaluate
+ * @returns {Promise<object>} LENS_SCHEMA result carrying the qualifying reuse findings
+ */
+function runReuseAuditPass(head) {
+  return convergeAgent(
+    `You are the REUSE lens for ${prCoordinates}, HEAD ${head}. This pass runs once before convergence to find where the PR re-implements behavior the codebase already provides.\n\n` +
+      `Review the FULL origin/main...HEAD diff — every file the PR touches. Do NOT delta-scope to recent commits or a single file. The workflow already fetched origin/main, so do NOT run git fetch; run git diff --name-only origin/main...HEAD to enumerate the changed files, then read the complete diff of each. For every new function, helper, constant, type, or block of logic the PR introduces, search the repository (Serena symbol search, grep, and the project's config/ and shared/ modules) for an existing equivalent that already provides the same behavior.\n\n` +
+      `Report a reuse finding ONLY when ALL THREE criteria hold — when any one is in doubt, omit the finding:\n` +
+      `  A. CERTAIN: an existing symbol or module unquestionably covers the new code's behavior, and you can cite it at file:line.\n` +
+      `  B. BEHAVIORALLY IDENTICAL: replacing the new code with the existing one changes no observable behavior — same inputs, outputs, side effects, and error handling.\n` +
+      `  C. AUTONOMOUSLY IMPLEMENTABLE: the replacement is a mechanical edit (import and call the existing symbol, delete the duplicate) that needs no product decision, no API the existing code lacks, and no human judgment.\n\n` +
+      `Do NOT edit, commit, or push — report only; a separate fix step applies what you return. Return strictly the schema: clean=true with empty findings when no reuse case clears all three criteria, otherwise one entry per qualifying reuse improvement. For each: file and line of the duplicate in the PR; severity P2; category 'code-standard'; title naming the existing symbol to reuse; detail giving the existing symbol's file:line and the exact mechanical replacement; replyToCommentId=null. Set sha=${'`'}${head}${'`'}, down=false.`,
+    { label: 'lens:reuse', phase: 'Reuse', schema: LENS_SCHEMA, agentType: 'code-quality-agent' },
+  )
+}
+
 /**
  * Render the numbered findings block shared by the fix steps.
  * @param {Array<object>} findings deduped findings to render
@@ -792,7 +856,8 @@ function applyFixesEdit(head, findings, sourceLabel) {
       `Return values:\n` +
       `- When you edited code to fix at least one finding: edited=true, resolvedWithoutCommit=false.\n` +
       `- When every finding was already addressed so no code change was needed — yet you still resolved each GitHub review thread above: edited=false, resolvedWithoutCommit=true. Only set this when every thread that carries a comment id is resolved; otherwise the round is treated as stalled.\n` +
-      `Always include a one-line summary.`,
+      `Always include a one-line summary.` +
+      PRE_COMMIT_GATE_STEP,
     { label: `fix-edit:${sourceLabel}`, phase: 'Converge', schema: EDIT_SCHEMA, agentType: 'clean-coder' },
   )
 }
@@ -865,7 +930,8 @@ function recoverCommitBlockEdit(head, blockerDetail, sourceLabel, attempt) {
       `- Confirm the working tree is on the PR branch at HEAD ${head} with the prior fixes still present.\n` +
       `- Fix ONLY the violation named above, test-first (failing test, then minimum code to pass) per CODE_RULES. Do not re-open the original findings, and do not touch GitHub review threads — the edit step already handled those.\n` +
       `- Leave the corrected fixes in the working tree. Do NOT commit and do NOT push — the verify step re-binds a verdict and the commit step pushes after you.\n\n` +
-      `Return values: edited=true with a one-line summary when you changed code to clear the block; edited=false, resolvedWithoutCommit=false when the block cannot be cleared with a code change.`,
+      `Return values: edited=true with a one-line summary when you changed code to clear the block; edited=false, resolvedWithoutCommit=false when the block cannot be cleared with a code change.` +
+      PRE_COMMIT_GATE_STEP,
     { label: `fix-recover:${sourceLabel}`, phase: 'Converge', schema: EDIT_SCHEMA, agentType: 'clean-coder' },
   )
 }
@@ -891,7 +957,8 @@ function recoverVerifyFailEdit(head, objection, sourceLabel, attempt) {
       `- Confirm the working tree is on the PR branch at HEAD ${head} with the prior fixes still present.\n` +
       `- Address every objection above test-first (failing test, then minimum code to pass) per CODE_RULES, so each named concern is genuinely resolved the way the verdict requires. Do not touch GitHub review threads — the edit step already handled those.\n` +
       `- Leave the corrected fixes in the working tree. Do NOT commit and do NOT push — the verify step re-binds a verdict and the commit step pushes after you.\n\n` +
-      `Return values: edited=true with a one-line summary when you changed code to address the objections; edited=false, resolvedWithoutCommit=false when the objections cannot be cleared with a code change.`,
+      `Return values: edited=true with a one-line summary when you changed code to address the objections; edited=false, resolvedWithoutCommit=false when the objections cannot be cleared with a code change.` +
+      PRE_COMMIT_GATE_STEP,
     { label: `fix-verify-recover:${sourceLabel}`, phase: 'Converge', schema: EDIT_SCHEMA, agentType: 'clean-coder' },
   )
 }
@@ -1130,7 +1197,8 @@ function repairConvergenceEdit(head, failures) {
       `- edited=true when you changed code in the working tree to fix a bot-thread concern.\n` +
       `- rebased=true when you rebased the branch onto origin/main.\n` +
       `- resolvedWithoutCommit=true only when you addressed the gates with neither a code change nor a rebase (bot threads resolved only), so there is nothing for the commit step to push.\n` +
-      `Always include a one-line summary.`,
+      `Always include a one-line summary.` +
+      PRE_COMMIT_GATE_STEP,
     { label: 'repair-edit', phase: 'Finalize', schema: REPAIR_EDIT_SCHEMA, agentType: 'clean-coder' },
   )
 }
@@ -1235,6 +1303,79 @@ async function repairConvergence(head, failures) {
   })
 }
 
+/**
+ * Pre-flight merge-conflict check: ask GitHub whether the PR branch still merges
+ * cleanly into its base. GitHub computes mergeability asynchronously, so the
+ * agent polls until .mergeable resolves to a boolean before judging. Read-only —
+ * it makes no edit, commit, push, or rebase.
+ * @param {string} head PR HEAD SHA the check runs against
+ * @returns {Promise<object>} MERGE_CONFLICT_SCHEMA result
+ */
+function checkMergeConflicts(head) {
+  return convergeAgent(
+    `Report whether ${prCoordinates} (HEAD ${head}) has merge conflicts with its base branch. Do not edit, commit, push, or rebase — read only.\n\n` +
+      `GitHub computes mergeability asynchronously, so .mergeable is null right after a push until it finishes. Poll until it resolves: run\n` +
+      `   gh api repos/${input.owner}/${input.repo}/pulls/${input.prNumber} --jq '{mergeable: .mergeable, state: .mergeable_state}'\n` +
+      `up to 5 times, 5 seconds apart (delay each retry with "sleep 5", or the PowerShell alternative "Start-Sleep -Seconds 5"), stopping as soon as mergeable is true or false.\n\n` +
+      `Return conflicting:true when mergeable is false or state is "dirty" (the branch conflicts with the base). Return conflicting:false when mergeable is true, or when mergeable stays null after the full poll budget — mergeability is unknown, so let the bug checks proceed rather than rebase on a guess.`,
+    { label: 'check-merge-conflicts', phase: 'Converge', schema: MERGE_CONFLICT_SCHEMA, agentType: 'Explore' },
+  )
+}
+
+/**
+ * Conflict-resolution edit step: one clean-coder rebases the PR branch onto
+ * origin/main and resolves every conflict in the working tree, making NO push —
+ * the verify step binds a verdict to the rebased tree before the commit step
+ * force-pushes it. A rebase necessarily creates local commits, which is expected;
+ * only the force-push is withheld so the verifier binds the surface first.
+ * @param {string} head PR HEAD SHA before the rebase
+ * @returns {Promise<object>} CONFLICT_EDIT_SCHEMA result
+ */
+function resolveConflictsEdit(head) {
+  return convergeAgent(
+    `You are the EDIT step resolving merge conflicts for ${prCoordinates}, HEAD ${head}, before the bug checks run. The PR branch conflicts with origin/main. A separate verify step then a separate commit step run after you.\n\n` +
+      `Rules:\n` +
+      `- Confirm the working tree is on the PR branch at HEAD ${head} with no unrelated edits before you start.\n` +
+      `- Rebase the branch onto origin/main and resolve every conflict so the tree is clean and conflict-free: git fetch origin main; git rebase origin/main; resolve each conflict, preserving the intent of both the PR's change and the incoming base change. A rebase creates local commits, which is fine.\n` +
+      `- Do NOT push and do NOT force-push — the commit step force-pushes after the verify step binds a verdict. Pushing here would change the surface the verifier binds to.\n\n` +
+      `Return rebased=true with a one-line summary when you rebased onto origin/main and resolved the conflicts; rebased=false with a summary when the branch did not actually need a rebase or you could not complete it.`,
+    { label: 'resolve-conflicts-edit', phase: 'Converge', schema: CONFLICT_EDIT_SCHEMA, agentType: 'clean-coder' },
+  )
+}
+
+/**
+ * Pre-flight conflict resolution: when the PR branch conflicts with its base,
+ * rebase it clean before the bug checks run — check (Explore probes mergeability)
+ * -> edit (clean-coder rebases and resolves, no push) -> verify (code-verifier
+ * binds a verdict to the rebased tree) -> commit (clean-coder force-with-lease
+ * pushes). Returns the post-rebase HEAD so the first converge round runs its
+ * lenses on the conflict-free diff. A non-conflicting PR, a rebase the edit step
+ * declined, or a failed verdict returns the unchanged HEAD so the run proceeds to
+ * the bug checks unchanged. A mid-run conflict (origin/main advancing later) is
+ * still caught by the FINALIZE convergence repair, which also rebases.
+ * @param {string} head PR HEAD SHA before any rebase
+ * @returns {Promise<string>} the HEAD SHA after a successful rebase push, or the unchanged head
+ */
+async function resolveMergeConflicts(head) {
+  const mergeState = await checkMergeConflicts(head)
+  if (!isMergeConflicting(mergeState)) return head
+  log(`Pre-flight: ${prCoordinates} conflicts with origin/main — rebasing clean before the bug checks`)
+  const editResult = await resolveConflictsEdit(head)
+  if (editResult?.rebased !== true) return head
+  const failures = ['PR branch had merge conflicts with origin/main; the rebase must leave a clean, conflict-free tree']
+  const verifyTranscript = await verifyWithRecovery({
+    runVerify: () => verifyRepairChanges(head, failures),
+    runRecoverEdit: (objection, attempt) => recoverVerifyFailEdit(head, objection, 'conflict-rebase', attempt),
+  })
+  if (!verdictPassed(verifyTranscript)) return head
+  const commitResult = await commitWithRecovery({
+    runCommit: () => commitRepairFixes(head, true),
+    runVerify: () => verifyRepairChanges(head, failures),
+    runRecoverEdit: (detail, attempt) => recoverCommitBlockEdit(head, detail, 'conflict-rebase', attempt),
+  })
+  return commitResult?.newSha || head
+}
+
 /**
  * Decide whether a review round surfaced ONLY code-standard violations — pure
  * CODE_RULES/style findings with no behavioral impact. Such a round passes for
@@ -1269,7 +1410,8 @@ function standardsFollowUpEdit(head, findings, sourceLabel) {
       `1. Follow-up fix issue: file a GitHub issue on ${input.owner}/${input.repo} (gh issue create --body-file with a temp file) titled "Deferred code-standard fixes from PR #${input.prNumber}". The body references the PR and lists each finding with its file:line, severity, and detail. The issue carries the fix work; do not open a fix PR. Capture the issue URL.\n` +
       `2. Stage the environment-hardening change: in the Claude environment config repo (the repo owning ~/.claude hooks and rules — JonEcho/llm-settings for hooks, jl-cmd/claude-code-config for rules/skills; pick whichever owns the surface that would block these violation classes), find or clone a local checkout, fetch origin, and create a branch off origin/main. Edit the hooks/rules in that checkout's WORKING TREE so each violation class found here is blocked at Write/Edit time, before code is written. Do NOT commit and do NOT push — the commit step does that after the verify step binds a verdict to the working tree. Return the checkout's absolute path in hardeningRepoPath, the branch name in hardeningBranch, and set hardeningEdited=true. When no hardening is feasible for these classes, leave hardeningRepoPath and hardeningBranch empty and hardeningEdited=false; the follow-up issue still stands.\n` +
       `3. For each finding that carries a GitHub review comment id (${threadIds.length ? threadIds.join(', ') : 'none this batch'}): post an inline reply via python "${CONFIG.sharedScripts}/post_fix_reply.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --in-reply-to <id> --body "Code-standard-only finding — deferred to follow-up issue <url>." Then resolve the thread by its PRRT_ node id (GraphQL lookup on comment databaseId, then resolveReviewThread or the github MCP pull_request_review_write method=resolve_thread — not the numeric comment id).\n\n` +
-      `Return the issue URL in issueUrl (empty string when it could not be filed), the hardening checkout path and branch, hardeningEdited, and a one-line summary.`,
+      `Return the issue URL in issueUrl (empty string when it could not be filed), the hardening checkout path and branch, hardeningEdited, and a one-line summary.` +
+      PRE_COMMIT_GATE_STEP,
     { label: `standards-edit:${sourceLabel}`, phase: 'Converge', schema: STANDARDS_EDIT_SCHEMA, agentType: 'clean-coder' },
   )
 }
@@ -1428,9 +1570,36 @@ let bugbotDown = input.bugbotDisabled || false
 let copilotDown = false
 let copilotNote = null
 let standardsNote = null
+let reuseNote = null
 const allRoundFindings = []
 const fixSummaries = []
 
+const preflightHead = await resolveHead()
+if (isResolvedHeadUsable(preflightHead)) {
+  await resolveMergeConflicts(preflightHead)
+}
+
+log('Reuse pass: scanning the full diff for certain, behaviorally identical, autonomously implementable reuse improvements before convergence')
+const reuseHead = await resolveHead()
+if (isResolvedHeadUsable(reuseHead)) {
+  await prefetchMainForRound()
+  const reuse = await runReuseAuditPass(reuseHead)
+  const reuseFindings = reuse?.findings || []
+  if (reuseFindings.length > 0) {
+    log(`Reuse pass: ${reuseFindings.length} qualifying reuse improvement(s) — applying before convergence`)
+    allRoundFindings.push(...reuseFindings)
+    const reuseFix = await applyFixes(reuseHead, reuseFindings, 'reuse-pass')
+    if (reuseFix?.summary) fixSummaries.push(reuseFix.summary)
+    reuseNote = reuseFix?.pushed === true
+      ? `${reuseFindings.length} reuse improvement(s) applied before convergence (${reuseFix.newSha?.slice(0, SHA_COMPARISON_PREFIX_LENGTH)})`
+      : `${reuseFindings.length} reuse improvement(s) identified before convergence but not landed — the code-review lens re-surfaces any that remain`
+  } else {
+    log('Reuse pass: no reuse case cleared all three criteria — proceeding to convergence')
+  }
+} else {
+  log('Reuse pass: could not resolve HEAD — proceeding to convergence')
+}
+
 while (iterations < CONFIG.maxIterations) {
   iterations += 1
   if (phase === 'CONVERGE') {
@@ -1556,7 +1725,7 @@ while (iterations < CONFIG.maxIterations) {
       const readyOutcome = classifyReadyOutcome(readyResult)
       if (readyOutcome.converged) {
         await spawnConvergenceSummary(dedupeFindings(allRoundFindings), fixSummaries, rounds, standardsNote, copilotNote)
-        return { converged: true, rounds, finalSha: head, blocker: null, standardsNote, copilotNote }
+        return { converged: true, rounds, finalSha: head, blocker: null, standardsNote, copilotNote, reuseNote }
       }
       blocker = readyOutcome.blocker
       break
@@ -1575,4 +1744,5 @@ return {
   blocker: blocker || `iteration cap reached (${CONFIG.maxIterations})`,
   standardsNote,
   copilotNote,
+  reuseNote,
 }

package/skills/bugteam/scripts/bugteam_code_rules_gate.py

@@ -544,6 +544,48 @@ def check_database_column_string_magic(content: str, file_path: str) -> list[str
     return issues
 
 
+def is_test_path(file_path: str) -> bool:
+    """Return True when *file_path* matches CODE_RULES.md test-file detection patterns.
+
+    Mirrors the test-file detection rule documented in CODE_RULES.md:
+    filename matches test_*.py OR *_test.py OR *.test.* OR *.spec.* OR
+    conftest.py, OR path contains the segment /tests/.
+
+    Args:
+        file_path: Path string to classify; backslashes are normalized to
+            forward slashes before pattern matching.
+
+    Returns:
+        True when the path matches any test-file pattern; False otherwise.
+    """
+    tests_path_segment = "/tests/"
+    conftest_filename = "conftest.py"
+    test_filename_prefix = "test_"
+    all_test_filename_suffixes = ("_test.py",)
+    all_test_filename_glob_suffixes = (".test.", ".spec.")
+    normalized_posix = file_path.replace("\\", "/")
+    filename_only = normalized_posix.rsplit("/", maxsplit=1)[-1]
+    if tests_path_segment in normalized_posix:
+        return True
+    if filename_only == conftest_filename:
+        return True
+    if filename_only.startswith(test_filename_prefix) and filename_only.endswith(
+        PYTHON_FILE_EXTENSION
+    ):
+        return True
+    if any(
+        filename_only.endswith(each_suffix)
+        for each_suffix in all_test_filename_suffixes
+    ):
+        return True
+    if any(
+        each_glob_suffix in filename_only
+        for each_glob_suffix in all_test_filename_glob_suffixes
+    ):
+        return True
+    return False
+
+
 def _iter_calls_excluding_nested_functions(node: ast.AST) -> Iterator[ast.Call]:
     for each_child in ast.iter_child_nodes(node):
         if isinstance(each_child, (ast.FunctionDef, ast.AsyncFunctionDef)):
@@ -636,11 +678,11 @@ def check_wrapper_plumb_through(content: str, file_path: str) -> list[str]:
     Args:
         content: File content as a single string for AST parsing.
         file_path: Repository-relative POSIX path of the file (used to
-            skip non-Python code extensions early).
+            skip non-Python code extensions and test files early).
 
     Returns:
-        List of violation strings, one per dropped optional kwarg. Returns
-        an empty list when the file is not Python or has a syntax error.
+        List of violation strings, one per dropped optional kwarg. Empty for
+        a non-Python file, a test file, or a file with a syntax error.
     """
     non_python_code_extensions = ALL_CODE_FILE_EXTENSIONS - {PYTHON_FILE_EXTENSION}
     lowercase_file_path = file_path.lower()
@@ -649,6 +691,8 @@ def check_wrapper_plumb_through(content: str, file_path: str) -> list[str]:
         for each_extension in non_python_code_extensions
     ):
         return []
+    if is_test_path(file_path):
+        return []
     try:
         tree = ast.parse(content)
     except SyntaxError:

package/skills/bugteam/scripts/test_bugteam_code_rules_gate.py

@@ -790,6 +790,40 @@ def test_check_wrapper_plumb_through_flags_name_call_dropping_kwarg() -> None:
     )
 
 
+def test_check_wrapper_plumb_through_exempts_test_files() -> None:
+    """A test_* function in a test-file path that calls a module-level helper
+    exposing an optional kwarg is an ordinary pytest case, not a wrapper; the
+    bugteam gate must exempt test files and emit zero findings."""
+    source = (
+        "def _helper(name, *, clean_name=None):\n"
+        "    return (name, clean_name)\n"
+        "\n"
+        "def test_uses_helper():\n"
+        "    return _helper('a', clean_name='b')\n"
+    )
+    issues = gate_module.check_wrapper_plumb_through(source, "pkg/test_thing.py")
+    assert issues == [], (
+        f"a wrapper shape in a test file must yield no findings; got {issues!r}"
+    )
+
+
+def test_check_wrapper_plumb_through_still_flags_non_test_path_with_test_shape() -> None:
+    """The test-file exemption is scoped to test paths only; the same wrapper
+    shape on a non-test path must still be flagged."""
+    source = (
+        "def _helper(name, *, clean_name=None):\n"
+        "    return (name, clean_name)\n"
+        "\n"
+        "def test_uses_helper():\n"
+        "    return _helper('a', clean_name='b')\n"
+    )
+    issues = gate_module.check_wrapper_plumb_through(source, "pkg/module.py")
+    assert any(
+        "test_uses_helper" in each_issue and "clean_name" in each_issue
+        for each_issue in issues
+    ), f"the same wrapper shape on a non-test path must still flag; got {issues!r}"
+
+
 def test_check_wrapper_plumb_through_ignores_calls_nested_inside_delegate_arguments() -> None:
     """A callee nested as an argument (``delegate(helper(x))``) is not a
     separate call site; only the enclosing call is inspected, matching the