docs-mr: Gate docs MRs on the target's own linters

docs-mr.sh now refuses to write a docs MR until the changed pages pass the target project's own Vale and markdownlint-cli2, run with that project's config and styles at one resolved commit. docs-mr.md also gains a step to read the target's guidance for agents before drafting: in gitlab-org/gitlab that is doc/AGENTS.md and the distilled documentation principles it names.

The skill never ran a prose linter. Its style section said "a prose linter catches the mechanical part" and named none. GitLab's documentation workflow asks for a Vale run on AI-generated documentation before it goes to a technical writer (workflow.md), and the blocking docs-lint markdown job fails on the same Vale errors and markdownlint failures.

flowchart LR
  A[Resolve the target branch to a SHA] --> B[Fetch .vale.ini and the markdownlint config]
  B --> C[Fetch the StylesPath in one archive call]
  C --> D[Run Vale and markdownlint-cli2 on the changed pages]
  D -->|error or failure| E[Block, exit 1]
  D -->|fetch error, 429, zero files| F[Cannot run, exit 2]
  D -->|clean, warnings printed| G[docs-mr.sh writes branch, commit and MR]
  • The styles path comes from the target's own .vale.ini (doc/.vale, docs/.vale and .vale all occur across gitlab-org projects).
  • Tool versions come from the target's .tool-versions or mise.toml, and a local mismatch warns.
  • gitlab-org/gitlab's markdownlint config loads one custom rule file. The gate fetches it at the pinned SHA and runs it, as that project's CI and lefthook do.
  • --no-docs-lint skips the gate for a target that ships no .vale.ini, following the existing --no-title-lint.

Verified: just ci passes (119 tests, shellcheck clean). Against gitlab-org/gitlab at 6e6eb039, a clean page passes with exit 0, and a copy seeded with "GitLab's" and "the the" blocks on gitlab_base.Possessive and gitlab_base.Repetition with exit 1.

Merge request reports

Loading
Loading