Let the model write Liquid.
Never let it publish.

Generation is the easy half

Here is the architecture, and the interesting thing about it is how little of it is the model.

A local inference server runs a code-specialised model for Liquid and a small embedding model for retrieval. Product records are indexed into a vector store so that when the system writes about an item, the specification comes from the record rather than from the model's memory of what that kind of item usually is. That is the entire generation stack, it runs on one machine, and the system's own documentation describes it as the secondary concern.

Read that twice, because it inverts the way nearly everyone is currently building. The usual shape is: get a better model, write a better prompt, add a retry, maybe have a second model review the first one. Every one of those moves spends effort on the probabilistic half. This system spends its effort on the half that can be proven, and treats the model the way you would treat a contractor — useful, replaceable, and not allowed near the keys.

Why this is worth copying even at small scale

You do not need eleven control sets to get the benefit. The benefit arrives the moment the decision to publish stops being made by the same kind of system that wrote the thing. Two components, one wall:

• Generator. Any model, any prompt, any vendor. It has one job and no authority.
• Gate. Ordinary code — regular expressions, parsers, lookups against a record. It has authority and no creativity.

The wall is the product. Once it exists, a model upgrade is a Tuesday afternoon rather than a re-audit, because nothing about your safety depends on which model produced the text.

Sort your rules by what a violation costs

The gate is thirty-seven deterministic checks across seven surfaces where a claim can appear. The design decision worth stealing is not the number. It is that the rules are tiered by consequence, and only the cheapest tier is allowed to pass with a warning.

Notice what tiering buys you: it makes “warn” a legitimate outcome again. In an untiered checker every rule eventually gets downgraded to a warning, because one over-strict rule blocking a good batch at midnight is all it takes. Then the warnings pile up and nobody reads them. Tiering stops that slide by deciding, in advance and in writing, which rules are allowed to be advisory.

Try the tiering yourself

Below is the same decision the gate makes, with the certificate names replaced by placeholders. Each candidate sentence runs through the tiers in order and stops at the first one that catches it. Work out where each stops before you reveal it — the interesting ones are the sentences that are entirely true.

The case that publishes is the point of the exercise. A gate that rejected it would be a gate that suppresses true, carefully-phrased sentences — and the system's own specification says so in as many words: “do not over-block. A linter that rejects all certification language suppresses true statements.” Over-blocking feels safe and is not free. It trains everyone around it to turn the gate off.

A rule is a class of things. A token is one thing.

This is the defect that recurs more than any other, in every linter anyone has ever written, and it survives review because the broken version works on the example you tested it with.

Three instances from the handover, each shipped, each found later:

The third row is the one people underestimate. An over-fitted rule is quietly useless; a mis-modelled rule is loudly useless, and 518 false positives in one run will get the whole linter switched off by lunchtime. Both failures come from the same mistake — implementing the nearest thing you can express instead of the thing the rule says.

The tie-breaker that keeps this honest

You need a stated policy for what happens when a rule and a legitimate sentence disagree, and you need it written down before the argument, because in the moment the person who wants to ship will win it. Deciding in advance that the true sentence wins means every conflict becomes a bug report against the rule instead of a negotiation about the content.

Classify these six checks

Each one is a real check from a real linter, described by what it does rather than what it was meant to do. Decide whether the implementation actually expresses the rule.

No control is trusted until it has been made to go red

Two hundred and seventy-five controls across eleven sets, one command to run them, and an instruction in the handover that everything else depends on: if it is not green, nothing below is trustworthy. That part is ordinary. This part is not:

Twice. In one month. In a suite built by someone who takes this more seriously than almost anyone, and who wrote the register of his own ungated rules by hand. A control that passes with its subject disabled is not a weak control — it is a zero control that reports one, and it is indistinguishable from a real one until you break something on purpose.

The mechanics are small. For each control: comment out the rule it exercises, run the suite, and assert that this control fails and its neighbours do not. If it stays green, it was never testing what its name says. If the neighbours also go red, your controls are entangled and a single rule change will produce a wall of noise you will learn to ignore.

The because field

Every control in the suite carries the verbatim input that made it fail, stored next to the assertion. Not a description of the failing input — the input. This is a small habit with a large payoff:

• A failure message that contains the exact offending text costs nobody a debugging session.
• The control is self-documenting, so a year later you can tell what it was for without reading the rule.
• Most importantly, you cannot write the field without having actually seen the control fail. The format enforces the discipline above by making the green-only path impossible to complete.

That last point is the design lesson. When a discipline depends on somebody remembering to do a step, make the artifact impossible to finish without it.

Find the control that is lying

Three rounds. Each shows a set of controls after a mutation run — the rule under test has been switched off, so exactly one control in each round should have gone red and one is reporting something it cannot know.

Which control should have failed and did not?

One control passes for the wrong reason.

Two controls went green. Only one of them is honest.

An instrument is not a gate

The system has a similarity metric. It measures how much language a batch of generated descriptions shares — overlapping eight-word sequences across the corpus — and it was being read as a quality bar: below this number, good; above it, repetitive.

Then somebody checked what the number does when nothing changes except how many documents you feed it.

The metric more than doubled because the corpus grew. That is not a defect in the metric — more documents means more chances for any given phrase to recur, and the measurement is doing exactly what it says. The defect was in what it was being used for. A number that moves with the size of the thing you measure cannot be a threshold, because the threshold is then secretly a statement about corpus size.

What it was changed into

The fix is a good demonstration of the difference between the two kinds of measurement, and it split one number into two jobs:

• As an instrument: a generator regression test, run at a fixed reference corpus size. Because N is pinned, a movement in the score is now a movement in the generator, which is the only thing the number was ever able to tell you.
• As a gate: scored per document against a pinned reference set, with a stated bar. A document over the bar is dropped; the batch is not refused. One repetitive description should not cost you thirty good ones.

Both halves are now honest, and neither could have been made honest while they were the same number. If you have a metric on a dashboard that people treat as a pass mark, ask what it does when your input volume doubles. If the answer is “it goes up”, you do not have a pass mark. You have a thermometer somebody has drawn a line on.

The brief is the lever. The prompt is not.

This is the module that will change how you work tomorrow, and it is backed by measurements rather than opinion.

The system had a repetition problem: generated descriptions were converging on the same phrasing. The obvious response is prompt engineering — tell the model to vary its language, give it a list of phrases to avoid, add a style instruction. Here is what was actually tried, and what each move was worth.

The third row is the expensive lesson. Hundreds of individual corrections, carefully applied to live records, moved the measurement by three-tenths of a percentage point. All that effort went into the output, where the leverage is not.

Where prompt guidance does work — and where it provably does not

This is not an argument that prompts do nothing. The system's own register is more precise than that, and the precision is the useful part:

The practical test costs you one run: write the guidance, run it, and if the defect is still there, stop rewording and write a check. Two attempts is information. Eleven is a decision you have already made and are declining to notice.

The register: seventeen rules with no gate at all

The most unusual document in this repository is a list its author wrote against himself. Thirty-three routed rules; seventeen of them have no deterministic check behind them and are defended only by instructions in a prompt. It names each one, and it says plainly what that defence is worth.

And then it draws the line in exactly the right place:

Ungated where a mistake is ugly. Gated where a mistake is a lie. That is the same tiering from module 01, applied one level up — to the question of which rules get a checker at all. You will never gate everything. Deciding out loud which gaps you are accepting, and writing the list down, is what separates a known risk from a surprise.

A confession, because the register earned it

The seventeenth ungated rule in that document is about CSS. It says position: sticky fails in several ways — an overflow declaration on an ancestor, a transform, a static ancestor, a missing offset — and that when it fails, the sticky element simply stops sticking and the page still looks fine in review.

A rule written down with no checker behind it is a prediction of a future defect. That is the whole class in one sentence, and this is the evidence for it. The assembler that builds this page now carries a gate that refuses to write the file if the rail is declared static at any width. It is fourteen lines long. It would have cost ten minutes a week earlier.

Refuse before you prompt

The cheapest check is the one that runs before the model does. This system keeps a short list of things it will not do at all, and the list has no override argument — not a flag, not an environment variable, not a --force. That absence is the design.

Four permanent refusals

1. Three classes of theme file are never written. The layout directory and the two settings files. A generated edit to any of them can take down every page on the storefront at once, and no amount of linting makes that acceptable. They are excluded at the path level, before a generation request can be formed.
2. Ineligible items are refused before a prompt exists. If an item is outside the category the rules were written for, the system does not generate cautiously — it does not generate. Eligibility is a precondition, not a validation step.
3. There is no staging environment for product records. The system says so explicitly, which is the honest thing to do: every product write lands live. Knowing which of your surfaces have no rehearsal changes how you gate them.
4. Snapshots are dated, immutable and additive. Never overwritten, never regenerated in place.

Write the refusal list before you write the generator. It is the only part of the design that gets harder to add later, because by then somebody will have a deadline and a good reason.

Five traps, each paid for in production

None of these is in anybody's documentation in a form that would have saved the time. Each cost a halted run, a wrong verdict, or a day.

1. The comment that eats your query

Tooling recognises a leading #graphql tag inside a template literal and switches on syntax highlighting and validation for it. It is genuinely useful. It is also a comment, in GraphQL, to the end of its line — so anything you write after it on that same line is not part of the query. If your query opens on that line, the opening is gone, and the error you get back is a parse failure pointing somewhere unrelated.

2. The read-back that reads the wrong half

The Assets API updates an asset's metadata before its body. For a second or two after a write, the checksum and the timestamp are the new ones and the value is the old one. A lost-update guard that fetches the body and hashes it is therefore blind in exactly the window it exists to cover: green on every edit older than two seconds, silently wrong on every fresh one.

3. The character the platform changes behind you

A bare ampersand is canonicalised to its entity form on the way in. So a byte-for-byte comparison between what you wrote and what the platform now holds will report a difference that is not a difference. Use a surface-aware compare where two layers meet — and only there. A backup-versus-live comparison is two reads of the same system, so that one must stay a byte compare or you will normalise away a real corruption.

4. The control that reads a cache

“A control that reads a cache tests the cache.” Three controls in this suite were green and measuring nothing, because the fixture they read had been captured before the code they were testing existed in its current form.

5. The reference derived from the thing under test

A verification run reported every record identical to its backup. That proved nothing, because the backup had been re-taken from live after the write. The rule is short and absolute: never verify against a reference derived from the thing under test. If your baseline is regenerated from your own output, your comparison is a tautology that reports as a pass.

Read the publish helper line by line

Three of the five traps are in these nine lines, and the function looks reasonable. Work through it and mark the lines that are wrong.

async function publish(key, body) {  const q = `#graphql mutation Upsert($k: String!) {?    themeFilesUpsert(files: {filename: $k}) { userErrors { message } }  }`;  const res = await admin(q, { k: key, body });  await sleep(1000);?  const live = await get(key);  return md5(live.value) === md5(body) ? 'ok' : 'mismatch';?}

Build the wall, then put a model behind it

Each project stands alone and each one is small. Do them in order: the later ones assume the artifacts the earlier ones produce. None of them requires the model to be good, which is the point — use whatever generator you already have.

Write the specification for project 1

The tier table is the artifact everything else hangs off, and it is the one people skip. Fill this in and take the output with you — it is a specification, not a prompt, and it is meant to be read by a person before it is read by anything else.

Quoted

Every passage in quotation marks on this page is verbatim from the reference system's own documentation, written by its author about his own work before this class existed.

Measured

The repository scale in module 00, and the sticky-rail failure in module 05, were measured on 2026-09-22 by the methods stated in their receipts.

Reported, not measured here

The control count, the check count, the register size and every before-and-after percentage are figures the reference system reports about itself. They are reproduced as reported and were not independently re-measured.

Not verified

Whether the system is running today or its controls are green as you read this. It is bound to a private machine and unreachable from here.

Deliberately absent

Certificate names and schemes, supplier identities, product counts, file paths, hostnames, ports, theme identifiers and model names. The tiering is the transferable part; the specifics are not yours and were not the lesson.