/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", "output": "string"}, "test": {"status": "pass|fail|skip", "output": "string"}}

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": "pass|fail|skip",
  "test": "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 `{typecheck-command}` — must produce 0 errors. 2. Run `{test-command}` — must pass (exit code 0). 3. Run `{lint-command}` — must pass (warnings OK, errors NOT OK). 4. Check changed files for debug artifacts: `console.log`, `debugger`, `TODO: remove`.

Behavior: BLOCKING. Do not commit if any check fails. Fix quick issues (<2 min) inline. For anything longer, create a `priority::high` issue and proceed without committing the affected files.

> **Broken-Window cross-reference (#730/H5):** a Full-Gate PASS that ships with a documented exception (echo-stub, WARN-lint, overridden f