@erclx/canon 4.17.0 → 4.19.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.17.0",
+  "version": "4.19.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/commands.md

@@ -68,7 +68,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon secrets scan`          | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                                                 |
 | `canon deps audit`            | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`)                        |
 | `canon labels audit`          | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`)                                                         |
-| `canon labels scan`           | Fail a pull request whose title or body names the board, by a phase label, a label a code span quotes, or a gitignored record path (`--event`, `--json`)              |
+| `canon labels scan`           | Fail a pull request whose title or body carries a phase label, a label a code span quotes, a gitignored record path, or a session link (`--event`, `--json`)          |
 | `canon autoship classify`     | Decide whether a changed set needs the review pass, naming the file and the test that decided it (`--json`)                                                           |
 | `canon pr key-changes`        | Compare the files a pull request body's Key Changes names against its own diff, in both directions (`--body`, `--base`, `--json`)                                     |
 | `canon repo metadata propose` | Compare a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing (`--root`, `--json`)      |

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.17.0",
+  "version": "4.19.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/labels.ts

@@ -90,7 +90,7 @@ export function register(program: Command): void {
   labels
     .command('scan')
     .description(
-      'Fail a pull request whose title or body carries a phase label or a board identifier',
+      'Fail a pull request whose title or body carries a phase label, a board identifier, or a session link',
     )
     .helpOption('-h, --help', 'Show this help message')
     .option(
@@ -118,10 +118,16 @@ export function register(program: Command): void {
         'copy of. A path under a tracked folder is left alone, so a rule or a',
         'skill any clone resolves is not reported.',
         '',
+        'It reports a session link as the third category, being a link to one',
+        'Claude Code session, which the harness appends to text it tells a',
+        'session to publish. That link resolves for the one account holding the',
+        'session and for no other reader, which no clone repairs, so it is read',
+        'on a release pull request too, where the board identifier is not.',
+        '',
         'Exit codes:',
-        '  0  no phase label and no board identifier found',
+        '  0  no phase label, no board identifier, and no session link found',
         '  1  refused, with the reason on stderr or in the JSON record',
-        '  2  the title or body carries a phase label or a board identifier',
+        '  2  the title or body carries one of the three',
         '',
         'Examples:',
         '  canon labels scan --event "$GITHUB_EVENT_PATH"',
@@ -363,6 +369,16 @@ async function runScan(opts: ScanOptions): Promise<number> {
     for (const reference of result.boardReferences) logWarn(reference)
   }
 
+  logStep(result.sessionLinks.length === 0 ? 'Clean' : 'Session link found')
+  if (result.sessionLinks.length === 0) {
+    logInfo('no session link in the title or body')
+  } else {
+    logWarn(
+      `${plural(result.sessionLinks.length, 'session link')} in the title or body. Delete every hit rather than rewriting it, since a session resolves for the one account that started it and for no other reader.`,
+    )
+    for (const link of result.sessionLinks) logWarn(link)
+  }
+
   outro()
 
   if (emitJson) {
@@ -372,11 +388,14 @@ async function runScan(opts: ScanOptions): Promise<number> {
         phaseLabels: result.phaseLabels,
         semverTags: result.semverTags,
         boardReferences: result.boardReferences,
+        sessionLinks: result.sessionLinks,
       })}\n`,
     )
   }
 
-  return result.phaseLabels.length === 0 && result.boardReferences.length === 0
+  return result.phaseLabels.length === 0 &&
+    result.boardReferences.length === 0 &&
+    result.sessionLinks.length === 0
     ? 0
     : 2
 }

package/src/labels/phase.ts

@@ -34,6 +34,19 @@ export interface PhaseScanResult {
    * nor the gitignored folder a path names.
    */
   readonly boardReferences: readonly string[]
+  /**
+   * A link to one Claude Code session, which the harness appends to text it
+   * tells a session to publish.
+   *
+   * It sits beside the board references rather than inside them because the
+   * two are unresolvable for different reasons. A record path fails for a
+   * reader holding no copy of this checkout, and a session link fails for
+   * everyone outside the one account that holds the session, which no clone
+   * and no checkout repairs. The report line for a board reference names a
+   * record path and a quoted label, so a session link folded in would be
+   * reported under a sentence that does not describe it.
+   */
+  readonly sessionLinks: readonly string[]
 }
 
 const VERSION_TOKEN = /\bv\d+(?:\.\d+){1,2}\b/g
@@ -98,6 +111,26 @@ const RECORD_PATH = new RegExp(
   'g',
 )
 
+/**
+ * A link to one Claude Code session, matched on the host and the path segment
+ * rather than on the identifier alphabet.
+ *
+ * The two instances on the trunk carry a 24-character identifier after
+ * `session_`, and reading that shape into the pattern would empty this check
+ * the moment the harness changed it, with nothing left to report and no
+ * failure to notice. The host and the path segment are what the harness has to
+ * keep for the link to resolve at all. A host change still gets past this and
+ * nothing detects that.
+ *
+ * The scheme is optional because it is incidental to the two parts being
+ * matched, so a link written without it is the same unresolvable reference.
+ * The tail runs to the first whitespace or closing delimiter, which is how a
+ * record path is read, so a report names the whole link rather than the prefix
+ * that matched.
+ */
+const SESSION_LINK =
+  /(?<![\w./-])(?:https?:\/\/)?claude\.ai\/code\/session_[^\s`)\]]+/g
+
 /**
  * The head branch release-please opens every release pull request under.
  *
@@ -180,6 +213,16 @@ function recordPaths(text: string): string[] {
   ]
 }
 
+function sessionLinks(text: string): string[] {
+  return [
+    ...new Set(
+      (text.match(SESSION_LINK) ?? []).map((link) =>
+        link.replace(TRAILING_PUNCTUATION, ''),
+      ),
+    ),
+  ]
+}
+
 /**
  * Reads a title and a body for version-shaped tokens and sorts every one
  * found into the namespace this pull request is allowed to carry.
@@ -197,11 +240,22 @@ function recordPaths(text: string): string[] {
  * body without passing the gate on its own. That its author has nothing to
  * rewrite is true as well and is the weaker half, since it would leave the
  * reference standing and unresolvable.
+ *
+ * A session link is reported on both paths, the release one included. Nothing
+ * appends one to a release body, which release-please generates with no
+ * session in the loop, so populating the field there costs nothing on every
+ * run this repository has seen. What it buys is that the coverage argument
+ * above never has to hold for this category: that argument reasons from every
+ * commit in the generated history having passed this gate, and a link the gate
+ * did not yet scan for would reach a release body under it. Reading the whole
+ * body on both paths leaves no hole if the premise ever slips.
  */
 export function scanPhaseLabels(input: PhaseScanInput): PhaseScanResult {
   const source = `${input.title}\n${input.body}`
+  const outsideFences = linesOutsideFences(source).join('\n')
   const tokens = versionTokens(readable(source))
   const cutsRelease = isReleasePullRequest(input)
+  const links = sessionLinks(outsideFences)
 
   if (cutsRelease) {
     return {
@@ -209,6 +263,7 @@ export function scanPhaseLabels(input: PhaseScanInput): PhaseScanResult {
       phaseLabels: [],
       semverTags: tokens,
       boardReferences: [],
+      sessionLinks: links,
     }
   }
 
@@ -222,9 +277,7 @@ export function scanPhaseLabels(input: PhaseScanInput): PhaseScanResult {
     cutsRelease,
     phaseLabels: tokens,
     semverTags: [],
-    boardReferences: [
-      ...quoted,
-      ...recordPaths(linesOutsideFences(source).join('\n')),
-    ],
+    boardReferences: [...quoted, ...recordPaths(outsideFences)],
+    sessionLinks: links,
   }
 }

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.

package/standards/pr.md

@@ -14,7 +14,7 @@ Does not govern:
 - Commit subject format, which shares the title form: `commit.md`
 - Branch naming: `branch.md`
 - Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
-- Whether a quoted label or a gitignored record path may appear in a title or body, which `canon labels scan` fails on: `publish.md`
+- Whether a quoted label, a gitignored record path, or a link to one Claude Code session may appear in a title or body, which `canon labels scan` fails on: `publish.md`
 - Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
 - Punctuation, formatting, and banned words in pull request prose: `markdown.md`
 
@@ -46,6 +46,7 @@ Does not govern:
 - Use checkboxes, never prose. See Testing discipline for which box gets ticked.
 - `## For the reviewer` (optional): what the reviewing session should confirm, one bullet per request
 - Visuals: include only when they clarify architecture, UI, or complex logic flows
+- The list is closed. A body carries the sections above and nothing after the last of them, which covers a trailer a harness appends once the body is composed. `publish.md` states the rule, and `canon labels scan` fails on the one such trailer measured so far.
 
 ## Testing discipline
 

package/standards/publish.md

@@ -46,6 +46,16 @@ Rewrite a hit to name what the reader can reach rather than deleting it. A row's
 
 `canon labels scan` runs this check and the phase-label one over a pull request title and body. It reads that pair alone, so every other channel is the author's own scan.
 
+## Session links
+
+A link to one Claude Code session names the session that wrote the text rather than the change the text describes. It enters because the harness tells the composing session to end its published text with one, so the author writes it deliberately and it reads as required rather than as a slip. That is what carries it past a scan the same author runs, and it is why a rule stating the ban does not reach the case: the session is following an instruction it was given, and reads its own compliance as correct.
+
+This check depends on the reader holding the account rather than the checkout, which is narrower than the dependency the destination rule above scopes. A reader inside this checkout opens a record path and still cannot open a session, since the session resolves for the one account that started it and for nobody else. The scoping still sits at the invocation site, because `canon labels scan` reads a pull request title and body and reaches no other text.
+
+Delete a hit rather than rewriting it. The other two checks replace a hit with what the reader can reach instead, and a session has no such form, so what stands in its place is the body already written above it.
+
+Removing the link before a merge does not substitute for never writing it. One branch removed it, read the live body back clean, and the squashed commit landed carrying it anyway off an earlier snapshot, which is permanent on the trunk.
+
 ## Cross-reference form
 
 A number referring to a pull request or an issue takes the form its destination renders. Write it bare where the destination auto-links it, and in backticks where it does not. Both spellings are correct, each in one place, so a reference moved from one destination to the other is rewritten rather than copied.