feat(docs): draw the wiring lane and the honesty lane - #5
Merged
Conversation
plexus computes a wiring graph, plans a pipeline over it, and reports what does not connect. The README explains all three in text, and one of them, the honesty surface, is the part hardest to picture from prose: unmet inputs, unconsumed outputs, feedback loops, and colliding organ ids are four different absences and they read as a list rather than as one comparison. Two diagrams and a repository mark, rendered from docs/art/plexus.art.json by a script. The picture is a pure function of a spec that diffs, and a gate re-renders and compares bytes, so a stage name edited without a re-render fails the suite instead of shipping a drawing of a version that no longer exists. The stage labels come from src/plexus/mesh.py, plan.py, and receipt.py rather than from the README, which surfaced two mechanisms the front page did not state. verify_plan rebuilds the receipt from the plan it just re-derived rather than from the saved body, so editing that body cannot make a plan agree with itself. And the receipt's method version has to match before anything else is compared, so a plan written by an older plexus fails rather than being re-interpreted under new rules. Both are now in the text. .gitattributes pins docs/art to LF, because the gate compares committed bytes to a fresh render and per-platform normalization would make that comparison depend on who checked the repository out. tests/test_repo_art.py runs the gate under pytest and asserts on its receipt, including one test that feeds the outcome-box check a note too wide for its box, so a green suite means the gate can still fail. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this adds
Two diagrams and a repository mark on the plexus front page, rendered from a spec
rather than drawn by hand.
docs/art/wiring-lane.svgdocs/art/honesty-lane.svgdocs/art/plexus-header.svgThe honesty surface is the part hardest to picture from prose. Unmet inputs,
unconsumed outputs, feedback loops, and colliding organ ids read as four separate
bullet points, when they are four ways one comparison comes out.
The picture is derived, and a gate says so
docs/art/plexus.art.jsonis the source.tools/render_repo_art.pyrenders it;tools/check_repo_art.pyre-renders and compares bytes. Twelve gates run,covering determinism, per-repository identity, wrapper truncation, return-edge
geometry, outcome-box fit, tagline width, no local paths or em-dashes, and every
committed illustration actually being shown somewhere.
tests/test_repo_art.pyruns that gate under pytest and asserts on its receipt,so
python -m pytest -qcovers the front page with no CI change. One of thethree tests feeds the outcome-box check a note too wide for its box and requires
a complaint, so a green suite means the gate can still fail.
Two mechanisms moved from the source into the text
Stage labels were written from
src/plexus/mesh.py,plan.py, andreceipt.pyrather than from the README, which surfaced two things the code does and the front
page did not say:
verify_planrebuilds the receipt from the plan it just re-derived, not fromthe body saved in the file, so editing that body cannot make a plan agree with
itself.
method_versionhas to match before anything else is compared, soa plan written by an older plexus is reported as failing rather than silently
re-interpreted under new rules.
Line endings
.gitattributespinsdocs/art/*to LF. The gate compares committed bytesagainst a fresh render, so per-platform normalization would make the comparison
depend on who checked the repository out.
Honest nulls
tools/are a copy of the same files in thesibling repositories, now the eleventh. That is real duplication and a real
maintenance cost, taken deliberately so each repository stays dependency-free
and can render its own artwork from a fresh clone with nothing installed.
.github/assets/zentropy-banner.pngis no longer referenced byanything. It is left in place rather than deleted, in case something outside
this repository links to it.
that every edge is self-reported by its producer and that plexus does not import,
resolve, or run the source a manifest cites.
python examples/tour.pyexits 0.will fall back to system fonts, which is inference rather than a look.
🤖 Generated with Claude Code