tlc-claude-code 2.7.0 → 2.9.0

package/scripts/renumber-phases.test.js

@@ -0,0 +1,305 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawnSync } from 'child_process';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import renumberModule from './renumber-phases.js';
+
+const { main, parseArgs, renumberPhases, updatePhaseReferences } = renumberModule;
+
+const SCRIPT_PATH = path.join(process.cwd(), 'scripts', 'renumber-phases.js');
+const tempDirs = [];
+
+function createTempRepo(structure = {}) {
+  const repoPath = fs.mkdtempSync(path.join(os.tmpdir(), 'renumber-phases-'));
+  tempDirs.push(repoPath);
+
+  for (const [relativePath, content] of Object.entries(structure)) {
+    const filePath = path.join(repoPath, relativePath);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+  }
+
+  return repoPath;
+}
+
+function readFile(repoPath, relativePath) {
+  return fs.readFileSync(path.join(repoPath, relativePath), 'utf8');
+}
+
+function fileExists(repoPath, relativePath) {
+  return fs.existsSync(path.join(repoPath, relativePath));
+}
+
+function createPlanningRepo() {
+  return createTempRepo({
+    '.planning/ROADMAP.md': [
+      '# Roadmap',
+      '### Phase 108: Build the tool',
+      'Depends on Phase 107 and Phase 101b.',
+      'Already migrated: Phase TLC-999.',
+      '',
+    ].join('\n'),
+    '.planning/phases/108-PLAN.md': [
+      '# Phase 108',
+      'Depends on Phase 107.',
+      'Review Phase 101b before release.',
+      'Already references Phase TLC-105 correctly.',
+      '',
+    ].join('\n'),
+    '.planning/phases/108-DISCUSSION.md': 'Phase 108 requires context from Phase 107.\n',
+    '.planning/phases/101b-RESEARCH.md': 'Research for Phase 101b.\n',
+    '.planning/phases/108-PLAN.md.superseded': 'Superseded Phase 108 draft.\n',
+    '.planning/phases/TLC-105-PLAN.md': 'Already migrated.\n',
+    '.planning/phases/77-OldPLAN.md': 'Should be ignored.\n',
+    '.planning/phases/77-PLAN.md.md': 'Should be ignored.\n',
+    '.planning/phases/notes.txt': 'Should be ignored.\n',
+  });
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+
+  while (tempDirs.length > 0) {
+    fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+  }
+});
+
+describe('updatePhaseReferences', () => {
+  it('adds the prefix to bare phase references and leaves prefixed ones unchanged', () => {
+    const source = 'Phase 108 follows Phase 101b. Phase TLC-42 stays as-is.';
+
+    const result = updatePhaseReferences(source, 'TLC');
+
+    expect(result.content).toBe(
+      'Phase TLC-108 follows Phase TLC-101b. Phase TLC-42 stays as-is.'
+    );
+    expect(result.replacements).toBe(2);
+  });
+});
+
+describe('parseArgs', () => {
+  it('parses repo path, prefix, and dry-run', () => {
+    expect(
+      parseArgs(['--repo-path', '/tmp/repo', '--prefix', 'TLC', '--dry-run'])
+    ).toEqual({
+      dryRun: true,
+      repoPath: '/tmp/repo',
+      prefix: 'TLC',
+    });
+  });
+
+  it('throws when required arguments are missing', () => {
+    expect(() => parseArgs(['--prefix', 'TLC'])).toThrow('Missing required arguments');
+    expect(() => parseArgs(['--repo-path', '/tmp/repo'])).toThrow('Missing required arguments');
+  });
+});
+
+describe('renumberPhases', () => {
+  it('renames matching files, updates roadmap references, and preserves ignored files', () => {
+    const repoPath = createPlanningRepo();
+    const stdout = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const stderr = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const summary = renumberPhases({
+      repoPath,
+      prefix: 'TLC',
+    });
+
+    expect(summary).toEqual({
+      renamed: 4,
+      updated: 10,
+      errors: 0,
+    });
+
+    expect(fileExists(repoPath, '.planning/phases/TLC-108-PLAN.md')).toBe(true);
+    expect(fileExists(repoPath, '.planning/phases/TLC-108-DISCUSSION.md')).toBe(true);
+    expect(fileExists(repoPath, '.planning/phases/TLC-101b-RESEARCH.md')).toBe(true);
+    expect(fileExists(repoPath, '.planning/phases/TLC-108-PLAN.md.superseded')).toBe(true);
+
+    expect(fileExists(repoPath, '.planning/phases/108-PLAN.md')).toBe(false);
+    expect(fileExists(repoPath, '.planning/phases/108-DISCUSSION.md')).toBe(false);
+    expect(fileExists(repoPath, '.planning/phases/101b-RESEARCH.md')).toBe(false);
+    expect(fileExists(repoPath, '.planning/phases/108-PLAN.md.superseded')).toBe(false);
+
+    expect(fileExists(repoPath, '.planning/phases/TLC-105-PLAN.md')).toBe(true);
+    expect(fileExists(repoPath, '.planning/phases/77-OldPLAN.md')).toBe(true);
+    expect(fileExists(repoPath, '.planning/phases/77-PLAN.md.md')).toBe(true);
+
+    expect(readFile(repoPath, '.planning/ROADMAP.md')).toContain('### Phase TLC-108: Build the tool');
+    expect(readFile(repoPath, '.planning/ROADMAP.md')).toContain('Depends on Phase TLC-107 and Phase TLC-101b.');
+    expect(readFile(repoPath, '.planning/ROADMAP.md')).toContain('Already migrated: Phase TLC-999.');
+
+    expect(readFile(repoPath, '.planning/phases/TLC-108-PLAN.md')).toContain('Depends on Phase TLC-107.');
+    expect(readFile(repoPath, '.planning/phases/TLC-108-PLAN.md')).toContain(
+      'Review Phase TLC-101b before release.'
+    );
+    expect(readFile(repoPath, '.planning/phases/TLC-108-PLAN.md')).toContain(
+      'Already references Phase TLC-105 correctly.'
+    );
+    expect(readFile(repoPath, '.planning/phases/TLC-108-DISCUSSION.md')).toContain(
+      'Phase TLC-108 requires context from Phase TLC-107.'
+    );
+    expect(readFile(repoPath, '.planning/phases/TLC-108-PLAN.md.superseded')).toContain(
+      'Superseded Phase TLC-108 draft.'
+    );
+
+    expect(stdout).toHaveBeenLastCalledWith('Renamed: 4 files, Updated: 10 references, Errors: 0');
+    expect(stderr).not.toHaveBeenCalled();
+  });
+
+  it('supports dry-run without modifying files', () => {
+    const repoPath = createPlanningRepo();
+    const originalRoadmap = readFile(repoPath, '.planning/ROADMAP.md');
+    const originalPlan = readFile(repoPath, '.planning/phases/108-PLAN.md');
+    const stdout = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    const summary = renumberPhases({
+      repoPath,
+      prefix: 'TLC',
+      dryRun: true,
+    });
+
+    expect(summary).toEqual({
+      renamed: 4,
+      updated: 10,
+      errors: 0,
+    });
+
+    expect(fileExists(repoPath, '.planning/phases/108-PLAN.md')).toBe(true);
+    expect(fileExists(repoPath, '.planning/phases/TLC-108-PLAN.md')).toBe(false);
+    expect(readFile(repoPath, '.planning/ROADMAP.md')).toBe(originalRoadmap);
+    expect(readFile(repoPath, '.planning/phases/108-PLAN.md')).toBe(originalPlan);
+
+    expect(stdout.mock.calls).toEqual(
+      expect.arrayContaining([
+        [expect.stringContaining('DRY-RUN rename')],
+        [expect.stringContaining('DRY-RUN update')],
+        ['Renamed: 4 files, Updated: 10 references, Errors: 0'],
+      ])
+    );
+  });
+
+  it('is idempotent when run again on already-prefixed files', () => {
+    const repoPath = createPlanningRepo();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const firstSummary = renumberPhases({
+      repoPath,
+      prefix: 'TLC',
+    });
+
+    const secondSummary = renumberPhases({
+      repoPath,
+      prefix: 'TLC',
+    });
+
+    expect(firstSummary).toEqual({
+      renamed: 4,
+      updated: 10,
+      errors: 0,
+    });
+    expect(secondSummary).toEqual({
+      renamed: 0,
+      updated: 0,
+      errors: 0,
+    });
+
+    expect(fileExists(repoPath, '.planning/phases/TLC-108-PLAN.md')).toBe(true);
+    expect(readFile(repoPath, '.planning/ROADMAP.md')).toContain('### Phase TLC-108: Build the tool');
+  });
+
+  it('reports rename collisions as errors without overwriting files', () => {
+    const repoPath = createTempRepo({
+      '.planning/ROADMAP.md': '### Phase 108: Collision case\nPhase 108 only.\n',
+      '.planning/phases/108-PLAN.md': 'Phase 108.\n',
+      '.planning/phases/TLC-108-PLAN.md': 'Existing target.\n',
+    });
+    const stdout = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const stderr = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const summary = renumberPhases({
+      repoPath,
+      prefix: 'TLC',
+      dryRun: true,
+    });
+
+    expect(summary).toEqual({
+      renamed: 1,
+      updated: 3,
+      errors: 1,
+    });
+    expect(stderr).toHaveBeenCalledWith(
+      'Cannot rename 108-PLAN.md because TLC-108-PLAN.md already exists'
+    );
+    expect(stdout).toHaveBeenLastCalledWith('Renamed: 1 files, Updated: 3 references, Errors: 1');
+  });
+
+  it('throws when the phases directory is missing', () => {
+    const repoPath = createTempRepo({
+      '.planning/ROADMAP.md': '### Phase 1: Missing phases dir\n',
+    });
+
+    expect(() =>
+      renumberPhases({
+        repoPath,
+        prefix: 'TLC',
+      })
+    ).toThrow(`Missing phases directory: ${path.join(repoPath, '.planning', 'phases')}`);
+  });
+});
+
+describe('main', () => {
+  it('returns 1 and prints usage for missing repo-path', () => {
+    const stdout = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const exitCode = main(['--prefix', 'TLC']);
+
+    expect(exitCode).toBe(1);
+    expect(stdout).not.toHaveBeenCalled();
+    expect(stderr).toHaveBeenCalledWith(
+      'Usage: node scripts/renumber-phases.js --repo-path <path> --prefix <PREFIX> [--dry-run]\n'
+    );
+    expect(consoleError).toHaveBeenCalledWith('Missing required arguments');
+  });
+
+  it('returns 1 when the phases directory does not exist', () => {
+    const repoPath = createTempRepo({
+      '.planning/ROADMAP.md': '### Phase 1: Missing phases dir\n',
+    });
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const exitCode = main(['--repo-path', repoPath, '--prefix', 'TLC']);
+
+    expect(exitCode).toBe(1);
+    expect(consoleError).toHaveBeenCalledWith(
+      `Missing phases directory: ${path.join(repoPath, '.planning', 'phases')}`
+    );
+  });
+
+  it('works from the real CLI entry point', () => {
+    const repoPath = createTempRepo({
+      '.planning/ROADMAP.md': '### Phase 12: CLI check\nPhase 12 is ready.\n',
+      '.planning/phases/12-PLAN.md': 'Phase 12 is ready.\n',
+    });
+
+    const result = spawnSync(
+      process.execPath,
+      [SCRIPT_PATH, '--repo-path', repoPath, '--prefix', 'TLC'],
+      {
+        encoding: 'utf8',
+      }
+    );
+
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(result.stdout).toContain('Renamed: 1 files, Updated: 3 references, Errors: 0');
+    expect(fileExists(repoPath, '.planning/phases/TLC-12-PLAN.md')).toBe(true);
+    expect(readFile(repoPath, '.planning/ROADMAP.md')).toContain('### Phase TLC-12: CLI check');
+  });
+});

package/server/lib/orchestration/completion-checker.js

@@ -1,5 +1,17 @@
 const fs = require('fs/promises');
 
+const ACTIONABLE_MONITOR_STATES = new Map([
+  ['stuck', { suggestedAction: 'retry' }],
+  ['budget_exhausted', { suggestedAction: 'retry' }],
+]);
+
+const FAILURE_MONITOR_STATES = new Map([
+  ['crashed', 'session crashed and needs investigation'],
+  ['errored', 'session errored and needs investigation'],
+  ['loop_detected', 'session entered a loop and needs investigation'],
+  ['timed_out', 'session timed out and needs investigation'],
+]);
+
 async function readActiveSessions(activeSessionsPath) {
   try {
     const raw = await fs.readFile(activeSessionsPath, 'utf8');
@@ -18,6 +30,19 @@ async function writeActiveSessions(activeSessionsPath, sessions) {
   await fs.writeFile(activeSessionsPath, JSON.stringify(sessions, null, 2));
 }
 
+function getNormalizedStatus(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return null;
+  }
+
+  const monitorState = payload.monitorState
+    || payload.monitor?.state
+    || payload.metadata?.monitorState
+    || null;
+
+  return String(monitorState || payload.status || '').trim().toLowerCase() || null;
+}
+
 async function checkCompletions({
   activeSessionsPath,
   orchestratorUrl,
@@ -28,12 +53,14 @@ async function checkCompletions({
     return {
       completions: [],
       failures: [],
+      actionable: [],
       stillRunning: 0,
     };
   }
 
   const completions = [];
   const failures = [];
+  const actionable = [];
   const remainingSessions = [];
 
   let orchestratorReachable = true;
@@ -51,13 +78,14 @@ async function checkCompletions({
       }
 
       const payload = await response.json();
+      const status = getNormalizedStatus(payload);
 
-      if (payload.status === 'completed') {
+      if (status === 'completed') {
         completions.push(session);
         continue;
       }
 
-      if (payload.status === 'failed') {
+      if (status === 'failed') {
         failures.push({
           ...session,
           ...(payload.reason ? { reason: payload.reason } : {}),
@@ -65,6 +93,26 @@ async function checkCompletions({
         continue;
       }
 
+      if (ACTIONABLE_MONITOR_STATES.has(status)) {
+        actionable.push({
+          ...session,
+          status,
+          actionable: true,
+          suggestedAction: ACTIONABLE_MONITOR_STATES.get(status).suggestedAction,
+        });
+        continue;
+      }
+
+      if (FAILURE_MONITOR_STATES.has(status)) {
+        failures.push({
+          ...session,
+          status,
+          actionable: false,
+          failureReason: FAILURE_MONITOR_STATES.get(status),
+        });
+        continue;
+      }
+
       remainingSessions.push(session);
     } catch (error) {
       if (!orchestratorReachable) {
@@ -82,6 +130,7 @@ async function checkCompletions({
     return {
       completions: [],
       failures: [],
+      actionable: [],
       stillRunning: -1,
       error: 'orchestrator unreachable',
     };
@@ -92,6 +141,7 @@ async function checkCompletions({
   return {
     completions,
     failures,
+    actionable,
     stillRunning: remainingSessions.length,
   };
 }

package/server/lib/orchestration/completion-checker.test.js

@@ -49,6 +49,7 @@ describe('completion-checker', () => {
     expect(result).toEqual({
       completions: [],
       failures: [],
+      actionable: [],
       stillRunning: 0,
     });
     expect(fetch).not.toHaveBeenCalled();
@@ -74,6 +75,7 @@ describe('completion-checker', () => {
     expect(result).toEqual({
       completions: [makeSession()],
       failures: [],
+      actionable: [],
       stillRunning: 0,
     });
     expect(JSON.parse(fs.readFileSync(activeSessionsPath, 'utf8'))).toEqual([]);
@@ -97,6 +99,7 @@ describe('completion-checker', () => {
     expect(result).toEqual({
       completions: [],
       failures: [{ ...makeSession(), reason: 'Tests failed' }],
+      actionable: [],
       stillRunning: 0,
     });
     expect(JSON.parse(fs.readFileSync(activeSessionsPath, 'utf8'))).toEqual([]);
@@ -131,11 +134,70 @@ describe('completion-checker', () => {
     expect(result).toEqual({
       completions: [completed],
       failures: [{ ...failed, reason: 'Rejected' }],
+      actionable: [],
       stillRunning: 1,
     });
     expect(JSON.parse(fs.readFileSync(activeSessionsPath, 'utf8'))).toEqual([running]);
   });
 
+  it.each([
+    ['stuck', { status: 'stuck', actionable: true, suggestedAction: 'retry' }],
+    ['budget_exhausted', { status: 'budget_exhausted', actionable: true, suggestedAction: 'retry' }],
+  ])('reports actionable monitor state %s', async (state, expected) => {
+    const activeSessionsPath = makeActiveSessionsPath();
+    const session = makeSession();
+    writeSessionsFile(activeSessionsPath, [session]);
+
+    const fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ status: state }),
+    });
+
+    const result = await checkCompletions({
+      activeSessionsPath,
+      orchestratorUrl: 'http://orchestrator.test',
+      fetch,
+    });
+
+    expect(result).toEqual({
+      completions: [],
+      failures: [],
+      actionable: [{ ...session, ...expected }],
+      stillRunning: 0,
+    });
+    expect(JSON.parse(fs.readFileSync(activeSessionsPath, 'utf8'))).toEqual([]);
+  });
+
+  it.each([
+    ['crashed', 'session crashed and needs investigation'],
+    ['errored', 'session errored and needs investigation'],
+    ['loop_detected', 'session entered a loop and needs investigation'],
+    ['timed_out', 'session timed out and needs investigation'],
+  ])('reports failure monitor state %s', async (state, failureReason) => {
+    const activeSessionsPath = makeActiveSessionsPath();
+    const session = makeSession();
+    writeSessionsFile(activeSessionsPath, [session]);
+
+    const fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ status: state }),
+    });
+
+    const result = await checkCompletions({
+      activeSessionsPath,
+      orchestratorUrl: 'http://orchestrator.test',
+      fetch,
+    });
+
+    expect(result).toEqual({
+      completions: [],
+      failures: [{ ...session, status: state, actionable: false, failureReason }],
+      actionable: [],
+      stillRunning: 0,
+    });
+    expect(JSON.parse(fs.readFileSync(activeSessionsPath, 'utf8'))).toEqual([]);
+  });
+
   it('returns an error result when the orchestrator is unreachable', async () => {
     const activeSessionsPath = makeActiveSessionsPath();
     const session = makeSession();
@@ -152,6 +214,7 @@ describe('completion-checker', () => {
     expect(result).toEqual({
       completions: [],
       failures: [],
+      actionable: [],
       stillRunning: -1,
       error: 'orchestrator unreachable',
     });
@@ -170,6 +233,7 @@ describe('completion-checker', () => {
     expect(result).toEqual({
       completions: [],
       failures: [],
+      actionable: [],
       stillRunning: 0,
     });
     expect(fs.existsSync(activeSessionsPath)).toBe(false);

package/server/lib/orchestration/session-status.js

@@ -49,6 +49,24 @@ function buildSummary(session) {
   return titleCaseStatus(session.status);
 }
 
+function getSessionSkill(session) {
+  return session.metadata?.skill || session.skill || '-';
+}
+
+function getMonitorState(session) {
+  return session.monitorState || session.monitor?.state || session.metadata?.monitorState || '-';
+}
+
+function hasAlert(session) {
+  const monitorState = String(getMonitorState(session)).toLowerCase();
+  return ['stuck', 'errored', 'crashed'].includes(monitorState);
+}
+
+function formatSessionId(session) {
+  const id = session.id || '-';
+  return hasAlert(session) ? `[!] ${id}` : id;
+}
+
 /**
  * Format rows into an aligned CLI table.
  * @param {string[]} headers
@@ -108,11 +126,13 @@ function formatSessionStatus({ sessions } = {}) {
     sections.push([
       'Running Sessions',
       formatTable(
-        ['ID', 'Project', 'Status', 'Elapsed', 'Task'],
+        ['ID', 'Skill', 'Project', 'Status', 'Monitor', 'Elapsed', 'Task'],
         running.map((session) => [
-          session.id || '-',
+          formatSessionId(session),
+          getSessionSkill(session),
           session.project || '-',
           session.status || '-',
+          getMonitorState(session),
           formatElapsed(session.created_at),
           session.command || '-',
         ])
@@ -125,11 +145,13 @@ function formatSessionStatus({ sessions } = {}) {
     sections.push([
       'Completed Sessions',
       formatTable(
-        ['ID', 'Project', 'Status', 'Summary'],
+        ['ID', 'Skill', 'Project', 'Status', 'Monitor', 'Summary'],
         completed.map((session) => [
-          session.id || '-',
+          formatSessionId(session),
+          getSessionSkill(session),
           session.project || '-',
           session.status || '-',
+          getMonitorState(session),
           buildSummary(session),
         ])
       ),
@@ -144,4 +166,6 @@ module.exports = {
   formatSessionStatus,
   formatElapsed,
   buildSummary,
+  getSessionSkill,
+  getMonitorState,
 };