docs: cartridge scaffolder + Phase 2b session (humans + machines) (#26)

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) <noreply@anthropic.com>

Author: hyperpolymath

.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

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 (`<iser>-mcp/`) from an `iseriser.toml` manifest. Emits 13 files: top-level (README + cartridge.json + mod.js + panels/manifest.json), Idris2 ABI (README + `<iser>-mcp.ipkg` + `<Iser>Mcp/Safe<Iser>.idr` with the exposure-gate contract), Zig FFI (README + `build.zig` + `<iser>_ffi.zig` implementing the ADR-0006 5-symbol C ABI), and the unified gated adapter (README + `build.zig` + `<iser>_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/<name>_adapter.zig` into new -iser repos. The unified transaction-gated adapter belongs to the boj-server cartridge for the -iser (`boj-server/cartridges/<name>-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

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 (`<iser>-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/<name>_adapter.zig` into new -iser repos. The unified transaction-gated adapter belongs to the boj-server cartridge for the -iser (`boj-server/cartridges/<name>-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
 

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 (`<iser>-mcp/`) for the manifest's -iser — adapter + FFI + ABI + cartridge.json + panels + mod.js. Output goes to `<output>/<iser>-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: