diff --git a/apps/website/content/docs/concepts/tag-driven-gates.mdx b/apps/website/content/docs/concepts/tag-driven-gates.mdx index 7068a97a..8d22f322 100644 --- a/apps/website/content/docs/concepts/tag-driven-gates.mdx +++ b/apps/website/content/docs/concepts/tag-driven-gates.mdx @@ -52,3 +52,8 @@ Once a PR merges to the main branch, the gate does not run again — it already ## Setting it up (opt-in) Tier-aware gating is **off by default**. To turn it on, set `Pre-merge tiering: enabled` in your project's `way-of-working.md` — `setup-gates` also offers this as a guided-setup question (default **No**). With the flag enabled, `pair`'s `setup-gates` capability generates the tier-aware pipeline for your stack and wires the required status checks so a red gate blocks merge; you do not hand-write the tier logic — it is generated from the quality model's matrix, with the tag-reading step and the unconditional secret-scan job included. Leave the flag off (the default) and `setup-gates` generates the full-suite pipeline where every PR runs every suite. + +## Related + +- [Quality Gates & Configuration](/docs/reference/quality-gates-configuration) — the unifying catalog that indexes tiering and the coverage guardrail alongside every other opt-in knob, and lists what is always-on (secret scanning) +- [Quality Model](/docs/reference/quality-model) — how classification produces the `risk:*` tier this gate reads diff --git a/apps/website/content/docs/customization/templates.mdx b/apps/website/content/docs/customization/templates.mdx index f0f049b5..d375ea04 100644 --- a/apps/website/content/docs/customization/templates.mdx +++ b/apps/website/content/docs/customization/templates.mdx @@ -155,6 +155,7 @@ Never edit templates in `.pair/knowledge/` — your changes will be lost on the ## Related +- [Quality Gates & Configuration](/docs/reference/quality-gates-configuration) — the catalog of opt-in quality knobs, where the template override mechanism is indexed alongside the others - [Customize for Your Team](/docs/customization/team) — override guidelines and quality gates - [Guidelines & How-To Catalog](/docs/reference/guidelines-catalog) — all guideline categories including templates - [KB Structure Reference](/docs/reference/kb-structure) — directory layout and file purposes diff --git a/apps/website/content/docs/reference/index.mdx b/apps/website/content/docs/reference/index.mdx index ec5354bf..3eee5e17 100644 --- a/apps/website/content/docs/reference/index.mdx +++ b/apps/website/content/docs/reference/index.mdx @@ -21,6 +21,7 @@ Look-up material: complete, factual, no narrative. Come here when you know what - [Configuration](/docs/reference/configuration) — `config.json` options - [Quality Model](/docs/reference/quality-model) — Default quality rules, tiers, and tags - [Coupling Model](/docs/reference/coupling-model) — The three dimensions and the balance rule behind the coupling dimension +- [Quality Gates & Configuration](/docs/reference/quality-gates-configuration) — Catalog of every opt-in quality knob (default, flag, how to enable) plus what is always-on - [Skill Management](/docs/reference/skill-management) — How skills are resolved, transformed, and installed ## Specs diff --git a/apps/website/content/docs/reference/meta.json b/apps/website/content/docs/reference/meta.json index b759f4c5..ced3d12f 100644 --- a/apps/website/content/docs/reference/meta.json +++ b/apps/website/content/docs/reference/meta.json @@ -8,6 +8,7 @@ "guidelines-catalog", "quality-model", "coupling-model", + "quality-gates-configuration", "skill-management", "kb-structure", "configuration" diff --git a/apps/website/content/docs/reference/quality-gates-configuration.mdx b/apps/website/content/docs/reference/quality-gates-configuration.mdx new file mode 100644 index 00000000..fccfae24 --- /dev/null +++ b/apps/website/content/docs/reference/quality-gates-configuration.mdx @@ -0,0 +1,52 @@ +--- +title: Quality Gates & Configuration +description: One catalog of every opt-in quality configuration knob — what it is, its default state, the adoption flag/mechanism, how to enable it, and its owning page — plus what is mandatory and always-on. +--- + +Most of pair's quality mechanisms are **opt-in**: they ship **off** in the framework/dataset defaults and a project turns them on deliberately. This page is the single **catalog** of those knobs — discover in one place what exists, its default state, and how to enable each — and a clearly separated list of what is instead **mandatory / always-on**. + +This page is an **index, not a re-explanation**: every row deep-links to the owning concept/reference/guideline page for depth. It does not duplicate that page's prose — if a default or flag ever changes, the owning page is the source of truth and this catalog links to it. + +## Opt-in quality configuration + +Every row carries the same uniform schema — **what it is · default state · adoption flag / mechanism · how to enable · owning page**. Defaults below are the **framework/dataset defaults** (what a fresh `pair install` ships), not any single project's choices — see [Framework defaults vs pair's own opt-ins](#framework-defaults-vs-pairs-own-opt-ins). + +| Knob | What it is | Default | Adoption flag / mechanism | How to enable | Owning page | +| --- | --- | --- | --- | --- | --- | +| **Pre-merge tiering** | Tier-aware pre-merge gate: scales CI effort to each PR's `risk:*` tier by reading the tag only, running fewer checks on low-risk PRs | `disabled` — every PR runs the full check suite | `Pre-merge tiering:` line in `tech/way-of-working.md` | Set `Pre-merge tiering: enabled` in `way-of-working.md`, then run `/pair-capability-setup-gates` to regenerate the pipeline | [Tag-Driven Quality Gates](/docs/concepts/tag-driven-gates) | +| **Coverage guardrail** | Baseline regression job inside the same pipeline: fails a PR whose coverage drops below a human-committed baseline (maintaining/improving passes) | `disabled` — no coverage job generated | `Coverage guardrail:` line in `tech/way-of-working.md`; baseline in `tech/coverage-baseline.md` | Set `Coverage guardrail: enabled` in `way-of-working.md`, then run `/pair-capability-setup-gates` — it scaffolds `tech/coverage-baseline.md` from the KB template (per-type targets, baselines left unset) and wires the coverage job. The guardrail stays advisory-only until the maintainer commits the measured `baseline.` value(s) into that file (those values are always human-authored) | [Coverage guardrail](/docs/concepts/tag-driven-gates#coverage-guardrail-opt-in-off-by-default) | +| **Template override** | Replace any shipped workflow template (commit, PR, story, …) with your own copy, resolved override-first by a plain file-existence check | KB default template (no override) | File existence: `.pair/adoption/tech/templates/-template.md` matching a shipped KB filename | Copy the KB template into `.pair/adoption/tech/templates/` and edit it — the file existing on disk is the entire mechanism | [Customize Templates](/docs/customization/templates) | +| **Tag Projection** | Which classification tag families are emitted onto cards/PRs; the matrix is always computed, projection is what surfaces as labels | `risk` proposed on first `classify` run; `cost` and all others off | `## Tag Projection` section (`Active:` list) in `tech/risk-matrix.md` | Add the family to the `Active:` list (e.g. add `cost`); `classify` writes the `risk` declaration for you on first run when you confirm | [Quality Model — Tag Projection](/docs/reference/quality-model#tag-projection--eligibility) | +| **Criticality Table / Overrides** | Adoption delta over the quality model: service/domain → High/Medium/Low criticality, threshold tweaks, per-tier reviewer count / SLA overrides | Absent — KB defaults apply completely | `## Criticality Table` and/or `## Overrides` sections in `tech/risk-matrix.md` | Add the section(s) to `tech/risk-matrix.md` (e.g. `tier.red.reviewers: 2`); each section is independent — none implies the others | [Quality Model — Project Overrides](/docs/reference/quality-model#project-overrides--techrisk-matrixmd) | + +> **Boundary case — knob without a dedicated owning page.** Where a knob has no page of its own yet, its row links to the closest existing owner (the concept or the quality model) rather than a dead link. When a dedicated page ships later, the link is retargeted here. + +## Framework defaults vs pair's own opt-ins + +The **Default** column above is always the **framework/dataset default** — what the KB template ships with. A project (including pair itself) may opt into any knob; that project-level choice does **not** change the framework default. + +Concrete example: pair **dogfoods** the Coverage guardrail — its own `tech/way-of-working.md` sets `Coverage guardrail: enabled` and wires a CI job. The framework default **remains `disabled`**: a fresh `pair install` ships the guardrail off. Read a default here as "what you get out of the box", not "what pair runs on its own repo". + +## What is NOT optional (mandatory / always-on) + +These are not opt-in knobs. The first two are **truly always-on** — they run regardless of any adoption flag or risk tier. The third is a **default-on** state that Pre-merge tiering **supersedes** once enabled (turning tiering on is precisely what stops the full suite running on every PR). All three exist to make the opt-in vs always-on line unambiguous. + +| Mechanism | State | Why it is not tier-scoped | +| --- | --- | --- | +| **Deterministic secret scanning** (gitleaks by default, R6.5/D24) | Always active on every PR | A secret is a secret no matter how small the change — never skipped, never scoped to a tier, and independent of `Pre-merge tiering` | +| **Base pipeline** (install + lint + type + build) | Runs at every tier | The floor of verification; tiering only ever _adds_ checks above this, never removes the base | +| **Full-suite default** | Default-on — **superseded when `Pre-merge tiering` is enabled** | With `Pre-merge tiering: disabled` (the default), every PR runs the full check suite — tiering is a _narrowing_ optimization layered on top, so "off" is the safe, complete-verification state. Unlike the two rows above, this is not unconditional: enabling tiering narrows what runs per PR | + +Secret scanning is a separate deterministic CI layer, distinct from `assess-security` (which is judgment-based classification). See [Tag-Driven Quality Gates](/docs/concepts/tag-driven-gates) for how the always-on jobs sit alongside the tier matrix, and [Quality Model](/docs/reference/quality-model) for the classification pillars that feed the `risk:*` tag. + +## Keeping this catalog current + +This page is the **unifying index** of opt-in quality configuration. When a new opt-in knob ships, adding its row here — with the full uniform schema and a link to its owning page — is part of that feature's Definition of Done, so the catalog never silently drifts out of date. + +## Related + +- [Tag-Driven Quality Gates](/docs/concepts/tag-driven-gates) — the pre-merge tiering + coverage guardrail mechanics and the always-on jobs +- [Quality Model](/docs/reference/quality-model) — tag projection, tiers, and the `tech/risk-matrix.md` adoption delta +- [Customize Templates](/docs/customization/templates) — the file-existence template override mechanism +- [Customize for Your Team](/docs/customization/team) — how adoption files override guidelines and gates +- [Configuration](/docs/reference/configuration) — `config.json` registry and target options diff --git a/apps/website/content/docs/reference/quality-model.mdx b/apps/website/content/docs/reference/quality-model.mdx index 3db2d7f6..713df310 100644 --- a/apps/website/content/docs/reference/quality-model.mdx +++ b/apps/website/content/docs/reference/quality-model.mdx @@ -49,6 +49,7 @@ Optional file with up to three independent sections — none imply the others: * ## Related +- [Quality Gates & Configuration](/docs/reference/quality-gates-configuration) — the unifying catalog of every opt-in knob (tag projection, criticality overrides, tiering, coverage) and what is always-on - [Guidelines Catalog](/docs/reference/guidelines-catalog) — where the Quality Model sits among the other 9 guideline categories - [Customize for Your Team](/docs/customization/team) — how to override guidelines via adoption files - [KB Structure](/docs/reference/kb-structure) — directory layout, `knowledge/` vs `adoption/`