byterover-cli 1.8.0 → 2.1.0

package/dist/agent/infra/tools/implementations/search-knowledge-tool.js

@@ -3,6 +3,14 @@ import { ToolName } from '../../../core/domain/tools/constants.js';
 import { SearchKnowledgeService } from './search-knowledge-service.js';
 const SearchKnowledgeInputSchema = z
     .object({
+    excludeKinds: z
+        .array(z.enum(['archive_stub', 'context', 'domain', 'subtopic', 'topic']))
+        .optional()
+        .describe('Symbol kinds to exclude from results'),
+    includeKinds: z
+        .array(z.enum(['archive_stub', 'context', 'domain', 'subtopic', 'topic']))
+        .optional()
+        .describe('Symbol kinds to include in results (filters out others)'),
     limit: z
         .number()
         .int()
@@ -10,14 +18,40 @@ const SearchKnowledgeInputSchema = z
         .optional()
         .default(10)
         .describe('Maximum number of results to return (default: 10)'),
-    query: z.string().min(1).describe('Natural language query string to search for in the knowledge base'),
+    minMaturity: z
+        .enum(['core', 'draft', 'validated'])
+        .optional()
+        .describe('Minimum maturity tier for results'),
+    overview: z
+        .boolean()
+        .optional()
+        .describe('If true, return tree structure overview instead of search results'),
+    overviewDepth: z
+        .number()
+        .int()
+        .min(0)
+        .max(3)
+        .optional()
+        .default(2)
+        .describe('Depth for overview mode (default: 2, showing domains + topics)'),
+    query: z
+        .string()
+        .min(1)
+        .describe('Natural language query or symbolic path. ' +
+        'Supports path queries like "auth/jwt" to navigate the knowledge hierarchy. ' +
+        'Use "/" to scope searches (e.g., "auth/jwt refresh strategy" searches within auth/jwt).'),
+    scope: z
+        .string()
+        .optional()
+        .describe('Path prefix to scope search within (e.g., "auth" or "auth/jwt-tokens")'),
 })
     .strict();
 /**
  * Creates the search knowledge tool.
  *
  * Searches the curated knowledge base in .brv/context-tree/ for relevant topics.
- * Uses MiniSearch for full-text search with caching and indexing.
+ * Supports symbolic path queries, scoped search, kind/maturity filtering, and overview mode
+ * in addition to full-text BM25 search.
  *
  * @param fileSystem - File system service dependency
  * @param config - Optional configuration
@@ -28,11 +62,21 @@ export function createSearchKnowledgeTool(fileSystem, config = {}) {
     const service = new SearchKnowledgeService(fileSystem, config);
     return {
         description: 'Search the curated knowledge base in .brv/context-tree/ for relevant topics. ' +
-            'Use natural language queries to find knowledge about specific topics (e.g., "auth design", "API patterns"). ' +
-            'Returns matching file paths, titles, and relevant excerpts.',
+            'Use natural language queries or symbolic paths (e.g., "auth/jwt", "/auth/jwt-tokens") ' +
+            'to navigate the knowledge hierarchy. Supports scoped search, kind filtering, ' +
+            'maturity filtering, and overview mode. Returns matching file paths, titles, excerpts, ' +
+            'and symbolic metadata (kind, backlinks).',
         async execute(input, _context) {
-            const { limit, query } = SearchKnowledgeInputSchema.parse(input);
-            return service.search(query, { limit });
+            const parsed = SearchKnowledgeInputSchema.parse(input);
+            return service.search(parsed.query, {
+                excludeKinds: parsed.excludeKinds,
+                includeKinds: parsed.includeKinds,
+                limit: parsed.limit,
+                minMaturity: parsed.minMaturity,
+                overview: parsed.overview,
+                overviewDepth: parsed.overviewDepth,
+                scope: parsed.scope,
+            });
         },
         id: ToolName.SEARCH_KNOWLEDGE,
         inputSchema: SearchKnowledgeInputSchema,

package/dist/agent/infra/tools/tool-manager.js

@@ -29,7 +29,10 @@ export class ToolManager {
      * Uses code_exec only - curate operations available via tools.curate() in sandbox.
      */
     static CURATE_TOOL_NAMES = [
+        'agentic_map',
         'code_exec',
+        'expand_knowledge',
+        'llm_map',
     ];
     /**
      * Tools allowed for query operations - only code_exec for programmatic search
@@ -38,6 +41,7 @@ export class ToolManager {
      */
     static QUERY_TOOL_NAMES = [
         'code_exec',
+        'expand_knowledge',
     ];
     cacheValid = false;
     callIdCounter = 0;
@@ -113,6 +117,8 @@ export class ToolManager {
             // Execute tool via scheduler (with policy check) or directly via provider
             const result = this.scheduler
                 ? await this.scheduler.execute(toolName, effectiveArgs, {
+                    commandType: effectiveContext.commandType,
+                    metadata: effectiveContext.metadata,
                     sessionId: sessionId ?? 'default',
                     taskId: effectiveContext.taskId,
                 })

package/dist/agent/infra/tools/tool-provider.d.ts

@@ -13,6 +13,12 @@ import { ToolMarker } from './tool-markers.js';
  * 2. Execution phase (via invocation)
  */
 export declare class ToolProvider implements IToolProvider {
+    /**
+     * Known keys of ToolServices — used for runtime validation of Record<string, unknown> input.
+     * Derived from ToolServices type to prevent drift.
+     * TypeScript ensures this object matches ToolServices keys at compile time.
+     */
+    private static readonly VALID_SERVICE_KEYS;
     private readonly descriptionLoader?;
     private initialized;
     private invocationBuilder?;
@@ -74,6 +80,12 @@ export declare class ToolProvider implements IToolProvider {
      * If a description loader is provided, tool descriptions are loaded from external files.
      */
     initialize(): Promise<void>;
+    /**
+     * Atomically replace specific tools with new service dependencies.
+     * Build-then-swap pattern: builds new tool instances first, only swaps if all succeed.
+     * Throws if any requested tool cannot be rebuilt (no partial swap).
+     */
+    replaceTools(toolNames: string[], newServices: Record<string, unknown>): void;
     /**
      * Update services and re-register tools that depend on newly available services.
      * This is used to inject services that are created after ToolProvider initialization

package/dist/agent/infra/tools/tool-provider.js

@@ -12,6 +12,25 @@ import { convertZodToJsonSchema } from './utils/schema-converter.js';
  * 2. Execution phase (via invocation)
  */
 export class ToolProvider {
+    /**
+     * Known keys of ToolServices — used for runtime validation of Record<string, unknown> input.
+     * Derived from ToolServices type to prevent drift.
+     * TypeScript ensures this object matches ToolServices keys at compile time.
+     */
+    static VALID_SERVICE_KEYS = new Set(Object.keys({
+        agentInstance: 0,
+        contentGenerator: 0,
+        environmentContext: 0,
+        fileSystemService: 0,
+        getToolProvider: 0,
+        logger: 0,
+        maxContextTokens: 0,
+        memoryManager: 0,
+        processService: 0,
+        sandboxService: 0,
+        todoStorage: 0,
+        tokenizer: 0,
+    }));
     descriptionLoader;
     initialized = false;
     invocationBuilder;
@@ -178,6 +197,65 @@ export class ToolProvider {
         this.invocationBuilder = new ToolInvocationBuilder(this.tools);
         this.initialized = true;
     }
+    /**
+     * Atomically replace specific tools with new service dependencies.
+     * Build-then-swap pattern: builds new tool instances first, only swaps if all succeed.
+     * Throws if any requested tool cannot be rebuilt (no partial swap).
+     */
+    replaceTools(toolNames, newServices) {
+        // 0. Runtime key validation — catch typos in Record<string, unknown> early
+        for (const key of Object.keys(newServices)) {
+            if (!ToolProvider.VALID_SERVICE_KEYS.has(key)) {
+                throw new Error(`replaceTools: unknown service key "${key}" — valid keys: ${[...ToolProvider.VALID_SERVICE_KEYS].join(', ')}`);
+            }
+        }
+        // 1. Merge new services into existing (cast from Record to ToolServices)
+        const mergedServices = {
+            ...this.services,
+            ...newServices,
+        };
+        // 2. Deduplicate input tool names
+        const uniqueToolNames = [...new Set(toolNames)];
+        // 3. Stage new tool instances — fail hard if any tool cannot be built
+        const stagedTools = new Map();
+        for (const toolName of uniqueToolNames) {
+            const entry = TOOL_REGISTRY[toolName];
+            if (!entry) {
+                throw new Error(`replaceTools: unknown tool "${toolName}" not in TOOL_REGISTRY`);
+            }
+            // Check required services
+            const allServicesAvailable = entry.requiredServices.every((serviceName) => mergedServices[serviceName] !== undefined);
+            if (!allServicesAvailable) {
+                throw new Error(`replaceTools: missing required services for "${toolName}": ${entry.requiredServices.join(', ')}`);
+            }
+            // Build tool (throws on factory failure — old tools remain intact)
+            const tool = entry.factory(mergedServices);
+            // Apply description loader overrides
+            const fileDescription = this.loadExternalDescription(entry.descriptionFile);
+            if (fileDescription) {
+                tool.description = fileDescription;
+            }
+            stagedTools.set(toolName, tool);
+        }
+        // 4. Swap atomically — only reached if ALL builds succeeded
+        this.services = mergedServices;
+        for (const [name, tool] of stagedTools) {
+            this.tools.set(name, tool);
+        }
+        // 5. Recompute markers from all registered tools
+        this.toolMarkers.clear();
+        for (const [toolName, entry] of Object.entries(TOOL_REGISTRY)) {
+            if (this.tools.has(toolName)) {
+                for (const marker of entry.markers) {
+                    this.toolMarkers.add(marker);
+                }
+            }
+        }
+        // 6. Rebuild invocationBuilder
+        if (this.initialized && this.invocationBuilder) {
+            this.invocationBuilder = new ToolInvocationBuilder(this.tools);
+        }
+    }
     /**
      * Update services and re-register tools that depend on newly available services.
      * This is used to inject services that are created after ToolProvider initialization

package/dist/agent/infra/tools/tool-registry.d.ts

@@ -1,10 +1,14 @@
 import type { EnvironmentContext } from '../../core/domain/environment/types.js';
 import type { KnownTool } from '../../core/domain/tools/constants.js';
 import type { Tool } from '../../core/domain/tools/types.js';
+import type { ICipherAgent } from '../../core/interfaces/i-cipher-agent.js';
+import type { IContentGenerator } from '../../core/interfaces/i-content-generator.js';
 import type { IFileSystem } from '../../core/interfaces/i-file-system.js';
+import type { ILogger } from '../../core/interfaces/i-logger.js';
 import type { IProcessService } from '../../core/interfaces/i-process-service.js';
 import type { ISandboxService } from '../../core/interfaces/i-sandbox-service.js';
 import type { ITodoStorage } from '../../core/interfaces/i-todo-storage.js';
+import type { ITokenizer } from '../../core/interfaces/i-tokenizer.js';
 import type { MemoryManager } from '../memory/memory-manager.js';
 import type { ToolProviderGetter } from './tool-provider-getter.js';
 import { ToolMarker } from './tool-markers.js';
@@ -13,6 +17,10 @@ import { ToolMarker } from './tool-markers.js';
  * Tools declare which services they need via requiredServices.
  */
 export interface ToolServices {
+    /** Agent instance for creating sub-sessions (used by agentic_map) */
+    agentInstance?: ICipherAgent;
+    /** Content generator for stateless LLM calls (used by llm_map) */
+    contentGenerator?: IContentGenerator;
     /** Environment context for sandbox injection */
     environmentContext?: EnvironmentContext;
     /** File system service for file operations */
@@ -22,6 +30,10 @@ export interface ToolServices {
      * Used by batch tool to execute other tools.
      */
     getToolProvider?: ToolProviderGetter;
+    /** Logger for fail-open warnings in map tools */
+    logger?: ILogger;
+    /** Max context tokens for ContextTreeStore τ_hard computation */
+    maxContextTokens?: number;
     /** Memory manager for agent memory operations */
     memoryManager?: MemoryManager;
     /** Process service for command execution */
@@ -30,6 +42,8 @@ export interface ToolServices {
     sandboxService?: ISandboxService;
     /** Todo storage service for session-based todo persistence */
     todoStorage?: ITodoStorage;
+    /** Tokenizer for ContextTreeStore token counting */
+    tokenizer?: ITokenizer;
 }
 /**
  * Tool factory function type.

package/dist/agent/infra/tools/tool-registry.js

@@ -1,10 +1,13 @@
 import { ToolName } from '../../core/domain/tools/constants.js';
 import { createCurateService } from '../sandbox/curate-service.js';
+import { createAgenticMapTool } from './implementations/agentic-map-tool.js';
 import { createCodeExecTool } from './implementations/code-exec-tool.js';
 import { createCurateTool } from './implementations/curate-tool.js';
+import { createExpandKnowledgeTool } from './implementations/expand-knowledge-tool.js';
 import { createGlobFilesTool } from './implementations/glob-files-tool.js';
 import { createGrepContentTool } from './implementations/grep-content-tool.js';
 import { createListDirectoryTool } from './implementations/list-directory-tool.js';
+import { createLlmMapTool } from './implementations/llm-map-tool.js';
 import { createReadFileTool } from './implementations/read-file-tool.js';
 import { createSearchKnowledgeService } from './implementations/search-knowledge-service.js';
 import { createSearchKnowledgeTool } from './implementations/search-knowledge-tool.js';
@@ -35,6 +38,20 @@ function getRequiredService(service, serviceName) {
  * 3. Add entry to this registry
  */
 export const TOOL_REGISTRY = {
+    [ToolName.AGENTIC_MAP]: {
+        factory({ agentInstance, contentGenerator, environmentContext, logger, maxContextTokens, tokenizer }) {
+            const agent = getRequiredService(agentInstance, 'agentInstance');
+            const workingDirectory = environmentContext?.workingDirectory ?? process.cwd();
+            return createAgenticMapTool(agent, workingDirectory, {
+                generator: contentGenerator,
+                logger,
+                maxContextTokens,
+                tokenizer,
+            });
+        },
+        markers: [ToolMarker.Execution],
+        requiredServices: ['agentInstance'],
+    },
     [ToolName.CODE_EXEC]: {
         descriptionFile: 'code_exec',
         factory({ environmentContext, fileSystemService, sandboxService }) {
@@ -50,7 +67,7 @@ export const TOOL_REGISTRY = {
             }
             // Inject curate service into sandbox for Tools SDK
             if (sandbox.setCurateService) {
-                const curateService = createCurateService();
+                const curateService = createCurateService(environmentContext?.workingDirectory);
                 sandbox.setCurateService(curateService);
             }
             // Inject environment context into sandbox for env.* access
@@ -64,11 +81,17 @@ export const TOOL_REGISTRY = {
     },
     [ToolName.CURATE]: {
         descriptionFile: 'curate',
-        factory: () => createCurateTool(),
+        factory: ({ environmentContext }) => createCurateTool(environmentContext?.workingDirectory),
         markers: [ToolMarker.ContextBuilding, ToolMarker.Modification],
         outputGuidance: 'curate',
         requiredServices: [], // Uses DirectoryManager and MarkdownWriter for file operations
     },
+    [ToolName.EXPAND_KNOWLEDGE]: {
+        descriptionFile: 'expand_knowledge',
+        factory: ({ environmentContext }) => createExpandKnowledgeTool({ baseDirectory: environmentContext?.workingDirectory }),
+        markers: [ToolMarker.Discovery],
+        requiredServices: [],
+    },
     [ToolName.GLOB_FILES]: {
         descriptionFile: 'glob_files',
         factory: (services) => createGlobFilesTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
@@ -87,6 +110,15 @@ export const TOOL_REGISTRY = {
         markers: [ToolMarker.Discovery],
         requiredServices: ['fileSystemService'],
     },
+    [ToolName.LLM_MAP]: {
+        factory({ contentGenerator, environmentContext, logger, maxContextTokens, tokenizer }) {
+            const generator = getRequiredService(contentGenerator, 'contentGenerator');
+            const workingDirectory = environmentContext?.workingDirectory ?? process.cwd();
+            return createLlmMapTool(generator, workingDirectory, { logger, maxContextTokens, tokenizer });
+        },
+        markers: [ToolMarker.Execution],
+        requiredServices: ['contentGenerator'],
+    },
     [ToolName.READ_FILE]: {
         descriptionFile: 'read_file',
         factory: (services) => createReadFileTool(getRequiredService(services.fileSystemService, 'fileSystemService')),

package/dist/agent/infra/transport/transport-event-bridge.d.ts

@@ -0,0 +1,42 @@
+/**
+ * TransportEventBridge - Forwards AgentEventBus events to ITransportClient.
+ *
+ * Bridges the agent's internal event system with the transport layer,
+ * allowing agent child processes to stream LLM events directly to the
+ * daemon's transport server via Socket.IO.
+ *
+ * Per-task event forwarding:
+ * - setupForTask(taskId) registers listeners filtered by taskId
+ * - cleanup() returned by setupForTask removes those listeners
+ * - dispose() removes ALL active listeners across all tasks
+ *
+ * Consumed by:
+ * - agent-process.ts: creates bridge after CipherAgent.start(), sets up
+ *   forwarding for each incoming task:execute
+ */
+import type { ITransportClient } from '@campfirein/brv-transport-client';
+import type { AgentEventBus } from '../events/event-emitter.js';
+type TransportEventBridgeOptions = {
+    eventBus: AgentEventBus;
+    transport: ITransportClient;
+};
+export declare class TransportEventBridge {
+    private readonly activeCleanups;
+    private readonly eventBus;
+    private readonly transport;
+    constructor(options: TransportEventBridgeOptions);
+    /**
+     * Remove all active event listeners across all tasks.
+     * Called during agent process shutdown.
+     */
+    dispose(): void;
+    /**
+     * Register event listeners for a specific task.
+     * Only events matching the given taskId are forwarded to transport.
+     *
+     * @param taskId - Task ID to filter events by
+     * @returns Cleanup function that removes all listeners for this task
+     */
+    setupForTask(taskId: string): () => void;
+}
+export {};

package/dist/agent/infra/transport/transport-event-bridge.js

@@ -0,0 +1,90 @@
+/**
+ * TransportEventBridge - Forwards AgentEventBus events to ITransportClient.
+ *
+ * Bridges the agent's internal event system with the transport layer,
+ * allowing agent child processes to stream LLM events directly to the
+ * daemon's transport server via Socket.IO.
+ *
+ * Per-task event forwarding:
+ * - setupForTask(taskId) registers listeners filtered by taskId
+ * - cleanup() returned by setupForTask removes those listeners
+ * - dispose() removes ALL active listeners across all tasks
+ *
+ * Consumed by:
+ * - agent-process.ts: creates bridge after CipherAgent.start(), sets up
+ *   forwarding for each incoming task:execute
+ */
+/**
+ * LLM events forwarded from agent to transport server.
+ * Must match TransportLlmEventList in core/domain/transport/schemas.ts.
+ */
+const FORWARDED_EVENT_NAMES = [
+    'llmservice:thinking',
+    'llmservice:chunk',
+    'llmservice:response',
+    'llmservice:toolCall',
+    'llmservice:toolResult',
+    'llmservice:error',
+    'llmservice:unsupportedInput',
+];
+export class TransportEventBridge {
+    activeCleanups = new Map();
+    eventBus;
+    transport;
+    constructor(options) {
+        this.eventBus = options.eventBus;
+        this.transport = options.transport;
+    }
+    /**
+     * Remove all active event listeners across all tasks.
+     * Called during agent process shutdown.
+     */
+    dispose() {
+        for (const cleanup of this.activeCleanups.values()) {
+            cleanup();
+        }
+        this.activeCleanups.clear();
+    }
+    /**
+     * Register event listeners for a specific task.
+     * Only events matching the given taskId are forwarded to transport.
+     *
+     * @param taskId - Task ID to filter events by
+     * @returns Cleanup function that removes all listeners for this task
+     */
+    setupForTask(taskId) {
+        const handlers = [];
+        for (const eventName of FORWARDED_EVENT_NAMES) {
+            const handler = (payload) => {
+                if (!isPayloadForTask(payload, taskId))
+                    return;
+                this.transport.request(eventName, payload);
+            };
+            // Use the untyped overload of on() (accepts string event name)
+            // to avoid type narrowing issues when iterating over event names.
+            const name = eventName;
+            this.eventBus.on(name, handler);
+            handlers.push({ event: name, handler });
+        }
+        const cleanup = () => {
+            for (const { event, handler } of handlers) {
+                this.eventBus.off(event, handler);
+            }
+            handlers.length = 0;
+            this.activeCleanups.delete(taskId);
+        };
+        this.activeCleanups.set(taskId, cleanup);
+        return cleanup;
+    }
+}
+/**
+ * Type guard: checks if payload is an object with a matching taskId.
+ * All forwardable LLM events include taskId?: string in their payload.
+ */
+function isPayloadForTask(payload, taskId) {
+    if (typeof payload !== 'object' || payload === null)
+        return false;
+    if (!('taskId' in payload))
+        return false;
+    return payload.taskId === taskId;
+}

package/dist/agent/infra/validation/workspace-validator.d.ts

@@ -9,9 +9,9 @@ export declare class WorkspaceNotInitializedError extends Error {
 /**
  * Validates that the ByteRover workspace is properly initialized.
  *
- * Checks for the existence of:
- * - `.brv` directory (created by `brv init`)
- * - `.brv/blobs` directory (for blob storage)
+ * Checks for the existence of the `.brv` directory (auto-created on first command),
+ * which contains config.json and context-tree/.
+ * Blob/key storage resides at XDG paths and is not validated here.
  *
  * @param workingDirectory - The working directory to check (defaults to process.cwd())
  * @throws WorkspaceNotInitializedError if workspace is not initialized

package/dist/agent/infra/validation/workspace-validator.js

@@ -15,9 +15,9 @@ export class WorkspaceNotInitializedError extends Error {
 /**
  * Validates that the ByteRover workspace is properly initialized.
  *
- * Checks for the existence of:
- * - `.brv` directory (created by `brv init`)
- * - `.brv/blobs` directory (for blob storage)
+ * Checks for the existence of the `.brv` directory (auto-created on first command),
+ * which contains config.json and context-tree/.
+ * Blob/key storage resides at XDG paths and is not validated here.
  *
  * @param workingDirectory - The working directory to check (defaults to process.cwd())
  * @throws WorkspaceNotInitializedError if workspace is not initialized
@@ -25,13 +25,8 @@ export class WorkspaceNotInitializedError extends Error {
 export function validateWorkspaceInitialized(workingDirectory) {
     const cwd = workingDirectory ?? process.cwd();
     const brvDir = join(cwd, '.brv');
-    const blobsDir = join(cwd, '.brv', 'blobs');
     // Check if .brv directory exists
     if (!existsSync(brvDir)) {
         throw new WorkspaceNotInitializedError('Workspace not initialized', brvDir);
     }
-    // Check if .brv/blobs directory exists
-    if (!existsSync(blobsDir)) {
-        throw new WorkspaceNotInitializedError('Blob storage directory not found', blobsDir);
-    }
 }

package/dist/agent/resources/prompts/curate-detail-preservation.yml

@@ -15,7 +15,7 @@ prompt: |
   - NEVER skip a diagram because "it's too complex" - store it verbatim
 
   **Tables (MUST PRESERVE):**
-  - Markdown tables - preserve the full table in narrative.structure or narrative.features
+  - Markdown tables - preserve the full table in narrative.structure or narrative.highlights
   - Include column headers and ALL rows - do not summarize table content
   - If a table has 20 rows, store all 20 rows
 
@@ -57,6 +57,34 @@ prompt: |
     }
     ```
 
+  ## Non-Code Content Preservation
+
+  **Meeting Notes and Decisions (MUST PRESERVE):**
+  - Decision text with full rationale - store in narrative.rules or narrative.highlights
+  - Action items with assignees and deadlines - store in narrative.examples
+  - Voting results and priority rankings - preserve exact numbers
+  - Status updates and blockers - store in narrative.dependencies
+
+  **Process Documentation:**
+  - Workflow steps with all conditions - store in rawConcept.flow and narrative.rules
+  - Metrics and KPIs with exact values - store in narrative.highlights
+  - Timeline and milestone information - store in narrative.structure
+
+  ## Factual Statement Preservation
+
+  **Facts (MUST EXTRACT in content.facts array):**
+  - Personal information stated by the user (e.g., "My name is Andy") - store each as a separate fact with category: "personal"
+  - Project configuration values, versions, ports, URLs - preserve exact values with category: "project"
+  - Team conventions and processes - store with category: "convention"
+  - Preferences and opinions expressed as directives - store with category: "preference"
+  - Team structure and roles - store with category: "team"
+  - Environment and infrastructure details - store with category: "environment"
+  - Use `subject` field for the key concept in snake_case (e.g., "user_name", "database_version")
+  - Use `value` field for the extracted value (e.g., "Andy", "PostgreSQL 15")
+  - Do NOT infer facts that were not explicitly stated
+  - Do NOT merge multiple facts into one compound statement
+  - ALWAYS preserve the exact wording of the factual claim in `statement`
+
   ## General Detail Preservation
 
   **Completeness over conciseness:**