= SCM Format Family Standards Roadmap
:author: Jonathan D.A. Jewell
:revdate: 2026-01-18
:toc:
:toclevels: 3
:sectnums:
:icons: font

== Executive Summary

Handover (2026-01-18): standards track remains IETF Informational RFC; media-type registration draft exists and needs conformance examples.

The **SCM Format Family** is a collection of declarative S-expression formats for software development context. This document outlines the unified standardisation strategy for the family.

**Current Members:**

* **STATE.scm** - Session state persistence for AI conversations
* **ECOSYSTEM.scm** - Project ecosystem context and relationships

**Recommended Standards Track:** IETF Informational RFC (coordinated family submission)

**Rationale:** Data interchange formats have strong precedent at IETF (RFC 7946 GeoJSON, RFC 5545 iCalendar). Submitting as a coordinated family ensures consistent design and simplifies IANA registration.

== SCM Format Family Overview

[source]
----
┌─────────────────────────────────────────────────────────────────────┐
│                       SCM Format Family                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌──────────────────┐          ┌──────────────────┐               │
│   │    STATE.scm     │          │  ECOSYSTEM.scm   │               │
│   │                  │          │                  │               │
│   │  Session State   │◄────────►│  Project Context │               │
│   │  Progress Track  │  cross-  │  Relationships   │               │
│   │  Decision Queue  │   ref    │  Boundaries      │               │
│   └────────┬─────────┘          └────────┬─────────┘               │
│            │                             │                          │
│            └─────────────┬───────────────┘                          │
│                          │                                          │
│              ┌───────────┴───────────┐                              │
│              │   Shared Foundation   │                              │
│              │   - scm-core.abnf     │                              │
│              │   - scm-family.schema │                              │
│              │   - Common media type │                              │
│              │     pattern           │                              │
│              └───────────────────────┘                              │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
----

=== Domain Separation

[cols="2,3,3"]
|===
| Aspect | STATE.scm | ECOSYSTEM.scm

| *Domain*
| Temporal context
| Structural context

| *Scope*
| Single session/conversation
| Project lifetime

| *Persistence*
| Dynamic, conversation-specific
| Static, versioned with code

| *Location*
| Working directory, temp
| Repository root

| *Media Type*
| `application/vnd.state+scm`
| `application/vnd.ecosystem+scm`
|===

=== Integration Pattern

[source,scheme]
----
;; STATE.scm references ECOSYSTEM.scm
(state
  (metadata
    (version "2.0")
    (ecosystem-ref "./ECOSYSTEM.scm"))  ; Cross-reference
  (user ...)
  (session ...)
  (projects ...))

;; ECOSYSTEM.scm declares STATE.scm as sibling
(ecosystem
  (family
    (siblings
      (sibling (name "STATE.scm") (domain "session-state"))))
  (related-projects
    (project
      (name "STATE.scm")
      (relationship "sibling-standard"))))
----

== Standards Bodies Evaluation

=== IETF (Recommended)

[cols="1,4"]
|===
| Aspect | Assessment

| *Fit*
| ✓ Excellent. Data format specifications are core IETF territory.

| *Precedent*
| RFC 7946 (GeoJSON), RFC 5545 (iCalendar), RFC 8259 (JSON)

| *Family Support*
| Related RFCs common (e.g., RFC 7231 HTTP methods family)

| *Process*
| Internet-Draft → IETF Last Call → RFC publication

| *Timeline*
| 6-18 months for Informational RFC

| *Cost*
| Free (volunteer-driven)
|===

=== Alternative Bodies

[cols="2,2,3"]
|===
| Body | Fit | Notes

| IRTF
| ✗ Poor
| Research-focused, not operational specs

| ISO
| ✗ Poor
| Industrial focus, 3-5 year timeline, high cost

| W3C
| ○ Partial
| Web-focused; SCM is developer tooling

| ECMA
| ○ Partial
| Language-focused; accessible alternative

| OASIS
| ○ Acceptable
| Fallback if IETF stalls
|===

== Unified Roadmap

=== Phase 1: Foundation ✓ COMPLETE

**Status:** Complete for both formats

[cols="3,1,1,3"]
|===
| Deliverable | STATE | ECO | Location

| Canonical specification
| ✓
| ✓
| `STATE.scm`, `ECOSYSTEM.scm`

| Format-specific ABNF
| ✓
| ✓
| `spec/*.abnf`

| JSON Schema
| ✓
| ✓
| `spec/*.schema.json`

| Internet-Draft
| ✓
| ✓
| `spec/draft/draft-jewell-*-00.txt`

| IANA considerations
| ✓
| ✓
| `spec/IANA-CONSIDERATIONS.adoc`
|===

=== Phase 1.5: Family Integration ✓ COMPLETE

**Status:** Complete

[cols="3,1,3"]
|===
| Deliverable | Status | Location

| SCM Family specification
| ✓ Done
| `spec/family/SCM-FAMILY.adoc`

| Shared ABNF core
| ✓ Done
| `spec/family/scm-core.abnf`

| Unified JSON Schema
| ✓ Done
| `spec/family/scm-family.schema.json`

| Cross-references updated
| ✓ Done
| Both `*.scm` files
|===

=== Phase 2: Community Review

**Timeline:** 1-3 months

**Objectives:**

* [ ] Publish both specs for community feedback
* [ ] Gather implementation experience
* [ ] Refine shared grammar based on usage
* [ ] Validate cross-format integration patterns

**Actions:**

1. Announce SCM family on relevant forums
2. Create unified GitHub Discussions
3. Track issues across both repositories
4. Document integration patterns

=== Phase 3: Implementation

**Timeline:** 3-6 months

**Objectives:**

* [ ] Unified parser library (handles both formats)
* [ ] Validation tools
* [ ] Format conversion utilities
* [ ] Editor/IDE support

**Shared Implementation Strategy:**

[source,rust]
----
// Hypothetical unified parser API
use scm_family::{parse, Document, Format};

let doc = parse(content)?;

match doc.format() {
    Format::State(state) => {
        // Access STATE.scm specific fields
        let user = state.user()?;
        let projects = state.projects()?;
    }
    Format::Ecosystem(eco) => {
        // Access ECOSYSTEM.scm specific fields
        let related = eco.related_projects()?;
        let position = eco.position_in_ecosystem()?;
    }
}
----

**Implementation Priority:**

[cols="2,2,3"]
|===
| Language | Priority | Notes

| Rust
| Primary
| Unified reference implementation

| TypeScript
| Primary
| VS Code extension, web tooling

| Guile Scheme
| High
| Native format, REPL integration

| Python
| Medium
| Scripting, data analysis

| Go
| Medium
| Cloud tooling, CI/CD
|===

=== Phase 4: Coordinated IETF Submission

**Timeline:** Month 6-9

**Strategy:** Submit both I-Ds simultaneously with cross-references

**Actions:**

1. Create IETF Datatracker account
2. Submit both Internet-Drafts:
   - `draft-jewell-state-scm-00`
   - `draft-jewell-ecosystem-scm-00`
3. Reference shared family in both I-Ds
4. Request ART Area review (coordinated)
5. Iterate on both drafts together

**Draft Structure:**

[source]
----
draft-jewell-state-scm-00
├── References draft-jewell-ecosystem-scm-00
└── References shared ABNF core

draft-jewell-ecosystem-scm-00
├── References draft-jewell-state-scm-00
└── References shared ABNF core
----

=== Phase 5: IANA Registration

**Timeline:** Upon I-D acceptance

**Batch Registration:**

[cols="2,3,2"]
|===
| Media Type | Specification | Status

| `application/vnd.state+scm`
| draft-jewell-state-scm
| Pending

| `application/vnd.ecosystem+scm`
| draft-jewell-ecosystem-scm
| Pending

| `application/vnd.scm` (reserved)
| Future family container
| Reserved
|===

=== Phase 6: RFC Publication

**Timeline:** Month 12-18

**Target:** Two related Informational RFCs published together

**Milestones:**

1. Coordinated IETF Last Call
2. IESG Review (both documents)
3. RFC Editor processing
4. Simultaneous publication

== Success Criteria

=== For Family Informational RFCs

* [ ] Clear, complete specifications for both formats
* [ ] Shared ABNF core documented and validated
* [ ] At least one unified implementation
* [ ] Cross-format integration demonstrated
* [ ] No technical objections during Last Call
* [ ] Both IANA registrations approved

=== For Future Standards Track

* [ ] Two or more independent implementations per format
* [ ] Demonstrated interoperability
* [ ] Production adoption of integration patterns
* [ ] No IPR encumbrances

== Governance Model

=== Family Stewardship

* **Family Steward:** Jonathan D.A. Jewell
* **Individual Format Maintainers:** May be delegated
* **Shared Infrastructure:** Coordinated changes required

=== Versioning Strategy

[cols="2,3"]
|===
| Component | Strategy

| Individual formats
| Semantic versioning (independent)

| Shared ABNF core
| Semantic versioning (triggers format review)

| Family specification
| Document version (coordination updates)
|===

=== Change Process

1. **Format-specific changes:** Normal PR to respective repo
2. **Shared grammar changes:** PR to both repos with coordination
3. **Family-level changes:** Discussion in designated forum

== Risk Assessment

[cols="2,2,3"]
|===
| Risk | Likelihood | Mitigation

| Formats diverge
| Medium
| Shared grammar, coordinated releases

| Adoption imbalance
| Medium
| Promote together, unified tooling

| IETF coordination overhead
| Low
| Same author, related content

| Conflicting evolution
| Low
| Family steward oversight

| IPR claims
| Very Low
| PMPL-1.0 licence, contributor agreement
|===

== Timeline Summary

[source]
----
2025 Q4: Phase 1 Complete (Individual foundations)     ✓
2025 Q4: Phase 1.5 Complete (Family integration)       ✓ CURRENT
2026 Q1: Phase 2 (Community Review)
2026 Q2: Phase 3 (Unified Implementation)
2026 Q2: Phase 4 (Coordinated IETF Submission)
2026 Q3: Phase 5 (Batch IANA Registration)
2026 Q4: Phase 6 (Simultaneous RFC Publication)
----

== Repository Structure

[source]
----
ECOSYSTEM.scm/                          state.scm/
├── ECOSYSTEM.scm                       ├── STATE.scm
├── STANDARDS-ROADMAP.adoc (this file)  ├── (may reference this)
├── spec/                               ├── spec/
│   ├── ecosystem.abnf                  │   ├── state.abnf
│   ├── ecosystem.schema.json           │   ├── state.schema.json
│   ├── IANA-CONSIDERATIONS.adoc        │   ├── IANA-CONSIDERATIONS.adoc
│   ├── draft/                          │   ├── draft/
│   │   └── draft-jewell-ecosystem-*    │   │   └── draft-jewell-state-*
│   └── family/  ←──────────────────────┼───┤
│       ├── SCM-FAMILY.adoc             │   │ (shared or mirrored)
│       ├── scm-core.abnf               │   │
│       └── scm-family.schema.json      │   │
└── README.adoc                         └── README.adoc
----

== Appendix: IETF Process Reference

=== Useful Links

* https://www.ietf.org/standards/process/[IETF Standards Process]
* https://www.rfc-editor.org/rfc/rfc7322[RFC Style Guide]
* https://authors.ietf.org/[I-D Author Resources]
* https://datatracker.ietf.org/submit/[I-D Submission Tool]

=== Related RFC Precedents

* **RFC 7946 + RFC 7464:** GeoJSON and JSON Text Sequences
* **RFC 5545 + RFC 6321:** iCalendar and xCal (XML)
* **HTTP RFCs:** Multiple related documents

== Contact

For questions about SCM family standardisation:

* ECOSYSTEM.scm: https://github.com/hyperpolymath/ECOSYSTEM.scm
* STATE.scm: https://github.com/hyperpolymath/state.scm
