Provide a reusable CI script to check documentation synchronization

[adrianbrowning]

Parent

#10

What to build

Provide a ready-to-copy CI script that verifies Markdown code blocks are synchronized with their linked source files. The script should be suitable for a consumer repository and fail the job when mdcode would change a checked document.

Acceptance criteria

• A documented example CI script accepts one or more Markdown document paths.
• It runs mdcode in a non-mutating mode and compares the generated Markdown with the checked-in document.
• It exits successfully when every document is synchronized and non-zero when drift is found.
• It emits actionable output identifying each out-of-sync document.
• Documentation shows how to invoke the script from a GitHub Actions workflow and a local shell.

Blocked by

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

[adrianbrowning]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Provide a copyable CI and local-shell recipe that fails when linked Markdown code blocks drift from source files.

Current behavior:
The repository has no reusable consumer-facing drift-check script or GitHub Actions example. The existing update behavior does not yet offer the safe check contract needed for CI.

Desired behavior:
Consumers can copy one documented script, pass one or more Markdown documents, and run a non-mutating freshness check. The script reports each document with drift, exits successfully only when every selected document is synchronized, and works unchanged from a local shell or GitHub Actions job.

Key interfaces:

• Document inputs — accept one or more explicit Markdown paths and process each independently.
• Check operation — use the public non-mutating update --check behavior from issue Add plan, diff, apply, and check workflows for agent-driven sync #6.
• Exit behavior — success when no drift is found; non-zero drift result when one or more documents would change; operational failures remain distinguishable.
• Actionable reporting — identify every out-of-sync document and preserve the underlying command diagnostics.
• Consumer examples — provide both a local-shell invocation and a minimal GitHub Actions usage example.

Acceptance criteria:

• A documented, ready-to-copy script accepts one or more Markdown document paths.
• It runs mdcode without modifying the documents.
• It exits 0 only when every document is synchronized and returns a non-zero drift status otherwise.
• It reports each document that is out of sync.
• The same recipe is documented for local-shell and GitHub Actions use.
• Tests cover synchronized, drifted, multi-document, and operational-failure cases.

Out of scope:

• Project-level configuration or glob discovery.
• Runnable-example validation, which is issue Provide a CI example for validating runnable Markdown snippets #12.
• Release publishing or credential configuration, which is issue Gate package releases on mdcode documentation and example checks #13.
• Redefining the update/check contract, which is issue Add plan, diff, apply, and check workflows for agent-driven sync #6.

Verification status:
Confirmed: no existing GitHub Actions assets or reusable drift-check script exists. This issue is blocked by #6.