Add k9-ecosystem aggregator hub (staged for extraction) (#120)

## What this is

A **decision + scaffold** for organising the 11-repo K9 family. After
weighing monorepo vs. polyrepo against your existing conventions, this
lands on a **hub + submodules** model: one `k9-ecosystem` hub that owns
the spec and conformance suite, with the implementations and tooling
kept as standalone repos and aggregated as git submodules.

The hub is authored as a **standalone repo root** but **staged under
`k9-ecosystem/`** here, because creating a new top-level repo was
outside this session's scope. Promotion to `hyperpolymath/k9-ecosystem`
is a one-command extraction — see `k9-ecosystem/BOOTSTRAP.md`.

## Why hub + submodules (not a monorepo, not scattered)

Several members **cannot** be subdirectories without breaking their
toolchains:

- `tree-sitter-k9` — the Tree-sitter CLI + bindings expect a repo named
`tree-sitter-*` at root
- `k9-validate-action` — consumed as `owner/repo@ref`; Marketplace needs
its own repo
- `k9-pre-commit` — consumers reference the repo URL;
`.pre-commit-hooks.yaml` at root
- `vscode-k9` — `vsce` per-extension publishing

…and the five implementations each publish to a different registry
(crates.io / Hex / Hackage / JSR) with independent versioning. A hub
still delivers one spec source-of-truth, one conformance suite, and one
front door — the same `satellites/` + `*-ecosystem/` submodule pattern
this repo already uses.

It's a **separate primary** (not nested) because developer-ecosystem's
charter is dev *workflow* tooling, whereas K9 is a configuration
*format*. Named `k9-ecosystem` because `k9-svc` already means the Rust
crate lib (`k9_svc`) and a `hyperpolymath/standards` entry.

## Contents (`k9-ecosystem/`)

| Area | Files |
|---|---|
| Front door | `README.adoc`, `members/README.adoc` |
| Members manifest | `.gitmodules` (11 repos: implementations / tooling
/ ci / examples) |
| Spec (source of truth) | `spec/SPEC.adoc` (v0.1 **draft**; `k9-rs`
normative until ratified), `spec/README.adoc` |
| Conformance | `conformance/README.adoc` +
`fixtures/minimal/{component.k9, expected.json}` |
| Orchestration | `Justfile`, `scripts/init-submodules.sh` |
| Governance | `.machine_readable/6a2/{ECOSYSTEM,STATE,META}.a2ml`,
`LICENSE`, `BOOTSTRAP.md` |

`developer-ecosystem`'s own `ECOSYSTEM.a2ml` / `STATE.a2ml` are indexed
to reference the staged hub.

## Status / how to promote

- [ ] Extract to standalone `hyperpolymath/k9-ecosystem` (`BOOTSTRAP.md`
option A), **or** add that repo to session scope and I'll push it
directly
- [ ] Run `scripts/init-submodules.sh` to populate the 11 submodules
- [ ] Cross-link each member's `6a2/ECOSYSTEM.a2ml` back to the hub
- [ ] Ratify `SPEC.adoc` and resolve its `[OPEN]` items via fixtures

Validated locally: `bash -n` on the script and JSON parse on the fixture
both pass. No submodules are actually cloned here (the staged
`.gitmodules` is inert until extraction), so this PR adds plain files
only.

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

https://claude.ai/code/session_019i2e5ABGBKQmMdqk8puFWx

---
_Generated by [Claude
Code](https://claude.ai/code/session_019i2e5ABGBKQmMdqk8puFWx)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -18,7 +18,7 @@ git-tools = ["git-hud", "gitloom", "git-reunify", "git-seo", "polysafe-gitfixer"
 repo-management = ["oikos", "robot-repo-automaton", "grim-repo", "robot-vacuum-cleaner"]
 scaffolding = ["scaffoldia"]
 developer-ux = ["rescript-evangeliser (→ nextgen-languages-evangeliser)", "recon-silly-ation", "nickel-config-reporter"]
-ecosystems = ["affinescript-ecosystem", "rescript-ecosystem", "zig-ecosystem", "v-ecosystem (legacy/community-handoff)", "deno-ecosystem", "julia-ecosystem", "coq-ecosystem", "idris2-ecosystem", "iser-tools"]
+ecosystems = ["affinescript-ecosystem", "rescript-ecosystem", "zig-ecosystem", "v-ecosystem (legacy/community-handoff)", "deno-ecosystem", "julia-ecosystem", "coq-ecosystem", "idris2-ecosystem", "iser-tools", "k9-ecosystem (staged; pending extraction to standalone primary — see k9-ecosystem/BOOTSTRAP.md)"]
 cadre = ["cadre-router", "cadre-tea-router"]
 zig-api = ["zig-api (Phase 1+2 complete)"]
 

.machine_readable/6a2/STATE.a2ml

@@ -13,6 +13,10 @@ name = "developer-ecosystem"
 completion-percentage = 55
 phase = "license-stamps-flipped-to-MPL-2.0; bot_directives-rename-done; contractiles-currency-pass-2026-06-05"
 
+[session-2026-06-20-k9-ecosystem-scaffold]
+summary = "Scaffolded the k9-ecosystem aggregator hub under k9-ecosystem/ (staged for extraction to a standalone primary). Owns the K9 spec (spec/SPEC.adoc v0.1 draft) + conformance suite; aggregates 11 members (k9-rs/k9_ex/k9_gleam/k9-deno/k9-haskell + tree-sitter-k9/vscode-k9/pandoc-k9 + k9-validate-action/k9-pre-commit + k9-showcase) as git submodules via k9-ecosystem/.gitmodules. Added Justfile, scripts/init-submodules.sh, BOOTSTRAP.md, and 6a2 governance. Reasoning: members must stay standalone for their registries/toolchains; hub gives one spec + conformance source-of-truth. Staged here because a new top-level repo was outside session scope."
+files-changed = "18 (16 new under k9-ecosystem/, ECOSYSTEM.a2ml + STATE.a2ml indexed)"
+
 [session-2026-06-05-currency-checkpoint]
 summary = "Currency checkpoint (claude/zen-knuth-6hoEt branch). Tasks completed: (1) agent_instructions→bot_directives rename already done at root; external references fixed in 8 files across affinescript-ecosystem and rescript-ecosystem satellite subdirs. (2) Contractiles: INDEX.a2ml + _base.ncl added; missing verb dirs created (adjust/, bust/, intend/) each with Xfile.a2ml + canonical .ncl runner; must/trust/dust runners (must.ncl/trust.ncl/dust.ncl) added alongside existing Xfile.a2ml. (3) svc/k9 templates already present. (4) 6a2 files refreshed. (5) README/EXPLAINME currency-only fixes. (6) License scan flagged."
 files-changed = "~20 (currency + contractile files)"

k9-ecosystem/.gitignore

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: MPL-2.0
+# Submodule build artifacts (members manage their own; never commit theirs here)
+**/target/
+**/_build/
+**/build/
+**/node_modules/
+**/.deno/
+**/dist-newstyle/
+*.log
+.DS_Store

k9-ecosystem/.gitmodules

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MPL-2.0
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# K9 ecosystem members, grouped by role.
+# Inert while staged inside developer-ecosystem (git only reads the root
+# .gitmodules). Becomes active once this directory is extracted to its own
+# repository — see BOOTSTRAP.md.
+
+# --- Implementations -------------------------------------------------------
+[submodule "members/implementations/k9-rs"]
+	path = members/implementations/k9-rs
+	url = git@github.com:hyperpolymath/k9-rs.git
+[submodule "members/implementations/k9_ex"]
+	path = members/implementations/k9_ex
+	url = git@github.com:hyperpolymath/k9_ex.git
+[submodule "members/implementations/k9_gleam"]
+	path = members/implementations/k9_gleam
+	url = git@github.com:hyperpolymath/k9_gleam.git
+[submodule "members/implementations/k9-deno"]
+	path = members/implementations/k9-deno
+	url = git@github.com:hyperpolymath/k9-deno.git
+[submodule "members/implementations/k9-haskell"]
+	path = members/implementations/k9-haskell
+	url = git@github.com:hyperpolymath/k9-haskell.git
+
+# --- Tooling ---------------------------------------------------------------
+[submodule "members/tooling/tree-sitter-k9"]
+	path = members/tooling/tree-sitter-k9
+	url = git@github.com:hyperpolymath/tree-sitter-k9.git
+[submodule "members/tooling/vscode-k9"]
+	path = members/tooling/vscode-k9
+	url = git@github.com:hyperpolymath/vscode-k9.git
+[submodule "members/tooling/pandoc-k9"]
+	path = members/tooling/pandoc-k9
+	url = git@github.com:hyperpolymath/pandoc-k9.git
+
+# --- CI / validation -------------------------------------------------------
+[submodule "members/ci/k9-validate-action"]
+	path = members/ci/k9-validate-action
+	url = git@github.com:hyperpolymath/k9-validate-action.git
+[submodule "members/ci/k9-pre-commit"]
+	path = members/ci/k9-pre-commit
+	url = git@github.com:hyperpolymath/k9-pre-commit.git
+
+# --- Examples --------------------------------------------------------------
+[submodule "members/examples/k9-showcase"]
+	path = members/examples/k9-showcase
+	url = git@github.com:hyperpolymath/k9-showcase.git

k9-ecosystem/.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MPL-2.0
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+# ECOSYSTEM.a2ml — Ecosystem position
+
+[metadata]
+project = "k9-ecosystem"
+last-updated = "2026-06-20"
+ecosystem = "hyperpolymath"
+
+[position]
+type = "aggregator-hub"
+role = "canonical home of the K9 self-validating configuration format — owns the spec + conformance suite, aggregates the implementations and tooling as submodules"
+parent = "hyperpolymath estate"
+staged-in = "developer-ecosystem/k9-ecosystem (pending extraction to standalone repo — see BOOTSTRAP.md)"
+
+[members]
+# Aggregated as git submodules, grouped by role (see .gitmodules)
+implementations = ["k9-rs (reference, Rust/crates.io)", "k9_ex (Elixir/Hex)", "k9_gleam (Gleam/Hex)", "k9-deno (Deno/JSR)", "k9-haskell (Haskell/Hackage)"]
+tooling = ["tree-sitter-k9", "vscode-k9", "pandoc-k9"]
+ci = ["k9-validate-action", "k9-pre-commit"]
+examples = ["k9-showcase"]
+
+[owns]
+spec = "spec/SPEC.adoc (v0.1 draft; k9-rs normative until ratified)"
+conformance = "conformance/fixtures/ (canonical-projection golden tests, all implementations)"
+
+[related-projects]
+# relationship types: sibling-standard, dependency, dependent, inspiration, potential-consumer
+standards = { name = "hyperpolymath/standards", relationship = "dependent", note = "references k9-svc as a reusable standard" }
+developer-ecosystem = { name = "developer-ecosystem", relationship = "dependent", note = "contractile tridents consume .k9.ncl (k9.ncl); also potential dev-ux home for vscode-k9" }
+
+[integration-points]
+# Each implementation member is obligated to run conformance/fixtures/.

k9-ecosystem/.machine_readable/6a2/META.a2ml

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: MPL-2.0
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+# META.a2ml — Architecture decisions and development practices
+
+[metadata]
+project = "k9-ecosystem"
+last-updated = "2026-06-20"
+
+[decision.hub-plus-submodules]
+status = "accepted"
+date = "2026-06-20"
+decision = "Aggregate the K9 family as a hub repo with members as git submodules, rather than a single monorepo or scattered standalone repos."
+rationale = "Several members cannot be subdirectories without breaking their toolchains: tree-sitter-k9 (tree-sitter CLI + bindings expect a repo named tree-sitter-* at root), k9-validate-action (consumed as owner/repo@ref; Marketplace needs its own repo), k9-pre-commit (consumers reference the repo URL; .pre-commit-hooks.yaml at root), vscode-k9 (vsce per-extension publishing). The five implementations each publish to a different registry (crates.io/Hex/Hackage/JSR) with independent versioning. A hub still gives one spec source-of-truth, one conformance suite, and one front door."
+follows = "developer-ecosystem satellites + *-ecosystem submodule pattern"
+
+[decision.standalone-primary]
+status = "accepted"
+date = "2026-06-20"
+decision = "k9-ecosystem is its own top-level primary, not nested under developer-ecosystem."
+rationale = "developer-ecosystem's charter is developer workflow tooling; K9 is a configuration format/standard with a different audience. Nesting muddies both charters. Staged inside developer-ecosystem only as a delivery vehicle (session scope); end-state is standalone (BOOTSTRAP.md)."
+
+[decision.naming]
+status = "accepted"
+date = "2026-06-20"
+decision = "Umbrella named 'k9-ecosystem', not 'k9-svc'."
+rationale = "k9-svc is already the Rust crate lib name (k9_svc, 'self-validating configuration') and a referenced standard in hyperpolymath/standards; reusing it as the umbrella would collide. 'k9-ecosystem' matches the estate's *-ecosystem convention."
+
+[practices]
+spec-first = "Format changes land in spec/ first, gated by conformance/ fixtures, then propagate to implementations."
+spdx = "MPL-2.0 SPDX header on every file."
+languages = "Docs in AsciiDoc/Markdown; machine-readable in .a2ml (TOML); orchestration in just + minimal Bash; configs in Nickel. No banned languages introduced."

k9-ecosystem/.machine_readable/6a2/STATE.a2ml

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MPL-2.0
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+# STATE.a2ml — Project state checkpoint
+
+[metadata]
+project = "k9-ecosystem"
+version = "0.1.0"
+last-updated = "2026-06-20"
+status = "scaffolded"
+
+[project-context]
+name = "k9-ecosystem"
+completion-percentage = 20
+phase = "hub scaffolded and staged inside developer-ecosystem; awaiting extraction to standalone repo and live submodule wiring"
+
+[session-2026-06-20-hub-scaffold]
+summary = "Created the k9-ecosystem aggregator hub: README, .gitmodules (11 members grouped implementations/tooling/ci/examples), Justfile + scripts/init-submodules.sh, spec/SPEC.adoc (v0.1 draft) + spec/README, conformance/ suite with the 'minimal' fixture (component.k9.ncl + expected.json), members/README, LICENSE, BOOTSTRAP.md, and 6a2 governance. Staged at developer-ecosystem/k9-ecosystem/ because the session scope did not permit creating a new top-level repo."
+files-added = 16
+
+[session-2026-06-20-dogfood-fix]
+summary = "Fixed the Dogfood Gate 'Validate K9 contracts' failure on PR #120. The minimal fixture was a YAML-like sketch from the k9-rs README and lacked the K9! magic line and a 'pedigree = { }' block, so k9-validate-action errored. Rewrote it as a valid Nickel K9 contract (component.k9.ncl) modelled on the live corpus (K9! magic, SPDX, five-layer pedigree, 'Kennel leash), realigned expected.json and rewrote spec/SPEC.adoc to the actually-enforced format. The other three red checks on the PR (workflow security linter, trufflehog, deno @cadre/router duplicate) are pre-existing on main and untouched by this diff."
+
+[next-actions]
+extract = "Promote to standalone hyperpolymath/k9-ecosystem (BOOTSTRAP.md option A)"
+wire = "Run scripts/init-submodules.sh to populate the 11 member submodules"
+cross-link = "Update each member's 6a2/ECOSYSTEM.a2ml to reference k9-ecosystem (bidirectional graph)"
+spec = "Ratify SPEC.adoc; resolve the [OPEN] items via conformance fixtures"
+
+[blockers]
+new-repo-scope = "Creating/pushing hyperpolymath/k9-ecosystem is outside this session's repo scope; needs scope grant or manual extraction"

k9-ecosystem/BOOTSTRAP.md

@@ -0,0 +1,55 @@
+<!-- SPDX-License-Identifier: MPL-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> -->
+
+# Bootstrapping `k9-ecosystem` into a standalone repository
+
+This directory was authored as the **standalone `k9-ecosystem` hub** but is
+currently **staged inside `developer-ecosystem/`** because the delivering
+session's scope did not permit creating a new top-level GitHub repository.
+Everything here is defined as if `k9-ecosystem/` were a repository root (its own
+`.gitmodules`, `README.adoc`, `LICENSE`, `.machine_readable/6a2/`), so promotion
+is mechanical.
+
+## Option A — extract preserving history (recommended)
+
+```sh
+# from the developer-ecosystem repo root
+git subtree split -P k9-ecosystem -b k9-ecosystem-export
+
+# create the empty repo hyperpolymath/k9-ecosystem on GitHub first, then:
+mkdir ../k9-ecosystem && cd ../k9-ecosystem
+git init
+git pull ../developer-ecosystem k9-ecosystem-export
+git remote add origin git@github.com:hyperpolymath/k9-ecosystem.git
+git push -u origin main
+
+# activate the members
+just init        # or: bash scripts/init-submodules.sh
+```
+
+## Option B — fresh start (no history)
+
+```sh
+cp -r developer-ecosystem/k9-ecosystem /path/to/k9-ecosystem
+cd /path/to/k9-ecosystem
+git init && git add -A && git commit -m "Initialise k9-ecosystem hub"
+git remote add origin git@github.com:hyperpolymath/k9-ecosystem.git
+git push -u origin main
+bash scripts/init-submodules.sh
+```
+
+## After extraction
+
+1. Copy the full MPL-2.0 text to `license/MPL-2.0.txt` (see `LICENSE`).
+2. Remove the staging copy from `developer-ecosystem/` and, if desired, add the
+   new repo back as a submodule or cross-reference it from
+   `developer-ecosystem/.machine_readable/6a2/ECOSYSTEM.a2ml`.
+3. Point each member repo's `.machine_readable/6a2/ECOSYSTEM.a2ml` at
+   `k9-ecosystem` (relationship `dependency` / `sibling-standard`) so the graph
+   is bidirectional.
+
+## Alternative: let the agent push it directly
+
+If you add `hyperpolymath/k9-ecosystem` to the session's repository scope (and
+create the empty repo), the agent can push the hub and open its PR directly,
+skipping the manual extraction above.

k9-ecosystem/Justfile

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: MPL-2.0
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# k9-ecosystem hub — submodule orchestration.
+# These recipes assume this directory is a repository root (post-extraction).
+
+# List available recipes
+default:
+    @just --list
+
+# Populate every member submodule
+init:
+    git submodule update --init --recursive
+
+# Add all members from scratch (first-time wiring; idempotent)
+wire:
+    bash scripts/init-submodules.sh
+
+# Fast-forward every member to its tracked commit
+update:
+    git submodule update --remote --merge
+
+# Show checkout state of every member
+status:
+    git submodule status --recursive
+
+# Run a command in every member, e.g. `just foreach 'git status -s'`
+foreach CMD:
+    git submodule foreach --recursive '{{CMD}}'
+
+# Verify the canonical spec and conformance fixtures are present
+check-spec:
+    test -f spec/SPEC.adoc && echo "spec present"
+    test -d conformance/fixtures && echo "conformance fixtures present"

k9-ecosystem/LICENSE

@@ -0,0 +1,14 @@
+SPDX-License-Identifier: MPL-2.0
+SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+
+This project is licensed under the Mozilla Public License, version 2.0
+(MPL-2.0-or-later), consistent with the hyperpolymath estate's Palimpsest
+philosophy.
+
+The canonical MPL-2.0 text is provided by the estate at
+`developer-ecosystem/license/` and by the upstream palimpsest-license
+repository. When this directory is extracted into its own repository, copy the
+full MPL-2.0 text to `license/MPL-2.0.txt` alongside this notice
+(see BOOTSTRAP.md).
+
+Each source file additionally carries an SPDX `License-Identifier` header.