@oriro/orirocli 0.1.0

package/skills/craft/vercel-optimize/references/recommendations.md

@@ -0,0 +1,214 @@
+# Recommendations
+
+How recommendations are shaped, written, sanitized, and graded.
+
+## Table of contents
+
+- [Schema](#schema)
+- [Writing rules](#writing-rules)
+- [The 12 sanitizers](#the-12-sanitizers)
+- [Envelope-unwrap recovery](#envelope-unwrap-recovery)
+- [Grading rubric](#grading-rubric)
+- [Next.js version awareness](#nextjs-version-awareness)
+
+## Schema
+
+Every recommendation is a JSON object matching this TypeScript shape:
+
+```ts
+interface Recommendation {
+  // Customer-facing
+  what: string; // 1 line, lead with impact. Max 80 chars when feasible.
+  why: string; // 1-2 sentences. Root cause. Cites codebase findings + counts.
+  fix: string; // Step-by-step. Includes before/after code fences. Specific enough to implement.
+  bucket: "cost" | "performance" | "reliability";
+  effort: "low" | "medium" | "high";
+  affectedFiles: string[]; // Verified file paths, from candidate.files
+  currentBehavior: string; // What the code does now (with snippet)
+  desiredBehavior: string; // Target state (with snippet)
+  risk?: string; // Optional: e.g., "Removing force-dynamic may serve stale data on /admin"
+  verify: string; // How to confirm the fix worked. e.g., "Re-run `vercel metrics …` and watch p95"
+
+  // Impact (computed from impact-magnitude.mjs in Step 4)
+  impactLabel: {
+    performance?: string; // PRECISE: "Reduce /api/products p95 from 850ms toward ~250-400ms"
+    costMagnitude?: "negligible" | "small" | "medium" | "large" | "very-large";
+    costPhrase?: string; // "hundreds of dollars per month at current traffic"
+    billingDimension?: string;
+    fractionReduced?: number;
+  };
+  impactTier: "high" | "medium" | "low";
+  billingDimension?:
+    | "edge-requests"
+    | "function-duration"
+    | "image-optimization"
+    | "isr-reads"
+    | "isr-writes"
+    | "bandwidth"
+    | "data-cache-reads"
+    | "cron-invocations"
+    | string;
+
+  // Grounding
+  citations: string[]; // From references/docs-library.json allow-list. Required: ≥1 entry.
+  candidateRef?: string; // The gate candidate this rec traces to (e.g., "uncached_route:/api/products")
+  findingRefs?: string[]; // File:line markers from verifiedFindings.json
+  appliesAlsoTo?: Array<{
+    // Added by dedup when matching recs collapse into one customer-facing item.
+    candidateRef?: string;
+    affectedFiles?: string[];
+    o11ySignal?: string;
+    what?: string;
+  }>;
+  corroborationCount?: number; // Number of matching verified recs folded into this item, including itself.
+
+  // Verifier output (computed in Step 3.6)
+  verification?: {
+    passRate: number;
+    failed: Array<{ type: string; text: string; reason: string }>;
+  };
+
+  // Sanitizer audit trail (computed in Step 3.4)
+  sanitizerTrail?: string[]; // ["$-strip:2", "version-mismatch:next@15+:1", ...]
+  needsReview?: boolean; // Set when a sanitizer caught a hazard
+
+  // Grading (Step 3.5)
+  quality: {
+    specificity: number; // 0-1
+    actionability: number;
+    grounding: number;
+    evidence: number;
+    overall: number;
+    grade: "Excellent" | "Good" | "Fair" | "Poor";
+  };
+}
+```
+
+## Writing rules
+
+The recommender prompt explicitly tells the agent to follow these rules. Sanitizers enforce them after generation.
+
+**Voice and tone** are governed by [`references/voice.md`](./voice.md). Read it before writing recommendation prose; it keeps reports direct, metric-grounded, and free of internal process terms.
+
+### Lead with impact
+
+The `what` field opens with the verb + the change, not the framing. Compare:
+
+- ❌ "Consider enabling caching on the /api/products route" (filler before substance)
+- ✅ "Add Cache-Control with s-maxage to /api/products" (verb-first, scope-explicit)
+
+### Cite codebase findings with line numbers
+
+The `why` must reference a verified finding from `verifiedFindings.json`:
+
+- ❌ "The route is uncached" (could apply anywhere)
+- ✅ "src/app/api/products/route.ts:22 returns Response without Cache-Control; observability shows 0% cache hit on 1.2M invocations/mo"
+
+### No $ literals in customer fields
+
+The user-mandated rule. `what`/`why`/`fix`/`impact`/`currentBehavior`/`desiredBehavior` must not contain `$N` money literals. Use magnitude framing from `impact-magnitude.mjs`.
+
+- ❌ "Save $340/mo by adding s-maxage"
+- ✅ "Hundreds of dollars per month at current traffic"
+- ✅ (precise performance) "Move 1.2M monthly invocations to the CDN; expect p95 to drop from 850ms toward ~50ms on cache hits"
+
+The `$-strip` sanitizer enforces this at output time, but the prompt should also instruct the LLM not to emit dollar literals in the first place.
+
+### Before/after code fences required
+
+`currentBehavior` shows the offending snippet. `desiredBehavior` shows the target. Language-tagged code fences. Keep both under ~20 lines.
+
+### Cite at least one URL from the library
+
+`citations[]` must contain at least one entry from `references/docs-library.json`. The `missing-citation` sanitizer drops uncited recs. The `unknown-citation` and `version-mismatch` sanitizers strip invalid citations.
+
+### Match the user's framework version
+
+Don't recommend `'use cache'` (Next 15+) to a Next 13 user. The recommender prompt receives only the citation subset valid for the user's stack — but the LLM can still hallucinate. The `version-mismatch` sanitizer catches stragglers.
+
+## The 12 sanitizers
+
+Each sanitizer records its action in `rec.sanitizerTrail` when it mutates a field. Tag format: `tag:detail`. Tags are lexically stable — downstream consumers grep them.
+
+| #   | Sanitizer                 | Trigger                                                | Action                                             | Trail tag                              |
+| --- | ------------------------- | ------------------------------------------------------ | -------------------------------------------------- | -------------------------------------- |
+| 1   | `$-strip`                 | Money-literal regex in customer field                  | Replace with "the billed cost"                     | `$-strip:N`                            |
+| 2   | `vercel-directive-strip`  | `stale-if-error` / `proxy-revalidate` in cache-control | Strip directive (Vercel CDN doesn't honor)         | `vercel-directive-strip:directive`     |
+| 3   | `rate-limit`              | Concurrency × delay > known provider rate limit        | Prepend caveat, set needsReview                    | `rate-limit:provider:prescribed/limit` |
+| 4   | `pre-release`             | Fix enables `-rc`/`-beta`/`-canary` feature            | Append "requires pre-release version" caveat       | `pre-release:pkg@version`              |
+| 5   | `middleware-conflict`     | Rec targets route covered by middleware matcher        | Append "Middleware {matcher} may intercept" caveat | `middleware-conflict:matcher`          |
+| 6   | `undeclared-dep`          | Fix imports a package not in package.json              | Prepend "Add dependency first: npm i {pkg}"        | `undeclared-dep:pkg`                   |
+| 7   | `count-correct`           | Cited count > verified count, ground-truth known       | Rewrite to "~N" with verified count                | `count-correct:token:cited→actual`     |
+| 8   | `count-strip`             | Cited count > verified count, no ground truth          | Rewrite to "a number of"                           | `count-strip:token`                    |
+| 9   | `rendering-mode-mislabel` | Rec blames ISR/SSR on a static page                    | Append warning, set needsReview                    | `rendering-mode-mislabel`              |
+| 10  | `unknown-citation`        | URL not in `references/docs-library.json`              | Strip URL, set needsReview if all stripped         | `unknown-citation:url`                 |
+| 11  | `version-mismatch`        | URL's `applicableFrameworks` doesn't match stack       | Strip URL, set needsReview if all stripped         | `version-mismatch:url`                 |
+| 12  | `missing-citation`        | `citations.length === 0` after other sanitizers        | DROP rec entirely                                  | (rec not emitted; counted at end)      |
+
+The sanitizer order matters: dollar-strip runs first (cheap, deterministic), then content sanitizers, then citation sanitizers last. This guarantees citation count is computed against the final state.
+
+The `recordSanitizer(rec, tag)` helper is the single entry point — sanitizers MUST call it before mutating fields. Otherwise the audit trail rots.
+
+### Provider rate limits
+
+Used by sanitizer #3. These provider limits are public contract values:
+
+| Provider  | Limit   | Doc URL                                                |
+| --------- | ------- | ------------------------------------------------------ |
+| Notion    | 3 rps   | https://developers.notion.com/reference/request-limits |
+| OpenAI    | 30 rps  | https://platform.openai.com/docs/guides/rate-limits    |
+| Stripe    | 100 rps | https://docs.stripe.com/rate-limits                    |
+| Anthropic | 10 rps  | https://docs.anthropic.com/en/api/rate-limits          |
+
+Tiers/plans differ; these are first-tier defaults. The sanitizer prepends a caveat if the rec prescribes higher concurrency.
+
+## Envelope-unwrap recovery
+
+Not a sanitizer — a recovery step. LLMs occasionally wrap their JSON output in an envelope:
+
+```json
+{ "data": { "recommendations": [...] } }
+{ "result": { "recommendations": [...] } }
+{ "insights": { "recommendations": [...] } }
+```
+
+`attemptManualRecovery` peels one wrapping layer before schema validation. Increments `hygieneCounters.envelopeUnwraps`. Logs the unwrap to the run log.
+
+This is the only "creative" parsing the skill does. Anything else that fails schema validation is rejected.
+
+## Grading rubric
+
+Each rec is scored on four axes, 0-1 each. Average → grade:
+
+| Axis          | What it measures                            | Strong (1.0) signal                                                                        |
+| ------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Specificity   | Concrete files, line numbers, code snippets | Triple-backtick code fence OR inline code ≥10 chars + verified file path                   |
+| Actionability | Clear "do this then that" steps             | Numbered steps; verbs present in each step; no "consider"/"might"                          |
+| Grounding     | Claims trace to findings or metric data     | `sourceIndex` matches a finding OR rec has affectedFiles + code fences (presumed evidence) |
+| Evidence      | Numeric, observed claims                    | Count words (errors, queries, invocations) + units (% / ms / s / K / M)                    |
+
+Grade thresholds:
+
+- `Excellent` ≥ 0.85
+- `Good` 0.70 – 0.85
+- `Fair` 0.55 – 0.70
+- `Poor` < 0.55 → dropped at quality floor in Step 4
+
+## Next.js version awareness
+
+The recommender's citation library is filtered by `signals.json.stack.framework@frameworkVersion`. The agent should still self-check the version when picking which APIs to recommend:
+
+| Feature                            | Available   | Notes                                          |
+| ---------------------------------- | ----------- | ---------------------------------------------- |
+| App Router                         | Next ≥ 13.0 | Default since 14                               |
+| `generateStaticParams`             | Next ≥ 13.0 | Replaces getStaticPaths for App Router         |
+| Fetch `next: { revalidate }`       | Next ≥ 13.0 | Note: default fetch caching flipped in Next 15 |
+| `unstable_cache`                   | Next 14-15  | Replaced by 'use cache' in 16                  |
+| `'use cache'` directive            | Next ≥ 15.0 | Persistent cache primitive                     |
+| `cacheLife()`, `cacheTag()`        | Next ≥ 15.0 | Pairs with 'use cache'                         |
+| `after()`                          | Next ≥ 15.0 | Non-blocking post-response work                |
+| Partial Prerendering               | Next ≥ 15.0 | Stable target later — verify per release       |
+| `revalidateTag` / `revalidatePath` | Next ≥ 13.4 | Tag-based on-demand invalidation               |
+| `cookies()` / `headers()` async    | Next ≥ 15.0 | Async pattern in 15+                           |
+
+The skill's curated citation library encodes these constraints via `applicableFrameworks`. If a contributor adds a new Next.js feature URL, they MUST set the right semver range in `references/docs-library.json`.

package/skills/craft/vercel-optimize/references/scanner-patterns.md

@@ -0,0 +1,266 @@
+<!-- THIS FILE IS GENERATED by scripts/build-docs.mjs. Do not edit by hand. -->
+<!-- To change scanner descriptions, edit lib/scanners/*.mjs metadata exports. -->
+<!-- To change gate thresholds, edit lib/gates/*.mjs metadata exports. -->
+
+# Scanner patterns
+
+AST/grep-style scanners run in parallel with metric-driven investigation. They find known anti-patterns. Findings on cold-path or unmappable files are dropped unless the scanner declares `trafficIndependent: true`.
+
+Total scanners: 15.
+
+## Patterns
+
+### `cache-components-suspense-dedupe` — 'use cache' with multiple Suspense boundaries on the same data
+
+- **Severity**: medium
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** Default `'use cache'` does not dedupe identical calls across separate `<Suspense>` boundaries on the same render. Each boundary re-invokes the cached function, multiplying function-duration cost and inflating ISR write churn when the output is large.
+
+**Fix.** Hoist the promise to the page level (`const dataPromise = fetchData()` at the top, passed down to each Suspense child) OR move the shared fetch into a `'use cache: remote'` data-access layer so cross-request and cross-boundary dedupe applies.
+
+**Citations:**
+
+- `https://nextjs.org/docs/app/api-reference/directives/use-cache`
+- `https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents`
+- `https://nextjs.org/docs/app/guides/migrating-to-cache-components`
+
+---
+
+### `edge-heavy-import` — Heavy / node-only import inside edge-runtime file
+
+- **Severity**: high
+- **Billing dimension**: function-duration
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** Edge runtime is a constrained sandbox with no node: builtins and a much smaller cold-start budget than Node functions. Heavy SDKs (sharp, @aws-sdk/\*, @prisma/client, pg, puppeteer) either fail at deploy or inflate cold-start latency. Move the import to a Node runtime function, or replace with an edge-compatible alternative (e.g., neon-driver instead of pg).
+
+**Fix.** Either (a) drop the `export const runtime = 'edge'` so the route runs on Node (default in 2026), or (b) replace the heavy import with an edge-compatible alternative. For DB: use @neondatabase/serverless or @planetscale/database instead of pg/mysql2. For image: do the work in a Node route handler. For auth signing: use jose (Web Crypto) instead of jsonwebtoken.
+
+**Citations:**
+
+- `https://vercel.com/docs/functions/runtimes/edge-runtime`
+- `https://vercel.com/docs/fluid-compute`
+
+---
+
+### `force-dynamic` — export const dynamic = 'force-dynamic'
+
+- **Severity**: medium
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** force-dynamic disables static + ISR rendering. The route runs the function on every request. Sometimes necessary (cookies, headers, real-time data), often a habit that costs function-duration and edge-requests at scale.
+
+**Fix.** Audit the route. If dynamic behavior comes from cookies()/headers()/searchParams, force-dynamic may be redundant — Next infers dynamic automatically. Consider revalidate / 'use cache' / generateStaticParams if any portion can be pre-rendered.
+
+**Citations:**
+
+- `https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config`
+
+---
+
+### `headers-in-page` — Dynamic API call forcing dynamic rendering
+
+- **Severity**: medium
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** headers(), cookies(), and draftMode() are dynamic APIs. Reading them in a page/layout makes the entire segment dynamic — no ISR, no static generation, and a function invocation on every request.
+
+**Fix.** Move the dynamic API call into a child Server Component that lives inside a Suspense boundary. The parent can stay static; only the leaf re-renders dynamically.
+
+**Citations:**
+
+- `https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config`
+- `https://nextjs.org/docs/app/building-your-application/caching`
+
+---
+
+### `large-static-asset` — Large file in public/
+
+- **Severity**: medium
+- **Billing dimension**: bandwidth
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** Static assets in `public/` over 500 KB ship as-is from the CDN. Whether the cost is meaningful depends on traffic, but the candidate is binary — the file is either needed at that size or it can be optimized (compressed image, video transcode, or moved off the critical path).
+
+**Fix.** Verify the asset is reachable on the customer-facing hot path. Then choose: (a) compress (convert PNG → AVIF/WebP; transcode MP4 to lower bitrate); (b) host externally (Vercel Blob, S3, or a media CDN with per-asset signed URLs); (c) lazy-load (defer to client-side fetch instead of bundling into initial HTML).
+
+**Citations:**
+
+- `https://vercel.com/docs/manage-cdn-usage`
+- `https://vercel.com/docs/image-optimization`
+
+---
+
+### `max-age-without-s-maxage` — Cache-Control: max-age without s-maxage
+
+- **Severity**: medium
+- **Billing dimension**: edge-requests
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** max-age caches in the browser; s-maxage caches at the CDN. Without s-maxage, every uncached visitor request invokes the function. Adding s-maxage often cuts function invocations by 80%+ on read-heavy routes.
+
+**Fix.** Add s-maxage to the Cache-Control header. Example: Cache-Control: public, max-age=60, s-maxage=600, stale-while-revalidate=86400. Pair with explicit cache-bust strategy if content can change.
+
+**Citations:**
+
+- `https://vercel.com/docs/caching/cdn-cache`
+- `https://vercel.com/docs/caching/cache-control-headers`
+
+---
+
+### `middleware-broad-matcher` — Middleware matcher missing or too broad
+
+- **Severity**: high
+- **Billing dimension**: edge-requests
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** middleware.ts without a config.matcher (or matcher: ["/(.*)"]) runs on every request including \_next/static, \_next/image, favicon.ico, and image asset fetches. Edge-request cost scales accordingly.
+
+**Fix.** Scope the matcher to actual application paths. Example: matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)"]
+
+**Citations:**
+
+- `https://nextjs.org/docs/app/building-your-application/routing/middleware`
+
+---
+
+### `missing-cache-headers` — Cacheable route or fetch with no caching (Cache-Control absent or no-store)
+
+- **Severity**: medium
+- **Billing dimension**: edge-requests
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** Two antipatterns: (a) GET handlers without explicit Cache-Control headers serve uncached; (b) fetch() calls with cache:"no-store" or next:{revalidate:0} opt out of caching even on cacheable upstream data. For non-auth routes / fetches, both are leaving cache hits on the floor.
+
+**Fix.** For GET handlers: return a Response with Cache-Control: public, s-maxage=<seconds>, stale-while-revalidate=<window>. For fetch(): drop cache:"no-store" (use { next: { revalidate: <seconds> } } in Next.js) so the response is cached by the framework + CDN.
+
+**Citations:**
+
+- `https://vercel.com/docs/caching/cdn-cache`
+- `https://vercel.com/docs/caching/cache-control-headers`
+- `https://nextjs.org/docs/app/building-your-application/caching`
+
+---
+
+### `prisma-include-tree-bloat` — Deep Prisma include tree (3+ levels)
+
+- **Severity**: high
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** Nested .include({ x: { include: { y: { include: { z: ... } } } } }) makes Prisma issue a single huge join that scales O(N*M*K). Function duration explodes, memory spikes, often causes timeouts.
+
+**Fix.** Replace with explicit .findMany() calls or scoped .include() of only what the consumer reads. Consider Prisma.select() to project specific fields. For lists, batch with DataLoader patterns.
+
+**Citations:**
+
+- `vercel-react-best-practices:server-parallel-fetching`
+
+---
+
+### `region-pin-in-config` — Function region pinned in config
+
+- **Severity**: low
+- **Billing dimension**: function-duration
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** vercel.json `regions` or per-route `preferredRegion` is set. If the pinned region is far from the dominant user geo (or far from a data source) p95 TTFB suffers. This scanner provides the configured-region signal so the region-misconfig gate can recommend an audit.
+
+**Fix.** Audit the pinned region against traffic geography (Speed Insights or Web Analytics by country) and data-source location. Consider multi-region if data lives in a fixed location and users are global; consider relocating if users are concentrated in one geography.
+
+**Citations:**
+
+- `https://vercel.com/docs/functions/configuring-functions/region`
+- `https://vercel.com/docs/functions/configuring-functions/region`
+
+---
+
+### `source-maps-production` — Source maps enabled in production
+
+- **Severity**: low
+- **Billing dimension**: edge-requests
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** productionBrowserSourceMaps: true ships .map files in the production bundle, increasing transfer size 30-100% per visitor. Useful for error reporting via Sentry; not useful for users.
+
+**Fix.** Keep source maps generation but exclude them from the public bundle. Upload to your error tracker via build-time CI step; do not serve them with the deployment.
+
+**Citations:**
+
+- `https://nextjs.org/docs/messages/improper-devtool`
+
+---
+
+### `sveltekit-prerender-missing` — SvelteKit page without explicit prerender / ISR config
+
+- **Severity**: low
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** SvelteKit page or +page.server.ts is missing an explicit `prerender`, `ssr`, or adapter `config.isr` declaration. Default is per-request function execution — investigate whether the route could be prerendered or ISR-cached.
+
+**Fix.** If the page is static (no per-user / per-request data), add `export const prerender = true` in +page.ts or +page.server.ts. If the data refreshes on a schedule, prefer adapter-vercel's ISR option via `export const config = { isr: { expiration: 60 } }`.
+
+**Citations:**
+
+- `https://kit.svelte.dev/docs/page-options`
+- `https://kit.svelte.dev/docs/adapter-vercel`
+- `https://vercel.com/docs/incremental-static-regeneration`
+
+---
+
+### `turbo-force-bypass` — Turborepo cache bypass on a monorepo
+
+- **Severity**: high
+- **Billing dimension**: build
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** Turborepo's per-task cache can be bypassed by an explicit force flag, a `cache: false` config, or missing build-skip configuration. Every commit can rebuild unchanged work; Build Minutes climb with project count.
+
+**Fix.** Remove `TURBO_FORCE=true` from build env/scripts unless intentional. Set `tasks.build.cache: true` in `turbo.json` (or remove the override), and include generated outputs in Turbo's cache contract. Prefer Vercel's skip-unaffected monorepo behavior when available; use `ignoreCommand` only when that setting cannot cover the project.
+
+**Citations:**
+
+- `https://vercel.com/docs/monorepos`
+- `https://vercel.com/docs/builds`
+- `https://turborepo.dev/docs/crafting-your-repository/caching`
+
+---
+
+### `unoptimized-image` — Image optimization gap (raw <img>, global flag, missing sizes, or SVG mis-routed)
+
+- **Severity**: high
+- **Billing dimension**: image-optimization
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** Four shapes of image-cost waste: raw <img> tags bypass the framework Image component; `images.unoptimized: true` disables Vercel image optimization globally; <Image fill> without `sizes` forces serving the largest source variant; <Image src=".svg"> without `unoptimized` routes vector data through the raster pipeline.
+
+**Fix.** For raw <img>: switch to next/image, enhanced-img (SvelteKit), <Image /> (Astro), or NuxtImg. For global unoptimized:true: remove the flag unless the project is hosted outside Vercel. For fill without sizes: add `sizes="(max-width: 768px) 100vw, 50vw"` or whatever matches your layout. For SVG: add `unoptimized` so the raw SVG ships instead of rastering it.
+
+**Citations:**
+
+- `https://nextjs.org/docs/app/api-reference/components/image`
+- `https://vercel.com/docs/image-optimization`
+
+---
+
+### `use-cache-date-stamp` — new Date() / Date.now() / Math.random() inside a 'use cache' file
+
+- **Severity**: high
+- **Billing dimension**: isr
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** `'use cache'` memoizes by argument identity AND prerender output. A timestamp baked into the cached output (`new Date().getFullYear()` in a footer, `Date.now()` in a payload field) forces a fresh ISR write on every regeneration even when the underlying data is unchanged. Random values have the same failure mode.
+
+**Fix.** Replace module-scope `new Date()` with a build-time constant (`const buildYear = new Date().getFullYear()`) or move per-request timestamps into a client component inside `useEffect`. Do not pass dates as arguments to `'use cache'` functions — they invalidate the cache every call.
+
+**Citations:**
+
+- `https://nextjs.org/docs/app/api-reference/directives/use-cache`
+- `https://nextjs.org/docs/app/api-reference/functions/cacheLife`
+
+---