Pro · Before commit

Before a commit, GitHub must confirm the design

During Medium and Deep work, Claude writes a small note saying the design was shown and posted to GitHub. Before any commit, push or merge, a built-in check compares that note with the real GitHub issue. If GitHub cannot confirm it, the commit is blocked.

How it startsRuns automatically
Runs onCommits, pushes and merges during Medium and Deep runs

A design_gate.json receipt with the line "trail": "posted:42" highlighted, and a dotted line to a TLM Forge terminal where git commit is blocked because example-org/checkout#42 carries 0 mermaid blocks, with a card explaining the receipt claimed a post that GitHub does not show and the commit stops until both diagrams are on the issue.

How to use it

/tlmforge:build

Runs on its own before every git commit, git push and gh pr merge while a Medium or Deep run started with /tlmforge:build is open. Active on Pro. Light work does not open a run, and repos with no open run are not checked.

Words you will see on this page

Design gate: The point where TLM Forge shows you diagrams of the planned change and asks if they match what you want.
Receipt (design_gate.json): A small file Claude writes at the design gate, saying what it did and where it posted the design.
Mermaid block: A diagram written as text that GitHub draws as a picture. Two are needed: a flowchart and a sequence diagram.
Design council: On Deep work, a structured debate about the design. Each position is saved to a file, and the decisions are posted to the issue.
Hook: A small check built into the plugin that runs before Claude acts and can stop the action.
Pro: The TLM Forge plan on which this check is switched on.

What it checks

Check	Passes when	Blocks when
Receipt	design_gate.json exists for the current feature	It is missing, or names a different feature
Architecture file	docs/ARCHITECTURE.md exists	It is missing
Issue number	The receipt's issue number matches the one saved for the feature, on a github.com repo	The numbers differ, or the repo is not on github.com
Diagrams on GitHub	The issue and its comments hold two or more Mermaid blocks	There are fewer than two
Council (Deep only)	The council's decisions comment is on the issue and at least two position files exist	A council result is claimed with nothing behind it
GitHub reachable	gh can read the issue	GitHub is down, gh is missing or signed out, or the issue does not exist

When it runs, and when it does not

Situation	Checked?
Commit, push or merge during an open Medium or Deep run	Yes
Light work	No, Light work does not open a run
A repo with no open run	No
A run more than seven days old from another session	No
TLMFORGE_GITHUB_TRAIL=0, or the receipt says the trail was off	Local checks only, no GitHub call
"just do it" in your latest message, or TLMFORGE_HOOKS=0	Let through

What it does

The design gate is where you see the diagrams and approve them before anything is built. At that point Claude writes a small receipt, design_gate.json, saying what it did and where it posted the design. But the receipt is the AI's own account, and a run that skipped the gate is exactly the run whose account you cannot trust. So this check compares the receipt with something outside Claude's own files: the real GitHub issue.

Before a commit, push or merge, the check reads the receipt and makes sure it matches the current feature and issue number, and that docs/ARCHITECTURE.md exists. Then it reads the issue and its comments on GitHub. It needs at least two Mermaid diagrams, for the flowchart and the sequence diagram. On Deep work that claims a design council result, it also needs the council's comment and position files. Any gap stops the command with a message.

The rest of the GitHub trail never stops your work if GitHub is down. This check is different on purpose. If GitHub is unreachable, gh is missing or signed out, or the issue does not exist, it blocks and asks you to review the local files. A silent pass on a sign-off nobody can confirm is what it exists to prevent. A crash in the check itself, or an unreadable receipt, still lets the command through.

How it works, step by step

Spots the commit
It runs when a command contains git commit, git push or gh pr merge, even inside a longer chained command.
Checks that a run is open
It acts only during an open Medium or Deep run from this session or less than seven days old. Old spec folders and fresh installs are left alone.
Reads the receipt
A missing receipt blocks, and so does a receipt for a different feature. Light work passes.
Checks local files
docs/ARCHITECTURE.md must exist, the issue number must match, and the repo must be on github.com.
Checks GitHub
It reads the issue and every comment and counts the Mermaid diagrams, two or more required. Deep work with a council result also needs the council's comment.
Blocks or remembers the pass
A gap stops the command with a clear message. A pass is remembered per feature, so later commits make no network call, while a failure is checked again every time.

What it looks like

What you see when GitHub cannot confirm the design was posted (invented feature, message shortened). The check stops the commit and lists the local files to review.

$ git commit -m "retry failed charges"
[tlmforge] Design gate could not be verified against GitHub.
The receipt claims the design was posted, but that claim could not be confirmed. GitHub was
unreachable, `gh` is missing or unauthenticated, or the issue does not exist.
  specs/payment-retries/design_gate.json   what the run claims it did
  specs/payment-retries/.github_issue      the issue number it claims
  specs/payment-retries/debate/            council positions, if this was a Deep run
If the gate did happen and GitHub is simply down, proceed with the bypass below.
If it did not, run the gate before committing.
To proceed anyway: set TLMFORGE_HOOKS=0, or include 'just do it' in your message.

Why it is better

Checked against GitHub, not Claude's word

Without TLM Forge, you can only ask the AI to be honest about the design step. With it, the receipt is checked against the real issue, so a skipped or half-done design step shows up before the commit.

Unconfirmed means blocked

Without it, a missing answer from GitHub could pass quietly. With it, an unconfirmed sign-off is treated as unconfirmed, and you get a short list of files to review.

Clear, fixable messages

Without it, you would hunt for what went wrong. With it, each block names one problem, such as no receipt, no diagrams on the issue, or an issue number mismatch.

Cheap once it passes

Without caching, every commit would call GitHub. With it, once a feature passes, later commits in that feature make no network call.

Good to know

Active on Pro. The setting is controlled from the TLM Forge server, so it can change without a plugin update. In the server's warn mode it prints WOULD BLOCK and lets the command through.
Only Medium and Deep runs are checked.
To get past it, set TLMFORGE_HOOKS=0, or include "just do it" in your latest message ("be quick" and "trivial fix" also work).
With TLMFORGE_GITHUB_TRAIL=0, or a receipt saying the trail was off, only the local checks run. A receipt saying the post failed still blocks, so a person takes a look.
It counts the diagrams. It does not judge whether they are right or whether the design is good. That is your job when you approve the design.

Related features

Get TLM Forge