tlc-claude-code 2.4.1 → 2.4.3

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

@@ -10,12 +10,76 @@ This command supports multi-model routing via `~/.tlc/config.json`.
 
 1. Read routing config:
    ```bash
-   node -e "
-     const { resolveRouting } = require('./server/lib/task-router-config');
-     const flagModel = (process.argv.find(a => a.startsWith("--model")) || "").replace("--model=", "").replace("--model ", "") || null;
-     const r = resolveRouting({ command: 'plan', flagModel, projectDir: process.cwd(), homeDir: process.env.HOME });
-     console.log(JSON.stringify(r));
-   " 2>/dev/null
+   node -e "const fs = require('fs');
+const path = require('path');
+const os = require('os');
+function readJson(filePath, fileSystem) {
+  try {
+    return JSON.parse(fileSystem.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+function loadPersonalConfig(options) {
+  const configPath = path.join(options.homeDir, '.tlc', 'config.json');
+  return readJson(configPath, options.fs);
+}
+function loadProjectOverride(options) {
+  const configPath = path.join(options.projectDir, '.tlc.json');
+  const data = readJson(configPath, options.fs);
+  return data && data.task_routing_override ? data.task_routing_override : null;
+}
+function resolveRouting(options) {
+  let models = ['claude'];
+  let strategy = 'single';
+  let source = 'shipped-defaults';
+  let providers;
+  const personal = loadPersonalConfig({ homeDir: options.homeDir, fs: options.fs });
+  if (personal) {
+    if (personal.model_providers) {
+      providers = personal.model_providers;
+    }
+    const personalRouting = personal.task_routing && personal.task_routing[options.command];
+    if (personalRouting) {
+      if (Array.isArray(personalRouting.models)) {
+        models = personalRouting.models.slice();
+      } else if (typeof personalRouting.model === 'string') {
+        models = [personalRouting.model];
+      }
+      if (personalRouting.strategy) {
+        strategy = personalRouting.strategy;
+      }
+      source = 'personal-config';
+    }
+  }
+  const projectOverride = loadProjectOverride({ projectDir: options.projectDir, fs: options.fs });
+  if (projectOverride) {
+    const overrideEntry = projectOverride[options.command];
+    if (overrideEntry) {
+      if (Array.isArray(overrideEntry.models)) {
+        models = overrideEntry.models.slice();
+      } else if (typeof overrideEntry.model === 'string') {
+        models = [overrideEntry.model];
+      }
+      if (overrideEntry.strategy) {
+        strategy = overrideEntry.strategy;
+      }
+      source = 'project-override';
+    }
+  }
+  if (options.flagModel) {
+    models = [options.flagModel];
+    strategy = 'single';
+    source = 'flag-override';
+  }
+  const result = { models, strategy, source };
+  if (providers) {
+    result.providers = providers;
+  }
+  return result;
+}
+const result = resolveRouting({ command: \"plan\", flagModel: process.argv[1], projectDir: process.cwd(), homeDir: process.env.HOME || os.homedir(), fs });
+process.stdout.write(JSON.stringify(result));" 2>/dev/null
    ```
 
 2. If `models[0]` is NOT `claude` (i.e., routed to external model):
@@ -47,6 +111,7 @@ This command supports multi-model routing via `~/.tlc/config.json`.
 - **Extension points**: Where will this need to grow? Plan for it.
 - **Error boundaries**: Where can failures occur? How are they handled?
 - **Data flow**: How does data enter, transform, and exit the system?
+- **Outcome constraints**: Define required behaviors, scale limits, latency targets, and failure handling. Avoid prescribing implementation mechanics unless a constraint is already fixed by the system.
 
 ### Code Quality Gates
 - **File size limit**: No file should exceed 1000 lines. Plan splits for large modules.
@@ -58,6 +123,7 @@ This command supports multi-model routing via `~/.tlc/config.json`.
 - **Vertical slices**: Each task delivers testable, visible progress
 - **Risk-first**: Tackle unknowns and integrations early
 - **Dependencies explicit**: Mark what blocks what
+- **Strategic purpose clear**: Every task explains why it exists, what risk it retires, or what capability it unlocks
 
 ## What This Does
 
@@ -99,12 +165,21 @@ Each task should be:
 - **Testable** - has clear pass/fail criteria
 - **Independent** - minimal dependencies on other tasks
 - **Standards-compliant** - won't produce files >1000 lines or folders >15 files
+- **Strategically justified** - includes the problem solved and why this task matters now
 
 **Before finalizing tasks, check:**
 1. Will any planned file exceed 1000 lines? → Split into sub-modules
 2. Will any folder exceed 15 files? → Plan domain subfolders
 3. Are all interfaces defined? → Add `interfaces/` directory per module
 4. Are types explicit? → Plan typed interfaces, not `any`
+5. Do acceptance criteria describe outcomes instead of implementation? → Rewrite "use X" into "must achieve Y"
+6. Are any files likely to grow past 1000 lines after follow-on tasks? → Add a warning and split plan now, not later
+
+**When estimating file and folder impact:**
+- Check existing target files and folders before assigning work
+- Include projected growth from all tasks in the phase, not only the current task
+- Add an explicit warning in the plan if any task is likely to create or expand a file beyond 1000 lines
+- Prefer splitting by domain responsibility before implementation starts
 
 #### Task Status Markers (Multi-User)
 
@@ -125,6 +200,8 @@ Use `/tlc:claim` to claim a task, `/tlc:release` to release one.
 
 **Goal:** Define database schema for users table
 
+**Strategic Purpose:** Establish the canonical user data contract early so authentication, profile management, and downstream integrations build on a stable foundation.
+
 **Files:**
 - src/modules/user/interfaces/user.interface.ts
 - src/modules/user/user.repository.ts
@@ -135,6 +212,7 @@ Use `/tlc:claim` to claim a task, `/tlc:release` to release one.
 - [ ] Timestamps auto-populate
 - [ ] All types explicit (no `any`)
 - [ ] Exported functions have return types
+- [ ] Criteria describe observable outcomes and constraints, not implementation choices
 
 **Test Cases:**
 - Schema validates correct user data
@@ -157,18 +235,35 @@ Create `.planning/phases/{N}-PLAN.md`:
 
 - [ ] {Any setup or prior work needed}
 
+## Risk Assessment
+
+- **Unknowns:** {Unclear requirements, technical unknowns, external dependencies}
+- **Integration Points:** {Systems, modules, APIs, data contracts, migrations}
+- **Potential Failures:** {What could break, degrade, or block delivery}
+- **Mitigations:** {How the plan reduces or contains those risks}
+
+## Decision Log
+
+| Decision | Rationale | Alternatives Considered | Consequence |
+|----------|-----------|--------------------------|-------------|
+| {Architectural choice} | {Why this is the best fit now} | {What else was considered} | {Tradeoff or follow-on impact} |
+
 ## Tasks
 
 ### Task 1: {Title}
 
 **Goal:** {What this accomplishes}
 
+**Strategic Purpose:** {Why this task matters, what problem it solves, or what later work it unlocks}
+
 **Files:**
 - {files to create/modify}
+- {note if any file is at risk of exceeding 1000 lines and how the plan avoids it}
 
 **Acceptance Criteria:**
-- [ ] {Testable criterion 1}
-- [ ] {Testable criterion 2}
+- [ ] {Observable behavior or outcome 1}
+- [ ] {Observable behavior, scale constraint, latency target, or failure-handling outcome 2}
+- [ ] {No criterion prescribes implementation details unless already mandated by project constraints}
 
 **Test Cases:**
 - {Test description 1}
@@ -184,11 +279,21 @@ Create `.planning/phases/{N}-PLAN.md`:
 
 {Task dependencies if any - e.g., Task 3 requires Task 1}
 
+## Definition of Done
+
+| Dimension | Definition |
+|-----------|------------|
+| Behavior Change | {What users, operators, or dependent systems can now do differently} |
+| Tests | {Unit, integration, end-to-end, contract, or manual checks required} |
+| Failure Modes | {Known failure paths handled and verified} |
+| Rollback | {How the change can be reverted or disabled safely if needed} |
+
 ## Estimated Scope
 
 - Tasks: {N}
 - Files: {N}
 - Tests: ~{N} (estimated)
+- File size warnings: {None / list any files projected to exceed 1000 lines and planned split}
 ```
 
 ### Step 5: Review Plan
@@ -205,6 +310,9 @@ Tasks: 4
 4. Add loading/error states
 
 Estimated tests: 12
+Key risks: 2 integration points, 1 unresolved dependency
+Architecture decisions logged: 3
+File size warnings: none
 
 Proceed with this plan? (Y/n)
 ```
@@ -230,12 +338,15 @@ Task: Create login API endpoint
 - Validates email/password
 - Returns JWT token
 - Handles invalid credentials
+- Explains why login is needed now and what downstream work it unlocks
+- Defines outcomes such as response behavior, error handling, and throughput constraints
 ```
 
 **Bad tasks:**
 ```
 Task: Build auth system  <- too big
 Task: Add login          <- too vague
+Task: Use Redis cache    <- prescribes implementation, not outcome
 ```
 
 ## Example Output
@@ -247,12 +358,27 @@ Task: Add login          <- too vague
 
 User registration and login with JWT tokens.
 
+## Risk Assessment
+
+- **Unknowns:** Final session expiry requirements and auth provider migration timeline
+- **Integration Points:** Database schema, password hashing, token issuance, API error contracts
+- **Potential Failures:** Duplicate users, weak validation, token leakage, incompatible response shapes
+- **Mitigations:** Lock contracts early, validate edge cases, test failure paths before wiring UI
+
+## Decision Log
+
+| Decision | Rationale | Alternatives Considered | Consequence |
+|----------|-----------|--------------------------|-------------|
+| Use separate schema and endpoint tasks | Reduces coupling and surfaces auth contract risks early | Single end-to-end auth task | More handoff points, but lower integration risk |
+
 ## Tasks
 
 ### Task 1: Create user schema
 
 **Goal:** Database schema for users
 
+**Strategic Purpose:** Create the source-of-truth user contract first so registration, login, and profile features depend on one stable model instead of diverging assumptions.
+
 **Files:**
 - src/db/schema/users.ts
 - src/db/migrations/001_users.sql
@@ -261,6 +387,7 @@ User registration and login with JWT tokens.
 - [ ] Has id, email, passwordHash, createdAt, updatedAt
 - [ ] Email unique constraint
 - [ ] Password hashed with bcrypt
+- [ ] User creation rules are expressed as observable schema outcomes, not storage implementation notes
 
 **Test Cases:**
 - Schema accepts valid user data
@@ -273,6 +400,8 @@ User registration and login with JWT tokens.
 
 **Goal:** POST /api/auth/register
 
+**Strategic Purpose:** Deliver the first externally usable auth capability and validate that schema, validation, and response contracts work together under real request flows.
+
 **Files:**
 - src/api/auth/register.ts
 - src/lib/auth/password.ts
@@ -282,10 +411,20 @@ User registration and login with JWT tokens.
 - [ ] Returns user without password
 - [ ] Rejects existing email with 409
 - [ ] Validates email format
+- [ ] Handles invalid and duplicate registration attempts with stable API behavior under concurrent requests
 
 **Test Cases:**
 - Register with valid data returns user
 - Register with existing email returns 409
 - Register with invalid email returns 400
 - Password stored as hash
+
+## Definition of Done
+
+| Dimension | Definition |
+|-----------|------------|
+| Behavior Change | Users can register and authenticate through stable API contracts |
+| Tests | Schema, endpoint, validation, and concurrency-sensitive duplicate-user paths are covered |
+| Failure Modes | Duplicate email, invalid payloads, and password exposure paths are rejected safely |
+| Rollback | Auth routes can be disabled and schema migration reverted with a documented backout path |
 ```

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

@@ -10,12 +10,76 @@ This command supports multi-model routing via `~/.tlc/config.json`.
 
 1. Read routing config:
    ```bash
-   node -e "
-     const { resolveRouting } = require('./server/lib/task-router-config');
-     const flagModel = (process.argv.find(a => a.startsWith("--model")) || "").replace("--model=", "").replace("--model ", "") || null;
-     const r = resolveRouting({ command: 'quick', flagModel, projectDir: process.cwd(), homeDir: process.env.HOME });
-     console.log(JSON.stringify(r));
-   " 2>/dev/null
+   node -e "const fs = require('fs');
+const path = require('path');
+const os = require('os');
+function readJson(filePath, fileSystem) {
+  try {
+    return JSON.parse(fileSystem.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+function loadPersonalConfig(options) {
+  const configPath = path.join(options.homeDir, '.tlc', 'config.json');
+  return readJson(configPath, options.fs);
+}
+function loadProjectOverride(options) {
+  const configPath = path.join(options.projectDir, '.tlc.json');
+  const data = readJson(configPath, options.fs);
+  return data && data.task_routing_override ? data.task_routing_override : null;
+}
+function resolveRouting(options) {
+  let models = ['claude'];
+  let strategy = 'single';
+  let source = 'shipped-defaults';
+  let providers;
+  const personal = loadPersonalConfig({ homeDir: options.homeDir, fs: options.fs });
+  if (personal) {
+    if (personal.model_providers) {
+      providers = personal.model_providers;
+    }
+    const personalRouting = personal.task_routing && personal.task_routing[options.command];
+    if (personalRouting) {
+      if (Array.isArray(personalRouting.models)) {
+        models = personalRouting.models.slice();
+      } else if (typeof personalRouting.model === 'string') {
+        models = [personalRouting.model];
+      }
+      if (personalRouting.strategy) {
+        strategy = personalRouting.strategy;
+      }
+      source = 'personal-config';
+    }
+  }
+  const projectOverride = loadProjectOverride({ projectDir: options.projectDir, fs: options.fs });
+  if (projectOverride) {
+    const overrideEntry = projectOverride[options.command];
+    if (overrideEntry) {
+      if (Array.isArray(overrideEntry.models)) {
+        models = overrideEntry.models.slice();
+      } else if (typeof overrideEntry.model === 'string') {
+        models = [overrideEntry.model];
+      }
+      if (overrideEntry.strategy) {
+        strategy = overrideEntry.strategy;
+      }
+      source = 'project-override';
+    }
+  }
+  if (options.flagModel) {
+    models = [options.flagModel];
+    strategy = 'single';
+    source = 'flag-override';
+  }
+  const result = { models, strategy, source };
+  if (providers) {
+    result.providers = providers;
+  }
+  return result;
+}
+const result = resolveRouting({ command: \"quick\", flagModel: process.argv[1], projectDir: process.cwd(), homeDir: process.env.HOME || os.homedir(), fs });
+process.stdout.write(JSON.stringify(result));" 2>/dev/null
    ```
 
 2. If `models[0]` is NOT `claude` (i.e., routed to external model):

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

@@ -10,12 +10,76 @@ This command supports multi-model routing via `~/.tlc/config.json`.
 
 1. Read routing config:
    ```bash
-   node -e "
-     const { resolveRouting } = require('./server/lib/task-router-config');
-     const flagModel = (process.argv.find(a => a.startsWith("--model")) || "").replace("--model=", "").replace("--model ", "") || null;
-     const r = resolveRouting({ command: 'review', flagModel, projectDir: process.cwd(), homeDir: process.env.HOME });
-     console.log(JSON.stringify(r));
-   " 2>/dev/null
+   node -e "const fs = require('fs');
+const path = require('path');
+const os = require('os');
+function readJson(filePath, fileSystem) {
+  try {
+    return JSON.parse(fileSystem.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+function loadPersonalConfig(options) {
+  const configPath = path.join(options.homeDir, '.tlc', 'config.json');
+  return readJson(configPath, options.fs);
+}
+function loadProjectOverride(options) {
+  const configPath = path.join(options.projectDir, '.tlc.json');
+  const data = readJson(configPath, options.fs);
+  return data && data.task_routing_override ? data.task_routing_override : null;
+}
+function resolveRouting(options) {
+  let models = ['claude'];
+  let strategy = 'single';
+  let source = 'shipped-defaults';
+  let providers;
+  const personal = loadPersonalConfig({ homeDir: options.homeDir, fs: options.fs });
+  if (personal) {
+    if (personal.model_providers) {
+      providers = personal.model_providers;
+    }
+    const personalRouting = personal.task_routing && personal.task_routing[options.command];
+    if (personalRouting) {
+      if (Array.isArray(personalRouting.models)) {
+        models = personalRouting.models.slice();
+      } else if (typeof personalRouting.model === 'string') {
+        models = [personalRouting.model];
+      }
+      if (personalRouting.strategy) {
+        strategy = personalRouting.strategy;
+      }
+      source = 'personal-config';
+    }
+  }
+  const projectOverride = loadProjectOverride({ projectDir: options.projectDir, fs: options.fs });
+  if (projectOverride) {
+    const overrideEntry = projectOverride[options.command];
+    if (overrideEntry) {
+      if (Array.isArray(overrideEntry.models)) {
+        models = overrideEntry.models.slice();
+      } else if (typeof overrideEntry.model === 'string') {
+        models = [overrideEntry.model];
+      }
+      if (overrideEntry.strategy) {
+        strategy = overrideEntry.strategy;
+      }
+      source = 'project-override';
+    }
+  }
+  if (options.flagModel) {
+    models = [options.flagModel];
+    strategy = 'single';
+    source = 'flag-override';
+  }
+  const result = { models, strategy, source };
+  if (providers) {
+    result.providers = providers;
+  }
+  return result;
+}
+const result = resolveRouting({ command: \"review\", flagModel: process.argv[1], projectDir: process.cwd(), homeDir: process.env.HOME || os.homedir(), fs });
+process.stdout.write(JSON.stringify(result));" 2>/dev/null
    ```
 
 2. If `models[0]` is NOT `claude` (i.e., routed to external model):