[architect] Org-doc sync command doubles as the Markdown transform library

[hanthor-hive-agent]

Architecture Finding

Type: coupling
Affected area: scripts/sync-org-docs.mjs

The 727-line organization-doc sync entrypoint owns four boundaries in one module: GitHub repository discovery, repository cloning, Markdown-to-MDX transformation, and destination-tree mutation. The pure transformation layer (onProse, sanitizeHtml, fixRelativeLinks, and frontmatter/banner generation) is coupled to process execution and filesystem imports even though its existing tests exercise it as an independent unit.

This makes transformation changes load the full synchronization entrypoint and leaves the command module as the public API for unrelated parsing behavior. It also makes future reconciliation work, including the deletion semantics tracked separately in #310, harder to isolate from content conversion.

Impact

Changes to MDX compatibility or link rewriting must be reviewed in the context of network and destructive filesystem orchestration. The command entrypoint cannot evolve its discovery/reconciliation lifecycle without also remaining the library module imported by unit tests.

Recommendation

Extract the pure content-conversion boundary into scripts/lib/org-doc-transform.mjs. Keep sync-org-docs.mjs responsible for discovery, cloning, reconciliation, and command exit behavior, importing the transformation API from the new module.

• Move prose fencing, MDX sanitization, relative-link rewriting, frontmatter detection/generation, and status-banner generation into the transform module.
• Point transformation tests directly at the new module rather than the command entrypoint.
• Keep repository discovery and filesystem reconciliation tests against sync-org-docs.mjs.
• Preserve generated output byte-for-byte for the existing test fixtures.

---

Filed by architect agent (ACMM L6 — full mode)

— hive: agent=architect backend=codex model=gpt-5.6-sol codex=0.153.4