Back to Details

pre-push-checks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pre-push checks

推送前检查

Run relevant local evidence once before a push. Select the narrowest check that would fail for each regression; CI owns exhaustive coverage and the platform matrix.
在推送前运行一次相关的本地验证。为每个回归问题选择最窄范围的检查（若存在问题该检查会失败）；CI负责全面覆盖和平台矩阵验证。

Inspect the outgoing change

检查待推送的变更

  1. Confirm the checkout and branch:
sh
git status --short --branch
git rev-parse --show-toplevel
  1. Verify the live base or stack parent, then inspect the complete scope against it. Prefer the repository's change-scope tool, when present: it never guesses or fetches a base, so supply the ref you verified and add its head option only when inspecting a commit other than 
    HEAD
    (in a pnpm repository, for example, 
    pnpm --silent run change-scope --base <verified-base-ref>
    ). Without that tool, fall back to 
    git diff --stat origin/$(git branch --show-current) 2>/dev/null || git diff --stat HEAD~1
    .
Confirm the files the diff actually touches. After merging a changed base, rerun the scope report, reassess which checks the combined scope can still affect, and rerun only the checks the merge invalidated.
  1. 确认当前检出状态和分支：
sh
git status --short --branch
git rev-parse --show-toplevel
  1. 验证当前基准分支或栈式分支的父分支，然后对照它检查完整的变更范围。优先使用仓库的变更范围工具（如果存在）：该工具不会猜测或拉取基准分支，因此需提供你已验证的引用，且仅当检查的不是
    HEAD
    提交时才添加头部选项（例如在pnpm仓库中，
    pnpm --silent run change-scope --base <verified-base-ref>
    ）。若无该工具，则退而使用
    git diff --stat origin/$(git branch --show-current) 2>/dev/null || git diff --stat HEAD~1
    。
确认差异实际涉及的文件。在合并了已变更的基准分支后，重新运行范围报告，重新评估合并后的范围仍会影响哪些检查，仅重新运行被合并操作 invalidate 的检查。

Select relevant evidence

选择相关验证

There is no universal local baseline. Every behavior change needs the narrowest available test or purpose-built check that would fail for its regression; add broader checks only for surfaces the diff actually reaches.
  • Package or script behavior: run the owning test file or focused test name. Add adjacent package tests when a shared contract changes; leave repository-wide coverage to CI unless the change is genuinely cross-cutting or the user requests it.
  • Model-, editor-, CLI-, or terminal-visible output: run the focused snapshot or real runnable-example scenario that owns the output.
  • Package manifests, public exports, build configuration, or built runtime paths: run the build, the relevant hygiene checks, and the owning built-artifact smoke.
  • Real provider or agent behavior: run the relevant end-to-end target when credentials are available; never print secrets.
  • Skill changes (new 
    SKILL.md
    , frontmatter, body, or manifest): run your repository's skill validator against each changed skill directory, and confirm the manifest lists every skill.
  • Docs or decision records: run your repository's documentation checks (pairing, note format, budgets, links, wrap, archive).
  • Bilingual pairs: a change to either side updates the counterpart, then re-record the pair with your repository's pairing check; the pairing gate is green.
  • Whitespace and layout: 
    git diff --check
    .
Do not manually repeat a passing check merely because a commit or push follows, and do not run a broader suite for a change that only touches one skill or one doc.
不存在通用的本地基准。每个行为变更都需要最窄范围的可用测试或专门构建的检查（若存在回归问题该检查会失败）；仅当差异实际涉及相关表面时，才添加更宽泛的检查。
  • 包或脚本行为：运行对应的测试文件或聚焦的测试用例。当共享契约变更时，添加相邻包的测试；除非变更真正涉及跨模块，或用户明确要求，否则将仓库级别的全面覆盖交给CI处理。
  • 模型、编辑器、CLI或终端可见的输出：运行负责该输出的聚焦快照或可运行的真实示例场景。
  • 包清单、公共导出、构建配置或已构建的运行时路径：运行构建、相关的卫生检查，以及对应的构建制品冒烟测试。
  • 真实提供者或Agent行为：在有可用凭证时运行相关的端到端目标；切勿打印密钥。
  • Skill变更（新的
    SKILL.md
    、前置元数据、正文或清单）：针对每个已变更的Skill目录运行仓库的Skill验证器，并确认清单中列出了所有Skill。
  • 文档或决策记录：运行仓库的文档检查（配对、笔记格式、篇幅、链接、换行、归档）。
  • 双语配对内容：修改其中一侧后需更新另一侧，然后使用仓库的配对检查重新记录配对内容；确保配对检查通过。
  • 空白字符和布局：
    git diff --check
    。
不要仅仅因为后续有提交或推送，就手动重复已通过的检查；对于仅涉及一个Skill或一份文档的变更，不要运行更宽泛的测试套件。

Focus unit coverage on the affected source

聚焦受影响源码的单元测试覆盖率

Test selection and coverage selection are separate. A test filter chooses which tests run, while the repository's coverage configuration otherwise measures a wider default set. When unit coverage is relevant, name both the owning tests and the source files or package whose coverage those tests must prove. In a Vitest repository:
sh
pnpm exec vitest run packages/<group>/<package>/tests/<behavior>.spec.ts \
  --coverage \
  --coverage.include='packages/<group>/<package>/src/**/*.ts'
Use an exact source file when the behavior is truly confined to one module. Repeat 
--coverage.include
for multiple affected files or packages, and pass every owning test file needed to exercise that scope. When the owning tests are unclear, discover a candidate set with the runner's dependency-graph mode (
pnpm exec vitest related packages/<group>/<package>/src/<changed>.ts --run --coverage --coverage.include='packages/<group>/<package>/src/<changed>.ts'
in Vitest), then inspect the selected tests before treating the run as evidence. The configured per-file coverage thresholds still apply inside the selected source scope.
Dependency-graph discovery cannot see behavior reached only through configuration, dynamic loading, subprocesses, workers, built artifacts, or external providers; select those owning tests explicitly. When the selected scope fails a threshold, add its other relevant owning tests, or narrow the source scope only when the excluded modules cannot be affected. Do not use 
--passWithNoTests
, lower coverage thresholds, or narrow 
--coverage.include
merely to hide an uncovered affected file.
测试选择和覆盖率选择是两个独立的操作。测试过滤器选择要运行的测试，而仓库的覆盖率配置默认会测量更广泛的范围。当单元测试覆盖率相关时，需同时指定对应的测试文件，以及这些测试必须验证覆盖率的源码文件或包。在Vitest仓库中：
sh
pnpm exec vitest run packages/<group>/<package>/tests/<behavior>.spec.ts \
  --coverage \
  --coverage.include='packages/<group>/<package>/src/**/*.ts'
当行为确实局限于单个模块时，使用精确的源码文件。若有多个受影响的文件或包，重复
--coverage.include
参数，并传入所有需要覆盖该范围的测试文件。当对应的测试文件不明确时，使用测试运行器的依赖图模式来发现候选测试集（在Vitest中为
pnpm exec vitest related packages/<group>/<package>/src/<changed>.ts --run --coverage --coverage.include='packages/<group>/<package>/src/<changed>.ts'
），然后在将运行结果作为验证依据前，检查选中的测试。配置的单文件覆盖率阈值仍适用于选中的源码范围。
依赖图发现无法检测到仅通过配置、动态加载、子进程、工作线程、构建制品或外部提供者触发的行为；需显式选择对应的测试文件。当选中的范围未达到阈值时，添加其他相关的测试文件；仅当排除的模块不会受到影响时，才缩小源码范围。不要使用
--passWithNoTests
、降低覆盖率阈值或缩小
--coverage.include
范围来隐藏未覆盖的受影响文件。

Full local rehearsal

完整本地预演

Run the complete local approximation only when the user explicitly requests it, while diagnosing a CI failure, or when the change spans the repository so broadly that no narrower set is credible. Use the current workflow and package scripts as the inventory; do not recreate a removed aggregate check script.
仅当用户明确要求、诊断CI失败，或变更范围覆盖整个仓库以至于没有可信的窄范围检查集时，才运行完整的本地近似验证。使用当前的工作流和包脚本作为清单；不要重新创建已移除的聚合检查脚本。

Protect history-rewriting pushes

保护重写历史的推送

Rebase is allowed for standalone and stacked branches, including after review. Before a standalone history rewrite, fetch the current remote branch and record its exact OID; publish with 
--force-with-lease=<branch>:<observed-oid>
so a concurrent update aborts the push. A stack-management tool supplies lease protection for its managed branches. Raw 
--force
is never allowed.
After any rewritten push, fetch the live heads again and re-audit unresolved review threads, approvals, mergeability, and checks. Commit hashes and inline-comment anchors from before the rewrite are not current evidence.
允许对独立分支和栈式分支进行变基，包括审核之后。在独立分支的历史重写前，拉取当前的远程分支并记录其确切的OID；使用
--force-with-lease=<branch>:<observed-oid>
进行推送，这样并发更新会中止推送操作。栈式分支管理工具会为其管理的分支提供租赁保护。绝对不允许使用原生的
--force
。
在任何重写历史的推送之后，重新拉取当前的分支头，并重新审核未解决的审核线程、批准状态、可合并性和检查结果。重写之前的提交哈希和行内评论锚点不再是有效的验证依据。

Post-sync validation

同步后验证

A stack-sync tool that fetches, cascade-rebases, and pushes as one operation (for example, 
gh stack sync
) cannot place local validation between rewrite and publication. Before running it, require a clean worktree and record the official stack order and exact remote heads. After it returns:
  1. Re-query every branch head and the official stack order.
  2. Inspect the changed scope of every rewritten layer against its live base.
  3. Run the relevant evidence selected by this skill for each affected layer.
  4. Keep every PR unmerged and report validation as pending until all selected checks pass.
If post-sync evidence fails, leave the lease-protected published heads in place, repair the failure, validate the repair, and publish the correction. Do not claim the sync made the stack ready merely because the command succeeded.
若栈式分支同步工具将拉取、级联变基和推送作为一个操作执行（例如
gh stack sync
），则无法在重写和推送之间进行本地验证。运行该工具前，要求工作树干净，并记录官方的栈式分支顺序和确切的远程分支头。工具运行完成后：
  1. 重新查询每个分支的头和官方的栈式分支顺序。
  2. 检查每个重写层相对于当前基准分支的变更范围。
  3. 针对每个受影响的层，运行本Skill选择的相关验证。
  4. 保持所有PR未合并，并将验证状态报告为待处理，直到所有选中的检查通过。
如果同步后的验证失败，保留受租赁保护的已推送分支头，修复问题，验证修复结果，然后推送修正内容。不要仅仅因为命令执行成功，就声称栈式分支已准备就绪。

Handle failures

处理失败

If a relevant check fails before an ordinary push, stop and fix or explain the blocker; do not push and hope CI differs. For the post-sync exception, block the merge and follow the repair procedure above.
If a failure looks environment-specific, prove it: record the exact command, failing test, and platform-specific mismatch; confirm the relevant non-platform evidence; prefer fixing cross-platform nondeterminism when the check is required. Bypass a local check only when the user explicitly asks or agrees, and report exactly what failed and why CI is expected to differ.
若相关检查在普通推送前失败，请停止并修复或说明阻塞原因；不要推送并寄希望于CI结果不同。对于同步后的例外情况，阻止合并并遵循上述修复流程。
如果失败看起来是环境特定的，请证明这一点：记录确切的命令、失败的测试和平台特定的不匹配；确认相关的非平台验证；若该检查是必需的，优先修复跨平台的不确定性。仅当用户明确要求或同意时，才绕过本地检查，并准确报告失败内容以及预期CI结果不同的原因。

Push procedure

推送流程

For ordinary and standalone rebase pushes:
  1. Run the selected relevant checks once.
  2. Commit normally and inspect any files changed by a pre-commit fixer before continuing.
  3. Push normally, or use the exact lease for an authorized rewritten branch.
  4. Verify the remote ref matches local 
    HEAD
    :
sh
git rev-parse HEAD origin/$(git branch --show-current)
For GitHub PRs, inspect remote CI after the push:
sh
gh pr checks
Report pending checks as pending. Inspect failures before attributing them to the branch or the environment.
For a stack-sync push, use the post-sync validation sequence instead of pretending the ordinary order was possible.
对于普通推送和独立分支变基后的推送：
  1. 运行一次选中的相关检查。
  2. 正常提交，并在继续前检查预提交修复工具修改的任何文件。
  3. 正常推送，或对已授权的重写分支使用确切的租赁参数。
  4. 验证远程引用与本地
    HEAD
    匹配：
sh
git rev-parse HEAD origin/$(git branch --show-current)
对于GitHub PR，推送后检查远程CI状态：
sh
gh pr checks
将待处理的检查报告为待处理。在将失败归因于分支或环境前，先检查失败内容。
对于栈式分支同步推送，使用同步后验证流程，而非假装普通流程可行。