k9-ecosystem: ANCHOR.a2ml SSOT keystone (hub canonical + satellite template) (#124)

Wires the `ANCHOR.a2ml` *pin + verify* SSOT model into the (now-merged)
k9-ecosystem hub. Keystone of the "full propagation" you asked for —
*one writer, many pinned readers, divergence that is loud*.

## This PR (the keystone)

Adds `k9-ecosystem/.machine_readable/anchors/`:

- **`ANCHOR.a2ml`** — the hub anchor: `authority = upstream-canonical`,
`semantic-authority.owns` the K9 spec (`spec/SPEC.adoc`) + conformance
suite, and publishes `[spec-version].current = 0.1.0-draft` (the version
satellites pin). The hub is itself declared a *satellite of
`developer-ecosystem`* for governance.
- **`SATELLITE-ANCHOR.template.a2ml`** — what each member copies to
`.machine_readable/anchors/ANCHOR.a2ml` (`authority = satellite` +
`[upstream]` pin).
- **`README.adoc`** — the per-artifact contract (spec pin / conformance
run / generated grammars / vendored-governance hashes) and the
anchor-drift enforcement plan.

## Remaining propagation (tracked; separate PRs per repo)

- [ ] `k9-rs`: flip `upstream-canonical → satellite` (it's reference
*behaviour*, not spec *authority*)
- [ ] satellite anchors stamped across `k9_ex`, `k9_gleam`, `k9-deno`,
`k9-haskell`, `pandoc-k9`, `k9-pre-commit`, `k9-showcase`
- [ ] **anchor-drift job** in `k9-validate-action` (the enforcer: pinned
`spec-version` must exist upstream; vendored hashes must match)
- [ ] generate-from-spec + regenerate-&-diff for `tree-sitter-k9` /
`vscode-k9`

🤖 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 Opus 4.8 <noreply@anthropic.com>

Author: hyperpolymath

k9-ecosystem/.machine_readable/anchors/ANCHOR.a2ml

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MPL-2.0
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+# ANCHOR.a2ml — authoritative anchor for the k9-ecosystem hub.
+
+[metadata]
+version = "1.0.0"
+last-updated = "2026-06-20"
+
+[anchor]
+schema = "hyperpolymath.anchor/1"
+repo = "hyperpolymath/k9-ecosystem"
+authority = "upstream-canonical"
+purpose = [
+  "Own the canonical K9 format specification and conformance suite.",
+  "Define what K9 implementations (satellites) may extend but not redefine.",
+  "Publish the spec version that every satellite must pin.",
+]
+
+[identity]
+project = "k9-ecosystem"
+kind = "specification-hub"
+one-sentence = "Canonical home of the K9 self-validating configuration format: owns the spec and conformance suite, aggregates the implementations and tooling."
+domain = "software-component-declaration"
+
+[semantic-authority]
+policy = "canonical"
+owns = [
+  "K9 format specification (spec/SPEC.adoc)",
+  "Conformance suite and reference behavior (conformance/fixtures/)",
+  "K9 invariant definitions and the SecurityLevel / Leash model",
+]
+
+[semantic-authority-files]
+language-spec = "spec/SPEC.adoc"
+conformance = "conformance/fixtures/"
+
+[spec-version]
+# The version satellites pin. Bump on ratified spec changes.
+current = "0.1.0-draft"
+
+[governance-authority]
+# The hub is itself a satellite of the estate standards for governance:
+# the anchor schema, contractile model, and ECOSYSTEM.a2ml meta-layer are owned upstream.
+upstream = "hyperpolymath/developer-ecosystem"
+pins-schema = "hyperpolymath.anchor/1"
+
+[satellite-policy]
+# Obligations the hub places on every K9 member (implementation / tooling / ci / examples):
+must-pin-upstream = true
+must-declare-authority = true
+must-have-anchor = true
+must-run-conformance = true
+
+[implementation-policy]
+allowed = ["AsciiDoc", "Markdown", "Nickel", "Just", "Shell", "TOML"]
+forbidden = ["Node.js", "npm"]
+
+[golden-path]
+smoke-test-command = ["just check-spec"]
+success-criteria = [
+  "spec/SPEC.adoc present and versioned",
+  "conformance/fixtures present",
+]

k9-ecosystem/.machine_readable/anchors/README.adoc

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MPL-2.0
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+= K9 Anchors — single source of truth, enforced
+
+The K9 format has *one writer and many pinned readers*. This directory holds the
+mechanism that keeps them from drifting silently.
+
+== Roles
+
+* `ANCHOR.a2ml` — the *hub* anchor. Declares `authority = upstream-canonical`
+  and `semantic-authority.owns` the K9 spec (`spec/SPEC.adoc`) and conformance
+  suite. Publishes `[spec-version].current` — the version every member pins. The
+  hub is itself a *satellite of `developer-ecosystem`* for governance.
+* `SATELLITE-ANCHOR.template.a2ml` — copied into each member repo as
+  `.machine_readable/anchors/ANCHOR.a2ml`, with `authority = satellite` and an
+  `[upstream]` block pinning `spec-version`.
+
+== The contract (pin + verify, not hardlink)
+
+[cols="1,2,2", options="header"]
+|===
+| Artifact | Pin | Drift check
+| Spec prose | satellite cites `spec-version` | anchor-drift job: pinned version must exist upstream
+| Conformance fixtures | submodule / published artifact | conformance run: impl output != `expected.json` -> red
+| Derived grammars (tree-sitter, TextMate, JSON schema) | generated from the spec | regenerate-&-diff job: stale -> red
+| Vendored governance | stamped via `{{OWNER}}` templating + content hash | `a2ml-validate-action` re-stamp, fail on hash diff
+|===
+
+The enforcer is `hyperpolymath/k9-validate-action`: an *anchor-drift* job asserts
+every satellite pins an existing upstream `spec-version` and (where vendored) that
+governance hashes match. A drifted satellite cannot merge — the CI check is the
+hardlink: versioned and loud.
+
+== Propagation status
+
+* [x] Hub anchor (this PR)
+* [ ] `k9-rs` flipped `upstream-canonical -> satellite` (reference behaviour, not spec authority)
+* [ ] Satellite anchors stamped across the remaining members
+* [ ] anchor-drift job added to `k9-validate-action`
+* [ ] generate-from-spec + regen-diff wired for `tree-sitter-k9` / `vscode-k9`

k9-ecosystem/.machine_readable/anchors/SATELLITE-ANCHOR.template.a2ml

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MPL-2.0
+# SPDX-FileCopyrightText: 2026 {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>
+# ANCHOR.a2ml — satellite anchor template. Copy into a K9 member repo at
+# .machine_readable/anchors/ANCHOR.a2ml and fill the {{...}} fields.
+
+[metadata]
+version = "1.0.0"
+last-updated = "{{CURRENT_DATE}}"
+
+[anchor]
+schema = "hyperpolymath.anchor/1"
+repo = "{{OWNER}}/{{REPO}}"
+authority = "satellite"
+
+[identity]
+project = "{{PROJECT_NAME}}"
+kind = "{{PROJECT_KIND}}"            # implementation | tooling | ci | examples
+one-sentence = "{{PROJECT_PURPOSE}}"
+
+[upstream]
+# Canonical owner of the K9 format. This satellite may extend but not redefine it.
+canonical = "hyperpolymath/k9-ecosystem"
+spec-version = "0.1.0-draft"          # MUST equal an existing k9-ecosystem [spec-version].current
+conformance = "hyperpolymath/k9-ecosystem//conformance/fixtures"
+
+[satellite-policy]
+must-pin-upstream = true
+must-run-conformance = true           # reproduce conformance fixtures' expected.json
+redefines-spec = false
+
+[golden-path]
+smoke-test-command = ["just test"]
+success-criteria = [
+  "Conformance fixtures reproduced",
+  "Pinned spec-version exists upstream",
+]