README: collapse the generated tables, merge the three honesty sections

From ChatGPT's README handoff, which wants 750–900 visible words. The README is 3,391 today; main was 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:

Both generated blocks into <details>. Nothing deleted; visible length drops.
Merge Current limitations + When not to use this + What the checks guarantee, and what they do not — three sections of one honesty move.
Greeting is walked twice, in the quickstart and the five stages. Keep one.

Lands around 1,800 visible — main's length, now carrying the thesis, the glossary links and both tables.

⚠️ Standing rule: diff every REMOVED line against origin/main and 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_api forbids those). Two survived — the ~15 lines claim at README.md:61, and preserving the generated blocks.

Repo name: recommend keeping `workflow-workbench`

pydantic-graph-spec is discoverable (pydantic-settings/pydantic-evals set the convention) but the pydantic-* 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:

A declarative specification layer for Pydantic Graph.

README: the Pydantic Graph lineage, the learnings, and one stale tabl…

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.py imports GraphBuilder and builds through it; a pydantic_graph.Graph is what render() 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 is domain-language.md Should 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`, not `workflow-spec`

This issue recommended keeping workflow-workbench, and if renaming, implied workflow-spec. The corrected subtitle is what licenses the name, and workflow-spec says nothing about what the library wraps.


`graph-builder-spec`	matches the subtitle exactly. Reuses their noun — `domain-language.md` #1, before inventing a noun, look for one that exists. `-spec` matches `GraphSpec` / `StepSpec` / `StrategySpec`, the vocabulary a reader meets in the first code block. No namespace squat.
`workflow-spec`	keeps a word the code uses, says nothing about what it wraps
`graph-spec`	collides with graph DBs and GraphQL
`pydantic-graph-spec`, `pydantic-graph-builder-spec`	squat the `pydantic-*` namespace, which belongs to Pydantic's own packages

Its one weakness — bare graph-builder-spec does not say whose builder — is what the subtitle under it is for.

Timing is unchanged

Measured cost: 147 workflow_workbench references, 26 workflow-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.

A declaration layer over Pydantic Graph Builder — the subtitle, corre…

✅ 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 name

Both 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 next uv sync fails the moment the rename is on main,
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 each

uv.lock is deliberately untouched in both downstream PRs: the new URL does not resolve until
step 2, and uv re-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_workbench`	148 refs / 55 files
`workflow-workbench`	34 refs / 16 files
directory renames	the package, `frontend/workflow-workbench/`, and two built artifacts under `static/`
`WORKFLOW_WORKBENCH_TOKEN` / `_STORE`	⚠️ never mentioned anywhere until now

That 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_TOKEN is simply unset under the new name, and serve() raises SystemExit
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's docs/handoff-*.md and docs/issues-snapshot.md — point-in-time by
construction. One consequence recorded rather than hidden: issues-snapshot.md:392 now 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.

Rename to graph-builder-spec (#15)

Rename to graph-builder-spec (#15) (#23)

⛔ 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 repos
collapse 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 against origin/main and read it. Doing that on 2026-10-01 found two real losses a reread
had missed.

Navigation Menu

Repository navigation

README: collapse the generated tables, merge the three honesty sections #15

Structural, not a word target

Most of handoff #2's correction list targets claims that are not there

Repo name: recommend keeping `workflow-workbench`

Correction to this issue's naming recommendation

And the recommended name changes with it: `graph-builder-spec`, not `workflow-spec`

Timing is unchanged

✅ DECIDED — `graph-builder-spec`. Boris, 2026-10-06.

Open PRs, and the order matters

Measured surface, since the figures in the body were low

What is NOT renamed, on purpose

⛔ Reopened — #23 closed this issue and only did a third of it

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

README: collapse the generated tables, merge the three honesty sections #15

Description

Structural, not a word target

Most of handoff #2's correction list targets claims that are not there

Repo name: recommend keeping workflow-workbench

Activity

borisdev commented on Oct 6, 2026

Correction to this issue's naming recommendation

And the recommended name changes with it: graph-builder-spec, not workflow-spec

Timing is unchanged

borisdev commented on Oct 6, 2026

✅ DECIDED — graph-builder-spec. Boris, 2026-10-06.

Open PRs, and the order matters

Measured surface, since the figures in the body were low

What is NOT renamed, on purpose

borisdev commented on Oct 7, 2026

⛔ Reopened — #23 closed this issue and only did a third of it

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Repo name: recommend keeping `workflow-workbench`

And the recommended name changes with it: `graph-builder-spec`, not `workflow-spec`

✅ DECIDED — `graph-builder-spec`. Boris, 2026-10-06.