ADR-0001: Align the adr Genre Fully to Structured MADR
ADR-0001: Align the adr Genre Fully to Structured MADR
Section titled “ADR-0001: Align the adr Genre Fully to Structured MADR”Status
Section titled “Status”Accepted
Context
Section titled “Context”Background and Problem Statement
Section titled “Background and Problem Statement”The mif-docs plugin ships an adr genre skill — its flagship documentation
genre. An earlier working direction was to decouple the genre from
Structured MADR (structured-madr) and have the suite carry an MIF-only ADR
shape with, at most, an optional smadr check. Structured MADR is the
modeled-information-format org’s canonical ADR format, and it is validated by
the modeled-information-format/structured-madr GitHub Action in both smadr
(structural) and mif (conformance, levels 1-3) modes. We had to settle
whether the genre owns its own ADR schema or reuses the org’s Action-validated
one before publishing v0.1.0.
Current Limitations
Section titled “Current Limitations”- Ecosystem divergence: an MIF-only ADR shape would drift from the org’s canonical format, so ADRs authored by the plugin would not validate with the same Action every other org repo uses.
- Duplicated validation: keying ADRs into the suite’s own
mif-validatewould re-implement ADR validation thestructured-madrAction already owns. - Flagship risk: the
adrgenre is the most visible genre in the plugin; shipping it on a bespoke shape sets the wrong precedent for the other genres.
Decision Drivers
Section titled “Decision Drivers”Primary Decision Drivers
Section titled “Primary Decision Drivers”The following factors are weighted most heavily in this decision:
- Flagship genre: the
adrgenre shall be the reference example for the plugin, so it shall use the format the org already treats as canonical. - Canonical, Action-validated format: the genre shall validate against the
structured-madrAction that the org maintains, not a parallel schema. - No ecosystem divergence: an ADR authored by the plugin shall be indistinguishable, to the validator, from one authored anywhere else in the org.
Secondary Decision Drivers
Section titled “Secondary Decision Drivers”The following factors influenced the decision but were not individually decisive:
- Single source of truth: reusing the Action avoids maintaining a second ADR validator inside the suite.
- Author ergonomics: contributors who already know Structured MADR write conformant ADRs with no plugin-specific relearning.
Considered Options
Section titled “Considered Options”Option 1: Decouple with an optional smadr check
Section titled “Option 1: Decouple with an optional smadr check”Description: Keep an MIF-only ADR shape inside the suite and offer the
structured-madr check as an opt-in extra rather than the authority.
Technical Characteristics:
- ADR validation lives in the suite’s own
mif-validate. - The
structured-madrAction is advisory, not the gate.
Advantages:
- Full local control over the ADR shape.
- No hard dependency on the external Action.
Disadvantages:
- Re-implements ADR validation the org already maintains.
- Lets the plugin’s ADRs diverge from the canonical format over time.
Disqualifying Factor: an optional check that is not the gate cannot satisfy the “no ecosystem divergence” driver — divergence becomes possible the moment the two shapes drift.
Risk Assessment:
- Technical Risk: Medium. Two ADR validators must be kept in sync by hand.
- Schedule Risk: Medium. Ongoing maintenance of a duplicate validator.
- Ecosystem Risk: High. The plugin’s ADRs can drift from the org standard.
Option 2: Full Structured MADR alignment
Section titled “Option 2: Full Structured MADR alignment”Description: Align the adr genre fully to Structured MADR and make the
structured-madr Action the authority for ADR validation.
Technical Characteristics:
- Every ADR carries
type: adrplusconceptType: semantic. - The genre is exempt from the suite’s
mif-validate, which keys onconceptType; thestructured-madrAction validates it instead.
Advantages:
- ADRs validate with the org’s canonical Action in
smadrandmifmodes. - No duplicate ADR validator to maintain inside the suite.
Disadvantages:
- Adds a dependency on the external
structured-madrAction in CI.
Risk Assessment:
- Technical Risk: Low. One canonical validator, reused as-is.
- Schedule Risk: Low. No bespoke ADR schema to maintain.
- Ecosystem Risk: Low. The plugin tracks the org standard by construction.
Decision
Section titled “Decision”We align the adr genre fully to Structured MADR, reversing the earlier
decision to decouple from it. The structured-madr Action is the authority for
ADR validation.
The implementation is:
- Every ADR carries
type: adrandconceptType: semanticin its frontmatter. - The
adrgenre is exempt from the suite’smif-validate, which keys onconceptType; the fail-closed PostToolUse guard skipstype: adrdocuments for the same reason. - CI runs the
structured-madrAction over the ADRs in bothsmadr(strict) andmif(conformance) modes via theadr-smadrjob.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Canonical validation: ADRs validate with the same Action every org repo uses, satisfying the no-divergence driver directly.
- No duplicate validator: the suite carries no parallel ADR schema to keep in sync.
Negative
Section titled “Negative”- External dependency: ADR validation now depends on the
structured-madrAction in CI; mitigated because the Action is maintained in the same org and pinned by SHA. - Two validation paths: ADRs follow a different gate from the other genres;
mitigated by documenting the exemption where
conceptTypeis described.
Neutral
Section titled “Neutral”- Genre exemption: the
adrgenre is the one genre outside themif-validatesuite — a deliberate split, not an inconsistency.
Decision Outcome
Section titled “Decision Outcome”The decision achieves its primary objective — a flagship ADR genre that never
diverges from the org standard — measured by the adr-smadr CI job passing in
both smadr strict and mif conformance modes for every shipped ADR.
Mitigations:
- The external Action is pinned by SHA and maintained in the same org.
- The
mif-validateexemption is recorded whereverconceptTypegating is documented, so the two-path split is discoverable.
Related Decisions
Section titled “Related Decisions”- ADR-0002: Host Ontologies in a Separate Repository - another reuse of an org-shared, separately maintained source.
- ADR-0003: Attested-Delivery Release Pattern - the release gate that ships the conformant genre.
- Structured MADR — modeled-information-format/structured-madr - the canonical Action this genre aligns to.
More Information
Section titled “More Information”- Date: 2026-06-30
- Source: mif-docs v0.1.0 genre alignment review
- Related ADRs: ADR-0002, ADR-0003
2026-06-30
Section titled “2026-06-30”Status: Compliant
Findings:
| Finding | Files | Lines | Assessment |
|---|---|---|---|
| Earlier decouple-from-smadr direction reversed | - | - | accepted |
Summary: Decision accepted after the v0.1.0 genre alignment review; the earlier decouple-from-smadr direction was reversed in favor of full alignment.
Action Required: Keep the adr-smadr CI job green in both smadr and mif
modes for every shipped ADR.