tlc-claude-code 2.7.0 → 2.8.0

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

@@ -117,7 +117,7 @@ Claude is the **project manager**. Claude reads the plan, breaks tasks into smal
 
 ### Step O1: Read the Plan
 
-Read `.planning/phases/{N}-PLAN.md`. Extract each task's goal, files, acceptance criteria, and test cases.
+Read `.planning/phases/{PHASE_ID}-PLAN.md`, falling back to legacy `.planning/phases/{N}-PLAN.md` when no prefixed file exists. Extract each task's goal, files, acceptance criteria, and test cases.
 
 ### Step O2: Check Orchestrator Health
 
@@ -395,6 +395,20 @@ This is the core TLC command. Tests before code, one task at a time.
 /tlc:build <phase_number> --agents 5        # Limit parallel agents to 5
 ```
 
+## Phase Resolution
+
+Before loading plans, normalize the phase argument:
+
+1. If the argument is prefixed, such as `CORE-3`, discover the workspace manifest with `server/lib/workspace-manifest.js`, resolve the prefix to a repo, and run the build in that repo directory (for example `../tlc-core`).
+2. If the argument is unprefixed, such as `108`, resolve it to the current repo prefix when the workspace manifest exists, producing `TLC-108` in this repo.
+3. If the prefix is unknown, stop with:
+   `Unknown prefix FOO. Known: TLC, CORE, SA`
+4. If no workspace manifest exists:
+   - Prefixed cross-repo IDs return an error
+   - Unprefixed IDs still work in the current repo for backward compatibility
+
+Use `{PHASE_ID}` for artifact lookup and keep `{phase_number}` as the numeric/local branch component when needed.
+
 ## CodeDB Acceleration
 
 When CodeDB is available (`.mcp.json` has a `codedb` server), use these tools in the scan/search steps below. If CodeDB is unavailable, fall back to Grep/Glob/Read.
@@ -443,7 +457,12 @@ fi
 
 ### Step 1: Load Plans
 
-Read all `.planning/phases/{phase}-*-PLAN.md` files for this phase.
+Read the phase plan using prefixed matching first:
+
+- Preferred: `.planning/phases/{PREFIX}-{N}-PLAN.md`
+- Backward-compatible fallback: `.planning/phases/{N}-PLAN.md`
+
+Do not use the old ambiguous glob `.planning/phases/{phase}-*-PLAN.md` for primary lookup.
 
 ### Step 1a: Auto-Parallel Detection
 

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

@@ -173,6 +173,20 @@ The existing planning instructions below are the Inline Mode instructions and sh
 
 If no phase number, auto-detect current phase from ROADMAP.md.
 
+## Phase Resolution
+
+Before reading or writing phase artifacts, normalize the requested phase argument:
+
+1. If the user passes a prefixed ID such as `CORE-3`, discover the workspace manifest via `server/lib/workspace-manifest.js` and resolve the target repo from the prefix.
+2. If the user passes an unprefixed ID such as `108`, resolve it to the current repo prefix when the workspace manifest is available, producing `TLC-108` in this repo.
+3. If the user passes an unknown prefix, stop with:
+   `Unknown prefix FOO. Known: TLC, CORE, SA`
+4. If no workspace manifest exists:
+   - Prefixed cross-repo IDs return an error because repo resolution is unavailable
+   - Unprefixed IDs still work in the current repo for backward compatibility
+
+When a prefixed ID resolves to another repo, operate in that repo's directory (for example `CORE-3` resolves via the manifest and runs against `../tlc-core`).
+
 ## CodeDB Acceleration
 
 When CodeDB is available (`.mcp.json` has a `codedb` server), use these tools in the scan/search steps below. If CodeDB is unavailable, fall back to Grep/Glob/Read.
@@ -194,7 +208,7 @@ If CodeDB is unavailable, fall back to Grep/Glob/Read.
 
 Read:
 - `.planning/ROADMAP.md` - phase goal
-- `.planning/phases/{N}-DISCUSSION.md` - implementation preferences
+- `.planning/phases/{PHASE_ID}-DISCUSSION.md` - implementation preferences
 - `PROJECT.md` - tech stack, constraints
 
 ### Step 2: Research (if needed)
@@ -204,7 +218,7 @@ For phases requiring external knowledge:
 - Check best practices
 - Identify patterns
 
-Create `.planning/phases/{N}-RESEARCH.md` with findings.
+Create `.planning/phases/{PHASE_ID}-RESEARCH.md` with findings.
 
 ### Step 3: Break Into Tasks
 
@@ -270,10 +284,10 @@ Use `/tlc:claim` to claim a task, `/tlc:release` to release one.
 
 ### Step 4: Create Plan File
 
-Create `.planning/phases/{N}-PLAN.md`:
+Create `.planning/phases/{PHASE_ID}-PLAN.md` using the repo prefix when available, for example `TLC-{N}-PLAN.md`. If no workspace manifest or prefixed artifacts exist, fall back to legacy `{N}-PLAN.md`.
 
 ```markdown
-# Phase {N}: {Name} - Plan
+# Phase {PHASE_ID}: {Name} - Plan
 
 ## Overview
 
@@ -380,7 +394,7 @@ If the result is `true`:
      fs
    });
    console.log(JSON.stringify(r));
-   " ".planning/phases/{N}-PLAN.md" 2>/dev/null
+   " ".planning/phases/{PHASE_ID}-PLAN.md" 2>/dev/null
    ```
 2. Report results: "GitHub: Created N issues, updated M, linked to project board"
 3. If sync fails, warn but do not block: "GitHub sync failed: [reason]. Plan saved locally. Run `/tlc:issues sync` to retry."
@@ -413,7 +427,7 @@ Allow refinement if needed.
 ### Step 6: Save and Continue
 
 ```
-Plan saved to .planning/phases/{N}-PLAN.md
+Plan saved to .planning/phases/{PHASE_ID}-PLAN.md
 
 Ready to build?
 1) Yes, run /tlc:build (writes tests first)

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

@@ -31,26 +31,40 @@ No project found.
 Run /tlc:new-project to start, or /tlc:init to add TLC to existing code.
 ```
 
-### Step 2: Parse Roadmap
+### Step 2: Detect Workspace Scope
 
-Read `.planning/ROADMAP.md` and identify:
+Try to discover a workspace manifest via `server/lib/workspace-manifest.js`.
+
+- If a manifest exists, switch to workspace-wide progress mode
+- Use the manifest `workspace` name in the header
+- Iterate all repos declared in the manifest, listing the current repo first
+- Repos whose paths do not exist on disk must be shown as `[not cloned]`
+- If no manifest exists, fall back to single-repo mode
+
+### Step 3: Parse Roadmap
+
+In single-repo mode, read `.planning/ROADMAP.md` and identify:
 - Total phases
 - Completed phases (marked `[x]` or `[completed]`)
 - Current phase (marked `[>]` or `[current]`)
 - Pending phases
 
-### Step 3: Check Current Phase State
+In workspace-wide mode, do the same per repo and produce a compact repo summary such as:
+
+`TLC: Phase TLC-108 (3/10) | CORE: Phase CORE-1b (idle) | SA: Phase SA-105f (complete)`
+
+### Step 4: Check Current Phase State
 
 For the current/next phase, check what exists:
 
 | File | Meaning |
 |------|---------|
-| `{N}-DISCUSSION.md` | Discussed |
-| `{N}-PLAN.md` | Planned |
-| `{N}-TESTS.md` | Tests written |
-| `{N}-VERIFIED.md` | Human verified |
+| `{PREFIX}-{N}-DISCUSSION.md` or `{N}-DISCUSSION.md` | Discussed |
+| `{PREFIX}-{N}-PLAN.md` or `{N}-PLAN.md` | Planned |
+| `{PREFIX}-{N}-TESTS.md` or `{N}-TESTS.md` | Tests written |
+| `{PREFIX}-{N}-VERIFIED.md` or `{N}-VERIFIED.md` | Human verified |
 
-### Step 4: Run Tests
+### Step 5: Run Tests
 
 Execute test suite and capture:
 - Total tests
@@ -58,7 +72,7 @@ Execute test suite and capture:
 - Failing
 - Skipped
 
-### Step 5: Present Status
+### Step 6: Present Status
 
 ```
 Project: My App
@@ -82,6 +96,18 @@ Tests: 47 total | 45 passing | 2 failing
 Suggested: /tlc:build 4
 ```
 
+When workspace-wide mode is active, prefer a compact workspace summary:
+
+```
+Workspace: tlc-platform
+
+TLC: Phase TLC-108 (3/10) | CORE: Phase CORE-1b (idle) | SA: Phase SA-105f (complete)
+
+[TLC] Tests: 142 total | [CORE] Tests: 38 total | [SA] Tests: 67 total
+
+Next: /tlc in the active repo, or /tlc:build TLC-108
+```
+
 ### Step 5b: Team Status (Multi-User)
 
 If task markers (`[>@user]`, `[x@user]`) exist in PLAN.md, show team activity:
@@ -99,17 +125,17 @@ Parse `[>@user]` and `[x@user]` markers from current phase PLAN.md to build this
 
 If no markers exist, skip this section (single-user mode).
 
-### Step 6: Suggest Next Action
+### Step 7: Suggest Next Action
 
 Based on state:
 
 | State | Suggestion |
 |-------|------------|
-| No discussion | `/tlc:discuss {N}` |
-| Discussed, no plan | `/tlc:plan {N}` |
-| Planned, no tests | `/tlc:build {N}` |
-| Tests failing | Fix failures, then `/tlc:build {N}` |
-| Tests passing, not verified | `/tlc:verify {N}` |
+| No discussion | `/tlc:discuss {PHASE_ID}` |
+| Discussed, no plan | `/tlc:plan {PHASE_ID}` |
+| Planned, no tests | `/tlc:build {PHASE_ID}` |
+| Tests failing | Fix failures, then `/tlc:build {PHASE_ID}` |
+| Tests passing, not verified | `/tlc:verify {PHASE_ID}` |
 | Verified | Move to next phase |
 | All phases done | `/tlc:complete` |
 

package/.claude/commands/tlc/review-pr.md

@@ -72,16 +72,25 @@ Same checks as `/tlc:review`:
 *Automated review by [TLC](https://github.com/jurgencalleja/TLC)*
 ```
 
-### Step 5: Post Review
-
-```bash
-# Post as PR comment
-gh pr comment <number> --body "<review_markdown>"
-
-# Or submit as review
-gh pr review <number> --approve --body "<review_markdown>"
-gh pr review <number> --request-changes --body "<review_markdown>"
-```
+### Step 5: Post Review
+
+```bash
+# Submit approval review first
+if ! gh pr review <number> --approve --body "<review_markdown>" 2>/tmp/pr-review-err; then
+  if grep -q "Can not approve your own pull request" /tmp/pr-review-err; then
+    gh pr comment <number> --body "<review_markdown>"
+    echo "Posted as comment (self-owned PR — GitHub blocks self-approval)"
+  else
+    cat /tmp/pr-review-err
+  fi
+fi
+
+# Post as PR comment directly when comment-only mode is needed
+gh pr comment <number> --body "<review_markdown>"
+
+# Or request changes as a formal review
+gh pr review <number> --request-changes --body "<review_markdown>"
+```
 
 ## Example Output
 

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

@@ -12,9 +12,20 @@ If no phase specified, shows overall test status.
 
 ## Process
 
-1. **Detect test framework** (Vitest, Jest, pytest, etc.)
-2. **Run the test suite**
-3. **Report results** with next action
+1. **Detect workspace scope**
+   - Try `server/lib/workspace-manifest.js`
+   - If a workspace manifest exists, gather test status for every repo in the manifest with the current repo listed first
+   - Repos missing on disk show `[not cloned]`
+   - If no manifest exists, fall back to current-repo-only status
+2. **Detect test framework** (Vitest, Jest, pytest, etc.)
+3. **Run the test suite**
+4. **Report results** with next action
+
+When workspace mode is active, include a one-line summary such as:
+
+```text
+[TLC] 142 tests | [CORE] 38 tests | [SA] 67 tests
+```
 
 ## Output Examples
 
@@ -27,6 +38,15 @@ Test Status
 Ready for: /tlc:verify
 ```
 
+**Workspace-wide:**
+```
+Test Status
+───────────
+[TLC] 142 tests | [CORE] 38 tests | [SA] 67 tests
+
+Ready for: /tlc:verify in the active repo
+```
+
 **Some failing:**
 ```
 Test Status

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-claude-code",
-  "version": "2.7.0",
+  "version": "2.8.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,
+};

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/workspace-manifest.js

@@ -0,0 +1,138 @@
+const fs = require('fs');
+const path = require('path');
+
+const MANIFEST_FILENAME = '.tlc-workspace.json';
+
+/**
+ * Validate the parsed workspace manifest structure.
+ *
+ * @param {object} manifest - Parsed manifest JSON.
+ * @returns {object} The validated manifest object.
+ */
+function validateManifest(manifest) {
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    throw new Error(`Invalid workspace manifest: expected object in ${MANIFEST_FILENAME}`);
+  }
+
+  if (!manifest.repos || typeof manifest.repos !== 'object' || Array.isArray(manifest.repos)) {
+    throw new Error(`Invalid workspace manifest: missing repos key in ${MANIFEST_FILENAME}`);
+  }
+
+  return manifest;
+}
+
+/**
+ * Discover and parse the nearest workspace manifest by walking up the tree.
+ *
+ * @param {string} startDir - Directory to start searching from.
+ * @returns {object|null} Parsed workspace manifest, or null when not found.
+ */
+function discoverWorkspace(startDir) {
+  let currentDir = path.resolve(startDir);
+
+  try {
+    if (!fs.statSync(currentDir).isDirectory()) {
+      currentDir = path.dirname(currentDir);
+    }
+  } catch {
+    currentDir = path.dirname(currentDir);
+  }
+
+  while (true) {
+    const manifestPath = path.join(currentDir, MANIFEST_FILENAME);
+
+    if (fs.existsSync(manifestPath)) {
+      let parsed;
+
+      try {
+        parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      } catch (error) {
+        throw new Error(
+          `Failed to parse workspace manifest at ${manifestPath}: ${error.message}`
+        );
+      }
+
+      return validateManifest(parsed);
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      return null;
+    }
+    currentDir = parentDir;
+  }
+}
+
+/**
+ * Resolve a repository definition by prefix.
+ *
+ * @param {object} manifest - Parsed workspace manifest.
+ * @param {string} prefix - Repo prefix to look up.
+ * @returns {{ path: string, prefix: string, role: string }|null} Repo metadata or null.
+ */
+function resolveRepo(manifest, prefix) {
+  if (!manifest || !manifest.repos || !prefix) {
+    return null;
+  }
+
+  for (const repoConfig of Object.values(manifest.repos)) {
+    if (repoConfig && repoConfig.prefix === prefix) {
+      return {
+        path: repoConfig.path,
+        prefix: repoConfig.prefix,
+        role: repoConfig.role,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve a phase identifier into repo, prefix, and phase components.
+ *
+ * @param {object} manifest - Parsed workspace manifest.
+ * @param {string} phaseId - Phase identifier such as "CORE-2" or "108".
+ * @param {string} currentRepoPrefix - Prefix of the current repo for unprefixed phase IDs.
+ * @returns {{ repo: string, prefix: string, phase: string }|null} Resolved phase metadata or null.
+ */
+function resolvePhase(manifest, phaseId, currentRepoPrefix) {
+  if (!manifest || !manifest.repos || typeof phaseId !== 'string' || phaseId.length === 0) {
+    return null;
+  }
+
+  const prefixedMatch = /^([A-Z]+)-(.+)$/.exec(phaseId);
+  if (prefixedMatch) {
+    const [, prefix, phase] = prefixedMatch;
+
+    for (const [repo, repoConfig] of Object.entries(manifest.repos)) {
+      if (repoConfig && repoConfig.prefix === prefix) {
+        return { repo, prefix, phase };
+      }
+    }
+
+    return null;
+  }
+
+  if (!currentRepoPrefix) {
+    return null;
+  }
+
+  for (const [repo, repoConfig] of Object.entries(manifest.repos)) {
+    if (repoConfig && repoConfig.prefix === currentRepoPrefix) {
+      return {
+        repo,
+        prefix: currentRepoPrefix,
+        phase: phaseId,
+      };
+    }
+  }
+
+  return null;
+}
+
+module.exports = {
+  discoverWorkspace,
+  resolveRepo,
+  resolvePhase,
+};

package/server/lib/workspace-manifest.test.js

@@ -0,0 +1,179 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const {
+  discoverWorkspace,
+  resolveRepo,
+  resolvePhase,
+} = await import('./workspace-manifest.js');
+
+function makeTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'workspace-manifest-'));
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2));
+}
+
+function removeDir(dirPath) {
+  fs.rmSync(dirPath, { recursive: true, force: true });
+}
+
+function createManifest(overrides = {}) {
+  return {
+    workspace: 'tlc-platform',
+    repos: {
+      TLC: { path: 'TLC', prefix: 'TLC', role: 'Runtime library' },
+      'tlc-core': { path: 'tlc-core', prefix: 'CORE', role: 'Execution substrate' },
+      'tlc-standalone': {
+        path: 'tlc-standalone',
+        prefix: 'SA',
+        role: 'Provider-agnostic CLI',
+      },
+    },
+    orchestrator: { url: 'http://localhost:3100', provider: 'tlc-core' },
+    ...overrides,
+  };
+}
+
+describe('workspace-manifest', () => {
+  const tempDirs = [];
+
+  afterEach(() => {
+    while (tempDirs.length > 0) {
+      removeDir(tempDirs.pop());
+    }
+  });
+
+  it('discoverWorkspace from subdirectory finds manifest at parent', () => {
+    const rootDir = makeTmpDir();
+    tempDirs.push(rootDir);
+
+    const nestedDir = path.join(rootDir, 'TLC', 'server', 'lib');
+    fs.mkdirSync(nestedDir, { recursive: true });
+    writeJson(path.join(rootDir, '.tlc-workspace.json'), createManifest());
+
+    const manifest = discoverWorkspace(nestedDir);
+
+    expect(manifest).not.toBeNull();
+    expect(manifest.workspace).toBe('tlc-platform');
+    expect(manifest.repos.TLC.path).toBe('TLC');
+    expect(manifest.repos['tlc-core'].prefix).toBe('CORE');
+  });
+
+  it('resolveRepo("CORE") returns tlc-core metadata', () => {
+    const manifest = createManifest();
+
+    expect(resolveRepo(manifest, 'CORE')).toEqual({
+      path: 'tlc-core',
+      prefix: 'CORE',
+      role: 'Execution substrate',
+    });
+  });
+
+  it('resolvePhase("CORE-2") parses correctly', () => {
+    const manifest = createManifest();
+
+    expect(resolvePhase(manifest, 'CORE-2', 'TLC')).toEqual({
+      repo: 'tlc-core',
+      prefix: 'CORE',
+      phase: '2',
+    });
+  });
+
+  it('resolvePhase("108", "TLC") returns TLC-108', () => {
+    const manifest = createManifest();
+
+    expect(resolvePhase(manifest, '108', 'TLC')).toEqual({
+      repo: 'TLC',
+      prefix: 'TLC',
+      phase: '108',
+    });
+  });
+
+  it('discoverWorkspace from /tmp returns null when no manifest exists in tree', () => {
+    const rootDir = makeTmpDir();
+    tempDirs.push(rootDir);
+
+    const nestedDir = path.join(rootDir, 'lonely', 'child');
+    fs.mkdirSync(nestedDir, { recursive: true });
+
+    expect(discoverWorkspace(nestedDir)).toBeNull();
+  });
+
+  it('resolveRepo("UNKNOWN") returns null', () => {
+    const manifest = createManifest();
+
+    expect(resolveRepo(manifest, 'UNKNOWN')).toBeNull();
+  });
+
+  it('resolvePhase("NOPE-1") returns null', () => {
+    const manifest = createManifest();
+
+    expect(resolvePhase(manifest, 'NOPE-1', 'TLC')).toBeNull();
+  });
+
+  it('invalid JSON throws descriptive error', () => {
+    const rootDir = makeTmpDir();
+    tempDirs.push(rootDir);
+
+    fs.writeFileSync(
+      path.join(rootDir, '.tlc-workspace.json'),
+      '{"workspace":"tlc-platform","repos":'
+    );
+
+    expect(() => discoverWorkspace(rootDir)).toThrow(/parse workspace manifest/i);
+  });
+
+  it('manifest missing repos key throws descriptive error', () => {
+    const rootDir = makeTmpDir();
+    tempDirs.push(rootDir);
+
+    writeJson(path.join(rootDir, '.tlc-workspace.json'), {
+      workspace: 'tlc-platform',
+      orchestrator: { url: 'http://localhost:3100', provider: 'tlc-core' },
+    });
+
+    expect(() => discoverWorkspace(rootDir)).toThrow(/missing repos key/i);
+  });
+
+  it('discoverWorkspace accepts a file path and searches from its parent directory', () => {
+    const rootDir = makeTmpDir();
+    tempDirs.push(rootDir);
+
+    const repoDir = path.join(rootDir, 'TLC');
+    const filePath = path.join(repoDir, 'server', 'lib', 'workspace-manifest.js');
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, '// fixture');
+    writeJson(path.join(rootDir, '.tlc-workspace.json'), createManifest());
+
+    const manifest = discoverWorkspace(filePath);
+
+    expect(manifest.repos['tlc-standalone']).toEqual({
+      path: 'tlc-standalone',
+      prefix: 'SA',
+      role: 'Provider-agnostic CLI',
+    });
+  });
+
+  it('resolvePhase returns null for unprefixed phase when current repo prefix is unknown', () => {
+    const manifest = createManifest();
+
+    expect(resolvePhase(manifest, '108', 'NOPE')).toBeNull();
+  });
+
+  it('resolvePhase returns null when current repo prefix is not provided for unprefixed phase', () => {
+    const manifest = createManifest();
+
+    expect(resolvePhase(manifest, '108')).toBeNull();
+  });
+
+  it('resolveRepo returns null when prefix is missing', () => {
+    const manifest = createManifest();
+
+    expect(resolveRepo(manifest)).toBeNull();
+    expect(resolveRepo(manifest, '')).toBeNull();
+  });
+});