Documentation

Last Updated: 2026-08-22 | Version: 0.11.0

Agent maintenance

The repository's maintenance workflow is documented as a public, reusable skill: midi2-domain-maintenance. It is deliberately independent of any publication domain or hosting provider and is the first reference for agents changing code, contracts, evidence, documentation, or publication projections.

Documentation site

The static documentation projection is generated from the repository by Scripts/build_docs_site.py. Build it locally with:

python3 Scripts/build_docs_site.py --output /tmp/midi2-docs-site

The guarded publication helper is Scripts/publish_docs_site.sh. DNS and delivery are separate, explicitly verified operations; the generated site records its source commit and does not publish the normative source PDFs.

Quick Start

New to this project? Start here:

📊 Spec Compliance Dashboard - Executive summary and quick metrics
📖 Comprehensive Audit Report - Detailed analysis and recommendations
📋 Gap Closure Tracker - Action items with acceptance criteria

Specification Audit & Compliance (Updated Dec 2025)

Bidirectional standards contract

Normative Coverage Report - complete machine-readable inverse corpus report with per-source representations
Normative Coverage Methodology - extraction, status, scope, and claim boundaries
Normative Behavior Model - machine-readable protocol state machines and invariants linked from the inverse ledger
Full Object Composition - machine-readable composition of the structural and behavioral projections, with explicit completion boundaries
Normative Source Inventory - reproducible hash-bound page inventory for the remaining source extraction work
Normative Source Dispositions - explicit disposition for every extracted source-language candidate
Third-party Specification Sources - PDF hashes, attribution, and redistribution boundary
MIDI vs Fountain Coach Extensions - normative authority and extension separation

Overview Documents

Spec Compliance Dashboard - Quick reference with visual progress bars, metrics, and roadmap
Comprehensive Spec Audit Report - Full analysis covering:
- UMP encode/decode implementation (84% complete)
- MIDI-CI implementation (63% complete)
- Stream configuration (57% complete)
- Property Exchange (53% complete)
- 21 identified gaps (11 closed, 52%)
- Gap closure progress and remaining work
- Success metrics and recommendations

Detailed Tracking

Gap Closure Tracker - Detailed action plan for each of 21 gaps:
- Acceptance criteria
- Implementation steps
- Files to modify
- Dependencies
- Sprint allocation
- Status tracking (🔴🟡🟢⏸️)
Spec Traceability Matrix - generated object-to-source definition mapping. It is not the inverse normative inventory; use the Normative Coverage Report for that.

Existing Documentation

Status & Conformance

Conformance Checklist - Current implementation state against MIDI 2.0 specs
Spec Audit Log - Generated page-level citations for the current schema mapping
Traceability - Definition of Done traceability to code/tests

Other Resources

VRT-Protocol Quiet Frame Gap Closure Prompt - Visual baseline testing

Specification PDFs

For normative MIDI Association specification PDFs, see the repository root:

M2-100-U v1.1 (MIDI 2.0 Overview)
M2-101-UM v1.2 (MIDI-CI)
M2-102-U v1.1 (Profiles)
M2-103-UM v1.2 (Property Exchange)
M2-104-UM v1.1.2 (UMP and Protocol)
M2-116-U v1.0 (MIDI Clip File)

Document Relationships

┌─────────────────────────────────────────────────────────┐
│  spec-compliance-dashboard.md (START HERE)              │
│  ↓ Quick metrics & roadmap                              │
└─────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────┐
│  comprehensive-spec-audit-report.md                     │
│  ↓ Detailed analysis of all components                  │
│  ↓ Gap identification & recommendations                 │
└─────────────────────────────────────────────────────────┘
           ↓                              ↓
┌──────────────────────────┐    ┌────────────────────────┐
│ gap-closure-tracker.md   │    │ spec-traceability-     │
│ ↓ Action plans           │    │   matrix.md            │
│ ↓ Acceptance criteria    │    │ ↓ Requirement mapping  │
│ ↓ Sprint allocation      │    │ ↓ Evidence paths       │
└──────────────────────────┘    └────────────────────────┘
           ↓                              ↓
┌─────────────────────────────────────────────────────────┐
│  spec-audit.md                                          │
│  ↓ Page-level PDF references                            │
│  ↓ Schema/OpenAPI mappings                              │
└─────────────────────────────────────────────────────────┘
           ↓
┌─────────────────────────────────────────────────────────┐
│  conformance-checklist.md + traceability.md             │
│  ↓ Current implementation evidence                      │
└─────────────────────────────────────────────────────────┘

Maintenance

spec-compliance-dashboard.md: Update weekly during active sprints
gap-closure-tracker.md: Update status after each gap closure
comprehensive-spec-audit-report.md: Update at major milestones
spec-traceability-matrix.md: Update when specs change or gaps close
spec-audit.md: Update when adding new spec references
conformance-checklist.md: Update when implementation status changes

Legacy Documents

The following documents in legacy/ are archived for historical reference:

legacy/midi2-js-dod.md - Original DoD criteria (superseded by gap-closure-tracker.md)
legacy/midi2-js-gap-plan.md - Original gap plan (superseded by gap-closure-tracker.md)
legacy/AGENTS.md - Original maintenance policy (superseded by root AGENTS.md)
legacy/midi2-js-AGENTS.md - Original midi2.js AGENTS (superseded by midi2.js/README.md)

Contributing

When updating these documents:

Keep metrics consistent across all documents
Update cross-references when moving content
Maintain the visual progress indicators
Add citations to spec pages for new requirements
Update the "Last Updated" timestamps