Road to md-utils config v0.3

[DandyLyons]

Purpose

Track the road to the next md-utils configuration format, 0.3.0.

This issue is the umbrella for any feature that changes configuration structure, semantics, resource resolution, migration, schemas, CLI behavior, or documentation. Every such change must be reflected in a coherent 0.3.0 format rather than introducing unrelated or incompatible configuration changes.

Goals

• Define and publish one authoritative 0.3.0 configuration model.
• Coordinate changes that affect rules, matchers, schemas, Markdown types, and project resources.
• Preserve version-specific behavior for existing 0.1.0 and 0.2.0 configurations.
• Provide safe, testable migrations into 0.3.0.
• Keep bundled schemas, public schemas, CLI behavior, documentation, and Agent Skill documentation synchronized.
• Ensure configuration changes are deterministic, explainable, and backward compatible.

Related work

• Add 0.3.0 rule match query groups #71 — Add 0.3.0 rule match query groups
• Allow rules to require conformance to a named mdtype #109 — Allow rules to require conformance to a named mdtype
• Store each md-utils rule in .md-utils/rules/ #96 — Store each md-utils rule in .md-utils/rules/
• Add interactive authoring and editing for md-utils rules #58 — Add interactive authoring and editing for md-utils rules
• Unify duplicated schema files to prevent drift #72 — Unify duplicated schema files to prevent drift
• Add version-aware md-utils config handling #69 — Add version-aware md-utils config handling
• Rename schema validation to rules and support document lint checks #66 — Rename schema validation to rules and support document lint checks
• Add a first-class Markdown type system to MarkdownUtilities #74 — Add a first-class Markdown type system to MarkdownUtilities

The closed issues are included as completed foundations whose behavior must remain compatible with the final 0.3.0 design.

Required coordination

Before calling the 0.3.0 format complete:

• Identify every feature that changes configuration parsing, validation, storage, migration, resource resolution, or command behavior.
• Update the canonical bundled schema and all published schema copies.
• Define migration behavior, including dry-run/preview, collision handling, traversal and absolute-path safety, and interruption/recovery behavior. Recommend a backup of .md-utils/, preserve legacy artifacts, validate before writing, and replace the active config last. No staging directory or migration manifest is required; multi-file atomicity is not guaranteed.
• Add Swift Testing coverage for new behavior and backward compatibility.
• Update README, DocC, CLI help, and the bundled Agent Skill documentation.
• Keep unrelated configuration and resource files preserved by mutating commands.
• Document which behavior belongs to 0.3.0 and which remains version-specific legacy behavior.

Definition of done

• The 0.3.0 configuration model is documented and implemented.
• All related feature issues either land against that model or are explicitly deferred.
• 0.1.0 and 0.2.0 behavior remains covered and unchanged.
• Migration refusal, interruption, and recovery behavior are tested.
• Schemas, implementation, commands, documentation, and fixtures agree.
• A release note or changelog entry explains the new configuration format and migration path.

Implementation milestone

#71, #109 and #96 landed in 69918b4 and 8206166. Config 0.3.0 is opt-in, with shared CLI/server loading, recursive selection/type enforcement, standalone rule commands, and conservative migration. Required-schema-only conversions are supported; malformed-hint rejection is explicitly approved. Other incompatible conversions remain refused.

Remaining: #72 schema-source consolidation, #58 interactive authoring (or an explicit deferral), default initialization/latest-schema rollout, and release notes. This umbrella remains open. Deployed 0.3.0 schemas already match bundled copies; publication does not imply default-version rollout.

[DandyLyons]

Design milestone committed in a70741c: docs/rfcs/0002-config-v0.3.md now records the proposed config layout, recursive match/type expressions, type-file reference resolution, outcome-based composition errors, and migration compatibility boundary.

Migration may change documented diagnostics, but must reject conversions that change selection or pass/fail/skipped outcomes. Backups and preserved legacy artifacts replace a promise of multi-file transactional migration.

This completes the RFC drafting milestone, not this roadmap issue. Next implementation work starts with #109's portable type-enforcement foundation, followed by #71 and #96 against the shared format.

[DandyLyons]

Coordination update: #71, #96 and #109 now describe the approved RFC 0002 format and explicit ownership. Foundations are pushed through 0837bc0; shared integration is still unchecked and none of these issues is closed.

Commit 90793ab adds an executed migration compatibility regression and RFC evidence. All 1325 tests pass. A valid YAML record with malformed reserved $md-utils.typeHints passes a legacy required object-schema rule but fails its equivalent mdtype with type.hint.malformed. This changes pass/fail, not just diagnostics. The currently approved migration contract therefore requires refusing such a conversion unless equivalence can be established. Required-schema conversion cannot be assumed universally safe from matching schema/presence alone.

A decision is needed before broad automatic migration: retain strict outcome preservation and leave incompatible rules on legacy configs, or explicitly approve newly rejecting malformed type hints during migration. No change to this compatibility policy has been implemented.

[DandyLyons]

User-approved compatibility decision, recorded in ce27efa: migration may newly reject malformed $md-utils.typeHints using RFC 0001's existing type.hint.malformed error. Preview and documentation must disclose the change and remediation. Valid name-based hints remain supported. This resolves the specific decision blocker reported in 90793ab; the regression test remains evidence of the intentional difference. All other selection/pass/fail/skipped guarantees remain in force, including refusal of incompatible optional-schema-only or body-only conversions. This is not approval to alter legacy behavior or weaken type assessment. Implementation/integration criteria remain open.

[DandyLyons]

Follow-up: created #136, Add interactive authoring for md-utils configuration, to track the project-level workflow and full CRUD across configuration, types, and rules. It reuses the shared Noora interactive infrastructure planned for #58 and the related type authoring work.

[DandyLyons]

Correction: created #136, “Add interactive authoring for md-utils configuration,” to track the project-level config interactive workflow and full CRUD across configuration, types, and rules. It reuses the shared Noora interactive infrastructure planned for #58 and the related type authoring work.