sdtk-wiki-kit 0.1.0 → 0.1.2

package/src/lib/wiki-compile.js

@@ -12,6 +12,11 @@ const {
 } = require("./wiki-paths");
 
 const REPORT_PREFIX = "compile-dry-run-preview";
+const APPLY_PLAN_PREFIX = "compile-apply-plan";
+const APPLY_PLAN_RECORD_TYPE = "sdtk_wiki_compile_apply_plan";
+const APPLY_PLAN_SCHEMA_VERSION = 1;
+const PERSONAL_BRAIN_RELATIVE = path.join(".sdtk", "wiki", "personal-brain");
+const APPLY_MODE = "create_only_or_same_content_noop";
 const ALLOWED_OPERATION_TYPES = new Set([
   "append_section",
   "create_page",
@@ -27,6 +32,14 @@ function asArray(value) {
   return Array.isArray(value) ? value : [];
 }
 
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function stableHash(value) {
+  return require("crypto").createHash("sha256").update(String(value)).digest("hex");
+}
+
 function isRemoteUrl(value) {
   return /^(?:https?|ftp):\/\//i.test(String(value || ""));
 }
@@ -59,6 +72,430 @@ function ensureExistingWorkspace(projectPath) {
   return workspacePath;
 }
 
+function firstSourceRef(record) {
+  const refs = asArray(record.source_refs || record.sourceRefs);
+  return refs.length > 0 ? String(refs[0]) : "semantic_extraction_report";
+}
+
+function sourceHashFor(sourceById, sourceId, fallback = "") {
+  const source = sourceById.get(sourceId);
+  return source && source.source_hash ? String(source.source_hash) : fallback;
+}
+
+function refsFor(record) {
+  return [
+    ...asArray(record.source_refs || record.sourceRefs),
+    ...asArray(record.provenance_refs || record.provenanceRefs),
+    record.source_logical_path,
+    record.source_relative_path,
+  ].filter(Boolean).map(String);
+}
+
+function sourceRefsFor(record) {
+  const refs = asArray(record.source_refs || record.sourceRefs);
+  if (record.source_id) refs.unshift(record.source_id);
+  return [...new Set(refs.filter(Boolean).map(String))];
+}
+
+function provenanceRefsFor(record) {
+  return [...new Set(asArray(record.provenance_refs || record.provenanceRefs).filter(Boolean).map(String))];
+}
+
+function mdList(values) {
+  const items = asArray(values).filter(Boolean).map(String);
+  return items.length > 0 ? items.map((item) => `- ${item}`).join("\n") : "- None recorded.";
+}
+
+function recordTitle(record, fallback) {
+  return String(record.title || record.name || record.topic || record.entity_id || record.concept_id || record.source_id || fallback || "Generated page");
+}
+
+function renderSourcePage(source) {
+  return [
+    `# ${recordTitle(source, "Source")}`,
+    "",
+    "## Summary",
+    "",
+    `Local source page generated from ${source.source_logical_path || source.source_relative_path || source.source_id}.`,
+    "",
+    "## Source Metadata",
+    "",
+    `- source_id: ${source.source_id}`,
+    `- source_relative_path: ${source.source_relative_path || "(missing)"}`,
+    `- source_logical_path: ${source.source_logical_path || "(missing)"}`,
+    `- source_url: ${source.source_url || "(missing)"}`,
+    `- source_hash: ${source.source_hash || "(missing)"}`,
+    `- encoding_quality: ${source.encoding_quality || "(unknown)"}`,
+    "",
+    "## Source Quality",
+    "",
+    mdList(source.source_quality && source.source_quality.quality_flags),
+    "",
+    "## Provenance",
+    "",
+    mdList(provenanceRefsFor(source)),
+    "",
+  ].join("\n");
+}
+
+function renderToolEntityPage(entity) {
+  return [
+    `# ${recordTitle(entity, "Tool entity")}`,
+    "",
+    "## Summary",
+    "",
+    entity.summary || `Generated tool entity page for ${entity.name || entity.entity_id}.`,
+    "",
+    "## Repository",
+    "",
+    `- owner: ${entity.repo_owner || "(missing)"}`,
+    `- repo: ${entity.repo_name || "(missing)"}`,
+    `- url: ${entity.github_url || "(missing)"}`,
+    `- category: ${entity.category || "(unknown)"}`,
+    "",
+    "## Evidence",
+    "",
+    mdList(sourceRefsFor(entity)),
+    "",
+    "## Provenance",
+    "",
+    mdList(provenanceRefsFor(entity)),
+    "",
+  ].join("\n");
+}
+
+function renderConceptPage(concept) {
+  return [
+    `# ${recordTitle(concept, "Concept")}`,
+    "",
+    "## Definition",
+    "",
+    concept.definition || `Generated concept page for ${concept.name || concept.concept_id}.`,
+    "",
+    "## Aliases",
+    "",
+    mdList(concept.aliases),
+    "",
+    "## Related Entities",
+    "",
+    mdList(concept.related_entities),
+    "",
+    "## Sources",
+    "",
+    mdList(sourceRefsFor(concept)),
+    "",
+  ].join("\n");
+}
+
+function renderComparisonPage(comparison) {
+  return [
+    `# ${recordTitle(comparison, "Comparison")}`,
+    "",
+    "## Compared Entities",
+    "",
+    mdList(comparison.compared_entities),
+    "",
+    "## Criteria",
+    "",
+    mdList(comparison.criteria),
+    "",
+    "## Sources",
+    "",
+    mdList(sourceRefsFor(comparison)),
+    "",
+  ].join("\n");
+}
+
+function renderSynthesisPage(synthesis) {
+  return [
+    `# ${recordTitle(synthesis, "Synthesis")}`,
+    "",
+    "## Summary",
+    "",
+    synthesis.summary || `Generated synthesis page for ${synthesis.topic || synthesis.synthesis_id}.`,
+    "",
+    "## Recommendations",
+    "",
+    mdList(synthesis.recommendations),
+    "",
+    "## Sources",
+    "",
+    mdList(sourceRefsFor(synthesis)),
+    "",
+  ].join("\n");
+}
+
+function renderRootPage(name, payload) {
+  const extractionCounts = payload && payload.source_counts ? payload.source_counts : {};
+  const titles = {
+    index: "Personal Brain Index",
+    overview: "Personal Brain Overview",
+    ontology: "Personal Brain Ontology",
+    taxonomy: "Personal Brain Taxonomy",
+    graph: "Personal Brain Graph",
+    log: "Personal Brain Generation Log",
+  };
+  return [
+    `# ${titles[name] || "Personal Brain"}`,
+    "",
+    "## Generation Context",
+    "",
+    `- record_type: ${payload.record_type || "(unknown)"}`,
+    `- generated_at: ${payload.generated_at || "(unknown)"}`,
+    `- sources_scanned: ${extractionCounts.scanned ?? "(unknown)"}`,
+    `- sources_indexed: ${extractionCounts.indexed ?? "(unknown)"}`,
+    `- tool_candidates: ${asArray(payload.tool_entities).length}`,
+    `- concept_candidates: ${asArray(payload.concepts).length}`,
+    "",
+    "## Structure",
+    "",
+    "- sources/",
+    "- entities/tools/",
+    "- concepts/",
+    "- comparisons/",
+    "- syntheses/",
+    "- maintenance/",
+    "",
+  ].join("\n");
+}
+
+function renderMaintenancePage(payload) {
+  return [
+    "# Extraction Quality Review",
+    "",
+    "## Source Quality Findings",
+    "",
+    mdList(asArray(payload.source_quality_findings).map((finding) => `${finding.finding_id || finding.source_id}: ${asArray(finding.quality_flags).join(", ") || "review required"}`)),
+    "",
+    "## Unsupported Items",
+    "",
+    mdList(asArray(payload.unsupported_items).map((item) => `${item.item_id || "unsupported"}: ${item.reason || item.raw_observation_summary || "review required"}`)),
+    "",
+  ].join("\n");
+}
+
+function pushCreatePageOperation(operations, raw) {
+  if (!raw.target_page_path) return;
+  operations.push({
+    operation_id: raw.operation_id,
+    operation_type: "create_page",
+    source_id: raw.source_id || "semantic_extraction_report",
+    source_hash: raw.source_hash || "",
+    target_page_path: raw.target_page_path,
+    content: raw.content || "",
+    proposed_content_summary: raw.proposed_content_summary,
+    source_refs: raw.source_refs || [],
+    provenance_refs: raw.provenance_refs || [],
+    evidence_refs: raw.evidence_refs || [],
+    confidence: raw.confidence || "medium",
+    review_status: raw.review_status || "needs_review",
+  });
+}
+
+function operationsFromSemanticExtraction(payload) {
+  const sourceById = new Map(asArray(payload.sources).map((source) => [String(source.source_id), source]));
+  const operations = [];
+  const reportHash = stableHash(JSON.stringify({
+    generated_at: payload.generated_at,
+    source_counts: payload.source_counts,
+  })).slice(0, 12);
+  const rootSourceId = `semantic_extraction_${reportHash}`;
+  const rootSourceHash = reportHash;
+
+  for (const source of asArray(payload.sources)) {
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-source-${String(operations.length + 1).padStart(3, "0")}`,
+      source_id: source.source_id,
+      source_hash: source.source_hash,
+      target_page_path: source.target_page_path,
+      content: renderSourcePage(source),
+      proposed_content_summary: `Create personal-brain source page for ${source.source_logical_path || source.source_relative_path || source.source_id}.`,
+      source_refs: sourceRefsFor(source),
+      provenance_refs: provenanceRefsFor(source),
+      evidence_refs: refsFor(source),
+      confidence: source.source_quality && source.source_quality.low_confidence_extraction ? "low" : "medium",
+      review_status: source.source_quality && source.source_quality.low_confidence_extraction ? "needs_review" : "ready_for_review",
+    });
+  }
+
+  for (const entity of asArray(payload.tool_entities)) {
+    const sourceId = firstSourceRef(entity);
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-tool-${String(operations.length + 1).padStart(3, "0")}`,
+      source_id: sourceId,
+      source_hash: sourceHashFor(sourceById, sourceId),
+      target_page_path: entity.target_page_path,
+      content: renderToolEntityPage(entity),
+      proposed_content_summary: `Create tool entity page for ${entity.name || entity.entity_id}.`,
+      source_refs: sourceRefsFor(entity),
+      provenance_refs: provenanceRefsFor(entity),
+      evidence_refs: refsFor(entity),
+      confidence: entity.confidence_tier || entity.confidence || "medium",
+      review_status: "ready_for_review",
+    });
+    operations.push({
+      operation_id: `pb-tool-source-ref-${String(operations.length + 1).padStart(3, "0")}`,
+      operation_type: "add_source_ref",
+      source_id: sourceId,
+      source_hash: sourceHashFor(sourceById, sourceId),
+      target_page_path: entity.target_page_path,
+      content_sections: [
+        {
+          title: "Source References",
+          body: mdList(sourceRefsFor(entity)),
+        },
+      ],
+      proposed_content_summary: `Add source references for tool entity ${entity.name || entity.entity_id}.`,
+      source_refs: sourceRefsFor(entity),
+      provenance_refs: provenanceRefsFor(entity),
+      evidence_refs: refsFor(entity),
+      confidence: entity.confidence_tier || entity.confidence || "medium",
+      review_status: "ready_for_review",
+    });
+  }
+
+  for (const concept of asArray(payload.concepts)) {
+    const sourceId = firstSourceRef(concept);
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-concept-${String(operations.length + 1).padStart(3, "0")}`,
+      source_id: sourceId,
+      source_hash: sourceHashFor(sourceById, sourceId),
+      target_page_path: concept.target_page_path,
+      content: renderConceptPage(concept),
+      proposed_content_summary: `Create concept page for ${concept.name || concept.concept_id}.`,
+      source_refs: sourceRefsFor(concept),
+      provenance_refs: provenanceRefsFor(concept),
+      evidence_refs: refsFor(concept),
+      confidence: concept.confidence_tier || concept.confidence || "medium",
+      review_status: "ready_for_review",
+    });
+  }
+
+  for (const comparison of asArray(payload.comparisons)) {
+    const sourceId = firstSourceRef(comparison);
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-comparison-${String(operations.length + 1).padStart(3, "0")}`,
+      source_id: sourceId,
+      source_hash: sourceHashFor(sourceById, sourceId),
+      target_page_path: comparison.target_page_path,
+      content: renderComparisonPage(comparison),
+      proposed_content_summary: `Create comparison page for ${comparison.topic || comparison.comparison_id}.`,
+      source_refs: sourceRefsFor(comparison),
+      provenance_refs: provenanceRefsFor(comparison),
+      evidence_refs: refsFor(comparison),
+      confidence: comparison.confidence_tier || comparison.confidence || "medium",
+      review_status: "needs_review",
+    });
+  }
+
+  for (const synthesis of asArray(payload.syntheses)) {
+    const sourceId = firstSourceRef(synthesis);
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-synthesis-${String(operations.length + 1).padStart(3, "0")}`,
+      source_id: sourceId,
+      source_hash: sourceHashFor(sourceById, sourceId),
+      target_page_path: synthesis.target_page_path,
+      content: renderSynthesisPage(synthesis),
+      proposed_content_summary: `Create synthesis page for ${synthesis.topic || synthesis.synthesis_id}.`,
+      source_refs: sourceRefsFor(synthesis),
+      provenance_refs: provenanceRefsFor(synthesis),
+      evidence_refs: refsFor(synthesis),
+      confidence: synthesis.confidence_tier || synthesis.confidence || "medium",
+      review_status: "needs_review",
+    });
+  }
+
+  const rootPages = [
+    ["index", ".sdtk/wiki/personal-brain/index.md", "Create personal-brain index from semantic extraction output."],
+    ["overview", ".sdtk/wiki/personal-brain/overview.md", "Create personal-brain overview summarizing extracted local sources."],
+    ["ontology", ".sdtk/wiki/personal-brain/ontology.md", "Create ontology page describing source, tool_entity, concept, claim, relation, comparison, and synthesis records."],
+    ["taxonomy", ".sdtk/wiki/personal-brain/taxonomy.md", "Create taxonomy page for extracted categories and concepts."],
+    ["graph", ".sdtk/wiki/personal-brain/graph.md", "Create semantic graph summary page from extracted relations."],
+    ["log", ".sdtk/wiki/personal-brain/log.md", "Create generation log page for extraction and compile preview evidence."],
+  ];
+  for (const [name, target, summary] of rootPages) {
+    pushCreatePageOperation(operations, {
+      operation_id: `pb-root-${name}`,
+      source_id: rootSourceId,
+      source_hash: rootSourceHash,
+      target_page_path: target,
+      content: renderRootPage(name, payload),
+      proposed_content_summary: summary,
+      evidence_refs: [`record_type:${payload.record_type}`, `generated_at:${payload.generated_at || "(missing)"}`],
+      confidence: "medium",
+      review_status: "needs_review",
+    });
+  }
+
+  for (const relation of asArray(payload.relations)) {
+    operations.push({
+      operation_id: `pb-relation-${String(operations.length + 1).padStart(3, "0")}`,
+      operation_type: "add_relation",
+      source_id: relation.source_id || rootSourceId,
+      source_hash: rootSourceHash,
+      target_page_path: ".sdtk/wiki/personal-brain/graph.md",
+      content_sections: [
+        {
+          title: `Relation: ${relation.relation_type || relation.relation_id}`,
+          body: [
+            `- source_id: ${relation.source_id || "(missing)"}`,
+            `- target_id: ${relation.target_id || "(missing)"}`,
+            `- relation_type: ${relation.relation_type || "(missing)"}`,
+            `- evidence: ${relation.evidence || "(missing)"}`,
+            `- source_refs: ${sourceRefsFor(relation).join(", ") || "(missing)"}`,
+            `- provenance_refs: ${provenanceRefsFor(relation).join(", ") || "(missing)"}`,
+          ].join("\n"),
+        },
+      ],
+      proposed_content_summary: `Preview semantic relation ${relation.relation_type || relation.relation_id}.`,
+      source_refs: sourceRefsFor(relation),
+      provenance_refs: provenanceRefsFor(relation),
+      evidence_refs: refsFor(relation),
+      confidence: relation.confidence_tier || relation.confidence || "medium",
+      review_status: "ready_for_review",
+    });
+  }
+
+  const qualityFindingCount = asArray(payload.source_quality_findings).length;
+  const unsupportedCount = asArray(payload.unsupported_items).length;
+  if (qualityFindingCount > 0 || unsupportedCount > 0) {
+    pushCreatePageOperation(operations, {
+      operation_id: "pb-maintenance-extraction-quality-review",
+      source_id: rootSourceId,
+      source_hash: rootSourceHash,
+      target_page_path: ".sdtk/wiki/personal-brain/maintenance/extraction-quality-review.md",
+      content: renderMaintenancePage(payload),
+      proposed_content_summary: `Create maintenance review page for ${qualityFindingCount} source-quality finding(s) and ${unsupportedCount} unsupported extraction item(s).`,
+      evidence_refs: [`source_quality_findings:${qualityFindingCount}`, `unsupported_items:${unsupportedCount}`],
+      confidence: unsupportedCount > 0 ? "low" : "medium",
+      review_status: "needs_review",
+    });
+  }
+
+  return operations;
+}
+
+function emptySourceQualitySummary() {
+  return {
+    findings_count: 0,
+    unsupported_count: 0,
+    low_confidence_count: 0,
+    warning_count: 0,
+  };
+}
+
+function sourceQualitySummaryFromExtraction(payload) {
+  const findings = asArray(payload.source_quality_findings);
+  const unsupported = asArray(payload.unsupported_items);
+  const lowConfidence = findings.filter((finding) => ["low", "unsupported"].includes(String(finding.confidence_tier || finding.confidence || "").toLowerCase())).length;
+  return {
+    findings_count: findings.length,
+    unsupported_count: unsupported.length,
+    low_confidence_count: lowConfidence,
+    warning_count: findings.length + unsupported.length,
+  };
+}
+
 function parseJsonPlan(planPath) {
   let payload;
   try {
@@ -66,10 +503,25 @@ function parseJsonPlan(planPath) {
   } catch (error) {
     throw new ValidationError(`Invalid JSON compile plan: ${error.message}. No project files were changed.`);
   }
+  if (payload && payload.record_type === APPLY_PLAN_RECORD_TYPE) {
+    return {
+      operations: asArray(payload.operations),
+      sourceQualitySummary: payload.source_quality_summary || emptySourceQualitySummary(),
+    };
+  }
+  if (payload && payload.record_type === "sdtk_wiki_semantic_extraction") {
+    return {
+      operations: operationsFromSemanticExtraction(payload),
+      sourceQualitySummary: sourceQualitySummaryFromExtraction(payload),
+    };
+  }
   if (!payload || !Array.isArray(payload.operations)) {
     throw new ValidationError("Invalid compile plan: JSON plan must contain an operations array. No project files were changed.");
   }
-  return payload.operations;
+  return {
+    operations: payload.operations,
+    sourceQualitySummary: payload.source_quality_summary || emptySourceQualitySummary(),
+  };
 }
 
 function parseMarkdownPlan(planPath) {
@@ -104,7 +556,10 @@ function parseMarkdownPlan(planPath) {
       "Invalid markdown compile plan: expected structured operation blocks with operation_type. No project files were changed."
     );
   }
-  return operations;
+  return {
+    operations,
+    sourceQualitySummary: emptySourceQualitySummary(),
+  };
 }
 
 function parsePlanOperations(planPath) {
@@ -141,9 +596,52 @@ function expectedMutationFor(operation) {
   }
 }
 
-function normalizeOperation(rawOperation, index) {
+function renderContentSections(sections) {
+  return asArray(sections)
+    .map((section) => {
+      if (typeof section === "string") return section;
+      const title = section && section.title ? String(section.title) : "Generated Section";
+      const body = section && section.body ? String(section.body) : "";
+      return `## ${title}\n\n${body}`.trimEnd();
+    })
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+function fallbackOperationContent(operation) {
+  const title = operation.target_page_id || path.basename(operation.target_page_path || "generated-page.md", path.extname(operation.target_page_path || ""));
+  return [
+    `# ${title}`,
+    "",
+    "## Generated Operation",
+    "",
+    operation.proposed_content_summary || "Generated personal-brain content.",
+    "",
+    "## Evidence",
+    "",
+    mdList(operation.evidence_refs),
+    "",
+  ].join("\n");
+}
+
+function normalizeTargetPath(rawTargetPath, projectPath) {
+  const personalBrainRoot = path.join(getWikiWorkspacePath(projectPath), "personal-brain");
+  const targetValue = String(rawTargetPath || "");
+  const resolvedTarget = targetValue ? path.resolve(projectPath, targetValue) : "";
+  const withinProject = Boolean(resolvedTarget) && isPathInsideOrEqual(resolvedTarget, projectPath);
+  const withinPersonalBrain = Boolean(resolvedTarget) && isPathInsideOrEqual(resolvedTarget, personalBrainRoot);
+  return {
+    resolvedTarget,
+    targetPathNormalized: withinProject ? toPosix(path.relative(projectPath, resolvedTarget)) : toPosix(resolvedTarget),
+    withinProject,
+    withinPersonalBrain,
+  };
+}
+
+function normalizeOperation(rawOperation, index, projectPath) {
   const operationType = String(rawOperation.operation_type || rawOperation.operationType || "").trim();
   const isSupported = ALLOWED_OPERATION_TYPES.has(operationType);
+  const target = normalizeTargetPath(rawOperation.target_page_path || rawOperation.targetPagePath || "", projectPath);
   const operation = {
     operation_id: String(rawOperation.operation_id || rawOperation.operationId || `operation-${String(index + 1).padStart(3, "0")}`),
     source_id: String(rawOperation.source_id || rawOperation.sourceId || "unknown_source"),
@@ -151,14 +649,28 @@ function normalizeOperation(rawOperation, index) {
     revision: String(rawOperation.revision || ""),
     target_page_id: String(rawOperation.target_page_id || rawOperation.targetPageId || ""),
     target_page_path: String(rawOperation.target_page_path || rawOperation.targetPagePath || ""),
+    target_path_normalized: target.targetPathNormalized,
+    target_path_within_project: target.withinProject,
+    target_path_within_personal_brain: target.withinPersonalBrain,
     operation_type: operationType || "unsupported_operation",
     requested_operation_type: operationType || "(missing)",
     proposed_content_summary: String(rawOperation.proposed_content_summary || rawOperation.proposedContentSummary || ""),
+    content: String(rawOperation.content || ""),
+    content_sections: asArray(rawOperation.content_sections || rawOperation.contentSections),
+    source_refs: splitRefs(rawOperation.source_refs || rawOperation.sourceRefs || rawOperation.source_id || rawOperation.sourceId),
+    provenance_refs: splitRefs(rawOperation.provenance_refs || rawOperation.provenanceRefs),
     evidence_refs: splitRefs(rawOperation.evidence_refs || rawOperation.evidenceRefs),
     confidence: String(rawOperation.confidence || "unknown"),
     review_status: String(rawOperation.review_status || rawOperation.reviewStatus || "needs_review"),
     validation_status: isSupported ? "supported" : "unsupported_operation",
+    apply_mode: rawOperation.apply_mode || rawOperation.applyMode || APPLY_MODE,
   };
+  if (!operation.content && operation.content_sections.length > 0) {
+    operation.content = renderContentSections(operation.content_sections);
+  }
+  if (!operation.content) {
+    operation.content = fallbackOperationContent(operation);
+  }
   operation.expected_mutation_if_applied = expectedMutationFor(operation);
   if (!isSupported) {
     operation.operation_type = "unsupported_operation";
@@ -175,7 +687,7 @@ function summarizeOperations(operations) {
   return counts;
 }
 
-function renderReport({ projectPath, workspacePath, planPath, generatedAt, operations }) {
+function renderReport({ projectPath, workspacePath, planPath, applyPlanPath, generatedAt, operations }) {
   const summary = summarizeOperations(operations);
   const sortedTypes = Array.from(new Set([...Array.from(ALLOWED_OPERATION_TYPES), "unsupported_operation"]));
   const unsupported = operations.filter((operation) => operation.validation_status === "unsupported_operation");
@@ -186,6 +698,7 @@ function renderReport({ projectPath, workspacePath, planPath, generatedAt, opera
     `Project path: ${projectPath}`,
     `Workspace path: ${workspacePath}`,
     `Input plan path: ${planPath}`,
+    `Apply JSON sidecar path: ${applyPlanPath}`,
     `Operations: ${operations.length}`,
     "",
     "No wiki pages, raw sources, provenance, or atlas compatibility files were modified.",
@@ -238,6 +751,161 @@ function renderReport({ projectPath, workspacePath, planPath, generatedAt, opera
   return `${lines.join("\n").trimEnd()}\n`;
 }
 
+function renderApplyPlan({ projectPath, planPath, reportPath, generatedAt, operations, sourceQualitySummary }) {
+  return {
+    schema_version: APPLY_PLAN_SCHEMA_VERSION,
+    record_type: APPLY_PLAN_RECORD_TYPE,
+    generated_at: generatedAt,
+    project_path: projectPath,
+    source_plan_path: planPath,
+    dry_run_report_path: reportPath,
+    operation_counts: summarizeOperations(operations),
+    source_quality_summary: sourceQualitySummary || emptySourceQualitySummary(),
+    operations: operations.map((operation) => ({
+      operation_id: operation.operation_id,
+      operation_type: operation.operation_type,
+      target_page_path: operation.target_page_path,
+      target_path_normalized: operation.target_path_normalized,
+      target_path_within_project: operation.target_path_within_project,
+      target_path_within_personal_brain: operation.target_path_within_personal_brain,
+      content: operation.content,
+      content_sections: operation.content_sections,
+      source_refs: operation.source_refs,
+      provenance_refs: operation.provenance_refs,
+      evidence_refs: operation.evidence_refs,
+      confidence: operation.confidence,
+      review_status: operation.review_status,
+      validation_status: operation.validation_status,
+      expected_mutation_if_applied: operation.expected_mutation_if_applied,
+      apply_mode: APPLY_MODE,
+    })),
+  };
+}
+
+function ensureTrailingNewline(value) {
+  const text = String(value || "").replace(/\r\n/g, "\n").trimEnd();
+  return `${text}\n`;
+}
+
+function loadApplyPlan(planPath) {
+  if (path.extname(planPath).toLowerCase() !== ".json") {
+    throw new ValidationError("Apply requires a compile apply JSON sidecar. Markdown plans are rejected for apply. No project files were changed.");
+  }
+  let payload;
+  try {
+    payload = JSON.parse(fs.readFileSync(planPath, "utf-8"));
+  } catch (error) {
+    throw new ValidationError(`Invalid compile apply JSON sidecar: ${error.message}. No project files were changed.`);
+  }
+  if (payload && payload.record_type === "sdtk_wiki_semantic_extraction") {
+    throw new ValidationError("Apply rejects semantic extraction JSON. Run compile --dry-run first and apply the generated compile apply JSON sidecar. No project files were changed.");
+  }
+  if (!payload || payload.record_type !== APPLY_PLAN_RECORD_TYPE) {
+    throw new ValidationError(`Apply requires record_type ${APPLY_PLAN_RECORD_TYPE}. No project files were changed.`);
+  }
+  if (!Array.isArray(payload.operations)) {
+    throw new ValidationError("Compile apply JSON sidecar must contain operations[]. No project files were changed.");
+  }
+  return payload;
+}
+
+function validateApplyOperations(operations) {
+  const blocked = operations.filter((operation) => (
+    operation.validation_status !== "supported" ||
+    operation.operation_type === "unsupported_operation" ||
+    !ALLOWED_OPERATION_TYPES.has(operation.operation_type) ||
+    operation.apply_mode !== APPLY_MODE ||
+    !operation.target_path_within_project ||
+    !operation.target_path_within_personal_brain
+  ));
+  if (blocked.length > 0) {
+    throw new ValidationError(
+      `Compile apply plan contains ${blocked.length} blocked or unsafe operation(s). No project files were changed.`
+    );
+  }
+}
+
+function aggregateApplyTargets(operations, projectPath) {
+  const targets = new Map();
+  for (const operation of operations) {
+    const target = normalizeTargetPath(operation.target_page_path, projectPath);
+    if (!target.withinProject || !target.withinPersonalBrain) {
+      throw new ValidationError(`Unsafe personal-brain target path: ${operation.target_page_path}. No project files were changed.`);
+    }
+    const existing = targets.get(target.resolvedTarget) || {
+      path: target.resolvedTarget,
+      normalized: target.targetPathNormalized,
+      sections: [],
+      operationIds: [],
+    };
+    existing.operationIds.push(operation.operation_id);
+    existing.sections.push(ensureTrailingNewline(operation.content));
+    targets.set(target.resolvedTarget, existing);
+  }
+  for (const target of targets.values()) {
+    target.content = ensureTrailingNewline(target.sections.join("\n"));
+  }
+  return [...targets.values()].sort((a, b) => a.normalized.localeCompare(b.normalized));
+}
+
+function runWikiCompileApply({ projectPath, planArg }) {
+  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
+  if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
+    throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}`);
+  }
+
+  try {
+    ensureExistingWorkspace(resolvedProjectPath);
+    const planPath = resolvePlanPath(planArg, resolvedProjectPath);
+    const payload = loadApplyPlan(planPath);
+    const operations = payload.operations.map((operation, index) => normalizeOperation(operation, index, resolvedProjectPath));
+    validateApplyOperations(operations);
+    const targets = aggregateApplyTargets(operations, resolvedProjectPath);
+    const conflicts = [];
+    const unchanged = [];
+    const toCreate = [];
+
+    for (const target of targets) {
+      assertWikiWorkspaceWritePath(target.path, resolvedProjectPath);
+      if (!isPathInsideOrEqual(target.path, path.join(getWikiWorkspacePath(resolvedProjectPath), "personal-brain"))) {
+        throw new ValidationError(`Refusing to write outside .sdtk/wiki/personal-brain: ${target.normalized}. No project files were changed.`);
+      }
+      if (!fs.existsSync(target.path)) {
+        toCreate.push(target);
+        continue;
+      }
+      const current = fs.readFileSync(target.path, "utf-8").replace(/\r\n/g, "\n");
+      if (current === target.content) {
+        unchanged.push(target.normalized);
+      } else {
+        conflicts.push(target.normalized);
+      }
+    }
+
+    if (conflicts.length > 0) {
+      throw new ValidationError(`Compile apply would overwrite ${conflicts.length} existing different file(s): ${conflicts.join(", ")}. No project files were changed.`);
+    }
+
+    const created = [];
+    for (const target of toCreate) {
+      fs.mkdirSync(path.dirname(target.path), { recursive: true });
+      fs.writeFileSync(target.path, target.content, "utf-8");
+      created.push(target.normalized);
+    }
+
+    const sourceQualitySummary = payload.source_quality_summary || emptySourceQualitySummary();
+    return {
+      planPath,
+      created,
+      unchanged,
+      sourceQualityWarningCount: Number(sourceQualitySummary.warning_count || sourceQualitySummary.findings_count || 0),
+    };
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError(`Failed to apply SDTK-WIKI compile plan: ${error.message}`);
+  }
+}
+
 function runWikiCompileDryRun({ projectPath, planArg }) {
   const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
   if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
@@ -247,13 +915,17 @@ function runWikiCompileDryRun({ projectPath, planArg }) {
   try {
     const workspacePath = ensureExistingWorkspace(resolvedProjectPath);
     const planPath = resolvePlanPath(planArg, resolvedProjectPath);
-    const rawOperations = parsePlanOperations(planPath);
-    const operations = rawOperations.map((operation, index) => normalizeOperation(operation, index));
+    const parsed = parsePlanOperations(planPath);
+    const rawOperations = parsed.operations;
+    const sourceQualitySummary = parsed.sourceQualitySummary || emptySourceQualitySummary();
+    const operations = rawOperations.map((operation, index) => normalizeOperation(operation, index, resolvedProjectPath));
     const reportsPath = getWikiReportsPath(resolvedProjectPath);
     assertWikiWorkspaceWritePath(reportsPath, resolvedProjectPath);
     const generatedAt = new Date().toISOString();
     const reportPath = path.join(reportsPath, `${REPORT_PREFIX}-${todayStamp(new Date(generatedAt))}.md`);
+    const applyPlanPath = path.join(reportsPath, `${APPLY_PLAN_PREFIX}-${todayStamp(new Date(generatedAt))}.json`);
     assertWikiWorkspaceWritePath(reportPath, resolvedProjectPath);
+    assertWikiWorkspaceWritePath(applyPlanPath, resolvedProjectPath);
     fs.mkdirSync(reportsPath, { recursive: true });
     fs.writeFileSync(
       reportPath,
@@ -261,14 +933,28 @@ function runWikiCompileDryRun({ projectPath, planArg }) {
         projectPath: resolvedProjectPath,
         workspacePath,
         planPath,
+        applyPlanPath,
         generatedAt,
         operations,
       }),
       "utf-8"
     );
+    fs.writeFileSync(
+      applyPlanPath,
+      JSON.stringify(renderApplyPlan({
+        projectPath: resolvedProjectPath,
+        planPath,
+        reportPath,
+        generatedAt,
+        operations,
+        sourceQualitySummary,
+      }), null, 2) + "\n",
+      "utf-8"
+    );
 
     return {
       reportPath,
+      applyPlanPath,
       operations,
       summary: summarizeOperations(operations),
       unsupportedCount: operations.filter((operation) => operation.validation_status === "unsupported_operation").length,
@@ -280,8 +966,10 @@ function runWikiCompileDryRun({ projectPath, planArg }) {
 }
 
 module.exports = {
+  APPLY_PLAN_RECORD_TYPE,
   ALLOWED_OPERATION_TYPES,
   REPORT_PREFIX,
   renderReport,
+  runWikiCompileApply,
   runWikiCompileDryRun,
 };