byterover-cli 2.6.0 → 3.0.1

package/dist/agent/infra/tools/implementations/curate-tool.js

@@ -1,10 +1,12 @@
-import { existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { z } from 'zod';
+import { REVIEW_BACKUPS_DIR } from '../../../../server/constants.js';
 import { DirectoryManager } from '../../../../server/core/domain/knowledge/directory-manager.js';
 import { MarkdownWriter, parseFrontmatterScoring } from '../../../../server/core/domain/knowledge/markdown-writer.js';
 import { applyDefaultScoring, determineTier, recordCurateUpdate, } from '../../../../server/core/domain/knowledge/memory-scoring.js';
 import { toSnakeCase } from '../../../../server/utils/file-helpers.js';
+import { deriveImpactFromLoss, detectStructuralLoss } from '../../../core/domain/knowledge/conflict-detector.js';
+import { resolveStructuralLoss } from '../../../core/domain/knowledge/conflict-resolver.js';
 import { ToolName } from '../../../core/domain/tools/constants.js';
 /**
  * Operation types for curating knowledge topics.
@@ -16,14 +18,23 @@ const OperationType = z.enum(['ADD', 'UPDATE', 'UPSERT', 'MERGE', 'DELETE']);
  */
 const RawConceptSchema = z.object({
     author: z.string().optional().describe('Author or source attribution (e.g., "meowso", "Team Security")'),
-    changes: z.array(z.string()).optional().describe('What changes are induced by this concept (e.g., code changes, process updates, market shifts)'),
-    files: z.array(z.string()).optional().describe('Related documents, source files, or resources (e.g., source code paths, reports, data files)'),
+    changes: z
+        .array(z.string())
+        .optional()
+        .describe('What changes are induced by this concept (e.g., code changes, process updates, market shifts)'),
+    files: z
+        .array(z.string())
+        .optional()
+        .describe('Related documents, source files, or resources (e.g., source code paths, reports, data files)'),
     flow: z.string().optional().describe('The process flow or workflow described by this concept'),
-    patterns: z.array(z.object({
+    patterns: z
+        .array(z.object({
         description: z.string().describe('What this pattern matches or validates'),
         flags: z.string().optional().describe('Pattern flags (e.g., "gi" for regex)'),
-        pattern: z.string().describe('The exact pattern string (e.g., regex pattern)')
-    })).optional().describe('Regex or validation patterns related to this concept'),
+        pattern: z.string().describe('The exact pattern string (e.g., regex pattern)'),
+    }))
+        .optional()
+        .describe('Regex or validation patterns related to this concept'),
     task: z.string().optional().describe('What is the task related to this concept'),
     timestamp: z
         .string()
@@ -38,18 +49,26 @@ const NarrativeSchema = z.object({
         .string()
         .optional()
         .describe('Dependency or relationship information (e.g., prerequisite systems, required inputs, related components)'),
-    diagrams: z.array(z.object({
-        content: z.string().describe('The full diagram content (Mermaid code, PlantUML code, or ASCII art) - preserved verbatim'),
+    diagrams: z
+        .array(z.object({
+        content: z
+            .string()
+            .describe('The full diagram content (Mermaid code, PlantUML code, or ASCII art) - preserved verbatim'),
         title: z.string().optional().describe('Optional title or label for the diagram'),
         type: z.enum(['mermaid', 'plantuml', 'ascii', 'other']).describe('Diagram type for proper rendering'),
-    })).optional().describe('Diagrams found in source content - Mermaid, PlantUML, ASCII art, sequence diagrams. Preserve verbatim.'),
+    }))
+        .optional()
+        .describe('Diagrams found in source content - Mermaid, PlantUML, ASCII art, sequence diagrams. Preserve verbatim.'),
     examples: z.string().optional().describe('Concrete examples and use cases demonstrating the concept'),
     highlights: z
         .string()
         .optional()
         .describe('Key highlights, capabilities, deliverables, or notable outcomes (e.g., "User permission can be stale for up to 300 seconds due to Redis cache")'),
     rules: z.string().optional().describe('Exact rules, constraints, or guidelines - preserved verbatim from source'),
-    structure: z.string().optional().describe('Structural or organizational documentation (e.g., file layout, data schema, process hierarchy)'),
+    structure: z
+        .string()
+        .optional()
+        .describe('Structural or organizational documentation (e.g., file layout, data schema, process hierarchy)'),
 });
 /**
  * Fact schema for structured factual statements extracted during curation.
@@ -59,24 +78,25 @@ const FactSchema = z.object({
         .enum(['personal', 'project', 'preference', 'convention', 'team', 'environment', 'other'])
         .optional()
         .describe('Category of the fact (e.g., "personal", "project", "preference", "convention", "team", "environment")'),
-    statement: z
-        .string()
-        .describe('The full factual statement (e.g., "My name is Andy", "We use PostgreSQL 15")'),
+    statement: z.string().describe('The full factual statement (e.g., "My name is Andy", "We use PostgreSQL 15")'),
     subject: z
         .string()
         .optional()
         .describe('What the fact is about in snake_case (e.g., "user_name", "database", "sprint_duration")'),
-    value: z
-        .string()
-        .optional()
-        .describe('The extracted value (e.g., "Andy", "PostgreSQL 15", "2 weeks")'),
+    value: z.string().optional().describe('The extracted value (e.g., "Andy", "PostgreSQL 15", "2 weeks")'),
 });
 /**
  * Content structure for ADD and UPDATE operations.
  */
 const ContentSchema = z.object({
-    facts: z.array(FactSchema).optional().describe('Factual statements extracted from content (e.g., personal info, project facts, preferences, conventions)'),
-    keywords: z.array(z.string()).default([]).describe('Keywords for search and discovery (e.g., ["jwt", "refresh_token", "rotation"])'),
+    facts: z
+        .array(FactSchema)
+        .optional()
+        .describe('Factual statements extracted from content (e.g., personal info, project facts, preferences, conventions)'),
+    keywords: z
+        .array(z.string())
+        .default([])
+        .describe('Keywords for search and discovery (e.g., ["jwt", "refresh_token", "rotation"])'),
     narrative: NarrativeSchema.optional().describe('Narrative section with descriptive and structural context'),
     rawConcept: RawConceptSchema.optional().describe('Raw concept section with metadata and technical footprint'),
     relations: z
@@ -84,7 +104,10 @@ const ContentSchema = z.object({
         .optional()
         .describe('Related topics using domain/topic/title.md or domain/topic/subtopic/title.md notation'),
     snippets: z.array(z.string()).optional().describe('Code/text snippets'),
-    tags: z.array(z.string()).default([]).describe('Tags for categorization and filtering (e.g., ["authentication", "security", "jwt"])'),
+    tags: z
+        .array(z.string())
+        .default([])
+        .describe('Tags for categorization and filtering (e.g., ["authentication", "security", "jwt"])'),
 });
 /**
  * Domain context schema for domain-level context.md files.
@@ -137,13 +160,25 @@ const SubtopicContextSchema = z.object({
  * Single operation schema for curating knowledge.
  */
 const OperationSchema = z.object({
+    confidence: z
+        .enum(['high', 'low'])
+        .describe('Your confidence in the accuracy and completeness of this operation. Use "high" when you have direct evidence from the source material; use "low" when the information is inferred, uncertain, or incomplete.'),
     content: ContentSchema.optional().describe('Content for ADD/UPDATE operations'),
     domainContext: DomainContextSchema.optional().describe('Domain-level context for new domains. When creating content in a NEW domain, provide this to auto-generate domain/context.md with purpose, scope, ownership, and usage. Only needed when the domain does not exist yet.'),
+    impact: z
+        .enum(['high', 'low'])
+        .describe('Estimated scope of impact of this knowledge change. "high": Changes that alter core decisions, strategies, tools, or established approaches. Any change that contradicts or reverses previously curated knowledge. Updates to existing knowledge that change its core substance. Deletions are always high impact. "low": New additions to previously undocumented topics, minor corrections, supplementary details like examples and clarifications, or updates that extend existing knowledge without changing its core substance.'),
     mergeTarget: z.string().optional().describe('Target path for MERGE operation'),
     mergeTargetTitle: z.string().optional().describe('Title of the target file for MERGE operation'),
     path: z.string().describe('Path: domain/topic/title.md or domain/topic/subtopic/title.md'),
-    reason: z.string().describe('Reasoning for this operation'),
+    reason: z
+        .string()
+        .describe('The motivation and context behind this curation — the WHY, not the what. Describe the decision, event, conversation, or observation that made this knowledge worth capturing. Write it for a human reviewer: they will read this in the web inbox to decide whether to approve or modify the change. Example of a good reason: "After debating caching strategies in PR #42, the team chose Redis with a 5-minute TTL as a deliberate performance/freshness trade-off — future agents should know this was intentional." Bad example: "Updating caching documentation."'),
     subtopicContext: SubtopicContextSchema.optional().describe('Subtopic-level context for new subtopics. When creating content in a NEW subtopic, provide this to auto-generate subtopic/context.md with focus and parent relation. Only needed when the subtopic does not exist yet.'),
+    summary: z
+        .string()
+        .optional()
+        .describe('One-line semantic summary of what this knowledge file contains after this operation. For human reviewers to quickly grasp the content without reading the full document. Example: "Caching strategy using Redis with 5-min TTL and write-through invalidation". Required for ADD/UPDATE/UPSERT/MERGE, not needed for DELETE.'),
     title: z
         .string()
         .optional()
@@ -155,21 +190,20 @@ const OperationSchema = z.object({
  * Filter out non-existent files from rawConcept.files.
  * Returns a new content object with only valid file paths.
  */
-function filterValidFiles(content) {
+async function filterValidFiles(content) {
     if (!content.rawConcept?.files || content.rawConcept.files.length === 0) {
         return content;
     }
-    const validFiles = content.rawConcept.files.filter((filePath) => {
+    const checks = await Promise.all(content.rawConcept.files.map(async (filePath) => {
         // Skip filesystem validation for URLs and document references
-        if (filePath.includes('://')) {
+        if (filePath.includes('://'))
             return true;
-        }
         // Skip entries that look like document references (no path separators, contain spaces)
-        if (!filePath.includes('/') && !filePath.includes('\\') && filePath.includes(' ')) {
+        if (!filePath.includes('/') && !filePath.includes('\\') && filePath.includes(' '))
             return true;
-        }
-        return existsSync(filePath);
-    });
+        return DirectoryManager.fileExists(filePath);
+    }));
+    const validFiles = content.rawConcept.files.filter((_, i) => checks[i]);
     // Return content with filtered files (empty array if none exist)
     return {
         ...content,
@@ -187,6 +221,45 @@ export const CurateInputSchema = z.object({
     basePath: z.string().default('.brv/context-tree').describe('Base path for knowledge storage'),
     operations: z.array(OperationSchema).describe('Array of curate operations to apply'),
 });
+/**
+ * Derive review metadata for a curate operation.
+ * confidence and impact are LLM-provided (schema defaults applied by Zod when omitted).
+ * needsReview:
+ *   - DELETE always (irreversible)
+ *   - high impact always (core decisions, strategy changes, contradictions)
+ *   - low impact → no review (minor additions/corrections)
+ */
+function deriveReviewMetadata(type, confidence, impact) {
+    const needsReview = type === 'DELETE' || impact === 'high';
+    return { confidence, impact, needsReview };
+}
+/**
+ * Back up a file's content before curate overwrites or deletes it.
+ *
+ * First-write-wins: if a backup already exists for this path, this is a no-op.
+ * This ensures the backup always reflects the snapshot version (state at last push),
+ * even when multiple curate operations modify the same file between pushes.
+ *
+ * @param filePath - Absolute path to the context tree file being modified
+ * @param basePath - Context tree base path (e.g., '.brv/context-tree')
+ */
+async function backupBeforeWrite(filePath, basePath) {
+    try {
+        const brvDir = dirname(resolve(basePath));
+        const relativePath = relative(resolve(basePath), resolve(filePath));
+        const backupPath = join(brvDir, REVIEW_BACKUPS_DIR, relativePath);
+        // First-write-wins: skip if backup already exists
+        const backupExists = await DirectoryManager.fileExists(backupPath);
+        if (backupExists)
+            return;
+        // Read current content and save as backup
+        const content = await DirectoryManager.readFile(filePath);
+        await DirectoryManager.writeFileAtomic(backupPath, content);
+    }
+    catch {
+        // Best-effort: backup failure must never block curate operations
+    }
+}
 function generateDomainContextMarkdown(domainName, context) {
     const sections = [`# Domain: ${domainName}`, '', '## Purpose', context.purpose, '', '## Scope'];
     if (context.scope.included.length > 0) {
@@ -360,19 +433,24 @@ function buildFullPath(basePath, knowledgePath) {
  * Execute ADD operation - create new domain/topic/subtopic with {title}.md
  */
 async function executeAdd(basePath, operation) {
-    const { content, domainContext, path, reason, subtopicContext, title, topicContext } = operation;
+    const { confidence, content, domainContext, impact, path, reason, subtopicContext, summary, title, topicContext } = operation;
+    const reviewMeta = deriveReviewMetadata('ADD', confidence, impact);
     if (!title) {
         return {
+            ...reviewMeta,
             message: 'ADD operation requires a title',
             path,
+            reason,
             status: 'failed',
             type: 'ADD',
         };
     }
     if (!content) {
         return {
+            ...reviewMeta,
             message: 'ADD operation requires content',
             path,
+            reason,
             status: 'failed',
             type: 'ADD',
         };
@@ -381,8 +459,10 @@ async function executeAdd(basePath, operation) {
         const parsed = parsePath(path);
         if (!parsed) {
             return {
+                ...reviewMeta,
                 message: `Invalid path format: ${path}. Expected domain/topic or domain/topic/subtopic`,
                 path,
+                reason,
                 status: 'failed',
                 type: 'ADD',
             };
@@ -390,8 +470,10 @@ async function executeAdd(basePath, operation) {
         const domainValidation = validateDomain(parsed.domain);
         if (!domainValidation.allowed) {
             return {
+                ...reviewMeta,
                 message: domainValidation.reason,
                 path,
+                reason,
                 status: 'failed',
                 type: 'ADD',
             };
@@ -401,16 +483,18 @@ async function executeAdd(basePath, operation) {
         const topicPath = join(domainPath, toSnakeCase(parsed.topic));
         const finalPath = parsed.subtopic ? join(topicPath, toSnakeCase(parsed.subtopic)) : topicPath;
         // Filter out non-existent files from rawConcept.files
-        const filteredContent = filterValidFiles(content);
+        const filteredContent = await filterValidFiles(content);
         const contextContent = MarkdownWriter.generateContext({
             facts: filteredContent.facts,
             keywords: filteredContent.keywords,
             name: title,
             narrative: filteredContent.narrative,
             rawConcept: filteredContent.rawConcept,
+            reason,
             relations: filteredContent.relations,
             scoring: applyDefaultScoring(),
             snippets: filteredContent.snippets ?? [],
+            summary,
             tags: filteredContent.tags,
         });
         const filename = `${toSnakeCase(title)}.md`;
@@ -418,39 +502,57 @@ async function executeAdd(basePath, operation) {
         await DirectoryManager.writeFileAtomic(contextPath, contextContent);
         await ensureContextMd(basePath, parsed, topicContext, subtopicContext);
         return {
+            ...reviewMeta,
             filePath: contextPath,
             message: `Created ${path}/${filename} with ${content.snippets?.length || 0} snippets. Reason: ${reason}`,
             path,
+            reason,
             status: 'success',
+            summary,
             type: 'ADD',
         };
     }
     catch (error) {
         return {
+            ...reviewMeta,
             message: error instanceof Error ? error.message : String(error),
             path,
+            reason,
             status: 'failed',
             type: 'ADD',
         };
     }
 }
+/**
+ * Compute the maximum of two impact levels.
+ */
+function maxImpact(a, b) {
+    const rank = { high: 1, low: 0 };
+    return rank[a] >= rank[b] ? a : b;
+}
 /**
  * Execute UPDATE operation - modify existing {title}.md
  */
 async function executeUpdate(basePath, operation) {
-    const { content, domainContext, path, reason, subtopicContext, title, topicContext } = operation;
+    const { confidence, content, domainContext, impact, path, reason, subtopicContext, summary, title, topicContext } = operation;
+    // Used for early-exit validation failures (before structural loss can be assessed)
+    const baseReviewMeta = deriveReviewMetadata('UPDATE', confidence, impact);
     if (!title) {
         return {
+            ...baseReviewMeta,
             message: 'UPDATE operation requires a title',
             path,
+            reason,
             status: 'failed',
             type: 'UPDATE',
         };
     }
     if (!content) {
         return {
+            ...baseReviewMeta,
             message: 'UPDATE operation requires content',
             path,
+            reason,
             status: 'failed',
             type: 'UPDATE',
         };
@@ -459,8 +561,10 @@ async function executeUpdate(basePath, operation) {
         const parsed = parsePath(path);
         if (!parsed) {
             return {
+                ...baseReviewMeta,
                 message: `Invalid path format: ${path}. Expected domain/topic or domain/topic/subtopic`,
                 path,
+                reason,
                 status: 'failed',
                 type: 'UPDATE',
             };
@@ -471,46 +575,73 @@ async function executeUpdate(basePath, operation) {
         const exists = await DirectoryManager.fileExists(contextPath);
         if (!exists) {
             return {
+                ...baseReviewMeta,
                 message: `File does not exist: ${path}/${filename}`,
                 path,
+                reason,
                 status: 'failed',
                 type: 'UPDATE',
             };
         }
         await createDomainContextIfMissing(basePath, parsed.domain, domainContext);
-        // Read existing file to preserve and update scoring metadata
+        // Read existing file to preserve scoring metadata and detect structural loss
         const existingContent = await DirectoryManager.readFile(contextPath);
         const existingScoring = existingContent ? parseFrontmatterScoring(existingContent) : undefined;
         const updatedScoring = existingScoring ? recordCurateUpdate(existingScoring) : applyDefaultScoring();
         const newTier = determineTier(updatedScoring.importance ?? 50, (updatedScoring.maturity ?? 'draft'));
         const finalScoring = { ...updatedScoring, maturity: newTier };
         // Filter out non-existent files from rawConcept.files
-        const filteredContent = filterValidFiles(content);
-        const contextContent = MarkdownWriter.generateContext({
+        const filteredContent = await filterValidFiles(content);
+        // Extract previous summary from existing file's frontmatter (for review UI)
+        const existingParsed = existingContent ? MarkdownWriter.parseContent(existingContent, title) : null;
+        const previousSummary = existingParsed?.summary;
+        // Detect structural loss and auto-resolve: merge back anything the LLM dropped
+        const proposedContextData = {
             facts: filteredContent.facts,
             keywords: filteredContent.keywords,
             name: title,
             narrative: filteredContent.narrative,
             rawConcept: filteredContent.rawConcept,
             relations: filteredContent.relations,
-            scoring: finalScoring,
             snippets: filteredContent.snippets ?? [],
             tags: filteredContent.tags,
+        };
+        let resolvedContextData = proposedContextData;
+        let elevatedImpact = impact;
+        if (existingParsed) {
+            const loss = detectStructuralLoss(existingParsed, proposedContextData);
+            const structuralImpact = deriveImpactFromLoss(loss);
+            elevatedImpact = maxImpact(impact, structuralImpact);
+            resolvedContextData = resolveStructuralLoss(existingParsed, proposedContextData, loss);
+        }
+        const reviewMeta = deriveReviewMetadata('UPDATE', confidence, elevatedImpact);
+        const contextContent = MarkdownWriter.generateContext({
+            ...resolvedContextData,
+            reason,
+            scoring: finalScoring,
+            summary,
         });
+        await backupBeforeWrite(contextPath, basePath);
         await DirectoryManager.writeFileAtomic(contextPath, contextContent);
         await ensureContextMd(basePath, parsed, topicContext, subtopicContext);
         return {
+            ...reviewMeta,
             filePath: contextPath,
             message: `Updated ${path}/${filename}. Reason: ${reason}`,
             path,
+            previousSummary,
+            reason,
             status: 'success',
+            summary,
             type: 'UPDATE',
         };
     }
     catch (error) {
         return {
+            ...baseReviewMeta,
             message: error instanceof Error ? error.message : String(error),
             path,
+            reason,
             status: 'failed',
             type: 'UPDATE',
         };
@@ -521,19 +652,24 @@ async function executeUpdate(basePath, operation) {
  * This is the recommended operation type as it eliminates the need for pre-checks.
  */
 async function executeUpsert(basePath, operation) {
-    const { path, title } = operation;
+    const { path, reason, title } = operation;
+    const reviewMeta = deriveReviewMetadata('UPSERT', operation.confidence, operation.impact);
     if (!title) {
         return {
+            ...reviewMeta,
             message: 'UPSERT operation requires a title',
             path,
+            reason,
             status: 'failed',
             type: 'UPSERT',
         };
     }
     if (!operation.content) {
         return {
+            ...reviewMeta,
             message: 'UPSERT operation requires content',
             path,
+            reason,
             status: 'failed',
             type: 'UPSERT',
         };
@@ -542,8 +678,10 @@ async function executeUpsert(basePath, operation) {
         const parsed = parsePath(path);
         if (!parsed) {
             return {
+                ...reviewMeta,
                 message: `Invalid path format: ${path}. Expected domain/topic or domain/topic/subtopic`,
                 path,
+                reason,
                 status: 'failed',
                 type: 'UPSERT',
             };
@@ -574,8 +712,10 @@ async function executeUpsert(basePath, operation) {
     }
     catch (error) {
         return {
+            ...reviewMeta,
             message: error instanceof Error ? error.message : String(error),
             path,
+            reason,
             status: 'failed',
             type: 'UPSERT',
         };
@@ -585,27 +725,34 @@ async function executeUpsert(basePath, operation) {
  * Execute MERGE operation - combine source file into target file, delete source file
  */
 async function executeMerge(basePath, operation) {
-    const { domainContext, mergeTarget, mergeTargetTitle, path, reason, subtopicContext, title, topicContext } = operation;
+    const { confidence, domainContext, impact, mergeTarget, mergeTargetTitle, path, reason, subtopicContext, summary, title, topicContext, } = operation;
+    const reviewMeta = deriveReviewMetadata('MERGE', confidence, impact);
     if (!title) {
         return {
+            ...reviewMeta,
             message: 'MERGE operation requires a title (source file)',
             path,
+            reason,
             status: 'failed',
             type: 'MERGE',
         };
     }
     if (!mergeTarget) {
         return {
+            ...reviewMeta,
             message: 'MERGE operation requires mergeTarget',
             path,
+            reason,
             status: 'failed',
             type: 'MERGE',
         };
     }
     if (!mergeTargetTitle) {
         return {
+            ...reviewMeta,
             message: 'MERGE operation requires mergeTargetTitle',
             path,
+            reason,
             status: 'failed',
             type: 'MERGE',
         };
@@ -615,8 +762,10 @@ async function executeMerge(basePath, operation) {
         const targetParsed = parsePath(mergeTarget);
         if (!sourceParsed || !targetParsed) {
             return {
+                ...reviewMeta,
                 message: `Invalid path format. Expected domain/topic or domain/topic/subtopic`,
                 path,
+                reason,
                 status: 'failed',
                 type: 'MERGE',
             };
@@ -631,16 +780,20 @@ async function executeMerge(basePath, operation) {
         const targetExists = await DirectoryManager.fileExists(targetContextPath);
         if (!sourceExists) {
             return {
+                ...reviewMeta,
                 message: `Source file does not exist: ${path}/${sourceFilename}`,
                 path,
+                reason,
                 status: 'failed',
                 type: 'MERGE',
             };
         }
         if (!targetExists) {
             return {
+                ...reviewMeta,
                 message: `Target file does not exist: ${mergeTarget}/${targetFilename}`,
                 path,
+                reason,
                 status: 'failed',
                 type: 'MERGE',
             };
@@ -649,23 +802,36 @@ async function executeMerge(basePath, operation) {
         await createDomainContextIfMissing(basePath, targetParsed.domain, domainContext);
         const sourceContent = await DirectoryManager.readFile(sourceContextPath);
         const targetContent = await DirectoryManager.readFile(targetContextPath);
-        const mergedContent = MarkdownWriter.mergeContexts(sourceContent, targetContent);
+        // Extract previous summary from target file (for review UI)
+        const targetParsedContent = MarkdownWriter.parseContent(targetContent, mergeTargetTitle);
+        const previousSummary = targetParsedContent.summary;
+        // Backup both files before merge modifies target and deletes source
+        await backupBeforeWrite(targetContextPath, basePath);
+        await backupBeforeWrite(sourceContextPath, basePath);
+        const mergedContent = MarkdownWriter.mergeContexts(sourceContent, targetContent, reason, summary);
         await DirectoryManager.writeFileAtomic(targetContextPath, mergedContent);
         await DirectoryManager.deleteFile(sourceContextPath);
         await ensureContextMd(basePath, sourceParsed, topicContext, subtopicContext);
         await ensureContextMd(basePath, targetParsed, topicContext, subtopicContext);
         return {
+            ...reviewMeta,
+            additionalFilePaths: [sourceContextPath],
             filePath: targetContextPath,
             message: `Merged ${path}/${sourceFilename} into ${mergeTarget}/${targetFilename}. Reason: ${reason}`,
             path,
+            previousSummary,
+            reason,
             status: 'success',
+            summary,
             type: 'MERGE',
         };
     }
     catch (error) {
         return {
+            ...reviewMeta,
             message: error instanceof Error ? error.message : String(error),
             path,
+            reason,
             status: 'failed',
             type: 'MERGE',
         };
@@ -677,6 +843,7 @@ async function executeMerge(basePath, operation) {
  */
 async function executeDelete(basePath, operation) {
     const { path, reason, title } = operation;
+    const reviewMeta = deriveReviewMetadata('DELETE', operation.confidence, operation.impact);
     try {
         const fullPath = buildFullPath(basePath, path);
         if (title) {
@@ -686,16 +853,34 @@ async function executeDelete(basePath, operation) {
             const exists = await DirectoryManager.fileExists(filePath);
             if (!exists) {
                 return {
+                    ...reviewMeta,
                     message: `File does not exist: ${path}/${filename}`,
                     path,
+                    reason,
                     status: 'failed',
                     type: 'DELETE',
                 };
             }
+            // Extract previous summary from file being deleted (for review UI)
+            let previousSummary;
+            try {
+                const existingContent = await DirectoryManager.readFile(filePath);
+                if (existingContent) {
+                    previousSummary = MarkdownWriter.parseContent(existingContent, title).summary;
+                }
+            }
+            catch {
+                // Best-effort: summary extraction failure must never block delete
+            }
+            await backupBeforeWrite(filePath, basePath);
             await DirectoryManager.deleteFile(filePath);
             return {
+                ...reviewMeta,
+                filePath,
                 message: `Deleted ${path}/${filename}. Reason: ${reason}`,
                 path,
+                previousSummary,
+                reason,
                 status: 'success',
                 type: 'DELETE',
             };
@@ -704,24 +889,56 @@ async function executeDelete(basePath, operation) {
         const exists = await DirectoryManager.folderExists(fullPath);
         if (!exists) {
             return {
+                ...reviewMeta,
                 message: `Folder does not exist: ${path}`,
                 path,
+                reason,
                 status: 'failed',
                 type: 'DELETE',
             };
         }
+        // Backup all markdown files in the folder before deleting
+        const mdFiles = await DirectoryManager.listMarkdownFiles(fullPath);
+        // Extract previous summary as bullet list of individual file summaries (for review UI)
+        let previousSummary;
+        try {
+            const contentFiles = mdFiles.filter((f) => {
+                const name = basename(f);
+                return name !== '_index.md' && name !== 'context.md';
+            });
+            const contents = await Promise.all(contentFiles.map(async (f) => ({ content: await DirectoryManager.readFile(f), name: basename(f) })));
+            const bullets = contents
+                .filter((c) => c.content !== null && c.content !== undefined)
+                .map((c) => ({ name: c.name, summary: MarkdownWriter.parseContent(c.content, c.name.replace(/\.md$/, '')).summary }))
+                .filter((c) => c.summary !== undefined)
+                .map((c) => `- ${c.name.replace(/\.md$/, '').replaceAll('_', ' ')}: ${c.summary}`);
+            if (bullets.length > 0) {
+                previousSummary = bullets.join('\n');
+            }
+        }
+        catch {
+            // Best-effort: summary extraction failure must never block delete
+        }
+        await Promise.all(mdFiles.map((f) => backupBeforeWrite(f, basePath)));
         await DirectoryManager.deleteTopicRecursive(fullPath);
         return {
+            ...reviewMeta,
+            additionalFilePaths: mdFiles,
+            filePath: fullPath,
             message: `Deleted folder ${path}. Reason: ${reason}`,
             path,
+            previousSummary,
+            reason,
             status: 'success',
             type: 'DELETE',
         };
     }
     catch (error) {
         return {
+            ...reviewMeta,
             message: error instanceof Error ? error.message : String(error),
             path,
+            reason,
             status: 'failed',
             type: 'DELETE',
         };
@@ -737,8 +954,12 @@ export async function executeCurate(input, _context) {
         return {
             applied: [
                 {
+                    confidence: 'high',
+                    impact: 'low',
                     message: `Invalid input: ${parseResult.error.message}`,
+                    needsReview: false,
                     path: '',
+                    reason: '',
                     status: 'failed',
                     type: 'ADD',
                 },
@@ -806,8 +1027,12 @@ export async function executeCurate(input, _context) {
                 // Exhaustive type check - TypeScript will error if any case is missed
                 const exhaustiveCheck = operation.type;
                 result = {
+                    confidence: 'high',
+                    impact: 'low',
                     message: `Unknown operation type: ${exhaustiveCheck}`,
+                    needsReview: false,
                     path: operation.path,
+                    reason: operation.reason,
                     status: 'failed',
                     type: operation.type,
                 };
@@ -847,13 +1072,15 @@ export function createCurateTool(workingDirectory) {
 
 **Operations:**
 1. **ADD** - Create new titled context file in domain/topic/subtopic
-   - Requires: path, title, content (snippets and/or relations), reason
+   - Requires: path, title, content, confidence, impact, reason
    - Relations must be in the format of "domain/topic/title.md" or "domain/topic/subtopic/title.md"
    - Example with Raw Concept + Narrative:
      {
        type: "ADD",
        path: "structure/caching",
        title: "Redis User Permissions",
+       confidence: "high",
+       impact: "medium",
        content: {
          rawConcept: {
            task: "Introduce Redis cache for getUserPermissions(userId)",
@@ -869,26 +1096,46 @@ export function createCurateTool(workingDirectory) {
          },
          relations: ["structure/api-endpoints/validation.md", "structure/api-endpoints/error-handling/retry-logic.md"]
        },
-       reason: "New caching pattern"
+       reason: "Introduced after team discussion in PR #42: chose Redis over in-process cache to share state across replicas. The 5-minute staleness was a deliberate trade-off, not an oversight — future agents should not 'fix' it."
      }
    - Creates: structure/caching/redis_user_permissions.md
 
 2. **UPDATE** - Modify existing titled context file (full replacement)
-   - Requires: path, title, content, reason
+   - Requires: path, title, content, confidence, impact, reason
    - Relations must be in the format of "domain/topic/title.md" or "domain/topic/subtopic/title.md"
    - Supports same content structure as ADD
+   - reason example: \`"Token expiry was changed from 1h to 15min in the security audit (Jira SEC-204). Updated to reflect the new default and the reasoning: shorter TTL reduces blast radius of leaked tokens."\`
 
 3. **MERGE** - Combine source file into target file, delete source
-   - Requires: path (source), title (source file), mergeTarget (destination path), mergeTargetTitle (destination file), reason
-   - Example: { type: "MERGE", path: "code_style/old_topic", title: "Old Guide", mergeTarget: "code_style/new_topic", mergeTargetTitle: "New Guide", reason: "Consolidating" }
+   - Requires: path (source), title (source file), mergeTarget (destination path), mergeTargetTitle (destination file), confidence, impact, reason
+   - Example: { type: "MERGE", path: "code_style/old_topic", title: "Old Guide", mergeTarget: "code_style/new_topic", mergeTargetTitle: "New Guide", confidence: "high", impact: "medium", reason: "Both files cover the same conventions; merging keeps a single source of truth and avoids contradictions." }
    - Raw concepts and narratives are intelligently merged
 
 4. **DELETE** - Remove specific file or entire folder
-   - Requires: path, title (optional), reason
+   - Requires: path, title (optional), confidence, impact, reason
    - With title: deletes specific file; without title: deletes entire folder
+   - Example: { type: "DELETE", path: "auth/legacy", title: "Session Token Flow", confidence: "high", impact: "high", reason: "Session-based auth was fully replaced by JWT in v2.0 (PR #88). Keeping this would mislead future agents into thinking sessions are still in use." }
+
+**Review Metadata (per operation — always provide these):**
+- **confidence**: How confident you are in the accuracy/completeness of this knowledge.
+  - \`"high"\`: You have direct evidence from the source material, codebase, or conversation.
+  - \`"low"\`: The information is inferred, partially known, or uncertain.
+- **impact**: The scope of this knowledge change.
+  - \`"high"\`: A deletion, or a major architectural/structural change.
+  - \`"medium"\`: A significant update to existing knowledge.
+  - \`"low"\`: A new addition or minor update.
+- **reason**: The human-readable motivation for this curation. This is the most important review field — a human reviewer will read it in the web inbox to decide whether to approve, edit, or reject the change.
+  - **Capture the WHY, not the what.** The what is already encoded in type, path, title, and content. The reason should answer: *What triggered this? What decision was made? What context would be lost without this knowledge?*
+  - **Write for a future human or agent reader**, not for yourself in the moment. Ask: "If someone reads this 6 months from now with no context, will they understand why this knowledge exists and why it should not be changed?"
+  - **Include trade-offs and intent.** If a decision was deliberate (a performance trade-off, a rejected alternative, a known limitation), say so explicitly — this prevents future agents from "fixing" something that was intentional.
+  - Good: \`"Decided in PR #42 to use Redis over in-process cache to share state across replicas. The 5-min staleness is a deliberate trade-off — do not optimize it away."\`
+  - Good: \`"Session auth was fully removed in v2.0; keeping this doc would mislead future agents into thinking it's still active."\`
+  - Bad: \`"Updating caching docs"\` — describes the operation, not the motivation
+  - Bad: \`"New pattern"\` — vague, gives a reviewer nothing to evaluate
+- Low-confidence or DELETE operations are automatically flagged for human review in the web inbox after \`brv push\`.
 
 **CRITICAL - Path vs Title separation:**
-- "path" = folder location only (domain/topic or domain/topic/subtopic) - NEVER include file extension suffixes 
+- "path" = folder location only (domain/topic or domain/topic/subtopic) - NEVER include file extension suffixes
 - "title" = the context name (becomes {title}.md file automatically)
 - The system auto-generates the .md file from title - DO NOT put .md or _md anywhere in path