0-AI-MANIFEST.a2ml

# SPDX-License-Identifier: MPL-2.0
# STOP - CRITICAL READING REQUIRED

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

## WHAT IS THIS?

This is the AI manifest for **palimpsest-plasma** — a deterministic, typed
**policy engine** for the agentic era.

You write policies as machine-readable deontic rules (obligations,
prohibitions, permissions over repository state); `plasma check` evaluates a
repository against them with byte-for-byte reproducible results. The project
is implemented in **Rust** (three crates). It is the policy-definition and
compliance-evaluation member of a planned trio with `somethings-fishy`
(forensic bot-damage investigation) and `did-you-actually-do-that` (agent
claim verification).

**The Palimpsest license (PMPL) is a SEPARATE, FUTURE project.** This repo's
parser merely recognises PMPL SPDX identifiers. Do not reintroduce PMPL as
this project's identity.

## CANONICAL LOCATIONS (UNIVERSAL RULE)

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

1. **STATE.a2ml** - Project state, progress, blockers
2. **META.a2ml** - Architecture decisions, governance
3. **ECOSYSTEM.a2ml** - Position in ecosystem, sibling projects
4. **AGENTIC.a2ml** - AI agent interaction patterns
5. **NEUROSYM.a2ml** - Neurosymbolic integration config
6. **PLAYBOOK.a2ml** - Operational runbook

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

Bot-specific instructions for rhodibot, echidnabot, sustainabot, glambot,
seambot, finishbot.

### Agent Instructions

- `.claude/CLAUDE.md` - Claude-specific patterns
- `0-AI-MANIFEST.a2ml` - THIS FILE (universal entry point)

## CORE INVARIANTS

1. **Rust core** - The engine, parser, and CLI are Rust. Do not rewrite in
   another language. (A future OCaml/Catala *formal core* may verify the
   engine, per docs/engine-v0-design.adoc — that is verification, not a
   reimplementation of the runtime.)
2. **Determinism** - `evaluate` is pure and total: no clocks, randomness, IO,
   or ambient state; BTree ordering everywhere. Preserve this.
3. **Reject at load, never mid-run** - unsupported policy constructs fail
   schema validation up front, so any policy that loads evaluates.
4. **Deontic operators** - Obligation/Prohibition/Permission are first-class
   AST values.
5. **Overlays extend, never mutate** - overlays add rules; base policy is
   immutable.
6. **License consistency** - Code MPL-2.0; documentation CC-BY-SA-4.0. Every
   file carries an SPDX header.
7. **Author attribution** - Always "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>".
8. **Single source of truth** - `.machine_readable/6a2/` is authoritative for
   project state.

## REPOSITORY STRUCTURE

```
palimpsest-plasma/
├── 0-AI-MANIFEST.a2ml           # THIS FILE (start here)
├── README.adoc                   # Project overview
├── ROADMAP.adoc                  # Implementation milestones
├── TOPOLOGY.md                   # Architecture diagram + dashboard
├── LICENSE                       # MPL-2.0
├── Justfile                      # Build automation (cargo)
│
├── src/                          # the `plasma` CLI binary (Rust)
│   ├── main.rs                   # check/facts/policy/audit/init/badge/migrate
│   ├── check.rs facts_cmd.rs policy_cmd.rs
│   └── audit.rs init.rs migrate.rs badge.rs
│
├── plasma-engine/                # the policy engine (Rust)
│   ├── src/ast.rs schema.rs facts.rs eval.rs finding.rs
│   ├── src/report/               # human + SARIF renderers
│   └── policies/repo-hygiene.plasma.toml   # bundled, self-applied policy
│
├── plasma-parser/                # SPDX/license machinery (Rust)
│   └── src/{spdx,family,zone,audit,compat,report}/
│
├── docs/                         # Documentation
│   ├── engine-v0-design.adoc     # NORMATIVE semantics + Catala-readiness
│   ├── architecture.adoc         # System architecture, data flow
│   ├── policy-ast-v0.1.adoc      # Historical OCaml-typed design (lineage)
│   └── cli-design.adoc           # CLI and integration design
│
├── site/                         # Elixir/NimblePublisher static site
├── .machine_readable/            # a2ml metadata + bot directives + contractiles
└── .github/workflows/            # CI/CD workflows
```

## KEY DOCUMENTS

- `docs/engine-v0-design.adoc` - NORMATIVE: policy format, evaluation
  semantics, determinism/totality guarantees. Read before touching the engine.
- `docs/architecture.adoc` - Crate layout, data flow.
- `docs/policy-ast-v0.1.adoc` - Historical typed-AST design (lineage only).
- `docs/cli-design.adoc` - CLI subcommands and roadmap surfaces.
- `ROADMAP.adoc` - Milestones v0.2 → v1.0.

## SESSION STARTUP CHECKLIST

1. Read THIS file first
2. Read `.machine_readable/6a2/STATE.a2ml` for current status
3. Read `docs/engine-v0-design.adoc` before changing the engine
4. Verify with `cargo test --workspace` and `plasma check .`

## LIFECYCLE HOOKS

### on-enter (Session Start)
1. Read and acknowledge this manifest
2. Read `.machine_readable/6a2/STATE.a2ml`
3. State understanding of the Rust-core / determinism invariants

### on-exit (Session End)
1. Update `.machine_readable/6a2/STATE.a2ml` if changes made
2. Ensure `cargo test --workspace` passes and `plasma check .` is clean
3. Summarize outcomes

## META

- **Format Version:** 2.0.0
- **Created:** 2026-01-10
- **Updated:** 2026-07-02
- **Maintained By:** Jonathan D.A. Jewell (hyperpolymath)
- **License:** MPL-2.0
- **Protocol:** https://github.com/hyperpolymath/0-ai-gatekeeper-protocol