0-AI-MANIFEST.a2ml

# STOP - CRITICAL READING REQUIRED

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

## WHAT IS THIS?

This is the AI manifest for **k9iser**. k9iser analyses configuration files
(TOML, YAML, JSON, Nickel), infers constraints, generates K9 contracts,
validates configs against those contracts, and attests compliance with
cryptographic signatures.

K9 contracts encode four pillars: must (required constraints), trust (verified
sources), dust (cleanup rules), and intend (intent declarations). They
integrate with the contractile CLI system (must/trust/dust/intend/k9
validators).

## 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 automated agents.

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

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

This directory is especially significant for k9iser — the K9 contract
templates and validators live here:
- `.machine_readable/contractiles/k9/` — K9 contract templates by tier
- `.machine_readable/contractiles/k9/validators/` — K9 validator implementations
- `.machine_readable/contractiles/k9/examples/` — Example K9 contracts

### 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)

## REPOSITORY STRUCTURE

```
k9iser/
├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
├── README.adoc                 # What k9iser does, architecture, use cases
├── ROADMAP.adoc                # Phase 0-6 development plan
├── CONTRIBUTING.adoc           # Human contribution guide
├── Justfile                    # Task runner
├── Containerfile               # OCI build (Chainguard base)
├── Cargo.toml                  # Rust crate manifest
├── LICENSE                     # PMPL-1.0-or-later
├── src/                        # Rust source code
│   ├── main.rs                 # CLI entry point (clap)
│   ├── lib.rs                  # Library API
│   ├── manifest/               # k9iser.toml parser
│   ├── codegen/                # K9 contract code generation
│   ├── core/                   # Constraint inference, validation engine
│   ├── contracts/              # K9 contract data model
│   ├── definitions/            # Built-in constraint definitions
│   ├── errors/                 # Structured error types
│   ├── bridges/                # Format-specific parsers (TOML, YAML, JSON, Nickel)
│   ├── aspects/                # Cross-cutting (logging, attestation)
│   └── interface/              # Verified Interface Seams
│       ├── abi/                # Idris2 ABI — K9 contract domain types + proofs
│       │   ├── Types.idr       # K9Contract, Constraint, MustRule, etc.
│       │   ├── Layout.idr      # Contract struct layout proofs
│       │   └── Foreign.idr     # FFI declarations for validation engine
│       ├── ffi/                # Zig FFI — C-ABI validation bridge
│       │   ├── build.zig
│       │   ├── src/main.zig
│       │   └── test/integration_test.zig
│       └── generated/          # Auto-generated C headers
├── container/                  # Stapeln container ecosystem
├── docs/                       # Technical documentation
└── .machine_readable/          # ALL machine-readable metadata
    ├── 6a2/                    # STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK
    ├── contractiles/k9/        # K9 contract templates and validators
    ├── anchors/                # ANCHOR.a2ml
    ├── policies/               # Maintenance policies
    └── bot_directives/         # Bot configuration
```

## DOMAIN-SPECIFIC INVARIANTS

1. **K9 pillars** — every generated contract MUST contain all four pillars:
   must, trust, dust, intend. Even if a pillar has zero rules, its section
   must be present.
2. **Safety tiers** — every contract MUST be assigned exactly one tier:
   Kennel (safe), Yard (moderate), or Hunt (powerful).
3. **Config format support** — the parser MUST handle TOML, YAML, JSON,
   and Nickel. No other formats without an ADR.
4. **Contractile compatibility** — generated `.k9.ncl` contracts MUST be
   consumable by the `k9` validator from the contractile CLI.

## 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`

## SESSION STARTUP CHECKLIST

Read THIS file (0-AI-MANIFEST.a2ml) first
Understand canonical location: `.machine_readable/`
State understanding of canonical locations
Read STATE.a2ml for current progress
Read ECOSYSTEM.a2ml for integration context

## ATTESTATION PROOF

**"I have read the AI manifest for k9iser. 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. I understand that k9iser generates K9 contracts with four pillars (must, trust, dust, intend) at three safety tiers (Kennel, Yard, Hunt)."**