Skip to content

fix(patterns) redraw ten more ASCII diagrams under 78 columns - #434

Merged
mjmirza merged 3 commits into
mainfrom
fix/diagram-width-batch-11
Aug 24, 2026
Merged

mjmirza merged 3 commits into
mainfrom
fix/diagram-width-batch-11

Conversation

@mjmirza

@mjmirza mjmirza commented Aug 24, 2026

Copy link
Copy Markdown
Owner

Summary

  • Redraws ten more ASCII diagrams that exceeded 78 characters wide,
    the next tier at 80 to 81 characters, down to 51 to 60 characters.
  • medallion-architecture.md, stub.md, token-binding-and-dpop.md,
    profunctor.md, hierarchical-agents.md, error-budget.md,
    observer.md, dead-code.md, large-class.md,
    pipeline-architecture.md.
  • No structural, prose, reference, or code content changed. Only the
    diagram fences.
  • tools/gen-indexes.py was re-run before this commit, regenerating the
    nine family index tables these entries span.

Notable redesigns

  • medallion-architecture.md's bronze, silver, gold layer chain is now
    a straight vertical pipeline, with the catalog and lineage store
    cross-link (it both feeds Gold and is populated from Silver) stated
    in prose rather than drawn as a diagonal arrow.
  • large-class.md's Extract Class before-and-after example keeps all
    four responsibility clusters (pricing, fulfillment, notification,
    audit) and the four delegate classes the Order class ends up using.
  • dead-code.md's reachability graph section names every live call path
    from every entry point, and the guard-gated branch section keeps the
    distinction between structurally reachable and practically dead.

Test plan

  • check-structure.py, 884 of 884 entries pass
  • check-prose.py, 925 of 925 entries pass
  • markdownlint-cli2 0.23.2, 0 issues on the ten changed files
  • validate-refs.py --strict, every citation resolves
  • check-code.py --strict, 2826 compiled, 0 failed, 0 skipped
  • gen-indexes.py re-run, nine family README tables regenerated
    and committed alongside the content changes
  • git diff --stat -- docs and dist and the root README.md, all
    empty, no unexpected top level changes
  • a stray .ref-cache.json diff from the live citation probe was
    reverted before staging

27 more entries with the same width issue remain, to be worked through
in following batches.

Continues the diagram-width review pass. This batch covers the next
tier of offenders, 80 to 81 characters wide, redrawn as narrower
vertical layouts.

- medallion-architecture.md, 81 to 57 characters
- stub.md, 81 to 57 characters
- token-binding-and-dpop.md, 81 to 51 characters
- profunctor.md, 81 to 52 characters
- hierarchical-agents.md, 81 to 51 characters
- error-budget.md, 81 to 52 characters
- observer.md, 80 to 55 characters
- dead-code.md, 80 to 60 characters
- large-class.md, 80 to 51 characters
- pipeline-architecture.md, 80 to 53 characters

No structural, prose, reference, or code content changed, only the
diagram fences. Every redrawn diagram preserves every field, every
prose annotation, and every before/after framing from the original,
only the visual layout narrowed. medallion-architecture.md's bronze,
silver, gold layer chain plus the catalog and lineage store cross-link
is preserved. large-class.md's before-and-after Extract Class example,
all four responsibility clusters and their delegate classes, is
preserved. dead-code.md's reachability graph and guard-gated branch
sections both stay intact.

tools/gen-indexes.py was re-run before this commit, regenerating
the family index tables these ten entries span. A stray diff in
.ref-cache.json from validate-refs.py's live citation probe was
reverted before staging, keeping this diff scoped to content only.

check-structure.py 884/884, check-prose.py 925/925, markdownlint-cli2
0 issues, validate-refs.py --strict all citations resolve,
check-code.py --strict all code blocks still compile.

27 more entries with the same width issue remain, to be worked
through in following batches.
@mjmirza mjmirza added the enhancement New feature or request label Aug 24, 2026
@mjmirza

mjmirza commented Aug 24, 2026

Copy link
Copy Markdown
Owner Author

REVIEWED. Multi-pass review. This branch initially showed
mergeStateStatus CONFLICTING because it was created off main before
the prior batch's PR (#433) had merged, and both batches touch two
overlapping family folders, 05-architectural and 16-functional.
Resolved by merging origin/main into this branch, taking main's
version of the one file that had a real text conflict
(05-architectural/README.md; 16-functional/README.md auto-merged
cleanly), then re-running tools/gen-indexes.py so both batches' byte
counts are correctly reflected, then pushing. GitHub now reports
mergeStateStatus CLEAN, mergeable MERGEABLE, and the file list is
exactly the 19 files this batch actually touches, 10 content files
plus 9 family README tables.

Pass 1, content-only diff read. Confirmed every changed line sits
inside a diagram fence or a regenerated family index table row.

Pass 2, each of the ten diagrams read start to end against its source
of truth section. Confirmed every field, box, arrow, and prose
annotation from the original wide diagram survives in the narrower
one. medallion-architecture.md's bronze, silver, gold layer chain and
the catalog/lineage cross-link are preserved. large-class.md's four
responsibility clusters and their four delegate classes are intact.
dead-code.md's reachability graph and guard-gated branch sections
both stay intact.

Pass 3, gate output read directly. check-structure.py 884 of 884,
check-prose.py 925 of 925, markdownlint-cli2 zero issues,
validate-refs.py --strict all citations resolve, check-code.py
--strict 2826 compiled 0 failed. All ten new diagram widths verified
under 78 characters, range 51 to 60. CI's own checks are all pass
after the merge-fix push.

Approved.

@mjmirza
mjmirza merged commit a3ac3fe into main Aug 24, 2026
12 checks passed
@mjmirza
mjmirza deleted the fix/diagram-width-batch-11 branch August 24, 2026 01:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant