@gobing-ai/superskill 0.1.7 → 0.2.0

package/dist/index.js

@@ -9317,7 +9317,7 @@ function hashContent(filePath) {
 var init_hash = () => {};
 
 // ../../packages/core/src/content/identity.ts
-import { existsSync } from "fs";
+import { existsSync, statSync } from "fs";
 import { basename, dirname, extname, join } from "path";
 import { cwd } from "process";
 function resolveContentName(path) {
@@ -9333,10 +9333,26 @@ function resolveContentName(path) {
 }
 function resolveContentPath(type, name, opts) {
   if (name.includes("/") || name.includes("\\")) {
-    if (existsSync(name))
-      return name;
+    if (existsSync(name)) {
+      const st = statSync(name);
+      if (st.isDirectory()) {
+        const skillMd = join(name, "SKILL.md");
+        if (existsSync(skillMd))
+          return skillMd;
+      } else {
+        return name;
+      }
+    }
   }
   const base = opts?.baseDir ?? cwd();
+  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;
@@ -9355,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
@@ -9710,7 +9731,7 @@ var init_adapt_subagent = __esm(() => {
 });
 
 // ../../packages/core/src/mapper.ts
-import { existsSync as existsSync3, mkdirSync, readdirSync, readFileSync as readFileSync2, statSync, writeFileSync } from "fs";
+import { existsSync as existsSync3, mkdirSync, readdirSync, readFileSync as readFileSync2, statSync as statSync2, writeFileSync } from "fs";
 import { join as join3 } from "path";
 function mapPluginToRulesync(pluginPath, pluginName, outputDir) {
   assertSafePathSegment(pluginName, "plugin name");
@@ -9798,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) : {};
@@ -9833,7 +9849,7 @@ function copyAndRewriteDirectory(source, destination, pluginName) {
   for (const entry of readdirSync(source)) {
     const srcPath = join3(source, entry);
     const destPath = join3(destination, entry);
-    if (statSync(srcPath).isDirectory()) {
+    if (statSync2(srcPath).isDirectory()) {
       copyAndRewriteDirectory(srcPath, destPath, pluginName);
     } else {
       const content = readFileSync2(srcPath, "utf-8");
@@ -9842,6 +9858,7 @@ function copyAndRewriteDirectory(source, destination, pluginName) {
   }
 }
 var init_mapper = __esm(() => {
+  init_identity();
   init_adapt_command();
   init_adapt_subagent();
   init_rewrite_references();
@@ -13814,7 +13831,7 @@ var init_zod = __esm(() => {
 });
 
 // ../../packages/core/src/marketplace.ts
-import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "fs";
 import { join as join4, resolve } from "path";
 function resolvePlugin(marketplacePath, pluginName) {
   let manifestPath = null;
@@ -13861,8 +13878,19 @@ function resolvePlugin(marketplacePath, pluginName) {
   const marketplaceRoot = resolve(manifestPath, "..", "..");
   const pluginRootBase = manifest.metadata?.pluginRoot ?? "";
   const pluginRoot = resolve(marketplaceRoot, pluginRootBase, source);
-  if (!existsSync4(join4(pluginRoot, "plugin.json"))) {
-    throw new Error(`plugin.json not found in resolved plugin root: ${pluginRoot}`);
+  let dirents;
+  try {
+    dirents = readdirSync2(pluginRoot);
+  } catch {
+    throw new Error(`Plugin root not found: ${pluginRoot}`);
+  }
+  const hasSkills = dirents.includes("skills");
+  const hasCommands = dirents.includes("commands");
+  const hasAgents = dirents.includes("agents");
+  const hasHooksDir = dirents.includes("hooks");
+  const hasHooksFile = dirents.includes("hooks.json");
+  if (!(hasSkills || hasCommands || hasAgents || hasHooksDir || hasHooksFile)) {
+    throw new Error(`No recognizable plugin content (skills/, commands/, agents/, hooks/, hooks.json) in: ${pluginRoot}`);
   }
   return { pluginRoot, marketplaceRoot, source };
 }
@@ -14013,7 +14041,7 @@ var init_migrate = __esm(() => {
 });
 
 // ../../packages/core/src/operations/package.ts
-import { cpSync, existsSync as existsSync6, mkdirSync as mkdirSync3, statSync as statSync2 } from "fs";
+import { cpSync, existsSync as existsSync6, mkdirSync as mkdirSync3, statSync as statSync3 } from "fs";
 import { basename as basename2, dirname as dirname3, join as join5 } from "path";
 import { cwd as cwd3 } from "process";
 function resolveSkillDir(name) {
@@ -14021,7 +14049,7 @@ function resolveSkillDir(name) {
   if (!skillPath) {
     throw Object.assign(new Error(`Skill not found: ${name}`), { code: "ENOENT" });
   }
-  const dir = statSync2(skillPath).isDirectory() ? skillPath : dirname3(skillPath);
+  const dir = statSync3(skillPath).isDirectory() ? skillPath : dirname3(skillPath);
   return { dir, name: basename2(dir) };
 }
 function copyDirIfExists(src, dest) {
@@ -14062,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 resolveTemplate(type) {
+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, 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) {
@@ -14122,10 +14211,10 @@ var init_types2 = __esm(() => {
   VAGUE_KEYWORDS = ["maybe", "perhaps", "might", "could be", "probably"];
   REQUIRED_FIELDS = {
     skill: ["name", "description"],
-    command: ["name", "description"],
+    command: ["description"],
     agent: ["name", "description", "model", "tools"],
-    hook: ["name", "description", "event"],
-    magent: ["name", "description"]
+    hook: [],
+    magent: []
   };
 });
 
@@ -14224,89 +14313,180 @@ var init_heuristics = __esm(() => {
 });
 
 // ../../packages/core/src/quality/hook.ts
-function scoreCorrectness(data) {
-  const raw = data.event;
-  let base;
-  let note;
-  if (typeof raw === "string" && raw.trim().length > 0) {
-    const event = raw.trim();
-    if (KNOWN_HOOK_EVENTS.includes(event)) {
-      base = 1;
-      note = `Valid event: ${event}`;
-    } else {
-      base = 0.5;
-      note = `Unknown event: ${event}`;
+function parseHookEntries(raw) {
+  if (typeof raw !== "object" || raw === null)
+    return null;
+  const data = raw;
+  const hooks = data.hooks;
+  if (typeof hooks !== "object" || hooks === null)
+    return null;
+  const entries = [];
+  for (const [event, matcherBlocks] of Object.entries(hooks)) {
+    if (!Array.isArray(matcherBlocks))
+      continue;
+    for (const block of matcherBlocks) {
+      if (typeof block !== "object" || block === null)
+        continue;
+      const subHooks = block.hooks;
+      if (!Array.isArray(subHooks))
+        continue;
+      for (const h of subHooks) {
+        if (typeof h !== "object" || h === null)
+          continue;
+        entries.push({
+          event,
+          matcher: typeof block.matcher === "string" ? block.matcher : "",
+          command: typeof h.command === "string" ? h.command : "",
+          type: typeof h.type === "string" ? h.type : "",
+          timeout: typeof h.timeout === "number" ? h.timeout : undefined
+        });
+      }
     }
-  } else {
-    base = 0;
-    note = "Missing event field";
   }
-  if (data.enabled === true) {
-    base = clamp(base + 0.1);
-  }
-  return { score: clamp(base), note };
-}
-function scoreEventCoverage(data, body) {
-  const eventName = typeof data.event === "string" ? data.event.trim() : "";
-  const mentionsEventName = eventName.length > 0 && body.toLowerCase().includes(eventName.toLowerCase()) ? 1 : 0;
-  const density = keywordDensity(body, ["event", "intercept", "trigger", "when", "condition", "match"]);
-  const score = 0.5 * mentionsEventName + 0.5 * density;
-  const note = score >= 0.5 ? "Event coverage described" : "Minimal event description";
-  return { score: clamp(score), note };
+  return entries.length > 0 ? entries : null;
 }
-function scoreSafety(body) {
-  const density = keywordDensity(body, [
-    "safety",
-    "secure",
-    "gated",
-    "approval",
-    "explicit",
-    "dangerous",
-    "destructive",
-    "block"
-  ]);
-  const note = density >= 0.2 ? "Includes safety considerations" : "No safety gates described";
-  return { score: clamp(density), note };
-}
-function scorePatternMatchQuality(body) {
-  const hasSpecificGlob = /\*\.[a-z]+\b/i.test(body);
-  const patternDensity = keywordDensity(body, ["match", "pattern", "regex", "glob"]);
-  let score;
-  let note;
-  if (hasSpecificGlob) {
-    score = 0.9;
-    note = "Specific match patterns";
-  } else if (patternDensity > 0) {
-    score = 0.3;
-    note = "Broad/unspecific patterns";
-  } else {
-    score = 0;
-    note = "No match patterns";
+function scoreCorrectness(entries) {
+  let valid = 0;
+  for (const e of entries) {
+    if (e.type === "command" && e.command.length > 0 && e.matcher.length > 0)
+      valid++;
   }
+  const score = entries.length > 0 ? clamp(valid / entries.length) : 0;
+  const note = `${valid}/${entries.length} entries valid`;
   return { score, note };
 }
+function scoreEventCoverage(entries) {
+  const events = new Set(entries.map((e) => e.event));
+  const covered = KNOWN_HOOK_EVENTS.filter((e) => events.has(e)).length;
+  const score = clamp(Math.min(events.size / 3, 1));
+  const note = `${covered} of ${KNOWN_HOOK_EVENTS.length} known events covered (${events.size} total)`;
+  return { score, note };
+}
+function scoreSafety(entries) {
+  const dangerousPatterns = [
+    { re: /rm\s+-rf/i, label: "rm -rf" },
+    { re: /\b(?:curl|wget|fetch)\b.*\|\s*(?:ba|z)?sh\b/i, label: "download pipe to shell" },
+    { re: /--no-verify/i, label: "--no-verify bypass" },
+    { re: /\beval\b/i, label: "eval" },
+    { re: /sudo\b/i, label: "sudo" },
+    { re: /chmod\s+777/i, label: "chmod 777" },
+    { re: /\$\([^)]*\)/, label: "unquoted command substitution" },
+    { re: /`[^`]+`/, label: "backtick execution" }
+  ];
+  const findings = [];
+  let dangerous = 0;
+  for (const e of entries) {
+    for (const { re, label } of dangerousPatterns) {
+      if (re.test(e.command)) {
+        dangerous++;
+        findings.push(`[${e.event}] ${label}: ${e.command.slice(0, 60)}`);
+      }
+    }
+  }
+  const base = entries.length > 0 ? 1 - dangerous / (entries.length * 2) : 0;
+  const score = clamp(Math.max(base, 0.1));
+  const note = dangerous === 0 ? "No dangerous command patterns found" : `${dangerous} dangerous pattern(s) found`;
+  const recs = dangerous > 0 ? ["Replace dangerous patterns with safe alternatives; add explicit approval gates"] : undefined;
+  return { score, note, findings: findings.length > 0 ? findings : undefined, recommendations: recs };
+}
+function scorePatternMatchQuality(entries) {
+  let specificMatchers = 0;
+  let hasTimeout = 0;
+  let portable = 0;
+  for (const e of entries) {
+    if (e.matcher !== "*" && e.matcher.length > 0)
+      specificMatchers++;
+    if (e.timeout !== undefined && e.timeout > 0)
+      hasTimeout++;
+    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;
+  const timeoutScore = hasTimeout / n;
+  const portableScore = portable / n;
+  const score = clamp(0.3 * matcherScore + 0.4 * timeoutScore + 0.3 * portableScore);
+  const noteParts = [];
+  if (specificMatchers < n)
+    noteParts.push(`${n - specificMatchers} broad matcher(s)`);
+  if (hasTimeout < n)
+    noteParts.push(`${n - hasTimeout} missing timeout`);
+  if (portable < n)
+    noteParts.push(`${n - portable} non-portable path(s)`);
+  const findings = noteParts.length > 0 ? noteParts.map((p) => p) : undefined;
+  const recs = noteParts.length > 0 ? [
+    "Use specific matchers instead of *; add timeout to every hook; use CLAUDE_PLUGIN_ROOT env var for paths"
+  ] : undefined;
+  return {
+    score,
+    note: noteParts.length > 0 ? noteParts.join("; ") : "All entries specific, timed, and portable",
+    findings,
+    recommendations: recs
+  };
+}
 function evaluateHook(content, target) {
-  const parsed = parseFrontmatterSafe(content);
-  const data = parsed ?? {};
-  const body = extractBody(content);
-  const isParseError = parsed === null;
-  const dimensions = (() => {
-    if (isParseError) {
-      const errNote = parseErrorNote(content, "Frontmatter parse error");
+  const isJson = target.endsWith(".json") || /^\s*\{/.test(content);
+  if (isJson) {
+    let parsed;
+    try {
+      parsed = JSON.parse(content);
+    } catch {
       return {
-        correctness: { score: 0.1, note: errNote },
-        "event-coverage": { score: 0, note: errNote },
-        safety: { score: 0, note: errNote },
-        "pattern-match-quality": { score: 0, note: errNote }
+        type: "hook",
+        target,
+        content: "",
+        aggregate: 0,
+        dimensions: {
+          correctness: { score: 0, note: "Invalid JSON: parse error" },
+          "event-coverage": { score: 0, note: "Invalid JSON: parse error" },
+          safety: { score: 0, note: "Invalid JSON: parse error" },
+          "pattern-match-quality": { score: 0, note: "Invalid JSON: parse error" }
+        }
       };
     }
+    const entries = parseHookEntries(parsed);
+    if (!entries || entries.length === 0) {
+      return {
+        type: "hook",
+        target,
+        content: "",
+        aggregate: 0,
+        dimensions: {
+          correctness: { score: 0, note: "No hook entries found in JSON" },
+          "event-coverage": { score: 0, note: "No hook entries found in JSON" },
+          safety: { score: 0, note: "No hook entries found in JSON" },
+          "pattern-match-quality": { score: 0, note: "No hook entries found in JSON" }
+        }
+      };
+    }
+    const dimensions2 = {
+      correctness: scoreCorrectness(entries),
+      "event-coverage": scoreEventCoverage(entries),
+      safety: scoreSafety(entries),
+      "pattern-match-quality": scorePatternMatchQuality(entries)
+    };
     return {
-      correctness: scoreCorrectness(data),
-      "event-coverage": scoreEventCoverage(data, body),
-      safety: scoreSafety(body),
-      "pattern-match-quality": scorePatternMatchQuality(body)
+      type: "hook",
+      target,
+      content: "",
+      aggregate: computeAggregate(dimensions2),
+      dimensions: dimensions2
     };
-  })();
+  }
+  const dimensions = {
+    correctness: { score: 0, note: "Markdown hook definitions not supported; use hooks.json" },
+    "event-coverage": { score: 0, note: "Markdown hook definitions not supported; use hooks.json" },
+    safety: { score: 0, note: "Markdown hook definitions not supported; use hooks.json" },
+    "pattern-match-quality": { score: 0, note: "Markdown hook definitions not supported; use hooks.json" }
+  };
   return {
     type: "hook",
     target,
@@ -14333,8 +14513,34 @@ var init_hook = __esm(() => {
 });
 
 // ../../packages/core/src/operations/validate.ts
-import { existsSync as existsSync8, statSync as statSync3 } from "fs";
-import { dirname as dirname4 } from "path";
+import { existsSync as existsSync8, statSync as statSync4 } from "fs";
+import { dirname as dirname4, join as join7 } from "path";
+function checkBodyLinks(body, baseDir) {
+  const findings = [];
+  const linkRe = /\[([^\]]*)\]\(([^)]+)\)/g;
+  for (const match of body.matchAll(linkRe)) {
+    const linkText = match[1];
+    const target = match[2];
+    if (!target)
+      continue;
+    if (/^#/.test(target))
+      continue;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(target))
+      continue;
+    const filePart = target.split(/[#?]/)[0];
+    if (!filePart)
+      continue;
+    const resolved = join7(baseDir, filePart);
+    if (!existsSync8(resolved)) {
+      findings.push({
+        severity: "warning",
+        field: "_links",
+        message: `Broken body link: [${linkText}](${target}) \u2192 target not found: ${resolved}`
+      });
+    }
+  }
+  return findings;
+}
 async function validate(type, nameOrPath, opts) {
   const resolvedPath = resolveContentPath(type, nameOrPath);
   if (!resolvedPath) {
@@ -14345,7 +14551,7 @@ async function validate(type, nameOrPath, opts) {
   }
   let stat;
   try {
-    stat = statSync3(resolvedPath);
+    stat = statSync4(resolvedPath);
   } catch {
     return sentinelResult(`File not found: ${resolvedPath}`);
   }
@@ -14365,19 +14571,39 @@ async function validate(type, nameOrPath, opts) {
     return sentinelResult(`Cannot read file: ${resolvedPath}`);
   }
   const baseDir = dirname4(resolvedPath);
-  return _validateContent(type, content, {
+  const result = _validateContent(type, content, {
     ...opts,
     referenceChecker: (refType, refName) => resolveContentPath(refType, refName, { baseDir }) !== null
   });
+  const bodyStart = content.indexOf(`
+---
+`);
+  const body = bodyStart >= 0 ? content.slice(bodyStart + 5) : content;
+  const linkFindings = checkBodyLinks(body, baseDir);
+  result.findings.push(...linkFindings);
+  return result;
 }
 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}` });
@@ -14523,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) {
@@ -14560,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) {
@@ -14578,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();
@@ -14619,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
@@ -32208,7 +32451,7 @@ var init_config = __esm(() => {
 });
 
 // ../../node_modules/.bun/@gobing-ai+ts-runtime@0.3.21/node_modules/@gobing-ai/ts-runtime/dist/file-system-node.js
-import { appendFileSync, cpSync as cpSync2, createWriteStream, existsSync as existsSync9, mkdirSync as mkdirSync5, readdirSync as readdirSync2, readFileSync as readFileSync6, renameSync, rmSync as rmSync2, statSync as statSync4, writeFileSync as writeFileSync4 } from "fs";
+import { appendFileSync, cpSync as cpSync2, createWriteStream, existsSync as existsSync9, mkdirSync as mkdirSync5, readdirSync as readdirSync3, readFileSync as readFileSync6, renameSync, rmSync as rmSync2, statSync as statSync5, writeFileSync as writeFileSync4 } from "fs";
 import { dirname as dirname5, resolve as resolvePath } from "path";
 function createNodeFileSystem(root) {
   const projectRoot = root ?? findProjectRoot(process.cwd());
@@ -32228,7 +32471,7 @@ function createNodeFileSystem(root) {
     ensureDir: (path) => {
       mkdirSync5(path, { recursive: true });
     },
-    readDir: (path) => readdirSync2(path),
+    readDir: (path) => readdirSync3(path),
     deleteFile: (path) => {
       rmSync2(path, { recursive: true, force: true });
     },
@@ -32244,7 +32487,7 @@ function createNodeFileSystem(root) {
     },
     stat: (path) => {
       try {
-        const s = statSync4(path);
+        const s = statSync5(path);
         return {
           isFile: () => s.isFile(),
           isDirectory: () => s.isDirectory(),
@@ -34872,7 +35115,7 @@ var init_encoding_option = __esm(() => {
 });
 
 // ../../node_modules/.bun/execa@9.6.1/node_modules/execa/lib/arguments/cwd.js
-import { statSync as statSync5 } from "fs";
+import { statSync as statSync6 } from "fs";
 import path4 from "path";
 import process6 from "process";
 var normalizeCwd = (cwd5 = getDefaultCwd()) => {
@@ -34892,7 +35135,7 @@ ${error51.message}`;
   }
   let cwdStat;
   try {
-    cwdStat = statSync5(cwd5);
+    cwdStat = statSync6(cwd5);
   } catch (error51) {
     return `The "cwd" option is invalid: ${cwd5}.
 ${error51.message}
@@ -40376,8 +40619,14 @@ function scoreCompleteness(data) {
   const required2 = REQUIRED_FIELDS.agent;
   const score = scorePresence(fieldsPresent, required2);
   const missing = required2.filter((f) => !fieldsPresent.includes(f));
-  const note = missing.length > 0 ? `Missing: ${missing.join(", ")}` : "All required fields present";
-  return { score: clamp(score), note };
+  const findings = missing.length > 0 ? [`Missing required fields: ${missing.join(", ")}`] : undefined;
+  const recs = missing.length > 0 ? ["Add the missing frontmatter fields"] : undefined;
+  return {
+    score: clamp(score),
+    note: missing.length > 0 ? `Missing: ${missing.join(", ")}` : "All required fields present",
+    findings,
+    recommendations: recs
+  };
 }
 function scoreRoleClarity(body) {
   const patterns = [/you are/i, /role/i, /specialist/i, /persona/i];
@@ -40404,7 +40653,9 @@ function scoreRoleClarity(body) {
   }
   const score = specificity ? clamp(base2 + 0.2) : base2;
   const note = matchCount >= 2 ? "Clear role defined" : matchCount === 1 ? "Role definition vague/generic" : "No role definition found";
-  return { score, note };
+  const findings = matchCount < 2 ? ["Role definition is vague, generic, or absent"] : undefined;
+  const recs = matchCount === 0 ? ['Add a role statement (e.g. "You are a ... specialist")'] : matchCount === 1 ? ["Add more role signals (specialist, persona, role scope)"] : undefined;
+  return { score, note, findings, recommendations: recs };
 }
 function scoreToolSelection(data) {
   const tools = data.tools;
@@ -40417,7 +40668,9 @@ function scoreToolSelection(data) {
   } else {
     score = 0.1;
   }
-  return { score, note: `${count2} tools selected` };
+  const findings = count2 < 3 ? [`Only ${count2} tool(s) selected \u2014 3+ recommended`] : undefined;
+  const recs = count2 === 0 ? ["Add at least 3 tools to the agent frontmatter"] : count2 < 3 ? ["Add more tools to cover the agent workflow"] : undefined;
+  return { score, note: `${count2} tools selected`, findings, recommendations: recs };
 }
 function scoreSkillLinkage(body) {
   const patterns = [/skill:/i, /skills:/i, /skill/i];
@@ -40437,7 +40690,13 @@ function scoreSkillLinkage(body) {
     score = 0;
     note = "No skill references";
   }
-  return { score, note };
+  let findings;
+  let recs;
+  if (score < 1) {
+    findings = ["Skill linkage is weak or missing"];
+    recs = score === 0.5 ? ["Use structured skill references (skill: or skills:) in the agent body"] : ["Add skill references to the agent body for delegated workflows"];
+  }
+  return { score, note, findings, recommendations: recs };
 }
 function scoreModelFit(data) {
   const model = data.model;
@@ -40460,7 +40719,16 @@ function scoreModelFit(data) {
     score = 0;
     note = "Model: missing";
   }
-  return { score, note };
+  let findings;
+  let recs;
+  if (score < 0.5) {
+    findings = ["Model field is missing or unrecognized"];
+    recs = ["Specify a valid model (e.g. inherit, claude-sonnet-4, claude-opus-4)"];
+  } else if (score === 0.5) {
+    findings = ["Model name appears ambiguous"];
+    recs = ["Use a recognized model alias (inherit, sonnet, opus, haiku) or well-formed name (claude-sonnet-4)"];
+  }
+  return { score, note, findings, recommendations: recs };
 }
 function evaluateAgent(content, target) {
   const data = parseFrontmatterSafe(content) ?? {};
@@ -40489,53 +40757,99 @@ var init_agent = __esm(() => {
 function scoreCompleteness2(data) {
   const fieldsPresent = Object.keys(data);
   const base2 = scorePresence(fieldsPresent, REQUIRED_FIELDS.command);
-  const argsFactor = Array.isArray(data.arguments) ? 1 : 0;
-  const score = clamp(base2 * (0.5 + 0.5 * argsFactor));
+  const hasArgHint = typeof data["argument-hint"] === "string" && data["argument-hint"].length > 0;
+  const hasAllowedTools = Array.isArray(data["allowed-tools"]) && data["allowed-tools"].length > 0;
+  const optBonus = (hasArgHint ? 0.1 : 0) + (hasAllowedTools ? 0.1 : 0);
+  const score = clamp(Math.min(base2 + optBonus, 1));
   const missing = [];
   for (const f of REQUIRED_FIELDS.command) {
     if (!(f in data))
       missing.push(f);
   }
   const note = missing.length > 0 ? `Missing fields: ${missing.join(", ")}` : "All required fields present";
-  return { score, note };
+  const findings = missing.length > 0 ? [`Missing required fields: ${missing.join(", ")}`] : undefined;
+  const recs = missing.includes("description") ? ["Add a description field to the command frontmatter"] : undefined;
+  return { score, note, findings, recommendations: recs };
 }
 function scoreClarity(body) {
   return scoreClarityFromDensities(body);
 }
 function scoreArgumentHints(data) {
-  const args = data.arguments;
-  if (!Array.isArray(args)) {
-    return { score: 0, note: "No arguments array found" };
-  }
-  if (args.length === 0) {
-    return { score: 0, note: "0/0 arguments have hints" };
+  const hasKey = "argument-hint" in data;
+  const argHint = data["argument-hint"];
+  if (!hasKey) {
+    return { score: 1, note: "No argument-hint (command takes no parameters)" };
   }
-  let withHints = 0;
-  for (const arg of args) {
-    if (typeof arg === "object" && arg !== null && "name" in arg && "description" in arg) {
-      withHints++;
-    }
+  if (typeof argHint !== "string" || argHint.trim().length === 0) {
+    return {
+      score: 0.4,
+      note: "Argument-hint declared but empty",
+      findings: ["Argument-hint is declared but empty"],
+      recommendations: [
+        "Add a descriptive argument-hint string with placeholder syntax, or remove the empty field"
+      ]
+    };
   }
-  const score = clamp(withHints / args.length);
-  return { score, note: `${withHints}/${args.length} arguments have hints` };
-}
-function scoreToolReferences(body) {
+  const hint = argHint.trim();
+  const hasPositional = /<[a-z][^>]*>/i.test(hint);
+  const hasFlags = /\[?--[a-z][^\s\]]*\]?/i.test(hint);
+  let score;
+  let note;
+  if (hasPositional && hasFlags) {
+    score = 1;
+    note = "Rich argument-hint with positional args and flags";
+  } else if (hasPositional || hasFlags) {
+    score = 0.75;
+    note = "Argument-hint present but could be more descriptive";
+  } else {
+    score = 0.4;
+    note = "Argument-hint is vague or placeholder-only";
+  }
+  let findings;
+  let recs;
+  if (score < 1 && score > 0.5) {
+    findings = ["Argument-hint could be more descriptive"];
+    recs = ["Add both positional args (<name>) and flags ([--flag <value>]) to the argument-hint"];
+  } else if (score <= 0.5) {
+    findings = ["Argument-hint is vague or missing for a parameterized command"];
+    recs = ["Add a descriptive argument-hint string with placeholder syntax"];
+  }
+  return { score, note, findings, recommendations: recs };
+}
+function scoreToolReferences(body, data) {
+  const allowedTools = data["allowed-tools"];
+  const toolCount = Array.isArray(allowedTools) ? allowedTools.length : 0;
   const structuredCount = (body.match(/\btools?:/gi) ?? []).length;
   const backtickCount = (body.match(/`[a-z][a-z0-9_-]*`/g) ?? []).length;
-  const weightedCount = structuredCount + Math.min(backtickCount, 1);
+  const bodyWeighted = structuredCount + Math.min(backtickCount, 1);
   let score;
   let note;
-  if (structuredCount >= 1 || weightedCount >= 2) {
+  if (toolCount >= 5) {
     score = 1;
-    note = "Uses tool references";
-  } else if (weightedCount === 1) {
-    score = 0.6;
+    note = `${toolCount} allowed-tools declared`;
+  } else if (toolCount >= 3) {
+    score = 0.9;
+    note = `${toolCount} allowed-tools declared`;
+  } else if (toolCount >= 1 || structuredCount >= 1 || bodyWeighted >= 2) {
+    score = 0.7;
+    note = toolCount > 0 ? `${toolCount} allowed-tools declared` : "Uses tool references";
+  } else if (bodyWeighted === 1) {
+    score = 0.4;
     note = "Limited tool references";
   } else {
     score = 0.1;
     note = "No tool references found";
   }
-  return { score, note };
+  let findings;
+  let recs;
+  if (score < 0.5) {
+    findings = ["No tool references found"];
+    recs = ["Add allowed-tools to frontmatter or reference tools in the command body"];
+  } else if (score < 0.8) {
+    findings = ["Limited tool references"];
+    recs = ["Declare all required tools in the allowed-tools frontmatter array"];
+  }
+  return { score, note, findings, recommendations: recs };
 }
 function scoreSlashSyntax(body, target) {
   const slashPattern = /\/[a-z][a-z-]*/g;
@@ -40562,7 +40876,7 @@ function evaluateCommand(content, target) {
     completeness: scoreCompleteness2(data),
     clarity: scoreClarity(body),
     "argument-hints": scoreArgumentHints(data),
-    "tool-references": scoreToolReferences(body),
+    "tool-references": scoreToolReferences(body, data),
     "slash-syntax": scoreSlashSyntax(body, target)
   };
   return {
@@ -40581,16 +40895,21 @@ var init_command3 = __esm(() => {
 // ../../packages/core/src/quality/magent.ts
 function scoreCompleteness3(body) {
   let found = 0;
-  for (const re of MAGENT_SECTIONS) {
+  for (const { re } of MAGENT_SECTIONS) {
     if (re.test(body))
       found++;
   }
+  const score = clamp(found / MAGENT_SECTIONS.length);
+  const findings = found < MAGENT_SECTIONS.length / 2 ? ["Config is missing key governance sections"] : undefined;
+  const recs = found < MAGENT_SECTIONS.length ? ["Add more governance sections (commands, verification, conventions, safety, docs)"] : undefined;
   return {
-    score: clamp(found / MAGENT_SECTIONS.length),
-    note: `${found}/${MAGENT_SECTIONS.length} sections present`
+    score,
+    note: `${found}/${MAGENT_SECTIONS.length} governance sections present`,
+    findings,
+    recommendations: recs
   };
 }
-function scorePlatformCoverage(data) {
+function scorePlatformCoverage(data, body) {
   const raw = data.platforms;
   let platforms = [];
   if (Array.isArray(raw)) {
@@ -40598,8 +40917,29 @@ function scorePlatformCoverage(data) {
   } else if (typeof raw === "string") {
     platforms = raw.split(",").map((s) => s.trim()).filter(Boolean);
   }
+  if (platforms.length === 0) {
+    const detected = [];
+    const platformPatterns = [
+      [/claude.?code/i, "claude-code"],
+      [/codex/i, "codex"],
+      [/gemini/i, "gemini"],
+      [/cursor/i, "cursor"],
+      [/windsurf/i, "windsurf"],
+      [/opencode/i, "opencode"],
+      [/openclaw/i, "openclaw"],
+      [/antigravity/i, "antigravity"],
+      [/pi\b/i, "pi"]
+    ];
+    for (const [re, name] of platformPatterns) {
+      if (re.test(body))
+        detected.push(name);
+    }
+    platforms = detected;
+  }
   const score = clamp(Math.min(platforms.length / 5, 1));
-  return { score, note: `${platforms.length} platforms covered` };
+  const findings = platforms.length === 0 ? ["No platforms declared or detected"] : platforms.length < 3 ? ["Limited platform coverage"] : undefined;
+  const recs = platforms.length < 3 ? ["Declare supported platforms in frontmatter (platforms:) or mention them in prose"] : undefined;
+  return { score, note: `${platforms.length} platforms covered`, findings, recommendations: recs };
 }
 function scoreConciseness(body) {
   return {
@@ -40627,16 +40967,19 @@ function scoreSafety2(body) {
     if (lower.includes(kw.toLowerCase()))
       count2++;
   }
-  return { score: density, note: `${count2} safety markers found` };
+  const findings = count2 < 3 ? ["Limited safety markers in config"] : undefined;
+  const recs = count2 < 3 ? ["Add [CRITICAL] markers, safety rules, NEVER directives, and security validation"] : undefined;
+  return { score: density, note: `${count2} safety markers found`, findings, recommendations: recs };
 }
 function evaluateMagent(content, target) {
-  const fmResult = parseFrontmatterSafe(content);
-  const data = fmResult ?? {};
-  const fmNote = fmResult === null ? parseErrorNote(content, "unknown parse error") : null;
   const body = extractBody(content);
+  const hasFrontmatter = /^---\s*$/m.test(content);
+  const fmResult = hasFrontmatter ? parseFrontmatterSafe(content) : undefined;
+  const data = fmResult ?? {};
+  const fmNote = hasFrontmatter && fmResult === null ? parseErrorNote(content, "Frontmatter parse error") : null;
   const dimensions = {
     completeness: scoreCompleteness3(body),
-    "platform-coverage": scorePlatformCoverage(data),
+    "platform-coverage": scorePlatformCoverage(data, body),
     conciseness: scoreConciseness(body),
     "tone-consistency": scoreToneConsistency(body),
     safety: scoreSafety2(body)
@@ -40659,7 +41002,14 @@ var MAGENT_SECTIONS;
 var init_magent = __esm(() => {
   init_heuristics();
   init_types2();
-  MAGENT_SECTIONS = [/^## IDENTITY/m, /^## SOUL/m, /^## AGENTS/m, /^## USER/m];
+  MAGENT_SECTIONS = [
+    { re: /^## .*[Pp]roject|^## .*[Ss]tack/m, label: "project" },
+    { re: /^## .*[Cc]ommand|^## .*[Tt]ool/m, label: "commands" },
+    { re: /^## .*[Vv]erif|^## .*[Tt]est|^## .*[Gg]ate/m, label: "verification" },
+    { re: /^## .*[Cc]onvention|^## .*[Ss]tyle|^## .*[Bb]oundar/m, label: "conventions" },
+    { re: /^## .*[Ss]afety|^## .*[Ss]ecurity|^## .*[Cc]ritical/m, label: "safety" },
+    { re: /^## .*[Dd]oc|^## .*[Rr]eference|^## .*[Rr]outing/m, label: "docs" }
+  ];
 });
 
 // ../../packages/core/src/quality/skill.ts
@@ -40694,7 +41044,17 @@ function scoreCompleteness4(content, data, body) {
   const keySet = new Set(presentKeys);
   const missing = required2.filter((f) => !keySet.has(f));
   const note = missing.length > 0 ? `Missing fields: ${missing.join(", ")}` : "All required fields present";
-  return { score, note };
+  const findings = [];
+  const recommendations = [];
+  if (missing.length > 0) {
+    findings.push(`Missing required frontmatter: ${missing.join(", ")}`);
+    recommendations.push(`Add \`${missing.join("`, `")}\` to YAML frontmatter`);
+  }
+  if (structure < 1) {
+    findings.push("Body lacks section headings (# / ## / ###). Structure aids navigation.");
+    recommendations.push("Organize content with markdown headings for progressive disclosure");
+  }
+  return { score, note, findings, recommendations };
 }
 function scoreClarity2(body) {
   return scoreClarityFromDensities(body);
@@ -40709,7 +41069,16 @@ function scoreTriggerAccuracy(body) {
   } else {
     score = clamp(1 - (count2 - 10) / 10);
   }
-  return { score, note: `${count2} trigger phrases found` };
+  const findings = [];
+  const recommendations = [];
+  if (count2 < 3) {
+    findings.push(`Only ${count2} trigger phrase(s) found; aim for 3\u201310 for reliable skill activation.`);
+    recommendations.push("Add 1\u20132 more When-to-Use scenarios or trigger phrase patterns to the description.");
+  } else if (count2 > 10) {
+    findings.push(`${count2} trigger phrases may cause overlap with adjacent skills.`);
+    recommendations.push("Consolidate overlapping triggers or narrow the activation scope.");
+  }
+  return { score, note: `${count2} trigger phrases found`, findings, recommendations };
 }
 function scoreAntiHallucination(body) {
   const density = keywordDensity(body, [
@@ -40723,10 +41092,16 @@ function scoreAntiHallucination(body) {
     "evidence"
   ]);
   const note = density > 0 ? "Includes verification language" : "Missing verification instructions";
-  return { score: density, note };
+  const findings = [];
+  const recommendations = [];
+  if (density < 0.3) {
+    findings.push("Verification/citation language sparse or absent. Skill may invite fabrication.");
+    recommendations.push('Add explicit "verify with source", "cross-check against docs", or "cite the reference" instructions.');
+  }
+  return { score: density, note, findings, recommendations };
 }
 function scoreConciseness2(body) {
-  const score = scoreLength(body, 500, 5000);
+  const score = scoreLength(body, 500, 15000);
   return { score, note: `Body length: ${body.length} chars` };
 }
 function countTriggerPhrases(body) {
@@ -40791,7 +41166,7 @@ var init_evaluate = __esm(() => {
 // ../../packages/core/src/quality/rubric.ts
 import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
 import { homedir as homedir3 } from "os";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 function resolveRubricContent(type, opts) {
   if (opts?.path) {
     if (!existsSync10(opts.path)) {
@@ -40800,15 +41175,15 @@ function resolveRubricContent(type, opts) {
     return readFileSync9(opts.path, "utf-8");
   }
   const homeDir = process.env.HOME ?? homedir3();
-  const userPath = join7(homeDir, ".superskill", "rubrics", `${type}.yaml`);
+  const userPath = join8(homeDir, ".superskill", "rubrics", `${type}.yaml`);
   if (existsSync10(userPath)) {
     return readFileSync9(userPath, "utf-8");
   }
-  const devPath = join7(import.meta.dir, "..", "rubrics", `${type}.yaml`);
+  const devPath = join8(import.meta.dir, "..", "rubrics", `${type}.yaml`);
   if (existsSync10(devPath)) {
     return readFileSync9(devPath, "utf-8");
   }
-  const prodPath = join7(import.meta.dir, "..", "..", "rubrics", `${type}.yaml`);
+  const prodPath = join8(import.meta.dir, "..", "..", "rubrics", `${type}.yaml`);
   if (existsSync10(prodPath)) {
     return readFileSync9(prodPath, "utf-8");
   }
@@ -46639,11 +47014,11 @@ var require_out = __commonJS((exports) => {
     async.read(path7, getSettings(optionsOrSettingsOrCallback), callback);
   }
   exports.stat = stat;
-  function statSync6(path7, optionsOrSettings) {
+  function statSync7(path7, optionsOrSettings) {
     const settings = getSettings(optionsOrSettings);
     return sync.read(path7, settings);
   }
-  exports.statSync = statSync6;
+  exports.statSync = statSync7;
   function getSettings(settingsOrOptions = {}) {
     if (settingsOrOptions instanceof settings_1.default) {
       return settingsOrOptions;
@@ -57813,7 +58188,7 @@ import { join as join52 } from "path";
 import path10, { relative as relative2, resolve as resolve4 } from "path";
 import { basename as basename4, join as join9 } from "path";
 import { join as join72 } from "path";
-import { join as join8 } from "path";
+import { join as join82 } from "path";
 import { join as join10 } from "path";
 import { basename as basename22, join as join11 } from "path";
 import { join as join13 } from "path";
@@ -57886,7 +58261,7 @@ import { join as join79 } from "path";
 import { join as join81 } from "path";
 import { join as join80 } from "path";
 import { join as join84 } from "path";
-import { join as join82 } from "path";
+import { join as join822 } from "path";
 import { join as join83 } from "path";
 import { join as join85 } from "path";
 import { join as join86 } from "path";
@@ -63432,7 +63807,7 @@ var init_chunk_QKQNZ6C3 = __esm(() => {
     constructor({ frontmatter, body, ...rest2 }) {
       const parseResult = RulesyncCommandFrontmatterSchema.safeParse(frontmatter);
       if (!parseResult.success && rest2.validate) {
-        throw new Error(`Invalid frontmatter in ${join8(rest2.outputRoot ?? process.cwd(), rest2.relativeDirPath, rest2.relativeFilePath)}: ${formatError2(parseResult.error)}`);
+        throw new Error(`Invalid frontmatter in ${join82(rest2.outputRoot ?? process.cwd(), rest2.relativeDirPath, rest2.relativeFilePath)}: ${formatError2(parseResult.error)}`);
       }
       const parsedFrontmatter = parseResult.success ? { ...frontmatter, ...parseResult.data } : { ...frontmatter, targets: frontmatter.targets ?? ["*"] };
       super({
@@ -63473,7 +63848,7 @@ var init_chunk_QKQNZ6C3 = __esm(() => {
       } else {
         return {
           success: false,
-          error: new Error(`Invalid frontmatter in ${join8(this.relativeDirPath, this.relativeFilePath)}: ${formatError2(result.error)}`)
+          error: new Error(`Invalid frontmatter in ${join82(this.relativeDirPath, this.relativeFilePath)}: ${formatError2(result.error)}`)
         };
       }
     }
@@ -63481,7 +63856,7 @@ var init_chunk_QKQNZ6C3 = __esm(() => {
       outputRoot = process.cwd(),
       relativeFilePath
     }) {
-      const filePath = join8(outputRoot, _RulesyncCommand.getSettablePaths().relativeDirPath, relativeFilePath);
+      const filePath = join82(outputRoot, _RulesyncCommand.getSettablePaths().relativeDirPath, relativeFilePath);
       const fileContent = await readFileContent(filePath);
       const { frontmatter, body: content } = parseFrontmatter2(fileContent, filePath);
       const result = RulesyncCommandFrontmatterSchema.safeParse(frontmatter);
@@ -69803,9 +70178,9 @@ prompt = ""`;
       return ignoreProcessorToolTargets;
     }
   };
-  AMP_GLOBAL_DIR = join82(".config", "amp");
-  AMP_SKILLS_PROJECT_DIR = join82(AMP_AGENTS_DIR, "skills");
-  AMP_SKILLS_GLOBAL_DIR = join82(".config", "agents", "skills");
+  AMP_GLOBAL_DIR = join822(".config", "amp");
+  AMP_SKILLS_PROJECT_DIR = join822(AMP_AGENTS_DIR, "skills");
+  AMP_SKILLS_GLOBAL_DIR = join822(".config", "agents", "skills");
   EnvVarNameSchema = exports_external3.string().check(refine2((value) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(value), "envVars entries must be valid environment variable names"));
   McpServerSchema = exports_external3.looseObject({
     type: exports_external3.optional(exports_external3.enum(["local", "stdio", "sse", "http", "ws", "streamable-http"])),
@@ -88916,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();
@@ -94660,11 +95034,39 @@ function deserializeEvaluation(row) {
 }
 
 // src/operations/evaluate.ts
+async function showHistory(type, contentName, opts) {
+  const adapter = opts.adapter ?? await openStore();
+  const dao = new EvaluationDao(adapter);
+  const rows = await dao.getEvaluations(type, contentName);
+  if (rows.length === 0)
+    return;
+  const cols = { date: 19, agg: 9, verdict: 7 };
+  const lines = [];
+  lines.push(`Evaluation history for ${contentName} (${rows.length} entries):`);
+  lines.push("");
+  const header = `${"Date".padEnd(cols.date)}  ${"Aggregate".padEnd(cols.agg)}  ${"Verdict".padEnd(cols.verdict)}  Scorer`;
+  lines.push(header);
+  lines.push("-".repeat(header.length));
+  for (const row of rows) {
+    const date9 = new Date(row.created_at).toISOString().slice(0, 19).replace("T", " ");
+    const agg = row.aggregate.toFixed(2).padEnd(cols.agg);
+    const verdict = (row.aggregate >= 0.7 ? "PASS" : "FAIL").padEnd(cols.verdict);
+    const scorer = row.scorer ?? "heuristic";
+    const rv = row.rubric_version ? ` v${row.rubric_version}` : "";
+    lines.push(`${date9.padEnd(cols.date)}  ${agg}  ${verdict}  ${scorer}${rv}`);
+  }
+  echo(lines.join(`
+`));
+}
 async function evaluate3(type, nameOrPath, opts) {
   const resolvedPath = resolveContentPath(type, nameOrPath);
   if (!resolvedPath) {
     throw Object.assign(new Error(`File not found: ${nameOrPath}`), { code: 2 });
   }
+  if (opts?.history) {
+    await showHistory(type, resolveContentName(resolvedPath), opts);
+    return null;
+  }
   let content;
   try {
     content = await Bun.file(resolvedPath).text();
@@ -94680,8 +95082,24 @@ async function evaluate3(type, nameOrPath, opts) {
   }
   const report = evaluate(type, content, resolvedTarget);
   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;
 }
@@ -94695,11 +95113,30 @@ function computeWeightedAggregate(scores, rubric2) {
   }
   return sum2;
 }
+function applyRubricWeightingAndVerdict(type, report, opts) {
+  try {
+    const rubric2 = loadRubric(type, opts?.rubric ? { path: opts.rubric } : undefined);
+    report.aggregate = computeWeightedAggregate(report.dimensions, rubric2);
+  } catch {}
+  const agg = report.aggregate;
+  report.verdict = agg >= 0.7 ? "PASS" : "FAIL";
+  if (agg >= 0.9)
+    report.grade = "A";
+  else if (agg >= 0.75)
+    report.grade = "B";
+  else if (agg >= 0.6)
+    report.grade = "C";
+  else if (agg >= 0.45)
+    report.grade = "D";
+  else
+    report.grade = "F";
+}
 function emitEnvelope(type, resolvedPath, content, resolvedTarget, opts) {
   const rubric2 = loadRubric(type, { path: opts.rubric });
   const contentName = resolveContentName(resolvedPath);
   const baseline = evaluate(type, content, resolvedTarget);
   baseline.content = contentName;
+  applyRubricWeightingAndVerdict(type, baseline, opts);
   const envelope = {
     type,
     content_name: contentName,
@@ -94769,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);
@@ -94811,6 +95243,33 @@ function formatEvaluationReport(report, json3) {
   }
   lines.push(`  ${"\u2500".repeat(maxNameLen)}${"\u2500".repeat(30)}`);
   lines.push(`  ${"AGGREGATE".padEnd(maxNameLen)}  ${report.aggregate.toFixed(2)}`);
+  if (report.verdict || report.grade) {
+    lines.push("");
+    lines.push(`  Verdict: ${report.verdict ?? ""}  Grade: ${report.grade ?? ""}`);
+  }
+  const findings = [];
+  const recommendations = [];
+  for (const name of dimNames) {
+    const dim2 = report.dimensions[name];
+    if (!dim2)
+      continue;
+    if (dim2.findings)
+      findings.push(...dim2.findings.map((f) => `[${name}] ${f}`));
+    if (dim2.recommendations)
+      recommendations.push(...dim2.recommendations.map((r) => `[${name}] ${r}`));
+  }
+  if (findings.length > 0) {
+    lines.push("");
+    lines.push("Findings:");
+    for (const f of findings)
+      lines.push(`  \u2022 ${f}`);
+  }
+  if (recommendations.length > 0) {
+    lines.push("");
+    lines.push("Recommendations:");
+    for (const r of recommendations)
+      lines.push(`  \u2192 ${r}`);
+  }
   return lines.join(`
 `);
 }
@@ -94890,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 [];
@@ -94951,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");
@@ -94980,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: "",
@@ -95027,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);
@@ -95122,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,
@@ -95158,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);
@@ -95360,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);
@@ -95374,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);
@@ -95382,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);
@@ -95391,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.");
   }
@@ -95448,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,
@@ -95464,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") {
@@ -95485,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";
@@ -95497,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;
@@ -95653,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) {
@@ -95684,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 {
@@ -95712,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;
     }
@@ -95725,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;
@@ -95735,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)`);
@@ -95742,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.");
@@ -95755,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();
@@ -95766,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");
@@ -95786,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)) {
@@ -95819,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;
@@ -95850,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) {
@@ -95863,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;
 }
@@ -95893,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) => {
@@ -95909,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;
@@ -95940,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) {
@@ -95953,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;
 }
@@ -95983,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) => {
@@ -96004,10 +96771,10 @@ import {
   copyFileSync as copyFileSync2,
   existsSync as existsSync14,
   mkdirSync as mkdirSync9,
-  readdirSync as readdirSync3,
+  readdirSync as readdirSync4,
   readFileSync as readFileSync13,
   rmSync as rmSync4,
-  statSync as statSync6,
+  statSync as statSync7,
   writeFileSync as writeFileSync8
 } from "fs";
 import { homedir as homedir5 } from "os";
@@ -96267,7 +97034,7 @@ async function executeInstall(plugin, targets2, options2, dependencies = {}) {
       if (existsSync14(agentsDir) && !options2.dryRun) {
         const piAgentsDir = join223(outputRoot, ".pi", "agent", "agents");
         mkdirSync9(piAgentsDir, { recursive: true });
-        for (const entry of readdirSync3(agentsDir)) {
+        for (const entry of readdirSync4(agentsDir)) {
           if (!entry.endsWith(".md"))
             continue;
           const agentName = entry.replace(/\.md$/, "");
@@ -96332,7 +97099,7 @@ function resolvePluginRoot(plugin, marketplacePath) {
     return { pluginRoot: resolved.pluginRoot, marketplaceRoot: manifestRoot, marketplaceName };
   }
   const fallback = join223("plugins", plugin);
-  if (existsSync14(join223(fallback, "plugin.json")))
+  if (existsSync14(fallback) && readdirSync4(fallback).some((d) => ["skills", "commands", "agents", "hooks", "hooks.json"].includes(d)))
     return { pluginRoot: fallback };
   const available = listResolvablePlugins(marketplacePath);
   const msg = available.length > 0 ? `Available: ${available.join(", ")}` : "No marketplace manifest found and no plugins/<name>/ directory.";
@@ -96369,9 +97136,9 @@ function transformRulesyncMarkdown(root, target, pluginName) {
 function transformMarkdownDirectory(dir, target, pluginName) {
   if (!existsSync14(dir))
     return;
-  for (const entry of readdirSync3(dir)) {
+  for (const entry of readdirSync4(dir)) {
     const path11 = join223(dir, entry);
-    const stats = statSync6(path11);
+    const stats = statSync7(path11);
     if (stats.isDirectory()) {
       transformMarkdownDirectory(path11, target, pluginName);
       continue;
@@ -96388,12 +97155,12 @@ function copyDirectory(source, destination, options2 = {}) {
   if (!existsSync14(source))
     return;
   mkdirSync9(destination, { recursive: true });
-  for (const entry of readdirSync3(source)) {
+  for (const entry of readdirSync4(source)) {
     if (options2.skipDirectoryNames?.has(entry))
       continue;
     const sourcePath = join223(source, entry);
     const destinationPath = join223(destination, entry);
-    if (statSync6(sourcePath).isDirectory()) {
+    if (statSync7(sourcePath).isDirectory()) {
       copyDirectory(sourcePath, destinationPath, options2);
     } else {
       copyFileSync2(sourcePath, destinationPath);
@@ -96402,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 });
@@ -96426,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) {
@@ -96466,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);
@@ -96503,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) => {
@@ -96531,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;
@@ -96562,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) {
@@ -96575,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;
 }
@@ -96605,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) => {
@@ -96675,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;
@@ -96695,10 +97449,11 @@ async function skillEvaluate(opts) {
   const report = await evaluate3("skill", opts.nameOrPath, {
     target,
     save: opts.save,
+    history: opts.history,
     ...opts.rubric ? { rubric: opts.rubric } : {},
     ...opts.ingest ? { ingest: opts.ingest } : {}
   });
-  if (report) {
+  if (report && !opts.history) {
     const output2 = formatEvaluationReport(report, opts.json);
     echo(`${output2}`);
   }
@@ -96706,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) {
@@ -96719,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;
 }
@@ -96770,8 +97529,8 @@ function registerSkill(program2) {
   const cmd = program2.command("skill").description("Manage skill definitions");
   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)"))))).action(handleSkillEvaluate);
-  addSaveOption(addTargetOption(addAutoOption(cmd.command("refine <nameOrPath>").description("Evaluate and auto-fix a skill")))).action(handleSkillRefine);
+  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);
+  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);