docs: sync version + cartridge-count claims, mark gRPC/GraphQL planned#40
Merged
hyperpolymath merged 1 commit intomainfrom Apr 30, 2026
Merged
docs: sync version + cartridge-count claims, mark gRPC/GraphQL planned#40hyperpolymath merged 1 commit intomainfrom
hyperpolymath merged 1 commit intomainfrom
Conversation
Spec drift sweep across canonical surfaces. Brings every advertised version string into agreement with package.json (0.4.6) and every cartridge-count claim into agreement with the actual count of cartridges/*/ directories on disk (115). Versions (all -> 0.4.6): - Justfile: 0.3.1 -> 0.4.6 - openapi.yaml: 0.4.0 -> 0.4.6 - docs/specification/openapi.yaml: 0.3.0 -> 0.4.6 - smithery.yaml: 0.4.0 -> 0.4.6 - gemini-extension.json: 0.4.0 -> 0.4.6 - stapeln.toml: 0.3.1 -> 0.4.6 Cartridge counts (all -> 115, the actual filesystem count): - README.md: "50+" and "100" -> "115" - README.adoc: "106+" and "100" -> "115" - QUICKSTART-USER.adoc: "112" (x2) -> "115" - openapi.yaml description: 106 -> 115 - ai-plugin.json: 55 -> 115 (also: V-lang -> Deno/JS, V-lang banned 2026-04-12) - smithery.yaml: 53 -> 115 (description + boj_menu tool) - docs/glama/CAPABILITIES.md: 106 -> 115 - docs/glama/RESOURCES.md: 106 -> 115 (observation example) - llm-warmup-dev.md: 112 -> 115 (3 places) - llm-warmup-user.md: 112 -> 115 (file map row) - EXPLAINME.adoc: 112 -> 115 (4 places) QUICKSTART-USER.adoc port table: gRPC (7701) and GraphQL (7702) marked planned, with explicit NOTE that only REST :7700 is implemented today. This is consistent with ARCHITECTURE.md L163, which already records the gap. Verified: elixir/lib/boj_rest only contains a Plug router; zero matches for grpc/graphql/absinthe; no .proto or .graphql schema files exist in the repo. Out of scope (left unchanged; flagged for separate work): - ROADMAP.adoc, TEST-NEEDS.md, TOPOLOGY.md, ARCHITECTURE.md cartridge status breakdowns: date-stamped historical measurements (as of 2026-04-25) — re-measurement, not substitution. - docs/READINESS.md L75: per-cartridge metrics (103/106 built etc.) — needs re-run, not bump. - docs/outreach/awesome-list-descriptions.md and blog-post-draft.md: reference V-lang adapter as a third language; need a bigger rewrite now that V-lang is banned and Deno/JS replaces it. - docs/decisions/0006-cartridge-invoke-abi.md: hedged ~100 cartridges in an ADR — historical, fine. This advances ROADMAP.adoc v1.0.1's open checkbox: "Refresh repo documentation claims after migration closure (counts, completion text, handover docs)." Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced Apr 30, 2026
hyperpolymath
added a commit
that referenced
this pull request
Apr 30, 2026
) ## Summary Re-measures the date-stamped historical statements PR #40 deliberately left out of scope (because they were measurements taken on 2026-04-25 and substituting blind would have been wrong). Now refreshed against the actual repo state on 2026-04-30 after `just build` produced **111 of 115** cartridge `.so` libraries. ## Numbers refreshed | Surface | Old | New | |---|---|---| | `TOPOLOGY.md` L4 | "Updated 2026-04-25. 112 cartridges across 6 tiers." | "Updated 2026-04-30. 115 cartridges across 6 tiers (111 with `.so` built, 4 pending)." | | `TEST-NEEDS.md` L124 | "112 cartridges loaded … as of 2026-04-25" | "115 cartridges loaded … as of 2026-04-30" + the 4 not-yet-building names | | `ROADMAP.adoc` v1.0.1 (4 checkboxes) | mixed 112/checked + unchecked | bumped to 115, re-dated 2026-04-30, two unchecked items now [x] (this PR closes them) | | `ROADMAP.adoc` v1.1.0 | "99 of 106 cartridges use `mod.js`" | "4 of 115 cartridges still use `mod.js`" — the gap closed substantially | | `docs/ARCHITECTURE.md` L138 | "Once all 112 cartridges have verified `.so` builds" | 115 + parenthetical 2026-04-30 measurement | | `docs/ARCHITECTURE.md` L209–212 | "1 complete (boj-health), 111 in progress" — INVERTED | "111 with `.so` built, 4 not yet building" — actually inverts the breakdown | | `docs/READINESS.md` L75 | "Cartridge fleet (106) … 103/106 shared libs built" | "Cartridge fleet (115) … 111/115 shared libs built" | The 4 cartridges still without `.so`: **`database-mcp`**, **`echidna-llm-mcp`**, **`lang-mcp`**, **`orchestrator-lsp-mcp`**. Flagged in three places so the next investigator has a starting list. ## What this PR deliberately does NOT do - **Re-run mix test / zig test / FFI test counts.** The numbers in `READINESS.md` (`113 FFI tests`, `178 core tests`, `4 believe_me`, etc.) are last-documented values, not re-measured. The row text in `READINESS.md` honestly notes this. Test re-run is a separate follow-up. - **Re-count per-directory READMEs.** The "393 per-directory READMEs" number is also a last-documented value. Same reasoning. - **Investigate the 4 build-failing cartridges.** Their `just build` errors are out of scope here; flagged for a follow-up. - **Touch any other ARCHITECTURE / ROADMAP claims unrelated to count or build status.** ## Test plan - [ ] Visual review of the 5 changed files to make sure the numbers are coherent (115 across the board for "total"; 111 for "built"; 4 for "pending"; 2026-04-30 for "as of" dates). - [ ] CI green on the branch (will hit the same 3 pre-existing failures as #40 / #41 — TS/JS Blocker on the 6 `.ts` files, Hypatia missing GITHUB_TOKEN; admin merge expected, same as those). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hyperpolymath
added a commit
that referenced
this pull request
Apr 30, 2026
… mix path in service unit (#43) ## Summary Three of the four sub-parts of the deferred cleanup ledger from PR #40's out-of-scope list. The fourth (port the 6 `.ts` cartridge adapters to AffineScript→typed-wasm) is delegated to a scheduled remote agent that fires 2026-05-07 and runs **one cartridge per pass**, so it stays opportunistic and reviewable. ## Changes | File | Fix | |---|---| | `.github/workflows/hypatia-scan.yml` | Adds job-level `GITHUB_TOKEN` env (Hypatia CLI calls `gh api` for Dependabot lookups; without the token it logs `Dependabot alerts unavailable: GITHUB_TOKEN not set` and the job exits non-zero). Adds `security-events: read` permission. | | `.github/workflows/rsr-antipattern.yml` | "use ReScript instead" → "use AffineScript→typed-wasm instead". Header comment + Allows banner updated to reflect estate-wide language policy 2026-04-30 (RS/TS/JS default is AffineScript; ReScript transitional / adapter-shim only). | | `.github/workflows/ts-blocker.yml` | "port to Zig or ReScript" / "use Zig or ReScript instead" → "Zig (systems) or AffineScript→typed-wasm (application)". Underlying detection unchanged. | | `elixir/boj-rest.service` | Replace hardcoded `ExecStart=/usr/bin/mix` (which is apt's 1.14, fails `mix.exs` `~> 1.15` check on Ubuntu 24.04 LTS) with `ExecStart=mix run --no-halt`. Adds `Environment=PATH` with asdf shims, cargo bin, `~/.local/bin`. Adds `ASDF_DIR` + `ASDF_DATA_DIR` so asdf shims work under systemd's clean env. Bumps cartridge-count comment 112 → 115. | ## Why these specifically PR #40 (spec drift) merged on 2026-04-30 surfaced four follow-up cleanups; this PR closes three of them. The fourth (`.ts` → AffineScript ports) was deliberately scheduled rather than rushed — verifying AffineScript readiness for each cartridge is genuinely per-cartridge work and the scheduled agent does it one at a time. The `boj-rest.service` fix in particular was discovered the hard way during the maintainer's install: the deployed unit needed a hand-patch (`~/.config/systemd/user/boj-rest.service`) to point at `~/.asdf/installs/elixir/1.18.4-otp-25/bin/mix`. Persisting the fix to the source template (with `%h` systemd-substitution + asdf shim PATH) means the next person installing on a fresh Ubuntu doesn't repeat the dance. The three pre-existing CI failures that were blocking PRs #40, #41, #42 are likely partially closed by this PR: - **Hypatia** — should now pass with `GITHUB_TOKEN` wired up. - **TS/JS Blocker** and **antipattern-check** — will *still* fail on the 6 `.ts` cartridge adapters (`academic-workflow-mcp`, `bofig-mcp`, `ephapax-mcp`, `fireflag-mcp`, `hesiod-mcp`, `sanctify-mcp`). Those are the scheduled agent's work. Admin-merge-without-CI is still expected for this PR. ## Test plan - [ ] CI shows Hypatia passing on this branch (GITHUB_TOKEN now available). - [ ] Diff visual review for the policy text — make sure no instance of "use ReScript instead" remains in the workflow files. - [ ] After merge, fresh install on a clean Ubuntu 24.04 LTS host with asdf + the toolchain-pins from PR #41: `bash setup.sh && just doctor && just deps && just build && just install-service` — confirm `boj-rest.service` starts cleanly without the `(Mix) You're trying to run :boj_rest on Elixir v1.14.0` error that was previously hit. ## Out of scope - The 6 `.ts` → AffineScript ports (scheduled, one per week from 2026-05-07, routine `trig_01X9BreihRW4AU5BdELY2QBY`). - Re-running mix test / FFI tests for grade re-validation (READINESS.md still lists the last-documented numbers per the re-measurement PR #42). - The 4 cartridges still without `.so` (`database-mcp`, `echidna-llm-mcp`, `lang-mcp`, `orchestrator-lsp-mcp`) — listed in #42 for follow-up. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Sync of the canonical version + cartridge-count claims across the repo, plus an honest disclosure that the gRPC and GraphQL ports advertised in
QUICKSTART-USER.adocaren't implemented yet (only REST :7700 is live inelixir/lib/boj_rest/). 15 files, +37/-30. Pure docs/metadata change — no code or build behaviour affected.Drift reconciled
Justfileversion :=0.3.10.4.6openapi.yamlinfo.version0.4.00.4.6docs/specification/openapi.yamlversion0.3.00.4.6smithery.yamlversion0.4.00.4.6gemini-extension.jsonversion0.4.00.4.6stapeln.tomlversion0.3.10.4.6README.mdtwo count claims50+/100115/115README.adoctwo count claims106+/100115/115QUICKSTART-USER.adoctwo count claims112/112115/115openapi.yamldescription106 ... cartridges115 ... cartridgesai-plugin.jsontwo descriptions55 ... cartridges+V-lang adapter115 ... cartridges+Deno/JS adaptersmithery.yamldescription +boj_menu53 ... cartridges115 ... cartridgesdocs/glama/CAPABILITIES.md**106 Cartridges****115 Cartridges**docs/glama/RESOURCES.mdexamplesupports 106 cartridgessupports 115 cartridgesllm-warmup-dev.md(3 occurrences)112 cartridge…115 cartridge…llm-warmup-user.mdfile map row112 cartridge directories115 cartridge directoriesEXPLAINME.adoc(4 occurrences)112 cartridge…115 cartridge…package.jsonwas already at0.4.6and is treated as the authoritative version.115is the actual count ofcartridges/*/directories on disk.Honest disclosure: gRPC + GraphQL not implemented
QUICKSTART-USER.adoc'sKey Portstable previously advertised :7701 gRPC and :7702 GraphQL alongside :7700 REST without qualification. Verified against the current tree:elixir/lib/boj_rest/contains onlyapplication/catalog/credential_decryptor/invoker/js_invoker/js_worker/js_worker_pool/node_key/router/trust_policy.ex. Zero matches forgrpc,graphql, orabsinthe..protofiles anywhere in the repo (gh search code repo:hyperpolymath/boj-server extension:proto→ 0 hits).Boj.ProtocolABI enum listsGRPCbut not GraphQL.This is consistent with
docs/ARCHITECTURE.mdL163 ("gRPC (7701), GraphQL (7702), and SSE (7703) are not yet live — tracked as future work in ROADMAP.adoc"); the QUICKSTART table just hadn't been updated to match. The PR adds a per-row qualifier and a NOTE block under the table, preserving the forward-looking intent without making false claims.What's deliberately not in this PR
These warrant a follow-up; flagging here so they don't surprise:
ROADMAP.adocv1.0.1 checkboxes,TEST-NEEDS.mdL124,TOPOLOGY.mdL4,ARCHITECTURE.mdcartridge status breakdown): these reference measurements taken on 2026-04-25 (e.g. "all 112 cartridges covered 2026-04-25"). Those statements were correct at that date — fixing them is re-measurement against the current scaffold/build/.so state, not substitution. Out of scope.docs/READINESS.mdL75: per-cartridge metrics ("103/106 shared libs built", "113 FFI tests pass") — same re-measurement story.docs/outreach/awesome-list-descriptions.mdanddocs/outreach/blog-post-draft.md: heavily reference V-lang adapter (banned 2026-04-12, replaced by Deno/JS). They need a bigger rewrite, not just count substitution. Updating them in this PR would leave the architecture description internally inconsistent.docs/decisions/0006-cartridge-invoke-abi.mdL130 "~100 cartridges" — hedged, in an ADR, historical. Fine as-is.This PR also explicitly advances the open checkbox in
ROADMAP.adocv1.0.1: "Refresh repo documentation claims after migration closure (counts, completion text, handover docs)."Test plan
just doctorstill parses Justfile cleanly with new version.npm run test(mcp-bridge dispatch coherence test) still passes — no tool surface changes here, so this should be a no-op.openapi.yaml(e.g.redocly lint openapi.yaml) still clean.boj_menudescription insmithery.yamlstill matches the actualboj_menutool's documented behaviour inmcp-bridge/.🤖 Generated with Claude Code