Skip to content

AI-CONVENTIONS.adoc

Latest commit

 

History

History
85 lines (63 loc) · 3.65 KB

AI-CONVENTIONS.adoc

File metadata and controls

85 lines (63 loc) · 3.65 KB
Raw

AI Conventions

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/descriptiles/STATE.a2ml for current status and blockers.

  3. Read .machine_readable/descriptiles/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/descriptiles/AGENTIC.a2ml for agent constraints.

License

  • All original code: MPL-2.0

  • 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) Jonathan D.A. Jewell <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/descriptiles/AGENTIC.a2ml — agent permissions and constraints

  • .machine_readable/descriptiles/STATE.a2ml — current project state

  • .machine_readable/descriptiles/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