Quality Checkpoints

Quality checkpoints are stories of type quality_checkpoint that act as story-level quality gates. They run an intensive inspection pipeline separate from the regular 4-phase story pipeline, and pause for human review before downstream stories continue. They're distinct from release gates — releases run their own pipeline, documented on the Releases page.

What They're For

Use quality checkpoints when you want Trinity to pause and audit progress before the next batch of stories builds on top. Good placements:

  • End of a meaningful feature set
  • Before a major architectural shift
  • Anywhere downstream stories depend on the earlier work being correct

The Dependency Mapper phase of PRD planning places quality checkpoints automatically at natural boundaries, but you can also add or move them manually.

The Checkpoint Pipeline

When a worker picks up a quality_checkpoint story, it runs a dedicated pipeline (src/lib/execution/checkpoint/pipeline-run/index.ts):

  1. Audit / Implement loop — audit across every review lens → implement the auditor's findings → re-audit. The loop runs up to the checkpoint's authored audit→implement iterations (its audit_passes setting), early-exiting when an audit comes back clean. The auditor flags correctness, completeness, testing, architecture, and structural problems; the implementer resolves them (correctness fixes and structural moves both).
  2. Documentation — write up findings, update relevant knowledge pages
  3. Consolidation — editorial pass over project knowledge: merge duplicates, clean stale story references, dedupe gotchas
  4. Human gate (quality_checkpoint_approval) — review + approve before the block downstream of this checkpoint can run

Audit coverage and iterations

Every checkpoint audit runs the full set of review lenses in parallel — Security & Auth, Performance & Scalability, Error Handling & Robustness, Maintainability & Readability, Feature Completeness, Architecture & Patterns, and Structural Organization. This coverage is fixed; it isn't a knob.

The one tunable input is the checkpoint's audit→implement iterations — its audit_passes setting, edited on the story's Execution Settings card (floored at 1):

  • 1 — audit-only gate: the loop audits and reports once, but doesn't auto-implement.
  • 2 — one implement pass + re-verify.
  • 3 — standard quality gate: implement and re-verify until the audit comes back clean (no critical or warning findings; info is advisory). This is the typical checkpoint value.

Scope

Each checkpoint is scoped to the stories that depend on it. At audit time, the pipeline only inspects code produced by those upstream stories — it doesn't review pre-existing code or unrelated parts of the repo. This keeps the audit focused and prevents fix loops from trying to clean up the whole codebase.

On imported projects, the checkpoint prompt receives extra guidance: the Dependency Mapper places checkpoints more frequently (every 2–4 stories) and scopes them tightly to new-feature areas, so the audit doesn't drift into legacy code.

Dependency Gating

Downstream stories should list the checkpoint's display ID in their depends_on array. The coordinator treats a pending checkpoint as a hard block — nothing downstream runs until the checkpoint is approved (or skipped).

Approval

When the checkpoint pipeline reaches the gate, the Run page shows a quality_checkpoint_approval gate on the checkpoint story:

  • Approve — marks the story passed; downstream stories become runnable
  • Skip — acknowledges unresolved issues and continues (logs an entry in the audit trail so you have a paper trail for skipped gates)
  • Provide feedback — re-enters the feedback pipeline: triage → analyst → implementer → audit loop → documenter

Approvals and skips both transition the checkpoint to completed and unblock downstream work.

Auto-Approve

Toggle autoApproveQualityCheckpoints (global / team / project / entity / job — in that cascade order) to auto-approve these gates. The gate row is still created for audit purposes but resolves immediately so execution doesn't pause.

Checkpoints vs Auditor

Two distinct "quality" mechanisms — don't confuse them:

Feature Scope When it runs Gate type
Auditor (in story pipeline) A single story Inside the 4-phase story pipeline, automatic None — internal audit loop
Quality checkpoint (this page) Multiple upstream stories As its own quality_checkpoint story quality_checkpoint_approval

Tips

  • Don't over-place checkpoints — one at the end of each big feature set is usually enough. Checkpoints add real wall-clock time.
  • Watch the reentry count — if a checkpoint keeps bouncing through feedback without converging, the scoped work likely needs manual review
  • Pair with Audit — if a checkpoint surfaces issues that span beyond its scope, follow up with the Audit tool for a full-codebase scan
  • Trust the Dependency Mapper's placements first — it has full visibility into the story graph and places checkpoints at the boundaries that give you the best ROI