@delfini/cli 0.1.2 → 0.2.1

package/dist/cli.cjs

@@ -33,10 +33,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// ../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.9_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
+// ../../node_modules/.pnpm/tsup@8.5.1_postcss@8.5.15_tsx@4.22.4_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
 var getImportMetaUrl, importMetaUrl;
 var init_cjs_shims = __esm({
-  "../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.9_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js"() {
+  "../../node_modules/.pnpm/tsup@8.5.1_postcss@8.5.15_tsx@4.22.4_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js"() {
     "use strict";
     getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
     importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
@@ -1957,231 +1957,16 @@ function describeError(err) {
 
 // src/commands/install.ts
 init_cjs_shims();
-var import_node_fs2 = require("fs");
-var import_node_path2 = require("path");
+var import_node_fs3 = require("fs");
+var import_node_path3 = require("path");
 var import_promises = require("readline/promises");
 var import_node_url = require("url");
 
-// src/trace.ts
+// src/doc-scope.ts
 init_cjs_shims();
 var import_node_fs = require("fs");
-var import_node_path = require("path");
-var TRACE_DIR_NAME = ".delfini-trace";
-var GITIGNORE_LINE = ".delfini-trace/";
-function ensureTraceDir(repoRoot) {
-  const tracePath = (0, import_node_path.join)(repoRoot, TRACE_DIR_NAME);
-  if ((0, import_node_fs.existsSync)(tracePath)) {
-    const stat = (0, import_node_fs.statSync)(tracePath);
-    if (!stat.isDirectory()) {
-      throw new Error(
-        `ensureTraceDir: ${tracePath} exists but is not a directory. Remove or rename it so the CLI can create the trace directory.`
-      );
-    }
-    return tracePath;
-  }
-  (0, import_node_fs.mkdirSync)(tracePath, { recursive: true });
-  return tracePath;
-}
-function appendToGitignore(repoRoot) {
-  const gitignorePath = (0, import_node_path.join)(repoRoot, ".gitignore");
-  const existed = (0, import_node_fs.existsSync)(gitignorePath);
-  const existingContent = existed ? (0, import_node_fs.readFileSync)(gitignorePath, "utf8") : "";
-  const lines = existingContent.split(/\r?\n/);
-  for (const line of lines) {
-    if (line.trim() === GITIGNORE_LINE) {
-      return { changed: false };
-    }
-  }
-  const useCRLF = existingContent.includes("\r\n");
-  const newline = useCRLF ? "\r\n" : "\n";
-  if (!existed || existingContent.length === 0) {
-    (0, import_node_fs.writeFileSync)(gitignorePath, `${GITIGNORE_LINE}${newline}`);
-    return { changed: true };
-  }
-  const endsWithNewline = existingContent.endsWith("\n");
-  const prefix = endsWithNewline ? "" : newline;
-  (0, import_node_fs.appendFileSync)(gitignorePath, `${prefix}${GITIGNORE_LINE}${newline}`);
-  return { changed: true };
-}
-function writeTraceFile(repoRoot, filename, content) {
-  validateBasename(filename);
-  const traceDir = ensureTraceDir(repoRoot);
-  const target = (0, import_node_path.join)(traceDir, filename);
-  (0, import_node_fs.writeFileSync)(target, content);
-  return target;
-}
-function validateBasename(filename) {
-  if (filename.length === 0) {
-    throw new Error("writeTraceFile: filename must not be empty");
-  }
-  if (filename === "." || filename === "..") {
-    throw new Error(`writeTraceFile: filename must not be "${filename}"`);
-  }
-  if (filename.includes("/") || filename.includes("\\")) {
-    throw new Error(
-      `writeTraceFile: filename must be a basename without path separators, got "${filename}"`
-    );
-  }
-}
-
-// src/commands/install.ts
-var InstallToolNotSupportedError = class extends Error {
-  code = "INSTALL_TOOL_NOT_SUPPORTED";
-  constructor(tool) {
-    super(
-      `delfini install: --tool '${tool}' is not supported. The Skill is Claude-only in V1 (design-spec NG2 / project-context "Skill \u2014 Out of Scope in V1 / V1.1: No multi-LLM-provider support \u2014 Claude-only by design"). Use --tool CLAUDE (the default).`
-    );
-    this.name = "InstallToolNotSupportedError";
-  }
-};
-var CLAUDE_MD_OPEN_MARKER = "<!-- delfini:auto-invoke-block-v1 -->";
-var CLAUDE_MD_CLOSE_MARKER = "<!-- /delfini:auto-invoke-block-v1 -->";
-var SKILL_RELATIVE_PATH = ".claude/skills/delfini/SKILL.md";
-var CLAUDE_MD_FILENAME = "CLAUDE.md";
-var SUPPORTED_TOOL = "CLAUDE";
-var TEMPLATES_DIR = resolveTemplatesDir();
-function resolveTemplatesDir() {
-  let dir = (0, import_node_path2.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
-  for (let i = 0; i < 5; i++) {
-    const candidate = (0, import_node_path2.resolve)(dir, "templates");
-    if ((0, import_node_fs2.existsSync)((0, import_node_path2.join)(candidate, "SKILL.md"))) {
-      return candidate;
-    }
-    const parent = (0, import_node_path2.dirname)(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  throw new Error("templates/ directory not found relative to the CLI module");
-}
-async function runInstall(targetPath, options) {
-  const tool = options?.tool ?? SUPPORTED_TOOL;
-  const logger = options?.logger ?? console;
-  if (tool !== SUPPORTED_TOOL) {
-    throw new InstallToolNotSupportedError(tool);
-  }
-  const resolvedTarget = (0, import_node_path2.resolve)(process.cwd(), targetPath);
-  const repoRoot = await getRepoRoot(resolvedTarget);
-  writeSkillTemplate(repoRoot, logger);
-  await applyAutoInvokeDecision(repoRoot, logger, options?.confirmAutoInvoke);
-  appendGitignoreLine(repoRoot, logger);
-}
-function parseYesNo(answer) {
-  const normalised = answer.trim().toLowerCase();
-  return normalised === "y" || normalised === "yes";
-}
-async function applyAutoInvokeDecision(repoRoot, logger, confirmAutoInvoke) {
-  const decision = await resolveAutoInvoke(confirmAutoInvoke);
-  if (decision === "yes") {
-    appendClaudeMdBlock(repoRoot, logger);
-  } else if (decision === "no") {
-    stripClaudeMdBlock(repoRoot, logger);
-  } else {
-    const target = (0, import_node_path2.join)(repoRoot, CLAUDE_MD_FILENAME);
-    log(logger, `CLAUDE.md \u2192 ${target} (non-interactive shell: auto-invoke prompt skipped, no change)`);
-  }
-}
-async function resolveAutoInvoke(confirmAutoInvoke) {
-  if (confirmAutoInvoke) {
-    return await confirmAutoInvoke() ? "yes" : "no";
-  }
-  if (!process.stdin.isTTY) {
-    return "skip";
-  }
-  return await promptAutoInvoke() ? "yes" : "no";
-}
-async function promptAutoInvoke() {
-  const rl = (0, import_promises.createInterface)({ input: process.stdin, output: process.stdout });
-  try {
-    const answer = await rl.question("Auto-invoke /delfini on PR creation? (y/n) ");
-    return parseYesNo(answer);
-  } finally {
-    rl.close();
-  }
-}
-function writeSkillTemplate(repoRoot, logger) {
-  const target = (0, import_node_path2.join)(repoRoot, SKILL_RELATIVE_PATH);
-  const templateSource = (0, import_node_path2.join)(TEMPLATES_DIR, "SKILL.md");
-  const content = (0, import_node_fs2.readFileSync)(templateSource);
-  (0, import_node_fs2.mkdirSync)((0, import_node_path2.dirname)(target), { recursive: true });
-  (0, import_node_fs2.writeFileSync)(target, content);
-  log(logger, `SKILL.md \u2192 ${target}`);
-}
-function appendClaudeMdBlock(repoRoot, logger) {
-  const target = (0, import_node_path2.join)(repoRoot, CLAUDE_MD_FILENAME);
-  const blockSource = (0, import_node_path2.join)(TEMPLATES_DIR, "claude-md-append-block.txt");
-  const body = (0, import_node_fs2.readFileSync)(blockSource, "utf8").replace(/\s+$/u, "");
-  const block = `${CLAUDE_MD_OPEN_MARKER}
-${body}
-${CLAUDE_MD_CLOSE_MARKER}
-`;
-  if (!(0, import_node_fs2.existsSync)(target)) {
-    (0, import_node_fs2.writeFileSync)(target, block);
-    log(logger, `CLAUDE.md \u2192 ${target} (created)`);
-    return;
-  }
-  const existing = (0, import_node_fs2.readFileSync)(target, "utf8");
-  if (existing.includes(CLAUDE_MD_OPEN_MARKER)) {
-    log(logger, `CLAUDE.md \u2192 ${target} (block already present, no change)`);
-    return;
-  }
-  if (existing.length === 0) {
-    (0, import_node_fs2.writeFileSync)(target, block);
-    log(logger, `CLAUDE.md \u2192 ${target} (block appended)`);
-    return;
-  }
-  const needsLeadingNewline = !existing.endsWith("\n");
-  const prefix = needsLeadingNewline ? "\n" : "";
-  (0, import_node_fs2.writeFileSync)(target, `${existing}${prefix}${block}`);
-  log(logger, `CLAUDE.md \u2192 ${target} (block appended)`);
-}
-function stripClaudeMdBlock(repoRoot, logger) {
-  const target = (0, import_node_path2.join)(repoRoot, CLAUDE_MD_FILENAME);
-  if (!(0, import_node_fs2.existsSync)(target)) {
-    log(logger, `CLAUDE.md \u2192 ${target} (no block to remove, no change)`);
-    return;
-  }
-  const existing = (0, import_node_fs2.readFileSync)(target, "utf8");
-  const openIdx = existing.indexOf(CLAUDE_MD_OPEN_MARKER);
-  if (openIdx === -1) {
-    log(logger, `CLAUDE.md \u2192 ${target} (no block to remove, no change)`);
-    return;
-  }
-  const afterOpen = openIdx + CLAUDE_MD_OPEN_MARKER.length;
-  const closeIdx = existing.indexOf(CLAUDE_MD_CLOSE_MARKER, afterOpen);
-  let endIdx;
-  if (closeIdx === -1) {
-    endIdx = existing.length;
-  } else {
-    endIdx = closeIdx + CLAUDE_MD_CLOSE_MARKER.length;
-    if (existing.startsWith("\r\n", endIdx)) {
-      endIdx += 2;
-    } else if (existing[endIdx] === "\n") {
-      endIdx += 1;
-    }
-  }
-  const result = existing.slice(0, openIdx) + existing.slice(endIdx);
-  (0, import_node_fs2.writeFileSync)(target, result);
-  log(logger, `CLAUDE.md \u2192 ${target} (block removed)`);
-}
-function appendGitignoreLine(repoRoot, logger) {
-  const target = (0, import_node_path2.join)(repoRoot, ".gitignore");
-  const { changed } = appendToGitignore(repoRoot);
-  if (changed) {
-    log(logger, `.gitignore \u2192 ${target} (appended .delfini-trace/)`);
-  } else {
-    log(logger, `.gitignore \u2192 ${target} (.delfini-trace/ already present, no change)`);
-  }
-}
-function log(logger, message) {
-  if (typeof logger.log === "function") {
-    logger.log(message);
-  }
-}
-
-// src/commands/local-finalize.ts
-init_cjs_shims();
-var import_node_fs3 = require("fs");
-var import_node_path3 = __toESM(require("path"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_tinyglobby = require("tinyglobby");
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/index.js
 init_cjs_shims();
@@ -7299,54 +7084,527 @@ function mostCommonHunkReason(droppedHunks) {
   return bestReason;
 }
 
-// src/commands/local-finalize.ts
-var TRACE_DIR_RELATIVE = ".delfini-trace";
-var ANALYSIS_INPUT_FILENAME = "analysis-input.json";
-var REPORT_FILENAME = "report.md";
-var SEVERITY_ICON = {
-  High: "[H]",
-  Medium: "[M]",
-  Low: "[L]"
+// src/doc-scope.ts
+var DOC_SCOPE_RELATIVE_PATH = ".claude/skills/delfini/doc-scope.json";
+var DOC_SCOPE_VERSION = 1;
+var DOC_SCOPE_VERSION_MISMATCH_MESSAGE = "your doc-scope.json is for a newer @delfini/cli; please upgrade.";
+var REPO_ROOT_REL = ".";
+var DocScopeVersionMismatchError = class extends Error {
+  code = "DOC_SCOPE_VERSION_MISMATCH";
+  constructor(message = DOC_SCOPE_VERSION_MISMATCH_MESSAGE) {
+    super(message);
+    this.name = "DocScopeVersionMismatchError";
+  }
 };
-var ClarifyingQuestionSchema = external_exports.object({
-  whatChanged: external_exports.string().min(1),
-  naturalHomeDoc: external_exports.string().min(1),
-  naturalHomeSection: external_exports.string().min(1),
-  question: external_exports.string().min(1),
-  proposedReplacement: external_exports.string().nullable()
+var DocScopeCorruptError = class extends Error {
+  code = "DOC_SCOPE_CORRUPT";
+  constructor(message) {
+    super(message);
+    this.name = "DocScopeCorruptError";
+  }
+};
+var DocScopeValidationError = class extends Error {
+  code = "DOC_SCOPE_VALIDATION";
+  constructor(message) {
+    super(message);
+    this.name = "DocScopeValidationError";
+  }
+};
+var docScopeSchemaV1 = external_exports.object({
+  version: external_exports.literal(1),
+  doc_scope: external_exports.array(external_exports.string().min(1))
 });
-var ClarifyingQuestionsArraySchema = external_exports.array(ClarifyingQuestionSchema);
-async function runLocalFinalize(options) {
-  const stderr = options.stderr ?? process.stderr;
-  const stdout = options.stdout ?? process.stdout;
-  const repoRoot = options.repoRoot ?? await getRepoRoot();
-  const findingsPath = import_node_path3.default.isAbsolute(options.findingsPath) ? options.findingsPath : import_node_path3.default.join(repoRoot, options.findingsPath);
-  let findingsContent;
+var versionProbeSchema = external_exports.object({
+  version: external_exports.number().int().positive()
+});
+async function readDocScope(repoRoot) {
+  const root = repoRoot ?? await getRepoRoot();
+  const target = import_node_path.default.join(root, DOC_SCOPE_RELATIVE_PATH);
+  let raw;
   try {
-    findingsContent = await import_node_fs3.promises.readFile(findingsPath, "utf8");
+    raw = await import_node_fs.promises.readFile(target, "utf8");
   } catch (err) {
-    return emitSchemaValidationError(stderr, [
-      {
-        path: "findings.json",
-        message: `Failed to read findings file at "${findingsPath}": ${formatErrorMessage(err)}`
-      }
-    ]);
+    if (isNoEntError(err)) return null;
+    throw err;
   }
-  let rawJson;
+  let parsed;
   try {
-    rawJson = JSON.parse(findingsContent);
+    parsed = JSON.parse(raw);
   } catch (err) {
-    return emitSchemaValidationError(stderr, [
-      {
-        path: "findings.json",
-        message: `Failed to parse findings.json as JSON: ${formatErrorMessage(err)}`
-      }
-    ]);
+    throw new DocScopeCorruptError(
+      `${DOC_SCOPE_RELATIVE_PATH} is malformed: ${err.message}`
+    );
+  }
+  const probe = versionProbeSchema.safeParse(parsed);
+  if (probe.success && probe.data.version > DOC_SCOPE_VERSION) {
+    throw new DocScopeVersionMismatchError();
+  }
+  const result = docScopeSchemaV1.safeParse(parsed);
+  if (!result.success) {
+    throw new DocScopeCorruptError(
+      `${DOC_SCOPE_RELATIVE_PATH} is malformed: ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return result.data;
+}
+async function writeDocScope(paths, options) {
+  const root = options?.repoRoot ?? await getRepoRoot();
+  if (!Array.isArray(paths) || paths.length === 0) {
+    throw new DocScopeValidationError("at least one path is required");
+  }
+  const errors = [];
+  for (const entry of paths) {
+    const err = validateDocScopeEntry(entry, REPO_ROOT_REL);
+    if (err !== null) errors.push(err);
+  }
+  if (errors.length > 0) {
+    throw new DocScopeValidationError(
+      `${DOC_SCOPE_RELATIVE_PATH}: invalid path(s):
+${errors.map((e) => `  - ${e}`).join("\n")}`
+    );
+  }
+  const normalised = normalizeDocScope(paths);
+  if (normalised.length === 0) {
+    throw new DocScopeValidationError(
+      `${DOC_SCOPE_RELATIVE_PATH}: every entry collapses to an empty scope after normalisation (e.g. '.', './', 'docs/..') \u2014 provide at least one concrete path`
+    );
+  }
+  const target = import_node_path.default.join(root, DOC_SCOPE_RELATIVE_PATH);
+  await import_node_fs.promises.mkdir(import_node_path.default.dirname(target), { recursive: true });
+  const payload = { version: DOC_SCOPE_VERSION, doc_scope: normalised };
+  const json = `${JSON.stringify(payload, null, 2)}
+`;
+  await import_node_fs.promises.writeFile(target, json, "utf8");
+}
+async function docScopeExists(repoRoot) {
+  const root = repoRoot ?? await getRepoRoot();
+  const target = import_node_path.default.join(root, DOC_SCOPE_RELATIVE_PATH);
+  try {
+    const st = await import_node_fs.promises.stat(target);
+    return st.isFile();
+  } catch {
+    return false;
+  }
+}
+async function deleteDocScope(repoRoot) {
+  const root = repoRoot ?? await getRepoRoot();
+  const target = import_node_path.default.join(root, DOC_SCOPE_RELATIVE_PATH);
+  try {
+    await import_node_fs.promises.unlink(target);
+  } catch (err) {
+    if (!isNoEntError(err)) throw err;
+  }
+}
+async function expandDocScope(paths, repoRoot) {
+  const root = repoRoot ?? await getRepoRoot();
+  const normalisedRoot = import_node_path.default.resolve(root);
+  const found = /* @__PURE__ */ new Set();
+  const missing = [];
+  for (const rawEntry of paths) {
+    if (typeof rawEntry !== "string") continue;
+    const normalised = normalizeDocScope([rawEntry]);
+    if (normalised.length === 0) {
+      if (rawEntry.trim().length > 0) missing.push(rawEntry);
+      continue;
+    }
+    const entry = normalised[0];
+    if (validateDocScopeEntry(entry, REPO_ROOT_REL) !== null) {
+      missing.push(rawEntry);
+      continue;
+    }
+    if (classifyEntry(entry) === "glob") {
+      const matches = await (0, import_tinyglobby.glob)(entry, {
+        cwd: root,
+        absolute: true,
+        onlyFiles: true,
+        dot: false,
+        // Case-folding parity with the engine predicate (`nocase: true`).
+        caseSensitiveMatch: false,
+        // Migrating from fast-glob — disable tinyglobby's directory-pattern
+        // auto-expansion so a glob like `packages/*/README.md` keeps exact
+        // fast-glob semantics.
+        expandDirectories: false
+      });
+      const inRoot = matches.filter((m) => isInsideRoot(m, normalisedRoot));
+      if (inRoot.length === 0) {
+        missing.push(rawEntry);
+      } else {
+        for (const m of inRoot) found.add(m);
+      }
+      continue;
+    }
+    const absolute = import_node_path.default.resolve(root, entry);
+    let stat;
+    try {
+      stat = await import_node_fs.promises.stat(absolute);
+    } catch (err) {
+      if (isNoEntError(err)) {
+        missing.push(rawEntry);
+        continue;
+      }
+      throw err;
+    }
+    if (stat.isDirectory()) {
+      const children = await (0, import_tinyglobby.glob)("**/*.md", {
+        cwd: absolute,
+        absolute: true,
+        onlyFiles: true,
+        caseSensitiveMatch: false,
+        dot: false,
+        expandDirectories: false
+      });
+      for (const c of children) {
+        if (isInsideRoot(c, normalisedRoot)) found.add(c);
+      }
+    } else if (stat.isFile()) {
+      if (isInsideRoot(absolute, normalisedRoot)) found.add(absolute);
+    } else {
+      missing.push(rawEntry);
+    }
+  }
+  const files = Array.from(found).sort();
+  return { files, missingPaths: missing };
+}
+function isNoEntError(err) {
+  return typeof err === "object" && err !== null && err.code === "ENOENT";
+}
+function isInsideRoot(absolute, normalisedRoot) {
+  const resolved = import_node_path.default.resolve(absolute);
+  return resolved === normalisedRoot || resolved.startsWith(normalisedRoot + import_node_path.default.sep);
+}
+
+// src/trace.ts
+init_cjs_shims();
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var TRACE_DIR_NAME = ".delfini-trace";
+var GITIGNORE_LINE = ".delfini-trace/";
+function ensureTraceDir(repoRoot) {
+  const tracePath = (0, import_node_path2.join)(repoRoot, TRACE_DIR_NAME);
+  if ((0, import_node_fs2.existsSync)(tracePath)) {
+    const stat = (0, import_node_fs2.statSync)(tracePath);
+    if (!stat.isDirectory()) {
+      throw new Error(
+        `ensureTraceDir: ${tracePath} exists but is not a directory. Remove or rename it so the CLI can create the trace directory.`
+      );
+    }
+    return tracePath;
+  }
+  (0, import_node_fs2.mkdirSync)(tracePath, { recursive: true });
+  return tracePath;
+}
+function appendToGitignore(repoRoot) {
+  const gitignorePath = (0, import_node_path2.join)(repoRoot, ".gitignore");
+  const existed = (0, import_node_fs2.existsSync)(gitignorePath);
+  const existingContent = existed ? (0, import_node_fs2.readFileSync)(gitignorePath, "utf8") : "";
+  const lines = existingContent.split(/\r?\n/);
+  for (const line of lines) {
+    if (line.trim() === GITIGNORE_LINE) {
+      return { changed: false };
+    }
+  }
+  const useCRLF = existingContent.includes("\r\n");
+  const newline = useCRLF ? "\r\n" : "\n";
+  if (!existed || existingContent.length === 0) {
+    (0, import_node_fs2.writeFileSync)(gitignorePath, `${GITIGNORE_LINE}${newline}`);
+    return { changed: true };
+  }
+  const endsWithNewline = existingContent.endsWith("\n");
+  const prefix = endsWithNewline ? "" : newline;
+  (0, import_node_fs2.appendFileSync)(gitignorePath, `${prefix}${GITIGNORE_LINE}${newline}`);
+  return { changed: true };
+}
+function writeTraceFile(repoRoot, filename, content) {
+  validateBasename(filename);
+  const traceDir = ensureTraceDir(repoRoot);
+  const target = (0, import_node_path2.join)(traceDir, filename);
+  (0, import_node_fs2.writeFileSync)(target, content);
+  return target;
+}
+function validateBasename(filename) {
+  if (filename.length === 0) {
+    throw new Error("writeTraceFile: filename must not be empty");
+  }
+  if (filename === "." || filename === "..") {
+    throw new Error(`writeTraceFile: filename must not be "${filename}"`);
+  }
+  if (filename.includes("/") || filename.includes("\\")) {
+    throw new Error(
+      `writeTraceFile: filename must be a basename without path separators, got "${filename}"`
+    );
+  }
+}
+
+// src/commands/install.ts
+var InstallToolNotSupportedError = class extends Error {
+  code = "INSTALL_TOOL_NOT_SUPPORTED";
+  constructor(tool) {
+    super(
+      `delfini install: --tool '${tool}' is not supported. The Skill is Claude-only in V1 (design-spec NG2 / project-context "Skill \u2014 Out of Scope in V1 / V1.1: No multi-LLM-provider support \u2014 Claude-only by design"). Use --tool CLAUDE (the default).`
+    );
+    this.name = "InstallToolNotSupportedError";
+  }
+};
+var CLAUDE_MD_OPEN_MARKER = "<!-- delfini:auto-invoke-block-v1 -->";
+var CLAUDE_MD_CLOSE_MARKER = "<!-- /delfini:auto-invoke-block-v1 -->";
+var SKILL_RELATIVE_PATH = ".claude/skills/delfini/SKILL.md";
+var CLAUDE_MD_FILENAME = "CLAUDE.md";
+var SUPPORTED_TOOL = "CLAUDE";
+var TEMPLATES_DIR = resolveTemplatesDir();
+function resolveTemplatesDir() {
+  let dir = (0, import_node_path3.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
+  for (let i = 0; i < 5; i++) {
+    const candidate = (0, import_node_path3.resolve)(dir, "templates");
+    if ((0, import_node_fs3.existsSync)((0, import_node_path3.join)(candidate, "SKILL.md"))) {
+      return candidate;
+    }
+    const parent = (0, import_node_path3.dirname)(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error("templates/ directory not found relative to the CLI module");
+}
+async function runInstall(targetPath, options) {
+  const tool = options?.tool ?? SUPPORTED_TOOL;
+  const logger = options?.logger ?? console;
+  if (tool !== SUPPORTED_TOOL) {
+    throw new InstallToolNotSupportedError(tool);
   }
-  const analysisInputPath = import_node_path3.default.join(repoRoot, TRACE_DIR_RELATIVE, ANALYSIS_INPUT_FILENAME);
+  const resolvedTarget = (0, import_node_path3.resolve)(process.cwd(), targetPath);
+  const repoRoot = await getRepoRoot(resolvedTarget);
+  writeSkillTemplate(repoRoot, logger);
+  await applyDocScope(repoRoot, logger, options?.provideDocScope);
+  await applyAutoInvokeDecision(repoRoot, logger, options?.confirmAutoInvoke);
+  appendGitignoreLine(repoRoot, logger);
+}
+function parseScopeInput(answer) {
+  return answer.split(/[\s,]+/u).map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
+function sanitiseScope(paths) {
+  return paths.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
+async function applyDocScope(repoRoot, logger, provideDocScope) {
+  const target = (0, import_node_path3.join)(repoRoot, DOC_SCOPE_RELATIVE_PATH);
+  if (provideDocScope) {
+    const paths2 = sanitiseScope(await provideDocScope());
+    if (paths2.length === 0) {
+      log(logger, `doc-scope.json \u2192 ${target} (no paths provided, no change)`);
+      return;
+    }
+    await persistDocScope(repoRoot, logger, target, paths2);
+    return;
+  }
+  if (await docScopeExists(repoRoot)) {
+    log(logger, `doc-scope.json \u2192 ${target} (already configured, no change)`);
+    return;
+  }
+  if (!process.stdin.isTTY) {
+    log(
+      logger,
+      `doc-scope.json \u2192 ${target} (non-interactive shell: scope prompt skipped, no change)`
+    );
+    return;
+  }
+  const paths = await promptDocScope();
+  if (paths.length === 0) {
+    log(
+      logger,
+      `doc-scope.json \u2192 ${target} (no paths provided, no change \u2014 first /delfini run will prompt)`
+    );
+    return;
+  }
+  await persistDocScope(repoRoot, logger, target, paths);
+}
+async function promptDocScope() {
+  const rl = (0, import_promises.createInterface)({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(
+      "Which docs should Delfini track? Enter one or more paths \u2014 directories (recursive .md scan), files, or globs, space- or comma-separated (e.g. `docs/ specs/architecture.md packages/*/README.md`). Leave blank to skip: "
+    );
+    return parseScopeInput(answer);
+  } finally {
+    rl.close();
+  }
+}
+async function persistDocScope(repoRoot, logger, target, paths) {
+  try {
+    await writeDocScope(paths, { repoRoot });
+    log(logger, `doc-scope.json \u2192 ${target} (wrote ${paths.length} path(s))`);
+  } catch (err) {
+    if (err instanceof DocScopeValidationError) {
+      log(
+        logger,
+        `doc-scope.json \u2192 ${target} (skipped \u2014 ${err.message}). Fix the path(s) and re-run \`delfini install\`, edit the file directly, or set the scope on the first /delfini run.`
+      );
+      return;
+    }
+    throw err;
+  }
+}
+function parseYesNo(answer) {
+  const normalised = answer.trim().toLowerCase();
+  return normalised === "y" || normalised === "yes";
+}
+async function applyAutoInvokeDecision(repoRoot, logger, confirmAutoInvoke) {
+  const decision = await resolveAutoInvoke(confirmAutoInvoke);
+  if (decision === "yes") {
+    appendClaudeMdBlock(repoRoot, logger);
+  } else if (decision === "no") {
+    stripClaudeMdBlock(repoRoot, logger);
+  } else {
+    const target = (0, import_node_path3.join)(repoRoot, CLAUDE_MD_FILENAME);
+    log(logger, `CLAUDE.md \u2192 ${target} (non-interactive shell: auto-invoke prompt skipped, no change)`);
+  }
+}
+async function resolveAutoInvoke(confirmAutoInvoke) {
+  if (confirmAutoInvoke) {
+    return await confirmAutoInvoke() ? "yes" : "no";
+  }
+  if (!process.stdin.isTTY) {
+    return "skip";
+  }
+  return await promptAutoInvoke() ? "yes" : "no";
+}
+async function promptAutoInvoke() {
+  const rl = (0, import_promises.createInterface)({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question("Auto-invoke /delfini on PR creation? (y/n) ");
+    return parseYesNo(answer);
+  } finally {
+    rl.close();
+  }
+}
+function writeSkillTemplate(repoRoot, logger) {
+  const target = (0, import_node_path3.join)(repoRoot, SKILL_RELATIVE_PATH);
+  const templateSource = (0, import_node_path3.join)(TEMPLATES_DIR, "SKILL.md");
+  const content = (0, import_node_fs3.readFileSync)(templateSource);
+  (0, import_node_fs3.mkdirSync)((0, import_node_path3.dirname)(target), { recursive: true });
+  (0, import_node_fs3.writeFileSync)(target, content);
+  log(logger, `SKILL.md \u2192 ${target}`);
+}
+function appendClaudeMdBlock(repoRoot, logger) {
+  const target = (0, import_node_path3.join)(repoRoot, CLAUDE_MD_FILENAME);
+  const blockSource = (0, import_node_path3.join)(TEMPLATES_DIR, "claude-md-append-block.txt");
+  const body = (0, import_node_fs3.readFileSync)(blockSource, "utf8").replace(/\s+$/u, "");
+  const block = `${CLAUDE_MD_OPEN_MARKER}
+${body}
+${CLAUDE_MD_CLOSE_MARKER}
+`;
+  if (!(0, import_node_fs3.existsSync)(target)) {
+    (0, import_node_fs3.writeFileSync)(target, block);
+    log(logger, `CLAUDE.md \u2192 ${target} (created)`);
+    return;
+  }
+  const existing = (0, import_node_fs3.readFileSync)(target, "utf8");
+  if (existing.includes(CLAUDE_MD_OPEN_MARKER)) {
+    log(logger, `CLAUDE.md \u2192 ${target} (block already present, no change)`);
+    return;
+  }
+  if (existing.length === 0) {
+    (0, import_node_fs3.writeFileSync)(target, block);
+    log(logger, `CLAUDE.md \u2192 ${target} (block appended)`);
+    return;
+  }
+  const needsLeadingNewline = !existing.endsWith("\n");
+  const prefix = needsLeadingNewline ? "\n" : "";
+  (0, import_node_fs3.writeFileSync)(target, `${existing}${prefix}${block}`);
+  log(logger, `CLAUDE.md \u2192 ${target} (block appended)`);
+}
+function stripClaudeMdBlock(repoRoot, logger) {
+  const target = (0, import_node_path3.join)(repoRoot, CLAUDE_MD_FILENAME);
+  if (!(0, import_node_fs3.existsSync)(target)) {
+    log(logger, `CLAUDE.md \u2192 ${target} (no block to remove, no change)`);
+    return;
+  }
+  const existing = (0, import_node_fs3.readFileSync)(target, "utf8");
+  const openIdx = existing.indexOf(CLAUDE_MD_OPEN_MARKER);
+  if (openIdx === -1) {
+    log(logger, `CLAUDE.md \u2192 ${target} (no block to remove, no change)`);
+    return;
+  }
+  const afterOpen = openIdx + CLAUDE_MD_OPEN_MARKER.length;
+  const closeIdx = existing.indexOf(CLAUDE_MD_CLOSE_MARKER, afterOpen);
+  let endIdx;
+  if (closeIdx === -1) {
+    endIdx = existing.length;
+  } else {
+    endIdx = closeIdx + CLAUDE_MD_CLOSE_MARKER.length;
+    if (existing.startsWith("\r\n", endIdx)) {
+      endIdx += 2;
+    } else if (existing[endIdx] === "\n") {
+      endIdx += 1;
+    }
+  }
+  const result = existing.slice(0, openIdx) + existing.slice(endIdx);
+  (0, import_node_fs3.writeFileSync)(target, result);
+  log(logger, `CLAUDE.md \u2192 ${target} (block removed)`);
+}
+function appendGitignoreLine(repoRoot, logger) {
+  const target = (0, import_node_path3.join)(repoRoot, ".gitignore");
+  const { changed } = appendToGitignore(repoRoot);
+  if (changed) {
+    log(logger, `.gitignore \u2192 ${target} (appended .delfini-trace/)`);
+  } else {
+    log(logger, `.gitignore \u2192 ${target} (.delfini-trace/ already present, no change)`);
+  }
+}
+function log(logger, message) {
+  if (typeof logger.log === "function") {
+    logger.log(message);
+  }
+}
+
+// src/commands/local-finalize.ts
+init_cjs_shims();
+var import_node_fs4 = require("fs");
+var import_node_path4 = __toESM(require("path"), 1);
+var TRACE_DIR_RELATIVE = ".delfini-trace";
+var ANALYSIS_INPUT_FILENAME = "analysis-input.json";
+var REPORT_FILENAME = "report.md";
+var SEVERITY_ICON = {
+  High: "[H]",
+  Medium: "[M]",
+  Low: "[L]"
+};
+var ClarifyingQuestionSchema = external_exports.object({
+  whatChanged: external_exports.string().min(1),
+  naturalHomeDoc: external_exports.string().min(1),
+  naturalHomeSection: external_exports.string().min(1),
+  question: external_exports.string().min(1),
+  proposedReplacement: external_exports.string().nullable()
+});
+var ClarifyingQuestionsArraySchema = external_exports.array(ClarifyingQuestionSchema);
+async function runLocalFinalize(options) {
+  const stderr = options.stderr ?? process.stderr;
+  const stdout = options.stdout ?? process.stdout;
+  const repoRoot = options.repoRoot ?? await getRepoRoot();
+  const findingsPath = import_node_path4.default.isAbsolute(options.findingsPath) ? options.findingsPath : import_node_path4.default.join(repoRoot, options.findingsPath);
+  let findingsContent;
+  try {
+    findingsContent = await import_node_fs4.promises.readFile(findingsPath, "utf8");
+  } catch (err) {
+    return emitSchemaValidationError(stderr, [
+      {
+        path: "findings.json",
+        message: `Failed to read findings file at "${findingsPath}": ${formatErrorMessage(err)}`
+      }
+    ]);
+  }
+  let rawJson;
+  try {
+    rawJson = JSON.parse(findingsContent);
+  } catch (err) {
+    return emitSchemaValidationError(stderr, [
+      {
+        path: "findings.json",
+        message: `Failed to parse findings.json as JSON: ${formatErrorMessage(err)}`
+      }
+    ]);
+  }
+  const analysisInputPath = import_node_path4.default.join(repoRoot, TRACE_DIR_RELATIVE, ANALYSIS_INPUT_FILENAME);
   let docs;
   try {
-    const raw = await import_node_fs3.promises.readFile(analysisInputPath, "utf8");
+    const raw = await import_node_fs4.promises.readFile(analysisInputPath, "utf8");
     const parsed = JSON.parse(raw);
     if (!Array.isArray(parsed.docs)) {
       return emitSchemaValidationError(stderr, [
@@ -7561,155 +7819,6 @@ var import_node_path5 = __toESM(require("path"), 1);
 var import_node_url2 = require("url");
 var import_node_util = require("util");
 var import_simple_git3 = __toESM(require("simple-git"), 1);
-
-// src/doc-scope.ts
-init_cjs_shims();
-var import_node_fs4 = require("fs");
-var import_node_path4 = __toESM(require("path"), 1);
-var import_tinyglobby = require("tinyglobby");
-var DOC_SCOPE_RELATIVE_PATH = ".claude/skills/delfini/doc-scope.json";
-var DOC_SCOPE_VERSION = 1;
-var DOC_SCOPE_VERSION_MISMATCH_MESSAGE = "your doc-scope.json is for a newer @delfini/cli; please upgrade.";
-var REPO_ROOT_REL = ".";
-var DocScopeVersionMismatchError = class extends Error {
-  code = "DOC_SCOPE_VERSION_MISMATCH";
-  constructor(message = DOC_SCOPE_VERSION_MISMATCH_MESSAGE) {
-    super(message);
-    this.name = "DocScopeVersionMismatchError";
-  }
-};
-var DocScopeCorruptError = class extends Error {
-  code = "DOC_SCOPE_CORRUPT";
-  constructor(message) {
-    super(message);
-    this.name = "DocScopeCorruptError";
-  }
-};
-var docScopeSchemaV1 = external_exports.object({
-  version: external_exports.literal(1),
-  doc_scope: external_exports.array(external_exports.string().min(1))
-});
-var versionProbeSchema = external_exports.object({
-  version: external_exports.number().int().positive()
-});
-async function readDocScope(repoRoot) {
-  const root = repoRoot ?? await getRepoRoot();
-  const target = import_node_path4.default.join(root, DOC_SCOPE_RELATIVE_PATH);
-  let raw;
-  try {
-    raw = await import_node_fs4.promises.readFile(target, "utf8");
-  } catch (err) {
-    if (isNoEntError(err)) return null;
-    throw err;
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw new DocScopeCorruptError(
-      `${DOC_SCOPE_RELATIVE_PATH} is malformed: ${err.message}`
-    );
-  }
-  const probe = versionProbeSchema.safeParse(parsed);
-  if (probe.success && probe.data.version > DOC_SCOPE_VERSION) {
-    throw new DocScopeVersionMismatchError();
-  }
-  const result = docScopeSchemaV1.safeParse(parsed);
-  if (!result.success) {
-    throw new DocScopeCorruptError(
-      `${DOC_SCOPE_RELATIVE_PATH} is malformed: ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
-    );
-  }
-  return result.data;
-}
-async function deleteDocScope(repoRoot) {
-  const root = repoRoot ?? await getRepoRoot();
-  const target = import_node_path4.default.join(root, DOC_SCOPE_RELATIVE_PATH);
-  try {
-    await import_node_fs4.promises.unlink(target);
-  } catch (err) {
-    if (!isNoEntError(err)) throw err;
-  }
-}
-async function expandDocScope(paths, repoRoot) {
-  const root = repoRoot ?? await getRepoRoot();
-  const normalisedRoot = import_node_path4.default.resolve(root);
-  const found = /* @__PURE__ */ new Set();
-  const missing = [];
-  for (const rawEntry of paths) {
-    if (typeof rawEntry !== "string") continue;
-    const normalised = normalizeDocScope([rawEntry]);
-    if (normalised.length === 0) {
-      if (rawEntry.trim().length > 0) missing.push(rawEntry);
-      continue;
-    }
-    const entry = normalised[0];
-    if (validateDocScopeEntry(entry, REPO_ROOT_REL) !== null) {
-      missing.push(rawEntry);
-      continue;
-    }
-    if (classifyEntry(entry) === "glob") {
-      const matches = await (0, import_tinyglobby.glob)(entry, {
-        cwd: root,
-        absolute: true,
-        onlyFiles: true,
-        dot: false,
-        // Case-folding parity with the engine predicate (`nocase: true`).
-        caseSensitiveMatch: false,
-        // Migrating from fast-glob — disable tinyglobby's directory-pattern
-        // auto-expansion so a glob like `packages/*/README.md` keeps exact
-        // fast-glob semantics.
-        expandDirectories: false
-      });
-      const inRoot = matches.filter((m) => isInsideRoot(m, normalisedRoot));
-      if (inRoot.length === 0) {
-        missing.push(rawEntry);
-      } else {
-        for (const m of inRoot) found.add(m);
-      }
-      continue;
-    }
-    const absolute = import_node_path4.default.resolve(root, entry);
-    let stat;
-    try {
-      stat = await import_node_fs4.promises.stat(absolute);
-    } catch (err) {
-      if (isNoEntError(err)) {
-        missing.push(rawEntry);
-        continue;
-      }
-      throw err;
-    }
-    if (stat.isDirectory()) {
-      const children = await (0, import_tinyglobby.glob)("**/*.md", {
-        cwd: absolute,
-        absolute: true,
-        onlyFiles: true,
-        caseSensitiveMatch: false,
-        dot: false,
-        expandDirectories: false
-      });
-      for (const c of children) {
-        if (isInsideRoot(c, normalisedRoot)) found.add(c);
-      }
-    } else if (stat.isFile()) {
-      if (isInsideRoot(absolute, normalisedRoot)) found.add(absolute);
-    } else {
-      missing.push(rawEntry);
-    }
-  }
-  const files = Array.from(found).sort();
-  return { files, missingPaths: missing };
-}
-function isNoEntError(err) {
-  return typeof err === "object" && err !== null && err.code === "ENOENT";
-}
-function isInsideRoot(absolute, normalisedRoot) {
-  const resolved = import_node_path4.default.resolve(absolute);
-  return resolved === normalisedRoot || resolved.startsWith(normalisedRoot + import_node_path4.default.sep);
-}
-
-// src/commands/local-prepare.ts
 var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
 var UNTRACKED_DIFF_MAX_BUFFER = 64 * 1024 * 1024;
 var PROMPT_TOKEN_BUDGET = 15e4;
@@ -8037,10 +8146,16 @@ async function main(argv) {
   });
   program.command("install <path>").description(
     "Scaffold .claude/skills/delfini/SKILL.md + CLAUDE.md auto-invoke + .gitignore append"
-  ).option("--tool <agent>", "Coding agent target (only 'CLAUDE' supported in V1)", "CLAUDE").option("--auto-invoke", "append the CLAUDE.md auto-invoke block without prompting").option("--no-auto-invoke", "strip the CLAUDE.md auto-invoke block without prompting").action(async (targetPath, opts) => {
-    const confirmAutoInvoke = opts.autoInvoke === void 0 ? void 0 : () => Promise.resolve(opts.autoInvoke);
-    await runInstall(targetPath, { tool: opts.tool, confirmAutoInvoke });
-  });
+  ).option("--tool <agent>", "Coding agent target (only 'CLAUDE' supported in V1)", "CLAUDE").option("--auto-invoke", "append the CLAUDE.md auto-invoke block without prompting").option("--no-auto-invoke", "strip the CLAUDE.md auto-invoke block without prompting").option(
+    "--scope <paths>",
+    "Seed doc-scope.json with these paths (space- or comma-separated; overwrites any existing scope) without prompting. Omit to be prompted interactively on a TTY."
+  ).action(
+    async (targetPath, opts) => {
+      const confirmAutoInvoke = opts.autoInvoke === void 0 ? void 0 : () => Promise.resolve(opts.autoInvoke);
+      const provideDocScope = opts.scope === void 0 ? void 0 : () => Promise.resolve(parseScopeInput(opts.scope));
+      await runInstall(targetPath, { tool: opts.tool, confirmAutoInvoke, provideDocScope });
+    }
+  );
   program.command("local-prepare").description(
     "Compute diff + doc-scope + prompt + token-budget gate; write .delfini-trace/"
   ).option("--scope <paths>", "Comma-separated doc-scope paths (overrides doc-scope.json)").option("--base <ref>", "Diff base ref (default: git merge-base HEAD origin/main)").option(