selftune 0.2.23 → 0.2.24

package/cli/selftune/evolution/validate-proposal.ts

@@ -6,17 +6,14 @@
  * to determine whether the proposal is an improvement.
  */
 
-import type { EvalEntry, EvolutionProposal, InvocationTypeScores } from "../types.js";
+import type {
+  EvalEntry,
+  EvolutionProposal,
+  InvocationTypeScores,
+  ValidationMode,
+} from "../types.js";
 import { callLlm, type EffortLevel } from "../utils/llm-call.js";
-import {
-  buildBatchTriggerCheckPrompt,
-  buildTriggerCheckPrompt,
-  parseBatchTriggerResponse,
-  parseTriggerResponse,
-} from "../utils/trigger-check.js";
-
-// Re-export so existing consumers don't break
-export { buildTriggerCheckPrompt, parseTriggerResponse };
+import { buildBatchTriggerCheckPrompt, parseBatchTriggerResponse } from "../utils/trigger-check.js";
 
 /** Number of eval queries to batch into a single LLM call.
  * Higher = fewer claude -p spawns = much faster (each spawn has ~30-60s overhead).
@@ -40,147 +37,11 @@ export interface ValidationResult {
   net_change: number; // after - before pass rate
   by_invocation_type?: InvocationTypeScores;
   per_entry_results?: Array<{ entry: EvalEntry; before_pass: boolean; after_pass: boolean }>;
-  validation_mode?: "llm_judge";
+  validation_mode?: ValidationMode;
   validation_agent?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Proposal validation
-// ---------------------------------------------------------------------------
-
-/** Validate a proposal sequentially (one LLM call per query). Kept for backward compat. */
-export async function validateProposalSequential(
-  proposal: EvolutionProposal,
-  evalSet: EvalEntry[],
-  agent: string,
-  modelFlag?: string,
-  effort?: EffortLevel,
-): Promise<ValidationResult> {
-  if (evalSet.length === 0) {
-    return {
-      proposal_id: proposal.proposal_id,
-      before_pass_rate: 0,
-      after_pass_rate: 0,
-      improved: false,
-      regressions: [],
-      new_passes: [],
-      net_change: 0,
-      validation_mode: "llm_judge",
-      validation_agent: agent,
-    };
-  }
-
-  const systemPrompt = "You are an evaluation assistant. Answer only YES or NO.";
-  const regressions: EvalEntry[] = [];
-  const newPasses: EvalEntry[] = [];
-  const perEntryResults: Array<{ entry: EvalEntry; before_pass: boolean; after_pass: boolean }> =
-    [];
-  let beforePassed = 0;
-  let afterPassed = 0;
-
-  for (const entry of evalSet) {
-    // Check with original description
-    const beforePrompt = buildTriggerCheckPrompt(proposal.original_description, entry.query);
-    const beforeRaw = await callLlm(systemPrompt, beforePrompt, agent, modelFlag, effort);
-    const beforeTriggered = parseTriggerResponse(beforeRaw);
-    const beforePass =
-      (entry.should_trigger && beforeTriggered) || (!entry.should_trigger && !beforeTriggered);
-
-    // Check with proposed description
-    const afterPrompt = buildTriggerCheckPrompt(proposal.proposed_description, entry.query);
-    const afterRaw = await callLlm(systemPrompt, afterPrompt, agent, modelFlag, effort);
-    const afterTriggered = parseTriggerResponse(afterRaw);
-    const afterPass =
-      (entry.should_trigger && afterTriggered) || (!entry.should_trigger && !afterTriggered);
-
-    if (beforePass) beforePassed++;
-    if (afterPass) afterPassed++;
-
-    // Regression: passed before, fails after
-    if (beforePass && !afterPass) {
-      regressions.push(entry);
-    }
-
-    // New pass: failed before, passes after
-    if (!beforePass && afterPass) {
-      newPasses.push(entry);
-    }
-
-    perEntryResults.push({ entry, before_pass: beforePass, after_pass: afterPass });
-  }
-
-  const total = evalSet.length;
-  const beforePassRate = beforePassed / total;
-  const afterPassRate = afterPassed / total;
-  const netChange = afterPassRate - beforePassRate;
-
-  // A proposal is improved when ALL of:
-  //   - after_pass_rate > before_pass_rate
-  //   - regressions count < 5% of total eval entries
-  //   - Either net improvement >= 0.10 OR new_passes.length >= 2
-  const improved =
-    afterPassRate > beforePassRate &&
-    regressions.length < total * 0.05 &&
-    (netChange >= 0.1 || newPasses.length >= 2);
-
-  // Compute per-invocation-type scores (initialize all required keys)
-  const byInvocationType: Record<string, { passed: number; total: number }> = {
-    explicit: { passed: 0, total: 0 },
-    implicit: { passed: 0, total: 0 },
-    contextual: { passed: 0, total: 0 },
-    negative: { passed: 0, total: 0 },
-  };
-  for (const r of perEntryResults) {
-    const type = r.entry.invocation_type ?? "implicit";
-    if (!byInvocationType[type]) byInvocationType[type] = { passed: 0, total: 0 };
-    byInvocationType[type].total++;
-    if (r.after_pass) byInvocationType[type].passed++;
-  }
-
-  const invocationScores: InvocationTypeScores = {
-    explicit: {
-      ...byInvocationType.explicit,
-      pass_rate:
-        byInvocationType.explicit.total > 0
-          ? byInvocationType.explicit.passed / byInvocationType.explicit.total
-          : 0,
-    },
-    implicit: {
-      ...byInvocationType.implicit,
-      pass_rate:
-        byInvocationType.implicit.total > 0
-          ? byInvocationType.implicit.passed / byInvocationType.implicit.total
-          : 0,
-    },
-    contextual: {
-      ...byInvocationType.contextual,
-      pass_rate:
-        byInvocationType.contextual.total > 0
-          ? byInvocationType.contextual.passed / byInvocationType.contextual.total
-          : 0,
-    },
-    negative: {
-      ...byInvocationType.negative,
-      pass_rate:
-        byInvocationType.negative.total > 0
-          ? byInvocationType.negative.passed / byInvocationType.negative.total
-          : 0,
-    },
-  };
-
-  return {
-    proposal_id: proposal.proposal_id,
-    before_pass_rate: beforePassRate,
-    after_pass_rate: afterPassRate,
-    improved,
-    regressions,
-    new_passes: newPasses,
-    net_change: netChange,
-    by_invocation_type: invocationScores,
-    per_entry_results: perEntryResults,
-    validation_mode: "llm_judge",
-    validation_agent: agent,
-  };
+  validation_fixture_id?: string;
+  validation_fallback_reason?: string;
+  before_entry_results?: Array<{ entry: EvalEntry; before_pass: boolean; after_pass: boolean }>;
 }
 
 // ---------------------------------------------------------------------------

package/cli/selftune/evolution/validate-routing.ts

@@ -13,20 +13,12 @@ import type {
   BodyValidationResult,
   EvalEntry,
   RoutingReplayEntryResult,
+  ValidationGate,
   ValidationMode,
 } from "../types.js";
 import { runJudgeValidation } from "./engines/judge-engine.js";
-import {
-  runReplayValidation,
-  type ReplayRunner,
-  type ReplayRunnerInput,
-  type ReplayValidationOptions,
-} from "./engines/replay-engine.js";
-
-// Re-export engine types for backward compatibility
-export type { ReplayRunnerInput as RoutingReplayRunnerInput };
-export type { ReplayRunner as RoutingReplayRunner };
-export type { ReplayValidationOptions as RoutingValidationOptions };
+import { type ReplayValidationOptions } from "./engines/replay-engine.js";
+import { runValidationContract, type ValidationStrategy } from "./validation-contract.js";
 
 export interface RoutingTriggerAccuracyResult {
   before_pass_rate: number;
@@ -35,10 +27,16 @@ export interface RoutingTriggerAccuracyResult {
   validation_mode: ValidationMode;
   validation_agent: string;
   validation_fixture_id?: string;
+  validation_fallback_reason?: string;
   per_entry_results?: RoutingReplayEntryResult[];
   before_entry_results?: RoutingReplayEntryResult[];
 }
 
+export interface RoutingValidationOptions extends ReplayValidationOptions {
+  mode?: ValidationStrategy;
+  onReplayFallback?: (reason?: string) => void;
+}
+
 // ---------------------------------------------------------------------------
 // Structural validation
 // ---------------------------------------------------------------------------
@@ -101,7 +99,7 @@ export function validateRoutingStructure(routing: string): { valid: boolean; rea
  * Run before/after trigger checks on the eval set using the routing content.
  * Returns pass rates for comparison.
  *
- * Prefers replay-backed validation when a fixture is available,
+ * Prefers host/runtime replay when a runtime runner is available,
  * falls back to LLM judge otherwise.
  */
 export async function validateRoutingTriggerAccuracy(
@@ -110,7 +108,7 @@ export async function validateRoutingTriggerAccuracy(
   evalSet: EvalEntry[],
   agent: string,
   modelFlag?: string,
-  options: ReplayValidationOptions = {},
+  options: RoutingValidationOptions = {},
 ): Promise<RoutingTriggerAccuracyResult> {
   if (evalSet.length === 0) {
     return {
@@ -122,35 +120,38 @@ export async function validateRoutingTriggerAccuracy(
     };
   }
 
-  // Try replay-backed validation first
-  const replayResult = await runReplayValidation(
-    originalRouting,
-    proposedRouting,
-    evalSet,
-    agent,
-    options,
-  );
-
-  if (replayResult) {
-    return replayResult;
-  }
-
-  // Fall back to LLM judge
-  const judgeResult = await runJudgeValidation(
-    originalRouting,
-    proposedRouting,
+  const { result, fallbackReason } = await runValidationContract<RoutingTriggerAccuracyResult>({
+    mode: options.mode ?? "auto",
+    originalContent: originalRouting,
+    proposedContent: proposedRouting,
     evalSet,
     agent,
-    modelFlag,
-  );
+    replayOptions: options,
+    runJudge: async () => {
+      const judgeResult = await runJudgeValidation(
+        originalRouting,
+        proposedRouting,
+        evalSet,
+        agent,
+        modelFlag,
+      );
+
+      return {
+        result: {
+          before_pass_rate: judgeResult.before_pass_rate,
+          after_pass_rate: judgeResult.after_pass_rate,
+          improved: judgeResult.improved,
+          validation_mode: judgeResult.validation_mode,
+          validation_agent: judgeResult.validation_agent,
+        },
+        modeUsed: judgeResult.validation_mode,
+      };
+    },
+    onReplayFallback: options.onReplayFallback,
+    adaptReplayResult: (replayResult) => replayResult,
+  });
 
-  return {
-    before_pass_rate: judgeResult.before_pass_rate,
-    after_pass_rate: judgeResult.after_pass_rate,
-    improved: judgeResult.improved,
-    validation_mode: judgeResult.validation_mode,
-    validation_agent: judgeResult.validation_agent,
-  };
+  return fallbackReason ? { ...result, validation_fallback_reason: fallbackReason } : result;
 }
 
 // ---------------------------------------------------------------------------
@@ -163,9 +164,9 @@ export async function validateRoutingProposal(
   evalSet: EvalEntry[],
   agent: string,
   modelFlag?: string,
-  options: ReplayValidationOptions = {},
+  options: RoutingValidationOptions = {},
 ): Promise<BodyValidationResult> {
-  const gateResults: Array<{ gate: string; passed: boolean; reason: string }> = [];
+  const gateResults: Array<{ gate: ValidationGate; passed: boolean; reason: string }> = [];
 
   // Gate 1: Structural validation
   const structural = validateRoutingStructure(proposal.proposed_body);
@@ -217,6 +218,7 @@ export async function validateRoutingProposal(
     validation_mode: accuracy.validation_mode,
     validation_agent: accuracy.validation_agent,
     validation_fixture_id: accuracy.validation_fixture_id,
+    validation_fallback_reason: accuracy.validation_fallback_reason,
     before_pass_rate: accuracy.before_pass_rate,
     after_pass_rate: accuracy.after_pass_rate,
     per_entry_results: accuracy.per_entry_results,

package/cli/selftune/evolution/validation-contract.ts

@@ -0,0 +1,91 @@
+import type { EvalEntry, ValidationMode } from "../types.js";
+import { CLIError } from "../utils/cli-error.js";
+import {
+  runReplayValidation,
+  type ReplayValidationOptions,
+  type ReplayValidationResult,
+} from "./engines/replay-engine.js";
+
+export type ValidationStrategy = "auto" | "replay" | "judge";
+
+export const DEFAULT_VALIDATION_STRATEGY: ValidationStrategy = "auto";
+
+export interface ValidationExecutionResult<TResult> {
+  result: TResult;
+  modeUsed: ValidationMode;
+  fallbackReason?: string;
+}
+
+export interface ValidationContractOptions<TResult> {
+  mode?: ValidationStrategy;
+  originalContent: string;
+  proposedContent: string;
+  evalSet: EvalEntry[];
+  agent: string;
+  replayOptions?: ReplayValidationOptions;
+  runJudge: () => Promise<ValidationExecutionResult<TResult>>;
+  adaptReplayResult: (replayResult: ReplayValidationResult) => TResult;
+  onReplayFallback?: (reason?: string) => void;
+}
+
+export function hasReplayValidationPath(
+  replayOptions?: ReplayValidationOptions,
+): replayOptions is ReplayValidationOptions {
+  return Boolean(replayOptions?.replayFixture || replayOptions?.replayRunner);
+}
+
+export function createReplayUnavailableError(reason?: string): CLIError {
+  const message = reason
+    ? `Replay validation requested but real host/runtime replay is unavailable: ${reason}`
+    : "Replay validation requested but real host/runtime replay is unavailable.";
+  return new CLIError(
+    message,
+    "REPLAY_UNAVAILABLE",
+    "Use --validation-mode auto to allow LLM judge fallback, or run selftune on a host/agent with runtime replay support for this skill.",
+  );
+}
+
+export async function runValidationContract<TResult>(
+  options: ValidationContractOptions<TResult>,
+): Promise<ValidationExecutionResult<TResult>> {
+  const mode = options.mode ?? DEFAULT_VALIDATION_STRATEGY;
+
+  if (mode === "judge") {
+    return options.runJudge();
+  }
+
+  if (hasReplayValidationPath(options.replayOptions)) {
+    const replayAttempt = await runReplayValidation(
+      options.originalContent,
+      options.proposedContent,
+      options.evalSet,
+      options.agent,
+      options.replayOptions,
+    );
+
+    if (replayAttempt.result) {
+      return {
+        result: options.adaptReplayResult(replayAttempt.result),
+        modeUsed: replayAttempt.result.validation_mode,
+      };
+    }
+
+    if (mode === "replay") {
+      throw createReplayUnavailableError(replayAttempt.fallbackReason);
+    }
+
+    options.onReplayFallback?.(replayAttempt.fallbackReason);
+    const judgeResult = await options.runJudge();
+    return {
+      ...judgeResult,
+      fallbackReason: replayAttempt.fallbackReason,
+    };
+  }
+
+  if (mode === "replay") {
+    throw createReplayUnavailableError();
+  }
+
+  options.onReplayFallback?.();
+  return options.runJudge();
+}

package/cli/selftune/grading/auto-grade.ts

@@ -13,12 +13,16 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { parseArgs } from "node:util";
 
-import { AGENT_CANDIDATES, TELEMETRY_LOG } from "../constants.js";
+import { TELEMETRY_LOG } from "../constants.js";
 import { getDb } from "../localdb/db.js";
 import { querySessionTelemetry, querySkillUsageRecords } from "../localdb/queries.js";
 import type { GradingResult, SessionTelemetryRecord, SkillUsageRecord } from "../types.js";
 import { CLIError, handleCLIError } from "../utils/cli-error.js";
-import { detectAgent as _detectAgent } from "../utils/llm-call.js";
+import {
+  detectLlmAgent as _detectAgent,
+  isLlmBackedAgent,
+  LLM_BACKED_AGENT_CANDIDATES,
+} from "../utils/llm-call.js";
 import { readExcerpt } from "../utils/transcript.js";
 import {
   buildDefaultGradingOutputPath,
@@ -55,7 +59,7 @@ Options:
   --session-id        Grade a specific session (auto-detects most recent if omitted)
   --telemetry-log     Path to telemetry log (default: ~/.claude/session_telemetry_log.jsonl)
   --output            Output path for grading JSON (default: ~/.selftune/grading/result-<session>.json)
-  --agent             Agent CLI to use (${AGENT_CANDIDATES.join(", ")})
+  --agent             Agent CLI to use (${LLM_BACKED_AGENT_CANDIDATES.join(", ")})
   --show-transcript   Print transcript excerpt before grading
   -h, --help          Show this help message`);
     process.exit(0);
@@ -68,9 +72,9 @@ Options:
 
   // --- Determine agent ---
   let agent: string | null = null;
-  const validAgents = [...AGENT_CANDIDATES];
+  const validAgents = [...LLM_BACKED_AGENT_CANDIDATES];
   if (values.agent) {
-    if (!validAgents.includes(values.agent)) {
+    if (!isLlmBackedAgent(values.agent)) {
       throw new CLIError(
         `Invalid --agent '${values.agent}'. Expected one of: ${validAgents.join(", ")}`,
         "INVALID_FLAG",
@@ -84,9 +88,9 @@ Options:
 
   if (!agent) {
     throw new CLIError(
-      `No supported agent CLI (${AGENT_CANDIDATES.join("/")}) found in PATH`,
+      `No supported agent CLI (${LLM_BACKED_AGENT_CANDIDATES.join("/")}) found in PATH`,
       "AGENT_NOT_FOUND",
-      "Install one of the supported agent CLIs",
+      "Install Claude Code, Codex, OpenCode, or Pi",
     );
   }
 

package/cli/selftune/grading/grade-session.ts

@@ -5,19 +5,14 @@
  * Rubric-based grader for Claude Code skill sessions.
  * Migrated from grade_session.py.
  *
- * Grades via an installed agent CLI selected from AGENT_CANDIDATES.
+ * Grades via an installed agent CLI selected from the LLM-backed agent set.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { parseArgs } from "node:util";
 
-import {
-  AGENT_CANDIDATES,
-  CLAUDE_CODE_PROJECTS_DIR,
-  SELFTUNE_CONFIG_DIR,
-  TELEMETRY_LOG,
-} from "../constants.js";
+import { CLAUDE_CODE_PROJECTS_DIR, SELFTUNE_CONFIG_DIR, TELEMETRY_LOG } from "../constants.js";
 import { getDb } from "../localdb/db.js";
 import { querySessionTelemetry, querySkillUsageRecords } from "../localdb/queries.js";
 import type {
@@ -31,7 +26,9 @@ import type {
 } from "../types.js";
 import { CLIError, handleCLIError } from "../utils/cli-error.js";
 import {
-  detectAgent as _detectAgent,
+  detectLlmAgent as _detectAgent,
+  isLlmBackedAgent,
+  LLM_BACKED_AGENT_CANDIDATES,
   stripMarkdownFences as _stripMarkdownFences,
   callViaAgent,
 } from "../utils/llm-call.js";
@@ -42,9 +39,6 @@ import {
 } from "../utils/transcript.js";
 import { type PreGateContext, runPreGates } from "./pre-gates.js";
 
-// Re-export for backward compatibility
-export { detectAgent, stripMarkdownFences } from "../utils/llm-call.js";
-
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -756,7 +750,7 @@ Options:
   --transcript        Path to transcript file
   --telemetry-log     Path to telemetry log (default: ~/.claude/session_telemetry_log.jsonl)
   --output            Output path for grading JSON (default: ~/.selftune/grading/result-<session>.json)
-  --agent             Agent CLI to use (${AGENT_CANDIDATES.join(", ")})
+  --agent             Agent CLI to use (${LLM_BACKED_AGENT_CANDIDATES.join(", ")})
   --show-transcript   Print transcript excerpt before grading
   -h, --help          Show this help message`);
     process.exit(0);
@@ -769,9 +763,9 @@ Options:
 
   // --- Determine agent ---
   let agent: string | null = null;
-  const validAgents = [...AGENT_CANDIDATES];
+  const validAgents = [...LLM_BACKED_AGENT_CANDIDATES];
   if (values.agent) {
-    if (!validAgents.includes(values.agent)) {
+    if (!isLlmBackedAgent(values.agent)) {
       throw new CLIError(
         `Invalid --agent '${values.agent}'. Expected one of: ${validAgents.join(", ")}`,
         "INVALID_FLAG",
@@ -785,9 +779,9 @@ Options:
 
   if (!agent) {
     throw new CLIError(
-      `No supported agent CLI (${AGENT_CANDIDATES.join("/")}) found in PATH`,
+      `No supported agent CLI (${LLM_BACKED_AGENT_CANDIDATES.join("/")}) found in PATH`,
       "AGENT_NOT_FOUND",
-      "Install claude, codex, or opencode CLI, then retry",
+      "Install Claude Code, Codex, OpenCode, or Pi, then retry",
     );
   }
 

package/cli/selftune/index.ts

@@ -21,7 +21,7 @@
  *   selftune contribute         — Export anonymized skill data for community
  *   selftune contributions      — Manage creator-directed sharing preferences
  *   selftune creator-contributions — Manage creator-side contribution configs
- *   selftune workflows          — Discover and manage multi-skill workflows
+ *   selftune workflows          — Discover workflows and scaffold workflow skills
  *   selftune quickstart         — Guided onboarding: init, ingest, status, and suggestions
  *   selftune repair-skill-usage — Rebuild trustworthy skill usage from transcripts
  *   selftune export             — Export SQLite data to JSONL snapshots
@@ -38,6 +38,7 @@
  */
 
 import { CLIError, handleCLIError } from "./utils/cli-error.js";
+import { PUBLIC_COMMAND_SURFACES, renderCommandHelp } from "./command-surface.js";
 
 process.on("uncaughtException", handleCLIError);
 process.on("unhandledRejection", handleCLIError);
@@ -69,7 +70,7 @@ Commands:
   contribute         Export anonymized skill data for community
   contributions      Manage creator-directed sharing preferences
   creator-contributions Manage creator-side contribution configs
-  workflows          Discover and manage multi-skill workflows
+  workflows          Discover workflows and scaffold workflow skills
   quickstart         Guided onboarding: init, ingest, status, and suggestions
   repair-skill-usage Rebuild trustworthy skill usage from transcripts
   export             Export SQLite data to JSONL snapshots
@@ -227,12 +228,12 @@ Run 'selftune grade <subcommand> --help' for subcommand-specific options.`);
   case "evolve": {
     const sub = process.argv[2];
     if (sub === "--help" || sub === "-h") {
-      console.log(`selftune evolve — Evolve skill descriptions
+      console.log(`${renderCommandHelp(PUBLIC_COMMAND_SURFACES.evolve)}
 
-Usage:
-  selftune evolve [options]            Run description evolution
-  selftune evolve body [options]       Evolve full body or routing table
-  selftune evolve rollback [options]   Rollback a previous evolution
+Subcommands:
+  selftune evolve body [options]              Evolve full body or routing table
+  selftune evolve rollback [options]          Rollback a previous evolution
+  selftune evolve apply-proposal [options]    Apply an approved contributor proposal
 
 Run 'selftune evolve <subcommand> --help' for subcommand-specific options.`);
       process.exit(0);
@@ -255,6 +256,11 @@ Run 'selftune evolve <subcommand> --help' for subcommand-specific options.`);
           await cliMain();
           break;
         }
+        case "apply-proposal": {
+          const { cliMain } = await import("./evolution/apply-proposal.js");
+          await cliMain();
+          break;
+        }
         default:
           throw new CLIError(
             `Unknown evolve target: ${sub}`,
@@ -281,6 +287,12 @@ Actions:
   composability  Analyze skill co-occurrence conflicts
   family-overlap Detect sibling-skill overlap and consolidation pressure
 
+Recommended creator loop:
+  1. selftune eval generate --skill <name>
+  2. selftune eval unit-test --skill <name> --generate --skill-path <path>
+  3. selftune evolve --skill <name> --skill-path <path> --dry-run --validation-mode replay
+  4. selftune grade baseline --skill <name> --skill-path <path>
+
 Run 'selftune eval <action> --help' for action-specific options.`);
       process.exit(0);
     }
@@ -337,7 +349,8 @@ Run 'selftune eval <action> --help' for action-specific options.`);
             "selftune eval composability --skill <name>",
           );
         }
-        const logPath = values["telemetry-log"] ?? TELEMETRY_LOG;
+        const logPath =
+          typeof values["telemetry-log"] === "string" ? values["telemetry-log"] : TELEMETRY_LOG;
         let telemetry: unknown[];
         if (logPath === TELEMETRY_LOG) {
           try {
@@ -363,7 +376,19 @@ Run 'selftune eval <action> --help' for action-specific options.`);
           );
         }
         const windowSize = rawWindow === undefined ? undefined : Number(rawWindow);
-        const report = analyzeComposability(values.skill, telemetry, windowSize);
+        const skillName = typeof values.skill === "string" ? values.skill : undefined;
+        if (!skillName) {
+          throw new CLIError(
+            "--skill <name> is required.",
+            "MISSING_FLAG",
+            "selftune eval composability --skill <name>",
+          );
+        }
+        const report = analyzeComposability(
+          skillName,
+          telemetry as import("./types.js").SessionTelemetryRecord[],
+          windowSize,
+        );
         console.log(JSON.stringify(report, null, 2));
         break;
       }
@@ -720,7 +745,7 @@ Output:
           userId: identity.user_id,
           agentType: readConfiguredAgentType(SELFTUNE_CONFIG_PATH, "unknown"),
           selftuneVersion: getSelftuneVersion(),
-          dryRun: values["dry-run"] ?? false,
+          dryRun: values["dry-run"] === true,
           apiKey: identity.api_key,
         });