feat(docs-hygiene): repo-wide audit-noise sweep and clean-tree fallback - #2696
feat(docs-hygiene): repo-wide audit-noise sweep and clean-tree fallback#2696kyle-sexton wants to merge 2 commits into
Conversation
Round 1 asked (Q1-Q6): deliverable shape, corpus scope, report destination, orchestration parameters, skill fallback update scope, rate-limit telemetry issue. Awaiting answers before the orchestrated sweep runs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H9A7ewGsRVk4KWVUhUcgpq
|
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. |
kyle-sexton
changed the title
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0325c97371
ℹ️ 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".
| @@ -0,0 +1,35 @@ | |||
| # /planning:interview Checklist — docs-hygiene-audit-noise | |||
There was a problem hiding this comment.
This checklist is explicitly classified as checkout-local memory that belongs under .work/<topic-slug>/ and must never be committed (plugins/planning/reference/topic-docs.md:22 and docs/conventions/topic-docs/README.md:41). Merging this file would distribute an unfinished Q&A ledger to every clone instead of keeping the pending session state local; remove it from the tracked diff and retain it only in the self-ignored memory slice.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Confirmed against docs/conventions/topic-docs/README.md (tier table) and plugins/planning/reference/topic-docs.md — the ledger is memory-tier and must never be committed. Fixed in f0b8d07: untracked the file and added the .work/.gitignore self-ignore (*), which the first memory-tier write should have created. This PR is being closed as premature; the branch will return with real content.
Generated by Claude Code
The memory tier (.work/<slug>/) is never committed and self-ignoring (docs/conventions/topic-docs/README.md tier table); the ledger commit violated that. The slice now carries its self-ignore and stays local. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H9A7ewGsRVk4KWVUhUcgpq
|
Claude encountered an error after 0s —— View job I'll analyze this and get back to you. |
|
Warning Automated review did not complete — this is an infrastructure failure, not a review verdict. Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."
Re-run the job, or workflow_dispatch this workflow with the PR number, to retry the review. A new push re-triggers this lane only if the caller's |
…back, paragraph-scope markers (#2721) No linked issue ## What this is The apply phase of the first repo-wide `/docs-hygiene:audit-noise` run (2026-08-15): 1,027 tracked markdown files scanned with the skill's own `detect.sh`, 55 scanner candidates judged by two concurrent Opus workers, all actionable verdicts adversarially verified by a fresh-context verifier (54 checked, 50 upheld, 4 overturned — overturns applied). Net: 2 Tier 1 + 30 Tier 2 findings, 24 scanner false positives dismissed, all 33 flagged files passing the existence pre-check. ## Commits - **`docs:` treatments (31 of 32 actionable findings):** ghost-refs get carrying-PR permalinks (#796, #794, #1459, #1185, #330, #1400), checkout-local caveats, or strips; citations relocate to `## Sources`/`## History` footers; retired-path mentions that ARE the stated rule/history get opt-out markers; a Reference-quadrant preamble collapses; hardcoded rosters reopen. Deliberately not edited: `line-brainstorm-prompt.md:182` (roster inside an output-template code fence — accepted as a reviewed hardcode; this PR is the recorded review). - **`feat(docs-hygiene): 0.12.0`:** audit-noise's clean-tree default becomes a confirmation-gated repo-wide offer (blocked when unattended) instead of a silent no-op; `detect.sh`'s opt-out markers now honor the documented paragraph scope (`-line` distinguished; heading also closes scope); Tier 3 explicitly carries no treatment; recurring judgment dismissal grounds codified; carrying/pruning PR numbers sanctioned as durable ghost-ref pointers; `CHANGELOG.md` skipped by basename per the long-documented exemption. Tests 38/38; shellcheck/shfmt/markdownlint/changelog-parity clean. - **`chore:` version bumps** required by the changelog-parity gate for touched plugin trees (session-flow 0.23.5, songwriting 1.4.4) and the regenerated `docs/CATALOG.md`. - **`fix:` fresh-context verification minors** — diff verification returned CLEAN (all six PR-citation claims verified against git history); 6 of its 9 minor observations fixed, 3 recorded as accepted in the PR comments. ## Dispositions — nothing left dangling Completed in this PR: Tier-3 treatment semantics, `-line` marker docs, PR-number pointers, codified dismissal grounds, CHANGELOG basename skip, marker paragraph scope, clean-tree fallback. Filed as issues (from the run + the follow-up `/plugin-quality:audit` of the components this session exercised): - #2730 — `.work/running-retros/` concern-root codification (convention-ownership decision) - #2734 — sibling audit skills adopt the clean-tree fallback - #2739 — cloud-bootstrap installs npm-global tools into an nvm prefix invisible to plugin hooks (markdown lint gate silently lost in cloud sessions; found via this session's hook false-negative) - #2740 — markdown-format notice wording ("skipped for this session" misstates the latch) + probed-PATH diagnostic - #2741 — `detect.sh` per-line subshell forking (~700× grep; root cause of this run's scan timeout) + chunking affordance for the new fallback - #2742 — scanner exemption gaps (frontmatter unimplemented, marker-substring self-trigger, no code-fence awareness, section-state leaks) ## Verification state Fresh-context diff verification: CLEAN. Automated security review: clean at every pushed head. Automated code review: no findings. Local gates green (38/38 script tests, shellcheck/shfmt, markdownlint, changelog parity, plugin validation + catalog). ## Related - Predecessor PR #2696 (closed as premature; carried only the since-reverted ledger commit) - Follow-up issues: #2730, #2734, #2739, #2740, #2741, #2742 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01H9A7ewGsRVk4KWVUhUcgpq --------- Co-authored-by: Claude <noreply@anthropic.com>
2 participants
No linked issue
Summary
Orchestrated repo-wide
/docs-hygiene:audit-noiserun (inventory → chunked scan → sub-agent judgment passes → fresh-context verification → report), plus a skill update givingaudit-noisea confirmation-gated whole-repo fallback when invoked with no target on a clean tree (today's behavior: silent no-op).Work in progress — an interview round (Q1–Q6 in
.work/docs-hygiene-audit-noise/interview-checklist.md) is pending user answers on deliverable shape, corpus scope, report destination, orchestration parameters, and skill-update scope. Audit deliverables land here as they complete.Fix
So far: opened the topic's interview ledger in the
.work/memory slice per the repo's topic-docs convention. The orchestrated sweep and skill edit follow once the round resolves.Verification
detect.sh --paths-fileover the 1027-file corpus (tracked.mdminusevals/fixtures/and changelogs) confirmed the serial pass exceeds 5 minutes — the run will be chunked/parallelized.Related
N/A (a rate-limit-telemetry enhancement issue may be filed and linked per interview Q6)
Generated by Claude Code