docs: comments name what the code does, not how it was built

Thirty-one files carried internal build vocabulary and anchors pointing at
notes that are not in the repository: a reader of `checklist.ts` in a year
would find its rationale keyed to a research id they cannot open, inside a
comment that also names an internal build stage. Two test titles carried the
same anchors.

The version tags and the whole of the reasoning stay; only the vocabulary and
the dangling references go, with the few sentences that were built around an
anchor rewritten to stand on their own.

e2e/onboarding-ai-offer.spec.ts

@@ -1,5 +1,5 @@
 /**
- * v1.38.19 (wave D) — the AI offer at the end of the setup flow.
+ * v1.38.19 — the AI offer at the end of the setup flow.
  *
  * The screen used to promise that insights "work for you right now" the
  * moment the operator had configured a key. It never knew whether the key

e2e/setup-flow-a11y.spec.ts

@@ -118,7 +118,7 @@ const SCREENS: ScreenCase[] = [
   {
     screen: "first-result",
     path: "/onboarding/first-result",
-    // v1.38.19 (wave B) — wait for the tile the screen SETTLED on, not for
+    // v1.38.19 — wait for the tile the screen SETTLED on, not for
     // the connect card. This sweep used to name the connect card, which is
     // painted for the few hundred milliseconds before the status envelope
     // resolves whatever the account's real state is — so it scanned a frame

e2e/setup-flow-connect.spec.ts

@@ -1,5 +1,5 @@
 /**
- * v1.38.19 (wave B / C1, C2) — the setup flow, path 5: a wearable on Q4.
+ * v1.38.19 — the setup flow, path 5: a wearable on Q4.
  *
  * The connect arm is the only place in the flow that renders a claim about
  * real account state, and until this file no journey reached it: bp answers

e2e/setup/ai-offer-fixture.ts

@@ -1,5 +1,5 @@
 /**
- * v1.38.19 (wave D) — the instance state the shared-provider offer reads.
+ * v1.38.19 — the instance state the shared-provider offer reads.
  *
  * Two rows decide what the setup flow's last screen may say, and neither has
  * a product endpoint that writes them the way this journey needs:

e2e/setup/global-setup.ts

@@ -481,7 +481,7 @@ export const E2E_SETUP_A11Y = {
 } as const;
 
 /**
- * v1.38.19 (wave B) — the connect-source journey's account.
+ * v1.38.19 — the connect-source journey's account.
  *
  * The one arm of the flow that renders a claim about real account state had
  * no journey that reached it: bp answers `manual`, visit answers `file`, and
@@ -503,7 +503,7 @@ export const E2E_SETUP_LOCALE = {
 } as const;
 
 /**
- * v1.38.19 (wave D) — the shared-provider offer's own account.
+ * v1.38.19 — the shared-provider offer's own account.
  *
  * Its journey seeds INSTANCE-wide state (the operator key's presence and the
  * provider-health ledger the tri-state folds) and mints a consent receipt on

src/__tests__/profile-rejection-surface-guard.test.ts

@@ -35,7 +35,7 @@ function sourceFiles(): string[] {
     walkSourceFiles(SRC, { floor: 3000 })
       .filter((p) => !p.startsWith("generated/"))
       .filter((p) => !p.startsWith("app/api/"))
-      // v1.39 (Wave C, C6) — the edge proxy names routes and methods as DATA
+      // v1.39 — the edge proxy names routes and methods as DATA
       // (the demo-mode mutation allowlist is a list of path/method pairs), and
       // a pair reads to the matcher below exactly like a request expression. It
       // submits nothing and has no answer to read.

src/app/api/integrations/status/__tests__/route.test.ts

@@ -347,7 +347,7 @@ describe("/api/integrations/status — the freshness read failed", () => {
 });
 
 /**
- * v1.38.19 (wave B / I5) — the never-connected provider on the wire.
+ * v1.38.19 — the never-connected provider on the wire.
  *
  * The ledger's synthetic "no row" snapshot reads `unknown`, and the envelope
  * publishes it verbatim. A client that reads `state` must see a value that

src/app/api/user/ai-provider/__tests__/route.test.ts

@@ -43,7 +43,7 @@ vi.mock("@/lib/logging/context", () => ({
   annotate: vi.fn(),
 }));
 
-// v1.38.19 (wave D) — the four preconditions the honest offer rides on.
+// v1.38.19 — the four preconditions the honest offer rides on.
 vi.mock("@/lib/ai/server-provider-health", () => ({
   readServerProviderHealth: vi.fn(),
 }));
@@ -441,7 +441,7 @@ describe("GET /api/user/ai-provider — the gateway's fields (#470)", () => {
 });
 
 /**
- * v1.38.19 (wave D) — the honest shared-provider offer.
+ * v1.38.19 — the honest shared-provider offer.
  *
  * The setup flow's last screen used to promise that insights "work for you
  * right away" whenever `managedBy` said `server`. That is a presence read:

src/app/api/user/ai-provider/route.ts

@@ -42,7 +42,7 @@ export const GET = apiHandler(async () => {
       aiCompatModel: true,
       // v1.22 (#89)
       aiResponseTimeoutSeconds: true,
-      // v1.38.19 (wave D) — a managed profile is never the party that gives
+      // v1.38.19 — a managed profile is never the party that gives
       // consent for itself; the offer below has to know.
       managedProfileAt: true,
     },
@@ -55,7 +55,7 @@ export const GET = apiHandler(async () => {
   // `managedBy` reports the origin only; no admin keys/endpoints are leaked.
   const { aiAvailable, managedBy } = await resolveProviderAvailability(user.id);
 
-  // ── v1.38.19 (wave D) — the shared provider, honestly ────────────────
+  // ── v1.38.19 — the shared provider, honestly ────────────────
   // `managedBy: "server"` says the operator configured a key. It has never
   // said the key WORKS, and the setup flow spent three releases promising
   // that it did. It also says nothing about the consent receipt
@@ -125,7 +125,7 @@ export const GET = apiHandler(async () => {
     hasCompatKey: Boolean(u?.aiCompatKeyEncrypted),
     // v1.22 (#89) — per-user response timeout, in seconds (null = default).
     responseTimeoutSeconds: u?.aiResponseTimeoutSeconds ?? null,
-    // v1.38.19 (wave D) — see the block above. A tri-state and two booleans;
+    // v1.38.19 — see the block above. A tri-state and two booleans;
     // no count, no timestamp and no other account is inferable from them.
     serverProviderHealth,
     serverProviderOffer,

src/components/onboarding/__tests__/confirm-failure-recovery.test.ts

@@ -1,16 +1,16 @@
 /**
- * v1.39 (Wave C, C2) — a failed completion leaves the confirm screen usable.
+ * v1.39 — a failed completion leaves the confirm screen usable.
  *
  * Two defects, one symptom. `advance()` in the baseline form set its pending
  * flag and never reset it on the success path, and `finish()` on the confirm
  * screen caught its own error and returned normally — so a failed
  * `POST /api/onboarding/complete` (or a 429 on the answer PATCHes before it)
  * left "Überspringen" and "Bestätigen und weiter" disabled for the rest of the
- * page's life and only a reload recovered (research I10).
+ * page's life and only a reload recovered.
  *
  * The second defect is the retry itself: `finish()` fires one PATCH per
  * question the flow never showed, and a failure midway left a partly-passed
- * ledger that the next attempt walked from the top again (M-j).
+ * ledger that the next attempt walked from the top again.
  *
  * Both are pinned at the seam the component drives, because this repo's
  * component tests render server-side and cannot click.
@@ -127,7 +127,7 @@ describe("runConfirmFinish", () => {
     expect(navigate).not.toHaveBeenCalled();
   });
 
-  it("does not pass a step the failed attempt already passed (M-j)", async () => {
+  it("does not pass a step the failed attempt already passed", async () => {
     const ledger = { current: state() };
     const passed: PassableStep[] = [];
     const passStep = async (step: PassableStep) => {

src/components/onboarding/__tests__/confirm-screen.test.tsx

@@ -1,13 +1,13 @@
 /**
- * v1.39 (Wave C) — what the confirm screen is allowed to claim.
+ * v1.39 — what the confirm screen is allowed to claim.
  *
- * C5 (research M-l): both of the screen's own Settings links are page routes,
+ * Both of the screen's own Settings links are page routes,
  * and `hl_onboarding=pending` is still set while this screen is on — the
  * completion is what clears it, and this screen is what calls the completion.
  * The proxy sends both straight back to the flow, so on a first run they are
  * dead links under a sentence that is not yet true.
  *
- * C4 (research I6): the screen listed what the answers switch ON and said
+ * The screen listed what the answers switch ON and said
  * everything else "stays one click away under Settings, Modules" — true of
  * reachability, false of the navigation entry. A module the answers do not
  * ask for leaves the navigation, and nothing said so.
@@ -75,7 +75,7 @@ function render(
   );
 }
 
-describe("<ConfirmScreen> — modules leaving the navigation (C4)", () => {
+describe("<ConfirmScreen> — modules leaving the navigation", () => {
   it("names them when the answers do not ask for what the record shows", () => {
     const html = render(state({}, { areas: ["sleep"], medication: "no" }), {
       medications: true,
@@ -111,7 +111,7 @@ describe("<ConfirmScreen> — modules leaving the navigation (C4)", () => {
   });
 });
 
-describe("<ConfirmScreen> — Settings links on a first run (C5)", () => {
+describe("<ConfirmScreen> — Settings links on a first run", () => {
   it("renders both as plain text while the completion has not run", () => {
     const html = render(state());
     expect(html).not.toContain('href="/settings/modules"');

src/components/onboarding/__tests__/done-screen.test.tsx

@@ -150,7 +150,7 @@ describe("<DoneScreen> AI panel", () => {
 });
 
 /**
- * v1.38.19 (wave D) — the shared provider, offered only when it works.
+ * v1.38.19 — the shared provider, offered only when it works.
  *
  * The card used to read `managedBy === "server"` and promise that insights
  * "work for you right now". That is a presence read: it knew a key was

src/components/onboarding/__tests__/first-result-screen.test.tsx

@@ -1,5 +1,5 @@
 /**
- * v1.38.19 (wave B / C1, C2, I1, I2, I3) — the connect arm of the one task
+ * v1.38.19 — the connect arm of the one task
  * the flow ends on.
  *
  * This arm is the only place in the flow that renders a claim about real
@@ -202,7 +202,7 @@ describe("<FirstResultScreen> — the connect arm", () => {
   });
 
   /**
-   * v1.38.19 (wave B / I1) — the heading is chosen from the answers alone on
+   * v1.38.19 — the heading is chosen from the answers alone on
    * the server, because no status is in hand there. Once the envelope has
    * resolved the screen re-picks: a source that is already delivering is not
    * a task, and "Connect WHOOP" over a WHOOP that has been feeding the

src/components/onboarding/__tests__/getting-started-checklist.test.tsx

@@ -1,5 +1,5 @@
 /**
- * v1.39 (Wave C, C1) — the checklist's data queries follow the same rule as
+ * v1.39 — the checklist's data queries follow the same rule as
  * its visibility.
  *
  * `shouldShowChecklist` gained `hasEnteredOnboardingFlow` as a third
@@ -7,7 +7,7 @@
  * half of the rule, so a wizard-run account past five readings still saw the
  * card while every supporting query was `enabled: false` — the medication,
  * data-source, notification and insights rows read "not done" for things the
- * account had already done (research I9).
+ * account had already done.
  *
  * Rendered SSR-only, per this repo's component-test convention. `useQuery` is
  * mocked to honour `enabled` exactly the way tanstack does — a disabled query

src/components/onboarding/__tests__/units-screen.test.tsx

@@ -1,5 +1,5 @@
 /**
- * v1.39 (Wave C, C3) — Q6 cannot be answered with nothing chosen (M-k).
+ * v1.39 — Q6 cannot be answered with nothing chosen.
  *
  * "Weiter" used to be live on an untouched units screen: it wrote
  * `{ units: {} }`, which marked the step DONE without recording a preference,

src/components/onboarding/baseline-form.tsx

@@ -72,7 +72,7 @@ interface BaselineFormState {
 }
 
 /**
- * v1.39 (Wave C, C2) — one attempt at confirming, with the buttons always
+ * v1.39 — one attempt at confirming, with the buttons always
  * handed back.
  *
  * `advance()` used to raise its own pending flag and lower it again on two of
@@ -81,7 +81,7 @@ interface BaselineFormState {
  * `onConfirmed` is the confirm screen's completion, which caught its own
  * error and returned normally. So a failed completion disabled "Skip" and
  * "Confirm and continue" for the rest of the page's life and only a reload
- * recovered (research I10).
+ * recovered.
  *
  * The reset lives in a `finally` here, which is the one place it cannot be
  * forgotten on a new exit, and the component has no other way to move the

src/components/onboarding/confirm-screen.tsx

@@ -59,7 +59,7 @@ import {
  * passed explicitly so the ledger reads as settled rather than owed.
  */
 /**
- * v1.39 (Wave C, C2) — the completion sequence, apart from the component so
+ * v1.39 — the completion sequence, apart from the component so
  * a failure partway through it can be pinned without a browser.
  *
  * Passes every question the flow never showed (the route derives only once
@@ -112,7 +112,7 @@ export function ConfirmScreen({
   const answer = useOnboardingAnswer();
   const [finishing, setFinishing] = useState(false);
   /**
-   * v1.39 (Wave C, C2) — the ledger as the last write left it (M-j).
+   * v1.39 — the ledger as the last write left it.
    * `finish()` sends one PATCH per question the flow never showed; a failure
    * midway used to leave a partly-passed ledger that the next attempt walked
    * from the top again, because the `state` prop it read was the one this
@@ -125,7 +125,7 @@ export function ConfirmScreen({
 
   const needs = state.needs;
   /**
-   * v1.39 (Wave C, C5) — is `hl_onboarding=pending` still set? (research M-l)
+   * v1.39 — is `hl_onboarding=pending` still set?
    *
    * Both of this screen's Settings links are page routes, and the cookie is
    * cleared by the completion — which is what THIS screen calls. So on a
@@ -161,12 +161,12 @@ export function ConfirmScreen({
    * record and stamps this one complete without deriving, so the guardian's
    * own modules are never re-ordered around the child's answers.
    *
-   * v1.39 (Wave C, C2) — this RETHROWS. `<BaselineForm>` owns the two
+   * v1.39 — this RETHROWS. `<BaselineForm>` owns the two
    * buttons and releases them in its own `finally`, and it can only do that
    * for a failure it is told about: the previous version caught, toasted and
-   * returned normally, which left both buttons disabled until a reload
-   * (research I10). The two managed-arm callers, which have no form around
-   * them, go through `finishReporting` below.
+   * returned normally, which left both buttons disabled until a reload.
+   * The two managed-arm callers, which have no form around them, go through
+   * `finishReporting` below.
    */
   async function finish(managedRecordId?: string) {
     if (finishing) return;

src/components/onboarding/done-screen.tsx

@@ -35,7 +35,7 @@ interface AiProviderStatus {
   /** Origin of the provider that would serve this user, if any. */
   managedBy?: "user" | "local" | "server" | null;
   /**
-   * v1.38.19 (wave D) — the instance-wide tri-state. Fail closed for the
+   * v1.38.19 — the instance-wide tri-state. Fail closed for the
    * offer: neither `unhealthy` nor `unknown` earns one. Only `unhealthy` is
    * a verdict this screen may state out loud.
    */
@@ -112,7 +112,7 @@ export function DoneScreen({ state }: { state: OnboardingStateDto }) {
     router.push("/");
   }
 
-  // ── v1.38.19 (wave D) — the shared provider, offered only when it works ──
+  // ── v1.38.19 — the shared provider, offered only when it works ──
   //
   // This block used to be one line: `managedBy === "server"` painted a note
   // reading "insights work for you right now — no setup needed". Both halves

src/components/onboarding/getting-started-checklist.tsx

@@ -246,12 +246,12 @@ export function GettingStartedChecklist() {
   // the snapshot having resolved so the count is real, not the
   // loading-default 0.
   //
-  // v1.39 (Wave C, C1) — the rule is `isStillInSetup`, the same predicate
+  // v1.39 — the rule is `isStillInSetup`, the same predicate
   // `shouldShowChecklist` applies, rather than a restatement of half of it.
   // The two drifted apart once already: the visibility rule learned about
   // records that ran the setup flow and this gate did not, so the card
   // rendered for a wizard-run account past five readings with every
-  // network-backed row frozen at "not done" (research I9, M-p).
+  // network-backed row frozen at "not done".
   const checklistRelevant =
     !!user &&
     !dismissedAll &&

src/lib/ai/__tests__/server-provider-health.test.ts

@@ -1,5 +1,5 @@
 /**
- * v1.38.19 (wave D) — the instance-wide health of the operator's shared
+ * v1.38.19 — the instance-wide health of the operator's shared
  * provider, as a tri-state a FRESH account is allowed to read.
  *
  * The ledger itself is per-user and fails OPEN (an optimisation, never a

src/lib/ai/server-provider-health.ts

@@ -1,5 +1,5 @@
 /**
- * v1.38.19 (wave D) — "does the shared provider of THIS instance work?",
+ * v1.38.19 — "does the shared provider of THIS instance work?",
  * answered for a user who has never made a single AI call.
  *
  * The question comes from the end of the setup flow. The done screen used

src/lib/integrations/__tests__/status.test.ts

@@ -1371,7 +1371,7 @@ describe("recordSyncFailure — leg set", () => {
 });
 
 /**
- * v1.38.19 (wave B / I5) — the synthetic "no row" snapshot.
+ * v1.38.19 — the synthetic "no row" snapshot.
  *
  * `state: "connected"` used to be the value an account with no sync history
  * read back, which made the ledger field's default mean the opposite of its

src/lib/onboarding/__tests__/checklist.test.ts

@@ -613,7 +613,7 @@ describe("shouldShowChecklist and the setup flow", () => {
 describe("isStillInSetup", () => {
   // The one predicate both the visibility rule and the component's query gate
   // read, so the card can never render with its supporting queries switched
-  // off (research I9).
+  // off.
   it("is true for a record that ran the flow, whatever its reading count", () => {
     expect(
       isStillInSetup({
@@ -624,7 +624,7 @@ describe("isStillInSetup", () => {
     ).toBe(true);
   });
 
-  it("is true for a restarted run nobody finished (M-p)", () => {
+  it("is true for a restarted run nobody finished", () => {
     const restarted = onboardingState({ completedAt: null });
     expect(
       isStillInSetup({

src/lib/onboarding/__tests__/confirm-summary.test.ts

@@ -67,7 +67,7 @@ describe("confirmedModules", () => {
   });
 });
 
-describe("confirmedModules — what leaves the navigation (I6)", () => {
+describe("confirmedModules — what leaves the navigation", () => {
   const noMedication = {
     ...emptyOnboardingNeeds(),
     recordTarget: "me" as const,

src/lib/onboarding/__tests__/first-result-config.test.ts

@@ -45,7 +45,7 @@ describe("first-result targets", () => {
 });
 
 /**
- * v1.38.19 (wave B / C1, I2, I3) — what the connect step is allowed to say.
+ * v1.38.19 — what the connect step is allowed to say.
  *
  * The screen used to decide "connected" from the ledger's `state` field, whose
  * default meant the opposite of its name, and had one piece of copy for every
@@ -222,7 +222,7 @@ describe("connect-source state copy", () => {
 });
 
 /**
- * v1.38.19 (wave B / I1) — which sources the flow must stop offering.
+ * v1.38.19 — which sources the flow must stop offering.
  *
  * Only a connection that is actually delivering, or one whose data has merely
  * gone quiet: both are real connections the person made, and offering to make

src/lib/onboarding/__tests__/question-config.test.ts

@@ -80,7 +80,7 @@ describe("questionAnswerBody", () => {
     expect(questionAnswerBody("visit", [])).toBeNull();
   });
 
-  it("is null for a many-answer question with nothing chosen (I4)", () => {
+  it("is null for a many-answer question with nothing chosen", () => {
     // An empty tick list is not an opinion. It used to be sent as an
     // ANSWER, and an answered Q2 with no areas is what switched every
     // optional module off for somebody who meant "no preference" — Skip is
@@ -129,7 +129,7 @@ describe("units", () => {
     expect(onboardingAnswerSchema.safeParse(body).success).toBe(true);
   });
 
-  it("is null when nothing was chosen, so Skip is the way past (M-k)", () => {
+  it("is null when nothing was chosen, so Skip is the way past", () => {
     // An empty units answer marked Q6 done without recording a preference.
     expect(
       unitsAnswerBody({

src/lib/onboarding/__tests__/wizard-steps.test.ts

@@ -169,7 +169,7 @@ describe("chooseFirstResultTask", () => {
   });
 
   /**
-   * v1.38.19 (wave B / I1) — the choice used to read the answers alone, so an
+   * v1.38.19 — the choice used to read the answers alone, so an
    * account whose WHOOP had been delivering for months was told to go and
    * connect WHOOP. A source that is already delivering is not a task; the
    * priority falls through to the next one the person's answers name.

src/lib/onboarding/checklist.ts

@@ -296,15 +296,15 @@ export interface StillInSetupInputs {
 }
 
 /**
- * v1.39 (Wave C, C1) — "is this record still being set up?", as ONE predicate.
+ * v1.39 — "is this record still being set up?", as ONE predicate.
  *
  * Two places decide this: whether the card renders at all, and whether the
  * component fetches the data its rows are about. They were two restatements of
  * the same rule and they drifted — the visibility rule gained
  * `hasEnteredOnboardingFlow`, the query gate kept the older half, and a
  * wizard-run account past five readings got a permanently visible card whose
- * every network-backed row read "not done" (research I9). A record whose
- * restarted run was abandoned is in the same state (M-p): `restart` clears the
+ * every network-backed row read "not done". A record whose
+ * restarted run was abandoned is in the same state: `restart` clears the
  * record's own `completedAt` and deliberately not the account stamp, so
  * `hasEnteredOnboardingFlow` is what keeps its rows live.
  *

src/lib/onboarding/confirm-summary.ts

@@ -29,11 +29,10 @@ export interface ConfirmedModules {
   /** On whatever the answers say. */
   alwaysOn: ModuleKey[];
   /**
-   * v1.39 (Wave C, C4) — what the derivation takes OUT of the navigation:
-   * modules this record shows today that the answers do not ask for
-   * (research I6). Empty until the account payload has resolved, because a
-   * module the payload says nothing about is a module this screen knows
-   * nothing about.
+   * v1.39 — what the derivation takes OUT of the navigation:
+   * modules this record shows today that the answers do not ask for. Empty
+   * until the account payload has resolved, because a module the payload
+   * says nothing about is a module this screen knows nothing about.
    */
   wouldSwitchOff: ModuleKey[];
 }

src/lib/onboarding/question-config.ts

@@ -114,8 +114,8 @@ function only<T extends string>(
  * vocabulary is dropped rather than sent, so the strict server schema never
  * sees a chip this file did not offer.
  *
- * v1.39 (Wave C, C3) — an empty tick list is not an answer either (research
- * I4). The many-answer arms used to send `[]` and mark the step DONE, and an
+ * v1.39 — an empty tick list is not an answer either. The many-answer arms
+ * used to send `[]` and mark the step DONE, and an
  * answered Q2 with no areas is what switched every optional module off for
  * somebody whose click meant "no preference". Skip is the way past a question
  * nobody wants to answer, and Skip is the conservative derivation.
@@ -192,7 +192,7 @@ export function unitsAnswerBody(input: {
   if (input.asked.weight && input.unitPreference) {
     units.unitPreference = input.unitPreference;
   }
-  // v1.39 (Wave C, C3) — nothing chosen is not an answer (M-k): an empty
+  // v1.39 — nothing chosen is not an answer: an empty
   // units body marked Q6 done while recording no preference at all.
   return Object.keys(units).length > 0 ? { step: "units", units } : null;
 }

src/lib/openapi/routes/profile.ts

@@ -559,7 +559,7 @@ const aiProviderResponse = z
       .describe(
         "v1.22 (#89) — per-user response timeout for AI generation, in seconds (10–600). Null = the built-in comprehensive-briefing default (~120 s). Mainly for slow local/self-hosted backends.",
       ),
-    // v1.38.19 (wave D) — the setup flow's last screen used to promise
+    // v1.38.19 — the setup flow's last screen used to promise
     // that insights "work for you right away" as soon as `managedBy` read
     // `server`. That is a presence read; it never knew whether the key
     // worked, and it said nothing about the consent receipt the egress