feat(docs-hygiene): add audit-progressive-disclosure skill (0.16.0)

[kyle-sexton]

No linked issue

Summary

Adds /docs-hygiene:audit-progressive-disclosure — a read-only classifier that grades agent-facing instruction markdown against a three-tier load-cost model (always-loaded / invocation-loaded / on-demand), finding both split opportunities (oversized, mixed-concern, or tier-inappropriate content) and hub/spoke disclosure defects (blind pointers, orphan spokes, deep nesting, missing TOCs). Bumps docs-hygiene to 0.16.0 and applies the treatments from the skill's first live run against its own plugin.

Fix

• New skill plugins/docs-hygiene/skills/audit-progressive-disclosure/: SKILL.md hub (154 lines) with a 7-shape/2-lane findings taxonomy and audit-noise-style Tier 1/2/3 semantics; context/tier-model.md spoke carrying the official numbers (500-line SKILL.md cap with "approaching" as the split trigger, 200-line CLAUDE.md target, listing caps/budgets), split triggers, pointer-quality criteria, and an explicit citation posture (Anthropic-prescribed vs independently corroborated vs community-advisory).
• scripts/detect.sh deterministic fact emitter (sizes, heading census, load-tier classification, pointer inventory with source-line context, orphan/chain detection) with scan-root-relative corpus exclusions so explicit fixture descent still works; 28-case detect.test.sh.
• Evals: 7 cases over 3 fixture sets (mixed-concern instruction file, healthy hub/spoke false-positive guard, broken hub/spoke).
• Design postures (locked via a 16-question interview plus a verified multi-source research pass over Anthropic's prescribed progressive-disclosure model): thresholds advisory (ceilings, not targets); two-band TOC treatment reflecting the official 100-vs-300-line inconsistency; no "should have spokes" shape for small single-file skills; pointer chains beyond one level flagged. The interview Brief rode this branch as a Contract-tier slice and was pruned before merge per the topic-docs convention (8bb24ac9); its durable outcomes live in the skill body, the tier-model spoke, and the CHANGELOG entry.
• Live-run treatments applied (6c3d67e8): the skill's first run against docs-hygiene itself found 2 Tier-1 missing-toc findings (723-line patterns.md, 314-line identify.md) and 15 awareness-band spokes — all 16 enumerable spokes got fence-aware, anchor-validated Contents sections; patterns.md a jump-by-form grep recipe; append-only lessons.md a drift-safe grep recipe instead of a list that would drift on every append.
• Integration: plugin.json 0.16.0 + keywords, README skill-table row, CHANGELOG entry, marketplace tags (progressive-disclosure, context-engineering), shared clean-tree-fallback row, allowed-tools pairing-test roster.

Verification

• check-skill.sh audit-progressive-disclosure: PASS — 0 errors, 0 warnings (description 1154/1536 chars, 154/500 lines, summary 80/100 codepoints).
• detect.test.sh: 28/28 cases pass; check-evals-quality.sh: PASS, 0 warnings; evals.json validates against the bundled schema.
• allowed-tools-pairing.test.sh: all checks pass with the new skill in the roster.
• markdownlint-cli2 across the plugin (49 files): 0 issues — every generated TOC anchor validated by the link-fragment rule; typos, shellcheck, and shfmt clean; both manifests validate against their schemastore schemas.
• Live run re-executed after treatments: every 100-plus-line enumerable spoke now reports toc=yes; the two Tier-1 findings clear; check-skill PASS on all four touched skills.
• contract-slice-prune-gate: initially red on the Brief slice, green after the prune commit 8bb24ac9 (the gate's intended lifecycle — slice on branch, pruned before merge).

Related

• Topic-docs convention (docs/conventions/topic-docs/README.md) — governs the Contract-tier slice lifecycle this PR followed; the pruned Brief remains readable in branch history at b5ff2b31.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WNJdbHgak9WnA46CVedYEa

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

Claude finished @kyle-sexton's task in 4m 2s —— View job

---

Claude finished the code review

• Gather context (PR body, changed files, CLAUDE.md/REVIEW.md)
• Invoke /review:code-review and apply its criteria
• Post inline findings
• Post final summary

Review scope

This repo carries a claude-security-review.yml workflow, so per REVIEW.md this lane is scoped to correctness/design/conventions/tests/docs — security findings are left to that lane. I read the full diff (git diff origin/main...HEAD), traced detect.sh's logic by hand against all three eval fixtures (broken-skill, healthy-skill, mixed-instructions.md), spot-checked every new/changed Table-of-Contents against its file's actual headings (including fence-awareness — batch.md has decoy headings inside code fences that are correctly excluded), and verified the manifest/README/CHANGELOG bumps are mutually consistent. I could not execute detect.sh or detect.test.sh myself (sandboxed environment blocks running arbitrary scripts) — the PR's claimed "28/28 pass" and "0 markdownlint issues" results are author-reported and unverified by me; everything else above I checked directly.

Findings

One inline comment posted:

• plugins/docs-hygiene/skills/audit-progressive-disclosure/SKILL.md:78 — a numbered-list formatting bug in the "Auto-detect default" section. Items 3 and 4 are merged onto one source line, so Markdown renders them as a single list item, and the next line's "4." collides with the literal "4." embedded in that merged text. The intended 5-rule list (offer / uncommitted / single-file / directory / audit-keyword) collapses to 4 items, with "Directory path → recursive batch" losing its own bullet even though the Action Router table above correctly lists it as distinct. Low severity (the rule is still stated correctly elsewhere), but worth a quick fix — suggestion included inline.

Everything else held up under inspection: detect.sh's pointer/orphan/chain logic matches the eval expectations exactly when traced by hand against the fixtures, the tier-classification heuristics and TOC two-band treatment match context/tier-model.md's stated numbers, version/description/keyword bumps across plugin.json/README.md/CHANGELOG.md/marketplace.json are consistent, and the "live-run treatment" TOCs added to extract-ssot/rename-references/audit-derivability spokes all match their files' real headings.

[claude]

Claude finished @kyle-sexton's task in 1m 24s —— View job

---

Security Review — /review:security-review

Task list

• Gather context (PR diff, repo CLAUDE.md, custom instructions)
• Run /review:security-review per custom instructions
• Post findings (or clean bill of health)

Scope reviewed: all 35 files changed in this PR (git diff origin/main...HEAD, head 6c3d67e). This PR adds a new read-only docs-hygiene skill (audit-progressive-disclosure) plus supporting markdown/context/eval fixtures across four skills, a plugin-manifest bump, and CHANGELOG/README updates. The only executable surface is two new bash scripts and one modified test script:

• skills/audit-progressive-disclosure/scripts/detect.sh — a read-only fact emitter (find/grep/awk/sed over local markdown files). Path arguments are consistently quoted, find/grep calls use -- where relevant or are otherwise not shell-injectable, and there's no eval, no network I/O, and no execution of file contents (markdown is only read as data via grep/sed/awk).
• skills/audit-progressive-disclosure/scripts/detect.test.sh — self-contained regression tests operating entirely on throwaway mktemp fixtures.
• scripts/allowed-tools-pairing.test.sh — trivial formatting change plus adding audit-progressive-disclosure to the roster array.

The new skill's allowed-tools frontmatter (SKILL.md) is scoped to detect.sh, grep, head, and echo, and the skill explicitly enforces read-only behavior ("no Edit, no Write, no mutating Bash ops"). The ! pre-computed-context commands (git branch --show-current, git status --porcelain | grep | head) take no external input and are read-only.

I scanned the full diff for injection surfaces, credential/token handling, unsafe network calls, and GitHub Actions permission/trigger changes (curl/wget/eval/sudo/chmod/secrets/tokens/pull_request_target/workflow_run) — no .github/workflows/* files are touched by this PR, and no matches indicated a real exploitable path (the "token" hits are all about LLM context-window tokens in documentation prose, not credentials).

No security issues found. This PR is documentation/skill content plus a local, read-only shell fact-emitter — no trust-boundary crossings, no injection surface, no CI/workflow changes.

[github-actions]

Last security-reviewed head: 1999427fbcb58b611623985b148704ec3815c8e7. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6c3d67e80d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Claude has reviewed this PR 5 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

Claude finished @kyle-sexton's task in 4m 2s —— View job

---

/review:code-review

• Gather context / read skill instructions
• Skip-gate check (open/draft/trivial/already-reviewed) — PR is open, non-trivial (1121 additions across 34 files), no prior review this head — proceeded
• Review diff vs origin/main for correctness & maintainability
• Post inline findings
• Final summary

Reviewed the diff (git diff origin/main...HEAD, 34 files) against the code-review lane's high-signal bar: correctness and maintainability, scoped to changed lines, excluding anything a linter/formatter would catch and excluding security (routed to the dedicated security lane). Read the new audit-progressive-disclosure skill (SKILL.md, context/tier-model.md), the fact-emitter scripts/detect.sh and its detect.test.sh contract tests, all three eval fixture sets against evals/evals.json's stated expectations, and the mechanical TOC-only diffs to extract-ssot/rename-references/audit-derivability context files, plugin manifests, README, and CHANGELOG.

Note: this environment's Bash access for this lane is scoped to gh pr diff/view/comment/review, Read, Glob, Grep — I could not execute detect.test.sh or run detect.sh against fixtures myself, so the "28/28 pass" and live-run claims in the PR description are author-stated and unverified by me; I instead statically traced the script logic and cross-checked it against the fixtures and test assertions, which line up correctly.

Posted 2 inline findings:

1. skills/audit-progressive-disclosure/SKILL.md:78-79 — a numbering slip in the auto-detect router's ordered list: item 3 embeds 4. Directory path → recursive batch. as trailing prose instead of its own list item, then the next line reuses the number 4 for the explicit-audit-form rule. Only 4 numbers cover 5 distinct router behaviors. Minor but notable given the file's own subject matter is instruction-file clarity.
2. skills/audit-progressive-disclosure/scripts/detect.sh:230-233 — the orphan-spoke "referenced" check greps for the spoke's bare basename as a substring anywhere in sibling markdown text rather than checking for an actual pointer to it, so a plain-text mention of the filename (not a link) silently suppresses a true orphan finding. This is more significant than a typical heuristic gap because SKILL.md's "Facts vs judgment" section doesn't list orphan review among the things the judgment layer double-checks — orphan records from detect.sh are treated as authoritative, so there's no downstream layer to catch the false negative. Suggested reusing the already-built md_links() pointer extraction instead of a raw substring grep.

Everything else checked out: the eval fixtures (broken-skill, healthy-skill, mixed-instructions.md) match what evals.json claims they exercise; the tier-model citation posture (Anthropic-prescribed / corroborated / community) is applied consistently; manifest/README/CHANGELOG version bumps (0.15.2 → 0.16.0) are consistent across plugin.json, marketplace.json, and CHANGELOG.md; and the TOC additions to sibling skill files are inert (headings only, no content changes).

Branch: claude/progressive-disclosure-skill-b84q34

[claude]

Claude finished @kyle-sexton's task in 1m 10s —— View job

---

Security Review — /review:security-review

Task list

• Gather context (PR diff, custom instructions, prior review state)
• Run /review:security-review per custom instructions
• Post findings (or clean bill of health)

Scope reviewed: This lane already posted a clean security review at head 6c3d67e80d. Per the skip-gate ("this head already has a successful security review that still applies"), I scoped this pass to the commits added since then — 8bb24ac (pruned the Contract-tier design-doc slice, docs/topics/progressive-disclosure-skill/PLAN.md) and c6feff8 (addressed the five review findings on detect.sh/SKILL.md), bringing HEAD to c6feff86a3fca89e52a81b4a92bff01e0810b4db.

What changed in that delta:

• scripts/detect.sh — pure logic fixes to the read-only fact-emitter: subtree CLAUDE.md now classifies as invocation tier instead of always (path-prefix comparison against the scan root, no external input); orphan detection now does a hub-rooted BFS (normalize() + ref_candidates()) instead of an unbounded grep -r, correctly bounding traversal to paths under $hub and rejecting ..-escapes; the TOC heuristic switched from grep -c (line count) to grep -o | wc -l (link count) restricted to the first 40 lines. All new code operates on local files with quoted variables, no eval, no network I/O, no shell-metacharacter interpolation from untrusted input — same posture as the already-reviewed version.
• SKILL.md — fixed the numbered-list rendering bug (splits the merged "single-file / directory" rule into two items) and clarified that the pre-computed git status --porcelain | head -10 context is a sample, not the full corpus, directing the agent to re-derive the full uncommitted-file list in-session rather than silently truncating at 10. This is a prompt-clarity fix, not a new capability or tool grant — allowed-tools is unchanged.
• detect.test.sh — new regression cases for the above (nested CLAUDE.md, disconnected reference cycles, deep vs. compact TOC anchors). Test-only, no execution surface change.
• CHANGELOG.md — prose only.

No .github/workflows/* files, permissions, secrets, or trust boundaries are touched by this delta. No eval, no new network calls, no credential handling introduced.

No security issues found. The delta since the last reviewed head is a self-contained bug-fix to a local, read-only shell fact-emitter plus a prompt-clarity edit — no new injection surface, no trust-boundary changes, no CI/workflow changes.

[claude]

Claude finished @kyle-sexton's task in 3m 24s —— View job

---

Claude finished @kyle-sexton's task —

Todo list

• Gather context (PR body, diff, CLAUDE.md/REVIEW.md)
• Invoke /review:code-review and apply its criteria
• Post inline findings
• Post final summary

Review scope

c6feff8 is a follow-up fix commit addressing the four Codex findings and the one Claude-lane finding from the prior review round on this PR (all at commit 6c3d67e). This lane is scoped to correctness/design/conventions per REVIEW.md (security lane covers the rest), so I focused on verifying those five fixes by hand-tracing detect.sh's new logic against the fixtures and the skill's own SKILL.md action-router rules — I can't execute shell scripts in this sandboxed environment, so nothing below is claimed as "ran and passed"; it's all read/trace-verified.

Findings

One inline comment posted:

• detect.sh:204 — the nested-CLAUDE.md tier fix is incomplete: it only works in directory-scan mode. In single-file mode (SKILL.md's Action Router rule 3 — "Single file path → single-file audit" — runs detect.sh directly on that one path), TROOTS is set to dirname(arg), so rel at line 204 is mathematically always equal to basename(f) regardless of nesting depth. That makes classify_tier always return always for a directly-targeted CLAUDE.md/AGENTS.md/MEMORY.md, even a deeply nested one like packages/api/CLAUDE.md, contradicting context/tier-model.md. The new regression tests only cover this fix via directory-mode scanning, so the single-file path — arguably the more common real-world invocation for auditing one specific instruction file — never got exercised and the bug slipped through. Details and a suggested fix direction are in the inline comment.

The other four fixes in this commit held up under trace-verification:

• Orphan reachability (detect.sh:266-296) — now a proper hub-rooted BFS over markdown links + backtick mentions. Traced by hand against the new disconnected-cycle fixture (cycle-a.md/cycle-b.md referencing only each other): correctly reported as orphans since neither is reachable from SKILL.md, unlike the old any-inbound-mention test Codex flagged.
• TOC heuristic (detect.sh:150-156) — switched from grep -c (line count) to grep -o (occurrence count) scoped to the first 40 lines. Confirms Codex's two counter-examples are now both handled: a compact one-line TOC with 3 links now registers as toc=yes, and 3 scattered deep anchors now correctly register as toc=no.
• 10-file sample cap (SKILL.md:14, SKILL.md:79-81) — the pre-computed line is now labeled a sample and the routing rule explicitly says to re-derive the full uncommitted-file list in-session rather than trust the capped precompute.
• Numbered-list bug (SKILL.md:77-81) — items 3/4 are now on separate source lines; the Auto-detect list renders as the intended 5 distinct rules.

No other issues found in the delta introduced by this commit.

[claude]

Claude finished @kyle-sexton's task in 1m 33s —— View job

---

/review:code-review

• Gather context (PR body, prior review threads, CLAUDE.md/REVIEW.md)
• Invoke /review:code-review and apply its criteria to the diff since last-reviewed head
• Post inline findings
• Post final summary

Review scope

Skip-gate: this head (1999427) has new commits since the last applicable code-review pass (which ran against c6feff86 and flagged one open finding). Per REVIEW.md, security is out of scope for this lane (dedicated claude-security-review workflow exists). Scoped this pass to the delta c6feff8...1999427 (git diff c6feff8..1999427) — 3 files, +17/-2:

• plugins/docs-hygiene/skills/audit-progressive-disclosure/scripts/detect.sh
• plugins/docs-hygiene/skills/audit-progressive-disclosure/scripts/detect.test.sh
• docs/CATALOG.md

Findings

None. This commit (1999427) fixes the single remaining open finding from the prior review round.

Previously: detect.sh single-file-mode tier bug — in single-file mode, TROOTS was set to dirname(arg), so rel always collapsed to basename(f) regardless of nesting depth, making classify_tier always report tier=always for a directly-targeted CLAUDE.md, even a nested one like packages/api/CLAUDE.md.

Fix verified by hand-tracing the new logic:

• detect.sh:67-77 — file-arg TROOTS entry changed from dirname "$arg" to the literal .. At the classification call site (rel="${f#"$root"/}", line 211), stripping the literal ./ prefix is a no-op for both a bare CLAUDE.md and a nested packages/api/CLAUDE.md typed as-is, so rel now correctly preserves the as-typed nesting into classify_tier instead of always collapsing to the basename.
• Traced both cases: bare CLAUDE.md → rel == base → tier=always; packages/api/CLAUDE.md → rel != base → tier=invocation. Matches context/tier-model.md's stated semantics.
• The documented residual (absolute file-arg paths classify by full path since there's no cwd anchor to relativize against) is called out honestly in the added comment rather than silently mishandled, and is consistent with how the skill's Action Router passes relative paths (from git status --porcelain output or user-typed relative targets).
• detect.test.sh:109-115 — new regression cases exercise single-file mode directly (cd "$d" && bash "$SCRIPT" CLAUDE.md / ... packages/api/CLAUDE.md), which is exactly the invocation path the prior fix's test coverage was missing. Both assertions match the traced behavior.
• docs/CATALOG.md — mechanical regen adding the audit-progressive-disclosure entry to the docs-hygiene catalog row, consistent with the other skill descriptions in that list.

I could not execute detect.test.sh myself (no shell-execution access in this lane beyond gh/Read/Glob/Grep) — verification above is static trace-through of the script logic against the new test fixtures, not a claimed test run.

No other findings. All five issues raised across the prior review rounds on this PR (numbered-list formatting, nested-CLAUDE.md tier misclassification in directory mode, orphan-reachability BFS, TOC heuristic, and now this single-file-mode variant of the tier fix) are resolved as of this head.
· branch claude/progressive-disclosure-skill-b84q34

[claude]

Claude finished @kyle-sexton's task in 53s —— View job

---

/review:security-review

Task list

• Gather context (PR diff, custom instructions, prior review state)
• Run /review:security-review per custom instructions
• Post findings (or clean bill of health)

Scope reviewed: this lane already posted clean security reviews at heads 6c3d67e80d and c6feff86a3. Per the skip-gate, this pass is scoped to the commits added since the last reviewed head — 1999427fbcb58b611623985b148704ec3815c8e7 ("fix(docs-hygiene): carry tier nesting into single-file mode; regenerate catalog"), which brings HEAD current with this PR.

What changed in that delta (3 files, +17/-2):

• scripts/detect.sh — fixes the single-file-mode tier-classification bug flagged in the prior review round (nested CLAUDE.md audited directly always reported tier=always). The fix changes TROOTS+=("$(dirname "$arg")") to TROOTS+=(".") for file args, so rel at line 211 preserves the as-typed relative path instead of collapsing to basename. This is a pure string-prefix change on an already-validated local [[ -f "$arg" ]] path — no new external input source, no eval, no command construction from the value, no change to quoting. Traced the rel="${f#"$root"/}" substitution by hand for CLAUDE.md, packages/api/CLAUDE.md, ./CLAUDE.md, and an absolute path — all behave as the inline comment documents, with no injection or traversal exposure (it's a bash parameter-expansion prefix-strip against a hardcoded ., not a path re-resolution).
• scripts/detect.test.sh — new regression cases only (single-file-mode bare and nested CLAUDE.md). Test-only, no execution-surface change; runs entirely against mktemp fixtures.
• docs/CATALOG.md — prose-only catalog regeneration (adds the new skill's one-line description).

No .github/workflows/* files, permissions, secrets, or trust boundaries are touched by this delta (confirmed via git diff c6feff86..1999427 --name-only, and separately confirmed no .github/ changes at all). No eval, no new network calls, no credential handling, no allowed-tools grant changes.

No security issues found. The delta since the last reviewed head is a self-contained bug-fix (path-prefix logic) to a local, read-only shell fact-emitter, plus test-only and documentation-only changes — same posture as the prior clean reviews on this PR: no new injection surface, no trust-boundary changes, no CI/workflow changes.
· Branch: claude/progressive-disclosure-skill-b84q34

[claude]

Claude finished @kyle-sexton's task in 1m 43s —— View job

---

/review:code-review

• Gather context (PR body, prior review threads, HEAD SHA)
• Invoke /review:code-review and apply its criteria to the diff since last-reviewed head
• Post inline findings (if any)
• Post final summary

Review scope

Note: this PR merged into main as 465178c while this run was in flight, so origin/main already contains the full PR content under a different (squash) SHA. I scoped this pass to the delta the trigger asked for — commits since the last-reviewed head 1999427fbcb58b611623985b148704ec3815c8e7 up to the stated HEAD d1cb8268c950e41cb69df53168434fd2d80ecbeb — via git diff 1999427f..d1cb8268:

docs/SKILL-CHEAT-SHEET.md | 1 +
1 file changed, 1 insertion(+)

That's the entire delta: one commit (d1cb8268, "docs: regenerate the skill cheat sheet for audit-progressive-disclosure") adding a single generated row for the new skill.

Findings

None. Verified the addition against its sources:

• Row text ("Grade instruction files for split opportunities and hub/spoke disclosure defects") matches metadata.summary in SKILL.md verbatim.
• Row is inserted in correct alphabetical position (between audit-noise and compress), matching the sort order of every surrounding row.
• Link path and plugin-tag column (docs-hygiene) match the file's actual location and other rows in the same plugin group.
• This is a purely mechanical, generated-artifact fix (the commit message notes it was produced by scripts/generate-cheatsheet.mjs) — no logic, no hand-authored prose to scrutinize.

All five substantive findings raised across earlier review rounds on this PR (numbered-list formatting, nested-CLAUDE.md tier misclassification in both directory and single-file modes, orphan-reachability BFS, TOC heuristic) were already resolved as of 1999427f, per the prior review rounds on this thread. This final commit is docs-generation-only and introduces nothing new to flag.
· Branch: claude/progressive-disclosure-skill-b84q34