Skip to content

feat(cartridges): canonicalise BoJ cartridge format in standards/#200

Merged
hyperpolymath merged 1 commit into
mainfrom
feat/cartridge-format-spec
May 26, 2026
Merged

feat(cartridges): canonicalise BoJ cartridge format in standards/#200
hyperpolymath merged 1 commit into
mainfrom
feat/cartridge-format-spec

Conversation

@hyperpolymath
Copy link
Copy Markdown
Owner

Summary

Adds the canonical cartridge format specification + JSON schema as a new top-level standards/cartridges/ directory, plus ADR-002 ratifying standards as the canonical home with boj-server's local schema becoming a SHA-pinned mirror.

This is the foundational PR for an estate-wide initiative to (1) extract the 125 cartridges currently bundled in boj-server/cartridges/ into a new hyperpolymath/boj-server-cartridges repo with on-demand fetch, and (2) expand cartridge coverage beyond MCP into LSP/DAP/BSP/Format/Lint/Build/NeSy/Agentic/Fleet roles (using polystack's archived LSP code as the seed for the LSP halves).

Files

  • standards/cartridges/CARTRIDGE-FORMAT.adoc — prose spec
  • standards/cartridges/cartridge-v1.json — JSON Schema (canonical URL https://hyperpolymath.dev/standards/cartridges/cartridge-v1.json)
  • standards/cartridges/0.2-AI-MANIFEST.a2ml — directory manifest
  • standards/docs/decisions/ADR-002-cartridge-format-canonical-home.adoc — decision record

Key schema changes vs prior boj-server schema

  • Drops the -mcp-only name restriction. Cartridges may end in any canonical role suffix: (mcp|lsp|dap|bsp|debug|format|lint|build|nesy|agentic|fleet).
  • Adds required category (domain | cross-cutting | template).
  • Adds optional states (per panll v0.3.0) and source (registry + path + sha256).
  • Absorbs panll/src/abi/cartridge-schema.json v0.3.0's broader protocol set.

Companion / follow-up PRs (this session)

  • boj-server: replace its local schema with SHA-pinned mirror + add category field to 125 cartridges (mechanical sweep)
  • Create hyperpolymath/boj-server-cartridges repo + populate with copies (PR 2 in plan)
  • Cartridge minter tool (PR 3)
  • Catalog refactor for on-demand fetch (PR 4)
  • boj-server: remove cartridges/ dir (PR 5)
  • polystack 12 LSP halves → new cartridges (PR 6)
  • fleet-mcp redesign from poly-orchestrator-lsp (PR 7)

Test plan

  • Schema is self-consistent JSON
  • All commit GPG-signed
  • CI green
  • No code paths consume this spec yet; additive only

🤖 Generated with Claude Code

Adds the canonical cartridge format specification and JSON schema as a
new top-level standards/cartridges/ directory:

* CARTRIDGE-FORMAT.adoc — prose spec
* cartridge-v1.json — JSON Schema (canonical URL:
  https://hyperpolymath.dev/standards/cartridges/cartridge-v1.json)
* 0.2-AI-MANIFEST.a2ml — directory manifest

Plus docs/decisions/ADR-002-cartridge-format-canonical-home.adoc
ratifying standards as the canonical home, with boj-server's schema
becoming a SHA-pinned mirror.

The schema:

* Drops boj-server's `-mcp`-only name restriction. Cartridges may now end
  in any of the canonical role suffixes: mcp, lsp, dap, bsp, debug,
  format, lint, build, nesy, agentic, fleet — covering the full BoJ
  server-role taxonomy that panll/src/abi/cartridge-schema.json v0.3.0
  already enumerated.

* Adds `category` (domain | cross-cutting | template), `states`
  (state-machine states per panll v0.3.0), and `source` (registry +
  path + optional sha256 for remote-fetched cartridges).

* Preserves all existing required fields. Existing boj-server cartridge
  manifests remain valid against this schema once they gain the new
  required `category` field (mechanical sweep, separate PR).

This is the foundational PR for extracting cartridges out of boj-server
into a new boj-server-cartridges repository and expanding cartridge
coverage to LSP/DAP/BSP/Format/Lint/Build/NeSy/Agentic/Fleet beyond the
current MCP-only set. The follow-up PRs in this initiative will:

1. boj-server: replace boj-server/schemas/cartridge-v1.json with a
   SHA-pinned vendor of this canonical, update `$schema` URLs in all 125
   cartridges, and add `category` fields.
2. Create hyperpolymath/boj-server-cartridges repository.
3. Refactor boj-server's catalog (BojRest.Catalog) for on-demand fetch
   from the new registry.
4. Port polystack's LSP halves as cartridges in the new repo (12 LSPs).
5. Redesign poly-orchestrator-lsp as fleet-mcp.

No code paths consume this spec yet; CI surface is additive only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@hyperpolymath hyperpolymath enabled auto-merge (squash) May 26, 2026 12:41
hyperpolymath added a commit to hyperpolymath/boj-server that referenced this pull request May 26, 2026
…gory field sweep (#158)

## Summary
Three changes that prepare boj-server to consume cartridges from the new
[`hyperpolymath/boj-server-cartridges`](https://github.com/hyperpolymath/boj-server-cartridges)
repository on demand instead of bundling them in-tree:

### 1. Configurable cartridges root
`elixir/lib/boj_rest/application.ex` gains a fallback chain:
```
Application env (:boj_rest, :cartridges_root)
  → BOJ_CARTRIDGES_PATH environment variable
  → default "./cartridges" (preserves historical bundled behaviour)
```
Operators wanting on-demand fetch set `BOJ_CARTRIDGES_PATH` to their
local cache (e.g. `~/.boj/cartridges/`) and arrange for tray to populate
it. No runtime change unless the env var is set.

### 2. Canonical schema mirror
`schemas/cartridge-v1.json` is replaced with a vendored copy of the
canonical schema filed as
[standards#200](hyperpolymath/standards#200) —
which expands the original `-mcp`-only `name` regex to admit the full
BoJ server-role taxonomy:
`(mcp|lsp|dap|bsp|debug|format|lint|build|nesy|agentic|fleet)`, and adds
`category`, `states`, `source` fields. `schemas/SCHEMA-MIRROR.md`
documents the mirror discipline + the pending SHA-pinning ceremony
(executes once standards#200 merges).

### 3. `category` field sweep on 125 cartridge manifests
The new schema makes `category` required. Mechanical sweep assigns:
- `"category": "template"` (1: gossamer-mcp)
- `"category": "cross-cutting"` (11: agent-mcp, claude-agents-power-mcp,
claude-ai-mcp, local-coord-mcp, model-router-mcp, nesy-mcp, ml-mcp,
fleet-mcp, boj-health, dap-mcp, bsp-mcp)
- `"category": "domain"` (113)

Matches the taxonomy ratified in [boj-server-cartridges
ADR-001](https://github.com/hyperpolymath/boj-server-cartridges/blob/main/docs/decisions/ADR-001-taxonomy.adoc).

## Deferred to follow-up PRs
- tray → boj-server-cartridges on-demand fetch wiring (tray has the
cartridge-source subscription concept already in `tray/src/main.rs` /
`server.rs`; needs default registry configured).
- `BojRest.Catalog` reload-without-restart.
- Strict SHA-pin of local schema mirror to a specific standards commit +
sha256 (pending standards#200 merge).

## Test plan
- [x] All 125 cartridge manifests gain `category` field at correct value
- [x] Schema admits all 11 canonical role suffixes
- [x] `BOJ_CARTRIDGES_PATH=/foo bin/boj-server` would read from `/foo`
(manual trace)
- [x] Default behaviour unchanged when neither Application env nor
BOJ_CARTRIDGES_PATH set
- [ ] CI green
- [ ] Validate all 125 manifests against the new schema (follow-up;
tooling TBD)

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

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown

🔍 Hypatia Security Scan

Findings: 118 issues detected

Severity Count
🔴 Critical 64
🟠 High 43
🟡 Medium 11

⚠️ Action Required: Critical security issues found!

View findings
[
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/deno-ci-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "deno-ci-reusable.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance-reusable.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "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": "Python file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/standards/standards/a2ml-templates/state-scm-to-v2.py",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/standards/standards/a2ml/bindings/deno/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/standards/standards/lol/test/vitest.config.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/standards/standards/k9-svc/bindings/deno/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "Agda postulate assumes without proof -- potential soundness hole (4 occurrences, CWE-704)",
    "type": "agda_postulate",
    "file": "/home/runner/work/standards/standards/lol/proofs/theories/information_theory.agda",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  },
  {
    "reason": "believe_me undermines formal verification (1 occurrences, CWE-704)",
    "type": "believe_me",
    "file": "/home/runner/work/standards/standards/lol/src/abi/Locale.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  },
  {
    "reason": "Wildcard CORS -- restrict to specific origins or use env var (1 occurrences, CWE-942)",
    "type": "js_wildcard_cors",
    "file": "/home/runner/work/standards/standards/consent-aware-http/examples/reference-implementations/deno/aibdp_middleware.js",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "high"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

@hyperpolymath hyperpolymath merged commit 7c2b815 into main May 26, 2026
18 checks passed
@hyperpolymath hyperpolymath deleted the feat/cartridge-format-spec branch May 26, 2026 16:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant