diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f0293d1ddb..08c889e70c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -46,9 +46,9 @@ jobs: # Doc-sync gates (RFC 006). doc-typecheck compiles the fenced ts blocks in # the docs and resolves vendor packages via their built declarations, which # the typecheck step above emits — so it runs after typecheck. The event - # taxonomy check only reads source. Same `doc-sync` script the pre-push - # hook runs (ADR 0007: one source of truth). - - name: Doc-sync gates (doc code blocks + event taxonomy) + # taxonomy check and the markdown wrap check only read source. Same + # `doc-sync` script the pre-push hook runs (ADR 0007: one source of truth). + - name: Doc-sync gates (doc code blocks + event taxonomy + markdown wrap) run: pnpm run doc-sync # Module-graph freshness: regenerate docs/module-graph.md from the diff --git a/docs/adr/0014-doc-sync-enforcement.md b/docs/adr/0014-doc-sync-enforcement.md index 6c248b9431..2187249c43 100644 --- a/docs/adr/0014-doc-sync-enforcement.md +++ b/docs/adr/0014-doc-sync-enforcement.md @@ -15,9 +15,11 @@ Two gates, mirroring the existing `scripts/` style (tsx ESM, one job each): Both run via a shared `doc-sync` package.json script that the lefthook pre-push hook and CI both invoke (ADR 0007: hooks and CI call the same scripts, so the gate fires locally before a push — not only after it). They run after `pnpm run typecheck` (which emits the vendor `lib/` that doc-typecheck resolves against). API-extractor golden reports (RFC 006 part 3) were deliberately **deferred** — low value for an internal monorepo where reviewers already see the source diff, and a heavy, finicky dependency. +**Amendment (2026-06-17):** a third gate, **`verify-md-wrap`**, was later folded into `doc-sync`. It parses each in-scope Markdown file (`README.md`, `docs/**`, `packages/*/README.md`, plus `AGENTS.md` / `packages/AGENTS.md`) with `mdast-util-from-markdown` + GFM and fails on any `paragraph` node spanning more than one source line, enforcing the AGENTS.md "Markdown is not hard-wrapped" convention. Same verify-don't-generate principle: it reports hard-wraps and never rewrites, so it adds no formatting churn. `doc-sync` is now three gates. + ## Consequences -- Doc drift in the two checkable classes now fails the pre-push hook and CI instead of waiting for a reviewer to notice. This is an instance of ADR 0007's "mechanical gates over prose." +- Doc drift in the checkable classes now fails the pre-push hook and CI instead of waiting for a reviewer to notice. This is an instance of ADR 0007's "mechanical gates over prose." - Making doc snippets compile costs a few stub imports/`declare`s; the `ignore-check` ratio must stay low or the gate is theater (the ratio guard enforces this). - The taxonomy check is name-only — a wrong Mode or Purpose column still needs human review. Generating the table from source was considered and rejected as more machinery than the problem warrants. - API reports remain available to revisit if the packages are ever published externally.