团队 GitLab 代码门禁

概述

适用与不适用

适用于团队内部 Windows 本地 Git 仓库中的代码修改、变更审查、提交和推送准备。Codex 可自动触发；其他具备文件读取、PowerShell、Git 和 Ruby 执行能力的 AI 工具可按相同流程调用脚本。不适用于无本地仓库或无命令执行能力的云端对话，也不因触发本技能而获得提交或推送授权。

首次使用与包内版本

读取 [团队安装与诊断](references/team-install.md)，由使用者在自己的机器上运行安装脚本；安装会设置 Git hooks，不能在解压时自动执行。精确注释引擎及配置位于 engine/，来自已验证的团队快照，使用时不依赖门禁仓库或内网连接。版本依据和更新方式见 [引擎快照](references/engine-snapshot.md)。提交与评分流程同时读取 [Git 评分守卫](references/score-guard-workflow.md)。

Primary objective

For code changes and code reviews, the primary job of this skill is to repair declaration comments during authoring or review, before CZ (the team's interactive commit-message tool) or push time. Build the member-ownership map from the intended diff, put verified comments at the declarations, and keep existing JSDoc synchronized with changed signatures and side effects. The CZ commit-msg hook and exact engine are a final safety net, not the source from which the AI should discover ordinary missing comments.

This skill applies automatically when the user's intent is to add, modify, delete, refactor, generate, migrate, or fix code; review changed or unpushed code; prepare or perform a commit/push; recover from a remote rejection; or assess GitLab gate compliance. Activate it before the first repository inspection so pre-edit checks happen before any edit. Do not activate it for unrelated read-only explanation, browsing, architecture discussion, or diagnosis alone. Do not wait for the user to mention this skill when the request is a code change or changed-code review.

Single source of truth

The main file covers ordinary code changes. Load the full bundled [Git 提交与推送指南-new.md](references/Git 提交与推送指南-new.md) only for commit/push preparation or exact recovery steps. For a v9.7 subject-only classification, read only the compact [v9.7 subject decision](references/v97-subject-decision.md); it is the canonical table for concrete subject outcomes. Do not load the general standard section for that decision, because its stricter syntax examples can conflict with the company hook. Load the larger [Team GitLab v9.7 实现对照.md](references/Team%20GitLab%20v9.7%20实现对照.md) for the current v9.7/v9.8 comment-engine scope, exemptions, fail-open behavior, or final push readiness; load [local preflight](references/local-preflight.md) for outgoing-file discovery, declaration-audit execution, or remote-rejection recovery; load [annotation-quality.md](references/annotation-quality.md) only when adding, reviewing, or repairing declaration comments; load [upgrade-protocol.md](references/upgrade-protocol.md) only when updating this skill or reconciling a newer server revision.

Do not invent or merge in a different remote rule from memory, a local convention, another skill, a screenshot, or an unverified hook message. If another source conflicts with the bundled guide, report the conflict and follow the guide unless a newer user-provided guide replaces it.

The bundled guide contains the general Conventional Commits rules and the company's implementation rules. The implementation map records code-level behavior from the current v9.7/v9.8 hook and comment engine. When prose and executable behavior differ, report the conflict and follow the executable behavior. The compact v9.7 reference is the canonical routing source for concrete subject classification; implementation evidence elsewhere must not be turned into a second competing decision table.

For any outgoing JavaScript, TypeScript, or Vue file, also read [JS/TS/Vue attribution](references/js-ts-vue-attribution.md). This reference records parser behavior and the regression pattern that previously caused six remote findings to escape local review. For CZ, commit-hook, or local automatic preflight integration, read [commit-hook integration](references/commit-hook-integration.md). For score guard rules during commit or push preparation, read [score guard workflow](references/score-guard-workflow.md).

v9.7 routing guardrail

When a task involves a v9.7 commit subject, load [v9.7 subject decision](references/v97-subject-decision.md) before classifying it. Never substitute the stricter generic Conventional Commits syntax for the company's executable hook behavior, and never treat automatic Merge or Revert " handling as a bypass permission.

Server boundary and local push-safe preflight

The exact engine owns changed-line-to-member attribution. local-preflight.md owns the conservative outgoing-file fallback; it is not a second server rule. Files outside the candidate or final outgoing set remain out of scope. Any unresolved member in either path blocks a push-ready result.

Hard local-engine boundary

The local gate is only valid when the bundled engine actually ran and produced a result record. A zero exit code by itself is not a pass: the engine can fail-open after an internal error, and Windows Ruby cannot use the engine's POSIX /dev/null stderr sink. Always invoke scripts/run-comment-gate.ps1; it launches scripts/local-comment-engine.rb, captures stdout/stderr and the engine log, and blocks on ERROR, fail-open, SKIP, missing output, or a missing COMMENT_RESULT record. Never invoke the Ruby file directly or report 0 issue from a silent exit.

If the wrapper reports server-engine-unverified, the bundled engine did not produce a trustworthy result: enter the conservative member audit, keep push-ready false, and do not downgrade the state because lint, build, or a clean-looking diff succeeded. environment-not-ready is different: stop before source editing and report the missing Ruby, bundled file, hooks, or other environment prerequisite; it does not permit a degraded audit to authorize coding.

For the staged index and temporary-message lifecycle, follow [commit-hook integration](references/commit-hook-integration.md). The staged check creates no visible commit.

When changing this skill, its wrapper, or the bundled gate integration, run scripts/verify-local-gate.ps1. The regression must reject an unannotated TypeScript type declaration and then pass the same fixture after the declaration is annotated; a skill repair is incomplete if either half is not observed.

Required behavior during every code change or changed-code review

1. Inspect the repository root, current branch, worktree status, existing diff, and applicable project instructions before editing. Run the doctor before the first source edit. If it reports environment-not-ready, stop; after repairing the environment, rerun doctor before resuming. Never assume the earlier failure cleared. Preserve user changes and do not silently reset, checkout, clean, overwrite, commit, or push.
2. Stage only the intended changed source files, including new files, then verify the staged candidate list. Run run-comment-gate.ps1 -Mode staged -RequireCandidate without MessagePath; staged reads the index only, and no candidate is not a pass for a source-changing task. See commit-hook-integration.md for when to omit -RequireCandidate and how unrelated staged sources are handled.
3. Before the exact check, run the compact JS/TS/Vue owner-coverage pass defined in references/js-ts-vue-attribution.md: start from changed high-risk members, then include only the declaration and whichever parser-state context is needed—multiline-import continuation, matching braces, or nested callback boundaries; more than one may be needed. Stop before unrelated siblings. It is not a full-file inventory. Other Team-gated extensions use the exact engine and their language rules only.
4. Run the exact staged engine and resolve its findings. If ownership is ambiguous/unresolved or the result is server-engine-unverified, use the full owner matrix in references/local-preflight.md; if it is environment-not-ready, stop and repair the environment. A remote rejection remains an exceptional recovery path.
5. Place each repaired comment immediately above its final declaration. If a function signature, parameter, return value, or side-effect contract changes, update its existing JSDoc in the same edit. Do not defer ordinary comment repair to CZ output.
6. For already committed or cherry-picked changes, compare the verified base ref to the target ref with read-only git diff --unified=0; do not clone a working repository merely to compensate for a missing outgoing-audit mode. A clone or worktree requires explicit user authorization and is never the default comment-repair path.
7. When adding or repairing a comment, read references/annotation-quality.md. At minimum, add a verified business meaning, intent, contract, constraint, or side effect beyond the member name/signature; do not invent backend facts, add line-by-line narration, or optimize for comment count.
8. Keep the implementation type-safe and semantically clear, then run the project's relevant tests, lint, type check, build, and diff checks. Treat failures as failed work. The exact engine is the normal member-attribution check; local-preflight.md is the explicit degraded path, not a competing parser.

Commit and push readiness

Before a user-authorized commit or push, use the exact outgoing file set and the commit hook's final commit-msg check. If the exact engine is unavailable, apply local-preflight.md to that same set and keep the result server-engine-unverified; do not claim push-ready from lint, build, or a generic top-level scan.

When the repository uses the bundled Git hooks, the exact engine must run only from commit-msg after CZ has produced the final message and before Git creates the commit. pre-push must not invoke the Team comment engine. Use scripts/run-comment-gate.ps1 and the [commit-hook integration](references/commit-hook-integration.md) rather than the historical generic scanners. A failed local engine is a stop signal, not a reason to create a later documentation-only repair commit.

• The first non-empty physical line must use one of feat, fix, docs, style, refactor, perf, test, build, chore, revert, merge, or wip, with a v9.6/v9.7-valid description. Type case, colon, and the space after colon are optional; use action + object, not a bare generic word.
• Reject bare type/punctuation/number, one-character filler, bare version such as v2, normalized generic-word descriptions, descriptions placed only on the next line, and all skip markers. merge/Revert "..." automatic handling is not a fabrication route.
• Include a real TASK or BUG number when one is available and automatic ZenTao closure is intended. Never invent an issue number.
• Stage only intended files. Do not use git add . when unrelated changes exist. Do not use --no-verify, skip flags, fake issue numbers, meaningless comments, or meaningless commits to evade a check.
• A remote rejection is actionable evidence: read Remote:/❌, treat every listed member as in scope even if its declaration predates the diff or the reported changed line is elsewhere, repair it at the declaration, rerun both local preflight passes for every outgoing source file, restage intended files, validate, then retry. If a required finding remains unresolved, report the push as not ready rather than treating it as a harmless historical gap.
• Comment-engine fail-open for timeout, exception, missing engine, non-UTF-8, commit/file/line limits, or report/off mode affects only comment checking. It does not make an invalid commit message valid and must never be reported as “all checks passed”.
• Do not use destructive recovery such as reset --hard without explicit user authorization. If a multi-commit recovery is required, preserve the working tree with the guide's mixed-reset approach and verify the resulting diff before committing again.

Do not create a commit or push merely because this skill is active. A push requires explicit user authorization; once authorized, complete the gate and report the final remote ref and worktree state.

Optional supporting tools

• ripwire, if already installed, may advise on repository orientation, impact, and test scope; it cannot replace GitLab rules or install hooks/MCP.
• skill-up, if already installed, may create regression cases and evaluate triggering/rule-following; it cannot change the push guide.

Pitfalls（实测）

• Windows Ruby 对引擎默认的 /dev/null stderr 路径会出错并触发 fail-open；只通过 run-comment-gate.ps1 调用，并核对 COMMENT_RESULT。
• Vue template 或 style 的 diff 行不得映射到 script 声明。包内引擎已修复行号过滤与偏移；更新引擎必须通过 verify-vue-line-offset.ps1 重跑回归，避免 Windows Ruby 错误解码中文安装路径。
• 团队库上传通道不收 .conf 与无扩展名文件，因此包内配置以 *.conf.txt、钩子以 *.sh 交付；install.ps1 与 run-comment-gate.ps1 会按字节还原为运行名。重新解压技能后若未再运行安装或 doctor，钩子文件名尚未还原，Git 会静默不调用钩子——这不是门禁通过，必须先跑一次安装或 doctor。
• 只复制 SKILL.md 不会安装 Git hooks。使用者需要按团队安装说明显式安装并在目标仓库运行 doctor；解压不自动修改 Git 配置。
• 仓库级路径豁免仅影响注释检查。若需要与服务器的个别项目豁免一致，维护者须提供真实项目 ID 和路径模式；使用者只在对应仓库设置 teamGate.projectId 与 teamGate.pathExclude，未设置时检查更严格。

Acceptance checklist

• Activated before code editing; read-only tasks stay out of scope unless they explicitly assess this gate.
• Doctor passed before editing; after an environment-not-ready, the repaired environment was checked with doctor again before work resumed.
• The intended staged candidate is nonempty and scoped; exact engine completed with a valid result record, and all reported findings were resolved.
• JS/TS/Vue compact coverage checked changed high-risk members and parser-linked context; other Team-gated extensions were checked by the exact engine and their language rules only. Any expanded matrix has no unresolved members, with enum members listed individually.
• The outgoing file set is complete; required comments meet the substantive standard in Required behavior step 7; push-ready is withheld while any member is unresolved or the engine is unverified.
• Skill, wrapper, engine, or hook changes pass verify-local-gate.ps1, verify-vue-line-offset.ps1, and the isolated verify-team-package.ps1 integration cases; project validation and diff checks pass.
• No filler comments, placeholder comments, skip markers, guessed issue numbers, fabricated commits, or unverified rule substitutions were introduced.