tlc-claude-code 2.5.0 → 2.6.1

package/.claude/commands/tlc/verify.md

@@ -1,13 +1,13 @@
-# /tlc:verify - Human Acceptance Testing
+# /tlc:verify - Acceptance Verification
 
-Verify the phase works as expected — with your own eyes.
+Verify the phase automatically from its plan acceptance criteria, then leave only the genuinely manual items for human follow-up.
 
 ## What This Does
 
-1. Runs tests to confirm code works
-2. Walks you through each deliverable
-3. Captures issues for fixing
-4. Marks phase as verified when done
+1. Reads acceptance criteria from the phase plan
+2. Runs `server/lib/e2e/verify-runner.js` against the project automatically
+3. Captures verified, failed, and manual-only criteria
+4. Marks the phase verified when all automatable criteria pass
 
 ## Usage
 
@@ -19,78 +19,85 @@ If no phase number, auto-detect current phase.
 
 ## Process
 
-### Step 1: Run Tests
+### Step 1: Load the Phase Plan
 
 ```bash
-npm test   # or pytest, go test, etc.
+cat .planning/phases/{N}-PLAN.md
 ```
 
-- ✅ All pass → Continue to human verification
-- ❌ Some fail → Report failures, suggest fixing first
+Pass the detected plan path into `server/lib/e2e/verify-runner.js`:
 
-### Step 2: Load Phase Deliverables
+```js
+const { runVerification } = require('./server/lib/e2e/verify-runner.js');
+```
 
-Read from `.planning/phases/{N}-PLAN.md`:
-- Extract acceptance criteria from each task
-- Build verification checklist
+The runner must be used by default instead of asking the user to validate each criterion manually.
 
-### Step 3: Walk Through Each Deliverable
+### Step 2: Run Automated Verification
 
-For each testable feature:
+Call:
 
+```js
+await runVerification({
+  planPath,
+  projectDir,
+  exec,
+  fs,
+});
 ```
-Phase 1: Authentication
 
-Verifying 3 deliverables:
+Behavior:
+- Parse acceptance criteria from the plan file
+- Detect the available E2E framework
+- Run the matching E2E command automatically
+- Return `{ verified, manual, failed, results }`
 
-[1/3] User login with email/password
+### Step 3: Interpret Results
 
-Can you:
-1. Go to /login
-2. Enter valid credentials
-3. Get redirected to dashboard
+Report each criterion with its status:
 
-Works as expected? (Y/n/describe issue)
->
 ```
+verified: 5
+manual: 1
+failed: 0
 
-### Step 4: Handle Issues
-
-If user reports issue:
+- User can click the export button → verified
+- GET /health endpoint returns 200 → verified
+- Data is retained for 30 days. → manual
 ```
-> n - login works but no error message for wrong password
 
-Got it. Creating fix task:
+Only criteria returned as `manual` should be handed back to a human for confirmation.
 
-Issue: No error message for wrong password
-Location: Login form
-Expected: Show "Invalid credentials" message
+### Step 4: Handle Failures
 
-Add to current phase as fix task? (Y/n)
+If any criteria fail:
+```
+Verification failed:
+- User login redirects to dashboard → failed
+  logErrors: Timeout while waiting for dashboard
 ```
 
+Fix the implementation or tests, then rerun `runVerification(...)`.
+
 ### Step 5: Mark Verified or Loop
 
 **All verified:**
 ```
 ✅ Phase 1 verified
 
-All 3 deliverables confirmed working.
+All automatable acceptance criteria passed.
 
 Creating .planning/phases/1-VERIFIED.md
-
-Ready for next phase? (Y/n)
 ```
 
 **Issues found:**
 ```
 Phase 1 verification incomplete
 
-Issues found:
-1. No error message for wrong password
-2. Session doesn't persist on refresh
+Automated verification failed for 2 criteria.
+1 manual criterion still requires human confirmation.
 
-Fix tasks added to phase. Run /tlc:build 1 to implement fixes.
+Run /tlc:build 1 to implement fixes, then /tlc:verify again.
 ```
 
 ### Step 6: Create Verification Record
@@ -106,7 +113,7 @@ Verified: {date}
 
 - [x] User login with email/password
 - [x] Session persistence
-- [x] Logout functionality
+- [ ] Data retention wording confirmed manually
 
 ## Issues Found & Fixed
 
@@ -118,42 +125,34 @@ Verified: {date}
 {Any additional observations}
 ```
 
-## Why Human Verification?
+## Why This Order?
 
-**Tests verify code works.**
-**You verify it works the way you wanted.**
+**Automated verification should handle every criterion it can.**
+**Humans should only validate what cannot be expressed as a reliable automated check.**
 
-Tests catch:
+Automation catches:
 - Logic errors
 - Regressions
-- Edge cases
+- Broken user flows
 
-You catch:
-- "Technically correct but wrong layout"
-- "Works but confusing UX"
-- "Missing something I forgot to specify"
+Humans catch:
+- Ambiguous qualitative requirements
+- Visual or product judgment not encoded in tests
+- Criteria intentionally marked as manual
 
-Both matter.
+Both still matter, but `/tlc:verify` should not default to a manual checklist when the runner can verify the phase directly.
 
 ## Example
 
 ```
 > /tlc:verify 1
 
-Running tests... ✅ 11 passing
+Loading phase plan... ✅
+Running verify-runner... ✅
 
-Phase 1: Authentication
-
-[1/3] Login with email/password
-Works? (Y/n) > y
-
-[2/3] Session persists across page refresh
-Works? (Y/n) > y
-
-[3/3] Logout clears session
-Works? (Y/n) > y
+verified: 3
+manual: 0
+failed: 0
 
 ✅ Phase 1 verified!
-
-Moving to Phase 2: Dashboard
 ```

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

@@ -157,3 +157,13 @@ Run #4522 (CI) — in progress...
 - 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
+
+## `--detached`
+
+`/tlc:watchci --detached` dispatches CI watching through the local orchestrator instead of keeping the current session attached.
+
+- Send a `POST` request to `http://localhost:3100`
+- Ask the orchestrator to run the CI watch workflow for the current project/branch
+- Return the dispatched session details so the user can check status later
+
+Detached mode changes how the command is launched, not what it does. The orchestrated worker should still follow the same watch/fix loop defined above.

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

@@ -25,11 +25,24 @@ case "$TOOL" in
   ExitPlanMode)
     REASON="BLOCKED by TLC. Plans are approved via /tlc:build, not ExitPlanMode."
     ;;
+  Agent)
+    FLAG_FILE=".tlc/.build-routing-active"
+    if [[ -f "$FLAG_FILE" ]]; then
+      PROVIDER=$(tr -d '[:space:]' < "$FLAG_FILE")
+      if [[ -n "$PROVIDER" && "$PROVIDER" != "claude" ]]; then
+        REASON="BLOCKED by TLC. Agent is routed to ${PROVIDER} while ${FLAG_FILE} is active."
+      fi
+    fi
+    ;;
   *)
     exit 0
     ;;
 esac
 
+if [[ -z "$REASON" ]]; then
+  exit 0
+fi
+
 cat <<EOF
 {
   "hookSpecificOutput": {

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

@@ -43,6 +43,35 @@ else
   done
 fi
 
+# --- tlc-core Orchestrator ---
+# Kill switch: export TLC_CORE_AUTOSTART=false to disable auto-start
+TLC_CORE_PORT="${TLC_CORE_PORT:-3100}"
+if [ "${TLC_CORE_AUTOSTART}" = "false" ]; then
+  echo "tlc-core orchestrator: auto-start disabled (TLC_CORE_AUTOSTART=false)"
+elif curl -sf --max-time 1 "http://localhost:${TLC_CORE_PORT}/health" > /dev/null 2>&1; then
+  SESSIONS=$(curl -sf --max-time 1 "http://localhost:${TLC_CORE_PORT}/sessions" 2>/dev/null | jq "length" 2>/dev/null || echo "0")
+  echo "tlc-core orchestrator: healthy (${SESSIONS} sessions)"
+else
+  # Try to auto-start if tlc-core CLI is available
+  if command -v tlc-core >/dev/null 2>&1; then
+    echo "tlc-core orchestrator: not running — starting..."
+    tlc-core start > /dev/null 2>&1 &
+    # Wait up to 15s for health
+    for i in 1 2 3 4 5; do
+      sleep 3
+      if curl -sf --max-time 1 "http://localhost:${TLC_CORE_PORT}/health" > /dev/null 2>&1; then
+        echo "tlc-core orchestrator: started successfully"
+        break
+      fi
+    done
+    if ! curl -sf --max-time 1 "http://localhost:${TLC_CORE_PORT}/health" > /dev/null 2>&1; then
+      echo "tlc-core orchestrator: failed to start. Run 'tlc-core start' manually."
+    fi
+  else
+    echo "tlc-core orchestrator: not installed. Run: git clone git@github.com:TwentyTwoLabs22/tlc-core.git && cd cli && npm install && npm link"
+  fi
+fi
+
 # ─── Memory System Init ─────────────────────────────
 mkdir -p "$PROJECT_DIR/.tlc/memory/team/decisions" \
          "$PROJECT_DIR/.tlc/memory/team/gotchas" \

package/CODING-STANDARDS.md

@@ -425,16 +425,41 @@ export class AppError extends Error {
   }
 }
 
-export class NotFoundError extends AppError {
-  constructor(entity: string, id: string) {
-    super(`${entity} not found: ${id}`, 'NOT_FOUND', 404);
-  }
-}
-```
-
----
-
-## 13. Deprecated Re-exports
+export class NotFoundError extends AppError {
+  constructor(entity: string, id: string) {
+    super(`${entity} not found: ${id}`, 'NOT_FOUND', 404);
+  }
+}
+```
+
+## Observability
+
+### Structured Logging
+- Use structured JSON logging (`pino` for Node.js, `structlog` for Python, `slog` for Go)
+- Log levels: `ERROR` (needs attention), `WARN` (degraded), `INFO` (business events), `DEBUG` (troubleshooting)
+- Every log must include: `level`, `message`, `context` object, `timestamp`
+- No bare `console.log` for errors; use the project logger
+- No sensitive data in logs (`passwords`, `tokens`, `PII`)
+
+### Connection State Logging
+- Every external connection (DB, Redis, WebSocket, Docker, HTTP client, queue) must log: connect, disconnect, reconnect, and failure
+- Connection state changes are `INFO` level, not `DEBUG`
+- Include connection target in log context (`host`, `port`, database name)
+
+### Health Endpoints
+- Every server project must expose a health endpoint
+- Docker Compose: `GET /health` -> `{ status, dependencies, uptime }`
+- Kubernetes: `GET /healthz` + `/ready` + `/startup` with appropriate checks
+- Health checks must have timeouts (never hang)
+
+### Startup Health
+- Log the state of every dependency on startup
+- `"Connected to Postgres"`, `"Docker socket accessible"`, `"Redis: connection refused"`
+- Never start silently; if a dependency is down, log it at `WARN` level
+
+---
+
+## 13. Deprecated Re-exports
 
 When migrating, old file locations should become deprecated re-exports:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-claude-code",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc-claude-code": "./bin/install.js",

package/server/lib/block-tools-hook.js

@@ -0,0 +1,23 @@
+const fs = require('fs');
+const path = require('path');
+
+const BUILD_ROUTING_FLAG = path.join('.tlc', '.build-routing-active');
+
+function shouldBlockAgent(projectRoot = process.cwd()) {
+  const flagPath = path.join(projectRoot, BUILD_ROUTING_FLAG);
+  if (!fs.existsSync(flagPath)) {
+    return null;
+  }
+
+  const provider = fs.readFileSync(flagPath, 'utf8').trim();
+  if (!provider || provider === 'claude') {
+    return null;
+  }
+
+  return provider;
+}
+
+module.exports = {
+  BUILD_ROUTING_FLAG,
+  shouldBlockAgent,
+};

package/server/lib/e2e/acceptance-parser.js

@@ -0,0 +1,132 @@
+/**
+ * Parse acceptance criteria from plan content into normalized E2E records.
+ */
+
+const CHECKBOX_REGEX = /^\s*[-*]\s*\[[ xX]?\]\s+(.+?)\s*$/;
+const SHOULD_REGEX = /^(?:[-*]\s*)?(?:it\s+)?should\s+(.+)$/i;
+const GIVEN_REGEX = /^\s*(?:[-*]\s*)?(?:\*\*)?given(?:\*\*)?\s*:?\s+(.+?)\s*$/i;
+const WHEN_REGEX = /^\s*(?:[-*]\s*)?(?:\*\*)?when(?:\*\*)?\s*:?\s+(.+?)\s*$/i;
+const THEN_REGEX = /^\s*(?:[-*]\s*)?(?:\*\*)?then(?:\*\*)?\s*:?\s+(.+?)\s*$/i;
+
+function detectType(text) {
+  if (/\b(post|get|api|endpoint)\b/i.test(text)) {
+    return 'api';
+  }
+
+  if (/\b(click|page|button)\b/i.test(text)) {
+    return 'ui';
+  }
+
+  return 'manual';
+}
+
+function normalizeCriterion(text) {
+  return String(text || '')
+    .trim()
+    .replace(/\s+/g, ' ');
+}
+
+function isIgnorableLine(line) {
+  const trimmed = line.trim();
+
+  if (!trimmed) return true;
+  if (/^#{1,6}\s/.test(trimmed)) return true;
+  if (/^\*\*acceptance criteria:?\*\*$/i.test(trimmed)) return true;
+  if (/^acceptance criteria:?$/i.test(trimmed)) return true;
+  if (/^-{3,}$/.test(trimmed)) return true;
+
+  return false;
+}
+
+function parseAcceptanceCriteria({ planContent }) {
+  if (!planContent || typeof planContent !== 'string') {
+    return [];
+  }
+
+  const lines = planContent.replace(/\r\n/g, '\n').split('\n');
+  const criteria = [];
+  const consumed = new Set();
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const givenMatch = lines[index].match(GIVEN_REGEX);
+    if (!givenMatch) continue;
+
+    let cursor = index + 1;
+    while (cursor < lines.length && !lines[cursor].trim()) {
+      cursor += 1;
+    }
+
+    const whenMatch = cursor < lines.length ? lines[cursor].match(WHEN_REGEX) : null;
+    if (!whenMatch) continue;
+
+    cursor += 1;
+    while (cursor < lines.length && !lines[cursor].trim()) {
+      cursor += 1;
+    }
+
+    const thenMatch = cursor < lines.length ? lines[cursor].match(THEN_REGEX) : null;
+    if (!thenMatch) continue;
+
+    const given = normalizeCriterion(givenMatch[1]);
+    const when = normalizeCriterion(whenMatch[1]);
+    const then = normalizeCriterion(thenMatch[1]);
+    const scenario = `Given ${given} When ${when} Then ${then}`;
+
+    criteria.push({
+      criterion: then,
+      type: detectType(scenario),
+      scenario,
+    });
+
+    consumed.add(index);
+    consumed.add(cursor - 1);
+    consumed.add(cursor);
+    index = cursor;
+  }
+
+  for (let index = 0; index < lines.length; index += 1) {
+    if (consumed.has(index)) continue;
+
+    const line = lines[index];
+    if (isIgnorableLine(line)) continue;
+
+    const checkboxMatch = line.match(CHECKBOX_REGEX);
+    if (checkboxMatch) {
+      const criterion = normalizeCriterion(checkboxMatch[1]);
+      criteria.push({
+        criterion,
+        type: detectType(criterion),
+        scenario: null,
+      });
+      continue;
+    }
+
+    const shouldMatch = line.match(SHOULD_REGEX);
+    if (shouldMatch) {
+      const criterion = `should ${normalizeCriterion(shouldMatch[1])}`;
+      criteria.push({
+        criterion,
+        type: detectType(criterion),
+        scenario: null,
+      });
+      continue;
+    }
+
+    const trimmed = line.trim();
+    if (/^(?:[-*]\s*)?(?:given|when|then)\b/i.test(trimmed)) {
+      continue;
+    }
+
+    criteria.push({
+      criterion: normalizeCriterion(trimmed.replace(/^[-*]\s*/, '')),
+      type: detectType(trimmed),
+      scenario: null,
+    });
+  }
+
+  return criteria;
+}
+
+module.exports = {
+  parseAcceptanceCriteria,
+};

package/server/lib/e2e/acceptance-parser.test.js

@@ -0,0 +1,110 @@
+import { describe, it } from 'vitest';
+const assert = require('node:assert');
+
+const { parseAcceptanceCriteria } = require('./acceptance-parser.js');
+
+describe('parseAcceptanceCriteria', () => {
+  it('extracts checkbox criteria and infers types', () => {
+    const result = parseAcceptanceCriteria({
+      planContent: `
+**Acceptance Criteria:**
+- [ ] User can click the save button
+- [x] GET /health endpoint returns 200
+`,
+    });
+
+    assert.deepStrictEqual(result, [
+      {
+        criterion: 'User can click the save button',
+        type: 'ui',
+        scenario: null,
+      },
+      {
+        criterion: 'GET /health endpoint returns 200',
+        type: 'api',
+        scenario: null,
+      },
+    ]);
+  });
+
+  it('extracts Given/When/Then scenarios', () => {
+    const result = parseAcceptanceCriteria({
+      planContent: `
+Given the user is on the login page
+When they click the sign in button
+Then the dashboard page should load
+`,
+    });
+
+    assert.deepStrictEqual(result, [
+      {
+        criterion: 'the dashboard page should load',
+        type: 'ui',
+        scenario: 'Given the user is on the login page When they click the sign in button Then the dashboard page should load',
+      },
+    ]);
+  });
+
+  it('extracts should statements from bullets or plain text', () => {
+    const result = parseAcceptanceCriteria({
+      planContent: `
+should call the API with the updated payload
+- should show the success page
+`,
+    });
+
+    assert.deepStrictEqual(result, [
+      {
+        criterion: 'should call the API with the updated payload',
+        type: 'api',
+        scenario: null,
+      },
+      {
+        criterion: 'should show the success page',
+        type: 'ui',
+        scenario: null,
+      },
+    ]);
+  });
+
+  it('falls back to free-text and marks ambiguous criteria as manual', () => {
+    const result = parseAcceptanceCriteria({
+      planContent: `
+Acceptance Criteria:
+Data is retained for 30 days.
+`,
+    });
+
+    assert.deepStrictEqual(result, [
+      {
+        criterion: 'Data is retained for 30 days.',
+        type: 'manual',
+        scenario: null,
+      },
+    ]);
+  });
+
+  it('ignores markdown structure around parsed lines', () => {
+    const result = parseAcceptanceCriteria({
+      planContent: `
+## Task 4
+
+**Acceptance Criteria:**
+
+Given an admin user
+When they POST /users
+Then the API returns 201
+
+---
+`,
+    });
+
+    assert.deepStrictEqual(result, [
+      {
+        criterion: 'the API returns 201',
+        type: 'api',
+        scenario: 'Given an admin user When they POST /users Then the API returns 201',
+      },
+    ]);
+  });
+});

package/server/lib/e2e/framework-detector.js

@@ -0,0 +1,47 @@
+const path = require('node:path');
+
+function hasDependency(packageJson, dependencyName) {
+  const dependencyGroups = [
+    packageJson.dependencies,
+    packageJson.devDependencies,
+    packageJson.peerDependencies,
+    packageJson.optionalDependencies,
+  ];
+
+  return dependencyGroups.some(
+    (dependencies) =>
+      dependencies &&
+      typeof dependencies === 'object' &&
+      Object.prototype.hasOwnProperty.call(dependencies, dependencyName)
+  );
+}
+
+function readPackageJson(packageJsonPath, fs) {
+  try {
+    const packageJsonText = fs.readFileSync(packageJsonPath, 'utf8');
+    return JSON.parse(packageJsonText);
+  } catch (error) {
+    return null;
+  }
+}
+
+function detectE2eFramework({ projectDir, fs }) {
+  const packageJsonPath = path.join(projectDir, 'package.json');
+  const playwrightConfigPath = path.join(projectDir, 'playwright.config.ts');
+  const packageJson = readPackageJson(packageJsonPath, fs);
+  const hasPlaywrightConfig = fs.existsSync(playwrightConfigPath);
+
+  if (hasPlaywrightConfig) {
+    return { framework: 'playwright' };
+  }
+
+  if (packageJson && hasDependency(packageJson, 'supertest')) {
+    return { framework: 'supertest' };
+  }
+
+  return { framework: 'none' };
+}
+
+module.exports = {
+  detectE2eFramework,
+};