tlc-claude-code 1.8.5 → 2.1.0

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

@@ -41,19 +41,32 @@ TLC automatically uses ALL providers configured for the `review` capability in `
 
 ## Process
 
-### Step 1: Load Router Configuration
+### Step 1: Load Router State (Persistent)
 
-Read `.tlc.json` to get configured review providers:
+**Always read from the router state file first**, then fall back to config:
 
 ```javascript
+// 1. Read persistent router state (written by session-init hook)
+const routerState = JSON.parse(fs.readFileSync('.tlc/.router-state.json', 'utf-8'));
+
+// 2. Read config for capability mappings
 const config = JSON.parse(fs.readFileSync('.tlc.json', 'utf-8'));
 const reviewProviders = config.router?.capabilities?.review?.providers || ['claude'];
 const providers = config.router?.providers || {};
+
+// 3. Filter to only AVAILABLE providers (from state file)
+const availableReviewers = reviewProviders.filter(p =>
+  routerState.providers[p]?.available === true
+);
 ```
 
-**Default providers for review:** `['claude', 'codex']`
+**The state file (`.tlc/.router-state.json`) is authoritative for availability.** It's written by the `SessionStart` hook, re-probed every hour, and persists across skill invocations. Never run `which codex` yourself — read the state file.
+
+If the state file is missing or stale (>1 hour), probe manually and write a fresh one.
+
+**Default providers for review:** `['claude', 'codex']` — but only invoked if the state file confirms they're available.
 
-If Codex is configured and available, it WILL be invoked automatically.
+If Codex is configured AND available in state, it WILL be invoked automatically.
 
 ### Step 2: Identify Changes
 

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

@@ -0,0 +1,159 @@
+# /tlc:watchci - Watch CI and Fix Until Green
+
+After pushing code, monitor the GitHub Actions run and fix failures in a loop until CI passes.
+
+## What This Does
+
+1. **Identifies the GH Actions run** triggered by the latest push
+2. **Polls until complete** (or fails)
+3. **On failure**: reads the logs, identifies the issue, fixes it, commits, pushes again
+4. **Repeats** until green or max attempts reached
+5. **Reports** final status
+
+This is the "I pushed, now babysit CI for me" command.
+
+## Usage
+
+```
+/tlc:watchci
+/tlc:watchci 3          # max 3 fix attempts (default: 5)
+```
+
+## Process
+
+### Step 1: Find the Active Run
+
+```bash
+gh run list --limit 5 --json databaseId,status,conclusion,headBranch,event,name,createdAt
+```
+
+- Find the most recent run on the current branch
+- If no run is in progress or recently completed, tell the user and exit
+- Show: workflow name, run ID, status
+
+### Step 2: Wait for Completion
+
+Poll the run status every 30 seconds:
+
+```bash
+gh run view <run_id> --json status,conclusion
+```
+
+While status is `in_progress` or `queued`:
+- Print a brief status update every 60 seconds (not every poll)
+- Continue waiting
+
+### Step 3: Check Result
+
+If `conclusion` is `success`:
+- Report green and exit
+
+If `conclusion` is `failure`:
+- Move to Step 4
+
+### Step 4: Read Failure Logs
+
+```bash
+gh run view <run_id> --log-failed
+```
+
+- Parse the failed step(s) and their log output
+- Identify the root cause:
+  - **Test failure**: Which test, what assertion, what file
+  - **Build failure**: Which compilation error, what file/line
+  - **Lint failure**: Which rule, what file/line
+  - **Dependency issue**: Which package, what version conflict
+  - **Other**: Extract the relevant error message
+
+### Step 5: Fix the Issue
+
+Based on the failure type:
+
+**Test failure:**
+- Read the failing test file and the source file it tests
+- Understand what broke
+- Fix the source code (not the test, unless the test itself is wrong)
+- Run the test locally first to verify: `npm test` or `npx vitest run <file>`
+
+**Build failure:**
+- Read the file with the compilation error
+- Fix the type error, missing import, etc.
+- Verify locally: `npm run build` or `npx tsc --noEmit`
+
+**Lint failure:**
+- Read the file and fix the lint issue
+- Verify locally: `npm run lint`
+
+**Dependency issue:**
+- Fix package.json or lock file as needed
+- Verify locally: `npm ci`
+
+### Step 6: Commit and Push
+
+- Stage only the files you changed
+- Commit with message: `fix: resolve CI failure - <brief description>`
+- Push to the same branch
+- **Ask user before pushing** (per TLC rules)
+
+### Step 7: Loop Back
+
+- Return to Step 1 to watch the new run
+- Track attempt count
+- If max attempts (default 5) reached without green, stop and report:
+  - What was tried
+  - What's still failing
+  - Suggestion for manual investigation
+
+## Guard Rails
+
+- **Never push without asking.** Even in a fix loop, confirm before each push.
+- **Never modify tests to make CI pass** unless the test itself has a genuine bug (not a "make the assertion match the wrong output" fix).
+- **Local verification first.** Always run the fix locally before pushing.
+- **Max attempts.** Default 5. Don't loop forever.
+- **Don't mask failures.** If a test is legitimately catching a bug, fix the bug. Don't skip the test.
+
+## Example
+
+```
+> /tlc:watchci
+
+Watching CI for branch: feature/auth-module
+Run #4521 (CI) — in progress...
+
+⏳ Waiting... (2m elapsed)
+⏳ Waiting... (3m elapsed)
+
+❌ Run #4521 failed
+
+Failed step: "Run tests"
+Error: FAIL server/lib/auth/auth.test.js
+  ● validateToken › should reject expired tokens
+    Expected: "TOKEN_EXPIRED"
+    Received: "INVALID_TOKEN"
+
+Reading auth.test.js and auth.service.js...
+
+Found: validateToken returns generic "INVALID_TOKEN" for expired tokens
+instead of the specific "TOKEN_EXPIRED" error code.
+
+Fix: Update the expiry check in auth.service.js to return "TOKEN_EXPIRED"
+
+Running locally... ✅ Test passes
+
+Ready to commit and push fix? (Y/n)
+> y
+
+Pushed. Watching new run...
+
+Run #4522 (CI) — in progress...
+⏳ Waiting... (2m elapsed)
+
+✅ Run #4522 passed! CI is green.
+```
+
+## When to Use
+
+- After pushing and you want CI monitored automatically
+- After `/tlc:build` when you've pushed your work
+- When CI keeps failing and you want the fix loop automated
+- Pair with `/tlc:e2e-verify` for full verification after CI is green

package/.claude/hooks/tlc-block-tools.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# TLC Enforcement Layer 1: Hard-block non-TLC planning tools
+# Fires on PreToolUse for banned tools and DENIES them.
+# Claude cannot bypass this - the tool call never executes.
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+case "$TOOL" in
+  EnterPlanMode)
+    REASON="BLOCKED by TLC. Use /tlc:plan instead. Plans go in .planning/phases/ files."
+    ;;
+  TaskCreate)
+    REASON="BLOCKED by TLC. Tasks live in .planning/phases/{N}-PLAN.md with [ ] markers."
+    ;;
+  TaskUpdate)
+    REASON="BLOCKED by TLC. Update task markers in .planning/phases/{N}-PLAN.md files."
+    ;;
+  TaskGet)
+    REASON="BLOCKED by TLC. Read tasks from .planning/phases/{N}-PLAN.md files."
+    ;;
+  TaskList)
+    REASON="BLOCKED by TLC. Use /tlc:progress to check task status."
+    ;;
+  ExitPlanMode)
+    REASON="BLOCKED by TLC. Plans are approved via /tlc:build, not ExitPlanMode."
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "${REASON}"
+  }
+}
+EOF

package/.claude/hooks/tlc-capture-exchange.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# TLC Memory Capture - Claude Code Stop Hook
+#
+# Reads Stop hook JSON from stdin, extracts the assistant response,
+# and sends it to the TLC server for memory processing.
+# Falls back to local spool when server is unreachable.
+#
+# This script MUST exit 0 always - capture failures never block Claude.
+
+set -o pipefail
+
+# Read stdin (Stop hook provides JSON)
+INPUT=$(cat)
+
+# Quick exit if no input
+[ -z "$INPUT" ] && exit 0
+
+# Use the capture-bridge Node.js module for reliable processing
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+BRIDGE_SCRIPT="$PROJECT_DIR/server/lib/capture-bridge.js"
+
+if [ -f "$BRIDGE_SCRIPT" ]; then
+  echo "$INPUT" | node -e "
+    const bridge = require('$BRIDGE_SCRIPT');
+    let input = '';
+    process.stdin.on('data', d => input += d);
+    process.stdin.on('end', async () => {
+      const parsed = bridge.parseStopHookInput(input);
+      if (!parsed || !parsed.assistantMessage) process.exit(0);
+
+      const userMessage = parsed.transcriptPath
+        ? bridge.extractLastUserMessage(parsed.transcriptPath)
+        : null;
+
+      await bridge.captureExchange({
+        cwd: parsed.cwd || '$PROJECT_DIR',
+        assistantMessage: parsed.assistantMessage,
+        userMessage,
+        sessionId: parsed.sessionId,
+      });
+
+      const path = require('path');
+      const spoolDir = path.join(parsed.cwd || '$PROJECT_DIR', '.tlc', 'memory');
+      await bridge.drainSpool(spoolDir);
+    });
+  " 2>/dev/null
+fi
+
+# Always exit 0 - never block Claude
+exit 0

package/.claude/hooks/tlc-post-build.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# TLC Plugin: Post-build and post-plan automation chain
+# Fires on PostToolUse for Skill.
+#
+# After /tlc:build (code written):
+#   guard → preflight → review (Claude + Codex) → if APPROVED → offer push + PR
+#
+# After /tlc:plan:
+#   guard plan → validate structure
+#
+# After /tlc:quick:
+#   preflight → review → offer push
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+# Only care about Skill tool
+[ "$TOOL" != "Skill" ] && exit 0
+
+SKILL=$(echo "$INPUT" | jq -r '.tool_input.skill // empty')
+
+case "$SKILL" in
+  tlc:build)
+    echo "[TLC-PLUGIN] Build phase complete. Mandatory post-build chain:
+(1) Run /tlc:guard to validate TLC process compliance (test-first, coverage, no skipped tests).
+(2) Run /tlc:preflight to check for gaps (references, registries, configs, distribution).
+(3) Run /tlc:review to invoke multi-LLM review — Claude reviews in-session, THEN invoke Codex CLI for second opinion. BOTH must APPROVE.
+(4) If review APPROVED: ask user for permission to push to remote and create a PR for main.
+(5) If review CHANGES_REQUESTED: fix the issues and re-run the review. Do NOT push.
+Do NOT skip any step. Do NOT push without review approval."
+    ;;
+  tlc:plan)
+    echo "[TLC-PLUGIN] Plan created. Now automatically run /tlc:guard plan to validate the plan has proper task breakdown, acceptance criteria, and dependency ordering. Do NOT skip."
+    ;;
+  tlc:quick)
+    echo "[TLC-PLUGIN] Quick task complete. Run /tlc:preflight then /tlc:review (Claude + Codex). If APPROVED, ask user for permission to push and create PR."
+    ;;
+esac

package/.claude/hooks/tlc-post-push.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# TLC Plugin: Post-push automation chain
+# Fires on PostToolUse for Bash. Detects git push.
+#
+# After git push:
+#   watchci (monitor GH Actions) → if green → e2e-verify (screenshots + logs)
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+# Only care about Bash tool
+[ "$TOOL" != "Bash" ] && exit 0
+
+# Check if the command was a git push
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+if echo "$COMMAND" | grep -qE '^git push'; then
+  echo "[TLC-PLUGIN] git push detected. Mandatory post-push chain:
+(1) Run /tlc:watchci — monitor the GitHub Actions run, read failure logs, fix issues, and push again until CI is green.
+(2) Once CI is green, run /tlc:e2e-verify — start the app, take screenshots, read them visually, check server and console logs for errors.
+(3) If e2e-verify finds issues, fix them and push again (which restarts this chain).
+Do NOT skip any step."
+fi

package/.claude/hooks/tlc-prompt-guard.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# TLC Enforcement Layer 2: Smart intent detection + routing
+# Fires on every UserPromptSubmit. Parses user message for intent and
+# injects specific TLC command routing — not a generic reminder.
+#
+# Output appears as <user-prompt-submit-hook> and Claude treats it as user instruction.
+# Survives context compaction because it is re-injected every turn.
+
+# Only active in TLC projects
+[ ! -f ".tlc.json" ] && exit 0
+
+# Read user's message from stdin
+INPUT=$(cat)
+MSG=$(echo "$INPUT" | jq -r '.user_prompt // empty' 2>/dev/null)
+
+# If we can't parse the message, fall back to generic reminder
+if [ -z "$MSG" ]; then
+  echo "[TLC PROJECT] All work uses /tlc commands. Never write code without tests. Run /tlc if unsure."
+  exit 0
+fi
+
+# Lowercase for matching
+MSG_LOWER=$(echo "$MSG" | tr '[:upper:]' '[:lower:]')
+
+# Detect intent and inject specific routing
+# Priority order: most specific first
+
+# Plan intent
+if echo "$MSG_LOWER" | grep -qE '\b(plan|break.*(down|into)|design|architect|roadmap)\b'; then
+  if ! echo "$MSG_LOWER" | grep -qE '/tlc'; then
+    echo "[TLC-ENFORCE] Planning detected. You MUST use /tlc:plan for this. Plans go in .planning/phases/ files, not in chat. Invoke Skill(skill=\"tlc:plan\") now."
+    exit 0
+  fi
+fi
+
+# Build/implement intent
+if echo "$MSG_LOWER" | grep -qE '\b(build|implement|create|add|code|write|develop|make)\b.*(feature|function|module|component|endpoint|api|page|service|handler|route|model)'; then
+  if ! echo "$MSG_LOWER" | grep -qE '/tlc'; then
+    echo "[TLC-ENFORCE] Implementation detected. You MUST use /tlc:build for this. Tests before code — Red, Green, Refactor. Run /tlc:progress first, then invoke Skill(skill=\"tlc:build\"). Do NOT write code directly."
+    exit 0
+  fi
+fi
+
+# Fix/bug intent
+if echo "$MSG_LOWER" | grep -qE '\b(fix|bug|broken|not working|failing|crash|error)\b'; then
+  if ! echo "$MSG_LOWER" | grep -qE '/tlc'; then
+    echo "[TLC-ENFORCE] Bug/fix detected. Use /tlc:quick for small fixes (still test-first) or /tlc:autofix if tests are failing. Do NOT write code directly without tests."
+    exit 0
+  fi
+fi
+
+# Refactor intent
+if echo "$MSG_LOWER" | grep -qE '\b(refactor|clean.?up|restructure|reorganize|simplify)\b'; then
+  if ! echo "$MSG_LOWER" | grep -qE '/tlc'; then
+    echo "[TLC-ENFORCE] Refactoring detected. Use /tlc:refactor for step-by-step standards refactoring with tests. Invoke Skill(skill=\"tlc:refactor\")."
+    exit 0
+  fi
+fi
+
+# Deploy intent
+if echo "$MSG_LOWER" | grep -qE '\b(deploy|ship|release|publish|push to prod|staging)\b'; then
+  if ! echo "$MSG_LOWER" | grep -qE '/tlc'; then
+    echo "[TLC-ENFORCE] Deployment detected. Use /tlc:deploy for deployment. Secrets must come from HashiCorp Vault or environment — never hardcode. Invoke Skill(skill=\"tlc:deploy\")."
+    exit 0
+  fi
+fi
+
+# Generic fallback for TLC projects
+echo "[TLC PROJECT] All work uses /tlc commands. Never write code without tests. Run /tlc if unsure."

package/.claude/hooks/tlc-session-init.sh

@@ -0,0 +1,123 @@
+#!/bin/bash
+# TLC Enforcement Layer 2b: Session initialization
+# 1. Inject TLC awareness
+# 2. Ensure TLC server is running
+# 3. Probe LLM providers and write persistent router state
+
+if [ ! -f ".tlc.json" ]; then
+  exit 0
+fi
+
+echo "TLC project detected. All work goes through /tlc commands. Run /tlc for current status and next action."
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# ─── TLC Server ───────────────────────────────────────────
+
+TLC_PORT="${TLC_PORT:-3147}"
+if curl -sf --max-time 1 "http://localhost:${TLC_PORT}/api/health" > /dev/null 2>&1; then
+  : # Server is running
+else
+  PLIST="$HOME/Library/LaunchAgents/com.tlc.server.plist"
+
+  if [ -f "$PLIST" ]; then
+    launchctl kickstart -k "gui/$(id -u)/com.tlc.server" 2>/dev/null
+  elif [ -f "$PROJECT_DIR/server/index.js" ]; then
+    nohup node "$PROJECT_DIR/server/index.js" > "$HOME/.tlc/logs/server.log" 2>&1 &
+  fi
+
+  for i in 1 2 3; do
+    sleep 1
+    curl -sf --max-time 1 "http://localhost:${TLC_PORT}/api/health" > /dev/null 2>&1 && break
+  done
+fi
+
+# ─── LLM Router: Probe Providers ─────────────────────────
+#
+# Writes .tlc/.router-state.json with provider availability.
+# Skills read this file instead of probing from scratch.
+# State has a TTL — re-probed if older than 1 hour.
+
+STATE_DIR="$PROJECT_DIR/.tlc"
+STATE_FILE="$STATE_DIR/.router-state.json"
+mkdir -p "$STATE_DIR"
+
+# Check if state is fresh (less than 1 hour old)
+STALE=true
+if [ -f "$STATE_FILE" ]; then
+  STATE_AGE=$(( $(date +%s) - $(stat -f %m "$STATE_FILE" 2>/dev/null || stat -c %Y "$STATE_FILE" 2>/dev/null || echo 0) ))
+  if [ "$STATE_AGE" -lt 3600 ]; then
+    STALE=false
+  fi
+fi
+
+if [ "$STALE" = true ]; then
+  # Probe each provider
+  CLAUDE_PATH=$(which claude 2>/dev/null || echo "")
+  CODEX_PATH=$(which codex 2>/dev/null || echo "")
+  GEMINI_PATH=$(which gemini 2>/dev/null || echo "")
+
+  CLAUDE_OK="false"
+  CODEX_OK="false"
+  GEMINI_OK="false"
+
+  [ -n "$CLAUDE_PATH" ] && CLAUDE_OK="true"
+  [ -n "$CODEX_PATH" ] && CODEX_OK="true"
+  [ -n "$GEMINI_PATH" ] && GEMINI_OK="true"
+
+  # Count available
+  AVAILABLE=0
+  [ "$CLAUDE_OK" = "true" ] && AVAILABLE=$((AVAILABLE + 1))
+  [ "$CODEX_OK" = "true" ] && AVAILABLE=$((AVAILABLE + 1))
+  [ "$GEMINI_OK" = "true" ] && AVAILABLE=$((AVAILABLE + 1))
+
+  # Read configured providers from .tlc.json
+  CONFIGURED_PROVIDERS=""
+  if command -v jq >/dev/null 2>&1; then
+    CONFIGURED_PROVIDERS=$(jq -r '.router.providers // {} | keys[]' .tlc.json 2>/dev/null | tr '\n' ',' | sed 's/,$//')
+  fi
+
+  # Write state file
+  cat > "$STATE_FILE" <<STATEEOF
+{
+  "probed_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "ttl_seconds": 3600,
+  "providers": {
+    "claude": {
+      "available": $CLAUDE_OK,
+      "path": "$CLAUDE_PATH"
+    },
+    "codex": {
+      "available": $CODEX_OK,
+      "path": "$CODEX_PATH"
+    },
+    "gemini": {
+      "available": $GEMINI_OK,
+      "path": "$GEMINI_PATH"
+    }
+  },
+  "summary": {
+    "available_count": $AVAILABLE,
+    "configured": "$CONFIGURED_PROVIDERS"
+  }
+}
+STATEEOF
+
+  # Report to Claude
+  if [ "$AVAILABLE" -gt 0 ]; then
+    PROVIDERS_LIST=""
+    [ "$CLAUDE_OK" = "true" ] && PROVIDERS_LIST="${PROVIDERS_LIST}claude, "
+    [ "$CODEX_OK" = "true" ] && PROVIDERS_LIST="${PROVIDERS_LIST}codex, "
+    [ "$GEMINI_OK" = "true" ] && PROVIDERS_LIST="${PROVIDERS_LIST}gemini, "
+    PROVIDERS_LIST=$(echo "$PROVIDERS_LIST" | sed 's/, $//')
+    echo "LLM Router: ${AVAILABLE} providers available (${PROVIDERS_LIST}). State written to .tlc/.router-state.json. All routing skills MUST read this file for provider availability — do not probe manually."
+  else
+    echo "LLM Router: No external providers detected. Running Claude-only mode. Install codex or gemini for multi-LLM reviews."
+  fi
+else
+  # State is fresh — just report it
+  if command -v jq >/dev/null 2>&1 && [ -f "$STATE_FILE" ]; then
+    COUNT=$(jq -r '.summary.available_count' "$STATE_FILE" 2>/dev/null)
+    echo "LLM Router: ${COUNT} providers available (cached). State at .tlc/.router-state.json."
+  fi
+fi