Both reference tables in the README, generated from the package's own docstrings

[borisdev]

Stacked on #5 — base is coherence-finding, because these tables name coherence_check() and that branch is where the rename lands. Merge #5 first.

The README said what the library is for and never what it checks. A reader could not tell whether coherence_check() was three trivial rules or eleven real ones — and the data language, the whole reason the design is inspectable at all, was never written down anywhere.

Two generated tables, in the README

the data language	every word you declare a design with, grouped into values / boxes / wires / endpoints / the design
well-formedness	every rule coherence_check() enforces, split by whether it needs a strategy

python3 -m workflow_workbench.reference --write
python3 -m workflow_workbench.reference --check

No description is authored. Every cell is the first line of the thing's own docstring — or, for the two unions, which have no docstring of their own, the names of their members. A table cannot claim what the code does not say.

What is authored is the grouping: which word sits under "boxes" and which under "wires". That's curation, it's source, and there's a test asserting GROUPS carries names only — so the table can never become half source and half derived.

The README opening now names the failure, not the audience

Your framing: an agent left to run free produces work that runs and is incoherent — each piece locally fine, the whole not adding up. That's a reason to care. "For developing workflows with an AI coding agent" only said who it was for.

Four problems, one declaration answering all four: incoherence, strategies that can only be compared rather than asserted, reuse, and visibility.

⚠️ The visualization claim is narrowed to what's true

pydantic-graph does emit mermaid — build_mermaid_graph in graph_builder.py — so "they have none" would have been false. Measured: it isn't exported from their __init__, and it takes a built graph's internals, so every implementation must exist first. Two honest differences, not a feature list: ours reads the declaration, and ours can draw two strategies at once.

Fixed at source, not worked around

• _Start's first docstring line ended mid-sentence on "so mypy can narrow a"; _End's was "See _Start." Both are standalone sentences now, because the table lifts that line verbatim. A test makes a wrapping summary a failure rather than a fragment in the README.
• The union rows needed their pipes escaped — a bare | is a column separator, so StepSpec | JoinSpec | DecisionSpec rendered as three empty cells. Invisible in the source string; the test asserts the rendered row.
• The generated prose said NodeSpec(...) is a TypeError, which test_the_docs_use_the_current_api greps for. Reworded at source rather than exempting the README — that lint exists because the README's own example once stopped running and nothing said so, and the README is the last file that should be exempt. It caught me twice in this change, both times correctly.

docs/well-formedness.md is deleted — the tables live in the README now, and two homes for one generated table is exactly the duplication this repo keeps drift tests to avoid.

Mutation-tested

Six ways this can rot, introduced one at a time, each went red:

mutation	caught by
hand-edit a README table row	the --check drift test
a docstring changes, nobody regenerates	same
a new export left out of the table	the completeness guard
a stale exclusion naming something no longer exported	the exclusion-existence test
GROUPS grows a hand-written description	the source/derived test
the unions lose pipe escaping	the rendered-row test

245 tests pass. parity --check and reference --check both green.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

The inventory omits an enforced recursion rule, and the documentation describes a nonexistent structured finding API.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Include recursive subgraph binding checks in the inventory · New
• Document GraphSpec.check()'s actual string-based API · New

What changed in this PR

Adds generated documentation for the well-formedness checks enforced by check().

Changes:

• Adds a rules documentation generator and drift checks.
• Adds generated README and detailed documentation sections.
• Adds tests for completeness, grouping, and generated counts.

File	Description
workflow_workbench/​rules.py	Generates rule documentation from check metadata.
tests/​test_rules.py	Tests generation and rule discovery.
README.md	Adds a generated rules summary.
docs/​well-formedness.md	Documents checks and findings.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

The rules table omits recursive-subgraph cycle detection enforced by coherence_check().

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Generated rules omit the recursive-subgraph coherence check · New
• Include recursive subgraph binding checks in the inventory
• Document GraphSpec.check()'s actual string-based API

[borisdev]

Contained in #8, merged as a merge commit — all eight commits are in main's history, so this branch's review record stands and nothing is lost. Closing rather than merging to avoid three successive squash-divergence resolutions.