META.scm

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

This repository is part of the SCM Format Family — 7 Scheme S-expression formats for software engineering workflows. All specification repos are satellites of hyperpolymath/standards.

Format	Tier	Purpose	Specification
META.scm	Primary	Architecture decisions (ADRs), development practices	This repo
STATE.scm	Primary	Project state, phase, milestones, session history	Companion (this repo)
ECOSYSTEM.scm	Primary	Ecosystem positioning, related projects	Companion (this repo)
PLAYBOOK.scm	Execution	Executable plans, procedures, alerts	playbook-scm
AGENTIC.scm	Execution	AI agent operational gating, entropy budgets	agentic-scm
NEUROSYM.scm	Execution	Symbolic semantics, proof obligations	neurosym-scm
ANCHOR.scm	Intervention	Project recalibration/realignment	anchor.scm

Execution Pipeline

All implementations MUST respect this ordering:

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.scm can override any level

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.

;; SPDX-License-Identifier: PMPL-1.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?

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

;; SPDX-License-Identifier: PMPL-1.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

• SCM-FORMAT-FAMILY.adoc - .scm format family overview

• UNIFIED-STANDARDS-STRATEGY.adoc - Coordinated standards approach

• shared/s-expression.abnf - Shared ABNF grammar

• shared/scm-common.schema.json - Shared JSON Schema

META.scm Specific

• META-FORMAT-SPEC.adoc - Complete specification

• abnf/meta.abnf - ABNF grammar

• schema/meta.schema.json - JSON Schema

• VERSION-POLICY.adoc - Version policy

• STANDARDS-TRACK.adoc - Standardization roadmap

• IANA-MEDIA-TYPE.adoc - Media type registration

Examples

See the examples/ directory:

• minimal.scm - Minimal valid META file

• comprehensive.scm - Full-featured example

Integration with STATE.scm

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

;; 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:

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 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

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 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:

• standards — Organization standards hub

• SATELLITES.scm — Machine-readable satellite registry

SCM Format Family (Siblings):

• playbook-scm — PLAYBOOK.scm (execution tier)

• agentic-scm — AGENTIC.scm (execution tier)

• neurosym-scm — NEUROSYM.scm (execution tier)

• anchor.scm — ANCHOR.scm (intervention tier)

Related Standards:

• MADR - Markdown ADR format

• SPDX - Software Package Data Exchange

• ISO/IEC 5962:2021 - SPDX as ISO standard