= AI Manifest Format Specification
:toc: left
:toclevels: 4
:numbered:
:icons: font

**SPDX-License-Identifier: CC-BY-SA-4.0**

[cols="1,3"]
|===
| Status | Draft
| Version | 1.0.0
| Date | 2026-02-07
| Authors | Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
| Media Type | `application/vnd.hyperpolymath.ai-manifest+a2ml`
| File Extension | `.a2ml`
|===

== Abstract

This document specifies the AI Manifest format (`.a2ml`) - a standardized format for declaring repository structure, canonical file locations, and critical invariants to AI agents. The format is designed to be:

* **Universal** - Readable by any AI agent (Claude, Gemini, OpenAI, Mistral, etc.)
* **Human-readable** - Plain text with markdown-style formatting
* **Machine-parseable** - Structured sections with consistent format
* **Extensible** - Can evolve without breaking existing manifests
* **Platform-agnostic** - Not tied to any specific AI platform

== Status of This Document

This is a DRAFT specification. Feedback is welcome via GitHub Issues at:
https://github.com/hyperpolymath/0-ai-gatekeeper-protocol/issues

== Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

* **AI Agent** - Any artificial intelligence system capable of reading files and performing repository operations (e.g., Claude, Gemini, OpenAI ChatGPT, GitHub Copilot)
* **Manifest** - A file declaring repository structure and constraints
* **Invariant** - A rule or constraint that MUST NOT be violated
* **Canonical Location** - The ONLY valid location for a specific type of file
* **Attestation** - Cryptographic proof that an agent has read the manifest
* **Session** - A period of AI agent interaction with a repository

== File Naming

Manifests MUST use one of the following filenames (in order of preference):

1. `0-AI-MANIFEST.a2ml` (RECOMMENDED - sorts first alphabetically)
2. `AI.a2ml` (legacy name, still supported)
3. `!AI.a2ml` (alternative for systems where `0` prefix problematic)

Repositories MUST contain exactly ONE manifest file. Multiple manifests are FORBIDDEN.

The manifest MUST be located in the repository root directory.

== File Format

=== Character Encoding

Manifests MUST be encoded in UTF-8.

=== Line Endings

Manifests SHOULD use Unix-style line endings (`\n`). Windows-style (`\r\n`) and classic Mac (`\r`) are supported but discouraged.

=== Whitespace

* Leading/trailing whitespace on lines is OPTIONAL and SHOULD be ignored by parsers
* Blank lines are OPTIONAL and SHOULD be ignored by parsers
* Indentation is OPTIONAL and used only for human readability

=== Comments

Lines beginning with `#` (after optional whitespace) are comments and MUST be ignored by parsers, EXCEPT when part of a heading.

[source]
----
# This is a comment
This is content
----

== Structure

=== Required Sections

All manifests MUST contain these sections (in any order):

1. **Warning Header** - Attention-grabbing notice
2. **What Is This** - Brief explanation of manifest purpose
3. **Canonical Locations** - Where files MUST be located
4. **Core Invariants** - Rules that MUST NOT be violated
5. **Repository Structure** - Overview of repo organization
6. **Attestation Proof** - How agents prove understanding

=== Optional Sections

Manifests MAY contain these sections:

* **Session Startup Checklist** - Steps for session initialization
* **Lifecycle Hooks** - on-enter and on-exit actions
* **Enforcement Mechanisms** - How invariants are enforced
* **Why This Exists** - Rationale (RECOMMENDED)
* **Bot Fleet Integration** - Bot-specific instructions
* **Platform-Specific Notes** - Platform-specific guidance
* **Further Reading** - Links to related documentation
* **Meta** - Manifest metadata

== Section Specifications

=== Warning Header

**Format:** Markdown heading level 1 (`#`)

**Content:** MUST include clear warning that file must be read first

**Example:**
[source,markdown]
----
# ⚠️ STOP - CRITICAL READING REQUIRED

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

**Requirements:**
* MUST be first substantive content in file (after any comments)
* MUST use attention-grabbing language
* SHOULD use emoji warning symbol
* MUST convey urgency and importance

=== What Is This

**Format:** Markdown heading level 2 (`##`)

**Content:** Brief explanation (1-3 paragraphs) of what the manifest is and why it exists

**Example:**
[source,markdown]
----
## WHAT IS THIS?

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

**Requirements:**
* MUST identify the repository by name
* MUST list what the manifest declares
* SHOULD be concise (< 200 words)

=== Canonical Locations

**Format:** Markdown heading level 2 (`##`)

**Content:** MUST declare where specific file types are located

**Structure:**
[source,markdown]
----
## CANONICAL LOCATIONS (UNIVERSAL RULE)

### [Category Name]

[Description]

**Files:**
1. **[File Name]** - [Description]
2. **[File Name]** - [Description]

**CRITICAL:** [Warning about violations]
----

**Requirements:**
* MUST use "ONLY" or "MUST" language to indicate exclusivity
* MUST state explicitly where files MUST be located
* MUST state explicitly where files MUST NOT be located
* SHOULD organize by category (e.g., "Machine-Readable Metadata", "Bot Directives")

**Example:**
[source,markdown]
----
## CANONICAL LOCATIONS (UNIVERSAL RULE)

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

These 6 A2ML files MUST exist in `.machine_readable/6a2/` directory ONLY
(migrated from Guile Scheme on 2026-04-12):
1. **STATE.a2ml** - Project state, progress, blockers
2. **META.a2ml** - Architecture decisions, governance
...

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

=== Core Invariants

**Format:** Markdown heading level 2 (`##`)

**Content:** Numbered list of rules that MUST NOT be violated

**Requirements:**
* MUST be concrete and specific
* MUST be mechanically enforceable (or verifiable)
* SHOULD include consequences of violation
* MUST use imperative language ("No ...", "Always ...", "Never ...")

**Example:**
[source,markdown]
----
## CORE INVARIANTS

1. **No A2ML duplication** - Root must NOT contain STATE.a2ml, META.a2ml, etc. (or legacy STATE.scm, META.scm)
2. **Single source of truth** - `.machine_readable/6a2/` is authoritative
3. **No stale metadata** - If root A2ML/SCM files exist, they are OUT OF DATE
4. **License consistency** - All code PMPL-1.0-or-later unless platform requires MPL-2.0
----

=== Repository Structure

**Format:** Markdown heading level 2 (`##`)

**Content:** Overview of repository organization with directory tree

**Requirements:**
* SHOULD use ASCII/Unicode tree diagram or code block
* MUST show key directories and their purposes
* SHOULD include brief descriptions
* MAY be customized per repository

**Example:**
[source,markdown]
----
## REPOSITORY STRUCTURE

```
repo-name/
├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
├── README.md                   # Project overview
├── src/                        # Source code
├── .machine_readable/          # A2ML files (6 files in 6a2/ subdirectory)
│   └── 6a2/
│       ├── STATE.a2ml
│       └── ...
└── .bot_directives/            # Bot instructions
```
----

=== Session Startup Checklist

**Format:** Markdown heading level 2 (`##`)

**Content:** Checklist (using ✅ or [ ]) of steps for session initialization

**Requirements:**
* SHOULD use checkbox format
* MUST include "Read manifest" as first step
* SHOULD include "Read STATE.a2ml" step
* MAY include platform-specific steps

**Example:**
[source,markdown]
----
## SESSION STARTUP CHECKLIST

✅ Read THIS file (0-AI-MANIFEST.a2ml) first
✅ Understand canonical locations
✅ Know the invariants
✅ Read `.machine_readable/6a2/STATE.a2ml`
----

=== Lifecycle Hooks

**Format:** Markdown heading level 2 (`##`)

**Content:** Sections for `on-enter` and `on-exit` with numbered steps

**Requirements:**
* MUST have subsections for `on-enter` and `on-exit`
* SHOULD specify log format if logging required
* SHOULD specify log location
* MUST use clear, actionable language

**Example:**
[source,markdown]
----
## LIFECYCLE HOOKS

### on-enter (Session Start)

When starting a new session:

1. Read and acknowledge this manifest
2. Log session start (optional but recommended)
   - Format: `[YYYY-MM-DD HH:MM:SS] Session started: [agent-name]`
   - Location: `.machine_readable/session-log.txt`
3. Read `.machine_readable/6a2/STATE.a2ml`

### on-exit (Session End)

When ending a session:

1. Update `.machine_readable/6a2/STATE.a2ml` if changes made
2. Log session end
3. Document new blockers
----

=== Attestation Proof

**Format:** Markdown heading level 2 (`##`)

**Content:** Statement agents must make to prove understanding

**Requirements:**
* MUST include exact statement agents should make
* SHOULD be in blockquote or emphasis
* MUST mention key canonical locations
* SHOULD be copy-pasteable

**Example:**
[source,markdown]
----
## ATTESTATION PROOF

After reading this file, demonstrate understanding by stating:

**"I have read the AI manifest. SCM files are located in `.machine_readable/` ONLY, bot directives in `.bot_directives/`, and I will not create duplicate files."**
----

=== Meta Section

**Format:** Markdown heading level 2 (`##`)

**Content:** Metadata about the manifest itself

**Requirements:**
* SHOULD include format version
* SHOULD include creation date
* SHOULD include maintainer
* SHOULD include license
* SHOULD reference protocol

**Example:**
[source,markdown]
----
## META

- **Format Version:** 1.0.0
- **Created:** 2026-02-07
- **Maintained By:** hyperpolymath
- **License:** PMPL-1.0-or-later
- **Protocol:** https://github.com/hyperpolymath/0-ai-gatekeeper-protocol
----

== Parsing Rules

=== Heading Detection

Headings are lines beginning with `#` (after optional whitespace):

* `# Heading 1` - Level 1
* `## Heading 2` - Level 2
* `### Heading 3` - Level 3

=== Content Extraction

* Content belongs to the most recent heading
* Content continues until next heading or end of file
* Blank lines separate paragraphs within content

=== List Detection

* Numbered lists: Lines beginning with `1.`, `2.`, etc.
* Bullet lists: Lines beginning with `*`, `-`, or `•`
* Checkbox lists: Lines beginning with `[ ]`, `[x]`, or `✅`

=== Emphasis Detection

* **Bold:** Text surrounded by `**` or `__`
* *Italic:* Text surrounded by `*` or `_`
* `Code:` Text surrounded by backticks

== Validation

=== Required Section Validation

A valid manifest MUST contain all required sections. Parsers SHOULD:

1. Check for presence of required section headings (case-insensitive)
2. Verify each section has non-empty content
3. Warn if optional sections missing

=== Invariant Validation

Parsers SHOULD validate that:

* Canonical locations are specified with "ONLY" or "MUST" language
* Invariants are stated clearly and concretely
* Repository structure section exists
* Attestation proof is present

=== Hash Computation

For attestation, SHA-256 hash MUST be computed over:

1. Entire file content (including all whitespace and newlines)
2. UTF-8 encoded bytes
3. Result expressed as lowercase hexadecimal string

== Extensibility

=== Adding New Sections

New sections MAY be added in future versions. Parsers MUST:

* Ignore unknown sections gracefully
* NOT fail on presence of unknown sections
* Warn if unknown section appears to contain critical information

=== Version Compatibility

Manifests SHOULD declare format version in Meta section. Parsers MAY:

* Support multiple format versions
* Warn on unknown versions
* Use heuristics to parse unknown versions

== Security Considerations

=== Attestation Security

SHA-256 provides:

* **Collision resistance** - Practically impossible to forge hash
* **Modification detection** - Any change invalidates hash
* **Non-repudiation** - Agent cannot claim to have read different content

However, attestation does NOT provide:

* **Confidentiality** - Manifest content is public
* **Authentication** - Hash doesn't prove agent identity
* **Authorization** - Hash doesn't grant specific permissions

=== Injection Attacks

Manifests should NOT:

* Execute code during parsing
* Include external resources (no `<script>`, `<img>`, etc.)
* Contain shell commands for execution

Parsers MUST:

* Treat manifest as pure data
* NOT execute any content
* Sanitize output when displaying to users

== Implementation Notes

=== Minimal Parser

A minimal conformant parser MUST:

1. Read file as UTF-8 text
2. Extract required sections by heading
3. Verify all required sections present
4. Compute SHA-256 hash of entire file
5. Return structured data or error

=== Full-Featured Parser

A full-featured parser SHOULD:

1. All minimal parser requirements
2. Extract and parse lists
3. Detect and preserve emphasis
4. Validate canonical location declarations
5. Check invariant statements for clarity
6. Warn on potential issues

=== Example Implementation

See `mcp-repo-guardian/src/manifest.ts` for reference implementation in TypeScript.

== Media Type Registration

**Media Type:** `application/vnd.hyperpolymath.ai-manifest+a2ml`

**File Extension:** `.a2ml`

**Encoding:** UTF-8

**Fragment Identifier:** Section headings (e.g., `#canonical-locations`)

== Examples

See `examples/0-AI-MANIFEST.a2ml` in the protocol repository for a complete example manifest.

== References

* **Protocol Repository:** https://github.com/hyperpolymath/0-ai-gatekeeper-protocol
* **MCP Server:** https://github.com/hyperpolymath/mcp-repo-guardian
* **RFC 2119:** Key words for use in RFCs to Indicate Requirement Levels

== Changelog

* **2026-02-07:** Initial draft (v1.0.0)

== Authors

Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>

== Copyright

This specification is licensed under PMPL-1.0-or-later.

Copyright (c) 2026 hyperpolymath
