From 8a72b96c3f54cf17b7ada5aa8bb2420b2b69a199 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 26 Aug 2026 16:27:22 +0100 Subject: [PATCH] =?UTF-8?q?fix(scripts):=20repair=20readiness-check=20doc?= =?UTF-8?q?=20gate=20=E2=80=94=203=20defects,=20gate=20was=20unsatisfiable?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A code-quality report flagged scripts/readiness-check.sh:98 with SC1064/SC1065, which read like style nits. They were not. check_doc_alignment() could never pass, for three separate reasons. 1. BACKTICKS CAUSED COMMAND SUBSTITUTION (runtime bug) echo "...missing the direct checkpoint `from_pytorch(\"model.pt\")` example." Inside double quotes backticks are command substitution, so bash tried to EXECUTE from_pytorch("model.pt"): bash: command substitution: syntax error near unexpected token `"model.pt"' README.adoc is missing the direct checkpoint example. Two errors to stderr, and the message printed with the crucial part silently deleted - so the diagnostic never said what was missing. `bash -n` does not catch this; only shellcheck does. 2. THE ASSERTION DEMANDED A PYTHON PATH THE LIBRARY REJECTS The check failed unless README.adoc documented from_pytorch("model.pt"). But src/integrations/interop.jl:352 explicitly throws on .pt/.pth/.ckpt because those are Python pickles needing a PyTorch runtime. So the gate demanded documentation of something the code refuses by design, contradicting interop.jl:98 (the python3 shell-out was deliberately removed) and k9iser.toml:30 ("Python interop is opt-in only, never a hard dep"). The README was already correct - it documents the supported JSON descriptor form and explains why raw checkpoints are unsupported. The check was a leftover from before the de-Python refactor, failing the build for a README that was right. Now asserts the supported form, and ADDS a guard that the .pt/.pth/.ckpt warning stays in the README - turning the gate from demanding the Python path into protecting the no-Python posture. 3. A STALE ROADMAP.md CHECK MADE THE FUNCTION UNSATISFIABLE Found while exercising the function. The .md -> .adoc migration added a ROADMAP.adoc check but never removed the ROADMAP.md one. The repo ships only ROADMAP.adoc, so `rg` failed on a missing file, `! rg` was permanently true, and status=1 regardless of documentation quality. Removed; the .adoc check below it is the migrated equivalent and passes. Verified: shellcheck 5 findings -> 0 check_doc_alignment exit 1 -> exit 0 message text truncated -> prints intact negative test, example gone supported-form FAILs, guard still PASSes negative test, warning gone supported-form PASSes, guard FAILs diff scope scripts/readiness-check.sh only The negative tests matter: they show each check fails independently for its own reason, so this is not a gate that merely reports green. No change to README.adoc or interop.jl - both were already correct. --- scripts/readiness-check.sh | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/scripts/readiness-check.sh b/scripts/readiness-check.sh index 7a3a23e..4d93016 100755 --- a/scripts/readiness-check.sh +++ b/scripts/readiness-check.sh @@ -94,21 +94,32 @@ check_markers() { check_doc_alignment() { local status=0 - if ! rg -Fq 'model = from_pytorch("model.pt")' README.adoc; then - echo "README.adoc is missing the direct checkpoint `from_pytorch(\"model.pt\")` example." + # Assert the SUPPORTED import form. from_pytorch() throws on .pt/.pth/.ckpt by + # design (src/integrations/interop.jl) because those are Python pickles needing a + # PyTorch runtime, so requiring a "model.pt" example failed the gate for a README + # that was correct. Single-quoted: backticks in a double-quoted string are command + # substitution, which is what silently truncated this message. + if ! rg -Fq 'model = from_pytorch("model.pytorch.json")' README.adoc; then + echo 'README.adoc is missing the supported from_pytorch("model.pytorch.json") descriptor example.' status=1 fi - if ! rg -Fq "application/grpc+json" README.adoc; then - echo "README.adoc is missing gRPC bridge content-type coverage notes." + # Guard the no-Python posture: the README must keep warning that raw checkpoints + # need a PyTorch/Python runtime, so a future edit cannot quietly reintroduce one. + if ! rg -Fq '.pt/.pth/.ckpt' README.adoc; then + echo 'README.adoc no longer warns that raw .pt/.pth/.ckpt need a PyTorch/Python runtime.' status=1 fi - if ! rg -Fq "## Deferred Commitments (Tracked)" ROADMAP.md; then - echo "ROADMAP.md is missing the deferred commitments section." + if ! rg -Fq "application/grpc+json" README.adoc; then + echo "README.adoc is missing gRPC bridge content-type coverage notes." status=1 fi + # The ROADMAP.md check that used to sit here was a leftover from the .md -> .adoc + # migration: the repo ships only ROADMAP.adoc, so `rg` failed on a missing file and + # `! rg` was permanently true, making check_doc_alignment unsatisfiable regardless of + # documentation quality. The .adoc check below is the migrated equivalent. if ! rg -Fq "== Deferred Commitments (Tracked)" ROADMAP.adoc; then echo "ROADMAP.adoc is missing the deferred commitments section." status=1