tlc-claude-code 1.8.4 → 2.0.1

package/server/lib/memory-hooks.js

@@ -121,7 +121,108 @@ function createMemoryHooks(projectRoot) {
   };
 }
 
+/**
+ * Default number of exchanges before auto-triggering capture processing
+ * @type {number}
+ */
+const DEFAULT_CAPTURE_THRESHOLD = 5;
+
+/**
+ * Create capture hooks for rolling buffer conversation capture.
+ *
+ * Accumulates exchanges in a rolling buffer and processes them through
+ * chunking, rich capture writing, and vector indexing when a threshold
+ * is reached, a TLC command fires, or flush() is called explicitly.
+ *
+ * Processing is non-blocking (fire-and-forget via Promise microtask).
+ *
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} deps - Injected dependencies
+ * @param {Object} deps.chunker - Chunker with chunkConversation(exchanges)
+ * @param {Object} deps.richCapture - Writer with writeConversationChunk(projectRoot, chunk)
+ * @param {Object} deps.vectorIndexer - Indexer with indexChunk(chunk)
+ * @returns {{ onExchange: Function, getBufferSize: Function, onTlcCommand: Function, flush: Function, processBuffer: Function }}
+ */
+function createCaptureHooks(projectRoot, deps) {
+  const { chunker, richCapture, vectorIndexer } = deps;
+  let buffer = [];
+  let processing = false;
+
+  /**
+   * Process the current buffer: chunk, write, index, then clear.
+   * Runs asynchronously in a microtask so it never blocks the caller.
+   * The buffer is cleared after processing completes, not before.
+   */
+  function processBuffer() {
+    if (buffer.length === 0 || processing) return;
+
+    processing = true;
+
+    Promise.resolve().then(async () => {
+      try {
+        const exchanges = buffer.slice();
+        const chunks = chunker.chunkConversation(exchanges);
+        for (const chunk of chunks) {
+          await richCapture.writeConversationChunk(projectRoot, chunk);
+          await vectorIndexer.indexChunk(chunk);
+        }
+        buffer = [];
+      } catch (_err) {
+        // Error resilience: capture failures must not propagate.
+        // Hooks remain functional after errors.
+        buffer = [];
+      } finally {
+        processing = false;
+      }
+    });
+  }
+
+  /**
+   * Add an exchange to the rolling buffer.
+   * Automatically triggers processing when the buffer reaches the threshold.
+   * @param {{ user: string, assistant: string, timestamp: number }} exchange
+   */
+  function onExchange(exchange) {
+    buffer.push(exchange);
+
+    if (buffer.length >= DEFAULT_CAPTURE_THRESHOLD) {
+      processBuffer();
+    }
+  }
+
+  /**
+   * @returns {number} Current number of exchanges in the buffer
+   */
+  function getBufferSize() {
+    return buffer.length;
+  }
+
+  /**
+   * A TLC command was invoked -- trigger immediate capture of buffered exchanges.
+   * @param {string} _command - The TLC command name (e.g. 'build', 'plan')
+   */
+  function onTlcCommand(_command) {
+    processBuffer();
+  }
+
+  /**
+   * Force-flush the buffer regardless of threshold.
+   */
+  function flush() {
+    processBuffer();
+  }
+
+  return {
+    onExchange,
+    getBufferSize,
+    onTlcCommand,
+    flush,
+    processBuffer,
+  };
+}
+
 module.exports = {
   createMemoryHooks,
   MemoryHooks,
+  createCaptureHooks,
 };

package/server/lib/memory-inheritance.js

@@ -0,0 +1,179 @@
+/**
+ * Memory Inheritance Engine
+ *
+ * When loading memory for a project, also loads workspace-level memory
+ * and merges with correct priority. Project-level items override
+ * workspace-level items that share the same filename slug (topic).
+ *
+ * @module memory-inheritance
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Default relevance score for project-level memory items.
+ * @type {number}
+ */
+const PROJECT_RELEVANCE = 1.0;
+
+/**
+ * Default relevance score for workspace-level memory items.
+ * @type {number}
+ */
+const WORKSPACE_RELEVANCE = 0.5;
+
+/**
+ * Memory categories that the inheritance engine reads.
+ * @type {string[]}
+ */
+const CATEGORIES = ['decisions', 'gotchas', 'preferences', 'conversations'];
+
+/**
+ * Read all .md files from a directory, returning an array of memory items.
+ *
+ * @param {string} dir - Absolute path to a memory category directory
+ * @param {string} source - 'project' or 'workspace'
+ * @returns {Object[]} Array of { filename, text, source, topic, relevance }
+ */
+function readMemoryFiles(dir, source) {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+
+  const items = [];
+  const relevance = source === 'project' ? PROJECT_RELEVANCE : WORKSPACE_RELEVANCE;
+
+  for (const filename of entries.sort()) {
+    if (!filename.endsWith('.md')) continue;
+
+    const filepath = path.join(dir, filename);
+    try {
+      const stat = fs.statSync(filepath);
+      if (!stat.isFile()) continue;
+    } catch {
+      continue;
+    }
+
+    const text = fs.readFileSync(filepath, 'utf8');
+    const topic = filename.replace(/\.md$/, '');
+
+    items.push({
+      filename,
+      text,
+      source,
+      topic,
+      relevance,
+    });
+  }
+
+  return items;
+}
+
+/**
+ * Merge two arrays of memory items. Project items override workspace items
+ * when they share the same topic (filename slug). For categories where
+ * override semantics apply (decisions, preferences), matching topics cause
+ * the workspace item to be dropped. For union categories (gotchas,
+ * conversations), all items are included.
+ *
+ * @param {Object[]} projectItems - Items from the project memory
+ * @param {Object[]} workspaceItems - Items from the workspace memory
+ * @param {string} category - The category name
+ * @returns {Object[]} Merged items with project taking priority
+ */
+function mergeItems(projectItems, workspaceItems, category) {
+  const overrideCategories = ['decisions', 'preferences'];
+
+  if (!overrideCategories.includes(category)) {
+    // Union: include all items from both sources
+    return [...projectItems, ...workspaceItems];
+  }
+
+  // Override: project items replace workspace items with the same topic
+  const projectTopics = new Set(projectItems.map((item) => item.topic));
+  const filtered = workspaceItems.filter(
+    (item) => !projectTopics.has(item.topic)
+  );
+
+  return [...projectItems, ...filtered];
+}
+
+/**
+ * Create a memory inheritance engine instance.
+ *
+ * @param {Object} options
+ * @param {Object} options.workspaceDetector - A workspace detector instance
+ *   with a detectWorkspace(projectDir) method.
+ * @returns {{ loadInheritedMemory: Function, getInheritedRoots: Function }}
+ */
+export function createMemoryInheritance({ workspaceDetector }) {
+  /**
+   * Load memory from a project directory, inheriting workspace-level memory
+   * when the project is inside a workspace.
+   *
+   * @param {string} projectDir - Absolute path to the project directory
+   * @returns {Promise<Object>} Merged memory with decisions, gotchas,
+   *   preferences, and conversations arrays
+   */
+  async function loadInheritedMemory(projectDir) {
+    const resolved = path.resolve(projectDir);
+    const wsResult = workspaceDetector.detectWorkspace(resolved);
+
+    const projectMemoryRoot = path.join(resolved, 'memory');
+    const workspaceMemoryRoot = wsResult.isInWorkspace
+      ? path.join(wsResult.workspaceRoot, 'memory')
+      : null;
+
+    const result = {
+      decisions: [],
+      gotchas: [],
+      preferences: [],
+      conversations: [],
+    };
+
+    for (const category of CATEGORIES) {
+      const projectDir_ = path.join(projectMemoryRoot, category);
+      const projectItems = readMemoryFiles(projectDir_, 'project');
+
+      let workspaceItems = [];
+      if (workspaceMemoryRoot) {
+        const wsDir = path.join(workspaceMemoryRoot, category);
+        workspaceItems = readMemoryFiles(wsDir, 'workspace');
+      }
+
+      result[category] = mergeItems(projectItems, workspaceItems, category);
+    }
+
+    return result;
+  }
+
+  /**
+   * Get the list of memory root directories that would be consulted
+   * for the given project.
+   *
+   * @param {string} projectDir - Absolute path to the project directory
+   * @returns {string[]} Array of memory root paths (project first, then workspace)
+   */
+  function getInheritedRoots(projectDir) {
+    const resolved = path.resolve(projectDir);
+    const wsResult = workspaceDetector.detectWorkspace(resolved);
+
+    const roots = [path.join(resolved, 'memory')];
+
+    if (wsResult.isInWorkspace) {
+      roots.push(path.join(wsResult.workspaceRoot, 'memory'));
+    }
+
+    return roots;
+  }
+
+  return { loadInheritedMemory, getInheritedRoots };
+}

package/server/lib/memory-inheritance.test.js

@@ -0,0 +1,360 @@
+/**
+ * Memory Inheritance Engine Tests
+ *
+ * Tests for loading and merging memory from both project-level and
+ * workspace-level sources with correct priority.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createMemoryInheritance } from './memory-inheritance.js';
+
+/** Create a unique temp directory for each test */
+function makeTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'mem-inherit-'));
+}
+
+/** Recursively remove a directory */
+function rmDir(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/**
+ * Helper: create a memory directory structure with .md files.
+ * @param {string} root - Root directory to create memory in
+ * @param {Object} contents - { decisions: [{filename, text}], gotchas: [...], preferences: [...], conversations: [...] }
+ */
+function createMemoryDir(root, contents = {}) {
+  const memoryDir = path.join(root, 'memory');
+  const categories = ['decisions', 'gotchas', 'preferences', 'conversations'];
+
+  for (const cat of categories) {
+    const catDir = path.join(memoryDir, cat);
+    fs.mkdirSync(catDir, { recursive: true });
+
+    if (contents[cat]) {
+      for (const item of contents[cat]) {
+        fs.writeFileSync(
+          path.join(catDir, item.filename),
+          item.text,
+          'utf8'
+        );
+      }
+    }
+  }
+
+  return memoryDir;
+}
+
+describe('memory-inheritance', () => {
+  let tmpDir;
+  let workspaceDir;
+  let projectDir;
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir();
+    workspaceDir = path.join(tmpDir, 'workspace');
+    projectDir = path.join(workspaceDir, 'my-project');
+    fs.mkdirSync(projectDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (tmpDir) rmDir(tmpDir);
+  });
+
+  /**
+   * Create a mock workspaceDetector that returns configured workspace info.
+   */
+  function mockDetector(wsRoot) {
+    return {
+      detectWorkspace: vi.fn((dir) => {
+        if (wsRoot) {
+          return {
+            isInWorkspace: true,
+            workspaceRoot: wsRoot,
+            projectPath: dir,
+            relativeProjectPath: path.relative(wsRoot, dir),
+          };
+        }
+        return {
+          isInWorkspace: false,
+          workspaceRoot: null,
+          projectPath: dir,
+          relativeProjectPath: null,
+        };
+      }),
+    };
+  }
+
+  describe('loadInheritedMemory', () => {
+    it('loads project-level decisions from memory/decisions/', async () => {
+      createMemoryDir(projectDir, {
+        decisions: [
+          { filename: 'use-postgres.md', text: '# Use Postgres\n\nWe chose Postgres for JSONB support.' },
+          { filename: 'use-rest.md', text: '# Use REST\n\nREST is simpler for our use case.' },
+        ],
+      });
+
+      const detector = mockDetector(null); // standalone
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const merged = await inheritance.loadInheritedMemory(projectDir);
+
+      expect(merged.decisions).toHaveLength(2);
+      expect(merged.decisions[0].text).toContain('Postgres');
+      expect(merged.decisions[1].text).toContain('REST');
+    });
+
+    it('loads workspace-level decisions from workspace memory/decisions/', async () => {
+      createMemoryDir(workspaceDir, {
+        decisions: [
+          { filename: 'shared-auth.md', text: '# Shared Auth\n\nAll projects use OAuth2.' },
+        ],
+      });
+      createMemoryDir(projectDir, { decisions: [] });
+
+      const detector = mockDetector(workspaceDir);
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const merged = await inheritance.loadInheritedMemory(projectDir);
+
+      expect(merged.decisions).toHaveLength(1);
+      expect(merged.decisions[0].text).toContain('OAuth2');
+      expect(merged.decisions[0].source).toBe('workspace');
+    });
+
+    it('merges decisions from both sources (union)', async () => {
+      createMemoryDir(workspaceDir, {
+        decisions: [
+          { filename: 'shared-auth.md', text: '# Shared Auth\n\nOAuth2 everywhere.' },
+        ],
+      });
+      createMemoryDir(projectDir, {
+        decisions: [
+          { filename: 'use-postgres.md', text: '# Use Postgres\n\nJSONB support.' },
+        ],
+      });
+
+      const detector = mockDetector(workspaceDir);
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const merged = await inheritance.loadInheritedMemory(projectDir);
+
+      expect(merged.decisions).toHaveLength(2);
+      const sources = merged.decisions.map((d) => d.source);
+      expect(sources).toContain('project');
+      expect(sources).toContain('workspace');
+    });
+
+    it('project decisions override workspace for same topic (matching filename slug)', async () => {
+      createMemoryDir(workspaceDir, {
+        decisions: [
+          { filename: 'database-choice.md', text: '# Database\n\nWorkspace says MySQL.' },
+        ],
+      });
+      createMemoryDir(projectDir, {
+        decisions: [
+          { filename: 'database-choice.md', text: '# Database\n\nProject says Postgres.' },
+        ],
+      });
+
+      const detector = mockDetector(workspaceDir);
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const merged = await inheritance.loadInheritedMemory(projectDir);
+
+      // Same filename slug = same topic; project wins
+      expect(merged.decisions).toHaveLength(1);
+      expect(merged.decisions[0].text).toContain('Postgres');
+      expect(merged.decisions[0].source).toBe('project');
+    });
+
+    it('loads and merges gotchas (union of both)', async () => {
+      createMemoryDir(workspaceDir, {
+        gotchas: [
+          { filename: 'auth-warmup.md', text: '# Auth Warmup\n\nNeeds 2s delay.' },
+        ],
+      });
+      createMemoryDir(projectDir, {
+        gotchas: [
+          { filename: 'db-timeout.md', text: '# DB Timeout\n\nIncrease pool size.' },
+        ],
+      });
+
+      const detector = mockDetector(workspaceDir);
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const merged = await inheritance.loadInheritedMemory(projectDir);
+
+      expect(merged.gotchas).toHaveLength(2);
+      const texts = merged.gotchas.map((g) => g.text);
+      expect(texts.some((t) => t.includes('Auth Warmup'))).toBe(true);
+      expect(texts.some((t) => t.includes('DB Timeout'))).toBe(true);
+    });
+
+    it('project preferences override workspace preferences (same filename slug)', async () => {
+      createMemoryDir(workspaceDir, {
+        preferences: [
+          { filename: 'code-style.md', text: '# Code Style\n\nWorkspace: use tabs.' },
+        ],
+      });
+      createMemoryDir(projectDir, {
+        preferences: [
+          { filename: 'code-style.md', text: '# Code Style\n\nProject: use spaces.' },
+        ],
+      });
+
+      const detector = mockDetector(workspaceDir);
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const merged = await inheritance.loadInheritedMemory(projectDir);
+
+      // Same slug = same topic; project wins
+      expect(merged.preferences).toHaveLength(1);
+      expect(merged.preferences[0].text).toContain('spaces');
+      expect(merged.preferences[0].source).toBe('project');
+    });
+
+    it('conversations from both sources are included', async () => {
+      createMemoryDir(workspaceDir, {
+        conversations: [
+          { filename: 'ws-session-1.md', text: '# Session 1\n\nDiscussed architecture.' },
+        ],
+      });
+      createMemoryDir(projectDir, {
+        conversations: [
+          { filename: 'proj-session-1.md', text: '# Session 1\n\nDiscussed database.' },
+        ],
+      });
+
+      const detector = mockDetector(workspaceDir);
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const merged = await inheritance.loadInheritedMemory(projectDir);
+
+      expect(merged.conversations).toHaveLength(2);
+      const sources = merged.conversations.map((c) => c.source);
+      expect(sources).toContain('project');
+      expect(sources).toContain('workspace');
+    });
+
+    it('each item is tagged with source: project or workspace', async () => {
+      createMemoryDir(workspaceDir, {
+        decisions: [
+          { filename: 'ws-decision.md', text: '# WS Decision\n\nShared policy.' },
+        ],
+        gotchas: [
+          { filename: 'ws-gotcha.md', text: '# WS Gotcha\n\nWatch out.' },
+        ],
+      });
+      createMemoryDir(projectDir, {
+        decisions: [
+          { filename: 'proj-decision.md', text: '# Proj Decision\n\nLocal policy.' },
+        ],
+        gotchas: [
+          { filename: 'proj-gotcha.md', text: '# Proj Gotcha\n\nBe careful.' },
+        ],
+      });
+
+      const detector = mockDetector(workspaceDir);
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const merged = await inheritance.loadInheritedMemory(projectDir);
+
+      for (const item of [...merged.decisions, ...merged.gotchas]) {
+        expect(item).toHaveProperty('source');
+        expect(['project', 'workspace']).toContain(item.source);
+      }
+
+      const projectItems = merged.decisions.filter((d) => d.source === 'project');
+      const workspaceItems = merged.decisions.filter((d) => d.source === 'workspace');
+      expect(projectItems).toHaveLength(1);
+      expect(workspaceItems).toHaveLength(1);
+    });
+
+    it('workspace items have lower relevance than project items', async () => {
+      createMemoryDir(workspaceDir, {
+        decisions: [
+          { filename: 'ws-decision.md', text: '# WS Decision\n\nShared.' },
+        ],
+      });
+      createMemoryDir(projectDir, {
+        decisions: [
+          { filename: 'proj-decision.md', text: '# Proj Decision\n\nLocal.' },
+        ],
+      });
+
+      const detector = mockDetector(workspaceDir);
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const merged = await inheritance.loadInheritedMemory(projectDir);
+
+      const projectItem = merged.decisions.find((d) => d.source === 'project');
+      const workspaceItem = merged.decisions.find((d) => d.source === 'workspace');
+
+      expect(projectItem).toHaveProperty('relevance');
+      expect(workspaceItem).toHaveProperty('relevance');
+      expect(workspaceItem.relevance).toBeLessThan(projectItem.relevance);
+    });
+
+    it('standalone project returns only own memory (no workspace)', async () => {
+      createMemoryDir(projectDir, {
+        decisions: [
+          { filename: 'local-only.md', text: '# Local Only\n\nNo workspace.' },
+        ],
+        gotchas: [],
+        preferences: [],
+        conversations: [],
+      });
+
+      const detector = mockDetector(null); // standalone
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const merged = await inheritance.loadInheritedMemory(projectDir);
+
+      expect(merged.decisions).toHaveLength(1);
+      expect(merged.decisions[0].source).toBe('project');
+      expect(merged.gotchas).toHaveLength(0);
+      expect(merged.preferences).toHaveLength(0);
+      expect(merged.conversations).toHaveLength(0);
+    });
+  });
+
+  describe('getInheritedRoots', () => {
+    it('returns both memory paths when in a workspace', () => {
+      createMemoryDir(workspaceDir);
+      createMemoryDir(projectDir);
+
+      const detector = mockDetector(workspaceDir);
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const roots = inheritance.getInheritedRoots(projectDir);
+
+      expect(roots).toHaveLength(2);
+      expect(roots).toContain(path.join(projectDir, 'memory'));
+      expect(roots).toContain(path.join(workspaceDir, 'memory'));
+    });
+
+    it('returns only project memory path for standalone project', () => {
+      createMemoryDir(projectDir);
+
+      const detector = mockDetector(null); // standalone
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const roots = inheritance.getInheritedRoots(projectDir);
+
+      expect(roots).toHaveLength(1);
+      expect(roots[0]).toBe(path.join(projectDir, 'memory'));
+    });
+  });
+
+  describe('error handling', () => {
+    it('handles missing workspace memory directory gracefully', async () => {
+      // Workspace exists but has no memory/ dir
+      createMemoryDir(projectDir, {
+        decisions: [
+          { filename: 'local.md', text: '# Local\n\nOnly local memory.' },
+        ],
+      });
+      // No createMemoryDir for workspace -- so workspace/memory/ does not exist
+
+      const detector = mockDetector(workspaceDir);
+      const inheritance = createMemoryInheritance({ workspaceDetector: detector });
+      const merged = await inheritance.loadInheritedMemory(projectDir);
+
+      // Should not throw; just return project-only memory
+      expect(merged.decisions).toHaveLength(1);
+      expect(merged.decisions[0].source).toBe('project');
+    });
+  });
+});

package/server/lib/plan-parser.js

@@ -18,7 +18,7 @@ function parsePlan(projectDir) {
   if (fs.existsSync(roadmapPath)) {
     const content = fs.readFileSync(roadmapPath, 'utf-8');
 
-    // Find first incomplete phase
+    // Format 1: ## Phase N: Name [x] (heading format)
     const phaseMatches = content.matchAll(/##\s+Phase\s+(\d+)(?:\.(\d+))?[:\s]+(.+?)(?:\s*\[([x ])\])?$/gm);
     for (const match of phaseMatches) {
       const phaseNum = match[2] ? `${match[1]}.${match[2]}` : match[1];
@@ -31,16 +31,42 @@ function parsePlan(projectDir) {
         break;
       }
     }
+
+    // Format 2: Table format | 01 | [Name](link) | status | description |
+    if (!result.currentPhase) {
+      const tableMatches = content.matchAll(/\|\s*(\d+)\s*\|\s*\[([^\]]+)\][^\|]*\|\s*(\w+)\s*\|/g);
+      for (const match of tableMatches) {
+        const phaseNum = match[1].replace(/^0+/, '') || '0'; // strip leading zeros
+        const phaseName = match[2].trim();
+        const status = match[3].trim().toLowerCase();
+        const completed = status === 'complete' || status === 'done' || status === 'verified';
+
+        if (!completed) {
+          result.currentPhase = phaseNum;
+          result.currentPhaseName = phaseName;
+          break;
+        }
+      }
+    }
   }
 
   // Load current phase PLAN.md
   if (result.currentPhase) {
-    const planPath = path.join(
-      projectDir,
-      '.planning',
-      'phases',
-      `${result.currentPhase}-PLAN.md`
-    );
+    const phasesDir = path.join(projectDir, '.planning', 'phases');
+    let planPath = path.join(phasesDir, `${result.currentPhase}-PLAN.md`);
+
+    // Try exact match first, then glob for prefixed names like "06-name-PLAN.md"
+    if (!fs.existsSync(planPath) && fs.existsSync(phasesDir)) {
+      const padded = result.currentPhase.toString().padStart(2, '0');
+      const files = fs.readdirSync(phasesDir);
+      const match = files.find(f =>
+        (f.startsWith(`${padded}-`) || f.startsWith(`${result.currentPhase}-`)) &&
+        f.endsWith('-PLAN.md')
+      );
+      if (match) {
+        planPath = path.join(phasesDir, match);
+      }
+    }
 
     if (fs.existsSync(planPath)) {
       const content = fs.readFileSync(planPath, 'utf-8');