selftune 0.2.14 → 0.2.16

package/cli/selftune/schedule.ts

@@ -18,6 +18,7 @@ import { dirname, join } from "node:path";
 import { parseArgs } from "node:util";
 
 import { DEFAULT_CRON_JOBS } from "./cron/setup.js";
+import { CLIError, handleCLIError } from "./utils/cli-error.js";
 
 // ---------------------------------------------------------------------------
 // Binary resolution — launchd runs with minimal PATH, so we need full paths
@@ -533,10 +534,11 @@ export function cliMain(): void {
       applyCronArtifact(values["apply-cron-artifact"]);
       return;
     } catch (err) {
-      console.error(
+      throw new CLIError(
         `Failed to apply selftune cron artifact: ${err instanceof Error ? err.message : String(err)}`,
+        "OPERATION_FAILED",
+        "selftune schedule --install --dry-run",
       );
-      process.exit(1);
     }
   }
 
@@ -569,8 +571,11 @@ For OpenClaw-specific scheduling, see: selftune cron`);
         dryRun: values["dry-run"] ?? false,
       });
       if (!result.dryRun && !result.activated) {
-        console.error("Failed to activate installed schedule artifacts.");
-        process.exit(1);
+        throw new CLIError(
+          "Failed to activate installed schedule artifacts.",
+          "OPERATION_FAILED",
+          "selftune schedule --install --dry-run",
+        );
       }
       console.log(
         JSON.stringify(
@@ -587,21 +592,30 @@ For OpenClaw-specific scheduling, see: selftune cron`);
       );
       return;
     } catch (err) {
-      console.error(
+      if (err instanceof CLIError) throw err;
+      throw new CLIError(
         `Failed to install schedule artifacts: ${err instanceof Error ? err.message : String(err)}`,
+        "OPERATION_FAILED",
+        "selftune schedule --install --dry-run",
       );
-      process.exit(1);
     }
   }
 
   const result = formatOutput(values.format);
   if (!result.ok) {
-    console.error(result.error);
-    process.exit(1);
+    throw new CLIError(
+      result.error ?? "Invalid schedule format",
+      "INVALID_FLAG",
+      "selftune schedule --format cron",
+    );
   }
   console.log(result.data);
 }
 
 if (import.meta.main) {
-  cliMain();
+  try {
+    cliMain();
+  } catch (err) {
+    handleCLIError(err);
+  }
 }

package/cli/selftune/sync.ts

@@ -62,6 +62,7 @@ import {
   rebuildSkillUsageFromTranscripts,
 } from "./repair/skill-usage.js";
 import type { SkillUsageRecord } from "./types.js";
+import { CLIError, handleCLIError } from "./utils/cli-error.js";
 import { loadMarker, readJsonl, saveMarker } from "./utils/jsonl.js";
 import { writeRepairedSkillUsageRecords } from "./utils/skill-log.js";
 
@@ -560,8 +561,11 @@ Options:
   if (values.since) {
     since = new Date(values.since);
     if (Number.isNaN(since.getTime())) {
-      console.error(`[ERROR] Invalid --since date: ${values.since}`);
-      process.exit(1);
+      throw new CLIError(
+        `Invalid --since date: ${values.since}`,
+        "INVALID_FLAG",
+        "selftune sync --since 2026-01-01",
+      );
     }
   }
 
@@ -665,5 +669,5 @@ Options:
 }
 
 if (import.meta.main) {
-  cliMain();
+  cliMain().catch(handleCLIError);
 }

package/cli/selftune/types.ts

@@ -166,26 +166,46 @@ export interface TranscriptMetrics {
 // Hook payloads (received via stdin from Claude Code)
 // ---------------------------------------------------------------------------
 
+/**
+ * Common fields present on ALL hook event payloads per Claude Code docs.
+ * Individual payloads extend this with event-specific fields.
+ */
+export interface CommonHookPayload {
+  session_id?: string;
+  transcript_path?: string;
+  cwd?: string;
+  permission_mode?: string;
+  hook_event_name?: string;
+  /** Present when hook fires inside a subagent. */
+  agent_id?: string;
+  /** Agent name (e.g. "Explore", "Plan", or custom agent name). */
+  agent_type?: string;
+}
+
 // Shared base for pre/post tool-use hook payloads
-export interface BaseToolUsePayload {
+export interface BaseToolUsePayload extends CommonHookPayload {
   tool_name: string;
   tool_input: Record<string, unknown>;
-  session_id?: string;
+  tool_use_id?: string;
 }
 
-export interface PromptSubmitPayload {
-  user_prompt: string;
-  session_id?: string;
+export interface PromptSubmitPayload extends CommonHookPayload {
+  /** Current field name per Claude Code docs (2025+). */
+  prompt?: string;
+  /** Legacy field name — kept for backwards compatibility. */
+  user_prompt?: string;
 }
 
 export interface PostToolUsePayload extends BaseToolUsePayload {
-  transcript_path?: string;
+  /** Tool execution result, schema depends on the tool. */
+  tool_response?: Record<string, unknown>;
 }
 
-export interface StopPayload {
-  session_id?: string;
-  transcript_path?: string;
-  cwd?: string;
+export interface StopPayload extends CommonHookPayload {
+  /** True when Claude Code is continuing as a result of a stop hook. */
+  stop_hook_active?: boolean;
+  /** Text content of Claude's final response. */
+  last_assistant_message?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -394,6 +414,18 @@ export interface EvolutionConfig {
 // Validation result base (self-contained for Pareto types)
 // ---------------------------------------------------------------------------
 
+/** Heuristic quality score for a skill description (no LLM, pure function). */
+export interface DescriptionQualityScore {
+  composite: number; // 0.0-1.0 weighted aggregate
+  criteria: {
+    length: number; // description length in optimal range
+    trigger_context: number; // includes when/if/before/after context
+    vagueness: number; // absence of vague words
+    specificity: number; // concrete action verbs present
+    not_just_name: number; // not just restating the skill name
+  };
+}
+
 /** Compact summary of an evolve run, used for CLI JSON output. */
 export interface EvolveResultSummary {
   skill: string;
@@ -412,6 +444,9 @@ export interface EvolveResultSummary {
   rationale: string;
   version?: string;
   dashboard_url: string;
+  description_quality_before?: number;
+  description_quality_after?: number;
+  suggestions?: string[];
 }
 
 export interface ValidationResultBase {

package/cli/selftune/utils/cli-error.ts

@@ -0,0 +1,102 @@
+/**
+ * Typed CLI error with machine-readable code, agent-actionable suggestion, and exit code.
+ *
+ * Replaces ad-hoc `console.error() + process.exit(1)` patterns across the CLI.
+ * When `--json` mode is active, errors serialize to structured JSON on stderr.
+ * When text mode is active, errors print human-readable messages with suggestions.
+ *
+ * @example
+ * ```ts
+ * throw new CLIError(
+ *   "No selftune config found",
+ *   "CONFIG_MISSING",
+ *   "Run: selftune init",
+ *   4,  // exit code for config-missing per agent-cli-contract
+ * );
+ * ```
+ */
+
+export type CLIErrorCode =
+  | "INVALID_FLAG"
+  | "MISSING_FLAG"
+  | "CONFIG_MISSING"
+  | "FILE_NOT_FOUND"
+  | "AGENT_NOT_FOUND"
+  | "UNKNOWN_COMMAND"
+  | "GUARD_BLOCKED"
+  | "OPERATION_FAILED"
+  | "MISSING_DATA"
+  | "INTERNAL_ERROR";
+
+export class CLIError extends Error {
+  constructor(
+    message: string,
+    /** Machine-readable error code (SCREAMING_SNAKE_CASE). */
+    public readonly code: CLIErrorCode,
+    /** Agent-actionable next command or remediation step. */
+    public readonly suggestion?: string,
+    /** Process exit code. Default 1 (general error). */
+    public readonly exitCode: number = 1,
+    /** Whether the agent should retry the same command. */
+    public readonly retryable: boolean = false,
+  ) {
+    super(message);
+    this.name = "CLIError";
+  }
+
+  /** Structured JSON representation for `--json` mode. */
+  toJSON(): {
+    error: {
+      code: CLIErrorCode;
+      message: string;
+      suggestion?: string;
+      retryable: boolean;
+    };
+  } {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.suggestion ? { suggestion: this.suggestion } : {}),
+        retryable: this.retryable,
+      },
+    };
+  }
+}
+
+/**
+ * Top-level error handler for CLI entry points.
+ *
+ * Install at the bottom of any CLI entry point:
+ * ```ts
+ * cliMain().catch(handleCLIError);
+ * ```
+ */
+/** Detect JSON output mode: explicit --json flag or non-TTY stdout (automation). */
+export function isJsonOutputMode(): boolean {
+  return process.argv.includes("--json") || process.stdout?.isTTY === false;
+}
+
+export function handleCLIError(error: unknown): never {
+  const jsonMode = isJsonOutputMode();
+
+  if (error instanceof CLIError) {
+    if (jsonMode) {
+      console.error(JSON.stringify(error.toJSON()));
+      process.exit(error.exitCode);
+    }
+    console.error(`[ERROR] ${error.message}`);
+    if (error.suggestion) {
+      console.error(`  → ${error.suggestion}`);
+    }
+    process.exit(error.exitCode);
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  if (jsonMode) {
+    console.error(JSON.stringify({ error: { code: "INTERNAL_ERROR", message, retryable: false } }));
+    process.exit(1);
+  }
+  console.error(`[FATAL] ${message}`);
+  process.exit(1);
+}

package/cli/selftune/utils/hooks.ts

@@ -13,14 +13,24 @@ function isHookEntry(value: unknown): value is ClaudeCodeHookEntry {
   return typeof value === "object" && value !== null;
 }
 
+/** Check if a command string references a selftune-managed hook. */
+export function isSelftuneCommand(command: string): boolean {
+  const normalized = command.replace(/\\/g, "/");
+  return (
+    normalized.includes("/cli/selftune/hooks/") ||
+    normalized.includes("/bin/run-hook.cjs") ||
+    normalized.startsWith("npx selftune hook ")
+  );
+}
+
 export function entryReferencesSelftune(entry: ClaudeCodeHookEntry): boolean {
-  if (typeof entry.command === "string" && entry.command.includes("selftune")) {
+  if (typeof entry.command === "string" && isSelftuneCommand(entry.command)) {
     return true;
   }
 
   if (Array.isArray(entry.hooks)) {
     return entry.hooks.some(
-      (hook) => typeof hook.command === "string" && hook.command.includes("selftune"),
+      (hook) => typeof hook.command === "string" && isSelftuneCommand(hook.command),
     );
   }
 

package/cli/selftune/workflows/workflows.ts

@@ -19,6 +19,7 @@ import type {
   SkillUsageRecord,
   WorkflowDiscoveryReport,
 } from "../types.js";
+import { CLIError } from "../utils/cli-error.js";
 import { discoverWorkflows } from "./discover.js";
 import { appendWorkflow } from "./skill-md-writer.js";
 
@@ -79,13 +80,11 @@ export async function cliMain(): Promise<void> {
     ? Number.parseInt(values["min-occurrences"], 10)
     : undefined;
   if (minOccurrences !== undefined && (Number.isNaN(minOccurrences) || minOccurrences < 0)) {
-    console.error("[ERROR] --min-occurrences must be a non-negative integer.");
-    process.exit(1);
+    throw new CLIError("--min-occurrences must be a non-negative integer.", "INVALID_FLAG");
   }
   const window = values.window ? Number.parseInt(values.window, 10) : undefined;
   if (window !== undefined && (Number.isNaN(window) || window < 0)) {
-    console.error("[ERROR] --window must be a non-negative integer.");
-    process.exit(1);
+    throw new CLIError("--window must be a non-negative integer.", "INVALID_FLAG");
   }
 
   // Read telemetry and skill usage logs from SQLite
@@ -104,8 +103,11 @@ export async function cliMain(): Promise<void> {
     // Save subcommand: find workflow, append to SKILL.md
     const nameArg = positionals[1];
     if (!nameArg) {
-      console.error("[ERROR] Usage: selftune workflows save <name-or-index>");
-      process.exit(1);
+      throw new CLIError(
+        "Usage: selftune workflows save <name-or-index>",
+        "MISSING_FLAG",
+        "Provide a workflow name or index (e.g., selftune workflows save 1).",
+      );
     }
 
     // Match by numeric index (1-based) or workflow_id
@@ -118,9 +120,11 @@ export async function cliMain(): Promise<void> {
     }
 
     if (!workflow) {
-      console.error(`[ERROR] No workflow found matching "${nameArg}".`);
-      console.error("Run 'selftune workflows' to see discovered workflows and their indices.");
-      process.exit(1);
+      throw new CLIError(
+        `No workflow found matching "${nameArg}".`,
+        "INVALID_FLAG",
+        "Run 'selftune workflows' to see discovered workflows and their indices.",
+      );
     }
 
     // Determine SKILL.md path
@@ -140,18 +144,20 @@ export async function cliMain(): Promise<void> {
         skillPath = uniquePaths[0];
       } else if (uniquePaths.length > 1) {
         // Ambiguous: multiple SKILL.md paths found across contributing sessions
-        console.error(`[ERROR] Multiple SKILL.md paths found for "${firstSkill}":`);
-        for (const p of uniquePaths) {
-          console.error(`  - ${p}`);
-        }
-        console.error("Use --skill-path to specify which one to update.");
-        process.exit(1);
+        throw new CLIError(
+          `Multiple SKILL.md paths found for "${firstSkill}": ${uniquePaths.join(", ")}`,
+          "INVALID_FLAG",
+          "Use --skill-path to specify which one to update.",
+        );
       }
     }
 
     if (!skillPath || !existsSync(skillPath)) {
-      console.error(`[ERROR] Could not determine SKILL.md path. Use --skill-path to specify.`);
-      process.exit(1);
+      throw new CLIError(
+        "Could not determine SKILL.md path.",
+        "FILE_NOT_FOUND",
+        "Use --skill-path to specify the SKILL.md file to update.",
+      );
     }
 
     // Build CodifiedWorkflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selftune",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Self-improving skills CLI for AI agents",
   "keywords": [
     "agent",

package/skill/SKILL.md

@@ -12,7 +12,7 @@ description: >
   even if they don't say "selftune" explicitly.
 metadata:
   author: selftune-dev
-  version: 0.2.14
+  version: 0.2.16
   category: developer-tools
 ---
 

package/skill/Workflows/AutoActivation.md

@@ -110,7 +110,7 @@ The hook is registered under `UserPromptSubmit`:
   "hooks": {
     "UserPromptSubmit": [
       {
-        "command": "bun run /path/to/cli/selftune/hooks/auto-activate.ts"
+        "command": "node /path/to/bin/run-hook.cjs /path/to/cli/selftune/hooks/auto-activate.ts"
       }
     ]
   }

package/skill/Workflows/Evolve.md

@@ -278,6 +278,10 @@ After evolution completes (deploy or dry-run), the memory writer updates:
 This ensures the next evolve, watch, or rollback workflow has full context
 even after a context window reset.
 
+### Description Quality Scoring
+
+Proposals are scored on heuristic quality criteria (no LLM required). The composite score (0.0–1.0) uses five weighted criteria: trigger context (0.30), vagueness absence (0.20), specificity (0.20), length (0.15), and not-just-name (0.15). Proposals that regress in quality score are rejected. See `docs/design-docs/evolution-pipeline.md` for full criteria details.
+
 ### Stopping Criteria
 
 The evolution loop stops when any of these conditions is met (priority order):

package/skill/Workflows/Initialize.md

@@ -126,14 +126,14 @@ Code subagent calls stay up to date.
 
 **Hook reference** (for troubleshooting):
 
-| Hook                       | Script                        | Purpose                                         |
-| -------------------------- | ----------------------------- | ----------------------------------------------- |
-| `UserPromptSubmit`         | `hooks/prompt-log.ts`         | Log every user query                            |
-| `UserPromptSubmit`         | `hooks/auto-activate.ts`      | Suggest skills before prompt processing         |
-| `PreToolUse` (Write/Edit)  | `hooks/skill-change-guard.ts` | Detect uncontrolled skill edits                 |
-| `PreToolUse` (Write/Edit)  | `hooks/evolution-guard.ts`    | Block SKILL.md edits on monitored skills        |
-| `PostToolUse` (Read/Skill) | `hooks/skill-eval.ts`         | Track skill triggers and Skill tool invocations |
-| `Stop`                     | `hooks/session-stop.ts`       | Capture session telemetry                       |
+| Hook                       | Script                        | Purpose                                         | Notes                                          |
+| -------------------------- | ----------------------------- | ----------------------------------------------- | ---------------------------------------------- |
+| `UserPromptSubmit`         | `hooks/prompt-log.ts`         | Log every user query                            | Accepts both `prompt` and legacy `user_prompt` |
+| `UserPromptSubmit`         | `hooks/auto-activate.ts`      | Suggest skills before prompt processing         | Uses `additionalContext` JSON for suggestions  |
+| `PreToolUse` (Write/Edit)  | `hooks/skill-change-guard.ts` | Detect uncontrolled skill edits                 | `if` filter: only fires on `*SKILL.md` paths   |
+| `PreToolUse` (Write/Edit)  | `hooks/evolution-guard.ts`    | Block SKILL.md edits on monitored skills        | `if` filter: only fires on `*SKILL.md` paths   |
+| `PostToolUse` (Read/Skill) | `hooks/skill-eval.ts`         | Track skill triggers and Skill tool invocations |                                                |
+| `Stop`                     | `hooks/session-stop.ts`       | Capture session telemetry                       | Runs async (non-blocking), 60s timeout         |
 
 **Codex agents:**
 

package/skill/settings_snippet.json

@@ -9,13 +9,15 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun run /PATH/TO/cli/selftune/hooks/prompt-log.ts",
-            "timeout": 5
+            "command": "node /PATH/TO/bin/run-hook.cjs /PATH/TO/cli/selftune/hooks/prompt-log.ts",
+            "timeout": 5,
+            "statusMessage": "selftune: logging prompt"
           },
           {
             "type": "command",
-            "command": "bun run /PATH/TO/cli/selftune/hooks/auto-activate.ts",
-            "timeout": 5
+            "command": "node /PATH/TO/bin/run-hook.cjs /PATH/TO/cli/selftune/hooks/auto-activate.ts",
+            "timeout": 5,
+            "statusMessage": "selftune: checking activation rules"
           }
         ]
       }
@@ -26,13 +28,31 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun run /PATH/TO/cli/selftune/hooks/skill-change-guard.ts",
-            "timeout": 5
+            "if": "Write(*SKILL.md)",
+            "command": "node /PATH/TO/bin/run-hook.cjs /PATH/TO/cli/selftune/hooks/skill-change-guard.ts",
+            "timeout": 5,
+            "statusMessage": "selftune: checking skill change guard"
           },
           {
             "type": "command",
-            "command": "bun run /PATH/TO/cli/selftune/hooks/evolution-guard.ts",
-            "timeout": 5
+            "if": "Edit(*SKILL.md)",
+            "command": "node /PATH/TO/bin/run-hook.cjs /PATH/TO/cli/selftune/hooks/skill-change-guard.ts",
+            "timeout": 5,
+            "statusMessage": "selftune: checking skill change guard"
+          },
+          {
+            "type": "command",
+            "if": "Write(*SKILL.md)",
+            "command": "node /PATH/TO/bin/run-hook.cjs /PATH/TO/cli/selftune/hooks/evolution-guard.ts",
+            "timeout": 5,
+            "statusMessage": "selftune: checking evolution guard"
+          },
+          {
+            "type": "command",
+            "if": "Edit(*SKILL.md)",
+            "command": "node /PATH/TO/bin/run-hook.cjs /PATH/TO/cli/selftune/hooks/evolution-guard.ts",
+            "timeout": 5,
+            "statusMessage": "selftune: checking evolution guard"
           }
         ]
       }
@@ -43,8 +63,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun run /PATH/TO/cli/selftune/hooks/skill-eval.ts",
-            "timeout": 5
+            "command": "node /PATH/TO/bin/run-hook.cjs /PATH/TO/cli/selftune/hooks/skill-eval.ts",
+            "timeout": 5,
+            "statusMessage": "selftune: evaluating skill usage"
           }
         ]
       }
@@ -54,8 +75,10 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun run /PATH/TO/cli/selftune/hooks/session-stop.ts",
-            "timeout": 15
+            "command": "node /PATH/TO/bin/run-hook.cjs /PATH/TO/cli/selftune/hooks/session-stop.ts",
+            "timeout": 60,
+            "async": true,
+            "statusMessage": "selftune: capturing session telemetry"
           }
         ]
       }