Audited the checked-out pr-192 branch against local mermaid@11.16.0 and the vendored official pages for FLOWCHART, STATE, and SEQUENCE. plan.md and progress.md were requested but are absent in this checkout. The PR diff is Sankey-focused; the findings below are pre-existing family-contract gaps exposed by auditing the PR's overall claimed capability state, not regressions introduced in its changed source files.
- Syntax:
Loading
sequenceDiagram A-|/B: bottom half arrow A-|\B: top half arrow
- Expected Mermaid implication: The complete
-|//-|\token is the message arrow and the recipient remainsB. Mermaid 11.16 documents the complete solid/dotted, forward/reverse half-arrow vocabulary, including-|/,-|\,-//, and their reverse forms (skills/agentic-mermaid-diagram-workflow/references/upstream/sequenceDiagram.md:439-462). - Actual Agentic behavior: The message regex consumes only
-|and treats the final/or\as part of the participant id. The probe produced actorsA,/BforA-|/BandA,\BforA-|\B. It similarly parsesA-//Bas recipient/B. The regex only has one-character half-head alternatives (src/sequence/parser.ts:6), while the IR has onlyhalf-top/half-bottomand cannot retain the documented stick/non-stick distinction (src/sequence/types.ts:32-33). No diagnostic is emitted. - Ledger status: Unrecorded gap. The capability ledger generically maps all
documentedheadings tosource-preserved(src/syntax-capability-ledger.ts:178-188), but the renderer parser actively misparses these lines; the sequence opaque-segment divergence only concerns typed mutation (docs/project/divergences.md:20-25,44-50). - Smallest contract/test: Parameterize every row in the official half-arrow table. Assert
from === A,to === B, exact solid/dotted and start/end orientation, stable serialize/reparse, SVG marker side/shape, and no phantom slash/backslash actor. The IR likely needs distinct normal/stick half-head variants.
- Syntax:
sequenceDiagram; participant A; participant B; A->>B: hi - Expected Mermaid implication: Semicolons may replace line breaks; the official page explicitly requires
#59;when a literal semicolon is desired in message text (skills/agentic-mermaid-diagram-workflow/references/upstream/sequenceDiagram.md:930-946). Local Mermaid 11.16mermaid.parseaccepts this exact source assequence. - Actual Agentic behavior:
verifyMermaidreturns no warnings, but SVG contains no actors and nohimessage.parseSequenceDiagraminitializes an empty diagram and processes only entries after the first array element (src/sequence/parser.ts:65-81; line-oriented implementation), with no sequence statement splitter comparable to Flowchart's. The audit probe rendered a 1,707-byte empty shell. - Ledger status: Unrecorded and silent. This is neither the documented segment-preserving limitation nor a diagnosed divergence.
- Smallest contract/test: A conformance test comparing newline and semicolon forms for actors, messages, blocks, notes, layout semantics, and non-empty SVG. Split only grammar-level semicolons and preserve
#59;/entity content.
- Syntax:
Loading
stateDiagram-v2 A --> B %% inline comment B --> C
- Expected Mermaid implication: State comments may occur at the end of a statement; everything after
%%to newline is ignored (skills/agentic-mermaid-diagram-workflow/references/upstream/stateDiagram.md:440-458). Both transitions remain. - Actual Agentic behavior: Only the
B --> Cedge survives. Global preprocessing removes only lines that start with%%(src/parser.ts:35-36), then the anchored transition grammar rejects the trailing comment (src/state/parse-core.ts:109-116). The structured body preserves the source by falling opaque and emits genericstate_opaque, but the render parser still drops topology. - Ledger status: Partially ledgered, behavior gap unrecorded. Opaque round-trip/mutation refusal follows
docs/project/divergences.md:18,38-50; silently losing a legal edge during render does not. - Smallest contract/test: Strip quote-aware trailing
%%...before both shared state parsers. Assert graph edgesA→B,B→C, structured (not opaque) body, round-trip, SVG connectors, and no comment text.
- Syntax:
Loading
sequenceDiagram critical connect A->>B: try option timeout B-->>A: fail end - Expected Mermaid implication:
optionpartitions alternatives inside acriticalregion (skills/agentic-mermaid-diagram-workflow/references/upstream/sequenceDiagram.md:754-795). - Actual Agentic behavior: The opener regex lacks a keyword boundary and matches
optat the start ofoption(src/sequence/parser.ts:248-259); the divider grammar recognizes onlyelse|and, notoption(src/sequence/parser.ts:263-271). The SVG therefore contains a fabricated nestedopt [ion timeout]block instead of a critical option divider. The genericsequence_opaque_segmentwarning only says typed read-back is incomplete, not that rendering changes semantics. - Ledger status: Typed critical regions being source-preserved is deliberate (
docs/project/divergences.md:24-25); the renderer's prefix misparse is unrecorded. - Smallest contract/test: Require keyword boundaries, recognize
optiononly incritical, and test block tree/divider positions plus SVG labels (critical [connect],timeout, noopt [ion timeout]).
- Syntax:
Loading
sequenceDiagram rect rgb(255, 0, 0) A->>B: hi end - Expected Mermaid implication: The region background is highlighted with the authored RGB/RGBA color (
skills/agentic-mermaid-diagram-workflow/references/upstream/sequenceDiagram.md:846-901). - Actual Agentic behavior: Parser stores the color as an ordinary block
label(src/sequence/parser.ts:248-258). Renderer uses theme group fill/none(src/sequence/renderer.ts:532-552) and printsrect [rgb(255, 0, 0)]as a header (src/sequence/renderer.ts:604-609). Probe confirmed the region rect hadfill="none". - Ledger status: Source preservation for rect blocks is deliberate at the edit layer (
src/agent/sequence-body.ts:44-48;docs/project/divergences.md:24-25), but the documented rendering implication is not recorded as divergent. - Smallest contract/test: Add an optional background paint field to rect blocks; assert exact effective fill, no synthetic header label, nested rect compositing, deterministic SVG, and contrast/security validation.
- Syntax:
class Moving, Crash movement - Expected Mermaid implication: Apply
movementto both states; this exact spaced form appears in the official syntax and examples (skills/agentic-mermaid-diagram-workflow/references/upstream/stateDiagram.md:519-535,560,584). - Actual Agentic behavior: Both legacy and structured regexes disallow whitespace in the comma-separated id group (
src/parser.ts:596-603,src/agent/state-body.ts:178-190). The render graph has no class assignments and no authored fill. Verification emits only genericstate_opaque, so the user is told mutation is unavailable, not that rendering ignored a valid style. - Ledger status: Opaque preservation is deliberate; ignored authored appearance is unrecorded.
- Smallest contract/test: Permit optional whitespace around commas, trim ids, and assert two class assignments, two styled SVG nodes, structured round-trip, and equivalence with
class Moving,Crash movement.
- Syntax:
Loading
flowchart LR A e1@--> B classDef hot stroke:#f00,stroke-width:8px class e1 hot
- Expected Mermaid implication:
class e1 hotapplies the class to edgee1; official docs use this mechanism for edge animation (skills/agentic-mermaid-diagram-workflow/references/upstream/flowchart.md:1268-1294). - Actual Agentic behavior: The parser records
classAssignments[e1] = hot(src/parser.ts:340-347), but the assignment is consumed by node styling only; probe SVG contained neither#f00nor the 8px edge paint, and verification returned no warnings. The targeted Flowchart warning pass covers metadata, images, interactions, markdown, and malformed statements but not ineffective edge classes (src/agent/flowchart-unsupported.ts:28-56). - Ledger status: Unrecorded gap. This is source-preserved and apparently structured, but not operable or diagnosed.
- Smallest contract/test: Resolve class assignment targets against both node and edge identities. Assert static edge paint from classDef; if animation CSS is intentionally unsupported, emit a specific ineffective/unsupported diagnostic rather than claiming full class effect.
- FLOWCHART: Extra-dash minimum link length is modeled: probe parsed
A ----> Cwithlength: 3, matching the documented rank-length implication (skills/agentic-mermaid-diagram-workflow/references/upstream/flowchart.md:1348-1409). Edge IDs have dedicated parse/round-trip/SVG/op/verify coverage (src/__tests__/flowchart-edge-ids.test.ts:30-118); ampersand fan-out and same-line semicolon statements are covered (src/__tests__/flowchart-parser-conformance.test.ts:54-67). Documented-but-unwired config is explicitly named rather than swallowed (src/flowchart-config.ts:42-58). - STATE: Notes have parse/layout/SVG/agent/ops coverage (
src/__tests__/state-notes.test.ts:53-153). Choice/fork/join, history diagnostics, and concurrency regions have semantic geometry tests (src/__tests__/state-pseudostates.test.ts:56-165). State config separates wired and legacy ineffective keys (src/state/config.ts:6-30,54-96). - SEQUENCE: Actor/message/block/note basics are exercised (
src/__tests__/sequence-parser.test.ts:20-223); boxes, autonumber, and create/destroy each have parse/layout/render tests (src/__tests__/sequence-box.test.ts:44-190,src/__tests__/sequence-autonumber.test.ts:19-74,src/__tests__/sequence-create-destroy.test.ts:30-112). Actor stereotype vocabulary and safe menu fields are typed (src/sequence/types.ts:32-56). Documented-but-unwired config keys are explicitly listed for ineffective-config diagnostics (src/sequence/config.ts:45-94). - Preservation contract: Sequence critical/rect and State unknown forms can remain source-preserved for serialization/typed-edit refusal. That is a useful deliberate divergence, but it does not make incorrect renderer lowering acceptable (
docs/project/divergences.md:38-50).
- Half-arrow glyph distinctions beyond endpoint corruption: Endpoint corruption is confirmed. Separately, the local IR collapses the official normal/stick and some reverse half-arrow forms into only two head kinds (
src/sequence/types.ts:32-33). A browser-backed Mermaid 11.16 render oracle should pin the exact marker geometry before choosing the expanded local enum. - State inline-comment upstream executable probe: The official documentation is explicit, and Agentic loss is confirmed. Local
mermaid.parsefor State was blocked in the headless probe by the package'sDOMPurify.addHookenvironment requirement, so a jsdom/browser oracle should be added when fixing it.
git diff --name-status main...HEAD, branch/log/status inspection: PR is Sankey-focused; no staged files; only pre-existing untracked.pi-subagents/is present.- Custom Bun parser/verify/SVG probes reproduced all seven Agentic behaviors above. A first temporary harness invocation failed because
/tmprelative imports did not resolve; the corrected absolute-import harness passed. - Local Mermaid 11.16
mermaid.parseaccepted sequence semicolon, critical, rect, and flow edge-class probes. State probes reached a headless DOMPurify environment error, not a reported grammar rejection. - No full suite was run: this was a read-only syntax audit, and no project/source files or tests were changed.
{
"criteriaSatisfied": [
{
"id": "criterion-1",
"status": "satisfied",
"evidence": "Seven concrete findings include severity, exact official syntax, expected vs actual behavior, project file:line evidence, vendored official-doc citations, ledger classification, and smallest required contract/test."
}
],
"changedFiles": [],
"testsAddedOrUpdated": [],
"commandsRun": [
{
"command": "git status --short; git diff --name-status main...HEAD; git diff --cached --name-only",
"result": "passed",
"summary": "Confirmed pr-192 scope, no staged files, and only pre-existing untracked .pi-subagents/."
},
{
"command": "bun /tmp/audit-probes-abs.ts (corrected absolute-import harness)",
"result": "passed",
"summary": "Reproduced empty semicolon sequence, half-arrow endpoint corruption, state topology/style loss, critical option misparse, rect fill loss, and ineffective flow edge class."
},
{
"command": "node /tmp/mermaid-parse.mjs",
"result": "passed",
"summary": "Pinned Mermaid 11.16 accepted sequence semicolon/critical/rect and Flowchart edge-class syntax; State checks were limited by headless DOMPurify setup."
},
{
"command": "bun /tmp/audit-probes.ts (initial relative-import harness)",
"result": "failed",
"summary": "Temporary audit harness could not resolve ./src from /tmp; corrected with absolute imports. This was not a product/test failure."
}
],
"validationOutput": [
"A-|/B parsed recipient as /B; A-|\\B parsed recipient as \\B.",
"Semicolon-only sequence verified clean but rendered no actors/messages.",
"State inline comment left only B->C; spaced class list produced zero class assignments.",
"Critical option rendered as opt [ion timeout]; rect rgb region rendered fill=none.",
"Flow edge-ID class assignment was parsed but SVG contained no authored red/8px edge style."
],
"residualRisks": [
"No browser-backed Mermaid SVG oracle was available for State or exact half-arrow glyph geometry.",
"Full repository tests were not run because the task was review-only and no code changed.",
"plan.md and progress.md requested by the task were absent from the checkout."
],
"noStagedFiles": true,
"diffSummary": "Review-only; no repository diff created. PR #192 itself is Sankey-focused, while this report identifies pre-existing Flowchart/State/Sequence contract gaps visible in the PR's overall capability state.",
"reviewFindings": [
"high: src/sequence/parser.ts:6 - documented half-arrow tokens corrupt recipient ids",
"high: src/sequence/parser.ts:65 - semicolon-separated sequence markup renders empty without warning",
"high: src/state/parse-core.ts:109 - legal trailing comments delete transitions from rendering",
"high: src/sequence/parser.ts:249 - critical option is prefix-misparsed as opt",
"medium: src/sequence/renderer.ts:532 - rect COLOR is ignored as fill and displayed as a header",
"medium: src/parser.ts:597 - spaced State class lists are ignored",
"medium: src/parser.ts:341 - Flowchart edge class assignments are parsed but ineffective"
],
"manualNotes": "Report saved to the authoritative /tmp path. No project/source edits were made."
}