@rhize/skill-forge 0.9.0 → 0.10.0

package/dist/cli.js

@@ -1370,14 +1370,14 @@ skill skills user claude code based comprehensive enhanced practical including i
 `.split(/\s+/).filter(Boolean)
 );
 var DEFAULT_SET_THRESHOLD = 0.45;
-function splitLimited(text, sep2, maxSplit) {
+function splitLimited(text, sep3, maxSplit) {
   const parts = [];
   let rest = text;
   for (let i = 0; i < maxSplit; i++) {
-    const idx = rest.indexOf(sep2);
+    const idx = rest.indexOf(sep3);
     if (idx === -1) break;
     parts.push(rest.slice(0, idx));
-    rest = rest.slice(idx + sep2.length);
+    rest = rest.slice(idx + sep3.length);
   }
   parts.push(rest);
   return parts;
@@ -5022,6 +5022,1506 @@ async function queueClose(id, options = {}) {
   console.log(`[skill-forge] queue entry ${updated.id} closed -> status: ${updated.status}`);
 }
 
+// src/commands/refine.ts
+import { createHash as createHash3, randomUUID as randomUUID4 } from "crypto";
+import { chmodSync, existsSync as existsSync20, lstatSync as lstatSync3, mkdirSync as mkdirSync9, readFileSync as readFileSync15, realpathSync as realpathSync7, renameSync as renameSync5, rmSync as rmSync7, writeFileSync as writeFileSync9 } from "fs";
+import { dirname as dirname11, isAbsolute as isAbsolute3, join as join25, relative as relative3, resolve as resolvePath11, sep as sep2 } from "path";
+import { createInterface as createInterface5 } from "readline/promises";
+
+// src/refine/context.ts
+import { existsSync as existsSync19, realpathSync as realpathSync6, statSync as statSync11 } from "fs";
+import { isAbsolute as isAbsolute2, join as join24, relative as relative2, resolve as resolvePath10 } from "path";
+
+// src/refine/models.ts
+import { randomBytes } from "crypto";
+var REFINEMENT_CATEGORIES = ["trigger", "content", "hook", "tool", "pattern", "config", "new"];
+var OVERRIDE_TYPES = ["patch", "extend", "config", "full", "hook", "script", "new"];
+var PATCH_ACTIONS = ["append", "prepend", "replace-section", "insert-after", "insert-before", "delete-section"];
+var PATTERN_STATUSES = ["tracking", "ready", "generalized", "dismissed"];
+function isRefinementCategory(value) {
+  return REFINEMENT_CATEGORIES.includes(value);
+}
+function isOverrideType(value) {
+  return OVERRIDE_TYPES.includes(value);
+}
+function isPatchAction(value) {
+  return PATCH_ACTIONS.includes(value);
+}
+function isPatternStatus(value) {
+  return PATTERN_STATUSES.includes(value);
+}
+var REFINEMENT_STATUSES = ["pending", "applied", "generalized"];
+function isRefinementStatus(value) {
+  return REFINEMENT_STATUSES.includes(value);
+}
+function patternCount(pattern) {
+  return new Set(pattern.occurrences.map((o) => o.projectRealpath)).size;
+}
+function defaultRandomHex() {
+  return randomBytes(2).toString("hex");
+}
+function formatYYYYMMDD(date) {
+  const yyyy = date.getUTCFullYear().toString().padStart(4, "0");
+  const mm = (date.getUTCMonth() + 1).toString().padStart(2, "0");
+  const dd = date.getUTCDate().toString().padStart(2, "0");
+  return `${yyyy}${mm}${dd}`;
+}
+function generateRefinementId(existingIds = /* @__PURE__ */ new Set(), now = /* @__PURE__ */ new Date(), randomHex = defaultRandomHex) {
+  const datePart = formatYYYYMMDD(now);
+  let id;
+  do {
+    id = `REF-${datePart}-${randomHex()}`;
+  } while (existingIds.has(id));
+  return id;
+}
+function generatePatternId(existingIds = /* @__PURE__ */ new Set(), randomHex = defaultRandomHex) {
+  let id;
+  do {
+    id = `PAT-${randomHex()}`;
+  } while (existingIds.has(id));
+  return id;
+}
+function fingerprintKey(skill, target, overrideType, action) {
+  const normalize = (s) => s.trim().toLowerCase().replace(/\s+/g, " ");
+  return [normalize(skill), normalize(target), overrideType, action ?? ""].join("::");
+}
+function contentSimilarity(a, b) {
+  const tokenize2 = (s) => new Set(s.toLowerCase().split(/\s+/).filter(Boolean));
+  const tokensA = tokenize2(a);
+  const tokensB = tokenize2(b);
+  if (tokensA.size === 0 || tokensB.size === 0) return 0;
+  let intersectionSize = 0;
+  for (const token of tokensA) {
+    if (tokensB.has(token)) intersectionSize++;
+  }
+  const unionSize2 = tokensA.size + tokensB.size - intersectionSize;
+  return unionSize2 === 0 ? 0 : intersectionSize / unionSize2;
+}
+
+// src/refine/store.ts
+import { createHash as createHash2, randomUUID as randomUUID3 } from "crypto";
+import { existsSync as existsSync18, mkdirSync as mkdirSync8, readFileSync as readFileSync14, renameSync as renameSync4, rmSync as rmSync6, statSync as statSync10, writeFileSync as writeFileSync8, realpathSync as realpathSync5 } from "fs";
+import { basename as basename9, dirname as dirname10, join as join23, resolve as resolvePath9 } from "path";
+var SIMILARITY_JOIN_THRESHOLD = 0.7;
+var READY_THRESHOLD = 2;
+function getRefinementsDir() {
+  return join23(getHomeDir(), "refinements");
+}
+function getRefinementsPath() {
+  return join23(getRefinementsDir(), "refinements.json");
+}
+function getPatternsPath() {
+  return join23(getRefinementsDir(), "patterns.json");
+}
+function getBackupsDir() {
+  return join23(getRefinementsDir(), "backups");
+}
+function writeJsonAtomic(path, data) {
+  const dir = dirname10(path);
+  mkdirSync8(dir, { recursive: true });
+  const tempPath = join23(dir, `.${basename9(path)}.tmp-${randomUUID3()}`);
+  try {
+    writeFileSync8(tempPath, JSON.stringify(data, null, 2) + "\n", { encoding: "utf-8", mode: 384 });
+    renameSync4(tempPath, path);
+  } catch (err) {
+    rmSync6(tempPath, { force: true });
+    throw err;
+  }
+}
+function readJsonFile(path, label) {
+  let raw;
+  try {
+    raw = readFileSync14(path, "utf-8");
+  } catch (err) {
+    throw new UserError(`unable to read ${label} at ${path}: ${err.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new UserError(`malformed ${label} at ${path}: not valid JSON`);
+  }
+}
+function readStore(path, label, validateRecord) {
+  if (!existsSync18(path)) {
+    return { schemaVersion: 1, records: [] };
+  }
+  const parsed = readJsonFile(path, label);
+  if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.records)) {
+    throw new UserError(`malformed ${label} at ${path}: expected an object with a "records" array`);
+  }
+  const records = parsed.records;
+  if (validateRecord) {
+    records.forEach((record, index) => validateRecord(record, index));
+  }
+  return { schemaVersion: 1, records };
+}
+function validateRefinementRecordShape(record, index, path) {
+  if (typeof record !== "object" || record === null) {
+    throw new UserError(`malformed refinements.json at ${path}: record[${index}] is not an object`);
+  }
+  const r = record;
+  if (typeof r.id !== "string" || r.id.length === 0) {
+    throw new UserError(`malformed refinements.json at ${path}: record[${index}] is missing a valid "id"`);
+  }
+  if (typeof r.createdAt !== "string" || r.createdAt.length === 0) {
+    throw new UserError(`malformed refinements.json at ${path}: record "${r.id}" is missing a valid "createdAt"`);
+  }
+  if (typeof r.status !== "string" || r.status.length === 0) {
+    throw new UserError(`malformed refinements.json at ${path}: record "${r.id}" is missing a valid "status"`);
+  }
+  if (typeof r.skill !== "string" || r.skill.length === 0) {
+    throw new UserError(`malformed refinements.json at ${path}: record "${r.id}" is missing a valid "skill"`);
+  }
+  const patchActionsRequiringMarker = /* @__PURE__ */ new Set(["insert-after", "insert-before", "replace-section", "delete-section"]);
+  if (r.overrideType === "patch") {
+    if (typeof r.patchAction !== "string" || r.patchAction.length === 0) {
+      throw new UserError(`malformed refinements.json at ${path}: record "${r.id}" has overrideType "patch" but is missing "patchAction"`);
+    }
+    if (patchActionsRequiringMarker.has(r.patchAction) && (typeof r.patchMarker !== "string" || r.patchMarker.length === 0)) {
+      throw new UserError(
+        `malformed refinements.json at ${path}: record "${r.id}" has patchAction "${r.patchAction}" but is missing "patchMarker"`
+      );
+    }
+    if (typeof r.patchContent !== "string" || r.patchContent.length === 0) {
+      throw new UserError(`malformed refinements.json at ${path}: record "${r.id}" has overrideType "patch" but is missing "patchContent"`);
+    }
+  } else if (r.patchAction !== void 0) {
+    throw new UserError(
+      `malformed refinements.json at ${path}: record "${r.id}" has overrideType "${String(r.overrideType)}" but carries "patchAction" \u2014 only valid when overrideType is "patch"`
+    );
+  }
+}
+function validatePatternRecordShape(record, index, path) {
+  if (typeof record !== "object" || record === null) {
+    throw new UserError(`malformed patterns.json at ${path}: record[${index}] is not an object`);
+  }
+  const p = record;
+  if (typeof p.id !== "string" || p.id.length === 0) {
+    throw new UserError(`malformed patterns.json at ${path}: record[${index}] is missing a valid "id"`);
+  }
+  if (typeof p.status !== "string" || p.status.length === 0) {
+    throw new UserError(`malformed patterns.json at ${path}: record "${p.id}" is missing a valid "status"`);
+  }
+  if (!Array.isArray(p.occurrences)) {
+    throw new UserError(`malformed patterns.json at ${path}: record "${p.id}" is missing a valid "occurrences" array`);
+  }
+  if (p.status === "dismissed" && (typeof p.dismissedReason !== "string" || p.dismissedReason.length === 0)) {
+    throw new UserError(`malformed patterns.json at ${path}: record "${p.id}" has status "dismissed" but is missing "dismissedReason"`);
+  }
+  if (p.status === "generalized") {
+    if (typeof p.generalizedAt !== "string" || p.generalizedAt.length === 0) {
+      throw new UserError(`malformed patterns.json at ${path}: record "${p.id}" has status "generalized" but is missing "generalizedAt"`);
+    }
+    if (typeof p.generalizedBackupId !== "string" || p.generalizedBackupId.length === 0) {
+      throw new UserError(`malformed patterns.json at ${path}: record "${p.id}" has status "generalized" but is missing "generalizedBackupId"`);
+    }
+  }
+}
+function readRefinementsStore() {
+  const path = getRefinementsPath();
+  return readStore(path, "refinements.json", (record, index) => validateRefinementRecordShape(record, index, path));
+}
+function writeRefinementsStore(store) {
+  writeJsonAtomic(getRefinementsPath(), store);
+}
+function readPatternsStore() {
+  const path = getPatternsPath();
+  return readStore(path, "patterns.json", (record, index) => validatePatternRecordShape(record, index, path));
+}
+function writePatternsStore(store) {
+  writeJsonAtomic(getPatternsPath(), store);
+}
+function resolveProjectRealpath(projectRoot) {
+  const resolved = resolvePath9(projectRoot);
+  try {
+    return realpathSync5(resolved);
+  } catch {
+    return resolved;
+  }
+}
+function generatePatternName(refinement) {
+  const parts = refinement.targetSection.replace(/\//g, " ").replace(/-/g, " ").split(/\s+/).filter(Boolean);
+  const lastThree = parts.slice(-3);
+  if (lastThree.length === 0) return refinement.targetSection || `pattern-${refinement.skill}`;
+  return lastThree.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function generatePatternDescription(refinement) {
+  const category = refinement.category.charAt(0).toUpperCase() + refinement.category.slice(1);
+  const cause = refinement.rootCause || refinement.expectedBehavior;
+  return `${category} modification for ${refinement.skill}: ${cause}`;
+}
+function upsertPattern(records, refinement, projectRealpath, nowIso, randomHex, explicitPatternId) {
+  let pattern;
+  if (explicitPatternId) {
+    pattern = records.find((p) => p.id === explicitPatternId);
+    if (!pattern) {
+      throw new UserError(`no pattern with id: ${explicitPatternId}`);
+    }
+    if (pattern.status === "dismissed" || pattern.status === "generalized") {
+      throw new UserError(`cannot join pattern ${explicitPatternId}: it is ${pattern.status} and no longer accepts new occurrences`);
+    }
+  } else {
+    const joinable = records.filter((p) => p.status !== "generalized" && p.status !== "dismissed");
+    const fingerprint = fingerprintKey(refinement.skill, refinement.targetSection, refinement.overrideType, refinement.patchAction);
+    pattern = joinable.find((p) => p.fingerprint === fingerprint);
+    if (!pattern && refinement.patchContent) {
+      pattern = joinable.find((p) => {
+        const sample = p.proposedChanges.content;
+        return sample ? contentSimilarity(refinement.patchContent, sample) > SIMILARITY_JOIN_THRESHOLD : false;
+      });
+    }
+  }
+  const wasTracking = pattern?.status === "tracking";
+  if (!pattern) {
+    const created = {
+      id: generatePatternId(new Set(records.map((p) => p.id)), randomHex),
+      name: generatePatternName(refinement),
+      description: generatePatternDescription(refinement),
+      affectedSkills: [refinement.skill],
+      refinementIds: [refinement.id],
+      occurrences: [{ refinementId: refinement.id, projectRealpath, timestamp: nowIso }],
+      status: "tracking",
+      proposedChanges: refinement.patchContent ? { content: refinement.patchContent } : {},
+      fingerprint: fingerprintKey(refinement.skill, refinement.targetSection, refinement.overrideType, refinement.patchAction),
+      firstSeen: nowIso,
+      lastSeen: nowIso
+    };
+    records.push(created);
+    return { pattern: created, becameReady: false };
+  }
+  if (!pattern.affectedSkills.includes(refinement.skill)) pattern.affectedSkills.push(refinement.skill);
+  if (!pattern.refinementIds.includes(refinement.id)) pattern.refinementIds.push(refinement.id);
+  pattern.occurrences.push({ refinementId: refinement.id, projectRealpath, timestamp: nowIso });
+  pattern.lastSeen = nowIso;
+  const becameReady = wasTracking && patternCount(pattern) >= READY_THRESHOLD;
+  if (becameReady) pattern.status = "ready";
+  return { pattern, becameReady };
+}
+function recordRefinement(input, deps = {}) {
+  const now = deps.now ?? /* @__PURE__ */ new Date();
+  const nowIso = now.toISOString();
+  const refinementsStore = readRefinementsStore();
+  const patternsStore = readPatternsStore();
+  const existingRefIds = new Set(refinementsStore.records.map((r) => r.id));
+  const refinementId = deps.id ?? generateRefinementId(existingRefIds, now, deps.randomHex);
+  const projectRealpath = resolveProjectRealpath(input.projectRoot);
+  const refinement = {
+    id: refinementId,
+    skill: input.skill,
+    category: input.category,
+    overrideType: input.overrideType,
+    targetSection: input.targetSection,
+    expectedBehavior: input.expectedBehavior,
+    actualBehavior: input.actualBehavior,
+    example: input.example,
+    desiredOutcome: input.desiredOutcome,
+    rootCause: input.rootCause,
+    confidence: input.confidence,
+    project: input.project,
+    projectRoot: projectRealpath,
+    patchAction: input.patchAction,
+    patchMarker: input.patchMarker,
+    patchContent: input.patchContent,
+    generalizationPotential: input.generalizationPotential,
+    scope: input.scope,
+    status: input.status ?? "applied",
+    createdAt: nowIso
+  };
+  const { pattern, becameReady } = upsertPattern(patternsStore.records, refinement, projectRealpath, nowIso, deps.randomHex, input.patternId);
+  refinement.patternId = pattern.id;
+  refinementsStore.records.push(refinement);
+  writeRefinementsStore(refinementsStore);
+  try {
+    writePatternsStore(patternsStore);
+  } catch (err) {
+    throw new UserError(
+      `refinements.json was updated with refinement ${refinement.id}, but patterns.json failed to update: ${err.message}`
+    );
+  }
+  return { refinement, pattern, patternBecameReady: becameReady };
+}
+function markGeneralized(id, backupId) {
+  const store = readPatternsStore();
+  const pattern = store.records.find((p) => p.id === id);
+  if (!pattern) {
+    throw new UserError(`no pattern with id: ${id}`);
+  }
+  const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+  pattern.status = "generalized";
+  pattern.generalizedAt = nowIso;
+  pattern.generalizedBackupId = backupId;
+  pattern.lastSeen = nowIso;
+  writePatternsStore(store);
+  return pattern;
+}
+function formatBackupTimestamp(date) {
+  return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+}
+var BACKUP_ID_PATTERN = /^\d{8}T\d{6}Z-[0-9a-f]{4}$/;
+function isValidBackupId(id) {
+  return BACKUP_ID_PATTERN.test(id);
+}
+function createBackup(filePaths, deps = {}) {
+  const now = deps.now ?? /* @__PURE__ */ new Date();
+  const randomHex = deps.randomHex ?? defaultRandomHex;
+  const id = `${formatBackupTimestamp(now)}-${randomHex()}`;
+  const files = filePaths.map((path) => {
+    if (!existsSync18(path)) {
+      return { path, existed: false, sha256: null, mode: null, contentBase64: null };
+    }
+    const bytes = readFileSync14(path);
+    const mode = statSync10(path).mode & 511;
+    const sha256 = createHash2("sha256").update(bytes).digest("hex");
+    return { path, existed: true, sha256, mode, contentBase64: bytes.toString("base64") };
+  });
+  const manifest = { id, createdAt: now.toISOString(), files };
+  writeJsonAtomic(join23(getBackupsDir(), id, "manifest.json"), manifest);
+  return manifest;
+}
+function validateBackupManifestShape(value, path) {
+  if (typeof value !== "object" || value === null) {
+    throw new UserError(`malformed backup manifest at ${path}: not an object`);
+  }
+  const m = value;
+  if (typeof m.id !== "string" || m.id.length === 0) {
+    throw new UserError(`malformed backup manifest at ${path}: missing a valid "id"`);
+  }
+  if (typeof m.createdAt !== "string" || m.createdAt.length === 0) {
+    throw new UserError(`malformed backup manifest at ${path}: missing a valid "createdAt"`);
+  }
+  if (!Array.isArray(m.files)) {
+    throw new UserError(`malformed backup manifest at ${path}: missing a valid "files" array`);
+  }
+  m.files.forEach((entry, index) => {
+    if (typeof entry !== "object" || entry === null) {
+      throw new UserError(`malformed backup manifest at ${path}: files[${index}] is not an object`);
+    }
+    const f = entry;
+    if (typeof f.path !== "string" || f.path.length === 0) {
+      throw new UserError(`malformed backup manifest at ${path}: files[${index}] is missing a valid "path"`);
+    }
+    if (typeof f.existed !== "boolean") {
+      throw new UserError(`malformed backup manifest at ${path}: files[${index}] ("${f.path}") is missing a valid "existed" (must be boolean)`);
+    }
+    if (f.existed) {
+      if (typeof f.sha256 !== "string" || f.sha256.length === 0) {
+        throw new UserError(`malformed backup manifest at ${path}: files[${index}] ("${f.path}") has existed:true but is missing "sha256"`);
+      }
+      if (typeof f.mode !== "number") {
+        throw new UserError(`malformed backup manifest at ${path}: files[${index}] ("${f.path}") has existed:true but is missing a numeric "mode"`);
+      }
+      if (typeof f.contentBase64 !== "string") {
+        throw new UserError(`malformed backup manifest at ${path}: files[${index}] ("${f.path}") has existed:true but is missing "contentBase64"`);
+      }
+    } else {
+      if (f.sha256 !== null || f.mode !== null || f.contentBase64 !== null) {
+        throw new UserError(`malformed backup manifest at ${path}: files[${index}] ("${f.path}") has existed:false (a tombstone) but sha256/mode/contentBase64 are not all null`);
+      }
+    }
+  });
+}
+function readBackupManifest(id) {
+  if (!isValidBackupId(id)) {
+    throw new UserError(`invalid backup id "${id}" \u2014 expected the format produced by \`skill-forge refine promote\` (e.g. 20260720T142305Z-a1b2)`);
+  }
+  const manifestPath = join23(getBackupsDir(), id, "manifest.json");
+  if (!existsSync18(manifestPath)) {
+    throw new UserError(`no backup with id: ${id}`);
+  }
+  const parsed = readJsonFile(manifestPath, "backup manifest");
+  validateBackupManifestShape(parsed, manifestPath);
+  return parsed;
+}
+
+// src/refine/context.ts
+function resolveConfiguredRoot2(root) {
+  return resolvePath10(expandHome(root));
+}
+function assertPlainSkillName(name) {
+  if (!name || name.trim().length === 0) {
+    throw new UserError("skill name must not be empty");
+  }
+  if (name.includes("/") || name.includes("\\") || name === "." || name === "..") {
+    throw new UserError(`invalid skill name "${name}" \u2014 must be a plain directory name, not a path`);
+  }
+}
+function realpathOrNull2(p) {
+  try {
+    return realpathSync6(p);
+  } catch {
+    return null;
+  }
+}
+function isUnderRoot2(candidate, root) {
+  const rel = relative2(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
+}
+function resolveScopes(config, cwd, skill, userRootFlag) {
+  assertPlainSkillName(skill);
+  const resolvedCwd = resolvePath10(cwd);
+  const localDir = join24(resolvedCwd, ".claude", "skills", skill);
+  const sharedDir = join24(resolvedCwd, "skills", skill);
+  const local = { scope: "local", dir: localDir, exists: existsSync19(localDir) };
+  const shared = { scope: "shared", dir: sharedDir, exists: existsSync19(sharedDir) };
+  const user = resolveUserScope(config, resolvedCwd, skill, userRootFlag);
+  return { local, shared, user };
+}
+function resolveUserScope(config, resolvedCwd, skill, userRootFlag) {
+  if (userRootFlag) {
+    const root = resolvePath10(userRootFlag);
+    return { resolved: true, dir: join24(root, skill), root: userRootFlag, reason: "flag" };
+  }
+  const cwdReal = realpathOrNull2(resolvedCwd) ?? resolvedCwd;
+  const candidates = config.skillsRoots.map((root) => ({ root, dir: join24(resolveConfiguredRoot2(root), skill) }));
+  for (const candidate of candidates) {
+    const skillReal = realpathOrNull2(candidate.dir);
+    if (skillReal) {
+      return { resolved: true, dir: candidate.dir, root: candidate.root, reason: "contains-skill" };
+    }
+  }
+  const externalCandidates = candidates.filter((candidate) => {
+    const rootReal = realpathOrNull2(resolveConfiguredRoot2(candidate.root)) ?? resolveConfiguredRoot2(candidate.root);
+    return !isUnderRoot2(rootReal, cwdReal) && !isUnderRoot2(cwdReal, rootReal);
+  });
+  if (externalCandidates.length === 1) {
+    return { resolved: true, dir: externalCandidates[0].dir, root: externalCandidates[0].root, reason: "sole-external-root" };
+  }
+  return { resolved: false, candidates: externalCandidates.length > 0 ? externalCandidates : candidates };
+}
+function isFile2(p) {
+  try {
+    return statSync11(p).isFile();
+  } catch {
+    return false;
+  }
+}
+function isDirectory(p) {
+  try {
+    return statSync11(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function inventoryScopeDir(scope, dir) {
+  return {
+    scope,
+    dir,
+    dirExists: isDirectory(dir),
+    skillMd: isFile2(join24(dir, "SKILL.md")),
+    patchMd: isFile2(join24(dir, "SKILL.patch.md")),
+    extendMd: isFile2(join24(dir, "SKILL.extend.md")),
+    configJson: isFile2(join24(dir, "skill-config.json")),
+    hooksDir: isDirectory(join24(dir, "hooks")),
+    scriptsDir: isDirectory(join24(dir, "scripts"))
+  };
+}
+function inventoryAllScopes(resolution) {
+  const rows = [inventoryScopeDir("local", resolution.local.dir), inventoryScopeDir("shared", resolution.shared.dir)];
+  if (resolution.user.resolved) {
+    rows.push(inventoryScopeDir("user", resolution.user.dir));
+  }
+  return rows;
+}
+
+// src/refine/patch.ts
+var FENCE_RE = /^\s*(```|~~~)/;
+var HEADING_RE = /^(#{1,6})\s+(.*)$/;
+function frontmatterOffset(lines) {
+  if (lines[0] !== "---") return 0;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") return i + 1;
+  }
+  return 0;
+}
+function buildHeadingTree(lines, bodyOffset) {
+  const flat = [];
+  let inFence = false;
+  for (let i = bodyOffset; i < lines.length; i++) {
+    const line = lines[i];
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const m = HEADING_RE.exec(line);
+    if (m) flat.push({ level: m[1].length, text: m[2].trim(), line: i });
+  }
+  const root = { level: 0, heading: "", headingLine: bodyOffset - 1, bodyStart: bodyOffset, bodyEnd: lines.length, children: [] };
+  const stack = [root];
+  for (const h of flat) {
+    while (stack.length > 1 && stack[stack.length - 1].level >= h.level) {
+      const done = stack.pop();
+      if (done) done.bodyEnd = h.line;
+    }
+    const node = { level: h.level, heading: h.text, headingLine: h.line, bodyStart: h.line + 1, bodyEnd: lines.length, children: [] };
+    stack[stack.length - 1].children.push(node);
+    stack.push(node);
+  }
+  return root;
+}
+function normalizeText(s) {
+  return s.trim().replace(/\s+/g, " ");
+}
+function splitHeadingPath(target) {
+  return target.split(">").map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+}
+function collectDescendants(node, acc) {
+  acc.push(node);
+  for (const child of node.children) collectDescendants(child, acc);
+}
+function resolveHeadingPath(root, segments) {
+  if (segments.length === 0) return root;
+  const allNodes = [];
+  collectDescendants(root, allNodes);
+  const headingNodes = allNodes.filter((n) => n.level > 0);
+  const firstNorm = normalizeText(segments[0]);
+  let candidates = headingNodes.filter((n) => normalizeText(n.heading) === firstNorm);
+  if (candidates.length === 0) {
+    const available = headingNodes.map((n) => n.heading);
+    throw new UserError(`No section matching "${segments[0]}" found (available headings: ${available.length > 0 ? available.join(", ") : "none"})`);
+  }
+  for (let i = 1; i < segments.length; i++) {
+    const segment = segments[i];
+    const norm = normalizeText(segment);
+    const next = [];
+    for (const candidate of candidates) {
+      for (const child of candidate.children) {
+        if (normalizeText(child.heading) === norm) next.push(child);
+      }
+    }
+    if (next.length === 0) {
+      const available = [...new Set(candidates.flatMap((c) => c.children.map((child) => child.heading)))];
+      throw new UserError(`No section matching "${segment}" found (available headings: ${available.length > 0 ? available.join(", ") : "none"})`);
+    }
+    candidates = next;
+  }
+  if (candidates.length > 1) {
+    throw new UserError(`Target selector "${segments.join(" > ")}" matched ${candidates.length} sections; be more specific`);
+  }
+  return candidates[0];
+}
+function findMarkerLine(lines, start, end, marker) {
+  const norm = normalizeText(marker);
+  const matches = [];
+  for (let i = start; i < end; i++) {
+    if (normalizeText(lines[i]).includes(norm)) matches.push(i);
+  }
+  if (matches.length === 0) {
+    throw new UserError(`No line matching marker "${marker}" found in target section`);
+  }
+  if (matches.length > 1) {
+    const preview = matches.map((i) => `line ${i + 1}: "${lines[i].trim()}"`).join("; ");
+    throw new UserError(`Marker "${marker}" matched ${matches.length} lines, expected exactly 1 (${preview})`);
+  }
+  return matches[0];
+}
+function findChildByMarker(target, marker) {
+  const norm = normalizeText(marker);
+  const matches = target.children.filter((c) => normalizeText(c.heading).includes(norm));
+  if (matches.length === 0) {
+    const available = target.children.map((c) => c.heading).join(", ") || "none";
+    throw new UserError(`No subsection matching "${marker}" found under target section (available: ${available})`);
+  }
+  if (matches.length > 1) {
+    throw new UserError(`Marker "${marker}" matched ${matches.length} subsections: ${matches.map((c) => c.heading).join(", ")}`);
+  }
+  return matches[0];
+}
+function requireMarker(block) {
+  if (!block.marker || block.marker.trim().length === 0) {
+    throw new UserError(`Action "${block.action}" requires a marker`);
+  }
+  return block.marker;
+}
+function applyOneAction(lines, target, block) {
+  const contentLines = block.content.length === 0 ? [""] : block.content.split("\n");
+  switch (block.action) {
+    case "append": {
+      lines.splice(target.bodyEnd, 0, ...contentLines);
+      return;
+    }
+    case "prepend": {
+      lines.splice(target.bodyStart, 0, ...contentLines);
+      return;
+    }
+    case "insert-after":
+    case "insert-before": {
+      const idx = findMarkerLine(lines, target.bodyStart, target.bodyEnd, requireMarker(block));
+      lines.splice(block.action === "insert-after" ? idx + 1 : idx, 0, ...contentLines);
+      return;
+    }
+    case "replace-section":
+    case "delete-section": {
+      const child = findChildByMarker(target, requireMarker(block));
+      const replacement = block.action === "replace-section" ? contentLines : [];
+      lines.splice(child.headingLine, child.bodyEnd - child.headingLine, ...replacement);
+      return;
+    }
+    default: {
+      const exhaustive = block.action;
+      throw new UserError(`Unknown patch action "${exhaustive}"`);
+    }
+  }
+}
+function applyPatchBlocks(skillMd, blocks) {
+  const lines = skillMd.split("\n");
+  for (const block of blocks) {
+    const bodyOffset = frontmatterOffset(lines);
+    const root = buildHeadingTree(lines, bodyOffset);
+    const segments = block.target ? splitHeadingPath(block.target) : [];
+    const target = resolveHeadingPath(root, segments);
+    applyOneAction(lines, target, block);
+  }
+  return lines.join("\n");
+}
+function renderExtendFile(meta) {
+  return [
+    "# SKILL.extend.md",
+    `# Extensions for: ${meta.skillName}`,
+    `# Generated: ${meta.generatedAt}`,
+    `# Refinement: ${meta.refinementId}`,
+    "",
+    `## EXTEND: ${meta.targetSection}`,
+    "<!-- ACTION: append -->",
+    meta.content,
+    ""
+  ].join("\n");
+}
+function renderConfigOverride(meta) {
+  const payload = {
+    skill: meta.skillName,
+    version: "1.0.0",
+    generated: meta.generatedAt,
+    config: meta.config
+  };
+  return `${JSON.stringify(payload, null, 2)}
+`;
+}
+function computeLcsDiff(a, b) {
+  const n = a.length;
+  const m = b.length;
+  const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i2 = n - 1; i2 >= 0; i2--) {
+    for (let j2 = m - 1; j2 >= 0; j2--) {
+      dp[i2][j2] = a[i2] === b[j2] ? dp[i2 + 1][j2 + 1] + 1 : Math.max(dp[i2 + 1][j2], dp[i2][j2 + 1]);
+    }
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ type: "context", line: a[i] });
+      i++;
+      j++;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      ops.push({ type: "remove", line: a[i] });
+      i++;
+    } else {
+      ops.push({ type: "add", line: b[j] });
+      j++;
+    }
+  }
+  while (i < n) {
+    ops.push({ type: "remove", line: a[i] });
+    i++;
+  }
+  while (j < m) {
+    ops.push({ type: "add", line: b[j] });
+    j++;
+  }
+  return ops;
+}
+function previewDiff(before, after, path) {
+  const a = before.split("\n");
+  const b = after.split("\n");
+  const ops = computeLcsDiff(a, b);
+  const lines = [`--- ${path}`, `+++ ${path}`];
+  for (const op of ops) {
+    const prefix = op.type === "add" ? "+" : op.type === "remove" ? "-" : " ";
+    lines.push(`${prefix}${op.line}`);
+  }
+  return lines.join("\n");
+}
+
+// src/commands/refine.ts
+var PRO_FEATURE_LABEL6 = "skill refinement";
+var REFINE_PROMPT_ASSET = "refine-prompt.md";
+function requireProFeature2() {
+  const status2 = proFeatureStatus(PRO_FEATURE_LABEL6);
+  if (!status2.enabled) {
+    throw new UserError(status2.notice ?? "refine is a Pro feature \u2014 set SKILL_FORGE_LICENSE or config.licenseKey to a valid license to unlock.");
+  }
+  if (status2.notice) console.error(`[skill-forge] ${status2.notice}`);
+}
+function isInteractive(json) {
+  return !json && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+}
+function emit(json, payload, renderText) {
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    renderText();
+  }
+}
+async function confirmYesNo(rl, question) {
+  const answer = (await rl.question(question)).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+async function confirmWrite(yes, json, prompt) {
+  if (yes) return true;
+  if (!isInteractive(json)) {
+    throw new UserError("refusing to write without confirmation \u2014 pass --yes, or run interactively.");
+  }
+  const rl = createInterface5({ input: process.stdin, output: process.stdout });
+  try {
+    return await confirmYesNo(rl, prompt);
+  } finally {
+    rl.close();
+  }
+}
+function resolveConfiguredRoot3(root) {
+  return resolvePath11(expandHome(root));
+}
+function isUnderRoot3(candidate, root) {
+  const rel = relative3(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute3(rel);
+}
+function sanitizeDiffForConsole(diff) {
+  return diff.split("\n").map((line) => sanitizeForMarkdown(line)).join("\n");
+}
+function resolveContentOption(options) {
+  if (options.content !== void 0) return options.content;
+  if (options.contentFile) return readFileSync15(resolvePath11(options.contentFile), "utf-8");
+  return void 0;
+}
+function validateCaptureOptions(options) {
+  if (!options.skill) throw new UserError("--skill is required");
+  assertPlainSkillName(options.skill);
+  if (!options.category || !isRefinementCategory(options.category)) {
+    throw new UserError(`--category is required and must be one of: trigger, content, hook, tool, pattern, config, new`);
+  }
+  if (!options.target) throw new UserError("--target is required (heading-path selector or a short description for whole-file override types)");
+  if (!options.overrideType || !isOverrideType(options.overrideType)) {
+    throw new UserError("--override-type is required and must be one of: patch, extend, config, full, hook, script, new");
+  }
+  if (!options.expected) throw new UserError("--expected is required");
+  if (!options.actual) throw new UserError("--actual is required");
+  const scopeRaw = options.scope ?? "local";
+  if (scopeRaw !== "local" && scopeRaw !== "shared") {
+    throw new UserError('--scope must be "local" or "shared"');
+  }
+  let action;
+  if (options.overrideType === "patch") {
+    if (!options.action || !isPatchAction(options.action)) {
+      throw new UserError(
+        "--action is required for --override-type patch (one of: append, prepend, replace-section, insert-after, insert-before, delete-section)"
+      );
+    }
+    action = options.action;
+  }
+  return {
+    skill: options.skill,
+    category: options.category,
+    target: options.target,
+    overrideType: options.overrideType,
+    action,
+    marker: options.marker,
+    expected: options.expected,
+    actual: options.actual,
+    example: options.example,
+    outcome: options.outcome,
+    rootCause: options.rootCause,
+    patternId: options.patternId,
+    scope: scopeRaw,
+    dryRun: options.dryRun ?? false,
+    json: options.json ?? false,
+    yes: options.yes ?? false,
+    handoff: options.handoff ?? false
+  };
+}
+function renderPatchActionBlock(params) {
+  const lines = [];
+  lines.push(params.marker ? `<!-- ACTION: ${params.action} "${params.marker}" -->` : `<!-- ACTION: ${params.action} -->`);
+  lines.push(`<!-- TARGET: ${params.target} -->`);
+  lines.push(params.content);
+  return lines.join("\n");
+}
+function defaultOverrideFilename(overrideType) {
+  switch (overrideType) {
+    case "full":
+      return "SKILL.md";
+    case "hook":
+      return "hooks/refinement.sh";
+    case "script":
+      return "scripts/refinement.sh";
+    default: {
+      const exhaustive = overrideType;
+      throw new Error(`internal error: defaultOverrideFilename called for non-whole-file override type "${exhaustive}"`);
+    }
+  }
+}
+function renderCaptureArtifact(opts, content, refinementId, generatedAt, existingContent) {
+  switch (opts.overrideType) {
+    case "patch": {
+      if (!content) throw new UserError("--content or --content-file is required for --override-type patch");
+      const block = renderPatchActionBlock({ action: opts.action, marker: opts.marker, target: opts.target, content });
+      const preamble = `# SKILL.patch.md
+# Patches for: ${opts.skill}
+`;
+      const base = existingContent.trim().length > 0 ? existingContent.trimEnd() : preamble.trimEnd();
+      return { relPath: "SKILL.patch.md", content: `${base}
+
+${block}
+` };
+    }
+    case "extend":
+    case "new": {
+      if (!content) throw new UserError(`--content or --content-file is required for --override-type ${opts.overrideType}`);
+      const rendered = renderExtendFile({ skillName: opts.skill, refinementId, generatedAt, targetSection: opts.target, content });
+      const combined = existingContent.trim().length > 0 ? `${existingContent.trimEnd()}
+
+${rendered}` : rendered;
+      return { relPath: "SKILL.extend.md", content: combined };
+    }
+    case "config": {
+      if (!content) throw new UserError("--content or --content-file (JSON object) is required for --override-type config");
+      let parsed;
+      try {
+        parsed = JSON.parse(content);
+      } catch (err) {
+        throw new UserError(`--content for --override-type config must be valid JSON: ${err.message}`);
+      }
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new UserError("--content for --override-type config must be a JSON object");
+      }
+      const rendered = renderConfigOverride({
+        skillName: opts.skill,
+        refinementId,
+        generatedAt,
+        config: parsed
+      });
+      return { relPath: "skill-config.json", content: rendered };
+    }
+    case "full":
+    case "hook":
+    case "script": {
+      if (!content) throw new UserError(`--content or --content-file is required for --override-type ${opts.overrideType}`);
+      return { relPath: opts.marker && opts.marker.trim().length > 0 ? opts.marker.trim() : defaultOverrideFilename(opts.overrideType), content };
+    }
+    default: {
+      const exhaustive = opts.overrideType;
+      throw new UserError(`unknown override type "${exhaustive}"`);
+    }
+  }
+}
+function ensureScopeDirSafe(scopeDir, resolvedCwd) {
+  let lst;
+  try {
+    lst = lstatSync3(scopeDir);
+  } catch {
+    lst = void 0;
+  }
+  if (lst?.isSymbolicLink()) {
+    throw new UserError(`refusing to write under ${scopeDir}: scope directory is a symlink`);
+  }
+  mkdirSync9(scopeDir, { recursive: true });
+  const real = resolveConfiguredRoot3(scopeDir);
+  const lexical = resolvePath11(scopeDir);
+  let realResolved;
+  try {
+    realResolved = realpathSync7(scopeDir);
+  } catch {
+    realResolved = real;
+  }
+  if (realResolved !== lexical) {
+    throw new UserError(`refusing to write under ${scopeDir}: path contains a symlink`);
+  }
+  if (!isUnderRoot3(realResolved, resolveConfiguredRoot3(resolvedCwd))) {
+    throw new UserError(`refusing to write under ${scopeDir}: resolves outside the project root ${resolvedCwd}`);
+  }
+  return realResolved;
+}
+function writeOverrideFile(scopeDir, relPath, content, resolvedCwd) {
+  const realScopeDir = ensureScopeDirSafe(scopeDir, resolvedCwd);
+  const destPath = join25(scopeDir, relPath);
+  const destDir = dirname11(destPath);
+  mkdirSync9(destDir, { recursive: true });
+  const realDestDir = realpathSync7(destDir);
+  if (!isUnderRoot3(realDestDir, realScopeDir)) {
+    throw new UserError(`refusing to write ${destPath}: resolves outside scope directory ${scopeDir}`);
+  }
+  let destLst;
+  try {
+    destLst = lstatSync3(destPath);
+  } catch {
+    destLst = void 0;
+  }
+  if (destLst?.isSymbolicLink()) {
+    throw new UserError(`refusing to write ${destPath}: destination is a symlink`);
+  }
+  writeFileSync9(destPath, content, { mode: 384 });
+  chmodSync(destPath, 384);
+  return destPath;
+}
+async function refineCaptureCommand(rawOptions = {}) {
+  requireProFeature2();
+  const opts = validateCaptureOptions(rawOptions);
+  const config = loadConfig();
+  const cwd = process.cwd();
+  const scopes = resolveScopes(config, cwd, opts.skill);
+  const scopeDir = opts.scope === "local" ? scopes.local.dir : scopes.shared.dir;
+  const content = resolveContentOption(rawOptions);
+  const now = /* @__PURE__ */ new Date();
+  const existingIds = new Set(readRefinementsStore().records.map((r) => r.id));
+  const refinementId = generateRefinementId(existingIds, now, defaultRandomHex);
+  const preview = renderCaptureArtifactPreview(opts, content, refinementId, now.toISOString(), scopeDir);
+  if (opts.dryRun) {
+    emit(opts.json, { dryRun: true, path: preview.destPath, diff: preview.diff }, () => {
+      console.log(`[skill-forge] refine capture \u2014 ${opts.overrideType} override for "${sanitizeForMarkdown(opts.skill)}" at ${opts.scope} scope`);
+      console.log(sanitizeDiffForConsole(preview.diff));
+    });
+    return;
+  }
+  if (!opts.json) {
+    console.log(`[skill-forge] refine capture \u2014 ${opts.overrideType} override for "${sanitizeForMarkdown(opts.skill)}" at ${opts.scope} scope`);
+    console.log(sanitizeDiffForConsole(preview.diff));
+  }
+  const proceed = await confirmWrite(opts.yes, opts.json, `
+Write ${preview.destPath}? [y/N] `);
+  if (!proceed) {
+    emit(opts.json, { written: false, cancelled: true, path: preview.destPath }, () => {
+      console.log("[skill-forge] capture cancelled \u2014 nothing written.");
+    });
+    return;
+  }
+  const writtenPath = writeOverrideFile(scopeDir, preview.relPath, preview.content, cwd);
+  let result;
+  try {
+    result = recordRefinement(
+      {
+        skill: opts.skill,
+        category: opts.category,
+        overrideType: opts.overrideType,
+        targetSection: opts.target,
+        expectedBehavior: opts.expected,
+        actualBehavior: opts.actual,
+        example: opts.example,
+        desiredOutcome: opts.outcome,
+        rootCause: opts.rootCause,
+        project: cwd,
+        projectRoot: cwd,
+        patchAction: opts.action,
+        patchMarker: opts.marker,
+        patchContent: content,
+        status: "applied",
+        scope: opts.scope,
+        patternId: opts.patternId
+      },
+      { now, id: refinementId }
+    );
+  } catch (err) {
+    throw new UserError(`wrote the override artifact at ${writtenPath}, but recording the refinement in the store failed: ${err.message}`);
+  }
+  emit(
+    opts.json,
+    { written: true, path: writtenPath, refinementId: result.refinement.id, patternId: result.pattern.id, patternBecameReady: result.patternBecameReady },
+    () => {
+      console.log(`[skill-forge] wrote ${writtenPath}`);
+      console.log(`[skill-forge] recorded refinement ${result.refinement.id} -> pattern ${result.pattern.id} (status: ${result.pattern.status})`);
+      if (result.patternBecameReady) {
+        console.log(`[skill-forge] pattern ${result.pattern.id} is now READY (seen in a second project) \u2014 consider \`skill-forge refine promote ${result.pattern.id}\``);
+      }
+    }
+  );
+  if (opts.handoff) {
+    runHandoff(config, writtenPath, { promptAsset: REFINE_PROMPT_ASSET, log: opts.json ? console.error : console.log });
+  }
+}
+function renderCaptureArtifactPreview(opts, content, refinementId, generatedAt, scopeDir) {
+  const probeRelPath = opts.overrideType === "patch" ? "SKILL.patch.md" : opts.overrideType === "extend" || opts.overrideType === "new" ? "SKILL.extend.md" : void 0;
+  const probePath = probeRelPath ? join25(scopeDir, probeRelPath) : void 0;
+  const existingContent = probePath && existsSync20(probePath) ? readFileSync15(probePath, "utf-8") : "";
+  const rendered = renderCaptureArtifact(opts, content, refinementId, generatedAt, existingContent);
+  const relPath = rendered.relPath;
+  const destPath = join25(scopeDir, relPath);
+  const before = existsSync20(destPath) ? readFileSync15(destPath, "utf-8") : "";
+  const diff = previewDiff(before, rendered.content, destPath);
+  return { relPath, content: rendered.content, destPath, diff };
+}
+async function refineListCommand(options = {}) {
+  requireProFeature2();
+  const { records } = readRefinementsStore();
+  let rows = records;
+  if (options.skill) rows = rows.filter((r) => r.skill === options.skill);
+  if (options.project) rows = rows.filter((r) => r.project === options.project || r.projectRoot === resolvePath11(options.project));
+  if (options.status) {
+    if (!isRefinementStatus(options.status)) {
+      throw new UserError("--status must be one of: pending, applied, generalized");
+    }
+    rows = rows.filter((r) => r.status === options.status);
+  }
+  const filtered = Boolean(options.skill || options.project || options.status);
+  emit(options.json, { records: rows }, () => {
+    if (rows.length === 0) {
+      if (filtered && records.length > 0) {
+        console.log(`[skill-forge] no refinements match the given filter(s) (${records.length} total recorded).`);
+      } else {
+        console.log("[skill-forge] no refinements recorded.");
+      }
+      return;
+    }
+    console.log(`[skill-forge] ${rows.length} refinement(s):`);
+    for (const r of rows) {
+      console.log(
+        `  ${r.id}  ${sanitizeForMarkdown(r.skill)}  [${r.category}/${r.overrideType}]  status=${r.status}  pattern=${r.patternId ?? "(none)"}  ${r.createdAt}`
+      );
+    }
+  });
+}
+async function refinePatternsCommand(options = {}) {
+  requireProFeature2();
+  const { records } = readPatternsStore();
+  let rows = records;
+  if (options.status) {
+    if (!isPatternStatus(options.status)) {
+      throw new UserError("--status must be one of: tracking, ready, generalized, dismissed");
+    }
+    rows = rows.filter((p) => p.status === options.status);
+  }
+  if (options.skill) rows = rows.filter((p) => p.affectedSkills.includes(options.skill));
+  if (options.project) {
+    const resolvedProject = resolvePath11(options.project);
+    rows = rows.filter((p) => p.occurrences.some((o) => o.projectRealpath === resolvedProject));
+  }
+  const filtered = Boolean(options.skill || options.project || options.status);
+  emit(options.json, { records: rows.map((p) => ({ ...p, count: patternCount(p) })) }, () => {
+    if (rows.length === 0) {
+      if (filtered && records.length > 0) {
+        console.log(`[skill-forge] no patterns match the given filter(s) (${records.length} total recorded).`);
+      } else {
+        console.log("[skill-forge] no patterns recorded.");
+      }
+      return;
+    }
+    console.log(`[skill-forge] ${rows.length} pattern(s):`);
+    for (const p of rows) {
+      console.log(
+        `  ${p.id}  ${sanitizeForMarkdown(p.name)}  status=${p.status}  count=${patternCount(p)}  skills=${p.affectedSkills.map(sanitizeForMarkdown).join(", ")}`
+      );
+    }
+  });
+}
+function renderInventoryLine(row) {
+  const present = [
+    row.skillMd ? "SKILL.md" : void 0,
+    row.patchMd ? "SKILL.patch.md" : void 0,
+    row.extendMd ? "SKILL.extend.md" : void 0,
+    row.configJson ? "skill-config.json" : void 0,
+    row.hooksDir ? "hooks/" : void 0,
+    row.scriptsDir ? "scripts/" : void 0
+  ].filter((v) => Boolean(v));
+  return `  [${row.scope}] ${row.dir}${row.dirExists ? "" : " (missing)"} \u2014 ${present.length > 0 ? present.join(", ") : "(no override files)"}`;
+}
+async function refineWhichCommand(skill, options = {}) {
+  requireProFeature2();
+  if (!skill) throw new UserError("a skill name is required: skill-forge refine which <skill>");
+  const config = loadConfig();
+  const cwd = process.cwd();
+  const scopes = resolveScopes(config, cwd, skill, options.userRoot);
+  const inventory = inventoryAllScopes(scopes);
+  emit(options.json, { scopes, inventory }, () => {
+    console.log(`[skill-forge] refine which "${sanitizeForMarkdown(skill)}" \u2014 resolution order (highest precedence first):`);
+    for (const row of inventory) console.log(renderInventoryLine(row));
+    if (!scopes.user.resolved) {
+      console.log(
+        `  [user] ambiguous \u2014 candidates: ${scopes.user.candidates.map((c) => c.root).join(", ") || "(none configured)"} (pass --user-root to disambiguate)`
+      );
+    }
+  });
+}
+function writePostWriteSidecar(backupId, files) {
+  const sidecar = { schemaVersion: 1, files };
+  const dir = join25(getBackupsDir(), backupId);
+  mkdirSync9(dir, { recursive: true });
+  writeFileSync9(join25(dir, "post.json"), JSON.stringify(sidecar, null, 2) + "\n", { mode: 384 });
+}
+function readPostWriteSidecar(backupId) {
+  const path = join25(getBackupsDir(), backupId, "post.json");
+  if (!existsSync20(path)) return { hashes: /* @__PURE__ */ new Map(), status: "missing" };
+  let raw;
+  try {
+    raw = readFileSync15(path, "utf-8");
+  } catch {
+    return { hashes: /* @__PURE__ */ new Map(), status: "unreadable" };
+  }
+  const hashes = /* @__PURE__ */ new Map();
+  try {
+    const parsed = JSON.parse(raw);
+    for (const f of parsed.files ?? []) {
+      if (typeof f !== "object" || f === null || typeof f.path !== "string" || typeof f.sha256 !== "string") {
+        throw new Error("malformed post.json files entry");
+      }
+      hashes.set(f.path, f.sha256);
+    }
+  } catch {
+    return { hashes: /* @__PURE__ */ new Map(), status: "corrupt" };
+  }
+  return { hashes, status: "ok" };
+}
+async function refinePromoteCommand(patternId, options = {}) {
+  requireProFeature2();
+  if (!patternId) throw new UserError("a pattern id is required: skill-forge refine promote <pattern-id>");
+  const patternsStore = readPatternsStore();
+  const pattern = patternsStore.records.find((p) => p.id === patternId);
+  if (!pattern) throw new UserError(`no pattern with id: ${patternId}`);
+  if (pattern.status === "generalized" && !options.force) {
+    throw new UserError(`pattern ${patternId} is already generalized (backup ${pattern.generalizedBackupId ?? "(unknown)"}) \u2014 pass --force to re-promote.`);
+  }
+  if (pattern.status !== "ready" && pattern.status !== "generalized" && !options.force) {
+    throw new UserError(`pattern ${patternId} is not ready (status: ${pattern.status}) \u2014 pass --force to promote anyway.`);
+  }
+  const skill = pattern.affectedSkills[0];
+  if (!skill) throw new UserError(`pattern ${patternId} has no affected skills recorded`);
+  assertPlainSkillName(skill);
+  const config = loadConfig();
+  const cwd = process.cwd();
+  const scopes = resolveScopes(config, cwd, skill, options.userRoot);
+  if (!scopes.user.resolved) {
+    throw new UserError(
+      `cannot resolve a single user scope for skill "${skill}" \u2014 candidates: ${scopes.user.candidates.map((c) => c.root).join(", ") || "(none configured)"}. Pass --user-root to disambiguate.`
+    );
+  }
+  const skillDir = scopes.user.dir;
+  const resolvedUserRoot = resolveConfiguredRoot3(scopes.user.root);
+  let realUserRoot;
+  try {
+    realUserRoot = realpathSync7(resolvedUserRoot);
+  } catch {
+    realUserRoot = resolvedUserRoot;
+  }
+  let realSkillDir;
+  try {
+    realSkillDir = realpathSync7(skillDir);
+  } catch {
+    realSkillDir = resolvePath11(skillDir);
+  }
+  if (!isUnderRoot3(realSkillDir, realUserRoot)) {
+    throw new UserError(`refusing to promote: resolved skill directory ${skillDir} is outside the configured user scope root ${scopes.user.root}`);
+  }
+  const skillMdPath = join25(skillDir, "SKILL.md");
+  if (!existsSync20(skillMdPath)) {
+    throw new UserError(`user-scope SKILL.md not found at ${skillMdPath} \u2014 refusing to promote against a missing base skill.`);
+  }
+  const refinementsStore = readRefinementsStore();
+  const patternRefinements = refinementsStore.records.filter((r) => pattern.refinementIds.includes(r.id));
+  const representative = patternRefinements[patternRefinements.length - 1];
+  if (!representative) throw new UserError(`pattern ${patternId} has no recorded refinements to promote`);
+  let block;
+  if (representative.overrideType === "patch" && representative.patchAction && representative.patchContent) {
+    block = { action: representative.patchAction, marker: representative.patchMarker, target: representative.targetSection, content: representative.patchContent };
+  } else if ((representative.overrideType === "extend" || representative.overrideType === "new") && representative.patchContent) {
+    block = { action: "append", target: representative.targetSection, content: representative.patchContent };
+  } else {
+    throw new UserError(
+      `pattern ${patternId}'s representative refinement is a '${representative.overrideType}' override \u2014 promote currently only materializes patch/extend/new-type patterns against the user-scope SKILL.md; other override types must be merged manually.`
+    );
+  }
+  const before = readFileSync15(skillMdPath, "utf-8");
+  const after = applyPatchBlocks(before, [block]);
+  const diff = previewDiff(before, after, skillMdPath);
+  if (options.dryRun) {
+    emit(options.json, { dryRun: true, path: skillMdPath, diff }, () => {
+      console.log(`[skill-forge] refine promote ${patternId} -> ${skillMdPath}`);
+      console.log(sanitizeDiffForConsole(diff));
+    });
+    return;
+  }
+  if (!options.json) {
+    console.log(`[skill-forge] refine promote ${patternId} -> ${skillMdPath}`);
+    console.log(sanitizeDiffForConsole(diff));
+  }
+  const proceed = await confirmWrite(options.yes, options.json, `
+Promote pattern ${patternId} into ${skillMdPath}? [y/N] `);
+  if (!proceed) {
+    emit(options.json, { promoted: false, cancelled: true }, () => {
+      console.log("[skill-forge] promote cancelled \u2014 nothing written.");
+    });
+    return;
+  }
+  const backup = createBackup([skillMdPath]);
+  const tempPath = `${skillMdPath}.tmp-${randomUUID4()}`;
+  try {
+    writeFileSync9(tempPath, after, "utf-8");
+    renameSync5(tempPath, skillMdPath);
+  } catch (err) {
+    rmSync7(tempPath, { force: true });
+    throw err;
+  }
+  try {
+    const postSha256 = createHash3("sha256").update(readFileSync15(skillMdPath)).digest("hex");
+    writePostWriteSidecar(backup.id, [{ path: skillMdPath, sha256: postSha256 }]);
+    markGeneralized(patternId, backup.id);
+    const skillsRoot = resolveConfiguredRoot3(scopes.user.root);
+    appendProvenance(
+      {
+        name: skill,
+        source: `skill-forge refine (${patternId})`,
+        verb: "DEFER",
+        target: skillMdPath,
+        took: `applied a ${block.action} patch materializing pattern ${patternId}`,
+        notes: `generalized from ${patternId} via skill-forge refine`
+      },
+      skillsRoot
+    );
+  } catch (err) {
+    throw new UserError(
+      `the user-scope skill was updated at ${skillMdPath} (backup ${backup.id}), but recording post-write verification and/or pattern/provenance state failed: ${err.message}`
+    );
+  }
+  emit(options.json, { promoted: true, path: skillMdPath, backupId: backup.id }, () => {
+    console.log(`[skill-forge] promoted pattern ${patternId} -> ${skillMdPath} (backup: ${backup.id})`);
+  });
+}
+function assertBackupDirContained(backupId) {
+  const backupsDir = getBackupsDir();
+  if (!existsSync20(backupsDir)) return;
+  const realBackupsDir = realpathSync7(backupsDir);
+  const backupDir = join25(backupsDir, backupId);
+  if (!existsSync20(backupDir)) return;
+  const realBackupDir = realpathSync7(backupDir);
+  if (!isUnderRoot3(realBackupDir, realBackupsDir)) {
+    throw new UserError(`refusing rollback: backup id "${backupId}" resolves outside the backups directory`);
+  }
+}
+function resolveTargetRealPath(path) {
+  let lexicalAncestor = resolvePath11(path);
+  while (true) {
+    try {
+      const real = realpathSync7(lexicalAncestor);
+      const remainder = relative3(lexicalAncestor, resolvePath11(path));
+      return remainder === "" ? real : join25(real, remainder);
+    } catch {
+      const parent = dirname11(lexicalAncestor);
+      if (parent === lexicalAncestor) return resolvePath11(path);
+      lexicalAncestor = parent;
+    }
+  }
+}
+function assertManifestPathsWithinRoots(manifest, config) {
+  if (config.skillsRoots.length === 0) {
+    throw new UserError(`refusing rollback ${manifest.id}: no skillsRoots are configured \u2014 cannot verify the backup's file paths are within a trusted skills root.`);
+  }
+  const roots = config.skillsRoots.map((root) => {
+    const resolved = resolveConfiguredRoot3(root);
+    try {
+      return realpathSync7(resolved);
+    } catch {
+      return resolved;
+    }
+  });
+  for (const file of manifest.files) {
+    const resolvedTarget = resolveTargetRealPath(file.path);
+    const withinAnyRoot = roots.some((root) => isUnderRoot3(resolvedTarget, root));
+    if (!withinAnyRoot) {
+      throw new UserError(`refusing rollback ${manifest.id}: backup manifest references a path outside configured skills roots \u2014 ${file.path}`);
+    }
+  }
+}
+function assertNoSymlinkLeaves(manifest) {
+  for (const file of manifest.files) {
+    let lst;
+    try {
+      lst = lstatSync3(file.path);
+    } catch {
+      lst = void 0;
+    }
+    if (lst?.isSymbolicLink()) {
+      throw new UserError(`refusing rollback ${manifest.id}: backup manifest path is currently a symlink \u2014 refusing to follow or overwrite it: ${file.path}`);
+    }
+  }
+}
+function findLexicalRoot(filePath, config) {
+  const lexicalTarget = resolvePath11(filePath);
+  for (const root of config.skillsRoots) {
+    const rootLexical = resolveConfiguredRoot3(root);
+    const rel = relative3(rootLexical, lexicalTarget);
+    if (rel !== "" && (rel === ".." || rel.startsWith(`..${sep2}`) || isAbsolute3(rel))) continue;
+    let rootReal;
+    try {
+      rootReal = realpathSync7(rootLexical);
+    } catch {
+      rootReal = rootLexical;
+    }
+    return { rootLexical, rootReal };
+  }
+  throw new UserError(`refusing to operate on ${filePath}: does not resolve lexically under any configured skills root`);
+}
+function walkRealComponents(filePath, config, createMissing) {
+  const { rootLexical, rootReal } = findLexicalRoot(filePath, config);
+  const relPath = relative3(rootLexical, resolvePath11(filePath));
+  const components = relPath.split(sep2).filter((c) => c.length > 0);
+  if (components.length === 0) {
+    throw new UserError(`refusing to operate on ${filePath}: resolves to the skills root itself`);
+  }
+  const leafComponent = components[components.length - 1];
+  const dirComponents = components.slice(0, -1);
+  let current = rootReal;
+  for (const component of dirComponents) {
+    if (current === void 0) break;
+    const next = join25(current, component);
+    let lst;
+    try {
+      lst = lstatSync3(next);
+    } catch {
+      lst = void 0;
+    }
+    if (lst === void 0) {
+      if (!createMissing) {
+        current = void 0;
+        continue;
+      }
+      mkdirSync9(next);
+      current = next;
+      continue;
+    }
+    if (lst.isSymbolicLink()) {
+      throw new UserError(`refusing to operate on ${filePath}: intermediate path component is a symlink \u2014 ${next}`);
+    }
+    if (!lst.isDirectory()) {
+      throw new UserError(`refusing to operate on ${filePath}: intermediate path component is not a directory \u2014 ${next}`);
+    }
+    current = next;
+  }
+  return { parentReal: current, leafComponent, rootReal };
+}
+function safeRestoreWrite(filePath, contentBuffer, mode, config) {
+  const { parentReal, leafComponent, rootReal } = walkRealComponents(filePath, config, true);
+  if (parentReal === void 0) {
+    throw new UserError(`refusing to restore ${filePath}: could not establish a real parent directory`);
+  }
+  const finalPath = join25(parentReal, leafComponent);
+  if (!isUnderRoot3(finalPath, rootReal)) {
+    throw new UserError(`refusing to restore ${filePath}: resolves outside root ${rootReal}`);
+  }
+  let leafLst;
+  try {
+    leafLst = lstatSync3(finalPath);
+  } catch {
+    leafLst = void 0;
+  }
+  if (leafLst?.isSymbolicLink()) {
+    throw new UserError(`refusing to restore ${filePath}: it is now a symlink \u2014 refusing to follow or overwrite it.`);
+  }
+  const tempPath = `${finalPath}.tmp-${randomUUID4()}`;
+  try {
+    writeFileSync9(tempPath, contentBuffer);
+    chmodSync(tempPath, mode);
+    renameSync5(tempPath, finalPath);
+  } catch (err) {
+    rmSync7(tempPath, { force: true });
+    throw err;
+  }
+}
+function safeDeleteTombstone(filePath, config) {
+  const { parentReal, leafComponent, rootReal } = walkRealComponents(filePath, config, false);
+  if (parentReal === void 0) return;
+  const finalPath = join25(parentReal, leafComponent);
+  if (!isUnderRoot3(finalPath, rootReal)) {
+    throw new UserError(`refusing to delete ${filePath}: resolves outside root ${rootReal}`);
+  }
+  let leafLst;
+  try {
+    leafLst = lstatSync3(finalPath);
+  } catch {
+    leafLst = void 0;
+  }
+  if (leafLst === void 0) return;
+  if (leafLst.isSymbolicLink()) {
+    throw new UserError(`refusing to delete ${filePath}: it is now a symlink \u2014 refusing to follow or overwrite it.`);
+  }
+  rmSync7(finalPath, { force: true });
+}
+async function refineRollbackCommand(backupId, options = {}) {
+  requireProFeature2();
+  if (!backupId) throw new UserError("a backup id is required: skill-forge refine rollback <backup-id>");
+  if (!isValidBackupId(backupId)) {
+    throw new UserError(`invalid backup id "${backupId}" \u2014 expected the format produced by \`skill-forge refine promote\` (e.g. 20260720T142305Z-a1b2)`);
+  }
+  assertBackupDirContained(backupId);
+  const manifest = readBackupManifest(backupId);
+  const config = loadConfig();
+  assertManifestPathsWithinRoots(manifest, config);
+  assertNoSymlinkLeaves(manifest);
+  const warnings = [];
+  const sidecar = readPostWriteSidecar(backupId);
+  if (sidecar.status !== "ok") {
+    const reason = sidecar.status;
+    if (!options.force) {
+      throw new UserError(
+        `refusing rollback ${backupId}: post-write verification data (post.json) is ${reason} \u2014 cannot confirm the current file state matches what was promoted. Pass --force to override.`
+      );
+    }
+    warnings.push(`post-write verification data for backup ${backupId} is ${reason} \u2014 restoring without hash verification (--force).`);
+  }
+  const mismatches = [];
+  for (const file of manifest.files) {
+    const expected = sidecar.hashes.get(file.path);
+    if (expected === void 0) continue;
+    const currentSha256 = existsSync20(file.path) ? createHash3("sha256").update(readFileSync15(file.path)).digest("hex") : null;
+    if (currentSha256 !== expected) mismatches.push(file.path);
+  }
+  if (mismatches.length > 0 && !options.force) {
+    throw new UserError(
+      `refusing rollback ${backupId}: current file(s) differ from the state recorded right after promote \u2014 ${mismatches.join(", ")} (pass --force to override)`
+    );
+  }
+  const fileList = manifest.files.map((file) => `  ${file.existed ? "restore" : "delete"} ${file.path}`).join("\n");
+  if (!options.json) {
+    console.log(`[skill-forge] refine rollback ${backupId} \u2014 restoring ${manifest.files.length} file(s):`);
+    console.log(fileList);
+    for (const w of warnings) console.log(`[skill-forge] warning: ${w}`);
+  }
+  const proceed = await confirmWrite(options.yes, options.json, `
+Roll back backup ${backupId}? Affected files:
+${fileList}
+[y/N] `);
+  if (!proceed) {
+    emit(options.json, { rolledBack: false, cancelled: true, backupId }, () => {
+      console.log("[skill-forge] rollback cancelled \u2014 nothing restored.");
+    });
+    return;
+  }
+  const restored = [];
+  for (const file of manifest.files) {
+    try {
+      if (!file.existed) {
+        safeDeleteTombstone(file.path, config);
+      } else {
+        safeRestoreWrite(file.path, Buffer.from(file.contentBase64 ?? "", "base64"), file.mode ?? 420, config);
+      }
+      restored.push(file.path);
+    } catch (err) {
+      const remaining = manifest.files.slice(restored.length + 1).map((f) => f.path);
+      throw new UserError(
+        `rollback ${backupId} failed partway through: restored ${restored.length} of ${manifest.files.length} file(s) (${restored.join(", ") || "(none)"}), then failed on ${file.path}: ${err.message}. NOT restored: ${[file.path, ...remaining].join(", ")}.`
+      );
+    }
+  }
+  const patternsStore = readPatternsStore();
+  const pattern = patternsStore.records.find((p) => p.generalizedBackupId === backupId);
+  if (pattern) {
+    pattern.status = "ready";
+    pattern.generalizedAt = void 0;
+    pattern.generalizedBackupId = void 0;
+    writePatternsStore(patternsStore);
+  }
+  emit(options.json, { rolledBack: true, backupId, patternReset: pattern?.id, warnings }, () => {
+    console.log(`[skill-forge] rollback complete for ${backupId}${pattern ? ` (pattern ${pattern.id} reset to ready)` : ""}`);
+    for (const w of warnings) console.log(`[skill-forge] warning: ${w}`);
+  });
+}
+
 // src/cli.ts
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
@@ -5064,6 +6564,13 @@ program.command("ingest").description(
 ).option("--list", "print pending queue entries and exit \u2014 no handoff").option("--json", "with --list: print pending entries as JSON").action(ingest);
 var queue = program.command("queue").description("Manage the pending-ingestion queue (Pro)");
 queue.command("close <id>").description("Close a queue entry after the decide pass \u2014 agents use this instead of hand-editing queue.json").requiredOption("--status <status>", 'final status: "ingested" or "dismissed"').action(queueClose);
+var refine = program.command("refine").description("Capture, apply, and generalize improvements to installed skills from usage feedback (Pro)");
+refine.command("capture", { isDefault: true }).description("Record a refinement and write a project-scope override artifact (never touches the base skill)").option("--skill <name>", "target skill name").option("--category <cat>", "trigger|content|hook|tool|pattern|config|new").option("--target <section>", 'heading path or file the refinement targets, e.g. "Hooks > duplicate-check"').option("--override-type <type>", "patch|extend|config|full|hook|script|new").option("--action <action>", "patch action: append|prepend|replace-section|insert-after|insert-before|delete-section").option("--marker <text>", "marker text for insert-* / replace-section / delete-section (filename for full|hook|script)").option("--content <text>", "override content inline").option("--content-file <file>", "read override content from a file").option("--expected <text>", "expected behavior").option("--actual <text>", "actual observed behavior").option("--example <text>", "concrete example of the gap").option("--outcome <text>", "desired outcome").option("--root-cause <text>", "root cause per the gap analysis").option("--pattern-id <id>", "join an existing pattern (PAT-xxxx) instead of fingerprint matching").option("--scope <scope>", 'where to write the artifact: "local" (.claude/skills, default) or "shared" (./skills)').option("--dry-run", "preview the artifact diff; write nothing").option("--json", "print the result as JSON").option("-y, --yes", "skip the interactive confirm; never implies --handoff").option("--handoff", "authorizes launching the configured agent with the bundled refine prompt").action(refineCaptureCommand);
+refine.command("list").description("Show refinement history from the user-scope store").option("--status <status>", "filter by refinement status").option("--skill <name>", "filter by skill").option("--project <name>", "filter by project").option("--json", "print records as JSON").action(refineListCommand);
+refine.command("patterns").description("Review tracked patterns and the generalization queue").option("--status <status>", "filter: tracking|ready|generalized|dismissed").option("--skill <name>", "filter by affected skill").option("--project <name>", "filter by project").option("--json", "print patterns as JSON").action(refinePatternsCommand);
+refine.command("which <skill>").description("Print override-scope resolution order and which override files exist at each scope").option("--user-root <dir>", "explicit user-scope skills root").option("--json", "print the resolution as JSON").action(refineWhichCommand);
+refine.command("promote <pattern-id>").description("Materialize a READY pattern into the user-scope skill default (backup + manifest first)").option("--force", "promote a pattern that is not READY").option("--dry-run", "preview the user-scope diff; write nothing").option("--user-root <dir>", "explicit user-scope skills root").option("--json", "print the result as JSON").option("-y, --yes", "skip the interactive confirm").action(refinePromoteCommand);
+refine.command("rollback <backup-id>").description("Restore a promotion backup (refuses if files changed since promotion unless --force)").option("--force", "restore even if current files differ from the post-promotion state").option("--json", "print the result as JSON").option("-y, --yes", "skip the interactive confirm").action(refineRollbackCommand);
 program.command("init").description("Detect installed agents and set gate targets, default promotion target, and handoff agent").option("--defaults", "non-interactive: use all detected agents as gate targets, the first as the default target").option("--list", "print detected agent skill roots and exit \u2014 no writes").action(init);
 try {
   await program.parseAsync();