atris 3.35.0 → 3.37.0

package/lib/wish-design.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DESIGN_BRIEF_PATHS = [
+  path.join('atris', 'skills', 'design', 'SKILL.md'),
+  path.join('atris', 'policies', 'atris-design.md'),
+  path.join('.atris', 'theme.json'),
+];
+
+const FRONTEND_WISH_RE = /\b(ui|page|design|frontend|component|style|theme|landing|dashboard|layout|css|button|font|color|hero|nav|cards?)\b/i;
+const NEGATIVE_COLLOCATION_RE = /\b(?:code\s+style|page\s+size|button\s+up)\b/i;
+const BACKEND_CONTEXT_RE = /\b(?:api|json|endpoint|terminal|log|logs|deploy|release|script|build|pipeline|step|compress|minify|server|cache|config|webhook|payloads?|secrets?)\b/i;
+const PATH_CONTEXT_RE = /(?:^|\s)(?:lib|bin|scripts)\/|\b[A-Za-z0-9_.-]+\/[A-Za-z0-9_.\/-]+\b/;
+const WEAK_FRONTEND_RE = /\b(?:page|design|style|theme|screen|button|font|color|landing)\b/i;
+const WEAK_ASSET_SURFACE_RE = /\b(?:cards?|images?)\b/i;
+const VISUAL_PERCEPTION_RE = /\b(?:cramped|spacing|padding|whitespace|dense|crowded|looks?\s+like|looks|boring|bland|ugly|prettier|pretty|beautiful|gorgeous|plain|breathing\s+room|washes?\s+out)\b/i;
+const UI_SURFACE_RE = /\b(?:bar|headers?|footers?|toolbar|sidebar|modal|dropdown|tooltip|screen|website|site|mobile|viewport|cards?|charts?)\b/i;
+const SOLID_UI_SURFACE_RE = /\b(?:bar|headers?|footers?|toolbar|sidebar|modal|dropdown|tooltip|website|site|mobile|viewport|cards?|charts?)\b/i;
+const STATE_COLLOCATION_RE = /\b(?:empty|loading|error)\s+state\b/i;
+const STRONG_FRONTEND_RE = /\b(?:ui|frontend|component|dashboard|layout|css|hero|nav)\b/i;
+const FOLD_COLLOCATION_RE = /\b(?:above\s+the\s+fold|below\s+the\s+fold|the\s+fold|fold)\b/i;
+const MODE_COLLOCATION_RE = /\bdark\s+mode\b/i;
+
+function toPosixPath(value) {
+  return String(value || '').split(path.sep).join('/');
+}
+
+function readPackageJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function detectDesignContext(workspaceRoot = process.cwd()) {
+  const root = path.resolve(workspaceRoot || process.cwd());
+  const briefPaths = [];
+
+  for (const relativePath of DESIGN_BRIEF_PATHS) {
+    if (fs.existsSync(path.join(root, relativePath))) briefPaths.push(toPosixPath(relativePath));
+  }
+
+  const packagePath = path.join(root, 'package.json');
+  let auditCommand = null;
+  if (fs.existsSync(packagePath)) {
+    const manifest = readPackageJson(packagePath);
+    const scripts = manifest && typeof manifest === 'object' ? manifest.scripts : null;
+    if (scripts && Object.prototype.hasOwnProperty.call(scripts, 'audit:design')) {
+      briefPaths.push('package.json');
+      auditCommand = 'npm run audit:design';
+    }
+  }
+
+  return {
+    hasDesign: briefPaths.length > 0,
+    briefPaths,
+    auditCommand,
+  };
+}
+
+function isFrontendWish(text) {
+  const raw = String(text || '');
+  if (!raw.trim()) return false;
+  if (NEGATIVE_COLLOCATION_RE.test(raw)) return false;
+  if (/\blanding\b(?!\s+page\b)/i.test(raw)) return false;
+
+  const weakMatches = raw.match(new RegExp(WEAK_FRONTEND_RE.source, 'gi')) || [];
+  const visualPositive = VISUAL_PERCEPTION_RE.test(raw) || FOLD_COLLOCATION_RE.test(raw) || MODE_COLLOCATION_RE.test(raw);
+  const backendContext = BACKEND_CONTEXT_RE.test(raw) || PATH_CONTEXT_RE.test(raw);
+  if (backendContext
+    && WEAK_ASSET_SURFACE_RE.test(raw)
+    && !STRONG_FRONTEND_RE.test(raw)
+    && !visualPositive
+    && !STATE_COLLOCATION_RE.test(raw)
+    && !/\blanding\s+page\b/i.test(raw)) {
+    return false;
+  }
+  const weakOnly = weakMatches.length > 0
+    && !STRONG_FRONTEND_RE.test(raw)
+    && !visualPositive
+    && !UI_SURFACE_RE.test(raw)
+    && !STATE_COLLOCATION_RE.test(raw)
+    && !/\blanding\s+page\b/i.test(raw);
+  if (weakOnly && backendContext) return false;
+  const backendWeakOnly = weakMatches.length > 0
+    && backendContext
+    && !STRONG_FRONTEND_RE.test(raw)
+    && !visualPositive
+    && !SOLID_UI_SURFACE_RE.test(raw)
+    && !STATE_COLLOCATION_RE.test(raw)
+    && !/\blanding\s+page\b/i.test(raw);
+  if (backendWeakOnly) return false;
+
+  return STATE_COLLOCATION_RE.test(raw)
+    || visualPositive
+    || UI_SURFACE_RE.test(raw)
+    || FOLD_COLLOCATION_RE.test(raw)
+    || MODE_COLLOCATION_RE.test(raw)
+    || /\blanding\s+page\b/i.test(raw)
+    || STRONG_FRONTEND_RE.test(raw)
+    || FRONTEND_WISH_RE.test(raw);
+}
+
+module.exports = {
+  detectDesignContext,
+  isFrontendWish,
+};

package/lib/wish-stats.js

@@ -0,0 +1,183 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { readWishEvents, readWishes } = require('./wish-store');
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+
+function parseTime(value) {
+  const parsed = Date.parse(value || '');
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function countInWindow(items, now, startOffset, endOffset, timeFn) {
+  const start = now - endOffset;
+  const end = now - startOffset;
+  return items.filter((item) => {
+    const time = timeFn(item);
+    return time !== null && time >= start && time < end;
+  }).length;
+}
+
+function wishCreatedTime(wish) {
+  return parseTime(wish && (wish.first_ts || wish.ts));
+}
+
+function reviewTime(review) {
+  return parseTime(review && review.ts);
+}
+
+function isShippedWish(wish) {
+  const status = String(wish && wish.status || '').trim();
+  const verifyStatus = String(wish && wish.verify_status || '').trim();
+  return status === 'complete'
+    || status === 'completed'
+    || ['verified', 'passed', 'success'].includes(verifyStatus);
+}
+
+function formatRatio(top, bottom) {
+  if (!bottom) return '0.00';
+  return (top / bottom).toFixed(2);
+}
+
+function formatAverage(scores) {
+  if (!scores.length) return 'n/a';
+  const value = scores.reduce((sum, score) => sum + score, 0) / scores.length;
+  return Number.isInteger(value) ? String(value) : value.toFixed(2);
+}
+
+function scoresInWindow(reviews, now, startOffset, endOffset) {
+  const start = now - endOffset;
+  const end = now - startOffset;
+  return reviews
+    .filter((review) => {
+      const time = reviewTime(review);
+      return time !== null && time >= start && time < end;
+    })
+    .map((review) => review.review_score)
+    .filter((score) => score !== undefined && score !== null && String(score).trim() !== '')
+    .map((score) => Number(score))
+    .filter((score) => Number.isFinite(score));
+}
+
+function readJsonFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function missionReceiptFiles(root = process.cwd()) {
+  const runsDir = path.join(root, 'atris', 'runs');
+  try {
+    return fs.readdirSync(runsDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && /^mission-.*\.json$/.test(entry.name))
+      .map((entry) => path.join(runsDir, entry.name));
+  } catch {
+    return [];
+  }
+}
+
+function verifierPassed(receipt) {
+  const bools = [
+    receipt && receipt.verifier_result && receipt.verifier_result.passed,
+    receipt && receipt.result && receipt.result.verifier_result && receipt.result.verifier_result.passed,
+    receipt && receipt.result && receipt.result.tick && receipt.result.tick.verifier_passed,
+    receipt && receipt.result && receipt.result.passed,
+  ];
+  for (const value of bools) {
+    if (typeof value === 'boolean') return value;
+  }
+  const statuses = [
+    receipt && receipt.verifier_result && receipt.verifier_result.status,
+    receipt && receipt.result && receipt.result.verifier_result && receipt.result.verifier_result.status,
+  ];
+  for (const value of statuses) {
+    const status = Number(value);
+    if (Number.isInteger(status)) return status === 0;
+  }
+  return false;
+}
+
+function haikuRates(root = process.cwd()) {
+  const rates = {
+    haiku: { passed: 0, total: 0 },
+    other: { passed: 0, total: 0 },
+  };
+  for (const file of missionReceiptFiles(root)) {
+    const receipt = readJsonFile(file);
+    if (!receipt || (receipt.schema && receipt.schema !== 'atris.mission_receipt.v1')) continue;
+    const runner = String(receipt.result && receipt.result.frozen && receipt.result.frozen.runner || '').trim().toLowerCase();
+    if (!runner) continue;
+    const bucket = runner === 'haiku' ? rates.haiku : rates.other;
+    bucket.total += 1;
+    if (verifierPassed(receipt)) bucket.passed += 1;
+  }
+  return rates;
+}
+
+function buildWishStats(root = process.cwd(), options = {}) {
+  const now = Number.isFinite(options.now) ? options.now : Date.now();
+  const wishes = readWishes(root);
+  const reviews = readWishEvents(root).filter((event) => event && event.kind === 'review');
+  const shipped = wishes.filter(isShippedWish);
+  const thisWeekWishes = countInWindow(wishes, now, 0, WEEK_MS, wishCreatedTime);
+  const priorWeekWishes = countInWindow(wishes, now, WEEK_MS, WEEK_MS * 2, wishCreatedTime);
+  const thisWeekScores = scoresInWindow(reviews, now, 0, WEEK_MS);
+  const priorWeekScores = scoresInWindow(reviews, now, WEEK_MS, WEEK_MS * 2);
+  const rates = haikuRates(root);
+  const lines = [
+    `wishes this week: ${thisWeekWishes}, prior week ${priorWeekWishes}`,
+    `reviews per shipped wish: ${formatRatio(reviews.length, shipped.length)}`,
+    `average score trend: ${formatAverage(thisWeekScores)} this week, ${formatAverage(priorWeekScores)} prior week`,
+    `haiku pass rate: ${rates.haiku.passed}/${rates.haiku.total}, all other runners ${rates.other.passed}/${rates.other.total}`,
+  ];
+  return {
+    lines,
+    wishes_this_week: thisWeekWishes,
+    wishes_prior_week: priorWeekWishes,
+    reviews_per_shipped_wish: formatRatio(reviews.length, shipped.length),
+    average_score_this_week: formatAverage(thisWeekScores),
+    average_score_prior_week: formatAverage(priorWeekScores),
+    haiku: rates.haiku,
+    other: rates.other,
+  };
+}
+
+function localDateName(date = new Date()) {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+
+function wishStatsLogPath(root = process.cwd(), date = new Date()) {
+  return path.join(root, 'atris', 'logs', String(date.getFullYear()), `${localDateName(date)}.md`);
+}
+
+function writeWishStats(root = process.cwd(), lines = [], options = {}) {
+  const date = options.date instanceof Date ? options.date : new Date();
+  const file = wishStatsLogPath(root, date);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const prefix = existing.trim() ? '\n\n' : '';
+  fs.appendFileSync(file, `${prefix}## Wish stats\n${lines.join('\n')}\n`, 'utf8');
+  return file;
+}
+
+function printWishStats(root = process.cwd(), options = {}) {
+  const stats = buildWishStats(root, options);
+  if (options.write) writeWishStats(root, stats.lines, options);
+  console.log(stats.lines.join('\n'));
+  return 0;
+}
+
+module.exports = {
+  buildWishStats,
+  haikuRates,
+  missionReceiptFiles,
+  printWishStats,
+  verifierPassed,
+  wishStatsLogPath,
+  writeWishStats,
+};

package/lib/wish-store.js

@@ -0,0 +1,354 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { nextRecordNumber } = require('./short-name');
+
+function stateFile(root = process.cwd()) {
+  return path.join(root, '.atris', 'state', 'wishes.jsonl');
+}
+
+function stampIso() {
+  return new Date().toISOString();
+}
+
+function todayName(date = new Date()) {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+
+function slugify(value) {
+  return String(value || 'wish')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 36) || 'wish';
+}
+
+function wishId(text, ts = stampIso()) {
+  const hash = crypto.createHash('sha1').update(`${text}:${ts}`).digest('hex').slice(0, 8);
+  return `wish-${todayName(new Date(ts))}-${slugify(text)}-${hash}`;
+}
+
+function appendJsonLine(file, record) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, `${JSON.stringify(record)}\n`, 'utf8');
+  return file;
+}
+
+function appendWishRecord(root, record) {
+  return appendJsonLine(stateFile(root), record);
+}
+
+function nextWishNumber(root = process.cwd()) {
+  return nextRecordNumber(readJsonLines(stateFile(root)));
+}
+
+function readJsonLines(file) {
+  if (!fs.existsSync(file)) return [];
+  return fs.readFileSync(file, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function eventAnswers(event) {
+  const answers = [];
+  for (const key of ['answer', 'answer_text', 'grant_answer']) {
+    const value = event && event[key];
+    if (String(value || '').trim()) answers.push(String(value));
+  }
+  if (Array.isArray(event && event.answers)) {
+    answers.push(...event.answers.map(String).filter((value) => value.trim()));
+  }
+  return answers;
+}
+
+function readWishEvents(root = process.cwd()) {
+  return readJsonLines(stateFile(root));
+}
+
+function readWishes(root = process.cwd()) {
+  const byId = new Map();
+  for (const event of readWishEvents(root)) {
+    if (event && event.kind === 'steer') {
+      const wishId = String(event.wish_id || '').trim();
+      if (!wishId) continue;
+      const current = byId.get(wishId) || {
+        id: wishId,
+        ts: event.ts,
+        text: '',
+        answers: [],
+        reviews: [],
+        steers: [],
+        first_ts: event.ts,
+      };
+      const steer = {
+        ts: event.ts,
+        note: event.note || '',
+        steered_by: event.steered_by || null,
+        mission_id: event.mission_id || null,
+      };
+      const steers = [...(current.steers || []), steer];
+      byId.set(wishId, {
+        ...current,
+        steers,
+        steer_count: steers.length,
+        latest_steer: steer,
+      });
+      continue;
+    }
+    if (event && event.kind === 'review') {
+      const wishId = String(event.wish_id || '').trim();
+      if (!wishId) continue;
+      const current = byId.get(wishId) || {
+        id: wishId,
+        ts: event.ts,
+        text: '',
+        answers: [],
+        reviews: [],
+        steers: [],
+        first_ts: event.ts,
+      };
+      const review = {
+        ts: event.ts,
+        review_text: event.review_text || '',
+        review_score: event.review_score === undefined ? null : event.review_score,
+        reviewed_by: event.reviewed_by || null,
+      };
+      const reviews = [...(current.reviews || []), review];
+      byId.set(wishId, {
+        ...current,
+        reviews,
+        reviewed: true,
+        review_count: reviews.length,
+        latest_review: review,
+      });
+      continue;
+    }
+    if (!event || !event.id) continue;
+    const current = byId.get(event.id) || {
+      id: event.id,
+      ts: event.ts,
+      text: event.text || '',
+      answers: [],
+      reviews: [],
+      steers: [],
+      first_ts: event.ts,
+    };
+    const next = {
+      ...current,
+      ...event,
+      first_ts: current.first_ts || event.ts,
+      answers: current.answers || [],
+      reviews: current.reviews || [],
+      steers: current.steers || [],
+    };
+    const answers = eventAnswers(event);
+    if (answers.length) next.answers = [...next.answers, ...answers];
+    byId.set(event.id, next);
+  }
+  return Array.from(byId.values())
+    .sort((a, b) => String(a.first_ts || a.ts || '').localeCompare(String(b.first_ts || b.ts || '')));
+}
+
+function improveCursorFile(root = process.cwd()) {
+  return path.join(root, '.atris', 'state', 'wish-improve.cursor.json');
+}
+
+function lessonsFile(root = process.cwd()) {
+  return path.join(root, '.claude', 'skills', 'wish', 'LESSONS.md');
+}
+
+const LESSONS_HEADER = [
+  '# Wish lessons',
+  '',
+  'Reviews from `atris wish review` land here via `atris wish improve`.',
+  'The model running the wish skill distills raw inbox entries into one-line lessons, then deletes the raw entries.',
+  '',
+  '## Lessons',
+  '',
+  '## Review inbox (raw, distill me)',
+  '',
+].join('\n');
+
+function readImproveCursor(root = process.cwd()) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(improveCursorFile(root), 'utf8'));
+    return String((parsed && parsed.last_ts) || '');
+  } catch {
+    return '';
+  }
+}
+
+function writeImproveCursor(root, lastTs) {
+  const file = improveCursorFile(root);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify({ last_ts: lastTs, updated: stampIso() }, null, 2)}\n`, 'utf8');
+}
+
+function readLessonsSection(root, heading, cap = Infinity) {
+  try {
+    const content = fs.readFileSync(lessonsFile(root), 'utf8');
+    const match = content.match(new RegExp(`## ${heading}\\n([\\s\\S]*?)(?=\\n## |$)`));
+    if (!match) return [];
+    return match[1]
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.startsWith('- '))
+      .slice(0, cap);
+  } catch {
+    return [];
+  }
+}
+
+function readWishLessonLines(root = process.cwd(), cap = 10) {
+  return readLessonsSection(root, 'Lessons', cap);
+}
+
+function wishLessonsSummary(root = process.cwd()) {
+  const scores = readWishEvents(root)
+    .filter((event) => event && event.kind === 'review' && typeof event.review_score === 'number')
+    .sort((a, b) => String(a.ts || '').localeCompare(String(b.ts || '')))
+    .map((event) => event.review_score);
+  const avg = (list) => (list.length ? Number((list.reduce((s, n) => s + n, 0) / list.length).toFixed(2)) : null);
+  return {
+    lessons: readLessonsSection(root, 'Lessons'),
+    pruned: readLessonsSection(root, 'Pruned \\(did not move the score\\)'),
+    inbox: readLessonsSection(root, 'Review inbox \\(raw, distill me\\)').length,
+    reviews: scores.length,
+    avg_all: avg(scores),
+    avg_last5: avg(scores.slice(-5)),
+  };
+}
+
+function wishLessonsBrief(root = process.cwd(), cap = 10) {
+  const lines = readWishLessonLines(root, cap);
+  if (!lines.length) return '';
+  return ['Lessons from past wishes (apply these):', ...lines].join('\n');
+}
+
+const PRUNE_MIN_REVIEWS_AFTER = 3;
+
+function pruneWishLessons(root = process.cwd(), options = {}) {
+  const quiet = options.quiet === true;
+  const say = quiet ? () => {} : console.log.bind(console);
+  const file = lessonsFile(root);
+  if (!fs.existsSync(file)) return [];
+  const content = fs.readFileSync(file, 'utf8');
+  const match = content.match(/## Lessons\n([\s\S]*?)(?=\n## |$)/);
+  if (!match) return [];
+  const scored = readWishEvents(root)
+    .filter((event) => event && event.kind === 'review' && typeof event.review_score === 'number')
+    .map((event) => ({ ts: String(event.ts || ''), score: event.review_score }))
+    .filter((event) => event.ts)
+    .sort((a, b) => a.ts.localeCompare(b.ts));
+  const avg = (list) => list.reduce((sum, item) => sum + item.score, 0) / list.length;
+  const pruned = [];
+  const kept = match[1].split('\n').filter((line) => {
+    const trimmed = line.trim();
+    const dated = trimmed.match(/^- (\d{4}-\d{2}-\d{2}):/);
+    if (!dated) return true;
+    const since = dated[1];
+    const before = scored.filter((event) => event.ts.slice(0, 10) < since);
+    const after = scored.filter((event) => event.ts.slice(0, 10) >= since);
+    if (!before.length || after.length < PRUNE_MIN_REVIEWS_AFTER) return true;
+    if (avg(after) >= avg(before)) return true;
+    pruned.push({
+      lesson: trimmed,
+      avg_before: Number(avg(before).toFixed(2)),
+      avg_after: Number(avg(after).toFixed(2)),
+      reviews_after: after.length,
+    });
+    return false;
+  });
+  if (!pruned.length) return [];
+  let next = content.replace(match[0], `## Lessons\n${kept.join('\n')}`);
+  const graveyard = pruned.map((item) =>
+    `${item.lesson} [pruned ${todayName()}: avg ${item.avg_before} -> ${item.avg_after} over ${item.reviews_after} reviews]`);
+  if (next.includes('## Pruned (did not move the score)')) {
+    next = next.replace('## Pruned (did not move the score)', `## Pruned (did not move the score)\n${graveyard.join('\n')}`);
+  } else {
+    next = `${next.replace(/\s*$/, '')}\n\n## Pruned (did not move the score)\n${graveyard.join('\n')}\n`;
+  }
+  fs.writeFileSync(file, next, 'utf8');
+  for (const item of pruned) {
+    say(`wish improve: pruned lesson (avg ${item.avg_before} -> ${item.avg_after} over ${item.reviews_after} reviews): ${item.lesson}`);
+  }
+  return pruned;
+}
+
+function improveWishes(root = process.cwd(), options = {}) {
+  const quiet = options.quiet === true;
+  const say = quiet ? () => {} : console.log.bind(console);
+  const cursor = readImproveCursor(root);
+  pruneWishLessons(root, options);
+  const reviews = readWishEvents(root)
+    .filter((event) => event && event.kind === 'review' && String(event.ts || ''))
+    .filter((event) => String(event.ts) > cursor)
+    .sort((a, b) => String(a.ts).localeCompare(String(b.ts)));
+  if (!reviews.length) {
+    say('wish improve: nothing new.');
+    return 0;
+  }
+  const scores = reviews
+    .map((event) => event.review_score)
+    .filter((score) => typeof score === 'number');
+  const avg = scores.length
+    ? (scores.reduce((sum, score) => sum + score, 0) / scores.length).toFixed(2)
+    : 'n/a';
+  const negatives = scores.filter((score) => score < 0).length;
+  const file = lessonsFile(root);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let content = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : LESSONS_HEADER;
+  if (!content.includes('## Review inbox (raw, distill me)')) {
+    content = `${content.replace(/\s*$/, '')}\n\n## Review inbox (raw, distill me)\n`;
+  }
+  const lines = reviews.map((event) => {
+    const score = event.review_score === null || event.review_score === undefined ? 'none' : event.review_score;
+    return `- ${event.ts} | ${event.wish_id || 'unknown-wish'} | score ${score} | ${String(event.review_text || '').trim()} (by ${event.reviewed_by || 'unknown'})`;
+  });
+  content = `${content.replace(/\s*$/, '')}\n${lines.join('\n')}\n`;
+  fs.writeFileSync(file, content, 'utf8');
+  writeImproveCursor(root, String(reviews[reviews.length - 1].ts));
+  say(`wish improve: ingested ${reviews.length} review${reviews.length === 1 ? '' : 's'} (avg score ${avg}, ${negatives} negative) into ${path.relative(root, file)}.`);
+  return 0;
+}
+
+function latestWishEventMap(root = process.cwd()) {
+  const byId = new Map();
+  for (const event of readWishEvents(root)) {
+    if (event && event.id) byId.set(event.id, event);
+  }
+  return byId;
+}
+
+module.exports = {
+  appendJsonLine,
+  appendWishRecord,
+  eventAnswers,
+  improveWishes,
+  lessonsFile,
+  pruneWishLessons,
+  readWishLessonLines,
+  wishLessonsBrief,
+  wishLessonsSummary,
+  latestWishEventMap,
+  nextWishNumber,
+  readJsonLines,
+  readWishEvents,
+  readWishes,
+  slugify,
+  stampIso,
+  stateFile,
+  todayName,
+  wishId,
+};