Add plan, diff, apply, and check workflows for agent-driven sync #6

Activity

1. adrianbrowning

   marked this as blocked on Aug 8, 2026

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

   marked this as blocking 5 issues on Aug 8, 2026

   • Publish an agent integration guide and workflow examples #8
   • Expose mdcode as typed MCP tools for LLM agents #9
   • Add project configuration and document-glob support #14
   • Add a safe watch mode for local documentation development #18
   • Consolidate the public library interface and CLI adapter #19
3. 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: Make Markdown synchronization safe by default with explicit plan, diff, apply, and check modes.

   Current behavior:
   The update command reads linked source files and writes the resulting Markdown in place by default when given a file. The stdout option is the only non-mutating alternative. There is no structured plan, reviewable diff, drift check, or explicit apply gate.

   Desired behavior:
   Update is non-mutating by default. It determines the selected block changes and returns a change plan; writing requires an explicit --apply option. Agents and humans can inspect the plan, view a unified diff, or check for drift without modifying Markdown. Selection uses the stable names introduced by issue #16.

   Key interfaces:

   • Update default and --plan — produce a non-mutating change plan. Under --json, use the versioned response envelope from issue Add a versioned machine-readable CLI contract for agents #5.
   • --apply — the only mode that writes an input Markdown document in place.
   • --diff — emit a unified diff for intended Markdown changes and never write.
   • --check — never write; exit with status 1 when selected blocks are out of sync. Operational, validation, and configuration failures remain distinct errors.
   • --name — select a documented stable block name, following issue Add stable block identities and robust metadata syntax #16.
   • --stdout — retain as a compatibility alias for obtaining updated Markdown without a write.

   Acceptance criteria:

   • Update without --apply does not modify the input Markdown document and returns a change plan.
   • --apply writes only the selected intended Markdown changes.
   • --diff produces a reviewable unified diff without writing files.
   • --check exits 0 when selected blocks are synchronized and 1 when drift exists, without writing files.
   • Operational or validation failures have a structured error result and do not masquerade as drift.
   • --name deterministically limits every mode to the named block or blocks.
   • --stdout remains available as a non-mutating compatibility path.
   • Integration tests cover plan, apply, diff, check, named selection, no-op, drift, and error paths.

   Out of scope:

   • Stable-name and quoted-metadata implementation, which is issue Add stable block identities and robust metadata syntax #16.
   • The versioned JSON envelope itself, which is issue Add a versioned machine-readable CLI contract for agents #5.
   • Project-level configuration, file watching, or CI workflow design.

   Verification status:
   Confirmed: update currently writes in place by default and offers no plan, diff, or check mode. This issue remains blocked by #5.
4. 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
5. adrianbrowning

   marked this as blocking on Oct 4, 2026

   • Provide a reusable CI script to check documentation synchronization #11
6. adrianbrowning

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

   feat(update): plan by default; explicit --apply, --diff and --check (#34

   ...

   7835414
7. adrianbrowning

   closed this as completedin #34on Oct 4, 2026