coordination.k9

K9!
# SPDX-License-Identifier: MPL-2.0
# coordination.k9 — AI Coordination Protocol for standards
#
# This is the nerve receptor for the standards monorepo.
# It declares what this repo emits (afferent), responds to (efferent),
# and guards (reflex). It is also the reference implementation of the
# coordination.k9 format — this repo defines the format AND uses it.
#
# Conforms to 2-protocols/k9-coordination/spec/abnf/coordination-k9-grammar_v1.2.abnf.
# Repository facts that are not agent coordination were moved out 2026-10-13:
#   - the VeriSimDB port (8097) is set in .verisimdb/config.toml;
#   - the CRG grade is declared in the root READINESS.md, per
#     component-readiness-grades/COMPONENT-READINESS-GRADES.adoc.
#   A2ML is retired, so neither went there.
#
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)

metadata:
  schema: k9-coordination
  schema_version: 1.2.0
  generated_by: manual
  last_updated: 2026-10-14

project:
  name: "standards"
  description: "Constitutional authority for 290+ hyperpolymath repos. Defines CRG grades, RSR compliance, A2ML formats, K9 components, contractiles, protocol specs (Groove, AVOW, AXEL, Consent-Aware HTTP), and the innervation architecture that binds them."
  license: MPL-2.0
  repo: hyperpolymath/standards
  languages:
    - Rust
    - Zig
    - AffineScript
    - Idris2
    - JavaScript
    - Nickel
    - Julia
  build_system: just

build_commands:
  - command: "just build"
    purpose: "No-op: the canon ships specs (the k9 binding moved to hyperpolymath/k9-ecosystem)"
  - command: "just test"
    purpose: "Run the repository test suite (scripts/run-shell-test-suite.sh)"
  - command: "just lint"
    purpose: "Run the structural gates (delegates to just validate)"
  - command: "just fmt"
    purpose: "Format sources"
  - command: "just clean"
    purpose: "Clean build artefacts"
  - command: "just assail"
    purpose: "Run panic-attack pre-commit scan"
  - command: "just v1-audit"
    purpose: "Run release pre-flight audit"
  - command: "just doctor"
    purpose: "Self-diagnostic"

invariants:
  - id: a2ml-in-machine-readable
    rule: "A2ML files (STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK) MUST be in .machine_readable/ only — NEVER in root"
    reason: "Core structural invariant. Root-level A2ML files are out-of-date duplicates."
    severity: critical
  - id: no-banned-languages
    rule: "No TypeScript, ReScript, Python, Go, Java, Kotlin, Swift, Deno or yarn in any sub-project; Bun is the JS runtime and package manager"
    reason: "Language policy is the first standard this repo defines. Violating it here destroys credibility."
    severity: critical
  - id: specs-are-authoritative
    rule: "Specification documents in spec/ directories are the canonical truth. Implementations must conform to specs, not vice versa."
    reason: "Standards repo is spec-first. If code disagrees with spec, the code is wrong."
    severity: critical
  - id: self-dogfooding
    rule: "This repo MUST use every standard it defines: CRG grades, RSR compliance, K9 coordination, Hypatia scanning, A2ML metadata"
    reason: "A constitution that exempts itself from its own laws has no authority."
    severity: critical
  - id: ietf-draft-names-frozen
    rule: "IETF Internet-Draft names (draft-jewell-*) must NOT be renamed even if the project name changes"
    reason: "Draft names are formally registered identifiers. Renaming them breaks citation chains."
    severity: critical
  - id: mpl-code-cc-by-sa-prose
    rule: "Original code, configuration and scripts are MPL-2.0; prose documentation is CC-BY-SA-4.0. PMPL-1.0-or-later only in repos on the Palimpsest register (3-practice/LICENCE-POLICY.adoc Rule 2). Licence changes are owner-approved, per file."
    reason: "Owner rulings 2026-06-04 and 2026-10-13. 3-practice/LICENCE-POLICY.adoc is authoritative."
    severity: high
  - id: no-postulate-inflation
    rule: "Do not add new postulates/axioms without proof that they cannot be constructively proven"
    reason: "Postulates are technical debt in formal systems. Each one weakens the trust chain."
    severity: high
  - id: sha-pinned-actions
    rule: "All GitHub Actions must be SHA-pinned, not version-tagged"
    reason: "Version tags are mutable. SHA pins are immutable. This is a security invariant."
    severity: high

protected:
  - path: component-readiness-grades/
    reason: "CRG specification — the grading system used by 290+ repos"
  - path: rhodium-standard-repositories/
    reason: "RESIDUAL — only actions-allowlist/ remains here. It is a live published interface: allowed-actions.json is fetched by raw URL from allowlist-preflight-reusable.yml and governance-reusable.yml, so moving it breaks consumers outside this repo. Needs its own deprecation/redirect plan."
  - path: 9-archive/
    reason: "FROZEN ARCHIVE — the LAST COPY of dead upstream trees (rhodium-standard-repositories and its satellites). Not maintained, not to be edited for conformance: a change made here to satisfy a gate would falsify the historical record. Exempt from K9 validation and the debt ledger by .githooks/validate-k9.sh."
  - path: 1-formats/k9/
    reason: "K9 self-validating component specification"
  - path: 2-protocols/k9-coordination/
    reason: "K9 coordination protocol (this format's own spec)"
  - path: 2-protocols/groove/
    reason: "Groove inter-service communication protocol"
  - path: 2-protocols/avow/
    reason: "AVOW spam prevention protocol"
  - path: 2-protocols/axel/
    reason: "AXEL age-gating protocol"
  - path: 2-protocols/0-ai-gatekeeper/
    reason: "AI manifest enforcement system"
  - path: .machine_readable/
    reason: "Canonical A2ML metadata location"
  - path: coordination.k9
    reason: "This file — the nerve receptor"

architecture:
  - id: innervation-model
    decision: "Standards are moving from static 6a2 files to an innervation architecture: inline annotations + coordination.k9 + VeriSimDB + Hypatia + PanLL"
    reason: "The 6a2 model served well for 2025 but the ecosystem has outgrown static files. VeriSimDB, Hypatia, ECHIDNA, K9, and PanLL can carry the load with less overhead and more power."
    alternatives_rejected:
      - "Keep all 6 A2ML files per repo (too much overhead)"
      - "Single monolithic metadata file (loses semantic separation)"
      - "Pure database with no repo-local files (loses git auditability)"
  - id: specs-then-implementations
    decision: "This repo contains both specifications and reference implementations"
    reason: "The 'standards only, no code' non-goal was superseded. Specs without implementations are untestable."
  - id: monorepo-with-absorbed-satellites
    decision: "All 7 A2ML format specs are absorbed into this monorepo (since 2026-02-08)"
    reason: "Eliminates cross-repo synchronisation overhead. Single PR for spec changes."
  - id: k9-as-universal-receptor
    decision: "coordination.k9 replaces per-repo AGENTIC.a2ml + NEUROSYM.a2ml + parts of META.a2ml"
    reason: "K9 already has Must/Trust/Dust/Intent semantics. Extending it to carry agent constraints is natural."

# ─────────────────────────────────────────────────────────────
# Innervation — afferent/efferent/reflex
# ─────────────────────────────────────────────────────────────

innervation:
  afferent:
    - signal: "spec.updated"
      description: "A specification document changed"
      triggers_on: "push to spec/ directories"
      consumers:
        - hypatia
        - verisimdb
        - panll
    - signal: "proof.changed"
      description: "An Agda or Idris2 proof file was modified"
      triggers_on: "push to **/proofs/ or **/src/abi/"
      consumers:
        - echidna
        - verisimdb
    - signal: "crg.grade.assessed"
      description: "A CRG grade was assigned or changed"
      triggers_on: "change to component-readiness-grades/"
      consumers:
        - verisimdb
        - panll
    - signal: "test.results"
      description: "Test suite results from just test"
      triggers_on: "CI completion"
      consumers:
        - verisimdb
        - hypatia
  efferent:
    - signal: "hypatia.finding"
      action: "Log finding, update compliance scan octad in VeriSimDB"
      auto_fix: false
    - signal: "echidna.proof.stale"
      action: "Re-verify proof, update proof-status octad"
      auto_fix: true
    - signal: "ecosystem.link.stale"
      action: "Re-derive from imports, update Graph modality"
      auto_fix: true
  reflex:
    - trigger: "pre-commit"
      guard: "panic-attack assail"
      action: "Block commit if critical findings"
    - trigger: "file-create"
      guard: "No A2ML files in root directory"
      action: "Reject and suggest .machine_readable/"
    - trigger: "file-create"
      guard: "No banned language files (*.ts, *.res, *.py, *.go, *.java, *.kt)"
      action: "Reject with language policy link"

do_not_create:
  - pattern: **/*.ts
    reason: "TypeScript is banned — use AffineScript"
  - pattern: **/*.py
    reason: "Python is banned"
  - pattern: **/*.go
    reason: "Go is banned — use Rust"
  - pattern: Dockerfile
    reason: "Use Containerfile (Podman, not Docker)"
  - pattern: Makefile
    reason: "Use Justfile/Mustfile"
  - pattern: STATE.a2ml
    reason: "A2ML files go in .machine_readable/ only"
  - pattern: META.a2ml
    reason: "A2ML files go in .machine_readable/ only"

terminology:
  - correct: A2ML
    incorrect:
      - SCM
      - scm
    context: "The metadata format was renamed from SCM to A2ML. All references must use the new name."
  - correct: coordination.k9
    incorrect:
      - config-file
      - settings-file
    context: "The per-repo AI coordination file is coordination.k9 — it is a nerve receptor, not a config file or a settings file."
  - correct: innervation
    incorrect:
      - integration-layer
      - middleware
      - glue-code
    context: "The standards architecture is innervation — the nervous system runs through everything, not on top. Not an integration layer, middleware or glue code."

ecosystem:
  depends_on:
    - name: verisimdb
      role: "Knowledge graph — stores CRG grades, proof status, compliance evidence, ecosystem links"
    - name: hypatia
      role: "Enforcement layer — scans for violations, fires recipes"
    - name: echidna
      role: "Proof verification — Agda/Idris2 backend"
    - name: panic-attack
      role: "Pre-commit security scanning"
  consumed_by:
    - name: hyperpolymath-estate
      role: "The 290+ hyperpolymath repos: follow RSR, CRG, A2ML, K9, language policy, and other standards defined here"
    - name: panll
      role: "Visualises standards compliance via CRG Dashboard, Compliance Monitor, Proof Hub panels"
    - name: gitbot-fleet
      role: "Automated fixes based on standards compliance findings"
  related:
    - name: rsr-template-repo
      role: "Scaffolding template that implements standards for new repos"
    - name: palimpsest-license
      role: "License specification referenced by all repos"