tlc-claude-code 2.7.0 → 2.9.0

package/.claude/commands/tlc/tlc.md

@@ -198,6 +198,14 @@ If no roadmap exists:
 
 ### Step 2: Find The Active Phase
 
+Before matching phase artifacts, determine the current repo prefix:
+
+1. Try workspace-aware discovery first:
+   - Load `/workspace/Tools/.tlc-workspace.json` when available, or discover the nearest manifest via `server/lib/workspace-manifest.js`
+   - Use the current repo path plus the manifest to resolve the repo prefix (`TLC`, `CORE`, `SA`, etc.)
+2. If no manifest is available, scan `.planning/phases/` for existing prefixed artifacts such as `TLC-108-PLAN.md` and infer the current repo prefix from those filenames
+3. If neither manifest nor prefixed files are available, fall back to legacy unprefixed detection
+
 From the roadmap, identify:
 
 - The current phase marked as in progress, current, or active
@@ -206,18 +214,22 @@ From the roadmap, identify:
 
 Extract:
 
-- Phase number
+- Phase number / phase ID
 - Phase name
 - Task count if the roadmap or plan exposes it
 - Completed task count if available
 
 ### Step 3: Check Artifacts In The Same Pass
 
-For the active phase `N`, check:
+For the active phase, build the preferred prefixed ID `{PREFIX}-{N}` when a prefix is known. Check artifacts in this order:
 
-- Discussion: `.planning/phases/{N}-DISCUSSION.md`
-- Plan: `.planning/phases/{N}-PLAN.md`
-- Verification: `.planning/phases/{N}-VERIFIED.md`
+- Discussion: `.planning/phases/{PREFIX}-{N}-DISCUSSION.md`, then legacy `.planning/phases/{N}-DISCUSSION.md`
+- Plan: `.planning/phases/{PREFIX}-{N}-PLAN.md`, then legacy `.planning/phases/{N}-PLAN.md`
+- Verification: `.planning/phases/{PREFIX}-{N}-VERIFIED.md`, then legacy `.planning/phases/{N}-VERIFIED.md`
+
+Phase file pattern matching must accept both:
+- Prefixed: `{PREFIX}-{N}-PLAN.md`, `{PREFIX}-{N}-DISCUSSION.md`, `{PREFIX}-{N}-VERIFIED.md`
+- Legacy: `{N}-PLAN.md`, `{N}-DISCUSSION.md`, `{N}-VERIFIED.md`
 
 If the plan exists, inspect it to determine build state:
 
@@ -228,16 +240,20 @@ If the plan exists, inspect it to determine build state:
 Use these state rules:
 
 1. No discussion file:
-   Run `/tlc:discuss {N}`
+   Run `/tlc:discuss {PHASE_ID}`
 2. Discussion exists, no plan:
-   Run `/tlc:plan {N}`
+   Run `/tlc:plan {PHASE_ID}`
 3. Plan exists and phase is not fully built:
-   Run `/tlc:build {N}`
+   Run `/tlc:build {PHASE_ID}`
 4. Build complete, no verification file:
-   Run `/tlc:verify {N}`
+   Run `/tlc:verify {PHASE_ID}`
 5. Verification exists or all phases are complete:
    Suggest release, but do not auto-run it
 
+Backward compatibility:
+- If prefixed artifacts exist, prefer them everywhere in status output and auto-run commands
+- If no prefixed artifacts exist and no workspace manifest is found, continue using legacy unprefixed phase IDs
+
 ## Output Format
 
 Normal output must stay within 3-5 lines.
@@ -245,9 +261,9 @@ Normal output must stay within 3-5 lines.
 Use this pattern:
 
 ```text
-TLC v{version} | Phase {N}: {Name} | {done}/{total} tasks done
+TLC v{version} | Phase {PHASE_ID}: {Name} | {done}/{total} tasks done
 Next: {action summary}
-Running /tlc:{command} {N}...
+Running /tlc:{command} {PHASE_ID}...
 ```
 
 If there is nothing safe to auto-run:
@@ -288,7 +304,7 @@ Auto-run:
 Auto-run:
 
 ```text
-/tlc:plan {N}
+/tlc:plan {PHASE_ID}
 ```
 
 ### Planned, Not Built
@@ -296,7 +312,7 @@ Auto-run:
 Auto-run:
 
 ```text
-/tlc:build {N}
+/tlc:build {PHASE_ID}
 ```
 
 Use the next incomplete task from the plan in the status line when available.
@@ -306,7 +322,7 @@ Use the next incomplete task from the plan in the status line when available.
 Auto-run:
 
 ```text
-/tlc:verify {N}
+/tlc:verify {PHASE_ID}
 ```
 
 ### All Complete
@@ -322,9 +338,9 @@ Run /tlc:complete or /tlc:new-milestone
 ## Example
 
 ```text
-TLC v2.4.2 | Phase 8: Auth System | 3/5 tasks done
+TLC v2.4.2 | Phase TLC-8: Auth System | 3/5 tasks done
 Next: build task 4 (JWT middleware)
-Running /tlc:build 8...
+Running /tlc:build TLC-8...
 ```
 
 ## Summary

package/.claude/commands/tlc/verify.md

@@ -17,6 +17,18 @@ Verify the phase automatically from its plan acceptance criteria, then leave onl
 
 If no phase number, auto-detect current phase.
 
+## Background Dispatch
+
+When the orchestrator is available (`curl -sf http://localhost:3100/health`), dispatch this command to a background agent session instead of running inline.
+
+1. Check orchestrator health
+2. If available: package the full skill prompt with project context (branch, changed files, current phase) and dispatch via `skill-dispatcher.dispatch({ skill: 'verify', prompt, project })`
+3. Report to user: "Dispatched verify to background session ses_XXXX. Results will appear when complete."
+4. When session completes, capture result via `skill-dispatcher.captureResult()` and display summary
+5. If orchestrator unavailable, fall back to inline execution (existing behavior below)
+
+Override: `--inline` flag forces inline execution even when orchestrator is available.
+
 ## Process
 
 ### Step 1: Load the Phase Plan

package/.claude/commands/tlc/watchci.md

@@ -19,6 +19,18 @@ This is the "I pushed, now babysit CI for me" command.
 /tlc:watchci 3          # max 3 fix attempts (default: 5)
 ```
 
+## Background Dispatch
+
+When the orchestrator is available (`curl -sf http://localhost:3100/health`), dispatch this command to a background agent session instead of running inline.
+
+1. Check orchestrator health
+2. If available: package the full skill prompt with project context (branch, changed files, current phase) and dispatch via `skill-dispatcher.dispatch({ skill: 'watchci', prompt, project })`
+3. Report to user: "Dispatched watchci to background session ses_XXXX. Results will appear when complete."
+4. When session completes, capture result via `skill-dispatcher.captureResult()` and display summary
+5. If orchestrator unavailable, fall back to inline execution (existing behavior below)
+
+Override: `--inline` flag forces inline execution even when orchestrator is available.
+
 ## Process
 
 ### Step 1: Find the Active Run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-claude-code",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc-claude-code": "./bin/install.js",

package/scripts/renumber-phases.js

@@ -0,0 +1,283 @@
+const fs = require('fs');
+const path = require('path');
+
+const ALLOWED_SUFFIXES = new Set([
+  'PLAN',
+  'DISCUSSION',
+  'TESTS',
+  'VERIFIED',
+  'TEST-PLAN',
+  'ARCHITECTURE',
+  'COMPLETION-PLAN',
+  'NOTE',
+  'AUDIT-REPORT',
+  'RESEARCH',
+  'DISCUSSION-addendum',
+]);
+
+const PHASE_FILE_PATTERN = /^([A-Za-z0-9]+)-([A-Za-z-]+)\.md(\.superseded)?$/;
+
+function printUsage(stream = process.stderr) {
+  stream.write(
+    'Usage: node scripts/renumber-phases.js --repo-path <path> --prefix <PREFIX> [--dry-run]\n'
+  );
+}
+
+function parseArgs(argv) {
+  const options = {
+    dryRun: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (arg === '--repo-path' || arg === '--prefix') {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error(`Missing value for ${arg}`);
+      }
+
+      if (arg === '--repo-path') {
+        options.repoPath = value;
+      } else {
+        options.prefix = value;
+      }
+
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  if (!options.repoPath || !options.prefix) {
+    throw new Error('Missing required arguments');
+  }
+
+  return options;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function createPhaseReferenceRegex(prefix) {
+  return new RegExp(`\\bPhase\\s+(${escapeRegExp(prefix)}-)?(\\d+[A-Za-z]?)\\b`, 'g');
+}
+
+function updatePhaseReferences(content, prefix) {
+  const regex = createPhaseReferenceRegex(prefix);
+  let replacements = 0;
+
+  const updated = content.replace(regex, (match, existingPrefix, phaseId) => {
+    if (existingPrefix) {
+      return match;
+    }
+
+    replacements += 1;
+    return `Phase ${prefix}-${phaseId}`;
+  });
+
+  return {
+    content: updated,
+    replacements,
+  };
+}
+
+function isEligiblePhaseFile(name, prefix) {
+  const match = name.match(PHASE_FILE_PATTERN);
+  if (!match) {
+    return null;
+  }
+
+  const [, phaseId, suffix, supersededExtension = ''] = match;
+
+  if (phaseId.startsWith(`${prefix}-`)) {
+    return null;
+  }
+
+  if (!/^\d+[A-Za-z]?$/.test(phaseId)) {
+    return null;
+  }
+
+  if (!ALLOWED_SUFFIXES.has(suffix)) {
+    return null;
+  }
+
+  return {
+    phaseId,
+    suffix,
+    supersededExtension,
+  };
+}
+
+function collectOperations(repoPath, prefix) {
+  const phasesDir = path.join(repoPath, '.planning', 'phases');
+  if (!fs.existsSync(phasesDir) || !fs.statSync(phasesDir).isDirectory()) {
+    throw new Error(`Missing phases directory: ${phasesDir}`);
+  }
+
+  const roadmapPath = path.join(repoPath, '.planning', 'ROADMAP.md');
+  const operations = [];
+  const errors = [];
+
+  for (const entry of fs.readdirSync(phasesDir, { withFileTypes: true })) {
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const fileInfo = isEligiblePhaseFile(entry.name, prefix);
+    if (!fileInfo) {
+      continue;
+    }
+
+    const nextName = `${prefix}-${fileInfo.phaseId}-${fileInfo.suffix}.md${fileInfo.supersededExtension}`;
+    operations.push({
+      type: 'rename-file',
+      from: path.join(phasesDir, entry.name),
+      to: path.join(phasesDir, nextName),
+      phaseId: fileInfo.phaseId,
+    });
+  }
+
+  if (fs.existsSync(roadmapPath)) {
+    const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+    const updatedRoadmap = updatePhaseReferences(roadmapContent, prefix);
+
+    if (updatedRoadmap.replacements > 0) {
+      operations.push({
+        type: 'update-file',
+        target: roadmapPath,
+        nextContent: updatedRoadmap.content,
+        replacements: updatedRoadmap.replacements,
+      });
+    }
+  }
+
+  for (const renameOperation of operations.filter((operation) => operation.type === 'rename-file')) {
+    const content = fs.readFileSync(renameOperation.from, 'utf8');
+    const updated = updatePhaseReferences(content, prefix);
+
+    if (updated.replacements > 0) {
+      operations.push({
+        type: 'update-renamed-file',
+        target: renameOperation.to,
+        sourcePath: renameOperation.from,
+        nextContent: updated.content,
+        replacements: updated.replacements,
+      });
+    }
+  }
+
+  for (const renameOperation of operations.filter((operation) => operation.type === 'rename-file')) {
+    if (!fs.existsSync(renameOperation.to)) {
+      continue;
+    }
+
+    errors.push(
+      `Cannot rename ${path.basename(renameOperation.from)} because ${path.basename(renameOperation.to)} already exists`
+    );
+  }
+
+  return {
+    operations,
+    errors,
+  };
+}
+
+function applyOperations(operations, dryRun) {
+  const summary = {
+    renamed: 0,
+    updated: 0,
+  };
+
+  for (const operation of operations) {
+    if (operation.type === 'rename-file') {
+      if (dryRun) {
+        console.log(`DRY-RUN rename ${operation.from} -> ${operation.to}`);
+      } else {
+        fs.renameSync(operation.from, operation.to);
+      }
+
+      summary.renamed += 1;
+      continue;
+    }
+
+    if (operation.type === 'update-file' || operation.type === 'update-renamed-file') {
+      if (dryRun) {
+        console.log(`DRY-RUN update ${operation.target} (${operation.replacements} references)`);
+      } else {
+        fs.writeFileSync(operation.target, operation.nextContent);
+      }
+
+      summary.updated += operation.replacements;
+    }
+  }
+
+  return summary;
+}
+
+function renumberPhases({ repoPath, prefix, dryRun = false }) {
+  const resolvedRepoPath = path.resolve(repoPath);
+  const trimmedPrefix = prefix.trim();
+
+  if (!trimmedPrefix) {
+    throw new Error('Prefix must not be empty');
+  }
+
+  const { operations, errors } = collectOperations(resolvedRepoPath, trimmedPrefix);
+  const summary = applyOperations(operations, dryRun);
+
+  for (const error of errors) {
+    console.error(error);
+  }
+
+  const finalSummary = {
+    renamed: summary.renamed,
+    updated: summary.updated,
+    errors: errors.length,
+  };
+
+  console.log(
+    `Renamed: ${finalSummary.renamed} files, Updated: ${finalSummary.updated} references, Errors: ${finalSummary.errors}`
+  );
+
+  return finalSummary;
+}
+
+function main(argv = process.argv.slice(2)) {
+  try {
+    const options = parseArgs(argv);
+    renumberPhases(options);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+
+    if (message.startsWith('Missing required arguments') || message.startsWith('Missing value for')) {
+      printUsage(process.stderr);
+    }
+
+    console.error(message);
+    return 1;
+  }
+}
+
+if (require.main === module) {
+  process.exit(main());
+}
+
+module.exports = {
+  ALLOWED_SUFFIXES,
+  PHASE_FILE_PATTERN,
+  collectOperations,
+  main,
+  parseArgs,
+  printUsage,
+  renumberPhases,
+  updatePhaseReferences,
+};