selftune 0.2.22 → 0.2.24

package/cli/selftune/types.ts

@@ -12,6 +12,8 @@ export interface AlphaIdentity {
   cloud_user_id?: string;
   /** Cloud-issued org ID. Set during device-code approval. */
   cloud_org_id?: string;
+  /** Optional override for cloud API base URL. */
+  cloud_api_url?: string;
   /** Cached email from cloud account. Not authoritative. */
   email?: string;
   /** Cached display name from cloud account. Not authoritative. */
@@ -34,7 +36,7 @@ export type AlphaLinkState =
   | "ready";
 
 export interface SelftuneConfig {
-  agent_type: "claude_code" | "codex" | "opencode" | "openclaw" | "unknown";
+  agent_type: "claude_code" | "codex" | "opencode" | "openclaw" | "pi" | "unknown";
   cli_path: string;
   llm_mode: "agent";
   agent_cli: string | null;
@@ -134,6 +136,7 @@ export type {
   CanonicalRecordKind,
   CanonicalSchemaVersion,
   CanonicalSessionRecord,
+  CanonicalSessionRecordBase,
   CanonicalSkillInvocationRecord,
   CanonicalSourceSessionKind,
 } from "@selftune/telemetry-contract/types";
@@ -167,7 +170,7 @@ export interface TranscriptMetrics {
   total_tool_calls: number;
   bash_commands: string[];
   skills_triggered: string[];
-  skills_invoked: string[];
+  skills_invoked?: string[];
   assistant_turns: number;
   errors_encountered: number;
   transcript_chars: number;
@@ -247,6 +250,40 @@ export interface EvalEntry {
   query: string;
   should_trigger: boolean;
   invocation_type?: InvocationType;
+  /** Provenance: where this eval entry originated */
+  source?: "synthetic" | "log" | "blended";
+  /** ISO timestamp when this eval entry was created */
+  created_at?: string;
+}
+
+/** Experimental execution eval entry — extends trigger evals with assertion-based validation. */
+export interface ExecutionEvalEntry extends EvalEntry {
+  /** Assertions to verify against the execution result */
+  assertions: ExecutionAssertion[];
+  /** Whether this entry requires a staged workspace */
+  requires_workspace?: boolean;
+  /** Experimental flag — must be explicitly opted into */
+  experimental: true;
+}
+
+export interface ExecutionAssertion {
+  /** What to check: file existence, content match, command output, etc. */
+  type: "file_exists" | "file_contains" | "command_output" | "skill_triggered" | "custom";
+  /** Target path, command, or skill name depending on type */
+  target: string;
+  /** Expected value or pattern (regex for content/output checks) */
+  expected?: string;
+  /** Whether the assertion is negated (must NOT match) */
+  negated?: boolean;
+}
+
+export interface EvalSourceStats {
+  total: number;
+  synthetic: number;
+  log: number;
+  blended: number;
+  oldest?: string;
+  newest?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -414,12 +451,14 @@ export interface EvolutionEvidenceValidation {
   regressions?: EvalEntry[] | string[];
   new_passes?: EvalEntry[];
   per_entry_results?: Array<{ entry: EvalEntry; before_pass: boolean; after_pass: boolean }>;
+  before_entry_results?: Array<{ entry: EvalEntry; before_pass: boolean; after_pass: boolean }>;
   gates_passed?: number;
   gates_total?: number;
   gate_results?: Array<{ gate: ValidationGate; passed: boolean; reason: string }>;
   validation_mode?: ValidationMode;
   validation_agent?: string;
   validation_fixture_id?: string;
+  validation_fallback_reason?: string;
   validation_evidence_ref?: string;
 }
 
@@ -429,7 +468,7 @@ export interface EvolutionEvidenceEntry {
   skill_name: string;
   skill_path: string;
   target: EvolutionTarget;
-  stage: "created" | "validated" | "deployed" | "rejected" | "rolled_back";
+  stage: "proposed" | "created" | "validated" | "deployed" | "rejected" | "rolled_back";
   rationale?: string;
   confidence?: number;
   details?: string;
@@ -677,7 +716,7 @@ export interface ContributionBundle {
 // ---------------------------------------------------------------------------
 
 /** Which part of a skill is being evolved. */
-export type EvolutionTarget = "description" | "routing" | "body";
+export type EvolutionTarget = "description" | "routing" | "body" | "new_skill";
 
 /** Parsed sections of a SKILL.md file. */
 export interface SkillSections {
@@ -709,7 +748,7 @@ export type ValidationMode = "structural_guard" | "host_replay" | "llm_judge";
 
 export interface RoutingReplayFixture {
   fixture_id: string;
-  platform: "claude_code" | "codex";
+  platform: "claude_code" | "codex" | "opencode";
   target_skill_name: string;
   target_skill_path: string;
   competing_skill_paths: string[];
@@ -735,9 +774,11 @@ export interface BodyValidationResult {
   validation_mode?: ValidationMode;
   validation_agent?: string;
   validation_fixture_id?: string;
+  validation_fallback_reason?: string;
   before_pass_rate?: number;
   after_pass_rate?: number;
   per_entry_results?: RoutingReplayEntryResult[];
+  before_entry_results?: RoutingReplayEntryResult[];
 }
 
 /** Configuration for which LLM model a role should use. */

package/cli/selftune/uninstall.ts

@@ -121,7 +121,8 @@ function isSelfttuneHookEntry(entry: unknown): boolean {
 
   // Check direct command
   if (typeof obj.command === "string") {
-    return SELFTUNE_HOOK_SCRIPTS.some((script) => obj.command?.includes(script));
+    const command = obj.command;
+    return SELFTUNE_HOOK_SCRIPTS.some((script) => command.includes(script));
   }
 
   // Check hooks array (the nested structure used in settings.json)

package/cli/selftune/utils/canonical-log.ts

@@ -1,4 +1,4 @@
-import { existsSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 
 import {
   type CanonicalPlatform,
@@ -37,11 +37,3 @@ export function serializeCanonicalRecords(records: CanonicalRecord[], pretty = f
     records.map((record) => JSON.stringify(record)).join("\n") + (records.length > 0 ? "\n" : "")
   );
 }
-
-export function writeCanonicalExport(
-  records: CanonicalRecord[],
-  outPath: string,
-  pretty = false,
-): void {
-  writeFileSync(outPath, serializeCanonicalRecords(records, pretty), "utf-8");
-}

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

@@ -21,11 +21,20 @@ export type CLIErrorCode =
   | "MISSING_FLAG"
   | "CONFIG_MISSING"
   | "FILE_NOT_FOUND"
+  | "FILE_EXISTS"
   | "AGENT_NOT_FOUND"
   | "UNKNOWN_COMMAND"
   | "GUARD_BLOCKED"
   | "OPERATION_FAILED"
+  | "API_ERROR"
+  | "AUTH_MISSING"
+  | "BLEND_NO_LOGS"
+  | "INVALID_PROPOSAL"
+  | "INVALID_STATUS"
   | "MISSING_DATA"
+  | "NOT_FOUND"
+  | "REPLAY_UNAVAILABLE"
+  | "UNSUPPORTED_TYPE"
   | "INTERNAL_ERROR";
 
 export class CLIError extends Error {

package/cli/selftune/utils/jsonl.ts

@@ -1,9 +1,8 @@
 /**
- * JSONL read/write/append utilities.
+ * JSONL read utilities and marker file helpers.
  */
 
 import {
-  appendFileSync,
   closeSync,
   existsSync,
   fstatSync,
@@ -15,10 +14,6 @@ import {
 } from "node:fs";
 import { dirname } from "node:path";
 
-import { createLogger } from "./logging.js";
-import type { LogType } from "./schema-validator.js";
-import { validateRecord } from "./schema-validator.js";
-
 /**
  * Read a JSONL file and return parsed records.
  * Skips blank lines and lines that fail to parse.
@@ -86,30 +81,6 @@ export function readJsonlFrom<T = Record<string, unknown>>(
   }
 }
 
-/**
- * Append a single record to a JSONL file. Creates parent directories if needed.
- * When logType is provided, validates the record and logs warnings on failure
- * but still writes the record (fail-open: hooks must never block).
- *
- * @deprecated Phase 3: JSONL writes removed. Retained for materializer/test utilities only.
- */
-export function appendJsonl(path: string, record: unknown, logType?: LogType): void {
-  if (logType) {
-    const result = validateRecord(record, logType);
-    if (!result.valid) {
-      const logger = createLogger("jsonl");
-      for (const error of result.errors) {
-        logger.warn(`Validation warning for ${logType}: ${error}`);
-      }
-    }
-  }
-  const dir = dirname(path);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  appendFileSync(path, `${JSON.stringify(record)}\n`, "utf-8");
-}
-
 /**
  * Load a marker file (JSON array of strings) for idempotent ingestion.
  */

package/cli/selftune/utils/llm-call.ts

@@ -2,7 +2,7 @@
  * Shared LLM call utility.
  *
  * Provides a unified interface for calling LLMs via agent subprocess
- * (claude/codex/opencode). Extracted from grade-session.ts so other
+ * (claude/codex/opencode/pi). Extracted from grade-session.ts so other
  * modules can reuse the same calling logic.
  */
 
@@ -14,6 +14,8 @@ import { AGENT_CANDIDATES } from "../constants.js";
 import { createLogger } from "./logging.js";
 
 const logger = createLogger("llm-call");
+export const LLM_BACKED_AGENT_CANDIDATES = ["claude", "codex", "opencode", "pi"] as const;
+export type LlmBackedAgent = (typeof LLM_BACKED_AGENT_CANDIDATES)[number];
 
 // ---------------------------------------------------------------------------
 // Model alias resolution
@@ -48,6 +50,17 @@ function resolveOpenCodeModel(flag: string): string {
   return OPENCODE_MODEL_MAP[flag] ?? flag;
 }
 
+const PI_THINKING_MAP: Record<EffortLevel, string> = {
+  low: "low",
+  medium: "medium",
+  high: "high",
+  max: "xhigh",
+};
+
+function resolvePiThinking(effort: EffortLevel): string {
+  return PI_THINKING_MAP[effort];
+}
+
 // ---------------------------------------------------------------------------
 // Bundled agent file loading (for codex inline prompt injection)
 // ---------------------------------------------------------------------------
@@ -79,6 +92,33 @@ export function detectAgent(): string | null {
   return null;
 }
 
+/** Detect first available agent CLI that can execute selftune LLM-backed workflows. */
+export function detectLlmAgent(): LlmBackedAgent | null {
+  for (const agent of LLM_BACKED_AGENT_CANDIDATES) {
+    if (Bun.which(agent)) return agent;
+  }
+  return null;
+}
+
+export function isLlmBackedAgent(value: string): value is LlmBackedAgent {
+  return (LLM_BACKED_AGENT_CANDIDATES as readonly string[]).includes(value);
+}
+
+function unsupportedAgentError(agent: string, capability: "llm calls" | "subagent calls"): Error {
+  const supported = LLM_BACKED_AGENT_CANDIDATES.join(", ");
+  if (agent === "openclaw") {
+    return new Error(
+      `Detected agent CLI '${agent}', but selftune ${capability} currently support only ${supported}. ` +
+        `LLM-backed judge, eval, and optimizer workflows are unavailable on ${agent}; ` +
+        `use Claude Code, Codex, OpenCode, or Pi for those workflows, or stay on ingest/sync support for ${agent}.`,
+    );
+  }
+
+  return new Error(
+    `Unknown agent '${agent}'. selftune ${capability} currently support only ${supported}.`,
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Markdown fence stripping
 // ---------------------------------------------------------------------------
@@ -160,7 +200,7 @@ function sleep(ms: number): Promise<void> {
 /** Effort level for Claude CLI (controls thinking depth). Opus 4.6 only for 'max'. */
 export type EffortLevel = "low" | "medium" | "high" | "max";
 
-/** Call LLM via agent subprocess (claude/codex/opencode). Returns raw text. */
+/** Call LLM via agent subprocess (claude/codex/opencode/pi). Returns raw text. */
 export async function callViaAgent(
   systemPrompt: string,
   userPrompt: string,
@@ -194,8 +234,30 @@ export async function callViaAgent(
         cmd.push("--model", resolveOpenCodeModel(modelFlag));
       }
       cmd.push(promptContent);
+    } else if (agent === "pi") {
+      cmd = [
+        "pi",
+        "-p",
+        "--mode",
+        "text",
+        "--no-session",
+        "--no-tools",
+        "--no-extensions",
+        "--no-skills",
+        "--no-prompt-templates",
+        "--no-themes",
+        "--system-prompt",
+        systemPrompt,
+      ];
+      if (modelFlag) {
+        cmd.push("--model", modelFlag);
+      }
+      if (effort) {
+        cmd.push("--thinking", resolvePiThinking(effort));
+      }
+      cmd.push(userPrompt);
     } else {
-      throw new Error(`Unknown agent: ${agent}`);
+      throw unsupportedAgentError(agent, "llm calls");
     }
 
     // Retry loop with exponential backoff for transient failures
@@ -256,6 +318,23 @@ export async function callViaAgent(
   }
 }
 
+function mapAllowedToolsToPi(tools?: string[]): string[] {
+  if (!tools || tools.length === 0) return [];
+
+  const mapped = new Set<string>();
+  for (const tool of tools) {
+    if (tool === "Read") mapped.add("read");
+    else if (tool === "Write") mapped.add("write");
+    else if (tool === "Edit") mapped.add("edit");
+    else if (tool === "Bash") mapped.add("bash");
+    else if (tool === "Grep") mapped.add("grep");
+    else if (tool === "Glob" || tool === "Find") mapped.add("find");
+    else if (tool === "LS" || tool === "Ls") mapped.add("ls");
+  }
+
+  return [...mapped];
+}
+
 // ---------------------------------------------------------------------------
 // Call LLM via named subagent (multi-turn, agentic)
 // ---------------------------------------------------------------------------
@@ -301,10 +380,10 @@ export async function callViaSubagent(options: SubagentCallOptions): Promise<str
     allowedTools,
   } = options;
 
-  const agent = detectAgent();
-  if (!agent || (agent !== "claude" && agent !== "opencode" && agent !== "codex")) {
+  const agent = detectLlmAgent();
+  if (!agent) {
     throw new Error(
-      `Subagent calls require 'claude', 'opencode', or 'codex' CLI in PATH (detected: ${agent ?? "none"})`,
+      "Subagent calls require one of these CLIs in PATH: claude, codex, opencode, pi.",
     );
   }
 
@@ -333,6 +412,47 @@ export async function callViaSubagent(options: SubagentCallOptions): Promise<str
     const agentInstructions = loadAgentInstructions(agentName);
     const fullPrompt = agentInstructions ? `${agentInstructions}\n\n---\n\n${prompt}` : prompt;
     cmd = ["codex", "exec", "--skip-git-repo-check", fullPrompt];
+  } else if (agent === "pi") {
+    if (maxTurns !== 8) {
+      logger.warn(`Subagent '${agentName}' on pi: maxTurns is not supported and will be ignored`);
+    }
+    const agentInstructions = loadAgentInstructions(agentName);
+    const systemParts = [agentInstructions, appendSystemPrompt].filter((value): value is string =>
+      Boolean(value?.trim()),
+    );
+
+    cmd = [
+      "pi",
+      "-p",
+      "--mode",
+      "text",
+      "--no-session",
+      "--no-extensions",
+      "--no-skills",
+      "--no-prompt-templates",
+      "--no-themes",
+    ];
+
+    if (systemParts.length > 0) {
+      cmd.push("--system-prompt", systemParts.join("\n\n"));
+    }
+    if (modelFlag) {
+      cmd.push("--model", modelFlag);
+    }
+    if (effort) {
+      cmd.push("--thinking", resolvePiThinking(effort));
+    }
+
+    const piTools = mapAllowedToolsToPi(allowedTools);
+    if (allowedTools && allowedTools.length > 0) {
+      if (piTools.length > 0) {
+        cmd.push("--tools", piTools.join(","));
+      } else {
+        cmd.push("--no-tools");
+      }
+    }
+
+    cmd.push(prompt);
   } else {
     // Claude Code
     cmd = ["claude", "-p", prompt, "--agent", agentName, "--max-turns", String(maxTurns)];

package/cli/selftune/utils/skill-discovery.ts

@@ -263,6 +263,28 @@ export function classifySkillPath(
   return { skill_scope: "unknown" };
 }
 
+const TEST_PATH_SEGMENTS = [
+  "/tests/",
+  "/__tests__/",
+  "/test/",
+  "/fixtures/",
+  "/sandbox/",
+  "/test-data/",
+  "/testdata/",
+  "/mock/",
+  "/mocks/",
+];
+
+/**
+ * Check if a skill path is inside a test/fixture directory.
+ * Used to prevent test fixture skills from leaking into production data.
+ */
+export function isTestFixturePath(skillPath: string): boolean {
+  if (!skillPath) return false;
+  const normalized = skillPath.toLowerCase();
+  return TEST_PATH_SEGMENTS.some((seg) => normalized.includes(seg));
+}
+
 export function extractSkillNamesFromInstructions(
   text: string,
   knownSkillNames?: Iterable<string>,
@@ -319,6 +341,8 @@ export function extractSkillNamesFromPathReferences(
   const patterns = [
     /(?:^|[\s"'`])(?:[^"'`\s]*?\.agents\/skills\/)([^/\s"'`]+)(?=\/)/gi,
     /(?:^|[\s"'`])(?:[^"'`\s]*?\.codex\/skills\/(?:\.system\/)?)([^/\s"'`]+)(?=\/)/gi,
+    /(?:^|[\s"'`])(?:[^"'`\s]*?\.opencode\/skills\/)([^/\s"'`]+)(?=\/)/gi,
+    /(?:^|[\s"'`])(?:[^"'`\s]*?\.claude\/skills\/)([^/\s"'`]+)(?=\/)/gi,
     /(?:^|[\s"'`])(\/etc\/codex\/skills\/)([^/\s"'`]+)(?=\/)/gi,
   ];
 

package/cli/selftune/workflows/proposals.ts

@@ -0,0 +1,184 @@
+/**
+ * proposals.ts
+ *
+ * Turns strong multi-skill workflow patterns into review-first new-skill
+ * proposals that can be surfaced locally and synced to the cloud.
+ */
+
+import { createHash } from "node:crypto";
+
+import { appendAuditEntry } from "../evolution/audit.js";
+import { appendEvidenceEntry } from "../evolution/evidence.js";
+import type {
+  DiscoveredWorkflow,
+  EvolutionAuditEntry,
+  EvolutionEvidenceEntry,
+  SessionTelemetryRecord,
+  SkillUsageRecord,
+} from "../types.js";
+import { discoverWorkflows } from "./discover.js";
+import { buildWorkflowSkillDraft, type WorkflowSkillDraft } from "./skill-scaffold.js";
+
+export interface WorkflowSkillProposal {
+  proposal_id: string;
+  source_skill_name: string;
+  workflow: DiscoveredWorkflow;
+  draft: WorkflowSkillDraft;
+  summary: string;
+  current_value: string;
+  proposed_value: string;
+  rationale: string;
+  confidence: number;
+}
+
+export interface WorkflowSkillProposalOptions {
+  cwd?: string;
+  skillFilter?: string;
+  maxProposals?: number;
+  minOccurrences?: number;
+  minSynergy?: number;
+  minConsistency?: number;
+  minCompletionRate?: number;
+  resolveSkillPath?: (skillName: string) => string | undefined;
+  existingAuditEntries?: EvolutionAuditEntry[];
+}
+
+export interface WorkflowSkillProposalPersistOptions {
+  now?: Date;
+  sourceSkillPath?: string;
+  appendAudit?: (entry: EvolutionAuditEntry) => void;
+  appendEvidence?: (entry: EvolutionEvidenceEntry) => void;
+}
+
+export const DEFAULT_WORKFLOW_PROPOSAL_MIN_OCCURRENCES = 3;
+export const DEFAULT_WORKFLOW_PROPOSAL_MAX = 2;
+export const DEFAULT_WORKFLOW_PROPOSAL_MIN_SYNERGY = 0;
+export const DEFAULT_WORKFLOW_PROPOSAL_MIN_CONSISTENCY = 0.75;
+export const DEFAULT_WORKFLOW_PROPOSAL_MIN_COMPLETION = 0.65;
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+function buildWorkflowProposalConfidence(workflow: DiscoveredWorkflow): number {
+  const normalizedSynergy = clamp01((workflow.synergy_score + 1) / 2);
+  const occurrenceBoost = clamp01(workflow.occurrence_count / 6);
+  return round2(
+    normalizedSynergy * 0.4 +
+      workflow.sequence_consistency * 0.3 +
+      workflow.completion_rate * 0.2 +
+      occurrenceBoost * 0.1,
+  );
+}
+
+function buildWorkflowProposalId(sourceSkillName: string, draft: WorkflowSkillDraft): string {
+  const digest = createHash("sha256")
+    .update(`${sourceSkillName}:${draft.skill_name}:${draft.source_workflow.workflow_id}`)
+    .digest("hex")
+    .slice(0, 16);
+  return `wf-${draft.skill_name}-${digest}`;
+}
+
+function buildWorkflowProposalSummary(
+  workflow: DiscoveredWorkflow,
+  draft: WorkflowSkillDraft,
+): string {
+  const chain = workflow.skills.join(" -> ");
+  return `Create new_skill "${draft.skill_name}" from workflow ${chain} (${workflow.occurrence_count} sessions, synergy ${workflow.synergy_score.toFixed(2)}, consistency ${Math.round(workflow.sequence_consistency * 100)}%, completion ${Math.round(workflow.completion_rate * 100)}%).`;
+}
+
+function hasExistingProposal(proposalId: string, auditEntries: EvolutionAuditEntry[]): boolean {
+  return auditEntries.some((entry) => entry.proposal_id === proposalId);
+}
+
+export function discoverWorkflowSkillProposals(
+  telemetry: SessionTelemetryRecord[],
+  usage: SkillUsageRecord[],
+  options: WorkflowSkillProposalOptions = {},
+): WorkflowSkillProposal[] {
+  const minOccurrences = options.minOccurrences ?? DEFAULT_WORKFLOW_PROPOSAL_MIN_OCCURRENCES;
+  const maxProposals = options.maxProposals ?? DEFAULT_WORKFLOW_PROPOSAL_MAX;
+  const minSynergy = options.minSynergy ?? DEFAULT_WORKFLOW_PROPOSAL_MIN_SYNERGY;
+  const minConsistency = options.minConsistency ?? DEFAULT_WORKFLOW_PROPOSAL_MIN_CONSISTENCY;
+  const minCompletionRate = options.minCompletionRate ?? DEFAULT_WORKFLOW_PROPOSAL_MIN_COMPLETION;
+  const report = discoverWorkflows(telemetry, usage, {
+    minOccurrences,
+    skill: options.skillFilter,
+  });
+  const existingAuditEntries = options.existingAuditEntries ?? [];
+  const proposals: WorkflowSkillProposal[] = [];
+
+  for (const workflow of report.workflows) {
+    if (workflow.occurrence_count < minOccurrences) continue;
+    if (workflow.synergy_score < minSynergy) continue;
+    if (workflow.sequence_consistency < minConsistency) continue;
+    if (workflow.completion_rate < minCompletionRate) continue;
+    if (workflow.skills.length < 2) continue;
+
+    const draft = buildWorkflowSkillDraft(workflow, { cwd: options.cwd });
+    if (!draft.skill_name) continue;
+    if (options.resolveSkillPath?.(draft.skill_name)) continue;
+
+    const sourceSkillName = workflow.skills[0];
+    const proposalId = buildWorkflowProposalId(sourceSkillName, draft);
+    if (hasExistingProposal(proposalId, existingAuditEntries)) continue;
+
+    const summary = buildWorkflowProposalSummary(workflow, draft);
+    const currentValue = `No dedicated workflow skill exists for ${workflow.skills.join(" -> ")}.`;
+    const proposedValue = `Create ${draft.skill_name} at ${draft.skill_path}`;
+    const queryClause = workflow.representative_query.trim()
+      ? ` Common trigger: "${workflow.representative_query.trim()}".`
+      : "";
+
+    proposals.push({
+      proposal_id: proposalId,
+      source_skill_name: sourceSkillName,
+      workflow,
+      draft,
+      summary,
+      current_value: currentValue,
+      proposed_value: proposedValue,
+      rationale: `${summary}${queryClause}`,
+      confidence: buildWorkflowProposalConfidence(workflow),
+    });
+
+    if (proposals.length >= maxProposals) break;
+  }
+
+  return proposals;
+}
+
+export function persistWorkflowSkillProposal(
+  proposal: WorkflowSkillProposal,
+  options: WorkflowSkillProposalPersistOptions = {},
+): void {
+  const timestamp = (options.now ?? new Date()).toISOString();
+  const appendAudit = options.appendAudit ?? appendAuditEntry;
+  const appendEvidence = options.appendEvidence ?? appendEvidenceEntry;
+
+  appendAudit({
+    timestamp,
+    proposal_id: proposal.proposal_id,
+    skill_name: proposal.source_skill_name,
+    action: "created",
+    details: proposal.summary,
+  });
+
+  appendEvidence({
+    timestamp,
+    proposal_id: proposal.proposal_id,
+    skill_name: proposal.source_skill_name,
+    skill_path: options.sourceSkillPath ?? "",
+    target: "new_skill",
+    stage: "proposed",
+    rationale: proposal.rationale,
+    confidence: proposal.confidence,
+    details: proposal.proposed_value,
+    original_text: proposal.current_value,
+    proposed_text: proposal.draft.content,
+  });
+}