docs: apply repo-wide progressive-disclosure audit treatments

[kyle-sexton]

Summary

Applies every valid treatment from a repo-wide /docs-hygiene:audit-progressive-disclosure run over ~1,260 tracked markdown files (18 audit lanes, every Tier-1 finding re-verified by a fresh-context adversarial pass, every Tier-2 finding adjudicated under 2-of-3 consensus between two independent reviewer models and the orchestrating session).

Fix

• 47 confirmed Tier-1 findings: 20 deep-nesting fixes (direct conditioned hub pointers for required reference files that sat 2-3 hops away, in work-items, autonomy:setup, claude-ops:observability, claude-memory:audit) and 27 missing-toc fixes (Contents sections for every 300+ line file without one, including the 1,741-line audit-instructions criteria reference).
• 12 consensus-approved Tier-2 treatments: argument-gated sections extracted to spokes behind their router rows (planning:plan review-mode and close-out, planning:interview relentless-mode, guardrails:setup's two opt-in install procedures); babysit-prs flag documentation deduped into its declared single home, skills/babysit-prs/reference/safety.md, after a per-flag disposition check that first added the semantics safety.md was missing; suno claim-audit history merged into its drift ledger; discovery research/explore by-value detail moved into their dispatch spokes; autonomy sub-hub leaves given direct pointers and its bare pointers standardized to conditioned when-clauses; orphaned machine-health shared references pointed from the maintainer README; the topic-docs worked-slice example linked from its convention README.
• 17 Tier-2 findings rejected by consensus, unchanged on purpose: co-located test/CI docs, the CI-gated byte-identical artifact-protocol.md mirror, cycle-resident safety text in work-loop and disk-hygiene:clean, the boris quick reference, and the teach workspace-root ladder (security-load-bearing).

All moves are behavior-preserving relocations: no action or router row deleted, no guard sentence lost, moved text verified verbatim in its destination.

Verification

• markdownlint-cli2 (incl. MD051 link fragments): 0 issues across all 54 changed files; typos clean; editorconfig-checker clean.
• Detector re-run: every treated file now registers toc=yes; every previously deep-nested target is directly hub-reachable.
• Fresh-context adversarial diff review passed all five gates: content preservation (every sentence removed from a hub found in its spoke), link integrity (all 51 added link targets resolve), behavior preservation (guards and invariants intact), house style (no newly authored em dashes), lint.

Related

Closes #3385. Follow-ups recorded on that issue: extend detect.sh's pointer regex to register inline-code ${CLAUDE_PLUGIN_ROOT} paths, a plugin-README TOC convention decision, possible corpus exclusion for docs/topics, and reconciling the blanked AGENTS.md with its CLAUDE.md import.

🤖 Generated with Claude Code

https://claude.ai/code/session_013R8BNLHSBTrQXAiJU7RLYe

---

Generated by Claude Code

[claude]

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

---

Code review (/review:code-review)

• Gather context (PR description, changed files, diff via gh pr diff)
• Invoke /review:code-review skill and follow its instructions
• Verify all new cross-references / spoke files actually exist (autonomy templates, work-items reference leaves, machine-health shared refs, planning context files, guardrails install context files)
• Check moved-content sections for duplication with pre-existing destination content
• Post findings as inline comments
• Post summary review comment

This lane covers correctness/maintainability; security is scoped to claude-security-review (present in this repo), so I left that out.

Scope note: this PR is a large, mechanical docs-restructuring pass (TOCs + content relocation to spoke files). I did not re-verify every TOC anchor by hand (that's exactly what the PR's own markdownlint-cli2/MD051 run already covers, and re-deriving it here would just be restating a linter). Instead I focused on the two things a linter can't catch: whether every new pointer/link target actually exists, and whether "moved" content landed cleanly at its destination rather than duplicating what was already there.

Findings (2, both same pattern, inline on the changed lines):

1. plugins/discovery/skills/explore/reference/dispatch.md lines 128–130 — the two paragraphs moved in from SKILL.md restate facts the file already stated a few lines above/below (the filename-check/collision rule at lines 105–120, and the "failed dispatch, not a fallback" framing at lines 132–135). SKILL.md was correctly trimmed to a pointer, but the destination wasn't checked for pre-existing equivalent content, so the net effect is added redundancy rather than a single clean home.
2. plugins/discovery/skills/research/context/dispatch.md lines 210–212 — identical pattern: the moved paragraphs restate the filename-check step at lines 183–188 and the "failed dispatch, not a fallback" paragraph at lines 214–218.

Neither is linter-catchable (no broken links, no lint violations), but both work against this PR's own stated goal of consolidating duplicated docs into single homes, and both are the kind of thing that will quietly drift out of sync (two near-identical statements of the same rule, in the same file, that could diverge under a future edit to only one of them).

Verified clean (no action needed):

• Every new file reference / pointer added in this PR resolves to a real file: autonomy's templates/*.md and reference/guardrails/*.md/reference/runner/*.md leaves, work-items' reference/*.md leaves (tracker-seam.md, capability-tier-labels.md, label-taxonomy.md, issue-conventions.md, agent-brief.md, standing-item-preconditions.md, work-class-labels.md), machine-health's references/shared/{correlation-rules,testing}.md, claude-memory's ../stateless/context/status.md, topic-docs's examples/worked-slice.md, and all the new planning:plan/interview and guardrails:setup context spokes.
• The plan/context/review-mode.md relative link to plan-template.md was correctly re-pathed (dropped the context/ prefix) now that the file itself lives inside context/.
• The babysit-prs dedup into reference/safety.md (a pre-existing "single home" for that content) is clean — no leftover duplication, and SKILL.md's shortened bullets are consistent with what safety.md now says in full.

[claude]

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

---

Security review complete

• Gather context (PR docs: apply repo-wide progressive-disclosure audit treatments #3386, docs-only progressive-disclosure audit changes)
• Invoke /review:security-review per custom instructions
• Post findings (or clean bill)

Scope confirmed: all 54 changed files are Markdown (docs/, plugins/**/SKILL.md, plugins/**/reference|context/*.md, prompts/loops/*.md). No code, scripts, workflows, hooks, or config files are touched. I read the full PR diff (gh pr diff 3386, 1,798 lines) end to end rather than sampling.

What the diff actually does:

• Adds ## Contents (TOC) blocks to files ≥300 lines.
• Extracts argument-gated sections (e.g. guardrails:setup's install-commit-msg / install-pre-commit-content opt-in hook installers, planning:plan's review/close-out modes, babysit-prs safety flag docs) into spoke files behind pointer sentences in the hub SKILL.md.

Security-adjacent surfaces specifically diffed line-by-line, since this repo's docs are literal agent instructions:

• plugins/guardrails/skills/setup/context/install-commit-msg.md and install-pre-commit-content.md (new files describing git hook installation, secret-pattern scanning): byte-identical to the text they replaced in SKILL.md. Preflight refusals (managed-repo detection, no-overwrite, chain-or-refuse), the personal-.git/hooks/-only lane, and the "never suggests bypass" language are all preserved verbatim.
• plugins/source-control/skills/babysit-prs/SKILL.md + reference/safety.md: the merge/thread-resolution wrapper docs were reworded and deduped into safety.md, but every fail-closed guarantee (--allowed-owners required, --allow-unpinned-head rejected outright, --admin never used, override flags "never passed autonomously", dependency-manager and unprotected-base refusals) is still stated, just in one place instead of two.
• plugins/discovery/skills/explore/reference/dispatch.md and research/context/dispatch.md: the path-traversal guard on agent-written filenames (only bare EXPLORE.md/EXPLORE-<section>.md or RESEARCH*.md; any /, .., or leading slash is a failed dispatch, not sanitized) moved from SKILL.md into the reference file unchanged.

No secrets, credentials, tokens, or executable content were added. No curl|bash-style patterns, no new external URLs outside github.com/code.claude.com/claude.ai/vendor doc sites already in the repo, no guard logic was weakened, removed, or made bypassable in transit. This matches the PR description's claim of "behavior-preserving relocations" — verified independently against the actual diff rather than taken on faith.

No security findings.
· Branch

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3ea4106a73

ℹ️ 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]

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

[claude]

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

---

Security review

• Gather context (PR description, changed files, diff)
• Invoke /review:security-review and follow its instructions
• Post findings
• Post summary review comment

Scope confirmed: all 80 changed files are documentation (*.md, CHANGELOG.md, .claude-plugin/plugin.json version bumps) implementing the progressive-disclosure moves described in the PR body. No source code, no .github/workflows/**, no dependency manifests, no file-mode changes.

What I checked:

• Full PR diff (gh pr diff 3386) scanned for secrets, credentials, and unsafe-command patterns (curl|wget|eval|token|ssh|chmod|sudo|rm -rf|--no-verify|http://) in added lines — no live secrets or unsafe instructions found; the only hits are documentation describing the guardrails plugin's own secret-detection/hook-bypass guards.
• No workflow files touched, so no Actions permissions/trigger surface changed.
• New git-hook install docs (plugins/guardrails/skills/setup/context/install-commit-msg.md, install-pre-commit-content.md, split out of guardrails/skills/setup/SKILL.md): both preserve the fail-closed preflight (managed-repo detection, refuse-don't-overwrite on an existing hook, chain-or-refuse choice), the personal-lane-only scope (no core.hooksPath scaffolding), and the --no-verify/block-no-verify interaction notes from the pre-move version.
• babysit-prs dedup (SKILL.md → reference/safety.md): diffed old vs. new text directly. Every safety-relevant detail that moved — fail-closed --allowed-owners, expected-head pin and its refusal of --allow-unpinned-head, no --admin/no force-push/no reply, dependency-manager and unprotected-base holds, --independent-resolver evidence gating, JSON action/exit-code parsing — is present verbatim in the new location. Nothing was dropped or weakened in the move.
• Suno drift-ledger merge, discovery/planning/autonomy spoke extractions, and work-items doc updates: all pure text relocation behind existing router rows, no logic or command changes.

Result: no security findings. This is a behavior-preserving documentation reorganization; the safety-critical guard text (guardrails hook installers, babysit-prs merge/resolve gates) was moved intact, not altered.

[github-actions]

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

[claude]

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

---

Code review (/review:code-review)

• Load /review:code-review lane instructions
• Gather PR context (diff, changed files, CLAUDE.md)
• Check skip gate (PR open, non-draft, meaningful surface — proceeded)
• Review changed files for correctness/maintainability
• Post findings

No blocking findings.

Reviewed the full diff (all 80 changed files) against the CODE-REVIEW lane's correctness/maintainability bar. This is a large but low-risk mechanical restructuring (TOC insertions, hub→spoke pointer extractions, and a few dedup merges). I specifically checked the higher-risk spots — the places where prose was moved or merged rather than purely added:

• guardrails/skills/setup/SKILL.md → context/install-commit-msg.md / install-pre-commit-content.md: verbatim extraction confirmed, target files exist.
• planning/skills/plan/SKILL.md → context/review-mode.md / close-out.md, and planning/skills/interview/SKILL.md → context/relentless-mode.md: verbatim, and the [plan template](plan-template.md) relative link in the relocated review-mode.md was re-pointed correctly for its new directory (verified plan-template.md lives alongside it in context/).
• source-control/skills/babysit-prs/SKILL.md + reference/safety.md: this one is a reworded merge (not verbatim), consolidating flag semantics into safety.md. Spot-checked the moved details (self-logins, dependency-manager overrides, thread-resolution pins, action vocabulary) against the original SKILL.md text and didn't find dropped semantics.
• songwriting/skills/suno/SKILL.md → reference/suno-drift-audit-ledger.md: the removed "Re-verified 2026-07-18…" character-limit bullet reappears as ledger row S20; content preserved.
• All new/changed relative links and ${CLAUDE_PLUGIN_ROOT}-relative references I checked resolve to real files (autonomy templates/guardrails/runner leaves, work-items reference/*, claude-memory stateless/context/status.md, machine-health shared references).
• Spot-checked GitHub anchor slugification on the larger hand-authored TOCs (criteria.md's 17 checks, rerun-contract.md's backtick/em-dash headings) — anchors match actual heading slugs.

Nothing here rises to a block-worthy correctness or maintainability issue. The runner-policy/policy.json and .markdownlint-cli2.jsonc deltas that show up in a plain origin/main..HEAD diff are pre-existing upstream drift (this branch is behind main on those two files), not part of this PR's changeset per the file list — not flagged.

[claude]

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

---

Security review

• Gather context (PR description, changed files, diff)
• Invoke /review:security-review and follow its instructions
• Post findings
• Post summary review comment

Skip gate hit: this head (e7e4073) already has a successful, complete security review posted on this PR — the 22:13:29 run, which scanned all 80 changed files (matching the current PR's changed-file count exactly) and concluded no security findings. Per /review:security-review's skip gate ("this head already has a successful security review that still applies"), I'm not re-running a duplicate full review.

Summary of that prior finding, for reference: all 80 changed files are documentation (*.md, CHANGELOG.md, .claude-plugin/plugin.json version bumps). Security-adjacent surfaces (guardrails hook installers in plugins/guardrails/skills/setup/context/, the babysit-prs safety-flag dedup into reference/safety.md, the discovery dispatch path-traversal guards) were diffed line-by-line and confirmed behavior-preserving — no fail-closed guard was weakened, removed, or made bypassable. No secrets, unsafe commands, or workflow/permission changes in the diff.

If you'd like a fresh full re-review anyway (e.g. because you don't trust the prior pass), delete the "Last security-reviewed head" gate comment on this PR and re-trigger, or just ask me directly and I'll bypass the skip gate.

[claude]

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

---

Code review (/review:code-review)

• Gather context (PR description, changed files, diff)
• Invoke /review:code-review skill and follow its instructions
• Cross-check standing findings from prior review passes against current HEAD
• Post summary review comment

Scope: re-ran the code-review lane at HEAD e7e4073 (the latest commit, docs(source-control): restore contract-pinned merge-gate phrases in babysit-prs, only touches plugins/source-control/skills/babysit-prs/SKILL.md). Security is scoped out — claude-security-review already covers this PR and returned clean.

Verified: the latest commit's fix is correct. babysit-prs/SKILL.md's "Merge readiness" bullet still states the exact pinned invocation (--merge --expected-head <vetted-head-sha>) and the missing/stale-pin refusal wording inline, while keeping the rest of the flag detail deduped to reference/safety.md — this is the right fix for what the commit message describes (skill-contract tests pinning that exact phrasing).

Standing findings from prior review passes on this PR, re-checked against current HEAD and still open (not re-posting as duplicate inline comments since they're already anchored on the PR; noting status here per this lane's own review):

1. Duplicate content, not new since the last pass — plugins/discovery/skills/explore/reference/dispatch.md#L128-L130 and the sibling plugins/discovery/skills/research/context/dispatch.md#L210-L212 still restate rules the same file already states a few lines away (filename-check step, "failed dispatch, not a fallback" paragraph). Confirmed unresolved at this HEAD.
2. Codex's two P2 findings are valid and unresolved: plugins/claude-config/skills/audit-instructions/reference/criteria.md#L10 and plugins/source-control/skills/setup/reference/apply-convention.md#L16. Both new grep lookup recipes are written as bare relative paths (reference/criteria.md, apply-convention.md), which only resolve when the agent's cwd happens to already be the skill's own directory — not the consuming repo root, which is where these skills normally run. I independently verified the grep patterns themselves are correct (they do match the real headings once cwd is right); the bug is purely the implied cwd, matching Codex's read. Fix: anchor both at ${CLAUDE_PLUGIN_ROOT}/skills/<skill>/reference/<file>.md.

New in this pass: none. I read the full diff (all 80 files) independently and didn't find additional correctness/maintainability issues beyond the three items above — the rest of the PR (TOC additions, the babysit-prs dedup, the guardrails install-*.md extraction, the planning/autonomy/work-items pointer additions) is mechanical, verbatim-preserving, and checks out against its own stated destinations.
· Branch

[claude]

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

---

Code review (/review:code-review)

• Gather context (PR description, diff, changed files)
• Invoke /review:code-review skill and follow its instructions exactly
• Verify the four previously-flagged findings against current HEAD
• Review remainder of diff for new issues
• Post summary review comment

Scope: re-ran the code-review lane at HEAD 825c51a (merge of origin/main's a4915d4 into this branch — nets to the same 81-file diff against origin/main as before; no new content beyond the prior merge base). The only substantive commit since the last full pass (e7e4073) is 11d9a47, "docs(disclosure-audit): address review findings and repin interview digest," which touches exactly 5 files. Security stays scoped to claude-security-review, already clean on this PR.

All four previously-open findings are fixed, verified against the current diff:

1. plugins/claude-config/skills/audit-instructions/reference/criteria.md#L11 — Codex's cwd-relative-path finding. Now reads "${CLAUDE_PLUGIN_ROOT}/skills/audit-instructions/reference/criteria.md", resolves independent of the caller's cwd. Fixed correctly.
2. plugins/source-control/skills/setup/reference/apply-convention.md#L16 — same pattern, same fix: "${CLAUDE_PLUGIN_ROOT}/skills/setup/reference/apply-convention.md". Fixed correctly.
3. plugins/discovery/skills/explore/reference/dispatch.md#L128-132 — the duplicate filename-check/failed-dispatch paragraph pair is removed; the file now states each rule once and the topic-docs.md pointer was folded into the surviving paragraph rather than restated. Read the surrounding section (lines 90–139) to confirm — clean, no orphaned reference to the removed text.
4. plugins/discovery/skills/research/context/dispatch.md#L210-215 — same fix as its sibling, same verification (lines 175–224 read cleanly, no duplication, no dangling reference).

New in this pass: none. I read the rest of the diff at this HEAD — the ## Contents TOC insertions across docs/topics/** and plugin READMEs/reference files are purely additive and mechanical (headings match anchors), and the non-TOC content in plugins/work-items/** (the new ${CLAUDE_PLUGIN_ROOT}/reference/*.md pointers in track, triage, work, setup) was already spot-checked and confirmed to resolve to real files in an earlier pass on this PR and is unchanged since. Nothing rises to a blocking correctness or maintainability issue.

No inline comments posted — no open or new findings to anchor.
· Branch

[claude]

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

---

Security review

• Gather context (PR description, changed files, diff at HEAD 825c51a)
• Invoke /review:security-review and follow its instructions
• Post findings
• Post summary review comment

Skip gate hit: the last full security review on this PR ran at head e7e4073 (all 80 files, no findings). The only commit since then on this branch is 11d9a47, "address review findings and repin interview digest" (the merge commit 825c51a and a4915d4 just bring in unrelated origin/main history, e.g. #3388, already covered by main's own review). I read that commit's full diff directly rather than relying on the prior review:

• plugins/claude-config/skills/audit-instructions/reference/criteria.md#L10 and plugins/source-control/skills/setup/reference/apply-convention.md#L16: the grep lookup recipes are now anchored at ${CLAUDE_PLUGIN_ROOT}/skills/.../reference/*.md instead of a bare relative path — a correctness fix (addresses the two Codex P2 findings), no security surface either way.
• plugins/discovery/skills/explore/reference/dispatch.md and research/context/dispatch.md: drops the duplicated paragraph pair flagged in the earlier code-review pass. Diffed old vs. new text directly — the fail-closed filename gate (bare EXPLORE.md/EXPLORE-<section>.md or RESEARCH*.md only; any /, .., or leading slash is a failed dispatch, never sanitized) and the "by-value payload is a failed dispatch, not a fallback" rule are both still stated in full in the retained paragraph — nothing guard-related was thinned out along with the duplication.
• plugins/planning/tests/interview-defenses.test.sh: only a SHA-256 test-fixture digest updated to match a reworded (not weakened) doc section. No logic change.

All five changed lines are docs/test-fixture edits with no security-relevant surface. Per the skip gate ("this head already has a successful security review that still applies"), no further findings to report.

No security findings (unchanged from the prior full review at e7e4073).
· Branch