feat(md043): add sequence-alignment diagnostics

docs/md043.md

@@ -62,7 +62,7 @@ Run the following...
 MIT License
 ```
 
-### 🔧 Fixed
+### Manually corrected
 
 ```markdown
 # Overview                    <!-- Corrected heading -->
@@ -164,9 +164,13 @@ headings = [
 ]
 ```
 
+Adjacent wildcards form one run. Each `?` and `+` contributes one required heading, and a run containing `*` or `+` can absorb additional headings. For example, `["?", "+"]` requires at least two headings, while `["*", "?"]` requires at least one.
+
+Wildcard runs fill their required `?` and `+` slots from left to right. A required slot may consume a heading whose text also matches the next literal; this matters when that literal occurs more than once. After the required slots are filled, the repeating portion contributed by `*` or `+` stops at the earliest heading matching the next configured literal. When more than one alignment has the same edit cost, MD043 preserves the alignment with the most exact literal matches, then prefers legal wildcard absorption and substitutions.
+
 ## Diagnostic messages
 
-When a document does not match the required structure, MD043 reports the first point where the actual headings diverge from the configured pattern.
+When a document does not match the required structure, MD043 aligns the configured and actual heading sequences and reports every actionable difference. Exact matches and headings legally consumed by wildcards do not produce warnings.
 
 For example, with this configuration:
 
@@ -185,34 +189,41 @@ This document:
 ## License
 ```
 
-Reports that `## Installation` was expected before `## Usage`:
+Reports the missing heading at `## Usage`:
 
 ```text
-Heading structure does not match required structure. Expected heading '## Installation' at position 2, but found '## Usage'
+Heading structure does not match required structure. Missing required heading '## Installation'
 ```
 
-Wildcard patterns are described in the same focused way. For example, `+` requires at least one heading before the next configured heading:
+Substitutions name both headings:
 
 ```text
-Heading structure does not match required structure. Expected one or more headings before '## Contributing', but found '## Contributing' immediately
+Heading structure does not match required structure. Expected heading '## Installation', but found '## Setup'
 ```
 
-## Automatic fixes
+Unexpected headings include their position in the document, and moved headings describe their nearest configured literal neighbors:
+
+```text
+Heading structure does not match required structure. Unexpected heading '## Notes' at position 3
+Heading structure does not match required structure. Heading '## Usage' is out of order; expected between '## Installation' and '## License'
+```
 
-When enabled, this rule will:
+An unsatisfied `?` or `+` produces its own warning. Missing requirements attach to the next actual heading; trailing requirements attach to the last heading, and headingless nonempty documents use line 1.
 
-- Identify heading structure mismatches
-- Preserve original content to prevent data loss
-- Support wildcard patterns for flexible matching
+This intentionally changes warning counts and locations from the former behavior: MD043 now emits one warning per alignment edit instead of repeating the first divergence at every document heading.
+
+## Automatic fixes
 
-**Note:** Automatic fixes for this rule are conservative to avoid destructive changes.
+MD043 does not automatically restructure documents. Its fix operation preserves the original content because inserting, renaming, or moving headings can change document meaning.
 
 ## Special cases
 
 - Empty configuration disables this rule
 - Wildcards (`*`, `+`, `?`) provide flexible pattern matching
 - Order of headings matters - patterns are matched sequentially
 - Case sensitivity controlled by `match-case` option
+- The complete heading string is matched, so a different heading level is a normal mismatch
+- Invalid heading syntax is ignored by MD043
 - All wildcards pattern (e.g., `["*"]`) allows any structure
 
 ## Learn more