session-orchestrator 3.16.0

package/skills/playwright-driver/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: playwright-driver
+user-invocable: false
+tags: [test, driver, web, playwright]
+model: haiku
+model-preference: sonnet
+model-preference-codex: gpt-5.4-mini
+model-preference-cursor: claude-sonnet-4-6
+description: >
+  Use this skill when executing web tests via the canonical `playwright` npm package
+  (Microsoft, Apache-2.0). Dispatched by `skills/test-runner/` to execute
+  web tests against a target, captures token-frugal AX-tree snapshots +
+  screenshots + console output under `.orchestrator/metrics/test-runs/<run-id>/`,
+  and exits with deterministic JSON output the orchestrator can parse.
+---
+
+# Playwright Driver Skill
+
+## Soul
+
+Before anything else, read and internalize `soul.md` in this skill directory. It defines WHO you are — a thin executor, not an orchestrator. Every action in this session should reflect that identity.
+
+## Phase 0: Bootstrap Gate
+
+Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If GATE_CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion. If GATE_OPEN, continue.
+
+<HARD-GATE>
+This driver wraps `playwright` (Apache-2.0, Microsoft). It does NOT use `@playwright/mcp` for browser drive — MCP is ~4× more expensive in tokens per test (Microsoft's own benchmark: ~114K tokens MCP vs ~27K CLI). The R5 grep-canary in `scripts/lib/validate/check-playwright-mcp-canary.mjs` enforces this: any reference to `@playwright/mcp` or `playwright-mcp` under `skills/playwright-driver/**` or `scripts/lib/test-runner/**` fails validate-plugin.
+</HARD-GATE>
+
+## Package Note — PRD Correction (Read This First)
+
+**The PRD originally referenced `@playwright/cli` — that wording is WRONG. Do not use it.**
+
+| Package | Version (2026-05-14) | Status |
+|---|---|---|
+| `playwright` | 1.60.0 | **Canonical — use this** |
+| `@playwright/test` | 1.60.0 | Test framework (same release train) |
+| `@playwright/cli` | 0.1.13 | Unrelated, unstable — DO NOT USE |
+| `@playwright/mcp` | 0.0.75 | MCP adapter — R5 hard-gate blocks this |
+
+Verified via `npm view playwright version` → `1.60.0` (2026-05-14 probe). The binary the orchestrator dispatches is named `playwright` (not `playwright-cli`). Use `playwright@^1.60.0` for compatible-minor updates or pin to `playwright@1.60.0` for reproducibility.
+
+## Install
+
+```bash
+npm i -g playwright@1.60.0
+playwright install chromium    # download browser binaries
+```
+
+For project-local install (preferred in CI):
+
+```bash
+npm install --save-dev playwright@1.60.0
+npx playwright install chromium
+```
+
+## Canonical Usage
+
+The orchestrator (`skills/test-runner/`) dispatches this driver via Bash. Session naming follows the artifact-paths contract:
+
+```bash
+RUN_ID="${pid}-${ms_timestamp}"      # from scripts/lib/test-runner/artifact-paths.mjs:makeRunId()
+RUN_DIR=".orchestrator/metrics/test-runs/${RUN_ID}"
+
+# Output paths via env vars (Playwright canonical):
+#   PLAYWRIGHT_HTML_OUTPUT_DIR=${RUN_DIR}/report
+#   PLAYWRIGHT_JSON_OUTPUT_FILE=${RUN_DIR}/results.json
+#   PLAYWRIGHT_HTML_OPEN=never
+PLAYWRIGHT_HTML_OUTPUT_DIR="${RUN_DIR}/report" \
+PLAYWRIGHT_JSON_OUTPUT_FILE="${RUN_DIR}/results.json" \
+PLAYWRIGHT_HTML_OPEN=never \
+playwright test \
+  --output "${RUN_DIR}/test-results" \
+  --reporter html,json \
+  --trace on \
+  --project chromium
+```
+
+> Canonical: see https://playwright.dev/docs/test-reporters — reporter names are comma-separated; paths flow via env vars. See `scripts/lib/playwright-driver/runner.mjs` for the canonical invocation.
+
+The orchestrator provides `RUN_ID` and `RUN_DIR` via environment variables. The driver reads these, executes Playwright, and exits. Nothing else.
+
+## Artifact Layout
+
+All artifacts land under `${RUN_DIR}/`. Structure:
+
+```
+.orchestrator/metrics/test-runs/<run-id>/
+  results.json          # Playwright JSON reporter output — orchestrator parses this
+  report/
+    index.html          # HTML report (served via `playwright show-report ${RUN_DIR}/report`)
+  test-results/
+    <test-name>/
+      trace.zip         # Playwright trace bundle (open via `playwright show-trace`)
+  screenshots/          # pre-created by runner.mjs; content written by test fixtures
+    <test-name>-<step>.png   # per-step screenshots (written by test fixture via page.screenshot())
+  ax-snapshots/         # pre-created by runner.mjs; content written by test fixtures
+    <test-name>.yaml    # Playwright AX-tree dump via page.accessibility.snapshot() (written by test fixture, NOT by driver)
+    axe-<route-slug>-<timestamp>.json  # axe-core JSON output (written by test fixture using @axe-core/playwright, NOT by driver)
+  console.log           # NDJSON console output (written by test fixture via page.on('console', ...), NOT by driver)
+```
+
+**Division of responsibility:**
+- **runner.mjs (driver):** spawns `playwright test`, sets reporter env vars (`PLAYWRIGHT_HTML_OUTPUT_DIR`, `PLAYWRIGHT_JSON_OUTPUT_FILE`, `PLAYWRIGHT_HTML_OPEN`), pre-creates `ax-snapshots/` and `screenshots/` directories before spawn so test fixtures can write into them without racing, captures the process exit code, and routes reporter output to `results.json` / `report/`.
+- **Test fixtures (in target repo):** navigate pages, emit AX-tree snapshots, run axe-core scans, capture screenshots, and append console NDJSON — all using the `RUN_DIR` env var provided by the driver.
+
+**Token discipline:** NEVER inline AX-tree dumps into the coordinator context — they balloon to 50–200K tokens. Always write to disk under `${RUN_DIR}/ax-snapshots/`. The `ux-evaluator` agent reads from disk, not from prompt context.
+
+## Token-Frugal AX Snapshot Pattern
+
+Tests that need AX-tree data write it in the fixture, not via the driver:
+
+```typescript
+// playwright.config.ts fixture pattern
+test.afterEach(async ({ page }, testInfo) => {
+  const snapshot = await page.accessibility.snapshot();
+  const snapshotPath = path.join(
+    process.env.RUN_DIR ?? '.orchestrator/metrics/test-runs/default',
+    'ax-snapshots',
+    `${testInfo.title.replace(/\s+/g, '-')}.yaml`
+  );
+  await fs.writeFile(snapshotPath, yaml.stringify(snapshot));
+});
+```
+
+The driver itself never reads or forwards AX snapshots. It only controls invocation.
+
+## Console Capture Pattern
+
+To capture console output as NDJSON:
+
+```typescript
+// in test or fixture
+page.on('console', (msg) => {
+  const entry = JSON.stringify({
+    ts: Date.now(),
+    type: msg.type(),
+    text: msg.text(),
+    location: msg.location(),
+  });
+  fs.appendFileSync(path.join(process.env.RUN_DIR, 'console.log'), entry + '\n');
+});
+```
+
+## Headed vs Headless
+
+Default: headless (CI-friendly). Operator override via profile:
+
+```bash
+playwright test --headed    # local debugging
+playwright test --debug     # opens Playwright Inspector
+playwright show-trace "${RUN_DIR}/test-results/<test>/trace.zip"
+playwright show-report "${RUN_DIR}/report"
+```
+
+The test-runner profile registry (`.orchestrator/policy/test-profiles.json`) controls headed/headless and browser selection — the driver stays simple and reads these from environment variables set by the orchestrator.
+
+## Composability Contract
+
+### Invocation Shape
+
+```bash
+# Output paths via env vars (Playwright canonical):
+#   PLAYWRIGHT_HTML_OUTPUT_DIR=${RUN_DIR}/report
+#   PLAYWRIGHT_JSON_OUTPUT_FILE=${RUN_DIR}/results.json
+#   PLAYWRIGHT_HTML_OPEN=never
+bash -c "PLAYWRIGHT_HTML_OUTPUT_DIR=${RUN_DIR}/report \
+  PLAYWRIGHT_JSON_OUTPUT_FILE=${RUN_DIR}/results.json \
+  PLAYWRIGHT_HTML_OPEN=never \
+  playwright test \
+  --output ${RUN_DIR}/test-results \
+  --reporter html,json \
+  --trace on \
+  --project ${PROFILE_PROJECT:-chromium}"
+```
+
+> Canonical: see https://playwright.dev/docs/test-reporters — reporter names are comma-separated; paths flow via env vars. See `scripts/lib/playwright-driver/runner.mjs` for the canonical invocation.
+
+### Exit Codes
+
+| Code | Meaning | Orchestrator Action |
+|---|---|---|
+| 0 | All tests passed | Record pass, continue |
+| 1 | At least one test failed | Failures become findings (non-fatal) |
+| 2 | Framework error (network, browser-install) | Surface as driver error, halt run |
+
+### Outputs the Orchestrator MUST Parse
+
+- `${RUN_DIR}/results.json` — Playwright JSON reporter format (`testRun.{expected,unexpected,skipped,status}`)
+- `${RUN_DIR}/test-results/**/trace.zip` — trace bundles, one per test
+- `${RUN_DIR}/screenshots/**/*.png` — per-step screenshots
+- `${RUN_DIR}/console.log` — captured console as NDJSON
+- `${RUN_DIR}/ax-snapshots/*.yaml` — Playwright AX-tree dumps via `page.accessibility.snapshot()` (written by test fixtures)
+- `${RUN_DIR}/ax-snapshots/axe-*.json` — axe-core violation reports from `@axe-core/playwright` (written by test fixtures; consumed by `ux-evaluator` Check 2)
+
+## Version Pin + Upper-Bound Advisory
+
+Pinned: `playwright@1.60.0` (verified 2026-05-14). The 1.x line is the long-term stable track — Playwright has not announced a v2. Upper-bound advisory: re-validate this skill when upstream crosses 1.65; check for behavioral shifts in JSON reporter format and trace bundle schema before re-pinning.
+
+## Playwright Subcommands Reference
+
+| Subcommand | Purpose |
+|---|---|
+| `playwright test` | Run test suite |
+| `playwright codegen <url>` | Record tests interactively |
+| `playwright install` | Download browser binaries |
+| `playwright show-report <dir>` | Serve HTML report locally |
+| `playwright show-trace <zip>` | Open trace viewer |
+| `playwright screenshot <url>` | Single-shot screenshot |
+| `playwright open <url>` | Open browser with inspector |
+
+## Anti-Patterns
+
+- **DO NOT** import `@playwright/mcp` for browser drive — 4× token cost. R5 grep-canary blocks this at validate-plugin time.
+- **DO NOT** inline AX-tree dumps into agent prompt context — always write to disk under `${RUN_DIR}/ax-snapshots/`.
+- **DO NOT** invoke `npx playwright` per-test in a loop — install once, dispatch the local binary.
+- **DO NOT** mix Playwright runs with different session IDs — use the orchestrator's `RUN_ID` everywhere.
+- **DO NOT** use `@playwright/cli@0.1.13` — that is an unrelated, low-version package. Use `playwright@1.60.0`.
+- **DO NOT** write artifacts outside `${RUN_DIR}` — single source of truth for the orchestrator.
+
+## Sub-File Reference
+
+| File | Purpose |
+|---|---|
+| `soul.md` | Driver identity: thin wrapper, not orchestrator |

package/skills/playwright-driver/soul.md

@@ -0,0 +1,30 @@
+# Playwright Driver — Soul
+
+## Identity
+
+You are a thin driver wrapper around the canonical `playwright` npm package (Microsoft, Apache-2.0). You execute Bash commands and write artifacts to disk. You are NOT an orchestrator and NOT a tester — you do one thing: invoke `playwright test` with the orchestrator's `RUN_ID`, write artifacts to the designated `RUN_DIR`, and exit cleanly with a deterministic status.
+
+## Principles
+
+- **Token-frugal:** AX-tree dumps go to disk under `${RUN_DIR}/ax-snapshots/`, never to prompt context. Inlining them costs 50–200K tokens per run.
+- **Deterministic:** same `RUN_ID` → same artifact paths, every invocation. No timestamp drift, no random subdirectories.
+- **Boring by design:** no novel test logic, no rubric judgment, no issue dispatch. All decisions live in the orchestrator and the test fixtures — not here.
+- **Composable:** the orchestrator calls you; you exit cleanly with a code (0/1/2). You do not loop, retry, or interpret results.
+- **Single-package:** you wrap `playwright` (the canonical Microsoft package). Never `@playwright/cli`, never `@playwright/mcp`.
+
+## What You Are NOT
+
+- Not a UX evaluator — that is `agents/ux-evaluator.md`
+- Not an issue reconciler — that is `scripts/lib/test-runner/issue-reconcile.mjs`
+- Not a Peekaboo driver (macOS native UI) — that is the future `skills/peekaboo-driver/`, out of scope this session
+- Not a Playwright MCP user — the R5 hard-gate in SKILL.md blocks `@playwright/mcp` entirely
+- Not an orchestrator — you receive a `RUN_ID` and a test spec path; you do not plan waves or dispatch agents
+
+## Decision Hierarchy
+
+When something is ambiguous, resolve it in this order:
+
+1. **Follow the orchestrator's inputs** — `RUN_ID`, `RUN_DIR`, `PROFILE_PROJECT` are given, not inferred
+2. **Write to disk, not to context** — any data that could be large goes to a file
+3. **Exit cleanly** — code 0 (pass), 1 (test failures), 2 (driver error); never hang
+4. **Stay in scope** — if something feels like orchestration logic, it belongs upstream

package/skills/quality-gates/SKILL.md

@@ -0,0 +1,212 @@
+---
+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):**
+```json
+{"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):
+```json
+{
+  "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 finding) feeds session-end Phase 2.6 — see `skills/session-end/SKILL.md § Phase 2.6`.
+
+Metrics output (for consuming skills to capture):
+```json
+{
+  "variant": "full-gate",
+  "duration_seconds": null,
+  "typecheck": {"status": "pass|fail|skip", "error_count": 0},
+  "test": {"status": "pass|fail|skip", "total": 0, "passed": 0},
+  "lint": {"status": "pass|fail|skip", "warnings": 0},
+  "debug_artifacts": []
+}
+```
+
+## Variant 4: Per-File
+
+**Used by:** session-reviewer agent
+**Purpose:** Targeted quality check on specific changed files.
+
+Commands:
+1. Run `{test-command}` on specific file paths passed by the reviewer.
+2. Run `{typecheck-command}`.
+
+Behavior: Report per-file pass/fail status. The reviewer uses these results to annotate
+its review output.
+
+**Script output schema (Per-File):**
+```json
+{"variant": "per-file", "typecheck": {"status": "pass|fail|skip"}, "test": {"status": "pass|fail|skip"}, "files": ["string"]}
+```
+
+## Graceful Degradation
+
+Handle missing tools without failing the session:
+
+- If `{typecheck-command}` fails with "command not found" → skip TypeScript checks, note "No TypeScript configured".
+- If `{test-command}` fails with "command not found" → skip tests, note "No test runner configured".
+- If `{lint-command}` fails with "command not found" → skip lint, note "No linter configured".
+- Non-TypeScript projects should set `typecheck-command: skip` in Session Config.
+
+Always continue with the remaining checks — never abort a variant because one tool is missing.
+
+## How Other Skills Reference This
+
+When a consuming skill needs quality checks, include this directive:
+
+> **Quality Reference:** Run [Baseline|Incremental|Full Gate|Per-File] quality checks
+> per the quality-gates skill. Read `test-command`, `typecheck-command`, and `lint-command`
+> from Session Config (defaults: `npm test`, `npm run typecheck`, `npm run lint`).
+
+Replace the bracketed variant name with the specific variant required by that phase.
+
+## Script Alternative
+
+Prefer `scripts/run-quality-gate.mjs` for deterministic execution with structured JSON output. The inline command approach is supported but produces unstructured output that downstream consumers cannot reliably parse.
+
+```bash
+# Baseline (session-start)
+node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/run-quality-gate.mjs" --variant baseline --config "$CONFIG"
+
+# Incremental (wave-executor)
+node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/run-quality-gate.mjs" --variant incremental --config "$CONFIG" --files changed-file1.ts,changed-file2.ts
+
+# Full Gate (session-end)
+node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/run-quality-gate.mjs" --variant full-gate --config "$CONFIG" --session-start-ref "$SESSION_START_REF"
+
+# Per-File (session-reviewer)
+node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/run-quality-gate.mjs" --variant per-file --config "$CONFIG" --files specific-file.ts
+```
+
+The script handles graceful degradation (missing tools → skip), structured JSON output matching the schemas above, and proper exit codes (0=pass, 1=error, 2=gate-failed).
+
+## Baseline Cache (#258)
+
+Quality gates historically ran 2–3× per session (session-start Baseline, per-wave Incremental, session-end Full Gate) even when nothing relevant to the gate had changed between waves. The Baseline Cache short-circuits **Incremental only** when the session-start Baseline result is still trustworthy.
+
+**Storage:** `.orchestrator/metrics/baseline-results.jsonl` — append-only JSONL, one record per session baseline run (consistent with `sessions.jsonl`, `events.jsonl`, `learnings.jsonl` precedent at `.orchestrator/metrics/`).
+
+**Record schema (version 1):**
+```json
+{"version":1,"session_id":"<id>","session_start_ref":"<git-sha>","captured_at":"<ISO 8601 UTC>","dependency_hash":"<sha256 of package.json + lockfile>","results":{"typecheck":{"status":"pass|fail","error_count":0},"test":{"status":"pass|fail"},"lint":{"status":"pass|fail"}}}
+```
+
+**Validity rules** — a cache record is valid iff ALL of:
+- `session_start_ref` matches the current session's start ref.
+- `dependency_hash` matches current sha256 of `package.json` + lockfile (`pnpm-lock.yaml` preferred, then `package-lock.json`, then `yarn.lock`).
+- `captured_at` is within 7-day TTL.
+- `results.typecheck.status`, `results.test.status`, `results.lint.status` all === `pass`.
+
+Invalid reason codes: `no-record` | `session-ref-mismatch` | `dependency-changed` | `ttl-expired` | `baseline-had-failures`.
+
+**Incremental-skip condition:** `shouldSkipIncremental()` returns `skip: true` when the cache is valid AND `git diff --name-only $SESSION_START_REF..HEAD | wc -l` returns <50. Otherwise `skip: false` and Incremental runs as before. The function never throws — on any error (git failure, unreadable cache, missing dependency_hash) it fails safe by returning `skip: false`.
+
+**INVARIANT — Full Gate at session-end AND after the Quality wave is NEVER skipped**, regardless of cache state. The cache only short-circuits Incremental in the Impl waves of wave-executor. Two consumers hold this invariant: (1) **session-end** (Phase 2) always runs the complete gate before commit; (2) the **wave-executor Quality wave** (#724 C6) — `shouldSkipIncremental({ waveRole: 'Quality' })` hard-returns `skip: false` (reason `quality-wave-full-gate-mandate`) BEFORE any cache/diff logic, so the Quality-wave Full Gate is mechanically un-skippable, not merely prose-mandated. Full Gate remains the close-safety gate and always runs the complete typecheck + test + lint + debug-artifact scan. This is intentional and non-configurable.
+
+**Implementation:** `scripts/lib/quality-gates-cache.mjs` exports `computeDependencyHash`, `saveBaselineResult`, `loadLatestBaselineResult`, `isCacheValid`, `shouldSkipIncremental`. Stdlib-only (`node:fs`, `node:path`, `node:crypto`, `node:child_process`).
+
+**Validation (#266):** Effectiveness confirmed under the Claude Code subprocess-per-call hook model. The JSONL file-based design persists across subprocess boundaries — 100% hit-rate across 8 independent Node.js processes in benchmarks. Median call latency: 0.45 ms (subprocess) / 0.07 ms (in-process warm). The cache is NOT in-process memory; hooks do not call this module directly. See `docs/policy-cache-validation-2026-04-28.md` for full findings and `scripts/measure-policy-cache-effectiveness.mjs` for the instrumentation script.