From 601f573ebdb173cf918bccafa2e64f9b91ee1fd5 Mon Sep 17 00:00:00 2001
From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com>
Date: Wed, 26 Aug 2026 16:28:18 +0100
Subject: [PATCH] =?UTF-8?q?fix(Axiom.jl):=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

Mirrors hyperpolymath/Axiom.jl#82 into the vendored copy. The file here was
byte-identical to Axiom.jl origin/main (sha256 4e8618eebc...) before the change,
so the same patch applies verbatim.

check_doc_alignment() could never pass, for three separate reasons:

1. Backticks inside a double-quoted string caused COMMAND SUBSTITUTION at
   scripts/readiness-check.sh:98 - bash tried to execute from_pytorch("model.pt"),
   emitted two syntax errors to stderr, and printed the message with the crucial
   part silently deleted. 'bash -n' does not catch this; only shellcheck does.

2. The assertion demanded README.adoc document from_pytorch("model.pt"), which
   src/integrations/interop.jl:352 explicitly THROWS on - .pt/.pth/.ckpt are
   Python pickles needing a PyTorch runtime. The gate demanded documentation of a
   path 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. Now asserts
   the supported JSON descriptor form and ADDS a guard that the .pt/.pth/.ckpt
   warning stays, protecting the no-Python posture instead of demanding Python.

3. A stale ROADMAP.md check survived the .md -> .adoc migration. The repo ships
   only ROADMAP.adoc, so rg failed on a missing file and '! rg' was permanently
   true, forcing status=1 regardless of documentation quality.

Verified in this vendored context: shellcheck 0 findings; check_doc_alignment
exits 0; diff touches only packages/Axiom.jl/scripts/readiness-check.sh.
---
 packages/Axiom.jl/scripts/readiness-check.sh | 23 +++++++++++++++-----
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/packages/Axiom.jl/scripts/readiness-check.sh b/packages/Axiom.jl/scripts/readiness-check.sh
index 7a3a23ed0..4d930162c 100755
--- a/packages/Axiom.jl/scripts/readiness-check.sh
+++ b/packages/Axiom.jl/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