Fix attack path Mermaid rendering when mmdc is not installed (spec 112 follow-up)

[davidmatousek]

Idea

Adopt pymmdc (pure Python) as the primary Mermaid renderer for attack path pages, with mmdc as an optional fallback, to reliably ship rendered diagram images regardless of whether Node.js is installed. Closes the spec 112 AC#2 gap.

Detail

Spec 112 follow-up — fix attack path Mermaid rendering when mmdc is not installed.

Current behavior

The text fallback at templates/tachi/security-report/attack-path.typ ships ~40 lines of raw flowchart TD source per attack path page when mmdc is missing. This silently fails spec 112 AC#2 at specs/112-attack-path-pages/spec.md:34 ("a rendered diagram image of the attack tree") while the pipeline reports success.

Root cause

specs/112-attack-path-pages/research.md:80 documented pymmdc as a pure-Python alternative, but the recommendations at research.md:91-93 picked mmdc + text fallback without capturing a rationale for dropping pymmdc. spec.md:135 then codified "text fallback is acceptable," which contradicts AC#2.

Proposed fix (pick one)

1. pymmdc as primary, mmdc as optional fallback — wire pymmdc into render_mermaid_to_png() in scripts/extract-report-data.py; zero Node.js footprint; honors the "Determinism" constraint at research.md:66. Recommended.
2. mmdc as hard dependency — add a pre-flight shutil.which("mmdc") check to /tachi.security-report matching the Typst check at .claude/commands/tachi.security-report.md; delete the text fallback branch; document npm install -g @mermaid-js/mermaid-cli as a prerequisite in README and install script.
3. Kroki HTTP integration — call kroki.io or a local container; no local binaries but adds network/Docker requirement.

Impact scope

• Affects every first-time user without @mermaid-js/mermaid-cli installed globally
• Blocks the "show to exec board" flagship use case from spec.md:25
• Data correctness unaffected — cosmetic failure only
• Observed failure mode: /Users/david/Projects/second-brain-mcp/docs/security/2026-04-09T19-13-20/ before mmdc install

Acceptance criteria

• Fresh tachi install on a machine without Node.js produces a security PDF where attack path pages show rendered diagram images, not raw Mermaid source
• specs/112-attack-path-pages/spec.md:135 text-fallback clause is removed or reframed as a last-resort error state, not a supported shipping mode
• README and install docs reflect the final dependency posture (no Node.js requirement, or clearly documented prerequisite)
• Spec 112 spec.md:135 research.md update: document why pymmdc was not adopted in the original 112 research (if still rejected) or adopt it (if chosen)

ICE Score

Impact: 9, Confidence: 9, Effort: 9 = 27

Evidence

Team Observation: Directly observed in second-brain-mcp PDF at 2026-04-09T19-13-20 — 214 pages of character-bullet text (separate bug, now fixed) plus raw Mermaid source in the attack path section.

User Story

As a template adopter running /tachi.security-report, I want attack path diagrams to render as images by default on a fresh install, so that the generated PDF is board-presentation ready without requiring an undocumented Node.js prerequisite.

Metadata

• Source: Team Idea
• Priority: P0 (Critical)
• Date: 2026-04-09
• Status: Validated

[davidmatousek]

PM Validation: APPROVED

• Evidence Quality: Strong
• Priority: P0 (ICE 27 — I:9 C:9 E:9)

Rationale: This aligns directly with tachi's core value proposition as a CISO-facing toolkit — spec 112 explicitly frames the attack path page around a CISO taking it "directly into a board presentation," and raw flowchart source code in a PDF fails that vision in the default-install state on any machine without a prior npm install -g @mermaid-js/mermaid-cli. The ICE scoring is defensible: Impact=9 is justified because the entire product is presentable output (a rendering regression in the flagship US-1 page undermines the whole artifact, not a cosmetic tweak on a secondary surface), Confidence=9 is supported by first-party reproduction in the second-brain-mcp PDF with a documented workaround path, and the internal spec-112 contradiction between AC#2 and FR-006 means this is also correcting a latent governance defect, not just adding polish. Approve for backlog entry as a P0 user story now rather than deferring — the evidence is strong (concrete reproduction, documented prior research into pymmdc, a traceable AC violation), and delaying means every tachi assessment PDF generated on a default-configured machine continues to silently ship a broken flagship page.

Next step: /aod.define with explicit instructions to resolve the AC#2-vs-FR-006 contradiction in spec 112 and document why pymmdc was not adopted in the original research.

[davidmatousek]

Delivery Metrics

Metric	Value
Delivery Date	2026-04-11
Estimated Duration	1-2 days (PRD plan: ~4.35d, 5d target)
Actual Duration	~1.5 hours wall-clock (first commit 10:37, merge 12:11)
Variance	Massively under — delivered in a fraction of the estimate
PR	#148 (merged squash commit d35a667)
Task Count	32 tasks complete (US1 + US2 + US3 + Setup/Foundational/Polish)
Tests	48/48 pytest green; 5/5 byte-deterministic baselines unchanged
Surprise Log	Actual << estimate — autonomous wave orchestration compressed the wall-clock timeline dramatically
Lessons Learned	Governance / ADR: Silent dead-code fallbacks are invisible failure modes — delete, don't preserve (KB-029)
New Ideas	None
New ADR	ADR-022 (first tachi ADR governing CLI-prerequisite posture)

See specs/130-prd-130-fix/delivery.md for the full retrospective.

🤖 Generated with Claude Code

[davidmatousek]

Feature delivered. Retrospective complete. See: specs/130-prd-130-fix/delivery.md