coordination.k9

K9!
# SPDX-License-Identifier: PMPL-1.0-or-later
# 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.
#
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)

---
metadata:
  schema: k9-coordination
  schema_version: 1.0.0
  generated_by: manual
  last_updated: 2026-04-04

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: PMPL-1.0-or-later
  repo: "hyperpolymath/standards"
  languages:
    - Rust
    - Zig
    - ReScript
    - Idris2
    - Agda
    - JavaScript
    - Elixir
    - Nickel
  build_system: just
  crg_grade: B
  verisimdb_port: 8097

build_commands:
  just build: "Build all sub-project artefacts (Rust, Zig)"
  just test: "Run all 5 sub-project test suites (158+ tests)"
  just lint: "Lint Rust (clippy) and Deno sub-projects"
  just fmt: "Format Rust and Deno source"
  just clean: "Clean build artefacts"
  just assail: "Run panic-attack pre-commit scan"
  just v1-audit: "Run release pre-flight audit"
  just doctor: "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, Python, Go, Java, Kotlin, Swift, npm, Bun in any sub-project"
    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: pmpl-license-only
    rule: "All original code uses PMPL-1.0-or-later. MPL-2.0 fallback only where platform requires OSI approval."
    reason: "License consistency across the ecosystem."
    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: "RSR specification — the repo quality framework"
  - path: a2ml/
    reason: "A2ML format specification and reference implementation"
  - path: k9-svc/
    reason: "K9 self-validating component specification"
  - path: k9-coordination-protocol/
    reason: "K9 coordination protocol (this format's own spec)"
  - path: groove-protocol/
    reason: "Groove inter-service communication protocol"
  - path: avow-protocol/
    reason: "AVOW spam prevention protocol"
  - path: axel-protocol/
    reason: "AXEL age-gating protocol"
  - path: consent-aware-http/
    reason: "Consent-Aware HTTP specification (IETF draft)"
  - path: lol/
    reason: "LOL multilingual corpus — active, production-grade"
  - path: 0-ai-gatekeeper-protocol/
    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: what this repo emits to the nervous system
  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: what this repo responds to
  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: local guards that don't need central processing
  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, *.py, *.go, *.java, *.kt)"
      action: "Reject with language policy link"

do_not_create:
  - pattern: "**/*.ts"
    reason: "TypeScript is banned — use ReScript"
  - 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."
  - correct: innervation
    incorrect:
      - integration layer
      - middleware
      - glue code
    context: "The standards architecture is innervation — the nervous system runs through everything, not on top."

ports:
  verisimdb: 8097

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: "290+ hyperpolymath repos"
      role: "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"