Doctor · Rules
Rule catalog
Every check doctor can emit, from a single registry that the engine and
specline rules share — so a finding can never carry a rule_id
the catalog lacks, and the catalog can never drift from what fires.
Scope — repo findings fail everywhere; spec
findings fail only when that spec is in --changed (quarantine), else warn.
Downgradable — in author mode a downgradable rule that
fires for a missing element becomes distance_to_ratifiable (info), not an error.
| rule_id | severity | scope | tier | downgradable | fires when |
|---|---|---|---|---|---|
STRUCT-MISSING-SPEC | error | spec | 1 | true | A specs/ folder has no spec.md. |
STRUCT-MISSING-RELATIONS | error | spec | 1 | true | A specs/ folder has no relations.md. |
FRONTMATTER-UNPARSEABLE | error | spec | 1 | false | spec.md frontmatter is missing or doesn't parse. |
FRONTMATTER-ID-MISMATCH | error | spec | 1 | false | frontmatter id or slug doesn't match the directory. |
FRONTMATTER-MISSING-RATIFIED | error | spec | 1 | false | ratified/building spec lacks ratified_by or ratified_at (B3). |
STATUS-SCHEMA | error | spec | 1 | false | status.md is missing or duplicates a required section. |
ENUM-INVALID | error | spec | 1 | false | blast_radius / target_model holds a value outside the allowed set. |
UNKNOWN-FRONTMATTER-KEY | warning | spec | 1 | false | an unrecognized frontmatter key — preserved, not failed (newer canon). |
UNKNOWN-SECTION | warning | spec | 1 | false | an unrecognized body section — preserved, not failed. |
RELATION-DANGLING | error | repo | 1 | false | a relations.md edge points to an id that exists nowhere. |
RELATION-CROSS-REPO | warning | repo | 1 | false | a repo:NNNN-slug edge — validated weakly, warn only. |
RELATION-KILLED | warning | repo | 1 | false | an edge points to a killed id — warn only. |
LINK-DANGLING | error | repo | 1 | false | a relative link under docs/ doesn't resolve. |
KNOWLEDGE-HAS-STATUS | error | repo | 1 | false | knowledge/ contains a lifecycle artifact (status.md, open-questions.md). |
ARCHIVE-EDITED | error | repo | 1 | false | an archived spec is modified (adding one is graduation, allowed) — the audit trail is immutable. |
ID-DUPLICATE | error | repo | 1 | false | an id appears in more than one spec-bearing location. |
ID-COUNTER-GAP | error | repo | 1 | false | an id ≤ .id-counter is accounted for nowhere. |
GOAL-MISSING | warning | spec | 1 | false | a spec has no `## Goal` — the build loop has no single falsifiable target. |
ACCEPTANCE-NOT-RUNNABLE | warning | spec | 1 | false | agent-loopable acceptance checks carry no runnable command — the loop must interpret prose. |
LOOP-BUDGET-INVALID | warning | spec | 1 | false | loop_budget is present but not a positive integer (the autonomy grant). |
This mirrors specline rules --format json, which is the authoritative, machine-readable catalog. Currently 20 rules at tier 1 (the canon 2.3 structural subset, plus loop-orientation nudges). Lifecycle/state rules are deferred to a later spec.