Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .hypatia-baseline.json
Original file line number Diff line number Diff line change
Expand Up @@ -1260,7 +1260,7 @@
"severity": "medium",
"rule_module": "structural_drift",
"type": "SD022",
"file": "2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC_v1.adoc",
"file": "2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc",
"note": "TRACKED DEBT (hypatia triage 2026-09-22): illustrative spec content referencing another project's path; needs an owner eyes-check before editing.",
"expires_at": "2026-12-22",
"tracking_issue": "hyperpolymath/standards#945"
Expand Down
2 changes: 1 addition & 1 deletion 2-protocols/chora/CHORA-SPEC.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,7 @@ The chora is not a layer in a stack. It is a *hub*:

* link:DEED-GRAMMAR-SPEC.adoc[DEED Grammar Specification]
* link:../grammars/deed.abnf[DEED ABNF Grammar]
* link:K9-COORDINATION-SPEC.adoc[K9 Coordination Specification]
* link:../k9-coordination/spec/COORDINATION-K9-SPEC.adoc[K9 Coordination Specification]
* link:K9-DEED-INTEGRATION-GUIDE.adoc[K9 and DEED Integration Guide]

== License
Expand Down
2 changes: 1 addition & 1 deletion 2-protocols/chora/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,7 @@ The chora is not a layer in a stack. It is a *hub*:

* link:DEED-GRAMMAR-SPEC.adoc[DEED Grammar Specification]
* link:../grammars/deed.abnf[DEED ABNF Grammar]
* link:K9-COORDINATION-SPEC.adoc[K9 Coordination Specification]
* link:../k9-coordination/spec/COORDINATION-K9-SPEC.adoc[K9 Coordination Specification]
* link:K9-DEED-INTEGRATION-GUIDE.adoc[K9 and DEED Integration Guide]

== License
Expand Down
43 changes: 22 additions & 21 deletions 2-protocols/k9-coordination/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@

= K9 Coordination Protocol
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
:version: 1.1.0
:version: 1.1.1
:status: STABLE
:revdate: 2026-04-09
:revdate: 2026-10-06
:toc:
:toclevels: 2

Expand All @@ -15,7 +15,7 @@ Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
The K9 Coordination File Specification is *STABLE* at version {version}.

The normative parsing grammar is
link:grammars/k9.abnf[K9 ABNF v1.1.1]. If this README or the prose
link:spec/abnf/coordination-k9-grammar_v1.1.abnf[K9 Coordination ABNF v1.1.1]. If this README or the prose
specification disagrees with the ABNF about syntax, the ABNF wins.

The implementation roadmap is currently at *Phase 1*. The grammar already
Expand All @@ -35,7 +35,7 @@ K9 is a *Kennel-level* format: pure data with no execution, functions, or
evaluation.

K9 is YAML-like, but it is *not YAML*. Implementations MUST use a K9-aware
parser conforming to link:grammars/k9.abnf[k9.abnf], not a generic YAML
parser conforming to link:spec/abnf/coordination-k9-grammar_v1.1.abnf[coordination-k9-grammar_v1.1.abnf], not a generic YAML
parser.

== The Problem
Expand Down Expand Up @@ -90,22 +90,23 @@ the epistemic identity record.
`project.deed_ref`.

| `0-AI-MANIFEST.a2ml`
| Transitional
| Gateway used by existing agent-discovery tooling. It SHOULD point to the
K9 and DEED files.
| Legacy, pending migration
| A2ML is retired (owner rulings D308, D313). Existing copies are legacy;
never create a new one. Its deed-era home is an
open owner decision (`1-formats/deed/mappings/ai-manifest-decision.adoc`).
|===

The normal discovery flow is:
The discovery flow is:

----
0-AI-MANIFEST.a2ml
→ coordination.k9
→ project.deed_ref
→ <project>_chora.deed
coordination.k9 (repository root)
→ project.deed_ref
→ <project>_chora.deed
----

Agents that do not use the A2ML gateway MAY discover `coordination.k9`
directly at the repository root.
Descriptive state (state, meta, ecosystem, agentic, neurosym, playbook)
lives in clauses of `<project>_chora.deed` (owner ruling D312), not in
separate `.a2ml` files.

== Key Syntax Rules

Expand All @@ -123,9 +124,10 @@ A conforming `coordination.k9` file follows these rules:
. Files MUST be valid UTF-8 without a BOM.
. LF and CRLF line endings are accepted. Mixing them is permitted but
discouraged.
. Blank lines and full-line comments are permitted between sections.
. Blank lines and comments are not permitted within a section under the
current grammar.
. Blank lines and full-line `#` comments are permitted between sections,
not within a section. A `---` separator is invalid.
. List items are indented one level deeper than their key, including
`languages:` items (four spaces under the two-space key).
. Inline comments following a value are not supported.
. Strings use double quotes and support only `\"`, `\\`, `\n`, and `\t`
escapes.
Expand Down Expand Up @@ -215,7 +217,7 @@ K9!

metadata:
schema: k9-coordination
schema_version: 1.1.0
schema_version: 1.1.1
generated_by: k9-init
last_updated: 2026-04-09

Expand Down Expand Up @@ -410,11 +412,10 @@ If `deed_ref` is present:

== See Also

* link:specs/K9-COORDINATION-SPEC.adoc[K9 Coordination File Specification]
* link:grammars/k9.abnf[K9 ABNF Grammar]
* link:spec/COORDINATION-K9-SPEC.adoc[K9 Coordination File Specification]
* link:spec/abnf/coordination-k9-grammar_v1.1.abnf[K9 Coordination ABNF Grammar v1.1.1]
* link:examples/[Example K9 files]
* link:generator/[Generator tool]
* link:specs/K9-DEED-INTEGRATION-GUIDE.adoc[K9 and DEED Integration Guide]
* link:https://www.rfc-editor.org/rfc/rfc7405[RFC 7405 — Case-Sensitive ABNF Strings]

== Licence
Expand Down
7 changes: 3 additions & 4 deletions 2-protocols/k9-coordination/examples/minimal.k9
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,16 @@ K9!
# identity and a few critical invariants. Even this much prevents the
# most common AI agent mistakes.

---
metadata:
schema: k9-coordination
schema_version: 1.0.0
schema_version: 1.1.1
last_updated: 2026-04-03

project:
name: "my-project"
description: "A brief description of what this project does"
license: PMPL-1.0-or-later
repo: hyperpolymath/my-project
languages:
- Rust
- ReScript
Expand All @@ -27,14 +27,13 @@ invariants:
rule: "Do not introduce TypeScript — ReScript is the frontend language"
reason: "Deliberate ecosystem choice"
severity: critical

- id: no-docker
rule: "Use Containerfile, not Dockerfile — Podman is the container runtime"
reason: "Docker is not used in this ecosystem"
severity: high

protected:
- path: .machine_readable/
reason: "Canonical location for A2ML state files"
reason: "Canonical location for machine-readable state"
- path: coordination.k9
reason: "Source of truth for AI coordination"
Loading
Loading