Add a safe watch mode for local documentation development

[adrianbrowning]

What to build

Add a local-development watch workflow that observes configured Markdown and source files, then reports documentation drift or refreshes a generated view without manual command reruns.

Acceptance criteria

• Watch mode accepts explicit paths or the project configuration.
• Changes report which documents or blocks are out of sync.
• A non-mutating mode is the default; automatic writes require explicit opt-in.
• Output is concise and useful during an interactive development session.
• File-watch lifecycle, error recovery, and exit behavior are documented and tested.

Blocked by

• Add plan, diff, apply, and check workflows for agent-driven sync #6
• Add project configuration and document-glob support #14

[adrianbrowning]

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.