/quality-gates

name: quality-gates
user-invocable: false
tags: [reference, quality, typecheck, test, lint]
model: haiku
model-preference: sonnet
model-preference-codex: gpt-5.4-mini
model-preference-cursor: claude-sonnet-4-6
description: >
  Use this skill when referencing canonical quality check commands for typecheck, test, and lint.
  Defines 4 variants (Baseline, Incremental, Full Gate, Per-File) used by
  session-start, wave-executor, session-end, and session-reviewer.
  Reference skill — not invoked directly.

Quality Gates — Reference Skill

This skill defines the canonical quality check commands. Do NOT invoke this skill directly. Consuming skills (session-start, wave-executor, session-end, session-reviewer) reference the variant they need and execute the commands inline.

Command Resolution (policy-file-first, #183)

Quality-gate commands are resolved in this priority order:

1. **`.orchestrator/policy/quality-gates.json`** — canonical policy file (preferred). Schema: `.orchestrator/policy/quality-gates.schema.json`. Bootstrap writes a package-manager-aware default; hand-edit to customize. 2. **Session Config** `test-command` / `typecheck-command` / `lint-command` in CLAUDE.md (Claude Code / Cursor) or AGENTS.md (Codex CLI) — fallback. 3. **Hardcoded defaults** — last resort: `npm test`, `npm run typecheck`, `npm run lint`.

Loader: `scripts/lib/quality-gates-policy.mjs` exports `loadQualityGatesPolicy(repoRoot)` and `resolveCommand(policy, key, fallback)`. The Node runner `scripts/run-quality-gate.mjs` performs the same resolution inline.

If any resolved command is set to the literal string `skip`, skip that check entirely.

Scope Policy (#320)

**Lint, typecheck, and test commands MUST run with the project's canonical, unscoped invocation** as resolved above (e.g., `npm run lint`, `npm test`, `npm run typecheck`). The resolved command's own configuration (`eslint.config.*`, `tsconfig.json`, `vitest.config.*`, `package.json` scripts) is the single source of truth for which files are checked.

**Domain-split scoping is FORBIDDEN.** Do NOT replace the canonical command with narrower variants such as:

• `pnpm lint src/` or `pnpm lint src/ scripts/` — silently hides errors in `tests/`, `tests/e2e/`, `tests/integration/`, root-level config files (`vitest.config.mjs`, `eslint.config.js`, etc.), and any directory outside the chosen split.
• `pnpm exec eslint src/**/*.ts` — same blind-spot; bypasses the project's lint script.
• `pnpm test src/foo/` instead of `pnpm test --run` — masks regressions in untouched modules.

This rule applies to **every consumer** of this skill: session-start Baseline, wave-executor Incremental, session-end Full Gate, session-reviewer Per-File, discovery probes, and repo-audit. It applies whether the command is invoked by an agent, by `scripts/run-quality-gate.mjs`, or by a human running it inline during triage.

**Exception — Incremental Per-File (Variant 4) test runs:** `{test-command}` MAY be invoked with explicit changed-file arguments (e.g., `pnpm test -- auth.test.ts`) per the per-file contract. Lint and typecheck have NO per-file exception — they always run the canonical command.

**Why:** Domain-split scoping was empirically shown (consumer-repo Deep-10 retro, 2026-05-20) to hide 2 errors and 17 warnings in `tests/integration/` and `tests/e2e/` that the canonical `pnpm lint` (841-file glob) catches. Narrowing scope to `src/+scripts/` for "lint-triage" produced a green W1, but the W4 Full Gate then surfaced the hidden errors, forcing a W5 sweep. The narrow-scope variant is a foot-gun: it looks faster but leaks debt across waves.

Session Config Fields (legacy fallback)

Read these from the project's `## Session Config` section when `.orchestrator/policy/quality-gates.json` is absent:

• **`test-command`** — Custom test command.
• **`typecheck-command`** — Custom typecheck command.
• **`lint-command`** — Custom lint command.

If a field is missing, use the hardcoded default.

Variant 1: Baseline

**Used by:** session-start (Phase 3) **Purpose:** Quick health check at session start — non-blocking.

Commands: 1. Run `{typecheck-command} 2>&1 | tail -5` 2. Run `{test-command} 2>&1 | tail -5`

Behavior: Report results but do NOT block the session. Capture error counts and store them as the session baseline for later comparison.

**Script output schema (Baseline):**

{"variant": "baseline", "typecheck": {"status": "pass|fail|skip"}, "test": {"status": "pass|fail|skip"}, "typecheck_output": "string", "test_output": "string"}

In every variant, each command object that was actually spawned also carries its per-command kill ladder: `timed_out` (boolean), `kill_signals` (string[]) and `survivors` (pid[]). A skipped or stubbed command has none of the three keys (absent, never `false`/`[]`). `scripts/run-quality-gate.mjs` joins them into `orchestrator.quality_gate.{passed,failed}` (#1457). A run whose joined `timed_out` is `true` is recorded as `.failed` in every variant, although Baseline, Incremental and Per-File still exit 0 (#1459, decided 2026-10-01).

Variant 2: Incremental

**Used by:** wave-executor (after implementation waves) **Purpose:** Verify implementation waves did not break anything.

Commands: 1. Run `{test-command}` on changed files only (e.g., `pnpm test -- <changed-test-files>`). 2. Run `{typecheck-command}`.

Behavior: Report failures. If issues are found, add fix tasks to the next wave automatically. Do not block wave progression — let the next wave address regressions.

Metrics output (for consuming skills to capture):

{
  "variant": "incremental",
  "duration_seconds": null,
  "typecheck": {"status": "pass|fail|skip"},
  "test": {"status": "pass|fail|skip"},
  "errors": []
}

Variant 3: Full Gate

**Used by:** session-end (Phase 2); wave-executor (Quality wave — mechanically enforced via the `waveRole` parameter, #724) **Purpose:** Final quality gate before commit — MUST pass.

Commands: 1. Run `{typec