Audit Encapsulation

Why this skill exists

Skills have a public API and a private body, the contract is context/public-surface-contract.md (bundled with this skill). External consumers, rules, agents, other skills, prose docs, must cite the public surface only. Editing the private body must not break external consumers because no external consumer is allowed to depend on it.

Without enforcement, private bodies leak. A rule file cites a path inside <skill>/<some-subdir>/ because the content is convenient. The skill author refactors that subdir and the citation breaks silently. Nothing fails the build, nothing greps red. The skill cannot evolve without coordinating with every leaker.

This skill provides the detection + classification + remediation discipline that closes that gap. Distinct concern from /docs-hygiene:extract-ssot (which detects content duplication via Rule of Three). Encapsulation violations are single-violation matters. Rule of Three does not gate them.

Public surface matrix

The Skill surface, Public = frontmatter + documented actions + args/flags + /skill-name slash invocation + the scripts/ entry surface; private = everything else inside .claude/skills/<X>/ or plugins/<plugin>/skills/<X>/ (any OTHER subdirectory, all *.schema.json at any depth, all heading anchors), is defined by context/public-surface-contract.md, including the data-file and scripts/ entry-surface carve-outs and the rip-and-paste-portability rationale. This skill audits cites against two more authoring surfaces the contract file does not enumerate:

CI / git-hook sharing. Pick a technique, not an exception

Workflows and git hooks needing logic that ALSO lives in a skill must not reach into skill internals. Pick a sharing technique by logic size. Scripts/ facade (the skill exposes a public scripts/<name>.sh entry delegating to a private backend; hooks/CI invoke it), intentional duplication, plugin packaging, or headless claude -p '/skill <action>' invocation, per context/public-surface-contract.md "CI / git-hook consumption. Entry surface, not internals".

The choice is per-cite. The bundled detect.sh is a candidate enumerator: it lists path shapes that may be private-surface cites. Exit 1 means candidates exist after mechanical filters, not that those hits are adjudicated violations. Classification (filter taxonomy below) is required before treating a hit as illegal. Do not hard-gate CI or pre-commit on detect.sh's exit code alone.

Action router

One action per response.

No inherited scope. Confirm before a repo-wide run

Shared clean-tree / no-scope shape: ../../context/clean-tree-fallback.md. Read it when the bare invocation is unattended or non-interactive, the case the rules below leave unstated, or when editing those rules. This skill's trigger is "no inherited scope" (not only "clean tree"), a dirty tree with unrelated edits still needs the confirm when nothing names the detect surface.

The default action's domain is the whole repo, but a bare invocation does not prove the user meant that. When the invocation arrives with NO inherited working set. No diff in flight, no prior audit notes, nothing in the conversation narrowing the scope. Ask ONE confirmation before running the detection, presenting these prescribed defaults for adjustment:

An inherited scope, or a scope the user already stated in the invocation ("across the repo", "audit this directory"). Suppresses the question; audit that surface directly. sweep is the explicit opt-in that skips the confirmation and runs the repo-wide detect immediately.

Detection

bash "${CLAUDE_SKILL_DIR}/scripts/detect.sh" (--apply-filters optional)

detect.sh enumerates candidates, not adjudicated violations. With --apply-filters, stderr summary keys are raw / mech-filtered / candidates. Exit 1 = candidates remain; exit 0 = no candidates (not a clean bill of health. See limitations below).

Matched shapes:

• Any path into a subdirectory under a skill (<X>/<any-subdir>/.... Regardless of subdir name, including uppercase / single-char / digit-leading / underscore-leading segments) except scripts/ (entry-surface carve-out, see below)
• Heading-anchor cites into SKILL.md body structure (<X>/SKILL.md#<anchor>)
• Any *.schema.json file at any depth (<X>/<file>.schema.json)

Matched path prefixes: .claude/skills/<X>/..., plugins/<plugin>/skills/<X>/..., and relative forms (skills/<X>/... plugin-README short cites, plus ../-prefixed cites whose lexical resolution lands on a private skill surface, including sibling-skill links that never spell skills/ in the cite text).

Legal external cites: bare <X>/SKILL.md path (discouraged but legal. Natural-language + slash invocation is canonical), <X>/<file>.json data files at skill root (data-file carve-out), and <X>/scripts/<entry> entry scripts (entry-surface carve-out below).

scripts/ entry-surface carve-out: a skill's scripts/ is its declared ENTRY surface per context/public-surface-contract.md. Harness / CI / hooks / workflow registries MAY path-cite a skill's entry scripts directly, so this inbound audit treats <X>/scripts/... cites as legal (like data files and bare SKILL.md) and never flags them. The skill-to-skill half of the asymmetry, a sibling SKILL.md citing another skill's scripts/ stays slash-only, is out of this inbound audit's scope; a consuming repo that wants it enforced wires its own outbound gate.

The script scans the consumer repo it runs in: every .claude/ child directory except skills/ (self-citation domain; opt in via --include-skills for skill-maintenance review) and worktrees/, plus .github/, docs/, .lefthook/, plugins/, root instruction/config files (AGENTS.md, CLAUDE.md, README.md, CONTRIBUTING.md, lefthook.yml), and .claude/ top-level files. Each filtered to what exists.

Or invoke the skill (the agent applies the filter taxonomy below):

/docs-hygiene:audit-encapsulation detect

Filter taxonomy. Legal hits

detect.sh output is broad without --apply-filters. Use the filter taxonomy below for KIND-1/2/3; --apply-filters drops only the mechanically-decidable subset (self-citation and worktree paths). Remaining rows are candidates. Apply KIND-1/2/3, mirror-automation, glob-config, and plugin-cache judgment in-session before calling anything a violation.

Hits that survive ALL filters = illegal. Report.

The intra-plugin filter is off unless the consuming repo has actually declared that convention and is built that way: one manifest and one version per plugin, no per-skill manifest, and no install path that separates two skills in one plugin. Check before applying it; the unrelaxed taxonomy is the default. A path that does not resolve as written is still a defect even when this filter would otherwise make it legal.

Remediation paths

Path A. Promote content out (caller wants the data)

Use when: the caller needs data the private file contains, and the data is genuinely shared vocabulary or constraint.

1. Invoke /docs-hygiene:extract-ssot verify via the Skill tool (the 6-gate refuse-fast check) against the private file's content
2. If it passes: extract the content into a shared rule or convention doc outside the skill (e.g. .claude/rules/<topic>.md, or extend an existing one)
3. Migrate the violator AND the original skill body to cite the new doc by heading
4. Delete or shrink the private file
5. Invoke /docs-hygiene:rename-references via the Skill tool to sweep all syntactic forms

Path B. Route via /skill-name invocation (caller wants the behavior)

Use when: the caller wants the skill's behavior, not the data. A reference into the private body is a workaround because the skill has no public action covering the use case.

1. Identify which skill action would deliver the desired behavior
2. If the action exists: rewrite the caller to invoke /<skill-name> <action> <args>
3. If the action does NOT exist:
   • Surface the gap to the user as a side note
   • File a tracking work item in the consumer's tracker for the missing public action
   • Leave the violation in place with a # TODO(audit-encapsulation): missing /<skill> <action> marker
   • Do NOT silently inline a workaround that makes the violation harder to find later

Refactor pass discipline

When invoked from another skill's execute pass (e.g. /docs-hygiene:extract-ssot execute):

A surfaced violation is never silently ignored: fix it, capture it as a side note to the user, or file a tracking work item.

Output shape (detect mode)

# Encapsulation audit — N violations

## Violations
| File | Line | Cite | Suggested path |
|------|------|------|----------------|
| ... | ... | `<skill>/<dir>/<file>` | A or B |

## Filtered (legal — sample for verification)
| File | Line | Filter applied |
|------|------|----------------|

## Summary
- Total raw hits: M
- Mechanically filtered: M-C
- Candidates (need taxonomy classification): C
- Adjudicated illegal after filters: N
- Path A candidates: a
- Path B candidates: b
- Missing public action (Path B blocked): c

## Recommended next step
`/docs-hygiene:audit-encapsulation fix <file>:<line>` for one-by-one OR `/docs-hygiene:audit-encapsulation file-issues` for batch work-item filing

Anti-patterns guarded

• Single-violation tolerance. "it's only one place, no big deal." Encapsulation rot accumulates one violation at a time. Each is a binary contract break, not a Rule of Three threshold.
• Silent workaround, the caller inlines the data instead of routing through the skill, hiding the violation from future audits. Mitigated by the # TODO(audit-encapsulation) marker requirement.
• Filter laziness. Flagging every grep hit without applying the filter taxonomy. False positives erode trust in the audit; users stop running it.
• Wrong-direction Path A. Promoting skill-internal content to a shared doc when the caller actually wanted skill behavior. Mitigated by the "data vs behavior" classification step in Path A vs Path B selection.

Sanity checks

What this skill does NOT do

• Detect content duplication / Rule of Three clusters → /docs-hygiene:extract-ssot
• Enforce code-side public/private (TypeScript export, .NET internal, Python _prefix) → language-level tooling (compiler, lint)
• Refactor skill bodies that ARE legitimately self-contained (no external violations) → general refactoring, out of scope
• File work items without classification. Path A vs Path B must be picked first
• Auto-fix without user review. Each Path B route changes call-site invocation; the user inspects the diff

Reference index. Load on demand

Recheck triggers