Diagnostics

Diagnostics are how ThoughtML tells you something’s wrong with a document’s form. They come in two severities:

• Error — the document is malformed. The CLI exits non-zero.
• Warning — suspicious but parseable. The CLI still exits zero, unless you pass --strict (which makes warnings fail too).

Diagnostics go to stderr; the JSON model goes to stdout. They are distinct from the mirror’s conflict report, which judges a document’s coherence, not its form, and never fails parsing.

The strict-clean invariant. Every bundled example parses with zero errors and zero warnings under default options. A test (bundled_examples_are_strict _clean) enforces it, so the corpus can’t silently rot.

Codes and machine-readable output

thoughtml check --json emits each diagnostic with a stable code, its severity, line, message, and — where one can be computed — a suggested help fix:

{ "code": "TML102", "severity": "warning", "line": 5,
  "message": "unknown relation `supprts`",
  "help": "did you mean `supports`? (relations are a closed set)" }

Codes are grouped so an agent or editor can route on the family:

For the “unknown <thing>” family the help is a nearest-spelling suggestion from the relevant closed vocabulary — it catches typos like supprts → supports. Codes are part of the tool’s contract and are not renumbered once assigned.

Errors

Warnings

Indentation & structure

• block lines should be indented by two or more spaces
• only a scope may contain nested objects; desugaring them at the top level

Ids & kinds

• duplicate id / id is reused across records
• focus … was declared as kind X but redeclared as Y; keeping X
• duplicate <field> field; using the last (kind, confidence, weight, probability, expects, status, formula)
• unknown focus kind / unknown posture / unknown relation / unknown field (unless a profile declares it)

Values

• quantity should be <number> <unit>
• weight/probability should be in 0..1; clamping
• probability on a <rel> link is ignored / a weight on a leads-to link is ignored
• kind requires a value / until requires a reference
• question should include body text or an expects field / about expects one or more ids

Reference resolution

• … is an unresolved reference (link endpoints, stance targets, about, because/answers/blocked-by/undercut-by, formula refs)

Semantic lints (need the whole graph)

• agent … takes contradictory stances on … — incompatible posture pairs: accepts/rejects, accepts/doubts, chooses/rejects, holds/rejects.
• cyclic dependency: a → b → a — a cycle among causes / depends-on edges.
• focus … is not connected to anything — an orphan: nothing links it, no stance targets it, no field references it.

Opinionated lints (only with thoughtml check --lint)

• focus … gathers N supports links and no counter-evidence (TML501) — a claim used as an enumeration. Evidence relations inflate derived_confidence; if these are list items, use part-of instead. Off by default so strict-clean documents are unaffected.
• circular justification: a → b → a (TML502) — a supports loop. The language refuses circular causation by default (TML303); this is circular justification, and it matters for the same reason plus one more: claims inside the loop derive confidence above 0.5 from no evidence outside it. Advisory rather than an error, because mutual support is not always a mistake — two readings of one body of evidence can genuinely reinforce each other. Either give one of them outside evidence, or merge them if they are one belief said twice.

Decision graph

• leads-to edge … points outcome … at itself
• option … has no leads-to outcomes, but its sibling options do — it’d be silently missing from the EV ranking.

Temporal

• … revises … but is asserted earlier
• valid-during … ends before it starts

Compute (only with the relevant opt-in flags)

• formula: parse error, unresolved/quantity-less reference, dimension mismatch, dependency cycle.
• decision EV: missing probability/payoff, mixed dimensions, probability mass > 1.

Provenance (only with --strict-provenance)

• … declares no basis (add measured/estimated/assumed)

Imports

• unknown import … / import cycle through …; skipped