chore: project-wide comment cleanup + 4 small-bug fixes (#393)

Swept the whole codebase (12 disjoint slices, ~211 files) to remove
AI/bot/ process noise from comments and make them read like professional
engineering comments — about the code, not the process:
- Stripped bot-reviewer attributions (Copilot/Codex/Sourcery review #N,
"finding YYYY-MM-DD"), process/PR meta ("in this PR", "as discussed"),
and standalone wave/cycle/date WHEN-stamps that git already records.
- Rewrote each to keep the WHY (security/ordering/rationale) without the
noise; deleted purely redundant "what" comments.
- Preserved load-bearing anchors exactly: CLAUDE.md A-rule refs,
decision #N, Phase N flag tags, G-/L-finding security-addendum anchors,
RFC/NIST/spec citations, real Claude/Anthropic API product references,
and all @smoke/@regression/@cycle CI grep tags + test/describe titles
(untouched).

Small bugs found + fixed during the sweep:
- onboarding.service.js: note.create used an unknown Prisma field
`visibility:'private'` (Note has `private`) — would throw a validation
error and 500 the onboarding "upload_note" first-action. Now `private:
true`.
- DataAndBatteryTab.jsx: success toast was the JS string 'Data &
battery preferences saved.' so it rendered the literal "&". Now
plain "&".
- moderationEngine.js: JSDoc said "scans via OpenAI Moderation API" but
the code calls Claude Haiku — corrected the doc.
- achievements.engine.js: JSDoc referenced a non-existent function name.

Backend 3,507 + frontend 876 tests pass; lint + build clean. No behavior
change beyond the two real fixes above. Riskier items (settings export
field drift, a moderation ternary precedence) were REPORTED, not changed
— left for review.

Author: Apexone11

backend/scripts/migrate-to-send-error.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * migrate-to-send-error.js — one-shot codemod for Day 3 of the tech-debt week.
+ * migrate-to-send-error.js — one-shot codemod.
  *
  * Rewrites `res.status(XXX).json({ error: '...' })` → `sendError(res, XXX, '...', ERROR_CODES.Y)`
  * and inserts the `sendError` import if absent. Supports:

backend/scripts/restoreVolumeFromR2.js

@@ -1,7 +1,7 @@
 /**
  * restoreVolumeFromR2.js — disaster-recovery for /data/uploads.
  *
- * Wave-12.11. Pairs with backend/src/lib/jobs/uploadVolumeBackup.js.
+ * Pairs with backend/src/lib/jobs/uploadVolumeBackup.js.
  *
  * When to run: the Railway volume is gone, corrupted, or replaced. The
  * DB rows still point at /uploads/... paths; without restoring the

backend/scripts/seedBetaUsers.js

@@ -163,10 +163,9 @@ async function seedFeedFixture(studentUserId) {
  * /users/beta_student1?tab=overview renders a happy-path card out of
  * the box — no curl, no Prisma Studio, no manual setup.
  *
- * Codifies the "every feature must ship with seed data" rule added to
- * CLAUDE.md §Working-Agreement #11 during the Day 3 smoke-test
- * regression. See docs/internal/audits/2026-04-24-day3-polish-and-
- * ship-handoff.md.
+ * Codifies the "every feature must ship with seed data" rule from
+ * CLAUDE.md §Working-Agreement #11. See
+ * docs/internal/audits/2026-04-24-day3-polish-and-ship-handoff.md.
  *
  * Idempotent: uses a stable (userId, title) de-dupe so re-running
  * `npm run seed:beta` doesn't pile up duplicate rows.
@@ -301,7 +300,7 @@ async function seedAiSuggestions(studentUsers) {
 }
 
 /**
- * Seed published study sheets for the Sheets Grid view (Phase 4 Day 3).
+ * Seed published study sheets for the Sheets Grid view (Phase 4).
  *
  * /sheets must show beta_student1 a meaningful state out of the box —
  * 6+ sheets across 3 courses, all with non-null previewText so the Grid

backend/src/index.js

@@ -708,7 +708,7 @@ app.use('/api/library', libraryRoutes)
 // Scholar v1 endpoints under /api/scholar (master plan §18).
 app.use('/api/scholar', scholarRoutes)
 
-// Related-work strips on detail pages (wave-12.3 ecosystem Track 5).
+// Related-work strips on detail pages (ecosystem Track 5).
 // Public read-only — surfaces sibling sheets / linked notes / cross-
 // surface references for sheets, notes, papers, and library books.
 app.use('/api/related', relatedRoutes)
@@ -898,8 +898,8 @@ async function startServer() {
       ).unref()
     }, msUntilNextFour).unref()
 
-    // Wave-12.11 — daily mirror of /data/uploads to R2 so user-
-    // uploaded photos survive a Railway volume crash. No-ops
+    // Daily mirror of /data/uploads to R2 so user-uploaded photos
+    // survive a Railway volume crash. No-ops
     // gracefully when R2_BUCKET_UPLOAD_BACKUP is unset. Recovery
     // procedure documented in docs/internal/security/
     // RUNBOOK_DB_RESTORE.md "Upload Volume Recovery" section.

backend/src/lib/dataSaverNegotiation.js

@@ -1,7 +1,7 @@
 /**
  * dataSaverNegotiation.js — server-side data-saver detection.
  *
- * Wave-12.11. Pairs with the frontend `useDataSaver` hook.
+ * Pairs with the frontend `useDataSaver` hook.
  *
  * Returns true when the current request should receive a lighter
  * response (smaller image variants, no thumbnail array, no SSE

backend/src/lib/deleteUserAccount.js

@@ -325,8 +325,7 @@ async function deleteUserAccount(prisma, { userId, username, reason = null, deta
     // schema.prisma, so Prisma 6 defaults to Restrict. Deleting the user
     // FIRST would crash with a foreign-key constraint violation. This
     // delete-messages-then-user ordering is the contract — do not reorder
-    // without first migrating the schema to `onDelete: SetNull` (audit
-    // 2026-05-03).
+    // without first migrating the schema to `onDelete: SetNull`.
     await tx.messageReaction.deleteMany({ where: { userId } })
     await tx.message.deleteMany({ where: { senderId: userId } })
     // Remove user from all conversations as participant

backend/src/lib/deviceCookie.js

@@ -12,10 +12,10 @@
  * Reads are cheap. Writes happen at most once per browser-lifetime unless
  * the user manually clears cookies or we explicitly rotate (panic mode).
  *
- * SameSite history (2026-05-14): was hard-coded to 'lax' which caused
- * the device cookie to drop on cross-site fetches between SPA and API
- * origins, degrading device-trust scoring and triggering extra 2FA
- * prompts. Mirrors the proven `authTokens.js` pattern now.
+ * SameSite must follow the cross-origin rules: a hard-coded 'lax' drops
+ * the device cookie on cross-site fetches between the SPA and API origins,
+ * degrading device-trust scoring and triggering extra 2FA prompts. Mirrors
+ * the `authTokens.js` cookie pattern.
  */
 
 const crypto = require('crypto')

backend/src/lib/getUserPlan.js

@@ -6,11 +6,10 @@
 const prisma = require('./prisma')
 
 // Active statuses that grant Pro access. `past_due` is intentionally NOT
-// here as of 2026-05-03: previously a payment failure granted up to 3
-// weeks of free Pro while Stripe's smart retry chain ran. Now we treat
-// past_due as a hard cutoff — the UI shows a "fix payment" banner but the
-// quotas drop to free. The user can restore Pro by updating their card via
-// the Stripe Customer Portal.
+// here: including it would grant up to 3 weeks of free Pro while Stripe's
+// smart retry chain runs. past_due is a hard cutoff — the UI shows a "fix
+// payment" banner but quotas drop to free. The user can restore Pro by
+// updating their card via the Stripe Customer Portal.
 const ACTIVE_STATUSES = ['active', 'trialing']
 
 async function getUserPlan(userId) {

backend/src/lib/html/htmlDraftWorkflow.js

@@ -249,7 +249,7 @@ async function submitHtmlDraftForReview(prisma, { sheetId, user }) {
   // the AI-first model the founder approved 2026-05-03 — admins should
   // see "special cases" only, not the full Tier 2 firehose. The
   // sendHighRiskSheetAlert + admin notification fan-out lives in
-  // sheetReviewer.service.js's escalation branch (Copilot review #4).
+  // sheetReviewer.service.js's escalation branch.
 
   // Tier 3 — notify the AUTHOR that their sheet was auto-rejected with the
   // reason so they can fix it and resubmit. CLAUDE.md ESSENTIAL list

backend/src/lib/jobs/uploadVolumeBackup.js

@@ -1,9 +1,9 @@
 /**
  * uploadVolumeBackup.js — daily mirror of /data/uploads to R2.
  *
- * Wave-12.11 — closes the gap documented in RUNBOOK_DB_RESTORE.md
- * "What's NOT backed up: Uploaded files (avatars, attachments, school
- * logos)". A Railway volume is a single point of failure: if the
+ * Closes the gap documented in RUNBOOK_DB_RESTORE.md "What's NOT
+ * backed up: Uploaded files (avatars, attachments, school logos)".
+ * A Railway volume is a single point of failure: if the
  * disk corrupts or the instance is rebuilt, every user-uploaded image
  * is gone forever and the DB row points at a 404.
  *
@@ -86,9 +86,8 @@ function fileToKey(uploadsDir, filePath) {
  * Streams the file rather than buffering it: video uploads can be
  * hundreds of MB, and `fs.readFileSync` would force the whole file
  * into Node's heap. AWS SDK v3 supports a ReadStream Body — the
- * underlying http client consumes it incrementally. Caught by the
- * wave-12.11 audit pass as an OOM risk on Railway hobby tiers
- * (default 512 MB).
+ * underlying http client consumes it incrementally. Buffering would
+ * be an OOM risk on Railway hobby tiers (default 512 MB).
  */
 async function mirrorFile(uploadsDir, filePath, bucketOverride) {
   const key = fileToKey(uploadsDir, filePath)