docs: Quality gates & configuration reference (catalog of opt-in quality knobs)

[rucka]

Story Statement

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 — instead of hunting across concepts/, customization/, and reference/.

Where: docs-site (apps/website), a new page under reference/ — content only, no framework/skill logic.

Epic Context

Parent Epic: #93 Website & Documentation — Landing + Docs + Brand Identity
Status: Refined
Priority: P1 (Should-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Classification

risk:green · cost:green · coupling: not assessed — no domain artifacts

Matrix — per dimension

Dimension	Tier	Source	Note
Service/domain criticality	green	KB default	docs-site content; no runtime/service surface
Change/diff risk	green	story scope	one new MDX page + nav entry + a few cross-link edits, content-only
Business impact	green	subdomain class (supporting)	documentation; no user-facing product behavior
Security relevance	green	path heuristic	pure MDX under apps/website/content/docs, no secrets/auth/infra paths
Coupling balance	not assessed	absent	no domain artifacts for this scope; excluded from tier max (D21/D38)

Risk tier = max across assessed dimensions = 🟢 green. Cost class = green (no build/runtime/infra cost — a docs page). risk:* projection is active in this repo, so risk:green is emitted; cost class shown for completeness.

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given a reader on the docs-site who wants to know which quality mechanisms are configurable
   When they open the new "Quality gates & configuration" reference page
   Then they see a single catalog listing every opt-in quality knob, each row carrying the uniform schema: what it is · default state · adoption flag / mechanism · how to enable · link to owning guideline/concept page.

2. Given the catalog page
   When the reader scans it
   Then it covers at least: Pre-merge tiering (Pre-merge tiering: disabled default, way-of-working.md), Coverage guardrail (Coverage guardrail: disabled default, way-of-working.md + tech/coverage-baseline.md), Template override (file-existence mechanism adoption/tech/templates/<name>-template.md), Tag Projection (## Tag Projection in tech/risk-matrix.md; risk proposed, cost/others opt-in), and Criticality Table / Overrides (tech/risk-matrix.md adoption delta).

3. Given the same page
   When the reader looks for what is NOT optional
   Then a clearly separated section lists the mandatory / default-on gates — with deterministic secret-scanning (gitleaks, R6.5/D24) called out as always-active and never tier-scoped — so the opt-in vs always-on distinction is unambiguous.

4. Given the docs navigation and the existing feature pages
   When the reader browses the reference/ section or lands on a related page (concepts/tag-driven-gates, reference/quality-model, customization/templates)
   Then the new page is listed in the reference/ nav (meta.json) and linked from reference/index.mdx, and each related feature page cross-links to it as the unifying index.

5. Given the page content
   When each opt-in knob's default state and enable-flag is stated
   Then it matches the current source of truth (e.g. framework default disabled for tiering and coverage guardrail, per the KB/dataset template — not pair's own project-level opt-in), and each row deep-links to its owning concept/reference/guideline page rather than duplicating that page's prose.

Business Rules

• Uniform schema is mandatory for every catalog row: what · default · flag/mechanism · how to enable · guideline link. No row omits a column.
• The page is an index/catalog, not a re-explanation: it links to the owning page (tag-driven-gates, quality-model, templates) for depth; it does not duplicate their content.
• Defaults quoted are the framework/dataset defaults (default-off for tiering & coverage guardrail), explicitly distinguished from pair's own dogfooding opt-ins where relevant.
• Content only — the story introduces no skill, CLI, or pipeline logic; it documents existing mechanisms.

Edge Cases and Error Handling

• Invalid Input: N/A — static docs page; no user input.
• System Errors: build-time — page must pass the docs-site build (MDX/lint, internal-link check); broken internal links fail the build.
• Boundary Conditions: a knob whose owning page does not yet exist → link to the closest existing owner (concept or quality-model) and note it, rather than a dead link.
• Exceptional Scenarios: a new opt-in knob ships later → page carries an explicit maintenance note (this catalog is the unifying index; each feature PR adds its row here as part of its DoD), so staleness is visible.

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• Content follows docs-site conventions (frontmatter title+description, MDX structure, heading hierarchy)
• Code review completed and approved by team member
• Internal links resolve (docs-site link check passes)
• Nav updated: page added to reference/meta.json and linked from reference/index.mdx
• Cross-links added from related feature pages to the catalog
• Docs-site build + lint pass

Quality Assurance

• Every catalog row carries the full uniform schema (no missing column)
• Opt-in vs mandatory/default-on distinction present and correct (secret-scan called out)
• Defaults/flags match current source of truth (way-of-working flags, risk-matrix sections, template resolution)
• No content duplication — rows link to owning pages
• Renders correctly (local docs-site preview)

Deployment and Release

• Merged to main; docs-site deploy (Vercel) succeeds
• Page reachable in production nav under Reference

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: S (2)
Confidence Level: High
Sizing Justification: One new MDX page with a well-understood schema (mechanisms already documented on their own pages), plus a nav entry, an index link, and a handful of one-line cross-link edits. No logic, no tests beyond the docs build/link check. Breadth (5 knobs + mandatory-gates contrast) is content assembly, not complexity.

Sprint Capacity Validation

Sprint Fit Assessment: Fits comfortably in a single sprint.
Development Time Estimate: ~0.5 day
Testing Time Estimate: ~0.25 day (build + link check + preview review)
Total Effort Assessment: Fits within sprint capacity: Yes

Story Splitting Recommendations

Not required — story is already small and delivers end-to-end value (a reachable, linked catalog page) in one slice.

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: None hard-blocking. Content is most accurate once the opt-in reframes it documents are settled — coverage guardrail opt-in (#282) and pre-merge tiering (#258, already opt-in). If any default is still in flux, quote the current KB/dataset default and update on change (maintenance note covers this).
Dependent Stories: None.
Shared Components: Sibling of #353 (operational narrative "how the delivery process changes") — complementary, not blocking. This story is the configuration reference (knob catalog); #353 is the process narrative. Distinct from reference/quality-model (conceptual model) and reference/configuration (registry config.json).

Team Coordination

• Frontend: N/A (content only; uses existing docs-site MDX + nav).
• Backend: N/A.
• QA: Verify catalog completeness and default-state accuracy against source of truth.
• UX/UI: N/A beyond standard docs page rendering review.

External Dependencies

Third-party Integrations: None.
Infrastructure Requirements: Existing docs-site build + Vercel deploy.
Compliance Requirements: None.

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: Docs-site build + MDX lint + internal-link check; manual preview review against the AC checklist (schema completeness per row, opt-in vs mandatory split, cross-links present).
Test Data Requirements: None.
Environment Requirements: Local docs-site dev/build; production deploy verification.

User Validation

User Feedback Collection: Review by a maintainer familiar with the quality model; optional adopter read-through.
Success Metrics: A reader can, from this one page, name every opt-in knob, its default, and how to enable it — without opening the source repo.
Rollback Plan: Revert the docs PR (content-only; no runtime impact).

Notes and Additional Context

Refinement Session Insights: Story reframed from the Draft "knobs" brief into a refined DoR-complete spec. Scope confirmed content-only on apps/website. Parent epic set to #93.
Team Concerns: Keep the catalog an index (link, don't duplicate) so it does not drift from the owning pages; the maintenance note makes staleness visible and ties row-upkeep to each feature PR's DoD.
Future Considerations: A staleness/link-check gate could later assert every opt-in flag documented in way-of-working.md/risk-matrix.md has a catalog row (out of scope here).
Documentation Links: concepts/tag-driven-gates.mdx, reference/quality-model.mdx, customization/templates.mdx, reference/configuration.mdx (registry config — explicitly the other configuration page).

Technical Analysis

Implementation Approach

Technical Strategy: Add one new MDX reference page and wire it into the docs-site nav; add cross-links from the related feature pages. No framework, skill, CLI, or pipeline changes. Purely apps/website docs content.
Key Components:

• New page apps/website/content/docs/reference/quality-gates-configuration.mdx (frontmatter + uniform catalog table(s) + mandatory/default-on contrast section + maintenance note).
• Nav: apps/website/content/docs/reference/meta.json (add the page) and apps/website/content/docs/reference/index.mdx (link under "Structure & configuration").
• Cross-links: one line each in concepts/tag-driven-gates.mdx, reference/quality-model.mdx, customization/templates.mdx.
  Data Flow: N/A — static content rendered by the existing Fumadocs/Next.js docs pipeline.
  Integration Points: Docs-site build + internal-link validation; Vercel deploy.
  Design: not required — approach is understood; standard docs page following existing reference/ page conventions.

Technical Requirements

• Follow docs-site MDX conventions (frontmatter title/description, heading hierarchy, tables).
• All internal links must resolve (build fails otherwise).
• Content matches current source of truth for defaults/flags.
• Accessibility/readability per existing docs-site standards (no new components required).

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Documented defaults drift from KB/dataset source of truth	Medium	Medium	Quote current defaults, deep-link owning pages, add explicit maintenance note tying row-upkeep to each feature PR's DoD
Content duplicates owning pages and diverges	Low	Medium	Catalog is an index — rows link out, do not restate depth
Broken internal links	Low	Low	Docs-site build/link check in CI

Spike Requirements

Required Spikes: None.
Estimated Spike Effort: 0.

Task Breakdown

• T1 — Draft catalog page: create apps/website/content/docs/reference/quality-gates-configuration.mdx with frontmatter and the uniform-schema table(s) covering pre-merge tiering, coverage guardrail, template override, tag projection, criticality table/overrides (AC1, AC2, AC5).
• T2 — Mandatory/default-on contrast section: add the "what is NOT optional" section, secret-scanning (gitleaks, R6.5/D24) called out as always-active (AC3).
• T3 — Maintenance note: add the staleness/maintenance note tying each future knob's row to its feature PR DoD (edge case, business rule).
• T4 — Nav wiring: add the page to apps/website/content/docs/reference/meta.json and link it under "Structure & configuration" in apps/website/content/docs/reference/index.mdx (AC4).
• T5 — Cross-links: add one cross-link to the catalog from each of concepts/tag-driven-gates.mdx, reference/quality-model.mdx, customization/templates.mdx (AC4).
• T6 — Verify: run docs-site build + internal-link check, preview-review against the AC checklist (schema completeness, opt-in vs mandatory split, links resolve).

---

Refinement Completed By: Product Engineer (AI-assisted refinement)
Refinement Date: 2026-07-23
Review and Approval: Pending product-owner confirmation on board move to Refined