fix(docs): declare frac in strategy README's 'Register your own' basis() hook (Fixes #274)

[statxc]

PR kind

• fix
• feat

Fixes #274.

Summary

multiply_subspace forwards the run's vram_fraction only to a basis() that declares frac — an inspect.signature gate whose else branch is a legacy-compat shim. So a contributor who copies a snippet without frac lands in the legacy branch and silently streams their basis at the default fraction instead of --vram-fraction (the bug #211 fixed for rsvd).

CONTRIBUTING.md, transform_template.py and run_example.py were all brought in line. strategy/README.md's "Register your own (the updatable hook)" — the copy a contributor meets first — still showed the old signature:

def basis(self, n, m, backend, dtype, A=None, B=None):     # no frac

Why it survived

tests/test_contributor_docs_basis_signature.py was added for exactly this class of drift, but never covered the README. Its own docstring scoped it out:

these tests cover the two remaining copies contributors actually read: CONTRIBUTING.md's … snippet … strategy/examples/run_example.py's FirstAxes

So the one uncovered snippet is precisely the one that stayed stale — and #274 notes it has now regressed twice.

Fix

• strategy/README.md: the hook declares frac, with a note on what to do with it (forward to stream_gemm_*; declare it even if unused, because the gate keys off the signature).
• tests/…basis_signature.py: close the hole. The markdown copies now run through one parametrized table (CONTRIBUTING.md, strategy/README.md), so a rollback — or a newly added doc — cannot quietly skip the check. Also asserts the full parameter list against Transform.basis (defaults stripped), not merely the presence of frac, so a snippet cannot drift on any other argument either.

Proof the guard actually bites — reverting just the README makes it fail:

AssertionError: strategy/README.md basis() snippet omits frac:
                def basis(self, n, m, backend, dtype, A=None, B=None)

Credit

#275 (@luciferlive112116) reported the same gap. It was closed unmerged by the 12h merge-conflict rule after #253 landed the test file underneath it — not on merits. This is an independent implementation against current main, scoped to the one snippet that is still stale (CONTRIBUTING.md and run_example.py are already correct).

Touches only strategy/README.md and tests/ — no protected paths. (docs/whitepaper.md has the same stale snippet but is maintainer-owned, so it is left alone.)

Validation

uv run --extra test python -m pytest tests/test_contributor_docs_basis_signature.py -q  # 6 passed
uv run --extra test python -m pytest tests/ strategy/tests/ eval/tests/ -q              # 467 passed, 24 skipped

Pure text/AST parsing — no GPU needed.

Checklist

• CPU-safe validation passed.
• My commits do not include Co-authored-by footers for coding agents such as Cursor, Codex, Claude, Copilot, or similar tools.
• Not a feat PR — no scorecard required.

[zeokin]

Fixes #274: strategy/README's 'Register your own' hook still showed basis() without frac, so a copied snippet hits multiply_subspace's legacy branch and silently ignores --vram-fraction. Also extends the drift test to cover the README (the hole that let it drift).