tlc-claude-code 1.2.5 → 1.2.7

package/help.md

@@ -115,6 +115,8 @@ That's it. `/tlc` handles everything:
  ↓
  Rebase detected? → "Run sync? (Y/n)" → Reconcile
  ↓
+ Main ahead? → "Integrate? [1/2]" → Read & rebuild (no rebase)
+ ↓
  Already synced? → Dashboard + next actions
 ```
 
@@ -125,6 +127,13 @@ git rebase origin/main
 /tlc                    ← Detects changes, asks, syncs, continues
 ```
 
+**When main is ahead (no rebase):**
+```
+/tlc                    ← Detects main ahead, offers to integrate
+    ↓
+[1] Integrate          ← Claude reads changes, rebuilds locally
+```
+
 ---
 
 ## What `/tlc` Does

package/package.json

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

package/sync.md

@@ -8,6 +8,8 @@ The unified entry point for TLC adoption and codebase synchronization.
 
 **Post-rebase:** Detect changes and reconcile incoming code with TLC standards.
 
+**Main ahead:** Read changes from main, understand context, rebuild locally without rebasing.
+
 ## Usage
 
 ```
@@ -16,20 +18,42 @@ The unified entry point for TLC adoption and codebase synchronization.
 
 No arguments. TLC auto-detects the scenario.
 
-## Scenario Detection
+## CRITICAL: Execution Flow
+
+**You MUST detect the scenario FIRST, then execute ONLY that scenario.**
 
 ```
-Check for .tlc.json:
-  ├── Not found → First-time adoption
-  └── Found → Check for changes
-                 ├── HEAD matches lastSync → Already synced
-                 └── HEAD differs → Post-rebase reconciliation
+Step 1: Check for .tlc.json
+        │
+        ├── NOT FOUND → Execute "Scenario 1: First-Time Adoption" ONLY
+        │
+        └── FOUND → Step 2: Check branch status
+                    │
+                    ├── HEAD == lastSync AND main not ahead → "✓ Already synced" STOP
+                    │
+                    ├── HEAD != lastSync → Execute "Scenario 2: Post-Rebase" ONLY
+                    │
+                    └── Main is ahead of current branch → Execute "Scenario 3: Integrate Main" ONLY
+```
+
+**Detection for "main ahead":**
+```bash
+mainBranch=$(jq -r '.git.mainBranch // "main"' .tlc.json)
+git fetch origin $mainBranch
+behindCount=$(git rev-list HEAD..origin/$mainBranch --count)
+if [ "$behindCount" -gt 0 ]; then
+  # Main is ahead - offer Scenario 3
+fi
 ```
 
+**DO NOT run multiple scenarios. Pick ONE based on detection.**
+
 ---
 
 ## Scenario 1: First-Time Adoption
 
+**ONLY run this if .tlc.json does NOT exist.**
+
 Complete onboarding questionnaire. All settings in one flow so nothing gets forgotten.
 
 ### Step 1.1: Welcome
@@ -293,6 +317,8 @@ Happy testing! 🧪
 
 ## Scenario 2: Post-Rebase Reconciliation
 
+**ONLY run this if .tlc.json EXISTS and HEAD differs from lastSync.**
+
 Detect and handle code changes from rebase.
 
 ### Step 2.1: Detect Changes
@@ -358,254 +384,219 @@ Changes detected:
   Tests for new code: 0 found ⚠️
 ```
 
-### Step 2.3: Choose Reconciliation Strategy
+### Step 2.3: Auto-Sync (Default Behavior)
 
-```
-─────────────────────────────────────────────────────
- RECONCILIATION STRATEGY
-─────────────────────────────────────────────────────
-
-How should TLC handle the incoming code?
-
-[1] CONFORM TO TLC (Recommended)
-    → Analyze incoming code
-    → Generate tests for new files
-    → Apply TLC patterns (if needed)
-    → May modify incoming files
-
-    Best when: You want all code to follow TLC standards
-
-[2] PRESERVE INCOMING
-    → Keep incoming code exactly as-is
-    → Update YOUR existing code to work with it
-    → Incoming files are untouched
+**DO NOT ask about individual files. Just sync automatically.**
 
-    Best when: Incoming code is reviewed/approved,
-    you just need to integrate
-
-[3] MANUAL REVIEW
-    → Show detailed diff
-    → Let me decide file-by-file
-
-    Best when: Mixed situation, some files need
-    conforming, others should be preserved
-
-Choice [1/2/3]: _
 ```
+Syncing...
 
-### Step 2.4a: Strategy - Conform to TLC
+✓ Updated lastSync to ${currentHead:0:7}
+✓ Removed rebase marker (if present)
 
+Sync complete.
 ```
-─────────────────────────────────────────────────────
- CONFORMING INCOMING CODE TO TLC
-─────────────────────────────────────────────────────
-
-Analyzing 4 new files...
-
-src/api/payments.ts
-  → No tests found
-  → Generating: tests/api/payments.test.ts
-  → 6 test cases identified
-
-src/api/webhooks.ts
-  → No tests found
-  → Generating: tests/api/webhooks.test.ts
-  → 4 test cases identified
-
-src/services/stripe.ts
-  → No tests found
-  → Generating: tests/services/stripe.test.ts
-  → 8 test cases identified (mocking Stripe API)
 
-src/utils/currency.ts
-  → No tests found
-  → Generating: tests/utils/currency.test.ts
-  → 5 test cases identified
+That's it. The sync just updates the tracking. Tests are written when you run `/tlc:build`.
 
-Analyzing 7 modified files...
+**Why no file-by-file questions?**
+- Incoming code was already reviewed in the PR
+- Tests will be written during the build phase
+- Asking about every file is annoying and slow
 
-src/api/users.ts
-  → Existing tests: tests/api/users.test.ts
-  → 2 new functions added, need 3 new test cases
-  → Updating test file
+### Step 2.4: Optional - Add Tests for Untested Code
 
-src/db/schema.ts
-  → Existing tests cover changes ✓
+If `.tlc.json` has `existingCode.strategy: "backlog"`, silently note any new untested files:
 
-...
+```bash
+# Find new source files without tests
+newUntested=$(for f in $newFiles; do
+  if [[ $f == src/* ]] && ! [ -f "tests/${f#src/}" ]; then
+    echo "$f"
+  fi
+done)
 
-─────────────────────────────────────────────────────
- PROPOSED CHANGES
-─────────────────────────────────────────────────────
+if [ -n "$newUntested" ]; then
+  echo "Note: $(echo "$newUntested" | wc -l) new files added to test backlog"
+fi
+```
 
-Will create:
-  + tests/api/payments.test.ts (6 tests)
-  + tests/api/webhooks.test.ts (4 tests)
-  + tests/services/stripe.test.ts (8 tests)
-  + tests/utils/currency.test.ts (5 tests)
+DO NOT ask about them. Just note and continue.
 
-Will update:
-  ~ tests/api/users.test.ts (+3 tests)
+### Step 2.6: Update Sync State
 
-Total: 26 new tests
+After sync completes:
 
-Apply changes? (Y/n): _
-```
+```bash
+# Update lastSync in .tlc.json
+currentHead=$(git rev-parse HEAD)
+jq ".lastSync = \"$currentHead\"" .tlc.json > .tlc.json.tmp
+mv .tlc.json.tmp .tlc.json
 
-If confirmed, write tests and run them:
+# Remove rebase marker if exists
+rm -f .tlc-rebase-marker
 
+# Commit the sync
+git add .
+git commit -m "sync: reconcile changes from rebase"
 ```
-Creating tests...
 
-✓ tests/api/payments.test.ts
-  Running... 6 passing
+---
 
-✓ tests/api/webhooks.test.ts
-  Running... 4 passing
+## Scenario 3: Integrate Main (No Rebase)
 
-✓ tests/services/stripe.test.ts
-  Running... 7 passing, 1 failing
+**ONLY run this if main branch is ahead of current branch.**
 
-  ⚠️ stripe.test.ts:45 - handleRefund expects different response
+This is for when you want to incorporate changes from main WITHOUT rebasing. Claude reads and understands the changes, then rebuilds them in your branch's context.
 
-  Options:
-    [1] Fix the test (incoming code is correct)
-    [2] Fix the code (test expectation is correct)
-    [3] Skip for now (add to backlog)
+### When to Use This
 
-  Choice: _
+- Rebase would cause too many conflicts
+- You want to cherry-pick specific improvements
+- You need to understand what changed before integrating
+- Your branch has diverged significantly from main
 
-✓ tests/utils/currency.test.ts
-  Running... 5 passing
+### Step 3.1: Detect Main Ahead
 
-✓ tests/api/users.test.ts (updated)
-  Running... 12 passing
+```bash
+mainBranch=$(jq -r '.git.mainBranch // "main"' .tlc.json)
+git fetch origin $mainBranch
+
+behindCount=$(git rev-list HEAD..origin/$mainBranch --count)
+aheadCount=$(git rev-list origin/$mainBranch..HEAD --count)
+
+if [ "$behindCount" -gt 0 ]; then
+  echo "─────────────────────────────────────────────────────"
+  echo " MAIN IS AHEAD"
+  echo "─────────────────────────────────────────────────────"
+  echo ""
+  echo "Your branch: $(git branch --show-current)"
+  echo "Main branch: $mainBranch"
+  echo ""
+  echo "  $behindCount commits behind main"
+  echo "  $aheadCount commits ahead of main"
+  echo ""
+  echo "Options:"
+  echo "  [1] Integrate changes (read & rebuild without rebase)"
+  echo "  [2] Skip for now"
+  echo ""
+  echo "Choice [1/2]: _"
+fi
+```
 
-─────────────────────────────────────────────────────
+### Step 3.2: Analyze Main's Changes
 
-Sync complete!
-  → 25 tests passing
-  → 1 issue added to backlog
-  → Committed: "sync: add tests for rebased code"
+If user chooses to integrate:
 
-Updated .tlc.json lastSync to def456
+```bash
+# Get the changes from main that we don't have
+git log --oneline HEAD..origin/$mainBranch
+git diff HEAD...origin/$mainBranch --stat
 ```
 
-### Step 2.4b: Strategy - Preserve Incoming
+Present summary:
 
 ```
 ─────────────────────────────────────────────────────
- PRESERVING INCOMING CODE
+ CHANGES IN MAIN
 ─────────────────────────────────────────────────────
 
-Incoming files will NOT be modified.
-Checking integration points...
-
-Analyzing impact on existing TLC code...
+12 commits to integrate:
 
-src/api/users.ts (incoming) affects:
-  → tests/api/users.test.ts (yours)
-    3 tests now failing due to API changes
+  abc1234 feat: add payment processing
+  def5678 fix: user validation bug
+  ghi9012 refactor: cleanup auth module
+  ...
 
-src/db/schema.ts (incoming) affects:
-  → tests/db/schema.test.ts (yours)
-    1 test failing - new required field
-  → src/api/auth.ts (yours)
-    Type error - User type changed
+Files changed: 23
+  + 8 new files
+  ~ 12 modified files
+  - 3 deleted files
 
-─────────────────────────────────────────────────────
- REQUIRED UPDATES TO YOUR CODE
-─────────────────────────────────────────────────────
-
-To integrate incoming changes, TLC needs to update:
-
-  tests/api/users.test.ts
-    → Update 3 test expectations to match new API
-
-  tests/db/schema.test.ts
-    → Add required field to test fixtures
+Key changes:
+  • New payment system (src/payments/*)
+  • Auth module refactored
+  • Bug fixes in user validation
+```
 
-  src/api/auth.ts
-    → Update User type usage (line 45, 67)
+### Step 3.3: Read and Understand
 
-Apply updates? (Y/n): _
-```
+**Claude reads the actual changes (not just filenames):**
 
-If confirmed:
+```bash
+# Read new files entirely
+for f in $(git diff --name-only --diff-filter=A HEAD...origin/$mainBranch); do
+  git show origin/$mainBranch:$f
+done
 
+# Read diffs for modified files
+git diff HEAD...origin/$mainBranch
 ```
-Updating your code to integrate...
-
-✓ tests/api/users.test.ts - 3 expectations updated
-✓ tests/db/schema.test.ts - fixture updated
-✓ src/api/auth.ts - type usage fixed
 
-Running all tests...
-✓ 47 passing
+**Build context:**
+- What new features were added?
+- What bugs were fixed?
+- What was refactored and why?
+- What was deleted and why?
 
-Sync complete!
-  → Incoming code preserved
-  → Your code updated to integrate
-  → Committed: "sync: integrate rebased changes"
+### Step 3.4: Rebuild Locally
 
-Updated .tlc.json lastSync to def456
-```
+Instead of rebasing, Claude:
 
-### Step 2.4c: Strategy - Manual Review
+1. **Creates new files** based on understanding (not copy-paste)
+2. **Applies fixes** to your branch's version of files
+3. **Incorporates refactors** that make sense in your context
+4. **Skips changes** that conflict with your work (notes them)
 
 ```
 ─────────────────────────────────────────────────────
- MANUAL FILE-BY-FILE REVIEW
+ INTEGRATING CHANGES
 ─────────────────────────────────────────────────────
 
-Review each changed file:
+Reading main's changes...
 
-[1/4] src/api/payments.ts (NEW)
+✓ New: src/payments/processor.ts
+  → Created in your branch (adapted to your patterns)
 
-      No tests. 142 lines. Payment processing logic.
+✓ Fix: src/api/users.ts - validation bug
+  → Applied fix to your version
 
-      Action:
-        [C] Conform - generate tests
-        [P] Preserve - add to backlog for later
-        [S] Skip - ignore this file
+✓ Refactor: src/auth/login.ts
+  → Incorporated improvements
 
-      Choice: _
+⚠ Skipped: src/api/orders.ts
+  → Conflicts with your changes (noted for manual review)
 
-[2/4] src/api/webhooks.ts (NEW)
-      ...
+─────────────────────────────────────────────────────
 
-[3/4] src/api/users.ts (MODIFIED)
+Integrated 11 of 12 changes.
+1 change skipped (see .planning/INTEGRATION-NOTES.md)
 
-      Changes: +45 lines, -12 lines
-      2 new functions: updateProfile, deleteAccount
+Commit these changes? (Y/n): _
+```
 
-      Existing tests: tests/api/users.test.ts
-      Tests affected: 3 failing
+### Step 3.5: Commit Integration
 
-      Action:
-        [C] Conform - update tests for new behavior
-        [P] Preserve - update your code to match
-        [V] View diff
+```bash
+git add -A
+git commit -m "integrate: incorporate changes from main (no rebase)
 
-      Choice: _
-```
+Changes integrated:
+- Payment processing system
+- User validation fix
+- Auth module improvements
 
-### Step 2.5: Update Sync State
+Skipped (manual review needed):
+- src/api/orders.ts (conflicts with current work)"
+```
 
-After any strategy completes:
+### Step 3.6: Update Sync State
 
 ```bash
-# Update lastSync in .tlc.json
-currentHead=$(git rev-parse HEAD)
-jq ".lastSync = \"$currentHead\"" .tlc.json > .tlc.json.tmp
+# Note that we've seen main's changes (even if not fully merged)
+mainHead=$(git rev-parse origin/$mainBranch)
+jq ".lastMainCheck = \"$mainHead\"" .tlc.json > .tlc.json.tmp
 mv .tlc.json.tmp .tlc.json
-
-# Remove rebase marker if exists
-rm -f .tlc-rebase-marker
-
-# Commit the sync
-git add .
-git commit -m "sync: reconcile changes from rebase"
 ```
 
 ---
@@ -655,26 +646,7 @@ Run: git init
 **Uncommitted changes:**
 ```
 ⚠️ You have uncommitted changes.
-
-TLC sync works best with a clean working tree.
-Options:
-  [1] Stash changes, sync, then restore
-  [2] Commit changes first
-  [3] Continue anyway (not recommended)
-
-Choice: _
+Commit or stash them before syncing.
 ```
 
-**Merge conflicts during reconciliation:**
-```
-⚠️ Conflict in tests/api/users.test.ts
-
-The incoming code and your tests have conflicting changes.
-
-Options:
-  [1] Keep yours (incoming tests discarded)
-  [2] Keep theirs (your tests replaced)
-  [3] Open in editor to resolve manually
-
-Choice: _
-```
+Then stop. Don't offer choices.

package/tlc.md

@@ -34,57 +34,69 @@ if [ ! -f ".tlc.json" ]; then
   echo "This configures test framework, team settings, quality gates, and more."
   echo ""
   echo "Run setup now? (Y/n)"
-  # If yes → Run /tlc:sync inline (first-time flow)
+  # If yes → Run sync.md "Scenario 1: First-Time Adoption" ONLY
+  # DO NOT run Scenario 2
   # Then continue to Step 1
+  exit  # Don't fall through to other checks
 fi
 
-# Check for rebase marker
-if [ -f ".tlc-rebase-marker" ]; then
-  echo "⚠️ Rebase detected since last sync."
-  echo ""
-  echo "TLC needs to reconcile incoming changes."
-  echo "This ensures new code meets TLC standards."
-  echo ""
-  echo "Run sync now? (Y/n)"
-  # If yes → Run /tlc:sync inline (post-rebase flow)
-  # Then continue to Step 1
-fi
-
-# Check if HEAD matches lastSync
+# .tlc.json exists - check sync state
 lastSync=$(jq -r '.lastSync // ""' .tlc.json)
 currentHead=$(git rev-parse HEAD 2>/dev/null)
 
-# If lastSync missing, initialize it (existing config, first sync tracking)
+# If lastSync missing, initialize it
 if [ -z "$lastSync" ]; then
   echo "Initializing sync tracking..."
-  # Update .tlc.json with current HEAD as lastSync
   jq ".lastSync = \"$currentHead\"" .tlc.json > .tlc.json.tmp && mv .tlc.json.tmp .tlc.json
   echo "✓ Synced (initialized to ${currentHead:0:7})"
-  # Continue to Step 1
+  # Continue to Step 1 - NO sync needed
 fi
 
-if [ -n "$lastSync" ] && [ "$lastSync" != "$currentHead" ]; then
+# Check for rebase marker OR HEAD mismatch
+if [ -f ".tlc-rebase-marker" ] || [ "$lastSync" != "$currentHead" ]; then
   echo "⚠️ Codebase changed since last sync."
   echo "   Last sync: ${lastSync:0:7}"
   echo "   Current:   ${currentHead:0:7}"
-  echo ""
   changedCount=$(git diff --name-only $lastSync $currentHead 2>/dev/null | wc -l)
   echo "   $changedCount files changed"
   echo ""
   echo "Run sync now? (Y/n)"
-  # If yes → Run /tlc:sync inline (post-rebase flow)
+  # If yes → Run sync.md "Scenario 2: Post-Rebase Reconciliation" ONLY
+  # DO NOT run Scenario 1 (no questionnaire!)
   # Then continue to Step 1
+  exit  # Don't fall through to main-ahead check
+fi
+
+# Check if main is ahead of current branch
+mainBranch=$(jq -r '.git.mainBranch // "main"' .tlc.json)
+git fetch origin $mainBranch 2>/dev/null
+behindCount=$(git rev-list HEAD..origin/$mainBranch --count 2>/dev/null)
+
+if [ "$behindCount" -gt 0 ]; then
+  echo "⚠️ Main branch is $behindCount commits ahead."
+  echo ""
+  echo "Options:"
+  echo "  [1] Integrate changes (read & rebuild without rebase)"
+  echo "  [2] Skip for now"
+  echo ""
+  # If 1 → Run sync.md "Scenario 3: Integrate Main" ONLY
+  # If 2 → Continue to dashboard
 fi
 
 # If we get here, sync is current
 echo "✓ Synced"
 ```
 
-**Key behavior:**
-- Detects if sync needed
-- Asks for confirmation
-- Runs sync flow inline (not separate command)
-- Then continues to dashboard/status
+**CRITICAL - Which sync scenario to run:**
+
+| Condition | Action |
+|-----------|--------|
+| No `.tlc.json` | Run sync.md **Scenario 1** (questionnaire) |
+| `.tlc.json` exists, HEAD changed | Run sync.md **Scenario 2** (reconciliation only, NO questionnaire) |
+| Main is ahead of current branch | Run sync.md **Scenario 3** (integrate without rebase) |
+| `.tlc.json` exists, all synced | Already synced, skip to dashboard |
+
+**The questionnaire ONLY runs on first-time setup, NEVER after rebase or integrate.**
 
 User never needs to know about `/tlc:sync` as a separate command - `/tlc` handles everything.