// SPDX-License-Identifier: CC-BY-SA-4.0
// 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

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

=== Option A: Guix (preferred)

[source,bash]
----
guix shell
----

=== Option B: Nix (fallback)

[source,bash]
----
nix develop
----

=== Option C: Manual

[source,bash]
----
git clone https://github.com/hyperpolymath/standards.git
cd standards
just setup-dev
----

== Build

[source,bash]
----
just build          # builds the Rust/Zig sub-project artefacts
----

== Test

[source,bash]
----
just test           # runs every sub-project test suite
----

== Project Structure

[source]
----
standards/
├── 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 / 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

[source,bash]
----
just build          # Build the project
just test           # Run tests
just doctor         # Self-diagnostic
just lint           # Lint and format
just panic-scan     # Security scan via panic-attacker
just tour           # Guided tour of the codebase
----

== Before Submitting a PR

[source,bash]
----
just lint           # Format and lint
just test           # All tests pass
just panic-scan     # No new security issues
----

== Contractile Invariants

Read `.machine_readable/MUST.contractile` before making changes.
Key invariants that must never be violated:

* 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

If using an AI assistant, load the warmup context first:

[source,bash]
----
just llm-context    # Outputs role-appropriate context
----

Or read `0-AI-MANIFEST.a2ml` and `.claude/CLAUDE.md` directly.

== Get Help

* **Architecture**: link:EXPLAINME.adoc[EXPLAINME.adoc]
* **Wiki**: https://github.com/hyperpolymath/standards/wiki
* **Report issue**: `just help-me`
