selftune 0.1.4 → 0.2.1

package/cli/selftune/memory/writer.ts

@@ -0,0 +1,447 @@
+/**
+ * Memory writer — pure functions for reading/writing evolution memory files.
+ *
+ * Memory files live at ~/.selftune/memory/ and provide human-readable session
+ * context that survives context resets. Three files:
+ *   - context.md  — active evolutions, known issues
+ *   - plan.md     — current priorities, strategy
+ *   - decisions.md — append-only decision log
+ *
+ * All functions accept an optional memoryDir parameter for testability.
+ * Default: MEMORY_DIR from constants.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { MEMORY_DIR } from "../constants.js";
+import type { EvolveResult } from "../evolution/evolve.js";
+import type { RollbackResult } from "../evolution/rollback.js";
+import type {
+  DecisionRecord,
+  EvolutionProposal,
+  MemoryContext,
+  MemoryPlan,
+  MonitoringSnapshot,
+} from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Directory management
+// ---------------------------------------------------------------------------
+
+export function ensureMemoryDir(memoryDir: string = MEMORY_DIR): void {
+  if (!existsSync(memoryDir)) {
+    mkdirSync(memoryDir, { recursive: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// context.md
+// ---------------------------------------------------------------------------
+
+function formatContext(data: MemoryContext): string {
+  const lines: string[] = ["# Selftune Context", ""];
+
+  lines.push("## Active Evolutions");
+  if (data.activeEvolutions.length === 0) {
+    lines.push("- (none)");
+  } else {
+    for (const evo of data.activeEvolutions) {
+      lines.push(`- ${evo.skillName}: ${evo.status} — ${evo.description}`);
+    }
+  }
+  lines.push("");
+
+  lines.push("## Known Issues");
+  if (data.knownIssues.length === 0) {
+    lines.push("- (none)");
+  } else {
+    for (const issue of data.knownIssues) {
+      lines.push(`- ${issue}`);
+    }
+  }
+  lines.push("");
+
+  lines.push("## Last Updated");
+  lines.push(data.lastUpdated);
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function parseContext(content: string): MemoryContext {
+  const result: MemoryContext = {
+    activeEvolutions: [],
+    knownIssues: [],
+    lastUpdated: "",
+  };
+
+  const lines = content.split("\n");
+  let section = "";
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed === "## Active Evolutions") {
+      section = "evolutions";
+      continue;
+    }
+    if (trimmed === "## Known Issues") {
+      section = "issues";
+      continue;
+    }
+    if (trimmed === "## Last Updated") {
+      section = "updated";
+      continue;
+    }
+    if (trimmed.startsWith("# ")) {
+      section = "";
+      continue;
+    }
+
+    if (section === "evolutions" && trimmed.startsWith("- ") && trimmed !== "- (none)") {
+      // Format: "- skillName: status — description"
+      const body = trimmed.slice(2);
+      const colonIdx = body.indexOf(":");
+      if (colonIdx === -1) continue;
+      const skillName = body.slice(0, colonIdx).trim();
+      const rest = body.slice(colonIdx + 1).trim();
+      const dashIdx = rest.indexOf("—");
+      if (dashIdx === -1) {
+        result.activeEvolutions.push({ skillName, status: rest.trim(), description: "" });
+      } else {
+        const status = rest.slice(0, dashIdx).trim();
+        const description = rest.slice(dashIdx + 1).trim();
+        result.activeEvolutions.push({ skillName, status, description });
+      }
+    }
+
+    if (section === "issues" && trimmed.startsWith("- ") && trimmed !== "- (none)") {
+      result.knownIssues.push(trimmed.slice(2));
+    }
+
+    if (section === "updated" && trimmed.length > 0) {
+      result.lastUpdated = trimmed;
+      section = "";
+    }
+  }
+
+  return result;
+}
+
+export function writeContext(data: MemoryContext, memoryDir: string = MEMORY_DIR): void {
+  ensureMemoryDir(memoryDir);
+  const filePath = join(memoryDir, "context.md");
+  writeFileSync(filePath, formatContext(data), "utf-8");
+}
+
+export function readContext(memoryDir: string = MEMORY_DIR): MemoryContext {
+  const filePath = join(memoryDir, "context.md");
+  if (!existsSync(filePath)) {
+    return { activeEvolutions: [], knownIssues: [], lastUpdated: "" };
+  }
+  const content = readFileSync(filePath, "utf-8");
+  return parseContext(content);
+}
+
+// ---------------------------------------------------------------------------
+// plan.md
+// ---------------------------------------------------------------------------
+
+function formatPlan(data: MemoryPlan): string {
+  const lines: string[] = ["# Evolution Plan", ""];
+
+  lines.push("## Current Priorities");
+  if (data.currentPriorities.length === 0) {
+    lines.push("1. (none)");
+  } else {
+    for (let i = 0; i < data.currentPriorities.length; i++) {
+      lines.push(`${i + 1}. ${data.currentPriorities[i]}`);
+    }
+  }
+  lines.push("");
+
+  lines.push("## Strategy");
+  lines.push(data.strategy || "(no strategy defined)");
+  lines.push("");
+
+  lines.push("## Last Updated");
+  lines.push(data.lastUpdated);
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function parsePlan(content: string): MemoryPlan {
+  const result: MemoryPlan = {
+    currentPriorities: [],
+    strategy: "",
+    lastUpdated: "",
+  };
+
+  const lines = content.split("\n");
+  let section = "";
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed === "## Current Priorities") {
+      section = "priorities";
+      continue;
+    }
+    if (trimmed === "## Strategy") {
+      section = "strategy";
+      continue;
+    }
+    if (trimmed === "## Last Updated") {
+      section = "updated";
+      continue;
+    }
+    if (trimmed.startsWith("# ")) {
+      section = "";
+      continue;
+    }
+
+    if (section === "priorities") {
+      // Format: "1. priority text"
+      const match = trimmed.match(/^\d+\.\s+(.+)$/);
+      if (match && match[1] !== "(none)") {
+        result.currentPriorities.push(match[1]);
+      }
+    }
+
+    // Intentionally captures only the first non-empty line as the strategy for simplicity
+    if (section === "strategy" && trimmed.length > 0 && trimmed !== "(no strategy defined)") {
+      result.strategy = trimmed;
+    }
+
+    if (section === "updated" && trimmed.length > 0) {
+      result.lastUpdated = trimmed;
+      section = "";
+    }
+  }
+
+  return result;
+}
+
+export function writePlan(data: MemoryPlan, memoryDir: string = MEMORY_DIR): void {
+  ensureMemoryDir(memoryDir);
+  const filePath = join(memoryDir, "plan.md");
+  writeFileSync(filePath, formatPlan(data), "utf-8");
+}
+
+export function readPlan(memoryDir: string = MEMORY_DIR): MemoryPlan {
+  const filePath = join(memoryDir, "plan.md");
+  if (!existsSync(filePath)) {
+    return { currentPriorities: [], strategy: "", lastUpdated: "" };
+  }
+  const content = readFileSync(filePath, "utf-8");
+  return parsePlan(content);
+}
+
+// ---------------------------------------------------------------------------
+// decisions.md (append-only)
+// ---------------------------------------------------------------------------
+
+function formatDecisionEntry(record: DecisionRecord): string {
+  const lines: string[] = [
+    `## ${record.timestamp} — ${record.actionType}`,
+    `- **Skill:** ${record.skillName}`,
+    `- **Action:** ${record.action}`,
+    `- **Rationale:** ${record.rationale}`,
+    `- **Result:** ${record.result}`,
+    "",
+    "---",
+    "",
+  ];
+  return lines.join("\n");
+}
+
+function parseDecisions(content: string): DecisionRecord[] {
+  const records: DecisionRecord[] = [];
+  // Split on --- separators
+  const blocks = content.split(/^---$/m);
+
+  for (const block of blocks) {
+    const lines = block
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0);
+
+    let timestamp = "";
+    let actionType = "";
+    let skillName = "";
+    let action: DecisionRecord["action"] = "watched";
+    let rationale = "";
+    let result = "";
+
+    for (const line of lines) {
+      // Header: "## 2026-03-01T00:00:00Z — evolve"
+      const headerMatch = line.match(/^## (.+?) — (.+)$/);
+      if (headerMatch) {
+        timestamp = headerMatch[1];
+        actionType = headerMatch[2];
+        continue;
+      }
+
+      if (line.startsWith("- **Skill:**")) {
+        skillName = line.replace("- **Skill:**", "").trim();
+      } else if (line.startsWith("- **Action:**")) {
+        const raw = line.replace("- **Action:**", "").trim();
+        if (raw === "evolved" || raw === "rolled-back" || raw === "watched") {
+          action = raw;
+        }
+      } else if (line.startsWith("- **Rationale:**")) {
+        rationale = line.replace("- **Rationale:**", "").trim();
+      } else if (line.startsWith("- **Result:**")) {
+        result = line.replace("- **Result:**", "").trim();
+      }
+    }
+
+    if (timestamp && skillName) {
+      records.push({ timestamp, actionType, skillName, action, rationale, result });
+    }
+  }
+
+  return records;
+}
+
+export function appendDecision(record: DecisionRecord, memoryDir: string = MEMORY_DIR): void {
+  ensureMemoryDir(memoryDir);
+  const filePath = join(memoryDir, "decisions.md");
+
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, "# Decision Log\n\n", "utf-8");
+  }
+
+  const entry = formatDecisionEntry(record);
+  appendFileSync(filePath, entry, "utf-8");
+}
+
+export function readDecisions(memoryDir: string = MEMORY_DIR): DecisionRecord[] {
+  const filePath = join(memoryDir, "decisions.md");
+  if (!existsSync(filePath)) {
+    return [];
+  }
+  const content = readFileSync(filePath, "utf-8");
+  return parseDecisions(content);
+}
+
+// ---------------------------------------------------------------------------
+// High-level helpers for integration
+// ---------------------------------------------------------------------------
+
+export function updateContextAfterEvolve(
+  skillName: string,
+  proposal: EvolutionProposal,
+  result: EvolveResult,
+  memoryDir: string = MEMORY_DIR,
+): void {
+  const now = new Date().toISOString();
+  const context = readContext(memoryDir);
+
+  const status = result.deployed ? "deployed" : "failed";
+  const description = proposal.rationale || result.reason;
+
+  // Update or add the evolution entry
+  const idx = context.activeEvolutions.findIndex((e) => e.skillName === skillName);
+  if (idx >= 0) {
+    context.activeEvolutions[idx] = { skillName, status, description };
+  } else {
+    context.activeEvolutions.push({ skillName, status, description });
+  }
+
+  context.lastUpdated = now;
+  writeContext(context, memoryDir);
+
+  // Append decision
+  appendDecision(
+    {
+      timestamp: now,
+      actionType: "evolve",
+      skillName,
+      action: "evolved",
+      rationale: proposal.rationale || "Evolution triggered",
+      result: result.reason,
+    },
+    memoryDir,
+  );
+}
+
+export function updateContextAfterRollback(
+  skillName: string,
+  result: RollbackResult,
+  memoryDir: string = MEMORY_DIR,
+): void {
+  const now = new Date().toISOString();
+  const context = readContext(memoryDir);
+
+  const status = result.rolledBack ? "rolled-back" : "rollback-failed";
+  const description = result.reason;
+
+  const idx = context.activeEvolutions.findIndex((e) => e.skillName === skillName);
+  if (idx >= 0) {
+    context.activeEvolutions[idx] = { skillName, status, description };
+  } else {
+    context.activeEvolutions.push({ skillName, status, description });
+  }
+
+  context.lastUpdated = now;
+  writeContext(context, memoryDir);
+
+  appendDecision(
+    {
+      timestamp: now,
+      actionType: "rollback",
+      skillName,
+      action: "rolled-back",
+      rationale: result.reason,
+      result: result.rolledBack ? "Successfully rolled back" : "Rollback failed",
+    },
+    memoryDir,
+  );
+}
+
+export function updateContextAfterWatch(
+  skillName: string,
+  snapshot: MonitoringSnapshot,
+  memoryDir: string = MEMORY_DIR,
+): void {
+  const now = new Date().toISOString();
+  const context = readContext(memoryDir);
+
+  const status = snapshot.regression_detected ? "regression" : "healthy";
+  const description = `pass_rate=${snapshot.pass_rate.toFixed(2)}, baseline=${snapshot.baseline_pass_rate.toFixed(2)}`;
+
+  const idx = context.activeEvolutions.findIndex((e) => e.skillName === skillName);
+  if (idx >= 0) {
+    context.activeEvolutions[idx] = { skillName, status, description };
+  } else {
+    context.activeEvolutions.push({ skillName, status, description });
+  }
+
+  // Add known issue if regression detected
+  if (snapshot.regression_detected) {
+    const issue = `Regression detected for ${skillName}: pass_rate=${snapshot.pass_rate.toFixed(2)} below baseline=${snapshot.baseline_pass_rate.toFixed(2)}`;
+    if (!context.knownIssues.some((i) => i.includes(skillName) && i.includes("Regression"))) {
+      context.knownIssues.push(issue);
+    }
+  }
+
+  context.lastUpdated = now;
+  writeContext(context, memoryDir);
+
+  appendDecision(
+    {
+      timestamp: now,
+      actionType: "watch",
+      skillName,
+      action: "watched",
+      rationale: `Monitoring check: pass_rate=${snapshot.pass_rate.toFixed(2)}, regression=${snapshot.regression_detected}`,
+      result: snapshot.regression_detected
+        ? `Regression detected (pass_rate=${snapshot.pass_rate.toFixed(2)})`
+        : `Healthy (pass_rate=${snapshot.pass_rate.toFixed(2)})`,
+    },
+    memoryDir,
+  );
+}

package/cli/selftune/monitoring/watch.ts

@@ -9,7 +9,10 @@
 import { parseArgs } from "node:util";
 
 import { QUERY_LOG, SKILL_LOG, TELEMETRY_LOG } from "../constants.js";
+import { classifyInvocation } from "../eval/hooks-to-evals.js";
 import { getLastDeployedProposal } from "../evolution/audit.js";
+import { updateContextAfterWatch } from "../memory/writer.js";
+import type { SyncResult } from "../sync.js";
 import type {
   InvocationType,
   MonitoringSnapshot,
@@ -18,6 +21,11 @@ import type {
   SkillUsageRecord,
 } from "../types.js";
 import { readJsonl } from "../utils/jsonl.js";
+import {
+  filterActionableQueryRecords,
+  filterActionableSkillUsageRecords,
+} from "../utils/query-filter.js";
+import { readEffectiveSkillUsageRecords } from "../utils/skill-log.js";
 
 // ---------------------------------------------------------------------------
 // Public interfaces
@@ -40,6 +48,10 @@ export interface WatchOptions {
     skillPath: string;
     proposalId?: string;
   }) => Promise<{ rolledBack: boolean; restoredDescription: string; reason: string }>;
+  /** Source-truth refresh before reading logs. */
+  syncFirst?: boolean;
+  syncForce?: boolean;
+  _syncFn?: typeof import("../sync.js").syncSources;
 }
 
 export interface WatchResult {
@@ -47,6 +59,7 @@ export interface WatchResult {
   alert: string | null;
   rolledBack: boolean;
   recommendation: string;
+  sync_result?: SyncResult;
 }
 
 // ---------------------------------------------------------------------------
@@ -55,6 +68,7 @@ export interface WatchResult {
 
 const DEFAULT_BASELINE_PASS_RATE = 0.5;
 const DEFAULT_REGRESSION_THRESHOLD = 0.1;
+export const MIN_MONITORING_SKILL_CHECKS = 3;
 
 // ---------------------------------------------------------------------------
 // computeMonitoringSnapshot - pure function
@@ -64,9 +78,9 @@ const DEFAULT_REGRESSION_THRESHOLD = 0.1;
  * Compute a monitoring snapshot from raw log records.
  *
  * The function windows telemetry to the last `windowSessions` entries, then
- * scopes skill and query records to those sessions. If telemetry is empty or
- * no records match the windowed session IDs, all provided skill/query records
- * are used directly (unfiltered by session).
+ * scopes skill and actionable query records to those sessions. If telemetry is
+ * empty or no records match the windowed session IDs, all provided skill/query
+ * records are used directly (unfiltered by session).
  *
  * @param skillName        - The skill to monitor
  * @param telemetry        - All session telemetry records
@@ -86,43 +100,53 @@ export function computeMonitoringSnapshot(
   regressionThreshold: number = DEFAULT_REGRESSION_THRESHOLD,
 ): MonitoringSnapshot {
   // 1. Window the telemetry to the last N sessions (by array order, assumed chronological)
+  const actionableSkillRecords = filterActionableSkillUsageRecords(skillRecords);
+  const actionableQueryRecords = filterActionableQueryRecords(queryRecords);
   const windowedTelemetry = telemetry.slice(-windowSessions);
   const windowedSessionIds = new Set(windowedTelemetry.map((t) => t.session_id));
 
   // 2. Filter skill records by skill name first
-  const skillNameFiltered = skillRecords.filter((r) => r.skill_name === skillName);
+  const skillNameFiltered = actionableSkillRecords.filter((r) => r.skill_name === skillName);
 
   // 3. Apply session ID windowing only if telemetry is present and overlaps
   const hasSessionOverlap =
     windowedSessionIds.size > 0 &&
     (skillNameFiltered.some((r) => windowedSessionIds.has(r.session_id)) ||
-      queryRecords.some((r) => windowedSessionIds.has(r.session_id)));
+      actionableQueryRecords.some((r) => windowedSessionIds.has(r.session_id)));
 
   const filteredSkillRecords = hasSessionOverlap
     ? skillNameFiltered.filter((r) => windowedSessionIds.has(r.session_id))
     : skillNameFiltered;
-
   const filteredQueryRecords = hasSessionOverlap
-    ? queryRecords.filter((r) => windowedSessionIds.has(r.session_id))
-    : queryRecords;
+    ? actionableQueryRecords.filter((r) => windowedSessionIds.has(r.session_id))
+    : actionableQueryRecords;
 
-  // 4. Compute pass rate: triggered_count / total_query_count
+  // 4. Compute pass rate from explicit skill checks, not from all queries.
   const triggeredCount = filteredSkillRecords.filter((r) => r.triggered).length;
-  const totalQueries = filteredQueryRecords.length;
-  const passRate = totalQueries === 0 ? 1.0 : triggeredCount / totalQueries;
+  const totalSkillChecks = filteredSkillRecords.length;
+  const passRate = totalSkillChecks === 0 ? 0 : triggeredCount / totalSkillChecks;
 
   // 5. Compute false negative rate from skill usage records
-  const totalSkillChecks = filteredSkillRecords.length;
   const falseNegatives = filteredSkillRecords.filter((r) => !r.triggered).length;
   const falseNegativeRate = totalSkillChecks === 0 ? 0 : falseNegatives / totalSkillChecks;
 
-  // 6. by_invocation_type: MVP classifies everything as "implicit"
+  // 6. by_invocation_type: classify each skill record using classifyInvocation
   const byInvocationType: Record<InvocationType, { passed: number; total: number }> = {
     explicit: { passed: 0, total: 0 },
-    implicit: { passed: triggeredCount, total: totalSkillChecks },
+    implicit: { passed: 0, total: 0 },
     contextual: { passed: 0, total: 0 },
     negative: { passed: 0, total: 0 },
   };
+  for (const record of filteredSkillRecords) {
+    const invType = classifyInvocation(
+      typeof record.query === "string" ? record.query : "",
+      skillName,
+    );
+    byInvocationType[invType].total++;
+    if (record.triggered) {
+      byInvocationType[invType].passed++;
+    }
+  }
 
   // 7. Regression detection: pass_rate < baseline - threshold
   // Use rounding to avoid floating-point boundary issues (e.g. 0.8 - 0.1 = 0.7000000000000001)
@@ -130,12 +154,16 @@ export function computeMonitoringSnapshot(
   const adjustedThreshold =
     Math.round((baselinePassRate - regressionThreshold) * precision) / precision;
   const roundedPassRate = Math.round(passRate * precision) / precision;
-  const regressionDetected = roundedPassRate < adjustedThreshold;
+  const hasEnoughSignalForRegression =
+    totalSkillChecks >= MIN_MONITORING_SKILL_CHECKS ||
+    (totalSkillChecks === 0 && filteredQueryRecords.length >= MIN_MONITORING_SKILL_CHECKS);
+  const regressionDetected = hasEnoughSignalForRegression && roundedPassRate < adjustedThreshold;
 
   return {
     timestamp: new Date().toISOString(),
     skill_name: skillName,
     window_sessions: windowSessions,
+    skill_checks: totalSkillChecks,
     pass_rate: passRate,
     false_negative_rate: falseNegativeRate,
     by_invocation_type: byInvocationType,
@@ -163,11 +191,28 @@ export async function watch(options: WatchOptions): Promise<WatchResult> {
     _queryLogPath = QUERY_LOG,
     _auditLogPath,
     _rollbackFn,
+    syncFirst = false,
+    syncForce = false,
+    _syncFn,
   } = options;
 
+  let syncResult: SyncResult | undefined;
+  if (syncFirst) {
+    const { createDefaultSyncOptions, syncSources: realSyncSources } = await import("../sync.js");
+    const syncRunner = _syncFn ?? realSyncSources;
+    syncResult = syncRunner(
+      createDefaultSyncOptions({
+        force: syncForce,
+      }),
+    );
+  }
+
   // 1. Read log files
   const telemetry = readJsonl<SessionTelemetryRecord>(_telemetryLogPath);
-  const skillRecords = readJsonl<SkillUsageRecord>(_skillLogPath);
+  const skillRecords =
+    _skillLogPath === SKILL_LOG
+      ? readEffectiveSkillUsageRecords()
+      : readJsonl<SkillUsageRecord>(_skillLogPath);
   const queryRecords = readJsonl<QueryLogRecord>(_queryLogPath);
 
   // 2. Determine baseline pass rate from last deployed audit entry
@@ -208,15 +253,34 @@ export async function watch(options: WatchOptions): Promise<WatchResult> {
     recommendation = rolledBack
       ? `Rolled back "${skillName}" to previous version. Monitor to confirm recovery.`
       : `Consider running: selftune rollback --skill "${skillName}" --skill-path "${skillPath}"`;
+  } else if (snapshot.skill_checks < MIN_MONITORING_SKILL_CHECKS) {
+    recommendation =
+      `Skill "${skillName}" has only ${snapshot.skill_checks} actionable check(s) in the current window. ` +
+      `Need at least ${MIN_MONITORING_SKILL_CHECKS} before calling it stable.`;
   } else {
     recommendation = `Skill "${skillName}" is stable. Pass rate ${snapshot.pass_rate.toFixed(2)} is within acceptable range of baseline ${baselinePassRate.toFixed(2)}.`;
   }
 
+  // Update evolution memory (fail-open)
+  try {
+    updateContextAfterWatch(skillName, snapshot);
+  } catch (err) {
+    // Fail-open: memory writes should never fail the main operation
+    console.error(
+      JSON.stringify({
+        level: "debug",
+        code: "memory_write_failed",
+        message: `Failed to update memory after watch for "${skillName}": ${err instanceof Error ? err.message : String(err)}`,
+      }),
+    );
+  }
+
   return {
     snapshot,
     alert,
     rolledBack,
     recommendation,
+    ...(syncResult ? { sync_result: syncResult } : {}),
   };
 }
 
@@ -260,6 +324,8 @@ export async function cliMain(): Promise<void> {
       window: { type: "string", default: "20" },
       threshold: { type: "string", default: "0.1" },
       "auto-rollback": { type: "boolean", default: false },
+      "sync-first": { type: "boolean", default: false },
+      "sync-force": { type: "boolean", default: false },
       help: { type: "boolean", default: false },
     },
     strict: true,
@@ -277,6 +343,8 @@ Options:
   --window            Number of recent sessions to consider (default: 20)
   --threshold         Regression threshold below baseline (default: 0.1)
   --auto-rollback     Automatically rollback on regression detection
+  --sync-first        Refresh source-truth telemetry before reading watch inputs
+  --sync-force        Force a full rescan during --sync-first
   --help              Show this help message`);
     process.exit(0);
   }
@@ -285,6 +353,10 @@ Options:
     console.error("[ERROR] --skill and --skill-path are required");
     process.exit(1);
   }
+  if ((values["sync-force"] ?? false) && !(values["sync-first"] ?? false)) {
+    console.error("[ERROR] --sync-force requires --sync-first");
+    process.exit(1);
+  }
 
   const rawWindow = values.window ?? "20";
   if (!/^\d+$/.test(rawWindow)) {
@@ -314,6 +386,8 @@ Options:
     windowSessions,
     regressionThreshold,
     autoRollback: values["auto-rollback"] ?? false,
+    syncFirst: values["sync-first"] ?? false,
+    syncForce: values["sync-force"] ?? false,
   });
 
   console.log(JSON.stringify(result, null, 2));