style: tighten comments and drop stale scratch tooling (#58)

* style: tighten comments and drop stale scratch tooling

* style: note tab tolerance in fence-boundary comment

Author: aiedwardyi

.gitignore

@@ -46,7 +46,7 @@ service-account*.json
 # Superpowers brainstorm sessions
 .superpowers/
 
-# Playwright MCP (Claude Code)
+# Playwright artifacts
 .playwright-mcp/
 
 # Test screenshots

package.json

@@ -10,8 +10,7 @@
     "lint": "eslint .",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "test": "vitest run",
-    "test:providers": "npx tsx src/lib/providers/test-providers.ts"
+    "test": "vitest run"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.80.0",

src/app/api/chat/route.ts

@@ -31,9 +31,7 @@ function getResponseLengthInstruction(length: ResponseLength): string {
 function getMaxTokens(length: ResponseLength): number {
   switch (length) {
     case "short":
-      // Korean uses 2-3x more tokens than English in Gemini's tokenizer.
-      // Bumped from 350 to 800 so short responses don't get cut mid-sentence
-      // in Korean. Output is still clamped by clampToWordLimit downstream.
+      // Korean tokenizes 2-3x heavier; 800 keeps short mode from cutting mid-sentence.
       return 800
     case "long":
       return 4096
@@ -72,16 +70,8 @@ function stripUnmatchedPair(text: string, token: string): string {
   return `${text.slice(0, lastIndex)}${text.slice(lastIndex + token.length)}`
 }
 
-/**
- * Walks from the end of a truncated response and drops lines that are
- * dangling markdown structure with no body: a heading that has no content
- * below it, a lone bullet or numbered marker, or a table row that was cut
- * mid-write (starts with `|` but doesn't close with `|`). Only used on
- * responses that the stream clamper actually truncated, so normal answers
- * are never touched.
- *
- * Exported for unit testing.
- */
+/** Drops dangling markdown at a truncation point: a heading with no body, a
+ *  lone list marker, a half-written table row. Only runs on clamped text. */
 export function stripDanglingStructure(text: string): string {
   const lines = text.split("\n")
   while (lines.length > 0) {
@@ -90,24 +80,17 @@ export function stripDanglingStructure(text: string): string {
       lines.pop()
       continue
     }
-    // Any heading at the absolute end of the response is dangling by
-    // definition - a properly-followed heading would not be the last
-    // non-blank line. Applies to both `### Title` (heading cut before
-    // its body) and `### ` (marker alone).
+    // A heading as the last non-blank line is dangling by definition.
     if (/^#{1,6}(?:\s.*)?$/.test(last)) {
       lines.pop()
       continue
     }
-    // Lone list marker with nothing after it: `-`, `* `, `1.`, `2. `, etc.
+    // Lone list marker.
     if (/^(?:[-*]|\d+\.)\s*$/.test(last)) {
       lines.pop()
       continue
     }
-    // Truncated table row: line starts with `|` and EITHER does not close
-    // with `|` (mid-cell cut) OR has fewer pipes than the pipe-line above
-    // it (cut between cells, still has a trailing `|` but not enough
-    // columns). Complete rows that match the column count of the row
-    // above are left alone.
+    // Table row cut mid-cell (no closing pipe) or short of the row above's columns.
     if (/^\s*\|/.test(last)) {
       const endsWithPipe = /\|\s*$/.test(last)
       if (!endsWithPipe) {
@@ -131,15 +114,8 @@ export function stripDanglingStructure(text: string): string {
   return lines.join("\n").trimEnd()
 }
 
-/**
- * Polishes a response that the word-limit clamper had to truncate mid-write.
- * Tries to end at the last complete sentence, strips dangling markdown
- * structure (headings/bullets/table rows with no body), removes unmatched
- * bold/italic/code markers, and appends an ellipsis if the result still
- * doesn't end cleanly. Only called when `wasTruncated` is true.
- *
- * Exported for unit testing.
- */
+/** Ends clamped text cleanly: last full sentence, unmatched-marker strip,
+ *  dangling-structure drop, ellipsis fallback. Truncated responses only. */
 export function polishTruncatedResponse(text: string, wordLimit: number): string {
   let result = text.trimEnd()
 
@@ -188,12 +164,7 @@ export function polishTruncatedResponse(text: string, wordLimit: number): string
   return clampToWordLimit(result, wordLimit).text
 }
 
-// Formatting guidance varies by length. Short stays plain prose so tight
-// answers don't get cluttered with structure. Medium unlocks bullets and
-// numbered lists when the content is naturally a list. Long unlocks ###
-// and #### subheadings, GFM tables, and fenced code, but NOT # or ##
-// (those would compete with the app's own UI headers). The guiding line
-// in every tier: "structure is a tool, not decoration."
+// Formatting ladder: short = prose only, medium = lists, long = ###/tables/code. # and ## stay forbidden - they compete with the app's own UI headers.
 export function getFormattingInstruction(length: ResponseLength, isKorean: boolean): string {
   if (isKorean) {
     switch (length) {
@@ -309,11 +280,7 @@ export async function POST(request: Request) {
     }
 
     const inputMessages = messages.filter((m) => m.sender !== "system" && m.sender !== "verdict")
-    // CRITICAL: only consider the USER's own messages when detecting the
-    // conversation language. Otherwise one AI that hallucinates a Korean
-    // summary mid-response tips the ratio and forces every subsequent
-    // provider in the debate to respond entirely in Korean - the
-    // cascading Korean drift bug observed on 2026-04-11.
+    // Detect language from USER messages only - one model hallucinating Korean would otherwise cascade the whole debate into Korean.
     const userOnlyMessages = inputMessages.filter((m) => m.sender === "user")
     const forceKorean = validatedLocale !== "ko" && isPredominantlyKorean(userOnlyMessages)
     const streamFn = getStreamFn(provider)
@@ -331,20 +298,12 @@ export async function POST(request: Request) {
       requestApiKey
     )
     if (blockedResponse) return blockedResponse
-    // Hard word caps per response length. These sit behind the prompt
-    // instruction as a belt-and-suspenders guard: when a provider (Gemini
-    // especially) decides to run 2x longer than requested, the server
-    // clamps the stream mid-flight instead of letting the oversized
-    // bubble dominate the debate feed.
+    // Hard server-side clamp behind the prompt instruction; Gemini especially overruns.
     const wordLimit =
       validatedResponseLength === "short" ? 75 : validatedResponseLength === "medium" ? 170 : 500
     const encoder = new TextEncoder()
     let fullContent = ""
-    // Whether any clampToWordLimit pass actually truncated the stream.
-    // We only call polishTruncatedResponse when this is true, because
-    // polishing can strip unmatched markdown pairs and trailing
-    // connector words, which would unintentionally mutate normal
-    // (non-truncated) responses in medium/long mode.
+    // Polishing mutates text (marker strip, connector trim) - only run it on actually-truncated responses.
     let wasTruncated = false
 
     const stream = new ReadableStream({
@@ -417,11 +376,7 @@ export async function POST(request: Request) {
               fullContent = polishTruncatedResponse(fullContent, wordLimit)
             }
 
-            // Empty-stream guard: providers occasionally close the stream
-            // without yielding any text (safety filter, transient model glitch).
-            // streamGemini already retries once internally. Surface it as an
-            // explicit empty flag so the client can show a clear fallback
-            // instead of a placeholder stuck in "thinking..." forever.
+            // Providers occasionally close without yielding (safety filter, glitch); flag it so the client shows a fallback instead of eternal "thinking...".
             const isEmpty = !fullContent.trim()
 
             enqueueEvent({
@@ -438,16 +393,7 @@ export async function POST(request: Request) {
             closeController()
             return
           }
-          // Route provider failures through the `error` channel rather
-          // than streaming them as bubble content. The old path wrote
-          // `${DISPLAY_NAMES[provider]} encountered an error: ${raw}`
-          // into a chat chunk, so upstream garbage like
-          // "[VertexAI.ClientError]: got status: 499 Client Closed
-          // Request. {"error":{"code":499,..}}" leaked verbatim into
-          // the user-visible bubble. On the client side, data.error
-          // throws into callModel's catch, which now substitutes the
-          // friendly "stepped out for a snack break" system message.
-          // The raw detail still lands in the server log for debugging.
+          // Provider failures go through the error channel, never bubble content - raw upstream errors used to leak verbatim into the chat. Client shows the friendly fallback; detail stays in the server log.
           const msg = error instanceof Error ? error.message : "Unknown error"
           const sanitized = redactSecrets(msg)
           console.error(`[chat/${provider}] stream failed:`, sanitized)

src/app/api/consensus/route.ts

@@ -15,19 +15,10 @@ import { generateGeminiVerdictWithApiKey, getConfiguredGeminiApiKey } from "@/li
 import { resolveUserProviderApiKey } from "@/lib/server-provider-keys"
 import { redactSecrets } from "@/lib/redact-secrets"
 
-/**
- * Vertex AI response schema mirroring validateVerdictResult. Forces the
- * model to emit a structurally valid JSON object with our exact field
- * names, instead of "helpful" prose or invented schemas (gemini-2.5-flash
- * was observed returning markdown bullet lists and renaming
- * recommendedAnswer to summary/recommendation when given only natural-
- * language instructions).
- *
- * Vertex's Schema subset doesn't support min/max constraints on numbers,
- * so the runtime range check on `confidence` stays in
- * validateVerdictResult as defense in depth. Optional fields are listed
- * in `properties` but omitted from `required` so the model can skip them.
- */
+/** Forces structurally valid JSON with our exact field names - flash was seen
+ *  emitting markdown lists and renaming fields under prose instructions alone.
+ *  Vertex's Schema subset lacks numeric min/max, so the confidence range check
+ *  stays in validateVerdictResult. */
 const VERDICT_RESPONSE_SCHEMA: ResponseSchema = {
   type: SchemaType.OBJECT,
   properties: {
@@ -147,12 +138,7 @@ export async function POST(req: NextRequest) {
       (m) => m.sender !== "system" && m.sender !== "verdict"
     )
 
-    // Match the chat route's behavior: if the USER'S OWN messages are
-    // predominantly Korean, force the verdict prompt into Korean even
-    // when the UI locale is English. We intentionally ignore AI responses
-    // here so a single hallucinated Korean span in one AI's reply can't
-    // cascade the whole verdict into Korean - same class of bug that
-    // hit the chat route on 2026-04-11.
+    // User messages only - AI hallucinating Korean must not cascade the whole verdict into Korean.
     const userOnlyMessages = discussionMessages.filter((m) => m.sender === "user")
     const effectiveLocale: Locale = isPredominantlyKorean(userOnlyMessages) ? "ko" : locale
 
@@ -169,16 +155,7 @@ export async function POST(req: NextRequest) {
 
     const thread = formatThread(discussionMessages)
 
-    // Hybrid Flash/Pro verdict routing. The verdict's job is synthesis,
-    // not deep reasoning - the 4 panelist AIs already did the heavy
-    // thinking, and Flash is more than capable of picking the consensus
-    // and formatting it. The one case where Pro is meaningfully better
-    // is continuations: when there's already a prior verdict in the
-    // thread, the new verdict must reconcile against it without flip-
-    // flopping, and Pro is noticeably steadier at that. Everything else
-    // - any length, any round count, any model count - uses Flash, which
-    // cuts verdict wall time from ~15s to ~5s and now produces
-    // schema-conforming JSON thanks to responseSchema enforcement.
+    // Flash for first verdicts (~5s); Pro for continuations where it must reconcile without flip-flopping.
     const useProModel = previousVerdicts.length > 0
     const verdictModelName = useProModel ? "gemini-2.5-pro" : "gemini-2.5-flash"
     const verdictTier = useProModel ? "pro" : "flash"
@@ -231,12 +208,7 @@ export async function POST(req: NextRequest) {
       `[verdict] Generating verdict tier=${verdictTier} source=${userGeminiApiKey ? "user-key" : geminiApiKey ? "gemini-api-key" : "vertex"} for ${aiMessages.length} AI messages, locale=${locale}, effective=${effectiveLocale}, responseLength=${responseLength}, previousVerdicts=${previousVerdicts.length}`
     )
 
-    // Per-tier timeout. Pro verdicts on a 2-round debate with 8 AI
-    // messages legitimately run over a minute; give Pro a full 2
-    // minutes of headroom so it never aborts mid-synthesis. Flash
-    // verdicts finish well under 10s in local testing, so 30s is
-    // plenty of margin - anything past that is a real problem we
-    // want to surface quickly rather than hide behind a long wait.
+    // Pro can legitimately take 2+ minutes on long debates; Flash is well under 10s so 30s surfaces real problems fast.
     const VERDICT_TIMEOUT_MS = useProModel ? 120_000 : 30_000
 
     const generateVerdictText = async (
@@ -277,11 +249,6 @@ export async function POST(req: NextRequest) {
               parts: [{ text: userPrompt }],
             },
           ],
-          // Force structurally valid JSON matching VERDICT_RESPONSE_SCHEMA.
-          // Without this, gemini-2.5-flash returns markdown prose or
-          // invents alternate schemas (summary/recommendation instead of
-          // recommendedAnswer). With it, both Flash and Pro emit
-          // schema-conforming JSON the validator can accept directly.
           generationConfig: verdictGenerationConfig,
         }),
         new Promise<never>((_, reject) =>
@@ -306,22 +273,15 @@ export async function POST(req: NextRequest) {
     const raw = firstResult.raw
 
     if (!raw) {
-      // Empty responses are usually a safety filter trip or a Pro
-      // thinking-only response with no output tokens. Log the full
-      // candidate shape so we can see finishReason/safetyRatings when
-      // this recurs.
+      // Safety filter or Pro thinking-only; log shape for debugging.
       console.error(`[verdict] Empty response. finishReason=${firstResult.finishReason}`, {
         safetyRatings: firstResult.safetyRatings,
         promptFeedback: firstResult.promptFeedback,
       })
       throw new Error("Gemini returned an empty response")
     }
 
-    // Log ONLY metadata in production - the raw-response preview
-    // echoes model output which frequently contains user document
-    // content, legal text, or other sensitive inputs. In dev we keep
-    // the preview for parse-debugging; in prod only length and the
-    // Vertex finishReason ship to CloudWatch / equivalent.
+    // Raw preview only in dev - it echoes user document content which must not land in prod logs.
     if (process.env.NODE_ENV === "development") {
       console.log(
         `[verdict] Raw response length=${raw.length}, finishReason=${firstResult.finishReason ?? "unknown"}, first200=${raw.slice(0, 200).replace(/\n/g, "\\n")}`
@@ -332,13 +292,7 @@ export async function POST(req: NextRequest) {
       )
     }
 
-    // Try to extract a JSON object from the response, even if Pro
-    // wrapped it in thinking text or markdown prose. Strategy:
-    //   1. Strip markdown code fences (```json ... ``` wrappers).
-    //   2. If the result isn't pure JSON, find the first `{` and the
-    //      last `}` and slice between them - this tolerates a preamble
-    //      like "Here's my analysis:" or a trailing summary comment
-    //      without needing a repair round-trip.
+    // Strip fences, then slice first-{ to last-} to tolerate Pro preamble/trailing text.
     const extractJson = (text: string): string => {
       const stripped = text
         .replace(/```json\s*/gi, "")
@@ -357,10 +311,7 @@ export async function POST(req: NextRequest) {
     try {
       parsed = JSON.parse(cleaned)
     } catch (jsonErr) {
-      // First-pass parse failed. Ask Gemini to repair it, then extract
-      // again. The cleaned/retry previews contain model output which
-      // can echo user documents and legal text - gate them to dev so
-      // they never land in production server logs.
+      // Repair retry; previews gated to dev (echo user content).
       const parseErrMsg = jsonErr instanceof Error ? jsonErr.message : String(jsonErr)
       if (process.env.NODE_ENV === "development") {
         console.warn(
@@ -369,9 +320,6 @@ export async function POST(req: NextRequest) {
       } else {
         console.warn(`[verdict] JSON parse failed: ${parseErrMsg}`)
       }
-      // Same schema enforcement on the repair retry. Without it the
-      // retry path was the second observed source of wrong-schema
-      // output (Flash inventing field names like 'summary').
       const retryResult = await generateVerdictText(
         `The following JSON is malformed. Fix it and return ONLY valid JSON, no other text:\n\n${cleaned}`,
         30_000