The Blueprint Gate

The blueprint gate is the enforce layer of FlowForge’s blueprint discipline. The Blueprints Are Sacred doctrine teaches the discipline in prose; the gate makes skipping it visible. Before feature-sized work is dispatched, the gate checks that the work’s blueprints are linked in the docs trail.

The gate guides and warns by default, with every override recorded; hard enforcement that refuses dispatch is opt-in. It is not a hard block out of the box — it never silently stops your work.

What the gate looks for

Before dispatching feature-sized work, the work’s umbrella must have these artifacts linked in the docs trail:

Artifact	Trail role	Authored by
Requirements	`requirements`	`fft-requirements-analyst`
PO brief	`po-brief`	`fft-product-owner`
Architecture decision	`adr`	`fft-architecture` (`flowforge adr`)
Mockup — only where a screen exists	`designer-mockup`	`fft-designer`

The pre-dispatch habit

Run the gate check before you dispatch a feature-sized worker:

flowforge gate check <ticket|work-id>

Exit 0 — pass. Dispatch freely.
Exit 1 + WARN — the work is feature-tier and artifacts are missing. The honest move is to author them (flowforge trail new, flowforge adr new, flowforge trail link). If you must dispatch anyway, re-run with --override: it exits 0 and records the override in the audit log. Overriding is allowed; invisible overriding is not.
Exit 1 + BLOCK — hard mode, which is an opt-in settings value, not the default. There is no CLI bypass: author the blueprints, or dial the mode back in settings.

The same check runs automatically at the worker-spawn chokepoint — the TUI spawner, the MCP create_worker tool, and ForgePlay all converge on one spawn implementation. In warn mode the spawn proceeds and proceeding past the warn is the recorded override; in hard mode the dispatch is refused.

Size tiers — never crying wolf

The gate is size-tiered so the feature-level warning keeps its teeth. A gate that warns on every typo fix teaches users it is noise, and the discipline evaporates.

Trivial and bugfix work passes free.
Feature is the default tier.

The gate classifies by precedence: an explicit --tier flag first, then title and label conventions (fix: / bug → bugfix; chore: / docs / typo → trivial; feat: / epic → feature), then the trail work-node kind, and finally — when nothing else resolves — it defaults to feature.

# Escape hatch when the default over-classifies your work
flowforge gate check <ticket> --tier trivial
flowforge gate check <ticket> --tier bugfix

# Declare a screen so the mockup requirement applies
flowforge gate check <ticket> --screen

The default biases toward feature on purpose: a gate that defaulted to trivial would vanish for anyone who never labels their work. When the default fires, the warning says so and offers the --tier escape hatch.

Children inherit their umbrella’s blueprints. A micro-ticket under a blueprinted feature passes — the artifacts live on the umbrella, exactly how the umbrella-and-child-ticket convention is meant to work.

Screens are opt-in by declaration. --screen (or ui/tui/frontend conventions) adds the designer-mockup requirement. Backend work never gets warned about mockups.

Why every override is recorded

The warn-override rate — overrides divided by feature warns — is the single most honest measure of whether people are routing around the discipline. It is the spine’s number-one vital sign.

A recorded override is a legitimate professional judgment call. A climbing override rate is a product signal worth paying attention to. That is exactly why the gate warns loudly and records, rather than blocking silently or absolutely: the goal is visibility, not obstruction.

Hard enforcement (opt-in)

If you want the gate to refuse dispatch rather than warn, you can switch it to hard mode in settings. This is an explicit opt-in — it is never the out-of-box default. In hard mode there is no CLI bypass; you either author the blueprints or change the setting back.

The structural sibling: EMIT ⟺ RATIFIED

The blueprint gate warns; it does not, by default, refuse. Its harder-edged sibling sits one step later in the flow, at ticket emission. When a feature’s blueprint has been ratified, its implementation tickets are written by flowforge feature emit from the ratified record — and a guard denies a controller’s direct gh issue create (or the API/GraphQL equivalents) for implementation work. There is no path to hand-create a ticket that skips the blueprint.

This is the EMIT ⟺ RATIFIED chokepoint: ratification is the precondition for emission, and emission is derived from the ratified design rather than typed by hand. Like the blueprint gate, it is honest about its edges — overriding is possible via a recorded override and a kill-switch, and the guard fails safe (permits) on a genuine infrastructure error, because a guard that false-blocks reads as “the product is broken.” What it never does is let an implementation ticket appear with no blueprint behind it and no record of the exception.

The enforcement registry — what is truly enforced vs. what is discipline

FlowForge keeps an honest enforcement registry — an internal map that grades each invariant as enforced by construction (a fails-closed chokepoint), partial (enforced on some paths, or a wired warning that records but does not block), or discipline only (upheld by a skill or a habit, with no chokepoint). The blueprint gate above is graded partial — a wired warning that records every override — precisely because it warns rather than blocks by default. The EMIT ⟺ RATIFIED chokepoint is graded enforced. Keeping that distinction honest, rather than implying everything is a hard lock, is the point: the discipline is real where it is enforced, and candid about where it is still a habit.

Honest degrades

The gate never crashes a dispatch, never silently passes feature work, and never writes the trail — it is a pure read. When the trail is not ready, it offers guidance instead of failing:

No trail in the repo → flowforge trail init.
Ticket not registered → flowforge trail new --provider-ref N.
Index missing or stale → flowforge trail heal.

Blueprints Are Sacred — what blueprints are once ratified.
The Process — where the gate sits in the full delivery flow.