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 Audit → Fix Iterations, 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 — bring each package's documentation in the repo, and the project's start scripts, in line with what the fixes changed, checked against the documentation standard and committed on the checkpoint branch
  3. Consolidation — an editorial pass over each package's documentation. Stories write their documentation separately, so two can cover the same topic or drift from the code; this phase merges duplicates, rewrites what drifted, removes pages about code that is gone, checks the result and commits it. The gate's Consolidation tab lists each page it changed
  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 → Fix Iterations — the project's Reviewers per Story unless the checkpoint carries its own, 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.

Pull Requests and Issues

The fixes a checkpoint makes land on a fix branch, and Trinity opens a pull request for it in every repo that has changes, ready for the human gate. Each of those pull requests links an issue on your repository host (Tracks) that carries the checkpoint's audit summary and findings as its plan, and the issue is updated when a later pass changes the audit. The issue closes as completed when the pull request merges. A checkpoint whose audit comes back clean has nothing to fix, so it opens no pull request and files no issue. A host without an issue tracker (Bitbucket) carries the audit in the pull request description instead; see Story Issues.

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)
  • Diagnose — re-enters the feedback pipeline: triage → analyst → implementer → audit → documenter

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

Auto-Approve

Toggle autoApproveQualityCheckpoints (workspace / member / 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 review round
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
  • 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