Add a safe watch mode for local documentation development #18

Activity

1. adrianbrowning

   marked this as blocked by 2 issues on Aug 8, 2026

   • Add plan, diff, apply, and check workflows for agent-driven sync #6
   • Add project configuration and document-glob support #14
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: Add a safe, concise local watch workflow for documentation drift and optional refresh.

   Current behavior:
   mdcode has no file-watch command or watcher dependency. Users must manually rerun synchronization or freshness commands after changing Markdown or linked source files.

   Desired behavior:
   mdcode watch accepts explicit document paths or falls back to the project configuration. It watches selected Markdown and resolved source files, debounces bursts of changes, and runs one reconciliation pass. The default is non-mutating status reporting; --apply is the only automatic-write mode.

   Key interfaces:

   • Watch inputs — explicit document paths take precedence; otherwise load mdcode.config.json from issue Add project configuration and document-glob support #14.
   • Watched set — selected Markdown documents and their resolved linked source files. Refresh the set as configuration or mappings change.
   • Reconciliation — default to the non-mutating plan/check behavior from issue Add plan, diff, apply, and check workflows for agent-driven sync #6 and report only documents or blocks with drift/errors.
   • --apply — explicitly refreshes changed Markdown after reconciliation. Coalesce or ignore watcher events caused by its own writes to prevent feedback loops.
   • Lifecycle — debounce rapid file events; keep watching after recoverable file or configuration errors; produce concise interactive output; document startup, interruption, and unrecoverable error exits.
   • Test seam — isolate the watcher adapter from reconciliation so event behavior can be tested deterministically. Use a reliable cross-platform backend if native watching cannot satisfy recursive/glob needs.

   Acceptance criteria:

   • Watch accepts explicit document paths or configuration-derived documents.
   • It observes selected Markdown and resolved source files and reconciles after debounced changes.
   • Default mode does not write and reports drifted documents or blocks concisely.
   • --apply is required for automatic Markdown writes.
   • Apply-generated file events do not cause a write loop.
   • Recoverable errors are reported while watching continues; startup and exit behavior are documented.
   • Tests cover debounce, source/Markdown changes, non-mutating default, apply mode, feedback-loop prevention, and error recovery.

   Out of scope:

   • A GUI, editor extension, or remote/watch-server mode.
   • Project configuration design, which is issue Add project configuration and document-glob support #14.
   • Redefining safe plan, apply, or check semantics from issue Add plan, diff, apply, and check workflows for agent-driven sync #6.
   • CI polling or release workflow behavior.

   Verification status:
   Confirmed: the repository has no watch implementation or watcher dependency. This issue remains blocked by #6 and #14.
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

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

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

   5db510b

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

   ...

   900a191
5. adrianbrowning

   closed this as completedin #45on Oct 6, 2026