Execution Gates

Gates are checkpoints where Trinity pauses the pipeline and asks for your input. They keep you in control of decisions that the agent can't (or shouldn't) make on its own.

How Gates Work

When an agent or the coordinator detects a situation that needs human judgment, it raises a gate. The job transitions to waiting_gate, a notification appears on the Run page and in the sidebar task indicator, and the pipeline won't advance until you respond.

Gates are tied to an entity (either a story or a release). Each gate carries a typed payload describing what triggered it — the same structure powers both the UI and the feedback pipeline.

Gate Types

The full set of gate types (from the JobGateType enum):

Deviation Approval (deviation_approval)

When The analyst detects that a technology specified in the roadmap has a genuine blocker — security vulnerability, end-of-life status, or incompatibility with other stack choices.

Payload: The agent's analysis, the proposed alternative, and the reasoning for the substitution.

Actions
  • Approve — accept the substitution; the implementer uses the alternative
  • Reject — keep the original technology; the implementer proceeds as planned
Important
Deviations are only raised for concrete blockers (security, EOL, incompatibility). Personal preference or "this is better" are **not** valid grounds — the prompt explicitly filters those out.

Missing Assets (missing_assets)

When The analyst declared one or more specific asset needs in its plan — real visual content the story can't ship with placeholders (hero imagery, logos, product photos, brand icons). This is plan-time, raised by the analyst, not a heuristic regex count.

Payload: One card per declared need, each with a purpose line and a prose description of what the story expects.

Actions
  • Save & Continue — upload real assets to those cards, then the story replans with the new assets in hand
  • Use Placeholders — explicit opt-in. Trinity threads this choice back into the analyst as a feedback directive so it doesn't redeclare the same need on replan. The post-checkpoint placeholder audit remains the safety net.

Skip globally: toggle skipAssetCheck in project settings or globally. The flag is resolved up front and threaded into the analyst prompt so the analyst never declares when you've opted out.

Checkpoint + Release Placeholder Audits

Quality and release checkpoints run a full-worktree placeholder scan in addition to the analyst-plan pre-flight. Two regex families are independent:

  • Images (skipCheckpointAssetAudit / skipReleaseAssetAudit) — catches shipped placeholder.svg, picsum.photos, Lorem ipsum, etc.
  • Contacts (skipCheckpointBusinessDetailsAudit / skipReleaseBusinessDetailsAudit) — catches example.com emails, 555-* phones, John Doe, Your Company, stale copyright years.

Findings surface as entries on the existing checkpoint / release approval gate — each with file:line refs.

Agent triage (optional): turn on aiPlaceholderTriageCheckpoint / aiPlaceholderTriageRelease to run an agent that classifies each match as leak (blocks), fixture / docs (info, non-blocking), or false_positive (dropped). For leaks, the agent also suggests a replacement using the project's uploaded assets + business details. Default: off at checkpoint (frequent), on at release (high stakes).

Custom excludes: placeholderAuditExcludes (project / team / global) is a list of glob patterns added to the hard-coded base list (node_modules/, **/__tests__/**, etc.). A .trinityignore file at the worktree root is also honoured (gitignore syntax).

On-demand scrub: Project Settings → Audit Codebase runs the same scan at any time — informational, nothing blocks.

Missing Business Details (missing_business_details)

When The analyst flags the story needs business info (company name, contact email, branding) but the project's business details aren't populated.

Payload: Which fields are missing + why the story needs them.

Actions
  • Fill in details in Project Settings → Business, then resume
  • Skip — proceed without business details

Skip globally: toggle skipBusinessDetailsCheck in project settings or globally.

Missing Secret (missing_secret)

When A story requires an API key or credential that isn't configured in the project's secrets.

Payload: Which service needs the key + why.

Actions
  • Add the secret in Project Settings → Secrets, then resume
  • Skip — proceed without (the story will likely fail when it calls the service)

External Dependencies (external_deps)

When The story requires something outside Trinity's control — a third-party service to be provisioned, manual configuration, or setup an agent cannot automate.

Payload: List of external deps (name, description) and a human-readable explanation.

Actions
  • Complete the action externally, then resume
  • Skip — proceed without

Story Blocked (story_blocked)

When An agent raised its hand. Any pipeline phase (Analyst, Implementer, Documenter, Checkpoint Fix) can call the `signal_blocked` MCP tool when it genuinely cannot make progress — intractable build error, missing context the plan doesn't cover, ambiguous requirements, a corrupted worktree, a vault write that keeps failing. The pipeline pauses at a gate so you can diagnose and unblock.

Payload: Which agent phase escalated, a prose explanation of what's stuck, and (optionally) the list of approaches the agent already tried — so you know what not to suggest.

Actions
  • Provide feedback — guide the agent through the feedback pipeline (most common)
  • Skip — mark the story as skipped
  • Cancel — kill the job

PR Review (pr_review)

When A story's PR is open and waiting for your review before the merge chain continues.

Payload: PR URLs + repo names (multi-repo projects get one entry per repo).

Actions
  • Approve — continue the merge chain
  • Provide feedback — re-run the feedback pipeline against your review comments
  • Skip — cancel this leg of the merge

Quality Checkpoint Approval (quality_checkpoint_approval)

When A `quality_checkpoint` story has finished its intensive audit pipeline and needs sign-off before downstream stories continue.

Payload: Audit findings, fixes applied, any remaining issues.

Actions
  • Approve — marks the checkpoint passed
  • Skip — acknowledges unresolved issues and continues
  • Provide feedback — re-enter the feedback pipeline
Auto-approve toggle `autoApproveQualityCheckpoints` (global, team, project, entity, or job level) to auto-approve the gate. The gate row is still created for the audit trail but resolves immediately.

Release Approval (release_approval)

When A release's pipeline has finished (preflight, SEO audit/fix, release notes, documentation, consolidation) and the release is ready to tag.

Payload: Release notes, per-repo version tags that will be created, preflight check results, audit findings.

Actions
  • Approve — tags affected repos with the semver template, walks the merge chain, marks gated stories as released
  • Skip — marks the release passed without tagging
  • Provide feedback — re-runs the release pipeline with your input
Note
`release_approval` always requires manual approval regardless of the `autoApproveQualityCheckpoints` setting — that setting only affects story-level quality checkpoints.

Release Notes Failed (release_notes_failed)

When The release notes writer agent failed to produce usable notes for one or more targets during a release run.

Payload: Which targets failed + the error details.

Actions
  • Retry — re-run the release notes writer
  • Write manually — supply your own notes inline
  • Skip — continue the release pipeline without these notes

Merge Conflict (merge_conflict)

When A story's PR can't merge cleanly — git reports conflicts Trinity can't resolve automatically.

Payload: Which repo, branch, and base branch are conflicting. Shown alongside a "resolve locally" hint.

Actions
  • Retry — re-run the merge (useful after you pushed a manual conflict resolution)
  • Skip — leave the PR open and continue the merge chain without this repo
  • Abort — cancel the job entirely

External PR Closed (external_pr_closed)

When A PR Trinity opened was closed on GitHub outside Trinity (manually or by another tool) while Trinity was still waiting on it.

Payload: PR URL, branch, and repo — so you can see what was closed.

Actions
  • Recreate — re-open a fresh PR with the same branch and keep going
  • Skip — accept the PR is dead; skip this leg of the merge chain
  • Abort — cancel the job

Partial Merge Failed (partial_merge_failed)

When A release tagged some repos but others failed to merge or tag (e.g., a branch protection rule rejected the push, a CI check flipped red during the tagging window).

Payload: Which repos succeeded vs. failed, with error details per failed repo.

Actions
  • Retry failed — re-attempt the failed repos (bounded by releases.auto_retry_count, capped at 3)
  • Skip failed — accept the partial release; successful repos stay tagged, failed repos remain un-tagged

This gate is specific to polyrepo releases — monorepo/turborepo releases either all succeed or all fail.

Release to Base (release_to_base)

When A release has been tagged and is ready to merge its release branch into the base branch (only appears when `useReleaseBranches` is on and `autoReleaseToBase` is off — otherwise the merge happens automatically).

Payload: The release branch, target base branch, and which repos are in scope.

Actions
  • Merge to base — runs the merge
  • Skip — leave the release branch alone (advanced — the release stays released but base doesn't catch up)

Gate Feedback

Instead of a binary approve/skip, every gate supports a feedback response that re-enters the story (or release) through the feedback pipeline:

  1. Triage — Claude classifies what you're asking for
  2. Analyst — re-reads the codebase with your feedback as context
  3. Implementer — makes changes (no commit)
  4. Simplify loop — Auditor passes over the new changes
  5. Documenter — commits, updates the PR, walks the merge chain

This is the sanctioned way to iterate on agent output without editing code yourself. It's the same shape for story gates and release gates.

Attachments

When you provide feedback, you can attach files:

  • Screenshots of desired behavior
  • Updated wireframes or specs
  • API contracts or documentation
  • Anything the agent might need to reason about

Attachments are scoped to the gate and cleaned up when the gate resolves (approve / skip / merge). They're not mixed into project assets.

Gate Reentry

Every gate tracks how many times it's been re-entered via gate_reentry_count. Visible on the gate card — useful for spotting stories that keep bouncing back through feedback without converging. If a story hits a high reentry count, that's usually a sign the problem needs manual intervention or a restructured plan.

Best Practices

  • Respond promptly — gates block the pipeline, and dependent stories stall behind them
  • Prefer feedback over skip — the feedback pipeline can fix most issues without you editing code
  • Be specific — "Make the button blue" beats "This doesn't look right"; include screenshots when layout matters
  • Use skip judiciously — skipped work can leave downstream stories brittle; the gate exists for a reason
  • Audit skipped gates — check the activity feed to see which gates you skipped and why