tlc-claude-code 2.4.9 → 2.5.0

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

@@ -57,6 +57,11 @@ Run `auditProject(projectPath)` which executes:
 | **Secrets in Responses** | Response objects containing fields named `apiKey`, `secret`, `token`, `password` | error |
 | **Manual Instantiation** | `new .*Provider(` or `new .*Service(` in application code | warning |
 | **Missing Ownership Check** | Controller methods with `@Param('id')` but no ownership/authorization guard | warning |
+| **Empty Catch Blocks** | `catch (e) {}` or `catch { }` with no logging or rethrow | error |
+| **Silent Error Returns** | `catch (e) { return null/undefined/false }` without logging | error |
+| **Missing Error Handling** | External calls (HTTP, DB, Docker, file I/O, spawn) without try/catch | error |
+| **No Connection Logging** | DB/Redis/WebSocket/Docker connections without connect/disconnect/error logging | warning |
+| **Bare console.log Errors** | `console.log(error)` instead of structured logging with context | warning |
 
 ### Step 3: Generate Report
 

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

@@ -96,6 +96,10 @@ process.stdout.write(JSON.stringify(result));" 2>/dev/null
    - Execute inline (Claude) AND dispatch each external provider via `dispatch` from `orchestration/cli-dispatch`
    - After each provider completes, capture its output with `captureFromProvider` from `capture`
    - Collect and merge results
+   - **CRITICAL: If a provider fails (wrong model, auth error, CLI missing), do NOT silently fall back to single-provider.** Instead:
+     1. Check `.tlc/.router-state.json` for the provider's actual available model and retry
+     2. If retry fails, ask the user: "[Provider] failed: [reason]. Run with [other provider] only, or fix and retry?"
+     3. Never say "proceeding with X-only" without user consent
 
 **Override:** Pass `--model <name>` to route this specific run to a different model.
 
@@ -210,19 +214,25 @@ function processOrder(order) {
 - **JSDoc for public API**: Parameters, returns, throws, examples.
 - **No obvious comments**: `// increment i` before `i++` is noise.
 
-### Error Handling
+### Error Handling (Zero Silent Failures)
+- **Every catch block must be visible**: Log with context OR rethrow. No exceptions.
 - **Specific error types**: `UserNotFoundError` not generic `Error`.
-- **Actionable messages**: "User 'abc123' not found" not "Not found".
-- **Don't swallow errors**: Log or rethrow, never empty catch blocks.
+- **Actionable messages**: "User 'abc123' not found in database 'users'" not "Not found".
+- **Don't swallow errors**: Log or rethrow, never empty catch blocks. This is the #1 cause of production bugs.
 - **Error boundaries**: Catch at appropriate level, not everywhere.
 - **User vs developer errors**: Different messages for each audience.
-
-### Logging Standards
-- **Structured logging**: JSON format with consistent fields.
-- **Log levels**: ERROR (failures), WARN (concerning), INFO (business events), DEBUG (troubleshooting).
-- **Context**: Include request ID, user ID, relevant entity IDs.
+- **External calls MUST have error handling**: HTTP, DB, Docker, file I/O, CLI spawn — every one gets try/catch with logging.
+
+### Observability (CRITICAL — silent failures are unacceptable)
+- **No empty catch blocks**: Every `catch` must log with context OR rethrow. `catch (e) {}` is never acceptable.
+- **No silent returns**: `catch (e) { return null }` without logging is a bug. Log first, then return.
+- **Structured logging**: JSON format: `{ level, message, context, error, timestamp }`.
+- **Log levels**: ERROR (failures needing attention), WARN (degraded but working), INFO (business events), DEBUG (troubleshooting).
+- **Context in every log**: Include what operation failed, what inputs caused it, what the caller should know.
+- **Connection state logging**: Every external connection (DB, Redis, Docker, WebSocket, HTTP client, queue) must log: connect, disconnect, reconnect, and failure. Connection state changes are INFO level, not DEBUG.
+- **Startup health**: Log the state of every dependency on startup. "Connected to Postgres", "Docker socket accessible", "Redis: connection refused". Never start silently.
 - **No sensitive data**: Never log passwords, tokens, PII.
-- **Performance**: Don't log in tight loops.
+- **Performance**: Don't log in tight loops. Do log every error, even in loops.
 
 ### Performance Awareness
 - **O(n) thinking**: Know the complexity of your algorithms. Avoid nested loops on large datasets.
@@ -270,8 +280,7 @@ This is the core TLC command. Tests before code, one task at a time.
 ```
 /tlc:build <phase_number>
 /tlc:build <phase_number> --sequential      # Force sequential mode
-/tlc:build <phase_number> --model sonnet    # Force all agents to use sonnet
-/tlc:build <phase_number> --model haiku     # Force all agents to use haiku (fast/cheap)
+/tlc:build <phase_number> --model opus      # All agents use opus (this is the default)
 /tlc:build <phase_number> --max-turns 30    # Limit agent execution length
 /tlc:build <phase_number> --agents 5        # Limit parallel agents to 5
 ```
@@ -327,7 +336,7 @@ After loading plans, analyze task dependencies and available providers to pick t
 |-----------|----------|--------------|
 | 2+ independent tasks, Claude + Codex available, tmux available | **Worktree + Tmux** | Each task gets own git worktree + tmux pane. Claude and Codex work simultaneously. |
 | 2+ independent tasks, Claude + Codex available, no tmux | **Worktree + Background** | Same but without tmux visibility. |
-| 2+ independent tasks, single provider only | **In-process agents** | Agent tool spawns parallel sub-agents (sonnet/haiku by complexity). |
+| 2+ independent tasks, single provider only | **In-process agents** | Agent tool spawns parallel sub-agents (all opus). |
 | All tasks have dependencies | **Sequential** | One task at a time, in dependency order. |
 | 1 task only | **Sequential** | Just build it. |
 
@@ -353,9 +362,9 @@ Providers: claude (1 available)
 Strategy: in-process agents (parallel)
 
   Task 1: Create user schema         → opus   (heavy)
-  Task 2: Add validation helpers     → sonnet (standard)
-  Task 3: Write migration scripts    → sonnet (standard)
-  Task 4: Create seed data           → haiku  (light)
+  Task 2: Add validation helpers     → opus (standard)
+  Task 3: Write migration scripts    → opus (standard)
+  Task 4: Create seed data           → opus  (light)
 
 Launching...
 ```
@@ -371,12 +380,13 @@ Strategy: sequential
 Starting Task 1...
 ```
 
-**Model auto-selection (in-process agent mode):**
-| Complexity | Model | When |
-|-----------|-------|------|
-| Heavy | opus | Architecture, multi-file features, security, auth, database |
-| Standard | sonnet | Normal implementation tasks (default) |
-| Light | haiku | Config, boilerplate, DTOs, enums, constants, seed data |
+**Model selection (in-process agent mode):**
+
+All agents use **opus**. No opus, no opus. Cost is not a concern — quality is.
+
+| Task | Model |
+|------|-------|
+| Any | opus |
 
 **Provider round-robin (worktree mode):**
 Tasks alternate between available providers. If Claude + Codex are both available, odd tasks go to Claude, even to Codex. Respects router state — never dispatches to unavailable providers.
@@ -391,9 +401,9 @@ Tasks alternate between available providers. If Claude + Codex are both availabl
 Spawning 4 agents in parallel...
 
 Agent 1: Task 1 - Create user schema          [opus]
-Agent 2: Task 2 - Add validation helpers      [sonnet]
-Agent 3: Task 3 - Write migration scripts     [sonnet]
-Agent 4: Task 4 - Create seed data            [haiku]
+Agent 2: Task 2 - Add validation helpers      [opus]
+Agent 3: Task 3 - Write migration scripts     [opus]
+Agent 4: Task 4 - Create seed data            [opus]
 
 [All agents spawned - working in background]
 ```
@@ -410,9 +420,9 @@ Agent 4: Task 4 - Create seed data            [haiku]
 
 ```
 Task(description="Agent 1: Task 1", prompt="...", subagent_type="general-purpose", model="opus", max_turns=50, run_in_background=true)
-Task(description="Agent 2: Task 2", prompt="...", subagent_type="general-purpose", model="sonnet", max_turns=50, run_in_background=true)
-Task(description="Agent 3: Task 3", prompt="...", subagent_type="general-purpose", model="sonnet", max_turns=50, run_in_background=true)
-Task(description="Agent 4: Task 4", prompt="...", subagent_type="general-purpose", model="haiku", max_turns=50, run_in_background=true)
+Task(description="Agent 2: Task 2", prompt="...", subagent_type="general-purpose", model="opus", max_turns=50, run_in_background=true)
+Task(description="Agent 3: Task 3", prompt="...", subagent_type="general-purpose", model="opus", max_turns=50, run_in_background=true)
+Task(description="Agent 4: Task 4", prompt="...", subagent_type="general-purpose", model="opus", max_turns=50, run_in_background=true)
 ```
 
 **Live Progress Monitoring (TaskOutput):**
@@ -443,9 +453,9 @@ Display format:
 | Agent | Task | Model | Tests | Phase |
 |-------|------|-------|-------|-------|
 | a1b2c3 | User Schema | opus | 29 ✓ | committed |
-| d4e5f6 | Validation | sonnet | 18 ✓ | implementing |
-| g7h8i9 | Migrations | sonnet | - | writing-tests |
-| j0k1l2 | Seed Data | haiku | 5 ✓ | committed |
+| d4e5f6 | Validation | opus | 18 ✓ | implementing |
+| g7h8i9 | Migrations | opus | - | writing-tests |
+| j0k1l2 | Seed Data | opus | 5 ✓ | committed |
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -781,6 +791,33 @@ Review the task's:
 - Acceptance criteria
 - Test cases (now written and failing)
 
+#### 7a-gh. GitHub: Mark In Progress
+
+If GitHub sync is enabled, update the linked GitHub issue for this task:
+
+```bash
+node -e "
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+let gh;
+try { gh = require('tlc-claude-code/server/lib/github'); }
+catch { gh = require(path.join(process.cwd(), 'server/lib/github')); }
+try {
+  const cfg = gh.loadGitHubConfig(process.cwd(), { fs }).config;
+  if (!cfg) process.exit(0);
+  const exec = (cmd) => execSync(cmd, { encoding: 'utf-8', stdio: ['pipe','pipe','pipe'] });
+  const user = execSync('git config user.name', { encoding: 'utf-8' }).trim();
+  const issueNumber = process.argv[1];
+  if (issueNumber) {
+    gh.assignIssue({ owner: cfg.owner, repo: cfg.repo, number: Number(issueNumber), assignees: [user], exec });
+  }
+} catch (e) { console.error('[TLC] GitHub status update failed:', e.message); }
+" "{issue_number}" 2>/dev/null
+```
+
+If no issue is linked to this task, skip silently. Failures warn but never block.
+
 #### 7b. Implement the code
 Write the minimum code needed to pass the tests:
 - Create files specified in the task
@@ -822,6 +859,35 @@ This keeps the plan file as the single source of truth for task status. Do NOT w
 
 If in multi-user mode, also push to share progress with team.
 
+#### 7e-gh. GitHub: Mark Done
+
+If GitHub sync is enabled, update the linked issue status after marking the task `[x]`:
+
+```bash
+node -e "
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+let gh;
+try { gh = require('tlc-claude-code/server/lib/github'); }
+catch { gh = require(path.join(process.cwd(), 'server/lib/github')); }
+try {
+  const cfg = gh.loadGitHubConfig(process.cwd(), { fs }).config;
+  if (!cfg) process.exit(0);
+  const planPath = process.argv[1];
+  const r = gh.updateTaskStatuses({
+    planPath,
+    config: cfg,
+    ghClient: { exec: (cmd) => execSync(cmd, { encoding: 'utf-8', stdio: ['pipe','pipe','pipe'] }) },
+    fs
+  });
+  console.log(JSON.stringify(r));
+} catch (e) { console.error('[TLC] GitHub status sync failed:', e.message); }
+" ".planning/phases/{N}-PLAN.md" 2>/dev/null
+```
+
+Failures warn but never block the build.
+
 #### 7f. Move to next task
 Repeat 7a-7e for each task in the phase.
 
@@ -868,20 +934,22 @@ git diff --name-status main...HEAD
 
 **Checks performed:**
 
-1. **Test Coverage** - Every implementation file has a test file
-2. **TDD Compliance** - Commits show test-first pattern (score ≥ 50%)
-3. **Security Scan** - No hardcoded secrets, eval(), innerHTML, etc.
-4. **Authorization** - Every data-access endpoint has ownership checks, not just auth guards
-5. **Secrets Exposure** - No API keys, tokens, or passwords returned in responses/HTML
-6. **Config Hygiene** - No `process.env` outside config module; config validated at startup
-7. **Output Encoding** - No unescaped `${...}` interpolation in HTML template strings
-8. **Sensitive Data** - OTPs, reset tokens, session secrets are hashed before storage
-9. **DI Compliance** - No manual `new Service()` / `new Provider()` in application code
-10. **File Size** - No file exceeds 1000 lines (warning at 500+)
-11. **Folder Size** - No folder exceeds 15 files (warning at 8+)
-12. **Strict Typing** - No `any` types in new/changed files
-13. **Return Types** - All exported functions have explicit return types
-14. **Module Structure** - Files grouped by domain entity, not by type
+1. **Silent Failure Scan (CRITICAL)** - No empty catch blocks. Every catch must log with context OR rethrow. `catch (e) {}` and `catch (e) { return null }` without logging are **auto-rejected**. Every external call (HTTP, DB, Docker, CLI, file I/O) must have error handling that produces an observable signal (log, metric, or rethrow).
+2. **Error Logging** - Every error path must use structured logging: `{ level, message, context, error }`. No bare `console.log` for errors — use a logger with level + context. No `console.error` without identifying WHAT failed and WHERE.
+3. **Test Coverage** - Every implementation file has a test file
+4. **TDD Compliance** - Commits show test-first pattern (score ≥ 50%)
+5. **Security Scan** - No hardcoded secrets, eval(), innerHTML, etc.
+6. **Authorization** - Every data-access endpoint has ownership checks, not just auth guards
+7. **Secrets Exposure** - No API keys, tokens, or passwords returned in responses/HTML
+8. **Config Hygiene** - No `process.env` outside config module; config validated at startup
+9. **Output Encoding** - No unescaped `${...}` interpolation in HTML template strings
+10. **Sensitive Data** - OTPs, reset tokens, session secrets are hashed before storage
+11. **DI Compliance** - No manual `new Service()` / `new Provider()` in application code
+12. **File Size** - No file exceeds 1000 lines (warning at 500+)
+13. **Folder Size** - No folder exceeds 15 files (warning at 8+)
+14. **Strict Typing** - No `any` types in new/changed files
+15. **Return Types** - All exported functions have explicit return types
+16. **Module Structure** - Files grouped by domain entity, not by type
 
 **Review output:**
 
@@ -1000,6 +1068,39 @@ gh pr create \
 {test runner summary}"
 ```
 
+#### Step 11-gh: GitHub: Link PR to Project
+
+If GitHub sync is enabled, after the PR is created:
+
+1. Add `Closes #N` references to the PR body for all completed task issues (parse `<!-- gh:N -->` markers from PLAN.md)
+2. Add the PR to the GitHub project board if configured
+3. Set the phase issue Status to "In review"
+
+```bash
+node -e "
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+let gh;
+try { gh = require('tlc-claude-code/server/lib/github'); }
+catch { gh = require(path.join(process.cwd(), 'server/lib/github')); }
+try {
+  const cfg = gh.loadGitHubConfig(process.cwd(), { fs }).config;
+  if (!cfg) process.exit(0);
+  const exec = (cmd) => execSync(cmd, { encoding: 'utf-8', stdio: ['pipe','pipe','pipe'] });
+  const prNumber = Number(process.argv[1]);
+  const planPath = process.argv[2];
+  const content = fs.readFileSync(planPath, 'utf-8');
+  const issueRefs = [...content.matchAll(/<!-- gh:(\d+) -->/g)].map(m => Number(m[1]));
+  if (issueRefs.length > 0) {
+    gh.linkPrToIssue({ ...cfg, prNumber, issueNumbers: issueRefs, exec });
+  }
+} catch (e) { console.error('[TLC] GitHub PR link failed:', e.message); }
+" "{pr_number}" ".planning/phases/{N}-PLAN.md" 2>/dev/null
+```
+
+Failures warn but never block.
+
 **The PR is the deliverable, not the commits.** CI runs on the PR. Merge when green.
 
 **If the user has already been working on main** (e.g., first time using branching): push main directly but note that future phases MUST use branches.

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

@@ -28,6 +28,26 @@ Commands:
 
 ## Setup
 
+### Implementation
+
+Setup uses `server/lib/github/config.js` to auto-detect the repo and configure sync:
+
+```bash
+node -e "
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+let gh;
+try { gh = require('tlc-claude-code/server/lib/github'); }
+catch { gh = require(path.join(process.cwd(), 'server/lib/github')); }
+const exec = (cmd) => execSync(cmd, { encoding: 'utf-8', stdio: ['pipe','pipe','pipe'] });
+const suggestion = gh.detectAndSuggestConfig({ ghClient: { detectRepo: () => gh.detectRepo({ exec }), checkAuth: () => gh.checkAuth({ exec }) }, ghProjects: null, projectDir: process.cwd(), fs });
+console.log(JSON.stringify(suggestion, null, 2));
+// If user approves, write config:
+// gh.writeGitHubConfig(process.cwd(), suggestion.config, { fs });
+" 2>/dev/null
+```
+
 ### GitHub Issues
 
 ```
@@ -129,6 +149,32 @@ In `.tlc.json`:
 
 ## Sync Tasks
 
+### Implementation
+
+The sync is powered by `server/lib/github/plan-sync.js`:
+
+```bash
+node -e "
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+let gh;
+try { gh = require('tlc-claude-code/server/lib/github'); }
+catch { gh = require(path.join(process.cwd(), 'server/lib/github')); }
+const cfg = gh.loadGitHubConfig(process.cwd(), { fs }).config;
+if (!cfg) { console.error('No GitHub config. Run /tlc:issues setup first.'); process.exit(1); }
+const planPath = process.argv[1];
+const r = gh.syncPlan({
+  planPath,
+  config: cfg,
+  ghClient: { exec: (cmd) => execSync(cmd, { encoding: 'utf-8', stdio: ['pipe','pipe','pipe'] }) },
+  ghProjects: null,
+  fs
+});
+console.log(JSON.stringify(r, null, 2));
+" ".planning/phases/{N}-PLAN.md" 2>/dev/null
+```
+
 ### Export to Issue Tracker
 
 ```

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

@@ -296,6 +296,49 @@ Create `.planning/phases/{N}-PLAN.md`:
 - File size warnings: {None / list any files projected to exceed 1000 lines and planned split}
 ```
 
+### Step 4b: GitHub Sync (automatic)
+
+After writing the plan file, check if GitHub sync is enabled and sync tasks to GitHub Issues:
+
+```bash
+node -e "
+const path = require('path');
+let gh;
+try { gh = require('tlc-claude-code/server/lib/github'); }
+catch { gh = require(path.join(process.cwd(), 'server/lib/github')); }
+console.log(gh.isGitHubEnabled(process.cwd()));
+" 2>/dev/null
+```
+
+If the result is `true`:
+
+1. Run the sync:
+   ```bash
+   node -e "
+   const path = require('path');
+   const fs = require('fs');
+   const { execSync } = require('child_process');
+   let gh;
+   try { gh = require('tlc-claude-code/server/lib/github'); }
+   catch { gh = require(path.join(process.cwd(), 'server/lib/github')); }
+   const config = gh.loadGitHubConfig(process.cwd(), { fs }).config;
+   if (!config) { console.log('GitHub sync: no config'); process.exit(0); }
+   const planPath = process.argv[1];
+   const r = gh.syncPlan({
+     planPath,
+     config,
+     ghClient: { exec: (cmd) => execSync(cmd, { encoding: 'utf-8', stdio: ['pipe','pipe','pipe'] }) },
+     ghProjects: null,
+     fs
+   });
+   console.log(JSON.stringify(r));
+   " ".planning/phases/{N}-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."
+
+If not enabled, skip silently (no message).
+
 ### Step 5: Review Plan
 
 Present plan summary: