Compiling

Diagnostics

The checker reports provable defects as errors (they block build) and best-practice violations as warnings. Every code is explainable with typeglish --explain <code>.

Diagnostic codes

Every diagnostic carries {code, severity, range, message} and often a machine-applicable fix. Errors block build; warnings and info are advisory. Explain any code with typeglish --explain <code>.

Code	Severity	What it proves
`clarity/dead-rule`	warn	A rule whose condition can never hold, so it never fires.
`clarity/duplicate`	warn	Two rules say the same thing; one is redundant.
`clarity/unused-definition`	warn	A $DEFINE condition no $IF, $SWITCH, or guard references.
`clarity/unused-variable`	warn	A $REQUIRE variable no @{reference} ever fills into the prompt.
`config/bad-number`	warn	A numeric config param (max_tokens, temperature) is not a number.
`config/dangling-service`	error	A config param's `via` names a $SERVICE that is not defined.
`config/missing-conditional`	warn	A glish cross-field rule ($REQUIRE X when Y is Z) is unmet: the condition holds but the required kind is absent.
`config/missing-param`	warn	A config kind is missing a required param (e.g. model's via) — a nudge, not a block.
`config/out-of-range`	warn	A config param value violates its declared refinement (a numeric range, character length, or pattern).
`config/unknown-kind`	error	A $CONFIG kind the schema does not know - the line was stripped and configured NOTHING. The $-command contract: silent misconfiguration errors.
`config/unknown-model`	warn	The $CONFIG model is not a recognized model id.
`config/unknown-param`	info	A config param is not in the kind's schema.
`flow/reassignment`	info	State re-assigned along the flow — a later stage changes an earlier value. Legal (state evolves); surfaced so nothing changes silently.
`grammar/agreement`	warn	Number/person concord broken — subject × copula (the cars is) or determiner × noun (these car); collectives and PP objects abstain (THE GRAMMATICALITY NET).
`grammar/article`	warn	a/an chosen against the word’s spoken onset (a hour, an formal) — the onset table owns the phonology (THE GRAMMATICALITY NET).
`grammar/confused-word`	warn	A homophone/near-form in a seat it can never fill (you/your, its/it’s, their/there, then/than, to/too) — convicted on seat evidence with the one-edit repair (THE GRAMMATICALITY NET).
`grammar/double-word`	warn	A word repeated back-to-back, like "the the".
`grammar/spacing`	info	Irregular spacing around punctuation.
`grammar/spine`	warn	The clause spine is broken — the finite verb is missing (the car not green), uninflected (the car be green), or misplaced (the car green is); the one-edit repair restores it (THE SPINE CHECK).
`grammar/standalone-i`	warn	Lowercase "i" as a pronoun; write "I".
`import/ambiguous-file`	error	An import path several workspace files could answer by name — qualify the path so exactly one resolves.
`import/cycle`	error	Two $IMPORT files reference each other in a loop.
`import/missing-export`	error	An imported section or anchor does not exist in the target file.
`import/missing-file`	error	An $IMPORT file path resolves to no file.
`import/missing-section`	error	A {file.section} reference names a section the file lacks.
`import/nested`	error	A problem inside an imported file (imports compose transitively), reported at the $IMPORT line that pulled it in.
`import/unfilled-requirement`	warn	An imported file needs a variable the import site did not fill.
`import/unmet-section-requirement`	warn	A $REQUIRE section no file in the composed closure declares — declare it in a composing file, or keep the $REQUIRE if the platform supplies it.
`import/unused-file`	warn	An $IMPORT file is declared but never referenced.
`logic/action-count`	error	One action is given two different counts (call five tools vs call six tools).
`logic/axis-strength`	error	One truth per axis — a second same-axis value is contained by (or contains) the first, so the looser is dead weight (fast after very fast).
`logic/axis-tension`	warn	A general axis claim (`Be formal.`) and an action-scoped one (`Speak casually.`) pull opposite ways — coherent (“formal overall, casual when speaking”), but worth an explicit scope.
`logic/cardinality`	error	Two counts for one set cannot both hold (there is only one X vs there are many Xs).
`logic/contradiction`	error	Two rules provably conflict, like MUST X versus NEVER X.
`logic/definite-ambiguous`	error	A definite "the <symbol>" is bound to two or more different declared symbols.
`logic/definite-identity`	error	A definite reference resolves to the one object that carries its predication, and the statement denies that identity (the cool guy is NOT Xavi, when Xavi is the only declared cool guy).
`logic/definite-undeclared`	error	A definite "the <symbol>" names a symbol kind the file never declares.
`logic/epistemic-conflict`	error	Two statements make the same claim with opposite certainty (definitely X vs cannot X) - the certainty square proves both cannot hold.
`logic/exclusivity`	error	An "only" rule is exclusive, but another rule adds a member outside it.
`logic/force-subsumption`	error	A weaker rule is fully guaranteed by a stronger one on the same force axis (Always X entails Sometimes X, MUST X entails SHOULD X) - it adds nothing but waver.
`logic/insufficient-set`	error	A directive needs more items than the declared set holds (call five tools vs there is only one tool).
`logic/lead-clash`	warn	A lead-time floor beside a same-day grant on the same work - the booking-to-event interval cannot satisfy both. Scope one rule ("except same-day slots"), or drop one.
`logic/majority`	error	Two "most" claims about the same set cannot both hold.
`logic/measure`	error	Two money values claim one slot (over $10,000 vs under $10,000) — the intervals cannot intersect (SPEC §7).
`logic/measure-strength`	error	One money value per slot — a bound restates one it already entails, or the same amount in another surface ($10 then ten dollars).
`logic/modifier-contradiction`	error	Two rules share one action but sit at opposite poles, and the prohibition covers everything the obligation demands (MUST send short replies vs MUST NOT send replies) - both cannot hold.
`logic/numeric`	error	A numeric impossibility (at most 3 vs at least 5), proven by Z3.
`logic/only-gate`	warn	An action is gated (`X only when C` / `never X until C` — C is necessary for X) yet mandated elsewhere without the condition: the gate is provably dropped where the two co-serve (THE PROCESS SCOPE). Add the condition to the mandate, or loosen the gate.
`logic/order`	error	Steps require an impossible ordering.
`logic/quantifier`	error	Quantified statements provably conflict (all / some / no, or a universal vs a specific case).
`logic/quantifier-strength`	error	One quantity per fact — a quantified claim restates one it already entails (all vs some).
`logic/redeclaration`	error	A name is bound to two conflicting values.
`logic/syllogism`	error	A transitive quantifier chain is contradictory (all A are B, all B are C, no A is C).
`logic/time`	error	Two time values claim one event slot (closes at 9pm vs closes at 8pm) — the intervals cannot intersect.
`logic/time-strength`	error	One time bound per slot — a duration bound restates one it already entails (within 2 hours after within 30 minutes).
`logic/window-containment`	warn	A recurring slot time falls outside one operating day’s declared window while fitting the others - the slot cannot exist on that day. Scope the slot ("except Friday") or extend that day’s hours.
`prompt/agentless-passive`	info	The doer is deleted (agentless passive) or demoted to a by-phrase - name the actor or use the imperative.
`prompt/ambiguous-reference`	warn	A definite singular (the dog) points at a slot the world proves holds 2 or more - which one? Name the one you mean, or make the reference plural.
`prompt/authority-cap`	warn	An authority ceiling (refunds up to $200) beside an unbounded grant of the SAME action (offer a full refund) with no route past the cap — coherent only as ceiling + routed exception (the contradiction hunt, class 3). Add the approval route, or scope the entitlement.
`prompt/cap-tension`	warn	A bounded output (replies capped at N sentences) beside an exhaustive mandate (confirm the FULL order) — coherent only as default + exception; scope the cap (the contradiction hunt, class 2).
`prompt/conjunct-cap`	warn	A mandated ask carries more questions than the question cap allows — the count rides the coordination, one per repeated whether/wh-marker (THE CONJUNCT COUNT, THE COUNT SCOPE tier 2). Split the ask into separate turns, or scope the cap.
`prompt/count-alignment`	warn	One counted thing, two count spellings (a unitless bound beside a per-unit one, or a count inside an either/or) — state one bound with one unit (THE COUNT SCOPE, the hunt’s class 1 advisory tier).
`prompt/dangling-name`	warn	A paired %name literal% no declaration binds — declare it, or quote it ("%…%") to keep it literal prose.
`prompt/dangling-reference`	warn	A pro-form (it, this) points at nothing the prompt has introduced - a model will guess the referent.
`prompt/declared-later`	info	An identity is declared AFTER its first use (you on line 3, used on line 1) - the model reads top-down, so declare identities before the rules that use them.
`prompt/determinable-expect`	info	A judge-scored expectation that has an exact deterministic form.
`prompt/duplicated-declaration`	warn	A declaration that renders AND is @{expanded} elsewhere — the model reads the value twice.
`prompt/expletive-frame`	warn	A dummy-it frame (It is important to ...) carries no doer - state the instruction directly.
`prompt/guard-priority`	warn	Two guard-led rules — one condition provably specializes the other, the actions diverge, and no priority is stated (`otherwise`/`instead`): a case serving both guards leaves the model guessing which rule wins (THE PROCESS SCOPE tier 3).
`prompt/hedging`	info	A hedge (try to, if possible) softens an instruction; commit to a modal.
`prompt/implied-doer`	info	A document of imperatives that never establishes its addressee - one declaration (You are the dispatcher.) anchors every instruction. Fires once per document.
`prompt/mixed-timezone`	warn	Two different timezones qualify times in one prompt — unify them, or make the zone a variable.
`prompt/multiword-definite`	warn	A multi-word definite subject the compiler cannot bound — wrap the name in %…% to bind it as one object.
`prompt/naive-time`	info	The prompt states clock times but never fixes a timezone — the model will guess. Declare a timezone variable (default UTC) or qualify the times.
`prompt/nominalized-process`	warn	The action is packed into a noun (a review must take place) and nobody performs it - use the verb with a doer.
`prompt/possessive-fragment`	info	A possessive fragment (The boy's father.) asserts only that the thing exists — add a predicate to bind a value, or spell the copula (The boy is …) to assert a trait.
`prompt/prose-step-ref`	info	A prose step reference that resolves through a Step-titled section — works; the @<section> pointer is the stronger, rename-safe form.
`prompt/scale-gap`	warn	A prose scale is defined with holes (severity one and three defined, two never) — the model must guess the middle (the contradiction hunt, class 5).
`prompt/tier-overlap`	warn	Adjacent authority tiers double-cover a value - a shared boundary point (info) or a nested range (warn) gives one amount two handlers. Make the tiers exclusive ("over $150"), or state which rule wins.
`prompt/undefined-adjective`	error	An adjective claims on an UNNAMED axis — define it (`$CONFIG adjective <word>` with an axis) or relax the dial (`$CONFIG lexicon` → undefined_adjectives). ERROR by default: a claim the checker holds with one hand.
`prompt/unintroduced-definite`	info	A definite retrieves a card the document never introduces (Open the store. - which store?) - introduce the head on another line, or the model guesses.
`prompt/unmeasurable`	warn	A rule with no concrete, checkable action or bound.
`prompt/unowned-attribute`	info	A bare attribute (The tone is …) names a slot but not its owner — own it (Your tone is …) or name the owner (The response’s tone is …). The unowned slot is judged bare-vs-bare but never paired with owned slots.
`prompt/unregistered-doer`	info	A bare generic doer (Users should ...) never enters the world model - the imperative or a definite party registers who acts.
`prompt/untested-rule`	info	No $TEST case exercises this rule, so its behavioral impact cannot be measured.
`prompt/vague`	info	Vague wording the model can read many ways.
`security/injection`	warn	Text resembling a prompt-injection pattern.
`security/leaked-secret`	error	A credential literal in the prompt; secrets never live in the file.
`semantic/covered`	info	Everything a line asserts is already said elsewhere (the semantic tier's entailment read) — near-total coverage escalates to warn.
`spelling/typo`	warn	A likely misspelling, with a suggested correction.
`spelling/unknown-word`	info	A word the dictionary does not recognize.
`structure/alias-collision`	warn	A statement alias (`@@ name:`) already names another annotation, section, tool, or import — one name, one referent.
`structure/ambiguous-section-ref`	error	A reference (or transclusion) to a section name declared in several scopes, with no enclosing scope to pick one.
`structure/ambiguous-step-ref`	error	A step reference that several sections' steps could answer — qualify it (`per <section> step 2`) or use a #anchor.
`structure/bad-case-expr`	error	A chain arm's condition does not parse — the arm would silently never fire.
`structure/bad-define-expr`	error	A $DEFINE whose condition does not parse.
`structure/bad-example`	error	A malformed $EXAMPLE block field — the block cannot compile faithfully.
`structure/bad-guard-expr`	error	A `<tag when=…>` guard that is not a valid condition — the section could not resolve away soundly.
`structure/bad-indent`	warn	Indentation does not mirror the section nesting (2 spaces per level); the nesting read is best-effort.
`structure/bad-input-type`	error	A `$REQUIRE variable` whose name or type is malformed — the name must be one `@{…}` can read back, and chains and guards on a bad type would be unsound.
`structure/bad-pointer-name`	error	A pointer name the grammar cannot lex (`@{2fa}`, `@{_x}`, `@{customer-id}`, `@{}`) — a pointer name begins with a LETTER. Read at the whole bracket, so both failures land here: a pointer-shaped name the emitter expands into a placeholder nothing can fill, and one it cannot read at all, which reaches the model with its compile-time `@` still attached.
`structure/bad-switch`	error	A malformed $SWITCH or $IF chain shape (retired inline form, nested deterministic IF, dangling ELSE).
`structure/bad-test`	error	A malformed $TEST block field (e.g. the retired EXPECT form).
`structure/bare-tool-ref`	error	An exact tool name in bare prose; point it with @[name], or quote it to speak the name as text.
`structure/config-section-content`	error	Content inside a `<$config>` section that is not `$IMPORT`/`$CONFIG` rows.
`structure/curly-quote`	warn	A curly quote or apostrophe; only ASCII quotes bind — the lookalike ships as prose, the fix is mechanical.
`structure/dangling-binding-param`	error	A @{name} in a request or value that is not a declared parameter — declare it under input::, or use @{env.NAME}.
`structure/dangling-section-ref`	error	A cited <tag> that nothing declares — fix the spelling, or declare it with `$REQUIRE section` when a host composes it in.
`structure/dangling-service`	error	A request references a $SERVICE that is not defined — the binding has no base to compile against.
`structure/dangling-step-ref`	error	A pointer to a step ordinal this document never defines.
`structure/define-binder`	error	A $DEFINE using `=` — the binder is AS.
`structure/define-cycle`	error	$DEFINEs that depend on themselves in a cycle — no evaluation order exists.
`structure/define-in-prose`	error	A $DEFINE pointed at from prose; a compile-time condition would leak as a dangling runtime placeholder.
`structure/define-word-class`	error	A $DEFINE word row whose `- class::` is not a word class (noun, verb, adjective) — the row defines nothing.
`structure/define-word-form`	error	A malformed $DEFINE word header — the lemma is missing, or is not a single word.
`structure/define-word-param`	error	A $DEFINE word body param outside the closed schema (class, unique) — read without it, it configured nothing.
`structure/define-word-unique`	error	A $DEFINE word `- unique::` that is not a boolean, or sits on a non-noun — unique referents are a noun feature.
`structure/duplicate-case`	error	An arm matched entirely by an earlier arm — it can never run.
`structure/duplicate-define`	error	One $DEFINE name bound more than once.
`structure/duplicate-define-word`	error	One $DEFINE word lemma defined more than once in a source — the first row wins.
`structure/duplicate-key`	error	A field key repeated within one $TOOL / $SERVICE block — one per block.
`structure/duplicate-param`	error	One tool parameter defined more than once — the schema can carry it once.
`structure/duplicate-section`	error	Two sections share one tag — a reference to it is ambiguous; give each a distinct name.
`structure/duplicate-service`	error	One $SERVICE name defined more than once.
`structure/duplicate-step`	error	Several steps in one scope carry the same number — a reference to it is ambiguous.
`structure/duplicate-term`	warn	A definition term repeats within one list.
`structure/duplicate-tool`	error	One $TOOL name defined more than once.
`structure/em-dash`	warn	An em or en dash splices a line; the checker reads it as one statement — split it or use a comma.
`structure/empty-service`	error	A $SERVICE with no body — its fields (base::, headers::) indent beneath it.
`structure/empty-tool`	error	A $TOOL with no body — its fields (description::, input::, request::) indent beneath it.
`structure/env-shadow`	warn	A declared variable named env beside a $TOOL/$SERVICE binding reading @{env.…} — inside a tool block that spelling is the AMBIENT environment, in prose it is a field of the declared variable: one spelling, two referents. Rename the variable.
`structure/guard-on-heading`	error	A when= guard on a # heading is inert — the content would always ship; guards live on <tag when=...> sections.
`structure/guard-type-mismatch`	error	A guard or $DEFINE reads an input at the wrong type — a bare read wants a bool, a comparison wants an enum member.
`structure/half-quoted-literal`	error	A literal-zone tag missing one of its quotes; the name is quoted whole: <"name">.
`structure/header-without-binding`	warn	Tool headers with no request:: — headers ride an HTTP binding, so these do nothing; add the request or delete them.
`structure/heading-outside-section`	warn	A # heading sits outside the XML sections the prompt uses.
`structure/hoist-arm`	info	Every arm repeats the same statement — shared content is branch-independent; hoist it above the chain.
`structure/impossible-case`	error	A CASE pattern outside the switch domain — the arm can never fire.
`structure/impossible-value`	error	A comparison against a value outside the input's declared domain.
`structure/inline-marker`	warn	A "::" definition marker used inline; read as prose and shipped verbatim — nest it as a "- " sub-definition, or quote it as a sample.
`structure/large-arm`	info	An arm body large enough to extract — move it to a section and point at it.
`structure/loose-content`	warn	Content outside any section once XML tags are used.
`structure/malformed-binding`	error	A binding placeholder written {name} — a pointer is @{name}; the rewrite is attached.
`structure/malformed-header`	error	A line that is not a header — a header is "- Header-Name:: value".
`structure/malformed-param`	error	A line that is not a valid tool parameter — "- name:: type: description." with the type in English; the rewrite is attached.
`structure/malformed-service`	error	A line that is not a field of its $SERVICE — fields are "- key:: value" rows; the rewrite is attached.
`structure/malformed-tool`	error	A line that is not a field of its $TOOL — fields are "- key:: value" rows; the rewrite is attached.
`structure/misplaced-annotation`	warn	A @@ note trailing after content instead of above it.
`structure/misplaced-command`	error	A $-command below content — commands sit at the top of the file, outside any section.
`structure/misplaced-param`	error	A parameter row inside description:: text — it would never reach the schema; move it under "- input::".
`structure/missing-period`	warn	An unterminated statement; the checker assumes the terminator — end with . ! ? or a lead-in colon.
`structure/missing-step`	error	A gap in a step sequence — the numbering jumps over a step that does not exist.
`structure/near-duplicate-section`	warn	Two section names within one edit of each other — read as DISTINCT sections (refs bind by exact tag); a possible typo.
`structure/needs-sigil`	error	A command keyword without its `$` sigil — the line would ship as prose and configure nothing.
`structure/no-default-branch`	error	A decision with no Otherwise — a state matching none of the branches would be unhandled.
`structure/non-exhaustive-branch`	error	A decision over an enum that leaves members unhandled.
`structure/non-exhaustive-switch`	error	A chain over open-ended conditions cannot be proven exhaustive — add an ELSE arm.
`structure/one-of-colon`	error	"one of" took a colon; the quantifier never does.
`structure/opaque-switch`	error	A $SWITCH over an input with no declared domain — coverage cannot be proven; type the input.
`structure/overlapping-guard`	warn	One value handled by more than one branch — in a decision only one runs, and an LLM won't reliably pick the same one.
`structure/phantom-column`	warn	A run of two or more interior spaces doing alignment structure; collapses mechanically.
`structure/retired-brace-ref`	error	Bare {braces} / [squares] are prose now: use @{name} to reference a declared name or import.
`structure/retired-literal-sigil`	error	The old <=name> literal-zone spelling; the sigil is the quote pair now: <"name">.
`structure/secret-literal`	warn	A credential-looking literal in a $SERVICE / $TOOL value — secrets never live in the file; use @{env.NAME}.
`structure/service-no-base`	error	A $SERVICE without a base — every request through it needs a URL to compile against.
`structure/special-character`	warn	A typographic or decorative codepoint outside the ASCII plane; ships as-is, the ASCII fix is attached.
`structure/split-declaration`	warn	One subject declared with separate single values across statements — multiplicity must be spelled in one statement (THE ONE-STATEMENT LAW).
`structure/stacked-annotation`	error	A @@ note directly above another @@ note.
`structure/stray-close-tag`	error	A closing tag with no matching open — the section extent is undefined.
`structure/switch-arm`	error	A malformed `- member:: …` arm row in a $SWITCH block.
`structure/switch-shaped-chain`	info	Every arm tests one input for one member — this chain is a $SWITCH in disguise; the block form proves coverage.
`structure/tab`	warn	A tab; the indent unit is 2 spaces — the fix is mechanical.
`structure/tool-defined-and-imported`	warn	A tool both defined ($TOOL) and imported ($IMPORT tool) — pick one; the definition wins.
`structure/tool-no-description`	warn	A $TOOL without a description — the model has nothing to decide WHEN to call it.
`structure/trailing-space`	warn	Trailing whitespace at the end of a line; strips mechanically.
`structure/unattached-annotation`	error	A @@ note whose next line is not a statement.
`structure/unclosed-tag`	error	A section tag opened but never closed — the section extent is undefined.
`structure/undeclared-input`	error	A guard, chain, or $DEFINE reads a variable that is not a declared input or $DEFINE.
`structure/undeclared-tool`	error	A tool the prose uses that no $TOOL defines and no $IMPORT tool declares.
`structure/undefined-ref`	error	An @{name} pointer resolving to nothing declared.
`structure/undefined-tool-inline`	error	A tool used inline but never imported or defined.
`structure/unknown-service-key`	warn	A $SERVICE field key outside the schema (base, headers).
`structure/unknown-tool-key`	warn	A $TOOL field key outside the schema (description, input, request, headers).
`structure/unordered-step`	warn	Steps out of numeric order within their scope.
`structure/unreachable-branch`	error	A branch after Otherwise — it can never run.
`structure/unreachable-case`	error	An arm after the fallback — it can never run.
`structure/unreachable-otherwise`	error	Every member already has an arm, so Otherwise can never run.
`structure/unused-define`	warn	A $DEFINE nothing reads.
`structure/unused-import`	warn	An $IMPORT nothing references — the manifest over-declares.
`structure/unused-service`	warn	A $SERVICE no tool's request or via:: transport uses.
`structure/unused-tool`	warn	A defined tool the prompt never mentions — the model cannot discover it.
`structure/vacuous-line`	warn	A line that interrupts a numbered step run and says nothing the checker can read — attach it, promote it to a heading, or delete it.
`structure/vague-section-name`	warn	A section name too short or generic to be meaningful — name it for what it contains.
`structure/wrapped-definition`	error	A hard-wrapped definition continuation; one statement per line.
`structure/wrapped-fragment`	warn	A line that reads as a hard-wrapped continuation of the one above.
`style/quoted-prose`	warn	A whole-line quote hides a statement from the checker.
`style/wordy`	info	Wordy phrasing a tighter form would carry.
`testfile/duplicate-case`	error	A case id is defined both inline and in the sibling .test.tg.
`testfile/empty`	warn	A discovered .test.tg declares no $TEST or $EXAMPLE blocks.
`testfile/missing-prompt`	error	A .test.tg has no sibling .tg prompt to test.
`typeglish/if-then`	info	A conditional (IF / WHEN / UNLESS / WHILE / …) opened without its THEN — an ADVISORY by the owner’s ruling (2026-08, two hunt rounds measured it at ~79% of all warns on plain-prose imports, drowning the signal; the canonical-form nudge stays, at info).