skillwiki 0.10.9 → 0.10.11

package/dist/{chunk-AVCGIWSL.js → chunk-P2FCRGKU.js}

@@ -22,6 +22,7 @@ import {
 } from "./chunk-U34B2XQJ.js";
 import {
   CONFIG_KEYS,
+  git,
   isValidWikiProfileKey,
   listReviewRequiredOps,
   loadFleetManifestAndHost,
@@ -3212,12 +3213,13 @@ function buildCliSurface() {
   program.command("sync");
   program.command("backup");
   program.command("seed").option("--wiki <name>");
-  program.command("observe").requiredOption("--text <text>").option("--kind <kind>").option("--project <slug>").option("--wiki <name>");
+  program.command("observe").requiredOption("--text <text>").option("--kind <kind>").option("--project <slug>").option("--severity <level>").option("--capture-budget <n>").option("--wiki <name>");
   program.command("session-brief").option("--project <slug>").option("--write").option("--wiki <name>");
   program.command("memory");
   program.command("ingest").requiredOption("--vault <path>").requiredOption("--type <type>").requiredOption("--title <title>").option("--tags <csv>").option("--provenance <provenance>").option("--dry-run");
   program.command("fleet");
   program.command("page");
+  program.command("write-preflight").option("--command <name>").option("--dirty-threshold <n>").option("--skip-dirty").option("--prior-artifact-file <path>").option("--prior-artifact-text <text>").option("--consecutive-no-decision <n>").option("--no-decision-threshold <n>").option("--human-allow").option("--mission-kind <kind>").option("--skip-mission").option("--project <slug>").option("--capture-day <date>").option("--capture-budget <n>").option("--severity <level>").option("--skip-budget").option("--checks <list>").option("--wiki <name>");
   const graphCmd = program.commands.find((c) => c.name() === "graph");
   graphCmd.command("build").option("--out <path>").option("--wiki <name>");
   const canvasCmd = program.commands.find((c) => c.name() === "canvas");
@@ -4650,7 +4652,7 @@ async function runSyncLintDelta(input) {
   const { mkdtempSync, rmSync, existsSync: fsExists } = await import("fs");
   const { join: pathJoin } = await import("path");
   const { tmpdir } = await import("os");
-  const { execFileSync: execFileSync2 } = await import("child_process");
+  const { execFileSync: execFileSync3 } = await import("child_process");
   const vault = input.vault;
   const baseRef = input.baseRef ?? "origin/main";
   const days = input.days ?? 90;
@@ -4663,7 +4665,7 @@ async function runSyncLintDelta(input) {
     };
   }
   try {
-    execFileSync2("git", ["rev-parse", "--verify", baseRef], {
+    execFileSync3("git", ["rev-parse", "--verify", baseRef], {
       cwd: vault,
       stdio: ["pipe", "pipe", "pipe"]
     });
@@ -4693,12 +4695,12 @@ async function runSyncLintDelta(input) {
   const fullFps = collectLintErrorFingerprints(fullOutput);
   const tmpRoot = mkdtempSync(pathJoin(tmpdir(), "skillwiki-lint-delta-"));
   try {
-    const archive = execFileSync2("git", ["archive", "--format=tar", baseRef], {
+    const archive = execFileSync3("git", ["archive", "--format=tar", baseRef], {
       cwd: vault,
       stdio: ["pipe", "pipe", "pipe"],
       maxBuffer: 256 * 1024 * 1024
     });
-    execFileSync2("tar", ["-xf", "-"], {
+    execFileSync3("tar", ["-xf", "-"], {
       cwd: tmpRoot,
       input: archive,
       stdio: ["pipe", "pipe", "pipe"]
@@ -7124,10 +7126,401 @@ function readCliPackageJson(baseUrl = import.meta.url) {
   throw new Error(`Could not locate skillwiki package.json from ${baseUrl}`);
 }
 
+// src/utils/vault-write-gates.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import { existsSync as existsSync14, readdirSync as readdirSync4, readFileSync as readFileSync12, statSync as statSync3 } from "fs";
+import { join as join26, relative as relative3 } from "path";
+var DEFAULT_DIRTY_VOLUME_THRESHOLD = 50;
+var DEFAULT_CAPTURE_BUDGET = 20;
+var DEFAULT_NO_DECISION_STREAK = 3;
+var GateError = {
+  VAULT_DIRTY_BACKLOG: "VAULT_DIRTY_BACKLOG",
+  DIMINISHING_RETURNS: "DIMINISHING_RETURNS",
+  CAPTURE_BUDGET_EXHAUSTED: "CAPTURE_BUDGET_EXHAUSTED",
+  USAGE: "USAGE",
+  VAULT_PATH_INVALID: "VAULT_PATH_INVALID"
+};
+var HYGIENE_COMMANDS = /* @__PURE__ */ new Set([
+  "write-preflight",
+  "sync status",
+  "sync push",
+  "sync pull",
+  "sync lock",
+  "sync unlock",
+  "sync resolve-derived",
+  "sync journal list",
+  "sync journal clear-stale",
+  "sync lint-delta",
+  "sync peers",
+  "work-complete",
+  "work-validate",
+  "log materialize",
+  "log migrate-legacy",
+  "index rebuild",
+  "projections materialize",
+  "doctor",
+  "health",
+  "lint",
+  "status",
+  "path",
+  "fleet context",
+  "fleet validate",
+  "fleet health"
+]);
+function isHygieneCommand(command) {
+  const c = command.trim().toLowerCase().replace(/\s+/g, " ");
+  if (HYGIENE_COMMANDS.has(c)) return true;
+  if (c === "sync" || c.startsWith("sync ")) {
+    const rest = c.slice(5).trim();
+    if (!rest) return true;
+    return HYGIENE_COMMANDS.has(`sync ${rest}`);
+  }
+  return false;
+}
+function measureDirtyVolume(vault) {
+  const empty = (extra = {}) => ({
+    porcelain_lines: 0,
+    expanded_files: 0,
+    modified: 0,
+    untracked: 0,
+    buckets: [],
+    threshold: 0,
+    over_threshold: false,
+    is_git_repo: false,
+    ...extra
+  });
+  if (!existsSync14(vault) || !statSync3(vault).isDirectory()) {
+    return empty();
+  }
+  const gitDir = git(vault, ["rev-parse", "--absolute-git-dir"]);
+  if (!gitDir) {
+    return empty({ is_git_repo: false });
+  }
+  let porcelain = "";
+  try {
+    porcelain = execFileSync2("git", ["status", "--porcelain"], {
+      cwd: vault,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch {
+    porcelain = "";
+  }
+  const lines = porcelain.replace(/\n+$/, "").split("\n").filter((l) => l.length > 0);
+  let modified = 0;
+  let untracked = 0;
+  let expanded = 0;
+  const bucketMap = /* @__PURE__ */ new Map();
+  const addBucket = (rel, n) => {
+    const top = rel.split(/[/\\]/)[0] || ".";
+    bucketMap.set(top, (bucketMap.get(top) ?? 0) + n);
+  };
+  for (const line of lines) {
+    const match = line.match(/^(.{2}) (.*)$/);
+    if (!match) continue;
+    const code = match[1];
+    let pathPart = match[2] ?? "";
+    if (pathPart.includes(" -> ")) {
+      pathPart = pathPart.split(" -> ").pop() ?? pathPart;
+    }
+    const rel = pathPart.replace(/^"(.*)"$/, "$1").trim();
+    if (!rel) continue;
+    if (code === "??") {
+      untracked += 1;
+      const abs = join26(vault, rel);
+      if (existsSync14(abs) && statSync3(abs).isDirectory()) {
+        const files = listFilesRecursive(abs);
+        expanded += files.length;
+        addBucket(rel, files.length);
+      } else {
+        expanded += 1;
+        addBucket(rel, 1);
+      }
+    } else {
+      modified += 1;
+      expanded += 1;
+      addBucket(rel, 1);
+    }
+  }
+  const buckets = [...bucketMap.entries()].map(([bucket, count]) => ({ bucket, count })).sort((a, b) => b.count - a.count);
+  return {
+    porcelain_lines: lines.length,
+    expanded_files: expanded,
+    modified,
+    untracked,
+    buckets,
+    threshold: 0,
+    over_threshold: false,
+    is_git_repo: true
+  };
+}
+function listFilesRecursive(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync4(dir);
+  } catch {
+    return out;
+  }
+  for (const name of entries) {
+    if (name === ".git") continue;
+    const p = join26(dir, name);
+    try {
+      const st = statSync3(p);
+      if (st.isDirectory()) out.push(...listFilesRecursive(p));
+      else if (st.isFile()) out.push(p);
+    } catch {
+    }
+  }
+  return out;
+}
+function evaluateDirtyVolumeGate(input) {
+  const threshold = input.threshold ?? DEFAULT_DIRTY_VOLUME_THRESHOLD;
+  const report = measureDirtyVolume(input.vault);
+  report.threshold = threshold;
+  report.over_threshold = report.is_git_repo && report.expanded_files > threshold;
+  if (input.skip) {
+    return { allowed: true, reason: "skipped", report };
+  }
+  if (input.command && isHygieneCommand(input.command)) {
+    return { allowed: true, reason: "hygiene", report };
+  }
+  if (!report.is_git_repo) {
+    return { allowed: true, reason: "not_a_git_repo", report };
+  }
+  if (!report.over_threshold) {
+    return { allowed: true, reason: "under_threshold", report };
+  }
+  const top = report.buckets.slice(0, 5).map((b) => `${b.bucket}:${b.count}`).join(", ");
+  return {
+    allowed: false,
+    reason: "over_threshold",
+    code: GateError.VAULT_DIRTY_BACKLOG,
+    report,
+    humanHint: `Vault dirty volume ${report.expanded_files} exceeds threshold ${threshold} (porcelain ${report.porcelain_lines}; buckets: ${top || "none"}). Triage/commit keep-set before more non-hygiene writes. Hygiene commands still allowed.`
+  };
+}
+var SATURATION_PATTERNS = [
+  /\benablement\s+\*\*saturated\*\*/i,
+  /\bsaturated\b/i,
+  /\bexplicit hold\b/i,
+  /\bno further\b.*\bbatches\b/i,
+  /\bpause (?:the )?job\b/i,
+  /\bcancel research\b/i,
+  /\bkill research\b/i,
+  /\bdiminishing returns\b/i,
+  /\bhuman send only\b/i,
+  /\bno new decision\b/i,
+  /\bHOLD:\b/,
+  /\bstatus:\s*saturated\b/i,
+  /\bmission:\s*cancelled\b/i,
+  /\bcancelled mission\b/i
+];
+function detectSaturationSignals(text) {
+  if (!text) return [];
+  const hits = [];
+  for (const re of SATURATION_PATTERNS) {
+    const m = text.match(re);
+    if (m) hits.push(m[0]);
+  }
+  return hits;
+}
+function evaluateMissionCycleGate(input) {
+  if (input.humanAllow) {
+    return { allowed: true, reason: "human_allow", signals: [] };
+  }
+  const signals = detectSaturationSignals(input.priorArtifactText ?? "");
+  if (signals.length > 0) {
+    return {
+      allowed: false,
+      reason: "saturated_text",
+      code: GateError.DIMINISHING_RETURNS,
+      signals,
+      humanHint: `Mission saturated/hold/stop signal(s) in prior artifact: ${signals.slice(0, 5).join("; ")}. Refuse new ${input.missionKind ?? "cycle"} artifact without --human-allow.`
+    };
+  }
+  const streak = input.consecutiveNoNewDecision ?? 0;
+  const thresh = input.noDecisionThreshold ?? DEFAULT_NO_DECISION_STREAK;
+  if (streak >= thresh) {
+    return {
+      allowed: false,
+      reason: "no_decision_streak",
+      code: GateError.DIMINISHING_RETURNS,
+      signals: [`no_new_decision_streak=${streak}`],
+      humanHint: `${streak} consecutive no-new-decision cycles (\u2265 ${thresh}). Refuse further cycle artifacts without --human-allow.`
+    };
+  }
+  return { allowed: true, reason: "clean", signals: [] };
+}
+function utcDay(d = /* @__PURE__ */ new Date()) {
+  return d.toISOString().slice(0, 10);
+}
+var CAPTURE_HYGIENE_CONTRACT = `After each productive cycle (or when daily capture budget is reached), stage/commit the keep-set or discard noise so untracked investigate files for the project stay within the daily budget (default ${DEFAULT_CAPTURE_BUDGET}). P0 severity escapes the budget. Do not silently grow unbounded untracked investigate files.`;
+function listProjectDayCaptures(vault, project, day) {
+  const found = [];
+  const slug = project.replace(/^\[\[/, "").replace(/\]\]$/, "").trim();
+  if (!slug || !existsSync14(vault)) return found;
+  const consider = (abs, rel) => {
+    if (!rel.endsWith(".md")) return;
+    const base = rel.split(/[/\\]/).pop() ?? "";
+    if (!base.startsWith(day)) return;
+    const normRel = rel.replace(/\\/g, "/");
+    const captureLike = /investigate|dev-loop|research-cycle|pilot-q|cycle-\d+|batch-|idle-no-new|observation/.test(normRel) || /(^|\/)raw\/transcripts\//.test(normRel) || /(^|\/)requirements\//.test(normRel);
+    if (!captureLike && !/transcripts/.test(normRel)) {
+      return;
+    }
+    const norm = rel.replace(/\\/g, "/");
+    if (norm.startsWith(`projects/${slug}/`)) {
+      found.push(norm);
+      return;
+    }
+    if (norm.startsWith("raw/transcripts/")) {
+      try {
+        const body = readFileSync12(abs, "utf8");
+        if (body.includes(`project: ${slug}`) || body.includes(`project: "[[${slug}]]"`) || body.includes(`project: [[${slug}]]`)) {
+          found.push(norm);
+        } else if (base.includes(slug)) {
+          found.push(norm);
+        }
+      } catch {
+      }
+    }
+  };
+  const walk = (dir, relBase) => {
+    if (!existsSync14(dir)) return;
+    let entries;
+    try {
+      entries = readdirSync4(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      const abs = join26(dir, name);
+      const rel = relBase ? `${relBase}/${name}` : name;
+      try {
+        const st = statSync3(abs);
+        if (st.isDirectory()) walk(abs, rel);
+        else if (st.isFile()) consider(abs, rel);
+      } catch {
+      }
+    }
+  };
+  walk(join26(vault, "raw", "transcripts"), "raw/transcripts");
+  walk(join26(vault, "projects", slug, "raw", "transcripts"), `projects/${slug}/raw/transcripts`);
+  walk(join26(vault, "projects", slug, "requirements"), `projects/${slug}/requirements`);
+  const workRoot = join26(vault, "projects", slug, "work");
+  if (existsSync14(workRoot)) {
+    try {
+      for (const name of readdirSync4(workRoot)) {
+        if (!name.startsWith(day)) continue;
+        if (!/investigate|pilot-q|research|cycle|dev-loop/.test(name)) continue;
+        const abs = join26(workRoot, name);
+        if (statSync3(abs).isDirectory()) {
+          for (const f of listFilesRecursive(abs)) {
+            const rel = relative3(vault, f).replace(/\\/g, "/");
+            if (rel.endsWith(".md")) found.push(rel);
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return [...new Set(found)].sort();
+}
+function evaluateCaptureBudget(input) {
+  const day = input.day ?? utcDay();
+  const budget = input.budget ?? DEFAULT_CAPTURE_BUDGET;
+  const paths = listProjectDayCaptures(input.vault, input.project, day);
+  const used = paths.length;
+  const report = {
+    project: input.project,
+    day,
+    budget,
+    used,
+    remaining: Math.max(0, budget - used),
+    paths
+  };
+  if (input.skip) {
+    return { allowed: true, reason: "skipped", report };
+  }
+  const sev = (input.severity ?? "").toString().trim().toUpperCase();
+  if (sev === "P0" || sev === "0") {
+    return { allowed: true, reason: "p0_escape", report };
+  }
+  if (used >= budget) {
+    return {
+      allowed: false,
+      reason: "exhausted",
+      code: GateError.CAPTURE_BUDGET_EXHAUSTED,
+      report,
+      humanHint: `Capture budget exhausted for project ${input.project} on ${day}: ${used}/${budget}. ${CAPTURE_HYGIENE_CONTRACT}`
+    };
+  }
+  return { allowed: true, reason: "under_budget", report };
+}
+function runWritePreflight(input) {
+  if (!input.vault || !existsSync14(input.vault)) {
+    return err(GateError.VAULT_PATH_INVALID, { path: input.vault });
+  }
+  const want = new Set(input.checks ?? ["all"]);
+  const runAll = want.has("all");
+  const checks = {};
+  const refused = [];
+  if (runAll || want.has("dirty")) {
+    const dirty = evaluateDirtyVolumeGate({
+      vault: input.vault,
+      threshold: input.dirtyThreshold,
+      skip: input.skipDirty,
+      command: input.command
+    });
+    checks.dirty = dirty;
+    if (!dirty.allowed) {
+      refused.push({ code: dirty.code, humanHint: dirty.humanHint });
+    }
+  }
+  const missionRequested = runAll || want.has("mission") || input.priorArtifactText != null || input.consecutiveNoNewDecision != null;
+  if (missionRequested && !input.skipMission) {
+    if (want.has("mission") || input.priorArtifactText != null && input.priorArtifactText.length > 0 || input.consecutiveNoNewDecision != null && input.consecutiveNoNewDecision > 0) {
+      const mission = evaluateMissionCycleGate({
+        priorArtifactText: input.priorArtifactText,
+        consecutiveNoNewDecision: input.consecutiveNoNewDecision,
+        noDecisionThreshold: input.noDecisionThreshold,
+        humanAllow: input.humanAllow,
+        missionKind: input.missionKind
+      });
+      checks.mission = mission;
+      if (!mission.allowed) {
+        refused.push({ code: mission.code, humanHint: mission.humanHint });
+      }
+    }
+  }
+  if ((runAll || want.has("budget")) && input.project && !input.skipBudget) {
+    const budget = evaluateCaptureBudget({
+      vault: input.vault,
+      project: input.project,
+      day: input.captureDay,
+      budget: input.captureBudget,
+      severity: input.severity
+    });
+    checks.budget = budget;
+    if (!budget.allowed) {
+      refused.push({ code: budget.code, humanHint: budget.humanHint });
+    }
+  }
+  const allowed = refused.length === 0;
+  return ok({
+    allowed,
+    checks,
+    refused,
+    hygiene_contract: CAPTURE_HYGIENE_CONTRACT,
+    humanHint: allowed ? "write preflight: allowed" : `write preflight: refused \u2014 ${refused.map((r) => r.code).join(", ")}`
+  });
+}
+
 // src/commands/observe.ts
 import { mkdir as mkdir6, writeFile as writeFile4 } from "fs/promises";
-import { existsSync as existsSync14, statSync as statSync3 } from "fs";
-import { join as join26 } from "path";
+import { existsSync as existsSync15, statSync as statSync4 } from "fs";
+import { join as join27 } from "path";
 import { createHash as createHash6 } from "crypto";
 var ALLOWED_KINDS = /* @__PURE__ */ new Set(["note", "bug", "task", "idea", "session-log"]);
 function slugify(text) {
@@ -7150,13 +7543,33 @@ async function runObserve(input) {
       result: err("SCHEME_REJECTED", { message: "Text must not be empty" })
     };
   }
-  if (!existsSync14(input.vault) || !statSync3(input.vault).isDirectory()) {
+  if (!existsSync15(input.vault) || !statSync4(input.vault).isDirectory()) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("VAULT_PATH_INVALID", { path: input.vault })
     };
   }
-  const transcriptsDir = join26(input.vault, "raw", "transcripts");
+  if (input.project && !input.skipCaptureBudget) {
+    const budget = evaluateCaptureBudget({
+      vault: input.vault,
+      project: input.project,
+      day: input.captureDay,
+      budget: input.captureBudget,
+      severity: input.severity
+    });
+    if (!budget.allowed) {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err(GateError.CAPTURE_BUDGET_EXHAUSTED, {
+          reason: budget.reason,
+          report: budget.report,
+          humanHint: budget.humanHint,
+          hygiene_contract: CAPTURE_HYGIENE_CONTRACT
+        })
+      };
+    }
+  }
+  const transcriptsDir = join27(input.vault, "raw", "transcripts");
   try {
     await mkdir6(transcriptsDir, { recursive: true });
   } catch {
@@ -7168,7 +7581,7 @@ async function runObserve(input) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const slug = slugify(input.text);
   const fileName = `${today}-observation-${slug}.md`;
-  const filePath = join26(transcriptsDir, fileName);
+  const filePath = join27(transcriptsDir, fileName);
   const body = `
 ${input.text.trim()}
 `;
@@ -7210,7 +7623,7 @@ ${input.text.trim()}
 // src/commands/memory.ts
 import { createHash as createHash7 } from "crypto";
 import { mkdir as mkdir7, readFile as readFile17, readdir as readdir5, stat as stat5, writeFile as writeFile5 } from "fs/promises";
-import { basename as basename2, extname, join as join27, relative as relative3, sep as sep3 } from "path";
+import { basename as basename2, extname, join as join28, relative as relative4, sep as sep3 } from "path";
 
 // src/utils/memory-authority.ts
 var TIER_RANK = {
@@ -7329,8 +7742,8 @@ async function runMemoryIndex(input) {
   }
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
   const relCachePath = memoryCacheRelPath(input.project);
-  const absCachePath = join27(input.vault, relCachePath);
-  await mkdir7(join27(input.vault, ".skillwiki", "memory", input.project), { recursive: true });
+  const absCachePath = join28(input.vault, relCachePath);
+  await mkdir7(join28(input.vault, ".skillwiki", "memory", input.project), { recursive: true });
   await writeFile5(absCachePath, `${JSON.stringify({
     generated_at: generatedAt,
     project: input.project,
@@ -7522,7 +7935,7 @@ async function buildMemoryIndexState(pages, project) {
 }
 async function checkMemoryIndex(vault, project, current) {
   const relCachePath = memoryCacheRelPath(project);
-  const cacheText = await readIfExists2(join27(vault, relCachePath));
+  const cacheText = await readIfExists2(join28(vault, relCachePath));
   if (!cacheText) {
     return {
       ok: true,
@@ -7931,7 +8344,7 @@ async function walkImportFiles(dir, out) {
   const entries = await readdir5(dir, { withFileTypes: true });
   for (const entry of entries) {
     if (entry.name === ".git" || entry.name === "node_modules") continue;
-    const path = join27(dir, entry.name);
+    const path = join28(dir, entry.name);
     if (entry.isDirectory()) {
       await walkImportFiles(path, out);
     } else if (entry.isFile() && isImportCandidate(path)) {
@@ -7981,7 +8394,7 @@ async function buildImportEntry(file, sourceRoot, project, today, maxBytes) {
   const redacted = redactSensitiveContent(extracted, { file });
   const privacy = redacted.findings.length > 0 ? "sensitive" : "local";
   const sourceSlug = slugify2(basename2(file, extname(file)));
-  const relSource = relative3(sourceRoot, file).split(sep3).join("/");
+  const relSource = relative4(sourceRoot, file).split(sep3).join("/");
   const entry = {
     ...baseEntry,
     status: "ready",
@@ -7998,8 +8411,8 @@ async function writeImportCapture(vault, entry, today) {
   const content = hiddenString(entry, "__content");
   const project = hiddenString(entry, "__project");
   const relPath = await availableImportPath(vault, entry.proposed_path);
-  const absPath = join27(vault, relPath);
-  await mkdir7(join27(vault, "raw", "transcripts"), { recursive: true });
+  const absPath = join28(vault, relPath);
+  await mkdir7(join28(vault, "raw", "transcripts"), { recursive: true });
   await writeFile5(absPath, renderImportCapture(entry, content, project, today), "utf8");
   const validation = await runValidate({ file: absPath });
   return {
@@ -8015,7 +8428,7 @@ async function availableImportPath(vault, proposed) {
   const stem = proposed.slice(0, -ext.length);
   let candidate = proposed;
   let i = 2;
-  while (await readIfExists2(join27(vault, candidate))) {
+  while (await readIfExists2(join28(vault, candidate))) {
     candidate = `${stem}-${i}${ext}`;
     i++;
   }
@@ -8200,10 +8613,10 @@ function memoryCacheRelPath(project) {
 }
 async function readMemoryCache(vault, project) {
   if (project) {
-    const projectCache = await readIfExists2(join27(vault, memoryCacheRelPath(project)));
+    const projectCache = await readIfExists2(join28(vault, memoryCacheRelPath(project)));
     if (projectCache) return projectCache;
   }
-  return readIfExists2(join27(vault, ".skillwiki", "memory-topics.json"));
+  return readIfExists2(join28(vault, ".skillwiki", "memory-topics.json"));
 }
 function dedupePages(pages) {
   const seen = /* @__PURE__ */ new Set();
@@ -8295,7 +8708,7 @@ function slugify2(value) {
 
 // src/commands/query.ts
 import { readFile as readFile18, stat as stat6 } from "fs/promises";
-import { join as join28 } from "path";
+import { join as join29 } from "path";
 var W_KEYWORD = 2;
 var W_SOURCE_OVERLAP = 4;
 var W_WIKILINK = 3;
@@ -8416,7 +8829,7 @@ function computeKeywordScore(terms, title, tags, body) {
   return score;
 }
 async function loadOrBuildGraph(vault) {
-  const graphPath = join28(vault, ".skillwiki", "graph.json");
+  const graphPath = join29(vault, ".skillwiki", "graph.json");
   let needsBuild = false;
   try {
     const fileStat = await stat6(graphPath);
@@ -8445,7 +8858,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 
 // src/mcp/vault-resolve.ts
-import { join as join29, resolve as resolve7 } from "path";
+import { join as join30, resolve as resolve7 } from "path";
 
 // src/mcp/allowlist.ts
 import { resolve as resolve6, sep as sep4 } from "path";
@@ -8507,7 +8920,7 @@ async function resolveMcpVault(input) {
   return ok({ vault: vaultPath, source });
 }
 function defaultGraphOut(vault) {
-  return join29(vault, ".skillwiki", "graph.json");
+  return join30(vault, ".skillwiki", "graph.json");
 }
 
 // src/mcp/result-format.ts
@@ -8524,7 +8937,7 @@ function formatToolResult(payload) {
 // src/mcp/audit-log.ts
 import { appendFileSync, mkdirSync as mkdirSync5 } from "fs";
 import { homedir } from "os";
-import { join as join30 } from "path";
+import { join as join31 } from "path";
 function auditEnabled() {
   const v = process.env.SKILLWIKI_MCP_AUDIT;
   if (v === "0" || v === "false") return false;
@@ -8536,7 +8949,7 @@ function auditSink() {
 function auditFilePath() {
   const custom = process.env.SKILLWIKI_MCP_AUDIT_FILE;
   if (custom && custom.length > 0) return custom;
-  return join30(homedir(), ".skillwiki", "mcp-audit.jsonl");
+  return join31(homedir(), ".skillwiki", "mcp-audit.jsonl");
 }
 function auditMcpToolCall(entry) {
   if (!auditEnabled()) return;
@@ -8546,7 +8959,7 @@ function auditMcpToolCall(entry) {
     return;
   }
   const path = auditFilePath();
-  mkdirSync5(join30(path, ".."), { recursive: true });
+  mkdirSync5(join31(path, ".."), { recursive: true });
   appendFileSync(path, line, "utf8");
 }
 async function runMcpToolHandler(tool, input, fn) {
@@ -8767,7 +9180,7 @@ function registerMcpMutatingTools(server) {
 
 // src/mcp/resources.ts
 import { readFile as readFile20 } from "fs/promises";
-import { join as join32 } from "path";
+import { join as join33 } from "path";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/mcp/lint-bucket.ts
@@ -8896,8 +9309,8 @@ async function fetchQueryPreview(input) {
 
 // src/mcp/graph-html.ts
 import { readFile as readFile19 } from "fs/promises";
-import { join as join31 } from "path";
-import { existsSync as existsSync15 } from "fs";
+import { join as join32 } from "path";
+import { existsSync as existsSync16 } from "fs";
 var TYPE_COLORS = {
   entities: "#e74c3c",
   concepts: "#27ae60",
@@ -8965,9 +9378,9 @@ ${nodeSvg}
   return { html, node_count: nodes.length, edge_count: edges.length, truncated };
 }
 async function fetchGraphHtmlReport(input) {
-  const graphPath = input.graphPath ?? join31(input.vault, ".skillwiki", "graph.json");
+  const graphPath = input.graphPath ?? join32(input.vault, ".skillwiki", "graph.json");
   const maxNodes = Math.min(Math.max(10, input.maxNodes ?? 120), 500);
-  if (!existsSync15(graphPath)) {
+  if (!existsSync16(graphPath)) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
       result: err("GRAPH_MISSING", { path: graphPath, hint: "Run skillwiki.graph_build first." })
@@ -9039,7 +9452,7 @@ async function fetchStaleSummary(input) {
 
 // src/mcp/resources.ts
 async function readVaultFile(vault, rel) {
-  return readFile20(join32(vault, rel), "utf8");
+  return readFile20(join33(vault, rel), "utf8");
 }
 async function tailLines(text, lines) {
   const parts = text.split(/\r?\n/);
@@ -9125,7 +9538,7 @@ function registerMcpResources(server) {
       if (!v.ok) {
         return { contents: [{ uri: uri.href, mimeType: "text/plain", text: JSON.stringify(v) }] };
       }
-      const path = join32(v.data.vault, ".skillwiki", "graph.json");
+      const path = join33(v.data.vault, ".skillwiki", "graph.json");
       try {
         const raw = await readFile20(path, "utf8");
         const graph = JSON.parse(raw);
@@ -9500,6 +9913,13 @@ export {
   evaluateSatelliteRunHealth,
   runDoctor,
   readCliPackageJson,
+  DEFAULT_DIRTY_VOLUME_THRESHOLD,
+  DEFAULT_CAPTURE_BUDGET,
+  DEFAULT_NO_DECISION_STREAK,
+  GateError,
+  evaluateDirtyVolumeGate,
+  CAPTURE_HYGIENE_CONTRACT,
+  runWritePreflight,
   runObserve,
   memoryAuthorityTiersRank,
   runMemoryTopics,

package/dist/cli.js

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
 import {
+  CAPTURE_HYGIENE_CONTRACT,
+  DEFAULT_CAPTURE_BUDGET,
+  DEFAULT_DIRTY_VOLUME_THRESHOLD,
+  DEFAULT_NO_DECISION_STREAK,
+  GateError,
   SATELLITE_STALE_MS,
   acquireLock,
   acquireOwnedSyncLock,
@@ -9,6 +14,7 @@ import {
   buildRemoteObjectPath,
   clearLastOp,
   configPath,
+  evaluateDirtyVolumeGate,
   evaluateSatelliteRunHealth,
   extractCitationMarkers,
   extractTaxonomy,
@@ -66,13 +72,14 @@ import {
   runTagAudit,
   runTopicMapCheck,
   runValidate,
+  runWritePreflight,
   safeWritePage,
   satelliteLatestRunPath,
   scanConflictMarkerBlocksInText,
   taxonomyCommentForPage,
   upsertIndexEntry,
   writeLogEvent
-} from "./chunk-AVCGIWSL.js";
+} from "./chunk-P2FCRGKU.js";
 import {
   normalizeDistTag,
   readCache,
@@ -7086,6 +7093,67 @@ async function postCommit(vault, exitCode) {
   clearLastOp(vault);
 }
 
+// src/commands/write-preflight.ts
+import { existsSync as existsSync13, readFileSync as readFileSync15, statSync as statSync4 } from "fs";
+async function runWritePreflightCommand(input) {
+  if (!existsSync13(input.vault) || !statSync4(input.vault).isDirectory()) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err(GateError.VAULT_PATH_INVALID, { path: input.vault })
+    };
+  }
+  let priorText = input.priorArtifactText;
+  if (input.priorArtifactFile) {
+    if (!existsSync13(input.priorArtifactFile)) {
+      return {
+        exitCode: ExitCode.FILE_NOT_FOUND,
+        result: err("FILE_NOT_FOUND", { path: input.priorArtifactFile })
+      };
+    }
+    priorText = readFileSync15(input.priorArtifactFile, "utf8");
+  }
+  const checkList = input.checks ? input.checks.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+  const result = runWritePreflight({
+    vault: input.vault,
+    command: input.command,
+    dirtyThreshold: input.dirtyThreshold ?? DEFAULT_DIRTY_VOLUME_THRESHOLD,
+    skipDirty: input.skipDirty,
+    priorArtifactText: priorText,
+    consecutiveNoNewDecision: input.consecutiveNoNewDecision,
+    noDecisionThreshold: input.noDecisionThreshold ?? DEFAULT_NO_DECISION_STREAK,
+    humanAllow: input.humanAllow,
+    missionKind: input.missionKind,
+    skipMission: input.skipMission,
+    project: input.project,
+    captureDay: input.captureDay,
+    captureBudget: input.captureBudget ?? DEFAULT_CAPTURE_BUDGET,
+    severity: input.severity,
+    skipBudget: input.skipBudget,
+    checks: checkList
+  });
+  if (!result.ok) {
+    const code = result.error === GateError.VAULT_PATH_INVALID ? ExitCode.VAULT_PATH_INVALID : ExitCode.PREFLIGHT_FAILED;
+    return { exitCode: code, result };
+  }
+  if (!result.data.allowed) {
+    const first = result.data.refused[0];
+    return {
+      exitCode: ExitCode.PREFLIGHT_FAILED,
+      result: err(first?.code ?? GateError.VAULT_DIRTY_BACKLOG, {
+        ...result.data,
+        hygiene_contract: CAPTURE_HYGIENE_CONTRACT
+      })
+    };
+  }
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      ...result.data,
+      hygiene_contract: CAPTURE_HYGIENE_CONTRACT
+    })
+  };
+}
+
 // src/cli.ts
 var pkg = readCliPackageJson();
 var program = new Command();
@@ -7097,6 +7165,29 @@ async function emit(r, vault, opts) {
   if (vault && opts?.postCommit !== false) await postCommit(vault, r.exitCode);
   process.exit(r.exitCode);
 }
+function dirtyVolumeBlock(vault, command) {
+  if (process.env.SKILLWIKI_SKIP_DIRTY_GATE === "1") return null;
+  const thrRaw = process.env.SKILLWIKI_DIRTY_THRESHOLD;
+  const threshold = thrRaw != null && thrRaw !== "" ? Number(thrRaw) : void 0;
+  const gate = evaluateDirtyVolumeGate({
+    vault,
+    command,
+    threshold: Number.isFinite(threshold) ? threshold : void 0
+  });
+  if (gate.allowed) return null;
+  return {
+    exitCode: ExitCode.PREFLIGHT_FAILED,
+    result: {
+      ok: false,
+      error: gate.code,
+      detail: {
+        reason: gate.reason,
+        report: gate.report,
+        humanHint: gate.humanHint
+      }
+    }
+  };
+}
 async function emitGuardedVaultWrite(vault, command, run, opts) {
   const guard = await guardProtectedVaultWrite({
     vault,
@@ -7110,6 +7201,10 @@ async function emitGuardedVaultWrite(vault, command, run, opts) {
   if (guard.blocked) {
     return emit({ exitCode: guard.exitCode, result: guard.result }, void 0, { postCommit: false });
   }
+  const dirty = dirtyVolumeBlock(vault, command);
+  if (dirty) {
+    return emit(dirty, void 0, { postCommit: false });
+  }
   return emit(await run(), vault, opts);
 }
 async function emitManagedVaultWrite(vault, command, mutate, opts) {
@@ -7125,6 +7220,10 @@ async function emitManagedVaultWrite(vault, command, mutate, opts) {
   if (guard.blocked) {
     return emit({ exitCode: guard.exitCode, result: guard.result }, void 0, { postCommit: false });
   }
+  const dirty = dirtyVolumeBlock(vault, command);
+  if (dirty) {
+    return emit(dirty, void 0, { postCommit: false });
+  }
   const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-7TWSEZJZ.js");
   const run = await runManagedWriteTransaction2({
     vault,
@@ -7815,7 +7914,7 @@ program.command("seed [vault]").description("populate a vault with example conte
     () => runSeed({ vault: v.vault })
   );
 });
-program.command("observe [vault]").description("create a raw transcript observation entry").requiredOption("--text <text>", "observation text").option("--kind <kind>", "observation kind (note|bug|task|idea|session-log)", "task").option("--project <slug>", "associated project slug (required for task/bug claim detection)").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+program.command("observe [vault]").description("create a raw transcript observation entry").requiredOption("--text <text>", "observation text").option("--kind <kind>", "observation kind (note|bug|task|idea|session-log)", "task").option("--project <slug>", "associated project slug (required for task/bug claim detection)").option("--severity <level>", "severity (P0 escapes daily capture budget)").option("--capture-budget <n>", "override daily capture budget", (s) => parseInt(s, 10)).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else return emitGuardedVaultWrite(
@@ -7825,7 +7924,9 @@ program.command("observe [vault]").description("create a raw transcript observat
       vault: v.vault,
       text: opts.text,
       kind: opts.kind,
-      project: opts.project
+      project: opts.project,
+      severity: opts.severity,
+      captureBudget: opts.captureBudget
     })
   );
 });
@@ -7985,6 +8086,29 @@ fleetCmd.command("health [vault]").description("read-only health probe for skill
   });
   emit(r, vault);
 });
+program.command("write-preflight [vault]").description("agent write gates: dirty volume, saturated mission stop, capture budget (analysis M1\u2013M3)").option("--command <name>", "command name for hygiene classification", "agent-write").option("--dirty-threshold <n>", "expanded dirty-file threshold", (s) => parseInt(s, 10)).option("--skip-dirty", "skip dirty-volume gate", false).option("--prior-artifact-file <path>", "prior cycle artifact path for saturation scan").option("--prior-artifact-text <text>", "prior cycle artifact text for saturation scan").option("--consecutive-no-decision <n>", "no-new-decision streak", (s) => parseInt(s, 10)).option("--no-decision-threshold <n>", "streak threshold", (s) => parseInt(s, 10)).option("--human-allow", "explicit human allow for saturated missions", false).option("--mission-kind <kind>", "mission kind label (pilot-q, research-cycle, \u2026)").option("--skip-mission", "skip mission saturation gate", false).option("--project <slug>", "project slug for capture budget").option("--capture-day <date>", "YYYY-MM-DD for capture budget").option("--capture-budget <n>", "daily capture budget", (s) => parseInt(s, 10)).option("--severity <level>", "severity (P0 escapes budget)").option("--skip-budget", "skip capture budget gate", false).option("--checks <list>", "comma list: dirty,mission,budget,all", "all").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault, opts.wiki);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runWritePreflightCommand({
+    vault: v.vault,
+    command: opts.command,
+    dirtyThreshold: opts.dirtyThreshold,
+    skipDirty: !!opts.skipDirty,
+    priorArtifactFile: opts.priorArtifactFile,
+    priorArtifactText: opts.priorArtifactText,
+    consecutiveNoNewDecision: opts.consecutiveNoDecision,
+    noDecisionThreshold: opts.noDecisionThreshold,
+    humanAllow: !!opts.humanAllow,
+    missionKind: opts.missionKind,
+    skipMission: !!opts.skipMission,
+    project: opts.project,
+    captureDay: opts.captureDay,
+    captureBudget: opts.captureBudget,
+    severity: opts.severity,
+    skipBudget: !!opts.skipBudget,
+    checks: opts.checks
+  }), void 0, { postCommit: false });
+});
 program.command("mcp").description("start stdio Model Context Protocol server (read-only vault tools)").action(async () => {
   await runSkillwikiMcpStdio();
 });

package/dist/skillwiki-mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-AVCGIWSL.js";
+} from "./chunk-P2FCRGKU.js";
 import "./chunk-7I2TPIV5.js";
 import "./chunk-U34B2XQJ.js";
 import "./chunk-TYN2IHBY.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.9",
+  "version": "0.10.11",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js",

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.9",
+  "version": "0.10.11",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 19 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.9",
+  "version": "0.10.11",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 19 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.10.9",
+  "version": "0.10.11",
   "private": true,
   "files": [
     "wiki-*",