byterover-cli 1.0.4 → 1.0.5

package/dist/infra/cipher/session/session-metadata-store.js

@@ -0,0 +1,406 @@
+/**
+ * SessionMetadataStore - Manages session metadata persistence.
+ *
+ * Stores session metadata in .brv/sessions/ directory:
+ * - active.json: Current active session pointer
+ * - session-*.json: Individual session metadata files
+ *
+ * Design adapted from gemini-cli's ChatRecordingService pattern.
+ */
+import { randomUUID } from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { ACTIVE_SESSION_FILE, ActiveSessionPointerSchema, cleanMessageForTitle, generateSessionFilename, parseSessionFilename, SESSION_FILE_PREFIX, SessionMetadataSchema, SESSIONS_DIR, } from '../../../core/domain/cipher/session/session-metadata.js';
+/**
+ * Check if a process with given PID is running.
+ *
+ * @param pid - Process ID to check
+ * @returns True if process is running
+ */
+function isProcessRunning(pid) {
+    try {
+        // Sending signal 0 checks if process exists without actually sending a signal
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Session ID prefix used in the application.
+ */
+const SESSION_ID_PREFIX = 'agent-session-';
+/**
+ * Unique token for this process instance.
+ * Used to detect PID reuse: different process instance = different token,
+ * even if the OS assigned the same PID after the original process crashed.
+ */
+const PROCESS_TOKEN = randomUUID();
+/**
+ * Extract the UUID portion from a session ID.
+ *
+ * Session IDs have format: "agent-session-<UUID>" or just "<UUID>"
+ * This function handles both formats for backward compatibility.
+ *
+ * @param sessionId - The full session ID
+ * @returns The UUID portion without the prefix
+ */
+function extractUuidFromSessionId(sessionId) {
+    return sessionId.startsWith(SESSION_ID_PREFIX)
+        ? sessionId.slice(SESSION_ID_PREFIX.length)
+        : sessionId;
+}
+/**
+ * SessionMetadataStore implementation.
+ *
+ * Manages session metadata stored in .brv/sessions/ directory.
+ */
+export class SessionMetadataStore {
+    activeSessionPath;
+    sessionsDir;
+    workingDirectory;
+    /**
+     * Create a new SessionMetadataStore.
+     *
+     * @param workingDirectory - Project working directory (defaults to process.cwd())
+     */
+    constructor(workingDirectory) {
+        this.workingDirectory = workingDirectory ?? process.cwd();
+        this.sessionsDir = join(this.workingDirectory, '.brv', SESSIONS_DIR);
+        this.activeSessionPath = join(this.sessionsDir, ACTIVE_SESSION_FILE);
+    }
+    // ============================================================================
+    // Active Session Management
+    // ============================================================================
+    async cleanupSessions(config) {
+        const result = {
+            corruptedRemoved: 0,
+            deletedByAge: 0,
+            deletedByCount: 0,
+            remaining: 0,
+        };
+        try {
+            const files = await fs.readdir(this.sessionsDir);
+            const sessionFiles = files.filter((f) => f.startsWith(SESSION_FILE_PREFIX) && f.endsWith('.json'));
+            // IMPORTANT: Capture the active session ID as an immutable primitive BEFORE
+            // any file mutations. This prevents race conditions where concurrent cleanup
+            // operations could modify the active session pointer while we're iterating.
+            // Using a primitive string (not object reference) ensures we have a stable
+            // value to check against throughout the entire cleanup operation.
+            const active = await this.getActiveSession();
+            const activeSessionId = active?.sessionId;
+            const validSessions = [];
+            // First pass: identify corrupted files and valid sessions
+            for (const file of sessionFiles) {
+                const filePath = join(this.sessionsDir, file);
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    const content = await fs.readFile(filePath, 'utf8');
+                    const data = JSON.parse(content);
+                    const parseResult = SessionMetadataSchema.safeParse(data);
+                    if (!parseResult.success) {
+                        // Corrupted file - delete it
+                        // eslint-disable-next-line no-await-in-loop
+                        await fs.unlink(filePath);
+                        result.corruptedRemoved++;
+                        continue;
+                    }
+                    validSessions.push({ file, metadata: parseResult.data });
+                }
+                catch {
+                    // Can't read/parse - delete it
+                    try {
+                        // eslint-disable-next-line no-await-in-loop
+                        await fs.unlink(filePath);
+                        result.corruptedRemoved++;
+                    }
+                    catch {
+                        // Ignore delete errors
+                    }
+                }
+            }
+            // Sort by lastUpdated (newest first)
+            validSessions.sort((a, b) => new Date(b.metadata.lastUpdated).getTime() - new Date(a.metadata.lastUpdated).getTime());
+            const now = Date.now();
+            const maxAgeMs = config.maxAgeDays * 24 * 60 * 60 * 1000;
+            // Second pass: apply retention policies
+            for (const [i, { file, metadata }] of validSessions.entries()) {
+                // Never delete the current active session (uses captured primitive ID)
+                if (activeSessionId && metadata.sessionId === activeSessionId) {
+                    continue;
+                }
+                const age = now - new Date(metadata.lastUpdated).getTime();
+                const shouldDeleteByAge = age > maxAgeMs;
+                const shouldDeleteByCount = i >= config.maxCount;
+                const shouldDelete = shouldDeleteByAge || shouldDeleteByCount;
+                if (!shouldDelete) {
+                    continue;
+                }
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    await fs.unlink(join(this.sessionsDir, file));
+                    if (shouldDeleteByAge) {
+                        result.deletedByAge++;
+                    }
+                    else {
+                        result.deletedByCount++;
+                    }
+                }
+                catch {
+                    // Ignore delete errors
+                }
+            }
+            // Count remaining
+            const remainingFiles = await fs.readdir(this.sessionsDir);
+            result.remaining = remainingFiles.filter((f) => f.startsWith(SESSION_FILE_PREFIX) && f.endsWith('.json')).length;
+            return result;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return result;
+            }
+            throw error;
+        }
+    }
+    async clearActiveSession() {
+        try {
+            await fs.unlink(this.activeSessionPath);
+        }
+        catch (error) {
+            // Ignore if file doesn't exist
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Create a new session metadata object.
+     *
+     * @param sessionId - Session ID
+     * @returns New session metadata with defaults
+     */
+    createSessionMetadata(sessionId) {
+        const now = new Date().toISOString();
+        return {
+            createdAt: now,
+            lastUpdated: now,
+            messageCount: 0,
+            sessionId,
+            status: 'active',
+            workingDirectory: this.workingDirectory,
+        };
+    }
+    async deleteSession(sessionId) {
+        try {
+            const files = await fs.readdir(this.sessionsDir);
+            for (const file of files) {
+                if (!file.startsWith(SESSION_FILE_PREFIX) || !file.endsWith('.json')) {
+                    continue;
+                }
+                const parsed = parseSessionFilename(file);
+                // Extract UUID from sessionId (removes "agent-session-" prefix if present)
+                // then compare with the filename's uuid prefix
+                const uuid = extractUuidFromSessionId(sessionId);
+                if (parsed && uuid.startsWith(parsed.uuidPrefix)) {
+                    // eslint-disable-next-line no-await-in-loop
+                    await fs.unlink(join(this.sessionsDir, file));
+                    return true;
+                }
+                // Also check by reading the file to match full sessionId
+                try {
+                    const filePath = join(this.sessionsDir, file);
+                    // eslint-disable-next-line no-await-in-loop
+                    const content = await fs.readFile(filePath, 'utf8');
+                    const data = JSON.parse(content);
+                    if (data.sessionId === sessionId) {
+                        // eslint-disable-next-line no-await-in-loop
+                        await fs.unlink(filePath);
+                        return true;
+                    }
+                }
+                catch {
+                    // Continue to next file
+                }
+            }
+            return false;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return false;
+            }
+            throw error;
+        }
+    }
+    async getActiveSession() {
+        try {
+            const content = await fs.readFile(this.activeSessionPath, 'utf8');
+            const data = JSON.parse(content);
+            const result = ActiveSessionPointerSchema.safeParse(data);
+            if (!result.success) {
+                // Invalid format - treat as no active session
+                return null;
+            }
+            return result.data;
+        }
+        catch (error) {
+            // File doesn't exist or can't be read
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async getSession(sessionId) {
+        const sessions = await this.listSessions();
+        return sessions.find((s) => s.sessionId === sessionId) ?? null;
+    }
+    async isActiveSessionStale() {
+        const active = await this.getActiveSession();
+        if (!active) {
+            return false;
+        }
+        // If the process is not running, the session is definitely stale
+        if (!isProcessRunning(active.pid)) {
+            return true;
+        }
+        // If process is running but token is missing or doesn't match,
+        // it's either an old session file or a different process with the same PID.
+        // Both cases indicate a stale session.
+        if (!active.processToken || active.processToken !== PROCESS_TOKEN) {
+            return true;
+        }
+        return false;
+    }
+    async isSessionForCurrentProject(sessionId) {
+        const session = await this.getSession(sessionId);
+        if (!session) {
+            return false;
+        }
+        return session.workingDirectory === this.workingDirectory;
+    }
+    async listSessions() {
+        try {
+            await this.ensureSessionsDir();
+            const files = await fs.readdir(this.sessionsDir);
+            const sessionFiles = files.filter((f) => f.startsWith(SESSION_FILE_PREFIX) && f.endsWith('.json'));
+            const active = await this.getActiveSession();
+            const sessions = [];
+            for (const file of sessionFiles) {
+                try {
+                    const filePath = join(this.sessionsDir, file);
+                    // eslint-disable-next-line no-await-in-loop
+                    const content = await fs.readFile(filePath, 'utf8');
+                    const data = JSON.parse(content);
+                    const result = SessionMetadataSchema.safeParse(data);
+                    if (!result.success) {
+                        // Skip corrupted files
+                        continue;
+                    }
+                    const metadata = result.data;
+                    const isCurrentSession = active?.sessionId === metadata.sessionId;
+                    sessions.push({
+                        ...metadata,
+                        file: file.replace('.json', ''),
+                        fileName: file,
+                        firstUserMessage: metadata.title,
+                        index: 0, // Will be set after sorting
+                        isCurrentSession,
+                    });
+                }
+                catch {
+                    // Skip files that can't be read or parsed
+                    continue;
+                }
+            }
+            // Sort by lastUpdated (newest first)
+            sessions.sort((a, b) => new Date(b.lastUpdated).getTime() - new Date(a.lastUpdated).getTime());
+            // Set 1-based indexes
+            for (const [index, session] of sessions.entries()) {
+                session.index = index + 1;
+            }
+            return sessions;
+        }
+        catch (error) {
+            // Directory doesn't exist
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
+        }
+    }
+    // ============================================================================
+    // Session Lifecycle
+    // ============================================================================
+    async markSessionEnded(sessionId) {
+        const session = await this.getSession(sessionId);
+        if (session) {
+            session.status = 'ended';
+            session.lastUpdated = new Date().toISOString();
+            await this.saveSession(session);
+        }
+    }
+    async markSessionInterrupted(sessionId) {
+        const session = await this.getSession(sessionId);
+        if (session) {
+            session.status = 'interrupted';
+            session.lastUpdated = new Date().toISOString();
+            await this.saveSession(session);
+        }
+    }
+    async saveSession(metadata) {
+        await this.ensureSessionsDir();
+        // Find existing file for this session or create new
+        let filename;
+        try {
+            const files = await fs.readdir(this.sessionsDir);
+            const existingFile = files.find((f) => {
+                if (!f.startsWith(SESSION_FILE_PREFIX) || !f.endsWith('.json')) {
+                    return false;
+                }
+                const parsed = parseSessionFilename(f);
+                // Extract UUID from sessionId and compare with filename's uuid prefix
+                const uuid = extractUuidFromSessionId(metadata.sessionId);
+                return parsed && uuid.startsWith(parsed.uuidPrefix);
+            });
+            filename = existingFile ?? generateSessionFilename(metadata.sessionId);
+        }
+        catch {
+            filename = generateSessionFilename(metadata.sessionId);
+        }
+        const filePath = join(this.sessionsDir, filename);
+        await fs.writeFile(filePath, JSON.stringify(metadata, null, 2), 'utf8');
+    }
+    async setActiveSession(sessionId) {
+        await this.ensureSessionsDir();
+        const pointer = {
+            activatedAt: new Date().toISOString(),
+            pid: process.pid,
+            processToken: PROCESS_TOKEN,
+            sessionId,
+        };
+        await fs.writeFile(this.activeSessionPath, JSON.stringify(pointer, null, 2), 'utf8');
+    }
+    async setSessionTitle(sessionId, title) {
+        const session = await this.getSession(sessionId);
+        if (session && !session.title) {
+            session.title = cleanMessageForTitle(title);
+            session.lastUpdated = new Date().toISOString();
+            await this.saveSession(session);
+        }
+    }
+    async updateSessionActivity(sessionId, messageCount) {
+        const session = await this.getSession(sessionId);
+        if (session) {
+            session.lastUpdated = new Date().toISOString();
+            session.messageCount = messageCount;
+            await this.saveSession(session);
+        }
+    }
+    /**
+     * Ensure the sessions directory exists.
+     */
+    async ensureSessionsDir() {
+        await fs.mkdir(this.sessionsDir, { recursive: true });
+    }
+}

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

@@ -1,4 +1,3 @@
-import * as fs from 'node:fs/promises';
 import { join } from 'node:path';
 import { z } from 'zod';
 import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
@@ -10,14 +9,43 @@ import { toSnakeCase } from '../../../../utils/file-helpers.js';
  * Inspired by ACE Curator patterns.
  */
 const OperationType = z.enum(['ADD', 'UPDATE', 'MERGE', 'DELETE']);
+/**
+ * Raw Concept schema for structured metadata and technical footprint.
+ */
+const RawConceptSchema = z.object({
+    changes: z.array(z.string()).optional().describe('What changes in the codebase are induced by this concept'),
+    files: z.array(z.string()).optional().describe('Which files are related to this concept'),
+    flow: z.string().optional().describe('What is the flow included in this concept'),
+    task: z.string().optional().describe('What is the task related to this concept'),
+    timestamp: z
+        .string()
+        .optional()
+        .describe('When the concept was created or modified (ISO 8601 format, e.g., 2025-03-18)'),
+});
+/**
+ * Narrative schema for descriptive and structural context.
+ */
+const NarrativeSchema = z.object({
+    dependencies: z
+        .string()
+        .optional()
+        .describe('Dependency management information (e.g., "Singleton, init when service starts, hard dependency in smoke test")'),
+    features: z
+        .string()
+        .optional()
+        .describe('Feature documentation for this concept (e.g., "User permission can be stale for up to 300 seconds due to Redis cache")'),
+    structure: z.string().optional().describe('Code structure documentation (e.g., "clients/redis_client.go")'),
+});
 /**
  * Content structure for ADD and UPDATE operations.
  */
 const ContentSchema = z.object({
+    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
         .array(z.string())
         .optional()
-        .describe('Related topics using domain/topic or domain/topic/subtopic notation'),
+        .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'),
 });
 /**
@@ -27,9 +55,12 @@ const OperationSchema = z.object({
     content: ContentSchema.optional().describe('Content for ADD/UPDATE operations'),
     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 or domain/topic/subtopic'),
+    path: z.string().describe('Path: domain/topic/title.md or domain/topic/subtopic/title.md'),
     reason: z.string().describe('Reasoning for this operation'),
-    title: z.string().optional().describe('Title for the context file (saved as {title}.md in snake_case). Required for ADD/UPDATE/MERGE, optional for DELETE'),
+    title: z
+        .string()
+        .optional()
+        .describe('Title for the context file (saved as {title}.md in snake_case). Required for ADD/UPDATE/MERGE, optional for DELETE'),
     type: OperationType.describe('Operation type: ADD, UPDATE, MERGE, or DELETE'),
 });
 /**
@@ -53,33 +84,17 @@ function parsePath(path) {
         topic: parts[1],
     };
 }
-/**
- * Get existing domain names from the context tree.
- * Returns domain folder names that exist in the context tree.
- */
-async function getExistingDomains(basePath) {
-    try {
-        const entries = await fs.readdir(basePath, { withFileTypes: true });
-        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-    }
-    catch {
-        // Directory doesn't exist yet
-        return [];
-    }
-}
 /**
  * Validate domain name format.
  * Dynamic domains are allowed - no predefined list or limits.
  * The agent is responsible for creating semantically meaningful domains.
  */
-async function validateDomain(basePath, domainName) {
+function validateDomain(domainName) {
     const normalizedDomain = toSnakeCase(domainName);
-    const existingDomains = await getExistingDomains(basePath);
     // Validate domain name format (must be non-empty and valid for filesystem)
     if (!normalizedDomain || normalizedDomain.length === 0) {
         return {
             allowed: false,
-            existingDomains,
             reason: 'Domain name cannot be empty.',
         };
     }
@@ -87,12 +102,11 @@ async function validateDomain(basePath, domainName) {
     if (!/^[\w-]+$/.test(normalizedDomain)) {
         return {
             allowed: false,
-            existingDomains,
             reason: `Domain name "${normalizedDomain}" contains invalid characters. Use only letters, numbers, underscores, and hyphens.`,
         };
     }
     // All valid domain names are allowed - dynamic domain creation enabled
-    return { allowed: true, existingDomains };
+    return { allowed: true };
 }
 /**
  * Build the full filesystem path from base path and knowledge path.
@@ -142,7 +156,7 @@ async function executeAdd(basePath, operation) {
             };
         }
         // Validate domain before creating
-        const domainValidation = await validateDomain(basePath, parsed.domain);
+        const domainValidation = validateDomain(parsed.domain);
         if (!domainValidation.allowed) {
             return {
                 message: domainValidation.reason,
@@ -159,8 +173,10 @@ async function executeAdd(basePath, operation) {
         // Note: writeFileAtomic creates parent directories as needed, avoiding empty folder creation
         const contextContent = MarkdownWriter.generateContext({
             name: title,
+            narrative: content.narrative,
+            rawConcept: content.rawConcept,
             relations: content.relations,
-            snippets: content.snippets || [],
+            snippets: content.snippets ?? [],
         });
         const filename = `${toSnakeCase(title)}.md`;
         const contextPath = join(finalPath, filename);
@@ -220,8 +236,10 @@ async function executeUpdate(basePath, operation) {
         // Generate and write updated content (full replacement)
         const contextContent = MarkdownWriter.generateContext({
             name: title,
+            narrative: content.narrative,
+            rawConcept: content.rawConcept,
             relations: content.relations,
-            snippets: content.snippets || [],
+            snippets: content.snippets ?? [],
         });
         await DirectoryManager.writeFileAtomic(contextPath, contextContent);
         return {
@@ -381,7 +399,27 @@ async function executeDelete(basePath, operation) {
  * Execute curate operations on knowledge topics.
  */
 async function executeCurate(input, _context) {
-    const { basePath, operations } = input;
+    const parseResult = CurateInputSchema.safeParse(input);
+    if (!parseResult.success) {
+        return {
+            applied: [
+                {
+                    message: `Invalid input: ${parseResult.error.message}`,
+                    path: '',
+                    status: 'failed',
+                    type: 'ADD',
+                },
+            ],
+            summary: {
+                added: 0,
+                deleted: 0,
+                failed: 1,
+                merged: 0,
+                updated: 0,
+            },
+        };
+    }
+    const { basePath, operations } = parseResult.data;
     const applied = [];
     const summary = {
         added: 0,
@@ -420,8 +458,10 @@ async function executeCurate(input, _context) {
                 break;
             }
             default: {
+                // Exhaustive type check - TypeScript will error if any case is missed
+                const exhaustiveCheck = operation.type;
                 result = {
-                    message: `Unknown operation type: ${operation.type}`,
+                    message: `Unknown operation type: ${exhaustiveCheck}`,
                     path: operation.path,
                     status: 'failed',
                     type: operation.type,
@@ -446,29 +486,65 @@ async function executeCurate(input, _context) {
  */
 export function createCurateTool() {
     return {
-        description: `Curate knowledge topics with atomic operations. This tool manages the knowledge structure using four operation types:
+        description: `Curate knowledge topics with atomic operations. This tool manages the knowledge structure using four operation types and supports a two-part context model: Raw Concept + Narrative.
+
+**Content Structure (Two-Part Model):**
+- **rawConcept**: Captures essential metadata and technical footprint
+  - task: What is the task related to this concept
+  - changes: Array of changes induced in the codebase
+  - files: Array of related files
+  - flow: The execution flow of this concept
+  - timestamp: When created/modified (ISO 8601 format)
+- **narrative**: Captures descriptive and structural context
+  - structure: Code structure documentation
+  - dependencies: Dependency management information
+  - features: Feature documentation
+- **snippets**: Code/text snippets (legacy support)
+- **relations**: Related topics using @domain/topic notation
 
 **Operations:**
 1. **ADD** - Create new titled context file in domain/topic/subtopic
    - Requires: path, title, content (snippets and/or relations), reason
-   - Example: { type: "ADD", path: "code_style/error_handling", title: "Best Practices", content: { snippets: ["..."], relations: ["logging/basics"] }, reason: "New pattern" }
-   - Creates: code_style/error_handling/best_practices.md
+   - 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",
+       content: {
+         rawConcept: {
+           task: "Introduce Redis cache for getUserPermissions(userId)",
+           changes: ["Cached result using remote Redis", "Redis client: singleton"],
+           files: ["services/permission_service.go", "clients/redis_client.go"],
+           flow: "getUserPermissions -> check Redis -> on miss query DB -> store result -> return",
+           timestamp: "2025-03-18"
+         },
+         narrative: {
+           structure: "# Redis client\\n- clients/redis_client.go",
+           dependencies: "# Redis client\\n- Singleton, init when service starts",
+           features: "# Authorization\\n- User permission can be stale for up to 300 seconds"
+         },
+         relations: ["structure/api-endpoints/validation.md", "structure/api-endpoints/error-handling/retry-logic.md"]
+       },
+       reason: "New caching pattern"
+     }
+   - Creates: structure/caching/redis_user_permissions.md
 
 2. **UPDATE** - Modify existing titled context file (full replacement)
    - Requires: path, title, content, reason
-   - Example: { type: "UPDATE", path: "code_style/error_handling", title: "Best Practices", content: { snippets: ["Updated"] }, reason: "Improved" }
+   - Relations must be in the format of "domain/topic/title.md" or "domain/topic/subtopic/title.md"
+   - Supports same content structure as ADD
 
 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" }
+   - Raw concepts and narratives are intelligently merged
 
 4. **DELETE** - Remove specific file or entire folder
    - Requires: path, title (optional), reason
    - With title: deletes specific file; without title: deletes entire folder
-   - Example (file): { type: "DELETE", path: "code_style/deprecated", title: "Old Guide", reason: "No longer relevant" }
-   - Example (folder): { type: "DELETE", path: "code_style/deprecated", title: "", reason: "Removing topic" }
 
-**Path format:** domain/topic or domain/topic/subtopic (uses snake_case automatically)
+**Path format:** domain/topic/title.md or domain/topic/subtopic/title.md (uses snake_case automatically)
 **File naming:** Titles are converted to snake_case (e.g., "Best Practices" -> "best_practices.md")
 
 **Dynamic Domain Creation:**
@@ -485,6 +561,8 @@ export function createCurateTool() {
 - Avoid overly specific names that only fit one topic
 - Keep domain count reasonable by consolidating related concepts
 
+**Backward Compatibility:** Existing context entries using only snippets and relations continue to work.
+
 **Output:** Returns applied operations with status (success/failed), filePath (for created/modified files), and a summary of counts.`,
         execute: executeCurate,
         id: ToolName.CURATE,

package/dist/infra/cipher/tools/implementations/task-tool.js

@@ -95,6 +95,7 @@ export function createTaskTool(dependencies) {
     const registry = getAgentRegistry();
     return {
         description: buildTaskToolDescription(registry),
+        // eslint-disable-next-line complexity -- Inherent complexity: validates agent, manages sessions, handles errors
         async execute(input, context) {
             const params = input;
             const { contextTreeOnly, description, prompt, sessionId, subagentType } = params;