Add validation and duplicate-target protection before writes

[adrianbrowning]

What to build

Add a validation workflow that detects unsafe or ambiguous Markdown code-block mappings before mdcode writes files. Users should receive a clear report and a non-zero exit status instead of silent data loss or partial synchronization.

Acceptance criteria

• Validation detects duplicate target files that do not have an unambiguous merge strategy.
• Validation detects missing, mismatched, or invalid regions and missing referenced source files.
• Validation detects unsafe file paths and reports the affected block and document.
• Strict mode can require file metadata for every selected block.
• The report is available in both readable and machine-readable formats and is covered by tests.

Blocked by

• Add a versioned machine-readable CLI contract for agents #5
• Harden mdcode operations for untrusted Markdown and agent execution #7

[adrianbrowning]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Validate Markdown code-block mappings before writes to prevent ambiguity, unsafe paths, and partial synchronization.

Current behavior:
Extraction groups blocks by target path but, for a duplicate target without all blocks having regions, writes only the first block. Region reads do not require a unique, well-formed matching region. Metadata paths and source-read errors are not uniformly validated before operations begin.

Desired behavior:
A read-only validate command analyzes the selected operation before it writes. It reports every unsafe, missing, ambiguous, or malformed mapping in readable and structured form. Extract and update run the same validation before mutation.

Key interfaces:

• Validate command — perform no writes and return the common JSON response envelope from issue Add a versioned machine-readable CLI contract for agents #5 when JSON is selected.
• Duplicate target rule — multiple selected blocks may share a target only when every block has a non-empty, unique region name and every block has the same language. Every other duplicate target is an error.
• Region rule — a referenced region must occur exactly once and have a matching closing marker; missing, duplicate, malformed, and language-mismatched regions are errors.
• Path/source rule — use guarded path resolution from issue Harden mdcode operations for untrusted Markdown and agent execution #7 and report missing referenced source files.
• Strict mode — --strict requires file metadata on every selected block.
• Diagnostic identity — every finding includes the Markdown document and block name or source location, affected path, rule, and actionable message.

Acceptance criteria:

• Validate detects ambiguous duplicate targets before any write.
• Duplicate targets are allowed only for same-language blocks with distinct, non-empty regions.
• Validate detects missing source files, unsafe paths, missing regions, duplicate regions, malformed region markers, and language/region mismatches.
• --strict rejects every selected anonymous block.
• Extract and update fail validation before modifying files.
• Readable and JSON reports identify each affected document, block, path, and rule failure.
• Tests cover valid mappings and every validation error category.

Out of scope:

• Automatic conflict resolution or merging of ambiguous targets.
• Silently choosing the first duplicate block.
• Changing named-block or quoted-metadata syntax from issue Add stable block identities and robust metadata syntax #16.
• Redefining path containment or the shared JSON envelope.

Verification status:
Confirmed: duplicate extraction currently can write only the first block, and region/source failures are not uniformly preflighted. This issue is blocked by #5 and #7.