tlc-claude-code 2.5.0 → 2.6.0

package/.claude/commands/tlc/ci.md

@@ -1,414 +1,178 @@
-# /tlc:ci - CI/CD Integration
-
-Generate CI/CD pipeline configuration for your TLC project.
-
-## Usage
-
-```
-/tlc:ci [provider]
-```
-
-Providers: `github`, `gitlab`, `bitbucket`, `azure`, `circle`
-
-If no provider specified, auto-detects from git remote.
-
-## What This Does
-
-1. Detects your CI/CD platform from git remote
-2. Generates appropriate config file
-3. Includes test-first validation
-4. Adds regression test gates
-
-## GitHub Actions
-
-Creates `.github/workflows/tlc.yml`:
-
-```yaml
-name: TLC Pipeline
-
-on:
-  push:
-    branches: [main, develop]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run tests
-        run: npm test
-
-      - name: Upload coverage
-        uses: codecov/codecov-action@v4
-        if: always()
-
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-      - run: npm ci
-      - run: npm run lint
-
-  regression:
-    runs-on: ubuntu-latest
-    needs: [test]
-    if: github.event_name == 'pull_request'
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-
-      - run: npm ci
-
-      - name: Check for untested code
-        run: |
-          # Get changed files
-          CHANGED=$(git diff --name-only origin/main...HEAD | grep -E '\.(ts|js|tsx|jsx)$' | grep -v '\.test\.' || true)
-
-          if [ -n "$CHANGED" ]; then
-            echo "Changed source files:"
-            echo "$CHANGED"
-
-            # Check each has corresponding test
-            for file in $CHANGED; do
-              testfile="${file%.*}.test.${file##*.}"
-              if [ ! -f "$testfile" ]; then
-                echo "::warning file=$file::No test file found for $file"
-              fi
-            done
-          fi
-
-      - name: Run regression tests
-        run: npm test -- --coverage
-
-      - name: Coverage diff
-        run: |
-          # Compare coverage with base branch
-          echo "Coverage report generated"
-```
-
-## GitLab CI
-
-Creates `.gitlab-ci.yml`:
-
-```yaml
-stages:
-  - test
-  - regression
-
-default:
-  image: node:20
-  cache:
-    paths:
-      - node_modules/
-
-test:
-  stage: test
-  script:
-    - npm ci
-    - npm test
-  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'
-  artifacts:
-    reports:
-      coverage_report:
-        coverage_format: cobertura
-        path: coverage/cobertura-coverage.xml
-
-lint:
-  stage: test
-  script:
-    - npm ci
-    - npm run lint
-  allow_failure: true
-
-regression:
-  stage: regression
-  only:
-    - merge_requests
-  script:
-    - npm ci
-    - |
-      CHANGED=$(git diff --name-only $CI_MERGE_REQUEST_DIFF_BASE_SHA...HEAD | grep -E '\.(ts|js)$' | grep -v '\.test\.' || true)
-      if [ -n "$CHANGED" ]; then
-        echo "Checking tests for changed files..."
-        for file in $CHANGED; do
-          testfile="${file%.*}.test.${file##*.}"
-          if [ ! -f "$testfile" ]; then
-            echo "WARNING: No test file for $file"
-          fi
-        done
-      fi
-    - npm test -- --coverage
-```
-
-## Bitbucket Pipelines
-
-Creates `bitbucket-pipelines.yml`:
-
-```yaml
-image: node:20
-
-definitions:
-  caches:
-    npm: ~/.npm
-
-pipelines:
-  default:
-    - step:
-        name: Test
-        caches:
-          - npm
-        script:
-          - npm ci
-          - npm test
-
-  pull-requests:
-    '**':
-      - step:
-          name: Test
-          caches:
-            - npm
-          script:
-            - npm ci
-            - npm test
-      - step:
-          name: Regression Check
-          caches:
-            - npm
-          script:
-            - npm ci
-            - npm test -- --coverage
-```
-
-## Azure Pipelines
-
-Creates `azure-pipelines.yml`:
-
-```yaml
-trigger:
-  - main
-  - develop
-
-pool:
-  vmImage: 'ubuntu-latest'
-
-stages:
-  - stage: Test
-    jobs:
-      - job: Test
-        steps:
-          - task: NodeTool@0
-            inputs:
-              versionSpec: '20.x'
-
-          - script: npm ci
-            displayName: Install dependencies
-
-          - script: npm test
-            displayName: Run tests
-
-          - task: PublishCodeCoverageResults@2
-            inputs:
-              summaryFileLocation: '$(System.DefaultWorkingDirectory)/coverage/cobertura-coverage.xml'
-
-  - stage: Regression
-    condition: eq(variables['Build.Reason'], 'PullRequest')
-    jobs:
-      - job: Regression
-        steps:
-          - task: NodeTool@0
-            inputs:
-              versionSpec: '20.x'
-          - script: npm ci
-          - script: npm test -- --coverage
-            displayName: Regression tests
-```
-
-## CircleCI
-
-Creates `.circleci/config.yml`:
-
-```yaml
-version: 2.1
-
-executors:
-  node:
-    docker:
-      - image: cimg/node:20.0
-
-jobs:
-  test:
-    executor: node
-    steps:
-      - checkout
-      - restore_cache:
-          keys:
-            - npm-{{ checksum "package-lock.json" }}
-      - run: npm ci
-      - save_cache:
-          paths:
-            - node_modules
-          key: npm-{{ checksum "package-lock.json" }}
-      - run: npm test
-      - store_test_results:
-          path: test-results
-      - store_artifacts:
-          path: coverage
-
-  regression:
-    executor: node
-    steps:
-      - checkout
-      - restore_cache:
-          keys:
-            - npm-{{ checksum "package-lock.json" }}
-      - run: npm ci
-      - run:
-          name: Check for untested code
-          command: |
-            CHANGED=$(git diff --name-only origin/main...HEAD | grep -E '\.(ts|js)$' | grep -v '\.test\.' || true)
-            if [ -n "$CHANGED" ]; then
-              echo "Changed files: $CHANGED"
-            fi
-      - run: npm test -- --coverage
-
-workflows:
-  test-and-deploy:
-    jobs:
-      - test
-      - regression:
-          filters:
-            branches:
-              ignore: main
-```
-
-## Regression Test Features
-
-### Automatic Detection
-
-The CI config includes regression checks that:
-
-1. **Identify changed files** in the PR/MR
-2. **Verify test coverage** for changed files
-3. **Run full test suite** to catch regressions
-4. **Report coverage diff** vs base branch
-
-### Configuring Regression Behavior
-
-In `.tlc.json`:
-
-```json
-{
-  "ci": {
-    "requireTestsForNewFiles": true,
-    "coverageThreshold": 80,
-    "failOnCoverageDecrease": true,
-    "regressionOnPR": true
-  }
-}
-```
-
-### Coverage Requirements
-
-Set minimum coverage in `package.json`:
-
-```json
-{
-  "jest": {
-    "coverageThreshold": {
-      "global": {
-        "branches": 80,
-        "functions": 80,
-        "lines": 80,
-        "statements": 80
-      }
-    }
-  }
-}
-```
-
-Or for mocha with nyc:
-
-```json
-{
-  "nyc": {
-    "check-coverage": true,
-    "lines": 80,
-    "functions": 80,
-    "branches": 80
-  }
-}
-```
-
-## Import/Merge Regression
-
-When importing external code (`/tlc:import-project`), automatically run regression:
-
-```
-> /tlc:import-project ../legacy-api
-
-Importing legacy-api...
-
-Found 47 source files without tests.
-
-Running regression tests on merge...
-  ✓ 23 existing tests pass
-  ⚠ 12 new files need tests
-
-Create tasks for missing tests? (Y/n)
-```
-
-## Example Session
-
-```
-> /tlc:ci
-
-Detecting CI/CD platform...
-  Remote: git@github.com:acme/myproject.git
-  Platform: GitHub
-
-Generating .github/workflows/tlc.yml...
-
-Created CI pipeline with:
-  ✓ Test job (runs on all pushes)
-  ✓ Lint job (runs on all pushes)
-  ✓ Regression job (runs on PRs)
-  ✓ Coverage reporting (Codecov)
-
-Commit this file? (Y/n) y
-
-Committed: ci: add TLC GitHub Actions pipeline
-
-Next steps:
-  1. Push to GitHub
-  2. Add CODECOV_TOKEN secret (optional)
-  3. PRs will now require passing tests
-```
-
-## Notes
-
-- CI config respects `.tlc.json` settings
-- Coverage thresholds match project config
-- Regression checks are PR-only by default
-- Use `/tlc:ci --dry-run` to preview without creating files
+# /tlc:ci - CI/CD Integration
+
+Detect existing CI first, report what is already configured, then offer to scaffold only the missing pieces.
+
+## Usage
+
+```text
+/tlc:ci [provider]
+/tlc:ci [provider] --dry-run
+```
+
+Providers: `github`, `gitlab`, `bitbucket`, `azure`, `circle`
+
+- Keep the provider argument optional.
+- If no provider is passed, prefer the detected CI platform.
+- `--dry-run` previews findings and proposed scaffolding without writing files.
+
+## Detection-First Flow
+
+1. Detect existing CI with `server/lib/scaffolding/ci-detector.js`.
+2. Show what already exists.
+3. Show the gaps that were found.
+4. Offer to scaffold only the missing pieces with `server/lib/scaffolding/ci-scaffolder.js`.
+5. If `--dry-run` is set, stop after the preview and do not write anything.
+
+## Detection Step
+
+Run the detector before asking about providers or generating files.
+
+Use `server/lib/scaffolding/ci-detector.js` to inspect the project and return:
+
+- `platform`: detected CI platform, or `none`
+- `workflows`: existing workflow/config files with coverage of test, deploy, and coverage behavior
+- `gaps`: missing capabilities such as `no-ci`, `missing-test-step`, `missing-deploy-step`, and `missing-coverage-upload`
+
+Supported detected platforms today:
+
+- `github-actions`
+- `gitlab`
+- `jenkins`
+- `circleci`
+- `none`
+
+## Output Requirements
+
+Always show detection results before offering scaffolding.
+
+Detection output should include:
+
+- detected platform
+- each existing workflow/config file path
+- whether each file already includes test, deploy, and coverage behavior
+- the gap list
+
+Example:
+
+```text
+> /tlc:ci
+
+Detecting existing CI...
+
+Found:
+  Platform: github-actions
+  Workflows:
+    - .github/workflows/test.yml
+      test: yes
+      deploy: no
+      coverage: yes
+    - .github/workflows/release.yml
+      test: no
+      deploy: yes
+      coverage: no
+
+Gaps:
+  - missing-coverage-upload
+
+Scaffold the missing pieces with GitHub Actions templates? (Y/n)
+```
+
+If no CI exists:
+
+```text
+> /tlc:ci
+
+Detecting existing CI...
+
+Found:
+  Platform: none
+  Workflows: none
+
+Gaps:
+  - no-ci
+
+Scaffold a new CI pipeline? (Y/n)
+```
+
+## Scaffolding Step
+
+Only scaffold after detection results have been shown and the user accepts.
+
+Use `server/lib/scaffolding/ci-scaffolder.js` to generate the missing pieces for the selected or detected provider.
+
+Scaffolding rules:
+
+- do not replace working CI configs unless the user explicitly approves it
+- fill only the reported gaps when CI already exists
+- create a full starter pipeline when `gaps` contains `no-ci`
+- prefer the detected platform over a guessed provider
+- if the user passes a provider explicitly, use that provider for the scaffold preview and confirmation prompt
+
+## Dry Run
+
+`--dry-run` must run the same detection flow and the same scaffold planning logic, but without writing files.
+
+Dry-run output should:
+
+- show detected CI and gaps
+- show which files would be created or updated
+- show which missing capabilities would be added
+- not write files
+- not commit changes
+
+Example:
+
+```text
+> /tlc:ci github --dry-run
+
+Detecting existing CI...
+
+Found:
+  Platform: none
+  Workflows: none
+
+Gaps:
+  - no-ci
+
+Dry run:
+  Would create .github/workflows/tlc.yml
+  Would add:
+    - test job
+    - deploy job
+    - coverage upload
+
+No files written.
+```
+
+## Provider Handling
+
+- Keep `/tlc:ci [provider]` as the command shape.
+- A provider argument overrides the scaffold target, but detection still runs first.
+- If detection finds an existing platform and the provider differs, call that out before scaffolding.
+- If no provider is passed, use the detected platform when one exists.
+- If no provider is passed and detection returns `none`, prompt for a provider or infer from git remote if available.
+
+## Commit Behavior
+
+If files were written and the user confirms, commit the result after scaffolding.
+
+Suggested commit message:
+
+```text
+ci: scaffold missing CI pieces
+```
+
+If a brand-new pipeline was created, this is also acceptable:
+
+```text
+ci: add TLC CI pipeline
+```
+
+Do not commit on `--dry-run`.
+
+## Notes
+
+- Detection is mandatory and happens before scaffolding.
+- Gap reporting is mandatory even when CI already exists.
+- Scaffolding is opt-in.
+- `--dry-run` previews the exact changes without writing.

package/.claude/commands/tlc/coverage.md

@@ -97,6 +97,40 @@ process.stdout.write(JSON.stringify(result));" 2>/dev/null
 
 **Override:** Pass `--model <name>` to route this specific run to a different model.
 
+After `resolveRouting` returns, immediately write `.tlc/.coverage-routing-active` with the active provider name from `models[0]` before doing any other coverage work. Remove `.tlc/.coverage-routing-active` on completion, cancellation, or failure cleanup.
+
+**Routing decision:**
+- If routing says external provider (`models[0] !== 'claude'`), follow **ONLY ORCHESTRATOR MODE** below.
+- If routing says Claude (`models[0] === 'claude'`), follow **INLINE MODE** below.
+
+## ORCHESTRATOR MODE
+
+Use this mode only when `models[0]` is **NOT** `claude`.
+
+Claude does not execute the coverage instructions inline in this path. Claude acts as the orchestrator for the routed provider run:
+
+1. Claude acts as the orchestrator for routed coverage analysis instead of scanning the repo inline.
+2. Gather the project's test framework, source layout, and any existing coverage context before dispatching the analysis.
+3. Package a prompt that asks the routed provider to map source files to tests, identify critical untested paths, and produce a prioritized coverage report or backlog.
+4. Dispatch through the provider CLI path, using `codex exec` for Codex-style providers or `gemini -p` for Gemini-style providers, preferably via the shared dispatch layer when available.
+5. Verify the routed result before accepting it:
+   - Confirm it reflects the actual repository structure and test conventions.
+   - Confirm critical-path classifications are justified by the code, not by generic labels alone.
+   - Reject shallow reports that do not distinguish between tested, untested, and high-risk areas.
+6. If the routed analysis is incomplete or weak, dispatch a narrower follow-up for the missing directories, modules, or backlog output.
+7. Handle failures explicitly:
+   - If dispatch fails because of model mismatch, auth, or missing CLI, check `.tlc/.router-state.json` for the provider's actual available model and retry once with the corrected model.
+   - If retry still fails, stop and report the exact failure to the user. Do not silently fall back to Claude inline execution.
+   - If the provider produces a poor backlog or inaccurate mapping, reject it and rerun with explicit repository evidence.
+8. When finished, display the routed coverage result, persist any captured memory, remove `.tlc/.coverage-routing-active`, and stop. Do **not** execute Inline Mode afterward.
+
+## INLINE MODE
+
+Use this mode only when `models[0]` **IS** `claude`.
+
+The existing coverage instructions below are the Inline Mode instructions and should be followed unchanged.
+
+
 ## When to Use
 
 - After `/tlc:init` to add tests to existing code

package/.claude/commands/tlc/deploy.md

@@ -381,12 +381,25 @@ app.post('/api/deploy', requireRole(['admin', 'engineer']));
 app.get('/api/status', requireRole(['admin', 'engineer', 'qa', 'po']));
 ```
 
-## Deployment
-
-### Push to Deploy
-
-```
-> /tlc:deploy push
+## Deployment
+
+### Migration Snapshot
+
+Check for migration files in the current diff:
+```bash
+MIGRATION_FILES=$(git diff --name-only main...HEAD | grep -E "prisma/migrations|drizzle/|migrations/.*\.(ts|js|sql)|alembic/versions" | grep -v "\.test\.")
+```
+
+If `MIGRATION_FILES` is not empty:
+1. Detect DB connection from `.env` or config
+2. Take snapshot: run `server/lib/scaffolding/snapshot-manager.js takeSnapshot()`
+3. Report: `DB snapshot taken: .tlc/snapshots/{filename}. Run /tlc:restore to rollback if needed.`
+4. If snapshot fails (DB not running): warn but continue build
+
+### Push to Deploy
+
+```
+> /tlc:deploy push
 
 Deploying branch: feat-auth