= META.a2ml
image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]




:toc: left
:toclevels: 2
:icons: font

Machine-readable Engineering and Technical Architecture files.

Part of the **A2ML Format Family** -- A2ML (Annotated Markup Language) TOML-like key-value
data formats for software engineering workflows.

== The A2ML Format Family

This repository is part of the **A2ML Format Family** -- 7 A2ML formats for software engineering workflows. All specification repos are satellites of https://github.com/hyperpolymath/standards[hyperpolymath/standards].

[cols="1,1,2,1", options="header"]
|===
|Format |Tier |Purpose |Specification

|`META.a2ml`
|Primary
|Architecture decisions (ADRs), development practices
|**This repo**

|`STATE.a2ml`
|Primary
|Project state, phase, milestones, session history
|Companion (this repo)

|`ECOSYSTEM.a2ml`
|Primary
|Ecosystem positioning, related projects
|Companion (this repo)

|`PLAYBOOK.a2ml`
|Execution
|Executable plans, procedures, alerts
|link:../playbook-a2ml/[playbook-a2ml]

|`AGENTIC.a2ml`
|Execution
|AI agent operational gating, entropy budgets
|link:../agentic-a2ml/[agentic-a2ml]

|`NEUROSYM.a2ml`
|Execution
|Symbolic semantics, proof obligations
|link:../neurosym-a2ml/[neurosym-a2ml]

|`ANCHOR.a2ml`
|Intervention
|Project recalibration/realignment
|link:../anchor-a2ml/[anchor-a2ml]
|===

=== Execution Pipeline

All implementations MUST respect this ordering:

[source]
----
1. META validation      <- Constitutional authority check
2. AGENTIC gating       <- Operational safety
3. NEUROSYM semantics   <- Proof obligations
4. PLAYBOOK derivation  <- Build executable plan
5. Execution
6. ECOSYSTEM check      <- Integrity verification
7. STATE update         <- Record outcome

INTERVENTION: ANCHOR.a2ml can override any level
----

== What is META.a2ml?

META.a2ml is a format specification for documenting software project metadata,
architecture decisions, and development practices in machine-readable
A2ML (Annotated Markup Language) TOML-like key-value syntax.

[source,toml]
----
# SPDX-License-Identifier: MPL-2.0

[meta]
project = "my-project"

[meta.architecture-decisions.adr-001]
title = "Use Event Sourcing"
status = "accepted"
date = "2025-01-15"
context = "Need complete audit trail for orders"
decision = "Implement event sourcing for order service"
consequences = ["Full history", "Replay capability", "Eventual consistency"]

[meta.development-practices.testing]
framework = "pytest"
coverage-minimum = 80

[meta.development-practices.versioning]
scheme = "Semantic Versioning 2.0.0"

[meta.design-rationale]
why-event-sourcing = "Event sourcing provides immutable audit trail and temporal queries."
----

== Why META.a2ml?

[cols="1,3"]
|===
|Feature |Benefit

|*Machine-Readable*
|Tooling can parse, validate, and generate documentation

|*Human-Readable*
|TOML-like key-value pairs are readable without special editors

|*Structured ADRs*
|Architecture decisions in queryable format

|*VCS-Friendly*
|Plain text diffs, merges, and history

|*Extensible*
|Add custom sections without breaking compatibility

|*Cross-Format*
|STATE.a2ml can reference META.a2ml for project context
|===

== Core Sections

=== Architecture Decisions (`architecture-decisions`)

Structured Architecture Decision Records (ADRs):

* Unique identifier (`adr-NNN`)
* Title, status, date
* Context (problem statement)
* Decision (what was decided)
* Consequences (implications)

=== Development Practices (`development-practices`)

Codified development standards:

* `code-style` - Formatters, linters, type systems
* `security` - Security requirements
* `testing` - Test frameworks, coverage requirements
* `versioning` - Version scheme, changelog format
* `deployment` - Deployment strategy, environments
* `review` - Code review process

=== Design Rationale (`design-rationale`)

Narrative explanations of key decisions, linking to ADRs.

== Getting Started

=== Create a META.a2ml File

[source,toml]
----
# SPDX-License-Identifier: MPL-2.0
# SPDX-FileCopyrightText: 2026 Your Name
# META.a2ml -- Architecture Decisions and Development Practices

[meta]
project = "your-project"

[meta.architecture-decisions.adr-001]
title = "Your First Decision"
status = "accepted"
date = "2025-01-01"
context = "Describe the problem or situation"
decision = "What you decided"
consequences = ["Consequence 1", "Consequence 2"]

[meta.development-practices.code-style]
formatter = "your-formatter"
linter = "your-linter"

[meta.design-rationale]
why-this-decision = "Explain the reasoning behind your key decisions."
----

=== Validate with JSON Schema

For environments with JSON Schema support, convert to JSON and validate
against `spec/schema/meta.schema.json`.

== Specification

The formal specification is in the `spec/` directory:

=== Format Family

* link:spec/SCM-FORMAT-FAMILY.adoc[SCM-FORMAT-FAMILY.adoc] - A2ML format family overview
* link:spec/UNIFIED-STANDARDS-STRATEGY.adoc[UNIFIED-STANDARDS-STRATEGY.adoc] - Coordinated standards approach

=== META.a2ml Specific

* link:spec/META-FORMAT-SPEC.adoc[META-FORMAT-SPEC.adoc] - Complete specification
* link:spec/schema/meta.schema.json[schema/meta.schema.json] - JSON Schema
* link:spec/VERSION-POLICY.adoc[VERSION-POLICY.adoc] - Version policy
* link:spec/STANDARDS-TRACK.adoc[STANDARDS-TRACK.adoc] - Standardization roadmap
* link:spec/IANA-MEDIA-TYPE.adoc[IANA-MEDIA-TYPE.adoc] - Media type registration

== Examples

See the link:examples/[examples/] directory:

* link:examples/minimal.a2ml[minimal.a2ml] - Minimal valid META file
* link:examples/comprehensive.a2ml[comprehensive.a2ml] - Full-featured example

== Integration with STATE.a2ml

STATE.a2ml files (AI session checkpoints) can reference META.a2ml for project context:

[source,toml]
----
# In STATE.a2ml
[state.projects.my-project]
path = "/home/user/my-project"
meta-ref = "META.a2ml"
active-adrs = ["adr-001", "adr-003"]
relevant-practices = ["security", "testing"]
----

This enables AI assistants to:

* Query architecture decisions during implementation
* Enforce development practices
* Understand design rationale
* Maintain context across sessions

== Standards Track

The A2ML Format Family is on track for formal standardization:

[cols="1,2,1"]
|===
|Phase |Target |Status

|Community Specification
|Reference implementations, community adoption
|*In Progress*

|IANA Registration
|`application/vnd.meta+a2ml` media type
|Planned

|IETF RFC Series
|Core syntax + format-specific RFCs
|Planned
|===

See link:spec/UNIFIED-STANDARDS-STRATEGY.adoc[UNIFIED-STANDARDS-STRATEGY.adoc] for the coordinated roadmap.

== Media Type

* **MIME Type**: `application/vnd.meta+a2ml`
* **File Extension**: `.a2ml` (conventionally `META.a2ml`)
* **Encoding**: UTF-8

== ADR Status Values

[cols="1,3"]
|===
|Status |Meaning

|`proposed`
|Under consideration

|`accepted`
|Decided and in effect

|`deprecated`
|No longer recommended

|`superseded`
|Replaced by another decision

|`rejected`
|Considered but not adopted
|===

== Tooling (Planned)

* VS Code extension with syntax highlighting and validation
* CLI tool for linting and documentation generation
* CI/CD integration for ADR policy enforcement
* Markdown/HTML documentation generator
* Shared A2ML parser library (Rust, ReScript)

== Contributing

See link:CONTRIBUTING.md[CONTRIBUTING.md] for contribution guidelines.

== License

Palimpsest-MPL License v1.0 (PMPL-1.0). Copyright (c) 2025 Jonathan D.A. Jewell.

== Related Projects

**Standards Hub:**

* https://github.com/hyperpolymath/standards[standards] -- Organization standards hub
* https://github.com/hyperpolymath/standards/blob/main/SATELLITES.a2ml[SATELLITES.a2ml] -- Machine-readable satellite registry

**A2ML Format Family (Siblings):**

* link:../playbook-a2ml/[playbook-a2ml] -- PLAYBOOK.a2ml (execution tier)
* link:../agentic-a2ml/[agentic-a2ml] -- AGENTIC.a2ml (execution tier)
* link:../neurosym-a2ml/[neurosym-a2ml] -- NEUROSYM.a2ml (execution tier)
* link:../anchor-a2ml/[anchor-a2ml] -- ANCHOR.a2ml (intervention tier)

**Related Standards:**

* https://adr.github.io/madr/[MADR] - Markdown ADR format
* https://spdx.dev/[SPDX] - Software Package Data Exchange
* https://www.iso.org/standard/81870.html[ISO/IEC 5962:2021] - SPDX as ISO standard
