sdtk-brain-kit 0.1.1 → 0.2.1

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.1`
+Package version in this source snapshot: `0.2.1`
 CLI command: `sdtk-brain`
 
 Standalone by design: not part of the `sdtk-kit` umbrella, installs no agent
@@ -38,6 +38,8 @@ sdtk-brain open                      # docs view + graph view (local viewer, no
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdtk-brain-kit",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "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/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 = {
@@ -122,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.
@@ -133,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;
 }
@@ -251,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);
@@ -270,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/lib/wiki-build.js

@@ -873,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)}`,
     "---",
     "",
@@ -1021,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, workspaceRoot } = {}) {
+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);
@@ -1037,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}, ` +

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),

package/src/lib/wiki-extract.js

@@ -418,7 +418,16 @@ function lineOf(text, needle) {
 function boundedText(value, maxLength = 700) {
   const text = String(value || "").replace(/\s+/g, " ").trim();
   if (text.length <= maxLength) return text;
-  return `${text.slice(0, maxLength - 1).trim()}...`;
+  // Never split a surrogate pair (BK-331): a lone high surrogate cannot
+  // round-trip through fs.writeFileSync (it lands on disk as U+FFFD), so the
+  // regenerated plan content differed from the written page forever and the
+  // page flapped as a permanent apply "conflict" on unchanged input.
+  let cut = text.slice(0, maxLength - 1);
+  const last = cut.charCodeAt(cut.length - 1);
+  if (last >= 0xd800 && last <= 0xdbff) {
+    cut = cut.slice(0, -1);
+  }
+  return `${cut.trim()}...`;
 }
 
 function asArray(value) {