@@ -317,11 +317,32 @@ def _log_path(project_root: Path, lang: str) -> Path:
     return Path(tempfile.gettempdir()) / f"codeguard-gate-{key}-{lang}.log"
 
 
+def _rule_summary(full: str) -> str:
+    """ruff/checkstyle 输出的规则聚合计数行（如 "EXE001×3 UP009×1"）。
+
+    2026-09-23 opencli 会话实测：门禁输出被截断后 AI 修一个才暴露下一个
+    （whack-a-mole 升级版），聚合计数让 AI 一次看到问题全集与规模。
+    非 linter 标准行格式（无规则码锚）时返回空串。
+    """
+    import re as _re
+    counts: dict[str, int] = {}
+    for line in full.splitlines():
+        m = _re.search(r"\b([A-Z]{2,5}\d{3,4})\b", line)
+        if m and (":" in line or "-->" in line):
+            counts[m.group(1)] = counts.get(m.group(1), 0) + 1
+    if not counts:
+        return ""
+    return "规则汇总: " + " ".join(f"{k}×{v}" for k, v in sorted(counts.items()))
+
+
 def _truncate_detail(full: str, project_root: Path, lang: str) -> str:
     """节选 + 总量 + 完整日志路径：截断只留头 600 字符会让 AI 一次修 3 个、
     重试再看 3 个（whack-a-mole）；必须给出"共几行、完整在哪"。"""
     lines = [ln for ln in full.splitlines() if ln.strip()]
+    summary_line = _rule_summary(full)
     detail = full[:600]
+    if summary_line:
+        detail = summary_line + "\n" + detail
     if len(lines) > 8 or len(full) > 600:
         try:
             path = _log_path(project_root, lang)
@@ -415,7 +436,9 @@ def check(lang: str):
             if outcome["status"] == "PASS":
                 return None
             if outcome["status"] != "FAIL":
-                return (lang, None, f"java {outcome['status']}: {outcome['reason']}")
+                hint_extra = "；若 wrapper 缺执行位：chmod +x mvnw" \
+                    if "不可执行" in outcome.get("reason", "") else ""
+                return (lang, None, f"java {outcome['status']}: {outcome['reason']}{hint_extra}")
             detail = _truncate_detail(outcome.get("stdout_tail", "") + outcome.get("stderr_tail", ""), project_root, lang)
             if outcome.get("log_path"):
                 detail += f"\n完整输出: {outcome['log_path']}"
@@ -470,7 +493,7 @@ def check(lang: str):
                     return (lang, None,
                             (f"{lang} 项目分析 UNVERIFIED（{_jp.get('build_system', '?')}），"
                              f"原因: {'; '.join(_jp.get('reasons', []))}，本次未验证"))
-                exe = _jp.get("executable")
+                exe = _java_executable_from_plan(_jp)
                 if exe and base_cmd and base_cmd[0] in ("mvn", "gradle"):
                     base_cmd = [exe] + base_cmd[1:]
             except Exception as exc:  # noqa: BLE001 — 分析失败不阻塞门禁，走原路径
@@ -627,6 +650,26 @@ def _openspec_validate(project_root: Path, timeout_seconds: int = 300) -> dict:
     hint = "见 https://openspec.dev 或 `npm i -g @fission-ai/openspec`"
     return {"failures": [("openspec", detail, fix, hint)], "skipped": None}
 
+def _java_executable_from_plan(plan: dict) -> str | None:
+    """从 java_project.analyze 的产物里解析构建可执行文件。
+
+    两条来源按优先级：
+    1. 顶层 ``executable`` 键（java_project 正常产出）；
+    2. 回退 ``commands[0].argv[0]``——历史版本的 java_project 只把
+       wrapper 体现在计划命令里（实测 68c8a37 曾因此让 mvnw 感知成为
+       死代码：消费者读的键生产者从不写）。
+    非 mvn/gradle wrapper（如 codeguard.json 显式命令）不参与替换。
+    """
+    exe = plan.get("executable")
+    if exe:
+        return exe
+    for cmd in plan.get("commands", []) or []:
+        argv = cmd.get("argv") or []
+        if argv and Path(argv[0]).name in ("mvnw", "gradlew"):
+            return argv[0]
+    return None
+
+
 def skip_gate_via_git_config(project_root: Path) -> bool:
     """仓库级豁免：git config codeguard.skipGate true。
 
@@ -861,6 +904,8 @@ def _failure_detail_blocks(failures: list, *, fix_first: bool = False) -> list[s
             f"  ▶ 怎么修: {fix}",
             f"  ▶ 未安装工具时先安装: {hint}",
         ]
+        if lang == "python" and "[*]" in (detail or ""):
+            tail.append("  ▶ 含 [*] 可自动修复项: ruff check --fix <涉及路径>")
         body = detail if detail else "  lint 退出码非零，无文本输出"
         if fix_first:
             block += tail + [body]
@@ -886,19 +931,24 @@ def format_failure_report(failures: list) -> str:
     return "\n".join(lines)
 
 
-def gate_directive(failures: list) -> str:
+def gate_directive(failures: list, project_root: Path | str | None = None) -> str:
     """给 AI 的行动指令：收到后应立即修复并重新提交，而不是询问用户。
 
+    project_root：本次门禁的目标仓库根——cwd 漂移会让钩子扫到"非目标仓"
+    （实测：在 codex 仓 cwd 下提交 opencli，POM 4.1.0 报错让人以为改错了
+    文件），首行显式标注目标仓库可第一时间发现扫错对象。
+
     结构 = 综述（首行契约）→ 强制指令（前置！）→ 每语言细节（fix 先于
     detail）→ 修复入口；整体压到 REPORT_MAX_CHARS 内。指令必须前置：宿主把
     超长 stderr 从尾部截断，此前指令在报告末段，长报告下 AI 只看到首段 linter
     报错、「拆两次调用」与 skipGate 逃生门全部丢失（实测）。首行仍为综述、
     综述不重复、含「具体问题」——run_all/硬门禁契约保持。
     """
+    head_repo = f"本次门禁目标仓库: {Path(project_root).resolve()}\n" if project_root else ""
     header = [
         summarize_failures(failures),
         f"codeguard v{CODEGUARD_VERSION}",
-        "─" * 60,
+        head_repo + "─" * 60,
         "**给 AI 的强制指令**：提交门禁未通过，禁止执行 git commit / git push。\n"
         + "**⚠️ 整个工具调用没有执行**：被拦截的是一次包含 git commit/push 的完整 Bash "
         "调用——其中非 git 的前序步骤（写文件、跑脚本）也全部未运行。请把「修复」与"
@@ -914,7 +964,8 @@ def gate_directive(failures: list) -> str:
         + "确需绕过（仅用户明确要求时）：**单次豁免**用 `git -c codeguard.skipGate=true commit …`"
         "（不落配置、无残留，推荐）；**仓库级豁免**在该仓库执行 git config codeguard.skipGate true，"
         "完成后 git config --unset codeguard.skipGate 恢复。环境变量 CODEGUARD_SKIP_GATE "
-        "只对手动直调 run_check 有效（无法传入宿主钩子进程）。两种豁免都会记入会话审计明细。",
+        "只对手动直调 run_check 有效（无法传入宿主钩子进程）。两种豁免都会记入会话审计明细。"
+        "注意：仓库级豁免对该克隆**所有分支**生效且跨会话残留，务必按上方说明 unset 恢复。",
         "─" * 60,
     ]
     footer = f"一键尝试自动修复: python3 {PLUGIN_ROOT}/scripts/fix.py"
 
@@ -652,7 +652,7 @@ def main() -> int:
         if failures:
             # 版本自标识由 gate_directive 首行综述之后的第二行承担——
             # 此处不再前置横幅：stderr 首行必须是综述（三个契约测试锁定）。
-            reports.append(gate_directive(failures))
+            reports.append(gate_directive(failures, project_root=project_root))
         unknown = [s for s in _skipped if "本次改动未涉及" not in s and " SKIPPED:" not in s
                    and "markdown 风格告警" not in s]
         if unknown:
 
@@ -236,6 +236,10 @@ def analyze(project_root: str | Path, changed: list[str] | None = None) -> dict:
         executable = "./" + wrapper if (root / wrapper).is_file() else ("mvn" if system == "maven" else "gradle")
         if (root / wrapper).exists() and os.name != "nt" and not os.access(root / wrapper, os.X_OK):
             raise ValueError(f"wrapper 不可执行: {wrapper}")
+        # 顶层 executable 键：门禁消费者（gate_lib Java 门禁）直接读取，
+        # 用于把 PATH 上的 mvn/gradle 替换为项目自带 wrapper——
+        # POM 4.1.0 等 Maven 4 仓库在 Maven 3 下必然解析失败（实测）。
+        plan["executable"] = executable
         relevant = None if changed is None else [p for p in changed if p.endswith((".java", ".kt", ".groovy", ".scala"))
                                                  or "/src/" in "/" + p
                                                  or Path(p).name in _BUILD_FILES or p.startswith((".mvn/", "gradle/"))]
 
@@ -50,6 +50,31 @@
 )
 
 
+def is_git_repo(root: str | Path) -> bool:
+    """路径自身是否为 git 仓（.git 存在）。"""
+    return (Path(root) / ".git").exists()
+
+
+def child_git_repo_names(root: str | Path) -> list[str]:
+    """扫描根**不是** git 仓（典型：会话工作区根）时，列出其下自带 .git
+    的直接子目录名。
+
+    这些子目录是独立仓库、由它们各自的提交门禁负责；非 git 根的全量扫描
+    若把它们一并扫进去，就会出现"提交 A 仓却被 B 仓的存量问题拦截"的
+    跨仓误伤（2026-09-23 opencli-java-sdk 会话实测：workspace 根的
+    push-all-branches.sh 触发门禁时，根级脚本与子仓文件混在同一份报告里）。
+    根级别的散文件（不属于任何子仓）仍保留在扫描面内——它们没有别的门禁。
+    """
+    out: list[str] = []
+    try:
+        for child in sorted(Path(root).iterdir()):
+            if child.is_dir() and (child / ".git").exists():
+                out.append(child.name)
+    except OSError:
+        pass
+    return out
+
+
 def is_build_artifact(path: str | Path) -> bool:
     """路径是否落在构建产物/依赖快照目录下（任一段命中即算）。
 
@@ -63,7 +88,7 @@ def is_build_artifact(path: str | Path) -> bool:
 _RUFF_SNIPPET = Path(__file__).resolve().parents[1] / "linters" / "ruff" / "ruff.toml"
 
 
-def _inject_find_excludes(expr: str) -> str:
+def _inject_find_excludes(expr: str, excludes: tuple[str, ...] | list[str] = FULL_SCAN_EXCLUDES) -> str:
     """给 `find …` 型 gate 表达式注入构建产物目录排除（-not -path）。
 
     覆盖三种实测形态——只认一种就有整族门禁漏网：
@@ -79,7 +104,7 @@ def _inject_find_excludes(expr: str) -> str:
         return expr
     additions = "".join(
         f" -not -path '*/{d}/*'"
-        for d in FULL_SCAN_EXCLUDES
+        for d in excludes
         if f"'*/{d}/*'" not in expr and f"'*/{d}'" not in expr
     )
     if not additions:
@@ -179,16 +204,22 @@ def scope_cmd(
     if not out:
         return out
     targets = [single_file] if single_file else list(files or [])
+    root = Path(project_root)
+    # 非 git 根（会话工作区）的全量扫描：排除子 git 仓——它们由各自的
+    # 提交门禁负责，混进来就是跨仓误伤（见 child_git_repo_names）。
+    scan_excludes = list(FULL_SCAN_EXCLUDES)
+    if full_excludes and not is_git_repo(root):
+        scan_excludes += child_git_repo_names(root)
     if "{file}" in " ".join(out):
         return [c.replace("{file}", single_file or "") for c in out]
     if out[0] == "ruff":
         args = ruff_config_args(out, project_root)
         out = [out[0]] + args + out[1:]
         if full_excludes:
-            for d in FULL_SCAN_EXCLUDES:
+            for d in scan_excludes:
                 out += ["--exclude", d]
     elif full_excludes:
-        out = [_inject_find_excludes(c) if isinstance(c, str) else c for c in out]
+        out = [_inject_find_excludes(c, scan_excludes) if isinstance(c, str) else c for c in out]
     scan_idx = [i for i, tok in enumerate(out[1:], 1) if tok == "." or "**" in tok]
     if targets and scan_idx:
         flags = [tok for i, tok in enumerate(out) if i not in scan_idx and not tok.startswith("#")]
 
@@ -0,0 +1,172 @@
+"""2026-09-23 opencli/codex 双 SDK 发布会话实测痛点的修复回归。
+
+锚定四个实测坑：
+- POM 4.1.0 + mvnw 仓库：gate_lib 的 mvnw 感知读取的 `executable` 键
+  生产者（java_project）从不产出 → 感知死代码，门禁退回裸 mvn 必失败；
+- 门禁目标仓库不显式：cwd 漂移后 AI 以为改的是 A 仓，实际门禁扫的是 B 仓；
+- ruff [*] 可自动修复项藏在长输出尾部，AI 修完才发现有捷径；
+- 仓库级 skipGate 对该克隆所有分支生效且跨会话残留，提示里没有作用域警告。
+"""
+from __future__ import annotations
+
+import os
+import stat
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+PLUGIN = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(PLUGIN / "hooks"))
+sys.path.insert(0, str(PLUGIN / "scripts"))
+
+import gate_lib
+import scope
+from java_project import analyze
+
+
+class JavaExecutableContractTest(unittest.TestCase):
+    """生产者-消费者契约：java_project 必须产出顶层 executable 键。
+
+    68c8a37 曾让 mvnw 感知成为死代码——消费者读的键生产者从不写，
+    两侧各自的测试都绿，合在一起门禁照旧退回裸 mvn（实测）。
+    """
+
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.root = Path(self.tmp.name)
+        (self.root / "pom.xml").write_text(
+            '<project xmlns="http://maven.apache.org/POM/4.1.0">'
+            "<modelVersion>4.1.0</modelVersion></project>", encoding="utf-8")
+
+    def test_executable_wrapper_present_and_executable(self):
+        mvnw = self.root / "mvnw"
+        mvnw.write_text("#!/bin/sh\nexit 0\n")
+        mvnw.chmod(0o755)
+        plan = analyze(str(self.root))
+        self.assertEqual(plan["status"], "PLANNED")
+        self.assertEqual(plan.get("executable"), "./mvnw",
+                         "生产者必须产出顶层 executable 键（门禁消费者直接读取）")
+
+    def test_executable_wrapper_missing_falls_back_to_mvn(self):
+        plan = analyze(str(self.root))
+        self.assertEqual(plan.get("executable"), "mvn")
+
+    def test_executable_wrapper_not_executable_is_unverified(self):
+        mvnw = self.root / "mvnw"
+        mvnw.write_text("#!/bin/sh\nexit 0\n")
+        mvnw.chmod(0o644)
+        plan = analyze(str(self.root))
+        self.assertEqual(plan["status"], "UNVERIFIED")
+        self.assertTrue(any("不可执行" in r for r in plan["reasons"]))
+
+
+class JavaExecutableFromPlanTest(unittest.TestCase):
+    """消费者纯函数：两条来源优先级 + 非包装器不参与。"""
+
+    def test_prefers_top_level_key(self):
+        plan = {"executable": "./mvnw",
+                "commands": [{"argv": ["mvn", "verify"]}]}
+        self.assertEqual(gate_lib._java_executable_from_plan(plan), "./mvnw")
+
+    def test_falls_back_to_wrapper_in_command_argv(self):
+        plan = {"commands": [{"argv": ["./mvnw", "-B", "verify"]}]}
+        self.assertEqual(gate_lib._java_executable_from_plan(plan), "./mvnw")
+
+    def test_ignores_non_wrapper_command_heads(self):
+        plan = {"commands": [{"argv": ["mvn", "verify"]}]}
+        self.assertIsNone(gate_lib._java_executable_from_plan(plan))
+
+    def test_empty_plan_returns_none(self):
+        self.assertIsNone(gate_lib._java_executable_from_plan({}))
+
+
+class DirectiveRepoLabelTest(unittest.TestCase):
+    """目标仓库首行：cwd 漂移扫到非目标仓时，AI 第一眼就能发现。"""
+
+    def test_directive_names_target_repo_when_root_given(self):
+        report = gate_lib.gate_directive(
+            [("shell", "EXE001 detail", "fix cmd", "hint")],
+            project_root="/tmp/some-repo")
+        self.assertIn("本次门禁目标仓库", report)
+        self.assertIn("/tmp/some-repo", report)
+
+    def test_directive_without_root_omits_label(self):
+        report = gate_lib.gate_directive(
+            [("shell", "detail", "fix", "hint")])
+        self.assertNotIn("本次门禁目标仓库", report)
+
+    def test_directive_warns_clone_wide_scope_of_repo_level_skip(self):
+        report = gate_lib.gate_directive(
+            [("shell", "detail", "fix", "hint")],
+            project_root="/tmp/some-repo")
+        self.assertIn("所有分支", report)
+
+
+class PythonFixableHintTest(unittest.TestCase):
+    """ruff [*] 可自动修复项：提示必须显式给出 ruff check --fix。"""
+
+    def test_fixable_hint_appended_for_python(self):
+        blocks = gate_lib._failure_detail_blocks(
+            [("python", "UP009 [*] UTF-8 encoding declaration is unnecessary",
+              "remove comment", "hint")])
+        joined = "\n".join(blocks)
+        self.assertIn("ruff check --fix", joined)
+
+    def test_no_fixable_hint_for_shell(self):
+        blocks = gate_lib._failure_detail_blocks(
+            [("shell", "SC2086 detail", "quote it", "hint")])
+        self.assertNotIn("ruff check --fix", "\n".join(blocks))
+
+
+class RuleSummaryTest(unittest.TestCase):
+    """规则聚合计数：whack-a-mole 的治理——AI 一次看到问题全集。"""
+
+    def test_aggregates_rule_codes(self):
+        full = ("scripts/x.py:1:1 EXE001 Shebang\n"
+                "scripts/y.py:2:1 EXE001 Shebang\n"
+                "scripts/z.py:28:27 DTZ011 date.today() used")
+        self.assertEqual(
+            gate_lib._rule_summary(full),
+            "规则汇总: DTZ011×1 EXE001×2")
+
+    def test_empty_for_non_linter_output(self):
+        self.assertEqual(gate_lib._rule_summary("plain text\nno codes"), "")
+
+
+class ScopeChildGitRepoTest(unittest.TestCase):
+    """非 git 根（会话工作区）的全量扫描：子 git 仓必须排除。"""
+
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.root = Path(self.tmp.name)
+        (self.root / "sub-repo").mkdir()
+        (self.root / "sub-repo" / ".git").mkdir()
+        (self.root / "loose.sh").write_text("#!/bin/sh\n", encoding="utf-8")
+
+    def test_child_git_repos_detected(self):
+        self.assertFalse(scope.is_git_repo(self.root))
+        self.assertEqual(scope.child_git_repo_names(self.root), ["sub-repo"])
+
+    def test_find_gate_excludes_child_repos(self):
+        cmd = ["bash", "-c",
+               "find . \\( -name '*.sh' \\) -type f "
+               "-not -path '*/node_modules/*' -print0 | "
+               "xargs -0 -r shellcheck --severity=warning"]
+        out = scope.scope_cmd(cmd, str(self.root), full_excludes=True)
+        joined = " ".join(out)
+        self.assertIn("-not -path '*/sub-repo/*'", joined)
+        self.assertIn("-not -path '*/target/*'", joined)
+
+    def test_git_repo_root_gets_no_child_excludes(self):
+        (self.root / ".git").mkdir()
+        cmd = ["bash", "-c",
+               "find . -name '*.sh' -type f -print0 | xargs -0 -r true"]
+        out = scope.scope_cmd(cmd, str(self.root), full_excludes=True)
+        self.assertNotIn("-not -path '*/sub-repo/*'", " ".join(out))
+
+
+if __name__ == "__main__":
+    unittest.main()