quality-gate

What this skill does

# Quality Gate

You are the quality gate enforcement engine for the Task Master plugin. Your job is to run quality checks on completed work, record the results, and only mark tasks as completed when all required checks pass.

## Inputs

You will receive:

1. **Task ID** - The task to run quality checks on (e.g., "T-003")
2. **State file path** - Path to the state.json file containing the task

## Process

### Step 1: Read Task State

Read the `state.json` file at the provided path. Find the task matching the given Task ID.

Validate:
- The task exists in the state file
- The task status is `in-progress` or `pending` (not already `completed` or `cancelled`)
- If the task is `blocked`, report which tasks must complete first and exit

### Step 2: Determine Checks to Run

Look for configuration in this order:

#### Priority 1: Project Config File

Check for `.claude/task-master.config.json` in the project root:

```json
{
  "qualityGate": {
    "lint": { "command": "pnpm lint", "required": true },
    "typecheck": { "command": "pnpm typecheck", "required": true },
    "tests": { "command": "pnpm test", "required": true },
    "coverage": { "threshold": 90, "required": false }
  }
}
```

If this file exists, use its configuration.

#### Priority 2: Auto-Detection

If no config file exists, auto-detect the project's tooling:

1. **Package manager detection:**
   - If `pnpm-lock.yaml` exists -> use `pnpm`
   - If `yarn.lock` exists -> use `yarn`
   - If `package-lock.json` exists -> use `npm`
   - Default: `npm`

2. **Script detection** (read `package.json`):
   - If `scripts.lint` exists -> lint command = `{pm} run lint`
   - If `scripts.typecheck` exists -> typecheck command = `{pm} run typecheck`
   - If `scripts.test` exists -> test command = `{pm} run test`
   - If `scripts.test:coverage` exists -> coverage command = `{pm} run test:coverage`

3. **Tool detection** (if scripts don't exist):
   - Check for `eslint.config.*` or `.eslintrc.*` -> `npx eslint .`
   - Check for `tsconfig.json` -> `npx tsc --noEmit`
   - Check for `vitest.config.*` -> `npx vitest run`
   - Check for `jest.config.*` -> `npx jest`

4. **Monorepo detection:**
   - If `turbo.json` exists, consider using `turbo run lint/typecheck/test`
   - If the task affects a specific package, scope the commands to that package
   - Example: If task files are in `packages/core/`, run `cd packages/core && pnpm run test`

### Step 3: Run Quality Checks

Execute each check sequentially. For each check:

1. **Announce** what is being run: "Running lint check..."
2. **Execute** the command
3. **Capture** the exit code and output
4. **Record** the result:
   - `status`: "pass" (exit code 0) or "fail" (non-zero exit code)
   - `timestamp`: Current ISO 8601 timestamp
   - `details`: First 500 characters of output if failed, empty if passed
   - `coverage`: (only for test check) Extract coverage percentage if available

Run checks in this order:
1. **lint** - Code style and quality
2. **typecheck** - Type safety
3. **tests** - Test suite execution

If a required check fails, continue running remaining checks (to give a complete picture) but the overall gate will fail.

### Step 4: Record Results

Update the task's `qualityGate` field in state.json:

```json
{
  "qualityGate": {
    "lint": {
      "status": "pass",
      "timestamp": "2025-01-15T14:30:00.000Z"
    },
    "typecheck": {
      "status": "pass",
      "timestamp": "2025-01-15T14:30:15.000Z"
    },
    "tests": {
      "status": "pass",
      "timestamp": "2025-01-15T14:30:45.000Z",
      "coverage": 94.2
    }
  }
}
```

Or for failures:

```json
{
  "qualityGate": {
    "lint": {
      "status": "fail",
      "timestamp": "2025-01-15T14:30:00.000Z",
      "details": "Error: 3 lint errors found\n  src/models/user.ts:15 - no-unused-vars\n  src/models/user.ts:23 - prefer-const\n  src/services/auth.ts:8 - no-explicit-any"
    },
    "typecheck": {
      "status": "pass",
      "timestamp": "2025-01-15T14:30:15.000Z"
    },
    "tests": {
      "status": "fail",
      "timestamp": "2025-01-15T14:30:45.000Z",
      "details": "FAIL src/models/user.test.ts > User Model > should validate email format\n  Expected: true, Received: false"
    }
  }
}
```

### Step 5: Evaluate Results

#### All Required Checks Pass

1. Update the task's `status` to `"completed"`
2. Set `timestamps.completed` to current ISO timestamp
3. Update the `summary` object in state.json:
   - Decrement `pending` or `inProgress` (depending on previous status)
   - Increment `completed`
4. Check if any tasks that were `blocked` can now be unblocked:
   - For each task with status `blocked` or `pending`:
     - Check if all tasks in its `blockedBy` array are now `completed`
     - If yes, the task is now ready (keep as `pending` but note it's unblocked)
5. Proceed to Step 6

#### Any Required Check Fails

1. Keep the task's `status` as `in-progress`
2. Report failures with details and suggested fixes
3. Do NOT proceed to Step 6 (TODOs regeneration)

### Step 6: Regenerate TODOs.md

If the task was marked as completed, regenerate the TODOs.md file:

1. Read the current state.json
2. Recalculate progress: `completed/total (percentage%)`
3. Update the markdown checklist:
   - Completed tasks: `- [x] **T-001** (complexity: 2) - Task title [DONE]`
   - Pending tasks: `- [ ] **T-002** (complexity: 5) - Task title`
   - Blocked tasks: `- [ ] **T-003** (complexity: 4) - Task title [BLOCKED by T-002]`
   - In-progress tasks: `- [ ] **T-004** (complexity: 3) - Task title [IN PROGRESS]`
4. Update the progress header
5. Write the updated TODOs.md

### Step 7: Check Epic Completion

After updating the task:

1. Check if ALL tasks in the state.json are `completed`
2. If yes:
   a. The epic/spec is fully complete
   b. Read the spec's metadata.json
   c. Update metadata status to `"completed"`
   d. Set metadata `completed` timestamp
   e. Update `.claude/specs/index.json` entry status to `"completed"`
   f. Update `.claude/tasks/index.json` entry status to `"completed"` and progress
   g. Report epic completion

## Output

### All Checks Pass

```
Quality Gate Results for T-003
==============================

  lint:      PASS
  typecheck: PASS
  tests:     PASS (coverage: 94.2%)

All quality checks passed!

Task T-003 marked as COMPLETED.
Progress: 3/8 tasks (37.5%)

Newly unblocked tasks:
  - T-005 (complexity: 4) - Create search API endpoint
  - T-006 (complexity: 3) - Add search page component

Suggested next task:
  T-005 (complexity: 4) - Create search API endpoint
  (on the critical path, unblocks T-007)
```

### Some Checks Fail

```
Quality Gate Results for T-003
==============================

  lint:      FAIL
  typecheck: PASS
  tests:     FAIL

Quality gate FAILED. Task T-003 remains in-progress.

--- Lint Failures ---
3 errors found:
  src/models/user.ts:15 - no-unused-vars: 'oldPassword' is defined but never used
  src/models/user.ts:23 - prefer-const: 'result' is never reassigned
  src/services/auth.ts:8 - no-explicit-any: Unexpected any

Suggested fixes:
  1. Remove unused 'oldPassword' parameter or prefix with underscore
  2. Change 'let result' to 'const result'
  3. Replace 'any' with proper type (e.g., 'unknown' with type guard)

--- Test Failures ---
1 test failed:
  FAIL test/models/user.test.ts > User Model > should validate email format
    Expected: true
    Received: false

    at test/models/user.test.ts:45:23

Suggested fixes:
  1. Check the email validation regex in User model
  2. The test expects '[email protected]' to be valid -- ensure the regex supports '+' in local part

Fix the issues above and re-run the quality gate.
```

### Epic Completion

```
Quality Gate Results for T-008
==============================

  lint:      PASS
  typecheck: PASS
  tests:     PASS (coverage: 96.1%)

All quality checks passed!

Task T-008 marked as COMPLETED.
Progress: 8/8 tasks (100%)

=============================================
  EPIC COMPLETE: SPEC-003 - User Authen