oh-my-llmwikimode 1.0.0

package/src/stage4/graph-reasoning/analyzer.js

@@ -0,0 +1,255 @@
+import { validateGraphInsightArtifact } from "./schema.js";
+
+function compareStrings(left, right) {
+  return String(left ?? "").localeCompare(String(right ?? ""));
+}
+
+export function calculateNodeDegrees(graph) {
+  const nodes = Array.isArray(graph?.nodes) ? graph.nodes : [];
+  const edges = Array.isArray(graph?.edges) ? graph.edges : [];
+  const degrees = new Map();
+
+  for (const node of nodes) {
+    const nodeId = node.id || node.path || "";
+    if (nodeId) degrees.set(nodeId, 0);
+  }
+
+  for (const edge of edges) {
+    const source = edge.source || edge.from || "";
+    const target = edge.target || edge.to || "";
+    if (degrees.has(source)) degrees.set(source, degrees.get(source) + 1);
+    if (degrees.has(target)) degrees.set(target, degrees.get(target) + 1);
+  }
+
+  return degrees;
+}
+
+export function deriveDeterministicReferenceTime(inputs) {
+  const dates = [];
+
+  const graphMeta = inputs.graph?.meta || {};
+  if (typeof graphMeta.built_at === "string" && graphMeta.built_at.trim()) {
+    dates.push(graphMeta.built_at);
+  }
+
+  for (const card of inputs.curatorQueue?.cards || []) {
+    if (typeof card.created_at === "string" && card.created_at.trim()) {
+      dates.push(card.created_at);
+    }
+  }
+
+  for (const record of inputs.curatorAudit || []) {
+    if (typeof record.timestamp === "string" && record.timestamp.trim()) {
+      dates.push(record.timestamp);
+    }
+  }
+
+  const browserMeta = inputs.browserData?.meta || {};
+  if (typeof browserMeta.built_at === "string" && browserMeta.built_at.trim()) {
+    dates.push(browserMeta.built_at);
+  }
+
+  if (dates.length === 0) return "1970-01-01T00:00:00.000Z";
+  return dates.sort((a, b) => a.localeCompare(b)).at(-1);
+}
+
+function daysBetween(referenceTime, candidateTime) {
+  try {
+    const ref = Date.parse(referenceTime);
+    const cand = Date.parse(candidateTime);
+    if (Number.isNaN(ref) || Number.isNaN(cand)) return 0;
+    return Math.max(0, Math.floor((ref - cand) / (1000 * 60 * 60 * 24)));
+  } catch {
+    return 0;
+  }
+}
+
+function median(values) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 0) return (sorted[mid - 1] + sorted[mid]) / 2;
+  return sorted[mid];
+}
+
+function findOrphanedEntries(inputs, degrees) {
+  const insights = [];
+  const nodes = Array.isArray(inputs.graph?.nodes) ? inputs.graph.nodes : [];
+
+  for (const node of nodes) {
+    const nodePath = node.path || node.id || "";
+    if (!nodePath) continue;
+    const degree = degrees.get(nodePath) || 0;
+    if (degree === 0) {
+      const validation = validateGraphInsightArtifact({
+        schema_version: 1,
+        insight_id: `insight-orphaned-${nodePath.replace(/[^a-z0-9_-]/gi, "-")}`,
+        kind: "orphaned_entry_review",
+        title: `Review isolated entry: ${node.label || node.title || nodePath}`,
+        summary: `Entry has no graph edges and may need linking evidence or wikilink connections.`,
+        source_paths: [nodePath],
+        evidence_refs: [{ path: nodePath, reason: "isolated graph node with degree 0" }],
+        reasoning_hints: { graph_degree: degree, confidence: 0.4 },
+        review_status: "review_required",
+        review_only: true,
+        boundaries: { executed: false, mutates_sources: false, auto_promotes: false },
+        created_at: deriveDeterministicReferenceTime(inputs),
+      });
+      if (validation.valid) insights.push(validation.value);
+    }
+  }
+
+  return insights;
+}
+
+function findHighConnectivityEntries(inputs, degrees) {
+  const insights = [];
+  const nodeDegrees = [];
+  for (const [, degree] of degrees) {
+    nodeDegrees.push(degree);
+  }
+  const medianDegree = median(nodeDegrees);
+
+  for (const [nodePath, degree] of degrees) {
+    if (degree > medianDegree && degree >= 2) {
+      const validation = validateGraphInsightArtifact({
+        schema_version: 1,
+        insight_id: `insight-high-conn-${nodePath.replace(/[^a-z0-9_-]/gi, "-")}`,
+        kind: "high_connectivity_review",
+        title: `Review highly connected entry: ${nodePath}`,
+        summary: `Entry has ${degree} graph connections (above median ${medianDegree}). Review whether the links are meaningful and not over-connected.`,
+        source_paths: [nodePath],
+        evidence_refs: [{ path: nodePath, reason: `high degree ${degree} > median ${medianDegree}` }],
+        reasoning_hints: { graph_degree: degree, confidence: 0.5 },
+        review_status: "review_required",
+        review_only: true,
+        boundaries: { executed: false, mutates_sources: false, auto_promotes: false },
+        created_at: deriveDeterministicReferenceTime(inputs),
+      });
+      if (validation.valid) insights.push(validation.value);
+    }
+  }
+
+  return insights;
+}
+
+function findCuratorBacklogClusters(inputs) {
+  const insights = [];
+  const cards = Array.isArray(inputs.curatorQueue?.cards) ? inputs.curatorQueue.cards : [];
+  if (cards.length < 2) return insights;
+
+  const communities = Array.isArray(inputs.graph?.communities) ? inputs.graph.communities : [];
+  const pathToCommunities = new Map();
+  for (const community of communities) {
+    const members = Array.isArray(community.members) ? community.members : [];
+    for (const member of members) {
+      if (!pathToCommunities.has(member)) pathToCommunities.set(member, []);
+      pathToCommunities.get(member).push(community.id || community.label || "unknown");
+    }
+  }
+
+  for (let i = 0; i < cards.length; i++) {
+    for (let j = i + 1; j < cards.length; j++) {
+      const cardA = cards[i];
+      const cardB = cards[j];
+      const pathsA = Array.isArray(cardA.source_paths) ? cardA.source_paths : [];
+      const pathsB = Array.isArray(cardB.source_paths) ? cardB.source_paths : [];
+      const sharedPaths = pathsA.filter((p) => pathsB.includes(p));
+
+      const tagsA = Array.isArray(cardA.tags) ? cardA.tags : [];
+      const tagsB = Array.isArray(cardB.tags) ? cardB.tags : [];
+      const sharedTags = tagsA.filter((t) => tagsB.includes(t));
+
+      let sharedCommunities = 0;
+      for (const path of pathsA) {
+        const commsA = pathToCommunities.get(path) || [];
+        for (const pathB of pathsB) {
+          const commsB = pathToCommunities.get(pathB) || [];
+          sharedCommunities += commsA.filter((c) => commsB.includes(c)).length;
+        }
+      }
+
+      if (sharedPaths.length > 0 || sharedTags.length > 0 || sharedCommunities > 0) {
+        const clusterId = `insight-cluster-${cardA.id}-${cardB.id}`;
+        const validation = validateGraphInsightArtifact({
+          schema_version: 1,
+          insight_id: clusterId.slice(0, 120),
+          kind: "curator_backlog_cluster",
+          title: `Review related curator cards: ${cardA.title} / ${cardB.title}`,
+          summary: `Curator queue cards share ${sharedPaths.length} source path(s), ${sharedTags.length} tag(s), and ${sharedCommunities} community overlap(s). Consider whether they should be consolidated or ordered.`,
+          source_paths: [...new Set([...pathsA, ...pathsB])].sort(compareStrings),
+          evidence_refs: [
+            { path: cardA.artifact_path || cardA.id, reason: `shared with ${cardB.id}` },
+            { path: cardB.artifact_path || cardB.id, reason: `shared with ${cardA.id}` },
+          ].filter((ref) => ref.path),
+          reasoning_hints: {
+            community_overlap: sharedCommunities,
+            confidence: Math.min(1, (sharedPaths.length + sharedTags.length + sharedCommunities) * 0.2),
+          },
+          review_status: "review_required",
+          review_only: true,
+          boundaries: { executed: false, mutates_sources: false, auto_promotes: false },
+          created_at: deriveDeterministicReferenceTime(inputs),
+        });
+        if (validation.valid) insights.push(validation.value);
+      }
+    }
+  }
+
+  return insights;
+}
+
+function findStaleReviewCandidates(inputs) {
+  const insights = [];
+  const referenceTime = deriveDeterministicReferenceTime(inputs);
+  const candidates = Array.isArray(inputs.browserData?.candidates) ? inputs.browserData.candidates : [];
+
+  for (const candidate of candidates) {
+    const candidatePath = candidate.path || "";
+    const updatedAt = candidate.updated_at || candidate.created_at || "";
+    const daysStale = daysBetween(referenceTime, updatedAt);
+    if (daysStale >= 7) {
+      const validation = validateGraphInsightArtifact({
+        schema_version: 1,
+        insight_id: `insight-stale-${candidatePath.replace(/[^a-z0-9_-]/gi, "-")}`,
+        kind: "stale_review_candidate",
+        title: `Review stale candidate: ${candidate.title || candidatePath}`,
+        summary: `Candidate has not been updated for ${daysStale} day(s) since ${updatedAt}. Consider reviewing, promoting, or rejecting.`,
+        source_paths: [candidatePath],
+        evidence_refs: [{ path: candidatePath, reason: `stale for ${daysStale} days` }],
+        reasoning_hints: { days_since_update: daysStale, confidence: Math.min(1, daysStale / 30) },
+        review_status: "review_required",
+        review_only: true,
+        boundaries: { executed: false, mutates_sources: false, auto_promotes: false },
+        created_at: referenceTime,
+      });
+      if (validation.valid) insights.push(validation.value);
+    }
+  }
+
+  return insights;
+}
+
+export function sortInsightsDeterministically(insights) {
+  return [...insights].sort((left, right) => {
+    const kindCompare = compareStrings(left.kind, right.kind);
+    if (kindCompare !== 0) return kindCompare;
+    const idCompare = compareStrings(left.insight_id, right.insight_id);
+    if (idCompare !== 0) return idCompare;
+    return compareStrings(left.created_at, right.created_at);
+  });
+}
+
+export function analyzePersonalGraph(inputs) {
+  // deterministic graph reasoning: no Date.now(), no random, no remote APIs
+  const degrees = calculateNodeDegrees(inputs.graph);
+
+  const insights = [
+    ...findOrphanedEntries(inputs, degrees),
+    ...findHighConnectivityEntries(inputs, degrees),
+    ...findCuratorBacklogClusters(inputs),
+    ...findStaleReviewCandidates(inputs),
+  ];
+
+  return sortInsightsDeterministically(insights);
+}

package/src/stage4/graph-reasoning/browser-data.js

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getGraphReasoningPaths, loadPersonalGraphReasoningInputs, readJsonLinesIfExists } from "./loader.js";
+import { analyzePersonalGraph } from "./analyzer.js";
+import { writeGraphInsightArtifacts, readGraphReasoningQueue, appendGraphReasoningAudit } from "./queue.js";
+import { validateGraphInsightArtifact, normalizeStage4Path } from "./schema.js";
+
+function compareStrings(left, right) {
+  return String(left ?? "").localeCompare(String(right ?? ""));
+}
+
+function summarizeInsight(insight, artifactPath) {
+  return {
+    id: insight.insight_id,
+    kind: insight.kind,
+    title: insight.title,
+    status: insight.review_status,
+    review_only: insight.review_only,
+    artifact_path: artifactPath,
+    source_paths: insight.source_paths,
+    reasoning_hints: insight.reasoning_hints,
+    created_at: insight.created_at,
+    updated_at: insight.updated_at,
+  };
+}
+
+function readInsightArtifacts(wikiRoot) {
+  const paths = getGraphReasoningPaths(wikiRoot);
+  if (!paths.insightsDir || !fs.existsSync(paths.insightsDir)) return [];
+  return fs.readdirSync(paths.insightsDir)
+    .filter((fileName) => fileName.endsWith(".json"))
+    .sort(compareStrings)
+    .flatMap((fileName) => {
+      const filePath = path.join(paths.insightsDir, fileName);
+      const artifactPath = `.system/stage4/graph-reasoning/insights/${fileName}`;
+      try {
+        const rawInsight = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        // Re-validate to ensure the artifact still meets schema and safety requirements
+        const validation = validateGraphInsightArtifact(rawInsight);
+        if (!validation.valid) return [];
+        // Ensure artifact path is safe (no absolute or traversal paths in source_paths)
+        const hasUnsafePaths = validation.value.source_paths.some((sp) => {
+          try {
+            normalizeStage4Path(sp);
+            return false;
+          } catch {
+            return true;
+          }
+        });
+        if (hasUnsafePaths) return [];
+        return [summarizeInsight(validation.value, artifactPath)];
+      } catch {
+        return [];
+      }
+    });
+}
+
+function readAuditSummary(wikiRoot) {
+  const paths = getGraphReasoningPaths(wikiRoot);
+  const actionCounts = {};
+  let auditCount = 0;
+  let lastRecord = null;
+
+  const records = readJsonLinesIfExists(paths.auditFile);
+  for (const record of records) {
+    const action = String(record.action || "unknown");
+    actionCounts[action] = (actionCounts[action] || 0) + 1;
+    auditCount += 1;
+    lastRecord = record;
+  }
+
+  return {
+    audit_count: auditCount,
+    action_counts: Object.fromEntries(Object.entries(actionCounts).sort(([left], [right]) => compareStrings(left, right))),
+    last_action: lastRecord?.action || "",
+    last_actor: lastRecord?.actor || "",
+    last_timestamp: lastRecord?.timestamp || "",
+  };
+}
+
+export function buildGraphReasoningBrowserData(wikiRoot) {
+  const queue = readGraphReasoningQueue(wikiRoot);
+  const insights = readInsightArtifacts(wikiRoot);
+  const auditSummary = readAuditSummary(wikiRoot);
+
+  return {
+    queue_cards: queue.cards.map((card) => ({
+      id: card.id,
+      kind: card.kind,
+      title: card.title,
+      status: card.status,
+      review_only: card.review_only,
+      artifact_path: card.artifact_path,
+      source_paths: card.source_paths,
+      reasoning_hints: card.reasoning_hints,
+      created_at: card.created_at,
+      updated_at: card.updated_at,
+    })),
+    insights,
+    summary: {
+      ...auditSummary,
+      insight_count: insights.length,
+      queue_card_count: queue.cards.length,
+    },
+  };
+}
+
+export function runGraphReasoningAnalysis(wikiRoot, options = {}) {
+  const inputs = loadPersonalGraphReasoningInputs(wikiRoot);
+  const insights = analyzePersonalGraph(inputs);
+  const writeResult = writeGraphInsightArtifacts(wikiRoot, insights, options);
+
+  if (!writeResult.success) return writeResult;
+
+  // Always write an audit record, even for zero-insight runs
+  const auditResult = appendGraphReasoningAudit(wikiRoot, {
+    subject_id: "analysis-run",
+    action: "run_analysis",
+    source_paths: [],
+  }, options);
+
+  return {
+    success: true,
+    wikiRoot,
+    insight_count: writeResult.count,
+    artifacts: writeResult.artifacts,
+    audit: auditResult.success ? auditResult.audit : null,
+    message: `Graph reasoning analysis completed: ${writeResult.count} insight(s) generated.`,
+  };
+}

package/src/stage4/graph-reasoning/index.js

@@ -0,0 +1,35 @@
+export {
+  validateGraphInsightArtifact,
+  validateGraphReasoningQueueCard,
+  validateGraphReasoningAuditRecord,
+  normalizeStage4Path,
+  redactGraphReasoningText,
+  GRAPH_REASONING_REVIEW_STATUS,
+  GRAPH_REASONING_KINDS,
+} from "./schema.js";
+
+export {
+  getGraphReasoningPaths,
+  loadPersonalGraphReasoningInputs,
+  readJsonFileIfExists,
+  readJsonLinesIfExists,
+} from "./loader.js";
+
+export {
+  analyzePersonalGraph,
+  calculateNodeDegrees,
+  deriveDeterministicReferenceTime,
+  sortInsightsDeterministically,
+} from "./analyzer.js";
+
+export {
+  ensureGraphReasoningStructure,
+  writeGraphInsightArtifacts,
+  readGraphReasoningQueue,
+  appendGraphReasoningAudit,
+} from "./queue.js";
+
+export {
+  buildGraphReasoningBrowserData,
+  runGraphReasoningAnalysis,
+} from "./browser-data.js";

package/src/stage4/graph-reasoning/loader.js

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function getGraphReasoningPaths(wikiRoot) {
+  const systemDir = path.join(wikiRoot, ".system");
+  const root = path.join(systemDir, "stage4", "graph-reasoning");
+  return {
+    systemDir,
+    root,
+    queueFile: path.join(root, "queue.json"),
+    insightsDir: path.join(root, "insights"),
+    auditFile: path.join(root, "audit.jsonl"),
+  };
+}
+
+export function readJsonFileIfExists(filePath, fallback = null) {
+  try {
+    if (!fs.existsSync(filePath)) return fallback;
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch {
+    return fallback;
+  }
+}
+
+export function readJsonLinesIfExists(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return [];
+    return fs.readFileSync(filePath, "utf-8")
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function readCuratorArtifactsDir(dirPath) {
+  const artifacts = [];
+  try {
+    if (!fs.existsSync(dirPath)) return artifacts;
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      const filePath = path.join(dirPath, entry.name);
+      try {
+        const content = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        // Basic validation: must be an object with required fields
+        if (content && typeof content === "object" && !Array.isArray(content) && content.id && content.title) {
+          artifacts.push({
+            ...content,
+            _artifact_path: `.system/curator/${path.basename(dirPath)}/${entry.name}`,
+          });
+        }
+      } catch {
+        // skip malformed artifacts
+      }
+    }
+  } catch {
+    // skip unreadable directories
+  }
+  return artifacts;
+}
+
+export function loadPersonalGraphReasoningInputs(wikiRoot) {
+  const loadErrors = [];
+
+  // Reads local .system/graph.json and .system/browser-data.json read-only.
+  const graphPath = path.join(wikiRoot, ".system", "graph.json");
+  const graph = readJsonFileIfExists(graphPath, { nodes: [], edges: [], communities: [], meta: {} });
+  if (!fs.existsSync(graphPath)) {
+    loadErrors.push("graph.json missing");
+  }
+
+  const browserDataPath = path.join(wikiRoot, ".system", "browser-data.json");
+  const browserData = readJsonFileIfExists(browserDataPath, {});
+  if (!fs.existsSync(browserDataPath)) {
+    loadErrors.push("browser-data.json missing");
+  }
+
+  const curatorQueue = readJsonFileIfExists(path.join(wikiRoot, ".system", "curator", "queue.json"), { cards: [] });
+
+  const curatorAudit = readJsonLinesIfExists(path.join(wikiRoot, ".system", "curator", "audit.jsonl"));
+
+  // Load Stage 3 curator artifact directories read-only
+  const lessonCandidates = readCuratorArtifactsDir(path.join(wikiRoot, ".system", "curator", "lesson-candidates"));
+  const consolidationProposals = readCuratorArtifactsDir(path.join(wikiRoot, ".system", "curator", "consolidation-proposals"));
+
+  const sourceFilePaths = [];
+  try {
+    const paths = [path.join(wikiRoot, "inbox"), path.join(wikiRoot, "problems"), path.join(wikiRoot, "editorial", "lessons")];
+    for (const dir of paths) {
+      if (!fs.existsSync(dir)) continue;
+      const entries = fs.readdirSync(dir, { withFileTypes: true, recursive: true });
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith(".md")) {
+          const relativePath = path.relative(wikiRoot, path.join(dir, entry.name)).replace(/\\/g, "/");
+          sourceFilePaths.push(relativePath);
+        }
+      }
+    }
+  } catch (error) {
+    loadErrors.push(`source scan error: ${error.message}`);
+  }
+
+  return {
+    graph: graph || { nodes: [], edges: [], communities: [], meta: {} },
+    browserData: browserData || {},
+    curatorQueue: curatorQueue || { cards: [] },
+    curatorAudit: curatorAudit || [],
+    lessonCandidates,
+    consolidationProposals,
+    sourceFilePaths: sourceFilePaths.sort((a, b) => a.localeCompare(b)),
+    loadErrors,
+  };
+}

package/src/stage4/graph-reasoning/queue.js

@@ -0,0 +1,154 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { validateGraphInsightArtifact, validateGraphReasoningAuditRecord, validateGraphReasoningQueueCard } from "./schema.js";
+import { getGraphReasoningPaths } from "./loader.js";
+
+const DEFAULT_BUILT_AT = "1970-01-01T00:00:00.000Z";
+
+function compareStrings(left, right) {
+  return String(left ?? "").localeCompare(String(right ?? ""));
+}
+
+function atomicWriteJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmpFile = `${filePath}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+  fs.writeFileSync(tmpFile, JSON.stringify(data, null, 2));
+  fs.renameSync(tmpFile, filePath);
+}
+
+function safeId(value, fallback = "graph-reasoning") {
+  return String(value || fallback)
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80) || fallback;
+}
+
+function shortHash(value) {
+  return crypto.createHash("sha256").update(String(value)).digest("hex").slice(0, 12);
+}
+
+function nowIso(options = {}) {
+  return options.now || new Date().toISOString();
+}
+
+function normalizeQueue(queue) {
+  const cards = [];
+  for (const card of Array.isArray(queue?.cards) ? queue.cards : []) {
+    const validation = validateGraphReasoningQueueCard(card);
+    if (validation.valid) cards.push(validation.value);
+  }
+  return {
+    version: 1,
+    cards: [...new Map(cards.map((card) => [card.id, card])).values()]
+      .sort((left, right) => compareStrings(`${left.created_at}:${left.id}`, `${right.created_at}:${right.id}`)),
+    meta: { built_at: queue?.meta?.built_at || DEFAULT_BUILT_AT },
+  };
+}
+
+function createEmptyQueue() {
+  return { version: 1, cards: [], meta: { built_at: DEFAULT_BUILT_AT } };
+}
+
+function writeQueue(wikiRoot, queue, options = {}) {
+  const normalized = normalizeQueue({ ...queue, meta: { built_at: nowIso(options) } });
+  atomicWriteJson(getGraphReasoningPaths(wikiRoot).queueFile, normalized);
+  return normalized;
+}
+
+function result(success, payload = {}) {
+  return { success, ...payload };
+}
+
+export function ensureGraphReasoningStructure(wikiRoot) {
+  const paths = getGraphReasoningPaths(wikiRoot);
+  fs.mkdirSync(paths.insightsDir, { recursive: true });
+  return paths;
+}
+
+export function readGraphReasoningQueue(wikiRoot) {
+  const paths = getGraphReasoningPaths(wikiRoot);
+  if (!fs.existsSync(paths.queueFile)) return createEmptyQueue();
+  try {
+    return normalizeQueue(JSON.parse(fs.readFileSync(paths.queueFile, "utf-8")));
+  } catch {
+    return createEmptyQueue();
+  }
+}
+
+export function appendGraphReasoningAudit(wikiRoot, record, options = {}) {
+  // Appends audit record to .system/stage4/graph-reasoning/audit.jsonl
+  const validation = validateGraphReasoningAuditRecord({
+    timestamp: nowIso(options),
+    actor: options.actor || "system",
+    executed: false,
+    ...record,
+  });
+  if (!validation.valid) return result(false, { error: validation.errors.join("; ") });
+  const paths = getGraphReasoningPaths(wikiRoot);
+  fs.mkdirSync(paths.root, { recursive: true });
+  fs.appendFileSync(paths.auditFile, `${JSON.stringify(validation.value)}\n`);
+  return result(true, { audit: validation.value });
+}
+
+function upsertCard(wikiRoot, card, options = {}) {
+  const validation = validateGraphReasoningQueueCard(card);
+  if (!validation.valid) return result(false, { error: validation.errors.join("; ") });
+  const queue = readGraphReasoningQueue(wikiRoot);
+  queue.cards = [...queue.cards.filter((item) => item.id !== validation.value.id), validation.value];
+  return result(true, { queue: writeQueue(wikiRoot, queue, options), card: validation.value });
+}
+
+export function writeGraphInsightArtifacts(wikiRoot, insights, options = {}) {
+  try {
+    const paths = ensureGraphReasoningStructure(wikiRoot);
+    const createdAt = nowIso(options);
+    const writtenArtifacts = [];
+    const writtenCards = [];
+    const auditRecords = [];
+
+    for (const insight of insights) {
+      const validation = validateGraphInsightArtifact(insight);
+      if (!validation.valid) continue;
+
+      const fileName = `${safeId(validation.value.insight_id)}-${shortHash(validation.value.insight_id)}.json`;
+      const filePath = path.join(paths.insightsDir, fileName);
+      const relativePath = `.system/stage4/graph-reasoning/insights/${fileName}`;
+      atomicWriteJson(filePath, validation.value);
+      writtenArtifacts.push(relativePath);
+
+      const sourcePaths = Array.isArray(validation.value.source_paths) ? validation.value.source_paths : [];
+      const cardResult = upsertCard(wikiRoot, {
+        id: `card-${validation.value.insight_id}`,
+        kind: validation.value.kind,
+        title: validation.value.title,
+        status: "review_required",
+        artifact_path: relativePath,
+        source_paths: sourcePaths,
+        reasoning_hints: validation.value.reasoning_hints,
+        created_at: createdAt,
+        updated_at: createdAt,
+      }, options);
+      if (cardResult.success) writtenCards.push(cardResult.card);
+
+      const auditResult = appendGraphReasoningAudit(wikiRoot, {
+        subject_id: validation.value.insight_id,
+        artifact_path: relativePath,
+        source_paths: sourcePaths,
+        action: "generate_insight",
+      }, options);
+      if (auditResult.success) auditRecords.push(auditResult.audit);
+    }
+
+    return result(true, {
+      artifacts: writtenArtifacts,
+      cards: writtenCards,
+      audits: auditRecords,
+      count: writtenArtifacts.length,
+      message: `Graph reasoning insights written: ${writtenArtifacts.length}`,
+    });
+  } catch (error) {
+    return result(false, { error: error.message });
+  }
+}