Changelog
All notable changes to Structured MADR are documented here. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[2.0.0] - 2026-10-08
Section titled “[2.0.0] - 2026-10-08”This release is breaking for consumers of mode: mif: projected concept @ids
change from urn:mif:smadr:<project>:<slug> to urn:mif:<uuid> (see the
projected-ids entry under Changed). Reference the Action as @v2.
Changed
Section titled “Changed”- MIF Compliance: aligned with MIF specification 1.4.2. The vendored
schemas come from the immutable
https://mif-spec.dev/schema/1.4.2/mirror (were pinned to MIFdevelop/v1.0.0ate597da69, whose schemas match MIF 1.2.1);config.ymlmifVersionis 1.4.2 (was 1.0.0), andvendor-checkfails if it disagrees withVENDOR.lock’smifSpecVersion. The MIF gate warns when a consumer’smifVersiondiffers from the vendored release. - MIF Compliance: the vendor pin moved from MIF 1.4.1 to 1.4.2, the
coordinated MIF release with published artifacts. The 1.4.2 schemas are
byte-identical to 1.4.1 and 1.4.0, so the
VENDOR.locksha256s are unchanged. - MIF Compliance (breaking for consumers of projected ids): MIF 1.4.0+
requires a concept
@idofurn:mif:<uuid>. The projector uses a UUIDidas is (lowercased; bare,urn:mif:,urn:uuid:or{…}) and turns a slug, a legacyurn:mif:smadr:…id, or a missingidinto a deterministic UUIDv5 of the id the old projector emitted (smadr:<project>:<id-or-file-slug>) in the MIF namespaceuuid5(NAMESPACE_URL, "https://mif-spec.dev"), keeping the replaced id inaliases. The gate fails when two ADRs project to the same@id. AmemoryType-only ADR projects withmemoryTypeand no synthesizedconceptType, which satisfies Level 1. - Versioning: usage examples reference the Action as
@v2(were@v1); thestructured-madr-mifplugin version follows the project version (2.0.0). - Project: repository, docs and package metadata now point at the
modeled-information-formatorg and its canonical domains. - CI: adopted the org’s attested quality-gate backbone, gated on every PR;
npm run lintnow has an ESLint flat config and runs in CI; Node is pinned to 24.
Security
Section titled “Security”- Deps:
osv-scanner.tomlrecords braces GHSA-vfj7-8cjw-p6xm (no fixed release; build-time only) as the one remaining accepted advisory. - Deps: postcss-selector-parser GHSA-rj75-hqrm-r3gf is fixed rather than
waived: an npm
overridesentry forces^7.1.6past postcss-nested’s^6range, and itsosv-scanner.tomlwaiver is removed.
- MIF Compliance:
x-superseded-by: Bon ADR A projects assuperseded-by→ B; it wassupersedes→ B, the reverse of the fact.
- MIF Compliance: validate ADRs as MIF (Modeled Information Format) at a
user-selected level (
.github/config.ymlmifConformanceLevel: 1|2|3, default 2). Markdown stays canonical; a MIF JSON-LD object is derived from frontmatter + body and validated against per-level profiles.- Self-contained Claude Code plugin homed at
.github/(plugin root with.claude-plugin/plugin.json,commands/,agents/,skills/,hooks/, plus vendored + checksum-pinned MIF schemas, config, projector, validator, ADR-typing ontology). - Installable: the repository is a plugin marketplace (
.claude-plugin/marketplace.json,source: ./.github);.claude/settings.jsonregisters it and enables the plugin at project scope, so/plugin install structured-madr-mif@structured-madrworks. npm run validate:mif; composite action gainsmode: miffor downstream consumers.- CI gates:
mif-vendor-check(schema drift) and dogfoodedvalidate-mif. - ADR-0003 records the decision and is itself MIF-conformant (dogfooded).
- Self-contained Claude Code plugin homed at
- Docs Site:
llms.txtis generated at build time (starlight-llms-txt).
[1.2.0] - 2026-04-09
Section titled “[1.2.0] - 2026-04-09”Reconstructed from the v1.2.0 release notes and git log v1.1.0..v1.2.0; this
section was not written when 1.2.0 was tagged.
- GitHub Action: configurable body structure via the JSON schema’s
bodykey (required and optional sections, subsections, title pattern, option heading requirements). Without abodykey the validator falls back to the structured-madr defaults. - Project:
CITATION.cffwith academic citation metadata.
- GitHub Action: headings inside fenced code blocks no longer count as body sections (false positives).
Changed
Section titled “Changed”- Deps: astro 5.17.2 → 6.1.3, @astrojs/starlight 0.37.6 → 0.38.2, eslint 9.39.2 → 10.2.0, ajv 8.17.1 → 8.18.0, glob 11.1.0 → 13.0.6, yaml 2.8.2 → 2.8.3; GitHub Actions updated to current majors.
[1.1.0] - 2026-01-15
Section titled “[1.1.0] - 2026-01-15”- GitHub Action: Shareable validation action for CI/CD pipelines
- Composite action with configurable inputs (
path,pattern,schema,strict,fail-on-error) - Node.js validator with JSON Schema (ajv) and body structure validation
- GitHub-compatible annotations for PR feedback
- Outputs for workflow integration (
valid,total,passed,failed,warnings)
- Composite action with configurable inputs (
- Project ADRs: Exemplar ADRs demonstrating the format (dogfooding)
- ADR-0001: Adopt Structured MADR Format for Project Documentation
- ADR-0002: Shareable GitHub Action for Structured MADR Validation
- CI/CD: GitHub workflow to validate project and example ADRs
- Documentation: README updated with action usage, inputs/outputs, and local validation instructions
Changed
Section titled “Changed”- Tooling: Added npm package.json with validation dependencies (ajv, ajv-formats, glob, yaml)
[1.0.0] - 2026-01-15
Section titled “[1.0.0] - 2026-01-15”- Initial release of Structured MADR specification
- YAML frontmatter schema with required and optional fields
- Hierarchical decision drivers (Primary/Secondary)
- Per-option risk assessment (Technical/Schedule/Ecosystem)
- Categorized consequences (Positive/Negative/Neutral)
- Required Audit section with compliance tracking
- JSON Schema for frontmatter validation (
schemas/structured-madr.schema.json) - Full template with guidance text (
templates/template.md) - Bare template for experienced users (
templates/template-bare.md) - Real-world example ADR (
examples/0001-use-rust-implementation-language.md) - Formal specification document (
SPECIFICATION.md) - Contributing guidelines
Design Decisions
Section titled “Design Decisions”- MADR Compatibility: Section structure follows MADR 4.0.0 conventions for familiarity
- Machine-Readable Frontmatter: YAML chosen for broad tooling support
- Audit Requirements: Mandatory audit section ensures decisions are tracked and validated
- Risk Assessment: Three-dimension risk model (Technical/Schedule/Ecosystem) provides comprehensive evaluation
- Status Values: Limited to MADR-compatible values (proposed, accepted, deprecated, superseded)