dsh-pre-push-checks

DSH 推送前检查

在推送 deepseek-harness 前，使用此技能运行一次相关的本地验证。唯一的顺序例外是 gh stack sync：它可能会在重写后的层尚未验证时发布级联变基；请立即验证这些层，并且在验证通过前不要合并。Git 钩子有意保持精简：pre-commit 会修复暂存区中的 lint 问题、检查暂存内容的空白字符，并保护 vendored-source 元数据；pre-push 只运行增量式仓库类型检查。全面覆盖和平台矩阵由 CI 负责。

检查即将推送的更改

1. 确认检出状态和分支。

git status --short --branch
git rev-parse --show-toplevel

2. 验证当前 PR 的基分支或堆栈父级，获取该引用，并检查相对于它的完整变更范围。

pnpm --silent run change-scope --base <verified-base-ref>

此命令绝不会猜测或获取基分支。请提供根据当前远程或堆栈状态核实的引用；检查 HEAD 以外的提交时，请使用 --head <ref>。其版本化 JSON 会记录相对于已解析合并基点的已提交路径，而暂存、未暂存和未跟踪路径则描述当前工作树。合并已更改的基分支后，请重新运行报告，重新评估合并后的整体范围可能影响哪些行为，并且只重新运行因合并而失效的检查。

选择相关证据

除钩子外，没有适用于所有情况的本地基线。每项行为变更都需要使用范围最窄且可用的测试或专门检查，确保回归时会失败；只有当变更实际影响到更广的范围时，才添加更全面的检查。

如果待提交的变更新增或修改了拥有资源或异步执行的测试、夹具、辅助程序或 CI 执行路径，请先使用 dsh-ci-test-reliability，判断是否需要恢复、负向控制、静默拆卸或并发进程方面的证据。此技能仍用于选择命令，并避免重复已通过的检查。

• **包或脚本行为：**运行所属的 Vitest 文件或聚焦的测试名称。共享约定变更时，添加相邻包的测试；除非变更确实涉及多个领域，或用户提出要求，否则将仓库范围的覆盖交给 CI。
• **远程 mock 类型检查：**未构建的 any 是明确的本地回退，并非严格证据。提交 Remote/mock 变更前运行 pnpm run typecheck；诊断剩余错误前，先重新构建缺失、过期或不完整的生成声明。仅在 test proxy 中保留此例外，不要放入生产 Remote 类型、环境标志或复制的签名中。
• **文档、Agent Notes、目录或文档关联注释：**运行 pnpm run doc-sync；如果文档工作流要求完整 lint，则运行完整 lint。
• **模型、编辑器、CLI 或终端可见输出：**运行负责该输出的聚焦无密钥快照，或真实可运行示例场景。
• **预期输出的位置：**如果测试选用的已录制 Session 既作为重放输入，又作为预期的持久化输出，则应放在顶层 snapshots/ 下，并在 snapshot.yml 中注明已发布的 dsh 配置及组合／标头固定项。标准父文件为 session[.vN].jsonl，子文件为 session.<ordinal>[.vN].jsonl，测试工具会为每个角色选择最高版本。若 ARIA、几何、生成器、CLI 和单元测试的预期结果不涉及此类 Session 往返，则应放在所属测试旁的 tests/expected/ 下；不要将它们放入 snapshots/，也不要为其指定 *.snapshot.ts 所属文件。使用所属的 test:expected、test:web 或 test 流程。
• **配置文件与配置项的位置：**已发布 dsh 配置跨包行为的测试应放在 apps/cli/tests/profiles/ 下；包专属的 Loader 组合应放在该包的 tests/fixtures/ 下。面向用户的可选覆盖配置应放在 apps/cli/config/examples/ 下，并配套提供 docs/user/ 中的指南。
• **包清单、公开导出、构建配置、worker/bin 条目或构建后的运行时路径：**运行 pnpm run build、相关的卫生检查，以及所属的构建产物冒烟测试。
• 仓库测试与脚本类型：pnpm run build:artifacts 只会检查包项目。声明 TypeScript 变更已完成前，在最近一次 build:artifacts 后运行 pnpm run build:check，或运行 pnpm run build；build:check 会读取现有的 build:artifacts 输出，不会重新构建。
• **真实提供商或 Agent 行为：**凭证可用时，运行相关的 pnpm run test:e2e 目标；绝不打印机密信息。

不要仅仅因为之后要提交或推送，就手动重复已通过的检查。尤其是不要仅为重复提交前钩子的检查，而在推送前立即运行 typecheck。

使用 pnpm run 时，将 Vitest 文件和名称筛选器直接放在脚本名称后；不要插入单独的 --，否则它会传给 Vitest，并可能禁用 -t 筛选。例如，以下命令会运行一个无头快照场景：

pnpm run test:snapshot snapshots/session/headless.snapshot.ts -t 'cordis-inspect-jsdoc'

此规则适用于这些 pnpm 脚本；npm 和其他启动器仍使用各自的参数转发语法。将筛选运行视为聚焦证据前，请检查报告中选中的测试数量。

将单元测试覆盖率集中在受影响的源文件上

测试筛选和覆盖率筛选是分开的。Vitest 文件筛选器决定运行哪些测试，而仓库配置默认会测量所有 packages/*/*/src/**/*.ts 文件。当单元测试覆盖率与此次更改相关时，请同时指定所属测试，以及这些测试必须验证覆盖率的源文件或软件包：

pnpm exec vitest run packages/<group>/<package>/tests/<behavior>.spec.ts \
  --coverage \
  --coverage.include='packages/<group>/<package>/src/**/*.ts'

如果行为确实仅限于一个模块，请指定确切的源文件。多个受影响文件或软件包可重复使用 --coverage.include，并传入所有需要覆盖该范围的所属测试文件。在选定的源文件范围内，配置的每文件 100% 阈值仍然适用。

如果不清楚哪些测试属于该范围，可使用 Vitest 的依赖关系图找出候选测试集，然后检查所选测试，再将运行结果视为证据：

pnpm exec vitest related packages/<group>/<package>/src/<changed>.ts \
  --run \
  --coverage \
  --coverage.include='packages/<group>/<package>/src/<changed>.ts'

vitest related 无法发现仅通过配置、动态加载、子进程、工作线程、构建产物或外部提供方触发的行为；请显式选择这些行为所属的测试。不要使用 --passWithNoTests、降低覆盖率阈值或缩小 --coverage.include 范围来掩盖未覆盖的受影响文件。如果选定的软件包范围因某个聚焦测试未覆盖该范围而失败，请添加其他相关的所属测试；只有在排除的模块不会受到此次更改影响时，才缩小源文件范围。

完整的本地预演

只有在用户明确要求、排查 CI 故障，或更改涉及整个仓库且无法可信地采用更窄范围时，才运行完整的本地模拟。请以当前工作流和软件包脚本作为清单；不要重新创建已移除的 check:pre-push 汇总任务。

保护改写历史记录的推送

允许对独立 PR 分支和堆叠 PR 分支执行变基，包括评审之后。改写独立分支的历史记录之前，请获取当前远程分支并记录其确切 OID；发布时使用 --force-with-lease=<branch>:<observed-oid>，以便并发更新时中止推送。gh stack push 和 gh stack sync 会为其管理的分支提供租约保护。绝不允许使用原始 --force。

每次推送改写后的历史记录后，都要再次获取远程分支头，并重新审查未解决的评审线程、批准、可合并状态和检查。改写前的提交哈希和行内评论锚点不再是当前证据。

同步后的验证

gh stack sync 会在一次操作中获取分支、按级联方式执行变基并推送，因此无法在改写和发布之间进行本地验证。运行该命令前，确保工作树干净，并记录官方堆叠顺序和确切的远程分支头。命令返回后：

1. 重新查询每个分支头和官方 GitHub 堆叠顺序。
2. 根据各自实时 PR 的基准分支，检查每个经过改写的层所涉及的更改范围。
3. 对每个受影响的层运行本技能选定的相关验证。
4. 在所有选定检查通过前，保持所有 PR 未合并，并报告验证仍待完成。

如果同步后的验证失败，请保留受租约保护的已发布分支头，修复故障、验证修复，然后发布更正。不要仅因命令成功就声称同步已使整个堆叠分支具备就绪条件。

处理失败

如果常规推送前相关检查失败，请停止并修复问题或说明阻碍。不要抱着 CI 结果可能不同的侥幸心理推送。对于同步后的例外情况，请阻止合并并遵循上述修复流程。

如果失败看起来与环境有关，请提供证据：

• 记录确切命令、失败测试和特定于平台的不匹配之处。
• 确认相关的非平台证据。
• 如果该检查是必需的，优先修复跨平台的不确定性。
• 只有在用户明确要求或同意时，才绕过本地钩子，并准确报告失败内容及预期 CI 结果为何不同。

推送流程

对于常规推送和独立的变基推送：

1. 运行一次选定的相关检查。
2. 正常提交，并检查预提交修复器修改的任何文件，然后再继续。
3. 正常推送；若为获准重写的分支，则使用精确的租约，以便增量类型检查钩子运行。
4. 验证远程引用与本地 HEAD 一致。

git rev-parse HEAD origin/$(git branch --show-current)

对于 GitHub PR，推送后检查远程 CI：

gh pr checks

将待处理的检查报告为待处理。检查失败项后，再判断问题是由分支还是环境导致的。

当 gh pr checks 报告“no checks reported”，且 /actions/runs?head_sha=<sha> 返回 total_count: 0 时，在怀疑推送有问题或 GitHub 事件丢失之前，先读取合并状态：

gh pr view <number> --json mergeable,mergeStateStatus

PR 处于 CONFLICTING/DIRTY 状态时，GitHub 不会创建 pull_request 工作流运行记录，因此缺失的信号来自冲突，而不是基础设施。唯一的修复方法是解决冲突；空提交、--allow-empty 推送、草稿/就绪状态切换，以及撤销后恢复的往返操作都会让 total_count 保持为零，并产生无用的历史记录。如果分支尚无法在本地合并，请使用 git merge-tree --write-tree HEAD origin/<base> 确认冲突路径。

对于 gh stack sync，请使用同步后的验证顺序，而不要假装常规顺序可行。