docs(audit): 2026-06-10 repository architecture & best-practices audit

[ndycode]

Summary

The anchor deliverable of the repo-wide audit: a dated snapshot artifact at docs/audits/AUDIT_2026-06-10.md, following the docs/audits/README.md convention (new dated artifact, evidence preserved, marked as historical snapshot).

It covers six dimensions — architecture/modularity, security, correctness/concurrency, testing/CI, packaging/dependencies, docs/DX — with every accepted finding re-verified by hand against source (file:line evidence) before inclusion.

Contents

• Verified findings: 4 HIGH, 13 MEDIUM, 5 LOW — each with evidence and status
• Companion fix PR index: fix(security): use crypto randomness for temp-file staging paths and recovery ids #517 (temp-path entropy), chore(packaging): align engines, drop typescript peer dep, remove dead .npmignore #518 (packaging hygiene), ci: pin all workflow actions to commit SHAs #519 (CI action pinning), docs: fix stale command names, version drift, and duplicate doc-portal rows #520 (docs corrections), chore(hooks): run typecheck in pre-commit, drop deprecated husky bootstrap #521 (pre-commit typecheck) — all independent and individually revertable
• Refactor roadmap with concrete seams and blast-radius estimates for the work intentionally not executed as quick fixes: finishing the codex-manager.ts extraction (3,810 lines), splitting fetch-helpers.ts (1,497) and runtime-rotation-proxy.ts (2,497), consolidating the ~18 divergent retry loops, adopting the CodexError hierarchy end-to-end, consolidating ci.yml/pr-ci.yml, CLI test mock factories + snapshot tests, source-map trimming (~1 MB tarball), generating config.schema.json from the zod schema, lazy postinstall
• Strengths section documenting what must be preserved (atomic persistence discipline, OAuth hygiene, sandboxed test infra, docs governance)
• Rejected-findings section: six plausible-sounding automated claims (refresh-lease TOCTOU, floating prune promise, quota-cache EXDEV, refresh-queue timeout leak, shutdown handler race, OAuth-callback rate limiting) that were disproven by hand — recorded so future audits don't re-litigate them

Testing

• test/documentation.test.ts (25 doc-integrity assertions) passes with the new artifact in place ✅

https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB

---

Generated by Claude Code

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

pure docs pr adding a dated audit snapshot (docs/audits/AUDIT_2026-06-10.md) and its machine-captured evidence file. the document is well-structured: 22 verified findings with file:line evidence, a §6 rejected-findings log to prevent future re-litigation, a companion pr index (#517–#521), and a §5.1 delivery log that records all roadmap items subsequently executed in the same cycle.

• audit document covers 4 HIGH / 13 MEDIUM / 5 LOW findings across six dimensions; all HIGH and most MEDIUM items are marked fixed in their companion prs
• evidence file (test-baseline-2026-06-10.txt) captures 58 environment-only test failures (windows paths, IPv6, sandbox EACCES) on the audit-snapshot HEAD, correctly linked from §7
• M9 status inconsistency — the finding table still reads "Open" for @types/node ^25 but §5.1 records pr chore(deps): pin @types/node to the supported runtime floor major #528 as having resolved it; the status cell should be updated to avoid misleading future readers

Confidence Score: 5/5

docs-only change adding a static audit snapshot and evidence file — no executable code, no schema changes, no token or filesystem paths affected

both files are documentation artifacts with no runtime impact; the only real gap is a stale "Open" status on M9 in the findings table, which a one-word fix can address, and the previous thread concerns are already incorporated into the document

docs/audits/AUDIT_2026-06-10.md line 58 — M9 status cell reads "Open" but §5.1 records it as resolved

Important Files Changed

Filename	Overview
docs/audits/AUDIT_2026-06-10.md	dated audit snapshot — well-structured with 4 HIGH / 13 MEDIUM / 5 LOW findings, companion PR index, rejected-findings log, and a §5.1 delivery log; M9 status in §2 says "Open" but §5.1 records it as resolved by PR #528
docs/audits/evidence/test-baseline-2026-06-10.txt	machine-captured evidence file listing 58 environment-only test failures (windows paths, IPv6, sandbox EACCES) against HEAD 98d9819; correctly linked from §7 of the audit doc

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["AUDIT_2026-06-10.md\n(historical snapshot)"] --> B["§2 Verified Findings\n4 HIGH · 13 MEDIUM · 5 LOW"]
    A --> C["§3 Strengths\natomic persistence, OAuth hygiene,\ntest isolation, docs governance"]
    A --> D["§4 Refactor Roadmap\n(deferred, sized with blast-radius)"]
    A --> E["§5 Companion PRs\n#517–#521"]
    A --> F["§5.1 Delivery Log\n~20 roadmap items executed same cycle"]
    A --> G["§6 Rejected Findings\n6 disproven automated claims"]
    A --> H["§7 Snapshot Evidence\nevidence/test-baseline-2026-06-10.txt"]
    B --> B1["HIGH: H1-H4 → Fixed"]
    B --> B2["MEDIUM: M1-M6 → Fixed\nM7-M13 → Roadmap"]
    B --> B3["LOW: L1-L5 → Roadmap"]
    D --> F
    E --> F

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
docs/audits/AUDIT_2026-06-10.md:58
M9's status column still reads "Open — needs a maintainer decision now," but §5.1 of this same document records that PR #528 pinned `@types/node ^20` and explicitly marks it as resolving M9. a future reader scanning only §2 will believe this is still an outstanding item when it's already shipped.

```suggestion
| M9 | `@types/node ^25` against `engines >=18.17` — a **present** type-safety gap, not just polish: new code calling a Node 20+-only API (e.g. `fs.glob`) typechecks cleanly today but fails at runtime for Node 18.17 consumers | `package.json:159` | Fixed in PR #528 (pinned `^20`; see §5.1) |
```

_{Reviews (7): Last reviewed commit: "docs(audit): record #549/#550 and the #5..." | Re-trigger Greptile}

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[coderabbitai]

Warning

Review limit reached

@ndycode, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 17 minutes and 48 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: ae299f14-a1ec-4ca2-92d7-d11bb4a0f7e0

📥 Commits

Reviewing files that changed from the base of the PR and between 98d9819 and 22f8109.

📒 Files selected for processing (2)

• docs/audits/AUDIT_2026-06-10.md
• docs/audits/evidence/test-baseline-2026-06-10.txt

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/repo-architecture-audit-kk3xa8

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/repo-architecture-audit-kk3xa8

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}