DSH Pre-Push Checks

Use this skill to run relevant local evidence once before a deepseek-harness push. The sole ordering exception is gh stack sync, which may publish a cascading rebase before the rewritten layers can be validated; validate them immediately afterward and do not merge until the evidence passes. Git hooks are intentionally narrow: pre-commit fixes staged lint, checks staged whitespace, and guards vendored-source metadata; pre-push runs only the incremental repository typecheck. CI owns exhaustive coverage and the platform matrix.

Inspect the outgoing change

1. Confirm the checkout and branch.

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

1. Verify the live PR base or stack parent, fetch that ref, and inspect the complete scope against it.

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

The command never guesses or fetches a base. Supply the ref verified from current remote or stack state; use --head <ref> when inspecting a commit other than HEAD. Its versioned JSON records committed paths relative to the resolved merge base, while staged, unstaged, and untracked paths describe the current worktree. After merging a changed base, rerun the report, reassess which behavior the combined scope can affect, and rerun only checks invalidated by the merge.

Select relevant evidence

There is no universal local baseline beyond the hooks. 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.

When the outgoing change adds or changes a resource-owning or asynchronous test, fixture, helper, or CI execution path, use [dsh-ci-test-reliability](../dsh-ci-test-reliability/SKILL.md) first to decide whether restoration, negative-control, quiescent-teardown, or concurrent-process evidence applies. This skill still selects the commands and avoids repeating evidence that already passed.

• Package or script behavior: run the owning Vitest 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.
• Remote mock typing: unbuilt any is an explicit local fallback, not strict evidence. Run pnpm run typecheck before handing off Remote/mock changes; rebuild missing, stale, or partial generated declarations before diagnosing remaining errors. Keep the exception in the [test proxy](../../../packages/test-support/remote-mock/README.md#remote-proxy), never in production Remote types, ambient flags, or copied signatures.
• Documentation, Agent Notes, catalogs, or doc-linked comments: run pnpm run doc-sync; run full lint when the documentation workflow requires it.
• Model-, editor-, CLI-, or terminal-visible output: run the focused keyless snapshot or real runnable-example scenario that owns the output.
• Expected-output placement: a test whose selected recorded Session generation is replay input and expected persisted output belongs under top-level snapshots/, with snapshot.yml naming its shipped dsh profile and composition/header pin. Canonical parent files are session[.vN].jsonl, children are session.<ordinal>[.vN].jsonl, and the harness selects the highest generation per role. ARIA, geometry, generator, CLI, and unit expectations without that Session round trip stay beside their owning test under tests/expected/; do not place them in snapshots/ or give them a *.snapshot.ts owner. Use the owning test:expected, test:web, or test lane.
• Profile and configuration placement: cross-package behavior of a shipped dsh profile belongs under apps/cli/tests/profiles/; a package-specific Loader composition belongs under that package's tests/fixtures/. User-facing optional overlays live under apps/cli/config/examples/ and pair with a guide under docs/user/.
• Package manifests, public exports, build configuration, worker/bin entries, or built runtime paths: run pnpm run build, the relevant hygiene checks, and the owning built-artifact smoke.
• Real provider or agent behavior: run the relevant pnpm run test:e2e target when credentials are available; never print secrets.

Do not manually repeat a passing check merely because commit or push follows. In particular, do not run typecheck immediately before pushing solely to duplicate the pre-push hook.

Pass Vitest file and name filters directly after the script name with pnpm run; do not insert a standalone --, which reaches Vitest and can disable -t filtering. For example, this command runs one headless snapshot scenario:

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

This applies to these pnpm scripts; npm and other launchers retain their own argument-forwarding syntax. Check the reported selected test count before treating a filtered run as focused evidence.

Focus unit coverage on the affected source

Test selection and coverage selection are separate. A Vitest file filter chooses which tests run, while the repository configuration otherwise measures every packages///src/**/*.ts file. When unit coverage is relevant, name both the owning tests and the source files or package whose coverage those tests must prove:

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. The configured per-file 100% thresholds still apply inside the selected source scope.

When the owning tests are unclear, use Vitest's dependency graph to discover a candidate set, then inspect the selected tests before treating the run as evidence:

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

vitest related cannot discover behavior reached only through configuration, dynamic loading, subprocesses, workers, built artifacts, or external providers; select those owning tests explicitly. Do not use --passWithNoTests, lower coverage thresholds, or narrow --coverage.include merely to hide an uncovered affected file. If a selected package scope fails because one focused test does not cover it, add its other relevant owning tests or narrow the source scope only when the excluded modules cannot be affected by the change.

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 the removed check:pre-push aggregate.

Protect history-rewriting pushes

Rebase is allowed for standalone and stacked PR 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. gh stack push and gh stack sync supply lease protection for their 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.

Post-sync validation

gh stack sync fetches, cascade-rebases, and pushes as one operation, so it 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 GitHub stack order.
2. Inspect the changed scope of every rewritten layer against its live PR 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.

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 hook only when the user explicitly asks or agrees, and report exactly what failed and why CI is expected to differ.

Push procedure

For ordinary and standalone rebase pushes:

1. Run the selected relevant checks once.
2. Commit normally and inspect any files changed by the pre-commit fixer before continuing.
3. Push normally, or use the exact lease for an authorized rewritten branch, so the incremental typecheck hook runs.
4. Verify the remote ref matches local HEAD.

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

For GitHub PRs, inspect remote CI after the push:

gh pr checks

Report pending checks as pending. Inspect failures before attributing them to the branch or the environment.

When gh pr checks reports "no checks reported" and /actions/runs?head_sha=<sha> returns total_count: 0, read mergeability before suspecting the push or a dropped GitHub event:

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

GitHub creates no pull_request workflow runs while a PR is CONFLICTING/DIRTY, so the absent signal is the conflict, not infrastructure. Resolving the conflict is the only fix; empty commits, --allow-empty pushes, draft/ready toggles, and revert-and-restore bounces all leave total_count at zero and add junk history. Confirm the conflicting paths with git merge-tree --write-tree HEAD origin/<base> when the branch cannot be merged locally yet.

For gh stack sync, use the post-sync validation sequence instead of pretending the ordinary order was possible.