docs: Hygiene sweep — architecture correctness, cross-doc drift, comment cleanup

[vlad-ko]

Summary

Docs-and-comments-only sweep clearing the pre-existing drift catalogued during the epic work, plus a comment-cleanup policy pass. No behavior changes — every .ts diff is comment blocks only, verified by audit and a green suite.

• architecture.md correctness: the 👎 flow now describes flag-then-supersede (post-KB entry lifecycle: supersession + stale-context framing #124) instead of removal; mention-handler steps reflect chunk-0 reuse instead of delete-and-repost; the follow-up handler mentions the fail-closed classifier gate; all three entry points listed with a new code-index section; vector namespaces + lexical degradation documented; the stale inline structure tree replaced with a pointer to CLAUDE.md's canonical one.
• Cross-doc drift: source-hierarchy and progress-ux aligned with supersession and edit-in-place reality (progress-ux's "Why Delete?" section is now "Why Edit?"; also removed a documented-but-never-emitted "composing" status); usage/setup wording aligned; README's Feature Deep-Dives table now covers all 13 feature docs (5 rows were missing) and its env table gained the Redis/CRON_SECRET/Sentry rows; CLAUDE.md gained 9 unlisted lib files + 3 missing doc entries; contributing.md's ancient "148 tests" claim now reads 945/47 with a pointer instead of a second structure tree.
• Naming: "Vercel KV" → "Upstash Redis (Vercel Marketplace)" across docs, including corrected dashboard navigation. Deliberately NOT changed: the runtime prompt strings in claude.ts/save-knowledge.ts that still say "Vercel KV" — those are model-facing literals whose edit would invalidate the behavior-eval cassettes; they'll batch with the next cassette re-record, and the two doc passages quoting them verbatim stay verbatim until then.
• Comment cleanup: several code comments and doc passages referenced an external reference implementation by name; all rewritten to describe the design decisions generically (6 sites: compaction.ts, sentry.server.config.ts, reply-footer.ts, slack-users.ts, architecture.md, observability.md).

Verification

Suite green after the comment edits (945/47), full-repo grep confirms zero remaining references, .ts diffs audited as comment-only.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
battle-mage	Ready	Preview, Comment	Jul 9, 2026 2:59pm

[coderabbitai]

Warning

Review limit reached

@vlad-ko, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 18 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

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.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: bd8ac2b8-c629-424c-b1f2-4405874b3384

📥 Commits

Reviewing files that changed from the base of the PR and between 1ff4751 and d153734.

📒 Files selected for processing (14)

• CLAUDE.md
• README.md
• docs/architecture.md
• docs/contributing.md
• docs/features/knowledge-base.md
• docs/features/progress-ux.md
• docs/features/source-hierarchy.md
• docs/observability.md
• docs/setup.md
• docs/usage.md
• sentry.server.config.ts
• src/lib/compaction.ts
• src/lib/reply-footer.ts
• src/lib/slack-users.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/hygiene-sweep

---

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.}

[qodo-code-review]

PR Summary by Qodo

Docs hygiene sweep: fix lifecycle drift, Upstash Redis naming, comment cleanup

📝 Documentation 🕐 20-40 Minutes

AI Description

• Align docs with supersession-based KB lifecycle and edit-in-place progress UX.
• Standardize “Upstash Redis (Vercel Marketplace)” naming and update env/setup tables.
• Rewrite code/doc comments to remove named external reference implementation mentions.

Diagram

graph TD
  Slack{{"Slack"}} --> SlackRoute["/api/slack"] --> TurnRunner(["Turn runner"]) --> Agent(["Claude agent"]) --> Redis[("Upstash Redis")]
  Agent --> Vector[("Upstash Vector")]
  Cron{{"Vercel Cron"}} --> Sweep["/api/cron/sweep"] --> Recovery(["Recovery sweep"]) --> Redis
  Cron --> CodeIndex["/api/cron/code-index"] --> Indexer(["Code indexer"]) --> Vector

  subgraph Legend
    direction LR
    _ext{{"External"}} ~~~ _api["HTTP route"] ~~~ _svc(["Service"]) ~~~ _db[("Data store")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Automate doc drift checks (link/table/env validation in CI)

• ➕ Prevents future cross-doc drift (feature tables, env var lists, entry-point lists)
• ➕ Reduces manual hygiene sweeps and reviewer cognitive load
• ➖ Requires tooling investment (md parsing, canonical sources, CI wiring)
• ➖ Some docs are narrative and hard to validate mechanically

2. Generate canonical sections from code/config sources

• ➕ Single source of truth for env vars, routes, and file trees
• ➕ Avoids repeated structure listings across docs
• ➖ Generated content can be harder to edit/read in PRs
• ➖ Still needs narrative docs around the generated data

Recommendation: The PR’s approach (manual correctness sweep + consolidating the file tree to a single canonical location) is the right immediate fix given existing drift. A good follow-up is to add lightweight CI checks for doc tables/env-var lists and/or generate the most drift-prone sections (env vars, entry points) from canonical sources to prevent recurrence.

Files changed (14) +90 / -121

Documentation (14) +90 / -121

CLAUDE.mdUpdate canonical project tree, storage naming, and env var docs +22/-7

Update canonical project tree, storage naming, and env var docs

• Standardizes knowledge storage naming to Upstash Redis (Vercel Marketplace) and updates the progress UX description to edit-in-place. Expands the canonical project structure list and adds missing docs entries, plus clarifies cron auth scope and optional Sentry DSN override.

CLAUDE.md

README.mdAlign README feature table, env vars, and progress lifecycle +12/-3

Align README feature table, env vars, and progress lifecycle

• Updates KB naming to Upstash Redis, fills in missing Feature Deep-Dive rows, and expands the environment variable table (Redis, CRON_SECRET, Sentry). Corrects the “How it works” flow to reflect progress message reuse rather than deletion.

README.md

architecture.mdCorrect lifecycle narratives: chunk-0 reuse, supersession, and cron entry points +21/-44

Correct lifecycle narratives: chunk-0 reuse, supersession, and cron entry points

• Fixes the Slack mention and follow-up flows to reflect edit-in-place chunk-0 reuse and a fail-closed follow-up classifier gate. Updates 👎 auto-correction to flag-and-supersede (not delete) and documents all three HTTP entry points including '/api/cron/code-index', plus adds hybrid retrieval namespace/degradation notes and points project structure to CLAUDE.md.

docs/architecture.md

contributing.mdRefresh test suite counts and remove duplicated structure tree +3/-36

Refresh test suite counts and remove duplicated structure tree

• Updates the stated test counts to current values and makes CI guidance less brittle. Replaces the embedded project structure listing with a pointer to the canonical tree in CLAUDE.md.

docs/contributing.md

knowledge-base.mdClarify Upstash Redis provisioning and management UI terminology +7/-7

Clarify Upstash Redis provisioning and management UI terminology

• Rewords storage details to reflect Upstash Redis via Vercel Marketplace and updates dashboard navigation to the Upstash data browser. Adjusts lifecycle guidance and degradation language to refer to Upstash Redis rather than “Vercel KV”.

docs/features/knowledge-base.md

progress-ux.mdDocument edit-in-place progress message reuse (chunk 0) +11/-9

Document edit-in-place progress message reuse (chunk 0)

• Updates the progress UX flow to describe transforming the thinking message into the first answer chunk instead of delete-and-repost. Removes a documented-but-never-emitted status and reframes the rationale section around why editing is preferred, including the safety-net delete behavior on crashes.

docs/features/progress-ux.md

source-hierarchy.mdAlign auto-correction semantics with supersession (not deletion) +2/-2

Align auto-correction semantics with supersession (not deletion)

• Corrects the description of how KB staleness is handled on 👎: entries are flagged and later superseded by corrections rather than removed. Updates the explanation to emphasize retaining history while retiring stale sources from recall.

docs/features/source-hierarchy.md

observability.mdRemove named reference implementation mention in Sentry explanation +1/-1

Remove named reference implementation mention in Sentry explanation

• Keeps the operational rationale for Sentry-on-Vercel but rewrites the note to avoid referencing an external project by name. No behavior changes—documentation/comment wording only.

docs/observability.md

setup.mdUpdate setup text to reference Upstash Redis and edit-in-place UX +3/-3

Update setup text to reference Upstash Redis and edit-in-place UX

• Adjusts setup guidance to state that the knowledge base lives in Upstash Redis (not Vercel KV). Updates the expected end-to-end Slack behavior description to match the thinking-message transform-in-place lifecycle.

docs/setup.md

usage.mdAlign usage guide with edit-in-place answers and Upstash Redis storage +3/-3

Align usage guide with edit-in-place answers and Upstash Redis storage

• Updates the basic interaction steps to reflect editing the thinking message into the final answer, with additional replies for long outputs. Rewords knowledge/feedback persistence to reference Upstash Redis (Vercel Marketplace).

docs/usage.md

sentry.server.config.tsComment cleanup: remove external reference name from Sentry rationale +1/-2

Comment cleanup: remove external reference name from Sentry rationale

• Edits the explanatory comment about Sentry flush behavior on Vercel to remove a named external reference. No runtime behavior changes.

sentry.server.config.ts

compaction.tsComment cleanup: make compaction design note generic +1/-1

Comment cleanup: make compaction design note generic

• Renames a comment header to describe design choices without referencing an external implementation. Code behavior is unchanged.

src/lib/compaction.ts

reply-footer.tsComment cleanup: genericize reply-footer format rationale +2/-2

Comment cleanup: genericize reply-footer format rationale

• Rewrites comment text to remove an external project reference while keeping the same explanation of the footer format and intent. No behavior changes.

src/lib/reply-footer.ts

slack-users.tsComment cleanup: rename “Junior’s pattern” to a generic approach note +1/-1

Comment cleanup: rename “Junior’s pattern” to a generic approach note

• Updates a top-of-file comment to describe the caching/pre-resolution approach without naming an external reference implementation. Runtime logic is unchanged.

src/lib/slack-users.ts