codeguard

codeguard main entry: cross-language code standard gate

Turn "looks fine" into repeatable evidence with commands, scope, versions, and exit codes. See the current capability snapshot at references/capabilities/registry-summary.md。

Capability Boundaries

✅ Strengths

1. Automatic project language detection (dual recognition via extensions + marker files)
2. Unified lint gate:bin/codeguard check(or scripts/run_check.py), exit code 2 on failure
3. Unified automatic fix:bin/codeguard fix(spotless / cargo fmt / eslint --fix / ruff --fix), available only with the Legacy engine
4. CVE dependency vulnerability orchestration:bin/codeguard cve(Maven dependency-check / npm audit / pip-audit / cargo audit, with remediation guidance)
5. Commit gate: full re-check when the user expresses "commit/push" intent (UserPromptSubmit hook)
6. Session summary: Stop hook outputs this round's lint pass/fail/auto-fix counts

⚠️ Prerequisites

1. Toolchains for each language are installed (mvn / cargo / node / ruff); when missing, the gate reports "cannot verify" rather than passing
2. Redis (needed only by security hooks; the lint gate does not depend on it)

❌ Out of Scope (routing table)

1. Syntax learning, framework usage, library selection → the corresponding language's official skills repository (e.g. full-stack-skills/java-skills)
2. Branch creation and naming → codeguard-git-branch
3. commit message format → codeguard-git-commit
4. Leaks/secrets/CVE → codeguard-security-code
5. Privilege escalation/auth annotations/file upload → codeguard-security-api
6. Encrypted storage/data masking/national cryptography/classified protection security assessment → codeguard-security-data

When to Use

• "run lint" / "/check" / "code standard check"
• "fix style issues" / "/fix"
• "scan dependency vulnerabilities" / "codeguard cve"
• Final self-check before commit

I. Standard workflow

# 0. 先判定引擎（必做）
codeguard --version --format json 2>/dev/null && echo ENGINE=rust || echo ENGINE=legacy

For the full engine contract see references/operations/engine-contract.md. The main path below is the Legacy Python engine:

# 1. 检测语言
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/detect_lang.py" "$(pwd)"

# 2. 全量 lint 门禁（主路径）
bin/codeguard check                     # 或 python3 scripts/run_check.py
bin/codeguard check --lang java         # 只跑某语言

# 3. 失败 → 自动修复 → 复扫（fix 仅 Legacy 存在）
bin/codeguard fix --lang <name>

# 4. CVE 扫描（提交前必跑）
bin/codeguard cve --severity HIGH

Under the Rust engine, use positional arguments instead (check all|java、cve <rust|python|typescript>), and fix、--lang、--ecosystem、--severity none exist. Whether it can issue depends on its self-reported capabilities:codeguard capabilities all --format json in which that category status is implemented only then can it issue;gap、not_applicable, or when that unit cannot be read or found, always state it as incomplete and return to the Legacy command surface.

II. Gate rules (non-negotiable)

Rule	Description
lint failure = blocking	In strict mode the exit code is 2; the AI must fix it before continuing any coding action in the conversation
Cannot verify ≠ pass	A missing tool (exit 127) outputs "cannot verify" and gives the install command, and does not count as a pass
Incomplete ≠ pass	Exit code 3 means the check did not finish; you may only report it as incomplete and must not describe it as passing or zero vulnerabilities
What is found must be fixed	CVE/HIGH or above findings must come with a remediation action; reporting without handling is prohibited
Silent exemption prohibited	Do not use @SuppressWarnings / raise thresholds / change gate configuration to make failures disappear; if an exemption is truly needed, the user must explicitly agree and the reason must be registered in suppressions

III. Fix decision tree

lint 失败
├─ 格式类（缩进/import 顺序/行宽）→ 自动修复（fix 命令）→ 复扫
├─ 缺失类（javadoc/@param 缺失）→ 补写注释/文档
└─ 逻辑类（unused 变量有语义/复杂度超标）→ 人工判断，禁止自动改业务代码

Workflow

1. bin/codeguard detect Confirm language
2. bin/codeguard check Full scan
3. Failures are classified and handled according to the decision tree above
4. After handling, rescan until all green
5. When the user requests submission, confirm bin/codeguard cve also passes

Gotchas

1. mvn javadoc:jar errors do not appear in mvn compile —do not use compile results as the gate conclusion
2. Nested repositories/submodules can cause detect scans to time out—for large repositories use --lang to limit the scope
3. When the tool is not installed (exit 127), the gatedoes not pass but is not counted as a vulnerability, install the tool first and then rescan
4. npm audit fix may introduce breaking upgrades—regression testing is mandatory after fix

On-Demand Resources

• Capability snapshot:references/capabilities/registry-summary.md。
• Gate decision contract:references/rules/decision-contract.md。
• Evidence-based operations manual:references/operations/evidence-playbook.md。

Official References

• For official documentation of tools for each language, see the Official References section of the corresponding language skill

Out of scope (when not to use)

• If the task is syntax learning, framework design, or business modeling, use the corresponding professional skill directly.
• The user requests proof of production readiness, but currently only lint or local scan evidence can be obtained.
• The task requires installation, submission, push, release, or modification of security thresholds, but no explicit authorization has been obtained.

Data and security

This skill does not collect, upload, send, or store user source code or credentials. Routing is read-only by default; when network scanning, file modification, Git write operations, or security exceptions are involved, it must be handed over to a dedicated skill and the authorization boundaries must be rechecked.

Evidence-based Workflow

Step 1: Determine user intent

Classify the request as detect, check, fix, cve, Git governance, or security, to avoid invoking unrelated capabilities in a single call.

Step 2: Confirm scope and authorization

Record the repository/module, current Git status, whether modification is allowed, and the boundaries for network, installation, submission, and release.

Step 3: Read capability status

Check whether the current language or feature is stable or planned, and do not misrepresent recognition capability as an executable gate.

Step 4: Hand off to one primary skill

Produce conclusions with one primary skill; only invoke other skills when an independent evidence layer is needed.

Step 5: Verify and report

Layer lint, format, build, test, security, Git, and release evidence, and explicitly write PASS, FAIL, UNVERIFIED, or PLANNED.

Rules

1. Specify only one primary route per request; the others are optional evidence layers.
2. Missing tools, timeouts, or a capability being planned do not equal PASS.
3. Do not delete rules, lower thresholds, or silently suppress to manufacture a green light.
4. Submission, push, and release require independent authorization; passing quality checks does not mean they can be executed automatically.

Output template

Codeguard 路由结果
- 目标：<user intent>
- 作用域：<repo/module/path>
- 主技能：<selected skill>
- 能力状态：<stable/planned>
- 证据：<commands/checkpoints and results>
- 状态：PASS / FAIL / UNVERIFIED / PLANNED
- 未验证：<remaining layers>

Load resources on demand

• Read this when skill hierarchy and routing need to be checked references/capabilities/registry-summary.md。
• Read this when an evidence package needs to be formed references/operations/evidence-playbook.md。
• Read this when decision boundaries are needed references/rules/decision-contract.md。
• Open only examples/ the examples that match the current task.