Skip to content

quality-loop.md

Latest commit

 

History

History
90 lines (78 loc) · 4.5 KB

quality-loop.md

File metadata and controls

90 lines (78 loc) · 4.5 KB
Raw

Quality loop

Living document. Rationale: ADR-0019, ADR-0029. Contracts: specs/pr-review-rubric.md, specs/pr-acceptance-metric.md. docs/quality.md is a conformance alias for this file (ADR-0029).

Overview

How change quality is proposed, gated, observed, and learned from in this repo. One loop, five stations:

PR template ──► review rubric ──► CI gates ──► corrections ──► promotion
(risk tier)     (spec)            (ci.yml)     (.memory/)      (AGENTS.md,
     ▲                                                          docs, skills)
     └────────────── acceptance metric (spec) observes the stream ─────────┘

Design

  • Declare — .github/pull_request_template.md makes every PR state its risk tier (highest applicable, never lower — ADR-0019) and walk the docs-housekeeping checklist.
  • Review — the PR review rubric is the contract a review applies; the review runbook is its task-shaped form for agents.
  • Gate — .github/workflows/ci.yml (ADR-0021-compliant) runs two jobs on every PR:
    • docs-gate: node scripts/check-docs.mjs checks docs-index coverage, relative-link integrity, and symlink resolution against .coverage-thresholds.json — all 1.0, never_relax: true (the ADR-0019 guardrail: the loop may tighten, never loosen). This is the coverage gate for a repo whose product is docs.
    • scaffold-e2e: the docs-site scaffold suite (.agents/skills/frostyard-docs-site/scaffold/tests/, aliased at tests/e2e/scaffold-tests) — npm ci, then npm test builds the real site (Astro + Pagefind) and asserts on the final dist/ HTML.
  • Gate (fleet repositories) — every enabled repository pins its tools in mise.toml/mise.lock, requires them (no "skipping"), and exposes make verify (non-mutating; what a read-only reviewer runs), make check (developer, may format), and make ci (ADR-0022's gate, which calls verify) (ADR-0043), exposed as the same three make targets in every repository whatever its language (ADR-0044); the organization gate checks presence, never versions, via scripts/check-fleet-conventions.mjs (npm run check:fleet) and CI's fleet-conventions job.
  • Learn — corrections land in .memory/corrections.jsonl (append-only, five-field schema, ADR-0018) and are promoted into AGENTS.md, docs, or skills; promotion is the only sanctioned duplication.
  • Enforce mechanically — .claude/settings.json denies the ADR-0019 forbidden acts at the tool layer: merging PRs (gh pr merge), approving own work (gh pr review --approve), publishing releases (gh release), and pushing to main; session state lives in .claude/session-summary.md (ADR-0025).
  • Observe — the PR acceptance metric summarizes the stream; it informs, never gates.

Operational notes

Re-run every gate locally before pushing:

node scripts/check-docs.mjs
cd .agents/skills/frostyard-docs-site/scaffold && npm ci && npm test

Failure modes: a broken alias or missing index line fails docs-gate (fix the canonical target or the index, never the alias); scaffold-e2e failures mean the scaffold payload regressed — fix before merge, since consuming repos copy it as-is.

References