= META.scm
:toc: left
:toclevels: 2
:icons: font

Machine-readable Engineering and Technical Architecture files.

Part of the **.scm Format Family** — Scheme S-expression data formats for
software engineering workflows.

== The .scm Format Family

[cols="1,2,2"]
|===
|Format |Purpose |Use Case

|**META.scm**
|Project governance and architecture documentation
|ADRs, development practices, design rationale

|**STATE.scm**
|AI conversation checkpoint and restore
|Session persistence, context continuity
|===

Both formats share common S-expression syntax, enabling unified tooling while
serving complementary purposes.

== What is META.scm?

META.scm is a format specification for documenting software project metadata,
architecture decisions, and development practices in machine-readable
Scheme S-expression syntax.

[source,scheme]
----
;; SPDX-License-Identifier: MPL-2.0
(define-module (my-project meta)
  #:export (architecture-decisions development-practices design-rationale))

(define 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")))))

(define development-practices
  '((testing (framework . "pytest") (coverage-minimum . 80))
    (versioning (scheme . "Semantic Versioning 2.0.0"))))

(define design-rationale
  '((why-event-sourcing
     "Event sourcing provides immutable audit trail and temporal queries.")))
----

== Why META.scm?

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

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

|*Human-Readable*
|S-expressions 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.scm can reference META.scm 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.scm File

[source,scheme]
----
;; SPDX-License-Identifier: MPL-2.0
;; SPDX-FileCopyrightText: 2025 Your Name

;;; META.scm — Architecture Decisions and Development Practices
;;; your-project

(define-module (your-project meta)
  #:export (architecture-decisions
            development-practices
            design-rationale))

(define 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")))))

(define development-practices
  '((code-style
     (formatter . "your-formatter")
     (linter . "your-linter"))))

(define 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] - .scm format family overview
* link:spec/UNIFIED-STANDARDS-STRATEGY.adoc[UNIFIED-STANDARDS-STRATEGY.adoc] - Coordinated standards approach
* link:spec/shared/s-expression.abnf[shared/s-expression.abnf] - Shared ABNF grammar
* link:spec/shared/scm-common.schema.json[shared/scm-common.schema.json] - Shared JSON Schema

=== META.scm Specific

* link:spec/META-FORMAT-SPEC.adoc[META-FORMAT-SPEC.adoc] - Complete specification
* link:spec/abnf/meta.abnf[abnf/meta.abnf] - ABNF grammar
* 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.scm[minimal.scm] - Minimal valid META file
* link:examples/comprehensive.scm[comprehensive.scm] - Full-featured example

== Integration with STATE.scm

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

[source,scheme]
----
;; In STATE.scm
(define projects
  '((name . "my-project")
    (path . "/home/user/my-project")
    (meta-ref . "META.scm")           ; Reference to project's META.scm
    (active-adrs . (adr-001 adr-003)) ; Currently relevant decisions
    (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 .scm 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/meta+scheme` 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/meta+scheme`
* **File Extension**: `.scm` (conventionally `META.scm`)
* **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 S-expression parser library (TypeScript, Rust, Python)

== Contributing

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

== License

MIT License. Copyright (c) 2025 Jonathan D.A. Jewell.

== Related Work

* 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
* **STATE.scm** - AI conversation checkpoint format (companion specification)
