docs: repo-wide authoring-doctrine pass, and repair the grammar the em-dash purge left behind

[kyle-sexton]

No linked issue

Summary

A recall-side re-run of the two authoring-doctrine skills, docs-hygiene:write-for-agents and docs-hygiene:write-for-humans, across the whole tracked markdown corpus in two strictly separated lanes.

The 2026-08-26 sweep already ran these as its lanes L7 and L8, so a re-run needs a stated reason that is not "it has been a while". This is it, in that sweep's own words: it ran serially in one context, and "No subagent-spawn tool was available ... Every substitute for fan-out was a corpus-wide mechanical detector plus sampled adjudication, which trades recall for precision. The numbers above are precision-side results and should not be read as completeness" (docs/specs/docs-hygiene-sweep-yield-measurement.md). This pass closes that recall gap by reading every file end to end instead of grepping for cues. It deliberately does not re-run the noise, compression, or derivability lanes, which that record closes for this corpus.

The largest result was not a doctrine violation. Reading the corpus surfaced a regression left by the #2891 em-dash purge: where its mechanical substitution ran without the restructure step its own rewrite guide requires, it left broken grammar in shipped instruction surfaces, including three places where the meaning changed.

Fix

Two commits.

f38d1c16 applies 117 verified authoring-doctrine edits across 83 files: unresolvable cross-references, stale counts and inventories, pointers whose targets no longer exist, and self-contradicting recaps.

93c17eea repairs 17 grammar breaks across 11 skill bodies. The three that changed meaning rather than readability:

• implement-dispatch/SKILL.md — when the caller passes --wave-cap <N>. was a subordinate clause with no main clause, so Cap at that N read as an unconditional rule and contradicted the 3-5 by default line above it.
• docpage-digest/SKILL.md — a dedent inverted the instruction: Truncate the host+path prefix, never the hash so the whole slug is <= 40 chars reads as do not truncate the hash in order to keep it <= 40.
• implement/SKILL.md — two consecutive verbless sentences left Never the producing context auditing itself as a free-floating prohibition with no antecedent.

Repairs on paths in scripts/em-dash-purged-paths.txt restructure rather than reintroduce an em dash, and never substitute a parenthesis, en dash, or spaced hyphen.

Scope and method. 1,084 files read end to end across 90 batches: 995 agents lane, 86 humans lane, and 3 graded separately because lane purity barred both lanes from the write-for-humans tree itself. 274 files were excluded for stated reasons: changelogs and ADRs (historical record), vendored and upstream trees, generated regions, and deliberately defective eval fixtures.

219 findings were raised and all 219 independently verified by agents that did not produce them, with the producing rationale withheld and a default-refute posture: 197 confirmed, 22 refuted, and 15 more where the defect stood but the proposed fix was rejected. Verification caught a worker justifying an edit by citing a .claude/ai-slop.json exemption that does not exist, and another whose replacement would have changed a table's meaning.

102 findings are report-only and are not in this diff, each held for a checkable reason: the fix would rename a heading with inbound anchors (lychee.toml sets include_fragments = "full"), land inside a BEGIN GENERATED region, touch prose a test digest-pins, or force a paragraph rewrap. Notably planning/skills/interview/SKILL.md carries real purge damage inside a section interview-defenses.test.sh:531 pins, so it is routed to that plugin's owner rather than edited here.

Two structural defects found while reading are also fixed: a closing fence carrying trailing text in autonomy/skills/setup/templates/return-capture.md (the JSON block never closed, so 45 lines rendered as code), and a 5 minutes liveness constant in claude-config/skills/audit-pass/reference/run-state-and-resumability.md that contradicted the same file's own correction that the default stale_after_s is 30 minutes.

Verification

Gate	Result
scripts/check-purged-em-dashes.sh	21 declared paths, 30 files scanned, no em dashes
scripts/check-changed-skills.sh origin/main	28 skills checked, 0 failed; all base-ref trigger phrases preserved
markdownlint-cli2	0 issues across all changed files
typos	clean
editorconfig-checker	clean
scripts/affected-tests.sh --run	17 shell suites passed
pytest (7 selected suites)	667 passed, 271 subtests
plugins/planning/tests/interview-defenses.test.sh	passes; no digest-pinned section touched

The 18 selected vitest suites are NOT RUN by the shell runner per its own contract. They fail identically with ERR_MODULE_NOT_FOUND on a stashed tree at origin/main (vitest is absent from this environment), so they are unaffected by this change.

Related

• docs/specs/docs-hygiene-sweep-yield-measurement.md — the prior sweep's recall limitation that motivates this re-run
• docs/specs/docs-hygiene-sweep-unapplied-remediations.md — the prior L7/L8 backlog this extends; all 13 open L7 items verified already applied, and the 6 open L8 items were resolved rather than rediscovered
• docs/adr/0008-admit-only-present-text-defects-to-the-instruction-audit-catalog.md — every finding anchors to text that is present; absences are routed, not filed
• .claude/rules/vendor-docs-are-not-style.md — the declared house style the humans lane resolved to, superseding the skill's bundled default set
• Refs De-slop campaign: purge em dashes and AI tells from this repo's own corpus via /ai-slop:audit fix #2891 — the em-dash purge campaign whose residue this repairs

One item needs a human decision and is deliberately not fixed here. plugins/kindle-dedrm/README.md:25-32 warns "Private marketplace only. Carve out before publishing" and instructs that if the marketplace is ever made public, the plugin should be removed from marketplace.json first. Three sources now say the marketplace is public (README.md:3, docs/CI-RUNNER-ROUTING.md:3, .github/runner-policy.json), and .claude-plugin/marketplace.json:388 still publishes the entry. Correcting the word "private" alone would delete the warning's trigger while leaving the plugin published, and carving it out is a policy call that belongs to a maintainer.

---

Generated by Claude Code

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[github-actions]

Warning

Automated security review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

• Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/33149273653
• Failure class: rate-limit
• Last SDK result: {"subtype":"success","is_error":true,"num_turns":1,"duration_ms":307,"total_cost_usd":0,"api_error_status":429,"class":"rate-limit"}

The check is green on purpose, and it is not evidence. It certifies that a security pass ran, and this one did not complete — but the cause is outside this PR's control, so merging is deliberately left unblocked rather than locking every merge for the length of the outage. Nothing was reviewed at this head. Where this check is required, it is satisfied without that evidence; a human should review security-sensitive changes here before merging.

Re-run the job, or workflow_dispatch this workflow with the PR number, to retry the review (ci-workflows#227). A new push also retries it only if the caller's pull_request triggers include synchronize (the canonical security caller keeps it). An automatic retry may already have run — it is skipped when a partial review could duplicate comments, or when the failure class needs an operator.

Re-running does NOT help for every class:

• rate-limit that persists across re-runs, or auth — the credential or usage budget needs an operator; retrying will not clear it.
• a run that exhausted its turn budget ("subtype":"error_max_turns" above) will exhaust it again. As the PR author, split the change into smaller PRs; raising --max-turns is a change to the caller workflow, not something you can set on this PR.

[github-actions]

Warning

Automated review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

• Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/33149273668
• Failure class: rate-limit
• Last SDK result: {"subtype":"success","is_error":true,"num_turns":1,"duration_ms":406,"total_cost_usd":0,"api_error_status":429,"class":"rate-limit"}

Re-run the job, or workflow_dispatch this workflow with the PR number, to retry the review. A new push re-triggers this lane only if the caller's pull_request triggers include synchronize (the canonical caller omits it).
An automatic retry may already have run — it is skipped when a partial review could duplicate comments, or when the failure class needs an operator (auth).

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.