Architecture Decision Records

This section mirrors the Architecture Decision Records (ADRs) for the Modeled Information Format (MIF) project, whose source of record is the adr/ directory of the MIF repository. ADR-001 through ADR-012 are mirrored on this site; ADR-013 onward link to the MIF repository.

Format

ADRs follow the Structured MADR format — an extension of MADR (Markdown Architectural Decision Records) that adds YAML frontmatter, full risk-assessed option analysis, split Positive/Negative/Neutral consequences, and a required code-grounded Audit section.

Index

ADR	Title	Status	Description
ADR-001	Cognitive Triad Taxonomy	Accepted	Adopts the cognitive triad (semantic, episodic, procedural) as the foundational concept taxonomy — MIF’s answer to OKF’s absent concept-type system
ADR-002	Dual-Format Design (Markdown + JSON-LD)	Accepted	Supports both Markdown and JSON-LD as first-class formats (refined by ADR-011: Markdown is canonical)
ADR-003	Obsidian Compatibility	Superseded (by ADR-017)	Originally adopted Obsidian-specific conventions (wiki-links, @[[]], block references); reverted by ADR-017 for vendor neutrality
ADR-004	Three-Tier Trait Inheritance	Accepted	Defines a three-level trait inheritance model: mif-base, shared-traits, domain ontologies
ADR-005	Underscore Namespace Prefix Convention	Accepted	Uses underscore prefix for base-type namespace directories to distinguish from domain content
ADR-006	EntityData vs EntityReference	Accepted	Distinguishes inline structured entity data from lightweight entity references
ADR-007	GitHub Raw URLs for Schema IDs	Accepted (amended → mif-spec.dev)	Originally used GitHub raw URLs for schema $id values; amended to use mif-spec.dev
ADR-008	Decay Model Rationale	Accepted	Implements configurable exponential decay with half-life for memory relevance ranking
ADR-009	OKF Compliance as a Superset (Pinned OKF v0.1)	Accepted	MIF is a superset of a conformant OKF v0.1 bundle and pins the criteria — no floating dependency (Invariant 5)
ADR-010	Repositioning to Modeled Information Format	Accepted	Renames/repositions MIF as a general OKF-compliant content model; AI memory becomes the first domain profile
ADR-011	Markdown-Canonical with Derived JSON-LD Projection	Accepted	Markdown .md is the source of truth; JSON-LD is a derived projection (Invariant 2) — refines ADR-002
ADR-012	OKF Conformance Enforced as a Tested CI Invariant	Accepted (amended → validate-ontologies scope)	Enforces OKF conformance, lossless round-trip, and schema validity as gating CI checks; ontology-content/namespace validation stopped running after content moved to the ontologies repo per ADR-018/019 (coverage gap tracked as ontologies#51)
ADR-013	Provenance: Lightweight Core + Optional W3C-PROV Layer	Accepted	Lightweight provenance core (sourceType/trustLevel) plus an OPTIONAL, additive W3C-PROV-aligned layer (wasGeneratedBy/wasAttributedTo/wasDerivedFrom); full PROV graphs stay optional
ADR-014	Document References, Not Embedded Vendor Schema	Accepted	Source documents travel by vendor-neutral DocumentReference (pointer + integrity metadata), not by embedding a vendor model like DoclingDocument (reframes issue #77)
ADR-015	Attested Release Orchestration	Accepted (amended → draft-first publication)	Every release is SLSA-attested (provenance + CycloneDX SBOM, fail-closed verify) via a draft-first publication flow, with the full SAST/DAST/SCA/posture gate suite wired to the org’s central reusable workflows (each independently SHA-pinned)
ADR-016	Per-Version Schema Mirror Publication	Accepted	Each release publishes an immutable versioned schema mirror (/schema/X.Y.Z/, latest/, vMAJOR/) served by the doc site, keeping canonical $id values unversioned per ADR-007
ADR-017	Revert Obsidian Compatibility	Accepted	Supersedes ADR-003: drops Obsidian-specific notation (wiki-links, @[[]], block references, embeds) for vendor-neutral CommonMark with markdown-link relationships and frontmatter EntityReferences
ADR-018	Ontology Corpus: Dedicated Repository, Flat Layout, and Versioned Serving	Accepted (propagation mechanism replaced by ADR-019)	Resolves discussion #168: ontologies live in the dedicated ontologies repo (source of record) while the schema/context stay in MIF; served at mif-spec.dev/ontologies/ with immutable corpus-release mirrors per the ADR-016 model
ADR-019	Deploy-Time, Attestation-Verified Ontology Vendoring	Accepted	Amends ADR-018’s propagation mechanism: the deploy fetches the ontologies repo’s signed release tarball and fail-closed verifies it with gh attestation verify, replacing the committed public/ontologies/ mirror and its unbuilt PR-propagation follow-up
ADR-020	Confidence-Tiered Entity-Type Classification	Accepted	Adopts the two-threshold, three-tier confidence-score policy (auto-classify-eligible / flag-for-review / trigger-expansion) as the MIF-level classification pattern and adds optional entity_type fields aliases, exemplars, negative_examples (ontology schema 1.1.0)
ADR-021	Container Profile: A Derived Transport Envelope for Multi-Memory Corpora	Accepted	Defines an OPTIONAL, single-file *.corpus.json transport envelope derived from a Bundle, with vendor-specific corpus metadata (compression manifests, version DAGs) routed through a generalized extensions mechanism rather than native MIF vocabulary (reframes issue #77)

Creating New ADRs

1. Copy the structure from a recent ADR (e.g. ADR-009) as the Structured MADR exemplar
2. Use sequential numbering: ADR-NNN-short-title.md
3. Fill in all sections: frontmatter, Status, Context, Decision Drivers, Considered Options (with risk assessments), Decision, Consequences (Positive/Negative/Neutral), Decision Outcome, Related Decisions, Links, More Information, and Audit
4. In the Audit section, cite an anchor you have opened and confirmed; if a finding cannot be confirmed, set the audit Status: Pending rather than inventing a citation. Prefer a durable anchor (job id, step name:, heading text, field name — something grep -n still finds after the file changes) over a raw file:line range into a file that churns, such as a CI workflow: raw line numbers silently drift as steps are added/removed, and a citation that no longer points at what it claims defeats the point of auditing (see ADR-012’s Audit section for the pattern, and #241 for the existing ADRs still on raw line numbers). Also record the audited revision (commit SHA) for each dated Audit entry: an anchor persisting across commits doesn’t guarantee what it does hasn’t changed underneath it — pin the commit so a future reader can git show <sha>:<file> and verify the citation against exactly what was true at audit time, not just against whatever currently has a matching anchor
5. Update this index and link related ADRs bidirectionally via the related frontmatter

Status Values

Structured MADR frontmatter uses the standard MADR status enum:

• proposed - Under discussion
• accepted - Decision approved and in effect
• deprecated - No longer recommended
• superseded - Replaced by another ADR

An amended decision keeps status: accepted and documents the change in its ## Status line plus an ## Amendment section (see ADR-007).