docs-hygiene: agree the plugin's contract before it grows again

[kyle-sexton]

Why this issue

docs-hygiene now carries eleven skills across five distinct concerns, and PR #4133 added four of them at once. Before it grows again, it is worth writing down what the plugin is for, so the next addition is measured against a stated charter rather than against whether it feels adjacent.

This is a proposal, not a decision. Each section states what I would commit to and why; the point is to disagree with the parts that are wrong.

What the plugin is

A repository's tracked markdown, kept honest. Five concerns, each with a stated moment:

Concern	Moment	Skills
Authoring	while the text is being written	write-for-agents, write-for-humans
In-page quality	after it exists, inside one file	compress, audit-noise
Whole-document worth	after it exists, about the file itself	audit-derivability, audit-progressive-disclosure
Cross-file structure	about the relationships between files	extract-ssot, rename-references, the four file-name skills
Enforcement	so the above does not decay	generate-file-name-gate

The axis that makes it one plugin rather than four is the artifact: tracked markdown a repository maintains. That is a real boundary, and it is the one I would defend.

What it should not be

These are the boundaries I would hold, each with the reason it is a boundary and not a gap:

1. Not a prose-style engine. write-for-humans resolves the consuming project's own style guide first and falls back to a named public set. It must never accumulate house rules. The moment this plugin has opinions about the Oxford comma it has stopped being reusable.
2. Not a linter. Structural markdown lint belongs to markdownlint-cli2. Every skill here makes a judgment a linter cannot: whether a document earns its existence, whether a bare stem names a file or an English word, whether a citation may be rewritten.
3. Not a code-comment tool. code-tidying:audit-comment-residue owns non-markdown files and should keep owning them, even where the residue shapes are identical.
4. Not a commit or PR authoring tool. source-control owns commit-message shape and the marketplace owns PR-body sections.
5. Not an auto-applier. Every skill here that changes a file does it behind a human gate, per file. The file-name findings artifact deliberately does not declare type: review-findings for exactly this reason: that type is auto-applicable by construction, and these changes must not be.

The open question I would put first

Eleven skills is at the listing budget. check-listing-budget.sh plugins/docs-hygiene/skills reads 7986/8000. Every future addition now costs an existing skill's description, and PR #4133 already spent eight descriptions to fit four new skills. Three ways out, in the order I would consider them:

1. Split the plugin. The file-name set (setup, audit-file-names, realign-file-names, generate-file-name-gate) is self-contained: its own configuration surface, its own artifact contract, its own gate. It shares nothing with compress or write-for-humans but the word "docs". A docs-naming plugin would give both halves room. This is my recommendation.
2. Accept name-only listing for the least-invoked skills and rely on ## Next chains and explicit invocation. Cheap, but it makes discovery depend on a chain that only fires once something else is already loaded.
3. Hold the line and refuse the next skill. Honest, but it makes the budget the design authority rather than the charter.

Smaller things I would change

• audit-encapsulation is listed in the manifest description but has no README row. Either it belongs in the table or it should be reconsidered; it is the one skill whose concern (citations into skill-private surfaces) sits outside the markdown-artifact axis above.
• The four audit skills have no shared entry point. "Audit my docs" plausibly means any of audit-noise, audit-derivability, audit-progressive-disclosure, or audit-file-names, and a reader has to know the taxonomy to pick. A router would cost one more description, which the budget cannot pay today. Another argument for the split.
• compress gates its entry point on markdownlint-cli2 and no other skill does. Worth stating in the README's Requirements why that one is hard-required while extract-ssot merely names it as an option.
• Cross-platform coverage is Linux plus one Windows step. macOS is unverified and the README now says so. If the marketplace has macOS users, that is a gap worth a runner rather than a caveat.

What I would like agreed

1. The five-concern charter above, or a correction to it.
2. The five boundaries, or which of them are wrong.
3. Whether to split the file-name set into its own plugin, and if so, before or after feat(docs-hygiene): a reusable file-name audit, realign, and gate set #4133 merges.

Refs #4139, #4140, #4141.