tlc-claude-code 2.4.3 → 2.4.4

package/server/lib/orchestration/prompt-builder.js

@@ -0,0 +1,118 @@
+const path = require('path');
+const { packagePrompt } = require('../prompt-packager.js');
+
+function formatBulletList(items = []) {
+  return items.map((item) => `  - ${item}`).join('\n');
+}
+
+function buildTaskPrompt({ goal, files = [], criteria = [], testCases = [] }) {
+  return [
+    `Goal: ${goal}`,
+    '',
+    'Files to work with:',
+    formatBulletList(files),
+    '',
+    'Acceptance criteria:',
+    formatBulletList(criteria),
+    '',
+    'Test cases:',
+    formatBulletList(testCases),
+    '',
+    'Methodology: Write tests first (red → green → refactor). You MUST write the test before implementing any code. Test-first is required.',
+  ].join('\n');
+}
+
+function buildContextPrompt({
+  agentPrompt,
+  projectDoc,
+  planDoc,
+  codingStandards,
+  files,
+  tokenBudget = 100000,
+}) {
+  return packagePrompt({
+    agentPrompt,
+    projectDoc,
+    planDoc,
+    codingStandards,
+    files,
+    tokenBudget,
+  });
+}
+
+function readOptionalFile(fsImpl, filePath) {
+  if (!fsImpl.existsSync(filePath)) {
+    return null;
+  }
+  return fsImpl.readFileSync(filePath, 'utf-8');
+}
+
+function findPlanPath(projectDir, phase, fsImpl) {
+  if (!phase) {
+    return path.join(projectDir, 'PLAN.md');
+  }
+
+  const phasesDir = path.join(projectDir, '.planning', 'phases');
+  const exactPath = path.join(phasesDir, `${phase}-PLAN.md`);
+  if (fsImpl.existsSync(exactPath)) {
+    return exactPath;
+  }
+
+  if (!fsImpl.existsSync(phasesDir)) {
+    return path.join(projectDir, 'PLAN.md');
+  }
+
+  try {
+    const padded = String(phase).padStart(2, '0');
+    const match = fsImpl.readdirSync(phasesDir).find(
+      (name) =>
+        (name.startsWith(`${padded}-`) || name.startsWith(`${phase}-`)) &&
+        name.endsWith('-PLAN.md')
+    );
+
+    if (match) {
+      return path.join(phasesDir, match);
+    }
+  } catch {
+    return path.join(projectDir, 'PLAN.md');
+  }
+
+  return path.join(projectDir, 'PLAN.md');
+}
+
+function readRelevantFiles(fsImpl, projectDir, filePaths = []) {
+  return filePaths.reduce((acc, filePath) => {
+    const absolutePath = path.isAbsolute(filePath) ? filePath : path.join(projectDir, filePath);
+    if (!fsImpl.existsSync(absolutePath)) {
+      return acc;
+    }
+
+    acc.push({
+      path: filePath,
+      content: fsImpl.readFileSync(absolutePath, 'utf-8'),
+    });
+    return acc;
+  }, []);
+}
+
+function buildFullPrompt({ task, projectDir, phase, fs: fsImpl = require('fs') }) {
+  const agentPrompt = buildTaskPrompt(task);
+  const projectDoc = readOptionalFile(fsImpl, path.join(projectDir, 'PROJECT.md'));
+  const planDoc = readOptionalFile(fsImpl, findPlanPath(projectDir, phase, fsImpl));
+  const codingStandards = readOptionalFile(fsImpl, path.join(projectDir, 'CODING-STANDARDS.md'));
+  const files = readRelevantFiles(fsImpl, projectDir, task.files);
+
+  return buildContextPrompt({
+    agentPrompt,
+    projectDoc,
+    planDoc,
+    codingStandards,
+    files,
+  });
+}
+
+module.exports = {
+  buildTaskPrompt,
+  buildContextPrompt,
+  buildFullPrompt,
+};

package/server/lib/orchestration/prompt-builder.test.js

@@ -0,0 +1,200 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { createRequire } from 'module';
+import { describe, it, expect, afterEach } from 'vitest';
+
+const require = createRequire(import.meta.url);
+
+const { packagePrompt } = require('../prompt-packager.js');
+const { buildTaskPrompt, buildContextPrompt, buildFullPrompt } = require('./prompt-builder.js');
+
+const tempDirs = [];
+
+function makeTempProject() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-prompt-builder-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+  }
+});
+
+describe('prompt-builder', () => {
+  describe('buildTaskPrompt', () => {
+    it('matches the existing dispatcher prompt format and includes TDD instructions', () => {
+      const result = buildTaskPrompt({
+        goal: 'Implement login',
+        files: ['src/login.js', 'src/login.test.js'],
+        criteria: ['Supports valid credentials', 'Rejects bad passwords'],
+        testCases: ['logs in a valid user', 'rejects an invalid user'],
+      });
+
+      expect(result).toBe([
+        'Goal: Implement login',
+        '',
+        'Files to work with:',
+        '  - src/login.js',
+        '  - src/login.test.js',
+        '',
+        'Acceptance criteria:',
+        '  - Supports valid credentials',
+        '  - Rejects bad passwords',
+        '',
+        'Test cases:',
+        '  - logs in a valid user',
+        '  - rejects an invalid user',
+        '',
+        'Methodology: Write tests first (red → green → refactor). You MUST write the test before implementing any code. Test-first is required.',
+      ].join('\n'));
+    });
+
+    it('supports empty file, criteria, and test case lists', () => {
+      const result = buildTaskPrompt({ goal: 'Implement logout' });
+
+      expect(result).toContain('Goal: Implement logout');
+      expect(result).toContain('Files to work with:\n');
+      expect(result).toContain('Acceptance criteria:\n');
+      expect(result).toContain('Test cases:\n');
+      expect(result).toContain('Write tests first');
+    });
+  });
+
+  describe('buildContextPrompt', () => {
+    it('delegates to packagePrompt with the provided options', () => {
+      const input = {
+        agentPrompt: 'Do the task',
+        projectDoc: '# Project',
+        planDoc: '# Plan',
+        codingStandards: '# Standards',
+        files: [
+          { path: 'b.js', content: 'b' },
+          { path: 'a.js', content: 'a' },
+        ],
+        tokenBudget: 500,
+      };
+
+      expect(buildContextPrompt(input)).toBe(packagePrompt(input));
+    });
+  });
+
+  describe('buildFullPrompt', () => {
+    it('reads project docs and relevant files, then packages the full prompt', () => {
+      const projectDir = makeTempProject();
+      fs.mkdirSync(path.join(projectDir, '.planning', 'phases'), { recursive: true });
+      fs.writeFileSync(path.join(projectDir, 'PROJECT.md'), '# Project\nShip it');
+      fs.writeFileSync(path.join(projectDir, 'CODING-STANDARDS.md'), '# Standards\nWrite tests');
+      fs.writeFileSync(path.join(projectDir, '.planning', 'phases', '1-PLAN.md'), '# Phase 1\nDo it');
+      fs.mkdirSync(path.join(projectDir, 'src'), { recursive: true });
+      fs.writeFileSync(path.join(projectDir, 'src', 'feature.js'), 'module.exports = { feature: true };');
+      fs.writeFileSync(path.join(projectDir, 'src', 'feature.test.js'), 'test("feature", () => {});');
+
+      const result = buildFullPrompt({
+        task: {
+          goal: 'Build feature',
+          files: ['src/feature.js', 'src/feature.test.js'],
+          criteria: ['Feature works'],
+          testCases: ['Feature passes'],
+        },
+        projectDir,
+        phase: 1,
+      });
+
+      expect(result).toContain('--- Task ---');
+      expect(result).toContain('Goal: Build feature');
+      expect(result).toContain('--- PROJECT.md ---');
+      expect(result).toContain('# Project\nShip it');
+      expect(result).toContain('--- Current Phase Plan ---');
+      expect(result).toContain('# Phase 1\nDo it');
+      expect(result).toContain('--- Coding Standards ---');
+      expect(result).toContain('# Standards\nWrite tests');
+      expect(result).toContain('--- src/feature.js ---');
+      expect(result).toContain('module.exports = { feature: true };');
+      expect(result).toContain('--- src/feature.test.js ---');
+    });
+
+    it('resolves padded or prefixed phase plan filenames', () => {
+      const projectDir = makeTempProject();
+      fs.mkdirSync(path.join(projectDir, '.planning', 'phases'), { recursive: true });
+      fs.writeFileSync(path.join(projectDir, 'PROJECT.md'), '# Project');
+      fs.writeFileSync(path.join(projectDir, 'CODING-STANDARDS.md'), '# Standards');
+      fs.writeFileSync(path.join(projectDir, '.planning', 'phases', '02-api-PLAN.md'), '# Phase 2');
+
+      const result = buildFullPrompt({
+        task: { goal: 'Build API' },
+        projectDir,
+        phase: 2,
+      });
+
+      expect(result).toContain('--- Current Phase Plan ---');
+      expect(result).toContain('# Phase 2');
+    });
+
+    it('skips missing docs and missing task files instead of throwing', () => {
+      const projectDir = makeTempProject();
+
+      const result = buildFullPrompt({
+        task: {
+          goal: 'Build minimal task',
+          files: ['missing.js'],
+        },
+        projectDir,
+        phase: 3,
+      });
+
+      expect(result).toContain('--- Task ---');
+      expect(result).toContain('Goal: Build minimal task');
+      expect(result).not.toContain('--- PROJECT.md ---');
+      expect(result).not.toContain('--- Current Phase Plan ---');
+      expect(result).not.toContain('--- Coding Standards ---');
+      expect(result).not.toContain('--- Relevant Files ---');
+    });
+
+    it('supports injected fs implementations', () => {
+      const fakeFs = {
+        existsSync(targetPath) {
+          return [
+            '/project/PROJECT.md',
+            '/project/CODING-STANDARDS.md',
+            '/project/.planning/phases',
+            '/project/.planning/phases/4-build-PLAN.md',
+            '/project/src/app.js',
+          ].includes(targetPath);
+        },
+        readdirSync(targetPath) {
+          if (targetPath === '/project/.planning/phases') {
+            return ['4-build-PLAN.md'];
+          }
+          return [];
+        },
+        readFileSync(targetPath) {
+          const contents = {
+            '/project/PROJECT.md': '# Project',
+            '/project/CODING-STANDARDS.md': '# Standards',
+            '/project/.planning/phases/4-build-PLAN.md': '# Phase 4',
+            '/project/src/app.js': 'console.log("app");',
+          };
+          return contents[targetPath];
+        },
+      };
+
+      const result = buildFullPrompt({
+        task: {
+          goal: 'Build app',
+          files: ['src/app.js'],
+        },
+        projectDir: '/project',
+        phase: 4,
+        fs: fakeFs,
+      });
+
+      expect(result).toContain('# Project');
+      expect(result).toContain('# Standards');
+      expect(result).toContain('# Phase 4');
+      expect(result).toContain('--- src/app.js ---');
+    });
+  });
+});

package/server/lib/orchestration/standalone-compat.js

@@ -0,0 +1,39 @@
+const path = require('path');
+
+function guessProvider(binary) {
+  const basename = path.basename(String(binary || '')).toLowerCase();
+
+  if (['codex', 'claude', 'gemini', 'ollama'].includes(basename)) {
+    return basename;
+  }
+
+  return basename;
+}
+
+async function executeCli(prompt, endpoint, options = {}) {
+  const { dispatch } = require('./cli-dispatch');
+  const provider = guessProvider(endpoint && endpoint.binary);
+  const result = await dispatch({
+    ...options,
+    prompt,
+    provider,
+    // Preserve the original binary path so custom/absolute paths still work
+    binaryOverride: endpoint && endpoint.binary,
+    flags: Array.isArray(endpoint && endpoint.cli_flags) ? endpoint.cli_flags : [],
+  });
+
+  return {
+    response: result.stdout,
+    provider: endpoint && endpoint.name,
+    latency_ms: result.duration,
+  };
+}
+
+function buildTaskPrompt(task) {
+  return require('./prompt-builder').buildTaskPrompt(task);
+}
+
+module.exports = {
+  executeCli,
+  buildTaskPrompt,
+};

package/server/lib/orchestration/standalone-compat.test.js

@@ -0,0 +1,144 @@
+import path from 'path';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+
+const cliDispatch = require('./cli-dispatch.js');
+const promptBuilder = require('./prompt-builder.js');
+const { executeCli, buildTaskPrompt } = require('./standalone-compat.js');
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('standalone-compat', () => {
+  describe('executeCli', () => {
+    it('delegates to cli-dispatch with provider guessed from codex binary', async () => {
+      const dispatchSpy = vi.spyOn(cliDispatch, 'dispatch').mockResolvedValue({
+        stdout: 'ok',
+        duration: 42,
+      });
+
+      await executeCli(
+        'Ship it',
+        {
+          binary: 'codex',
+          cli_flags: ['--model', 'gpt-5.4'],
+          name: 'Codex CLI',
+        },
+        {
+          timeout: 5000,
+          worktreePath: '/tmp/worktree',
+        }
+      );
+
+      expect(dispatchSpy).toHaveBeenCalledWith({
+        prompt: 'Ship it',
+        provider: 'codex',
+        binaryOverride: 'codex',
+        flags: ['--model', 'gpt-5.4'],
+        timeout: 5000,
+        worktreePath: '/tmp/worktree',
+      });
+    });
+
+    it('guesses provider from the binary basename for known CLIs', async () => {
+      const dispatchSpy = vi.spyOn(cliDispatch, 'dispatch').mockResolvedValue({
+        stdout: 'done',
+        duration: 12,
+      });
+
+      await executeCli('Review this', {
+        binary: path.join('/usr', 'local', 'bin', 'claude'),
+        cli_flags: ['--permission-mode', 'auto'],
+        name: 'Claude Desktop',
+      });
+
+      expect(dispatchSpy).toHaveBeenCalledWith({
+        prompt: 'Review this',
+        provider: 'claude',
+        binaryOverride: path.join('/usr', 'local', 'bin', 'claude'),
+        flags: ['--permission-mode', 'auto'],
+      });
+    });
+
+    it('passes through empty flags when cli_flags is not provided', async () => {
+      const dispatchSpy = vi.spyOn(cliDispatch, 'dispatch').mockResolvedValue({
+        stdout: 'done',
+        duration: 7,
+      });
+
+      await executeCli('Run', {
+        binary: 'gemini',
+        name: 'Gemini CLI',
+      });
+
+      expect(dispatchSpy).toHaveBeenCalledWith({
+        prompt: 'Run',
+        provider: 'gemini',
+        binaryOverride: 'gemini',
+        flags: [],
+      });
+    });
+
+    it('falls back to the binary basename for unknown providers and reshapes the result', async () => {
+      vi.spyOn(cliDispatch, 'dispatch').mockResolvedValue({
+        stdout: 'custom output',
+        duration: 88,
+      });
+
+      const result = await executeCli('Custom task', {
+        binary: '/opt/tools/custom-runner',
+        cli_flags: ['--fast'],
+        name: 'Standalone Custom',
+      });
+
+      expect(result).toEqual({
+        response: 'custom output',
+        provider: 'Standalone Custom',
+        latency_ms: 88,
+      });
+    });
+
+    it('lets explicit options like spawn pass through unchanged', async () => {
+      const spawn = vi.fn();
+      const dispatchSpy = vi.spyOn(cliDispatch, 'dispatch').mockResolvedValue({
+        stdout: 'ok',
+        duration: 3,
+      });
+
+      await executeCli(
+        'Test',
+        {
+          binary: 'ollama',
+          cli_flags: ['llama3.2'],
+          name: 'Ollama',
+        },
+        { spawn }
+      );
+
+      expect(dispatchSpy).toHaveBeenCalledWith({
+        prompt: 'Test',
+        provider: 'ollama',
+        binaryOverride: 'ollama',
+        flags: ['llama3.2'],
+        spawn,
+      });
+    });
+  });
+
+  describe('buildTaskPrompt', () => {
+    it('delegates directly to prompt-builder and returns its string', () => {
+      const task = {
+        goal: 'Implement feature',
+        files: ['src/feature.js'],
+        criteria: ['It works'],
+        testCases: ['passes tests'],
+      };
+      const buildSpy = vi.spyOn(promptBuilder, 'buildTaskPrompt').mockReturnValue('prompt text');
+
+      const result = buildTaskPrompt(task);
+
+      expect(buildSpy).toHaveBeenCalledWith(task);
+      expect(result).toBe('prompt text');
+    });
+  });
+});

package/server/lib/orchestration/worktree-manager.js

@@ -16,6 +16,26 @@ export function sanitizeName(name) {
     .replace(/-{2,}/g, '-');
 }
 
+/**
+ * Build a short, stable task slug from a task name.
+ * Uses the first 4 words, lowercases, hyphenates, and limits to 30 chars.
+ * @param {string} taskName
+ * @returns {string}
+ */
+export function sanitizeTaskName(taskName) {
+  const words = String(taskName)
+    .trim()
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 4);
+
+  const truncated = words.join('-').slice(0, 30);
+  return sanitizeName(truncated)
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-');
+}
+
 /**
  * Create a git worktree for the given name.
  * @param {string} name - Worktree name (will be sanitized)
@@ -47,6 +67,29 @@ export function createWorktree(name, { exec, maxConcurrent } = {}) {
   return { name: safe, branch, path };
 }
 
+/**
+ * Create a git worktree named for a phase/task combination.
+ * @param {number|string} phase
+ * @param {number|string} taskNumber
+ * @param {string} taskName
+ * @param {{ exec: Function, baseBranch?: string }} options
+ * @returns {{ name: string, branch: string, path: string }}
+ */
+export function createTaskWorktree(phase, taskNumber, taskName, { exec, baseBranch } = {}) {
+  const taskSlug = sanitizeTaskName(taskName);
+  const rawName = taskSlug
+    ? `phase-${phase}-task-${taskNumber}-${taskSlug}`
+    : `phase-${phase}-task-${taskNumber}`;
+  const name = sanitizeName(rawName);
+  const branch = `worktree-${name}`;
+  const path = `.claude/worktrees/${name}`;
+  const startPoint = baseBranch || exec('git branch --show-current').trim();
+
+  exec(`git worktree add -b ${branch} ${path} ${startPoint}`);
+
+  return { name, branch, path };
+}
+
 /**
  * List active worktrees under .claude/worktrees/.
  * @param {{ exec: Function }} options

package/server/lib/orchestration/worktree-manager.test.js

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import {
   createWorktree,
+  createTaskWorktree,
   listWorktrees,
   mergeWorktree,
   removeWorktree,
@@ -58,6 +59,55 @@ describe('worktree-manager', () => {
     });
   });
 
+  describe('createTaskWorktree', () => {
+    it('builds a phase/task-based worktree name', () => {
+      exec.mockImplementation((cmd) => {
+        if (cmd === 'git branch --show-current') return 'feature/current\n';
+        return '';
+      });
+
+      const result = createTaskWorktree(30, 5, 'Config Size', { exec });
+
+      expect(result).toEqual({
+        name: 'phase-30-task-5-config-size',
+        branch: 'worktree-phase-30-task-5-config-size',
+        path: '.claude/worktrees/phase-30-task-5-config-size',
+      });
+      expect(exec).toHaveBeenCalledWith(
+        'git worktree add -b worktree-phase-30-task-5-config-size .claude/worktrees/phase-30-task-5-config-size feature/current'
+      );
+    });
+
+    it('sanitizes task name to first four words and max 30 chars', () => {
+      exec.mockImplementation((cmd) => {
+        if (cmd === 'git branch --show-current') return 'main\n';
+        return '';
+      });
+
+      const result = createTaskWorktree(
+        12,
+        9,
+        'Configuration synchronization validation instrumentation extra trailing words',
+        { exec }
+      );
+
+      expect(result.name).toBe('phase-12-task-9-configuration-synchronization');
+      expect(result.branch).toBe('worktree-phase-12-task-9-configuration-synchronization');
+    });
+
+    it('uses a provided base branch instead of the current branch', () => {
+      exec.mockReturnValue('');
+
+      const result = createTaskWorktree(7, 2, 'Ship Metrics', { exec, baseBranch: 'release/7' });
+
+      expect(result.name).toBe('phase-7-task-2-ship-metrics');
+      expect(exec).toHaveBeenCalledTimes(1);
+      expect(exec).toHaveBeenCalledWith(
+        'git worktree add -b worktree-phase-7-task-2-ship-metrics .claude/worktrees/phase-7-task-2-ship-metrics release/7'
+      );
+    });
+  });
+
   describe('listWorktrees', () => {
     it('returns active worktrees with branch and path', () => {
       exec.mockReturnValue(