docs-hygiene: proactive repo-scan detection for copied external content, capability enumerations, and internal-name coupling

[kyle-sexton]

Summary

docs-hygiene has no proactive, repo-wide scanner for three drift shapes
that the new /re-anchor:point-dont-copy corrector (#249) only catches
reactively, inside a live conversation. This issue proposes adding
detection for them — as new declutter noise shapes, a dedicated scan, or
a reviewer pass — so a repo can be swept for them without a human first
noticing the drift in-session.

The three detection gaps

1. External-copy blocks. Content copied or paraphrased from a source the
   repo does not own — a doc site, a third-party playbook, a tool's own
   documentation — that will drift from its upstream. Includes verbatim
   quotes, detail paraphrase (drifts the same as verbatim), extracted value
   tables, and copied config blocks. Distinct from extract-ssot, which
   deduplicates repetition within the repo; this is about copies of an
   external owner's facts.
2. Capability enumerations. Closed lists of what something can do — a
   hard-coded tool schema, a fixed "the N things this supports" list — in a
   durable doc. These go stale the moment the surface evolves; the
   discipline is to phrase duties open-ended and name current mechanisms only
   as marked examples.
3. Internal-name coupling. A durable doc (or citation) that references an
   internal script or file name where the public invocation contract
   (/plugin:skill + args) would do. Internal names are rename blast radius;
   the reference breaks silently on the next rename. Adjacent to
   rename-references (which sweeps after a rename) and audit-encapsulation
   (which catches reaching into skill-private surfaces), but neither
   proactively flags "this citation targets an internal name that should be
   the public contract."

Why proactive detection

point-dont-copy is a reactive corrector: it re-anchors the discipline and
audits the work in flight when a human fires it. That covers a live session
but not a repo-wide sweep — nobody fires a corrector against 200 existing
docs. The docs-hygiene toolkit is where the proactive, classify-the-whole-tree
counterparts live (declutter already classifies five other markdown noise
shapes; extract-ssot scans for duplication). These three shapes have no
proactive home.

Design considerations (not prescriptive)

• Boundary precision matters. Each shape has a legitimate look-alike the
  detector must NOT flag: an adapted-for-this-repo config, a self-pinned
  constraint the repo owns, a dated one-shot research deliverable, an
  empirically observed error string (external-copy); a genuinely
  fixed/closed set that is the contract (capability enumeration); a contract
  identifier that must stay inline (internal-name). A high false-positive
  rate makes the scan noise. point-dont-copy's OK/violation boundary table
  (feat(re-anchor): add discipline-corrector plugin #249) is a starting rubric for the copy shape.
• Placement. Could be new declutter shapes (it already classifies into
  Tier 1/2/3), a dedicated scan action, or a read-only reviewer agent —
  whichever fits the toolkit's structure best.
• Read-only, tiered findings. Consistent with declutter's existing
  contract: classify and surface, do not auto-edit.

Filed as part of the round-2 personal-skill graduation; point-dont-copy
(#249) is the reactive corrective, and this issue is the proactive-scan
counterpart it cannot cover.

[kyle-sexton]

Decision brief — where proactive detection for these three drift shapes lands

Human-operator decision brief. Read-only lane: this is analysis and a recommendation, not a decision. No labels changed, nothing closed.

Problem (2 sentences)

docs-hygiene has no proactive, repo-wide scanner for the three drift shapes that /re-anchor:point-dont-copy (#249) only corrects reactively inside a live session — external-copy blocks, capability enumerations, and internal-name coupling. The open question is purely architectural: where the proactive counterpart should live so it reuses existing scan infrastructure and follows the toolkit's established shape conventions rather than duplicating them.

What's verified today

Actual docs-hygiene skill inventory (gh api .../plugins/docs-hygiene/skills): audit-encapsulation, audit-noise, compress, extract-ssot, rename-references. Note: there is no skill named declutter — "declutter" is a trigger word in audit-noise's description, not a separate skill. The issue/repo vocabulary uses "declutter" to mean audit-noise; I use the real name below.

• audit-noise (plugins/docs-hygiene/skills/audit-noise/SKILL.md) is the proactive, classify-the-whole-tree counterpart pattern this capability wants. It is a read-only classifier driven by scripts/detect.sh, emitting Tier 1 / 2 / 3 findings with a per-shape treatment table, section exemptions, and <!-- markdown-discipline-ignore --> opt-out markers. It already ships five shapes: citation, ghost-ref, preamble, enum-list, scope-meta. Crucially, it already houses drift-risk shapes — enum-list targets enumeration drift ("drift on every add/remove") and citation targets staleness. So audit-noise is not a pure cosmetic-noise skill; the issue's capability-enum shape is a sibling of an existing shape, not a novel concept.
• extract-ssot dedups within-repo repetition at the Rule of Three (3+ files). It does not cover copies of an external owner's facts — confirming the issue's framing that external-copy has no home.
• rename-references sweeps after a rename; audit-encapsulation catches reaching into skill-private surfaces. Neither proactively flags "this citation targets an internal name where the public contract should be."
• /re-anchor:point-dont-copy (plugins/re-anchor/skills/point-dont-copy/SKILL.md) already covers all three shapes reactively — its audit list names copied/paraphrased content, hard-coded tool schemas / capability lists, internal-name references, and closed enumerations — plus an explicit "what is NOT a copy" boundary table (adapted config, self-pinned constraint, dated research deliverable, observed error string). That boundary table is the starting rubric for any proactive detector.
• review plugin already ships a doc-drift-detector agent (plugins/review/agents/doc-drift-detector.md) — a semantic-judgment reviewer for stale references and outdated conventions. Relevant to option (c) below.

The detection is not uniform across the three shapes

audit-noise's model is local regex, per file (detect.sh). That matters:

• capability-enum and internal-name are pattern-matchable — closed "supports N things" lists and internal-script/file-name citations have regex-visible signatures. They fit the detect.sh + tier model directly.
• external-copy is structurally different: a local regex can heuristically flag a candidate block, but it cannot confirm external ownership — that needs upstream comparison or semantic judgment, which a reviewer agent can do and a per-file regex cannot.
• All three still need human classification at the boundary (what's "internal" vs public contract; what's a legitimate fixed contract vs a drifting enumeration; what's adapted-and-owned vs copied). audit-noise's Tier 2 = "review needed" tier is built exactly for this: high-recall detection surfaces candidates, human classifies. Do not assume capability-enum and internal-name are "clean" and only external-copy is fuzzy — the issue's own Design Considerations flag false-positive risk for all three.

Options

(a) RECOMMENDED — Extend audit-noise with new shapes; hold external-copy's placement as an open sub-decision.
Add capability-enum and internal-name as new rows in audit-noise's shape table now. They reuse detect.sh, the Tier 1/2/3 model, the exemption/opt-out machinery, and the treatment-table convention — zero new scaffolding, and they sit beside enum-list/citation, which already do drift detection. This is the minimum-duplication path and matches the toolkit's established scan-shape convention.

• Open sub-question the human should settle: is capability-enum a new shape, or a widening of the existing enum-list (consumer-lists → any closed capability list)? Flag, don't assume.
• External-copy is the genuine open axis (your lane does not decide it): either a conservative Tier-2 heuristic inside audit-noise (deterministic, cheap, high-recall, human-classified — leans on the tier model's design intent) or a semantic reviewer pass in the review plugin reusing doc-drift-detector's judgment machinery. That is the one real tradeoff worth a human decision; see (c).
• Reversibility: highest. A shape is a table row + regex; adding or removing one is trivial and low-blast-radius.

(b) Dedicated new skill (e.g. docs-hygiene:audit-copied-content).
A standalone classifier for all three shapes.

• Tradeoff: duplicates audit-noise's entire scaffolding — a second scan runner, a second tier model, a second exemption/opt-out layer, a second invocation contract and discoverability surface — for shapes two of which are natural audit-noise rows. Splits the "sweep tracked markdown for drift shapes" concern across two skills that a user must now learn to choose between.
• When it wins: only if external-copy's detection grows heavy enough (upstream fetch, diff, caching) that it clearly does not belong beside per-file regex shapes. That is a future trigger, not today's state.
• Reversibility: lower. A new invocation contract is a public surface; retiring it later is a breaking change to anyone who scripted it.

(c) Fold into a review-plugin reviewer pass instead of docs-hygiene.
Put detection in a read-only reviewer agent (extend doc-drift-detector or add a sibling).

• Tradeoff: strongest fit for external-copy specifically (semantic ownership judgment is what reviewer agents do; regex can't confirm it). But routing capability-enum and internal-name here too would couple a docs-hygiene concern into a different plugin and bypass audit-noise's existing shape infra for shapes that fit it cleanly.
• Best role: not an alternative to (a) but the candidate home for external-copy if the human prefers semantic judgment over a Tier-2 regex heuristic. This is the other side of (a)'s open axis.
• Reversibility: medium — an agent is easier to retire than a skill invocation contract, but it introduces cross-plugin coupling of the concern.

Recommendation in one line

Extend audit-noise with capability-enum and internal-name shapes (clean infra reuse, sits beside existing drift shapes, trivially reversible); treat external-copy's placement — audit-noise Tier-2 heuristic vs. review-plugin reviewer pass — as the one explicit open sub-decision for the operator, because it is the only shape whose detection genuinely exceeds per-file regex. Also decide whether capability-enum is a new shape or a widening of enum-list.

Cross-links

• feat(re-anchor): add discipline-corrector plugin #249 (/re-anchor:point-dont-copy) — the reactive corrector this proactive scan complements; it already covers all three shapes in-session and its OK/violation boundary table is the detection rubric.