# 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 **wokelangiser**. It declares:
- Canonical file locations (where things MUST be, and nowhere else)
- Critical invariants (rules that must NEVER be violated)
- Repository structure and organization
**wokelangiser** adds consent patterns, accessibility annotations,
internationalisation hooks, and cultural sensitivity markers to existing
code via WokeLang. It is part of the hyperpolymath -iser family.
## CANONICAL LOCATIONS (UNIVERSAL RULE)
### Machine-Readable Metadata: `.machine_readable/` ONLY
These 6 a2ml files MUST exist in `.machine_readable/6a2/` 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.adoc` - 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)
## DOMAIN-SPECIFIC CONTEXT
### WokeLang Decorators
Wokelangiser processes four decorator families:
- `@consent` — opt-in/opt-out/withdraw/audit-trail for GDPR-compliant data handling
- `@accessible` — WCAG 2.2 levels A/AA/AAA with ARIA, contrast, focus annotations
- `@i18n` — locale binding, RTL, pluralisation, date/number/currency formatting
- `@sensitive` — cultural region markers, terminology domains, naming conventions
### ABI-FFI Architecture
- **Idris2 ABI** (`src/interface/abi/`): ConsentType, WCAGLevel, I18nHook,
CulturalContext, AccessibilityAnnotation — with formal proofs of correctness
- **Zig FFI** (`src/interface/ffi/`): consent injection, accessibility checking,
contrast ratio calculation, i18n extraction, sensitivity analysis
- **Rust CLI** (`src/main.rs`): manifest parsing, pipeline orchestration
### Consent State Machine
Pending -> Granted -> Active -> Revoked (with Granted -> Revoked shortcut).
All transitions formally verified in Types.idr via ValidTransition proofs.
## 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. **ABI types match FFI** - ConsentRecord (24B), AccessibilityRecord (32B), I18nRecord (24B) sizes must match between Idris2 Layout.idr and Zig main.zig
## REPOSITORY STRUCTURE
```
wokelangiser/
├── 0-AI-MANIFEST.a2ml # THIS FILE (start here)
├── README.adoc # Consent/accessibility wrapping overview
├── ROADMAP.adoc # Phase 0-6 with consent/a11y milestones
├── CONTRIBUTING.adoc # Human contribution guide
├── Justfile # Task runner
├── Cargo.toml # Rust CLI package
├── Containerfile # OCI build
├── LICENSE # PMPL-1.0-or-later
├── src/ # Source code
│ ├── main.rs # CLI entry point
│ ├── lib.rs # Library entry point
│ ├── manifest/ # wokelangiser.toml parser
│ ├── codegen/ # Target language code generation
│ ├── abi/ # Rust-side ABI module
│ └── interface/ # Verified Interface Seams
│ ├── abi/ # Idris2 ABI (consent, a11y, i18n types)
│ │ ├── Types.idr # ConsentType, WCAGLevel, I18nHook, CulturalContext
│ │ ├── Layout.idr # Memory layouts for FFI records
│ │ └── Foreign.idr # FFI function declarations
│ ├── ffi/ # Zig FFI (C-ABI bridge)
│ │ ├── build.zig
│ │ ├── src/main.zig # Consent/a11y/i18n implementations
│ │ └── test/ # Integration tests
│ └── generated/ # Auto-generated C headers
├── docs/ # Technical documentation
└── .machine_readable/ # ALL machine-readable metadata
└── 6a2/ # STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK
```
## SESSION STARTUP CHECKLIST
Read THIS file (0-AI-MANIFEST.a2ml) first
Understand canonical location: `.machine_readable/`
State understanding of canonical locations
Read .machine_readable/6a2/STATE.a2ml for current project state
## 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."**