Repository navigation
README: collapse the generated tables, merge the three honesty sections #15
Description
Activity
- added a commit that references this issue
on Oct 6, 2026 Correction to this issue's naming recommendation
The subtitle this issue proposed had two errors, both caught by Boris:
WRONG A declarative specification layer for Pydantic Graph RIGHT A declaration layer over Pydantic Graph Builder- "Pydantic Graph" → "Pydantic Graph Builder".
graph_spec.pyimportsGraphBuilderand builds through it; apydantic_graph.Graphis whatrender()returns. The subtitle named the output, not the thing wrapped. - "declarative specification layer" → "declaration layer". The glossary defines
Declaration layer. A second phrase for a defined word isdomain-language.mdShould EdgeSpec take a list of path items, like their Path? #2.
Shipped in #19, with a test pinning both corrections.
And the recommended name changes with it:
graph-builder-spec, notworkflow-specThis issue recommended keeping
workflow-workbench, and if renaming, impliedworkflow-spec. The corrected subtitle is what licenses the name, andworkflow-specsays nothing about what the library wraps.graph-builder-specmatches the subtitle exactly. Reuses their noun — domain-language.md#1, before inventing a noun, look for one that exists.-specmatchesGraphSpec/StepSpec/StrategySpec, the vocabulary a reader meets in the first code block. No namespace squat.workflow-speckeeps a word the code uses, says nothing about what it wraps graph-speccollides with graph DBs and GraphQL pydantic-graph-spec,pydantic-graph-builder-specsquat the pydantic-*namespace, which belongs to Pydantic's own packagesIts one weakness — bare
graph-builder-specdoes not say whose builder — is what the subtitle under it is for.Timing is unchanged
Measured cost: 147
workflow_workbenchreferences, 26workflow-workbench, 2 downstream repos pinning a sha, plus the generated tables that lift docstrings so the README moves too.The name is not the bottleneck; the flagship example (#17) is. A perfect name on a repo whose examples trim whitespace converts nobody. Proposing, not deciding —
domain-language.md#3.- "Pydantic Graph" → "Pydantic Graph Builder".
- added a commit that references this issue
on Oct 6, 2026 ✅ DECIDED —
graph-builder-spec. Boris, 2026-10-06."graph-builder-spec, on the grounds that #19's corrected subtitle — 'A declaration layer over
Pydantic Graph Builder' — is what licenses it, and that graph-builder-spec reuses Pydantic's own
noun rather than inventing one."⛔ This issue's BODY says "recommend keeping
workflow-workbench" and is now superseded. The
body and the comment above it have contradicted each other since 20:56 today, and that is how a
handoff came to report the rename as already decided when nothing had been. Read the body's name
section as history.Open PRs, and the order matters
borisdev/workflow-workbench #23 the rename itself. Stacked on #22 -> #20. borisdev/nobsmed-v2 #1021 28 files + the dependency name borisdev/ai_computer_use #17 3 files + the dependency nameBoth downstream repos track
main, not a sha — the recorded "2 downstream repos pinning a
sha" was wrong. GitHub redirects the old clone URL, so the git URL survives; the old
distribution name does not. So their nextuv syncfails the moment the rename is onmain,
which is why all three PRs exist together.1. merge #20, #22, #23 2. gh repo rename graph-builder-spec <- yours, outward-facing 3. merge #1021 and #17, then `uv lock` in eachuv.lockis deliberately untouched in both downstream PRs: the new URL does not resolve until
step 2, anduvre-sorts the package block and re-resolves the git sha, so a hand-edited lock is
an artifact nobody has validated.Measured surface, since the figures in the body were low
workflow_workbench148 refs / 55 files workflow-workbench34 refs / 16 files directory renames the package, frontend/workflow-workbench/, and two built artifacts understatic/WORKFLOW_WORKBENCH_TOKEN/_STORE⚠️ never mentioned anywhere until nowThat last row is the one worth keeping: my own rename script replaced three casings and not
SCREAMING_CASE, so the server's two env vars survived it. Found by a case-INSENSITIVE grep, which
is the check that should have been written first — the same narrower than its claim shape as
every Copilot finding on #8, #18, #19 and #22.Verified rather than assumed that the env-var rename fails closed: a stale
WORKFLOW_WORKBENCH_TOKENis simply unset under the new name, andserve()raisesSystemExit
rather than binding a non-localhost host unauthenticated. The process refuses to start. That is
what makes an alias unnecessary.What is NOT renamed, on purpose
- CHANGELOG entries for shipped releases. Those releases really were published as
workflow-workbench. The new entry states the mapping so a reader further down knows why. nobsmed-v2'sdocs/handoff-*.mdanddocs/issues-snapshot.md— point-in-time by
construction. One consequence recorded rather than hidden:issues-snapshot.md:392now names a
doc filename that moved.
The rest of this issue — collapsing the generated tables and merging the three honesty sections —
is untouched and still open.- CHANGELOG entries for shipped releases. Those releases really were published as
- added 2 commits that reference this issue
on Oct 7, 2026 ⛔ Reopened — #23 closed this issue and only did a third of it
My PR body said "Closes #15's naming question", and GitHub's keyword took the whole issue with
it. The naming decision is done and shipped. The work this issue is actually titled after is
not:repo name✅ DONE — graph-builder-spec, merged in #23, renamed across 3 reposcollapse both generated blocks into <details>⬜ untouched merge Current limitations+When not to use this+What the checks guarantee, and what they do not⬜ untouched greeting is walked twice (quickstart and the five stages) — keep one ⬜ untouched I even wrote "The rest of this issue … is untouched and still open" in a comment here, and then
closed it anyway with a keyword in a different repo's PR. Recording that rather than quietly
reopening, because it is the same shape as everything else this repo keeps catching: the claim
("closes #15") was broader than the thing done.⚠️ One of the three items is now partly stale and needs re-measuring before acting. The README
grew during the rename — the rules table went from 12 to 13 entries and the CHANGELOG gained a
breaking-rename section — so the "lands around 1,800 visible words" estimate in the body is
from before that. Re-count rather than trusting it.⚠️ The standing rule in the body still applies and is the important half: diff every REMOVED
line againstorigin/mainand read it. Doing that on 2026-10-01 found two real losses a reread
had missed.
From ChatGPT's README handoff, which wants 750–900 visible words. The README is 3,391 today;
mainwas 1,766.⛔ That target is wrong, and precisely why: it counted two generated tables as prose. The rules table and the data-language table are ~70 lines with a drift test, and #6 existed because a reader could not tell whether
coherence_check()was 3 trivial rules or 12 real ones. That is reference material, not bloat — and cutting to 900 words deletes it.Structural, not a word target
The drift test matches on the markers, so it does not care:
<details>. Nothing deleted; visible length drops.Current limitations+When not to use this+What the checks guarantee, and what they do not— three sections of one honesty move.Lands around 1,800 visible —
main's length, now carrying the thesis, the glossary links and both tables.origin/mainand read it. Doing that on 2026-10-01 found two real losses a reread had missed.Most of handoff #2's correction list targets claims that are not there
Verified absent from every current README: eval_battle auto-replicates, "a diff diagram proves causal attribution", "all reasoning can only be compared", old
NodeSpec(...)examples (test_the_docs_use_the_current_apiforbids those). Two survived — the~15 linesclaim atREADME.md:61, and preserving the generated blocks.Repo name: recommend keeping
workflow-workbenchpydantic-graph-specis discoverable (pydantic-settings/pydantic-evalsset the convention) but thepydantic-*prefix is not ours to take — those are Pydantic's own, and being asked to rename later is strictly worse than renaming now. It also welds the name to one executor.The name is not the bottleneck; the flagship example is (#14). Free discoverability instead, one line in the README and the PyPI description: