Polish: second cartridge, GUI smoke test, finish .adoc tidy (#39)

## Three small follow-ups, done in turn

### 1. Second example cartridge — proves the engine is language-agnostic
`cartridges/reference/python-ruby.cartridge.json`: 6 Python→Ruby
transitions spanning **cognate** (`def`, string interpolation),
**false-friend** (empty-collection truthiness — `[]` is falsy in Python,
truthy in Ruby), **alien-realization** (comprehension → block `map`),
**novel** (Ruby `:symbol`), and **vanished** (explicit `self`
parameter). Dogfoods the cartridge contract on a fresh pair. Cartridge
invariants went **59 → 107 checks**, all green; the CLI/GUI now present
2 packs / 12 correspondences.

### 2. GUI smoke test
`gui/server.js` now `export`s `handler` + `loadCartridges` and opens a
listener **only under `import.meta.main`** — so `test/gui_smoke_test.js`
drives the handler **in-process (no socket, `--allow-read` only)**: the
static shell + `#index/#paneForms/#paneClassify`, the `/app.js` bundle,
the `/api/cartridges` shape (every transition has a valid kind +
from/to), and a clean 404. **38 checks, all passing.** Wired into `deno
task test` (and `test:gui`) + a `just test-gui` recipe. Verified the
real server still starts via a live probe.

### 3. Finished the `.adoc` migration
`TOPOLOGY.md` → `TOPOLOGY.adoc` (and corrected its data-flow diagram,
which still described the old JS→migration-report pipeline, to the real
cartridge→engine→GUI/CLI flow) and `TEST-NEEDS.md` → `TEST-NEEDS.adoc`
(coverage refreshed to include the GUI smoke test). Root docs are now
AsciiDoc end-to-end, except the GitHub-required `CODE_OF_CONDUCT.md` /
`SECURITY.md`.

### Verified
`deno fmt --check`, `deno lint`, `deno task test` (cartridge invariants
+ GUI smoke), `deno task build` (2/2 cartridges valid), and a live GUI
probe — all green. No dangling links. Licence files untouched.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---
_Generated by [Claude
Code](https://claude.ai/code/session_01A1BaAhqxUjkgVb1yg1sZap)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

Justfile

@@ -70,11 +70,16 @@ gui:
 
 # === TESTING ===
 
-# Run all tests
+# Run all tests (cartridge invariants + GUI smoke test)
 test:
     @echo "🧪 Running tests..."
     deno task test
 
+# Run just the GUI smoke test (server handler: shell, bundle, cartridge API)
+test-gui:
+    @echo "🖥️  GUI smoke test..."
+    @deno task test:gui
+
 # === VALIDATION ===
 
 # Run full validation

TEST-NEEDS.adoc

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+= TEST-NEEDS — nextgen-languages-evangeliser
+
+CRG Grade: C (achieved 2026-04-04).
+
+== Current test state
+
+[cols="2,1,3",options="header"]
+|===
+| Category | Count | Notes
+
+| Cartridge invariant tests | 1 suite | `test/run_all.js` (Deno) — semantic invariants over every cartridge
+| GUI smoke test | 1 suite | `test/gui_smoke_test.js` (Deno) — server handler: shell, bundle, cartridge API
+| Cartridge schema validation | 1 | `scripts/validate-cartridges.js` (Deno + ajv, JSON-Schema 2020-12)
+| Idris2 ABI typecheck | 1 | `abi.ipkg` / `src/interface/Abi/*.idr` (CI: `idris2-abi.yml`)
+| Test framework | Deno + ajv + Idris2 | host-language unit tests were removed with the ReScript host
+|===
+
+== What's covered
+
+* Every correspondence is classified by one of the six CorrespondenceKinds
+* Well-formedness: Forms (language + surface), residue shapes, strata names/booleans
+* False-friend signature (surface holds ∧ intention diverges) — mirrors `Abi.Correspondence.isFalseFriendShape`
+* Residue direction for novel (absent-source) / vanished (absent-target)
+* The worked-examples reference cartridge demonstrates all six kinds
+* Cartridge JSON-Schema conformance (ajv)
+* GUI server handler: static shell, `/app.js` bundle, `/api/cartridges` shape, and a clean 404
+* Idris2 ABI typechecks (no `believe_me` / `assert_total`)
+
+== Still missing (for CRG B+)
+
+* Headless-DOM rendering test of `gui/app.js` (the smoke test covers the server / API, not the browser render)
+* Property-based generation over cartridge facts
+* Performance benchmarks
+* End-to-end "walk a correspondence" flow test
+
+== Run tests
+
+[source,bash]
+----
+just test          # cartridge invariants + GUI smoke test
+just test-gui      # GUI smoke test only
+deno task test     # same as `just test`
+deno task validate # cartridge schema validation
+----

TEST-NEEDS.md

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+= TOPOLOGY — nextgen-languages-evangeliser
+
+== Purpose
+
+Cross-language *comprehension and transfer* engine — Duolingo / Rosetta Stone for
+programming languages. It *classifies* correspondences between a known language and
+a target so learning transfers (it does not translate, lint, or build IDEs).
+Flagship / future host: AffineScript. Legacy target: ReScript (host removed). Runs
+on Deno; the browser multi-pane workspace is the primary surface.
+
+== Module map
+
+[source]
+----
+nextgen-languages-evangeliser/
+├── bin/evangeliser.js     # Offline CLI (Deno; reads cartridges)
+├── src/
+│   ├── cartridges.js      # Shared cartridge loader (Deno glue)
+│   └── interface/         # Engine spine: Idris2 ABI + Zig FFI + AffineScript host binding
+├── cartridges/            # Correspondence facts: schema + reference pack
+├── gui/                   # Browser multi-pane workspace (primary surface)
+├── scripts/               # Deno utilities (cartridge validator, GUI launcher)
+├── test/                  # Cartridge invariant tests + GUI smoke test
+├── config.ncl             # Nickel configuration
+├── docs/                  # Documentation (AsciiDoc)
+├── Justfile               # Task runner recipes
+└── deno.json              # Deno module config
+----
+
+== Data flow
+
+[source]
+----
+cartridges/**/*.cartridge.json          (authored correspondence facts)
+        │
+        ▼
+  shared loader (src/cartridges.js)
+        │
+        ├─► gui/server.js ──► browser workspace   (index · forms · classification)
+        ├─► bin/evangeliser.js ──► CLI            (--kind / --find / --json)
+        └─► test + scripts ──► invariants + schema validation
+        │
+        ▼
+  (downstream, planned) octads ──► VeriSimDB ──► PanLL panels
+----
+
+The classification vocabulary (six CorrespondenceKinds, strata, residue shapes) is
+specified in the Idris2 ABI (`src/interface/Abi/`) and mirrored by the cartridge
+schema. The engine *classifies* correspondences; it does not transform source.

TOPOLOGY.adoc

@@ -0,0 +1,122 @@
+{
+  "$schema": "../correspondence-cartridge.schema.json",
+  "spdx": "MPL-2.0",
+  "name": "python-ruby",
+  "version": "0.1.0",
+  "description": "Second reference cartridge: Python -> Ruby. Dogfoods the cartridge contract on a fresh language pair to show the engine is language-agnostic. Covers cognate / false-friend / alien-realization / novel / vanished from a Python learner's standpoint.",
+  "languages": ["python", "ruby"],
+  "transitions": [
+    {
+      "concept": "function-definition",
+      "from": { "language": "python", "surface": "def greet(name):\n    ..." },
+      "to": { "language": "ruby", "surface": "def greet(name)\n  ...\nend" },
+      "kind": "cognate",
+      "residue": {
+        "shape": "none",
+        "note": "Same keyword (`def`) and intent; Ruby closes the body with `end` where Python uses indentation."
+      },
+      "strata": [
+        { "stratum": "surface", "holds": true },
+        { "stratum": "intention", "holds": true }
+      ],
+      "narrative": {
+        "celebrate": "You already define functions with `def` — that word is the same in Ruby.",
+        "better": "Your `def` intuition transfers directly.",
+        "example": "def greet(name): ...   <->   def greet(name) ... end"
+      }
+    },
+    {
+      "concept": "string-interpolation",
+      "from": { "language": "python", "surface": "f\"Hi {name}\"" },
+      "to": { "language": "ruby", "surface": "\"Hi #{name}\"" },
+      "kind": "cognate",
+      "residue": {
+        "shape": "none",
+        "note": "Same intent (interpolate a value into a string); Ruby uses `#{}` and needs no `f` prefix."
+      },
+      "strata": [
+        { "stratum": "surface", "holds": true },
+        { "stratum": "intention", "holds": true }
+      ],
+      "narrative": {
+        "celebrate": "f-strings are second nature to you — interpolation carries straight over.",
+        "better": "Drop the `f` and write `#{}` instead of `{}`.",
+        "example": "f\"Hi {name}\"   <->   \"Hi #{name}\""
+      }
+    },
+    {
+      "concept": "empty-collection-truthiness",
+      "from": { "language": "python", "surface": "if items:  # empty list is falsy" },
+      "to": { "language": "ruby", "surface": "if items   # empty array is TRUTHY" },
+      "kind": "false-friend",
+      "residue": {
+        "shape": "lossy",
+        "note": "In Ruby only `nil` and `false` are falsy; `[]`, `\"\"`, and `0` are all truthy. The Python habit of testing a collection for emptiness via truthiness silently breaks."
+      },
+      "strata": [
+        { "stratum": "surface", "holds": true },
+        { "stratum": "intention", "holds": false }
+      ],
+      "narrative": {
+        "celebrate": "You've leaned on truthiness to check for empty/zero for years — that's a real, useful instinct.",
+        "safety": "In Ruby that instinct misfires: `if items` is true even when empty. Test emptiness explicitly.",
+        "example": "Python: if items:  ->  Ruby: if items.any?   (or: unless items.empty?)"
+      }
+    },
+    {
+      "concept": "map-over-collection",
+      "from": { "language": "python", "surface": "[f(x) for x in xs]" },
+      "to": { "language": "ruby", "surface": "xs.map { |x| f(x) }" },
+      "kind": "alien-realization",
+      "residue": {
+        "shape": "lossy",
+        "note": "Same intention (transform each element) realised through different machinery: a comprehension expression vs a method taking a block."
+      },
+      "strata": [
+        { "stratum": "intention", "holds": true },
+        { "stratum": "structure", "holds": false }
+      ],
+      "narrative": {
+        "celebrate": "You think in comprehensions — that mapping intent is exactly right.",
+        "better": "Ruby spells it as a block passed to `map`; once it clicks, blocks are everywhere.",
+        "example": "[f(x) for x in xs]   ->   xs.map { |x| f(x) }"
+      }
+    },
+    {
+      "concept": "symbol",
+      "from": { "language": "python", "surface": "(no analog)" },
+      "to": { "language": "ruby", "surface": ":status" },
+      "kind": "novel",
+      "residue": {
+        "shape": "absent-source",
+        "note": "Python has no symbol type. The nearest habits — interned strings, enum members, dict keys — are not the same thing; learn the symbol fresh."
+      },
+      "strata": [
+        { "stratum": "intention", "holds": false }
+      ],
+      "narrative": {
+        "celebrate": "Coming from Python you have great instincts for dict keys and enums.",
+        "safety": "A Ruby symbol (`:status`) is its own immutable, interned identifier — not a string. Learn it as a new thing rather than mapping it onto strings.",
+        "example": "{ status: :active }   # :active is a symbol, not \"active\""
+      }
+    },
+    {
+      "concept": "explicit-self-parameter",
+      "from": { "language": "python", "surface": "def m(self):\n    ..." },
+      "to": { "language": "ruby", "surface": "def m\n  ...\nend" },
+      "kind": "vanished",
+      "residue": {
+        "shape": "absent-target",
+        "note": "Ruby has no explicit `self` parameter; the receiver is implicit. The Python habit of writing `self` first in every method has nowhere to go — re-route it."
+      },
+      "strata": [
+        { "stratum": "intention", "holds": false }
+      ],
+      "narrative": {
+        "celebrate": "Writing `self` first is muscle memory from Python — totally reasonable.",
+        "safety": "In Ruby that parameter vanishes: methods take only their real arguments, and `self` is implicit (use it bare when you need the receiver).",
+        "example": "Python: def m(self): ...   ->   Ruby: def m ... end"
+      }
+    }
+  ]
+}

TOPOLOGY.md

@@ -10,7 +10,8 @@
     "gui": "deno run --allow-read --allow-net gui/server.js",
     "lint": "deno lint",
     "fmt": "deno fmt",
-    "test": "deno run --allow-read test/run_all.js",
+    "test": "deno run --allow-read test/run_all.js && deno run --allow-read test/gui_smoke_test.js",
+    "test:gui": "deno run --allow-read test/gui_smoke_test.js",
     "pre-commit": "deno task lint && deno task fmt --check"
   },
   "fmt": {
@@ -20,7 +21,7 @@
     "semiColons": false,
     "singleQuote": false,
     "proseWrap": "preserve",
-    "include": ["bin/", "src/cartridges.js", "test/run_all.js", "deno.json"]
+    "include": ["bin/", "src/cartridges.js", "test/", "deno.json"]
   },
   "lint": {
     "rules": {