release: v0.10.0（门禁全量扫描剔除构建产物——find 型 gate 注入 -not -path）

实测（ddd4j-boot 13 分支仓）：java 门禁 mvn javadoc:jar 在
target/**/apidocs/ 生成无 shebang 的 javadoc.sh，shell 门禁按源码扫
→ SC2148 必红且删了也输（两 gate 步骤并发互相矛盾）。

- scope: _RUFF_FULL_EXCLUDES → 公开 FULL_SCAN_EXCLUDES 单一事实源；
  full_excludes 时对 find -print0 型命令幂等注入 -not -path（ruff 不变）
- gate_lib: delta 超 50 文件回退全量路径同样剔除；java 依赖解析失败
  附 mvn install 行动指引；record_skip_event 保留最近 20 条明细
  （ts/kind/repo），总数与 kinds 兼容
- validate_languages_json: shellcheck gate/lint 必须钉扎 --severity=
  （防门禁结论随 cache 版本漂移——老发布版本缺省时 info 级 SC2059/SC2295
  也阻塞）
- tests/test_full_scan_excludes.py: 14 用例（注入幂等/端到端
  javadoc.sh/审计明细/依赖指引/severity 契约）；README zh+en；openspec change

tests: run_all 141 通过 + 新增 14 用例全绿；ruff 全绿

Author: loong10k

.agents/plugins/marketplace.json

@@ -9,20 +9,20 @@
       "source": {
         "source": "url",
         "url": "https://github.com/partme-ai/partme-codeguard-plugin.git",
-        "ref": "v0.8.2"
+        "ref": "v0.10.0"
       },
       "policy": {
         "installation": "AVAILABLE",
         "authentication": "ON_USE"
       },
       "category": "Developer Tools",
-      "version": "0.8.2",
+      "version": "0.10.0",
       "description": "Cross-language code lint enforcement for AI coding assistants (ZCode, Claude Code, Codex CLI, Kimi Code): Java, Rust, TypeScript, Python. PostToolUse hook auto-runs the native linter on every AI-written file and blocks on failure in strict mode.",
-      "icon": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.8.2/assets/official-logo.png",
+      "icon": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.10.0/assets/official-logo.png",
       "interface": {
         "displayName": "代码规范守卫",
         "shortDescription": "Make AI-written code pass lint on first try",
-        "logo": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.8.2/assets/official-logo.png"
+        "logo": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.10.0/assets/official-logo.png"
       }
     }
   ]

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codeguard",
-  "version": "0.8.2+codex.20260922",
+  "version": "0.10.0+codex.20260922",
   "description": "Cross-language code lint enforcement for AI coding assistants (ZCode, Claude Code, Codex CLI, Kimi Code): Java, Rust, TypeScript, Python. PostToolUse hook auto-runs the native linter on every AI-written file and blocks on failure in strict mode.",
   "author": {
     "name": "Full Stack Skills / PartMe.AI",

.zcode-plugin/plugin.json

@@ -5,7 +5,7 @@
     "en": "CodeGuard",
     "zh-CN": "代码规范检查"
   },
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "Cross-language code lint enforcement for AI coding assistants (ZCode, Claude Code, Codex CLI, Kimi Code): Java, Rust, TypeScript, Python. PostToolUse hook auto-runs the native linter on every AI-written file and blocks on failure in strict mode.",
   "description_i18n": {
     "en": "Cross-language code lint enforcement. PostToolUse hook auto-runs the language-specific linter on every AI-written file; failed lint blocks further writes when strict_mode is on. Ships ready-to-go .pre-commit-config.yaml templates for Java/Rust/TypeScript/Python.",

README.md

@@ -248,7 +248,12 @@ Gate scanning is scoped to **what you are about to change**, decided by git stat
 - Project-level `codeguard.json` (repo root) overrides the default:
   `{"gate_scope": "repo"}` restores full-repository scanning; `extensions` and
   `exclude` customize language detection. Full scans always skip vendor/build
-  snapshots (immutable supply-chain content).
+  snapshots (immutable supply-chain content) and build-output directories
+  (`target`, `dist`, `build`, … — also injected into `find -print0` style gates,
+  so generated artifacts like maven-javadoc's `javadoc.sh` no longer trip the
+  shell gate). The >50-file delta fallback to a full command applies the same
+  exclusions. Java gate failures caused by unresolvable dependencies now carry
+  an actionable hint (run `mvn install` first) instead of a bare maven stack.
 
 Verdict honesty: a linter crashing with exit 2 (usage/dependency failure) is
 reported as **unverified**, never as a lint failure — "cannot verify" is not
@@ -259,7 +264,8 @@ health surface must go red when tooling is absent.
 
 Escape hatch: `git config codeguard.skipGate true` bypasses both the soft and
 hard gate for one repository; every bypass is counted and surfaced by the Stop
-summary, which also warns when the flag is left enabled. Shared hook state lives
+summary, which also warns when the flag is left enabled. The audit keeps the
+last 20 events (timestamp + repository + kind). Shared hook state lives
 under `CODEGUARD_HOME` (default `~/.codeguard`): session lint statistics,
 double-install dedup keys, and the skip audit.
 

README.zh-CN.md

@@ -231,15 +231,20 @@ codeguard:
   提交进历史的坏改动，出门时仍会被拦下。
 - 项目根的 `codeguard.json` 可覆盖缺省：`{"gate_scope": "repo"}` 恢复全仓扫描；
   `extensions` 与 `exclude` 自定义语言识别。全仓扫描始终剔除 vendor/build
-  快照（供应链不可变内容）。
+  快照（供应链不可变内容）与构建产物目录（`target`、`dist`、`build` 等，
+  含 `find -print0` 型 gate——生成物如 maven-javadoc 的 `javadoc.sh` 不再让
+  shell 门禁误红）。delta 超 50 文件回退全量命令时同样剔除。
+  Java 门禁报依赖解析失败时附行动指引（`mvn install` 前置说明），而非只留
+  maven 堆栈尾部。
 
 判定诚实性：linter 以 exit 2（用法/依赖崩溃）退出时按**未验证**上报，绝不计
 为 lint 失败——"无法验证"不等于"验证失败"，工具崩溃也不会触发自动修复。
 exit 127（命令不存在）**按场景有意分流**：交互钩子跳过它（不因工具缺失挡人）；
 `check`/CI 面按**失败**处理——健康面在工具缺失时就该变红。
 
 逃生门：`git config codeguard.skipGate true` 对单仓同时豁免软门与硬门；每次
-绕过都会计数并由 Stop 汇总展示，标志遗留未清时也会提醒。钩子共享状态位于
+绕过都会计数并由 Stop 汇总展示，标志遗留未清时也会提醒，审计还保留最近 20
+条明细（时间 + 仓库 + 类型）。钩子共享状态位于
 `CODEGUARD_HOME`（缺省 `~/.codeguard`）：会话 lint 统计、双副本去重键与绕过
 审计。
 

hooks/gate_lib.py

@@ -11,13 +11,20 @@
 import contextlib
 import json
 import os
+import re
 import subprocess
 import sys
+import time
 from pathlib import Path
 
 PLUGIN_ROOT = Path(__file__).resolve().parents[1]   # hooks/ 的上级 = 插件根
 sys.path.insert(0, str(PLUGIN_ROOT / "scripts"))
 
+# maven 依赖解析失败的特征（javadoc:jar 独立 goal 在 reactor 上跑时的典型崩法）
+_DEP_RESOLUTION_RE = re.compile(
+    r"Could not resolve dependencies|Could not find artifact|DependencyResolutionException"
+)
+
 from detect_lang import (
     LANG_COMMANDS,
     detect_language,
@@ -321,7 +328,13 @@ def check(lang: str):
                     break
         else:
             if scope == "delta":
-                cmd = scope_cmd(base_cmd, project_root, files=lang_files if uses_delta_files else None)
+                # files=None（delta 超 50 文件回退全量命令）时同样要剔除构建产物——
+                # 否则回退路径反而比常规全量门禁更容易扫到 target/ 生成物。
+                cmd = scope_cmd(
+                    base_cmd, project_root,
+                    files=lang_files if uses_delta_files else None,
+                    full_excludes=not uses_delta_files,
+                )
             else:
                 cmd = scope_cmd(base_cmd, project_root, full_excludes=True)
             outputs.append(_run_one(cmd, timeout, lang, hint))
@@ -342,6 +355,9 @@ def check(lang: str):
             return (lang, None, f"{lang} 工具链异常未验证：exit 2（非 lint 结论）{('｜' + head[:80]) if head else ''}")
         full = "\n".join(seg for seg in ((out or "").rstrip(), (err or "").rstrip()) if seg)
         detail = _truncate_detail(full or "（linter 无输出）", project_root, lang)
+        dep_hint = _dependency_resolution_hint(lang, full)
+        if dep_hint:
+            detail += f"\n{dep_hint}"
         fix = f"自动修复: {' '.join(cmd_def['format'])}" if cmd_def.get("format") else "按上述问题逐项修复"
         return (lang, (lang, detail, fix, hint), None)
 
@@ -399,8 +415,29 @@ def session_state_path() -> Path:
     return codeguard_home() / "session_state.json"
 
 
-def record_skip_event(kind: str) -> None:
-    """记录一次绕过（skipGate/逃生门）到会话状态，Stop 汇总时可见。"""
+def _dependency_resolution_hint(lang: str, full: str) -> str | None:
+    """Java 门禁报依赖解析失败时给行动指引，而不是只留 maven 堆栈尾部。
+
+    javadoc:jar 以独立 goal 跑在 reactor 上，sample 类模块常设
+    maven.install.skip=true，它们的构件不在本地仓——下游模块必然
+    Could not resolve。没有这行提示，用户看到的是与"该改什么"无关的堆栈。
+    """
+    if lang != "java":
+        return None
+    if not _DEP_RESOLUTION_RE.search(full):
+        return None
+    return (
+        "提示：依赖构件不可解析（如 samples 模块 maven.install.skip=true 未入本地仓）。"
+        "先在仓根执行 mvn install -DskipTests（必要时加 -Dmaven.install.skip=false）再重试门禁。"
+    )
+
+
+def record_skip_event(kind: str, project_root: Path | None = None) -> None:
+    """记录一次绕过（skipGate/逃生门）到会话状态，Stop 汇总时可见。
+
+    除计数外保留最近 20 条明细（时间 + 仓库 + 类型）——豁免必须可回溯：
+    只有总数时无法回答"哪个仓、什么时候被跳过的"。
+    """
     state = {}
     path = session_state_path()
     try:
@@ -412,6 +449,13 @@ def record_skip_event(kind: str) -> None:
     meta["count"] = int(meta.get("count", 0)) + 1
     kinds = meta.setdefault("kinds", {})
     kinds[kind] = int(kinds.get(kind, 0)) + 1
+    events = meta.setdefault("events", [])
+    events.append({
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "kind": kind,
+        "repo": project_root.name if project_root else None,
+    })
+    del events[:-20]
     try:
         path.parent.mkdir(parents=True, exist_ok=True)
         path.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")

hooks/pre_tool_git_guard.py

@@ -298,7 +298,7 @@ def main() -> int:
     if not roots:
         return 0
     if any(skip_gate_via_git_config(r) for r in roots):
-        record_skip_event("skipGate")
+        record_skip_event("skipGate", roots[0])
         return 0
 
     # 每个被操作的仓库独立跑：linter 门禁 + 提交内容安全检查

hooks/user_prompt_validator.py

@@ -172,7 +172,7 @@ def main() -> int:
     if skip_gate_via_git_config(project_root):
         # 软门禁与硬门禁共用同一条仓库级豁免：此前 UPS 不认 skipGate，
         # 出现过"硬门放行、软门仍喊禁止提交"的自相矛盾。
-        record_skip_event("skipGate")
+        record_skip_event("skipGate", project_root)
         return 0
 
     cfg = load_user_config()

kimi.plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codeguard",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "Cross-language code lint enforcement for AI coding assistants (ZCode, Claude Code, Codex CLI, Kimi Code): Java, Rust, TypeScript, Python. PostToolUse hook auto-runs the native linter on every AI-written file and blocks on failure in strict mode.",
   "author": {
     "name": "Full Stack Skills / PartMe.AI"

openspec/changes/2026-09-22-gate-full-scan-excludes/proposal.md

@@ -0,0 +1,30 @@
+# 2026-09-22-gate-full-scan-excludes
+
+## Why
+
+ddd4j-boot 13 分支仓实测：java 门禁 `mvn javadoc:jar` 在 `target/**/apidocs/`
+生成无 shebang 的 `javadoc.sh`，shell 门禁的 find 把它当源码扫（SC2148），
+commit/push 门禁必红且删了也输（java lint 并发再生成）——两个 gate 步骤
+互相矛盾。排除基建已存在但只物化 ruff：`scope_cmd(full_excludes=True)`
+仅对 `ruff` 追加 `--exclude`，`find -print0` 型 gate 原样透传。同批实测
+还发现：老发布版本 shellcheck gate 缺 `--severity` 钉扎，info 级发现
+（SC2059/SC2295）也阻塞；skipGate 豁免只有总数没有明细。
+
+## What Changes
+
+- `scope.py`：`_RUFF_FULL_EXCLUDES` → 公开的 `FULL_SCAN_EXCLUDES`（单一
+  事实源）；新增 `_inject_find_excludes`——`full_excludes=True` 时给
+  `find … -print0` 型命令注入 `-not -path '*/<dir>/*'`，幂等，ruff 路径不变。
+- `gate_lib.py`：delta 超 50 文件回退全量命令的路径补 `full_excludes=True`
+  （回退路径此前比常规全量门禁更容易扫到 target/）；java 门禁依赖解析
+  失败（Could not resolve / Could not find artifact）追加行动指引；
+  `record_skip_event` 增加最近 20 条明细（时间 + 仓库 + 类型），总数与
+  kinds 字段保持兼容。
+- `validate_languages_json.py`：新契约——gate/lint 中调用 shellcheck 必须
+  钉扎 `--severity=`（防"门禁结论随 cache 版本漂移"回归）。
+
+## Impact
+
+- Affected specs: `language-gate-commands`（gate 命令可执行性 + 一致性契约）
+- 受益场景：任何 Maven/Gradle 项目（构建产物不再引发 shell/java 门禁互斥）、
+  skipGate 豁免可回溯、依赖解析失败有出路指引。