agentic-mermaid 0.1.1 → 0.2.0

package/docs/design/families/journey-mermaid-classic-prototype.svg

@@ -1,163 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1120" height="640" viewBox="0 0 1120 640" role="img" aria-labelledby="title desc">
-  <title id="title">Mermaid-style Journey diagram prototype</title>
-  <desc id="desc">A prototype Journey diagram using Mermaid's visual metaphor: actor legend at left, horizontal section spans, task boxes in source order, score-positioned sentiment marks, and a forward baseline.</desc>
-  <defs>
-    <marker id="arrowhead" markerWidth="10" markerHeight="8" refX="9" refY="4" orient="auto">
-      <path d="M0,0 L10,4 L0,8 Z" fill="#4b5563" />
-    </marker>
-    <filter id="softShadow" x="-10%" y="-10%" width="120%" height="130%">
-      <feDropShadow dx="0" dy="2" stdDeviation="2" flood-color="#111827" flood-opacity="0.12" />
-    </filter>
-    <style>
-      .bg { fill: #fffdfb; }
-      .title { fill: #1f2937; font: 700 24px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
-      .subtitle { fill: #6b7280; font: 500 12px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
-      .legend-title { fill: #374151; font: 700 13px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
-      .legend-label { fill: #374151; font: 500 13px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
-      .section-label { fill: #1f2937; font: 700 14px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
-      .task { fill: #ffffff; stroke: #cbd5e1; stroke-width: 1.2; filter: url(#softShadow); }
-      .task-label { fill: #1f2937; font: 650 13px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
-      .task-meta { fill: #6b7280; font: 500 11px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
-      .track { stroke: #cbd5e1; stroke-width: 1.2; stroke-dasharray: 4 6; }
-      .guide { stroke: #e5e7eb; stroke-width: 1; }
-      .score-label { fill: #9ca3af; font: 600 10px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
-      .baseline { stroke: #4b5563; stroke-width: 2.2; marker-end: url(#arrowhead); }
-      .face { fill: #facc15; stroke: #8a6d1d; stroke-width: 1.2; }
-      .face-eye { fill: #3f3f46; }
-      .face-mouth { fill: none; stroke: #3f3f46; stroke-width: 1.6; stroke-linecap: round; }
-      .section-discover { fill: #e8f3ff; stroke: #93c5fd; }
-      .section-try { fill: #eaf7ee; stroke: #86efac; }
-      .section-recover { fill: #fff0dd; stroke: #fdba74; }
-      .actor-user { fill: #2563eb; }
-      .actor-support { fill: #16a34a; }
-      .actor-ops { fill: #d97706; }
-    </style>
-  </defs>
-
-  <rect class="bg" x="0" y="0" width="1120" height="640" />
-  <text class="title" x="220" y="42">Checkout support journey</text>
-  <text class="subtitle" x="220" y="64">Mermaid-style score curve, not task cards</text>
-
-  <g aria-label="Actor legend">
-    <text class="legend-title" x="40" y="122">Actors</text>
-    <circle class="actor-user" cx="48" cy="148" r="6" />
-    <text class="legend-label" x="66" y="153">User</text>
-    <circle class="actor-support" cx="48" cy="176" r="6" />
-    <text class="legend-label" x="66" y="181">Support</text>
-    <circle class="actor-ops" cx="48" cy="204" r="6" />
-    <text class="legend-label" x="66" y="209">Ops</text>
-  </g>
-
-  <g aria-label="Section spans">
-    <rect class="section-discover" x="210" y="84" width="294" height="52" rx="6" />
-    <text class="section-label" x="357" y="116" text-anchor="middle">Discover</text>
-    <rect class="section-try" x="510" y="84" width="294" height="52" rx="6" />
-    <text class="section-label" x="657" y="116" text-anchor="middle">Try</text>
-    <rect class="section-recover" x="810" y="84" width="294" height="52" rx="6" />
-    <text class="section-label" x="957" y="116" text-anchor="middle">Recover</text>
-  </g>
-
-  <g aria-label="Score guide">
-    <line class="guide" x1="198" y1="294" x2="1084" y2="294" />
-    <line class="guide" x1="198" y1="334" x2="1084" y2="334" />
-    <line class="guide" x1="198" y1="374" x2="1084" y2="374" />
-    <line class="guide" x1="198" y1="414" x2="1084" y2="414" />
-    <line class="guide" x1="198" y1="454" x2="1084" y2="454" />
-    <text class="score-label" x="176" y="298">5</text>
-    <text class="score-label" x="176" y="338">4</text>
-    <text class="score-label" x="176" y="378">3</text>
-    <text class="score-label" x="176" y="418">2</text>
-    <text class="score-label" x="176" y="458">1</text>
-  </g>
-
-  <line class="baseline" x1="200" y1="512" x2="1084" y2="512" />
-
-  <g aria-label="Tasks">
-    <g transform="translate(220 166)">
-      <rect class="task" x="0" y="0" width="124" height="72" rx="5" />
-      <text class="task-label" x="62" y="27" text-anchor="middle">Find docs</text>
-      <text class="task-meta" x="62" y="49" text-anchor="middle">score 4</text>
-      <circle class="actor-user" cx="54" cy="61" r="4" />
-      <line class="track" x1="62" y1="74" x2="62" y2="346" />
-    </g>
-    <g transform="translate(370 166)">
-      <rect class="task" x="0" y="0" width="124" height="72" rx="5" />
-      <text class="task-label" x="62" y="27" text-anchor="middle">Choose setup</text>
-      <text class="task-meta" x="62" y="49" text-anchor="middle">score 3</text>
-      <circle class="actor-user" cx="47" cy="61" r="4" />
-      <circle class="actor-support" cx="62" cy="61" r="4" />
-      <line class="track" x1="62" y1="74" x2="62" y2="346" />
-    </g>
-    <g transform="translate(520 166)">
-      <rect class="task" x="0" y="0" width="124" height="72" rx="5" />
-      <text class="task-label" x="62" y="27" text-anchor="middle">Run install</text>
-      <text class="task-meta" x="62" y="49" text-anchor="middle">score 2</text>
-      <circle class="actor-user" cx="47" cy="61" r="4" />
-      <circle class="actor-ops" cx="62" cy="61" r="4" />
-      <line class="track" x1="62" y1="74" x2="62" y2="346" />
-    </g>
-    <g transform="translate(670 166)">
-      <rect class="task" x="0" y="0" width="124" height="72" rx="5" />
-      <text class="task-label" x="62" y="27" text-anchor="middle">First render</text>
-      <text class="task-meta" x="62" y="49" text-anchor="middle">score 5</text>
-      <circle class="actor-user" cx="54" cy="61" r="4" />
-      <line class="track" x1="62" y1="74" x2="62" y2="346" />
-    </g>
-    <g transform="translate(820 166)">
-      <rect class="task" x="0" y="0" width="124" height="72" rx="5" />
-      <text class="task-label" x="62" y="27" text-anchor="middle">Hit error</text>
-      <text class="task-meta" x="62" y="49" text-anchor="middle">score 1</text>
-      <circle class="actor-user" cx="47" cy="61" r="4" />
-      <circle class="actor-support" cx="62" cy="61" r="4" />
-      <line class="track" x1="62" y1="74" x2="62" y2="346" />
-    </g>
-    <g transform="translate(970 166)">
-      <rect class="task" x="0" y="0" width="124" height="72" rx="5" />
-      <text class="task-label" x="62" y="27" text-anchor="middle">Recover flow</text>
-      <text class="task-meta" x="62" y="49" text-anchor="middle">score 4</text>
-      <circle class="actor-user" cx="39" cy="61" r="4" />
-      <circle class="actor-support" cx="54" cy="61" r="4" />
-      <circle class="actor-ops" cx="69" cy="61" r="4" />
-      <line class="track" x1="62" y1="74" x2="62" y2="346" />
-    </g>
-  </g>
-
-  <g aria-label="Score markers">
-    <g transform="translate(282 334)">
-      <circle class="face" cx="0" cy="0" r="18" />
-      <circle class="face-eye" cx="-6" cy="-5" r="2" />
-      <circle class="face-eye" cx="6" cy="-5" r="2" />
-      <path class="face-mouth" d="M-8,5 Q0,12 8,5" />
-    </g>
-    <g transform="translate(432 374)">
-      <circle class="face" cx="0" cy="0" r="18" />
-      <circle class="face-eye" cx="-6" cy="-5" r="2" />
-      <circle class="face-eye" cx="6" cy="-5" r="2" />
-      <path class="face-mouth" d="M-8,6 L8,6" />
-    </g>
-    <g transform="translate(582 414)">
-      <circle class="face" cx="0" cy="0" r="18" />
-      <circle class="face-eye" cx="-6" cy="-5" r="2" />
-      <circle class="face-eye" cx="6" cy="-5" r="2" />
-      <path class="face-mouth" d="M-8,10 Q0,2 8,10" />
-    </g>
-    <g transform="translate(732 294)">
-      <circle class="face" cx="0" cy="0" r="18" />
-      <circle class="face-eye" cx="-6" cy="-5" r="2" />
-      <circle class="face-eye" cx="6" cy="-5" r="2" />
-      <path class="face-mouth" d="M-9,4 Q0,14 9,4" />
-    </g>
-    <g transform="translate(882 454)">
-      <circle class="face" cx="0" cy="0" r="18" />
-      <circle class="face-eye" cx="-6" cy="-5" r="2" />
-      <circle class="face-eye" cx="6" cy="-5" r="2" />
-      <path class="face-mouth" d="M-9,11 Q0,0 9,11" />
-    </g>
-    <g transform="translate(1032 334)">
-      <circle class="face" cx="0" cy="0" r="18" />
-      <circle class="face-eye" cx="-6" cy="-5" r="2" />
-      <circle class="face-eye" cx="6" cy="-5" r="2" />
-      <path class="face-mouth" d="M-8,5 Q0,12 8,5" />
-    </g>
-  </g>
-</svg>

package/docs/design/families/journey-migration-parity.md

@@ -1,439 +0,0 @@
-# Journey Migration Parity Spec
-
-Status: implemented — SVG visual metaphor (now with the experience-curve line
-and tiled section spans), shared parse core with typed opaque reasons,
-structured accessibility/literal text parity, semicolon statement parity,
-marker namespacing, ASCII width handling (grapheme-safe), style/palette/config
-coverage with WCAG-guarded section labels, and the Describe/Facts/Verify spec
-below. The elevation PR's description records why the first implementation's
-safeguards missed and what now enforces them.
-Last reviewed: 2026-07-10
-Issue: https://github.com/adewale/agentic-mermaid/issues/128
-Origin: https://github.com/adewale/agentic-mermaid/pull/6
-Research: [`journey-usage-research.md`](./journey-usage-research.md)
-
-## Problem
-
-Journey diagrams had two different gaps that were easy to conflate:
-
-1. Some Mermaid Journey syntax was parsed by the renderer path but still caused
-   the agent structured parser to fall back to opaque source preservation.
-2. Agentic Mermaid's previous Journey SVG used a card-based visual language,
-   while Mermaid's native Journey renderer uses a timeline-like experience curve.
-
-The first gap was a correctness and migration-support issue. The second is a
-visual parity issue. Pre-launch, we do not need to preserve the previous
-card-based Journey layout as public behavior. The chosen direction is to make
-Mermaid's Journey visual metaphor the default public renderer.
-
-## Origin
-
-Journey support was not originally requested through a tracked Agentic Mermaid
-issue. It landed in
-[`#6`](https://github.com/adewale/agentic-mermaid/pull/6), whose PR body says:
-there was "no tracked issue in this fork for the change." The immediate
-trigger was that Mermaid `journey` input failed with:
-
-```text
-Invalid mermaid header: "journey"
-```
-
-So the original implementation solved family coverage first: parse Mermaid
-Journey syntax, route it through SVG and ASCII rendering, preserve accessibility
-metadata, and add tests. The visual model was then made to fit the library's
-existing card-like house style. That is where the implementation diverged from
-Mermaid's own Journey metaphor.
-
-## Goals
-
-- Preserve Mermaid Journey syntax as structured data whenever the syntax is part
-  of Mermaid's documented Journey grammar.
-- Make parser failures explainable instead of silently collapsing to opaque.
-- Make `describe`, facts, verification, and ASCII output expose the same Journey
-  semantics that the SVG renderer consumes.
-- Make the public SVG Journey renderer use Mermaid's Journey visual metaphor:
-  a left-to-right experience curve with section spans, actor legend, actor
-  dots, score-positioned sentiment marks, and a progression baseline.
-- Treat the current card layout as an implementation artifact unless we later
-  choose to expose it as an explicitly named alternate look.
-
-## Current Syntax Support Snapshot
-
-Agentic Mermaid now supports the documented Mermaid Journey grammar in both the
-renderer parser and the structured agent parser:
-
-- `journey` header;
-- `title ...`;
-- `accTitle: ...`;
-- inline `accDescr: ...`;
-- block `accDescr { ... }` and `accDescr: { ... }`;
-- `section ...`;
-- task lines in the documented form `Task name: <score>: <actor>, <actor>`;
-- task lines without actors, which Mermaid accepts in practice;
-- comments, YAML frontmatter, and `%%{init: ...}%%` / `%%{initialize: ...}%%`
-  directives before parsing;
-- `<br>` / `<br/>` label normalization for title, section, task, and actor
-  text;
-- title/accessibility-only Journey header furniture.
-
-Mermaid's official docs define the score as an integer from 1 through 5. The
-parser enforces that range rather than accepting Mermaid's currently buggy
-out-of-range face placement behavior.
-
-The implementation also accepts the current Mermaid `JourneyDiagramConfig`
-shape:
-
-- margins and sizing: `diagramMarginX`, `diagramMarginY`, `leftMargin`,
-  `maxLabelWidth`, `width`, `height`, `taskMargin`;
-- title/task typography: `taskFontSize`, `taskFontFamily`, `titleColor`,
-  `titleFontFamily`, `titleFontSize`;
-- Journey colors: `actorColours`, `sectionFills`, `sectionColours`;
-- sequence-era compatibility fields present on Mermaid's Journey config:
-  `boxMargin`, `boxTextMargin`, `noteMargin`, `messageMargin`, `messageAlign`,
-  `bottomMarginAdj`, `rightAngles`, `activationWidth`, `textPlacement`.
-
-The fields that visibly affect the current Journey SVG are the Journey-specific
-layout, typography, and color fields. The sequence-era fields are accepted for
-Mermaid config compatibility but do not all have meaningful Journey geometry.
-
-Known remaining syntax/parity gaps and caveats:
-
-- Semicolon-separated Journey statements now follow upstream lexer semantics:
-  `;` terminates a statement (so `A: 5: Me; B: 3: Me` is two tasks) while
-  HTML entities such as `&amp;` keep their semicolons as literal label text.
-- Journey ASCII remains a compact semantic list, not a visual clone of
-  Mermaid's SVG Journey chart. It now wraps to `maxWidth` using terminal display
-  width, including CJK/emoji text, but it is intentionally not a miniature SVG
-  curve renderer.
-- Journey marker IDs are no longer the fixed `journey-arrowhead`; they are
-  derived from the diagram content and also participate in the repo-wide
-  `idPrefix` post-pass. Two different Journey diagrams no longer collide by
-  default. Repeated identical SVGs on the same page still need distinct
-  `idPrefix` values, matching the existing multi-diagram embedding contract.
-
-## Non-goals
-
-- Do not expand Journey into full customer journey mapping, service blueprinting,
-  emotional-lifecycle canvases, or swimlane workflow modeling in this issue.
-- Do not make Journey a flowchart variant.
-- Do not rely on embedding Mermaid's renderer as a black box.
-- Do not change the meaning of Mermaid Journey scores. Scores remain integers
-  from 1 through 5.
-
-## Current Failure Modes
-
-### Parser split
-
-There are two Journey parsers with different responsibilities:
-
-- `src/journey/parser.ts` powers the Journey renderer.
-- `src/agent/journey-body.ts` powers structured agent parsing and mutations.
-
-The renderer and structured agent parsers now accept Journey accessibility
-directives:
-
-- `accTitle: ...`
-- `accDescr: ...`
-- multiline `accDescr { ... }`
-
-It also normalizes quoted labels and `<br>` tags.
-
-The agent body parser now models those accessibility directives as part of the
-Journey body, so their presence no longer forces an opaque fallback. Title-only
-and accessibility-only Journey header furniture also stays structured when it is
-otherwise valid.
-
-This is where the implementation had gone wrong: accessibility was handled as a
-rendering concern, but it is also part of the family syntax contract. Every
-Journey syntax line that the renderer accepts must either be represented in
-`JourneyBody`, represented as shared diagram metadata without forcing an opaque
-body, or produce a targeted diagnostic.
-
-### Opaque fallback
-
-`structuredFamilyHooks` treats Journey parse misses as opaque source.
-The verifier still reports broad `UNSUPPORTED_SYNTAX` / `journey_opaque`
-diagnostics for genuinely unmodeled source. That preserves source, which is
-good, but migration tooling benefits when common malformed cases are separated:
-
-- unsupported documented syntax,
-- malformed score,
-- parser drift between renderer and agent paths,
-- or genuinely unknown Journey extension.
-
-Invalid Journey scores now receive a Journey-specific diagnostic. Broader
-malformed-line taxonomy is still a useful future refinement.
-
-### Incomplete semantic surfaces
-
-Structured Journey output still has room to become richer:
-
-- JSON describe output exposes task nodes but not a full Journey model.
-- Facts mention labels but do not summarize sections, score ranges, actor
-  participation, or Journey accessibility.
-- Verification offers targeted invalid-score diagnostics, but not yet precise
-  remediation for every malformed-line class.
-- ASCII width handling now wraps Journey task and actor text to `maxWidth` using
-  terminal display width; a visual clone of the SVG curve remains out of scope.
-
-### Visual expectation mismatch
-
-Before this migration, Agentic Mermaid's Journey renderer presented the diagram
-as section columns containing stacked task cards. Native Mermaid Journey diagrams present
-the same syntax as a left-to-right journey, where each task is a point in a
-progression and its score controls vertical placement.
-
-That difference is not a small styling mismatch. It changes the user's first
-read of the diagram:
-
-- Agentic Mermaid reads as a structured checklist grouped by section.
-- Mermaid Journey reads as an experience curve over time.
-
-## Mermaid Journey Visual Model
-
-Mermaid's native Journey renderer treats tasks as ordered points in a horizontal
-progression:
-
-- tasks are laid out left to right in source order,
-- sections span horizontal ranges across consecutive task columns,
-- actor names appear in a legend at the left,
-- actor participation on a task is shown with small colored dots,
-- each score maps to a vertical position,
-- each scored point is represented by a face icon,
-- a horizontal baseline or arrow reinforces forward progression.
-
-Journey-specific Mermaid config includes controls for task spacing, task font,
-actor colors, section fills, section colors, title color, left margin, and actor
-label wrapping. The implemented renderer maps those fields onto the Mermaid-like
-Journey metaphor while leaving sequence-era fields that do not apply to Journey
-geometry as accepted compatibility metadata.
-
-## Agentic Mermaid Visual Model
-
-The previous Agentic Mermaid Journey renderer was documented in
-`docs/design/families/journey.md` and implemented by:
-
-- `src/journey/layout.ts`
-- `src/journey/renderer.ts`
-- `src/ascii/journey.ts`
-
-It intentionally used Agentic Mermaid's house style:
-
-- sections are side-by-side columns,
-- tasks stack vertically inside each section,
-- each task is a card,
-- scores are shown as local five-cell meters,
-- actors are shown as local text pills,
-- section containers use crisp frames and header bands.
-
-That model was useful for compact, scannable documents, but it was not visually
-compatible with Mermaid Journey examples found in the wild.
-
-## Visual Parity Strategy
-
-Adopt Mermaid's Journey visual metaphor as the default public SVG renderer.
-
-Prototype and visual evidence:
-
-- [`journey-agentic-cards-before.png`](./journey-agentic-cards-before.png)
-- [`journey-mermaid-classic-prototype.svg`](./journey-mermaid-classic-prototype.svg)
-- [`journey-mermaid-classic-prototype.png`](./journey-mermaid-classic-prototype.png)
-- [`journey-mermaid-classic-implementation.png`](./journey-mermaid-classic-implementation.png)
-
-The old card layout has been removed from the public SVG renderer. If it ever
-returns, it should be an explicitly named alternate look rather than the default.
-The public default should remain Mermaid-compatible.
-
-Possible type if the alternate survives:
-
-```ts
-type JourneyLook = "mermaid-classic" | "agentic-cards";
-```
-
-Default:
-
-- Use `"mermaid-classic"`.
-
-There is currently no public alternate card layout. If one survives later, its
-setting should live near other render style options rather than in the parser:
-
-```ts
-render(source, {
-  journey: {
-    look: "agentic-cards"
-  }
-});
-```
-
-If the public API already has a stronger convention for family-specific render
-options, use that convention instead.
-
-## Mermaid-classic Acceptance Criteria
-
-The `"mermaid-classic"` Journey layout must:
-
-- place tasks in one left-to-right sequence using source order,
-- calculate section spans from the number of tasks in each section,
-- draw a left actor legend with stable actor colors,
-- wrap long actor labels within a configured maximum label width,
-- mark per-task actor participation with small colored dots,
-- map score 5 to the highest positive position and score 1 to the lowest,
-- render a neutral middle position for score 3,
-- show score state with face icons or an equivalent unmistakable sentiment mark,
-- draw a horizontal progression baseline or arrow,
-- keep visible title and accessibility metadata behavior unchanged,
-- support theme colors without hardcoded contrast regressions,
-- avoid clipping long task labels, actor labels, and section names.
-
-The implementation reuses the existing `JourneyDiagram` model. It does not
-introduce a second syntax model.
-
-## Parser and Model Spec
-
-### JourneyBody
-
-`JourneyBody` represents the supported Journey syntax consumed by the renderer:
-
-- visible title,
-- ordered sections,
-- ordered tasks,
-- score per task,
-- actors per task,
-- accessibility title,
-- accessibility description,
-- source locations when available through the shared source map.
-
-Accessibility metadata also appears in shared diagram metadata, but its presence
-does not force `JourneyBody` to become opaque.
-
-### Shared normalization
-
-Renderer and agent parsing share normalization behavior for:
-
-- quoted labels,
-- escaped quotes,
-- `<br>` and `<br/>`,
-- comments,
-- frontmatter and init directives before the `journey` header.
-
-The same source text should not produce different task labels depending on which
-surface parsed it.
-
-### Diagnostics
-
-Journey diagnostics should distinguish at least:
-
-- invalid score range,
-- malformed task line,
-- actor list parse failure,
-- unsupported but preserved Journey line,
-- parser drift between renderer and structured parser.
-
-Opaque fallback is still allowed for source preservation, but it should include
-the reason that triggered opacity.
-
-## Describe, Facts, and Verify Spec
-
-`describe(..., { format: "json" })` should expose a Journey body with:
-
-- diagram kind,
-- visible title,
-- accessibility title and description when present,
-- sections in source order,
-- tasks in source order,
-- task score,
-- task actors,
-- implicit section state for unsectioned tasks.
-
-Text facts should include:
-
-- section count,
-- task count,
-- actor count,
-- score range,
-- average score,
-- lowest-scoring tasks,
-- highest-scoring tasks,
-- actor participation counts,
-- accessibility title/description presence.
-
-`verify` should report Journey-specific diagnostics instead of only generic
-opaque warnings when the source is close enough to classify.
-
-## ASCII Spec
-
-Journey ASCII output should remain readable in plain terminals, but it should
-honor width constraints:
-
-- wrap task labels,
-- wrap actor labels,
-- keep score markers adjacent to the task they describe,
-- preserve section order,
-- avoid lines longer than `maxWidth` when a width is provided and feasible.
-
-A Mermaid-classic ASCII mode is optional. The priority is making current ASCII
-output truthful to the structured model and width contract.
-
-## Follow-up Implementation Plan
-
-1. Introduce a shared Journey parse core or shared normalization helpers so
-   `src/journey/parser.ts` and `src/agent/journey-body.ts` cannot drift on
-   documented syntax.
-2. Extend `JourneyBody` and related JSON serializers for accessibility metadata
-   and full section/task ordering.
-3. Replace Journey opaque fallback with typed parse outcomes that carry a reason.
-4. Update `verify` to map Journey parse outcomes to specific diagnostics.
-5. Expand Journey facts and describe output.
-6. Add richer Journey facts and JSON describe summaries.
-7. Keep migration fixtures based on representative Mermaid Journey examples.
-8. Decide separately whether the old card layout is worth reintroducing as a
-   deliberately named alternate look.
-
-## Test Plan
-
-Add fixtures covering:
-
-- `accTitle: ...`
-- `accDescr: ...`
-- multiline `accDescr { ... }`
-- quoted title, section, task, and actor labels,
-- `<br>` in title, section, task, actor, and accessibility text,
-- score values 1 through 5,
-- invalid scores 0, 6, and non-numeric scores,
-- tasks before the first explicit section,
-- long task labels,
-- long actor labels,
-- multiple actors per task,
-- repeated actors across sections.
-
-For each valid fixture, test:
-
-- renderer parser output,
-- agent structured body output,
-- `describe` JSON,
-- facts text,
-- `verify` result,
-- SVG accessibility metadata,
-- ASCII output under a narrow `maxWidth`.
-
-For the public Journey renderer, add SVG structure tests that assert:
-
-- tasks advance horizontally,
-- section spans cover the expected task columns,
-- actor legend is present,
-- actor dots are associated with the right tasks,
-- score positions are monotonic from 1 through 5.
-
-## Migration Decision
-
-The current Journey renderer should be treated as a supported Agentic Mermaid
-prototype that proved parser and renderer coverage, not as a public compatibility
-contract. The failure was that the implementation made Journey exist by adopting
-the library's card-layout house style instead of preserving Mermaid's Journey
-visual metaphor.
-
-The immediate fix for issue #128 should prioritize parser parity and diagnostics.
-Pre-launch, the visual fix should replace the default SVG layout with the
-Mermaid-style experience curve. The old card layout should be removed from the
-public renderer unless we later decide to reintroduce it as a deliberately named
-alternate look.