@delfini/cli 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -1802,26 +1802,28 @@ var require_picomatch2 = __commonJS({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  DOC_SCOPE_RELATIVE_PATH: () => DOC_SCOPE_RELATIVE_PATH,
-  DOC_SCOPE_VERSION: () => DOC_SCOPE_VERSION,
-  DocScopeCorruptError: () => DocScopeCorruptError,
-  DocScopeValidationError: () => DocScopeValidationError,
-  DocScopeVersionMismatchError: () => DocScopeVersionMismatchError,
+  ConfigCorruptError: () => ConfigCorruptError,
+  ConfigValidationError: () => ConfigValidationError,
+  ConfigVersionMismatchError: () => ConfigVersionMismatchError,
+  DELFINI_CONFIG_RELATIVE_PATH: () => DELFINI_CONFIG_RELATIVE_PATH,
+  DELFINI_CONFIG_VERSION: () => DELFINI_CONFIG_VERSION,
   InstallToolNotSupportedError: () => InstallToolNotSupportedError,
+  LEGACY_DOC_SCOPE_RELATIVE_PATH: () => LEGACY_DOC_SCOPE_RELATIVE_PATH,
   PROMPT_TOKEN_BUDGET: () => PROMPT_TOKEN_BUDGET,
   RepoRootNotFoundError: () => RepoRootNotFoundError,
   appendToGitignore: () => appendToGitignore,
-  deleteDocScope: () => deleteDocScope,
-  docScopeExists: () => docScopeExists,
+  configExists: () => configExists,
+  deleteConfig: () => deleteConfig,
   ensureTraceDir: () => ensureTraceDir,
   expandDocScope: () => expandDocScope,
   getRepoRoot: () => getRepoRoot,
   main: () => main,
-  readDocScope: () => readDocScope,
+  readConfig: () => readConfig,
   runDiffStatus: () => runDiffStatus,
   runInstall: () => runInstall,
   runLocalFinalize: () => runLocalFinalize,
   runLocalPrepare: () => runLocalPrepare,
+  writeConfig: () => writeConfig,
   writeDocScope: () => writeDocScope,
   writeRetryAttemptFile: () => writeRetryAttemptFile,
   writeTraceFile: () => writeTraceFile
@@ -1829,7 +1831,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 init_cjs_shims();
 
-// src/doc-scope.ts
+// src/config.ts
 init_cjs_shims();
 var import_node_fs = require("fs");
 var import_node_path = __toESM(require("path"), 1);
@@ -6478,6 +6480,18 @@ function classifyEntry(entry) {
     return "dir";
   return lastSegment.includes(".") ? "file" : "dir";
 }
+function isFileInDocScope(filePath, scope) {
+  const file = posixNormalize(toPosix(filePath).replace(/^\/+/, ""));
+  if (file === "" || file === ".")
+    return false;
+  const entries = normalizeDocScope(scope);
+  for (const entry of entries) {
+    const pattern = classifyEntry(entry) === "dir" ? `${entry}/**` : entry;
+    if ((0, import_picomatch.default)(pattern, { dot: false, nocase: true })(file))
+      return true;
+  }
+  return false;
+}
 function toPosix(p) {
   return p.split("\\").join("/");
 }
@@ -6511,7 +6525,10 @@ function posixNormalize(input) {
 
 // ../drift-engine/dist/diff-filter.js
 init_cjs_shims();
-function filterDiff(diff) {
+function filterDiff(diff, options = {}) {
+  const builtins = options.builtins ?? true;
+  const ignorePaths = options.ignorePaths ?? [];
+  const hasIgnore = ignorePaths.length > 0;
   const droppedPaths = [];
   const droppedHunks = [];
   const files = parseDiffIntoFiles(diff);
@@ -6520,6 +6537,14 @@ function filterDiff(diff) {
     keptParts.push(files.preamble);
   }
   for (const file of files.files) {
+    if (hasIgnore && isFileInDocScope(file.path, ignorePaths)) {
+      droppedPaths.push({ path: file.path, reason: "ignored" });
+      continue;
+    }
+    if (!builtins) {
+      keptParts.push(file.rawSlice);
+      continue;
+    }
     const pathReason = classifyPath(file.path);
     if (pathReason !== null) {
       droppedPaths.push({ path: file.path, reason: pathReason });
@@ -7046,42 +7071,48 @@ async function resolveBaseRef(git, explicitBase, stderr) {
   }
 }
 
-// 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.";
+// src/config.ts
+var DELFINI_CONFIG_RELATIVE_PATH = ".claude/skills/delfini/delfini-config.json";
+var LEGACY_DOC_SCOPE_RELATIVE_PATH = ".claude/skills/delfini/doc-scope.json";
+var DELFINI_CONFIG_VERSION = 1;
+var CONFIG_VERSION_MISMATCH_MESSAGE = "your delfini-config.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) {
+var ConfigVersionMismatchError = class extends Error {
+  code = "CONFIG_VERSION_MISMATCH";
+  constructor(message = CONFIG_VERSION_MISMATCH_MESSAGE) {
     super(message);
-    this.name = "DocScopeVersionMismatchError";
+    this.name = "ConfigVersionMismatchError";
   }
 };
-var DocScopeCorruptError = class extends Error {
-  code = "DOC_SCOPE_CORRUPT";
+var ConfigCorruptError = class extends Error {
+  code = "CONFIG_CORRUPT";
   constructor(message) {
     super(message);
-    this.name = "DocScopeCorruptError";
+    this.name = "ConfigCorruptError";
   }
 };
-var DocScopeValidationError = class extends Error {
-  code = "DOC_SCOPE_VALIDATION";
+var ConfigValidationError = class extends Error {
+  code = "CONFIG_VALIDATION";
   constructor(message) {
     super(message);
-    this.name = "DocScopeValidationError";
+    this.name = "ConfigValidationError";
   }
 };
-var docScopeSchemaV1 = external_exports.object({
+var configSchemaV1 = external_exports.object({
   version: external_exports.literal(1),
-  doc_scope: external_exports.array(external_exports.string().min(1))
+  doc_scope: external_exports.array(external_exports.string().min(1)),
+  ignore_code_scope: external_exports.array(external_exports.string().min(1)).optional()
 });
 var versionProbeSchema = external_exports.object({
   version: external_exports.number().int().positive()
 });
-async function readDocScope(repoRoot) {
+async function readConfig(repoRoot) {
   const root = repoRoot ?? await getRepoRoot();
-  const target = import_node_path.default.join(root, DOC_SCOPE_RELATIVE_PATH);
+  const primary = await readConfigFile(import_node_path.default.join(root, DELFINI_CONFIG_RELATIVE_PATH));
+  if (primary !== null) return primary;
+  return readConfigFile(import_node_path.default.join(root, LEGACY_DOC_SCOPE_RELATIVE_PATH));
+}
+async function readConfigFile(target) {
   let raw;
   try {
     raw = await import_node_fs.promises.readFile(target, "utf8");
@@ -7093,54 +7124,96 @@ async function readDocScope(repoRoot) {
   try {
     parsed = JSON.parse(raw);
   } catch (err) {
-    throw new DocScopeCorruptError(
-      `${DOC_SCOPE_RELATIVE_PATH} is malformed: ${err.message}`
+    throw new ConfigCorruptError(
+      `${import_node_path.default.basename(target)} is malformed: ${err.message}`
     );
   }
   const probe = versionProbeSchema.safeParse(parsed);
-  if (probe.success && probe.data.version > DOC_SCOPE_VERSION) {
-    throw new DocScopeVersionMismatchError();
+  if (probe.success && probe.data.version > DELFINI_CONFIG_VERSION) {
+    throw new ConfigVersionMismatchError();
   }
-  const result = docScopeSchemaV1.safeParse(parsed);
+  const result = configSchemaV1.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("; ")}`
+    throw new ConfigCorruptError(
+      `${import_node_path.default.basename(target)} is malformed: ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
     );
   }
-  return result.data;
+  return {
+    version: DELFINI_CONFIG_VERSION,
+    doc_scope: result.data.doc_scope,
+    ignore_code_scope: result.data.ignore_code_scope ?? []
+  };
 }
-async function writeDocScope(paths, options) {
+async function writeConfig(update, options) {
   const root = options?.repoRoot ?? await getRepoRoot();
+  const existing = await readConfig(root);
+  let docScope = existing?.doc_scope ?? [];
+  let ignoreCodeScope = existing?.ignore_code_scope ?? [];
+  if (update.doc_scope !== void 0) {
+    docScope = validateAndNormalize(update.doc_scope, "doc_scope", { requireNonEmpty: true });
+  }
+  if (update.ignore_code_scope !== void 0) {
+    ignoreCodeScope = validateAndNormalize(update.ignore_code_scope, "ignore_code_scope", {
+      requireNonEmpty: false
+    });
+  }
+  if (docScope.length === 0) {
+    throw new ConfigValidationError(
+      `${DELFINI_CONFIG_RELATIVE_PATH}: doc_scope requires at least one path`
+    );
+  }
+  const payload = {
+    version: DELFINI_CONFIG_VERSION,
+    doc_scope: docScope
+  };
+  if (ignoreCodeScope.length > 0) {
+    payload.ignore_code_scope = ignoreCodeScope;
+  }
+  const target = import_node_path.default.join(root, DELFINI_CONFIG_RELATIVE_PATH);
+  await import_node_fs.promises.mkdir(import_node_path.default.dirname(target), { recursive: true });
+  await import_node_fs.promises.writeFile(target, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+  await removeLegacyDocScope(root);
+}
+async function writeDocScope(paths, options) {
   if (!Array.isArray(paths) || paths.length === 0) {
-    throw new DocScopeValidationError("at least one path is required");
+    throw new ConfigValidationError("at least one path is required");
   }
+  await writeConfig({ doc_scope: paths }, options);
+}
+function validateAndNormalize(paths, field, opts) {
   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):
+    throw new ConfigValidationError(
+      `${DELFINI_CONFIG_RELATIVE_PATH}: invalid ${field} 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`
+  if (opts.requireNonEmpty && normalised.length === 0) {
+    throw new ConfigValidationError(
+      `${DELFINI_CONFIG_RELATIVE_PATH}: every ${field} 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");
+  return normalised;
+}
+async function removeLegacyDocScope(root) {
+  const legacy = import_node_path.default.join(root, LEGACY_DOC_SCOPE_RELATIVE_PATH);
+  try {
+    await import_node_fs.promises.unlink(legacy);
+  } catch (err) {
+    if (!isNoEntError(err)) throw err;
+  }
 }
-async function docScopeExists(repoRoot) {
+async function configExists(repoRoot) {
   const root = repoRoot ?? await getRepoRoot();
-  const target = import_node_path.default.join(root, DOC_SCOPE_RELATIVE_PATH);
+  return await isFile(import_node_path.default.join(root, DELFINI_CONFIG_RELATIVE_PATH)) || await isFile(import_node_path.default.join(root, LEGACY_DOC_SCOPE_RELATIVE_PATH));
+}
+async function isFile(target) {
   try {
     const st = await import_node_fs.promises.stat(target);
     return st.isFile();
@@ -7148,13 +7221,14 @@ async function docScopeExists(repoRoot) {
     return false;
   }
 }
-async function deleteDocScope(repoRoot) {
+async function deleteConfig(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;
+  for (const rel of [DELFINI_CONFIG_RELATIVE_PATH, LEGACY_DOC_SCOPE_RELATIVE_PATH]) {
+    try {
+      await import_node_fs.promises.unlink(import_node_path.default.join(root, rel));
+    } catch (err) {
+      if (!isNoEntError(err)) throw err;
+    }
   }
 }
 async function expandDocScope(paths, repoRoot) {
@@ -7413,24 +7487,24 @@ 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);
+  const target = (0, import_node_path3.join)(repoRoot, DELFINI_CONFIG_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)`);
+      log(logger, `delfini-config.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)`);
+  if (await configExists(repoRoot)) {
+    log(logger, `delfini-config.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)`
+      `delfini-config.json \u2192 ${target} (non-interactive shell: scope prompt skipped, no change)`
     );
     return;
   }
@@ -7438,7 +7512,7 @@ async function applyDocScope(repoRoot, logger, provideDocScope) {
   if (paths.length === 0) {
     log(
       logger,
-      `doc-scope.json \u2192 ${target} (no paths provided, no change \u2014 first /delfini run will prompt)`
+      `delfini-config.json \u2192 ${target} (no paths provided, no change \u2014 first /delfini run will prompt)`
     );
     return;
   }
@@ -7458,12 +7532,12 @@ async function promptDocScope() {
 async function persistDocScope(repoRoot, logger, target, paths) {
   try {
     await writeDocScope(paths, { repoRoot });
-    log(logger, `doc-scope.json \u2192 ${target} (wrote ${paths.length} path(s))`);
+    log(logger, `delfini-config.json \u2192 ${target} (wrote ${paths.length} path(s))`);
   } catch (err) {
-    if (err instanceof DocScopeValidationError) {
+    if (err instanceof ConfigValidationError) {
       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.`
+        `delfini-config.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;
     }
@@ -7889,13 +7963,15 @@ async function runLocalPrepare(options = {}) {
     );
   }
   const repoRoot = options.repoRoot ?? await getRepoRoot();
-  const scopePaths = await resolveScopePaths(options.scope, repoRoot);
+  const config = await readConfig(repoRoot);
+  const scopePaths = resolveScopePaths(options.scope, config);
   if (scopePaths === null) {
     stderr.write(
-      "No doc-scope configured. Pass `--scope <paths>` or run the skill\nfirst-run setup to create `.claude/skills/delfini/doc-scope.json`.\n"
+      "No doc-scope configured. Pass `--scope <paths>` or run the skill\nfirst-run setup to create `.claude/skills/delfini/delfini-config.json`.\n"
     );
     return 2;
   }
+  const ignoreCodeScope = resolveIgnoreCodeScope(options.ignoreCodeScope, config);
   const expansion = await expandDocScope(scopePaths, repoRoot);
   for (const missing of expansion.missingPaths) {
     stderr.write(formatMissingPathWarning(missing));
@@ -7905,8 +7981,12 @@ async function runLocalPrepare(options = {}) {
   const rawDiff = await computeDiff(git, repoRoot, baseRef, diffSource);
   let diff = rawDiff;
   let filterResult = null;
-  if (options.enableDiffPreFilter === true) {
-    filterResult = filterDiff(rawDiff);
+  const enableBuiltins = options.enableDiffPreFilter === true;
+  if (enableBuiltins || ignoreCodeScope.length > 0) {
+    filterResult = filterDiff(rawDiff, {
+      builtins: enableBuiltins,
+      ignorePaths: ignoreCodeScope
+    });
     diff = filterResult.keptDiff;
   }
   const docs = await readDocs(expansion.files, repoRoot, stderr);
@@ -7955,7 +8035,7 @@ async function runLocalPrepare(options = {}) {
 `);
   return 0;
 }
-async function resolveScopePaths(scopeOption, repoRoot) {
+function resolveScopePaths(scopeOption, config) {
   if (scopeOption !== void 0) {
     const normalised = normaliseScopeOption(scopeOption);
     if (normalised.length === 0) {
@@ -7963,11 +8043,16 @@ async function resolveScopePaths(scopeOption, repoRoot) {
     }
     return normalised;
   }
-  const persisted = await readDocScope(repoRoot);
-  if (persisted === null) {
+  if (config === null) {
     return null;
   }
-  return persisted.doc_scope;
+  return config.doc_scope;
+}
+function resolveIgnoreCodeScope(ignoreOption, config) {
+  if (ignoreOption !== void 0) {
+    return normaliseScopeOption(ignoreOption);
+  }
+  return config?.ignore_code_scope ?? [];
 }
 function normaliseScopeOption(scope) {
   const raw = Array.isArray(scope) ? scope : scope.split(",");
@@ -8167,7 +8252,7 @@ function readPackageJson() {
 }
 async function main(argv) {
   const program = new import_commander.Command();
-  program.name("delfini").description("Delfini Skill CLI \u2014 deterministic, never calls an LLM.").version(pkg.version, "-V, --version", "print the @delfini/cli version").option("--reset-scope", "delete the persisted doc-scope.json").exitOverride();
+  program.name("delfini").description("Delfini Skill CLI \u2014 deterministic, never calls an LLM.").version(pkg.version, "-V, --version", "print the @delfini/cli version").option("--reset-scope", "delete the persisted delfini-config.json (and any legacy doc-scope.json)").exitOverride();
   program.action(async (opts) => {
     if (opts.resetScope) {
       await handleResetScope();
@@ -8177,7 +8262,7 @@ async function main(argv) {
     "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").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."
+    "Seed delfini-config.json doc_scope 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);
@@ -8187,7 +8272,10 @@ async function main(argv) {
   );
   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(
+  ).option("--scope <paths>", "Comma-separated doc-scope paths (overrides delfini-config.json doc_scope)").option(
+    "--ignore-code-scope <paths>",
+    "Comma-separated code paths whose changes are ignored for analysis (overrides delfini-config.json ignore_code_scope). Each entry is a directory, file, or glob."
+  ).option("--base <ref>", "Diff base ref (default: git merge-base HEAD origin/main)").option(
     "--diff-source <source>",
     "Which diff to analyse: 'local' (default), 'committed', or 'both'",
     "local"
@@ -8216,6 +8304,7 @@ async function main(argv) {
     async (opts) => {
       const exitCode = await runLocalPrepare({
         scope: opts.scope,
+        ignoreCodeScope: opts.ignoreCodeScope,
         base: opts.base,
         diffSource: opts.diffSource,
         relevanceThreshold: opts.relevanceThreshold,
@@ -8245,7 +8334,7 @@ async function main(argv) {
 }
 async function handleResetScope() {
   try {
-    await deleteDocScope();
+    await deleteConfig();
   } catch (err) {
     if (err instanceof RepoRootNotFoundError) {
       return;
@@ -8255,26 +8344,28 @@ async function handleResetScope() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  DOC_SCOPE_RELATIVE_PATH,
-  DOC_SCOPE_VERSION,
-  DocScopeCorruptError,
-  DocScopeValidationError,
-  DocScopeVersionMismatchError,
+  ConfigCorruptError,
+  ConfigValidationError,
+  ConfigVersionMismatchError,
+  DELFINI_CONFIG_RELATIVE_PATH,
+  DELFINI_CONFIG_VERSION,
   InstallToolNotSupportedError,
+  LEGACY_DOC_SCOPE_RELATIVE_PATH,
   PROMPT_TOKEN_BUDGET,
   RepoRootNotFoundError,
   appendToGitignore,
-  deleteDocScope,
-  docScopeExists,
+  configExists,
+  deleteConfig,
   ensureTraceDir,
   expandDocScope,
   getRepoRoot,
   main,
-  readDocScope,
+  readConfig,
   runDiffStatus,
   runInstall,
   runLocalFinalize,
   runLocalPrepare,
+  writeConfig,
   writeDocScope,
   writeRetryAttemptFile,
   writeTraceFile

package/dist/index.d.cts

@@ -1,36 +1,78 @@
 export { main } from './cli.cjs';
 
-declare const DOC_SCOPE_RELATIVE_PATH = ".claude/skills/delfini/doc-scope.json";
-declare const DOC_SCOPE_VERSION: 1;
-interface DocScope {
+declare const DELFINI_CONFIG_RELATIVE_PATH = ".claude/skills/delfini/delfini-config.json";
+declare const LEGACY_DOC_SCOPE_RELATIVE_PATH = ".claude/skills/delfini/doc-scope.json";
+declare const DELFINI_CONFIG_VERSION: 1;
+interface DelfiniConfig {
     version: 1;
     doc_scope: string[];
+    /** Always present after `readConfig` (defaulted to `[]` when absent on disk). */
+    ignore_code_scope: string[];
 }
-interface DocScopeWriteOptions {
+interface ConfigWriteOptions {
     repoRoot?: string;
 }
+/** Partial update applied on top of any existing config by `writeConfig`. */
+interface ConfigUpdate {
+    /** Replace `doc_scope`. Must be non-empty after normalisation. */
+    doc_scope?: string[];
+    /** Replace `ignore_code_scope`. May be empty (means "ignore nothing"). */
+    ignore_code_scope?: string[];
+}
 interface DocScopeExpansionResult {
     /** Absolute paths to files matched by the scope entries. Sorted, deduped. */
     files: string[];
     /** Original entries from `paths` that resolved to nothing on disk. */
     missingPaths: string[];
 }
-declare class DocScopeVersionMismatchError extends Error {
-    readonly code: "DOC_SCOPE_VERSION_MISMATCH";
+declare class ConfigVersionMismatchError extends Error {
+    readonly code: "CONFIG_VERSION_MISMATCH";
     constructor(message?: string);
 }
-declare class DocScopeCorruptError extends Error {
-    readonly code: "DOC_SCOPE_CORRUPT";
+declare class ConfigCorruptError extends Error {
+    readonly code: "CONFIG_CORRUPT";
     constructor(message: string);
 }
-declare class DocScopeValidationError extends Error {
-    readonly code: "DOC_SCOPE_VALIDATION";
+declare class ConfigValidationError extends Error {
+    readonly code: "CONFIG_VALIDATION";
     constructor(message: string);
 }
-declare function readDocScope(repoRoot?: string): Promise<DocScope | null>;
-declare function writeDocScope(paths: string[], options?: DocScopeWriteOptions): Promise<void>;
-declare function docScopeExists(repoRoot?: string): Promise<boolean>;
-declare function deleteDocScope(repoRoot?: string): Promise<void>;
+/**
+ * Read the effective Delfini config, or null if none is configured.
+ *
+ * Resolution order: `delfini-config.json` first, then a legacy
+ * `doc-scope.json` fallback (read-only — migration to the new filename happens
+ * on the next `writeConfig`). `ignore_code_scope` is defaulted to `[]` when
+ * absent so callers never branch on undefined.
+ */
+declare function readConfig(repoRoot?: string): Promise<DelfiniConfig | null>;
+/**
+ * Persist a partial config update, merging over any existing config and
+ * preserving the scope not being edited. Writes `delfini-config.json` and
+ * removes a legacy `doc-scope.json` if present (one-time rename migration).
+ *
+ * `doc_scope` is required to be non-empty in the final config (a Delfini run
+ * with no docs is meaningless); `ignore_code_scope` may be empty.
+ */
+declare function writeConfig(update: ConfigUpdate, options?: ConfigWriteOptions): Promise<void>;
+/**
+ * Persist the doc scope, preserving any existing `ignore_code_scope`. Thin
+ * wrapper over `writeConfig` kept for the install / first-run callers whose
+ * only job is to seed the docs Delfini tracks.
+ */
+declare function writeDocScope(paths: string[], options?: ConfigWriteOptions): Promise<void>;
+/**
+ * True iff a Delfini config exists — the new `delfini-config.json` OR a legacy
+ * `doc-scope.json`. Used by `delfini install` to avoid clobbering an existing
+ * committed, team-shared config.
+ */
+declare function configExists(repoRoot?: string): Promise<boolean>;
+/**
+ * Delete the Delfini config — both the new `delfini-config.json` and any legacy
+ * `doc-scope.json` (`delfini --reset-scope`). Idempotent: absent files are a
+ * silent no-op.
+ */
+declare function deleteConfig(repoRoot?: string): Promise<void>;
 declare function expandDocScope(paths: string[], repoRoot?: string): Promise<DocScopeExpansionResult>;
 
 declare class RepoRootNotFoundError extends Error {
@@ -66,11 +108,11 @@ interface RunInstallOptions {
     /**
      * Resolves the doc-scope path list. When provided, `runInstall` uses it
      * directly (the `--scope` CLI flag and the test seam) and never prompts —
-     * a non-empty list is persisted to `doc-scope.json` (overwriting any
+     * a non-empty list is persisted to `delfini-config.json` doc_scope (overwriting any
      * existing file, since an explicit `--scope` is intent-to-overwrite); an
      * empty list is a no-op. When omitted, `runInstall` prompts interactively
-     * on a TTY only if no `doc-scope.json` exists yet; on a non-TTY stdin, or
-     * when a scope is already configured, it leaves `doc-scope.json` untouched.
+     * on a TTY only if no config exists yet; on a non-TTY stdin, or
+     * when a scope is already configured, it leaves the config untouched.
      * Invalid paths (rejected by `writeDocScope`) warn-and-skip — the scaffold
      * always completes; the SKILL.md first-run prompt re-seeds the scope later.
      */
@@ -88,10 +130,18 @@ declare const PROMPT_TOKEN_BUDGET = 150000;
 interface RunLocalPrepareOptions {
     /**
      * The `--scope <paths>` value. Accepts a comma-separated string OR a string[].
-     * When provided, overrides the persisted `.claude/skills/delfini/doc-scope.json`
+     * When provided, overrides the persisted `delfini-config.json` doc_scope
      * WITHOUT modifying that file (FR144 per-run override invariant).
      */
     scope?: string | string[];
+    /**
+     * The `--ignore-code-scope <paths>` value. Accepts a comma-separated string
+     * OR a string[]. When provided, overrides the persisted `delfini-config.json`
+     * `ignore_code_scope` WITHOUT modifying that file (per-run override). Changed
+     * files matching any entry are dropped from the analysed diff. Empty/omitted
+     * → use the persisted `ignore_code_scope` (or none).
+     */
+    ignoreCodeScope?: string | string[];
     /**
      * The `--base <ref>` value. When provided, used as the diff base directly.
      * When omitted, defaults to `git merge-base HEAD origin/main`.
@@ -210,4 +260,4 @@ interface RunLocalFinalizeOptions {
  */
 declare function runLocalFinalize(options: RunLocalFinalizeOptions): Promise<number>;
 
-export { DOC_SCOPE_RELATIVE_PATH, DOC_SCOPE_VERSION, type DiffSource, type DiffStatus, type DocScope, DocScopeCorruptError, type DocScopeExpansionResult, DocScopeValidationError, DocScopeVersionMismatchError, type DocScopeWriteOptions, type InstallLogger, InstallToolNotSupportedError, PROMPT_TOKEN_BUDGET, RepoRootNotFoundError, type RunDiffStatusOptions, type RunInstallOptions, type RunLocalFinalizeOptions, type RunLocalPrepareOptions, appendToGitignore, deleteDocScope, docScopeExists, ensureTraceDir, expandDocScope, getRepoRoot, readDocScope, runDiffStatus, runInstall, runLocalFinalize, runLocalPrepare, writeDocScope, writeRetryAttemptFile, writeTraceFile };
+export { ConfigCorruptError, type ConfigUpdate, ConfigValidationError, ConfigVersionMismatchError, type ConfigWriteOptions, DELFINI_CONFIG_RELATIVE_PATH, DELFINI_CONFIG_VERSION, type DelfiniConfig, type DiffSource, type DiffStatus, type DocScopeExpansionResult, type InstallLogger, InstallToolNotSupportedError, LEGACY_DOC_SCOPE_RELATIVE_PATH, PROMPT_TOKEN_BUDGET, RepoRootNotFoundError, type RunDiffStatusOptions, type RunInstallOptions, type RunLocalFinalizeOptions, type RunLocalPrepareOptions, appendToGitignore, configExists, deleteConfig, ensureTraceDir, expandDocScope, getRepoRoot, readConfig, runDiffStatus, runInstall, runLocalFinalize, runLocalPrepare, writeConfig, writeDocScope, writeRetryAttemptFile, writeTraceFile };