tlc-claude-code 2.2.0 → 2.3.0

package/.claude/agents/builder.md

@@ -122,6 +122,23 @@ src/modules/{entity}/
 - No credentials — use environment variables.
 - No magic numbers or strings — use named constants or enums.
 
+### Configuration
+- All `process.env` access MUST be in a config module — never in services or controllers.
+- Validate all required env vars at startup with a schema (Zod/Joi).
+- No silent empty-string fallbacks for secrets or connection strings.
+
+### Security
+- Every data-access endpoint MUST check resource ownership, not just authentication.
+- Never return secrets (API keys, tokens, passwords) in API responses or HTML.
+- Hash OTPs, reset tokens, and session secrets before storing — never plaintext.
+- Escape all dynamic values in HTML output — no raw interpolation.
+- No inline HTML string builders for new pages — use a proper frontend or templating engine.
+- Tests MUST prove that user A cannot read/modify user B's data.
+
+### Dependency Injection
+- Never manually instantiate services/providers with `new` — use DI.
+- Register all providers in the DI container.
+
 ### File and Folder Limits
 - Files: warn at 500 lines, error at 1000 lines.
 - Folders: warn at 8 files, error at 15 files.

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

@@ -52,6 +52,11 @@ Run `auditProject(projectPath)` which executes:
 | **Missing Return Types** | Exported functions without explicit return type | warning |
 | **Missing Parameter Types** | Function parameters without type annotations | error |
 | **Weak tsconfig** | `strict: true` not enabled in tsconfig.json | warning |
+| **Direct `process.env`** | `process.env.` usage outside config module files | error |
+| **Unescaped HTML** | Template literals containing HTML tags with `${` interpolation | error |
+| **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 |
 
 ### Step 3: Generate Report
 
@@ -109,6 +114,13 @@ Status: FAILED (18 issues found)
   JSDoc Coverage:       8 issues (42% of exports undocumented)
   Import Style:         PASSED
 
+  SECURITY & CONFIG
+  Direct process.env:   3 issues (outside config module)
+  Unescaped HTML:       2 issues
+  Secrets in Responses: 1 issue
+  Manual Instantiation: 1 issue
+  Missing Ownership:    2 issues
+
 Report saved to: .planning/AUDIT-REPORT.md
 
 Fix automatically? Run /tlc:cleanup

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

@@ -166,7 +166,7 @@ Senior engineers know when rules don't apply:
 
 This is the core TLC command. Tests before code, one task at a time.
 
-**Overdrive Mode (Opus 4.6):** When tasks are independent, TLC auto-detects and offers parallel execution with multiple agents. Agents are assigned models based on task complexity (opus for heavy, sonnet for standard, haiku for light). Failed agents can be resumed. No arbitrary cap on agent count.
+**Parallel by default:** When tasks are independent, TLC auto-detects and runs them in parallel. Multiple providers (Claude + Codex) get their own git worktrees and tmux panes. Single provider uses in-process agents. No flags needed — it just works.
 
 ## Usage
 
@@ -185,74 +185,80 @@ This is the core TLC command. Tests before code, one task at a time.
 
 Read all `.planning/phases/{phase}-*-PLAN.md` files for this phase.
 
-### Step 1a: Overdrive Detection (Auto-Parallel, Opus 4.6)
+### Step 1a: Auto-Parallel Detection
 
-After loading plans, analyze task dependencies to determine if parallel execution is possible.
+After loading plans, analyze task dependencies and available providers to pick the best execution strategy automatically.
 
-**Check for dependencies:**
-```javascript
-// Patterns that indicate dependencies:
-// - "depends on task N"
-// - "after task N"
-// - "requires task N"
-// - "blocked by task N"
-// - "## Dependencies" section with task relationships
-```
-
-**Decision logic:**
+**Detection:**
 1. Parse all tasks from plan
-2. Look for dependency markers in task descriptions
-3. Check "## Dependencies" section if present
-4. Identify independent tasks (no dependencies)
-5. Estimate task complexity for model assignment (heavy/standard/light)
+2. Check "## Dependencies" section for task relationships
+3. Identify independent tasks (no unmet dependencies)
+4. Read `.tlc/.router-state.json` for available providers
+5. Check if tmux is available
 
-**If 2+ independent tasks found:**
-```
-🚀 Overdrive Mode Available (Opus 4.6)
+**Strategy selection (automatic, no flags needed):**
 
-Phase 3 has 4 independent tasks that can run in 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)
+| Condition | Strategy | What happens |
+|-----------|----------|--------------|
+| 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). |
+| All tasks have dependencies | **Sequential** | One task at a time, in dependency order. |
+| 1 task only | **Sequential** | Just build it. |
 
-Recommended: 4 agents (one per independent task)
+**No prompt, no options menu.** TLC picks the best strategy and runs it. User sees:
 
-Options:
-1) Overdrive mode (parallel agents) [Recommended]
-2) Sequential mode (one task at a time)
-3) Let me pick which tasks to parallelize
 ```
+Phase 3 has 4 independent tasks.
+Providers: claude, codex (2 available)
+Strategy: worktree + tmux (parallel)
 
-**Model auto-selection per task complexity:**
-| 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 |
+  Task 1: Create user schema         → claude  [worktree-phase-3-task-1]
+  Task 2: Add validation helpers     → codex   [worktree-phase-3-task-2]
+  Task 3: Write migration scripts    → claude  [worktree-phase-3-task-3]
+  Task 4: Create seed data           → codex   [worktree-phase-3-task-4]
 
-Override with `--model sonnet` to force all agents to the same model.
+Launching...
+```
 
-**Router-aware model selection:**
-Before assigning models, check `.tlc.json` for `router.providers` and `router.capabilities`. If the project has a router config, respect it:
-- Use configured providers for their assigned capabilities (e.g., Gemini for design tasks)
-- Fall back to the complexity table above only when no router config exists
-- Run `/tlc:llm status` to see current routing
+Or for single provider:
+```
+Phase 3 has 4 independent tasks.
+Providers: claude (1 available)
+Strategy: in-process agents (parallel)
 
-**If tasks have dependencies (waterfall):**
+  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)
+
+Launching...
 ```
-📋 Sequential Mode
 
+Or for waterfall:
+```
 Phase 3 tasks have dependencies:
   Task 2 depends on Task 1
   Task 3 depends on Task 2
 
-Running in sequential order.
+Strategy: sequential
+
+Starting Task 1...
 ```
 
-### Step 1b: Execute Overdrive (if selected) — Opus 4.6 Multi-Agent
+**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 |
+
+**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.
 
-When overdrive mode is selected, spawn parallel agents with per-task model selection:
+### Step 1b: Execute Parallel Build
+
+**Worktree + Tmux mode** (multi-provider):
 
 ```
 🚀 Launching Overdrive Mode (Opus 4.6)
@@ -338,11 +344,45 @@ Task(resume="AGENT_ID", prompt="Continue from where you left off. Fix any errors
 - When user asks "check on agents"
 - After each agent completes
 
-**After all agents complete:**
-1. Run full test suite
+**Before spawning agents (integration branch):**
+
+Create an integration branch so all worktrees merge into one place, producing a single clean PR:
+
+```javascript
+const { createIntegrationBranch } = require('./server/lib/orchestration/worktree-manager');
+const { branch } = createIntegrationBranch(phaseNumber, { exec, baseBranch: 'main' });
+// branch = 'phase/42'
+```
+
+All worktrees branch off `phase/{N}`, not `main`. This means each worktree's diff is small and relative to the integration branch, not the entire main history.
+
+**After all agents complete — sequential merge-back:**
+
+```javascript
+const { mergeAllWorktrees, listWorktrees } = require('./server/lib/orchestration/worktree-manager');
+
+// Filter to only THIS phase's worktrees — don't merge unrelated work
+const allWorktrees = listWorktrees({ exec });
+const worktrees = allWorktrees.filter(wt => wt.name.startsWith(`phase-${phaseNumber}-`));
+const result = mergeAllWorktrees(worktrees, `phase/${phaseNumber}`, { exec });
+
+// result.merged = ['task-1', 'task-3', 'task-4']  — successfully merged
+// result.conflicts = ['task-2']                    — needs manual resolution
+```
+
+`mergeAllWorktrees` does the following automatically:
+1. **Analyzes file overlap** — worktrees touching disjoint files merge first
+2. **Merges one at a time** into `phase/{N}`
+3. **Rebases remaining worktrees** onto the updated `phase/{N}` after each merge
+4. **Skips conflicting worktrees** — preserves them for manual resolution, continues with others
+5. **Cleans up** merged worktrees (removes worktree dir + branch)
+
+After merge-back:
+1. Run full test suite on the integration branch
 2. Verify all tasks pass
-3. Report results
-4. Continue to Step 8 (verification)
+3. If conflicts exist, report them with file lists
+4. If clean, the integration branch is ready for a single PR to main
+5. Continue to Step 8 (verification)
 
 ### Step 1c: Sync and Claim (Multi-User, Sequential Only)
 
@@ -706,11 +746,17 @@ git diff --name-status main...HEAD
 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. **File Size** - No file exceeds 1000 lines (warning at 500+)
-5. **Folder Size** - No folder exceeds 15 files (warning at 8+)
-6. **Strict Typing** - No `any` types in new/changed files
-7. **Return Types** - All exported functions have explicit return types
-8. **Module Structure** - Files grouped by domain entity, not by type
+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
 
 **Review output:**
 
@@ -721,8 +767,11 @@ git diff --name-status main...HEAD
 Test Coverage: ✅ 5/5 files covered
 TDD Score: 75% ✅
 Security: ✅ No issues
+Authorization: ✅ All endpoints have ownership checks
+Secrets Exposure: ✅ No secrets in responses
+Config Hygiene: ✅ No process.env outside config
+Output Encoding: ✅ All HTML output escaped
 File Sizes: ✅ All under 1000 lines
-Folder Sizes: ✅ All under 15 files
 Strict Typing: ✅ No `any` found
 Return Types: ✅ All exports typed
 
@@ -893,10 +942,10 @@ Found: 2-PLAN.md (4 tasks)
 🚀 Overdrive Mode Available (Opus 4.6)
 
 Phase 2 has 4 independent tasks:
-  - Task 1: Create API routes         [sonnet] (standard)
-  - Task 2: Add input validation      [sonnet] (standard)
-  - Task 3: Write error handlers      [sonnet] (standard)
-  - Task 4: Add rate limiting config  [haiku]  (light)
+  - Task 1: Create API routes         [opus]
+  - Task 2: Add input validation      [opus]
+  - Task 3: Write error handlers      [opus]
+  - Task 4: Add rate limiting config  [opus]
 
 Recommended: 4 agents (one per task)
 
@@ -910,17 +959,17 @@ User: 1
 Claude: 🚀 Launching Overdrive Mode (Opus 4.6)
 
 Spawning 4 agents...
-[Agent 1] Task 1: Create API routes        [sonnet] - STARTED
-[Agent 2] Task 2: Add input validation     [sonnet] - STARTED
-[Agent 3] Task 3: Write error handlers     [sonnet] - STARTED
-[Agent 4] Task 4: Add rate limiting config [haiku]  - STARTED
+[Agent 1] Task 1: Create API routes        [opus] - STARTED
+[Agent 2] Task 2: Add input validation     [opus] - STARTED
+[Agent 3] Task 3: Write error handlers     [opus] - STARTED
+[Agent 4] Task 4: Add rate limiting config [opus] - STARTED
 
 ... agents working in background ...
 
-[Agent 4] ✅ Task 4 complete (1 commit)   [haiku - fast]
-[Agent 2] ✅ Task 2 complete (3 commits)  [sonnet]
-[Agent 1] ✅ Task 1 complete (4 commits)  [sonnet]
-[Agent 3] ✅ Task 3 complete (2 commits)  [sonnet]
+[Agent 4] ✅ Task 4 complete (1 commit)   [opus]
+[Agent 2] ✅ Task 2 complete (3 commits)  [opus]
+[Agent 1] ✅ Task 1 complete (4 commits)  [opus]
+[Agent 3] ✅ Task 3 complete (2 commits)  [opus]
 
 All agents complete. Running full test suite...
 ✅ 24 tests passing
@@ -951,7 +1000,7 @@ Phase 2 complete. Ready for /tlc:verify 2
 - Merge conflicts → Agents working on same files (rare if tasks are truly independent)
 - One agent failed → Other agents continue; resume failed agent or fix manually
 - Want sequential instead → Use `--sequential` flag: `/tlc:build 2 --sequential`
-- Cost too high → Use `--model haiku` to force all agents to haiku
+- Cost too high → Use `--agents 2` to limit parallelism
 - Agent running too long → Use `--max-turns 30` to limit execution
 
 ## Flags
@@ -960,16 +1009,15 @@ Phase 2 complete. Ready for /tlc:verify 2
 |------|-------------|
 | `--sequential` | Force sequential execution even if tasks are independent |
 | `--agents N` | Limit parallel agents to N (default: one per independent task) |
-| `--model MODEL` | Force all agents to use a specific model (opus, sonnet, haiku) |
+| `--model opus` | Force all agents to opus (default — all tiers use opus) |
 | `--max-turns N` | Limit each agent's execution to N turns (default: 50) |
-| `--parallel` | Multi-agent with git worktrees + tmux. Each task gets its own worktree and tmux pane. Claude and Codex work simultaneously. |
-| `--parallel --providers claude,codex` | Force specific providers for parallel mode |
-| `--parallel --no-tmux` | Parallel worktrees but without tmux visibility (background processes) |
-| `--parallel --dry-run` | Preview execution plan: show DAG, task assignments, provider routing |
+| `--providers claude,codex` | Force specific providers (default: auto-detect from router state) |
+| `--no-tmux` | Skip tmux panes, run worktree agents in background |
+| `--dry-run` | Preview execution plan without running (show DAG, task assignments) |
 
-## When Overdrive is NOT Used
+## When Parallel is NOT Used
 
-Overdrive auto-detects but won't activate when:
+Parallel is the default but won't activate when:
 - Only 1 task in phase
 - All tasks have dependencies (waterfall)
 - Tasks modify the same files

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

@@ -89,6 +89,15 @@ For a phase that's been (partially) built, verify TLC compliance:
 - [ ] No hardcoded secrets, URLs, or credentials (check for patterns)
 - [ ] No skipped tests (`.skip`, `xit`, `xdescribe`)
 
+**Security & Config (CODING-STANDARDS §6, §21, §22):**
+- [ ] Every data-access endpoint has ownership check (not just auth — verify user owns the resource)
+- [ ] No secrets (API keys, tokens, passwords) returned in API responses or rendered in HTML
+- [ ] No `process.env` in services/controllers — all config through validated config module
+- [ ] No unescaped `${...}` interpolation in HTML template strings
+- [ ] OTPs, reset tokens, session secrets are hashed before storage (not plaintext)
+- [ ] No `new ServiceClass()` / `new ProviderClass()` — use DI container
+- [ ] Tests prove user A cannot read/modify user B's data (ownership test)
+
 **Process:**
 - [ ] Phase plan exists and tasks are checked off
 - [ ] Implementation matches what was planned (no scope creep)

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

@@ -207,7 +207,18 @@ Start writing tests now, or save backlog for later?
 
 **If "Start now":** Begin writing tests for the first critical path item using Red-Green-Refactor (but code already exists, so focus on capturing current behavior).
 
-### 9. Create CLAUDE.md
+### 9. Inject Standards (CLAUDE.md + CODING-STANDARDS.md)
+
+**First, inject both standards files using the standards-injector module:**
+
+```javascript
+const { injectStandards } = require('./lib/standards/standards-injector');
+const results = await injectStandards(projectPath);
+// Creates CLAUDE.md and CODING-STANDARDS.md from templates if missing
+// Appends TLC section to existing CLAUDE.md if present
+```
+
+**If the module is not available** (e.g., TLC server not installed locally), create `CLAUDE.md` manually and copy `CODING-STANDARDS.md` from the TLC templates directory.
 
 Create `CLAUDE.md` to enforce TLC workflow over Claude's default behaviors:
 

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

@@ -116,6 +116,8 @@ git log --oneline --name-status main..HEAD
 
 Scan diff for common security issues:
 
+**Pattern-Based Checks:**
+
 | Pattern | Issue | Severity |
 |---------|-------|----------|
 | `password = "..."` | Hardcoded password | HIGH |
@@ -126,6 +128,17 @@ Scan diff for common security issues:
 | `exec("..." + var)` | Command injection | HIGH |
 | `SELECT...WHERE...+` | SQL injection | HIGH |
 
+**Semantic Security Checks (read the code, not just grep):**
+
+| Check | What to Look For | Severity |
+|-------|-----------------|----------|
+| **Ownership/IDOR** | Controller methods that take an ID param (`req.params.id`, `@Param('id')`) and query data without checking the requesting user owns the resource. Every data-access endpoint MUST verify ownership, not just authentication. | HIGH |
+| **Secrets in responses** | Response objects, DTOs, or `res.json()`/`res.send()` calls that include fields like `apiKey`, `secret`, `token`, `password`, `webhookSecret`. Secrets are write-only — never return them. | HIGH |
+| **Direct `process.env`** | `process.env.` usage in service, controller, or middleware files. All env access MUST go through a validated config module. Grep: `process\.env\.` in non-config files. | MEDIUM |
+| **Unescaped HTML** | Template literals that build HTML with `${...}` interpolation of variables (e.g., `` `<h1>${user.name}</h1>` ``). All dynamic values in HTML MUST be escaped. | HIGH |
+| **Plaintext sensitive data** | OTP codes, reset tokens, or session secrets stored without hashing. Look for database inserts/updates of these values without a hash step. | HIGH |
+| **Manual instantiation** | `new SomeProvider(...)` or `new SomeService(...)` in application code instead of using DI. | MEDIUM |
+
 **Fail if:** Any HIGH severity issues found.
 
 ### Step 5b: Coding Standards Check
@@ -311,6 +324,12 @@ After Steps 2-6 complete, if ANY issues were found:
 | `any` type | Replace with proper interface | If domain type unclear |
 | File >1000 lines | Split into sub-modules | If split strategy unclear |
 | Security vulnerability | Patch it | If fix might break behavior |
+| Missing ownership check | Add guard/check | If ownership model unclear |
+| Secrets in response | Remove or mask fields | If field is needed by client |
+| Direct `process.env` | Move to config module | If config module doesn't exist yet |
+| Unescaped HTML | Add escapeHtml() | If templating engine preferred |
+| Plaintext sensitive data | Add hash step | - |
+| Manual `new Service()` | Convert to DI | If DI container not set up |
 | Codex-flagged bug | Apply suggestion | If suggestion conflicts with Claude |
 | Merge conflict | - | Always human |