0-AI-MANIFEST.a2ml

# SPDX-License-Identifier: PMPL-1.0-or-later
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

# ⚠️ STOP - CRITICAL READING REQUIRED

**THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**

## WHAT IS THIS?

This is the AI manifest for **betlangiser**. It declares:
- Canonical file locations (where things MUST be, and nowhere else)
- Critical invariants (rules that must NEVER be violated)
- Repository structure and organization

Betlangiser adds ternary probabilistic modelling to deterministic code
via Betlang. It analyses source code, identifies values that should be
probabilistic, wraps them in distributions, and generates
uncertainty-propagating code with ternary logic (true/false/unknown).

## CANONICAL LOCATIONS (UNIVERSAL RULE)

### Machine-Readable Metadata: `.machine_readable/` ONLY

These 6 a2ml files MUST exist in `.machine_readable/` directory ONLY:
1. **STATE.a2ml** - Project state, progress, blockers
2. **META.a2ml** - Architecture decisions, governance
3. **ECOSYSTEM.a2ml** - Position in ecosystem, relationships
4. **AGENTIC.a2ml** - AI agent interaction patterns
5. **NEUROSYM.a2ml** - Neurosymbolic integration config
6. **PLAYBOOK.a2ml** - Operational runbook

**CRITICAL:** If ANY of these files exist in the root directory, this is an ERROR.

### Anchor File: `.machine_readable/anchors/ANCHOR.a2ml` ONLY

Canonical authority and semantic-boundary declaration MUST exist at:

` .machine_readable/anchors/ANCHOR.a2ml `

Do not place `ANCHOR.a2ml` at repository root.

### Maintenance Policies: `.machine_readable/policies/` ONLY

Canonical maintenance/governance files MUST exist under:

` .machine_readable/policies/ `

Minimum required files:
- `MAINTENANCE-AXES.a2ml`
- `MAINTENANCE-CHECKLIST.a2ml`
- `SOFTWARE-DEVELOPMENT-APPROACH.a2ml`

Do not place maintenance policy files in repository root.

### Bot Directives: `.machine_readable/bot_directives/` ONLY

Bot-specific instructions for your automated agents.

### Contractiles: `.machine_readable/contractiles/` ONLY

Policy enforcement contracts (k9, dust, lust, must, trust).

### AI Configuration & Guides: `.machine_readable/ai/` ONLY

- `AI.a2ml` - Language-specific or LLM-specific patterns
- `PLACEHOLDERS.md` - Bootstrap guide

### Community & Forge Metadata: `.github/` ONLY

- `CODEOWNERS` - Review assignments
- `MAINTAINERS` - Machine-readable contact list
- `SUPPORT` - Support channels
- `SECURITY.md` - Technical security policy
- `CONTRIBUTING.md` - Technical contribution manual
- `CODE_OF_CONDUCT.md` - Conduct rules

### Agent Instructions

- `0-AI-MANIFEST.a2ml` - THIS FILE (universal entry point)

## CORE INVARIANTS

1. **No state file duplication** - Root must NOT contain STATE.a2ml, META.a2ml, etc.
2. **Single source of truth** - `.machine_readable/` is authoritative
3. **No stale metadata** - If root state files exist, they are OUT OF DATE
4. **License consistency** - All code PMPL-1.0-or-later unless platform requires MPL-2.0
5. **Author attribution** - Always "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"
6. **Container images** - MUST use Chainguard base (`cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`)
7. **Container runtime** - Podman, never Docker. Files are `Containerfile`, never `Dockerfile`
8. **Container orchestration** - `selur-compose`, never `docker-compose`
9. **Distribution parameters** - Must be validated at type level (Idris2 dependent types)
10. **Ternary logic** - Kleene strong three-valued logic only, never Priest or Bochvar

## REPOSITORY STRUCTURE

This repo follows the **Dual-Track** architecture:

```
betlangiser/
├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
├── README.adoc                 # High-level orientation (Rich Human)
├── ROADMAP.adoc                # Future direction (6 phases)
├── TOPOLOGY.md                 # Structural map
├── Cargo.toml                  # Rust build configuration
├── LICENSE                     # PMPL-1.0-or-later
├── src/                        # Source code
│   ├── main.rs                 # Rust CLI (clap subcommands)
│   ├── lib.rs                  # Library exports
│   ├── manifest/               # betlangiser.toml parser
│   ├── codegen/                # Betlang wrapper generation
│   ├── core/                   # Analysis logic
│   └── interface/              # Verified Interface Seams
│       ├── abi/                # Idris2 ABI (Distribution, TernaryBool proofs)
│       ├── ffi/                # Zig FFI (sampling engine, ternary logic)
│       └── generated/          # C Headers
├── .machine_readable/          # ALL machine-readable metadata
│   ├── 6a2/                    # Core state files (STATE, META, ECOSYSTEM, etc.)
│   ├── CLADE.a2ml              # Clade taxonomy
│   └── ENSAID_CONFIG.a2ml      # PanLL environment config
├── .claude/                    # Claude Code instructions
└── .github/                    # Workflows and community metadata
```

## SESSION STARTUP CHECKLIST

✅ Read THIS file (0-AI-MANIFEST.a2ml) first
✅ Understand canonical location: `.machine_readable/`
✅ State understanding of canonical locations

## ATTESTATION PROOF

**"I have read the AI manifest. All machine-readable content (state files, anchors, policies, bot directives, contractiles, AI guides) is located in `.machine_readable/` ONLY, and community metadata is in `.github/`. I will not create duplicate files in the root directory."**