From 2eba6484b076e1212fdc412e1b3dab3690d4541f Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 6 Oct 2026 21:50:06 +0100 Subject: [PATCH 1/2] docs(k9): make coordination spec 1.1.1 one file that parses Consolidate the K9 coordination spec into one file and patch the grammar to 1.1.1 (owner rulings D311, D317, D318). - Replace the flat spec with the _v1 text; drop the duplicate. - Grammar 1.1.1: languages: items nest one level under their key (indent2) like every other list; full-line # comments are allowed between sections (rule gap), still not within one; --- stays invalid. - Every spec example, the README minimal example and examples/minimal.k9 now parse under the ABNF (apg-js); planted controls (2-space languages item, comment inside a section, ---) are rejected. - Validation Rules rewritten from the ABNF; protected moved under Optional Sections with the fixed-order rule. - Fix links to the spec and grammar across chora, CHECKLIST and TESTING-TAXONOMY; repoint the hypatia baseline SD022 path. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01D6JVLvmCeSFGcY6jSNesbL --- .hypatia-baseline.json | 2 +- 2-protocols/chora/CHORA-SPEC.adoc | 2 +- 2-protocols/chora/README.adoc | 2 +- 2-protocols/k9-coordination/README.adoc | 22 +- .../k9-coordination/examples/minimal.k9 | 5 +- .../spec/COORDINATION-K9-SPEC.adoc | 247 ++++++++++++------ .../spec/COORDINATION-K9-SPEC_v1.adoc | 230 ---------------- .../abnf/coordination-k9-grammar_v1.1.abnf | 40 +-- .../substantial-completion/CHECKLIST.adoc | 2 +- .../TESTING-TAXONOMY.adoc | 4 +- 10 files changed, 204 insertions(+), 352 deletions(-) delete mode 100644 2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC_v1.adoc diff --git a/.hypatia-baseline.json b/.hypatia-baseline.json index 40b90b6ea..a7cd98ea3 100644 --- a/.hypatia-baseline.json +++ b/.hypatia-baseline.json @@ -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" diff --git a/2-protocols/chora/CHORA-SPEC.adoc b/2-protocols/chora/CHORA-SPEC.adoc index a3c6d2ac6..c476ed091 100644 --- a/2-protocols/chora/CHORA-SPEC.adoc +++ b/2-protocols/chora/CHORA-SPEC.adoc @@ -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 diff --git a/2-protocols/chora/README.adoc b/2-protocols/chora/README.adoc index a3c6d2ac6..c476ed091 100644 --- a/2-protocols/chora/README.adoc +++ b/2-protocols/chora/README.adoc @@ -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 diff --git a/2-protocols/k9-coordination/README.adoc b/2-protocols/k9-coordination/README.adoc index 2b1ecdf76..4b6dc4e1a 100644 --- a/2-protocols/k9-coordination/README.adoc +++ b/2-protocols/k9-coordination/README.adoc @@ -4,9 +4,9 @@ = K9 Coordination Protocol Jonathan D.A. Jewell -:version: 1.1.0 +:version: 1.1.1 :status: STABLE -:revdate: 2026-04-09 +:revdate: 2026-10-06 :toc: :toclevels: 2 @@ -15,7 +15,7 @@ Jonathan D.A. Jewell 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 @@ -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 @@ -123,9 +123,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. @@ -215,7 +216,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 @@ -410,11 +411,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 diff --git a/2-protocols/k9-coordination/examples/minimal.k9 b/2-protocols/k9-coordination/examples/minimal.k9 index 41fbabec6..b5a271452 100644 --- a/2-protocols/k9-coordination/examples/minimal.k9 +++ b/2-protocols/k9-coordination/examples/minimal.k9 @@ -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 @@ -27,7 +27,6 @@ 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" diff --git a/2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc b/2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc index 2dccf4722..7231e5fe5 100644 --- a/2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc +++ b/2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc @@ -1,78 +1,112 @@ -K9 Coordination File Specification -Table of Contents -Status -File Identity -Schema -Required Sections -Optional Sections -Validation Rules -Generator Behaviour -Relationship to Existing Files -Status -Draft — Version 1.0.0 +// SPDX-License-Identifier: CC-BY-SA-4.0 += K9 Coordination File Specification +Jonathan D.A. Jewell +:revdate: 2026-10-06 +:revnumber: 1.1.1 +:description: Schema specification for coordination.k9 files +:toc: -File Identity -Filename +== Status -coordination.k9 +Stable — Version 1.1.1. Owner ruling D311 (2026-10-06) made the 1.1 line +canonical; rulings D317 and D318 made the 1.1.1 grammar patch below. -Location +The normative grammar is +link:abnf/coordination-k9-grammar_v1.1.abnf[`coordination-k9-grammar_v1.1.abnf`]. +Where this prose, its examples or a generator disagree with the ABNF about +syntax, the ABNF wins. -Repository root +Every example in this document parses under that ABNF. Read them closely: +`repo:`, `pattern:` and `languages:` items are bare tokens, while +`alternatives_rejected:` items are quoted strings. Blank lines appear +between sections, never inside one. -K9 Level +NOTE: *Changes in 1.1.1.* Two grammar fixes, both owner rulings of +2026-10-06. (1) D317: `languages:` items are indented one level deeper than +their key (four spaces), as every other list already was; 1.1.0 placed them +at the key's own indent. (2) D318: full-line `#` comments are permitted +between sections, as blank lines are. They are not permitted within a +section, and a `---` separator is still invalid. -Kennel (pure data, no execution) +== File Identity -Magic Number +[cols="1,3"] +|=== +| Filename | `coordination.k9` +| Location | Repository root +| K9 Level | Kennel (pure data, no execution) +| Magic Number | `K9!` (mandatory first line) +| SPDX | `PMPL-1.0-or-later` (or project license) +|=== -K9! (mandatory first line) +== Schema -SPDX +=== Required Sections -PMPL-1.0-or-later (or project license) +==== `metadata` -Schema -Required Sections -metadata Identity and versioning for the coordination file itself. +[source,yaml] +---- metadata: schema: k9-coordination - schema_version: 1.0.0 + schema_version: 1.1.1 generated_by: k9-coordination-generator last_updated: 2026-04-03 -project +---- + +==== `project` + Core project identity. Tells any arriving agent what this project IS. +[source,yaml] +---- project: name: "project-name" description: "One-line description" license: PMPL-1.0-or-later - repo: "hyperpolymath/project-name" + repo: hyperpolymath/project-name languages: - ReScript - Rust build_system: just runtime: deno -invariants +---- + +==== `invariants` + Rules that MUST NOT be violated. Each invariant has an id, rule, and reason. +[source,yaml] +---- invariants: - id: no-typescript rule: "Do not introduce TypeScript files anywhere in this project" reason: "ReScript is the chosen frontend language — this is deliberate" severity: critical - - id: custom-tea-runtime rule: "Do not replace the custom TEA runtime in src/tea/" reason: "18-module custom build — rescript-tea was deliberately rejected" severity: critical -Severity levels: critical (never violate), high (ask user first), moderate (prefer compliance). +---- -protected -Files and directories that are architecturally significant and must not be deleted, reorganised, or replaced without explicit user approval. +Severity levels: `critical` (never violate), `high` (ask user first), +`moderate` (prefer compliance). +=== Optional Sections + +Optional sections appear in this fixed order, each at most once: +`protected`, `architecture`, `do_not_create`, `terminology`, `ecosystem`, +`coordination`. + +==== `protected` + +Files and directories that are architecturally significant and must not be +deleted, reorganised, or replaced without explicit user approval. + +[source,yaml] +---- protected: - path: src/tea/ reason: "Custom TEA runtime — 18 modules" @@ -80,37 +114,51 @@ protected: reason: "Canonical location for all A2ML state files" - path: coordination.k9 reason: "This file — source of truth for AI coordination" -Optional Sections -architecture +---- + +==== `architecture` + Deliberate architectural decisions that may look wrong to an unfamiliar agent. +[source,yaml] +---- architecture: - id: gossamer-not-tauri decision: "Gossamer (Zig + WebKitGTK) is the desktop backend" reason: "Migrated from Tauri 2.0 — this is the intended direction" alternatives_rejected: - - Tauri - - Electron - - native GTK - + - "Tauri" + - "Electron" + - "native GTK" - id: deno-npm-hybrid decision: "Deno orchestrates builds but npm used for ReScript compiler" reason: "ReScript compiler requires npm — this is the only exception" -do_not_create -Things that must NOT be introduced. Prevents well-meaning agents from creating parallel systems. +---- + +==== `do_not_create` +Things that must NOT be introduced. Prevents well-meaning agents from +creating parallel systems. + +[source,yaml] +---- do_not_create: - - pattern: "**/*.ts" + - pattern: **/*.ts reason: "TypeScript is banned — use ReScript" - - pattern: "Dockerfile" + - pattern: Dockerfile reason: "Use Containerfile (Podman, not Docker)" - - pattern: "package-lock.json" + - pattern: package-lock.json reason: "npm lock files banned — use deno.lock" - description: "REST API parallel to Groove endpoints" reason: "Groove is the inter-service protocol" -terminology +---- + +==== `terminology` + Correct terminology for this project. Prevents agents from using wrong names. +[source,yaml] +---- terminology: - correct: panels incorrect: @@ -118,9 +166,15 @@ terminology: - tabs - windows context: "PanLL UI elements are always called panels" -ecosystem -How this project relates to others. Helps agents understand what NOT to duplicate and where to look for related functionality. +---- + +==== `ecosystem` +How this project relates to others. Helps agents understand what NOT to +duplicate and where to look for related functionality. + +[source,yaml] +---- ecosystem: depends_on: - name: gossamer @@ -133,9 +187,14 @@ ecosystem: related: - name: typell role: "Type intelligence engine — cross-panel type checking" -coordination (Phase 2) +---- + +==== `coordination` (Phase 2) + Active agent work tracking. Updated by agents or tooling. +[source,yaml] +---- coordination: active: - agent: claude @@ -154,41 +213,55 @@ coordination: available: - "Documentation for new API surface" - "Integration tests for Groove handlers" -Validation Rules -File MUST start with K9! on line 1 - -metadata section MUST be present with schema: k9-coordination - -project section MUST be present - -invariants section MUST be present (even if empty list) - -Each invariant MUST have id, rule, and reason - -Each protected entry MUST have path and reason - -Severity defaults to critical if omitted - -Generator Behaviour -The generator reads coordination.k9 and emits one file per supported AI tool. All generated files: - -Start with a comment indicating they were generated from coordination.k9 - -Include a "do not edit directly" warning - -Render all sections as markdown appropriate for the target tool - -Are idempotent — re-running overwrites with current state - -Generated files SHOULD be committed to the repository so that AI tools which read them on startup get the coordination context immediately. - -Relationship to Existing Files -coordination.k9 does NOT replace: - -0-AI-MANIFEST.a2ml — the gateway file still serves as universal entry point - -.machine_readable/*.a2ml — state/meta files remain authoritative - -.claude/CLAUDE.md — can coexist; generated CLAUDE.md merges with existing - -The A2ML gateway SHOULD reference coordination.k9 in its inventory so agents following the gatekeeper protocol discover it. +---- + +== Validation Rules + +The ABNF is normative; these rules summarise it (1–10) and add the schema +rules a grammar cannot express (11–13). + +1. File MUST start with `K9!` on line 1, with no leading whitespace or BOM. +2. One or more `# SPDX-` header lines MUST immediately follow the magic line. +3. `metadata`, `project` and `invariants` MUST appear, in that order. +4. Optional sections MUST appear in the fixed order given above, each at + most once. `protected`, `architecture`, `do_not_create`, `terminology`, + `ecosystem` and `coordination` each need at least one entry when present; + `invariants` may be empty. +5. Indentation is exactly two spaces per level; tabs are invalid. +6. Blank lines and full-line `#` comments are permitted between sections, + not within them. A `---` separator is invalid. +7. Keys and enumerated values are case-sensitive (RFC 7405 `%s`). +8. Strings are double-quoted and support only the escapes `\"`, `\\`, + `\n` and `\t`. +9. `schema_version:` (and any `value`) may be a bare version such as + `1.1.1`, unquoted. +10. Dates are ISO 8601 calendar dates (`2026-10-06`) or full RFC 3339 + date-times (`2026-10-06T12:00:00.5+01:00`). Line endings are LF or CRLF. +11. `metadata` MUST carry `schema: k9-coordination`. +12. Each invariant MUST have `id`, `rule` and `reason`; each protected + entry MUST have `path` and `reason`. +13. Severity defaults to `critical` if omitted. + +== Generator Behaviour + +The generator reads `coordination.k9` and emits one file per supported AI tool. +All generated files: + +1. Start with a comment indicating they were generated from `coordination.k9` +2. Include a "do not edit directly" warning +3. Render all sections as markdown appropriate for the target tool +4. Are idempotent — re-running overwrites with current state + +Generated files SHOULD be committed to the repository so that AI tools +which read them on startup get the coordination context immediately. + +== Relationship to Existing Files + +`coordination.k9` does NOT replace: + +* `0-AI-MANIFEST.a2ml` — the gateway file still serves as universal entry point +* `.machine_readable/*.a2ml` — state/meta files remain authoritative +* `.claude/CLAUDE.md` — can coexist; generated CLAUDE.md merges with existing + +The A2ML gateway SHOULD reference `coordination.k9` in its inventory so +agents following the gatekeeper protocol discover it. diff --git a/2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC_v1.adoc b/2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC_v1.adoc deleted file mode 100644 index fc1d21c6e..000000000 --- a/2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC_v1.adoc +++ /dev/null @@ -1,230 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= K9 Coordination File Specification -Jonathan D.A. Jewell -:revdate: 2026-04-03 -:revnumber: 1.0.0 -:description: Schema specification for coordination.k9 files -:toc: - -== Status - -Draft — Version 1.0.0 - -== File Identity - -[cols="1,3"] -|=== -| Filename | `coordination.k9` -| Location | Repository root -| K9 Level | Kennel (pure data, no execution) -| Magic Number | `K9!` (mandatory first line) -| SPDX | `PMPL-1.0-or-later` (or project license) -|=== - -== Schema - -=== Required Sections - -==== `metadata` - -Identity and versioning for the coordination file itself. - -[source,yaml] ----- -metadata: - schema: k9-coordination - schema_version: 1.0.0 - generated_by: k9-coordination-generator - last_updated: 2026-04-03 ----- - -==== `project` - -Core project identity. Tells any arriving agent what this project IS. - -[source,yaml] ----- -project: - name: "project-name" - description: "One-line description" - license: PMPL-1.0-or-later - repo: "hyperpolymath/project-name" - languages: - - ReScript - - Rust - build_system: just - runtime: deno ----- - -==== `invariants` - -Rules that MUST NOT be violated. Each invariant has an id, rule, and reason. - -[source,yaml] ----- -invariants: - - id: no-typescript - rule: "Do not introduce TypeScript files anywhere in this project" - reason: "ReScript is the chosen frontend language — this is deliberate" - severity: critical - - - id: custom-tea-runtime - rule: "Do not replace the custom TEA runtime in src/tea/" - reason: "18-module custom build — rescript-tea was deliberately rejected" - severity: critical ----- - -Severity levels: `critical` (never violate), `high` (ask user first), -`moderate` (prefer compliance). - -==== `protected` - -Files and directories that are architecturally significant and must not be -deleted, reorganised, or replaced without explicit user approval. - -[source,yaml] ----- -protected: - - path: src/tea/ - reason: "Custom TEA runtime — 18 modules" - - path: .machine_readable/ - reason: "Canonical location for all A2ML state files" - - path: coordination.k9 - reason: "This file — source of truth for AI coordination" ----- - -=== Optional Sections - -==== `architecture` - -Deliberate architectural decisions that may look wrong to an unfamiliar agent. - -[source,yaml] ----- -architecture: - - id: gossamer-not-tauri - decision: "Gossamer (Zig + WebKitGTK) is the desktop backend" - reason: "Migrated from Tauri 2.0 — this is the intended direction" - alternatives_rejected: - - Tauri - - Electron - - native GTK - - - id: deno-npm-hybrid - decision: "Deno orchestrates builds but npm used for ReScript compiler" - reason: "ReScript compiler requires npm — this is the only exception" ----- - -==== `do_not_create` - -Things that must NOT be introduced. Prevents well-meaning agents from -creating parallel systems. - -[source,yaml] ----- -do_not_create: - - pattern: "**/*.ts" - reason: "TypeScript is banned — use ReScript" - - pattern: "Dockerfile" - reason: "Use Containerfile (Podman, not Docker)" - - pattern: "package-lock.json" - reason: "npm lock files banned — use deno.lock" - - description: "REST API parallel to Groove endpoints" - reason: "Groove is the inter-service protocol" ----- - -==== `terminology` - -Correct terminology for this project. Prevents agents from using wrong names. - -[source,yaml] ----- -terminology: - - correct: panels - incorrect: - - panes - - tabs - - windows - context: "PanLL UI elements are always called panels" ----- - -==== `ecosystem` - -How this project relates to others. Helps agents understand what NOT to -duplicate and where to look for related functionality. - -[source,yaml] ----- -ecosystem: - depends_on: - - name: gossamer - role: "Desktop backend (WebKitGTK + Zig)" - - name: verisimdb - role: "Persistent storage layer" - consumed_by: - - name: idaptik - role: "Uses PanLL as level editor" - related: - - name: typell - role: "Type intelligence engine — cross-panel type checking" ----- - -==== `coordination` (Phase 2) - -Active agent work tracking. Updated by agents or tooling. - -[source,yaml] ----- -coordination: - active: - - agent: claude - area: "ABI layer + Groove endpoints" - started: 2026-04-03 - status: in-progress - - agent: gemini - area: "Test coverage for auth module" - started: 2026-04-02 - status: blocked - blocker: "Waiting for upstream API key" - completed: - - agent: cursor - area: "CSS layout refactor" - completed: 2026-04-02 - available: - - "Documentation for new API surface" - - "Integration tests for Groove handlers" ----- - -== Validation Rules - -1. File MUST start with `K9!` on line 1 -2. `metadata` section MUST be present with `schema: k9-coordination` -3. `project` section MUST be present -4. `invariants` section MUST be present (even if empty list) -5. Each invariant MUST have `id`, `rule`, and `reason` -6. Each protected entry MUST have `path` and `reason` -7. Severity defaults to `critical` if omitted - -== Generator Behaviour - -The generator reads `coordination.k9` and emits one file per supported AI tool. -All generated files: - -1. Start with a comment indicating they were generated from `coordination.k9` -2. Include a "do not edit directly" warning -3. Render all sections as markdown appropriate for the target tool -4. Are idempotent — re-running overwrites with current state - -Generated files SHOULD be committed to the repository so that AI tools -which read them on startup get the coordination context immediately. - -== Relationship to Existing Files - -`coordination.k9` does NOT replace: - -* `0-AI-MANIFEST.a2ml` — the gateway file still serves as universal entry point -* `.machine_readable/*.a2ml` — state/meta files remain authoritative -* `.claude/CLAUDE.md` — can coexist; generated CLAUDE.md merges with existing - -The A2ML gateway SHOULD reference `coordination.k9` in its inventory so -agents following the gatekeeper protocol discover it. diff --git a/2-protocols/k9-coordination/spec/abnf/coordination-k9-grammar_v1.1.abnf b/2-protocols/k9-coordination/spec/abnf/coordination-k9-grammar_v1.1.abnf index bc95fde75..6b1bdc5a6 100644 --- a/2-protocols/k9-coordination/spec/abnf/coordination-k9-grammar_v1.1.abnf +++ b/2-protocols/k9-coordination/spec/abnf/coordination-k9-grammar_v1.1.abnf @@ -2,15 +2,21 @@ ; SPDX-License: MPL-2.0 ; SPDX-License-Identifier: CC-BY-SA-4.0 ; -; K9 Coordination File Grammar, v1.1.0 +; K9 Coordination File Grammar, v1.1.1 ; Normative for parsing coordination.k9 files -; Prose specification: ../specs/K9-COORDINATION-SPEC.adoc +; Prose specification: ../COORDINATION-K9-SPEC.adoc ; ; K9 is YAML-like but NOT standard YAML. It is a domain-specific ; coordination language with strict schema validation. ; ; Requires RFC 7405 (%s"..." case-sensitive string literals). ; +; CHANGELOG (v1.1.0 -> v1.1.1), owner rulings D317 + D318: +; - lang-list items are indented one level under "languages:" (indent2), +; the same nesting every other list follows (was: indent, a defect) +; - Full-line "#" comments are permitted between sections (rule gap); +; still not within a section; "---" separators remain invalid +; ; CHANGELOG (v1.0.0 → v1.1.0): ; - Added %s prefix for case-sensitive literals (RFC 7405) ; - Unified line endings to line-end (CRLF or LF) throughout @@ -23,7 +29,7 @@ ; - Required ≥1 entry in ecosystem / coordination sections ; - Fixed optional sections: explicit order, no duplicates -k9-file = magic-line line-end header *blank-line body +k9-file = magic-line line-end header *gap body ; --- Magic Number (REQUIRED first line) ---------------------------- magic-line = %s"K9!" @@ -32,21 +38,24 @@ magic-line = %s"K9!" header = 1*spdx-line spdx-line = "#" SP %s"SPDX-" 1*text-char line-end -; --- Blank Lines (permitted between sections, not within) ---------- +; --- Gaps between sections (not permitted within a section) -------- +; A gap is a blank line or a full-line comment starting in column 0. +gap = blank-line / comment-line blank-line = *SP line-end +comment-line = "#" *text-char line-end ; --- Body Structure ------------------------------------------------ ; Required sections MUST appear in this order. ; Optional sections MUST appear in the order shown; each at most once. -body = metadata-section *blank-line - project-section *blank-line - invariants-section *blank-line - [protected-section *blank-line] - [architecture-section *blank-line] - [do-not-create-section *blank-line] - [terminology-section *blank-line] - [ecosystem-section *blank-line] - [coordination-section *blank-line] +body = metadata-section *gap + project-section *gap + invariants-section *gap + [protected-section *gap] + [architecture-section *gap] + [do-not-create-section *gap] + [terminology-section *gap] + [ecosystem-section *gap] + [coordination-section *gap] ; --- Required Sections --------------------------------------------- @@ -70,7 +79,7 @@ project-field = indent %s"name:" SP string line-end / indent %s"build_system:" SP symbol line-end / indent %s"runtime:" SP symbol line-end -lang-list = 1*(indent "- " symbol line-end) +lang-list = 1*(indent2 "- " symbol line-end) invariants-section = %s"invariants:" line-end *invariant-entry ; May be empty @@ -203,6 +212,7 @@ line-end = CRLF / LF ; 5. Optional sections appear in fixed order; each at most once. ; 6. deed_ref links to a .deed file for typed identity. ; 7. Line endings may be CRLF or LF (mixing is permitted). -; 8. Blank lines are permitted between sections, not within them. +; 8. Blank lines and full-line "#" comments are permitted between +; sections, not within them. ; 9. Strings support escape sequences: \" \\ \n \t ; 10. Bare version numbers (e.g., 1.0.0) are valid unquoted values. diff --git a/3-practice/session-management-standards/verify/substantial-completion/CHECKLIST.adoc b/3-practice/session-management-standards/verify/substantial-completion/CHECKLIST.adoc index bd335e2c6..c835532c3 100644 --- a/3-practice/session-management-standards/verify/substantial-completion/CHECKLIST.adoc +++ b/3-practice/session-management-standards/verify/substantial-completion/CHECKLIST.adoc @@ -298,4 +298,4 @@ echo "✅ Substantial Completion Protocol: PASSED" - link:../../../publication-pre-flight/PREFLIGHT.adoc[Publication Pre-Flight Standard] - link:../../../component-readiness-grades/README.adoc[Component Readiness Grades] - link:../../../rhodium-standard-repositories/COMPLIANCE_CHECKLIST.md[RSR Compliance Checklist] -- link:../../../k9-coordination-protocol/README.adoc[K9 Coordination Protocol] +- link:../../../../2-protocols/k9-coordination/README.adoc[K9 Coordination Protocol] diff --git a/3-practice/testing-and-benchmarking/TESTING-TAXONOMY.adoc b/3-practice/testing-and-benchmarking/TESTING-TAXONOMY.adoc index c66e8c2de..0ba2de8c7 100644 --- a/3-practice/testing-and-benchmarking/TESTING-TAXONOMY.adoc +++ b/3-practice/testing-and-benchmarking/TESTING-TAXONOMY.adoc @@ -910,7 +910,7 @@ under-specified in this document itself: == Appendix C: Reference Implementation -The **K9 Coordination Protocol** (`standards/k9-coordination-protocol/`) serves as the +The **K9 Coordination Protocol** (`standards/2-protocols/k9-coordination/`) serves as the reference implementation for this taxonomy. It demonstrates: - **Full blitz assessment** against all 16 test categories and 14 aspect dimensions @@ -938,7 +938,7 @@ Test files: | `generator/bench.js` | Benchmarks | 6 |=== -See `standards/k9-coordination-protocol/READINESS.md` for the full assessment. +See `standards/2-protocols/k9-coordination/READINESS.adoc` for the full assessment. This implementation demonstrates that even a small CLI tool (single generator script, ~580 lines) can be thoroughly assessed against the full taxonomy. The key insight: From 7a80c71d67500246a01342ab6bc49017952e28a8 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 6 Oct 2026 21:50:42 +0100 Subject: [PATCH 2/2] docs(k9): retire the A2ML gateway from the discovery flow A2ML is retired (D308, D313) and descriptiles are clauses of the chora deed (D312). The README and spec still named 0-AI-MANIFEST.a2ml as the discovery gateway and .machine_readable *.a2ml files as authoritative. - Discovery starts at coordination.k9 in the repository root. - 0-AI-MANIFEST.a2ml is listed as legacy; its deed-era home stays an open owner decision (deed/mappings/ai-manifest-decision.adoc). - Example protected reasons no longer name A2ML. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01D6JVLvmCeSFGcY6jSNesbL --- 2-protocols/k9-coordination/README.adoc | 21 ++++++++++--------- .../k9-coordination/examples/minimal.k9 | 2 +- .../spec/COORDINATION-K9-SPEC.adoc | 13 +++++++----- 3 files changed, 20 insertions(+), 16 deletions(-) diff --git a/2-protocols/k9-coordination/README.adoc b/2-protocols/k9-coordination/README.adoc index 4b6dc4e1a..e3c9035a8 100644 --- a/2-protocols/k9-coordination/README.adoc +++ b/2-protocols/k9-coordination/README.adoc @@ -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 - → _chora.deed +coordination.k9 (repository root) + → project.deed_ref + → _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 `_chora.deed` (owner ruling D312), not in +separate `.a2ml` files. == Key Syntax Rules diff --git a/2-protocols/k9-coordination/examples/minimal.k9 b/2-protocols/k9-coordination/examples/minimal.k9 index b5a271452..5e678684f 100644 --- a/2-protocols/k9-coordination/examples/minimal.k9 +++ b/2-protocols/k9-coordination/examples/minimal.k9 @@ -34,6 +34,6 @@ invariants: 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" diff --git a/2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc b/2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc index 7231e5fe5..23bbd5149 100644 --- a/2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc +++ b/2-protocols/k9-coordination/spec/COORDINATION-K9-SPEC.adoc @@ -111,7 +111,7 @@ protected: - path: src/tea/ reason: "Custom TEA runtime — 18 modules" - path: .machine_readable/ - reason: "Canonical location for all A2ML state files" + reason: "Canonical location for machine-readable state" - path: coordination.k9 reason: "This file — source of truth for AI coordination" ---- @@ -259,9 +259,12 @@ which read them on startup get the coordination context immediately. `coordination.k9` does NOT replace: -* `0-AI-MANIFEST.a2ml` — the gateway file still serves as universal entry point -* `.machine_readable/*.a2ml` — state/meta files remain authoritative +* `_chora.deed` — typed identity and descriptive state + (descriptiles are its clauses, owner ruling D312); `project.deed_ref` + links to it * `.claude/CLAUDE.md` — can coexist; generated CLAUDE.md merges with existing -The A2ML gateway SHOULD reference `coordination.k9` in its inventory so -agents following the gatekeeper protocol discover it. +A2ML is retired (owner rulings D308, D313). A legacy +`0-AI-MANIFEST.a2ml` or `.machine_readable/*.a2ml` file is not +authoritative and is not a discovery path; agents discover +`coordination.k9` at the repository root.