sdtk-brain-kit 0.1.0 → 0.2.0

package/README.md

@@ -6,7 +6,7 @@ layer (`wiki/`) that you — and your AI agent — can search, lint, and browse
 a graph. The agent reading the vault (per its `CLAUDE.md` contract) is the
 knowledge engine; this CLI provides the deterministic rails only.
 
-Package version in this source snapshot: `0.1.0`
+Package version in this source snapshot: `0.2.0`
 CLI command: `sdtk-brain`
 
 Standalone by design: not part of the `sdtk-kit` umbrella, installs no agent
@@ -29,7 +29,7 @@ cp ~/some-article.md raw/inbox/
 sdtk-brain ingest raw/inbox
 sdtk-brain compile --mode safe --apply
 sdtk-brain search "topic"
-sdtk-brain open                      # docs view + graph view (self-contained HTML)
+sdtk-brain open                      # docs view + graph view (local viewer, no server)
 ```
 
 ## Commands
@@ -38,6 +38,8 @@ sdtk-brain open                      # docs view + graph view (self-contained HT
 sdtk-brain init [--vault <path>]     scaffold a vault (refuses non-empty non-vault targets)
 sdtk-brain ingest <file|dir>         semantic extraction over raw sources (report-first)
 sdtk-brain compile --mode safe [--apply]   compile extraction into wiki/ pages
+  --skip-conflicts (with --apply)          apply only the non-conflicting remainder;
+                                           drifted pages stay untouched + reported
 sdtk-brain search [--json] "<q>"     deterministic search over the vault wiki
 sdtk-brain lint | maintain           report-first hygiene (orphans, links, stale, contradictions)
 sdtk-brain discover --plan           gap-analysis plan

package/assets/atlas/doc_atlas_viewer_template.html

@@ -1011,10 +1011,8 @@ body.panel-resizing [data-resizable]{transition:none!important;}
 </nav>
 
 <script src="./mermaid.min.js"></script>
+<script src="./viewer-data.js"></script>
 <script>
-const INDEX = __ATLAS_INDEX_JSON__;
-const GRAPH = __ATLAS_GRAPH_JSON__;
-const FAMILY_COLORS = __ATLAS_FAMILY_COLORS_JSON__;
 const FAMILY_GLYPHS = {
   'governance': 'G', 'product': 'P', 'spec': 'S', 'architecture': 'A', 'database': 'D',
   'api': 'I', 'qa': 'Q', 'design': 'L', 'dev': 'V', 'skill': 'K', 'template': 'T',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdtk-brain-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Standalone local-first second-brain vault CLI: immutable raw/ sources compiled into a markdown wiki/ knowledge layer, maintained by rails (ingest, compile, lint, search, graph viewer) while your agent is the knowledge engine.",
   "type": "commonjs",
   "bin": {

package/src/commands/enrich.js

@@ -24,6 +24,12 @@ Scope:
   Enriches EXTERNAL tool/repo candidates surfaced by the ingest/compile pipeline.
   Not related to your own project docs — those are indexed by "sdtk-brain atlas build".
 
+Options:
+  --source <source>       Required. Only "github" is supported in R1.
+  --mode <mode>           Required. Only "review" is supported in R1.
+  --project-path <path>   Project root. Defaults to the current directory.
+  -h, --help              Show this help.
+
 Safety:
   Review mode only in R1.
   No network fetch, page rewrite, source mutation, apply, entitlement change, or .brain-legacy-unused mutation.

package/src/commands/init.js

@@ -38,6 +38,10 @@ Scaffolds a second-brain vault:
   CLAUDE.md   the agent operating contract (how the vault is maintained)
   README.md   human orientation
 
+Options:
+  --vault <path>          Vault directory (defaults to the current directory).
+  -h, --help              Show this help.
+
 Safety:
   Defaults to the current directory as the vault. Refuses a target that is
   not empty unless it already looks like a vault (re-runs are idempotent and

package/src/commands/open.js

@@ -1,8 +1,10 @@
 "use strict";
 
 // `sdtk-brain open` — build the vault knowledge graph (shared atlas builder,
-// L-5) and open the self-contained viewer. The viewer is a single HTML file
-// with the graph JSON inlined, so file:// works without any server.
+// L-5) and open the viewer. The graph directory is self-contained
+// (viewer.html + viewer-data.js + mermaid.min.js, loaded by relative src),
+// so file:// works without any server (BK-321: data is a sibling script,
+// no longer inlined into a 28MB single file).
 
 const path = require("path");
 const { parseFlags } = require("../lib/args");
@@ -23,10 +25,16 @@ Usage:
   sdtk-brain open [--vault <path>] [--no-open]
 
 Builds the vault knowledge graph over wiki/ and raw/ (shared SDTK atlas
-builder) into .brain/graph and opens the self-contained viewer.html
-(docs view + graph view). --no-open builds without launching a browser.
+builder) into .brain/graph and opens the viewer (docs view + graph view).
+The output directory is self-contained: viewer.html loads its data from
+the sibling viewer-data.js. --no-open builds without launching a browser.
 
-Local-only: no server is required — the viewer inlines its data.`);
+Options:
+  --vault <path>          Vault directory (defaults to the current directory).
+  --no-open               Build without launching a browser.
+  -h, --help              Show this help.
+
+Local-only: no server is required — the viewer directory carries its data.`);
   return 0;
 }
 
@@ -46,7 +54,15 @@ async function cmdOpen(args) {
     return 1;
   }
 
-  const result = await buildAtlas({ projectRoot: vault, outputDir, scanRoots, excludes });
+  // BK-326: point the builder's pages/provenance workspace at .brain so no
+  // stray .sdtk tree ever lands in the vault root.
+  const result = await buildAtlas({
+    projectRoot: vault,
+    outputDir,
+    scanRoots,
+    excludes,
+    workspaceRoot: path.join(vault, ".brain"),
+  });
   const viewer = path.join(outputDir, "viewer.html");
   console.log(`[brain] Graph: ${result.node_count} nodes, ${result.edge_count} edges`);
   console.log(`[brain] Viewer: ${viewer}`);

package/src/commands/operations.js

@@ -23,6 +23,7 @@ const COMPILE_FLAG_DEFS = {
   "project-path": { type: "string" },
   mode: { type: "string" },
   apply: { type: "boolean" },
+  "skip-conflicts": { type: "boolean" },
 };
 
 const QUERY_FLAG_DEFS = {
@@ -110,7 +111,9 @@ Safety:
   No source mutation, local wiki page writes, graph rebuild, web fetch, Ask, raw/provenance mutation, or .brain-legacy-unused mutation.
 
 Next:
-  sdtk-brain compile --mode safe`);
+  sdtk-brain compile --mode safe
+
+Pass -h / --help on any verb to show its help.`);
   return 0;
 }
 
@@ -120,6 +123,16 @@ function cmdCompileHelp() {
 Usage:
   sdtk-brain compile --mode safe [--project-path <path>]
   sdtk-brain compile --mode safe --apply [--project-path <path>]
+  sdtk-brain compile --mode safe --apply --skip-conflicts [--project-path <path>]
+
+Options:
+  --mode safe             Required. Safe mode is the only R1 mode.
+  --apply                 Apply the JSON sidecar (otherwise preview only).
+  --skip-conflicts        With --apply: apply the non-conflicting remainder,
+                          leave every existing-but-different file untouched,
+                          and record the skipped list in .brain/reports.
+  --project-path <path>   Vault directory (--vault works as an alias).
+  -h, --help              Show this help.
 
 Purpose:
   Use the latest semantic extraction report to write a compile preview and JSON sidecar, then optionally apply the sidecar.
@@ -131,7 +144,8 @@ Scope:
 
 Safety:
   Safe mode is the only R1 mode.
-  --apply still uses the existing JSON sidecar contract.
+  --apply still uses the existing JSON sidecar contract; without
+  --skip-conflicts it refuses atomically when any existing file differs.
   No delete, archive, rewrite, raw/provenance mutation, source mutation, web fetch, Ask, or .brain-legacy-unused mutation.`);
   return 0;
 }
@@ -249,6 +263,9 @@ function cmdCompile(args) {
   if (flags.help) return cmdCompileHelp();
   ensureSafeMode(flags.mode, "compile");
   const projectPath = ensureProjectPath(flags["project-path"]);
+  if (flags["skip-conflicts"] && !flags.apply) {
+    throw new ValidationError("--skip-conflicts only makes sense with --apply. No project files were changed.");
+  }
 
   if (!flags.apply) {
     const result = runCompileDryRunFromLatestExtraction(projectPath);
@@ -268,13 +285,23 @@ function cmdCompile(args) {
   }
 
   const sidecar = ensureApplySidecar(projectPath);
-  const result = runWikiCompileApply({ projectPath, planArg: sidecar.sidecarPath });
+  const result = runWikiCompileApply({
+    projectPath,
+    planArg: sidecar.sidecarPath,
+    skipConflicts: Boolean(flags["skip-conflicts"]),
+  });
   console.log(`[brain] Compile apply plan: ${result.planPath}`);
   if (sidecar.createdFreshSidecar) {
     console.log(`[brain] Refreshed compile dry-run preview: ${sidecar.dryRun.reportPath}`);
   }
   console.log(`[brain] Created files: ${result.created.length}`);
   console.log(`[brain] Unchanged files: ${result.unchanged.length}`);
+  if (result.skipped && result.skipped.length > 0) {
+    console.log(`[brain] Skipped ${result.skipped.length} conflicting file(s) (existing content differs): ${result.skipped.join(", ")}`);
+    if (result.skipReportPath) {
+      console.log(`[brain] Skip report: ${result.skipReportPath}`);
+    }
+  }
   console.log(`[brain] Scaffold created/skipped: ${result.scaffoldCreated.length}/${result.scaffoldSkipped.length}`);
   console.log(`[brain] Source-quality warnings: ${result.sourceQualityWarningCount}`);
   console.log("[brain] Canonical local wiki output is <project>/wiki; .brain remains internal state. No source files, raw sources, provenance descriptors, or atlas compatibility files were modified.");

package/src/commands/search.js

@@ -30,6 +30,12 @@ Inputs:
   Duplicate coverage of the same source is de-duplicated; the atlas version wins.
   Each match reports its store (atlas | wiki).
 
+Options:
+  --project-path <path>   Vault directory (--vault works as an alias).
+  --json                  Emit the full result object as JSON.
+  --limit <n>             Maximum matches to display (default 10, max 50).
+  -h, --help              Show this help.
+
 Behavior:
   Read-only and non-premium.
   No wiki.ask entitlement is required.

package/src/commands/status.js

@@ -35,7 +35,7 @@ function countFiles(root, ext) {
 function cmdStatus(args) {
   const { flags } = parseFlags(args || [], STATUS_FLAG_DEFS);
   if (flags.help) {
-    console.log("Usage: sdtk-brain status [--vault <path>] — read-only vault status.");
+    console.log("Usage: sdtk-brain status [--vault <path>] [-h|--help] — read-only vault status.");
     return 0;
   }
   const vault = resolveProjectPath(flags.vault || process.cwd());

package/src/lib/wiki-build.js

@@ -7,7 +7,7 @@ const crypto = require("crypto");
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const ATLAS_STATE_VERSION = 6;
+const ATLAS_STATE_VERSION = 7;
 const WIKI_PAGE_SCHEMA_VERSION = 1;
 const WIKI_PROVENANCE_SCHEMA_VERSION = 1;
 
@@ -514,13 +514,38 @@ function load_atlas_state(atlas_dir) {
   }
 }
 
+// BK-324: the cache exists to skip re-PARSING (reference extraction etc.),
+// not to duplicate content — doc bodies are dropped at save time and
+// rehydrated from the source file on reuse (safe: mtime/hash verified the
+// file is unchanged). Cut the state file ~80% on real corpora.
+function _slim_state_for_save(state) {
+  const documents = {};
+  for (const [rel, record] of Object.entries(state.documents || {})) {
+    if (record && typeof record === "object" && record.doc && typeof record.doc === "object") {
+      const doc = { ...record.doc };
+      delete doc.body_markdown;
+      documents[rel] = { ...record, doc };
+    } else {
+      documents[rel] = record;
+    }
+  }
+  return { ...state, documents };
+}
+
 function save_atlas_state(state, atlas_dir) {
   fs.mkdirSync(atlas_dir, { recursive: true });
   const state_path = _atlas_state_path(atlas_dir);
-  _write_text_lf(state_path, _escapeNonAscii(JSON.stringify(state, null, 2)));
+  _write_text_lf(state_path, _escapeNonAscii(JSON.stringify(_slim_state_for_save(state), null, 2)));
   return state_path;
 }
 
+function _rehydrate_doc_body(doc, md_file) {
+  if (doc.body_markdown != null) return doc;
+  const text = fs.readFileSync(md_file, { encoding: "utf8" });
+  doc.body_markdown = _parse_frontmatter(text)[1];
+  return doc;
+}
+
 function build_docs_incremental(root, atlas_dir, generated, scan_roots, exclude_frags) {
   const prior_state = load_atlas_state(atlas_dir);
   const prior_documents = prior_state.documents || {};
@@ -545,6 +570,7 @@ function build_docs_incremental(root, atlas_dir, generated, scan_roots, exclude_
 
     if (prior_record && typeof prior_record === "object" && prior_doc &&
         prior_record.mtime === current_mtime) {
+      _rehydrate_doc_body(prior_doc, md_file);
       next_documents[rel] = prior_record;
       reused_count++;
       continue;
@@ -553,6 +579,7 @@ function build_docs_incremental(root, atlas_dir, generated, scan_roots, exclude_
     const current_hash = _compute_file_hash(md_file);
     if (prior_record && typeof prior_record === "object" && prior_doc &&
         prior_record.hash === current_hash) {
+      _rehydrate_doc_body(prior_doc, md_file);
       next_documents[rel] = {
         mtime: current_mtime,
         hash: current_hash,
@@ -753,24 +780,37 @@ function build_summary(docs, graph, generated, stats, root, scan_roots, exclude_
 // ---------------------------------------------------------------------------
 // Viewer builder
 // ---------------------------------------------------------------------------
-function build_viewer(index, graph, generated) {
-  if (!fs.existsSync(_VIEWER_TEMPLATE_PATH)) {
-    throw new Error(`Viewer template not found: ${_VIEWER_TEMPLATE_PATH}`);
-  }
+// BK-321: the doc index/graph are written to a sibling viewer-data.js instead
+// of being inlined into viewer.html (which grew to ~28MB on real corpora).
+// The viewer already loads ./mermaid.min.js by relative src, so a sibling
+// data script works identically under file:// and the atlas server. Top-level
+// const bindings in a classic script are visible to later classic scripts,
+// so the template's main script keeps using INDEX/GRAPH/FAMILY_COLORS as-is.
+function build_viewer_data(index, graph) {
+  // String concatenation, not String.replace: replace's string form treats
+  // "$&", "$`", "$'", "$$", "$<n>" in doc content as special patterns and
+  // spliced garbage into the script (BK-317). Concatenation has no such
+  // semantics, so "$"-bearing content is inherently safe here.
   const index_json = _json_for_inline_script(index);
   const graph_json = _json_for_inline_script(graph);
   const family_colors_json = _json_for_inline_script(_FAMILY_COLORS);
+  return [
+    "// Generated by the SDTK atlas builder — regenerable via `atlas build`, do not edit.",
+    "const INDEX = " + index_json + ";",
+    "const GRAPH = " + graph_json + ";",
+    "const FAMILY_COLORS = " + family_colors_json + ";",
+    "",
+  ].join("\n");
+}
+
+function build_viewer(generated) {
+  if (!fs.existsSync(_VIEWER_TEMPLATE_PATH)) {
+    throw new Error(`Viewer template not found: ${_VIEWER_TEMPLATE_PATH}`);
+  }
   const template = fs.readFileSync(_VIEWER_TEMPLATE_PATH, "utf8");
-  // Replacer functions, not plain strings: String.prototype.replace treats a
-  // string replacement's "$&", "$`", "$'", "$$", "$<n>" sequences as special
-  // patterns. Indexed doc content routinely contains "$" (shell docs, prices,
-  // template-literal examples), which previously spliced stray template/JSON
-  // fragments into the inline script and broke it (BK-317).
-  return template
-    .replace(/__ATLAS_GENERATED__/g, () => generated)
-    .replace(/__ATLAS_INDEX_JSON__/g, () => index_json)
-    .replace(/__ATLAS_GRAPH_JSON__/g, () => graph_json)
-    .replace(/__ATLAS_FAMILY_COLORS_JSON__/g, () => family_colors_json);
+  // Replacer function per BK-317 discipline (timestamp is "$"-free today, but
+  // the string form's special-pattern hazard is not worth re-litigating).
+  return template.replace(/__ATLAS_GENERATED__/g, () => generated);
 }
 
 function copy_viewer_assets(atlas_dir) {
@@ -786,9 +826,13 @@ function copy_viewer_assets(atlas_dir) {
 // ---------------------------------------------------------------------------
 // Wiki pages + provenance
 // ---------------------------------------------------------------------------
-function _wiki_workspace_root(root) { return path.join(root, ".sdtk", "wiki"); }
-function _wiki_pages_root(root) { return path.join(_wiki_workspace_root(root), "pages"); }
-function _wiki_provenance_root(root) { return path.join(_wiki_workspace_root(root), "provenance"); }
+// BK-326: the workspace root is overridable so hosts with a different
+// machine-state home (sdtk-brain uses `.brain/`) don't get a stray
+// `.sdtk/wiki` tree leaked into their vault root. sdtk-wiki's default is
+// unchanged.
+function _wiki_workspace_root(root, workspace_root) {
+  return workspace_root ? path.resolve(workspace_root) : path.join(root, ".sdtk", "wiki");
+}
 
 function _stable_page_id(source_path) {
   const norm = source_path.replace(/\\/g, "/");
@@ -803,12 +847,12 @@ function _safe_slug(value) {
   return slug || "page";
 }
 
-function _page_relative_path(doc) {
+function _page_relative_path(doc, pages_prefix) {
   const source_path = String(doc.path).replace(/\\/g, "/");
   const source_digest = crypto.createHash("sha256").update(source_path, "utf8").digest("hex").slice(0, 8);
   const slug = _safe_slug(String(doc.title || path.parse(source_path).name));
   const family = _safe_slug(String(doc.family || "other-markdown"));
-  return `.sdtk/wiki/pages/${family}/${slug}--${source_digest}.md`;
+  return `${pages_prefix || ".sdtk/wiki/pages"}/${family}/${slug}--${source_digest}.md`;
 }
 
 function _yaml_quote(value) {
@@ -829,6 +873,7 @@ function _render_generated_page(doc, page_id, source_hash, generated) {
     `title: ${_yaml_quote(doc.title || "")}`,
     `family: ${_yaml_quote(doc.family || "")}`,
     `role: ${_yaml_quote(doc.role || "")}`,
+    `trust_zone: ${_yaml_quote(doc.trust_zone || "medium")}`,
     `generated_at: ${_yaml_quote(generated)}`,
     "---",
     "",
@@ -871,10 +916,16 @@ function _build_change_set(prior_hashes, current_hashes) {
   return { added, changed, unchanged, removed };
 }
 
-function write_wiki_pages_and_provenance(docs, state, root, generated, scan_roots) {
-  const workspace_root = _wiki_workspace_root(root);
-  const pages_root = _wiki_pages_root(root);
-  const provenance_root = _wiki_provenance_root(root);
+function write_wiki_pages_and_provenance(docs, state, root, generated, scan_roots, workspaceRoot) {
+  const workspace_root = _wiki_workspace_root(root, workspaceRoot);
+  const pages_root = path.join(workspace_root, "pages");
+  const provenance_root = path.join(workspace_root, "provenance");
+  // Page paths are recorded relative to the project root (posix separators)
+  // so provenance and _index.md stay portable.
+  const pages_prefix = path
+    .relative(root, pages_root)
+    .split(path.sep)
+    .join("/");
   const sources_path = path.join(provenance_root, "sources.json");
   const changes_path = path.join(provenance_root, "changes.json");
 
@@ -897,7 +948,7 @@ function write_wiki_pages_and_provenance(docs, state, root, generated, scan_root
       source_hash = crypto.createHash("sha256").update(source_path, "utf8").digest("hex");
     }
     const page_id = _stable_page_id(source_path);
-    const page_rel = _page_relative_path(doc);
+    const page_rel = _page_relative_path(doc, pages_prefix);
     const page_path = path.join(root, page_rel);
 
     _assert_inside(workspace_root, page_path);
@@ -971,7 +1022,7 @@ function write_wiki_pages_and_provenance(docs, state, root, generated, scan_root
 // ---------------------------------------------------------------------------
 // Top-level buildAtlas
 // ---------------------------------------------------------------------------
-async function buildAtlas({ projectRoot, outputDir, scanRoots, excludes, verbose } = {}) {
+async function buildAtlas({ projectRoot, outputDir, scanRoots, excludes, verbose, workspaceRoot, archiveFrags } = {}) {
   const generated = _now_utc();
   const root = path.resolve(projectRoot);
   const atlas_dir = path.resolve(outputDir);
@@ -987,6 +1038,18 @@ async function buildAtlas({ projectRoot, outputDir, scanRoots, excludes, verbose
   process.stdout.write("[atlas] Scanning markdown files...\n");
   const [docs, state, stats] = build_docs_incremental(root, atlas_dir, generated, roots, frags);
 
+  // BK-325: archive tier. Applied to EVERY doc after the incremental pass —
+  // cache-reused docs carry the trust_zone of the build that cached them, so
+  // re-deriving here keeps tiering correct when the config changes without a
+  // reparse. Same path-fragment matching semantics as `excludes`.
+  const archive_frags = Array.isArray(archiveFrags) ? archiveFrags.filter(Boolean) : [];
+  for (const doc of docs) {
+    const abs = path.join(root, doc.path);
+    doc.trust_zone = archive_frags.length > 0 && _match_exclude(abs, root, archive_frags)
+      ? "archive"
+      : "medium";
+  }
+
   process.stdout.write(`[atlas] Indexed ${docs.length} documents.\n`);
   process.stdout.write(
     `[atlas] Scan coverage: scanned ${stats.scanned_count !== undefined ? stats.scanned_count : docs.length}, ` +
@@ -1008,7 +1071,7 @@ async function buildAtlas({ projectRoot, outputDir, scanRoots, excludes, verbose
   process.stdout.write(`[atlas] Graph: ${graph.nodes.length} nodes, ${graph.edges.length} edges.\n`);
 
   process.stdout.write("[atlas] Writing wiki pages and provenance...\n");
-  const wiki_result = write_wiki_pages_and_provenance(docs, state, root, generated, roots);
+  const wiki_result = write_wiki_pages_and_provenance(docs, state, root, generated, roots, workspaceRoot);
   process.stdout.write(`[atlas] Wiki pages: ${wiki_result.page_count}\n`);
 
   const index_data = {
@@ -1036,7 +1099,9 @@ async function buildAtlas({ projectRoot, outputDir, scanRoots, excludes, verbose
   const summary_path = path.join(atlas_dir, "SDTK_DOC_ATLAS_SUMMARY.md");
   _write_text_lf(summary_path, summary_text);
 
-  const viewer_html = build_viewer(index_data, graph_out, generated);
+  const viewer_data_js = build_viewer_data(index_data, graph_out);
+  _write_text_lf(path.join(atlas_dir, "viewer-data.js"), viewer_data_js);
+  const viewer_html = build_viewer(generated);
   const viewer_path = path.join(atlas_dir, "viewer.html");
   _write_text_lf(viewer_path, viewer_html);
 
@@ -1089,6 +1154,7 @@ module.exports = {
   build_graph,
   build_summary,
   build_viewer,
+  build_viewer_data,
   write_wiki_pages_and_provenance,
   load_atlas_state,
   save_atlas_state,

package/src/lib/wiki-compile.js

@@ -1975,7 +1975,7 @@ function scaffoldCanonicalWikiStructure(projectPath) {
   return { created, skipped };
 }
 
-function runWikiCompileApply({ projectPath, planArg }) {
+function runWikiCompileApply({ projectPath, planArg, skipConflicts = false }) {
   const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
   if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
     throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}`);
@@ -2012,8 +2012,8 @@ function runWikiCompileApply({ projectPath, planArg }) {
       }
     }
 
-    if (conflicts.length > 0) {
-      throw new ValidationError(`Compile apply would overwrite ${conflicts.length} existing different file(s): ${conflicts.join(", ")}. No project files were changed.`);
+    if (conflicts.length > 0 && !skipConflicts) {
+      throw new ValidationError(`Compile apply would overwrite ${conflicts.length} existing different file(s): ${conflicts.join(", ")}. No project files were changed. Pass --skip-conflicts to apply the non-conflicting remainder and leave these files untouched.`);
     }
 
     const created = [];
@@ -2025,10 +2025,39 @@ function runWikiCompileApply({ projectPath, planArg }) {
     }
 
     const sourceQualitySummary = payload.source_quality_summary || emptySourceQualitySummary();
+    // BK-327: when --skip-conflicts applied a partial plan, record the
+    // decision durably so the skip list is auditable later.
+    let skipReportPath = null;
+    if (skipConflicts) {
+      const reportsPath = getWikiReportsPath(resolvedProjectPath);
+      assertWikiWorkspaceWritePath(reportsPath, resolvedProjectPath);
+      fs.mkdirSync(reportsPath, { recursive: true });
+      skipReportPath = path.join(reportsPath, `compile-apply-result-${todayStamp()}.json`);
+      assertWikiWorkspaceWritePath(skipReportPath, resolvedProjectPath);
+      fs.writeFileSync(
+        skipReportPath,
+        JSON.stringify(
+          {
+            generated_at: new Date().toISOString(),
+            plan_path: planPath,
+            mode: "skip_conflicts",
+            created,
+            unchanged_count: unchanged.length,
+            skipped: conflicts,
+          },
+          null,
+          2
+        ) + "\n",
+        "utf-8"
+      );
+    }
+
     return {
       planPath,
       created,
       unchanged,
+      skipped: conflicts,
+      skipReportPath,
       scaffoldCreated: scaffold.created,
       scaffoldSkipped: scaffold.skipped,
       sourceQualityWarningCount: Number(sourceQualitySummary.warning_count || sourceQualitySummary.findings_count || 0),