Skip to content

feat(diagrams): verified story diagrams as the default architecture/flow graphics (ADR-0014) - #29

Merged
stuinfla merged 1 commit into
mainfrom
feat/story-diagrams
Oct 10, 2026
Merged

stuinfla merged 1 commit into
mainfrom
feat/story-diagrams

Conversation

@stuinfla

Copy link
Copy Markdown
Owner

What

Makes the owner-approved "story" graphics the default for the architecture and flow slots (ADR-0014), instead of the dependency-graph layout and the five-box vertical list.

  • visuals.systemMap → architecture slot: inputs → engine → surfaces (with real commands) + a WORKS WITH strip + RUNS ON.
  • visuals.decision → flow slot: candidates as gauges against a threshold, one skipped, one picked, animated handoff.

The rule that makes it safe

The brain does not get to assert any of it. make-diagrams verifies every claim against the cloned repo:

Claim Check
works with: yes / partial the verbatim quote must be in the named file
works with: no the tool greps the repo for the terms; kept only on zero matches
decision rule the rule.quote must be in rule.file

Unverifiable claims are dropped; if nothing survives, the slot keeps today's graph diagram (ADR-0011 — never fail a build for this).

Evidence

  • 23 new unit tests (tests/story-diagrams.test.mjs), including guards proven by mutation.
  • Full suite: 234 tests, 0 failing.
  • Real brain run on realiti4/claude-swap: the brain authored both models unprompted (including a Codex "no"); the tool confirmed the quotes and a zero-hit search; a fabricated claim injected in a separate run was dropped (quote not found in README.md).
  • Reference graphics (owner-signed-off) are expressed as data in tests/fixtures/story-claude-swap.mjs.

Known gaps (stated in the ADR)

  • Mobile legibility: ~1100px canvases; relies on the page's tap-to-zoom lightbox. A portrait layout is the follow-up.
  • Not measured on a corpus — two repos so far. The fallback keeps this safe; the gain is unproven until measured.
  • First tools/ → src/ import; the INV-23 mutation test now mirrors the real layout.

… walkthrough replace the vanilla architecture/flow slots (ADR-0014)
@netlify

netlify Bot commented Oct 10, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for explainmyrepo canceled.

Name Link
🔨 Latest commit 87ceb28
🔍 Latest deploy log https://app.netlify.com/projects/explainmyrepo/deploys/6acaa4fec1a92c000898275c

@stuinfla
stuinfla merged commit a64fd06 into main Oct 10, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant