[US-371] docs: quality gates & configuration reference (catalog of opt-in quality knobs)

[rucka]

PR Information

PR Title: [US-371] docs: quality gates & configuration reference (catalog of opt-in quality knobs)
Story/Epic: #371, parent epic #93
Type: Documentation
Priority: P1 (Should-Have)

Summary

What Changed

Adds one new docs-site reference page, apps/website/content/docs/reference/quality-gates-configuration.mdx, that catalogs every opt-in quality configuration knob (pre-merge tiering, coverage guardrail, template override, tag projection, criticality table/overrides) in a uniform schema, plus a clearly separated "what is NOT optional" section for always-on mechanisms (deterministic secret scanning — gitleaks, R6.5/D24 — and the base pipeline). Wires the page into nav (reference/meta.json, reference/index.mdx) and cross-links it from the three related feature pages (concepts/tag-driven-gates.mdx, reference/quality-model.mdx, customization/templates.mdx).

Why This Change

Opt-in quality mechanisms are currently discoverable only by reading through concepts/, customization/, and reference/ individually — there is no single place that tells a reader what exists, its default state, and how to turn it on. This page is that unifying index, content-only, introducing no new framework/skill/CLI logic.

Story Context

User Story: As a team adopting pair (docs reader / tech lead evaluating what to turn on), I want one docs-site reference page that catalogs every opt-in quality configuration with a uniform schema — and explicitly flags what is instead mandatory/default-on — so that I discover, in one place, which quality mechanisms exist, their default state, and how to enable each.

Acceptance Criteria: All 5 ACs in #371 addressed in this single PR (see mapping below).

Changes Made

Implementation Details

• New reference page — quality-gates-configuration.mdx: opt-in catalog table with the uniform schema (What it is · Default · Adoption flag/mechanism · How to enable · Owning page) for Pre-merge tiering, Coverage guardrail, Template override, Tag Projection, Criticality Table/Overrides (AC1, AC2).
• "What is NOT optional" section — mandatory/always-on table: deterministic secret scanning (gitleaks, R6.5/D24, never tier-scoped), base pipeline, full-suite default (AC3).
• Framework vs pair's own opt-ins — dedicated section distinguishing the framework/dataset default (disabled for tiering & coverage guardrail) from pair's own dogfooding choice (guardrail enabled on this repo), so defaults quoted are never conflated with pair's project-level adoption (AC5, Business Rules).
• Nav + cross-links — added to reference/meta.json and reference/index.mdx; added a ## Related (or entry) link from concepts/tag-driven-gates.mdx, reference/quality-model.mdx, customization/templates.mdx back to the new page as the unifying index (AC4).

Files Changed

• Added: apps/website/content/docs/reference/quality-gates-configuration.mdx
• Modified: apps/website/content/docs/reference/meta.json, apps/website/content/docs/reference/index.mdx, apps/website/content/docs/concepts/tag-driven-gates.mdx, apps/website/content/docs/reference/quality-model.mdx, apps/website/content/docs/customization/templates.mdx

Testing

Test Coverage

• Manual Testing: pnpm --filter @pair/website build — full Next.js/MDX production build, 81 static pages generated successfully, no broken internal links.

Test Results

Test Suite: N/A (content-only, no code)
Build: ✅ Passing (next build — 81/81 pages)
Linting: ✅ Clean (repo pre-push quality gate — ts:check, test, lint, prettier/mdlint, hygiene, docs:staleness, skills:conformance, dup:check — all passed on push)
Security Scan: N/A — no code/secret-relevant paths touched

Testing Strategy

• Happy Path: page renders under /docs/reference/quality-gates-configuration, reachable from nav and from each of the three cross-linked feature pages.
• Edge Cases: the "boundary case" callout in the page itself documents what happens when a knob has no dedicated owning page yet (link to closest existing owner, e.g. quality-model, rather than a dead link) — per AC's Boundary Conditions.
• Error Handling: N/A — static content; build-time link/MDX validation is the only "error path" and it passed.

Documentation

Documentation Updates

• Technical Documentation: this PR is the documentation change — see Summary.

Reviewer Guide

Review Focus Areas

1. Schema completeness per row — confirm none of the 5 catalog rows (tiering, coverage guardrail, template override, tag projection, criticality table/overrides) omits a column (what/default/flag/how-to-enable/owning-page), per Business Rules.
2. Default accuracy — confirm defaults quoted (disabled for tiering & coverage guardrail, "KB default — no override" for templates, risk proposed / others off for tag projection, "absent" for criticality table) match the current source of truth in way-of-working.md, risk-matrix.md, and the tag-driven-gates/quality-model pages, and that pair's own dogfooded Coverage guardrail: enabled is called out as a project-level opt-in, not the framework default.
3. Always-on section unambiguous — confirm the "what is NOT optional" table clearly separates always-on mechanisms (secret scanning, base pipeline) from the opt-in catalog above it, with no risk of a reader treating gitleaks as tier-scoped.
4. Nav/cross-link wiring — confirm the page appears in reference/meta.json's sidebar order and reference/index.mdx's list, and that the three related pages link back to it as the unifying index rather than duplicating its table.

Testing the Changes

git checkout docs/US-371-quality-gates-configuration-reference
pnpm install
pnpm --filter @pair/website build
pnpm --filter @pair/website dev   # then open /docs/reference/quality-gates-configuration

Key Test Scenarios

1. Navigate to /docs/reference — the new page is listed and links to /docs/reference/quality-gates-configuration.
2. Open the new page — verify all 5 knob rows render with all 5 schema columns filled, the "what is NOT optional" table is visually separated, and the framework-vs-pair's-own-opt-ins section is present.
3. From /docs/concepts/tag-driven-gates, /docs/reference/quality-model, /docs/customization/templates — confirm each has a working link back to the new catalog page.

Dependencies & Related Work

Related PRs

• Related: [#242] feat: refine-story = single Draft→Ready (grill phase 0, classify, map-* scoped) + template Classification slot #360 (refine-story classification template slot), [#258] feat: tier-aware pre-merge pipeline — reads classification tags only, fail-safe red #362 (tier-aware pre-merge pipeline), [#282] feat: coverage baseline + CI guardrail (tier-aware pipeline gate) #368 (coverage baseline + CI guardrail) — this page is the discovery index over those mechanisms; no code dependency, content-only.

---

Notes for reviewer (context not visible elsewhere): No ADR/ADL was needed — this is content-only, documents existing mechanisms, introduces no new decision. Classification (from the story): risk:green / cost:green (docs-only change, no domain/coupling artifacts — coupling dimension excluded from tier per D21/D38).

[rucka]

Code Review — PR #375

Review Information

• PR Number: [US-371] docs: quality gates & configuration reference (catalog of opt-in quality knobs) #375
• Author: rucka (Gianluca Carucci)
• Reviewer: Independent reviewer (Claude Code, /pair-process-review)
• Review Date: 2026-07-24
• Story/Epic: US-371 (parent epic Website & Documentation — Landing + Docs + Brand Identity #93)
• Review Type: Docs (content-only)

Review Summary

Overall Assessment

• Approved with Comments — Minor issues noted, can merge

Key Changes Summary

Adds one new reference page apps/website/content/docs/reference/quality-gates-configuration.mdx — a catalog of every opt-in quality knob (pre-merge tiering, coverage guardrail, template override, tag projection, criticality table/overrides) under a uniform 5-column schema, plus a "what is NOT optional" section (secret scanning, base pipeline, full-suite default) and a framework-vs-pair's-own-opt-ins section. Wires it into reference/meta.json + reference/index.mdx and cross-links it from concepts/tag-driven-gates.mdx, reference/quality-model.mdx, customization/templates.mdx. No code/skill/CLI/pipeline logic. +61/-0.

Business Value Validation

Delivers the story's value: a single discovery index for opt-in quality configuration. Verified reachable via nav + all three cross-links.

Acceptance Criteria Verification

AC	Verdict	Evidence
AC1 uniform-schema catalog	PASS	5-column table (what · default · flag/mechanism · how to enable · owning page); no row omits a column.
AC2 covers the 5 named knobs w/ correct defaults+flags	PASS	Tiering disabled (way-of-working.md:39); Coverage guardrail framework default disabled (way-of-working.md:40); Template override file-existence .pair/adoption/tech/templates/<name>-template.md (template-resolution.md:11); Tag Projection Active: risk, cost/others off (risk-matrix.md:5-9); Criticality Table/Overrides absent→KB defaults (risk-matrix.md:3). All match source of truth.
AC3 "what is NOT optional" section, secret-scan always-on	PASS (see Minor-1)	Separate table; gitleaks R6.5/D24 called out always-active and never tier-scoped.
AC4 nav + index + 3 cross-links	PASS	meta.json (valid JSON, page inserted after quality-model); index.mdx under "Structure & configuration"; cross-links present in all three feature pages.
AC5 defaults match source of truth, deep-link not duplicate	PASS	All defaults verified against way-of-working.md / risk-matrix.md / coverage-baseline.md; pair's dogfooded Coverage guardrail: enabled explicitly separated from the framework default; rows deep-link, do not restate prose.

All 5 business rules satisfied (uniform schema, index-not-re-explanation, framework-vs-own defaults, content-only).

Link & Build Integrity (verified statically)

• All 6 page-level link targets exist as .mdx files.
• All 3 fragment anchors recomputed via GitHub-slugger and match the target headings exactly:
  • #coverage-guardrail-opt-in-off-by-default → "Coverage guardrail (opt-in, off by default)" ✓
  • #tag-projection--eligibility → "Tag Projection & Eligibility" ✓ (double hyphen correct)
  • #project-overrides--techrisk-matrixmd → "Project Overrides — tech/risk-matrix.md" ✓ (double hyphen correct)
• meta.json valid JSON. New page has correct frontmatter (title+description) and no accidental h1 (title from frontmatter; all ##). Consistent with sibling reference pages.
• Full next build was NOT re-run in review; link/anchor/JSON integrity verified statically instead. PR reports build passing (81/81 pages).

Security Review

N/A — pure MDX under apps/website/content/docs. No secrets/auth/infra paths. No introduced findings. risk:green / cost:green confirmed (not raised).

Testing Review

Content-only; no automated tests expected. Acceptance test is the docs build + link check (verified statically here). No coverage impact.

Detailed Review Comments

Positive

• Exceptionally accurate: every quoted default/flag/path/example (baseline.<type>, .pair/adoption/tech/templates/<name>-template.md, tier.red.reviewers: 2, "three independent sections — none imply the others") matches its source of truth verbatim.
• Framework-default-vs-pair's-own-opt-in distinction is handled cleanly with a concrete example — directly satisfies the trickiest business rule and AC5.
• Deep-link anchors were computed correctly including edge-case double hyphens.

Minor Issues 💡

• [quality-gates-configuration.mdx · "What is NOT optional" table] The intro says these mechanisms "run regardless of any adoption flag or risk tier," but the Full-suite default row it contains is superseded when Pre-merge tiering: enabled (the full suite stops running on every PR — that is exactly what tiering does). Its own "why" cell concedes this ("With Pre-merge tiering: disabled (the default) …"). Internal inconsistency that risks the very ambiguity AC3 asks to remove — a reader could conclude the full suite always runs even under tiering. Recommend tightening the intro to distinguish truly always-on jobs (secret scan, base pipeline) from the "default-on but supersedable" full-suite state, or annotate that row. Actionable in this PR; non-blocking.

• [quality-gates-configuration.mdx · Coverage guardrail "How to enable"] The parenthetical "Set Coverage guardrail: enabled … (creates tech/coverage-baseline.md)" ambiguously attributes file creation to flipping the flag. Recommend clarifying that the baseline file is created/committed by the maintainer (or scaffolded by setup-gates), not by the flag line itself. Low impact.

Questions ❓ / By-design notes

• [quality-gates-configuration.mdx · "Boundary case" callout + "Keeping this catalog current"] Both are forward-looking: no current row hits the "knob without a dedicated owning page" boundary (all 5 rows link to real pages), and the "adding its row here … is part of that feature's Definition of Done" claim is asserted by the page rather than encoded in an actual DoD artifact. Both are explicitly required by the story's Edge Cases (Boundary Conditions + maintenance note), and the enforcement gate is deferred by the story's own Future Considerations. By design — flagged only for transparency.

• [quality-gates-configuration.mdx · 3 fragment deep-links] Correct today, but heading-slug-derived: Fumadocs' build validates page paths, not fragments, so a future reword of an owning-page heading would silently break these anchors. This matches the established docs-site deep-linking convention (e.g. quality-model.mdx), so no change requested here.

Risk Assessment

Risk	Impact	Probability	Mitigation
Documented defaults drift from source of truth	Low	Med	Rows deep-link owning pages; maintenance note present
Fragment anchor silently breaks on heading reword	Low	Low	Docs-site-wide concern; out of scope here

Decision

APPROVED WITH COMMENTS. All 5 ACs and all business rules met; content is accurate against every source of truth. Two Minor wording items (Full-suite-default framing; coverage-baseline "creates" phrasing) are worth a quick fix but do not block merge; the rest are by-design/transparency notes.

[rucka]

Remediation — round 2 (commits eb4e44e, 0e0ce32)

Responding to the review above.

Per finding:

• [Minor] "What is NOT optional" intro over-generalizes always-on to the supersedable full-suite default (quality-gates-configuration.mdx — "What is NOT optional" table) → Rewrote the intro to distinguish the two truly always-on jobs (secret scanning, base pipeline) from the Full-suite-default row, which is a default-on state superseded once Pre-merge tiering is enabled. Annotated that row's State cell (Default-on — superseded when Pre-merge tiering is enabled) and its "why" cell to say it is not unconditional, unlike the two rows above — apps/website/content/docs/reference/quality-gates-configuration.mdx (commit eb4e44e).
• [Minor] Coverage guardrail "How to enable" wrongly implies the flag creates tech/coverage-baseline.md (quality-gates-configuration.mdx — Coverage guardrail row, "How to enable" cell) → Two-step fix. First pass (eb4e44e) rewrote the cell to say the maintainer hand-creates and commits the baseline file, the flag doesn't generate it. That first wording then surfaced its own inconsistency against concepts/tag-driven-gates.mdx and /pair-capability-setup-gates, which actually scaffold tech/coverage-baseline.md from the KB template (per-type targets, baselines left unset) rather than leaving it purely hand-authored. Second pass (0e0ce32) corrected this: setup-gates scaffolds the file; the guardrail stays advisory-only until the maintainer commits the measured baseline.<type> value(s) into it (those values are always human-authored) — apps/website/content/docs/reference/quality-gates-configuration.mdx (commits eb4e44e, 0e0ce32).

Accepted / non-actionable (no code change, disposition below):

• [By-design] "Boundary case" callout + "Keeping this catalog current" note are forward-looking — no current row hits the boundary (all 5 knobs have an owning page); the DoD claim is asserted by the page, not enforced by a DoD artifact. Both are explicitly required by the story's Edge Cases / Future Considerations, which defer the enforcement gate. Accepted as-is, no change.
• [By-design] 3 fragment deep-links are heading-slug-derived, not build-validated — Fumadocs validates page paths, not fragments, so a future heading reword could silently break these anchors. This matches the established docs-site deep-linking convention (e.g. quality-model.mdx); reviewer explicitly requested no change here. Accepted as-is, out of scope.

Quality gates: PASS — pnpm --filter @pair/website build (81 static pages, no broken links); pre-push full gate PASS on both pushes (849dffc..eb4e44e, eb4e44e..0e0ce32).

Final verdict: latest independent re-review found zero actionable findings — review clean.

→ Ready to merge (human gate).