@gobing-ai/superskill 0.1.8 → 0.2.1

package/dist/index.js

@@ -9348,6 +9348,11 @@ function resolveContentPath(type, name, opts) {
   const asIs = join(base, name);
   if (existsSync(asIs) && statSync(asIs).isFile())
     return asIs;
+  if (type === "skill") {
+    const skillDirForm = join(base, name, "SKILL.md");
+    if (existsSync(skillDirForm))
+      return skillDirForm;
+  }
   const direct = join(base, `${name}.md`);
   if (existsSync(direct))
     return direct;
@@ -9366,6 +9371,11 @@ function resolveContentPath(type, name, opts) {
   }
   return null;
 }
+function assertSafePathSegment(value, label) {
+  if (!value || value === "." || value === ".." || value.includes("/") || value.includes("\\") || value.includes("\x00")) {
+    throw new Error(`Invalid ${label} '${value}': must be a single path segment`);
+  }
+}
 var init_identity = () => {};
 
 // ../../packages/core/src/content/paths.ts
@@ -9809,11 +9819,6 @@ function mapPluginToRulesync(pluginPath, pluginName, outputDir) {
   }
   return result;
 }
-function assertSafePathSegment(value, label) {
-  if (!value || value === "." || value === ".." || value.includes("/") || value.includes("\\") || value.includes("\x00")) {
-    throw new Error(`Invalid ${label} '${value}': must be a single path segment`);
-  }
-}
 function deepMergeJsonFile(sourcePath, targetPath) {
   const source = readJsonObject(sourcePath);
   const target = existsSync3(targetPath) ? readJsonObject(targetPath) : {};
@@ -9853,6 +9858,7 @@ function copyAndRewriteDirectory(source, destination, pluginName) {
   }
 }
 var init_mapper = __esm(() => {
+  init_identity();
   init_adapt_command();
   init_adapt_subagent();
   init_rewrite_references();
@@ -14084,45 +14090,106 @@ import { existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as rea
 import { homedir as homedir2 } from "os";
 import { join as join6 } from "path";
 import { cwd as cwd4 } from "process";
+function parseList(value) {
+  if (value === undefined)
+    return [];
+  if (Array.isArray(value)) {
+    return value.map((v) => v.trim()).filter((v) => v.length > 0);
+  }
+  return value.split(",").map((v) => v.trim()).filter((v) => v.length > 0);
+}
+function toYamlArray(items) {
+  return `[${items.join(", ")}]`;
+}
 function substituteVars(template, vars) {
-  return template.replaceAll(PLACEHOLDER_NAME, vars.name).replaceAll(PLACEHOLDER_DESCRIPTION, vars.description).replaceAll(PLACEHOLDER_TARGET, vars.target).replaceAll(PLACEHOLDER_BODY, vars.body);
+  return template.replaceAll(PLACEHOLDER_NAME, vars.name).replaceAll(PLACEHOLDER_DESCRIPTION, vars.description).replaceAll(PLACEHOLDER_TARGET, vars.target).replaceAll(PLACEHOLDER_BODY, vars.body).replaceAll(PLACEHOLDER_TOOLS, toYamlArray(vars.tools));
+}
+function mergeFrontmatterList(content, key, items) {
+  if (items.length === 0)
+    return content;
+  const fenceRe = /^---$/gm;
+  const matches = [...content.matchAll(fenceRe)];
+  if (matches.length < 2)
+    return content;
+  const openPos = matches[0]?.index ?? 0;
+  const closePos = matches[1]?.index ?? 0;
+  const fmStart = openPos + 3;
+  const fmBody = content.slice(fmStart, closePos);
+  const yamlValue = toYamlArray(items);
+  const pattern = new RegExp(`^${key}:.*$`, "m");
+  let newFmBody;
+  if (pattern.test(fmBody)) {
+    newFmBody = fmBody.replace(pattern, `${key}: ${yamlValue}`);
+  } else {
+    newFmBody = `${fmBody}${key}: ${yamlValue}
+`;
+  }
+  return content.slice(0, fmStart) + newFmBody + content.slice(closePos);
 }
-function resolveTemplate(type) {
+function resolveTemplate(type, tier) {
   const homeDir = process.env.HOME ?? homedir2();
+  const tierName = tier?.trim();
+  if (tierName && tierName !== "default") {
+    const userTierPath = join6(homeDir, ".superskill", "templates", type, `${tierName}.md`);
+    if (existsSync7(userTierPath)) {
+      return readFileSync5(userTierPath, "utf-8");
+    }
+    for (const base of TEMPLATE_BASE_DIRS) {
+      const path = join6(base, type, `${tierName}.md`);
+      if (existsSync7(path)) {
+        return readFileSync5(path, "utf-8");
+      }
+    }
+    throw new Error(`Unknown template tier "${tierName}" for type "${type}". ` + `No user override (~/.superskill/templates/${type}/${tierName}.md) ` + `or built-in template found. Omit --template to use the default tier.`);
+  }
   const userPath = join6(homeDir, ".superskill", "templates", type, "default.md");
   if (existsSync7(userPath)) {
     return readFileSync5(userPath, "utf-8");
   }
-  const devPath = join6(import.meta.dir, "..", "..", "..", "..", "apps", "cli", "src", "templates", type, "default.md");
-  if (existsSync7(devPath)) {
-    return readFileSync5(devPath, "utf-8");
+  for (const base of TEMPLATE_BASE_DIRS) {
+    const path = join6(base, type, "default.md");
+    if (existsSync7(path)) {
+      return readFileSync5(path, "utf-8");
+    }
   }
-  const prodPath = join6(import.meta.dir, "..", "templates", type, "default.md");
-  return readFileSync5(prodPath, "utf-8");
+  throw new Error(`No built-in default template found for type "${type}".`);
 }
 async function scaffold(type, name, opts = {}) {
-  const validTypes = ["skill", "command", "agent", "hook", "magent"];
+  const validTypes = ["skill", "command", "agent", "magent"];
   if (!validTypes.includes(type)) {
     throw new Error(`Unknown content type: "${type}". Expected one of: ${validTypes.join(", ")}`);
   }
-  const template = resolveTemplate(type);
-  const content = substituteVars(template, {
+  assertSafePathSegment(name, "content name");
+  const template = resolveTemplate(type, opts.template);
+  let content = substituteVars(template, {
     name,
     description: opts.description ?? "",
     target: opts.target ?? "claude",
-    body: ""
+    body: "",
+    tools: parseList(opts.tools)
   });
+  const toolField = type === "agent" ? "tools" : "allowed-tools";
+  content = mergeFrontmatterList(content, toolField, parseList(opts.tools));
   const outDir = opts.output ?? cwd4();
   mkdirSync4(outDir, { recursive: true });
-  const filePath = join6(outDir, `${name}.md`);
+  const filePath = type === "skill" ? join6(outDir, name, "SKILL.md") : join6(outDir, `${name}.md`);
+  if (type === "skill") {
+    mkdirSync4(join6(outDir, name), { recursive: true });
+  }
   if (existsSync7(filePath) && !opts.force) {
     throw new Error(`${filePath} already exists \u2014 pass --force to overwrite`);
   }
   writeFileSync3(filePath, content, "utf-8");
   return filePath;
 }
-var PLACEHOLDER_NAME = "<!-- NAME -->", PLACEHOLDER_DESCRIPTION = "<!-- DESCRIPTION -->", PLACEHOLDER_TARGET = "<!-- TARGET -->", PLACEHOLDER_BODY = "<!-- BODY -->";
-var init_scaffold = () => {};
+var PLACEHOLDER_NAME = "<!-- NAME -->", PLACEHOLDER_DESCRIPTION = "<!-- DESCRIPTION -->", PLACEHOLDER_TARGET = "<!-- TARGET -->", PLACEHOLDER_BODY = "<!-- BODY -->", PLACEHOLDER_TOOLS = "<!-- TOOLS -->", TEMPLATE_BASE_DIRS;
+var init_scaffold = __esm(() => {
+  init_identity();
+  TEMPLATE_BASE_DIRS = [
+    join6(import.meta.dir, "..", "..", "..", "..", "apps", "cli", "src", "templates"),
+    join6(import.meta.dir, "..", "templates")
+  ];
+});
 
 // ../../packages/core/src/quality/types.ts
 function computeAggregate(dimensions) {
@@ -14331,8 +14398,16 @@ function scorePatternMatchQuality(entries) {
       specificMatchers++;
     if (e.timeout !== undefined && e.timeout > 0)
       hasTimeout++;
-    if (/\$\{CLAUDE_PLUGIN_ROOT\}/.test(e.command) || !/^\//.test(e.command.trim()))
+    if (/\$\{CLAUDE_PLUGIN_ROOT\}/.test(e.command)) {
       portable++;
+    } else {
+      const tokens = e.command.trim().split(/\s+/);
+      const firstToken = tokens[0] ?? "";
+      const bareBinary = firstToken.length > 0 && !firstToken.includes("/") && !firstToken.startsWith(".");
+      const noPathTokens = tokens.every((t) => !t.includes("/") || /\$\{CLAUDE_PLUGIN_ROOT\}/.test(t));
+      if (bareBinary && noPathTokens)
+        portable++;
+    }
   }
   const n = entries.length || 1;
   const matcherScore = specificMatchers / n;
@@ -14512,10 +14587,23 @@ function _validateContent(type, content, opts) {
   const findings = [];
   let data;
   let body;
+  const frontmatterPresent = /^---\s*$/m.test(content);
   try {
-    const parsed = parseFrontmatter(content);
-    data = parsed.data;
-    body = parsed.body;
+    if (frontmatterPresent) {
+      const parsed = parseFrontmatter(content);
+      data = parsed.data;
+      body = parsed.body;
+    } else if (type === "magent") {
+      data = {};
+      body = content;
+    } else {
+      findings.push({
+        severity: "error",
+        field: "frontmatter",
+        message: "YAML parse error: Missing frontmatter: content must start with ---"
+      });
+      return { valid: false, findings };
+    }
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
     findings.push({ severity: "error", field: "frontmatter", message: `YAML parse error: ${msg}` });
@@ -14661,7 +14749,7 @@ function checkLinkValidity(type, data, referenceChecker) {
   }
   return findings;
 }
-function strictChecks(_type, data, body) {
+function strictChecks(type, data, body) {
   const findings = [];
   const desc = data.description;
   if (typeof desc === "string" && desc.length < 40) {
@@ -14698,6 +14786,22 @@ function strictChecks(_type, data, body) {
       });
     }
   }
+  const recognized = new Set([
+    ...Object.keys(FIELD_TYPES[type] ?? {}),
+    ...REQUIRED_FIELDS[type],
+    ...KNOWN_OPTIONAL[type] ?? []
+  ]);
+  for (const key of Object.keys(data)) {
+    if (recognized.has(key))
+      continue;
+    if (DEPRECATED_FIELDS[key] !== undefined)
+      continue;
+    findings.push({
+      severity: "warning",
+      field: key,
+      message: `Unknown frontmatter key '${key}'`
+    });
+  }
   return findings;
 }
 function formatValidationResult(result, json) {
@@ -14716,7 +14820,7 @@ function sentinelResult(message) {
     findings: [{ severity: "error", field: "_file", message }]
   };
 }
-var MODEL_ALIASES, FIELD_TYPES, DEPRECATED_FIELDS;
+var MODEL_ALIASES, FIELD_TYPES, DEPRECATED_FIELDS, KNOWN_OPTIONAL;
 var init_validate = __esm(() => {
   init_frontmatter();
   init_identity();
@@ -14757,12 +14861,13 @@ var init_validate = __esm(() => {
     author: "No longer used; remove.",
     version: "Version is derived from the source repository."
   };
-});
-
-// ../../packages/core/src/pipeline/pi-subagent.ts
-var init_pi_subagent = __esm(() => {
-  init_frontmatter();
-  init_pi_tools();
+  KNOWN_OPTIONAL = {
+    skill: ["license", "metadata"],
+    command: ["argument-hint", "allowed-tools", "target"],
+    agent: [],
+    hook: [],
+    magent: []
+  };
 });
 
 // ../../node_modules/.bun/@logtape+logtape@2.1.5/node_modules/@logtape/logtape/dist/context.js
@@ -89186,7 +89291,6 @@ var init_src = __esm(() => {
   init_validate();
   init_adapt_command();
   init_adapt_subagent();
-  init_pi_subagent();
   init_pi_tools();
   init_rewrite_references();
   init_slash_command2();
@@ -94980,7 +95084,22 @@ async function evaluate3(type, nameOrPath, opts) {
   report.content = resolveContentName(resolvedPath);
   applyRubricWeightingAndVerdict(type, report, opts);
   if (opts?.save) {
-    await persistEvaluation(type, resolvedPath, resolvedTarget, report, opts);
+    try {
+      const adapter = opts.adapter ?? await openStore();
+      await new EvaluationDao(adapter).insertEvaluation({
+        content_type: type,
+        content_name: resolveContentName(resolvedPath),
+        target_agent: resolvedTarget,
+        operation: opts.operation ?? "evaluate",
+        aggregate: report.aggregate,
+        dimensions: report.dimensions,
+        file_hash: hashContent(resolvedPath),
+        scorer: "heuristic"
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      echoError(`Warning: failed to save evaluation: ${msg}`);
+    }
   }
   return report;
 }
@@ -95087,31 +95206,26 @@ async function ingestScores(type, resolvedPath, resolvedTarget, opts) {
     dimensions
   };
   if (opts.save) {
-    await persistEvaluation(type, resolvedPath, resolvedTarget, report, opts, "rubric", rubric2.version);
+    try {
+      const adapter = opts.adapter ?? await openStore();
+      await new EvaluationDao(adapter).insertEvaluation({
+        content_type: type,
+        content_name: resolveContentName(resolvedPath),
+        target_agent: resolvedTarget,
+        operation: opts.operation ?? "evaluate",
+        aggregate: report.aggregate,
+        dimensions: report.dimensions,
+        file_hash: hashContent(resolvedPath),
+        scorer: "rubric",
+        rubric_version: rubric2.version
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      echoError(`Warning: failed to save evaluation: ${msg}`);
+    }
   }
   return report;
 }
-async function persistEvaluation(type, resolvedPath, resolvedTarget, report, opts, scorer, rubricVersion) {
-  try {
-    const fileHash = hashContent(resolvedPath);
-    const adapter = opts.adapter ?? await openStore();
-    const dao = new EvaluationDao(adapter);
-    await dao.insertEvaluation({
-      content_type: type,
-      content_name: resolveContentName(resolvedPath),
-      target_agent: resolvedTarget,
-      operation: opts.operation ?? "evaluate",
-      aggregate: report.aggregate,
-      dimensions: report.dimensions,
-      file_hash: fileHash,
-      scorer: scorer ?? "heuristic",
-      ...rubricVersion !== undefined ? { rubric_version: rubricVersion } : {}
-    });
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    echoError(`Warning: failed to save evaluation: ${msg}`);
-  }
-}
 function formatEvaluationReport(report, json3) {
   if (json3) {
     return JSON.stringify(report);
@@ -95235,6 +95349,11 @@ function deserializeProposal(row) {
 init_src();
 
 // src/operations/evolve.ts
+function isHookApplyCapableOpt(opts) {
+  if (!opts)
+    return false;
+  return Boolean(opts.proposeOnly || opts.acceptId || opts.rejectId || opts.ingest || opts.history || opts.rollback);
+}
 function computeTrends(evaluations2) {
   if (evaluations2.length < 2)
     return [];
@@ -95296,6 +95415,56 @@ function computeTrends(evaluations2) {
   });
   return trends;
 }
+function hasFrontmatter(content) {
+  if (!content.startsWith(`---
+`))
+    return false;
+  return /\n---(?=\n|$)/.test(content.slice(4));
+}
+function firstBodyLine(content) {
+  for (const line of content.split(`
+`)) {
+    const trimmed = line.trim();
+    if (trimmed)
+      return trimmed;
+  }
+  return "";
+}
+function generateChanges(report, trends, content) {
+  const changes = [];
+  const dimMap = new Map(Object.entries(report.dimensions));
+  const withFrontmatter = content === undefined ? true : hasFrontmatter(content);
+  const bodyAnchor = withFrontmatter ? "" : firstBodyLine(content ?? "");
+  for (const trend of trends) {
+    if (trend.trend === "declining" || trend.trend === "flat" && trend.latest < 0.7) {
+      const dimData = dimMap.get(trend.dimension);
+      const note = dimData?.note ?? "";
+      const scoreLine = `Score: ${trend.latest.toFixed(2)} (trend: ${trend.trend}, \u0394${trend.delta >= 0 ? "+" : ""}${trend.delta.toFixed(2)}).`;
+      if (withFrontmatter) {
+        const suggestion = note ? `[Improve ${trend.dimension}]: ${note}` : `[Improve ${trend.dimension}]: review and enhance the description for better ${trend.dimension}.`;
+        changes.push({
+          dimension: trend.dimension,
+          location: "frontmatter.description",
+          current: `${trend.dimension} score: ${trend.latest.toFixed(2)}`,
+          proposed: suggestion,
+          reason: note ? `${scoreLine} Note: "${note}".` : `${scoreLine} Score below threshold.`
+        });
+      } else {
+        const suggestion = note ? `[Improve ${trend.dimension}]: ${note}` : `[Improve ${trend.dimension}]: review and enhance this config for better ${trend.dimension}.`;
+        changes.push({
+          dimension: trend.dimension,
+          location: "body",
+          current: bodyAnchor,
+          proposed: bodyAnchor ? `${bodyAnchor}
+
+${suggestion}` : suggestion,
+          reason: `${scoreLine} Config has no frontmatter; suggesting a body addition rather than a frontmatter.description edit.`
+        });
+      }
+    }
+  }
+  return changes;
+}
 function generateProposalId(type, _name, existingProposals) {
   const date9 = new Date().toISOString().slice(0, 10);
   const seq = String(existingProposals.length + 1).padStart(3, "0");
@@ -95325,8 +95494,14 @@ function computeAnchorHash(anchor) {
   return hasher.digest("hex").slice(0, 16);
 }
 function computeBaselineAnchorHash(content) {
-  const parsed = parseFrontmatter(content);
-  const frontmatter2 = parsed.data;
+  let frontmatter2 = {};
+  if (hasFrontmatter(content)) {
+    try {
+      frontmatter2 = parseFrontmatter(content).data;
+    } catch {
+      frontmatter2 = {};
+    }
+  }
   return computeAnchorHash({
     frontmatter: frontmatter2,
     rubric_criteria: "",
@@ -95372,8 +95547,14 @@ async function runGate(input) {
 }
 function emitGenerationEnvelope(type, resolvedPath, content, baseline, trends) {
   const rubric2 = loadRubric(type);
-  const parsed = parseFrontmatter(content);
-  const frontmatter2 = parsed.data;
+  let frontmatter2 = {};
+  if (hasFrontmatter(content)) {
+    try {
+      frontmatter2 = parseFrontmatter(content).data;
+    } catch {
+      frontmatter2 = {};
+    }
+  }
   const description = frontmatter2.description;
   const negativeConstraints = extractNegativeConstraints(description);
   const contentName = resolveContentName(resolvedPath);
@@ -95467,6 +95648,9 @@ async function ingestProposal(db2, type, name, resolvedPath, ingestPath, opts, b
       ingestedAnchorHash: parsed.anchor_hash,
       skeptic: parsed.skeptic
     });
+    if (!verdict.rejected && verdict.backupPath) {
+      await persistVersionSnapshot(verdict.backupPath, resolvedPath, proposalId);
+    }
     return {
       baselineScore,
       postScore: verdict.postScore,
@@ -95503,8 +95687,8 @@ async function stepAnalyze(db2, type, name, opts) {
   const baselineDate = new Date(newest.created_at).toISOString();
   return { evaluations: evaluations2, trends, baselineScore, baselineDate };
 }
-async function stepPropose(db2, type, name, _report, trends, evaluations2, baselineScore, baselineDate) {
-  const changes = [];
+async function stepPropose(db2, type, name, report, trends, evaluations2, baselineScore, baselineDate, content) {
+  const changes = generateChanges(report, trends, content);
   const proposalDao = new ProposalDao(db2);
   const existingProposals = await proposalDao.getProposals(type, name);
   const proposalId = generateProposalId(type, name, existingProposals);
@@ -95705,12 +95889,58 @@ async function stepVerify(type, name, filePath, baselineScore, proposalDbId, opt
   } catch {
     echoError("Cannot link verify evaluation.");
   }
-  if (gate) {
-    rmSync3(gate.backupPath, { force: true });
-  }
+  const survivingBackupPath = gate?.backupPath;
   const pctStr = baselineScore > 0 ? `, ${delta >= 0 ? "+" : ""}${(delta / baselineScore * 100).toFixed(1)}%` : "";
   echo(`Score: ${baselineScore.toFixed(2)} \u2192 ${postScore.toFixed(2)} (${delta >= 0 ? "+" : ""}${delta.toFixed(2)}${pctStr})`);
-  return { postScore, delta };
+  return { postScore, delta, ...survivingBackupPath ? { backupPath: survivingBackupPath } : {} };
+}
+function scoreToGrade(score) {
+  if (score >= 0.9)
+    return "A";
+  if (score >= 0.75)
+    return "B";
+  if (score >= 0.6)
+    return "C";
+  if (score >= 0.45)
+    return "D";
+  return "F";
+}
+function formatAnalyze(name, analysis) {
+  const { trends, baselineScore, baselineDate, evaluations: evaluations2 } = analysis;
+  const grade = scoreToGrade(baselineScore);
+  const verdict = baselineScore >= 0.7 ? "PASS" : "FAIL";
+  const gitAvailable = existsSync12(join220(process.cwd(), ".git"));
+  const lines = [];
+  lines.push("=== Evolution Analysis ===");
+  lines.push(`Target: ${name}   Score: ${(baselineScore * 100).toFixed(0)}% (${grade})   Status: ${verdict}`);
+  lines.push(`Available data sources: evaluation-history (${evaluations2.length}) \xB7 git-history (${gitAvailable ? "\u2713" : "\u2717"})`);
+  if (trends.length > 0) {
+    lines.push("");
+    lines.push("| Dimension | Earliest | Latest | Trend |");
+    lines.push("|-----------|----------|--------|-------|");
+    for (const t of trends) {
+      const arrow = t.trend === "improving" ? "\u2191" : t.trend === "declining" ? "\u2193" : "\u2192";
+      lines.push(`| ${t.dimension} | ${t.earliest.toFixed(2)} | ${t.latest.toFixed(2)} | ${arrow} ${t.trend} |`);
+    }
+  }
+  const declining = trends.filter((t) => t.trend === "declining");
+  const flatLow = trends.filter((t) => t.trend === "flat" && t.latest < 0.7);
+  if (declining.length > 0) {
+    lines.push(`Patterns: [warning] declining dimensions: ${declining.map((t) => t.dimension).join(", ")}`);
+  } else if (flatLow.length > 0) {
+    lines.push(`Patterns: [warning] flat-low dimensions: ${flatLow.map((t) => t.dimension).join(", ")}`);
+  } else {
+    lines.push(`Patterns: [success] ${name} is currently stable at ${(baselineScore * 100).toFixed(0)}%`);
+  }
+  lines.push(`Baseline date: ${baselineDate}`);
+  return lines.join(`
+`);
+}
+async function persistVersionSnapshot(backupPath, resolvedPath, proposalId) {
+  const versionPath = `${resolvedPath}.version-${proposalId}`;
+  await Bun.write(versionPath, Bun.file(backupPath));
+  rmSync3(backupPath, { force: true });
+  return versionPath;
 }
 async function evolve(type, name, opts) {
   const resolvedPath = resolveContentPath(type, name);
@@ -95719,6 +95949,10 @@ async function evolve(type, name, opts) {
     return { baselineScore: 0, postScore: 0, delta: 0, changesApplied: 0, proposalPath: "" };
   }
   const contentName = resolveContentName(resolvedPath);
+  if (type === "hook" && isHookApplyCapableOpt(opts)) {
+    echoError("hook evolve is analyze-only \u2014 apply/history/rollback are not supported for hooks.");
+    return { baselineScore: 0, postScore: 0, delta: 0, changesApplied: 0, proposalPath: "" };
+  }
   let db2;
   try {
     db2 = await openDb(opts);
@@ -95727,6 +95961,45 @@ async function evolve(type, name, opts) {
     echoError(`Could not open the evaluation store. ${msg}`);
     return { baselineScore: 0, postScore: 0, delta: 0, changesApplied: 0, proposalPath: "" };
   }
+  if (opts?.history) {
+    const proposals2 = await new ProposalDao(db2).getProposals(type, contentName);
+    const accepted = proposals2.filter((p) => p.status === "accepted");
+    if (accepted.length === 0) {
+      echo(`No applied versions found for ${type}/${contentName}.`);
+      return { baselineScore: 0, postScore: 0, delta: 0, changesApplied: 0, proposalPath: "" };
+    }
+    const lines = [];
+    lines.push(`=== Version History: ${contentName} ===`);
+    lines.push("");
+    lines.push("| Version | Applied At | Snapshot |");
+    lines.push("|---------|------------|----------|");
+    for (const p of accepted) {
+      const json3 = typeof p.proposal_json === "string" ? JSON.parse(p.proposal_json) : p.proposal_json;
+      const proposalId2 = json3?.proposal_id;
+      const versionId = proposalId2 ?? `#${p.id}`;
+      const appliedAt = p.applied_at ?? "unknown";
+      const versionPath = `${resolvedPath}.version-${versionId}`;
+      const hasSnapshot = existsSync12(versionPath) ? "\u2713" : "\u2717";
+      lines.push(`| ${versionId} | ${appliedAt} | ${hasSnapshot} |`);
+    }
+    echo(lines.join(`
+`));
+    return { baselineScore: 0, postScore: 0, delta: 0, changesApplied: 0, proposalPath: "" };
+  }
+  if (opts?.rollback) {
+    if (!opts.confirm) {
+      echoError("--rollback requires --confirm to proceed.");
+      return { baselineScore: 0, postScore: 0, delta: 0, changesApplied: 0, proposalPath: "" };
+    }
+    const versionPath = `${resolvedPath}.version-${opts.rollback}`;
+    if (!existsSync12(versionPath)) {
+      echoError(`Version snapshot not found: ${opts.rollback}`);
+      return { baselineScore: 0, postScore: 0, delta: 0, changesApplied: 0, proposalPath: "" };
+    }
+    await Bun.write(resolvedPath, Bun.file(versionPath));
+    echo(`Rolled back ${contentName} to version ${opts.rollback}.`);
+    return { baselineScore: 0, postScore: 0, delta: 0, changesApplied: 0, proposalPath: "" };
+  }
   let analysis;
   try {
     analysis = await stepAnalyze(db2, type, contentName, opts);
@@ -95736,6 +96009,10 @@ async function evolve(type, name, opts) {
     return { baselineScore: 0, postScore: 0, delta: 0, changesApplied: 0, proposalPath: "" };
   }
   const { trends, baselineScore, baselineDate, evaluations: evaluations2 } = analysis;
+  if (opts?.analyze) {
+    echo(formatAnalyze(contentName, analysis));
+    return { baselineScore, postScore: baselineScore, delta: 0, changesApplied: 0, proposalPath: "" };
+  }
   if (evaluations2.length < 2) {
     echo("Only one evaluation found \u2014 need at least two for trend analysis. Running evaluation-based proposal instead.");
   }
@@ -95793,13 +96070,16 @@ async function evolve(type, name, opts) {
     } catch {
       acceptedFromStore = [];
     }
-    const backupPath = await backupFile(resolvedPath);
+    const backupPath2 = await backupFile(resolvedPath);
     const appliedCount = await stepApply(acceptedFromStore, resolvedPath, target.id, db2);
     const verdict = await stepVerify(type, contentName, resolvedPath, baselineScore, target.id, opts, db2, {
-      backupPath,
+      backupPath: backupPath2,
       ingestedAnchorHash: storedAnchorHash,
       skeptic: storedSkeptic
     });
+    if (!verdict.rejected && verdict.backupPath) {
+      await persistVersionSnapshot(verdict.backupPath, resolvedPath, opts.acceptId);
+    }
     return {
       baselineScore,
       postScore: verdict.postScore,
@@ -95809,20 +96089,24 @@ async function evolve(type, name, opts) {
       ...verdict.rejected ? { rejected: true, rejectionReason: verdict.reason } : {}
     };
   }
-  const { proposalDbId, proposalPath, changes } = await stepPropose(db2, type, contentName, baselineReport, trends, evaluations2, baselineScore, baselineDate);
+  const proposeContent = await Bun.file(resolvedPath).text();
+  const { proposalId, proposalDbId, proposalPath, changes } = await stepPropose(db2, type, contentName, baselineReport, trends, evaluations2, baselineScore, baselineDate, proposeContent);
   if (opts?.proposeOnly) {
     echo(`Proposal written to: ${proposalPath}`);
     return { baselineScore, postScore: baselineScore, delta: 0, changesApplied: 0, proposalPath };
   }
   const { accepted: acceptedChanges } = await interactiveReview(changes, trends);
+  const backupPath = await backupFile(resolvedPath);
   const changesApplied = await stepApply(acceptedChanges, resolvedPath, proposalDbId, db2);
   const { postScore, delta } = await stepVerify(type, contentName, resolvedPath, baselineScore, proposalDbId, opts, db2);
+  await persistVersionSnapshot(backupPath, resolvedPath, proposalId);
   return { baselineScore, postScore, delta, changesApplied, proposalPath };
 }
 
 // src/operations/refine.ts
 init_src();
 init_dist();
+init_db2();
 import { createInterface as createInterface2 } from "readline";
 class RefineAbortedError extends Error {
   constructor(message = "User quit interactive mode") {
@@ -95830,6 +96114,11 @@ class RefineAbortedError extends Error {
     this.name = "RefineAbortedError";
   }
 }
+function isHookApplyCapableOpt2(opts) {
+  if (!opts)
+    return false;
+  return Boolean(opts.auto || opts.save);
+}
 function classifyFix(finding) {
   if (finding.severity === "error") {
     return "auto-apply";
@@ -95842,17 +96131,59 @@ function classifyFix(finding) {
   }
   return "auto-apply";
 }
-function getDefaultForField(field) {
-  const DEFAULTS = {
-    name: "TODO",
-    description: "TODO",
-    model: "default"
-  };
-  return DEFAULTS[field] ?? "TODO";
+function getDefaultForField(field, content) {
+  if (field === "model")
+    return "inherit";
+  if (field === "tools")
+    return [];
+  const name = readFrontmatterName(content);
+  const h1 = extractFirstHeading(content);
+  if (field === "description") {
+    if (name)
+      return humanize(name);
+    if (h1)
+      return h1;
+    return null;
+  }
+  if (field === "name") {
+    if (h1)
+      return slugify2(h1);
+    return null;
+  }
+  return null;
+}
+function readFrontmatterName(content) {
+  try {
+    const parsed = parseFrontmatter(content);
+    const name = parsed.data.name;
+    return typeof name === "string" && name.trim() ? name.trim() : null;
+  } catch {
+    return null;
+  }
+}
+function extractFirstHeading(content) {
+  let body = content;
+  if (content.startsWith(`---
+`)) {
+    const closer = content.slice(4).match(/\n---(?=\n|$)/);
+    if (closer?.index !== undefined)
+      body = content.slice(closer.index + 4 + 4);
+  }
+  const headingMatch = /^\s*#\s+(.+?)\s*$/m.exec(body);
+  return headingMatch?.[1] ? headingMatch[1].trim() : null;
+}
+function humanize(slug) {
+  return slug.replace(/[-_]+/g, " ").replace(/\b\w/g, (c3) => c3.toUpperCase()).trim();
+}
+function slugify2(label) {
+  return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function generateAutoChange(finding, content) {
   if (finding.message.toLowerCase().includes("missing")) {
-    return { kind: "frontmatter", key: finding.field, value: getDefaultForField(finding.field) };
+    const value = getDefaultForField(finding.field, content);
+    if (value === null)
+      return null;
+    return { kind: "frontmatter", key: finding.field, value };
   }
   if (finding.message.includes("must be an array")) {
     let currentValue;
@@ -95998,30 +96329,30 @@ function applyAutoFixes(findings, content) {
 async function refine3(type, nameOrPath, opts) {
   const resolvedPath = resolveContentPath(type, nameOrPath);
   const resolvedTarget = opts?.target ?? "claude";
-  const validation = await validate(type, resolvedPath ?? nameOrPath, {
+  const filePath = resolvedPath ?? nameOrPath;
+  if (type === "hook" && isHookApplyCapableOpt2(opts)) {
+    echoError("hook refine is suggest-only \u2014 auto-apply and save are not supported for hooks. Use --dry-run to preview findings, then hand-fix and `hook validate`.");
+    return { preScore: 0, postScore: 0, delta: 0, fixesApplied: [], fixesSkipped: [] };
+  }
+  const validation = await validate(type, filePath, {
     target: resolvedTarget,
     strict: opts?.auto === true
   });
-  if (!validation.valid) {
-    for (const f of validation.findings) {
-      if (f.severity === "error") {
-        echoError(`[ERROR] ${f.field}: ${f.message}`);
-      }
+  let preScore = 0;
+  let preDimensions = {};
+  try {
+    const report = await evaluate3(type, filePath, { target: resolvedTarget });
+    if (report) {
+      preScore = report.aggregate;
+      preDimensions = report.dimensions;
     }
-    echoError("Fix validation errors before refining.");
-    return { preScore: 0, postScore: 0, delta: 0, fixesApplied: [], fixesSkipped: [] };
-  }
-  let preScore;
-  let preDimensions;
+  } catch {}
+  let content;
   try {
-    const report = await evaluate3(type, resolvedPath ?? nameOrPath, { target: resolvedTarget });
-    if (!report)
-      throw new Error("evaluate returned null in heuristic mode");
-    preScore = report.aggregate;
-    preDimensions = report.dimensions;
+    content = await Bun.file(filePath).text();
   } catch {
-    echoError("Cannot evaluate: file not found or unreadable.");
-    return { preScore: 0, postScore: 0, delta: 0, fixesApplied: [], fixesSkipped: [] };
+    echoError("Cannot read content file for editing.");
+    return { preScore, postScore: preScore, delta: 0, fixesApplied: [], fixesSkipped: [] };
   }
   const findings = [];
   for (const f of validation.findings) {
@@ -96029,26 +96360,23 @@ async function refine3(type, nameOrPath, opts) {
   }
   for (const [dimName, dimScore] of Object.entries(preDimensions)) {
     if (dimScore.score < 0.7 && dimScore.note?.trim()) {
-      const finding = {
-        severity: "warning",
-        field: dimName,
-        message: dimScore.note
-      };
-      findings.push({ finding, strategy: "suggest" });
+      findings.push({
+        finding: { severity: "warning", field: dimName, message: dimScore.note },
+        strategy: "suggest"
+      });
     }
   }
+  if (opts?.dryRun || type === "hook") {
+    if (type === "hook") {
+      echo("Hook refine is suggest-only (task 0061 decision C). Findings are recommendations; hooks.json is not modified. Hand-fix, then `hook validate`.");
+    }
+    return dryRunPreview(type, content, resolvedTarget, findings);
+  }
   if (findings.length === 0) {
     echo(`No issues found. Score: ${preScore.toFixed(2)}`);
     return { preScore, postScore: preScore, delta: 0, fixesApplied: [], fixesSkipped: [] };
   }
-  let content;
-  try {
-    content = await Bun.file(resolvedPath ?? nameOrPath).text();
-  } catch {
-    echoError("Cannot read content file for editing.");
-    return { preScore, postScore: preScore, delta: 0, fixesApplied: [], fixesSkipped: [] };
-  }
-  const backupPath = await backupFile(resolvedPath ?? nameOrPath);
+  const backupPath = await backupFile(filePath);
   let fixesApplied = [];
   let fixesSkipped = [];
   try {
@@ -96057,10 +96385,10 @@ async function refine3(type, nameOrPath, opts) {
       fixesApplied = result.fixesApplied;
       fixesSkipped = result.fixesSkipped;
       if (fixesApplied.length > 0) {
-        await Bun.write(resolvedPath ?? nameOrPath, result.content);
+        await Bun.write(filePath, result.content);
       }
     } else {
-      const result = await runInteractive(findings, content, resolvedPath ?? nameOrPath, backupPath);
+      const result = await runInteractive(findings, content, filePath, backupPath);
       fixesApplied = result.fixesApplied;
       fixesSkipped = result.fixesSkipped;
     }
@@ -96070,9 +96398,24 @@ async function refine3(type, nameOrPath, opts) {
     }
     throw err;
   }
+  if (!validation.valid) {
+    const revalidation = await validate(type, filePath, {
+      target: resolvedTarget,
+      strict: opts?.auto === true
+    });
+    if (!revalidation.valid) {
+      for (const f of revalidation.findings) {
+        if (f.severity === "error")
+          echoError(`[ERROR] ${f.field}: ${f.message}`);
+      }
+      echoError("Validation errors remain after structural fixes; refine aborted.");
+      return { preScore, postScore: preScore, delta: 0, fixesApplied, fixesSkipped };
+    }
+  }
   let postScore;
+  let postReport = null;
   try {
-    const postReport = await evaluate3(type, resolvedPath ?? nameOrPath, { target: resolvedTarget });
+    postReport = await evaluate3(type, filePath, { target: resolvedTarget });
     if (!postReport)
       throw new Error("evaluate returned null in heuristic mode");
     postScore = postReport.aggregate;
@@ -96080,6 +96423,14 @@ async function refine3(type, nameOrPath, opts) {
     echoError("Cannot re-evaluate after fixes.");
     return { preScore, postScore: preScore, delta: 0, fixesApplied, fixesSkipped };
   }
+  if (postScore < preScore) {
+    await restoreFromBackup(backupPath, filePath);
+    echo("Refine skipped: changes would have lowered the score; original restored.");
+    for (const f of fixesApplied)
+      fixesSkipped.push({ ...f, applied: false });
+    fixesApplied = [];
+    postScore = preScore;
+  }
   const delta = postScore - preScore;
   if (delta === 0 && preScore === postScore) {
     echo(`Score: ${preScore.toFixed(2)} (no change)`);
@@ -96087,12 +96438,20 @@ async function refine3(type, nameOrPath, opts) {
     const pctStr = preScore > 0 ? `, +${(delta / preScore * 100).toFixed(1)}%` : "";
     echo(`Score: ${preScore.toFixed(2)} \u2192 ${postScore.toFixed(2)} (${delta >= 0 ? "+" : ""}${delta.toFixed(2)}${pctStr})`);
   }
-  if (opts?.save) {
+  if (opts?.save && postReport) {
     try {
-      await evaluate3(type, resolvedPath ?? nameOrPath, {
-        target: resolvedTarget,
-        save: true,
-        operation: "refine"
+      const fileHash = hashContent(filePath);
+      const adapter = await openStore();
+      const dao = new EvaluationDao(adapter);
+      await dao.insertEvaluation({
+        content_type: type,
+        content_name: resolveContentName(filePath),
+        target_agent: resolvedTarget,
+        operation: "refine",
+        aggregate: postReport.aggregate,
+        dimensions: postReport.dimensions,
+        file_hash: fileHash,
+        scorer: "heuristic"
       });
     } catch {
       echoError("Warning: failed to save evaluation results.");
@@ -96100,6 +96459,48 @@ async function refine3(type, nameOrPath, opts) {
   }
   return { preScore, postScore, delta, fixesApplied, fixesSkipped };
 }
+function dryRunPreview(type, content, target, findings) {
+  let preScore = 0;
+  try {
+    preScore = evaluate(type, content, target).aggregate;
+  } catch {}
+  const autoFindings = findings.filter((f) => f.strategy === "auto-apply");
+  const projected = applyAutoFixes(autoFindings, content);
+  let projectedPost = preScore;
+  try {
+    projectedPost = evaluate(type, projected.content, target).aggregate;
+  } catch {}
+  echo("Dry run \u2014 no changes written.");
+  if (findings.length === 0) {
+    echo(`No issues found. Score: ${preScore.toFixed(2)}`);
+  } else {
+    const hookSuggestOnly2 = type === "hook";
+    for (const { finding, strategy } of findings) {
+      const effectiveStrategy = hookSuggestOnly2 ? "suggest" : strategy;
+      const tag = effectiveStrategy.toUpperCase();
+      const change = strategy === "auto-apply" ? generateAutoChange(finding, content) : null;
+      const proposed = !hookSuggestOnly2 && change && change.kind === "frontmatter" ? ` \u2192 would set ${change.key} = ${formatValue(change.value)}` : "";
+      echo(`[${tag}] ${finding.field}: ${finding.message}${proposed}`);
+    }
+    const delta = projectedPost - preScore;
+    const pctStr = preScore > 0 ? `, +${(delta / preScore * 100).toFixed(1)}%` : "";
+    echo(`Projected: ${preScore.toFixed(2)} \u2192 ${projectedPost.toFixed(2)} (${delta >= 0 ? "+" : ""}${delta.toFixed(2)}${pctStr})`);
+  }
+  const hookSuggestOnly = type === "hook";
+  const fixesSkipped = findings.map(({ finding, strategy }) => ({
+    severity: finding.severity,
+    field: finding.field,
+    message: finding.message,
+    strategy: hookSuggestOnly ? "suggest" : strategy,
+    applied: false
+  }));
+  return { preScore, postScore: projectedPost, delta: projectedPost - preScore, fixesApplied: [], fixesSkipped };
+}
+function formatValue(value) {
+  if (Array.isArray(value))
+    return value.length === 0 ? "[]" : `[${value.join(", ")}]`;
+  return String(value);
+}
 
 // src/operations/scaffold.ts
 init_src();
@@ -96111,10 +96512,16 @@ function addTargetOption(cmd) {
   return cmd.option("-t, --target <agent>", "Target agent platform", "claude");
 }
 function addScaffoldOptions(cmd) {
-  return cmd.option("-d, --description <text>", "Content description").option("-t, --target <agent>", "Target agent platform", "claude").option("-o, --output <dir>", "Output directory (default: cwd)").option("--force", "Overwrite existing file if present");
+  return cmd.option("-d, --description <text>", "Content description").option("-t, --target <agent>", "Target agent platform", "claude").option("-o, --output <dir>", "Output directory (default: cwd)").option("--template <tier>", "Template tier (e.g. minimal / standard / specialist)").option("--tools <list>", "Comma-separated tool names to pre-populate frontmatter").option("--force", "Overwrite existing file if present");
 }
 function addEvolveOptions(cmd) {
-  return cmd.option("-t, --target <agent>", "Target agent platform", "claude").option("--from <date>", "Analyze evaluations since date (ISO 8601)").option("--propose-only", "Generate proposal without applying").option("--accept <id>", "Accept a specific proposal by ID").option("--reject <id>", "Reject a specific proposal").option("--json", "Output machine-readable JSON (envelope-out with --propose-only)").option("--ingest <file>", "Agent-authored proposal JSON (ingest-in mode)").option("--margin <n>", "\u0394-margin gate threshold for accept (default 0.05)", Number.parseFloat, 0.05);
+  return cmd.option("-t, --target <agent>", "Target agent platform", "claude").option("--from <date>", "Analyze evaluations since date (ISO 8601)").option("--propose-only", "Generate proposal without applying").option("--accept <id>", "Accept a specific proposal by ID").option("--reject <id>", "Reject a specific proposal").option("--json", "Output machine-readable JSON (envelope-out with --propose-only)").option("--ingest <file>", "Agent-authored proposal JSON (ingest-in mode)").option("--margin <n>", "\u0394-margin gate threshold for accept (default 0.05)", Number.parseFloat, 0.05).option("--analyze", "Print analysis summary (trends, score, data sources) without writing a proposal").option("--history", "List applied proposal versions from the store").option("--rollback <id>", "Rollback to a prior version by proposal_id (requires --confirm)").option("--confirm", "Confirm a destructive operation (required for --rollback)");
+}
+function addHookEvolveOptions(cmd) {
+  return cmd.option("-t, --target <agent>", "Target agent platform", "claude").option("--from <date>", "Analyze evaluations since date (ISO 8601)").option("--analyze", "Print analysis summary (trends, score, data sources) \u2014 analyze-only, no apply").option("--json", "Output machine-readable JSON");
+}
+function addHookRefineOptions(cmd) {
+  return cmd.option("-t, --target <agent>", "Target agent platform", "claude").option("--dry-run", "Preview classified findings and recommendations without writing");
 }
 function addJsonOption(cmd) {
   return cmd.option("--json", "Output machine-readable JSON");
@@ -96131,6 +96538,9 @@ function addStrictOption(cmd) {
 function addAutoOption(cmd) {
   return cmd.option("--auto", "Apply low-risk fixes automatically");
 }
+function addDryRunOption(cmd) {
+  return cmd.option("--dry-run", "Preview classified fixes and projected delta without writing");
+}
 function resolveTarget(opts) {
   const raw = opts.target || "claude";
   if (!TARGETS.includes(raw)) {
@@ -96164,7 +96574,9 @@ async function agentScaffold(opts) {
     description: opts.description,
     target,
     output: opts.output,
-    force: opts.force
+    force: opts.force,
+    template: opts.template,
+    tools: opts.tools
   });
   echo(`Created: ${createdPath}`);
   return;
@@ -96195,7 +96607,7 @@ async function agentEvaluate(opts) {
 }
 async function agentRefine(opts) {
   const target = resolveTarget(opts);
-  await refine3("agent", opts.nameOrPath, { target, auto: opts.auto, save: opts.save });
+  await refine3("agent", opts.nameOrPath, { target, auto: opts.auto, save: opts.save, dryRun: opts.dryRun });
   return;
 }
 async function agentEvolve(opts) {
@@ -96208,7 +96620,11 @@ async function agentEvolve(opts) {
     rejectId: opts.reject,
     json: opts.json,
     ingest: opts.ingest,
-    margin: opts.margin
+    margin: opts.margin,
+    analyze: opts.analyze,
+    history: opts.history,
+    rollback: opts.rollback,
+    confirm: opts.confirm
   });
   return;
 }
@@ -96238,7 +96654,7 @@ function registerAgent(program2) {
   addEvaluateOptions(addSaveOption(addTargetOption(addJsonOption(cmd.command("evaluate <nameOrPath>").description("Evaluate agent quality (use --rubric --json for envelope, --ingest --save to persist scores)"))))).action(async (nameOrPath, opts) => {
     await handleAgentEvaluate({ nameOrPath, ...opts });
   });
-  addSaveOption(addTargetOption(addAutoOption(cmd.command("refine <nameOrPath>").description("Evaluate and auto-fix an agent")))).action(async (nameOrPath, opts) => {
+  addDryRunOption(addSaveOption(addTargetOption(addAutoOption(cmd.command("refine <nameOrPath>").description("Evaluate and auto-fix an agent"))))).action(async (nameOrPath, opts) => {
     await handleAgentRefine({ nameOrPath, ...opts });
   });
   addEvolveOptions(cmd.command("evolve <name>").description("Longitudinal improvement from evaluation history")).action(async (name, opts) => {
@@ -96254,7 +96670,9 @@ async function commandScaffold(opts) {
     description: opts.description,
     target,
     output: opts.output,
-    force: opts.force
+    force: opts.force,
+    template: opts.template,
+    tools: opts.tools
   });
   echo(`Created: ${createdPath}`);
   return;
@@ -96285,7 +96703,7 @@ async function commandEvaluate(opts) {
 }
 async function commandRefine(opts) {
   const target = resolveTarget(opts);
-  await refine3("command", opts.nameOrPath, { target, auto: opts.auto, save: opts.save });
+  await refine3("command", opts.nameOrPath, { target, auto: opts.auto, save: opts.save, dryRun: opts.dryRun });
   return;
 }
 async function commandEvolve(opts) {
@@ -96298,7 +96716,11 @@ async function commandEvolve(opts) {
     rejectId: opts.reject,
     json: opts.json,
     ingest: opts.ingest,
-    margin: opts.margin
+    margin: opts.margin,
+    analyze: opts.analyze,
+    history: opts.history,
+    rollback: opts.rollback,
+    confirm: opts.confirm
   });
   return;
 }
@@ -96328,7 +96750,7 @@ function registerCommand(program2) {
   addEvaluateOptions(addSaveOption(addTargetOption(addJsonOption(cmd.command("evaluate <nameOrPath>").description("Evaluate command quality (use --rubric --json for envelope, --ingest --save to persist scores)"))))).action(async (nameOrPath, opts) => {
     await handleCommandEvaluate({ nameOrPath, ...opts });
   });
-  addSaveOption(addTargetOption(addAutoOption(cmd.command("refine <nameOrPath>").description("Evaluate and auto-fix a command")))).action(async (nameOrPath, opts) => {
+  addDryRunOption(addSaveOption(addTargetOption(addAutoOption(cmd.command("refine <nameOrPath>").description("Evaluate and auto-fix a command"))))).action(async (nameOrPath, opts) => {
     await handleCommandRefine({ nameOrPath, ...opts });
   });
   addEvolveOptions(cmd.command("evolve <name>").description("Longitudinal improvement from evaluation history")).action(async (name, opts) => {
@@ -96747,15 +97169,6 @@ function copyDirectory(source, destination, options2 = {}) {
 }
 
 // src/commands/hook.ts
-async function scaffoldHook(name, opts) {
-  const target = resolveTarget(opts);
-  return scaffold("hook", name, {
-    description: opts.description,
-    target,
-    output: opts.output,
-    force: opts.force
-  });
-}
 async function validateHook(nameOrPath, opts) {
   const target = resolveTarget(opts);
   return validate("hook", nameOrPath, { target, strict: opts.strict });
@@ -96771,19 +97184,15 @@ async function evaluateHook2(nameOrPath, opts) {
 }
 async function refineHook(nameOrPath, opts) {
   const target = resolveTarget(opts);
-  return refine3("hook", nameOrPath, { target, auto: opts.auto, save: opts.save });
+  return refine3("hook", nameOrPath, { target, dryRun: opts.dryRun });
 }
 async function evolveHook(name, opts) {
   const target = resolveTarget(opts);
   return evolve("hook", name, {
     target,
     from: opts.from,
-    proposeOnly: opts.proposeOnly,
-    acceptId: opts.accept,
-    rejectId: opts.reject,
     json: opts.json,
-    ingest: opts.ingest,
-    margin: opts.margin
+    analyze: opts.analyze
   });
 }
 async function emitHook(name, opts) {
@@ -96811,11 +97220,6 @@ async function emitHook(name, opts) {
   }
   return { count: hookResult.count, message: hookResult.message };
 }
-async function hookScaffold(opts) {
-  const createdPath = await scaffoldHook(opts.name, opts);
-  echo(`Created: ${createdPath}`);
-  return;
-}
 async function hookValidate(opts) {
   const result = await validateHook(opts.nameOrPath, opts);
   const output2 = formatValidationResult(result, opts.json);
@@ -96848,19 +97252,16 @@ async function hookEmit(opts) {
 }
 function registerHook(program2) {
   const cmd = program2.command("hook").description("Manage hook definitions");
-  addScaffoldOptions(cmd.command("scaffold <name>").description("Create a new hook from template")).action(async (name, opts) => {
-    await runOperation(() => hookScaffold({ name, ...opts }));
-  });
   addStrictOption(addTargetOption(addJsonOption(cmd.command("validate <nameOrPath>").description("Validate a hook file")))).action(async (nameOrPath, opts) => {
     await runOperation(() => hookValidate({ nameOrPath, ...opts }));
   });
   addEvaluateOptions(addSaveOption(addTargetOption(addJsonOption(cmd.command("evaluate <nameOrPath>").description("Evaluate hook quality (use --rubric --json for envelope, --ingest --save to persist scores)"))))).action(async (nameOrPath, opts) => {
     await runOperation(() => hookEvaluate({ nameOrPath, ...opts }));
   });
-  addSaveOption(addTargetOption(addAutoOption(cmd.command("refine <nameOrPath>").description("Evaluate and auto-fix a hook")))).action(async (nameOrPath, opts) => {
+  addHookRefineOptions(cmd.command("refine <nameOrPath>").description("Surface hook quality findings as suggestions (suggest-only, no auto-apply)")).action(async (nameOrPath, opts) => {
     await runOperation(() => hookRefine({ nameOrPath, ...opts }));
   });
-  addEvolveOptions(cmd.command("evolve <name>").description("Longitudinal improvement from evaluation history")).action(async (name, opts) => {
+  addHookEvolveOptions(cmd.command("evolve <name>").description("Analyze hook evaluation trends (analyze-only, no apply)")).action(async (name, opts) => {
     await runOperation(() => hookEvolve({ name, ...opts }));
   });
   addTargetOption(cmd.command("emit <name>").description("Emit a hook definition to a single target agent (thin wrapper over the install hook path)")).option("--global", "Install to user-level global directory (default)", true).option("--dry-run", "Preview without writing files", false).action(async (name, opts) => {
@@ -96876,7 +97277,9 @@ async function magentScaffold(opts) {
     description: opts.description,
     target,
     output: opts.output,
-    force: opts.force
+    force: opts.force,
+    template: opts.template,
+    tools: opts.tools
   });
   echo(`Created: ${createdPath}`);
   return;
@@ -96907,7 +97310,7 @@ async function magentEvaluate(opts) {
 }
 async function magentRefine(opts) {
   const target = resolveTarget(opts);
-  await refine3("magent", opts.nameOrPath, { target, auto: opts.auto, save: opts.save });
+  await refine3("magent", opts.nameOrPath, { target, auto: opts.auto, save: opts.save, dryRun: opts.dryRun });
   return;
 }
 async function magentEvolve(opts) {
@@ -96920,7 +97323,11 @@ async function magentEvolve(opts) {
     rejectId: opts.reject,
     json: opts.json,
     ingest: opts.ingest,
-    margin: opts.margin
+    margin: opts.margin,
+    analyze: opts.analyze,
+    history: opts.history,
+    rollback: opts.rollback,
+    confirm: opts.confirm
   });
   return;
 }
@@ -96950,7 +97357,7 @@ function registerMagent(program2) {
   addEvaluateOptions(addSaveOption(addTargetOption(addJsonOption(cmd.command("evaluate <nameOrPath>").description("Evaluate magent quality (use --rubric --json for envelope, --ingest --save to persist scores)"))))).action(async (nameOrPath, opts) => {
     await handleMagentEvaluate({ nameOrPath, ...opts });
   });
-  addSaveOption(addTargetOption(addAutoOption(cmd.command("refine <nameOrPath>").description("Evaluate and auto-fix a magent")))).action(async (nameOrPath, opts) => {
+  addDryRunOption(addSaveOption(addTargetOption(addAutoOption(cmd.command("refine <nameOrPath>").description("Evaluate and auto-fix a magent"))))).action(async (nameOrPath, opts) => {
     await handleMagentRefine({ nameOrPath, ...opts });
   });
   addEvolveOptions(cmd.command("evolve <name>").description("Longitudinal improvement from evaluation history")).action(async (name, opts) => {
@@ -97020,7 +97427,9 @@ async function skillScaffold(opts) {
     description: opts.description,
     target,
     output: opts.output,
-    force: opts.force
+    force: opts.force,
+    template: opts.template,
+    tools: opts.tools
   });
   echo(`Created: ${createdPath}`);
   return;
@@ -97052,7 +97461,7 @@ async function skillEvaluate(opts) {
 }
 async function skillRefine(opts) {
   const target = resolveTarget(opts);
-  await refine3("skill", opts.nameOrPath, { target, auto: opts.auto, save: opts.save });
+  await refine3("skill", opts.nameOrPath, { target, auto: opts.auto, save: opts.save, dryRun: opts.dryRun });
   return;
 }
 async function skillEvolve(opts) {
@@ -97065,7 +97474,11 @@ async function skillEvolve(opts) {
     rejectId: opts.reject,
     json: opts.json,
     ingest: opts.ingest,
-    margin: opts.margin
+    margin: opts.margin,
+    analyze: opts.analyze,
+    history: opts.history,
+    rollback: opts.rollback,
+    confirm: opts.confirm
   });
   return;
 }
@@ -97117,7 +97530,7 @@ function registerSkill(program2) {
   addScaffoldOptions(cmd.command("scaffold <name>").description("Create a new skill from template")).action(handleSkillScaffold);
   addStrictOption(addTargetOption(addJsonOption(cmd.command("validate <nameOrPath>").description("Validate a skill file")))).action(handleSkillValidate);
   addEvaluateOptions(addSaveOption(addTargetOption(addJsonOption(cmd.command("evaluate <nameOrPath>").description("Evaluate skill quality (use --rubric --json for envelope, --ingest --save to persist scores)").option("--history", "Show prior evaluation rows from the store"))))).action(handleSkillEvaluate);
-  addSaveOption(addTargetOption(addAutoOption(cmd.command("refine <nameOrPath>").description("Evaluate and auto-fix a skill")))).action(handleSkillRefine);
+  addDryRunOption(addSaveOption(addTargetOption(addAutoOption(cmd.command("refine <nameOrPath>").description("Evaluate and auto-fix a skill"))))).action(handleSkillRefine);
   addEvolveOptions(cmd.command("evolve <name>").description("Longitudinal improvement from evaluation history")).action(handleSkillEvolve);
   cmd.command("package <name>").description("Package a skill for distribution").option("-o, --output <dir>", "Output directory (default: cwd)").option("--include-companions", "Include companion configs (metadata.openclaw, agents/)").action(handleSkillPackage);
   cmd.command("migrate <sources...>").description("Merge/migrate skills into a destination").option("--refine", "Route through the generation seam (F023) for content refinement").option("--ingest <file>", "Agent-authored proposal JSON (apply through the double-loop gate)").option("-t, --target <agent>", "Target agent platform", "claude").option("--margin <n>", "\u0394-margin gate threshold (default 0.05)", Number.parseFloat, 0.05).action(handleSkillMigrate);