Skip to content

docs: add repository cleanup audit (issues, docs inventory, deferred work) - #101

Merged
tyler-rich merged 1 commit into
devfrom
claude/repo-audit-docs-inventory-98ir14
Jul 26, 2026
Merged

docs: add repository cleanup audit (issues, docs inventory, deferred work)#101
tyler-rich merged 1 commit into
devfrom
claude/repo-audit-docs-inventory-98ir14

Conversation

@tyler-rich

@tyler-rich tyler-rich commented Jul 26, 2026

Copy link
Copy Markdown
Owner

Summary

Adds docs/reviews/CLEANUP-AUDIT.md, a read-only audit of the repository's open issues, the full docs/ tree, deferred work buried in docs/ARCHIVE.md §14, and general hygiene. This PR adds one file and changes nothing else — no issue was closed, no document amended, no file deleted or moved. Every proposal is written to be approved or rejected line by line.

What changed

One new file: docs/reviews/CLEANUP-AUDIT.md.

The audit is organized in four parts, led by a "recommended actions, highest value first" table.

Part 1 — Open issues. True status of all five open issues, determined against the code on dev at 96264fb and cited at file:line, not against issue state. The default branch is main while PRs target dev, so GitHub's closing keywords never fire and open-ness carries no information:

Part 2 — docs/ inventory. Every file and folder under docs/ recursively (18 files, ~430 KB) with size, last meaningful update from git history, purpose, and a KEEP / ARCHIVE / DELETE disposition. Confirms STATUS.md §1 is empty and argues it is now a historical artifact except for two operational follow-ups that should move to ROADMAP.md. Proposes deleting docs/upgrades/python-3.14.md and the folder, and flags every other document still carrying the superseded CVE-2025-15366 claim — including CHANGELOG.md lines 18-23, which is user-facing release-note text. Each proposed DELETE or ARCHIVE lists its full inbound-reference blast radius from a repo-wide grep, including code comments in .github/dependabot.yml. Ends with a proposed docs/ structure and a disposition for the audit file itself.

Part 3 — Deferred work in §14. Consolidated list of everything still outstanding, each with its source entry date, separating items with a live tracking reference from the three recorded in prose only (repo Settings work from 2026-07-06 and 2026-07-09 that never reached the ROADMAP governance checklist). Cross-checked against ROADMAP.md and the open issues so nothing is double-counted; ten previously-deferred items verified as since closed.

Part 4 — Other cleanup. ARCHIVE.md navigability, including a structural defect: fourteen dated deviation entries covering 2026-07-09 through 2026-07-26 sit underneath the ## Build performance heading rather than §14, plus one dead in-file link at ARCHIVE.md:1004. Four ROADMAP.md items now done, one of which states something false about the secret-store AAD binding. The four accumulated Unreleased changelog entries and why a v0.2.0 promotion is warranted, including the operational cost of main being 30 commits behind. 33 merged remote branches verified safe to prune, with the six PR-less review branches verified by content diff. Four aging Dependabot PRs. Proposed wording for two unrecorded CLAUDE.md operational rules (stacked-PR retargeting needs git rebase --onto; on: pull_request default types exclude edited, so a base change never re-runs CI).

The appendix states the verification method and explicitly lists what was not verified: the specific CVE list behind #75, and all GitHub repository settings.

Notes

  • Docs only — no application code, CI, configuration, schema, security-model, job-model, or auth change.
  • No docs/ARCHIVE.md § Deviations entry: this PR only adds an audit document and implements none of its recommendations. The deviation entry belongs with whichever proposals are accepted and acted on.
  • Not for merge until the proposals have been reviewed.

…work)

Read-only audit producing findings and proposals only; no code, config, or
existing document is changed.

- Part 1: true status of all five open issues against the code on dev — #63
  and #83 are fully resolved (#89, #87) and only open because closing keywords
  never fire on a dev-targeted PR; #98 and #52 are live waiver trackers; #75
  needs a release.
- Part 2: full recursive docs/ inventory with a KEEP/ARCHIVE/DELETE
  disposition per file, the inbound-reference blast radius for each proposed
  removal, and a proposed docs/history/ structure.
- Part 3: consolidated list of deferred work still outstanding in ARCHIVE.md
  section 14, separating items with a live tracking reference from the three
  recorded in prose only.
- Part 4: ARCHIVE.md navigability (including 14 deviation entries misfiled
  under the Build performance heading), ROADMAP items now done, the
  Unreleased changelog backlog, 33 prunable merged branches, and proposed
  CLAUDE.md wording for two operational lessons.
@tyler-rich
tyler-rich merged commit 4813b64 into dev Jul 26, 2026
4 checks passed
@tyler-rich
tyler-rich deleted the claude/repo-audit-docs-inventory-98ir14 branch July 31, 2026 04:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant