@equinor/fusion-framework-cli-plugin-copilot 2.0.2 → 2.0.3

package/dist/types/commands/app/format-plan.d.ts

@@ -0,0 +1,8 @@
+import type { Plan } from './types.js';
+/**
+ * Renders a structured plan as a human-readable summary.
+ *
+ * @param plan - The plan to render, containing a summary and ordered steps.
+ * @returns A multi-line string suitable for console output.
+ */
+export declare function formatPlan(plan: Plan): string;

package/dist/types/commands/app/format-step-result.d.ts

@@ -0,0 +1,8 @@
+import type { StepResult } from './types.js';
+/**
+ * Renders a single step execution result.
+ *
+ * @param result - The step result to render, including its outcome, note, and evidence.
+ * @returns A formatted two-line string describing the step outcome.
+ */
+export declare function formatStepResult(result: StepResult): string;

package/dist/types/commands/app/format-verdict.d.ts

@@ -0,0 +1,8 @@
+import type { Verdict } from './types.js';
+/**
+ * Renders the final verdict as a full-width coloured report.
+ *
+ * @param verdict - The verdict to render, including per-step results, reasoning, and UX feedback.
+ * @returns A multi-line string suitable for console output.
+ */
+export declare function formatVerdict(verdict: Verdict): string;

package/dist/types/commands/app/prompts/{step.prompt.d.ts → create-step-prompt.d.ts}

@@ -9,4 +9,4 @@ import type { PlanStep, RuntimeExecutionContext } from '../types.js';
  * @param ctx - Runtime context with output directory and app URL
  * @returns The fully interpolated prompt string
  */
-export declare const createStepPrompt: (step: PlanStep, ctx: RuntimeExecutionContext) => string;
+export declare const createStepPrompt: (step: PlanStep, _ctx: RuntimeExecutionContext) => string;

package/dist/types/commands/app/status-icon.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Renders a status glyph for a step or verdict outcome.
+ *
+ * @param ok - Outcome value: `true` (pass), `false` (fail), or a string label
+ *   such as `'blocked'` or `'flaky'` for anything in between.
+ * @returns A single coloured glyph representing the outcome.
+ */
+export declare function statusIcon(ok: boolean | string): string;

package/dist/types/commands/app/tools/create-append-file-tool.d.ts

@@ -0,0 +1,10 @@
+import type { DefineTool } from './types.js';
+/**
+ * Creates the append-file tool so the agent can append lines
+ * to artifacts like executions.jsonl.
+ *
+ * @param baseDir - The run output directory that scopes all writes
+ * @param defineTool - Copilot SDK helper used to declare tools
+ * @returns Copilot tool definition for appending to a file
+ */
+export declare function createAppendFileTool(baseDir: string, defineTool: DefineTool): import("node_modules/@github/copilot-sdk/dist/types.js").Tool<unknown>;

package/dist/types/commands/app/tools/{write-file.d.ts → create-write-file-tool.d.ts}

@@ -8,12 +8,3 @@ import type { DefineTool } from './types.js';
  * @returns Copilot tool definition for writing a file
  */
 export declare function createWriteFileTool(baseDir: string, defineTool: DefineTool): import("node_modules/@github/copilot-sdk/dist/types.js").Tool<unknown>;
-/**
- * Creates the append-file tool so the agent can append lines
- * to artifacts like executions.jsonl.
- *
- * @param baseDir - The run output directory that scopes all writes
- * @param defineTool - Copilot SDK helper used to declare tools
- * @returns Copilot tool definition for appending to a file
- */
-export declare function createAppendFileTool(baseDir: string, defineTool: DefineTool): import("node_modules/@github/copilot-sdk/dist/types.js").Tool<unknown>;

package/dist/types/commands/app/truncate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Truncates a string to a maximum length, appending an ellipsis when cut.
+ *
+ * @param str - The string to truncate.
+ * @param max - Maximum length of the returned string, including the ellipsis.
+ * @returns The original string, or a shortened version ending in `…`.
+ */
+export declare function truncate(str: string, max: number): string;

package/dist/types/commands/app/try-format-message.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Attempts to detect the JSON shape of an assistant message and format it.
+ *
+ * Returns `null` when the content is not a recognised structure, so the
+ * caller can fall back to plain-text rendering.
+ *
+ * @param content - Raw assistant message content, expected to be a JSON string.
+ * @returns A formatted string for a recognised plan, step result, or verdict, or `null` otherwise.
+ */
+export declare function tryFormatMessage(content: string): string | null;

package/dist/types/exit-with-resolution-error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Prints a CLI resolution error and exits the current process.
+ *
+ * @param message - Primary error message.
+ * @param detail - Optional follow-up detail shown on the next line.
+ * @returns This function never returns because the process exits.
+ */
+export declare function exitWithResolutionError(message: string, detail?: string): never;

package/dist/types/{eval-resolve.d.ts → resolve-eval-command-input.d.ts}

@@ -21,11 +21,3 @@ export interface EvalCommandInput {
  * @returns Normalized application path and optional direct eval file path.
  */
 export declare function resolveEvalCommandInput(inputPath: string): EvalCommandInput;
-/**
- * Resolves eval markdown files for a Fusion application.
- *
- * @param appPath - Path to the Fusion application directory
- * @param evalOpt - Value of the `--eval` CLI option (name, path, or `undefined`)
- * @returns Array of absolute paths to eval markdown files
- */
-export declare function resolveEvalFiles(appPath: string, evalOpt?: string): string[];

package/dist/types/resolve-eval-files.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolves eval markdown files for a Fusion application.
+ *
+ * @param appPath - Path to the Fusion application directory
+ * @param evalOpt - Value of the `--eval` CLI option (name, path, or `undefined`)
+ * @returns Array of absolute paths to eval markdown files
+ */
+export declare function resolveEvalFiles(appPath: string, evalOpt?: string): string[];

package/dist/types/utils/ab-error-message.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Extracts the user-facing error message from an agent-browser failure.
+ *
+ * Strips ANSI escape codes from stderr and returns only the diagnostic
+ * lines prefixed with `✗` or `⚠`. Falls back to the first 200 characters
+ * of the error message when no diagnostic lines are found.
+ *
+ * @param err - The caught error (typically from {@link ab})
+ * @returns A single-line summary suitable for console output
+ */
+export declare function abErrorMessage(err: unknown): string;

package/dist/types/utils/{agent-browser.d.ts → ab.d.ts}

@@ -1,5 +1,3 @@
-/** Persistent Chrome profile directory used across agent-browser sessions. */
-export declare const PROFILE_DIR: string;
 /**
  * Runs an agent-browser command with the persistent Chrome profile.
  *
@@ -13,14 +11,3 @@ export declare const PROFILE_DIR: string;
  * @throws {Error} When `agent-browser` exits with a non-zero code or times out
  */
 export declare function ab(args: string[], timeoutMs?: number): string;
-/**
- * Extracts the user-facing error message from an agent-browser failure.
- *
- * Strips ANSI escape codes from stderr and returns only the diagnostic
- * lines prefixed with `✗` or `⚠`. Falls back to the first 200 characters
- * of the error message when no diagnostic lines are found.
- *
- * @param err - The caught error (typically from {@link ab})
- * @returns A single-line summary suitable for console output
- */
-export declare function abErrorMessage(err: unknown): string;

package/dist/types/utils/create-run-dir.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Creates a timestamped, run-specific output directory for eval artifacts.
+ *
+ * @param title - Human label used as the directory name prefix (slugified)
+ * @param baseDir - Optional parent directory override
+ * @returns Absolute path to the newly created directory
+ */
+export declare function createRunDir(title: string, baseDir?: string): string;

package/dist/types/utils/{process.d.ts → helpers.d.ts}

@@ -1,10 +1,6 @@
 import type { ChildProcess } from 'node:child_process';
-/**
- * Sends `SIGTERM` to a child process if it is still running.
- *
- * @param proc - The child process to terminate (no-op when `undefined` or already killed)
- */
-export declare function cleanup(proc?: ChildProcess): void;
+/** Persistent Chrome profile directory used across agent-browser sessions. */
+export declare const PROFILE_DIR: string;
 /**
  * Returns a promise that resolves after the given delay.
  *
@@ -19,3 +15,14 @@ export declare function sleep(ms: number): Promise<void>;
  * @returns The input string with all ANSI escape sequences removed
  */
 export declare function stripAnsi(s: string): string;
+/**
+ * Sends `SIGTERM` to a child process if it is still running.
+ *
+ * @param proc - The child process to terminate (no-op when `undefined` or already killed)
+ */
+export declare function cleanup(proc?: ChildProcess): void;
+/**
+ * Clears the MSAL `interaction.status` flag from `sessionStorage` in the
+ * running browser via `agent-browser eval`.
+ */
+export declare function clearMsalInteraction(): void;

package/dist/types/utils/index.d.ts

@@ -1,5 +1,8 @@
-export { ab, abErrorMessage, PROFILE_DIR } from './agent-browser.js';
-export { resetDaemon, clearMsalInteraction } from './daemon.js';
-export { cleanup, sleep, stripAnsi } from './process.js';
-export { createRunDir, resolveAppKey, waitForServer } from './server.js';
-export { pollConsole } from './browser-poll.js';
+export { ab } from './ab.js';
+export { abErrorMessage } from './ab-error-message.js';
+export { PROFILE_DIR, sleep, stripAnsi, cleanup, clearMsalInteraction } from './helpers.js';
+export { resetDaemon } from './reset-daemon.js';
+export { createRunDir } from './create-run-dir.js';
+export { resolveAppKey } from './resolve-app-key.js';
+export { waitForServer } from './wait-for-server.js';
+export { pollConsole } from './poll-console.js';

package/dist/types/utils/{daemon.d.ts → reset-daemon.d.ts}

@@ -9,8 +9,3 @@
  * 4. Delete Session Storage to clear stuck MSAL `interaction.status` flags
  */
 export declare function resetDaemon(): void;
-/**
- * Clears the MSAL `interaction.status` flag from `sessionStorage` in the
- * running browser via `agent-browser eval`.
- */
-export declare function clearMsalInteraction(): void;

package/dist/types/utils/resolve-app-key.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolves the Fusion `appKey` by running `ffc app manifest --silent`
+ * in the given application directory and parsing the JSON output.
+ *
+ * @param appDir - Absolute path to the Fusion application
+ * @returns The `appKey` string from the manifest
+ * @throws {Error} When `ffc app manifest` fails or returns invalid JSON
+ */
+export declare function resolveAppKey(appDir: string): string;

package/dist/types/utils/wait-for-server.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Polls a server URL until it responds with a non-5xx status or the
+ * timeout is reached.
+ *
+ * @param url - The URL to poll (e.g. `http://localhost:3000`)
+ * @param timeoutSeconds - Maximum number of seconds to wait
+ * @returns `true` if the server responded before timeout, `false` otherwise
+ */
+export declare function waitForServer(url: string, timeoutSeconds: number): Promise<boolean>;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "2.0.2";
+export declare const version = "2.0.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-cli-plugin-copilot",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "Copilot SDK powered evaluation plugin for Fusion Framework CLI",
   "type": "module",
   "main": "dist/esm/index.js",
@@ -44,11 +44,11 @@
     "rxjs": "^7.8.2"
   },
   "peerDependencies": {
-    "@equinor/fusion-framework-cli": "^15.1.1"
+    "@equinor/fusion-framework-cli": "^15.2.1"
   },
   "devDependencies": {
-    "typescript": "^6.0.3",
-    "@equinor/fusion-framework-cli": "^15.1.1"
+    "typescript": "^7.0.2",
+    "@equinor/fusion-framework-cli": "^15.2.1"
   },
   "scripts": {
     "build": "tsc -b",

package/src/commands/app/{session-logger.ts → attach-session-logger.ts}

@@ -3,7 +3,7 @@ import ora from 'ora';
 
 import type { CopilotSession } from '@github/copilot-sdk';
 
-import { tryFormatMessage } from './format.js';
+import { tryFormatMessage } from './try-format-message.js';
 
 const TOOL_ICONS: Record<string, string> = {
   browser_screenshot: '📷',
@@ -31,7 +31,9 @@ export function attachSessionLogger(
   let spinner: ReturnType<typeof ora> | null = null;
 
   function syncSpinner(): void {
+    // No pending tools means the spinner has nothing left to show
     if (pendingTools.size === 0) {
+      // Stop the spinner only if one was actually running
       if (spinner) {
         spinner.stop();
         spinner = null;
@@ -39,6 +41,7 @@ export function attachSessionLogger(
       return;
     }
     const text = [...pendingTools.values()].join(chalk.dim(' | '));
+    // Reuse the existing spinner instance rather than starting a second one
     if (spinner) {
       spinner.text = text;
     } else {
@@ -47,6 +50,7 @@ export function attachSessionLogger(
   }
 
   function pauseSpinner(): void {
+    // Only stop the spinner if one is actually running
     if (spinner) {
       spinner.stop();
       spinner = null;
@@ -61,6 +65,7 @@ export function attachSessionLogger(
   }
 
   session.on((event) => {
+    // Dispatch on the Copilot SDK session event type to render the right log line
     switch (event.type) {
       case 'tool.execution_start': {
         const { toolCallId, toolName, arguments: args } = event.data;
@@ -74,6 +79,7 @@ export function attachSessionLogger(
       }
       case 'tool.execution_complete': {
         const label = pendingTools.get(event.data.toolCallId);
+        // Only log completion for tools we actually tracked the start of
         if (label) {
           pendingTools.delete(event.data.toolCallId);
           logCompletion(label, event.data.success);
@@ -82,6 +88,7 @@ export function attachSessionLogger(
       }
       case 'external_tool.completed': {
         const label = pendingTools.get(event.data.requestId);
+        // Only log completion for tools we actually tracked the start of
         if (label) {
           pendingTools.delete(event.data.requestId);
           logCompletion(label, true);
@@ -95,9 +102,11 @@ export function attachSessionLogger(
         break;
       }
       case 'assistant.message': {
+        // Skip empty assistant messages (e.g. tool-only turns)
         if (event.data.content) {
           pauseSpinner();
           const formatted = tryFormatMessage(event.data.content);
+          // Prefer the structured plan/verdict/step-result rendering when recognised
           if (formatted) {
             console.log(formatted);
           } else {
@@ -119,6 +128,7 @@ export function attachSessionLogger(
       }
       case 'permission.completed': {
         const label = pendingTools.get(event.data.requestId);
+        // Only log completion for permissions we actually tracked the request of
         if (label) {
           const approved = event.data.result?.kind === 'approved';
           pendingTools.delete(event.data.requestId);
@@ -128,8 +138,10 @@ export function attachSessionLogger(
       }
       case 'session.tools_updated': {
         const negotiatedModel = event.data.model as string | undefined;
+        // Only log tooling info once the server has actually negotiated a model
         if (negotiatedModel) {
           console.log(chalk.dim(`💾  ${negotiatedModel}`));
+          // Warn the user when the server picked a different model than requested
           if (options?.requestedModel && negotiatedModel !== options.requestedModel) {
             console.log(
               chalk.yellow(
@@ -157,6 +169,7 @@ export function attachSessionLogger(
       }
       case 'session.info': {
         const { message } = event.data as { message?: string };
+        // Skip empty info events
         if (message) {
           pauseSpinner();
           console.log(chalk.dim(`ℹ️  ${message}`));
@@ -166,6 +179,7 @@ export function attachSessionLogger(
       }
       case 'assistant.intent': {
         const { intent } = event.data as { intent?: string };
+        // Skip empty intent events
         if (intent) {
           pauseSpinner();
           console.log(chalk.yellow(`🎯 ${intent}`));

package/src/commands/app/{command.ts → copilot-command.ts}

@@ -2,17 +2,18 @@ import { createCommand } from 'commander';
 import { basename } from 'node:path';
 
 import { resetDaemon, cleanup, createRunDir } from '../../utils/index.js';
-import { runLogin } from './login.js';
-import { resolveEvalCommandInput, resolveEvalFiles } from '../../eval-resolve.js';
-import { createSession } from './eval.js';
-import { startAppServer } from './server.js';
-import { attachSessionLogger } from './session-logger.js';
+import { runLogin } from './run-login.js';
+import { resolveEvalCommandInput } from '../../resolve-eval-command-input.js';
+import { resolveEvalFiles } from '../../resolve-eval-files.js';
+import { createSession } from './create-session.js';
+import { startAppServer } from './start-app-server.js';
+import { attachSessionLogger } from './attach-session-logger.js';
 import type { CopilotEvalOptions, Plan, Verdict } from './types.js';
-import { formatVerdict } from './format.js';
+import { formatVerdict } from './format-verdict.js';
 import { existsSync, readFileSync } from 'node:fs';
-import { createPlanPrompt } from './prompts/plan.prompt.js';
-import { createStepPrompt } from './prompts/step.prompt.js';
-import { createJudgePrompt } from './prompts/judge.prompt.js';
+import { createPlanPrompt } from './prompts/create-plan-prompt.js';
+import { createStepPrompt } from './prompts/create-step-prompt.js';
+import { createJudgePrompt } from './prompts/create-judge-prompt.js';
 import chalk from 'chalk';
 
 /**
@@ -58,6 +59,7 @@ const _appEvalCommand = createCommand('eval')
     const port = parseInt(options.port, 10);
     const verbose = options.verbose;
 
+    // Reject ambiguous input that selects an eval two different ways
     if (resolvedInput.evalFile && options.eval) {
       console.error('❌ Do not combine a positional eval markdown file with --eval');
       process.exit(1);
@@ -73,9 +75,9 @@ const _appEvalCommand = createCommand('eval')
     const evalFiles = resolvedInput.evalFile
       ? [resolvedInput.evalFile]
       : resolveEvalFiles(absAppPath, options.eval);
-    console.log(
-      `📋 Found ${evalFiles.length} eval(s): ${evalFiles.map((f) => basename(f)).join(', ')}`,
-    );
+    // Summarize which eval files were discovered before the run starts
+    const evalFileNames = evalFiles.map((f) => basename(f)).join(', ');
+    console.log(`📋 Found ${evalFiles.length} eval(s): ${evalFileNames}`);
 
     // Start the app dev server (unless --url provides an already-running URL)
     const { serverProcess, appUrl } = await startAppServer(absAppPath, {
@@ -103,6 +105,7 @@ const _appEvalCommand = createCommand('eval')
 
     let failures = 0;
     try {
+      // Run every resolved eval file sequentially so output stays readable
       for (const evalFilePath of evalFiles) {
         const evalName = basename(evalFilePath, '.md');
         const query = readFileSync(evalFilePath, 'utf-8').trim();
@@ -129,6 +132,7 @@ const _appEvalCommand = createCommand('eval')
           await session.sendAndWait({ prompt: createPlanPrompt(query, ctx) }, 300_000);
 
           const planPath = `${runDir}/plan.json`;
+          // Bail out of this eval when the planning phase produced no plan file
           if (!existsSync(planPath)) {
             console.error(
               chalk.red(
@@ -138,6 +142,7 @@ const _appEvalCommand = createCommand('eval')
             session.disconnect();
             logger.stop();
             failures++;
+            // Skip execution/judging phases; this eval already failed at planning
             continue;
           }
 
@@ -147,6 +152,7 @@ const _appEvalCommand = createCommand('eval')
           // ── Phase 2: Execute + Evaluate each step ──────────────────
           for (const step of plan.steps) {
             console.log(chalk.cyan(`\n── Scenario: ${step.scenario}`));
+            // Print each acceptance criterion the agent will be judged against
             for (const c of step.criteria) {
               console.log(chalk.dim(`   • ${c}`));
             }
@@ -162,9 +168,11 @@ const _appEvalCommand = createCommand('eval')
 
           // Print the verdict
           const verdictPath = `${runDir}/verdict.json`;
+          // Only report a verdict when the judge phase actually produced one
           if (existsSync(verdictPath)) {
             const verdict = JSON.parse(readFileSync(verdictPath, 'utf-8')) as Verdict;
             console.log(formatVerdict(verdict));
+            // A failing verdict counts toward the overall exit-code failure total
             if (!verdict.pass) failures++;
           } else {
             console.error(chalk.red(`❌ Judge did not produce ${verdictPath}.`));
@@ -174,6 +182,7 @@ const _appEvalCommand = createCommand('eval')
           logger?.stop();
           const msg = err instanceof Error ? err.message : String(err);
           console.error(chalk.red(`\n❌ Eval "${evalName}" failed: ${msg}`));
+          // Print the stack trace too when one is available for debugging
           if (err instanceof Error && err.stack) {
             console.error(chalk.dim(err.stack));
           }

package/src/commands/app/{eval.ts → create-session.ts}

@@ -3,12 +3,13 @@ import { join } from 'node:path';
 
 import { ab, abErrorMessage } from '../../utils/index.js';
 import { createAgentBrowserTools } from './tools/index.js';
-import { createWriteFileTool, createAppendFileTool } from './tools/write-file.js';
-import { createReadFileTool } from './tools/read-file.js';
+import { createWriteFileTool } from './tools/create-write-file-tool.js';
+import { createAppendFileTool } from './tools/create-append-file-tool.js';
+import { createReadFileTool } from './tools/create-read-file-tool.js';
 import type { RuntimeExecutionContext } from './types.js';
 import type { CopilotSession, SessionConfig } from '@github/copilot-sdk';
-import { createSystemPrompt } from './prompts/system.prompt.js';
-import { createDevServerContext } from './prompts/system.dev-server.prompt.js';
+import { createSystemPrompt } from './prompts/create-system-prompt.js';
+import { createDevServerContext } from './prompts/create-dev-server-context.js';
 
 /**
  * Lazily imports the Copilot SDK to avoid module resolution errors at CLI startup.
@@ -44,6 +45,7 @@ export const createSession = async (options: SessionOptions): Promise<CopilotSes
     createAppendFileTool(ctx.outDir, defineTool),
   ];
 
+  // Combine built-in browser and file tools with any caller-supplied tools
   const tools = [
     ...createBrowserTools(defineTool, {
       cwd: ctx.outDir,

package/src/commands/app/format-plan.ts

@@ -0,0 +1,26 @@
+import chalk from 'chalk';
+
+import type { Plan } from './types.js';
+import { truncate } from './truncate.js';
+
+/**
+ * Renders a structured plan as a human-readable summary.
+ *
+ * @param plan - The plan to render, containing a summary and ordered steps.
+ * @returns A multi-line string suitable for console output.
+ */
+export function formatPlan(plan: Plan): string {
+  const lines = [
+    '',
+    chalk.bold(`📋 ${plan.summary}`),
+    '',
+    ...plan.steps.flatMap((s, si) => [
+      `  ${chalk.dim(`${si + 1}.`)} ${s.scenario}`,
+      ...s.criteria
+        // Truncate each criterion so long descriptions don't wrap the terminal
+        .map((c) => chalk.dim(`     • ${truncate(c, 70)}`)),
+    ]),
+    '',
+  ];
+  return lines.join('\n');
+}

package/src/commands/app/format-step-result.ts

@@ -0,0 +1,16 @@
+import chalk from 'chalk';
+
+import type { StepResult } from './types.js';
+import { statusIcon } from './status-icon.js';
+
+/**
+ * Renders a single step execution result.
+ *
+ * @param result - The step result to render, including its outcome, note, and evidence.
+ * @returns A formatted two-line string describing the step outcome.
+ */
+export function formatStepResult(result: StepResult): string {
+  const icon = statusIcon(result.ok);
+  const files = result.evidence.length ? chalk.dim(` [${result.evidence.join(', ')}]`) : '';
+  return `  ${icon}  ${result.criterion}\n${chalk.dim(`     ${result.note}`)}${files}`;
+}

package/src/commands/app/format-verdict.ts

@@ -0,0 +1,43 @@
+import chalk from 'chalk';
+
+import type { Verdict } from './types.js';
+import { statusIcon } from './status-icon.js';
+
+/**
+ * Renders the final verdict as a full-width coloured report.
+ *
+ * @param verdict - The verdict to render, including per-step results, reasoning, and UX feedback.
+ * @returns A multi-line string suitable for console output.
+ */
+export function formatVerdict(verdict: Verdict): string {
+  const bar = '═'.repeat(60);
+  const banner = verdict.pass
+    ? chalk.bgGreen.black.bold(' ✅ PASS ')
+    : chalk.bgRed.white.bold(' ❌ FAIL ');
+
+  const lines = [
+    '',
+    bar,
+    `  ${banner}`,
+    bar,
+    '',
+    ...verdict.steps
+      // Render each step's outcome as a status glyph, criterion, and note
+      .map((s) => `  ${statusIcon(s.ok)}  ${s.criterion}\n${chalk.dim(`     ${s.note}`)}`),
+    '',
+    chalk.dim(`  ${verdict.reasoning}`),
+    '',
+  ];
+
+  // Append optional UX feedback only when the judge actually provided any
+  if (verdict.ux && verdict.ux.length > 0) {
+    lines.push(chalk.bold('  💡 UX Feedback'), '');
+    // List every UX hint as its own bullet line
+    for (const hint of verdict.ux) {
+      lines.push(chalk.yellow(`  • ${hint}`));
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/commands/app/prompts/{judge.prompt.ts → create-judge-prompt.ts}

@@ -19,6 +19,7 @@ function collectEvidence(outDir: string): string {
 
   // ── executions.jsonl ──
   const execPath = join(outDir, 'executions.jsonl');
+  // Fall back to a placeholder note when the executions log is missing
   if (existsSync(execPath)) {
     parts.push('### executions.jsonl', readFileSync(execPath, 'utf-8').trim());
   } else {
@@ -27,10 +28,13 @@ function collectEvidence(outDir: string): string {
 
   // ── evidence/ directory ──
   const evidenceDir = join(outDir, 'evidence');
+  // Only scan for evidence files when the directory actually exists
   if (existsSync(evidenceDir)) {
     const files = readdirSync(evidenceDir).sort();
+    // Inline readable text evidence; list binary evidence by name only
     for (const file of files) {
       const ext = extname(file).toLowerCase();
+      // Inline the content of readable text extensions; list other files by name only
       if (TEXT_EXTENSIONS.has(ext)) {
         const content = readFileSync(join(evidenceDir, file), 'utf-8').trim();
         parts.push(`### evidence/${file}`, content);

package/src/commands/app/prompts/{step.prompt.ts → create-step-prompt.ts}

@@ -10,8 +10,9 @@ import type { PlanStep, RuntimeExecutionContext } from '../types.js';
  * @param ctx - Runtime context with output directory and app URL
  * @returns The fully interpolated prompt string
  */
-export const createStepPrompt = (step: PlanStep, ctx: RuntimeExecutionContext): string => {
+export const createStepPrompt = (step: PlanStep, _ctx: RuntimeExecutionContext): string => {
   const slug = slugify(step.scenario);
+  // Render each criterion with its expected pass/fail evidence for the prompt
   const criteriaBlock = step.criteria
     .map((c, i) => `${i + 1}. ${c}\n   Pass: ${step.pass[i] ?? ''}\n   Fail: ${step.fail[i] ?? ''}`)
     .join('\n');