@nemus-cli/nemus 0.2.13 → 0.3.1

package/dist/utils/reflect.js

@@ -0,0 +1,353 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REFLECT_SCHEMA = void 0;
+exports.distillTranscript = distillTranscript;
+exports.findLatestTranscriptFile = findLatestTranscriptFile;
+exports.gatherReflectionCorpus = gatherReflectionCorpus;
+exports.buildJudgePrompt = buildJudgePrompt;
+exports.parseReflectionReport = parseReflectionReport;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const workspace_meta_1 = require("./workspace-meta");
+const agent_config_1 = require("./agent-config");
+const claude_sessions_1 = require("./claude-sessions");
+// --------------------------------------------------------- transcript distill
+// Kept deliberately lean: the judge runs on the user's own (often local, slow)
+// agent, and a 10-workspace corpus at full verbosity produced a ~200KB prompt
+// that timed pi out. These bounds capture the pattern of a session at a
+// fraction of the tokens (~halving the prompt), so the judge actually finishes.
+const MAX_PROMPTS = 12;
+const MAX_ERRORS = 15;
+const PROMPT_CHARS = 400;
+const ERROR_CHARS = 200;
+/** Flatten a message `content` (string or content-block array) to plain text. */
+function contentToText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((b) => (b && b.type === 'text' && typeof b.text === 'string' ? b.text : ''))
+            .filter(Boolean)
+            .join('\n');
+    }
+    return '';
+}
+// Only used as a FALLBACK when a tool result carries no explicit error flag.
+// Kept to strong failure signals so a successful grep/log line for the word
+// "error", or a passing test named “…error…”, isn't mistaken for a failure.
+const ERROR_RE = /\b(fatal|failed|failure|exception|traceback|denied|not a git repository|timed out|exit code\s+[1-9])\b/i;
+/**
+ * Decide whether a tool result is a failure: trust the explicit `isError` flag
+ * when present (true => failure, false => success), and only guess from the
+ * text when there's no flag at all. This keeps the judge's “evidence” to real
+ * failures instead of any output that happens to contain the word “error”.
+ */
+function isToolFailure(flag, text) {
+    if (flag === true)
+        return true;
+    if (flag === false)
+        return false;
+    return ERROR_RE.test(text);
+}
+/**
+ * Distill a raw `.jsonl` transcript into the signals a judge needs: the human
+ * prompts, tool failures, and which tools ran. Pure (operates on file content),
+ * defensive about the several line shapes Claude/pi emit, and bounded so a huge
+ * transcript can't blow the prompt budget.
+ */
+function distillTranscript(raw, meta) {
+    const userPrompts = [];
+    const errors = [];
+    const tools = new Set();
+    let turns = 0;
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const msg = obj.message ?? obj;
+        const role = msg?.role ?? obj?.type;
+        const content = msg?.content;
+        // Assistant turn + tool uses. Claude uses `tool_use` blocks; pi uses `toolCall`.
+        if (role === 'assistant') {
+            turns++;
+            if (Array.isArray(content)) {
+                for (const b of content) {
+                    if (b && (b.type === 'tool_use' || b.type === 'toolCall') && typeof b.name === 'string')
+                        tools.add(b.name);
+                }
+            }
+        }
+        // Tool results, two shapes:
+        //  - pi: a top-level message with role 'toolResult' (+ toolName, content).
+        //  - Claude: a `tool_result` block inside a user message's content array.
+        if (role === 'toolResult') {
+            if (typeof msg.toolName === 'string')
+                tools.add(msg.toolName);
+            const text = contentToText(content);
+            if (isToolFailure(msg.isError ?? msg.is_error, text) && text.trim() && errors.length < MAX_ERRORS) {
+                errors.push(text.trim().slice(0, ERROR_CHARS));
+            }
+        }
+        if (Array.isArray(content)) {
+            for (const b of content) {
+                if (b && b.type === 'tool_result') {
+                    const text = contentToText(b.content);
+                    if (isToolFailure(b.is_error, text) && text.trim() && errors.length < MAX_ERRORS) {
+                        errors.push(text.trim().slice(0, ERROR_CHARS));
+                    }
+                }
+            }
+        }
+        // Human prompts: a user message that carries actual text (not a tool_result echo).
+        if (role === 'user') {
+            const isToolResultOnly = Array.isArray(content) && content.length > 0 && content.every((b) => b?.type === 'tool_result');
+            if (!isToolResultOnly) {
+                const text = contentToText(content).trim();
+                if (text && !text.startsWith('<') && userPrompts.length < MAX_PROMPTS) {
+                    userPrompts.push(text.slice(0, PROMPT_CHARS));
+                }
+            }
+        }
+    }
+    return { sessionId: meta.sessionId, agentType: meta.agentType, turns, userPrompts, errors, tools: [...tools] };
+}
+// --------------------------------------------------------- corpus gathering
+/** Locate the most recent `.jsonl` transcript for a workspace under an agent. */
+async function findLatestTranscriptFile(sessionProjectsDir, workspacePath, agentType) {
+    if (agentType !== 'claude' && agentType !== 'pi')
+        return null;
+    const projDir = path.join(sessionProjectsDir, (0, claude_sessions_1.pathToProjectDirName)(workspacePath, agentType));
+    let entries;
+    try {
+        entries = await fs.readdir(projDir);
+    }
+    catch {
+        return null;
+    }
+    const jsonl = entries.filter((f) => f.endsWith('.jsonl'));
+    if (jsonl.length === 0)
+        return null;
+    const stats = await Promise.all(jsonl.map(async (f) => {
+        try {
+            return { f, mtime: (await fs.stat(path.join(projDir, f))).mtime.getTime() };
+        }
+        catch {
+            return null;
+        }
+    }));
+    const best = stats.filter((s) => !!s).sort((a, b) => b.mtime - a.mtime)[0];
+    return best ? path.join(projDir, best.f) : null;
+}
+const MAX_TRANSCRIPT_BYTES = 4 * 1024 * 1024;
+/** Read + distill the transcript for a specific discovered session. Prefers the
+ *  exact `<sessionId>.jsonl`; falls back to the latest transcript in that
+ *  project dir if the exact file has been rotated away. */
+async function readDigestForSession(s) {
+    if (s.agentType !== 'claude' && s.agentType !== 'pi')
+        return null;
+    const projectsDir = (0, agent_config_1.getAgentPaths)(s.agentType).sessionProjectsDir;
+    const exact = path.join(projectsDir, (0, claude_sessions_1.pathToProjectDirName)(s.workspacePath, s.agentType), `${s.sessionId}.jsonl`);
+    let file = exact;
+    try {
+        await fs.access(exact);
+    }
+    catch {
+        file = await findLatestTranscriptFile(projectsDir, s.workspacePath, s.agentType);
+    }
+    if (!file)
+        return null;
+    let raw;
+    try {
+        raw = await fs.readFile(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    if (raw.length > MAX_TRANSCRIPT_BYTES)
+        raw = raw.slice(raw.length - MAX_TRANSCRIPT_BYTES); // keep the tail (most recent)
+    return distillTranscript(raw, { sessionId: s.sessionId, agentType: s.agentType });
+}
+async function listAvailableSkills() {
+    const names = new Set();
+    for (const dir of (0, agent_config_1.getSkillsTargetDirs)()) {
+        try {
+            for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+                if (entry.isDirectory())
+                    names.add(entry.name);
+                else if (entry.name.endsWith('.md'))
+                    names.add(entry.name.replace(/\.md$/, ''));
+            }
+        }
+        catch {
+            /* dir may not exist */
+        }
+    }
+    return [...names].sort();
+}
+async function contextFilesFor(workspacePath) {
+    const present = [];
+    for (const name of (0, agent_config_1.getAllKnownContextFileNames)()) {
+        try {
+            await fs.access(path.join(workspacePath, name));
+            present.push(name);
+        }
+        catch {
+            /* not present */
+        }
+    }
+    return present;
+}
+/**
+ * Build the corpus the judge reasons over: the `limit` most **recently active**
+ * workspaces (by their latest agent session, not creation date — a retrospective
+ * is about recent *work*), each with its repos, context files, and distilled
+ * session, plus the globally-available skills. `onProgress` (optional) fires
+ * once per workspace as it finishes, for a live progress display.
+ */
+async function gatherReflectionCorpus(limit, onProgress) {
+    const [sessions, workspaces, availableSkills] = await Promise.all([
+        (0, claude_sessions_1.getWorkspaceSessions)(), // already sorted by last-active, one per workspace
+        (0, workspace_meta_1.listWorkspaces)(false),
+        listAvailableSkills(),
+    ]);
+    const metaByName = new Map(workspaces.map((w) => [w.name, w]));
+    const recent = sessions.slice(0, limit);
+    const digests = [];
+    for (let index = 0; index < recent.length; index++) {
+        const s = recent[index];
+        const meta = metaByName.get(s.workspaceName);
+        const digest = {
+            name: s.workspaceName,
+            repoCount: meta?.metadata?.repositories?.length ?? 0,
+            repos: (meta?.metadata?.repositories ?? []).map((r) => r.name),
+            contextFiles: await contextFilesFor(s.workspacePath),
+            session: await readDigestForSession(s),
+        };
+        digests.push(digest);
+        onProgress?.({ index, total: recent.length, digest });
+    }
+    return { generatedAt: new Date().toISOString(), availableSkills, workspaces: digests };
+}
+// ------------------------------------------------------------- judge prompt
+/** JSON schema for `claude --json-schema` (best-effort; other agents ignore it). */
+exports.REFLECT_SCHEMA = JSON.stringify({
+    type: 'object',
+    properties: {
+        summary: { type: 'string' },
+        recommendations: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    kind: { type: 'string', enum: ['skill', 'context', 'test', 'prompt', 'connectivity', 'workflow', 'other'] },
+                    title: { type: 'string' },
+                    detail: { type: 'string' },
+                    target: { type: 'string' },
+                    priority: { type: 'string', enum: ['high', 'medium', 'low'] },
+                    example: { type: 'string' },
+                },
+                required: ['kind', 'title', 'detail', 'priority'],
+            },
+        },
+    },
+    required: ['summary', 'recommendations'],
+});
+/**
+ * Build the LLM-as-a-judge prompt. The judge sees distilled recent sessions and
+ * is asked to recommend concrete improvements to the user's SETUP (skills,
+ * AGENTS.md/context rules, connectivity/tests, prompt habits, workflow) — not to
+ * redo the tasks. Output is strict JSON matching REFLECT_SCHEMA.
+ */
+function buildJudgePrompt(corpus) {
+    const lines = [];
+    lines.push('You are an expert reviewer ("LLM as a judge") analyzing an engineer\'s recent AI coding-agent sessions.', 'Goal: recommend concrete improvements to their SETUP so the agent works better next time —', 'which skills to add and WHERE, which AGENTS.md/context rules are missing, missing connectivity/', 'smoke tests, and prompt habits to change. Judge the setup, do NOT redo the tasks.', '', 'Base every recommendation on evidence in the sessions below (repeated failures, retries, vague', 'prompts, missing context). Prefer a few high-signal, actionable items over many generic ones.', 'When you suggest a skill or an AGENTS.md rule, include a short concrete `example` snippet.', '', `Globally installed skills (don't re-suggest these; suggest genuinely missing ones): ${corpus.availableSkills.join(', ') || '(none)'}`, '', `Recent workspaces (${corpus.workspaces.length}):`);
+    for (const ws of corpus.workspaces) {
+        lines.push(`\n## ${ws.name}`);
+        lines.push(`repos: ${ws.repos.join(', ') || '(none)'} | context files: ${ws.contextFiles.join(', ') || 'NONE'}`);
+        if (!ws.session) {
+            lines.push('session: (no recent agent session found)');
+            continue;
+        }
+        lines.push(`session: ${ws.session.turns} turns, tools used: ${ws.session.tools.join(', ') || '(none)'}`);
+        if (ws.session.userPrompts.length) {
+            lines.push('user prompts:');
+            for (const p of ws.session.userPrompts)
+                lines.push(`  - ${p.replace(/\n/g, ' ')}`);
+        }
+        if (ws.session.errors.length) {
+            lines.push('errors/failures observed:');
+            for (const e of ws.session.errors)
+                lines.push(`  - ${e.replace(/\n/g, ' ')}`);
+        }
+    }
+    lines.push('', 'Respond with ONLY a JSON object of this shape (no prose, no markdown fence):', '{"summary": string, "recommendations": [{"kind":"skill|context|test|prompt|connectivity|workflow|other",', '"title": string, "detail": string, "target": string(optional workspace/repo/path),', '"priority":"high|medium|low", "example": string(optional snippet)}]}');
+    return lines.join('\n');
+}
+// ----------------------------------------------------------- response parse
+const KINDS = ['skill', 'context', 'test', 'prompt', 'connectivity', 'workflow', 'other'];
+const PRIORITIES = ['high', 'medium', 'low'];
+/** Validate + normalize the judge's parsed JSON into a ReflectionReport. */
+function parseReflectionReport(parsed) {
+    const obj = (parsed ?? {});
+    const summary = typeof obj.summary === 'string' ? obj.summary : '';
+    const rawRecs = Array.isArray(obj.recommendations) ? obj.recommendations : [];
+    const recommendations = rawRecs
+        .map((r) => {
+        if (!r || typeof r !== 'object')
+            return null;
+        const title = typeof r.title === 'string' ? r.title : '';
+        const detail = typeof r.detail === 'string' ? r.detail : '';
+        if (!title && !detail)
+            return null;
+        const kind = KINDS.includes(r.kind) ? r.kind : 'other';
+        const priority = PRIORITIES.includes(r.priority) ? r.priority : 'medium';
+        const rec = { kind, title, detail, priority };
+        if (typeof r.target === 'string' && r.target.trim())
+            rec.target = r.target.trim();
+        if (typeof r.example === 'string' && r.example.trim())
+            rec.example = r.example.trim();
+        return rec;
+    })
+        .filter((r) => r !== null);
+    return { summary, recommendations };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.2.13",
+  "version": "0.3.1",
   "workspaces": [
     "packages/*"
   ],

package/src/cli/ai-prompt.ts

@@ -1,4 +1,5 @@
 import { spawn, execFile, execFileSync } from 'child_process';
+import { parseAgentJson } from '../utils/agent-judge';
 import { promisify } from 'util';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -259,32 +260,21 @@ export async function extractIntent(prompt: string): Promise<ExtractedIntent> {
     result = runExtraction('pi', [...piLean, ...piCore], piCore);
   }
 
-  // Strip markdown code fences if present (Pi may wrap JSON in ```json...```)
-  let jsonStr = result.trim();
-  const fenceMatch = jsonStr.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
-  if (fenceMatch) {
-    jsonStr = fenceMatch[1].trim();
-  }
-
-  const parsed = JSON.parse(jsonStr);
-
-  // Handle different output formats:
-  // - Claude: { structured_output: {...} } or { result: "..." }
-  // - Pi: may return the object directly or wrap it
+  // Unwrap the agent's reply (code fences + the structured_output / result-string
+  // / result-object / bare-object envelopes) with the shared parser, so this and
+  // the reflect judge can't drift when a new agent shape is learned. The
+  // extraction-specific INVOCATION (lean flags + tailored timeout/auth errors)
+  // deliberately stays here — those messages are part of the `nemus --` UX.
   let intent: ExtractedIntent | undefined;
-  if (parsed.structured_output) {
-    intent = parsed.structured_output;
-  } else if (typeof parsed.result === 'string' && parsed.result) {
-    try { intent = JSON.parse(parsed.result); } catch { /* ignore */ }
-  } else if (typeof parsed.result === 'object' && parsed.result !== null) {
-    intent = parsed.result;
-  } else if (parsed.workspaceName || parsed.repos || parsed.remainingIntent !== undefined) {
-    // Pi may return the extracted object directly
-    intent = parsed;
+  try {
+    const parsed = parseAgentJson(result) as any;
+    if (parsed && typeof parsed === 'object') intent = parsed;
+  } catch {
+    throw new Error(`Could not extract intent from agent response: ${result.slice(0, 200)}`);
   }
 
   if (!intent) {
-    throw new Error(`Could not extract intent from agent response. Parsed: ${JSON.stringify(parsed).slice(0, 200)}`);
+    throw new Error(`Could not extract intent from agent response: ${result.slice(0, 200)}`);
   }
 
   // Coerce/validate field types so malformed model output can't crash the

package/src/commands/reflect.ts

@@ -0,0 +1,172 @@
+import { Command } from 'commander';
+import { logError, logInfo, logStep } from '../utils/logger';
+import { outputJson, outputJsonError } from '../utils/output';
+import { colorize } from '../utils/colors';
+import {
+  gatherReflectionCorpus,
+  buildJudgePrompt,
+  parseReflectionReport,
+  REFLECT_SCHEMA,
+  ReflectionReport,
+  ReflectProgress,
+  Recommendation,
+} from '../utils/reflect';
+import { runAgentJsonAsync } from '../utils/agent-judge';
+
+export function registerReflectCommand(parent: Command) {
+  parent
+    .command('reflect')
+    .alias('retro')
+    .description('Analyze your recent workspace sessions and suggest skill/prompt/context improvements (LLM-as-a-judge)')
+    .option('-n, --limit <n>', 'How many recent workspaces to analyze', '10')
+    .option('--json', 'Output the report as JSON')
+    .option('--dry-run', 'Print the assembled corpus + judge prompt without calling the agent')
+    .action(async (opts) => {
+      await handleReflect(opts);
+    });
+}
+
+async function handleReflect(opts: { limit?: string; json?: boolean; dryRun?: boolean }) {
+  const limit = Math.max(1, Number.parseInt(opts.limit ?? '10', 10) || 10);
+  try {
+    const showProgress = !opts.json && !opts.dryRun;
+    if (showProgress) {
+      logStep(`Analyzing your ${colorize(String(limit), 'cyan')} most recent workspaces…`);
+    }
+
+    const corpus = await gatherReflectionCorpus(limit, showProgress ? printProgress : undefined);
+    const withSessions = corpus.workspaces.filter((w) => w.session).length;
+    const prompt = buildJudgePrompt(corpus);
+
+    if (opts.dryRun) {
+      // No LLM call — surface exactly what the judge would see.
+      if (opts.json) outputJson({ corpus, prompt });
+      else {
+        process.stdout.write(prompt + '\n');
+      }
+      return;
+    }
+
+    if (withSessions === 0) {
+      const msg = 'No recent agent sessions found to analyze (need Claude/pi session transcripts).';
+      if (opts.json) outputJsonError(msg);
+      else logError(msg);
+      process.exit(1);
+    }
+
+    // The judge shells the user's own agent and can take minutes; run it async
+    // (non-blocking) so a live spinner shows it's alive, not hung. Timeout is
+    // overridable for slow local models.
+    const timeoutMs = Number.parseInt(process.env.NEMUS_JUDGE_TIMEOUT_MS ?? '', 10) || undefined;
+    const stopSpinner = opts.json
+      ? () => {}
+      : startSpinner(`Judging ${withSessions} session(s) with your configured agent (this can take a minute)…`);
+    let parsed: unknown;
+    try {
+      parsed = await runAgentJsonAsync(prompt, { schema: REFLECT_SCHEMA, timeoutMs });
+    } finally {
+      stopSpinner();
+    }
+    const report = parseReflectionReport(parsed);
+
+    if (opts.json) {
+      outputJson({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report });
+      return;
+    }
+    printReport(report, corpus.workspaces.length, withSessions);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : 'reflect failed';
+    if (opts.json) outputJsonError(msg);
+    else {
+      logError('Failed to analyze sessions');
+      logError(msg);
+    }
+    process.exit(1);
+  }
+}
+
+const KIND_LABEL: Record<Recommendation['kind'], string> = {
+  skill: 'Skill',
+  context: 'Context/AGENTS.md',
+  test: 'Test',
+  prompt: 'Prompt',
+  connectivity: 'Connectivity',
+  workflow: 'Workflow',
+  other: 'Other',
+};
+
+/**
+ * A minimal stderr spinner with elapsed seconds. Returns a stop() that clears
+ * the line. No-op (single log line) when stderr isn't a TTY (piped/CI), so it
+ * never pollutes captured output. Kept local + tiny — no new dependency.
+ */
+function startSpinner(text: string): () => void {
+  if (!process.stderr.isTTY) {
+    logInfo(text);
+    return () => {};
+  }
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  const start = Date.now();
+  let i = 0;
+  const render = () => {
+    const secs = Math.floor((Date.now() - start) / 1000);
+    process.stderr.write(`\r${colorize(frames[(i = (i + 1) % frames.length)], 'cyan')} ${text} ${colorize(`(${secs}s)`, 'dim')}`);
+  };
+  render();
+  const timer = setInterval(render, 100);
+  timer.unref?.(); // never keep the process alive on our account
+  return () => {
+    clearInterval(timer);
+    process.stderr.write('\r' + ' '.repeat(text.length + 24) + '\r');
+  };
+}
+
+/** Live per-workspace line during the gather phase (to stderr — stdout stays
+ *  reserved for the report / JSON). */
+function printProgress(p: ReflectProgress): void {
+  const n = colorize(`${p.index + 1}/${p.total}`, 'dim');
+  const d = p.digest.session;
+  if (!d) {
+    process.stderr.write(`  ${colorize('·', 'dim')} ${n} ${p.digest.name} ${colorize('— no session', 'dim')}\n`);
+    return;
+  }
+  const failures = `${d.errors.length} ${d.errors.length === 1 ? 'failure' : 'failures'}`;
+  const stats = colorize(`${d.turns} turns · ${d.userPrompts.length} prompts · ${failures}`, 'dim');
+  process.stderr.write(`  ${colorize('✓', 'green')} ${n} ${p.digest.name}  ${stats}\n`);
+}
+
+function priorityBadge(p: Recommendation['priority']): string {
+  if (p === 'high') return colorize('● high', 'red');
+  if (p === 'medium') return colorize('● med', 'yellow');
+  return colorize('● low', 'gray');
+}
+
+function printReport(report: ReflectionReport, workspaces: number, analyzed: number) {
+  console.log('');
+  console.log(colorize('  Reflection', 'bright') + colorize(`  (${analyzed} sessions across ${workspaces} workspaces)`, 'dim'));
+  console.log(colorize('  ' + '─'.repeat(56), 'dim'));
+  if (report.summary) {
+    console.log('\n  ' + report.summary.replace(/\n/g, '\n  '));
+  }
+
+  if (report.recommendations.length === 0) {
+    console.log('\n  ' + colorize('No specific recommendations — looks solid.', 'green') + '\n');
+    return;
+  }
+
+  // High priority first.
+  const order = { high: 0, medium: 1, low: 2 };
+  const recs = [...report.recommendations].sort((a, b) => order[a.priority] - order[b.priority]);
+
+  console.log('');
+  for (const r of recs) {
+    const target = r.target ? colorize(`  [${r.target}]`, 'cyan') : '';
+    console.log(`  ${priorityBadge(r.priority)}  ${colorize(KIND_LABEL[r.kind], 'bright')}  ${r.title}${target}`);
+    if (r.detail) console.log(`      ${r.detail.replace(/\n/g, '\n      ')}`);
+    if (r.example) {
+      console.log(colorize('      example:', 'dim'));
+      console.log(colorize(r.example.replace(/^/gm, '        '), 'dim'));
+    }
+    console.log('');
+  }
+}

package/src/program.ts

@@ -59,6 +59,7 @@ import { registerSaveContextCommand } from './commands/save-context';
 import { registerMigrateCommand } from './commands/migrate';
 import { registerReportBugCommand } from './commands/report-bug';
 import { registerCompletionCommand } from './commands/completion';
+import { registerReflectCommand } from './commands/reflect';
 
 registerCreateCommand(program);
 registerListCommand(program);
@@ -84,6 +85,7 @@ registerSaveContextCommand(program);
 registerMigrateCommand(program);
 registerReportBugCommand(program);
 registerCompletionCommand(program);
+registerReflectCommand(program);
 
 // Register TUI (delegates to existing Ink/React implementation)
 program