From fcb9a2262dc1b0b91d5b58c656a9c2e78f4c98bc Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Sun, 26 Apr 2026 22:07:43 +0200 Subject: [PATCH] docs(python-architect): document mermaid classDiagram :::cssClass GitHub-render trap GitHub's mermaid parser rejects ':::cssClass' appended to a relationship line ('A *-- B:::touched') with parse error 'Expecting NEWLINE, EOF, LABEL, got STYLE_SEPARATOR'. The shorthand is only valid as a standalone 'class Name:::cssClass' declaration in classDiagram. This trap silently breaks rendered diagrams in panel review verdict comments, which are the persona's authoritative output channel. The persona's existing illustrative example was already correct; this adds an explicit gotcha block so the rule cannot be missed. Trap does not apply to flowchart diagrams, where the inline form is valid. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .apm/agents/python-architect.agent.md | 10 ++++++++++ .github/agents/python-architect.agent.md | 10 ++++++++++ apm.lock.yaml | 2 +- 3 files changed, 21 insertions(+), 1 deletion(-) diff --git a/.apm/agents/python-architect.agent.md b/.apm/agents/python-architect.agent.md index 15bcee2e1..ebedc9af5 100644 --- a/.apm/agents/python-architect.agent.md +++ b/.apm/agents/python-architect.agent.md @@ -143,6 +143,16 @@ classDiagram Read the PR's diff and surrounding code, then draw the actual problem-space classes.) +**Mermaid `classDiagram` GitHub-render gotcha**: the `:::cssClass` +shorthand is ONLY valid as a standalone `class Name:::cssClass` +declaration (or inside a `class Name:::cssClass { ... }` block). +GitHub's mermaid parser rejects `:::cssClass` appended to a +relationship line (`A *-- B:::touched`) with `Expecting 'NEWLINE', +'EOF', 'LABEL', got 'STYLE_SEPARATOR'`. Always declare the styled +classes on their own lines BEFORE the `classDef` block. This trap +does not apply to `flowchart` diagrams, where the inline form is +valid. + If the PR is purely procedural (no class changes anywhere in scope), state that explicitly and substitute a `classDiagram` showing the module boundaries and the function entry points -- still annotated diff --git a/.github/agents/python-architect.agent.md b/.github/agents/python-architect.agent.md index 15bcee2e1..ebedc9af5 100644 --- a/.github/agents/python-architect.agent.md +++ b/.github/agents/python-architect.agent.md @@ -143,6 +143,16 @@ classDiagram Read the PR's diff and surrounding code, then draw the actual problem-space classes.) +**Mermaid `classDiagram` GitHub-render gotcha**: the `:::cssClass` +shorthand is ONLY valid as a standalone `class Name:::cssClass` +declaration (or inside a `class Name:::cssClass { ... }` block). +GitHub's mermaid parser rejects `:::cssClass` appended to a +relationship line (`A *-- B:::touched`) with `Expecting 'NEWLINE', +'EOF', 'LABEL', got 'STYLE_SEPARATOR'`. Always declare the styled +classes on their own lines BEFORE the `classDef` block. This trap +does not apply to `flowchart` diagrams, where the inline form is +valid. + If the PR is purely procedural (no class changes anywhere in scope), state that explicitly and substitute a `classDiagram` showing the module boundaries and the function entry points -- still annotated diff --git a/apm.lock.yaml b/apm.lock.yaml index e7d191917..b8facdf76 100644 --- a/apm.lock.yaml +++ b/apm.lock.yaml @@ -41,7 +41,7 @@ local_deployed_file_hashes: .github/agents/doc-analyser.agent.md: sha256:47b1d0204904b786c19d4fe84343e86cdab6f92f862f676ba741ffe6e1385679 .github/agents/doc-writer.agent.md: sha256:328a5b9ea079869b8ccd914a6e2135c204225a5eedb42f59a1ec73058f7f0b47 .github/agents/oss-growth-hacker.agent.md: sha256:8d18f5be46913c40ad3aa66fb984575a88988cfac402d39353cdfb09f7e582c5 - .github/agents/python-architect.agent.md: sha256:32ed3390cb0e41fea28b3fd95b00124cd097ea0db51f992d2349e6837742723c + .github/agents/python-architect.agent.md: sha256:a70b1be6cd877a85414a65a1db8117be7dbecc3865d98045f46ed14462fda099 .github/agents/supply-chain-security-expert.agent.md: sha256:9a4e731b12e7658f71d54c22e90f80ce0c45e3eacbb069b8505ed96ec9e79ba5 .github/instructions/changelog.instructions.md: sha256:1e51ec4c74e847967962bd279dc4c6e582c5d3578490b3c28d5f3acd3e05f73e .github/instructions/cicd.instructions.md: sha256:9c0fafc74f743aa97e5adba2168d66c9e3a327b135065e3b804bdbb5f04cda5d