Skip to content

AGENTS.adoc

Latest commit

 

History

History
72 lines (58 loc) · 3.74 KB

AGENTS.adoc

File metadata and controls

72 lines (58 loc) · 3.74 KB
Raw

Repository instructions

This repository is the canonical general standards authority for the Hyperpolymath estate. Read 0-AI-MANIFEST.a2ml, README.adoc, and 0-canon/constitution/README.adoc in that order before changing normative material.

Constitutional, normative, profile, local-policy, guidance, template, implementation, generated, and historical material are distinct authority classes. A proposal is not authorised policy until the applicable change procedure is completed. Evidence records what currently holds; it does not gain authority merely by being generated or machine-readable.

Canonical sources include 0-canon/constitution/, domain standard sources, and profile sources. TOPOLOGY.adoc is a frozen snapshot: never edit it directly. Preserve licences, coined names, MAA’s independent authority, and current language/build conventions. Do not add TypeScript or Deno, weaken validation, or describe draft/tested work as proven.

A2ML is retired (D99, D269c, D312, D313). Never create, restore or extend a .a2ml file. Repo metadata goes in <repo>_chora.deed clauses (grammar 1-formats/deed/spec/abnf/deed.abnf), contracts in *.k9.ncl, and agent coordination in coordination.k9 (grammar 2-protocols/k9-coordination/spec/abnf/coordination-k9-grammar_v1.2.abnf). 1-formats/deed/mappings/ says where former A2ML content goes.

Fork governance (read before opening a pull request)

Every pull request carries one generated comment titled Fork governance: a summary of three lanes, then the K9-DEED conformance grid, then the Hypatia verdict grid, in that order. The lanes are .github/workflows/deed-conformance.yml, k9-conformance.yml and hypatia-scan-reusable.yml, run by fork-governance.yml and posted by fork-governance-reusable.yml.

The normative documentation — comment contract, lane definitions, adoption and the discovery chain — is 3-practice/fork-governance/ (AsciiDoc). The machine-readable route is the :governance entry in the routing clause of standards_chora.deed.

Do not hand-edit a fork governance comment, and do not add a fourth lane without changing SPEC.adoc first: the section order and the markers are a contract with every repository that calls this one.

The canon–spine seam (read before adding a workflow or a doc class)

hyperpolymath/standards is the canon; hyperpolymath/rsr-template-repo is the spine that mints every other repository. They are one system with one wired half: the canon is checked against the spine (Gate A), and nothing checks the spine against the canon. Adoption is therefore a habit — 8 of the 22 reusable workflows the canon offers are called by the spine, and 23 of its 32 workflow files call nothing at all.

Consequences for an agent working here or there:

  • Adding a workflow to the spine? Check for a *-reusable.yml here first. If one does the job, call it. If not, the registry (see the proposal) is where the local copy must be classified.

  • Editing a GENERATED file? Edit its source. CLAUDE.md is generated from the repo deed; the workflow pins will be generated from canon.lock.

  • Widening or narrowing a check? Widening scope is a decision. Narrowing a check to make it pass is indistinguishable from deleting it.

Documentation, in AsciiDoc, is 3-practice/canon-spine/: README.adoc for the two roles and the measured seam, PROPOSAL.adoc for the diagnosis and the change list.

Run the relevant just/must targets, deed validation (bun 1-formats/deed/tools/deed_lint.js), Nickel/K9 validation (1-formats/k9/tools/k9-validate.sh --strict) where applicable, link/canonical-name checks, and git diff --check. Regenerate twice and require a clean second pass for generated outputs.