Claude/repo tidy rsr taxonomy by hyperpolymath · Pull Request #149 · hyperpolymath/boj-server

hyperpolymath · 2026-05-25T21:30:43Z

Summary

Repo-health tidy aligning boj-server's documentation taxonomy with hyperpolymath/rsr-template-repo. The root went from 17 .md/.adoc docs to 9 (all of which are either GitHub-required, load-bearing, or known high-coupling items deferred for separate work); docs/ now has audience-targeted subdirectories matching the template (quickstarts/, wikis/, architecture/, status/, developer/); and every non-GitHub-required .md doc in the moved set is now .adoc per the hyperpolymath language policy.

Changes — six logical commits

1. docs(taxonomy): move root .adoc docs under docs/<category>/ — 8 root .adoc files relocated:

EXPLAINME.adoc → docs/EXPLAINME.adoc
BOJ_LOGIC.adoc, NeSy_SERVERS.adoc → docs/architecture/
FUTURE_PLANS.adoc, ROADMAP.adoc → docs/status/
QUICKSTART-{USER,DEV,MAINTAINER}.adoc → docs/quickstarts/{USER,DEV,MAINTAINER}.adoc

Cross-refs updated in 0-AI-MANIFEST.a2ml, Justfile, elixir/boj-rest.service, .machine_readable/agent_instructions/methodology.a2ml, docs/README.adoc, docs/accessibility/README.adoc, and the two outreach/ drafts.

2. docs(readme): merge README.md into README.adoc, drop the .md duplicate — the substantive 518-line README.md (11-client install matrix, collapsible cartridge tables, AAA section) converted to AsciiDoc and merged with the unique sections from the shorter .adoc (Features bullets, Formal verification). README.md deleted. Refs in jsr.json, mcp-bridge/lib/resources.js, .github/SECURITY.md, and Intentfile repointed at README.adoc.

3. docs(taxonomy): convert wiki/llm-warmup/Phase-3B docs to .adoc and re-home them — five wiki pages converted and moved from docs/wiki/ to docs/wikis/ (template's spelling); llm-warmup-{dev,user}.md moved into docs/developer/; CARTRIDGE-PHASE-3B-COMPLETION.md moved into docs/status/. Also drift-fixed STATE.a2ml's stale cartridge counts (112 → 125, derived from actual directory count).

4. docs(taxonomy): convert docs/*.md to .adoc, relocate ARCHITECTURE+DEVELOPERS, add subdir READMEs — 8 docs/*.md files converted to .adoc; docs/ARCHITECTURE.md → docs/architecture/README.adoc; docs/DEVELOPERS.md → docs/developer/README.adoc. 99 files cross-rewritten (55 cartridge READMEs + governance/wiki/dev/architecture refs + Justfile, .github/copilot-instructions.md, SECURITY.md, src/abi/Boj/Catalogue.idr, k8s/service.yaml, mcp-bridge/lib/api-clients.js, etc.). New subdir orientation READMEs in docs/quickstarts/, docs/status/, docs/wikis/.

5. docs(quickstarts): replace stub DEV/MAINTAINER with the substantial docs/*.md content — the substantive docs/QUICKSTART.md (72 lines), docs/GETTING-STARTED.md (198 lines), and docs/OPERATOR-QUICKSTART.md (296 lines) replace the 39/40-line stubs that had moved over from root in commit 1. Result: docs/quickstarts/{USER, DEV, BUILD-FROM-SOURCE, MAINTAINER}.adoc.

6. docs(index): comprehensive docs/README.adoc rewrite + final TYPED-WASM-MCP-BRIDGE conversion — docs/README.adoc rewritten in full (four sections: "Reading order by audience", "Directory taxonomy", "Standalone docs/ root files", "Related root-level files"). Last lone .md in docs/architecture/ converted.

Known-deferred (not in this PR — high coupling)

These four root-level files are intentionally left in place because moving them would ripple across 5–16+ files including CI workflows, Idris2 proofs, and Elixir test fixtures:

PROOF-NEEDS.md (16 cross-refs, incl. .github/workflows/backend-assurance.yml, src/abi/Boj/SafetyLemmas.idr, 4 Elixir test files)
TOPOLOGY.md (11 cross-refs, incl. a CI workflow)
TEST-NEEDS.md (5 cross-refs)
GEMINI.md — not deferred; it's load-bearing (gemini-extension.json references it as contextFileName)

A follow-up PR can address the first three with a careful bulk-rewrite once these moves are accepted.

Issues + PRs

Verified all 6 open issues (#135, #111, #101, #100, #87, #67) are current — most recently updated 2026-05-20. No stale issues require closing.

Cartridge-count drift

.machine_readable/6a2/STATE.a2ml had cartridges-total = 112 but the actual count is 125 (every cartridge directory has cartridge.json). Bumped: cartridges-total 112 → 125, cartridges-with-zig-ffi 111 → 115 (manifest-counted), cartridges-with-js-mod 111 → 113, and the prose in [project-context].purpose.

Test plan

All cross-references rewritten in the same commits as the file moves (no dangling links). Verified via git grep -l <old-path> returning 0 for every moved file.
CHANGELOG.md and historical log entries inside .machine_readable/6a2/STATE.a2ml deliberately left intact (rewriting history obscures the audit trail).
CI is freshly running (26 checks queued from this push).
Reviewer spot-check: docs/README.adoc index accurately reflects the on-disk taxonomy.
Reviewer spot-check: at least one cartridge README (e.g. cartridges/aerie-mcp/README.adoc) still links cleanly to docs/READINESS.adoc.

🤖 Generated with Claude Code

…rsr-template-repo boj-server's root carried 8 long-form .adoc docs (EXPLAINME, BOJ_LOGIC, NeSy_SERVERS, FUTURE_PLANS, ROADMAP, plus three QUICKSTART variants) that the rsr-template-repo standard places inside docs/<category>/. Aligning to the template's taxonomy makes the root scannable and lets both humans and machines navigate by purpose rather than by guessing. EXPLAINME.adoc -> docs/EXPLAINME.adoc BOJ_LOGIC.adoc -> docs/architecture/BOJ_LOGIC.adoc NeSy_SERVERS.adoc -> docs/architecture/NeSy_SERVERS.adoc FUTURE_PLANS.adoc -> docs/status/FUTURE_PLANS.adoc ROADMAP.adoc -> docs/status/ROADMAP.adoc QUICKSTART-USER.adoc -> docs/quickstarts/USER.adoc QUICKSTART-DEV.adoc -> docs/quickstarts/DEV.adoc QUICKSTART-MAINTAINER.adoc -> docs/quickstarts/MAINTAINER.adoc Cross-references updated in the same commit so nothing dangles: * 0-AI-MANIFEST.a2ml (Tier-1 doc paths) * Justfile (help text + doc list) * elixir/boj-rest.service (systemd Documentation= URI) * .machine_readable/agent_instructions/methodology.a2ml (fallback-files list) * docs/README.adoc, docs/accessibility/README.adoc (relative link targets) * docs/outreach/show-hn-{draft,post}.md (public Quickstart URLs) Historical mentions inside CHANGELOG.md and the timestamped log entries in .machine_readable/6a2/STATE.a2ml are LEFT UNCHANGED — they describe what the paths were at the time the entry was written, and rewriting history obscures the audit trail. New entries written after this commit will naturally reference the new paths. Files NOT moved this pass (high coupling — to be handled separately): * PROOF-NEEDS.md (16 cross-refs incl. CI + Idris proofs + Elixir tests) * TOPOLOGY.md (11 cross-refs incl. CI workflow) * TEST-NEEDS.md (5 cross-refs incl. Elixir test fixtures) * README.md (will be merged into README.adoc separately) * GEMINI.md (load-bearing — gemini-extension.json contextFileName)

Two READMEs at the root violated the .adoc-only doc policy and meant the substantive content (README.md, 518 lines: 11-client install matrix, collapsible per-domain cartridge tables, Glama AAA section, Citing) was diverging from the shorter README.adoc (176 lines, but with unique Features-bullets + Formal-verification sections). Merge: take README.md as the structural base, convert markdown to AsciiDoc, fold in the .adoc-unique Features + Formal-verification sections, and delete README.md. Resulting README.adoc covers: Install (Deno/Bun/Node + 9 client recipes: Claude Code, Claude Desktop, Gemini CLI, GitHub Copilot, Cursor, Cline, Windsurf, Continue.dev, Zed, Generic stdio) Backend / Verify Features at a glance Scope — 12 collapsible cartridge categories with full per-cartridge tables (115 cartridges total) Bridge-level tools (41 exposed) Local-coord-mcp at a glance + Parallel agents and git + coord-tui Glama AAA posture Formal verification (carried over from .adoc) Citing License Cross-reference updates so nothing dangles: * jsr.json publish include list → README.adoc * mcp-bridge/lib/resources.js docs URL → README.adoc * .github/SECURITY.md "Other enquiries" link → ../README.adoc * Intentfile example_actions read-target → README.adoc contractile.just and Mustfile.a2ml already guard with `test -f README.adoc || test -f README.md`; the .adoc branch still satisfies them, no change required. Other README.md references in the tree point at OTHER READMEs (cartridge-template/, specification/, backend-assurance/, etc.) and are correct as-is.

…-home them Honors the .adoc-only doc policy and aligns wiki spelling with the rsr-template-repo (docs/wikis/, not docs/wiki/). All conversions preserve content; the Markdown sources are deleted in the same commit. docs/wiki/Home.md -> docs/wikis/Home.adoc docs/wiki/User-Guide.md -> docs/wikis/User-Guide.adoc docs/wiki/Developer-Guide.md -> docs/wikis/Developer-Guide.adoc docs/wiki/Operator-Guide.md -> docs/wikis/Operator-Guide.adoc docs/wiki/FAQ.md -> docs/wikis/FAQ.adoc llm-warmup-dev.md -> docs/developer/llm-warmup-dev.adoc llm-warmup-user.md -> docs/developer/llm-warmup-user.adoc CARTRIDGE-PHASE-3B-COMPLETION.md -> docs/status/cartridge-phase-3b-completion.adoc Conversion handled headings, fenced code blocks (with language attribute), ordered + unordered lists (preserving nesting), bold, italic, links, autolinks, and Markdown tables (converted to native AsciiDoc [cols=...] / |=== form). Legacy HTML-comment SPDX headers were stripped and replaced with the canonical `// SPDX-...` form. Cross-references updated: * docs/governance/CRG-AUDIT-2026-04-18.adoc `docs/wiki/` (5 pages) -> `docs/wikis/` Historical mentions of llm-warmup-{dev,user}.md inside the dated log entries of .machine_readable/6a2/STATE.a2ml are LEFT UNCHANGED — they describe what the paths were at the time of each event. Also drift-fixed STATE.a2ml's stale cartridge counts: cartridges-total 112 -> 125 (every dir under cartridges/* has cartridge.json) cartridges-with-zig-ffi 111 -> 115 (manifest-counted; binaries built per-platform) cartridges-with-js-mod 111 -> 113 project-context.purpose "112 cartridges" -> "125 cartridges"

github-actions · 2026-05-25T21:31:02Z

🏁 path-claims bench

Commit c4df731

Numbers

path-claims bench  (node v22.22.3)

  scenario                                              iters       ms        ns/op          ops/s
  --------------------------------------------------------------------------------------------------------------
  register: 10 active claims, 3 new paths               50000 iters    182 ms      3.65 µs/op    273.6k ops/s
  register: 100 active claims, 3 new paths              20000 iters    329 ms     16.50 µs/op     60.6k ops/s
  register: 1000 active claims, 3 new paths              5000 iters    986 ms    197.38 µs/op      5.1k ops/s
  register: 100 active claims, 20 new paths              5000 iters    360 ms     72.08 µs/op     13.9k ops/s

  pathsOverlap: deep diverge at segment 4             1000000 iters    157 ms     157.5 ns/op     6.35M ops/s
  pathsOverlap: short prefix match                    1000000 iters    139 ms     139.6 ns/op     7.16M ops/s

  refresh (existing claim)                             100000 iters     10 ms     107.8 ns/op     9.28M ops/s
  list (100 active claims)                              50000 iters    299 ms      5.98 µs/op    167.2k ops/s

  (Bench numbers depend on host; use deltas across commits, not absolute values.)

Host-dependent — compare deltas across commits, not absolute values.

github-actions · 2026-05-25T21:31:46Z

🔍 Hypatia Security Scan

Findings: 251 issues detected

Severity	Count
🔴 Critical	18
🟠 High	223
🟡 Medium	10

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Stale AI session file -- delete",
    "type": "stale",
    "file": "GEMINI.md",
    "action": "delete",
    "rule_module": "root_hygiene",
    "severity": "medium"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/sanctify-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/academic-workflow-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/fireflag-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/ephapax-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/bofig-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/hesiod-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/mcp-bridge/main.d.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "believe_me undermines formal verification (1 occurrences, CWE-704)",
    "type": "believe_me",
    "file": "/home/runner/work/boj-server/boj-server/src/abi/Boj/SafeHTTP.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

…ELOPERS, add subdir READMEs Continues the rsr-template-repo alignment. Three batches in this commit: 1. Format conversions (.md -> .adoc) for docs/ root files that the policy says should be AsciiDoc: docs/ABI-FFI-README.md -> docs/ABI-FFI-README.adoc docs/AI-CONVENTIONS.md -> docs/AI-CONVENTIONS.adoc docs/API-CONTRACT.md -> docs/API-CONTRACT.adoc docs/CULTURAL-RESPECT.md -> docs/CULTURAL-RESPECT.adoc docs/EXTENSIBILITY.md -> docs/EXTENSIBILITY.adoc docs/FEDERATION.md -> docs/FEDERATION.adoc docs/READINESS.md -> docs/READINESS.adoc docs/THREAT-MODEL.md -> docs/THREAT-MODEL.adoc 2. Relocations (file becomes the canonical README for its directory): docs/ARCHITECTURE.md -> docs/architecture/README.adoc docs/DEVELOPERS.md -> docs/developer/README.adoc 3. New subdirectory orientation READMEs so the taxonomy is self-documenting: docs/quickstarts/README.adoc -- chooses USER vs DEV vs MAINTAINER docs/status/README.adoc -- explains the ROADMAP/FUTURE/etc. layer docs/wikis/README.adoc -- maps to the five wiki pages Bulk cross-reference rewrite (sed-based) handled 55 cartridge READMEs, 9 architecture/wiki/governance docs, the Justfile, copilot instructions, SECURITY.md, the Catalogue Idris source, src/abi and ffi/zig READMEs, k8s/service.yaml, mcp-bridge/lib/api-clients.js, and miscellaneous outreach/practice docs -- a total of 99 files updated. Historical mentions inside CHANGELOG.md and the timestamped log entries in .machine_readable/6a2/STATE.a2ml are left intact. docs/READINESS.adoc deliberately stays at docs/ root (not moved into docs/status/) because 55+ cartridge READMEs link to the canonical docs/READINESS path; moving it would have rippled across 60+ more files for limited taxonomic benefit. status/README.adoc explains the exception.

github-actions · 2026-05-26T00:12:43Z

🔍 Hypatia Security Scan

Findings: 251 issues detected

Severity	Count
🔴 Critical	18
🟠 High	223
🟡 Medium	10

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Stale AI session file -- delete",
    "type": "stale",
    "file": "GEMINI.md",
    "action": "delete",
    "rule_module": "root_hygiene",
    "severity": "medium"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/sanctify-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/academic-workflow-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/fireflag-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/ephapax-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/bofig-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/hesiod-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/mcp-bridge/main.d.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "believe_me undermines formal verification (1 occurrences, CWE-704)",
    "type": "believe_me",
    "file": "/home/runner/work/boj-server/boj-server/src/abi/Boj/SafeHTTP.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

…ocs/*.md content Three substantive quickstart docs lived at docs/ root, while the quickstarts/ dir I created earlier carried only 39/40-line stubs inherited from the root QUICKSTART-DEV.adoc / QUICKSTART-MAINTAINER.adoc. The .md versions were the canonical content — fold them in. docs/QUICKSTART.md (72 lines) -> docs/quickstarts/DEV.adoc (replaces 39-line stub) docs/GETTING-STARTED.md (198 lines) -> docs/quickstarts/BUILD-FROM-SOURCE.adoc (new sibling) docs/OPERATOR-QUICKSTART.md (296 lines) -> docs/quickstarts/MAINTAINER.adoc (replaces 40-line stub) DEV.adoc is now the 60-second "I want it running" path; the longer BUILD-FROM-SOURCE.adoc covers the full Zig FFI + Elixir REST + Idris2 ABI build process for contributors who need to modify the layers. Keeping them as separate documents (rather than collapsing into one DEV.adoc) preserves the natural read-time split: developers who want to use BoJ vs. developers who want to extend it. docs/quickstarts/README.adoc updated to list all four documents and explain when to pick which. Cross-reference rewrite handled Mustfile, flake.nix's docs-install command, the CRG-LIFT-PLAN-2026-04-18 audit, and two outreach drafts that linked to the old paths.

github-actions · 2026-05-26T00:14:53Z

🔍 Hypatia Security Scan

Findings: 251 issues detected

Severity	Count
🔴 Critical	18
🟠 High	223
🟡 Medium	10

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Stale AI session file -- delete",
    "type": "stale",
    "file": "GEMINI.md",
    "action": "delete",
    "rule_module": "root_hygiene",
    "severity": "medium"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/sanctify-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/academic-workflow-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/fireflag-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/ephapax-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/bofig-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/hesiod-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/mcp-bridge/main.d.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "believe_me undermines formal verification (1 occurrences, CWE-704)",
    "type": "believe_me",
    "file": "/home/runner/work/boj-server/boj-server/src/abi/Boj/SafeHTTP.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

…M-MCP-BRIDGE conversion docs/README.adoc was stale — it linked to ARCHITECTURE.md, DEVELOPERS.md, FEDERATION.md etc. as if they were still .md files at docs/ root. After the four prior commits those paths no longer exist (relocated into architecture/, developer/, or format-converted). Rewriting the index in full so it accurately reflects the current taxonomy. The new index has three sections: 1. Reading order by audience — table answering "if you are X, start with Y". Covers new users, MCP-client setup, federation operators, developers (run vs. build), architecture work, cartridge contribution, formal-verification audit, security review. 2. Directory taxonomy — table mapping each docs/<subdir>/ to its contents. Includes quickstarts/, wikis/, architecture/, status/, developer/, governance/, decisions/, specification/, integration/, backend-assurance/, compliance/, practice/, proposals/, attribution/, accessibility/, papers/, examples/, glama/, outreach/, handover/, maintenance/. 3. Standalone docs/ root files — the AsciiDoc reference docs that don't fit a subdir (EXPLAINME, API-CONTRACT, RSR_OUTLINE, READINESS, EXTENSIBILITY, FEDERATION, THREAT-MODEL, CULTURAL-RESPECT, AI-CONVENTIONS, AUTH-DESIGN, ABI-FFI-README, CITATIONS, TOPOLOGY-GUIDE, gateway-catalog-integration, index.html). 4. Related root-level files — pointers up one level to README.adoc, TOPOLOGY.md / PROOF-NEEDS.md / TEST-NEEDS.md (with explanation of why they remain at root pending coupling resolution), CHANGELOG.md, the .machine_readable/6a2/ canonical layer, and GEMINI.md (with the load-bearing rationale). Also folds in the last lone .md inside docs/architecture/: docs/architecture/TYPED-WASM-MCP-BRIDGE.md -> docs/architecture/TYPED-WASM-MCP-BRIDGE.adoc Cross-references updated.

github-actions · 2026-05-26T00:16:36Z

🔍 Hypatia Security Scan

Findings: 251 issues detected

Severity	Count
🔴 Critical	18
🟠 High	223
🟡 Medium	10

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Stale AI session file -- delete",
    "type": "stale",
    "file": "GEMINI.md",
    "action": "delete",
    "rule_module": "root_hygiene",
    "severity": "medium"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/sanctify-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/academic-workflow-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/fireflag-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/ephapax-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/bofig-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/hesiod-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/mcp-bridge/main.d.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "believe_me undermines formal verification (1 occurrences, CWE-704)",
    "type": "believe_me",
    "file": "/home/runner/work/boj-server/boj-server/src/abi/Boj/SafeHTTP.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

STATE.a2ml: add session log entry documenting PR #149 scope (taxonomy reorganisation, .md→.adoc conversions, README merge, subdir READMEs, corrected cartridge count 112→125) and known-deferred items. CHANGELOG: [Unreleased] Documentation section covering the same scope for human readers. https://claude.ai/code/session_018MBrAtPrwfgn2WG4BAerZW

github-actions · 2026-05-26T00:27:19Z

🔍 Hypatia Security Scan

Findings: 251 issues detected

Severity	Count
🔴 Critical	18
🟠 High	223
🟡 Medium	10

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Stale AI session file -- delete",
    "type": "stale",
    "file": "GEMINI.md",
    "action": "delete",
    "rule_module": "root_hygiene",
    "severity": "medium"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/sanctify-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/academic-workflow-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/fireflag-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/ephapax-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/bofig-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/hesiod-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/mcp-bridge/main.d.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "believe_me undermines formal verification (1 occurrences, CWE-704)",
    "type": "believe_me",
    "file": "/home/runner/work/boj-server/boj-server/src/abi/Boj/SafeHTTP.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

… elixir Two failing checks on PR #149 (and on every PR/main run since at least 2026-05-20) had four distinct root causes. Each fixed at source: ## Aspect — Thread Safety + ABI Contract + SPDX (27 → 0 failures) 1. **Comment-stripping filters were broken.** Aspect 2 (Idris2 banned patterns) used `grep -v '^\s*--'` and `grep -v '^\s*|||'` to skip line-comments and `|||` doc-comments — but `grep -rn` output is `path:lineno:content`, so the line never starts with `--` or `|||`; it starts with the path. The filters silently let every commented match through, producing two false-positive failures (Admitted in `cartridges/fleet-mcp/.../SafeFleet.idr` doc-comment + trailing `Echidnabot — ... (Admitted, sorry)` comment). Fixed by anchoring the filters at `:[[:space:]]*--` etc., factored into one `strip_comments_and_docstrings` helper that also handles trailing `-- … <pat>` comment matches. 2. **`believe_me` check didn't exempt class-J axioms.** `src/abi/Boj/ SafetyLemmas.idr` declares 5 documented class-J `believe_me` primitives (`charEqSound`, `charEqSym`, `unpackLength`, `appendLengthSum`, `substrLengthBound`) — see PROOF-NEEDS.md / ADR- 008. Added a `PROOF_EXEMPT` regex so the test passes on documented axioms while still failing on any new `believe_me` elsewhere. 3. **Aspect 1 Mutex check was over-aggressive.** It failed any .zig file with `pub export fn` + zero `Mutex` references — including purely-functional FFI like `cartridges/burble-admin-mcp/ffi/ burble_admin_ffi.zig` (3 exports, ZERO file-scope globals — table lookups + arithmetic over i32). 9 false-positive failures. The right invariant: only fail when there's ALSO file-scope mutable global state (`^(pub )?var <ident>`). Refined accordingly. Now reports purely-functional FFI with a clear pass message. 4. **Aspect 4 lacked a stub/ffi_only status.** 15 cartridges failed "incomplete layers (ABI=false ...)" — but ~10 of them are manifest-only stubs (cartridge.json declares the API surface, no abi/ or ffi/ yet) and ~5 are intentionally proof-free observability/glue (boj-health, claude-ai-mcp, lang-mcp, orchestrator-lsp-mcp, toolchain-mcp). Added a `"status"` field to `cartridge.json` (`complete` (default) / `stub` / `ffi_only`); Aspect 4 honours it and reports `(N complete, M stub, K ffi_only)` so the categories stay visible. 5. **ums-mcp had a real bug.** 15 C-ABI exports operating on a global `var sessions: [MAX_SESSIONS]SessionSlot` array, no Mutex. The filter fixes above narrow Aspect 1 to true positives, and this was the one left over. Added `var sessions_mu: std.Thread.Mutex` and `sessions_mu.lock(); defer sessions_mu.unlock();` to all 14 sessions-touching exports. `ums_can_transition` is a pure function (enum→enum) and stays lock-free. Mirrors the 007-mcp pattern (`g_state_mu` in `cartridges/007-mcp/ffi/oo7_mcp_ffi.zig:79`). `cd cartridges/ums-mcp/ffi && zig build` passes. After all five fixes: 115 passed / 0 failed / 1 warning (was 87/27/1). The one warning (`federation.zig` `catch unreachable` patterns) was already pre-existing — out of scope here. ## E2E — Full REST + MCP Bridge (failing since 2026-05-20) `tests/e2e_full.sh` requires `mix` to start the Elixir backend, but `.github/workflows/e2e.yml` never installed Elixir/OTP. Added an `erlef/setup-beam@v1.18.2` step (Elixir 1.18 + OTP 27 — matches the estate convention used in every other repo's hypatia-scan.yml) plus a `mix deps.get` step before the test runs. ## Foundational follow-up (NOT in this PR) Same gap as r-g-t-v#89 and absolute-zero#42: `main` branch protection has no `required_status_checks` block, which is how three workflows (E2E, OpenSSF Scorecard Enforcer, Instant Sync) have been failing on main for days without blocking merges. Hypatia PR #316 ships the BH001/BH002/BH003 rules that detect this class estate-wide. ## Test plan - [x] `bash tests/aspect_tests.sh` — 115/0/1 (was 87/27/1) - [x] `cd cartridges/ums-mcp/ffi && zig build` — clean - [x] All cartridge.json files still valid JSON - [x] e2e.yml YAML parses; step ordering correct (setup-beam before build-FFI / run-e2e) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

… (unblocks #149) (#150) ## Summary Two failing checks (Aspect 27 fails + E2E 1 fail) had four distinct root causes. Each fixed at source: ### Aspect — Thread Safety + ABI Contract + SPDX (27 → 0 fails) | # | Root cause | Fix | |---|---|---| | 1 | Comment filters broken — `^\s*--` / `^\s*\|\|\|` never matched because `grep -rn` output starts with `path:lineno:`, not content | Anchor at `:[[:space:]]*--` / `:[[:space:]]*\|\|\|` + add trailing `-- … <pat>` comment filter, factored into `strip_comments_and_docstrings` helper | | 2 | `believe_me` check didn't exempt the 5 documented class-J axioms in `src/abi/Boj/SafetyLemmas.idr` | Added `PROOF_EXEMPT` regex; passes on documented axioms, fails on any new use elsewhere | | 3 | Aspect 1 Mutex check fired on purely-functional FFI (e.g. `burble_admin_ffi.zig` — 3 exports, zero file-scope globals — table lookups over `i32`) | Refined to only fail when there's ALSO `^(pub )?var <ident>` file-scope global state. Purely-functional exports now get an explicit pass message | | 4 | Aspect 4 had no concept of stub-or-by-design cartridges — 15 fails for "incomplete layers" included 10 manifest-only stubs (cartridge.json declares API; abi/ ffi/ not yet written) and 5 intentionally proof-free observability/glue (boj-health, claude-ai-mcp, lang-mcp, orchestrator-lsp-mcp, toolchain-mcp) | Added `"status": "stub" \| "ffi_only" \| "complete"` (default `complete`) field to `cartridge.json`. Aspect 4 honours it and reports `(N complete, M stub, K ffi_only)` so categories stay visible in CI logs | | 5 | **Real bug**: `cartridges/ums-mcp/ffi/ums_ffi.zig` has 15 C-ABI exports operating on a global `var sessions: [MAX_SESSIONS]SessionSlot`, no Mutex. Once the filter fixes narrow Aspect 1 to true positives, this is the one that remains. | Added `var sessions_mu: std.Thread.Mutex` and `sessions_mu.lock(); defer sessions_mu.unlock();` to all 14 sessions-touching exports. `ums_can_transition` is pure (enum→enum) and stays lock-free. Mirrors `g_state_mu` in `cartridges/007-mcp/ffi/oo7_mcp_ffi.zig:79`. `zig build` passes | After all five: **115 passed / 0 failed / 1 warning** (was 87/27/1). The one warning (`federation.zig` `catch unreachable`) was pre-existing — out of scope here. ### E2E — Full REST + MCP Bridge (failing since 2026-05-20) `tests/e2e_full.sh` requires `mix` to start the Elixir backend, but `.github/workflows/e2e.yml` never installed Elixir/OTP. Added an `erlef/setup-beam@v1.18.2` step (Elixir 1.18 + OTP 27 — matches the estate convention used in every repo's hypatia-scan.yml) plus a `mix deps.get` step before the test runs. ## Test plan - [x] `bash tests/aspect_tests.sh` — 115/0/1 (was 87/27/1) - [x] `cd cartridges/ums-mcp/ffi && zig build` — clean - [x] All 15 `cartridge.json` files still valid JSON - [x] `e2e.yml` YAML parses; step ordering correct (setup-beam before build-FFI / run-e2e) ## Foundational follow-up (NOT in this PR — flagged) Same gap as `r-g-t-v#89` and `absolute-zero#42`: `main` branch protection has no `required_status_checks` block, so red-CI PRs can merge despite three workflows (E2E + Aspect + Bench, OpenSSF Scorecard Enforcer, Instant Sync) being persistently red on main. Hypatia PR #316 ships BH001/BH002/BH003 to detect this class estate-wide; the BH001 rule fires on exactly this repo. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

github-actions · 2026-05-26T01:28:27Z

🔍 Hypatia Security Scan

Findings: 251 issues detected

Severity	Count
🔴 Critical	18
🟠 High	223
🟡 Medium	10

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Stale AI session file -- delete",
    "type": "stale",
    "file": "GEMINI.md",
    "action": "delete",
    "rule_module": "root_hygiene",
    "severity": "medium"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/sanctify-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/academic-workflow-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/fireflag-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/ephapax-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/bofig-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/hesiod-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/mcp-bridge/main.d.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "believe_me undermines formal verification (1 occurrences, CWE-704)",
    "type": "believe_me",
    "file": "/home/runner/work/boj-server/boj-server/src/abi/Boj/SafeHTTP.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

claude added 3 commits May 25, 2026 19:26

Merge branch 'main' into claude/repo-tidy-rsr-taxonomy

e94cf90

hyperpolymath merged commit 645a80e into main May 26, 2026
27 of 31 checks passed

hyperpolymath deleted the claude/repo-tidy-rsr-taxonomy branch May 26, 2026 11:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Claude/repo tidy rsr taxonomy#149

Claude/repo tidy rsr taxonomy#149
hyperpolymath merged 8 commits into
mainfrom
claude/repo-tidy-rsr-taxonomy

hyperpolymath commented May 25, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 25, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 25, 2026

Uh oh!

github-actions Bot commented May 26, 2026

Uh oh!

github-actions Bot commented May 26, 2026

Uh oh!

github-actions Bot commented May 26, 2026

Uh oh!

github-actions Bot commented May 26, 2026

Uh oh!

github-actions Bot commented May 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

hyperpolymath commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes — six logical commits

Known-deferred (not in this PR — high coupling)

Issues + PRs

Cartridge-count drift

Test plan

Uh oh!

github-actions Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🏁 path-claims bench

Uh oh!

github-actions Bot commented May 25, 2026

🔍 Hypatia Security Scan

Uh oh!

github-actions Bot commented May 26, 2026

🔍 Hypatia Security Scan

Uh oh!

github-actions Bot commented May 26, 2026

🔍 Hypatia Security Scan

Uh oh!

github-actions Bot commented May 26, 2026

🔍 Hypatia Security Scan

Uh oh!

github-actions Bot commented May 26, 2026

🔍 Hypatia Security Scan

Uh oh!

github-actions Bot commented May 26, 2026

🔍 Hypatia Security Scan

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

hyperpolymath commented May 25, 2026 •

edited

Loading

github-actions Bot commented May 25, 2026 •

edited

Loading