@erclx/canon 4.16.0 → 4.18.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.16.0",
+  "version": "4.18.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-diagram/SKILL.md

@@ -24,7 +24,7 @@ Read these from the project root in parallel, skipping any that do not exist:
 
 Do not recurse speculatively.
 
-Follow `${CLAUDE_SKILL_DIR}/../../standards/diagrams.md` for frontmatter, entry kinds, layout, budgets, accessibility, verification, and explanation rules.
+Follow `${CLAUDE_SKILL_DIR}/../../standards/diagrams.md` for frontmatter, entry kinds, and explanation rules. Follow `${CLAUDE_SKILL_DIR}/../../standards/mermaid.md` for what goes inside the fence: layout, budgets, accessibility, labels, and verification.
 
 ### Migrating a pre-split flat file
 
@@ -124,7 +124,7 @@ When the render fails for any reason (no browser engine, no network, no package
 
 ## Step 6: read the renders back
 
-Read each PNG and judge the picture against what the entry means to say. Apply the verification properties in the standard.
+Read each PNG and judge the picture against what the entry means to say. Apply the verification properties in `${CLAUDE_SKILL_DIR}/../../standards/mermaid.md`.
 
 Fix the source and re-render. Stop after two correction passes on an entry.
 

package/docs/agents/index.md

@@ -38,7 +38,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, and what each session surface can see
 - [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [Citation reach](skills-reach.md): Reporting the skill bodies that cite a path no target project receives, which corpus the verb reads, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
-- [Standard success criteria](standards-audit.md): Reading the corpus against the Success criterion gate, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
+- [Standard success criteria](standards-audit.md): Reading the corpus against the success-criterion gate, the two headings it accepts, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
 - [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
 - [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the family stem behind a templated citation, the exemption marker, the blind spots it cannot reach, and why it reports rather than gates
 - [Targets](targets.md): The projects this toolkit installed into, the record the install writes against the sweep that backs it, what bounds each answer, and the cross-target pull request read

package/docs/agents/standards-audit.md

@@ -1,11 +1,13 @@
 ---
 title: Standard success criteria
-description: Reading the corpus against the Success criterion gate, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
+description: Reading the corpus against the success-criterion gate, the two headings it accepts, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
 ---
 
 # Standard success criteria
 
-`canon standards audit` reads the corpus at `standards/` and reports which files carry a `## Success criterion` section against which do not, per `standards/standard.md`. It fails only on a standard new to the current branch, never on one already short the section.
+`canon standards audit` reads the corpus at `standards/` and reports which files state a success criterion against which do not, per `standards/standard.md`. It fails only on a standard new to the current branch, never on one already short the section.
+
+Two headings count, at any casing. `## Success criterion` is the wording that standard states the rule under, and `## What a working <document type> looks like` is the wording its template prescribes for the section itself. Most of the corpus writes the templated form, so accepting the rule's wording alone would refuse a conforming standard.
 
 ```bash
 canon standards audit
@@ -25,11 +27,11 @@ canon standards audit --arrivals-only
 
 ## Exit codes and refusals
 
-| Code | Meaning                                                         |
-| ---- | --------------------------------------------------------------- |
-| `0`  | every arriving standard carries the section                     |
-| `1`  | refused, with `reason` naming the cause                         |
-| `2`  | a standard new to this branch carries no `## Success criterion` |
+| Code | Meaning                                                                |
+| ---- | ---------------------------------------------------------------------- |
+| `0`  | every arriving standard carries the section                            |
+| `1`  | refused, with `reason` naming the cause                                |
+| `2`  | a standard new to this branch states no criterion under either heading |
 
 A project authoring no standards refuses with `no-corpus`, the ordinary state of most targets, the same absence `canon claude skills audit` reads as its own `no-corpus`.
 

package/governance/rules/claude/502-mermaid.md

@@ -0,0 +1,14 @@
+---
+description: Route a drafted Mermaid fence to the mermaid standard for layout, budgets, accessibility, labels, and render verification
+paths:
+  - '**/*.md'
+---
+
+# Mermaid diagram standards
+
+## Authority
+
+- Apply this rule only when the edit drafts or revises a Mermaid fence. Skip it on a markdown edit carrying no diagram.
+- Follow the mermaid standard for direction and layout, node and edge budgets, the accessibility fields, punctuation inside labels, and how a render is verified. It is the single source. Read it with `canon standards mermaid`.
+- Read it before drafting the fence. Do not work the layout or the budgets from memory.
+- Which diagram a document carries and what question it answers is a separate topic. `560-diagrams` routes it.

package/governance/rules/claude/560-diagrams.md

@@ -1,5 +1,5 @@
 ---
-description: Route .canon/diagrams edits to the diagrams standard for Mermaid conventions
+description: Route .canon/diagrams edits to the diagrams standard for entry kinds, frontmatter, and explanation prose
 paths:
   - '.canon/diagrams/**'
   - '.claude/DIAGRAMS.md'
@@ -9,7 +9,8 @@ paths:
 
 ## Authority
 
-- Follow the diagrams standard for Mermaid diagram layout, budgets, accessibility, verification, and explanation prose. It is the single source. Read it with `canon standards diagrams`.
+- Follow the diagrams standard for which question an entry answers, the entry kinds and their source signals, the frontmatter, and the explanation prose beneath the fence. It is the single source. Read it with `canon standards diagrams`.
+- Layout, budgets, accessibility, labels, and render verification inside the fence are a separate topic. `502-mermaid` routes them to `mermaid.md`.
 - A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.
 
 ## Scope

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.16.0",
+  "version": "4.18.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/gate/measures.ts

@@ -164,6 +164,94 @@ export const unreferencedRules: Measure = async (ctx) => {
   }
 }
 
+/**
+ * The files the sweep would rewrite, each with its own count, taken from the
+ * `paths` array the record carries beside the total.
+ *
+ * Every field is tested rather than trusted. The record reaches here as parsed
+ * JSON rather than as a type the compiler checked, so a shape that moved
+ * upstream drops the entries it can no longer read and leaves the count that
+ * was read from a field of its own standing.
+ */
+function citedPaths(record: { paths?: unknown } | undefined): string[] {
+  if (!Array.isArray(record?.paths)) return []
+
+  return record.paths.flatMap((entry) => {
+    const cited = entry as { path?: unknown; rewritten?: unknown }
+    if (typeof cited.path !== 'string') return []
+    return typeof cited.rewritten === 'number'
+      ? [`${cited.path} (${cited.rewritten})`]
+      : [cited.path]
+  })
+}
+
+/**
+ * A second run of the records move should rewrite nothing, and the count is
+ * only knowable once the folders themselves have landed.
+ *
+ * `moves` empty means every record folder already sits at `.canon/`, so any
+ * citation the sweep would still rewrite is one the move left stale, which is
+ * the defect this stage exists to catch. Where `moves` is nonempty the tree has
+ * not migrated at all and a nonzero rewrite count is the verb describing its
+ * own first pass, so the reading is reported and never failed on.
+ *
+ * Exit `0` is a tree with nothing to do and exit `2` is a plan drawn without
+ * `--write`, so both read a tree and both carry a record. Every other exit is a
+ * refusal that planned nothing, which is unmeasured for the reason the markdown
+ * stage treats its own refusal exit so.
+ */
+export const recordIdempotence: Measure = async (ctx) => {
+  const run = await ctx.cli(['migrate', 'records', '--json'])
+
+  if (run.exitCode !== 0 && run.exitCode !== 2) {
+    return {
+      emissions: [],
+      unmeasured: `The records sweep refused (exit ${run.exitCode}) and planned nothing.`,
+    }
+  }
+
+  const record = parseJson(run.stdout) as
+    | { moves?: unknown; rewritten?: unknown; paths?: unknown }
+    | undefined
+  const moves = record?.moves
+  const rewritten = record?.rewritten
+
+  if (!Array.isArray(moves) || typeof rewritten !== 'number') {
+    return {
+      emissions: [],
+      unmeasured:
+        'The records sweep carried no plan, so the stage read no count. Run bun src/cli.ts migrate records --json.',
+    }
+  }
+
+  if (moves.length > 0) {
+    return {
+      emissions: [
+        info(
+          `${moves.length} record folder(s) still at the old root, with ${rewritten} citation(s) that move with them`,
+        ),
+      ],
+    }
+  }
+
+  if (rewritten > 0) {
+    return {
+      // The payload already names every file, so listing them here is what
+      // separates a count a reader has to go and reproduce from a remedy they
+      // can act on. A malformed `paths` costs the list and not the finding,
+      // since the count above it was read from a field of its own.
+      emissions: citedPaths(record).map((path) => warn(path)),
+      failure: `The records are at .canon/ and ${rewritten} citation(s) still name the old root, so a second run of canon migrate records would rewrite them. Repoint each one, or mark it canon-keep-record-root where the sentence has to keep the old spelling.`,
+    }
+  }
+
+  return {
+    emissions: [
+      info('Records at .canon/, and a re-run of the move rewrites nothing'),
+    ],
+  }
+}
+
 /**
  * A banned character, word, or spelling is a fact rather than a threshold, so
  * it fails the push while bullet, paragraph, and depth weight stay advisory.

package/src/gate/stages.ts

@@ -4,6 +4,7 @@ import {
   markdownBans,
   type Measure,
   pluginManifests,
+  recordIdempotence,
   sandboxCoverage,
   seedStandards,
   standardCriteria,
@@ -337,6 +338,17 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Rule citations resolve',
   },
+  {
+    // A citation naming the old record root resolves to nothing once the
+    // folders have moved, and the sweep that would repoint it only runs when a
+    // person calls it. Reading its plan back is what turns a silent stale
+    // citation into a stopped push, and it sits with the two citation stages
+    // above rather than at the end of the file because it answers their
+    // question about a root rather than a path.
+    id: 'record-idempotence',
+    label: 'Record idempotence',
+    checks: [{ kind: 'measure', measure: recordIdempotence }],
+  },
   {
     id: 'markdown-bans',
     label: 'Markdown bans',

package/src/standards/audit.ts

@@ -5,11 +5,25 @@ import { gitEnv } from '@/git-env'
 import { resolveBaseRef } from '@/git-files'
 import { INDEX_FILE, standardsSourceDir } from '@/standards/read'
 
-/** Returned when a standard new to this branch carries no `## Success criterion` section, the gating check. */
+/** Returned when a standard new to this branch states no success criterion under either heading `CRITERION_HEADING` accepts, the gating check. */
 export const EXIT_MISSING_CRITERION = 2
 
-/** Matched at any casing, level-2 only, per the heading `standards/standard.md` itself uses. */
-const CRITERION_HEADING = /^##\s+success criterion\s*$/im
+/**
+ * Matched at any casing, level-2 only, in either heading the corpus writes a
+ * criterion under.
+ *
+ * `standards/standard.md` states the rule under `## Success criterion` and
+ * templates the section itself as `## What a working <document type> looks
+ * like`, and the template wins where the two disagree, which that file says in
+ * as many words. Reading the rule group's own heading as the one to match is
+ * what the first spelling here did, and no standard in the corpus carries a
+ * criterion under it: 12 of 28 use the templated form and `standard.md` alone
+ * carries the literal words, over its rules about criteria rather than over its
+ * own. Nothing caught that, because the gate reads a standard new since the
+ * merge base and none had arrived since it shipped.
+ */
+const CRITERION_HEADING =
+  /^##\s+(?:success criterion|what a working .+ looks like)\s*$/im
 
 /**
  * The reasons an audit produces no reading. `no-corpus` is the ordinary state

package/standards/diagrams.md

@@ -11,10 +11,11 @@ A diagram entry answers one question about the system with one or more Mermaid d
 
 ## Scope
 
-Governs per-kind diagram entries under `.canon/diagrams/`: which question each answers, the Mermaid source, the accessibility fields, and the explanation prose beneath. It states the voice for that prose, which is the yield the `write-human` skill grants a surface whose own standard sets one.
+Governs per-kind diagram entries under `.canon/diagrams/`: which question each answers, which kinds exist and what each is drawn from, the frontmatter, and the explanation prose beneath the fence. It states the voice for that prose, which is the yield the `write-human` skill grants a surface whose own standard sets one.
 
 Does not govern:
 
+- How the drawing inside the fence is laid out, budgeted, made accessible, and verified against its render: `mermaid.md`
 - Rhythm and sentence construction in explanation prose: the `write-human` skill, whose rules the yield does not lift beyond voice
 - Language, word choice, punctuation, and formatting in explanation prose and node labels: `markdown.md`, which the yield does not reach
 - The mechanism behind any component a diagram draws: `context.md`
@@ -63,28 +64,9 @@ The kinds drift at rates spanning roughly an order of magnitude, which is why th
 
 A second entry for one kind takes a suffixed name (`request-flow-admin.md`) and repeats the kind's `category` verbatim, which is what the grouping field is for. One entry per kind is the ordinary case, so most catalogs show one entry under each heading.
 
-## Layout
-
-- Declare `flowchart TB` by default. Mermaid ignores a subgraph's direction whenever that subgraph links outward, and an architecture diagram links across its subgraphs as the normal case, so top-bottom is a declaration rather than a guarantee.
-- Restructure a diagram that renders diagonal or left-to-right. Repeating the direction keyword does not fix it.
-- Render a context, component, or pipeline diagram taller than wide. A `sequenceDiagram` is wide by construction and is exempt.
-- Do not let independent nodes render in a row. A row of siblings reads as a sequential chain and asserts a pipeline the system does not have.
-- Do not converge many edges on one node from one side. A crossing bundle is unreadable whatever it encodes.
-- Keep node labels short. Three or four words max. Detail goes in the paragraph below the diagram.
-- Use `<br/>` for a second short line on a node when the label is two ideas, never for a sentence.
-- Subgraphs are for grouping unrelated lanes such as offline versus online or browser versus server. Do not subgraph a single linear flow.
-
 ## Budgets
 
-- Hold a diagram to roughly 5 to 10 nodes. Split it past 15.
-- Watch edge count harder than node count. It binds first, and a diagram whose edges outnumber its nodes is already too dense to read.
-- Treat a diagram that cannot be described in one sentence as two diagrams.
 - Keep an entry to one diagram by default. A second fence in the same file needs its own H2 naming what it adds, and a third is a sign the entry covers two kinds.
-- Warn rather than refuse on a budget, and name the split that would fix it. These numbers come from published Mermaid practice rather than from a measurement in this repository, so a hard refusal on them will be wrong sometimes and unarguable when it is.
-
-## Accessibility
-
-- Give every diagram `accTitle` and `accDescr`. `accTitle` names what the diagram answers. `accDescr` states the structure in one sentence for a reader who cannot see the render.
 
 ## Explanation
 
@@ -96,13 +78,6 @@ A second entry for one kind takes a suffixed name (`request-flow-admin.md`) and
 
 This section states the voice for the surface, which is what claims the yield the `write-human` skill grants to a surface whose own standard sets it. Explanation prose is pedagogical here and the default developer-facing voice does not apply. The yield covers voice alone. The rhythm and density rules that skill carries stay in force, as do the language bans, punctuation, and formatting in `markdown.md`, which grants no yield at all.
 
-## Verification
-
-- Judge a diagram from its rendered image, not from its source. Direction, sibling rows, and edge bundles are visible only in the output.
-- Render to PNG. An SVG export reads back as markup with no recoverable spatial meaning.
-- Apply four tests as a reviewer, the same ones the author applied: direction held, no sibling row reading as a chain, no crossing edge bundle, taller than wide outside a sequence diagram.
-- State which verification was skipped when no renderer is available. A diagram written without a render is still shippable, and one reported as verified without a render is not.
-
 ## What moves to .claude/context/
 
 Implementation detail that answers how a component is built belongs in a `.claude/context/` entry, not a diagram:
@@ -120,13 +95,13 @@ Reference the context entry by path when a reader needs the mechanism. The diagr
 - A diagram showing a defunct host or library is worse than no diagram. Audit the affected entry in the same PR.
 - `System context` has no named source signal beyond `.claude/REQUIREMENTS.md`, so nothing tells a session it went stale. Re-read it when the boundary or the set of external dependencies moves.
 - Nothing watches the folder for you. The entries are redrawn on demand rather than swept on every ship, so `verified` carries the whole signal: an entry whose date sits far behind the branch is due a read, and no pass is going to name which one.
-- The explanation paragraphs around a Mermaid block are prose and follow `markdown.md` and the `write-human` skill. The fenced block itself is not, which is why a check scoped to prose is the wrong thing to rely on for what sits inside it.
-- The punctuation bans still apply to node and subgraph labels, and nothing checks them there. An em dash in a label passes every gate the repository has, so read the labels before shipping the entry.
 
 ## Template
 
 The filename and the `category` value both come from Entry kinds and are fixed per kind. A stub nobody has drawn yet carries `TODO: never verified` in place of the SHA and date. The node names and labels inside the fence are placeholders, written bare because Mermaid reads an angle bracket as markup.
 
+What goes inside the fence, and how the render is checked once it is drawn, is `mermaid.md`. This template fixes the frame around it.
+
 ````markdown
 ---
 title: <what the entry answers>

package/standards/index.md

@@ -19,6 +19,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Issue reference](issue.md): GitHub issue title, labels, and body conventions
 - [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, banned words, and frontmatter wording
 - [Memory reference](memory.md): Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
+- [Mermaid reference](mermaid.md): Direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram
 - [Plan reference](plan.md): Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
 - [Pull request reference](pr.md): Pull request title and body conventions
 - [Publish reference](publish.md): Scan an author runs against finished text, the cross-reference form each destination takes, and the response to an unreadable source

package/standards/issue.md

@@ -19,13 +19,14 @@ Does not govern:
 ## Title
 
 - Format: `<type>: <subject>`
-- Type is `bug` or `task`. Lowercase the type and the first word of the subject.
+- Type is `bug`, `task`, or `feedback`. Lowercase the type and the first word of the subject for `bug` and `task`, both hand-composed. `feedback` is always lowercase. Its subject is derived by the CLI from the report's `### Surface` field verbatim, so the subject alone carries no casing rule.
 - Length: 72 characters maximum, no trailing period.
 
 ## Labels
 
-- Apply `bug` for a defect and `enhancement` for a task or improvement.
-- Both are GitHub default labels. A label that does not exist makes `gh` reject the issue. Create it once with `gh label create`.
+- Apply `bug` for a defect and `enhancement` for a task or improvement. Both are GitHub default labels.
+- Apply `feedback` to a report filed through `canon feedback --github`, which sets the label unconditionally rather than a session choosing it. It is not a GitHub default. Create it once per project with `gh label create feedback`.
+- A label that does not exist makes `gh` reject the issue. Create each one once with `gh label create`.
 - One label per issue unless a second genuinely applies.
 
 ## Content
@@ -37,16 +38,35 @@ Does not govern:
 
 ## Sections
 
+### Bug and task
+
 - `## Summary`: one line naming what and why.
 - `## Details`: for a bug, what happens versus what is expected. For a task, what to build.
 - `## Context`: for a bug, repro steps or commands. For a task, the driving reason, or `none`.
 - `## Proposed` (optional): one line naming a fix or approach. Omit when open.
 
+### Feedback
+
+- One `## Toolkit feedback` wrapper holds every field as a nested `###` heading. A flat `##` field is not recognized.
+- `### From project` (optional): the reporting project's name or kind.
+- `### Surface` (required): the toolkit surface and its type, and the specific file or name when known.
+- `### Observed` (required): the observed behavior.
+- `### Expected` (optional): the expected behavior, or `unclear`.
+- `### Repro` (optional): repro details, or `none`.
+- `### Proposed fix` (required): a proposed fix, or `open` when the session settled on no direction.
+- A required field is refused when present but empty. Write the fallback literal for an optional field rather than leaving it blank.
+
 ## Formatting
 
+### Bug and task
+
 - End every bullet with a period.
 - Keep each section to one or two lines.
 
+### Feedback
+
+- A field may run to multiple paragraphs and may hold a fenced code block. The one-or-two-line rule and the trailing-period rule do not apply.
+
 ## Examples
 
 ### Correct (bug)

package/standards/mermaid.md

@@ -0,0 +1,64 @@
+---
+title: Mermaid reference
+description: Direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram
+---
+
+# Mermaid reference
+
+Applies to every Mermaid fence, wherever it is written. A fence sits inside a document some other standard shapes, so this file reaches the drawing and stops at the fence markers.
+
+## Scope
+
+Governs the Mermaid attribute wherever a fence is written, naming no path because an attribute standard governs a drawing rather than a document type: direction and layout, node and edge budgets, the accessibility fields, how punctuation reaches a label, and how a rendered diagram is verified. It carries no template, since a fence has no document shape of its own and sits inside one another standard sets.
+
+Does not govern:
+
+- Which diagram a document carries, what question it answers, its frontmatter, and the explanation prose beneath it: `diagrams.md`
+- Language, word choice, punctuation, and formatting in the prose around a fence: `markdown.md`
+- Voice, rhythm, and sentence construction in that prose: the `write-human` skill
+- The mechanism behind any component a diagram draws: `context.md`
+
+## What a working diagram looks like
+
+A diagram works when a reviewer holding the rendered image, and nothing else, answers yes four times:
+
+- Did the declared direction hold?
+- Is every row of siblings free of a sequential reading the system does not have?
+- Is every convergence free of a crossing edge bundle?
+- Is it taller than wide, outside a sequence diagram?
+
+A diagram failing these is non-conforming even when it satisfies every shape rule below. The rules are the means. These four questions are the test.
+
+## Layout
+
+- Declare `flowchart TB` by default. Mermaid ignores a subgraph's direction whenever that subgraph links outward, and an architecture diagram links across its subgraphs as the normal case, so top-bottom is a declaration rather than a guarantee.
+- Restructure a diagram that renders diagonal or left-to-right. Repeating the direction keyword does not fix it.
+- Render a context, component, or pipeline diagram taller than wide. A `sequenceDiagram` is wide by construction and is exempt.
+- Do not let independent nodes render in a row. A row of siblings reads as a sequential chain and asserts a pipeline the system does not have.
+- Do not converge many edges on one node from one side. A crossing bundle is unreadable whatever it encodes.
+- Keep node labels short. Three or four words max. Detail goes in the paragraph below the diagram.
+- Use `<br/>` for a second short line on a node when the label is two ideas, never for a sentence.
+- Subgraphs are for grouping unrelated lanes such as offline versus online or browser versus server. Do not subgraph a single linear flow.
+
+## Budgets
+
+- Hold a diagram to roughly 5 to 10 nodes. Split it past 15.
+- Watch edge count harder than node count. It binds first, and a diagram whose edges outnumber its nodes is already too dense to read.
+- Treat a diagram that cannot be described in one sentence as two diagrams.
+- Warn rather than refuse on a budget, and name the split that would fix it. These numbers come from published Mermaid practice rather than from a measurement against a corpus, so a hard refusal on them will be wrong sometimes and unarguable when it is.
+
+## Labels
+
+- Apply the punctuation bans in `markdown.md` to node and subgraph labels. A label is not prose, so a check scoped to prose does not reach it, and reading the labels before shipping is the only gate they have.
+- Treat the prose around a fence and the text inside it as two surfaces. The paragraphs are prose and follow `markdown.md` and the `write-human` skill. The fenced block is not, which is why a check scoped to prose is the wrong thing to rely on for what sits inside it.
+
+## Accessibility
+
+- Give every diagram `accTitle` and `accDescr`. `accTitle` names what the diagram answers. `accDescr` states the structure in one sentence for a reader who cannot see the render.
+
+## Verification
+
+- Judge a diagram from its rendered image, not from its source. Direction, sibling rows, and edge bundles are visible only in the output.
+- Render to PNG. An SVG export reads back as markup with no recoverable spatial meaning.
+- Apply the four questions above as a reviewer, against the same render the author judged.
+- State which verification was skipped when no renderer is available. A diagram written without a render is still shippable, and one reported as verified without a render is not.