From eb232eb622f6e85f9b59bf1843c3829d70039536 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 3 Jun 2026 15:59:01 +0000 Subject: [PATCH 1/4] feat(front-door): verifiable spec registry + routing + drift automation Turn the ~7,000-file monorepo into something an agent or human can read as one coherent thing OR jump straight to what they need, and wire it into the live drift-detection automation. New verifiable registry + generator - scripts/build-registry.sh: generates .machine_readable/REGISTRY.a2ml (one [[spec]] block per standard with home + content-addressed source_hash over `git ls-files -s `) and the DERIVED TOPOLOGY.md, from the file tree + STATE.a2ml. Honest by construction (only emits homes that exist), deterministic, idempotent. `just registry` / `just registry-check`. - .machine_readable/REGISTRY.a2ml: 28 specs across 6 streams. - REGISTRY.adoc: prose on the registry, source_hash, and the drift loop. Drift becomes a detected, routed finding (not noticed 60 days later) - .github/workflows/registry-verify.yml: CI fails on registry/topology drift. - hypatia-rules/registry-staleness.a2ml (HYP-S006): recomputes hashes, emits doc.drift; @router defaults to auto_execute (regenerate) but HARD-CAPS any licence/SPDX-overlapping drift to :review (Manual-Only guardrail). Front door + routing - README.adoc: 'Start Here' + 'if you want X, go here' routing table covering the three streams, the registry, A2ML/K9 foundation, protocols, readiness grades, enforcement/CI. - 0-AI-MANIFEST.a2ml: rewritten as the real machine entry (was a generic template) with machine routing + registry pointer + real invariants. Kill duplication / fix drift - TOPOLOGY.md: now DERIVED/generated (was hand-frozen at 2026-04-04, 80% while integration read 0%); SPDX header preserved. - EXPLAINME.adoc: thin stub (drops the drifted ReScript-as-Primary line and the dead groove-protocol/ + palimpsest-license/ local links; defers the spec inventory to the registry). - llm-warmup-{dev,user}.md: were byte-identical; now role-specific stubs. - QUICKSTART-{DEV,USER,MAINTAINER}.adoc: filled the {{PLACEHOLDER}} markers. - REORGANIZATION-PLAN.md: marked SUPERSEDED (premises predate the monorepo consolidation + registry); points at the new front door. Licence note: this commit only REMOVES now-false PMPL-1.0 claims (replaced with neutral 'see LICENSE' / Manual-Only wording) and asserts no identifier. No LICENSE file or SPDX header is edited; TOPOLOGY.md keeps its AGPL header. https://claude.ai/code/session_011xv3VLrqeXkpjXxUojKz82 --- .github/workflows/registry-verify.yml | 33 +++ .machine_readable/REGISTRY.a2ml | 282 ++++++++++++++++++++++++++ 0-AI-MANIFEST.a2ml | 181 +++++++---------- EXPLAINME.adoc | 168 ++++----------- Justfile | 17 ++ QUICKSTART-DEV.adoc | 59 ++++-- QUICKSTART-MAINTAINER.adoc | 26 ++- QUICKSTART-USER.adoc | 136 +++---------- README.adoc | 57 ++++++ REGISTRY.adoc | 115 +++++++++++ REORGANIZATION-PLAN.md | 24 +++ TOPOLOGY.md | 206 +++++++------------ hypatia-rules/README.adoc | 10 + hypatia-rules/registry-staleness.a2ml | 107 ++++++++++ llm-warmup-dev.md | 37 ++-- llm-warmup-user.md | 32 +-- scripts/build-registry.sh | 246 ++++++++++++++++++++++ 17 files changed, 1213 insertions(+), 523 deletions(-) create mode 100644 .github/workflows/registry-verify.yml create mode 100644 .machine_readable/REGISTRY.a2ml create mode 100644 REGISTRY.adoc create mode 100644 hypatia-rules/registry-staleness.a2ml create mode 100755 scripts/build-registry.sh diff --git a/.github/workflows/registry-verify.yml b/.github/workflows/registry-verify.yml new file mode 100644 index 00000000..6373cf9d --- /dev/null +++ b/.github/workflows/registry-verify.yml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: AGPL-3.0-or-later +# registry-verify — fail the build if the spec registry or the DERIVED +# topology map has drifted from the file tree. This is the in-repo half of +# the drift-detection loop (the estate half is Hypatia rule HYP-S006). +name: Registry Verify + +on: + push: + branches: [ main, master ] + pull_request: + branches: [ main, master ] + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + verify: + name: Registry + topology in sync + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + fetch-depth: 0 # full history so `git ls-files -s` hashes are stable + + - name: Verify registry + derived topology are current + run: | + bash scripts/build-registry.sh --check diff --git a/.machine_readable/REGISTRY.a2ml b/.machine_readable/REGISTRY.a2ml new file mode 100644 index 00000000..ff8e806e --- /dev/null +++ b/.machine_readable/REGISTRY.a2ml @@ -0,0 +1,282 @@ +# SPDX-License-Identifier: AGPL-3.0-or-later +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# REGISTRY.a2ml — the verifiable index of every spec/standard in this monorepo. +# +# GENERATED FILE — DO NOT EDIT BY HAND. +# Regenerate with: bash scripts/build-registry.sh (or: just registry) +# Source of truth: the SPECS table in scripts/build-registry.sh + the file tree. +# +# Each entry's `source_hash` is a sha256 over `git ls-files -s `, so it +# changes whenever any tracked file under the spec's home changes. Hypatia rule +# HYP-S006 (hypatia-rules/registry-staleness.a2ml) recomputes these and emits a +# `doc.drift` finding (strategy :review) when a recorded hash goes stale. + +[registry] +version = "1.0.0" +generated = "2026-06-02" +generator = "scripts/build-registry.sh" +hash_algorithm = "sha256(git ls-files -s )" +entry_count = 28 + +[registry.streams] +foundation = "A2ML format family + K9 + contractiles (Stream 1)" +language = "AffineScript and language-policy specs (Stream 2)" +protocol = "Inter-service / agent protocols" +governance = "RSR, readiness grading, pre-flight gates, session standards" +readiness = "ARG / FRG / CRG / TRG maturity-grading frameworks" +integration = "Registry, hypatia rules, templates — the wiring (Stream 3)" + +[[spec]] +id = "a2ml" +name = "A2ML — Attested Markup Language" +stream = "foundation" +home = "a2ml/" +canonical_doc = "a2ml/README.adoc" +source_hash = "sha256:b34ffe4d51c1715c4f2e51183d7a510865dc03e962fbeae121e3868fd88a718a" +route = "the typed/verified machine-readable document format" + +[[spec]] +id = "k9-svc" +name = "K9 Self-Validating Components" +stream = "foundation" +home = "k9-svc/" +canonical_doc = "k9-svc/README.adoc" +source_hash = "sha256:eae3b6a0f4e2da1afcfddfecf7a5c173d6c0ac090923c63fe9c14806b5a3b11b" +route = "self-validating components with embedded contracts + deploy logic" + +[[spec]] +id = "contractiles" +name = "Contractiles (Must/Trust/Dust/Intend)" +stream = "foundation" +home = "contractiles/" +canonical_doc = "contractiles/README.adoc" +source_hash = "sha256:628efcbff607cc7382280b52bf662c2c79801ae8f01b902f3aebe84b08dd79ad" +route = "policy-enforcement primitives the K9 layer is built from" + +[[spec]] +id = "meta-a2ml" +name = "META.a2ml spec" +stream = "foundation" +home = "meta-a2ml/" +canonical_doc = "meta-a2ml/README.adoc" +source_hash = "sha256:2904f47d20a79723a830674fd9dc14105bf14911b5f700586480fe3a7a424542" +route = "architecture decisions / governance metadata format" + +[[spec]] +id = "state-a2ml" +name = "STATE.a2ml spec" +stream = "foundation" +home = "state-a2ml/" +canonical_doc = "state-a2ml/README.adoc" +source_hash = "sha256:21d88102987bae7853cf8d642aeeba13efdeb1a105bbd4d89e7064ef15ce8b9d" +route = "project-state metadata format (drives this registry's topology)" + +[[spec]] +id = "ecosystem-a2ml" +name = "ECOSYSTEM.a2ml spec" +stream = "foundation" +home = "ecosystem-a2ml/" +canonical_doc = "ecosystem-a2ml/README.adoc" +source_hash = "sha256:46b529c177ddc2166bc2cdfdccc55fef8650e03f8d6b3a1ee25d70a494fb1626" +route = "ecosystem-positioning metadata format" + +[[spec]] +id = "agentic-a2ml" +name = "AGENTIC.a2ml spec" +stream = "foundation" +home = "agentic-a2ml/" +canonical_doc = "agentic-a2ml/README.adoc" +source_hash = "sha256:31832029e8e989e200b4022075ed0c8807bb95f55baa0cda11ce079d1bd5b900" +route = "AI-agent operational gating / entropy budgets" + +[[spec]] +id = "neurosym-a2ml" +name = "NEUROSYM.a2ml spec" +stream = "foundation" +home = "neurosym-a2ml/" +canonical_doc = "neurosym-a2ml/README.adoc" +source_hash = "sha256:62bbea52b4b57bb582cc79b320b97d2fced2bef41a77c33590211cbf4ddbd224" +route = "symbolic semantics / proof obligations" + +[[spec]] +id = "playbook-a2ml" +name = "PLAYBOOK.a2ml spec" +stream = "foundation" +home = "playbook-a2ml/" +canonical_doc = "playbook-a2ml/README.adoc" +source_hash = "sha256:b00cd658fe367314735c9f2689579820263b26d1853252dc72a0fee3d784db63" +route = "executable operational runbooks" + +[[spec]] +id = "anchor-a2ml" +name = "ANCHOR.a2ml spec" +stream = "foundation" +home = "anchor-a2ml/" +canonical_doc = "anchor-a2ml/README.adoc" +source_hash = "sha256:2a88233f201c3d2c05dd4d2530cc0fe33423ce9540a0fc2aa21556233074f4fb" +route = "project-recalibration intervention format" + +[[spec]] +id = "0-ai-gatekeeper-protocol" +name = "0-AI Gatekeeper Protocol" +stream = "protocol" +home = "0-ai-gatekeeper-protocol/" +canonical_doc = "0-ai-gatekeeper-protocol/README.adoc" +source_hash = "sha256:e1893253df97b1b989b1ba8e6926548a9a06a6582ab8b9448438da0b4b3e4428" +route = "the AI-agent entry/gating protocol behind 0-AI-MANIFEST" + +[[spec]] +id = "k9-coordination-protocol" +name = "K9 Coordination Protocol" +stream = "protocol" +home = "k9-coordination-protocol/" +canonical_doc = "k9-coordination-protocol/README.adoc" +source_hash = "sha256:9c856a0ed99f92ab3f8f6049df918fe023422dc6688cbc6110190c122ab28f97" +route = "multi-agent coordination on top of K9" + +[[spec]] +id = "avow-protocol" +name = "AVOW Protocol" +stream = "protocol" +home = "avow-protocol/" +canonical_doc = "avow-protocol/README.adoc" +source_hash = "sha256:fc6011d8531fbe3d8fbc5ba0b819cea892d8e0dee7ccb31ef0a22b7d264a8263" +route = "consent-attested messaging / origin attribution" + +[[spec]] +id = "axel-protocol" +name = "AXEL Protocol" +stream = "protocol" +home = "axel-protocol/" +canonical_doc = "axel-protocol/README.adoc" +source_hash = "sha256:6884bcc4f845e05cb0ff0d6d77171707e74f6069512bcf233161a5d8de8fb704" +route = "age-gating + explicit-content enforcement" + +[[spec]] +id = "overlay-protocol" +name = "Overlay Protocol" +stream = "protocol" +home = "overlay-protocol/" +canonical_doc = "overlay-protocol/.machine_readable/6a2/ECOSYSTEM.a2ml" +source_hash = "sha256:4e490e20401ef888930d7b72fe151bc89e4d084606252a1d6344df2c1dc904e1" +route = "layered overlay composition spec" + +[[spec]] +id = "consent-aware-http" +name = "Consent-Aware HTTP" +stream = "protocol" +home = "consent-aware-http/" +canonical_doc = "consent-aware-http/README.adoc" +source_hash = "sha256:e4165fa238b12e8515b985a21e7c7a9d7337627a484e74abe17fa000113a22e0" +route = "consent headers / AI-usage boundaries for HTTP" + +[[spec]] +id = "adoption-readiness-grades" +name = "ARG — Adoption Readiness Grades" +stream = "readiness" +home = "adoption-readiness-grades/" +canonical_doc = "adoption-readiness-grades/README.adoc" +source_hash = "sha256:036055fcb1c66320015e5dfca56438d8c87fa078c527c4c6226ec9e16803b4e0" +route = "per-language adoption-maturity profile templates" + +[[spec]] +id = "foundations-readiness-grades" +name = "FRG — Foundations Readiness Grades" +stream = "readiness" +home = "foundations-readiness-grades/" +canonical_doc = "foundations-readiness-grades/README.adoc" +source_hash = "sha256:a0e205de918a34d731e65d76e0a87d879dfd07b4e7cefc9b9c59cf8e81a051cb" +route = "per-language foundational-maturity profile templates" + +[[spec]] +id = "component-readiness-grades" +name = "CRG — Component Readiness Grades" +stream = "readiness" +home = "component-readiness-grades/" +canonical_doc = "component-readiness-grades/README.adoc" +source_hash = "sha256:47e5a756220c6f2e1c7274f6814fdbd8fe5a235b808eb638f83f80994d0843e8" +route = "the X..A grading system for components" + +[[spec]] +id = "toolchain-readiness-grades" +name = "TRG — Toolchain Readiness Grades" +stream = "readiness" +home = "toolchain-readiness-grades/" +canonical_doc = "toolchain-readiness-grades/README.adoc" +source_hash = "sha256:26a5399a7b83ccd95e9eee574b90c92ed238fb671f9eb0e284bd7a0b0e109f36" +route = "per-toolchain readiness profile templates" + +[[spec]] +id = "rhodium-standard-repositories" +name = "RSR — Rhodium Standard Repositories" +stream = "governance" +home = "rhodium-standard-repositories/" +canonical_doc = "rhodium-standard-repositories/README.adoc" +source_hash = "sha256:9e10e92598a307d3e32f8af3dc8b5cdfdbbcfd6d78069498d6797dc1f0001e62" +route = "the repository-compliance standard every repo is graded against" + +[[spec]] +id = "session-management-standards" +name = "Session Management Standards" +stream = "governance" +home = "session-management-standards/" +canonical_doc = "session-management-standards/README.adoc" +source_hash = "sha256:86a7739ac5cfd12aa34b1be1505c169e41b53e01bd1b3e3b7be308cd3b06d6b3" +route = "continuity / verify / handover protocols" + +[[spec]] +id = "ensaid-config" +name = "ENSAID Config" +stream = "governance" +home = "ensaid-config/" +canonical_doc = "ensaid-config/README.adoc" +source_hash = "sha256:f6cc431368df4cea795ca24eafb26ae42e6ff6bb17a02d8c4c3d75218709d0b1" +route = "the ensaid configuration standard" + +[[spec]] +id = "accessibility" +name = "Accessibility Standard" +stream = "governance" +home = "accessibility/" +canonical_doc = "accessibility/STANDARD.a2ml" +source_hash = "sha256:2286b68bb6ededf8534e90ad52f3ae5f7d25e4193f890ce5c740686171a4db2b" +route = "estate accessibility requirements" + +[[spec]] +id = "publication-pre-flight" +name = "Publication Pre-Flight" +stream = "governance" +home = "publication-pre-flight/" +canonical_doc = "publication-pre-flight/ESTATE-AUDIT-BASELINE-2026-03-30.adoc" +source_hash = "sha256:5bcf21e86a10248b20bf37fa8480a16d3ab3604a784f3cdb23e2ec351329975b" +route = "submission gate (HOL + Zenodo checklists)" + +[[spec]] +id = "release-pre-flight" +name = "Release Pre-Flight (V1 Gate)" +stream = "governance" +home = "release-pre-flight/" +canonical_doc = "release-pre-flight/V1-GATE.adoc" +source_hash = "sha256:790505e07de1cc1f3a22eed1e9ee0be0c75e28f9adbdec0aa9833253d9030a4a" +route = "hard v1.0.0 audit requirements" + +[[spec]] +id = "hypatia-rules" +name = "Standards Hypatia Rules" +stream = "integration" +home = "hypatia-rules/" +canonical_doc = "hypatia-rules/README.adoc" +source_hash = "sha256:b7e8942d6676f507d676527d7d6aa0e2b20931c837f990f76041cfbd123be823" +route = "the dogfooding rules that scan THIS repo (incl. drift detection)" + +[[spec]] +id = "a2ml-templates" +name = "A2ML Templates" +stream = "integration" +home = "a2ml-templates/" +canonical_doc = "a2ml-templates/STATE.a2ml.v2.spec.adoc" +source_hash = "sha256:5105bc72621b6214f1adecdf33a1dadf62d1d2b0afd0c2c6a48bbc5e24e9a454" +route = "copy-in templates for the 7 A2ML files" + +### End of REGISTRY.a2ml diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml index ff53735f..235c745f 100644 --- a/0-AI-MANIFEST.a2ml +++ b/0-AI-MANIFEST.a2ml @@ -1,128 +1,101 @@ -# STOP - CRITICAL READING REQUIRED - -**THIS FILE MUST BE READ FIRST BY ALL AI AGENTS** - -## WHAT IS THIS? - -This is the AI manifest for **standards**. It declares: -- Canonical file locations (where things MUST be, and nowhere else) -- Critical invariants (rules that must NEVER be violated) -- Repository structure and organization +# STOP — CANONICAL MACHINE ENTRY POINT (read this first) + +**This is the canonical machine front door for `hyperpolymath/standards`.** +The canonical *human* front door is `README.adoc`. Every other "what is this +repo" doc (EXPLAINME.adoc, TOPOLOGY.md, QUICKSTART-*.adoc, llm-warmup-*.md) is a +thin pointer back to one of these two. + +## WHAT IS THIS REPO? + +The organization-wide standards monorepo: ~30 specs that govern every +Hyperpolymath project — the A2ML metadata family, K9 self-validating +components, the protocols, the readiness-grading frameworks (ARG/FRG/CRG/TRG), +RSR compliance, and the enforcement/CI that makes them stick. + +## ROUTING — where to go for X (machine index) + +The authoritative, verifiable index is **`.machine_readable/REGISTRY.a2ml`**: +one `[[spec]]` block per standard, each with its `home`, `canonical_doc`, and a +content-addressed `source_hash`. Prose explanation: `REGISTRY.adoc`. + +| If you want… | Go to | +|---|---| +| Every spec + home + source hash | `.machine_readable/REGISTRY.a2ml` | +| A2ML / K9 foundation (Stream 1) | `a2ml/`, `k9-svc/`, `contractiles/`, `*-a2ml/` | +| Language policy (Stream 2) | `.claude/CLAUDE.md` | +| Protocols | `*-protocol/` (registry stream `protocol`) | +| Readiness grades | `adoption-readiness-grades/`, `foundations-readiness-grades/`, `component-readiness-grades/`, `toolchain-readiness-grades/` | +| Enforcement / CI | `.github/workflows/`, `hooks/` | +| Drift / staleness automation | `REGISTRY.adoc`, `hypatia-rules/` (HYP-S006) | +| Derived architecture map | `TOPOLOGY.md` (generated — do not edit) | +| Current project state | `.machine_readable/6a2/STATE.a2ml` | ## CANONICAL LOCATIONS (UNIVERSAL RULE) -### Machine-Readable Metadata: `.machine_readable/` ONLY +### Machine-readable metadata lives in `.machine_readable/6a2/` ONLY -These 6 A2ML files MUST exist in `.machine_readable/` directory ONLY: -1. **STATE.a2ml** - Project state, progress, blockers -2. **META.a2ml** - Architecture decisions, governance -3. **ECOSYSTEM.a2ml** - Position in ecosystem, relationships -4. **AGENTIC.a2ml** - AI agent interaction patterns -5. **NEUROSYM.a2ml** - Neurosymbolic integration config -6. **PLAYBOOK.a2ml** - Operational runbook +The 7 A2ML files MUST exist under `.machine_readable/6a2/` (this repo's +absorbed-satellite layout), never in the repo root: -**CRITICAL:** If ANY of these files exist in the root directory, this is an ERROR. +1. **STATE.a2ml** — project state, progress, blockers +2. **META.a2ml** — architecture decisions, governance +3. **ECOSYSTEM.a2ml** — position in ecosystem, relationships +4. **AGENTIC.a2ml** — AI-agent interaction patterns +5. **NEUROSYM.a2ml** — neurosymbolic integration config +6. **PLAYBOOK.a2ml** — operational runbook +7. **ANCHOR.a2ml** — intervention/recalibration (under `.machine_readable/anchors/`) -### Bot Directives: `.bot_directives/` ONLY +**CRITICAL:** if any of these appear in the repo root, that is an ERROR. -Bot-specific instructions for: -- rhodibot - Git operations -- echidnabot - Code quality -- sustainabot - Dependency updates -- glambot - Documentation -- seambot - Integration -- finishbot - Task completion +### Generated files — DO NOT EDIT BY HAND -### Agent Instructions +- `.machine_readable/REGISTRY.a2ml` — regenerate with `just registry` +- `TOPOLOGY.md` — regenerated by the same generator (`scripts/build-registry.sh`) -- `.claude/CLAUDE.md` - Claude-specific patterns (if exists) -- `0-AI-MANIFEST.a2ml` - THIS FILE (universal entry point) +CI (`registry-verify.yml`) fails the build if either drifts from the file tree. ## CORE INVARIANTS -1. **No A2ML duplication** - Root must NOT contain STATE.a2ml, META.a2ml, etc. -2. **Single source of truth** - `.machine_readable/` is authoritative -3. **No stale metadata** - If root A2ML files exist, they are OUT OF DATE -4. **License consistency** - All code PMPL-1.0-or-later unless platform requires MPL-2.0 -5. **Author attribution** - Always "Jonathan D.A. Jewell " +1. **No A2ML duplication** — root must NOT contain STATE.a2ml, META.a2ml, etc. +2. **Single source of truth** — `.machine_readable/6a2/` is authoritative for state. +3. **Registry is generated, not authored** — edit the `SPECS` table in + `scripts/build-registry.sh`, then run `just registry`; never hand-edit + `REGISTRY.a2ml` or `TOPOLOGY.md`. +4. **Licence is Manual-Only for agents** — every file's licence/SPDX is set by + the owner. Agents NEVER edit, sweep, or relicense `LICENSE` files or SPDX + headers; licence drift is FLAG-ONLY (`:review`). See `LICENSE`, + `.machine_readable/licensing-policy.toml`, and `.claude/CLAUDE.md`. +5. **Author attribution** — "Jonathan D.A. Jewell ". -## REPOSITORY STRUCTURE +## SESSION STARTUP CHECKLIST - +- Read THIS file, then `README.adoc`. +- Read `.machine_readable/REGISTRY.a2ml` to locate the spec you need. +- Read `.machine_readable/6a2/STATE.a2ml` for current status + blockers. +- Read `.machine_readable/6a2/AGENTIC.a2ml` for interaction patterns. +- Read `.claude/CLAUDE.md` for the language + licence policy (binding). -This repo contains: +## DRIFT AUTOMATION (how this repo stays honest) ``` -standards/ -├── 0-AI-MANIFEST.a2ml # THIS FILE (start here) -├── README.md # Project overview -├── [your source files] # Main code -├── .machine_readable/ # A2ML files (6 files) -│ ├── STATE.a2ml -│ ├── META.a2ml -│ ├── ECOSYSTEM.a2ml -│ ├── AGENTIC.a2ml -│ ├── NEUROSYM.a2ml -│ └── PLAYBOOK.a2ml -└── .bot_directives/ # Bot instructions +file tree + STATE.a2ml ──► scripts/build-registry.sh ──► REGISTRY.a2ml ──► TOPOLOGY.md + ▲ │ + │ ▼ + just registry / registry-verify.yml HYP-S006 (registry-staleness) + (fails build on drift) emits doc.drift → router (:review-capped on licence) ``` -## A2ML ATOMICITY PROTOCOL (AAP) - -When multiple agents or bots may be writing to A2ML files concurrently: - -1. **Read** the file and record `git-sha-at-read` in the `[provenance]` section -2. **Lock** by creating `.machine_readable/.lock-` (advisory) -3. **Write** the updated file with new `[provenance]` metadata -4. **Release** by removing the lock file -5. **Conflict** — if `git-sha-at-read` does not match current HEAD, re-read and retry - -This prevents lost writes when multiple agents update state files simultaneously. - -## SESSION STARTUP CHECKLIST - -- Read THIS file (0-AI-MANIFEST.a2ml) first -- Understand canonical locations (.machine_readable/, .bot_directives/) -- Know the invariants (no A2ML duplication, etc.) -- Check for MCP enforcement (if applicable) -- Read `.machine_readable/6a2/STATE.a2ml` for current status -- Read `.machine_readable/6a2/AGENTIC.a2ml` for interaction patterns - -## LIFECYCLE HOOKS - -### on-enter (Session Start) - -When starting a new session: - -1. Read and acknowledge this manifest -2. Log session start (optional but recommended) - - Format: `[YYYY-MM-DD HH:MM:SS] Session started: [agent-name]` - - Location: `.machine_readable/session-log.txt` -3. Read `.machine_readable/6a2/STATE.a2ml` -4. Check for blockers -5. State understanding of canonical locations - -### on-exit (Session End) - -When ending a session: - -1. Update `.machine_readable/6a2/STATE.a2ml` if changes made -2. Log session end (optional but recommended) - - Format: `[YYYY-MM-DD HH:MM:SS] Session ended: [summary]` - - Location: `.machine_readable/session-log.txt` -3. Document new blockers -4. Summarize outcomes - -## ATTESTATION PROOF - -After reading this file, demonstrate understanding by stating: +## ATTESTATION -**"I have read the AI manifest. A2ML files are located in `.machine_readable/` ONLY, bot directives in `.bot_directives/`, and I will not create duplicate files in the root directory."** +After reading, state: **"I have read the standards manifest. The human front +door is README.adoc and the machine index is .machine_readable/REGISTRY.a2ml. +A2ML state lives in .machine_readable/6a2/ only. REGISTRY.a2ml and TOPOLOGY.md +are generated — I will not hand-edit them. Licence/SPDX is Manual-Only — I will +flag, never edit."** ## META -- **Format Version:** 1.0.0 -- **Created:** [DATE] -- **Maintained By:** [YOUR-NAME/ORG] -- **License:** PMPL-1.0-or-later +- **Format Version:** 2.0.0 +- **Maintained By:** Jonathan D.A. Jewell (hyperpolymath) +- **Licence:** see `LICENSE` - **Protocol:** https://github.com/hyperpolymath/0-ai-gatekeeper-protocol diff --git a/EXPLAINME.adoc b/EXPLAINME.adoc index dde78fa4..6b006dd7 100644 --- a/EXPLAINME.adoc +++ b/EXPLAINME.adoc @@ -1,159 +1,63 @@ // SPDX-License-Identifier: AGPL-3.0-or-later = Hyperpolymath Standards — EXPLAINME -:toc: preamble :icons: font -== Canonical source for policies, templates, and specifications +[NOTE] +==== +*This is a thin pointer, not an entry point.* The canonical front doors are: -[quote, README.adoc] -____ -Organization-wide standards, specifications, and governance templates for the Hyperpolymath ecosystem. -____ +* *Humans* → link:README.adoc[README.adoc] (overview + "if you want X, go here" routing) +* *Agents* → link:0-AI-MANIFEST.a2ml[0-AI-MANIFEST.a2ml] (machine routing) +* *The spec index* → link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml] (every spec + home + source hash) · prose in link:REGISTRY.adoc[REGISTRY.adoc] -This monorepo consolidates the A2ML specification family, governance templates, protocol definitions, and enforcement tooling that all Hyperpolymath projects must follow. -Former satellite repos (meta-a2ml, playbook-a2ml, agentic-a2ml, etc.) were absorbed into subdirectories as of 2026-02-08. -See link:README.adoc[] for the full directory map and specification list. +This file used to carry its own hand-maintained spec inventory, which drifted +(it listed ReScript as a primary language — banned 2026-04-30 in favour of +AffineScript — and referenced `groove-protocol/` and `palimpsest-license/` as +local directories that do not exist in this monorepo). That inventory now lives +in the generated, CI-verified registry instead, so it can no longer go stale. +==== -**Caveat:** Standards are prescriptive -- not every downstream repo is fully compliant yet. Enforcement is via CI workflows and Hypatia scanning, not manual audit. +== What this repo is -=== Architecture Decisions +The organization-wide standards monorepo: the A2ML metadata family, K9 +self-validating components, the protocols, the readiness-grading frameworks +(ARG/FRG/CRG/TRG), RSR compliance, and the enforcement/CI that makes them +stick. Former satellite repos were absorbed as subdirectories on 2026-02-08. + +For the full, verifiable list of specs and where each one lives, read +link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml] (or the human prose in +link:REGISTRY.adoc[REGISTRY.adoc]). + +== Architecture decisions (the durable ones) [cols="1,3", options="header"] |=== | Decision | Rationale | AsciiDoc-first documentation -| AsciiDoc supports semantic structure, cross-references, and conditional output better than Markdown. `.md` is only used for GitHub-required files (SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md). +| Semantic structure + cross-references; `.md` only for GitHub-required files. | Justfile over Makefiles -| `just` provides cross-platform recipes without implicit rules or tab sensitivity. Makefiles are banned org-wide. +| Cross-platform recipes without tab sensitivity; Makefiles are banned org-wide. -| Language policy (CCCP) -| Limits ecosystem fragmentation. Primary: ReScript, Rust, Gleam, Deno. Banned: TypeScript, Go, Python, Java/Kotlin/Swift. Exceptions documented per-repo. +| Language policy +| AffineScript (primary), Rust/SPARK, Zig, Gleam, Elixir, Idris2/Agda. Banned: TypeScript, ReScript, Python, Go, Java/Kotlin/Swift, V-lang, Makefiles. Canonical statement + carve-outs: link:.claude/CLAUDE.md[.claude/CLAUDE.md]. | A2ML over YAML/JSON for metadata -| Machine-readable, versionable, and carries semantic meaning. Each repo declares its state via `.machine_readable/STATE.a2ml`. - -| SHA-pinned GitHub Actions -| Prevents supply-chain attacks from mutable tags. All workflows pin actions by commit SHA. - -| Guix-first package management -| Reproducible builds. Nix flakes as fallback. No npm/node_modules in production. -|=== - -=== Evidence - -[cols="2,3", options="header"] -|=== -| Path | Proves - -| `a2ml/` -| A2ML format specification -- the machine-readable metadata format used across all repos (47 Rust tests) - -| `meta-a2ml/`, `state-a2ml/`, `ecosystem-a2ml/` -| META, STATE, ECOSYSTEM A2ML specs and IANA registration drafts - -| `agentic-a2ml/` -| AGENTIC.a2ml spec -- AI agent interaction patterns with contractile enforcement - -| `neurosym-a2ml/` -| NEUROSYM.a2ml spec -- neurosymbolic integration configuration with Nickel schemas - -| `playbook-a2ml/`, `anchor-a2ml/` -| PLAYBOOK and ANCHOR A2ML specs -- operational runbooks and intervention protocols - -| `contractiles/` -| Contractile system (must/trust/dust/intend/k9) -- policy enforcement primitives - -| `k9-svc/` -| K9 self-validating component framework (45 Rust tests, CRG Grade B, deployed on 105+ repos) - -| `k9-coordination-protocol/` -| AI agent coordination protocol (79 tests, Phase 1 complete) - -| `axel-protocol/` -| Axel protocol specification -- age-gating and explicit enforcement (14 Deno tests, beta) - -| `groove-protocol/` -| Groove universal plug-and-play protocol -- inter-service communication (10+ Zig tests, 80% complete) - -| `avow-protocol/` -| AVOW consent-attested messaging -- origin attribution and willingness verification (Idris2 + ReScript) - -| `consent-aware-http/` -| Multi-protocol AI usage boundaries -- consent headers for HTTP interactions - -| `hooks/` -| Pre-commit and CI hooks -- the enforcement layer that makes standards stick - -| `.github/workflows/` -| 23 CI/CD workflows -- policy enforcement, quality gates, security scanning, deployment -|=== - -=== How to Use This Repo - -1. **New project?** Copy `.machine_readable/` templates into your repo and fill in the A2ML files. -2. **CI enforcement?** Reference the shared workflows or copy the relevant `.github/workflows/` files. -3. **Language question?** Check the CCCP language policy in `CLAUDE.md` or the `language-policy.yml` workflow. -4. **Building?** Run `just build` (requires Rust, Zig, and Deno). Run `just test` for the full 158+ test suite. -5. **Self-check?** Run `just doctor` to verify your local toolchain, `just heal` to auto-fix common issues. - -=== Test Coverage - -[cols="2,1,1", options="header"] -|=== -| Suite | Technology | Tests - -| groove-protocol/reference/ipv6t | Zig | 10+ -| 0-ai-gatekeeper-protocol/mcp-repo-guardian | Deno | 36 -| axel-protocol | Deno | 14 -| a2ml/bindings/rust | Rust | 47 -| k9-svc/bindings/rust | Rust | 45 -| avow-protocol (ReScript) | Deno | 8 -| **Total** | | **160+** -|=== - -=== Dogfooded Across The Account - -The patterns mandated here are applied everywhere — not prescribed then ignored: - -[cols="1,2,2", options="header"] -|=== -| Standard | Where Mandated | Live Examples - -| A2ML machine-readable metadata -| link:a2ml/[a2ml/] spec (7 formats) -| Every RSR repo's `.machine_readable/`; link:meta-a2ml/[meta-a2ml] spec + IANA draft +| Machine-readable, versionable, semantically typed. Each repo declares state in `.machine_readable/`. | SHA-pinned GitHub Actions -| link:.github/workflows/workflow-linter.yml[workflow-linter.yml] CI gate -| All 23 workflows in `.github/workflows/` pin by SHA; enforced in >300 downstream repos - -| Contractile / K9 enforcement -| link:contractiles/CANONICAL-TEMPLATES.adoc[contractiles/] + link:k9-svc/[k9-svc/] -| hypatia, gossamer, burble, proven, proven-servers (105+ repos carry k9 guards) - -| Groove inter-service protocol -| link:groove-protocol/[groove-protocol/] spec -| gossamer (src/core/Groove.eph), burble (bridges), hypatia (dispatch connectors) - -| Idris2 ABI + Zig FFI standard -| link:ABI-FFI-README.md[ABI-FFI-README.md] + rsr-template-repo reference -| ephapax (idris2/), gossamer (src/interface/abi/), burble (src/Burble/ABI/), verisimdb, typed-wasm +| Prevents supply-chain attacks from mutable tags. | Guix-first package management -| CCCP language policy (CLAUDE.md) -| guix.scm at root; flake.nix as fallback — both present in this repo - -| PMPL-1.0-or-later licence -| link:palimpsest-license/[palimpsest-license/] + licence policy -| SPDX header on every source file estate-wide; link:LICENSE[LICENSE] here +| Reproducible builds; Nix flakes as fallback. |=== -=== Roadmap Phases +== How to use this repo -* **Phase A (Innervation):** Wire k9 coordination across all repos, replace static 6a2 files with derived STATE. -* **Phase B (Evidence):** Formal proof verification via ECHIDNA, VeriSimDB population, lol/ postulate resolution. -* **Phase C (Visibility):** PanLL dashboard panels, ecosystem health metrics, compliance heatmaps. -* **Phase D (Maturity):** CRG Grade A self-assessment, full dogfooding, external audit readiness. +. *New project?* See link:A2ML-REPO-TEMPLATE.adoc[A2ML-REPO-TEMPLATE.adoc] and the *Usage* section of link:README.adoc[README.adoc]. +. *Looking for a specific spec?* link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml]. +. *Language question?* link:.claude/CLAUDE.md[.claude/CLAUDE.md]. +. *CI / enforcement?* link:.github/workflows/[.github/workflows/] + link:hooks/[hooks/]. +. *Build / test?* `just build`, `just test` (see link:Justfile[Justfile]). diff --git a/Justfile b/Justfile index 066ff43c..489878bd 100644 --- a/Justfile +++ b/Justfile @@ -13,6 +13,23 @@ import? "contractile.just" default: @just --list +# Regenerate the verifiable spec registry + DERIVED topology from the file tree +registry: + @bash scripts/build-registry.sh + +# Alias: same generator also (re)writes TOPOLOGY.md +topology: registry + +# Fail if REGISTRY.a2ml or TOPOLOGY.md has drifted from the file tree +registry-check: + @bash scripts/build-registry.sh --check + +# Print role-appropriate LLM warm-up context (machine front door) +llm-context role="dev": + @echo "# Front door: 0-AI-MANIFEST.a2ml (machine) + README.adoc (human)" + @echo "# Registry: .machine_readable/REGISTRY.a2ml · prose: REGISTRY.adoc" + @cat "llm-warmup-{{role}}.md" 2>/dev/null || cat 0-AI-MANIFEST.a2ml + # Build all sub-project artefacts build: @echo "=== Standards Monorepo Build ===" diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc index 8908a16a..a0f67380 100644 --- a/QUICKSTART-DEV.adoc +++ b/QUICKSTART-DEV.adoc @@ -1,13 +1,25 @@ // SPDX-License-Identifier: AGPL-3.0-or-later -// Template: QUICKSTART-DEV.adoc — clone → build → test → PR -// Replace standards, {{BUILD_CMD}}, {{TEST_CMD}}, {{LANG_STACK}} with actuals +// QUICKSTART-DEV.adoc — working on the standards monorepo itself = standards — Quick Start for Developers :toc: :toclevels: 2 +[NOTE] +Working *on* the standards themselves. Canonical entry points: +link:README.adoc[README.adoc] (human), link:0-AI-MANIFEST.a2ml[0-AI-MANIFEST.a2ml] +(agent), link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml] (spec index). + == Tech Stack -{{LANG_STACK}} +The *product* is the specs (AsciiDoc + A2ML). The code is reference +implementations and language bindings that prove them: + +* *Rust/SPARK* — `a2ml/bindings/rust`, `k9-svc/bindings/rust` +* *Deno* — protocol reference impls (`axel-protocol`, `0-ai-gatekeeper-protocol/mcp-repo-guardian`) +* *Zig* — FFI/reference targets +* *AsciiDoc / A2ML* — the specs, templates, and machine-readable metadata + +Language + licence policy is binding: link:.claude/CLAUDE.md[.claude/CLAUDE.md]. == Set Up Development Environment @@ -38,14 +50,14 @@ just setup-dev [source,bash] ---- -{{BUILD_CMD}} +just build # builds the Rust/Zig sub-project artefacts ---- == Test [source,bash] ---- -{{TEST_CMD}} +just test # runs every sub-project test suite ---- == Project Structure @@ -53,16 +65,30 @@ just setup-dev [source] ---- standards/ -├── src/ # Source code -├── src/abi/ # Idris2 ABI definitions (if applicable) -├── ffi/zig/ # Zig FFI bridge (if applicable) -├── tests/ # Test suite -├── docs/ # Documentation -├── .machine_readable/ # Checkpoint files (STATE, META, ECOSYSTEM) +├── README.adoc # Human front door (routing table) +├── 0-AI-MANIFEST.a2ml # Machine front door (agent entry) +├── REGISTRY.adoc # Prose: the registry + drift automation +├── a2ml/ k9-svc/ *-a2ml/ # Foundation specs (Stream 1) +├── *-protocol/ # Protocol specs +├── *-readiness-grades/ # ARG / FRG / CRG / TRG frameworks +├── hypatia-rules/ # Dogfooding rules incl. HYP-S006 (drift) +├── scripts/build-registry.sh # Generator for REGISTRY.a2ml + TOPOLOGY.md +├── .machine_readable/ # State (6a2/), REGISTRY.a2ml, contractiles ├── Justfile # Task runner recipes -├── guix.scm # Guix environment -├── flake.nix # Nix environment (fallback) -└── 0-AI-MANIFEST.a2ml # AI agent entry point +├── guix.scm / flake.nix # Guix (primary) / Nix (fallback) env +└── .github/workflows/ # Enforcement + registry-verify CI +---- + +== Registry workflow (important) + +`.machine_readable/REGISTRY.a2ml` and `TOPOLOGY.md` are *generated*. To add or +move a spec, edit the `SPECS` table in +link:scripts/build-registry.sh[`scripts/build-registry.sh`], then: + +[source,bash] +---- +just registry # regenerate REGISTRY.a2ml + TOPOLOGY.md +just registry-check # what CI enforces — fails on drift ---- == Key Recipes @@ -91,7 +117,10 @@ just panic-scan # No new security issues Read `.machine_readable/MUST.contractile` before making changes. Key invariants that must never be violated: -{{MUST_INVARIANTS}} +* A2ML state files live in `.machine_readable/6a2/` only — never the repo root. +* `REGISTRY.a2ml` + `TOPOLOGY.md` are generated — regenerate, never hand-edit. +* No Makefiles (use Justfile); SPDX header on every source file. +* Licence/SPDX is Manual-Only for agents — flag drift, never edit it. == LLM/AI Agent Development diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index 28f677e3..34a3a0c9 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -1,6 +1,5 @@ // SPDX-License-Identifier: AGPL-3.0-or-later -// Template: QUICKSTART-MAINTAINER.adoc — packaging, deploying, and maintaining -// Replace standards, {{PACKAGE_NAME}}, {{DEPS}} with actuals +// QUICKSTART-MAINTAINER.adoc — packaging and maintaining the standards bundle = standards — Quick Start for Platform Maintainers :toc: :toclevels: 2 @@ -12,7 +11,12 @@ distribution on your platform. == Runtime Dependencies -{{DEPS}} +This is a specs/standards monorepo, not a runtime application — "packaging" +means bundling the spec tree and its reference implementations. + +* *Required:* `just`, `git` +* *Optional (to build/test reference impls):* `cargo` (Rust), `deno`, `zig` +* *Optional (reproducible env):* `guix` (primary) or `nix` (fallback) == Build from Source @@ -23,7 +27,7 @@ cd standards just build-release ---- -Output: `{{BUILD_OUTPUT_PATH}}` +Output: `spec bundle + reference-impl artefacts (no single binary)` == Packaging @@ -65,10 +69,10 @@ Files installed: | `$PREFIX/bin/` | Executables -| `$PREFIX/share/{{PACKAGE_NAME}}/` +| `$PREFIX/share/standards/` | Data files, assets -| `$PREFIX/share/doc/{{PACKAGE_NAME}}/` +| `$PREFIX/share/doc/standards/` | Documentation | `$PREFIX/share/applications/` @@ -80,9 +84,9 @@ Files installed: == Configuration -Default config location: `$XDG_CONFIG_HOME/{{PACKAGE_NAME}}/config.toml` +Default config location: `$XDG_CONFIG_HOME/standards/config.toml` -Fallback: `$HOME/.config/{{PACKAGE_NAME}}/config.toml` +Fallback: `$HOME/.config/standards/config.toml` == Health Checks @@ -102,7 +106,7 @@ just build-release just install --prefix=/usr/local ---- -Or via OPSM: `opsm update {{PACKAGE_NAME}}` +Or via OPSM: `opsm update standards` == Security Notes @@ -117,8 +121,8 @@ For deploying multiple instances (e.g., different users or tenants): [source,bash] ---- -just install --prefix=/opt/{{PACKAGE_NAME}}-instance1 --config=/etc/{{PACKAGE_NAME}}/instance1.toml -just install --prefix=/opt/{{PACKAGE_NAME}}-instance2 --config=/etc/{{PACKAGE_NAME}}/instance2.toml +just install --prefix=/opt/standards-instance1 --config=/etc/standards/instance1.toml +just install --prefix=/opt/standards-instance2 --config=/etc/standards/instance2.toml ---- Each instance has isolated config, data, and logs. diff --git a/QUICKSTART-USER.adoc b/QUICKSTART-USER.adoc index 4a0429ba..ced15f82 100644 --- a/QUICKSTART-USER.adoc +++ b/QUICKSTART-USER.adoc @@ -1,124 +1,48 @@ // SPDX-License-Identifier: AGPL-3.0-or-later -// Template: QUICKSTART-USER.adoc — 5-minute path to working software -// Replace standards, Standards — See README.adoc for details., just run, Standards started successfully. with actuals -= standards — Quick Start for Users +// QUICKSTART-USER.adoc — consuming the standards in your own repo += standards — Quick Start for Consumers :toc: :toclevels: 2 -== What is standards? - -Standards — See README.adoc for details. - -== Prerequisites - -Before you begin, ensure you have: - -* **just** — task runner (https://github.com/casey/just[install guide]) -* Platform-specific requirements listed below - -[cols="1,3"] -|=== -| Platform | Additional Requirements +[NOTE] +This is a *specs* monorepo, not an application to install and run. "Using" it +means *applying* the standards to your own repository. The canonical front door +is link:README.adoc[README.adoc]; the machine index is +link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml]. -| Linux -| See README.adoc - -| macOS -| See README.adoc - -| Windows -| See README.adoc -|=== +== What is standards? -== Install +The organization-wide source of truth for Hyperpolymath policies, the A2ML +metadata family, K9 components, the protocols, the readiness-grading +frameworks (ARG/FRG/CRG/TRG), RSR compliance, and the enforcement/CI that makes +them stick. See link:README.adoc[README.adoc] for the full overview and the +"if you want X, go here" routing table. -=== Option 1: Standard Install (recommended) +== Apply the standards to your repo [source,bash] ---- -# Clone and set up git clone https://github.com/hyperpolymath/standards.git -cd standards -just setup ----- - -The setup script will: - -* Detect your platform and shell -* Install missing dependencies (with your permission) -* Configure the application -* Offer install location choices -* Run a self-diagnostic to verify everything works - -=== Option 2: Container (via Stapeln) - -[source,bash] ----- -just stapeln-run ----- - -=== Option 3: Portable (no system changes) - -[source,bash] ----- -just install --portable --prefix=./standards-portable ---- -== First Run +. *Scaffold a compliant repo:* follow link:A2ML-REPO-TEMPLATE.adoc[A2ML-REPO-TEMPLATE.adoc] + and the *Usage* section of link:README.adoc[README.adoc]. +. *Add the 7 A2ML files:* copy from link:a2ml-templates/[`a2ml-templates/`] into + your repo's `.machine_readable/`. +. *Adopt enforcement:* copy the relevant link:.github/workflows/[workflows] and + link:hooks/[hooks] (language policy, doc-format, Makefile blocker, registry-verify). +. *Follow the language + licence policy:* link:.claude/CLAUDE.md[.claude/CLAUDE.md]. -[source,bash] ----- -just run ----- - -Expected output: - -[source] ----- -Standards started successfully. ----- - -== Self-Diagnostic - -If something isn't working: - -[source,bash] ----- -just doctor ----- - -This checks all dependencies, permissions, paths, and connectivity. -If it finds issues, it will suggest fixes. - -To attempt automatic repair: - -[source,bash] ----- -just heal ----- - -== Get Help - -* **In-app**: `just run --help` -* **Guided tour**: `just tour` -* **Report a problem**: `just help-me` (pre-fills diagnostic context) -* **Wiki**: https://github.com/hyperpolymath/standards/wiki - -== Uninstall - -[source,bash] ----- -just uninstall ----- +== Find a specific spec -You will be asked: +Use the registry — it routes you from a spec `id` to its `home` and the one doc +to read first: -1. Which uninstall tier (Bennett reversible, parameter-based, standard, or secure) -2. Whether to include or exclude your data -3. Whether to clear caches and LLM models +* Machine index: link:.machine_readable/REGISTRY.a2ml[`.machine_readable/REGISTRY.a2ml`] +* Prose + drift automation: link:REGISTRY.adoc[REGISTRY.adoc] -== Next Steps +== Get help -* Read the link:README.adoc[README] for full feature overview -* Read the link:EXPLAINME.adoc[EXPLAINME] for architecture and design decisions -* Try `just tour` for a guided walkthrough +* *Routing:* the table at the top of link:README.adoc[README.adoc] +* *Report a problem:* https://github.com/hyperpolymath/standards/issues +* *Architecture map (derived):* link:TOPOLOGY.md[TOPOLOGY.md] diff --git a/README.adoc b/README.adoc index aa67173e..096f69c9 100644 --- a/README.adoc +++ b/README.adoc @@ -11,6 +11,63 @@ Organization-wide standards, specifications, and governance templates for the Hy toc::[] +== Start Here — Front Door & Routing + +This monorepo holds ~7,000 files across ~30 specs. You do not need to read all +of it. There are exactly **two canonical entry points**, and everything else +routes off them: + +[cols="1,1,3", options="header"] +|=== +| You are… | Start at | Then + +| A **human** | this file (link:README.adoc[README.adoc]) | follow the routing table below +| An **AI agent** | link:0-AI-MANIFEST.a2ml[0-AI-MANIFEST.a2ml] | then link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml] for the machine index +|=== + +Every other "what is this repo" doc is now a thin pointer back to these two +(link:EXPLAINME.adoc[EXPLAINME.adoc], link:TOPOLOGY.md[TOPOLOGY.md], +`QUICKSTART-*.adoc`, `llm-warmup-*.md`). + +=== If you want X, go here + +[cols="2,3", options="header"] +|=== +| If you want… | Go to + +| The complete, verifiable index of every spec + its home + source hash +| link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml] (machine) · link:REGISTRY.adoc[REGISTRY.adoc] (prose) + +| The **A2ML / K9 foundation** (Stream 1) — the 7-format family, K9, contractiles +| link:a2ml/[a2ml/], link:k9-svc/[k9-svc/], link:contractiles/[contractiles/] and the `*-a2ml/` spec dirs + +| The **language policy** (Stream 2) — allowed/banned languages, AffineScript stance +| link:.claude/CLAUDE.md[.claude/CLAUDE.md] (canonical) + the <> table below + +| The **protocols** — AVOW, AXEL, Overlay, K9-coordination, Consent-Aware-HTTP, 0-AI-gatekeeper +| the `*-protocol/` dirs (see link:.machine_readable/REGISTRY.a2ml[registry], stream `protocol`) + +| The **readiness grades** — ARG / FRG / CRG / TRG +| link:adoption-readiness-grades/[ARG], link:foundations-readiness-grades/[FRG], link:component-readiness-grades/[CRG], link:toolchain-readiness-grades/[TRG] + +| **Enforcement / CI** — what blocks bad changes +| link:.github/workflows/[.github/workflows/] + link:hooks/[hooks/] + <> + +| The **drift / staleness automation** — how this repo keeps itself honest +| link:REGISTRY.adoc[REGISTRY.adoc] + link:hypatia-rules/[hypatia-rules/] (HYP-S006) + +| The **architecture map** (derived, never frozen) +| link:TOPOLOGY.md[TOPOLOGY.md] (generated from STATE + registry) + +| To **stand up a new repo** to these standards +| link:A2ML-REPO-TEMPLATE.adoc[A2ML-REPO-TEMPLATE.adoc] + <> +|=== + +NOTE: link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml] and +link:TOPOLOGY.md[TOPOLOGY.md] are **generated** by +`scripts/build-registry.sh` (`just registry`) and verified in CI by +`registry-verify.yml`. Do not hand-edit them. + == Overview This repository serves as the canonical source for policies, templates, and specifications governing all Hyperpolymath projects. It provides: diff --git a/REGISTRY.adoc b/REGISTRY.adoc new file mode 100644 index 00000000..b4bef1e8 --- /dev/null +++ b/REGISTRY.adoc @@ -0,0 +1,115 @@ +// SPDX-License-Identifier: AGPL-3.0-or-later += The Standards Registry — Verifiable Spec Index + Drift Automation +:toc: macro +:icons: font + +toc::[] + +This document explains the *verifiable registry* that indexes every spec in +this monorepo, and how it is wired into the live automation so that +documentation drift becomes a *detected, routed finding* instead of +something noticed sixty days later. + +The registry is the machine half of the *front door*. If you are arriving +here: + +* *Human?* Start at link:README.adoc[README.adoc]. +* *Agent?* Start at link:0-AI-MANIFEST.a2ml[0-AI-MANIFEST.a2ml]. +* *Want the raw index?* Read link:.machine_readable/REGISTRY.a2ml[`.machine_readable/REGISTRY.a2ml`]. + +== What the registry is + +link:.machine_readable/REGISTRY.a2ml[`.machine_readable/REGISTRY.a2ml`] is a +generated A2ML file with one `[[spec]]` block per standard. Each block records: + +[cols="1,3", options="header"] +|=== +| Field | Meaning + +| `id` | Stable short identifier. +| `name` | Human-readable name. +| `stream` | One of `foundation`, `language`, `protocol`, `governance`, `readiness`, `integration`. +| `home` | The canonical directory the spec lives in (verified to exist). +| `canonical_doc` | The single doc to read first for that spec. +| `source_hash` | `sha256` over `git ls-files -s ` — a content-addressed fingerprint of the whole home. +| `route` | One-line "go here if you want X". +|=== + +The registry is *honest by construction*: the generator only emits a spec +whose `home` directory actually exists, and reports a missing home to stderr +rather than inventing one. + +== How `source_hash` works (and why it catches drift) + +`git ls-files -s ` lists every tracked file under a home together with +its blob SHA and path. Hashing that listing yields a fingerprint that changes +whenever *any* tracked file under the spec changes — content, addition, or +removal. Recording it in the registry means a later recompute can prove +whether a spec has moved underneath its documentation. + +== Regenerating (the generator) + +The registry and the *derived* topology map are produced by one generator: + +[source,bash] +---- +just registry # writes .machine_readable/REGISTRY.a2ml + TOPOLOGY.md +just registry-check # verify-only; non-zero exit on drift +---- + +Both `.machine_readable/REGISTRY.a2ml` and link:TOPOLOGY.md[TOPOLOGY.md] are +*generated files — do not edit by hand*. The single source of truth is the +`SPECS` table in link:scripts/build-registry.sh[`scripts/build-registry.sh`]. +Add a spec there and the hash, the registry entry, and the topology row all +follow automatically. link:TOPOLOGY.md[TOPOLOGY.md] can therefore never +freeze the way the old hand-maintained version did (it sat at `2026-04-04` +claiming 80% while the integration layer read 0%). + +== The drift-detection loop + +Drift is caught at two layers that share the same hash algorithm: + +[cols="1,3", options="header"] +|=== +| Layer | What it does + +| *In-repo* — link:.github/workflows/registry-verify.yml[`registry-verify.yml`] +| Runs `build-registry.sh --check` on every push/PR and *fails the build* if the registry or topology is stale. + +| *Estate* — link:hypatia-rules/registry-staleness.a2ml[HYP-S006 `registry-staleness`] +| Hypatia recomputes the hashes fleet-wide and emits a `doc.drift` Groove signal when a recorded hash is stale or a derived doc was hand-edited. +|=== + +[source] +---- +file tree + STATE.a2ml ──► scripts/build-registry.sh ──► REGISTRY.a2ml ──► TOPOLOGY.md + ▲ │ + │ ▼ + just registry / registry-verify.yml HYP-S006 (registry-staleness) + (fails the build on drift) emits doc.drift → router +---- + +== The hybrid automation router + +When HYP-S006 fires, the *hybrid automation router* decides what happens to +the finding. Its strategy is declared in the rule's `@router` block: + +* *Default:* `auto_execute` — regenerating a derived file from the file tree + is mechanical and safe, so the router may run the `rebuild-registry` recipe. +* *Hard cap:* any drift whose content overlaps a licence/SPDX token + (`SPDX-License-Identifier`, `PMPL`, `MPL-2.0`, `AGPL`, `Palimpsest`, + `licen[cs]e`) is *demoted to `:review`* and never auto-applied. + +This cap mirrors the estate Manual-Only licence guardrail +(link:.claude/CLAUDE.md[`.claude/CLAUDE.md`]) and Hypatia's own +`license_finding_strategy/0`: *agents flag licence drift, the owner edits it* +(the rule that closed neurophone#99). Downstream pipelines MUST honour the +cap. + +== Adding or moving a spec + +1. Edit the `SPECS` table in link:scripts/build-registry.sh[`scripts/build-registry.sh`]. +2. Run `just registry`. +3. Commit the regenerated `REGISTRY.a2ml` + `TOPOLOGY.md` alongside your change. + +CI will reject the PR if you change a spec's home without regenerating. diff --git a/REORGANIZATION-PLAN.md b/REORGANIZATION-PLAN.md index 6f947fee..5d80bce6 100644 --- a/REORGANIZATION-PLAN.md +++ b/REORGANIZATION-PLAN.md @@ -1,5 +1,29 @@ # Standards Repo Reorganization Plan +> **⚠️ SUPERSEDED (2026-06-02) — historical record only.** +> +> This plan predates the monorepo consolidation and the verifiable registry. +> Its premises no longer match reality: it proposes moving content *out* to +> separate repos (`k9-svc-repo`, `rsr-engine-repo`, `a2ml-repo`), but those +> satellites were **absorbed into this monorepo** on 2026-02-08, and several +> "redundancies" it lists (e.g. duplicate K9 templates / RSR workflows) have +> since been resolved or re-scoped. +> +> **What replaced it:** +> - *Discoverability* is now solved by the generated index +> [`.machine_readable/REGISTRY.a2ml`](.machine_readable/REGISTRY.a2ml) +> (prose: [`REGISTRY.adoc`](REGISTRY.adoc)) — every spec, its home, and a +> content-addressed `source_hash`. +> - *"Where do I go for X"* is answered by the routing table at the top of +> [`README.adoc`](README.adoc) and by [`0-AI-MANIFEST.a2ml`](0-AI-MANIFEST.a2ml). +> - *Drift* (the thing this plan tried to prevent by hand) is now detected +> automatically: `registry-verify.yml` (CI) + Hypatia rule HYP-S006. +> +> Any still-relevant idea below should be re-filed as a registry entry or an +> issue. The text is retained unedited for provenance. + +--- + ## Current Redundancies Identified ### 1. Template Duplication diff --git a/TOPOLOGY.md b/TOPOLOGY.md index d8c7869e..882da79e 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.md @@ -1,134 +1,82 @@ - - - -# Hyperpolymath Standards — Project Topology - -## System Architecture + + + +# Hyperpolymath Standards — Topology (derived) + +> This file is **generated** from `.machine_readable/REGISTRY.a2ml` and +> `.machine_readable/6a2/STATE.a2ml` by `scripts/build-registry.sh`. +> It cannot freeze: every regeneration re-reads ground truth. Do not edit by hand. + +- **Phase:** active  |  **Maturity:** experimental  |  **STATE last-updated:** 2026-06-02T18:00:00Z +- **Registry entries:** 28 specs across 6 streams +- **Front door:** human → [README.adoc](README.adoc); machine → [0-AI-MANIFEST.a2ml](0-AI-MANIFEST.a2ml) +- **Registry:** [.machine_readable/REGISTRY.a2ml](.machine_readable/REGISTRY.a2ml) (index + source hashes) · prose: [REGISTRY.adoc](REGISTRY.adoc) + +## Specs by stream + +### Foundation — A2ML family + K9 + contractiles (Stream 1) + +| Spec | Home | If you want… | +|---|---|---| +| A2ML — Attested Markup Language | [`a2ml/`](a2ml/) | the typed/verified machine-readable document format | +| K9 Self-Validating Components | [`k9-svc/`](k9-svc/) | self-validating components with embedded contracts + deploy logic | +| Contractiles (Must/Trust/Dust/Intend) | [`contractiles/`](contractiles/) | policy-enforcement primitives the K9 layer is built from | +| META.a2ml spec | [`meta-a2ml/`](meta-a2ml/) | architecture decisions / governance metadata format | +| STATE.a2ml spec | [`state-a2ml/`](state-a2ml/) | project-state metadata format (drives this registry's topology) | +| ECOSYSTEM.a2ml spec | [`ecosystem-a2ml/`](ecosystem-a2ml/) | ecosystem-positioning metadata format | +| AGENTIC.a2ml spec | [`agentic-a2ml/`](agentic-a2ml/) | AI-agent operational gating / entropy budgets | +| NEUROSYM.a2ml spec | [`neurosym-a2ml/`](neurosym-a2ml/) | symbolic semantics / proof obligations | +| PLAYBOOK.a2ml spec | [`playbook-a2ml/`](playbook-a2ml/) | executable operational runbooks | +| ANCHOR.a2ml spec | [`anchor-a2ml/`](anchor-a2ml/) | project-recalibration intervention format | + +### Protocols + +| Spec | Home | If you want… | +|---|---|---| +| 0-AI Gatekeeper Protocol | [`0-ai-gatekeeper-protocol/`](0-ai-gatekeeper-protocol/) | the AI-agent entry/gating protocol behind 0-AI-MANIFEST | +| K9 Coordination Protocol | [`k9-coordination-protocol/`](k9-coordination-protocol/) | multi-agent coordination on top of K9 | +| AVOW Protocol | [`avow-protocol/`](avow-protocol/) | consent-attested messaging / origin attribution | +| AXEL Protocol | [`axel-protocol/`](axel-protocol/) | age-gating + explicit-content enforcement | +| Overlay Protocol | [`overlay-protocol/`](overlay-protocol/) | layered overlay composition spec | +| Consent-Aware HTTP | [`consent-aware-http/`](consent-aware-http/) | consent headers / AI-usage boundaries for HTTP | + +### Governance — RSR, gates, session standards + +| Spec | Home | If you want… | +|---|---|---| +| RSR — Rhodium Standard Repositories | [`rhodium-standard-repositories/`](rhodium-standard-repositories/) | the repository-compliance standard every repo is graded against | +| Session Management Standards | [`session-management-standards/`](session-management-standards/) | continuity / verify / handover protocols | +| ENSAID Config | [`ensaid-config/`](ensaid-config/) | the ensaid configuration standard | +| Accessibility Standard | [`accessibility/`](accessibility/) | estate accessibility requirements | +| Publication Pre-Flight | [`publication-pre-flight/`](publication-pre-flight/) | submission gate (HOL + Zenodo checklists) | +| Release Pre-Flight (V1 Gate) | [`release-pre-flight/`](release-pre-flight/) | hard v1.0.0 audit requirements | + +### Readiness grading — ARG / FRG / CRG / TRG + +| Spec | Home | If you want… | +|---|---|---| +| ARG — Adoption Readiness Grades | [`adoption-readiness-grades/`](adoption-readiness-grades/) | per-language adoption-maturity profile templates | +| FRG — Foundations Readiness Grades | [`foundations-readiness-grades/`](foundations-readiness-grades/) | per-language foundational-maturity profile templates | +| CRG — Component Readiness Grades | [`component-readiness-grades/`](component-readiness-grades/) | the X..A grading system for components | +| TRG — Toolchain Readiness Grades | [`toolchain-readiness-grades/`](toolchain-readiness-grades/) | per-toolchain readiness profile templates | + +### Integration — registry, hypatia rules, templates (Stream 3) + +| Spec | Home | If you want… | +|---|---|---| +| Standards Hypatia Rules | [`hypatia-rules/`](hypatia-rules/) | the dogfooding rules that scan THIS repo (incl. drift detection) | +| A2ML Templates | [`a2ml-templates/`](a2ml-templates/) | copy-in templates for the 7 A2ML files | + +## How this map stays honest ``` - ┌─────────────────────────────────────────┐ - │ EPISTEMIC FLEET │ - │ (275+ Target Repositories) │ - └───────────────────┬─────────────────────┘ - │ Policy Enforcement - ▼ - ┌─────────────────────────────────────────┐ - │ STANDARDS HUB LAYER │ - │ │ - │ ┌───────────┐ ┌───────────────────┐ │ - │ │ Language │ │ Governance │ │ - │ │ Policy │ │ Templates │ │ - │ │ (CCCP) │ │ (RSR Scaffolding) │ │ - │ └─────┬─────┘ └────────┬──────────┘ │ - │ │ │ │ - │ ┌─────▼─────┐ ┌────────▼──────────┐ │ - │ │ Build │ │ A2ML Metadata │ │ - │ │ System │ │ Family (7) │ │ - │ │ (Mustfile)│ │ (STATE, META, etc)│ │ - │ └─────┬─────┘ └────────┬──────────┘ │ - └────────│─────────────────│──────────────┘ - │ │ - ▼ ▼ - ┌─────────────────────────────────────────┐ - │ A2ML SPECIFICATION MODULES │ - │ ┌───────────┐ ┌───────────┐ ┌───────┐│ - │ │ meta-a2ml │ │ agentic- │ │neuro- ││ - │ │ │ │ a2ml │ │sym ││ - │ └───────────┘ └───────────┘ └───────┘│ - │ ┌───────────┐ ┌───────────┐ ┌───────┐│ - │ │state-a2ml │ │ playbook- │ │anchor-││ - │ │ │ │ a2ml │ │a2ml ││ - │ └───────────┘ └───────────┘ └───────┘│ - │ ┌───────────────────────────────────┐ │ - │ │ ecosystem-a2ml │ │ - │ └───────────────────────────────────┘ │ - └─────────────────────────────────────────┘ - - ┌─────────────────────────────────────────┐ - │ PROTOCOL SPECIFICATIONS │ - │ ┌───────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ - │ │Groove │ │ AVOW │ │ AXEL │ │ K9 │ │ - │ └───────┘ └──────┘ └──────┘ └──────┘ │ - │ ┌──────────────┐ ┌─────────────────┐ │ - │ │Consent-HTTP │ │Overlay Protocol │ │ - │ └──────────────┘ └─────────────────┘ │ - └─────────────────────────────────────────┘ - - ┌─────────────────────────────────────────┐ - │ INTEGRATION & TOOLING │ - │ VeriSimDB (:8097) Hypatia Scan │ - │ ECHIDNA Proofs PanLL Panels │ - │ Groove Registry K9 Coordination │ - └─────────────────────────────────────────┘ - - ┌─────────────────────────────────────────┐ - │ REPO INFRASTRUCTURE │ - │ Justfile Automation .machine_readable/ │ - │ CI/CD Workflows 0-AI-MANIFEST.a2ml │ - └─────────────────────────────────────────┘ +file tree + STATE.a2ml ──► scripts/build-registry.sh ──► REGISTRY.a2ml ──► TOPOLOGY.md + ▲ │ + │ ▼ + just registry / CI HYP-S006 (registry-staleness) + (registry-verify.yml) emits doc.drift on hash mismatch ``` -## Completion Dashboard - -``` -COMPONENT STATUS NOTES -───────────────────────────────── ────────────────── ───────────────────────────────── -CORE STANDARDS - Language Policy (CCCP) ██████████ 100% Approved/Banned list verified - SCM Format Family (7) ██████████ 100% All 7 specs stable & absorbed - RSR Compliance Framework ██████████ 100% Rhodium tiers defined - Governance Templates ██████████ 100% CODE_OF_CONDUCT/etc verified - -SPECIFICATION MODULES - meta-a2ml / state-a2ml ██████████ 100% ABNF & IANA specs stable - agentic-a2ml (Execution) ██████████ 100% Entropy budgets verified - neurosym-a2ml ██████████ 100% Proof obligations active - playbook-a2ml / anchor-a2ml ██████████ 100% Realign/Plan specs stable - ecosystem-a2ml ██████████ 100% Ecosystem positioning stable - -PROTOCOL SPECIFICATIONS - Groove Protocol ████████░░ 80% WIP: reference impls needed - AVOW Protocol ██████░░░░ 60% Draft spec; 0 tests - AXEL Protocol ████████░░ 80% Beta; 14 tests - K9 Self-Validating Components ██████████ 100% Stable; 45 tests - K9 Coordination Protocol ████████░░ 80% Phase 1 (Defensive) - Consent-Aware HTTP ██████░░░░ 60% Draft; spec-focused - Overlay Protocol ████░░░░░░ 40% Spec only; sparse impl - -INTEGRATION & DOGFOODING - VeriSimDB Instance ░░░░░░░░░░ 0% Not yet configured - Hypatia Self-Scan ░░░░░░░░░░ 0% Workflow missing - ECHIDNA Proof Verification ░░░░░░░░░░ 0% Proofs exist but unverified - PanLL Panels ░░░░░░░░░░ 0% No standards panels yet - CRG Self-Assessment ░░░░░░░░░░ 0% Standards not self-graded - -REPO INFRASTRUCTURE - Justfile / Mustfile ██████████ 100% Standard build tasks verified - .machine_readable/ ██████████ 100% STATE tracking active - Multi-Forge Enforcement ██████████ 100% CI/CD quality gates verified - -───────────────────────────────────────────────────────────────────────────── -OVERALL: ████████░░ 80% Core stable; integration layer needed -``` - -## Key Dependencies - -``` -Philosophy ──────► Standards Spec ──────► Implementation ─────► Audit - │ │ │ │ - ▼ ▼ ▼ ▼ -CCCP Policy ─────► 6SCM Family ────────► Repository ────────► Compliance -``` - -## Update Protocol - -This file is maintained by both humans and AI agents. When updating: - -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file - -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Regenerate after any spec change: `just registry` (writes REGISTRY.a2ml + TOPOLOGY.md). +CI (`registry-verify.yml`) runs `--check` and fails the build if either is stale. diff --git a/hypatia-rules/README.adoc b/hypatia-rules/README.adoc index f0ab13ff..992bae60 100644 --- a/hypatia-rules/README.adoc +++ b/hypatia-rules/README.adoc @@ -16,12 +16,22 @@ Groove `compliance.finding.new` signals. | HYP-S003 | `proof-freshness` | Alert when a proof hasn't been re-verified in > 30 days | | HYP-S004 | `rsr-self-compliance` | Validate standards repo against its own RSR definition | | HYP-S005 | `crg-overclaim-detector` | Alert when a self-declared CRG grade lacks v2.0 evidence artefacts | +| HYP-S006 | `registry-staleness` | Alert when REGISTRY.a2ml source hashes go stale or a DERIVED doc (TOPOLOGY.md) drifts | The CRG rule pair (S001 + S005) together enforce grade-honesty: S001 catches backwards moves, S005 catches forwards-overshoots. Both read from `crg-grade` octads in VeriSimDB, but S005 also scans the repo file tree for evidence artefacts required by CRG v2.0 (STRICT). +S006 closes the documentation-drift loop: it recomputes each spec's +`source_hash` from the file tree (the same way `scripts/build-registry.sh` +does) and emits a `doc.drift` signal when the recorded hash is stale or a +generated file (TOPOLOGY.md) was hand-edited. Its `@router` block defaults +to `auto_execute` (regenerate), but **caps any licence/SPDX-overlapping +drift to `:review`** — honouring the Manual-Only licence guardrail in +`.claude/CLAUDE.md`. This is the estate-side mirror of the in-repo +`registry-verify.yml` workflow. + == Implementation Rules live as `.a2ml` files in this directory. They are consumed by diff --git a/hypatia-rules/registry-staleness.a2ml b/hypatia-rules/registry-staleness.a2ml new file mode 100644 index 00000000..9ac7daa1 --- /dev/null +++ b/hypatia-rules/registry-staleness.a2ml @@ -0,0 +1,107 @@ +# SPDX-License-Identifier: AGPL-3.0-or-later +# HYP-S006 — Registry Staleness / Doc Drift +# Detects when the verifiable spec registry (.machine_readable/REGISTRY.a2ml) +# no longer matches the file tree, or when DERIVED docs (TOPOLOGY.md) were +# hand-edited away from their generated form. Drift becomes a routed finding +# the moment it lands — not something noticed 60 days later. +# +# Companion to scripts/build-registry.sh (the generator) and +# .github/workflows/registry-verify.yml (the in-repo --check gate). This rule +# is the estate-side half: it lets Hypatia surface the same drift across the +# fleet and route it through the hybrid automation router. + +@rule(version="1.0"): +id: HYP-S006 +name: "Registry staleness / doc drift" +description: "Alert when a spec's recorded source_hash in REGISTRY.a2ml no longer matches a fresh compute, or a DERIVED doc (TOPOLOGY.md) drifted from its generator" +severity: medium +category: StandardsCompliance +auto_fixable: true +source: standards/hypatia-rules + +@parameters: +# How long a hash mismatch may persist before the finding escalates. +stale_after_days: 14 +critical_after_days: 60 +@end + +@scanner(type="file-tree"): +find: + - glob: ".machine_readable/REGISTRY.a2ml" + - glob: "TOPOLOGY.md" + - glob: "scripts/build-registry.sh" +@end + +@logic(engine="built-in"): +# Recompute each spec's source_hash the same way the generator does +# (sha256 over `git ls-files -s `) and compare to the recorded value. +steps: + - parse_registry: ".machine_readable/REGISTRY.a2ml" + extract: + - key: "home" + as: home + - key: "source_hash" + as: recorded_hash + - for_each_spec: + recompute: "sha256(git ls-files -s ${home})" + compare_to: recorded_hash + emit_if: "recompute != recorded_hash" + finding_kind: registry-hash-stale + - check_home_exists: + emit_if: "home directory absent" + finding_kind: registry-dead-home + - check_derived_docs: + command: "bash scripts/build-registry.sh --check" + emit_if: "non-zero exit" + finding_kind: derived-doc-stale +@end + +# --------------------------------------------------------------------------- +# Hybrid automation router strategy. +# The router decides whether a finding is auto-executed or held for review. +# Doc/registry drift is mechanical and safe to regenerate, EXCEPT where the +# drifted content touches licence/SPDX — those are FLAG-ONLY per the estate +# Manual-Only licence guardrail (.claude/CLAUDE.md) and hypatia +# license_finding_strategy/0. The router MUST honour the cap below. +# --------------------------------------------------------------------------- +@router: +default_strategy: auto_execute # regenerate REGISTRY.a2ml + TOPOLOGY.md +recipe: rebuild-registry +# Hard cap: any finding whose drift overlaps a licence/SPDX token is demoted +# to :review and never auto-applied, mirroring license_finding_strategy/0. +strategy_caps: + - when: "finding touches /SPDX-License-Identifier|PMPL|MPL-2\\.0|AGPL|Palimpsest|licen[cs]e/i" + cap: review + reason: "Manual-Only licence guardrail — agents flag, owner edits (neurophone#99)" + - when: "finding_kind == registry-dead-home" + cap: review + reason: "A missing home is a structural change, not a regen — needs human triage" +@end + +@action: +emit_signal: doc.drift +message_template: >- + Registry drift: {finding_kind} for spec '{id}' (home={home}). + Recorded {recorded_hash}, recompute differs. Run 'just registry' to + regenerate, or triage if the home moved. ({age_days}d since generated) +recipe: rebuild-registry +severity_escalates_at: 60 +halt_on_violation: false +dedupe_window_days: 7 +@end + +@recipe(id="rebuild-registry"): +description: "Regenerate the registry + derived topology from the file tree" +command: "bash scripts/build-registry.sh" +auto_applicable: true +# NOTE: auto_applicable is gated by @router strategy_caps above — a licence- +# overlapping drift is capped to :review and will NOT auto-run this recipe. +@end + +@sibling_rules: +- HYP-S003 proof-freshness — same staleness shape, for proof artefacts +- HYP-S004 rsr-self-compliance — structural self-dogfooding gate +- HYP-S005 crg-overclaim-detector — grade-honesty gate +@end + +@end diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md index bb5165f2..7cd051c1 100644 --- a/llm-warmup-dev.md +++ b/llm-warmup-dev.md @@ -1,16 +1,27 @@ -# LLM Warmup — standards (Developer) +# LLM Warm-up — standards (Developer) -## What is standards? -See README.adoc for overview. +> Thin stub. Canonical machine entry: **`0-AI-MANIFEST.a2ml`**. +> Canonical human entry: **`README.adoc`**. Spec index: **`.machine_readable/REGISTRY.a2ml`**. -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair +## You are working *on* the standards themselves -## Quick Context -- License: PMPL-1.0-or-later -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture +- **Find a spec:** `.machine_readable/REGISTRY.a2ml` (id → home → source_hash). +- **Add/move a spec:** edit the `SPECS` table in `scripts/build-registry.sh`, + then `just registry` (regenerates `REGISTRY.a2ml` + `TOPOLOGY.md`). CI rejects + a spec change that forgets to regenerate (`registry-verify.yml`). +- **Language + licence policy (binding):** `.claude/CLAUDE.md`. + Licence/SPDX is **Manual-Only** — flag drift, never edit it. +- **State you must keep current:** `.machine_readable/6a2/STATE.a2ml`. + +## Key commands + +- `just registry` — regenerate the spec registry + derived topology +- `just registry-check` — fail on drift (what CI runs) +- `just build` / `just test` — build + run the sub-project test suites +- `just doctor` / `just heal` — diagnose / auto-repair + +## Quick context + +- Licence: see `LICENSE` (Manual-Only for agents). +- Part of the Hyperpolymath ecosystem. +- Architecture map (derived): `TOPOLOGY.md`. Drift automation: `REGISTRY.adoc`. diff --git a/llm-warmup-user.md b/llm-warmup-user.md index cb7ee8f0..5707bd78 100644 --- a/llm-warmup-user.md +++ b/llm-warmup-user.md @@ -1,16 +1,22 @@ -# LLM Warmup — standards (User) +# LLM Warm-up — standards (User / Consumer) -## What is standards? -See README.adoc for overview. +> Thin stub. Canonical machine entry: **`0-AI-MANIFEST.a2ml`**. +> Canonical human entry: **`README.adoc`**. Spec index: **`.machine_readable/REGISTRY.a2ml`**. -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair +## You are *applying* these standards to another repo -## Quick Context -- License: PMPL-1.0-or-later -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture +This monorepo is a set of specs to consume, not an app to run. Typical path: + +- **Stand up a compliant repo:** `A2ML-REPO-TEMPLATE.adoc` + the *Usage* section + of `README.adoc`; copy the 7 A2ML files from `a2ml-templates/`. +- **Pick the spec you need:** `.machine_readable/REGISTRY.a2ml` routes you by + `id` → `home` → `canonical_doc` (A2ML family, K9, protocols, readiness grades, + RSR, pre-flight gates). +- **Adopt the enforcement:** copy the relevant `.github/workflows/` + `hooks/`. +- **Language rules you must follow:** `.claude/CLAUDE.md`. + +## Quick context + +- Licence: see `LICENSE`. +- Part of the Hyperpolymath ecosystem. +- "If you want X, go here" routing lives at the top of `README.adoc`. diff --git a/scripts/build-registry.sh b/scripts/build-registry.sh new file mode 100755 index 00000000..67ffcf78 --- /dev/null +++ b/scripts/build-registry.sh @@ -0,0 +1,246 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: AGPL-3.0-or-later +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# build-registry.sh — regenerate the verifiable spec registry and the +# DERIVED topology map from ground truth (the file tree + STATE.a2ml). +# +# This is the generator behind two artefacts that MUST NOT be hand-edited: +# * .machine_readable/REGISTRY.a2ml — the machine index of every spec, +# its canonical home, and a content-addressed `source_hash`. +# * TOPOLOGY.md — the human-readable map, derived +# from the registry + STATE.a2ml so it can never freeze again. +# +# `source_hash` is computed from `git ls-files -s` over each home path: +# that listing already pins every tracked file's blob SHA + path, so any +# content change under a home changes its hash. Hypatia rule HYP-S006 +# (registry-staleness) compares the recorded hash against a fresh compute +# and emits a `doc.drift` finding when they diverge — drift becomes a +# detected, routed event instead of something noticed 60 days later. +# +# Principles (do not violate): +# * Honest. Only specs whose home directory exists are listed. A missing +# home is reported to stderr, never silently invented. +# * Deterministic + idempotent. Run twice → byte-identical output. +# * No network, no commit, no push. Run on a branch; review the diff. +# +# Usage: bash scripts/build-registry.sh # write artefacts +# bash scripts/build-registry.sh --check # verify, non-zero on drift +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +MODE="write" +[ "${1:-}" = "--check" ] && MODE="check" + +REGISTRY=".machine_readable/REGISTRY.a2ml" +TOPOLOGY="TOPOLOGY.md" +GEN_DATE="$(git log -1 --format=%cs 2>/dev/null || date -u +%Y-%m-%d)" + +# --------------------------------------------------------------------------- +# Spec table — the single source of truth for what this monorepo standardises. +# Columns: id | stream | home | name | route (one-line "go here if you want X") +# stream ∈ foundation | language | protocol | governance | readiness | integration +# Add a row here when a new spec lands; the hash + topology follow automatically. +# --------------------------------------------------------------------------- +read -r -d '' SPECS <<'TSV' || true +a2ml|foundation|a2ml/|A2ML — Attested Markup Language|the typed/verified machine-readable document format +k9-svc|foundation|k9-svc/|K9 Self-Validating Components|self-validating components with embedded contracts + deploy logic +contractiles|foundation|contractiles/|Contractiles (Must/Trust/Dust/Intend)|policy-enforcement primitives the K9 layer is built from +meta-a2ml|foundation|meta-a2ml/|META.a2ml spec|architecture decisions / governance metadata format +state-a2ml|foundation|state-a2ml/|STATE.a2ml spec|project-state metadata format (drives this registry's topology) +ecosystem-a2ml|foundation|ecosystem-a2ml/|ECOSYSTEM.a2ml spec|ecosystem-positioning metadata format +agentic-a2ml|foundation|agentic-a2ml/|AGENTIC.a2ml spec|AI-agent operational gating / entropy budgets +neurosym-a2ml|foundation|neurosym-a2ml/|NEUROSYM.a2ml spec|symbolic semantics / proof obligations +playbook-a2ml|foundation|playbook-a2ml/|PLAYBOOK.a2ml spec|executable operational runbooks +anchor-a2ml|foundation|anchor-a2ml/|ANCHOR.a2ml spec|project-recalibration intervention format +0-ai-gatekeeper-protocol|protocol|0-ai-gatekeeper-protocol/|0-AI Gatekeeper Protocol|the AI-agent entry/gating protocol behind 0-AI-MANIFEST +k9-coordination-protocol|protocol|k9-coordination-protocol/|K9 Coordination Protocol|multi-agent coordination on top of K9 +avow-protocol|protocol|avow-protocol/|AVOW Protocol|consent-attested messaging / origin attribution +axel-protocol|protocol|axel-protocol/|AXEL Protocol|age-gating + explicit-content enforcement +overlay-protocol|protocol|overlay-protocol/|Overlay Protocol|layered overlay composition spec +consent-aware-http|protocol|consent-aware-http/|Consent-Aware HTTP|consent headers / AI-usage boundaries for HTTP +adoption-readiness-grades|readiness|adoption-readiness-grades/|ARG — Adoption Readiness Grades|per-language adoption-maturity profile templates +foundations-readiness-grades|readiness|foundations-readiness-grades/|FRG — Foundations Readiness Grades|per-language foundational-maturity profile templates +component-readiness-grades|readiness|component-readiness-grades/|CRG — Component Readiness Grades|the X..A grading system for components +toolchain-readiness-grades|readiness|toolchain-readiness-grades/|TRG — Toolchain Readiness Grades|per-toolchain readiness profile templates +rhodium-standard-repositories|governance|rhodium-standard-repositories/|RSR — Rhodium Standard Repositories|the repository-compliance standard every repo is graded against +session-management-standards|governance|session-management-standards/|Session Management Standards|continuity / verify / handover protocols +ensaid-config|governance|ensaid-config/|ENSAID Config|the ensaid configuration standard +accessibility|governance|accessibility/|Accessibility Standard|estate accessibility requirements +publication-pre-flight|governance|publication-pre-flight/|Publication Pre-Flight|submission gate (HOL + Zenodo checklists) +release-pre-flight|governance|release-pre-flight/|Release Pre-Flight (V1 Gate)|hard v1.0.0 audit requirements +hypatia-rules|integration|hypatia-rules/|Standards Hypatia Rules|the dogfooding rules that scan THIS repo (incl. drift detection) +a2ml-templates|integration|a2ml-templates/|A2ML Templates|copy-in templates for the 7 A2ML files +TSV + +# Pick the canonical human doc for a home: README.adoc > README.md > first *.adoc spec. +canonical_doc() { + local home="$1" + for c in "${home}README.adoc" "${home}README.md"; do + [ -f "$c" ] && { printf '%s' "$c"; return; } + done + local first + first="$(git ls-files -- "${home}" | grep -iE '\.(adoc|a2ml)$' | head -1 || true)" + printf '%s' "${first:-${home}}" +} + +# Content-addressed hash of everything tracked under a home path. +home_hash() { + local home="$1" + git ls-files -s -- "$home" | sha256sum | cut -d' ' -f1 +} + +# --------------------------------------------------------------------------- +# Emit REGISTRY.a2ml +# --------------------------------------------------------------------------- +emit_registry() { + cat <
+# +# REGISTRY.a2ml — the verifiable index of every spec/standard in this monorepo. +# +# GENERATED FILE — DO NOT EDIT BY HAND. +# Regenerate with: bash scripts/build-registry.sh (or: just registry) +# Source of truth: the SPECS table in scripts/build-registry.sh + the file tree. +# +# Each entry's \`source_hash\` is a sha256 over \`git ls-files -s \`, so it +# changes whenever any tracked file under the spec's home changes. Hypatia rule +# HYP-S006 (hypatia-rules/registry-staleness.a2ml) recomputes these and emits a +# \`doc.drift\` finding (strategy :review) when a recorded hash goes stale. + +[registry] +version = "1.0.0" +generated = "${GEN_DATE}" +generator = "scripts/build-registry.sh" +hash_algorithm = "sha256(git ls-files -s )" +entry_count = ${ENTRY_COUNT} + +[registry.streams] +foundation = "A2ML format family + K9 + contractiles (Stream 1)" +language = "AffineScript and language-policy specs (Stream 2)" +protocol = "Inter-service / agent protocols" +governance = "RSR, readiness grading, pre-flight gates, session standards" +readiness = "ARG / FRG / CRG / TRG maturity-grading frameworks" +integration = "Registry, hypatia rules, templates — the wiring (Stream 3)" +HEADER + + while IFS='|' read -r id stream home name route; do + [ -z "$id" ] && continue + if [ ! -d "$home" ]; then + echo "WARN: home missing for '$id' ($home) — skipped" >&2 + continue + fi + local doc hash + doc="$(canonical_doc "$home")" + hash="$(home_hash "$home")" + cat </dev/null | head -1 \ + | sed -E 's/^[^=]*=[[:space:]]*//; s/[[:space:]]*#.*$//; s/[[:space:]]+$//; s/^"//; s/"$//' +} + +emit_topology() { + local phase maturity updated + phase="$(state_field phase)"; maturity="$(state_field maturity)" + updated="$(state_field last-updated)" + cat <
+ + + +# Hyperpolymath Standards — Topology (derived) + +> This file is **generated** from \`.machine_readable/REGISTRY.a2ml\` and +> \`.machine_readable/6a2/STATE.a2ml\` by \`scripts/build-registry.sh\`. +> It cannot freeze: every regeneration re-reads ground truth. Do not edit by hand. + +- **Phase:** ${phase:-unknown}  |  **Maturity:** ${maturity:-unknown}  |  **STATE last-updated:** ${updated:-unknown} +- **Registry entries:** ${ENTRY_COUNT} specs across 6 streams +- **Front door:** human → [README.adoc](README.adoc); machine → [0-AI-MANIFEST.a2ml](0-AI-MANIFEST.a2ml) +- **Registry:** [.machine_readable/REGISTRY.a2ml](.machine_readable/REGISTRY.a2ml) (index + source hashes) · prose: [REGISTRY.adoc](REGISTRY.adoc) + +## Specs by stream + +HEADER + + for s in foundation language protocol governance readiness integration; do + local label + case "$s" in + foundation) label="Foundation — A2ML family + K9 + contractiles (Stream 1)";; + language) label="Language — AffineScript + language policy (Stream 2)";; + protocol) label="Protocols";; + governance) label="Governance — RSR, gates, session standards";; + readiness) label="Readiness grading — ARG / FRG / CRG / TRG";; + integration)label="Integration — registry, hypatia rules, templates (Stream 3)";; + esac + # only print the section if it has rows + if grep -q "|${s}|" <<< "$SPECS"; then + printf '### %s\n\n' "$label" + printf '| Spec | Home | If you want… |\n|---|---|---|\n' + while IFS='|' read -r id stream home name route; do + [ -z "$id" ] && continue + [ "$stream" = "$s" ] || continue + [ -d "$home" ] || continue + printf '| %s | [`%s`](%s) | %s |\n' "$name" "$home" "$home" "$route" + done <<< "$SPECS" + printf '\n' + fi + done + + cat <<'FOOTER' +## How this map stays honest + +``` +file tree + STATE.a2ml ──► scripts/build-registry.sh ──► REGISTRY.a2ml ──► TOPOLOGY.md + ▲ │ + │ ▼ + just registry / CI HYP-S006 (registry-staleness) + (registry-verify.yml) emits doc.drift on hash mismatch +``` + +Regenerate after any spec change: `just registry` (writes REGISTRY.a2ml + TOPOLOGY.md). +CI (`registry-verify.yml`) runs `--check` and fails the build if either is stale. +FOOTER +} + +ENTRY_COUNT="$(grep -c '^[a-z0-9]' <<< "$SPECS" || true)" + +if [ "$MODE" = "check" ]; then + tmp_r="$(mktemp)"; tmp_t="$(mktemp)" + emit_registry > "$tmp_r"; emit_topology > "$tmp_t" + rc=0 + if ! diff -q "$tmp_r" "$REGISTRY" >/dev/null 2>&1; then + echo "DRIFT: $REGISTRY is stale — run 'just registry'"; rc=1; fi + if ! diff -q "$tmp_t" "$TOPOLOGY" >/dev/null 2>&1; then + echo "DRIFT: $TOPOLOGY is stale — run 'just registry'"; rc=1; fi + rm -f "$tmp_r" "$tmp_t" + [ "$rc" -eq 0 ] && echo "OK: registry + topology are in sync with the file tree." + exit "$rc" +fi + +emit_registry > "$REGISTRY" +emit_topology > "$TOPOLOGY" +echo "Wrote $REGISTRY and $TOPOLOGY ($ENTRY_COUNT specs)." From f805bdcf4c30f63f45cdd71cd0d170f6d0dc4a7f Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 3 Jun 2026 16:00:35 +0000 Subject: [PATCH 2/4] docs(licence): correct doc badges PMPL-1.0 -> MPL-2.0 to match LICENSE [OWNER REVIEW] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ⚠️ OWNER REVIEW REQUIRED — documentation-accuracy fix, NOT a relicensing. The repo's actual LICENSE file is MPL-2.0 (set owner-directed in #354), but several DOC BADGES / prose lines still asserted PMPL-1.0-or-later. This commit corrects only those human-facing descriptions to match the LICENSE file: - README.adoc: License badge PMPL-1.0 -> MPL-2.0; dropped the Palimpsest 'Philosophy' badge (this is not a Palimpsest carve-out repo); Licensing bullet, repo-structure LICENSE line, and == License section -> MPL-2.0 with a Manual-Only / owner-only note. - ROADMAP.adoc: License row -> MPL-2.0. - QUICKSTART-MAINTAINER.adoc: Security-Notes licence line -> MPL-2.0. - PALIMPSEST.adoc: added a clarifying NOTE that this document describes the PMPL framework generally and that THIS repo is MPL-2.0; Palimpsest applies only to palimpsest-license / palimpsest-plasma / consent-aware-http. This commit is deliberately isolated so it can be reviewed or dropped on its own. NO LICENSE file and NO SPDX header is touched (those remain owner-only, Manual-Only). Per .claude/CLAUDE.md this is proposed for owner review, not swept. https://claude.ai/code/session_011xv3VLrqeXkpjXxUojKz82 --- PALIMPSEST.adoc | 10 ++++++++++ QUICKSTART-MAINTAINER.adoc | 2 +- README.adoc | 15 +++++++++------ ROADMAP.adoc | 4 ++-- 4 files changed, 22 insertions(+), 9 deletions(-) diff --git a/PALIMPSEST.adoc b/PALIMPSEST.adoc index cac77799..6dd9c23c 100644 --- a/PALIMPSEST.adoc +++ b/PALIMPSEST.adoc @@ -7,6 +7,16 @@ Jonathan D.A. Jewell image:https://img.shields.io/badge/License-PMPL--1.0--or--later-blue.svg[PMPL-1.0-or-later,link="https://github.com/hyperpolymath/palimpsest-license"] image:https://img.shields.io/badge/Legal_fallback-MPL--2.0-orange.svg[MPL-2.0 fallback,link="https://www.mozilla.org/en-US/MPL/2.0/"] +[IMPORTANT] +==== +*This document describes the Palimpsest/PMPL framework as a general reference. +It does NOT state the licence of this `standards` repository.* Per the estate +licence policy (link:.claude/CLAUDE.md[.claude/CLAUDE.md]), the Palimpsest / +PMPL carve-out applies only to `palimpsest-license`, `palimpsest-plasma`, and +(prospectively) `consent-aware-http`. This repository is licensed *MPL-2.0* +(see link:LICENSE[LICENSE]). Licence/SPDX changes are owner-only and Manual-Only. +==== + == Licence Summary [cols="1,2"] diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index 34a3a0c9..1ae0c091 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -110,7 +110,7 @@ Or via OPSM: `opsm update standards` == Security Notes -* License: PMPL-1.0-or-later (Palimpsest License) +* Licence: MPL-2.0 (see link:LICENSE[LICENSE]) * All dependencies SHA-pinned * `panic-attacker` scan results: link:INSTALL-SECURITY-REPORT.adoc[] * OpenSSF Scorecard: see badge in README diff --git a/README.adoc b/README.adoc index 096f69c9..a55a2f11 100644 --- a/README.adoc +++ b/README.adoc @@ -1,7 +1,6 @@ = Hyperpolymath Standards -image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] -image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] +image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: MPL-2.0,link="https://www.mozilla.org/MPL/2.0/"] :toc: macro :toc-placement!: @@ -82,7 +81,7 @@ This repository serves as the canonical source for policies, templates, and spec * **Contractiles / K9** -- link:contractiles/CANONICAL-TEMPLATES.adoc[canonical Must/Trust/Dust/Intent semantics] and Kennel/Yard/Hunt guidance * **Governance Templates** -- Reusable CODE_OF_CONDUCT, CONTRIBUTING, and SECURITY documents * **CODEOWNERS Policy** -- link:CODEOWNERS-POLICY.adoc[canonical `CODEOWNERS` rules] (no catch-all/workflow lines on solo-owned repos) -* **Licensing Framework** -- PMPL-1.0-or-later with Palimpsest philosophical principles +* **Licensing** -- MPL-2.0 (see link:LICENSE[LICENSE]); licence/SPDX changes are owner-only (see link:.claude/CLAUDE.md[.claude/CLAUDE.md]) * **Enforcement** -- CI/CD workflows and pre-commit hooks == Standards Ecosystem @@ -417,7 +416,7 @@ standards/ +-- CODE_OF_CONDUCT.md # Template +-- CONTRIBUTING.md # Template +-- SECURITY.md # Template -+-- LICENSE.txt # PMPL-1.0-or-later + Palimpsest ++-- LICENSE # MPL-2.0 +-- ROADMAP.adoc +-- README.adoc # This file ---- @@ -472,9 +471,13 @@ standards/ == License -PMPL-1.0-or-later with Palimpsest philosophical overlay. +MPL-2.0. See link:LICENSE[LICENSE] for full terms. -See link:LICENSE[LICENSE] for full terms. +NOTE: Licence and SPDX headers in this repo are *owner-managed and +Manual-Only* — agents flag licence drift, they never edit `LICENSE` files or +SPDX headers (see link:.claude/CLAUDE.md[.claude/CLAUDE.md]). The Palimpsest / +PMPL framework applies only to `palimpsest-license`, `palimpsest-plasma`, and +(prospectively) `consent-aware-http` — not to this repository. == Contributing diff --git a/ROADMAP.adoc b/ROADMAP.adoc index 7a7822c7..ae43ff6f 100644 --- a/ROADMAP.adoc +++ b/ROADMAP.adoc @@ -16,8 +16,8 @@ Development roadmap for the Hyperpolymath standards and specifications repositor |Comprehensive allowed/banned language specification |Complete -|**License Framework** -|PMPL-1.0-or-later with Palimpsest philosophical overlay +|**License** +|MPL-2.0 (see LICENSE; licence/SPDX is owner-managed, Manual-Only) |Complete |**A2ML Format Family (7)** From 83e83a65d411641c9412e016a329a592bda81df7 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 3 Jun 2026 16:02:27 +0000 Subject: [PATCH 3/4] fix(registry): make generator output deterministic (drop volatile date) The generator stamped a commit-derived date into REGISTRY.a2ml and TOPOLOGY.md, so the output changed on every commit and 'build-registry.sh --check' (and thus registry-verify CI) would spuriously report drift. Remove the timestamp: the output is now a pure function of the committed tree (spec hashes + STATE), so --check is stable. https://claude.ai/code/session_011xv3VLrqeXkpjXxUojKz82 --- .machine_readable/REGISTRY.a2ml | 3 +-- TOPOLOGY.md | 2 +- scripts/build-registry.sh | 7 ++++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.machine_readable/REGISTRY.a2ml b/.machine_readable/REGISTRY.a2ml index ff8e806e..e151a695 100644 --- a/.machine_readable/REGISTRY.a2ml +++ b/.machine_readable/REGISTRY.a2ml @@ -14,7 +14,6 @@ [registry] version = "1.0.0" -generated = "2026-06-02" generator = "scripts/build-registry.sh" hash_algorithm = "sha256(git ls-files -s )" entry_count = 28 @@ -267,7 +266,7 @@ name = "Standards Hypatia Rules" stream = "integration" home = "hypatia-rules/" canonical_doc = "hypatia-rules/README.adoc" -source_hash = "sha256:b7e8942d6676f507d676527d7d6aa0e2b20931c837f990f76041cfbd123be823" +source_hash = "sha256:707852684795e8474bc764473c36bc4d56fa139014ab3abbc0f550319637138c" route = "the dogfooding rules that scan THIS repo (incl. drift detection)" [[spec]] diff --git a/TOPOLOGY.md b/TOPOLOGY.md index 882da79e..4d1839c2 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.md @@ -1,5 +1,5 @@ - + # Hyperpolymath Standards — Topology (derived) diff --git a/scripts/build-registry.sh b/scripts/build-registry.sh index 67ffcf78..56e8a08f 100755 --- a/scripts/build-registry.sh +++ b/scripts/build-registry.sh @@ -35,7 +35,9 @@ MODE="write" REGISTRY=".machine_readable/REGISTRY.a2ml" TOPOLOGY="TOPOLOGY.md" -GEN_DATE="$(git log -1 --format=%cs 2>/dev/null || date -u +%Y-%m-%d)" +# Intentionally NO generation timestamp: a volatile date would make every +# regeneration differ and defeat `--check`. The content (hashes + STATE) is the +# only source of truth, so the output is a pure function of the committed tree. # --------------------------------------------------------------------------- # Spec table — the single source of truth for what this monorepo standardises. @@ -112,7 +114,6 @@ emit_registry() { [registry] version = "1.0.0" -generated = "${GEN_DATE}" generator = "scripts/build-registry.sh" hash_algorithm = "sha256(git ls-files -s )" entry_count = ${ENTRY_COUNT} @@ -168,7 +169,7 @@ emit_topology() { updated="$(state_field last-updated)" cat <
- + # Hyperpolymath Standards — Topology (derived) From f2e3d0984b2946622c0a0af175d692b6e3a34a91 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 3 Jun 2026 16:05:33 +0000 Subject: [PATCH 4/4] ci(registry-verify): add timeout-minutes to the verify job Closes the one Hypatia workflow_audit finding (missing_timeout_minutes) that applies to the workflow this PR adds. The other 223 findings in the scan are pre-existing estate-wide workflow hygiene on unrelated workflows, out of scope for this PR. https://claude.ai/code/session_011xv3VLrqeXkpjXxUojKz82 --- .github/workflows/registry-verify.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/registry-verify.yml b/.github/workflows/registry-verify.yml index 6373cf9d..cd693c04 100644 --- a/.github/workflows/registry-verify.yml +++ b/.github/workflows/registry-verify.yml @@ -22,6 +22,7 @@ jobs: verify: name: Registry + topology in sync runs-on: ubuntu-latest + timeout-minutes: 10 steps: - name: Checkout repository uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2