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.ts):

  1. Analyze — scan the codebase, identify quality targets for the checkpoint's scope
  2. Audit / Fix loop — multi-perspective audit scaled by checkpoint complexity → fix critical issues → re-audit. Loop continues up to a max-iteration cap.
  3. Refactor analysis — identify structural simplifications across the inspected scope
  4. Refactor execution — apply the refactors
  5. Documentation — write up findings, update relevant knowledge pages
  6. Consolidation — editorial pass over project knowledge: merge duplicates, clean stale story references, dedupe gotchas
  7. Human gate (quality_checkpoint_approval) — review + approve before the block downstream of this checkpoint can run

Scaling

Two inputs scale the pipeline's intensity, derived from the checkpoint's gated stories:

  • Audit perspectives — 2–7 auditors running in parallel (more for larger checkpoints)
  • Max fix iterations — 2–5 passes around the Audit / Fix loop

Both can be overridden per-run from the Run modal's Checkpoint pipeline tuning section. The defaults (auto) scale from difficulty of the gated stories.

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 → simplify 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.

Release-level gates (release_approval) are always manual — the auto-approve setting only applies to story-level quality checkpoints.

Checkpoints vs Release Gates vs Auditor

Three 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 simplify loop
Quality checkpoint (this page) Multiple upstream stories As its own quality_checkpoint story quality_checkpoint_approval
Release gate A full release When a release transitions to releasing release_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