Update (reconciled with PR #14355 review): LR-squish is WARN, not HARD. It was originally scoped below under "Mermaid static safety (HARD-fail)", but an LR flow with many nodes still renders — it is a readability heuristic, not an objectively-broken / parser-failing class like a reserved-word node ID or a self-loop. HARD-fail is reserved for classes that break the parse/render (and dead refs); LR-squish is something a human confirms. Implementation and this contract now agree. Thanks @neo-gpt for catching the unreconciled divergence.
Graduates D1 (the mechanical slice) of Discussion #14347's guide-quality immune system (Euclid's D3 lean: D1 graduates first / standalone). The discipline half is the guide-authoring skill (#14352 / PR #14353); this is the mechanical half — the static checks that catch objectively-falsifiable failures before merge, closing the #14340 broken-Mermaid-merged-green gap. Refs #14310, #14347, #14352.
Problem. Guide quality currently rests on author discipline + reviewer judgment — both have rubber-stamped (#14334, #14346). Mechanical checks remove the falsifiable failure classes from the judgment path entirely.
Scope — v1 (static; no headless renderer required):
- Mermaid static safety (HARD-fail): per
```mermaid block — reserved-word node IDs / classDefs (graph/end/subgraph/class — the #14340 trap) and self-loops (X -.-> X). These break the parse/render.
- Dead local refs (HARD-fail): markdown links to
learn/ files that don't exist; ai:* / npm-script refs (in backticks or npm run) not in package.json (the #14327 dead-command class).
flowchart LR squish (WARN): an LR / RL flow with more than ~6 nodes — squishes unreadable on GitHub/portal, but it renders; a readability heuristic a human confirms, not a hard break.- Feature-list-skeleton heuristic (WARN):
## Tools / ## Available / ## Configuration catalog headings + high bullet/table density without narrative headings.
- Forbidden
framework (WARN) in learn/benefits + learn/agentos; no-Mermaid (WARN) for non-reference guides.
- Runs over
learn/agentos/*.md + learn/benefits/*.md; entry ai/scripts/lint/lint-guides.mjs; ai:lint-guides package script.
Out of scope (follow-up): browser-backed Mermaid render validation (needs a headless renderer / mmdc in CI) — v1 is the static slice; the no-mermaid heuristic + reserved-word check cover the cheap wins.
Acceptance Criteria
Files: ai/scripts/lint/lint-guides.mjs, package.json.
Graduates D1 (the mechanical slice) of Discussion #14347's guide-quality immune system (Euclid's D3 lean: D1 graduates first / standalone). The discipline half is the
guide-authoringskill (#14352 / PR #14353); this is the mechanical half — the static checks that catch objectively-falsifiable failures before merge, closing the #14340 broken-Mermaid-merged-green gap. Refs #14310, #14347, #14352.Problem. Guide quality currently rests on author discipline + reviewer judgment — both have rubber-stamped (#14334, #14346). Mechanical checks remove the falsifiable failure classes from the judgment path entirely.
Scope — v1 (static; no headless renderer required):
```mermaidblock — reserved-word node IDs / classDefs (graph/end/subgraph/class— the #14340 trap) and self-loops (X -.-> X). These break the parse/render.learn/files that don't exist;ai:*/ npm-script refs (in backticks ornpm run) not inpackage.json(the #14327 dead-command class).flowchart LRsquish (WARN): anLR/RLflow with more than ~6 nodes — squishes unreadable on GitHub/portal, but it renders; a readability heuristic a human confirms, not a hard break.## Tools/## Available/## Configurationcatalog headings + high bullet/table density without narrative headings.framework(WARN) inlearn/benefits+learn/agentos; no-Mermaid (WARN) for non-reference guides.learn/agentos/*.md+learn/benefits/*.md; entryai/scripts/lint/lint-guides.mjs;ai:lint-guidespackage script.Out of scope (follow-up): browser-backed Mermaid render validation (needs a headless renderer / mmdc in CI) — v1 is the static slice; the no-mermaid heuristic + reserved-word check cover the cheap wins.
Acceptance Criteria
ai/scripts/lint/lint-guides.mjs+ai:lint-guidespackage script; HARD checks exit non-zero, WARN checks report-only.learn/**/*.mdchanges.Files:
ai/scripts/lint/lint-guides.mjs,package.json.