[tannevaled]

Merges after ruby#819. The four new sections document modules that do not exist on rbgo's main yet, and the guard this PR adds says so precisely — which is the behaviour wanted, not a defect:

docs/scientific-stack.md:72:  ... will not run: uninitialized constant Special (NameError)
docs/scientific-stack.md:98:  ... will not run: uninitialized constant Stats (NameError)
docs/scientific-stack.md:118: ... will not run: uninitialized constant Integrate (NameError)
docs/scientific-stack.md:138: ... will not run: uninitialized constant Optimize (NameError)
11 example(s) with 25 claimed answer(s) over 13 file(s); 4 example(s) disagree

Against an rbgo built from #819's branch the same command reports 0 disagreements.

The page described two thirds of its subject

scientific-stack.md exists to describe the cgo-free numeric stack, and covered NDArray, FFT and Image. ruby#819 adds four more modules to that same stack, so the page gains a section for each, in the shape the existing ones use — what it binds, the surface, a short example — and index.md's summary and library list name them:

section	binds	surface
Special — scipy.special-style	go-numerics/special	all 67 functions, 66 Ruby names
Stats — scipy.stats-style	go-statistics/stats	32 univariate distributions, 19 methods each
Integrate — scipy.integrate-style	go-numerics/integrate	10 quadrature routines
Optimize — scipy.optimize-style	go-numerics/optimize	11 root finders and minimisers

The sections say why the names are scipy's and not transliterations of the Go ones: each module compares itself against scipy in ULPs and the pairing is a file in its repository, which is why Log1pExp is softplus and StudentT is t.

Every output in the new sections was produced by running it, not written from the definition.

Which is the point of tools/docexample

This site teaches by example, and an example carries its answer in a comment:

p Special.gamma(5.0)   # => 24.0

Nothing ran them. A binding renamed or a return shape changed upstream left every example here claiming its old output — which reads as a promise and is the first thing a reader tries. tools/conformancefigure already guards the one number this site states; this guards the outputs it states, and docs.yml runs it on every pull request.

What it judges. A ```ruby block is checked exactly when it claims an answer — when some line ends in # => …. That makes the selection self-evident instead of a list to maintain: the examples that read a photo off disk or start a server carry no # => and are left alone, and one that gains an answer is picked up without being registered anywhere.

How it compares. The block runs as one program, so earlier lines can set up later ones, and the lines it prints are compared in order with the answers it claims. A differing count is itself a failure: an example printing two lines while claiming one is as wrong as a wrong number, and the usual cause — p a, b printing twice — is exactly what nobody notices by reading. Only trailing whitespace is normalised, because authors align the comments; nothing else, because a digit's difference is the point.

It refuses rather than passes when it cannot judge. No interpreter is exit 2; finding nothing to check on a site full of examples is exit 3, because that means the extraction broke, not that the site is clean — the same refusal conformancefigure makes for an unreachable baseline.

Its extraction has a six-case self-test, which the workflow runs first: a pattern nobody tested is a guess, and a guess that matches nothing looks exactly like a clean site. The cases include the two that must not match — a comment that is not an answer (# exact, no 0.30000000000000004) and a non-Ruby fence — and one that must survive a # inside the value.

Measured

On the site as it stands, against an rbgo from #819: 11 examples, 25 claimed answers, 13 files, 0 disagreements. Broken three ways deliberately, it named each precisely:

break	what it said
a wrong number	scientific-stack.md:72: answer 1 is "24.0", the page says "24.5"
two printed lines, one claimed	printed: [… 4 values …] claims: [… 3 values …]
an example that no longer runs	claims 4 answer(s) but will not run: undefined method 'gammaa' for module Special

credscan 0. Measured 2026-10-17 with go1.27.2.

🤖 Generated with Claude Code

[tannevaled]

CI is red, and this is the run confirming why rather than an assumption — the dependency on ruby#819, and nothing else:

selftest: 6 case(s), 0 failure(s)
docs/scientific-stack.md:72:  ... will not run: uninitialized constant Special (NameError)
docs/scientific-stack.md:98:  ... will not run: uninitialized constant Stats (NameError)
docs/scientific-stack.md:118: ... will not run: uninitialized constant Integrate (NameError)
docs/scientific-stack.md:138: ... will not run: uninitialized constant Optimize (NameError)
11 example(s) with 25 claimed answer(s) over 13 file(s); 4 example(s) disagree

Four things are established by that output, which is more than "it is red":

• the self-test ran first and passed, so the extraction is doing what it claims;
• the GOBIN=/tmp go install …/cmd/rbgo@main step worked — the guard had an interpreter to judge with, so this is a disagreement and not the exit-2 refusal;
• the seven pre-existing examples still pass, so the new tool agrees with the site as it was;
• the four failures are exactly the four new sections, each naming its missing module.

Against an rbgo built from #819's branch the same command reports 11 example(s) with 25 claimed answer(s) over 13 file(s); 0 example(s) disagree.

So this goes in after #819 and turns green on its own, with no change here.

🤖 Generated with Claude Code