From 9764e32cad57811201ed304a0d86db9e6b466d39 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 20 May 2026 12:08:59 +0100 Subject: [PATCH] docs: cartridge scaffolder + Phase 2b session (humans + machines) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For humans: - README.adoc: document the new `cartridge` subcommand under "Iseriser CLI subcommands" and add a paragraph cross-referencing standards#89 (Phase 2b) and standards#91 (the gating dependency for estate-wide fan-out). - CHANGELOG.adoc and CHANGELOG.md: 2026-05-20 entries covering PRs #23 (revert wrong-place adapter), #24 (cartridge scaffolder), and #25 (`depends = base, contrib` correction). Each entry names what shipped, why, and the PR that landed it. For machines: - .machine_readable/6a2/STATE.a2ml: bump last-updated to 2026-05-20, phase to phase-2b-complete, maturity to alpha, completion to 62. Add a new [capabilities] block enumerating the shipped subcommands (init / validate / generate / cartridge / info / scan / abi-verify / abi-emit-manifest) and a [recent-prs] block listing the session's three PRs by number. Refresh milestones, blockers, and next-actions to reflect that Phase 1, standards#92 Phase 1+1b, and standards#89 Phase 2b are all complete; remaining open items (standards#90 fan-out, #91 gateway, #92 drift sweep) are correctly parked. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) --- .machine_readable/6a2/STATE.a2ml | 52 ++++++++++++++++++++++++-------- CHANGELOG.adoc | 9 ++++++ CHANGELOG.md | 7 +++++ README.adoc | 9 ++++++ 4 files changed, 64 insertions(+), 13 deletions(-) diff --git a/.machine_readable/6a2/STATE.a2ml b/.machine_readable/6a2/STATE.a2ml index 31e7bb9..183f17e 100644 --- a/.machine_readable/6a2/STATE.a2ml +++ b/.machine_readable/6a2/STATE.a2ml @@ -5,36 +5,62 @@ [metadata] project = "iseriser" version = "0.1.0" -last-updated = "2026-04-04" +last-updated = "2026-05-20" status = "active" -session = "converted from scheme — 2026-04-11" +session = "standards#89 Phase 2b — cartridge scaffolder shipped" [project-context] name = "Iseriser" -purpose = """Meta-framework that generates new -iser projects from language descriptions""" -completion-percentage = 48 +purpose = """Meta-framework that generates new -iser projects from language descriptions, plus the boj-server cartridge skeleton that wires each -iser into the unified regeneration-cartridge pattern.""" +completion-percentage = 62 [position] -phase = "phase-1-complete" # design | implementation | testing | maintenance | archived -maturity = "experimental" # experimental | alpha | beta | production | lts +phase = "phase-2b-complete" # design | implementation | testing | maintenance | archived +maturity = "alpha" # experimental | alpha | beta | production | lts + +[capabilities] +# CLI subcommands shipped (as of 2026-05-20). +subcommands = [ + "init", # initialise an iseriser.toml manifest + "validate", # structural + semantic validation + "generate", # scaffold a complete -iser repo + "cartridge", # scaffold a boj-server cartridge skeleton (standards#89 Phase 2b) + "info", # print a summary of a manifest + "scan", # walk a repo and recommend -iser tools + "abi-verify", # diff Zig FFI vs Idris2 ABI manifest (standards#92 Phase 1) + "abi-emit-manifest", # derive ABI manifest from Safe*.idr (standards#92 Phase 1b) +] [route-to-mvp] milestones = [ - # No milestones recorded + "Phase 1 complete (2026-03-21) — scaffold, CLI, manifest parser, codegen, ABI types", + "standards#92 Phase 1 + 1b complete (2026-05-20) — abi-verify + abi-emit-manifest shipped", + "standards#89 Phase 2b complete (2026-05-20) — cartridge subcommand emits the full boj-server cartridge skeleton (PR #24)", ] [blockers-and-issues] +# All open work is correctly parked. No active iseriser-side blockers. issues = [ - "No blockers — Phase 1 complete, ready for Phase 2", + "standards#90 — regen.yml fan-out across the 28 -iser repos remains owed; gated on standards#91 (gateway tier-2)", + "standards#91 — http-capability-gateway tier-2 production-wiring; ~8-12wk programme; the real blocker for the public surface going live", + "standards#92 — Class B/C/D drift across ~15 cartridges (sub-issues #150-156); active PR train on the boj-server side", ] [critical-next-actions] actions = [ - "Begin Phase 2 — implement core domain logic for iseriser", - "Write property-based tests for manifest parsing", - "Define Idris2 ABI proof obligations for Phase 3", + "Standby for standards#91 to land before opening the 28-repo regen.yml fan-out", + "Continue the standards#92 drift sweep as Class B/C/D sub-issues land", + "Phase 3 (TBD) — explore generating the Zig FFI directly from the Idris2 ABI rather than the current scaffolded-once + hand-evolved pattern", +] + +[recent-prs] +# 2026-05-20 session — full provenance. +prs = [ + "#23 — revert wrong-place adapter emission (standards#89 sub-issue 1 follow-up)", + "#24 — cartridge scaffolder (standards#89 Phase 2b)", + "#25 — cartridge ipkg dep correction: depends = base, contrib", ] [maintenance-status] -last-run-utc = "2026-04-04T00:00:00Z" -last-result = "unknown" # unknown | pass | warn | fail +last-run-utc = "2026-05-20T11:30:00Z" +last-result = "pass" # unknown | pass | warn | fail diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 2152922..eeee192 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -8,6 +8,15 @@ All notable changes to iseriser will be documented in this file. This format is based on https://keepachangelog.com/en/1.1.0/[Keep a Changelog], and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Versioning]. +== [Unreleased] + +=== Added (2026-05-20) +* `cartridge` subcommand — scaffolds a complete boj-server cartridge skeleton (`-mcp/`) from an `iseriser.toml` manifest. Emits 13 files: top-level (README + cartridge.json + mod.js + panels/manifest.json), Idris2 ABI (README + `-mcp.ipkg` + `Mcp/Safe.idr` with the exposure-gate contract), Zig FFI (README + `build.zig` + `_ffi.zig` implementing the ADR-0006 5-symbol C ABI), and the unified gated adapter (README + `build.zig` + `_adapter.zig` routing REST/SSE/GraphQL/gRPC-compat behind the transaction gate). Modelled on the k9iser-mcp pilot (boj-server#73). Verified end-to-end: `idris2 --build`, `zig build test` on both `ffi/` and `adapter/`. Implements hyperpolymath/standards#89 Phase 2b. (PR #24) + +=== Changed (2026-05-20) +* Scaffolder no longer emits `adapter/_adapter.zig` into new -iser repos. The unified transaction-gated adapter belongs to the boj-server cartridge for the -iser (`boj-server/cartridges/-mcp/adapter/`), not to the -iser repo itself. Use the new `cartridge` subcommand to scaffold the cartridge. (PR #23, reverts the wrong-place emission added in #12.) +* Cartridge scaffolder emits `depends = base, contrib` on the generated `.ipkg` to match the pilot convention and ensure cartridge authors have `Data.List` / `Data.String` helpers available out of the box. (PR #25, corrects an inadvertent omission in #24.) + == [0.1.0] - 2026-03-21 === Phase 1 — RSR Compliance Sweep diff --git a/CHANGELOG.md b/CHANGELOG.md index 5db3fee..5528aab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added (2026-05-20) +- `cartridge` subcommand — scaffolds a complete boj-server cartridge skeleton (`-mcp/`) from an `iseriser.toml` manifest. Emits 13 files across `cartridge.json`, `mod.js`, `panels/`, `abi/` (Idris2), `ffi/` (Zig, ADR-0006 5-symbol C ABI), and `adapter/` (unified gated adapter, REST + SSE + GraphQL + gRPC-compat behind the transaction gate). Modelled on the k9iser-mcp pilot (boj-server#73). Implements [standards#89 Phase 2b](https://github.com/hyperpolymath/standards/issues/89). End-to-end verified: `idris2 --build`, `zig build test` on `ffi/` (4/4) and `adapter/` (5/5). (PR #24) + +### Changed (2026-05-20) +- Scaffolder no longer emits `adapter/_adapter.zig` into new -iser repos. The unified transaction-gated adapter belongs to the boj-server cartridge for the -iser (`boj-server/cartridges/-mcp/adapter/`), not to the -iser repo itself. Use the new `cartridge` subcommand to scaffold the cartridge. (PR #23, reverts the wrong-place emission added in #12.) +- Cartridge scaffolder emits `depends = base, contrib` on the generated `.ipkg` to match the pilot convention. (PR #25, corrects an omission in #24.) + ### Added (2026-04-04) - Criterion benchmark suite (`benches/iseriser_bench.rs`) — 8 benchmarks covering codegen performance and manifest parsing efficiency diff --git a/README.adoc b/README.adoc index 0f78b50..310de2b 100644 --- a/README.adoc +++ b/README.adoc @@ -328,6 +328,7 @@ In addition to scaffolding new -isers, iseriser itself ships with: | `init` | Initialise an `iseriser.toml` manifest in the current directory. | `validate` | Structural + semantic validation of an `iseriser.toml`. | `generate` | Scaffold a complete -iser repo from the manifest. +| `cartridge` | Scaffold a boj-server cartridge skeleton (`-mcp/`) for the manifest's -iser — adapter + FFI + ABI + cartridge.json + panels + mod.js. Output goes to `/-mcp/`; place inside `boj-server/cartridges/` so the emitted Zig build files resolve the shared invoke-shim. See `examples/cartridge-skeleton/README.adoc`. | `info` | Print a summary of a manifest. | `scan` | Walk a repository and recommend applicable -iser tools. | `abi-verify` | (Phase 1) Diff a cartridge's Zig FFI against its Idris2-derived ABI manifest; exit 0=clean, 2=drift. See `examples/abi-manifests/README.adoc` for the drift taxonomy. @@ -340,6 +341,14 @@ https://github.com/hyperpolymath/standards/issues/92[standards#92] `examples/abi-manifests/README.adoc` for the schema, the drift taxonomy, and end-to-end usage. +The `cartridge` subcommand implements +https://github.com/hyperpolymath/standards/issues/89[standards#89] +Phase 2b — the boj-server cartridge skeleton, modelled on the +k9iser-mcp pilot (boj-server#73). Estate-wide fan-out of the +regeneration-cartridge pattern is gated on +https://github.com/hyperpolymath/standards/issues/91[standards#91] +(http-capability-gateway tier-2 production-wiring). + == Generated Repo Structure When iseriser generates a new -iser, it produces: