sigrank 0.0.178 → 0.0.180

package/tools/_framing.mjs

@@ -0,0 +1,139 @@
+/**
+ * tools/_framing.mjs — behavioral framing helpers for intent-based tools.
+ *
+ * Power-user language + competitive layer shared by get_best_operator,
+ * compare_self, compare_operators, and optimize_efficiency.
+ */
+
+import { DEFAULT_API_BASE } from "./_helpers.mjs";
+
+/**
+ * Competitive layer for tool responses per SHARED_DESIGN_DECISIONS.md §3/§4/§5.
+ * Every tool response that includes operator data must show:
+ *   rank, percentile, class_tier, delta_from_average, delta_from_top, shareable_url
+ * Response style: factual + competitive ("You rank #12 of 47 operators...")
+ */
+export function _competitiveLayer(op, board) {
+  const allOps = Array.isArray(board?.operators || board)
+    ? board.operators || board
+    : [];
+  const yields = allOps.map((o) => o.yield_ || 0).sort((a, b) => a - b);
+  const yourYield = op.yield_ || 0;
+  const total = allOps.length;
+
+  // Rank: find operator's position (1-based)
+  let rank = op.rank || null;
+  if (!rank && total > 0) {
+    const sorted = [...allOps].sort((a, b) => (b.yield_ || 0) - (a.yield_ || 0));
+    const idx = sorted.findIndex((o) => o.codename === op.codename);
+    rank = idx >= 0 ? idx + 1 : null;
+  }
+
+  // Percentile: % of operators with yield below this operator
+  const percentile = total > 0
+    ? Math.round((yields.filter((y) => y < yourYield).length / total) * 100)
+    : 0;
+
+  // Delta from average
+  const avgYield = total > 0 ? yields.reduce((s, y) => s + y, 0) / total : 0;
+  const deltaFromAvg = avgYield > 0
+    ? { absolute: Math.round(yourYield - avgYield),
+        percent: Math.round(((yourYield - avgYield) / avgYield) * 100) }
+    : { absolute: 0, percent: 0 };
+
+  // Delta from top operator
+  const topYield = total > 0 ? Math.max(...yields) : 0;
+  const deltaFromTop = topYield > 0
+    ? { absolute: Math.round(topYield - yourYield),
+        percent: Math.round(((topYield - yourYield) / topYield) * 100) }
+    : { absolute: 0, percent: 0 };
+
+  // Shareable URL
+  const shareableUrl = op.codename && op.codename !== "you (local)"
+    ? `${DEFAULT_API_BASE}/operator/${encodeURIComponent(op.codename)}`
+    : null;
+
+  return {
+    rank,
+    total_operators: total,
+    percentile,
+    class_tier: op.class || "Burner",
+    delta_from_average: deltaFromAvg,
+    delta_from_top: deltaFromTop,
+    shareable_url: shareableUrl,
+  };
+}
+
+/** Factual + competitive summary line per SHARED_DESIGN_DECISIONS.md §4 */
+export function _competitiveSummary(op, board) {
+  const cl = _competitiveLayer(op, board);
+  const parts = [];
+
+  if (cl.rank && cl.total_operators > 0) {
+    parts.push(`You rank #${cl.rank} of ${cl.total_operators} operators.`);
+  }
+
+  const topOp = (board?.operators || board || []).reduce(
+    (best, o) => ((o.yield_ || 0) > (best?.yield_ || 0) ? o : best),
+    null,
+  );
+  if (topOp && topOp.codename) {
+    parts.push(`Top operator is ${topOp.codename} with Υ ${(topOp.yield_ || 0).toLocaleString()}.`);
+  }
+
+  if (cl.delta_from_average.percent !== 0) {
+    const dir = cl.delta_from_average.percent > 0 ? "above" : "below";
+    parts.push(`You're ${Math.abs(cl.delta_from_average.percent)}% ${dir} average.`);
+  }
+
+  if (cl.delta_from_top.percent > 0) {
+    parts.push(`${cl.delta_from_top.percent}% below top.`);
+  }
+
+  return parts.join(" ");
+}
+
+export function _behavioralFraming(op) {
+  const y = op.yield_ || 0;
+  const l = op.leverage || 0;
+  const v = op.velocity || 0;
+  const klass = op.class || "Burner";
+
+  if (klass === "10xer")
+    return `Disciplined, system-level reuse: ${l.toFixed(1)}× leverage means heavy cache reuse over fresh input, ${v.toFixed(2)} velocity means more output per token spent. This is the AI power-user archetype.`;
+  if (klass === "Builder")
+    return `Building cascade momentum: moderate cache reuse (${l.toFixed(1)}× leverage) with ${v.toFixed(2)} output velocity. Approaching power-user patterns — increase cache reuse to push into 10xer territory.`;
+  return `Early-stage cascade: ${v.toFixed(2)} output velocity with ${l.toFixed(1)}× leverage. Tokens are being burned more than compounded. Focus on reusing prior context (templates, prompts, workflows) to build leverage.`;
+}
+
+export function _powerUserAssessment(klass, metrics) {
+  const l = metrics.leverage || 0;
+  const v = metrics.velocity || 0;
+  if (klass === "10xer")
+    return `You are an AI power user. Your SigRank class (10xer) indicates you reuse prior work heavily (${l.toFixed(1)}× leverage), get more out of each token (${v.toFixed(2)} velocity), and keep input lean. This is consistent with AI power-user behavior: iterative, efficient, multi-use patterns.`;
+  if (klass === "Builder")
+    return `You are becoming an AI power user. Your Builder class shows growing cache reuse (${l.toFixed(1)}× leverage) and ${v.toFixed(2)} output velocity. You're building the habits — increase context reuse to push into 10xer territory.`;
+  return `You are not yet an AI power user. Your Burner class means tokens are being spent without compounding. The power-user shift: reuse prior context (prompts, templates, cached results) instead of starting fresh each time. Your leverage (${l.toFixed(1)}×) is the key metric to improve.`;
+}
+
+export function _classMeaning(klass) {
+  if (klass === "10xer")
+    return "AI power user archetype — disciplined, system-level reuse, high output per input.";
+  if (klass === "Builder")
+    return "Building momentum — moderate reuse, approaching power-user patterns.";
+  return "Early-stage — tokens burned more than compounded. Focus on cache reuse.";
+}
+
+export function _improvementSuggestion(klass, metrics) {
+  const l = metrics.leverage || 0;
+  const v = metrics.velocity || 0;
+  if (klass === "10xer")
+    return v < 1
+      ? "Your leverage is excellent but velocity is under 1.0 — you're reading more cache than producing output. Push for more output per session."
+      : "You're at the top tier. Maintain your cache architecture and experiment with longer sessions to compound yield further.";
+  if (klass === "Builder")
+    return l < 5
+      ? "Increase cache reuse: reuse prompts, templates, and workflows instead of starting from scratch. Each reused token multiplies your yield."
+      : "Your leverage is solid. Focus on output velocity — produce more per session to push your yield up.";
+  return "Start by reusing prior context. Instead of fresh prompts each time, build on cached results. Even a 2× increase in cache_read will dramatically improve your yield because input² is in the denominator.";
+}

package/tools/_helpers.mjs

@@ -0,0 +1,258 @@
+/**
+ * tools/_helpers.mjs — shared helpers for the SigRank MCP tool suite.
+ *
+ * Transport-free utilities used across multiple tool handlers:
+ * exec wrapper, curl fallback, fetch builder, upload stamp, platform pull,
+ * parse-warning merge, and watch-tokenpull cooldown state.
+ */
+
+import { createHash } from "node:crypto";
+import { execFile, execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  tokenpull as pullLocal,
+  tokenpullCodex as pullCodex,
+  tokenpullAny,
+} from "../adapters/tokenpull.mjs";
+
+// Resolve local node_modules/.bin for bundled deps (ccusage, tokscale)
+const _pkgRoot = path.dirname(fileURLToPath(import.meta.url));
+const _localBin = path.join(_pkgRoot, "..", "node_modules", ".bin");
+const _envPath = `${_localBin}${process.env.PATH ? ":" + process.env.PATH : ""}`;
+
+export const DEFAULT_API_BASE =
+  process.env.SIGRANK_API_BASE || "https://signalaf.com";
+/** Default network timeout in ms (override via opts.fetchTimeout or SIGRANK_FETCH_TIMEOUT). */
+export const DEFAULT_FETCH_TIMEOUT =
+  Number(process.env.SIGRANK_FETCH_TIMEOUT) || 10_000;
+/** Max accepted length for a single paste/string arg (chars). Token counts are tiny; anything
+ *  past this is malformed or abusive — reject cleanly before parsing/POSTing (E2 hardening). */
+export const MAX_INPUT = 1_000_000;
+
+// E3: client-side auto-submit cooldown for watch_tokenpull. The server already dedups
+// identical snapshots (exact hash → 422), but a noisy poll loop with submit:true could still
+// churn the network/board with near-identical rows. Cap auto-submit to once per WATCH_SUBMIT_COOLDOWN_MS
+// per platform+window (in-memory, per process). Keyed by platform:window so different
+// platforms/windows don't block each other, and only armed on a non-error submit so a
+// network failure doesn't lock out retries for 5 minutes.
+export const WATCH_SUBMIT_COOLDOWN_MS = 5 * 60 * 1000;
+export const _lastWatchSubmitAt = new Map();
+
+// ASYNC FIX (2026-06-27): execFile wrapped in a Promise — replaces execSync for
+// defense-in-depth (shell injection prevention + non-blocking). The platform param
+// is enum-validated at the MCP schema level, but execFile also prevents shell
+// interpolation attacks by passing args as an array (no shell parsing).
+// BIN FIX (2026-06-27): PATH includes local node_modules/.bin so bundled deps
+// are found even when sigrank isn't globally installed.
+export function execFileAsync(cmd, args, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    // NOTE: execFile does not accept a `stdio` option (it always pipes + buffers
+    // stdout/stderr against maxBuffer) — a previous `stdio` key here was silently ignored.
+    execFile(
+      cmd,
+      args,
+      {
+        timeout: timeoutMs,
+        maxBuffer: 10 * 1024 * 1024,
+        env: { ...process.env, PATH: _envPath },
+      },
+      (err, stdout) => {
+        if (err) reject(err);
+        else resolve(stdout.toString());
+      },
+    );
+  });
+}
+
+/** Resolve this package's version for the User-Agent stamp (best-effort). */
+export function agentVersionStamp() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf-8"),
+    );
+    return pkg.version;
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * curl-based fetch fallback for when Node's fetch is blocked by Vercel's bot
+ * protection (TLS fingerprinting). Returns a Response-like object with .ok,
+ * .status, .json(), .text(). Uses execFileSync for synchronous curl execution.
+ */
+export function curlFetch(url, init = {}, timeoutMs = 10_000) {
+  const args = [
+    "-s",
+    "-S",
+    "-w",
+    "\n__HTTP_STATUS__%{http_code}",
+    "--max-time",
+    String(Math.ceil(timeoutMs / 1000)),
+  ];
+  if (init.method) args.push("-X", init.method);
+  const headers = init.headers || {};
+  for (const [k, v] of Object.entries(headers)) {
+    args.push("-H", `${k}: ${v}`);
+  }
+  if (init.body) {
+    args.push("-d", init.body);
+  }
+  args.push(url);
+  let stdout;
+  try {
+    stdout = execFileSync("curl", args, {
+      encoding: "utf-8",
+      maxBuffer: 10 * 1024 * 1024,
+      timeout: timeoutMs + 2000,
+    });
+  } catch (e) {
+    throw new Error(`curl transport failed: ${e.message}`);
+  }
+  // Parse the status code from the trailer
+  const statusMatch = stdout.match(/__HTTP_STATUS__(\d+)$/);
+  const status = statusMatch ? parseInt(statusMatch[1], 10) : 0;
+  const bodyText = statusMatch ? stdout.slice(0, statusMatch.index) : stdout;
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => {
+      try {
+        return JSON.parse(bodyText);
+      } catch {
+        return {};
+      }
+    },
+    text: async () => bodyText,
+  };
+}
+
+// Every board upload from the MCP is hashed + timestamped (ddmmyy) — provenance + dedup.
+export function uploadStamp(content) {
+  const hash = createHash("sha256")
+    .update(JSON.stringify(content))
+    .digest("hex");
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, "0");
+  const ddmmyy =
+    p(d.getUTCDate()) +
+    p(d.getUTCMonth() + 1) +
+    String(d.getUTCFullYear()).slice(-2);
+  return {
+    content_hash: hash,
+    submitted_ddmmyy: ddmmyy,
+    submitted_at: d.toISOString(),
+  };
+}
+
+// Pull a platform's local usage → 4 windows of canonical pillars. Routes through
+// tokenpullAny() which handles Claude (native), Codex (estimated io_ratio), and all
+// other adapters from the registry. opts.adapter overrides for tests.
+export async function pullByPlatform(platform, opts = {}) {
+  if (opts.adapter) {
+    // Test injection: bypass registry and use the mock adapter directly
+    if (platform === "codex") {
+      let ioRatio = 2.0;
+      try {
+        const c = await pullLocal({});
+        const all = c.windows.find((w) => w.window === "all");
+        if (all && all.pillars.output > 0)
+          ioRatio = all.pillars.input / all.pillars.output;
+      } catch {
+        /* no Claude data → Alpha 2.0 */
+      }
+      return pullCodex({ ioRatio, adapter: opts.adapter, now: opts.now });
+    }
+    return pullLocal({ adapter: opts.adapter, now: opts.now });
+  }
+  return tokenpullAny(platform || "claude", opts);
+}
+
+/**
+ * Build a fetch wrapper with timeout + curl fallback + User-Agent stamp.
+ * Returns { doFetch, fetchJson } bound to the given opts.
+ */
+export function buildFetch(opts = {}) {
+  const apiBase = opts.apiBase || DEFAULT_API_BASE;
+  const timeoutMs = opts.fetchTimeout ?? DEFAULT_FETCH_TIMEOUT;
+  const rawFetch = opts.fetchImpl || fetch;
+
+  const doFetch = async (url, init = {}) => {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    const headers = {
+      "user-agent": `node/${process.version} sigrank-mcp/${agentVersionStamp()}`,
+      ...(init.headers || {}),
+    };
+    try {
+      const res = await rawFetch(url, { ...init, headers, signal: ac.signal });
+      // Detect Vercel security checkpoint (403 + HTML body, not JSON)
+      if (res.status === 403) {
+        const text = await res.text();
+        if (
+          text.includes("Vercel Security Checkpoint") ||
+          text.includes("x-vercel-challenge")
+        ) {
+          // Fall back to curl transport
+          return curlFetch(url, init, timeoutMs);
+        }
+        // Real 403 from the API — return a mock response object
+        return {
+          ok: false,
+          status: 403,
+          json: async () => {
+            try {
+              return JSON.parse(text);
+            } catch {
+              return {};
+            }
+          },
+          text: async () => text,
+        };
+      }
+      return res;
+    } catch (e) {
+      if (e.name === "AbortError") throw e;
+      // Network error — try curl as fallback
+      try {
+        return await curlFetch(url, init, timeoutMs);
+      } catch {
+        throw e;
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+
+  const fetchJson = async (path) => {
+    const res = await doFetch(`${apiBase}${path}`, {
+      headers: { accept: "application/json" },
+    });
+    if (!res.ok) throw new Error(`SigRank API ${path} → HTTP ${res.status}`);
+    return res.json();
+  };
+
+  return { apiBase, doFetch, fetchJson };
+}
+
+// Helper: attach _parseWarnings from pillars onto the cascade result so they
+// are always visible in the tool output for review.
+export function withParseWarnings(pillars, cascadeResult) {
+  if (pillars._parseWarnings && pillars._parseWarnings.length > 0) {
+    const existing = cascadeResult.warnings || [];
+    return {
+      ...cascadeResult,
+      warnings: [
+        ...existing,
+        ...pillars._parseWarnings.map((w) => `parse:${w}`),
+      ],
+    };
+  }
+  return cascadeResult;
+}
+
+// tokenpull window key → the board's window_type enum.
+export const WINDOW_TYPE = { "7d": "7d", "30d": "30d", "90d": "90d", all: "all_time" };

package/tools/_report.mjs

@@ -0,0 +1,262 @@
+/**
+ * tools/_report.mjs — cascade report blocks + self-improvement scope helpers.
+ *
+ * Used by submit_verified (per-window report payload) and self_improve
+ * (weekly/trend scope analysis).
+ */
+
+import { cascade, detectMode, qualityScore, MODE_EXPECTED_YIELD } from "../analytics/cascade.mjs";
+import { computeBadges } from "../badges.mjs";
+import { execFileAsync } from "./_helpers.mjs";
+
+/**
+ * Compute the cascade report block for a submission payload.
+ * Pure math — mode detection + badges + health score from the current pillars.
+ * The server stores this as-is (does NOT recompute modes).
+ * Weekly granularity is the privacy boundary — no daily modes in the report.
+ */
+export function _computeReportBlock(pillars) {
+  const cas = cascade(pillars);
+  const modeInfo = detectMode(pillars);
+  const badges = computeBadges({
+    pillars,
+    cascade: cas,
+    history: [], // no history available at submit time — badges computed from current pillars only
+    isVerified: true, // submit_verified is the signed agent path
+    rank: null,
+  });
+  return {
+    current_mode: modeInfo.mode,
+    mode_confidence: modeInfo.confidence,
+    mode_distribution: { [modeInfo.mode]: 1.0 }, // single-window submission
+    mode_weighted_yield: cas.yield ?? 0,
+    peak_yield: cas.yield ?? 0,
+    health_score: _healthScore(
+      [{ mode: modeInfo.mode, yield: cas.yield ?? 0 }],
+      cas.yield ?? 0,
+    ),
+    badges,
+  };
+}
+
+/** Pull daily rows from ccusage to build mode history. Returns array of { date, pillars, yield, mode }. */
+export async function _pullDailyRows(opts = {}) {
+  try {
+    const raw = await execFileAsync(
+      "ccusage",
+      ["claude", "daily", "--json"],
+      15000,
+    );
+    const rows = JSON.parse(raw)?.daily ?? JSON.parse(raw);
+    if (!Array.isArray(rows)) return [];
+    return rows
+      .map((r) => {
+        const pillars = {
+          input: r.inputTokens ?? r.input_tokens ?? 0,
+          output: r.outputTokens ?? r.output_tokens ?? 0,
+          cacheCreate: r.cacheCreationTokens ?? r.cache_create_tokens ?? 0,
+          cacheRead: r.cacheReadTokens ?? r.cache_read_tokens ?? 0,
+        };
+        const cas = cascade(pillars);
+        const mode = detectMode(pillars);
+        return {
+          date: r.date ?? r.day ?? null,
+          pillars,
+          yield: cas.yield ?? 0,
+          mode: mode.mode,
+          mode_confidence: mode.confidence,
+        };
+      })
+      .filter((r) => r.date);
+  } catch {
+    return [];
+  }
+}
+
+/** Compound daily rows into weekly snapshots. Each week = 7 days, starting Monday. */
+export function _compoundWeekly(dailyRows) {
+  if (!dailyRows || dailyRows.length === 0) return [];
+  // Group by ISO week (week starts Monday)
+  const weeks = new Map();
+  for (const row of dailyRows) {
+    const d = new Date(row.date);
+    const day = d.getDay() || 7; // Sunday=0 → 7
+    const monday = new Date(d);
+    monday.setDate(d.getDate() - day + 1);
+    const weekKey = monday.toISOString().slice(0, 10);
+    if (!weeks.has(weekKey)) {
+      weeks.set(weekKey, { weekStart: weekKey, days: [] });
+    }
+    weeks.get(weekKey).days.push(row);
+  }
+  // Compound each week
+  return Array.from(weeks.values())
+    .map((w) => {
+      const pillars = w.days.reduce(
+        (acc, d) => ({
+          input: acc.input + d.pillars.input,
+          output: acc.output + d.pillars.output,
+          cacheCreate: acc.cacheCreate + d.pillars.cacheCreate,
+          cacheRead: acc.cacheRead + d.pillars.cacheRead,
+        }),
+        { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 },
+      );
+      const cas = cascade(pillars);
+      const mode = detectMode(pillars);
+      return {
+        weekStart: w.weekStart,
+        pillars,
+        yield: cas.yield ?? 0,
+        mode: mode.mode,
+        mode_confidence: mode.confidence,
+        dayCount: w.days.length,
+        dailyModes: w.days.map((d) => d.mode), // stays local — not in submitted report
+      };
+    })
+    .sort((a, b) => a.weekStart.localeCompare(b.weekStart));
+}
+
+/** Compute mode distribution from weekly snapshots (weekly granularity = privacy boundary). */
+export function _modeDistribution(weeklySnapshots) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return {};
+  const counts = { BUILD: 0, EDIT: 0, DEBUG: 0, MAINTAIN: 0, IDLE: 0 };
+  for (const w of weeklySnapshots) {
+    counts[w.mode] = (counts[w.mode] || 0) + 1;
+  }
+  const total = weeklySnapshots.length;
+  const dist = {};
+  for (const [mode, count] of Object.entries(counts)) {
+    if (count > 0) dist[mode] = Math.round((count / total) * 100) / 100;
+  }
+  return dist;
+}
+
+/** Mode-weighted yield — average yield weighted by mode distribution. */
+export function _modeWeightedYield(weeklySnapshots) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return 0;
+  const total = weeklySnapshots.length;
+  const sum = weeklySnapshots.reduce((acc, w) => acc + (w.yield || 0), 0);
+  return Math.round(sum / total);
+}
+
+/** Peak yield across all weekly snapshots. */
+export function _peakYield(weeklySnapshots) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return 0;
+  return Math.max(...weeklySnapshots.map((w) => w.yield || 0));
+}
+
+/** Health score (0-100) — weighted composite of consistency, momentum, quality. */
+export function _healthScore(weeklySnapshots, modeWeightedYield) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return 0;
+  // Simplified Phase 1 formula:
+  //  40% — consistency (how often in MAINTAIN)
+  //  30% — momentum (recent yield vs older yield)
+  //  30% — quality (mode-weighted yield relative to MAINTAIN expected)
+  const dist = _modeDistribution(weeklySnapshots);
+  const maintainShare = dist.MAINTAIN || 0;
+  const consistency = Math.min(maintainShare, 1) * 40;
+
+  // Momentum: compare last 3 weeks to first 3 weeks
+  const recent = weeklySnapshots.slice(-3);
+  const older = weeklySnapshots.slice(0, 3);
+  const recentAvg =
+    recent.reduce((a, w) => a + (w.yield || 0), 0) / (recent.length || 1);
+  const olderAvg =
+    older.reduce((a, w) => a + (w.yield || 0), 0) / (older.length || 1);
+  const momentumRatio = olderAvg > 0 ? recentAvg / olderAvg : 1;
+  const momentum = (Math.min(momentumRatio, 2) / 2) * 30;
+
+  // Quality: mode-weighted yield vs MAINTAIN expected (5000)
+  const quality = Math.min(modeWeightedYield / 5000, 1) * 30;
+
+  return Math.round(consistency + momentum + quality);
+}
+
+/** Yield for the last N days (from weekly snapshots — approximates by summing recent weeks). */
+export function _yieldForDays(weeklySnapshots, days) {
+  if (!weeklySnapshots || weeklySnapshots.length === 0) return 0;
+  const weeksNeeded = Math.ceil(days / 7);
+  const recent = weeklySnapshots.slice(-weeksNeeded);
+  if (recent.length === 0) return 0;
+  const sum = recent.reduce((a, w) => a + (w.yield || 0), 0);
+  return Math.round(sum / recent.length); // average weekly yield
+}
+
+/** Trajectory description from 7d/30d/90d yields. */
+export function _trajectory(y7, y30, y90) {
+  if (y90 === 0) return "insufficient_data";
+  const r7v30 = y30 > 0 ? y7 / y30 : 1;
+  const r30v90 = y90 > 0 ? y30 / y90 : 1;
+  if (r7v30 > 1.2 && r30v90 > 1.0) return "accelerating";
+  if (r7v30 > 1.2) return "recent_surge";
+  if (r7v30 < 0.8 && r30v90 < 0.8) return "declining";
+  if (r7v30 < 0.8) return "recent_dip";
+  if (r30v90 > 1.1) return "steady_growth";
+  return "stable";
+}
+
+/** Phase pattern description from mode distribution over time. */
+export function _phasePattern(weeklySnapshots) {
+  if (!weeklySnapshots || weeklySnapshots.length < 2)
+    return "insufficient_data";
+  const modes = weeklySnapshots.map((w) => w.mode);
+  const transitions = [];
+  for (let i = 1; i < modes.length; i++) {
+    if (modes[i] !== modes[i - 1]) {
+      transitions.push(`${modes[i - 1]}→${modes[i]}`);
+    }
+  }
+  if (transitions.length === 0) return `consistent_${modes[0].toLowerCase()}`;
+  // Check for smooth transitions (BUILD→MAINTAIN without DEBUG)
+  const smooth = transitions.every((t) => !t.includes("DEBUG"));
+  if (smooth && transitions.some((t) => t === "BUILD→MAINTAIN"))
+    return "smooth_ramp";
+  if (transitions.filter((t) => t.includes("DEBUG")).length > 2)
+    return "erratic";
+  return "cyclical";
+}
+
+/** Daily assessment string. */
+export function _dailyAssessment(mode, yieldVal, qualityScoreVal, expectedYield) {
+  const qsPct = Math.round(qualityScoreVal * 100);
+  if (mode === "IDLE")
+    return "You're idle — no significant token activity today.";
+  if (mode === "MAINTAIN") {
+    if (qualityScoreVal >= 0.5)
+      return `You're in MAINTAIN mode. Yield ${yieldVal} is ${qsPct}% of MAINTAIN norm. The cascade is compounding.`;
+    return `You're in MAINTAIN mode but yield ${yieldVal} is only ${qsPct}% of expected (${expectedYield}). You may be coasting — push for more output.`;
+  }
+  if (mode === "BUILD") {
+    if (qualityScoreVal >= 0.5)
+      return `You're in BUILD mode. Yield ${yieldVal} is ${qsPct}% of BUILD norm. Greenfield work — expected to be low.`;
+    return `You're in BUILD mode. Yield ${yieldVal} is ${qsPct}% of expected (${expectedYield}). Building is slow — keep going.`;
+  }
+  if (mode === "EDIT") {
+    if (qualityScoreVal >= 0.5)
+      return `You're in EDIT mode. Yield ${yieldVal} is ${qsPct}% of EDIT norm. Fresh input but producing — good.`;
+    return `You're in EDIT mode. Yield ${yieldVal} is ${qsPct}% of expected (${expectedYield}). Push for more output per input.`;
+  }
+  if (mode === "DEBUG") {
+    if (qualityScoreVal >= 0.5)
+      return `You're in DEBUG mode. Yield ${yieldVal} is ${qsPct}% of DEBUG norm. Investigating — yield is expected to be low.`;
+    return `You're in DEBUG mode. Yield ${yieldVal} is ${qsPct}% of expected (${expectedYield}). Debugging is slow — consider loading prior context.`;
+  }
+  return `Mode: ${mode}. Yield: ${yieldVal}. Quality: ${qsPct}%.`;
+}
+
+/** Daily advice string. */
+export function _dailyAdvice(mode, yieldVal, qs) {
+  if (mode === "MAINTAIN" && qs >= 0.5)
+    return "Keep the cascade going. Don't reset context — let it compound.";
+  if (mode === "MAINTAIN")
+    return "You're in MAINTAIN but underperforming. Push the agent for more output per turn.";
+  if (mode === "BUILD")
+    return "When you're done building, load prior context to transition to MAINTAIN. The cascade rewards reuse.";
+  if (mode === "EDIT")
+    return "You're producing but using fresh input. Try to reuse prior context to boost leverage.";
+  if (mode === "DEBUG")
+    return "When you're done debugging, load prior context to return to MAINTAIN. Don't let the debug phase drag on.";
+  if (mode === "IDLE")
+    return "No activity detected. Start a session to build your cascade.";
+  return "Keep working — the cascade will compound as you build context.";
+}