Repository navigation
Add plan, diff, apply, and check workflows for agent-driven sync #6
Description
Activity
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.- added a commit that references this issue
on Oct 4, 2026
What to build
Introduce an explicit inspect, plan, apply, and verify workflow for synchronizing Markdown code blocks. Agents must be able to determine the exact proposed change before mdcode writes a file.
Acceptance criteria
Blocked by