= AI Conventions
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> -->

# AI Conventions (Authoritative Source)

All AI coding agents working in this repository MUST follow these rules.
Per-tool config files (.cursorrules, .clinerules, etc.) reference this document.

## Session Startup

1. Read `0-AI-MANIFEST.a2ml` FIRST (mandatory gatekeeper).
2. Read `.machine_readable/STATE.a2ml` for current status and blockers.
3. Read `.machine_readable/anchors/ANCHOR.a2ml` for canonical authority boundaries.
4. Read `.machine_readable/policies/MAINTENANCE-AXES.a2ml` for maintenance/audit sequencing.
5. Read `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` for baseline controls.
6. Read `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` for execution order.
7. Read `.machine_readable/AGENTIC.a2ml` for agent constraints.

## License

- All original code: **PMPL-1.0-or-later**
- Fallback (platform-required only): MPL-2.0 with comment explaining why.
- NEVER use AGPL-3.0.
- Preserve third-party licenses verbatim.
- Every source file needs `# SPDX-License-Identifier: CC-BY-SA-4.0`.

## Author Attribution

- Name: **Jonathan D.A. Jewell**
- Email: **j.d.a.jewell@open.ac.uk**
- Copyright: `Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>`

## State Files

State/metadata files, anchors, and policies (.a2ml) belong in `.machine_readable/` ONLY.
NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml,
NEUROSYM.a2ml, PLAYBOOK.a2ml, ANCHOR.a2ml, MAINTENANCE-AXES.a2ml,
MAINTENANCE-CHECKLIST.a2ml, or SOFTWARE-DEVELOPMENT-APPROACH.a2ml in the repository root.

## Banned Patterns

| Language | Banned                              | Reason                    |
|----------|-------------------------------------|---------------------------|
| Idris2   | `believe_me`, `assert_total`        | Unsound escape hatches    |
| Haskell  | `unsafeCoerce`, `unsafePerformIO`   | Breaks type safety        |
| OCaml    | `Obj.magic`, `Obj.repr`, `Obj.obj`  | Unsafe casting            |
| Coq      | `Admitted`                          | Unproven assumption       |
| Lean     | `sorry`                             | Unproven assumption       |
| Rust     | `transmute` (unless FFI + SAFETY:)  | Unsound reinterpret       |

## Banned Languages

| Banned              | Use Instead        |
|---------------------|--------------------|
| TypeScript          | ReScript           |
| Node.js / npm / bun | Deno               |
| Go                  | Rust               |
| Python              | Julia / Rust       |

## Container Standard

- Runtime: **Podman** (never Docker).
- File: **Containerfile** (never Dockerfile).
- Base images: `cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`.

## ABI/FFI Standard

- ABI definitions: **Idris2** with dependent types (`src/abi/`).
- FFI implementation: **Zig** with C ABI compatibility (`ffi/zig/`).
- Generated C headers: `generated/abi/`.

## Build System

Use `just` (Justfile) for all build, test, lint, and format tasks.

## References

- `0-AI-MANIFEST.a2ml` -- universal AI entry point
- `.machine_readable/AGENTIC.a2ml` -- agent permissions and constraints
- `.machine_readable/STATE.a2ml` -- current project state
- `.machine_readable/anchors/ANCHOR.a2ml` -- canonical authority and policy boundary
- `.machine_readable/policies/MAINTENANCE-AXES.a2ml` -- canonical axis sequencing and audit requirements
- `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` -- baseline maintenance checklist policy
- `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` -- axis execution approach policy
