= AI Conventions
<!-- SPDX-License-Identifier: PMPL-1.0-or-later -->
<!-- Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -->
# 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: PMPL-1.0-or-later`.
## Author Attribution
- Name: **{{AUTHOR}}**
- Email: **{{AUTHOR_EMAIL}}**
- Copyright: `Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>`
## 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