[laithalsaadoon]

Retire the spaced em dash in the published docs and make Google.EmDash an error

Follow-up to #45 (the Vale ratchet). Vale 3.24.0 anchors a wrapped list item's alert on a later identical match and reports the two as one, so the Google.EmDash warning count (448 in .vale-baseline.json at 7ea99bb) could hold or fall on a change that added a spaced dash. As an error the rule fails on one alert: a merge folds two errors into one, never into none.

What changed

• Docs: every spaced dash (em or en, a line break counting as a space) in the prose of the Vale scope (docs/**/*.md, site/authored/**/*.md, README.md, AGENTS.md, CONTRIBUTING.md) is rewritten by sense as a colon, comma, period, semicolon or parentheses: 731 in prose before, 0 after. Four stay inside fenced code that quotes source verbatim (two docstrings in docs/insights/contract-map.md, two # noqa comments in docs/reference/public-api.md); Vale does not lint code. Files outside the scope (RELEASING.md, SECURITY.md, package READMEs, the PR template) are untouched.
• .vale.ini: Google.EmDash = error, comment rewritten to say why it sits at error.
• .vale-baseline.json: mise run docs:prose:baseline lowered Google.EmDash 448 -> 0, and the zero entry is removed by hand (the writer keeps a zeroed rule; an error rule has no warning budget). Every other rule is unchanged: 273 warnings.
• scripts/vale_gate.py, mise.toml: the docstring's Vale-limit paragraph says the rule is an error for that reason; examples name Google.WordListCase rather than EmDash.
• Selftest (packages/atif-cli/tests/test_vale_gate.py): the ratchet plants move to a Google.Will fixture (.vale/fixtures/planted-warning.md); new error plants: one spaced dash alone, one in a wrapped list item (.vale/fixtures/wrapped-emdash.md), the two-dash merge, and one beside the real tree (red, no ratchet line); the committed baseline is asserted to carry no Google.EmDash. The strict xfail now expects 2 errors from merged-emdash.md (Vale reports 1).
• CONTRIBUTING.md, AGENTS.md: one sentence each: a spaced dash is an error, write a colon, comma, period, or parentheses instead.
• site/authored/index.md: the front-matter description is quoted, since its new colon is YAML syntax (the built page's meta description is the same text with a colon).

Per-file spaced dashes in prose

File	Before (prose)	After (prose)	Left in fenced code
docs/insights/contract-map.md	113	0	2
docs/insights/impact-analysis.md	98	0	0
docs/behavior/processes.md	81	0	0
docs/architecture/module-map.md	79	0	0
docs/reference/cli.md	64	0	0
docs/insights/tech-debt.md	32	0	0
docs/analysis/risk-hotspots.md	28	0	0
docs/architecture/data-flow.md	28	0	0
docs/insights/debugging-guide.md	22	0	0
docs/insights/business-logic.md	21	0	0
docs/README.md	20	0	0
docs/analysis/dead-code.md	20	0	0
docs/diagrams/behavioral/sequences.md	20	0	0
AGENTS.md	17	0	0
docs/reference/public-api.md	12	0	2
site/authored/agents.md	13	0	0
CONTRIBUTING.md	12	0	0
docs/behavior/state-machines.md	11	0	0
README.md	8	0	0
docs/CONTRACT-V2.md	7	0	0
docs/diagrams/architecture/components.md	7	0	0
docs/architecture/system-overview.md	5	0	0
docs/diagrams/structural/dependency-graph.md	5	0	0
docs/CONTRACT.md	4	0	0
site/authored/index.md	4	0	0
total	731	0	4

Gates (on the committed tree, 5099c2a on main 7ea99bb)

• mise run check: green, docs:prose: vale checked 25 of 25 files: 0 errors, 273 warnings, 0 rules above the baseline of 273; pyright 0 errors; 2494 passed, 1 skipped, 1 xfailed.
• mise run docs:gate: green, docs:links: 20 pages, 45 documents read, 1962 internal links to 282 distinct targets, 0 broken, vitest 73 passed.
• Planted defects on the real tree, each reverted after: a spaced dash in the wrapped list item at docs/README.md:25 gave Google.EmDash and 1 error, exit 1; one at CONTRIBUTING.md:116 gave the same, exit 1; one in the README's "What you can do" intro gave README.md:46:43: Google.EmDash and 1 error, exit 1.

Risks and what to look at

• The rewrite is by sense, about 730 edits by hand. A script checked every changed file against main: inline code spans, links and numbers outside code identical; fenced blocks identical; table rows keep their pipe count. Read the word diff (git diff --word-diff) for meaning, especially sentences where a paired aside became parentheses or a clause became a new sentence (docs/analysis/risk-hotspots.md "Owners" lines, docs/insights/contract-map.md cached_tokens paragraph, docs/diagrams/structural/dependency-graph.md externals sentence).
• Eleven headings change anchors (AGENTS.md's title, eight in docs/behavior/processes.md, one each in contract-map.md and impact-analysis.md); nothing in the repo links to them, and docs:links is green. An outside deep link to the old anchors lands on the page top.
• The build prints [WARN] [content] Entry docs → 404 was not found.; not checked against main.

🤖 Generated with Claude Code