@nemus-cli/nemus 0.2.13 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-27
+
+### Added
+
+- **`nemus reflect` (alias `retro`) — LLM-as-a-judge retrospective.** Analyzes
+  your most recent workspaces (default 10) by reading their agent session
+  transcripts, distilling the human prompts + tool failures + tools used, and
+  asking your own configured agent (claude/pi/opencode — no API key of ours) to
+  recommend concrete setup improvements: which **skills** to add and where,
+  missing **AGENTS.md/context** rules, missing **connectivity/smoke tests**, and
+  **prompt/workflow** habits to change — each with a priority and a concrete
+  example snippet. Reads both Claude and pi transcript formats. Flags:
+  `--limit <n>`, `--json` (structured report, same `{ok:false,error}` failure
+  contract as the other JSON commands), and `--dry-run` (print the assembled
+  corpus + judge prompt without calling the agent). Idea courtesy of
+  **@lightpriest** — thank you for the great suggestion!
+
 ## [0.2.13] - 2026-08-27
 
 ### Added

package/README.md

@@ -280,6 +280,23 @@ nemus snapshot save ws        # (ss) capture exact branches/commits/dirty state
 nemus snapshot restore <id>   # (sr)
 ```
 
+### Reflect — improve your setup over time
+
+```bash
+nemus reflect                 # (retro) analyze your last 10 workspaces' sessions
+nemus reflect --limit 5       # narrow the window
+nemus reflect --json          # structured report for tooling
+nemus reflect --dry-run       # show what the judge sees, without calling the agent
+```
+
+`reflect` reads your recent agent **session transcripts** (Claude + pi), distills
+the prompts you sent, the failures the agent hit, and the tools it used, then asks
+**your own configured agent** (LLM-as-a-judge — no extra API key) to recommend
+concrete improvements: which **skills** to add and where, missing
+**AGENTS.md/context** rules, missing **connectivity/smoke tests**, and
+**prompt/workflow** habits — each with a priority and an example snippet. It's a
+fast retrospective on *how you drive the agent*, so next time works better.
+
 ### AI assistant
 
 ```bash

package/dist/cli/ai-prompt.js

@@ -41,6 +41,7 @@ exports.extractIntent = extractIntent;
 exports.run = run;
 exports.main = main;
 const child_process_1 = require("child_process");
+const agent_judge_1 = require("../utils/agent-judge");
 const util_1 = require("util");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -267,35 +268,22 @@ async function extractIntent(prompt) {
         ];
         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;
-    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;
+    try {
+        const parsed = (0, agent_judge_1.parseAgentJson)(result);
+        if (parsed && typeof parsed === 'object')
+            intent = parsed;
     }
-    else if (parsed.workspaceName || parsed.repos || parsed.remainingIntent !== undefined) {
-        // Pi may return the extracted object directly
-        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
     // downstream .trim()/sanitize path (a stringly-typed workspaceName or a

package/dist/commands/reflect.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerReflectCommand = registerReflectCommand;
+const logger_1 = require("../utils/logger");
+const output_1 = require("../utils/output");
+const colors_1 = require("../utils/colors");
+const reflect_1 = require("../utils/reflect");
+const agent_judge_1 = require("../utils/agent-judge");
+function registerReflectCommand(parent) {
+    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) {
+    const limit = Math.max(1, Number.parseInt(opts.limit ?? '10', 10) || 10);
+    try {
+        if (!opts.json && !opts.dryRun) {
+            (0, logger_1.logStep)(`Analyzing your ${(0, colors_1.colorize)(String(limit), 'cyan')} most recent workspaces…`);
+            (0, logger_1.logInfo)('Reading sessions and distilling prompts + failures…');
+        }
+        const corpus = await (0, reflect_1.gatherReflectionCorpus)(limit);
+        const withSessions = corpus.workspaces.filter((w) => w.session).length;
+        const prompt = (0, reflect_1.buildJudgePrompt)(corpus);
+        if (opts.dryRun) {
+            // No LLM call — surface exactly what the judge would see.
+            if (opts.json)
+                (0, output_1.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)
+                (0, output_1.outputJsonError)(msg);
+            else
+                (0, logger_1.logError)(msg);
+            process.exit(1);
+        }
+        if (!opts.json)
+            (0, logger_1.logInfo)(`Judging ${withSessions} session(s) with your configured agent…`);
+        const parsed = (0, agent_judge_1.runAgentJson)(prompt, { schema: reflect_1.REFLECT_SCHEMA });
+        const report = (0, reflect_1.parseReflectionReport)(parsed);
+        if (opts.json) {
+            (0, output_1.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)
+            (0, output_1.outputJsonError)(msg);
+        else {
+            (0, logger_1.logError)('Failed to analyze sessions');
+            (0, logger_1.logError)(msg);
+        }
+        process.exit(1);
+    }
+}
+const KIND_LABEL = {
+    skill: 'Skill',
+    context: 'Context/AGENTS.md',
+    test: 'Test',
+    prompt: 'Prompt',
+    connectivity: 'Connectivity',
+    workflow: 'Workflow',
+    other: 'Other',
+};
+function priorityBadge(p) {
+    if (p === 'high')
+        return (0, colors_1.colorize)('● high', 'red');
+    if (p === 'medium')
+        return (0, colors_1.colorize)('● med', 'yellow');
+    return (0, colors_1.colorize)('● low', 'gray');
+}
+function printReport(report, workspaces, analyzed) {
+    console.log('');
+    console.log((0, colors_1.colorize)('  Reflection', 'bright') + (0, colors_1.colorize)(`  (${analyzed} sessions across ${workspaces} workspaces)`, 'dim'));
+    console.log((0, colors_1.colorize)('  ' + '─'.repeat(56), 'dim'));
+    if (report.summary) {
+        console.log('\n  ' + report.summary.replace(/\n/g, '\n  '));
+    }
+    if (report.recommendations.length === 0) {
+        console.log('\n  ' + (0, colors_1.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 ? (0, colors_1.colorize)(`  [${r.target}]`, 'cyan') : '';
+        console.log(`  ${priorityBadge(r.priority)}  ${(0, colors_1.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((0, colors_1.colorize)('      example:', 'dim'));
+            console.log((0, colors_1.colorize)(r.example.replace(/^/gm, '        '), 'dim'));
+        }
+        console.log('');
+    }
+}

package/dist/program.js

@@ -89,6 +89,7 @@ const save_context_1 = require("./commands/save-context");
 const migrate_1 = require("./commands/migrate");
 const report_bug_1 = require("./commands/report-bug");
 const completion_1 = require("./commands/completion");
+const reflect_1 = require("./commands/reflect");
 (0, create_1.registerCreateCommand)(exports.program);
 (0, list_1.registerListCommand)(exports.program);
 (0, update_1.registerUpdateCommand)(exports.program);
@@ -113,6 +114,7 @@ const completion_1 = require("./commands/completion");
 (0, migrate_1.registerMigrateCommand)(exports.program);
 (0, report_bug_1.registerReportBugCommand)(exports.program);
 (0, completion_1.registerCompletionCommand)(exports.program);
+(0, reflect_1.registerReflectCommand)(exports.program);
 // Register TUI (delegates to existing Ink/React implementation)
 exports.program
     .command('tui')

package/dist/utils/agent-judge.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAgentRaw = runAgentRaw;
+exports.runAgentJson = runAgentJson;
+exports.parseAgentJson = parseAgentJson;
+const child_process_1 = require("child_process");
+const agent_config_1 = require("./agent-config");
+const DEFAULT_TIMEOUT_MS = 180000; // judging N transcripts is heavier than extraction
+const DEFAULT_MAX_BUFFER = 32 * 1024 * 1024;
+/**
+ * Invoke the agent with `prompt` and return the raw stdout. Throws a clear error
+ * on timeout / non-zero exit. Kept separate from parsing so callers can inspect
+ * raw output (e.g. `--dry-run`, debugging).
+ */
+function runAgentRaw(prompt, opts = {}) {
+    const agentType = opts.agentType ?? (0, agent_config_1.getPrimaryAgent)().type;
+    const timeout = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxBuffer = opts.maxBuffer ?? DEFAULT_MAX_BUFFER;
+    const exec = opts.exec ??
+        ((cmd, args, o) => (0, child_process_1.execFileSync)(cmd, args, { encoding: 'utf-8', timeout: o.timeout, maxBuffer: o.maxBuffer }));
+    const attempt = (cmd, args) => exec(cmd, args, { timeout, maxBuffer });
+    try {
+        if (agentType === 'claude') {
+            const preferred = ['-p', prompt, '--output-format', 'json', '--bare', '--strict-mcp-config', '--disable-slash-commands'];
+            if (opts.schema)
+                preferred.push('--json-schema', opts.schema);
+            try {
+                return attempt('claude', preferred);
+            }
+            catch {
+                // Older claude may reject the newer flags — fall back to the plainest form.
+                return attempt('claude', ['-p', prompt]);
+            }
+        }
+        if (agentType === 'opencode') {
+            return attempt('opencode', ['run', prompt]);
+        }
+        // pi (and any other): run as lean as possible so a bloated env can't hang it.
+        const piLean = ['--no-extensions', '--no-skills', '--no-prompt-templates', '--no-context-files', '--no-tools', '--no-session'];
+        try {
+            return attempt('pi', [...piLean, '-p', prompt]);
+        }
+        catch {
+            return attempt('pi', ['-p', prompt]);
+        }
+    }
+    catch (err) {
+        const detail = (err?.stderr || err?.stdout || err?.message || 'unknown error').toString().trim().slice(0, 500);
+        throw new Error(`agent judge failed (${agentType}): ${detail}`);
+    }
+}
+/**
+ * Run the agent and parse its reply as JSON, tolerating the shapes different
+ * agents emit: `{ structured_output }`, `{ result: "<json>" }`, a ```json fence,
+ * or a bare object. Returns `unknown`; callers validate/normalize their shape.
+ */
+function runAgentJson(prompt, opts = {}) {
+    const raw = runAgentRaw(prompt, opts);
+    return parseAgentJson(raw);
+}
+/** Extract a JSON object from an agent's raw stdout. Exported for tests. */
+function parseAgentJson(raw) {
+    let text = raw.trim();
+    const fence = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+    if (fence)
+        text = fence[1].trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // Last resort: grab the outermost {...} span.
+        const span = text.match(/\{[\s\S]*\}/);
+        if (!span)
+            throw new Error('agent did not return JSON');
+        parsed = JSON.parse(span[0]);
+    }
+    // Unwrap the common agent envelopes.
+    if (parsed && typeof parsed === 'object') {
+        if (parsed.structured_output && typeof parsed.structured_output === 'object')
+            return parsed.structured_output;
+        if (typeof parsed.result === 'string') {
+            try {
+                return JSON.parse(parsed.result);
+            }
+            catch {
+                /* fall through — result was plain text, return the envelope */
+            }
+        }
+        if (parsed.result && typeof parsed.result === 'object')
+            return parsed.result;
+    }
+    return parsed;
+}

package/dist/utils/reflect.js

@@ -0,0 +1,345 @@
+"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
+const MAX_PROMPTS = 25;
+const MAX_ERRORS = 25;
+const PROMPT_CHARS = 600;
+const ERROR_CHARS = 300;
+/** 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.
+ */
+async function gatherReflectionCorpus(limit) {
+    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 (const s of recent) {
+        const meta = metaByName.get(s.workspaceName);
+        digests.push({
+            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),
+        });
+    }
+    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 };
+}