Add validation and duplicate-target protection before writes #15

Activity

1. adrianbrowning

   marked this as blocked on Aug 8, 2026

   • Harden mdcode operations for untrusted Markdown and agent execution #7
2. adrianbrowning commented on Aug 8, 2026

   

   adrianbrowning

   on Aug 8, 2026

   OwnerAuthor

   More actions

   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.
3. adrianbrowning

   added

   enhancementNew feature or requestNew feature or request

   ready-for-agentFully specified and ready for an AFK agentFully specified and ready for an AFK agent

   on Aug 8, 2026
4. adrianbrowning

   marked this as blocked on Oct 4, 2026

   • Add a versioned machine-readable CLI contract for agents #5
5. adrianbrowning

   added a commit that references this issue on Oct 5, 2026

   feat: validate code-block mappings before extract or update writes (#15…

   ...

   f33b054
6. adrianbrowning

   closed this as completedin #42on Oct 5, 2026
7. adrianbrowning

   added 2 commits that reference this issue on Oct 6, 2026

   style: fix lint:s errors from #15 (#44)

   ef62bf3

   feat: mdcode watch reports drift as you edit; --apply writes it (#18) (…

   ...

   900a191