merge origin/main (v0.10.1) into fix/gate-hardening-from-session-feedback

并行会话先合入 #30(v0.10.0) 与 #32(v0.10.1)，本分支叠上去。冲突解法：
- 4 份版本 manifest 取 theirs（0.10.1，不回退已发布版本号）
- README 双语版本行对齐 0.10.1（#30/#32 未更新该行，顺手修正既存偏差）
- scripts/languages.json 自动合并：他们的 find 门禁 -not -path/xargs -r
  与本分支 append_files= false ×9 共存（9+13 处断言通过）
- hooks/gate_lib.py：scope_cmd 调用双参数并存
  （本分支 append_files=append + 上游 full_excludes=not uses_delta_files）
- scripts/scope.py：模块 docstring 合并双意图描述

验证：unittest 135/135（含上游新增用例）、run_all 141/0、schema 11 规则

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.3"
+        "ref": "v0.10.1"
       },
       "policy": {
         "installation": "AVAILABLE",
         "authentication": "ON_USE"
       },
       "category": "Developer Tools",
-      "version": "0.8.3",
+      "version": "0.10.1",
       "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.3/assets/official-logo.png",
+      "icon": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.10.1/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.3/assets/official-logo.png"
+        "logo": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.10.1/assets/official-logo.png"
       }
     }
   ]

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codeguard",
-  "version": "0.8.3+codex.20260922",
+  "version": "0.10.1+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.3",
+  "version": "0.10.1",
   "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

@@ -67,7 +67,7 @@ AI code that passes lint on first try
 |---|---|
 | Plugin ID | `partme-codeguard-plugin` |
 | Hosts | ZCode, Claude Code, Codex CLI, Kimi Code |
-| Current version | `0.8.3` |
+| Current version | `0.10.1` |
 | ZCode manifest | `.zcode-plugin/plugin.json` |
 | Codex manifest | `.codex-plugin/plugin.json` |
 | MCP server | Published: stdio server via the official SDK (`check_code_style` / `auto_fix` / `list_languages`); see Quick start |
@@ -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

@@ -67,7 +67,7 @@ AI 一次写出就过 lint 的代码
 |---|---|
 | 插件 ID | `partme-codeguard-plugin` |
 | 宿主 | ZCode、Claude Code、Codex CLI、Kimi Code |
-| 当前版本 | `0.8.3` |
+| 当前版本 | `0.10.1` |
 | ZCode manifest | `.zcode-plugin/plugin.json` |
 | Codex manifest | `.codex-plugin/plugin.json` |
 | MCP 服务 | 已发布：官方 SDK stdio 服务（`check_code_style` / `auto_fix` / `list_languages`）；见快速开始 |
@@ -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,
@@ -414,9 +421,12 @@ def check(lang: str):
                     break
         else:
             if scope == "delta":
+                # 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,
                     append_files=append,
                 )
             else:
@@ -444,6 +454,9 @@ def check(lang: str):
             if stale is not None:
                 return (lang, None, stale)
         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)
 
@@ -501,8 +514,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:
@@ -514,6 +548,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

@@ -466,7 +466,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
 
     # 按命令链预测实际提交面（纯 commit → 仅 staged；add -A/-a → 三路），

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.3",
+  "version": "0.10.1",
   "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 豁免可回溯、依赖解析失败有出路指引。