Parcourir la source

docs: record verify-md-wrap in the doc-sync source-of-truth docs

Adding verify-md-wrap to the shared doc-sync gate left its defining docs
stale (Codex review):
- ADR 0014 described doc-sync as two gates; add a dated amendment for the
  third (verify-md-wrap) and drop the "two checkable classes" wording.
- CI step label/comment said "doc code blocks + event taxonomy"; include
  the markdown wrap check.
Tianyi Cui il y a 3 mois
Parent
commit
ffc107aa57
2 fichiers modifiés avec 6 ajouts et 4 suppressions
  1. 3 3
      .github/workflows/ci.yml
  2. 3 1
      docs/adr/0014-doc-sync-enforcement.md

+ 3 - 3
.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

+ 3 - 1
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.