## Summary
Agents can produce prose that passes style checks but still sounds
unnatural or takes effort to understand. Add guidance to AGENTS.md and a
required prose review with concrete examples to the write skill.
Broaden the skill to cover PR text, release notes, and other prose,
while keeping its branch and commit workflow specific to documentation
fixes.
Markdown formatting passes. Vale reports only existing findings in
unchanged text; the skill validator rejects the existing `hooks` field.
Generated by Codex
Several documented prose patterns were not enforced, and agents could overlook non-fatal Vale warnings.
Expand Docker's local Vale rules, remove obsolete rule links, and clarify scoped agent validation.
The agent guide did not explain how sidebar recursion and sitemap filtering interact for hidden pages and sections.
Document tree construction, discovery exclusions, subtree cascading, and branch-scoped hidden navigation.
Note in AGENTS.md and the PR review workflow that
content/reference/api/ai-governance/api.yaml is a verbatim copy of the
upstream OpenAPI spec, vendored from the private docker/governor-services
repo via hack/sync-governance-api.sh, and should not be hand-edited.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
The lint script was buried in the write skill's scripts directory, so
only agents that invoked that specific skill discovered it. Move it to
the repo-level scripts/ directory and reference it from AGENTS.md so
every agent session sees the recommended workflow.
- scripts/lint.sh: scoped markdownlint + vale on changed files
- AGENTS.md Commands and Verification loop now point here
- write skill SKILL.md updated to use the new path
- post-edit.sh stays in the skill (it's a PostToolUse hook tied to that
skill's lifecycle)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The vale ruleset was producing ~1,600 violations, a meaningful fraction
of which were noise from a hard-to-maintain vocabulary file, sprawling
shortcode-ignore regex, and rule patterns with known false positive
modes. This commit cleans up all three.
Vocabulary fixes (accept.txt):
- Fix the case-insensitive catch-all `(?i)[A-Z]{2,}'?s` which was
matching every plural word and suppressing other rule checks on them
- Fix wrong-cased canonical entries that caused cascading Vale.Terms
false positives: Duckduckgo→DuckDuckGo, fluentd→Fluentd, [Rr]eadme
removed (README is correct), VPNKit, AppArmor, OpenSSL, etc.
- Remove `Mac` (Apple brand) — conflicted with `MAC` (address) under
Vale's case-insensitive vocab matching; both are in the base dictionary
- Resolve duplicate case entries (uncaptured/Uncaptured, etc.) by using
narrow character-class regex like `[Uu]ncaptured` to opt out of Terms
enforcement
- Add common tech terms missing from the vocab (Vitest, Deno, Pinecone,
Wolfi, Streamlit, ESLint, Kustomize, HAProxy, Qdrant, etc.)
- Add common acronyms and abbreviations as canonical uppercase (URL,
JSON, TCP, UID, SHA, CMD, VM, GPG, KVM)
Rule fixes:
- TokenIgnores/BlockIgnores collapsed from 7 patterns to 2 (one for
inline shortcodes, one for multi-line block shortcodes)
- Docker.Capitalization regex tightened to skip `docker` preceded or
followed by `-`/`.` (image names, URLs) and word chars after
(`dockerd`, `Dockerfile`)
- Docker.RecommendedWords `vs: versus` now excludes "VS Code" and "vs."
(heading abbreviation)
- Docker.We becomes case-sensitive so `US` (country) isn't flagged as
the pronoun `us`
- Docker.VersionText requires X.Y minimum to avoid matching port numbers
like "1025 or higher"
- Docker.Units drops KB→kB swap (KB is conventional in user-facing docs)
Section overrides:
- Brace-expansion glob `[{a,b,c}]` consolidates repeated path lists
- Release notes and previous-versions content fully disabled (each rule
listed explicitly because Vale's BasedOnStyles= empty in a section
doesn't actually disable rules, despite the docs)
- Reference content disables Vale.Spelling/Vale.Terms/Docker.Capitalization
Net result: 1,429 → ~1,070 violations, with spot-checks confirming the
remaining violations are real (CLI commands without backticks, first-
person plurals, `allows`→`lets`, etc.) and not artifacts of the rules.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
