@litfamily/litclaude 1.0.10 → 1.0.13

package/plugins/litclaude/lib/deliverable-hedge-guard.mjs

@@ -1,395 +1,301 @@
-import { readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { lstatSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { extname, isAbsolute, relative, resolve } from "node:path";
 
-import { extractMutatedFilePaths } from "./mutated-file-paths.mjs";
+import { extractCreatedDocumentPaths, extractMutatedFilePaths } from "./mutated-file-paths.mjs";
 import { readRegularStable } from "./secure-path-read.mjs";
+import { extractArtifactText } from "../skills/lit-humanizer/scripts/artifact-text.mjs";
 
 const MAX_ARTIFACT_BYTES = 512 * 1024;
-const MAX_ARTIFACT_AGGREGATE_BYTES = 2 * 1024 * 1024;
+const MAX_AGGREGATE_BYTES = 2 * 1024 * 1024;
 const MAX_ARTIFACT_PATHS = 16;
-const MAX_CONTEXT_DATA_CHARS = 4_096;
-const MAX_REPORTED_FINDINGS = 16;
-const MAX_TRANSCRIPT_BYTES = 8 * 1024 * 1024;
-const readerFacingExtensions = new Set([
-  ".adoc", ".csv", ".htm", ".html", ".markdown", ".md", ".rst", ".svg", ".tex", ".tsv", ".txt", ".xml",
+const MAX_POST_CREATE_BYTES = 8 * 1024 * 1024;
+const MAX_DIFF_LINES = 50_000;
+const MAX_DIFF_TRACE_CELLS = 500_000;
+const MAX_DIFF_WORK = 8_000_000;
+const SCANNER_TIMEOUT_MS = 2000;
+const TEXT_EXTENSIONS = new Set([
+  ".adoc", ".asciidoc", ".csv", ".htm", ".html", ".markdown", ".md", ".mdx", ".org", ".rst", ".svg", ".tex", ".tsv", ".txt", ".xml",
 ]);
-const readerFacingNames = new Set(["CHANGELOG", "CONTRIBUTING", "LICENSE", "NOTICE", "README"]);
-const outputChannelByGenre = new Map([
-  ["client_deliverable", "reply"],
-  ["internal_analysis", "designated_section"],
-  ["audit_report", "methodology_paragraph"],
-  ["working_note", "inline"],
-  ["no_artifact", "reply"],
-]);
-const lazyOutputChannelSkillIds = new Set(["frontend-ui-ux", "visual-qa"]);
-
-const patternClasses = Object.freeze([
-  Object.freeze({
-    className: "deferred",
-    patterns: [
-      /보류\s*중|별도로\s*진행|추후\s*진행/giu,
-      /\b(?:pending|deferred|to be determined separately|(?:will be|is) (?:handled|performed|conducted) separately)\b/giu,
-    ],
-  }),
-  Object.freeze({
-    className: "absent-evidence",
-    patterns: [
-      /(?:근거|자료|데이터|측정값|관찰\s*기록|실험\s*기록|출처|증거|수치)[^.!?\n]{0,80}(?:없(?:어(?:서)?|습니다|음|다)|부족|제공되지\s*않(?:았|습니다|는다|은)?|주어지지\s*않(?:았|습니다|는다|은)?|부재|확인되지\s*않|검증되지\s*않|평가할\s*수\s*없|판단할\s*수\s*없|산정할\s*수\s*없|알\s*수\s*없)/giu,
-      /아직[^.!?\n]{0,40}(?:근거|자료|데이터|측정값|관찰\s*기록|실험\s*기록|출처|증거|수치)[^.!?\n]{0,40}없습니다/giu,
-      /(?:근거|자료|데이터|측정값|관찰\s*기록|실험\s*기록|출처|증거|수치)[^.!?\n]{0,80}알\s*수\s*없/giu,
-      /\b(?:no evidence yet|not yet substantiated|no supporting evidence|supporting evidence (?:is|was) (?:missing|absent|not provided)|(?:evidence|supporting data|measurements?|observation records?|sources?|documentation|verification) (?:is|are|was|were) (?:missing|absent|not provided|not available|not verified|not validated))\b/giu,
-    ],
-  }),
-  Object.freeze({
-    className: "scope-limit",
-    patterns: [
-      /한정됩니다|국한됩니다|범위\s*내에서만/giu,
-      /\blimited to the provided evidence\b/giu,
-    ],
-  }),
-  Object.freeze({
-    className: "negated-action",
-    patterns: [
-      /하지\s*않았습니다|포함되지\s*않습니다|다루지\s*않습니다/giu,
-      /\b(?:was not performed|is not included|was not included)\b/giu,
-    ],
-  }),
-  Object.freeze({
-    className: "self-protection",
-    patterns: [
-      /참고용|추가\s*검증이\s*필요|완전하지\s*않을\s*수\s*있/giu,
-      /\b(?:for reference only|may be incomplete|requires additional verification|additional verification is needed)\b/giu,
-    ],
-  }),
-  Object.freeze({
-    className: "process-meta",
-    patterns: [
-      /이\s*작업에서는|프롬프트가/giu,
-      /\bas an AI\b/giu,
-    ],
-  }),
-]);
-
+const DOCUMENT_EXTENSIONS = new Set([".docx", ".pptx", ".pdf"]);
+const READER_FACING_NAMES = new Set(["CHANGELOG", "CONTRIBUTING", "LICENSE", "NOTICE", "README"]);
+const INTERNAL_PATH_COMPONENTS = new Set(["plans", "evidence", "ledger", "ledgers", ".hermes", [".", "om", "o"].join("")]);
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 
-const resetPattern = (pattern) => {
-  pattern.lastIndex = 0;
-  return pattern;
+const cleanResult = { status: "clean", findings: [], paths: [] };
+const extensionOf = (path) => extname(path).toLowerCase();
+const readerFacing = (path) => TEXT_EXTENSIONS.has(extensionOf(path))
+  || DOCUMENT_EXTENSIONS.has(extensionOf(path))
+  || READER_FACING_NAMES.has(path.split(/[\\/]/u).at(-1).toUpperCase());
+
+const internalPath = (cwd, path) => {
+  const components = relative(resolve(cwd), path).split(/[\\/]/u).filter(Boolean);
+  const basename = components.at(-1) ?? "";
+  return components.some((component) => {
+    const lower = component.toLowerCase();
+    return INTERNAL_PATH_COMPONENTS.has(lower) || lower.startsWith(".lit");
+  }) || /^handoff/iu.test(basename)
+    || /(?:^|[._-])ledger(?:[._-]|$)/iu.test(basename)
+    || /\.jsonl$/iu.test(basename);
 };
 
-const fencedLine = (line) => /^\s*(`{3,}|~{3,})/u.exec(line)?.[1];
-
-const isScalarLine = (line) => /^\s*(?:["'][^"']+["']|[A-Za-z0-9_.-]+)\s*:/u.test(line)
-  || /^\s*\{[^\n]*["'][^"']+["']\s*:/u.test(line);
-
-const isStatusTableLine = (line) => /\|\s*(?:pending|deferred|보류\s*중)\s*\|/iu.test(line);
-
-const isQuotedEnum = (line, start, end) => {
-  for (const quote of ['"', "'", "`"]) {
-    const left = line.lastIndexOf(quote, start);
-    const right = line.indexOf(quote, end);
-    if (left === -1 || right === -1) continue;
-    const scalar = line.slice(left + 1, right).trim();
-    if (/^(?:pending|deferred|보류\s*중)$/iu.test(scalar)) return true;
-  }
-  return false;
+const pathWithin = (cwd, path) => {
+  if (typeof cwd !== "string" || typeof path !== "string" || cwd.length === 0 || path.length === 0) return null;
+  const root = resolve(cwd);
+  const absolutePath = isAbsolute(path) ? resolve(path) : resolve(root, path);
+  const rel = relative(root, absolutePath);
+  return isAbsolute(rel) || rel.split(/[\\/]/u)[0] === ".." ? null : absolutePath;
 };
 
-const excludedDeferredState = (line, start, end) => isScalarLine(line)
-  || isStatusTableLine(line)
-  || isQuotedEnum(line, start, end);
-
-export const scanDeliverableHedges = (text) => {
-  if (typeof text !== "string" || text.length === 0) return [];
-  const findings = [];
-  let fence = null;
-  const lines = text.replace(/\r\n?/gu, "\n").split("\n");
-
-  for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
-    const line = lines[lineIndex];
-    const marker = fencedLine(line);
-    if (marker !== undefined) {
-      if (fence === null) fence = marker[0];
-      else if (marker[0] === fence) fence = null;
-      continue;
+const toolArtifacts = (input) => {
+  const toolName = typeof input?.tool_name === "string" ? input.tool_name.toLowerCase() : "";
+  const toolInput = isRecord(input?.tool_input) ? input.tool_input : null;
+  if (!toolInput) return { artifacts: [], skipped: false };
+  const path = [toolInput.file_path, toolInput.filePath, toolInput.path].find((value) => typeof value === "string" && value.length > 0);
+  if (toolName === "write") {
+    if (!path || typeof toolInput.content !== "string") return { artifacts: [], skipped: true };
+    return { artifacts: [{ path, text: toolInput.content, readBefore: true }], skipped: false };
+  }
+  if (toolName === "edit") {
+    const text = typeof toolInput.new_string === "string" ? toolInput.new_string : toolInput.newString;
+    const before = typeof toolInput.old_string === "string" ? toolInput.old_string : toolInput.oldString;
+    if (!path || typeof text !== "string") return { artifacts: [], skipped: true };
+    return { artifacts: [{ path, text, ...(typeof before === "string" ? { before } : {}) }], skipped: false };
+  }
+  if (toolName !== "multiedit" && toolName !== "multi_edit") return { artifacts: [], skipped: false };
+  if (path && Array.isArray(toolInput.edits)) {
+    const artifacts = [];
+    for (const edit of toolInput.edits) {
+      if (!isRecord(edit)) return { artifacts: [], skipped: true };
+      const text = typeof edit.new_string === "string" ? edit.new_string : edit.newString;
+      const before = typeof edit.old_string === "string" ? edit.old_string : edit.oldString;
+      if (typeof text !== "string") return { artifacts: [], skipped: true };
+      artifacts.push({ path, text, ...(typeof before === "string" ? { before } : {}) });
     }
-    if (fence !== null) continue;
+    return { artifacts, skipped: false };
+  }
+  if (!Array.isArray(toolInput.files)) return { artifacts: [], skipped: true };
+  const artifacts = [];
+  for (const file of toolInput.files) {
+    if (!isRecord(file)) return { artifacts: [], skipped: true };
+    const filePath = [file.file_path, file.filePath, file.path].find((value) => typeof value === "string" && value.length > 0);
+    const text = [file.content, file.new_string, file.newString].find((value) => typeof value === "string");
+    const before = [file.old_string, file.oldString].find((value) => typeof value === "string");
+    if (!filePath || text === undefined) return { artifacts: [], skipped: true };
+    artifacts.push({ path: filePath, text, ...(typeof before === "string" ? { before } : {}) });
+  }
+  return { artifacts, skipped: false };
+};
 
-    for (const patternClass of patternClasses) {
-      let accepted;
-      for (const pattern of patternClass.patterns) {
-        for (const match of line.matchAll(resetPattern(pattern))) {
-          const start = match.index ?? 0;
-          const end = start + match[0].length;
-          if (patternClass.className === "deferred" && excludedDeferredState(line, start, end)) continue;
-          accepted = match;
-          break;
+const changedLines = (before, after) => {
+  if (before === after) return "";
+  const oldLines = before.split(/\r?\n/u);
+  const newLines = after.split(/\r?\n/u);
+  if (oldLines.length > MAX_DIFF_LINES || newLines.length > MAX_DIFF_LINES) return null;
+  let prefix = 0;
+  while (prefix < oldLines.length && prefix < newLines.length && oldLines[prefix] === newLines[prefix]) prefix += 1;
+  let suffix = 0;
+  while (suffix < oldLines.length - prefix && suffix < newLines.length - prefix
+    && oldLines[oldLines.length - suffix - 1] === newLines[newLines.length - suffix - 1]) suffix += 1;
+  const oldMiddle = oldLines.slice(prefix, oldLines.length - suffix);
+  const newMiddle = newLines.slice(prefix, newLines.length - suffix);
+  if (oldMiddle.length === 0) return newMiddle.join("\n");
+  if (newMiddle.length === 0) return "";
+
+  const n = oldMiddle.length;
+  const m = newMiddle.length;
+  let frontier = new Map([[1, 0]]);
+  const trace = [];
+  let traceCells = 0;
+  let work = 0;
+  for (let distance = 0; distance <= n + m; distance += 1) {
+    trace.push(new Map(frontier));
+    traceCells += frontier.size;
+    if (traceCells > MAX_DIFF_TRACE_CELLS) return null;
+    for (let diagonal = -distance; diagonal <= distance; diagonal += 2) {
+      const x = diagonal === -distance
+        || (diagonal !== distance && (frontier.get(diagonal - 1) ?? -1) < (frontier.get(diagonal + 1) ?? -1))
+        ? frontier.get(diagonal + 1) ?? 0
+        : (frontier.get(diagonal - 1) ?? 0) + 1;
+      let nextX = x;
+      let nextY = nextX - diagonal;
+      while (nextX < n && nextY < m && nextX >= 0 && nextY >= 0
+        && oldMiddle[nextX] === newMiddle[nextY]) {
+        nextX += 1;
+        nextY += 1;
+        work += 1;
+      }
+      frontier.set(diagonal, nextX);
+      work += 1;
+      if (work > MAX_DIFF_WORK) return null;
+      if (nextX < n || nextY < m) continue;
+
+      const added = [];
+      let backX = n;
+      let backY = m;
+      for (let backDistance = distance; backDistance >= 0; backDistance -= 1) {
+        const previous = trace[backDistance];
+        const backDiagonal = backX - backY;
+        const previousDiagonal = backDiagonal === -backDistance
+          || (backDiagonal !== backDistance
+            && (previous.get(backDiagonal - 1) ?? -Infinity) < (previous.get(backDiagonal + 1) ?? -Infinity))
+          ? backDiagonal + 1
+          : backDiagonal - 1;
+        const previousX = previous.get(previousDiagonal) ?? 0;
+        const previousY = previousX - previousDiagonal;
+        while (backX > previousX && backY > previousY) {
+          backX -= 1;
+          backY -= 1;
+        }
+        if (backDistance === 0) break;
+        if (backX === previousX) {
+          added.push(newMiddle[backY - 1]);
+          backY -= 1;
+        } else {
+          backX -= 1;
         }
-        if (accepted !== undefined) break;
       }
-      if (accepted === undefined) continue;
-      findings.push(Object.freeze({
-        className: patternClass.className,
-        line: lineIndex + 1,
-        column: (accepted.index ?? 0) + 1,
-      }));
+      return added.reverse().join("\n");
     }
   }
-  return findings;
-};
-
-const declarationFrom = (text) => {
-  if (typeof text !== "string") return null;
-  const block = /^## #contract\.output_channels\s*\r?\n\s*```yaml\s*\r?\n([\s\S]*?)^```\s*$/mu.exec(text)?.[1];
-  if (block === undefined) return null;
-  const artifactGenre = /^artifact_genre:\s*(\S+)\s*$/mu.exec(block)?.[1];
-  const limitationsChannel = /^limitations_channel:\s*(\S+)\s*$/mu.exec(block)?.[1];
-  if (artifactGenre === undefined || limitationsChannel === undefined) return null;
-  if (outputChannelByGenre.get(artifactGenre) !== limitationsChannel) return null;
-  return { artifactGenre, limitationsChannel };
+  return null;
 };
 
-const declaredOutputChannel = (pluginRoot, skillId) => {
-  const skillDir = join(pluginRoot, "skills", skillId);
+const runScanner = (artifacts, pluginRoot, execute = spawnSync) => {
+  const script = resolve(pluginRoot, "skills/lit-humanizer/scripts/scan-input.mjs");
+  const request = JSON.stringify({ artifacts });
+  let run;
   try {
-    const skill = readFileSync(join(skillDir, "SKILL.md"), "utf8");
-    const direct = declarationFrom(skill);
-    if (direct !== null) return direct;
-    if (!lazyOutputChannelSkillIds.has(skillId)) return null;
-    return declarationFrom(readFileSync(join(skillDir, "references", "complete-contract.md"), "utf8"));
+    run = execute(process.execPath, [script], {
+      input: request,
+      encoding: "utf8",
+      timeout: SCANNER_TIMEOUT_MS,
+      maxBuffer: 256 * 1024,
+      windowsHide: true,
+    });
   } catch {
-    return null;
+    return { failure: "could not complete" };
   }
-};
-
-const knownSkillIds = (pluginRoot) => {
+  if (run.error?.code === "ETIMEDOUT") return { failure: "timed out" };
+  if (run.error || run.status !== 0) return { failure: "could not complete" };
   try {
-    return new Set(readdirSync(join(pluginRoot, "skills"), { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name));
+    const parsed = JSON.parse(run.stdout);
+    if (!Array.isArray(parsed.findings)) return { failure: "returned an invalid result" };
+    return { findings: parsed.findings };
   } catch {
-    return new Set();
+    return { failure: "returned an invalid result" };
   }
 };
 
-const normalizedSkillId = (value, ids) => {
-  if (typeof value !== "string") return null;
-  let candidate = value.trim();
-  const wrapper = /^Skill\(([^)\s]+)(?:\s[^)]*)?\)$/u.exec(candidate)?.[1];
-  if (wrapper !== undefined) candidate = wrapper;
-  candidate = candidate.replace(/^\//u, "").replace(/^litclaude:/u, "");
-  return ids.has(candidate) ? candidate : null;
+const resultFor = (findings, paths) => ({
+  status: findings.some((finding) => finding.severity === "block")
+    ? "block"
+    : findings.some((finding) => finding.severity === "warn") ? "warn" : "clean",
+  findings,
+  paths,
+});
+
+export const scanHumanizerText = async (text, file = "<stdin>", pluginRoot) => {
+  const scanned = runScanner([{ path: file, text }], pluginRoot);
+  if (scanned.failure) throw new Error(`lit-humanizer scan ${scanned.failure}`);
+  return scanned.findings;
 };
 
-const skillIdFromMarkerText = (text, ids, pluginRoot) => {
-  if (typeof text !== "string") return null;
-  const markers = [...text.matchAll(/<litclaude-skill-body name="([a-z0-9-]+)">[\s\S]*?<\/litclaude-skill-body>/gu)];
-  if (markers.length !== 1) return null;
-  const skillId = normalizedSkillId(markers[0][1], ids);
-  if (skillId === null) return null;
-  try {
-    const body = readFileSync(join(pluginRoot, "skills", skillId, "SKILL.md"), "utf8").trim();
-    const expected = `<litclaude-skill-body name="${skillId}">\n${body}\n</litclaude-skill-body>`;
-    return markers[0][0] === expected ? skillId : null;
-  } catch {
-    return null;
-  }
-};
+const evaluateDeliverableHedgeGuardInternal = ({ input, pluginRoot, phase = "pre-write", execute = spawnSync }) => {
+  if (!isRecord(input) || typeof pluginRoot !== "string") return cleanResult;
+  const cwd = typeof input.cwd === "string" ? input.cwd : process.cwd();
 
-const skillIdFromAssistantEvent = (event, ids) => {
-  if (!isRecord(event) || event.type !== "assistant") return null;
-  const content = event.message?.content;
-  const parts = Array.isArray(content) ? content : [{ type: "text", text: content }];
-  for (let index = parts.length - 1; index >= 0; index -= 1) {
-    const part = parts[index];
-    if (!isRecord(part)) continue;
-    if (part.type !== "tool_use" || part.name !== "Skill" || !isRecord(part.input)) continue;
-    for (const value of Object.values(part.input)) {
-      const invoked = normalizedSkillId(value, ids);
-      if (invoked !== null) return invoked;
+  if (phase === "post-create") {
+    const failed = isRecord(input.tool_response)
+      && (input.tool_response.isError === true || input.tool_response.is_error === true
+        || input.tool_response.error === true || input.tool_response.status === "error");
+    if (failed) return cleanResult;
+    const paths = [...new Set([...extractMutatedFilePaths(input), ...extractCreatedDocumentPaths(input)])]
+      .map((path) => pathWithin(cwd, path))
+      .filter((path) => path !== null && !internalPath(cwd, path) && DOCUMENT_EXTENSIONS.has(extensionOf(path)));
+    if (paths.length === 0) return cleanResult;
+    if (paths.length > 2) return { status: "unavailable", reason: "document count exceeded the check limit", findings: [], paths: [] };
+    const artifacts = [];
+    let aggregateBytes = 0;
+    for (const path of paths) {
+      const read = readRegularStable(cwd, path, undefined, { maxBytes: MAX_POST_CREATE_BYTES });
+      if (read.failure) return { status: "unavailable", reason: "document could not be read safely", findings: [], paths: [] };
+      aggregateBytes += read.bytes.length;
+      if (aggregateBytes > MAX_POST_CREATE_BYTES) return { status: "unavailable", reason: "document size exceeded the check limit", findings: [], paths: [] };
+      try {
+        artifacts.push({ path, text: extractArtifactText(extensionOf(path), read.bytes) });
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : "document extraction failed";
+        return { status: "unavailable", reason, findings: [], paths: [] };
+      }
     }
+    const scanned = runScanner(artifacts, pluginRoot, execute);
+    if (scanned.failure) return { status: "unavailable", reason: `detector ${scanned.failure}`, findings: [], paths: [] };
+    return { ...resultFor(scanned.findings, paths), phase };
   }
-  return null;
-};
-
-const skillIdFromHookAttachment = (event, ids, pluginRoot) => {
-  if (!isRecord(event) || event.type !== "attachment" || !isRecord(event.attachment)) return null;
-  const attachment = event.attachment;
-  const attachmentKeys = Object.keys(attachment).sort();
-  if (event.userType !== "external"
-    || typeof event.isSidechain !== "boolean"
-    || typeof event.entrypoint !== "string"
-    || typeof event.parentUuid !== "string"
-    || typeof event.sessionId !== "string"
-    || typeof event.timestamp !== "string"
-    || typeof event.uuid !== "string"
-    || typeof event.version !== "string"
-    || typeof event.cwd !== "string"
-    || attachmentKeys.join("\0") !== ["content", "hookEvent", "hookName", "toolUseID", "type"].join("\0")
-    || attachment.type !== "hook_additional_context"
-    || attachment.hookEvent !== "UserPromptSubmit"
-    || attachment.hookName !== "UserPromptSubmit"
-    || typeof attachment.toolUseID !== "string"
-    || attachment.toolUseID.length === 0
-    || !Array.isArray(attachment.content)
-    || !attachment.content.every((part) => typeof part === "string")) return null;
-  const marked = attachment.content
-    .map((part) => skillIdFromMarkerText(part, ids, pluginRoot))
-    .filter((skillId) => skillId !== null);
-  return marked.length === 1 ? marked[0] : null;
-};
-
-const isUserTurnBoundary = (event) => {
-  if (!isRecord(event) || event.type !== "user") return false;
-  const content = event.message?.content;
-  if (typeof content === "string") return content.trim().length > 0;
-  return Array.isArray(content) && content.some((part) =>
-    isRecord(part) && part.type === "text" && typeof part.text === "string" && part.text.trim().length > 0);
-};
 
-const activeSkillId = (transcriptPath, pluginRoot) => {
-  if (typeof transcriptPath !== "string" || transcriptPath.length === 0) return null;
-  const absolutePath = resolve(transcriptPath);
-  const result = readRegularStable(dirname(absolutePath), absolutePath, undefined, { maxBytes: MAX_TRANSCRIPT_BYTES });
-  if (result.failure !== undefined) return null;
-  const ids = knownSkillIds(pluginRoot);
-  const lines = result.bytes.toString("utf8").split(/\r?\n/u).filter(Boolean);
-  for (let index = lines.length - 1; index >= 0; index -= 1) {
-    try {
-      const event = JSON.parse(lines[index]);
-      const skillId = skillIdFromAssistantEvent(event, ids) ?? skillIdFromHookAttachment(event, ids, pluginRoot);
-      if (skillId !== null) return skillId;
-      if (isUserTurnBoundary(event)) return null;
-    } catch {
-      // A malformed or unrelated transcript entry cannot grant a genre.
+  const { artifacts: candidates, skipped } = toolArtifacts(input);
+  if (candidates.length === 0) return skipped
+    ? { status: "unavailable", reason: "changed text could not be read from the tool input", findings: [], paths: [] }
+    : cleanResult;
+  if (candidates.length > MAX_ARTIFACT_PATHS) return { status: "unavailable", reason: "file count exceeded the check limit", findings: [], paths: [] };
+  const byPath = new Map();
+  let aggregateBytes = 0;
+  for (const candidate of candidates) {
+    const path = pathWithin(cwd, candidate.path);
+    if (path === null || internalPath(cwd, path) || !readerFacing(path) || DOCUMENT_EXTENSIONS.has(extensionOf(path))) continue;
+    let text = candidate.text;
+    if (typeof candidate.before === "string") {
+      text = changedLines(candidate.before, text);
+      if (text === null) return { status: "unavailable", reason: "changed-text diff exceeded the check limit", findings: [], paths: [] };
+    } else if (candidate.readBefore) {
+      let exists;
+      try { exists = lstatSync(path, { throwIfNoEntry: false }); } catch {
+        return { status: "unavailable", reason: "existing text could not be checked safely", findings: [], paths: [] };
+      }
+      if (exists) {
+        const read = readRegularStable(cwd, path, undefined, { maxBytes: MAX_ARTIFACT_BYTES });
+        if (read.failure) return { status: "unavailable", reason: "existing text could not be read safely", findings: [], paths: [] };
+        text = changedLines(read.bytes.toString("utf8"), text);
+        if (text === null) return { status: "unavailable", reason: "changed-text diff exceeded the check limit", findings: [], paths: [] };
+      }
     }
-  }
-  return null;
-};
-
-const isReaderFacingPath = (path) => {
-  const extension = extname(path).toLowerCase();
-  if (readerFacingExtensions.has(extension)) return true;
-  return readerFacingNames.has(basename(path).toUpperCase());
-};
-
-const containedArtifactPath = (cwd, path) => {
-  if (typeof cwd !== "string" || cwd.length === 0) return null;
-  if (typeof path !== "string" || path.length === 0) return null;
-  const requestedRoot = resolve(cwd);
-  const requestedPath = isAbsolute(path) ? resolve(path) : resolve(requestedRoot, path);
-  const within = relative(requestedRoot, requestedPath);
-  if (isAbsolute(within) || within.split(/[\\/]/u)[0] === "..") return null;
-  return requestedPath;
-};
-
-const firstPathString = (...values) => values.find((value) => typeof value === "string" && value.length > 0);
-const firstContentString = (...values) => values.find((value) => typeof value === "string");
-
-const contentCandidates = (input) => {
-  const toolName = typeof input?.tool_name === "string" ? input.tool_name.toLowerCase() : "";
-  const toolInput = isRecord(input?.tool_input) ? input.tool_input : null;
-  if (toolInput === null) return null;
-  const path = firstPathString(toolInput.file_path, toolInput.filePath, toolInput.path);
-
-  if (toolName === "write") {
-    return path !== undefined && typeof toolInput.content === "string"
-      ? [{ path, text: toolInput.content }]
-      : null;
-  }
-  if (toolName === "edit") {
-    const text = firstContentString(toolInput.new_string, toolInput.newString);
-    return path !== undefined && text !== undefined ? [{ path, text }] : null;
-  }
-  if (toolName !== "multiedit" && toolName !== "multi_edit") return null;
-
-  if (path !== undefined && Array.isArray(toolInput.edits)) {
-    const chunks = [];
-    for (const edit of toolInput.edits) {
-      if (!isRecord(edit)) return null;
-      const text = firstContentString(edit.new_string, edit.newString);
-      if (text === undefined) return null;
-      chunks.push(text);
+    if (!text) continue;
+    const bytes = Buffer.byteLength(text, "utf8");
+    aggregateBytes += bytes;
+    if (bytes > MAX_ARTIFACT_BYTES || aggregateBytes > MAX_AGGREGATE_BYTES) {
+      return { status: "unavailable", reason: "changed text exceeded the check limit", findings: [], paths: [] };
     }
-    return chunks.length > 0 ? [{ path, text: chunks.join("\n") }] : null;
-  }
-
-  if (!Array.isArray(toolInput.files)) return null;
-  const candidates = [];
-  for (const file of toolInput.files) {
-    if (!isRecord(file)) return null;
-    const filePath = firstPathString(file.file_path, file.filePath, file.path);
-    const text = firstContentString(file.content, file.new_string, file.newString);
-    if (filePath === undefined || text === undefined) return null;
-    candidates.push({ path: filePath, text });
+    byPath.set(path, byPath.has(path) ? `${byPath.get(path)}\n${text}` : text);
   }
-  return candidates.length > 0 ? candidates : null;
+  if (byPath.size === 0) return cleanResult;
+  const artifacts = [...byPath].map(([path, text]) => ({ path, text }));
+  const scanned = runScanner(artifacts, pluginRoot, execute);
+  if (scanned.failure) return { status: "unavailable", reason: `detector ${scanned.failure}`, findings: [], paths: [] };
+  return resultFor(scanned.findings, artifacts.map(({ path }) => path));
 };
 
-const toolInputArtifacts = (input) => {
-  const mutatedPaths = extractMutatedFilePaths(input);
-  if (mutatedPaths.length === 0 || mutatedPaths.length > MAX_ARTIFACT_PATHS) return [];
-  const candidates = contentCandidates(input);
-  if (candidates === null) return [];
-  const cwd = typeof input.cwd === "string" ? input.cwd : process.cwd();
-  const byPath = new Map();
-  let aggregateBytes = 0;
-  for (const candidate of candidates) {
-    const path = containedArtifactPath(cwd, candidate.path);
-    if (path === null || !isReaderFacingPath(path)) continue;
-    const bytes = Buffer.byteLength(candidate.text, "utf8");
-    const previous = byPath.get(path);
-    const separatorBytes = previous === undefined ? 0 : 1;
-    const combinedBytes = (previous?.bytes ?? 0) + separatorBytes + bytes;
-    aggregateBytes += separatorBytes + bytes;
-    if (combinedBytes > MAX_ARTIFACT_BYTES || aggregateBytes > MAX_ARTIFACT_AGGREGATE_BYTES) return [];
-    byPath.set(path, {
-      path,
-      text: previous === undefined ? candidate.text : `${previous.text}\n${candidate.text}`,
-      bytes: combinedBytes,
-    });
+export const evaluateDeliverableHedgeGuard = (options) => {
+  try {
+    return evaluateDeliverableHedgeGuardInternal(options);
+  } catch {
+    return { status: "unavailable", reason: "check could not complete", findings: [], paths: [] };
   }
-  return [...byPath.values()];
 };
 
-export const evaluateDeliverableHedgeGuard = ({ input, pluginRoot }) => {
-  const empty = {
-    status: "clean",
-    skillId: null,
-    artifactGenre: null,
-    limitationsChannel: null,
-    findings: [],
-    paths: [],
-  };
-  if (!isRecord(input) || typeof pluginRoot !== "string") return empty;
-  const skillId = activeSkillId(input.transcript_path, pluginRoot);
-  if (skillId === null) return empty;
-  const declaration = declaredOutputChannel(pluginRoot, skillId);
-  if (declaration === null) return { ...empty, skillId };
-  const scoped = { ...empty, skillId, ...declaration };
-  if (declaration.artifactGenre !== "client_deliverable" || declaration.limitationsChannel !== "reply") return scoped;
-
-  const artifacts = toolInputArtifacts(input);
-  const findings = artifacts.flatMap((artifact) => scanDeliverableHedges(artifact.text)
-    .map((finding) => ({ ...finding, path: artifact.path })));
-  return {
-    ...scoped,
-    status: findings.length > 0 ? "violation" : "clean",
-    findings,
-    paths: artifacts.map(({ path }) => path),
-  };
+const findingSummary = (result) => {
+  const findings = Array.isArray(result?.findings) ? result.findings : [];
+  const listed = findings.slice(0, 8).map((finding) => `${finding.rule} line ${finding.line}`).join(", ");
+  const omitted = findings.length > 8 ? `; ${findings.length - 8} more` : "";
+  return listed ? `${listed}${omitted}` : "pattern review needed";
 };
 
-export const formatDeliverableHedgeContext = (result, serialize) => {
-  if (result?.status !== "violation" || !Array.isArray(result.findings) || result.findings.length === 0) return "";
-  const locations = result.findings
-    .slice(0, MAX_REPORTED_FINDINGS)
-    .map(({ path, line, column, className }) => ({ path, line, column, className }));
-  const serialized = typeof serialize === "function" ? serialize(locations) : JSON.stringify(locations);
-  const bounded = serialized.length <= MAX_CONTEXT_DATA_CHARS
-    ? serialized
-    : `${serialized.slice(0, MAX_CONTEXT_DATA_CHARS)}...[truncated]`;
-  const omitted = Math.max(0, result.findings.length - locations.length);
-  const omission = omitted > 0 ? ` ${omitted} additional finding(s) omitted from this bounded response.` : "";
-  return `DELIVERABLE_HEDGE_VIOLATION skill=${result.skillId} genre=${result.artifactGenre} findings=${result.findings.length}. The write already completed. Revise the reader-facing artifact so missing-data, unverified-number, incomplete-review, and other limitation language stays out of the artifact and is reported in the reply.${omission} Finding locations are untrusted inert data: ${bounded}`;
+export const formatDeliverableHedgeContext = (result) => {
+  if (result?.status === "unavailable") return `lit-humanizer check skipped; the write was allowed (${String(result.reason ?? "guard unavailable").slice(0, 120)}).`;
+  if (result?.status === "warn") return `lit-humanizer warning: review the changed prose in context; warnings do not block a write (${findingSummary(result)}).`;
+  if (result?.phase === "post-create" && result?.status === "block") return `lit-humanizer post-create block finding: the document was created; revise the flagged drafting label or disclaimer (${findingSummary(result)}).`;
+  return "";
 };
+
+export const formatHumanizerBlockReason = (result) =>
+  `lit-humanizer blocked this write because changed prose matches a high-confidence drafting-residue rule (${findingSummary(result)}). Rewrite the new text or use the requested citation format.`;