Skip to content

Commit 42db8f0

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
Add k9-ecosystem hub anchor + satellite template (SSOT keystone)
Establish the ANCHOR.a2ml pin+verify model for K9: the hub claims upstream-canonical semantic authority over spec/SPEC.adoc and the conformance suite, and publishes [spec-version].current as the version every member pins. Adds the satellite-anchor template members copy, and a README documenting the contract (spec pin, conformance run, generated grammars, vendored-governance hashes) and the anchor-drift enforcement to be added to k9-validate-action. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019i2e5ABGBKQmMdqk8puFWx
1 parent 22361a9 commit 42db8f0

3 files changed

Lines changed: 139 additions & 0 deletions

File tree

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

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# SPDX-License-Identifier: MPL-2.0
2+
# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
# ANCHOR.a2ml — authoritative anchor for the k9-ecosystem hub.
4+
5+
[metadata]
6+
version = "1.0.0"
7+
last-updated = "2026-06-20"
8+
9+
[anchor]
10+
schema = "hyperpolymath.anchor/1"
11+
repo = "hyperpolymath/k9-ecosystem"
12+
authority = "upstream-canonical"
13+
purpose = [
14+
"Own the canonical K9 format specification and conformance suite.",
15+
"Define what K9 implementations (satellites) may extend but not redefine.",
16+
"Publish the spec version that every satellite must pin.",
17+
]
18+
19+
[identity]
20+
project = "k9-ecosystem"
21+
kind = "specification-hub"
22+
one-sentence = "Canonical home of the K9 self-validating configuration format: owns the spec and conformance suite, aggregates the implementations and tooling."
23+
domain = "software-component-declaration"
24+
25+
[semantic-authority]
26+
policy = "canonical"
27+
owns = [
28+
"K9 format specification (spec/SPEC.adoc)",
29+
"Conformance suite and reference behavior (conformance/fixtures/)",
30+
"K9 invariant definitions and the SecurityLevel / Leash model",
31+
]
32+
33+
[semantic-authority-files]
34+
language-spec = "spec/SPEC.adoc"
35+
conformance = "conformance/fixtures/"
36+
37+
[spec-version]
38+
# The version satellites pin. Bump on ratified spec changes.
39+
current = "0.1.0-draft"
40+
41+
[governance-authority]
42+
# The hub is itself a satellite of the estate standards for governance:
43+
# the anchor schema, contractile model, and ECOSYSTEM.a2ml meta-layer are owned upstream.
44+
upstream = "hyperpolymath/developer-ecosystem"
45+
pins-schema = "hyperpolymath.anchor/1"
46+
47+
[satellite-policy]
48+
# Obligations the hub places on every K9 member (implementation / tooling / ci / examples):
49+
must-pin-upstream = true
50+
must-declare-authority = true
51+
must-have-anchor = true
52+
must-run-conformance = true
53+
54+
[implementation-policy]
55+
allowed = ["AsciiDoc", "Markdown", "Nickel", "Just", "Shell", "TOML"]
56+
forbidden = ["Node.js", "npm"]
57+
58+
[golden-path]
59+
smoke-test-command = ["just check-spec"]
60+
success-criteria = [
61+
"spec/SPEC.adoc present and versioned",
62+
"conformance/fixtures present",
63+
]

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

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

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# SPDX-License-Identifier: MPL-2.0
2+
# SPDX-FileCopyrightText: 2026 {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>
3+
# ANCHOR.a2ml — satellite anchor template. Copy into a K9 member repo at
4+
# .machine_readable/anchors/ANCHOR.a2ml and fill the {{...}} fields.
5+
6+
[metadata]
7+
version = "1.0.0"
8+
last-updated = "{{CURRENT_DATE}}"
9+
10+
[anchor]
11+
schema = "hyperpolymath.anchor/1"
12+
repo = "{{OWNER}}/{{REPO}}"
13+
authority = "satellite"
14+
15+
[identity]
16+
project = "{{PROJECT_NAME}}"
17+
kind = "{{PROJECT_KIND}}" # implementation | tooling | ci | examples
18+
one-sentence = "{{PROJECT_PURPOSE}}"
19+
20+
[upstream]
21+
# Canonical owner of the K9 format. This satellite may extend but not redefine it.
22+
canonical = "hyperpolymath/k9-ecosystem"
23+
spec-version = "0.1.0-draft" # MUST equal an existing k9-ecosystem [spec-version].current
24+
conformance = "hyperpolymath/k9-ecosystem//conformance/fixtures"
25+
26+
[satellite-policy]
27+
must-pin-upstream = true
28+
must-run-conformance = true # reproduce conformance fixtures' expected.json
29+
redefines-spec = false
30+
31+
[golden-path]
32+
smoke-test-command = ["just test"]
33+
success-criteria = [
34+
"Conformance fixtures reproduced",
35+
"Pinned spec-version exists upstream",
36+
]

0 commit comments

Comments
 (0)