tlc-claude-code 2.4.2 → 2.4.3

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

@@ -276,6 +276,34 @@ This is the core TLC command. Tests before code, one task at a time.
 
 ## Process
 
+### Step 0: Create Phase Branch (Mandatory)
+
+**Never commit directly to the main branch.** Before ANY work begins:
+
+```bash
+# Get main branch name from .tlc.json or default to "main"
+mainBranch=$(node -e "try{console.log(require('./.tlc.json').git?.mainBranch||'main')}catch{console.log('main')}" 2>/dev/null)
+
+# Check if already on a phase branch
+currentBranch=$(git branch --show-current)
+if [[ "$currentBranch" == phase/* ]]; then
+  echo "Already on phase branch: $currentBranch"
+else
+  # Create phase branch
+  branchName="phase/${phase_number}"
+  git checkout -b "$branchName" "$mainBranch" 2>/dev/null || git checkout "$branchName"
+  echo "Working on branch: $branchName"
+fi
+```
+
+**This is not optional.** All commits go to the phase branch. When the phase is complete:
+1. Push the branch: `git push -u origin phase/{N}`
+2. Create PR: `gh pr create --base main --head phase/{N}`
+3. CI validates on the PR
+4. Merge when green
+
+**Why:** TLC projects use integration branches. Committing to main bypasses CI, review, and the PR workflow we built. Eat your own soup.
+
 ### Step 1: Load Plans
 
 Read all `.planning/phases/{phase}-*-PLAN.md` files for this phase.
@@ -916,6 +944,46 @@ Verdict: ❌ CHANGES REQUESTED
 
 **CRITICAL: Phase is NOT complete until review passes.**
 
+### Step 11: Push Branch and Create PR (Mandatory)
+
+**After review passes, push the phase branch and create a PR. Ask the user before pushing.**
+
+```bash
+# Get current branch
+branchName=$(git branch --show-current)
+mainBranch=$(node -e "try{console.log(require('./.tlc.json').git?.mainBranch||'main')}catch{console.log('main')}" 2>/dev/null)
+
+# Confirm with user
+echo "Phase complete. Ready to push $branchName and create PR to $mainBranch?"
+```
+
+After user approval:
+
+```bash
+# Push branch
+git push -u origin "$branchName"
+
+# Create PR with phase summary
+gh pr create \
+  --base "$mainBranch" \
+  --head "$branchName" \
+  --title "Phase {N}: {Phase Name}" \
+  --body "## Summary
+- {task count} tasks completed
+- {test count} tests passing
+- Review: APPROVED
+
+## Tasks
+{list of completed tasks from PLAN.md}
+
+## Test Results
+{test runner summary}"
+```
+
+**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.
+
 ## Framework Defaults
 
 ### TLC Default: Mocha Stack

package/.claude/commands/tlc/discuss.md

@@ -99,7 +99,13 @@ process.stdout.write(JSON.stringify(result));" 2>/dev/null
 
 ## What This Does
 
-Gathers your preferences for HOW a phase should be built through adaptive questioning. Saves decisions to guide planning and test writing.
+Runs a short implementation interview for the current phase using a silent expansion workflow:
+- First scan the phase goal, codebase patterns, stack, and recent changes
+- Then propose a concrete implementation approach before asking questions
+- Ask only questions that materially improve the plan
+- Save decisions, trade-offs, and constraints to `.planning/phases/{N}-DISCUSSION.md`
+
+This command is not a blank-page brainstorming prompt. The agent should do the initial thinking first, then ask the user to confirm or correct the proposal.
 
 ## Usage
 
@@ -107,174 +113,219 @@ Gathers your preferences for HOW a phase should be built through adaptive questi
 /tlc:discuss [phase_number]
 ```
 
-If no phase number, auto-detect current phase from ROADMAP.md.
+If no phase number, auto-detect current phase from `.planning/ROADMAP.md`.
 
 ## Process
 
-### Step 1: Load Phase Context
+### Step 1: Scan Context First
 
-Read from `.planning/ROADMAP.md` to get:
-- Phase name and goal
-- What comes before (context)
-- What comes after (constraints)
+Before asking anything, silently inspect the implementation context for the phase.
 
-### Step 2: Adaptive Questioning
+Read:
+- `.planning/ROADMAP.md` - current phase name, goal, and surrounding phase context
+- `PROJECT.md` - product constraints, stack, architecture, conventions
+- `.planning/phases/{N}-DISCUSSION.md` if it exists - previously made decisions and unresolved gaps
+- Relevant code for the phase area - existing modules, patterns, folder structure, interfaces, tests
 
-Ask about implementation preferences. Adapt questions based on phase type.
+Also inspect:
+- Tech stack already in use
+- Existing implementation patterns that should be preserved
+- Recent git changes that affect the phase direction, integration surface, or constraints
 
-**For UI/Frontend phases:**
-```
-Layout approach?
-1) Component library (shadcn, MUI, etc.)
-2) Custom components
-3) Minimal styling (Tailwind only)
-
-State management?
-1) React state + context
-2) Zustand / Jotai
-3) Redux
-4) Server state only (React Query)
-
-Form handling?
-1) React Hook Form
-2) Formik
-3) Native forms
-```
+The scan should answer:
+- What is this phase trying to accomplish?
+- What implementation shape is most consistent with the current codebase?
+- What decisions are already implied by the stack or recent work?
+- What is still genuinely ambiguous?
 
-**For API/Backend phases:**
-```
-API style?
-1) REST
-2) tRPC
-3) GraphQL
-
-Validation approach?
-1) Zod schemas
-2) Yup
-3) Manual validation
-
-Error handling?
-1) Return error objects
-2) Throw exceptions
-3) Result types (Ok/Err)
-```
+Do not ask the user to restate information that can be learned from the repo.
 
-**For Data/Database phases:**
-```
-Query approach?
-1) Raw SQL
-2) Query builder (Kysely, Knex)
-3) ORM (Prisma, Drizzle)
-
-Migration strategy?
-1) Schema-first (Prisma migrate)
-2) Code-first
-3) Manual SQL migrations
-```
+### Step 2: Expand Before Asking
 
-**For Auth phases:**
-```
-Auth provider?
-1) Custom (JWT + bcrypt)
-2) NextAuth / Auth.js
-3) Clerk / Auth0 / Supabase Auth
-
-Session storage?
-1) JWT in httpOnly cookie
-2) Database sessions
-3) Redis sessions
-```
+After scanning, propose a full default implementation approach before any questions.
 
-### Step 3: Capture Edge Cases
+The proposal should be concrete enough that the user can react to it:
+- Architecture and boundaries
+- Main components/modules/files involved
+- Data flow or request flow
+- Key trade-offs
+- Constraints or risks that seem likely
+- Assumptions inferred from the stack and recent code
 
-```
-What edge cases should we handle?
+The proposal should sound like:
+
+```text
+Based on the roadmap goal, current patterns, and recent changes, I would implement this as:
+- ...
+- ...
 
-- Empty states?
-- Error states?
-- Loading states?
-- Offline behavior?
-- Rate limiting?
+The main open decisions I still need to confirm are:
+1. ...
+2. ...
 ```
 
-### Step 4: Capture Constraints
+Do not ask "What do you want?" or "How should we build this?" before giving a recommendation.
 
-```
-Any constraints or requirements?
+### Step 3: Filter Questions Aggressively
+
+Only ask a question if removing it would degrade the resulting `DISCUSSION.md` or weaken the next `/tlc:plan`.
+
+Each question must extract substance such as:
+- Architectural decisions
+- Integration boundaries
+- Operational constraints
+- Failure-mode handling
+- Trade-offs that materially change implementation
+
+Do not ask about preferences that do not affect the outcome, such as:
+- Naming choices
+- Formatting
+- Minor stylistic conventions
+- Options already dictated by the existing stack unless there is a real conflict
+
+Bad:
+- "What database should we use?"
+- "How do you want this named?"
+
+Good:
+- "I would keep this on SQLite with WAL mode because the project already uses local-first storage and recent work assumes file-backed state. Any reason to use a different persistence strategy?"
+- "I would model this as a service plus thin CLI adapter to match the existing command architecture. Good, or do you need a different boundary for reuse/testing?"
 
-- Performance targets?
-- Accessibility requirements?
-- Browser support?
-- Mobile considerations?
+### Step 4: Ask Propose-Then-Confirm Questions
+
+Every question must include:
+- The recommended answer
+- The evidence behind that recommendation
+- The decision to confirm or correct
+
+Question style:
+
+```text
+1. Persistence
+I would use SQLite with WAL mode because the current stack is local-first and this phase needs durable state with low operational overhead.
+Good to keep that, or do you need a different storage model for sync/concurrency reasons?
 ```
 
-### Step 5: Save Discussion
+Prefer questions that let the user confirm, reject, or constrain the recommendation.
+
+### Step 5: Calibrate Depth
+
+Choose question count based on phase complexity.
 
-Create `.planning/phases/{N}-DISCUSSION.md`:
+For simple phases:
+- Ask 2-3 questions maximum
+- Focus on the few decisions that materially change scope or architecture
+
+For complex phases:
+- Ask 5-8 questions
+- Cover the major decision surfaces only
+
+Complexity signals include:
+- Multiple subsystems or services
+- New infrastructure or persistence
+- Cross-cutting auth/security concerns
+- Large UX flows with state transitions
+- Significant ambiguity in roadmap wording
+
+Do not turn straightforward phases into long interviews.
+
+### Step 6: Iterate When Answers Reveal New Gaps
+
+If the user’s answers expose a new implementation gap, contradiction, or constraint, ask targeted follow-up questions.
+
+Follow-up questions must also use the same pattern:
+- explain the inferred implication
+- recommend the likely answer
+- ask for confirmation/correction
+
+Stop when the remaining uncertainty no longer meaningfully affects planning.
+
+### Step 7: Write Concrete Decisions
+
+Create or update `.planning/phases/{N}-DISCUSSION.md`.
+
+The file must contain decisions and rationale, not a transcript of the conversation.
+
+Use this structure:
 
 ```markdown
 # Phase {N}: {Name} - Discussion
 
-## Implementation Preferences
+## Proposed Approach
 
-| Decision | Choice | Notes |
-|----------|--------|-------|
-| State management | Zustand | Simple, minimal boilerplate |
-| Form handling | React Hook Form | Good validation support |
-| API style | tRPC | Type-safe, good DX |
+[Short summary of the implementation direction that emerged from the scan and discussion]
 
-## Edge Cases to Handle
+## Decisions
 
-- [ ] Empty state when no data
-- [ ] Error toast on API failure
-- [ ] Optimistic updates for better UX
+| Decision | Recommendation | Confirmed / Adjusted | Why It Matters |
+|----------|----------------|----------------------|----------------|
+| Service boundary | Core service with thin CLI adapter | Confirmed | Matches existing command architecture and keeps logic testable |
+| Persistence | SQLite with WAL mode | Adjusted: in-memory for this phase | Avoids premature persistence until sync arrives |
 
 ## Constraints
 
-- Must work on mobile
-- Target 100ms API response time
+- Must preserve existing module boundaries
+- Must work with current local-first workflow
+- Must remain compatible with `/tlc:plan`
 
-## Notes
+## Risks / Follow-Ups
 
-[Any additional context from discussion]
-```
+- Migration path needed if persistence changes in later phases
+- Error handling contract should be validated in planning
 
-### Step 6: Confirm and Continue
+## Planning Notes
 
+- Call out concrete file/module areas likely to change
+- Record unresolved items only if they materially affect planning
 ```
-Discussion saved to .planning/phases/{N}-DISCUSSION.md
 
-Ready to plan this phase?
-1) Yes, continue to /tlc:plan
-2) No, I'll plan later
-```
+Guidelines for the output:
+- Prefer concrete decisions over raw notes
+- Capture trade-offs and rationale briefly
+- Record unresolved questions only if they still matter for `/tlc:plan`
+- Do not dump the full interview transcript
 
-## Example
+### Step 8: Confirm Next Step
+
+After writing the file, report:
+
+```text
+Discussion saved to .planning/phases/{N}-DISCUSSION.md
 
+Ready to continue with /tlc:plan?
+1) Yes
+2) No
 ```
-> /tlc:discuss 2
 
-Phase 2: User Dashboard
+## Interview Rules
 
-Let's discuss how to build this.
+- Scan before asking
+- Propose before questioning
+- Ask only high-leverage questions
+- Recommend an answer in every question
+- Prefer substance over preference
+- Adapt question count to phase complexity
+- Add follow-ups only when answers reveal real new gaps
+- Produce a decision document, not a transcript
 
-State management approach?
-1) React state + context
-2) Zustand
-3) Server state only (React Query)
+## Example Opening
 
-> 3
+```text
+> /tlc:discuss 2
+
+Phase 2: User Dashboard
 
-Data fetching?
-1) REST + fetch
-2) tRPC
-3) React Query + REST
+Based on the roadmap goal, the existing React + tRPC patterns, and recent changes in the dashboard data layer, I would implement this as a server-driven dashboard shell with a thin client state layer for filters and optimistic updates.
 
-> 2
+I would keep data fetching in the existing query pattern, add one aggregation endpoint for summary cards, and keep widget rendering as local components rather than introducing a new layout system.
 
-[...continues until preferences captured...]
+The main decisions I still need to confirm are:
 
-Discussion saved.
+1. Dashboard state boundary
+I would keep filter/sort state in URL params plus local component state so it stays shareable without introducing a global store.
+Good, or do you need cross-page state that justifies Zustand?
 
-Ready to plan? (Y/n)
+2. Empty/loading/error behavior
+I would standardize on skeleton loading plus inline empty states because that matches current UI behavior and keeps failure modes visible per widget.
+Good, or do you need a page-level loading/error shell?
 ```

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

@@ -78,7 +78,7 @@ await page.screenshot({ path: '/tmp/tlc-screenshots/login.png', fullPage: true }
 
 // After login
 await page.fill('[data-testid="email"]', 'user@local.com');
-await page.fill('[data-testid="password"]', '2026rocks');
+await page.fill('[data-testid="password"]', 'REDACTED');
 await page.click('[data-testid="login-btn"]');
 await page.waitForURL('**/dashboard**');
 await page.screenshot({ path: '/tmp/tlc-screenshots/after-login.png', fullPage: true });

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

@@ -111,6 +111,7 @@ process.stdout.write(JSON.stringify(result));" 2>/dev/null
 - **Extension points**: Where will this need to grow? Plan for it.
 - **Error boundaries**: Where can failures occur? How are they handled?
 - **Data flow**: How does data enter, transform, and exit the system?
+- **Outcome constraints**: Define required behaviors, scale limits, latency targets, and failure handling. Avoid prescribing implementation mechanics unless a constraint is already fixed by the system.
 
 ### Code Quality Gates
 - **File size limit**: No file should exceed 1000 lines. Plan splits for large modules.
@@ -122,6 +123,7 @@ process.stdout.write(JSON.stringify(result));" 2>/dev/null
 - **Vertical slices**: Each task delivers testable, visible progress
 - **Risk-first**: Tackle unknowns and integrations early
 - **Dependencies explicit**: Mark what blocks what
+- **Strategic purpose clear**: Every task explains why it exists, what risk it retires, or what capability it unlocks
 
 ## What This Does
 
@@ -163,12 +165,21 @@ Each task should be:
 - **Testable** - has clear pass/fail criteria
 - **Independent** - minimal dependencies on other tasks
 - **Standards-compliant** - won't produce files >1000 lines or folders >15 files
+- **Strategically justified** - includes the problem solved and why this task matters now
 
 **Before finalizing tasks, check:**
 1. Will any planned file exceed 1000 lines? → Split into sub-modules
 2. Will any folder exceed 15 files? → Plan domain subfolders
 3. Are all interfaces defined? → Add `interfaces/` directory per module
 4. Are types explicit? → Plan typed interfaces, not `any`
+5. Do acceptance criteria describe outcomes instead of implementation? → Rewrite "use X" into "must achieve Y"
+6. Are any files likely to grow past 1000 lines after follow-on tasks? → Add a warning and split plan now, not later
+
+**When estimating file and folder impact:**
+- Check existing target files and folders before assigning work
+- Include projected growth from all tasks in the phase, not only the current task
+- Add an explicit warning in the plan if any task is likely to create or expand a file beyond 1000 lines
+- Prefer splitting by domain responsibility before implementation starts
 
 #### Task Status Markers (Multi-User)
 
@@ -189,6 +200,8 @@ Use `/tlc:claim` to claim a task, `/tlc:release` to release one.
 
 **Goal:** Define database schema for users table
 
+**Strategic Purpose:** Establish the canonical user data contract early so authentication, profile management, and downstream integrations build on a stable foundation.
+
 **Files:**
 - src/modules/user/interfaces/user.interface.ts
 - src/modules/user/user.repository.ts
@@ -199,6 +212,7 @@ Use `/tlc:claim` to claim a task, `/tlc:release` to release one.
 - [ ] Timestamps auto-populate
 - [ ] All types explicit (no `any`)
 - [ ] Exported functions have return types
+- [ ] Criteria describe observable outcomes and constraints, not implementation choices
 
 **Test Cases:**
 - Schema validates correct user data
@@ -221,18 +235,35 @@ Create `.planning/phases/{N}-PLAN.md`:
 
 - [ ] {Any setup or prior work needed}
 
+## Risk Assessment
+
+- **Unknowns:** {Unclear requirements, technical unknowns, external dependencies}
+- **Integration Points:** {Systems, modules, APIs, data contracts, migrations}
+- **Potential Failures:** {What could break, degrade, or block delivery}
+- **Mitigations:** {How the plan reduces or contains those risks}
+
+## Decision Log
+
+| Decision | Rationale | Alternatives Considered | Consequence |
+|----------|-----------|--------------------------|-------------|
+| {Architectural choice} | {Why this is the best fit now} | {What else was considered} | {Tradeoff or follow-on impact} |
+
 ## Tasks
 
 ### Task 1: {Title}
 
 **Goal:** {What this accomplishes}
 
+**Strategic Purpose:** {Why this task matters, what problem it solves, or what later work it unlocks}
+
 **Files:**
 - {files to create/modify}
+- {note if any file is at risk of exceeding 1000 lines and how the plan avoids it}
 
 **Acceptance Criteria:**
-- [ ] {Testable criterion 1}
-- [ ] {Testable criterion 2}
+- [ ] {Observable behavior or outcome 1}
+- [ ] {Observable behavior, scale constraint, latency target, or failure-handling outcome 2}
+- [ ] {No criterion prescribes implementation details unless already mandated by project constraints}
 
 **Test Cases:**
 - {Test description 1}
@@ -248,11 +279,21 @@ Create `.planning/phases/{N}-PLAN.md`:
 
 {Task dependencies if any - e.g., Task 3 requires Task 1}
 
+## Definition of Done
+
+| Dimension | Definition |
+|-----------|------------|
+| Behavior Change | {What users, operators, or dependent systems can now do differently} |
+| Tests | {Unit, integration, end-to-end, contract, or manual checks required} |
+| Failure Modes | {Known failure paths handled and verified} |
+| Rollback | {How the change can be reverted or disabled safely if needed} |
+
 ## Estimated Scope
 
 - Tasks: {N}
 - Files: {N}
 - Tests: ~{N} (estimated)
+- File size warnings: {None / list any files projected to exceed 1000 lines and planned split}
 ```
 
 ### Step 5: Review Plan
@@ -269,6 +310,9 @@ Tasks: 4
 4. Add loading/error states
 
 Estimated tests: 12
+Key risks: 2 integration points, 1 unresolved dependency
+Architecture decisions logged: 3
+File size warnings: none
 
 Proceed with this plan? (Y/n)
 ```
@@ -294,12 +338,15 @@ Task: Create login API endpoint
 - Validates email/password
 - Returns JWT token
 - Handles invalid credentials
+- Explains why login is needed now and what downstream work it unlocks
+- Defines outcomes such as response behavior, error handling, and throughput constraints
 ```
 
 **Bad tasks:**
 ```
 Task: Build auth system  <- too big
 Task: Add login          <- too vague
+Task: Use Redis cache    <- prescribes implementation, not outcome
 ```
 
 ## Example Output
@@ -311,12 +358,27 @@ Task: Add login          <- too vague
 
 User registration and login with JWT tokens.
 
+## Risk Assessment
+
+- **Unknowns:** Final session expiry requirements and auth provider migration timeline
+- **Integration Points:** Database schema, password hashing, token issuance, API error contracts
+- **Potential Failures:** Duplicate users, weak validation, token leakage, incompatible response shapes
+- **Mitigations:** Lock contracts early, validate edge cases, test failure paths before wiring UI
+
+## Decision Log
+
+| Decision | Rationale | Alternatives Considered | Consequence |
+|----------|-----------|--------------------------|-------------|
+| Use separate schema and endpoint tasks | Reduces coupling and surfaces auth contract risks early | Single end-to-end auth task | More handoff points, but lower integration risk |
+
 ## Tasks
 
 ### Task 1: Create user schema
 
 **Goal:** Database schema for users
 
+**Strategic Purpose:** Create the source-of-truth user contract first so registration, login, and profile features depend on one stable model instead of diverging assumptions.
+
 **Files:**
 - src/db/schema/users.ts
 - src/db/migrations/001_users.sql
@@ -325,6 +387,7 @@ User registration and login with JWT tokens.
 - [ ] Has id, email, passwordHash, createdAt, updatedAt
 - [ ] Email unique constraint
 - [ ] Password hashed with bcrypt
+- [ ] User creation rules are expressed as observable schema outcomes, not storage implementation notes
 
 **Test Cases:**
 - Schema accepts valid user data
@@ -337,6 +400,8 @@ User registration and login with JWT tokens.
 
 **Goal:** POST /api/auth/register
 
+**Strategic Purpose:** Deliver the first externally usable auth capability and validate that schema, validation, and response contracts work together under real request flows.
+
 **Files:**
 - src/api/auth/register.ts
 - src/lib/auth/password.ts
@@ -346,10 +411,20 @@ User registration and login with JWT tokens.
 - [ ] Returns user without password
 - [ ] Rejects existing email with 409
 - [ ] Validates email format
+- [ ] Handles invalid and duplicate registration attempts with stable API behavior under concurrent requests
 
 **Test Cases:**
 - Register with valid data returns user
 - Register with existing email returns 409
 - Register with invalid email returns 400
 - Password stored as hash
+
+## Definition of Done
+
+| Dimension | Definition |
+|-----------|------------|
+| Behavior Change | Users can register and authenticate through stable API contracts |
+| Tests | Schema, endpoint, validation, and concurrency-sensitive duplicate-user paths are covered |
+| Failure Modes | Duplicate email, invalid payloads, and password exposure paths are rejected safely |
+| Rollback | Auth routes can be disabled and schema migration reverted with a documented backout path |
 ```