Test Coverage Gate

Overview

Untested code is unverified code. Shipping without coverage data is shipping blind.

This skill enforces minimum test coverage thresholds before code leaves your machine. It detects your coverage tool, runs the analysis, compares results against thresholds, and blocks shipping if coverage is insufficient.

Core principle: No code ships without meeting coverage thresholds. Period.

Iron Law:

NO SHIP WITHOUT COVERAGE GATE PASSING
If coverage is below threshold, the PR does not get created.

When to Use

Always, before:

• Running /ship to create a PR
• Merging feature branches
• Tagging releases
• Deploying to staging or production

Especially when:

• Adding new features (new code must be tested)
• Refactoring (coverage must not drop)
• Fixing bugs (regression test required)
• Touching critical paths (auth, payments, data processing)

Skip only when:

• Documentation-only changes (no source code modified)
• Configuration file changes (non-code)
• Generated code explicitly excluded from coverage

Configuration

Default Thresholds

Line Coverage:     80%
Branch Coverage:   80%
Function Coverage: 80%

Custom Thresholds

Override defaults per project via codingbuddy.config.json, package.json, or tool-native config:

// codingbuddy.config.json
{
  "coverage": {
    "thresholds": {
      "lines": 80,
      "branches": 80,
      "functions": 80
    },
    "tool": "auto",        // "vitest" | "jest" | "c8" | "istanbul" | "auto"
    "excludePatterns": [
      "**/*.config.*",
      "**/generated/**",
      "**/migrations/**"
    ]
  }
}

// package.json (alternative)
{
  "coverageGate": {
    "lines": 80,
    "branches": 80,
    "functions": 80
  }
}

Per-Tool Native Config

If thresholds are already defined in your test tool's config, the gate respects them:

Priority order: CLI flags > codingbuddy.config.json > tool-native config > defaults (80%)

Supported Tools

Auto-Detection

The gate detects your coverage tool automatically:

1. Check package.json devDependencies:
   - @vitest/coverage-v8 or @vitest/coverage-istanbul → vitest
   - jest + jest coverage config → jest
   - c8 → c8
   - nyc or istanbul → istanbul
2. Check for tool-specific config files:
   - vitest.config.ts → vitest
   - jest.config.ts → jest
   - .c8rc.json → c8
   - .nycrc → istanbul
3. Fallback: prompt user to specify tool

Tool Commands

Workflow

Phase 1: Detect Coverage Tool

- [ ] Scan package.json devDependencies for coverage packages
- [ ] Check for tool-specific config files
- [ ] Resolve coverage tool (or prompt if ambiguous)
- [ ] Verify coverage tool is installed

If the tool is not installed:

# Suggest installation
echo "Coverage tool not found. Install with:"
echo "  yarn add -D @vitest/coverage-v8   # for vitest"
echo "  yarn add -D jest                   # for jest"
echo "  yarn add -D c8                     # for c8"
echo "  yarn add -D nyc                    # for istanbul/nyc"

Phase 2: Run Coverage Analysis

- [ ] Execute coverage command for detected tool
- [ ] Capture JSON coverage output
- [ ] Parse coverage summary (lines, branches, functions)

Expected output format (json-summary):

{
  "total": {
    "lines": { "total": 500, "covered": 420, "pct": 84.0 },
    "branches": { "total": 120, "covered": 96, "pct": 80.0 },
    "functions": { "total": 80, "covered": 68, "pct": 85.0 }
  }
}

Phase 3: Compare Against Thresholds

- [ ] Load thresholds (CLI > config > tool-native > defaults)
- [ ] Compare each metric against its threshold
- [ ] Classify result: PASS or FAIL per metric

Comparison logic:

For each metric in [lines, branches, functions]:
  actual = coverage_report.total[metric].pct
  threshold = resolved_thresholds[metric]
  result = actual >= threshold ? PASS : FAIL

Phase 4: Gate Decision

#### PASS — All metrics meet thresholds

Coverage Gate: PASS

  Lines:     84.0% >= 80% ✅
  Branches:  80.0% >= 80% ✅
  Functions: 85.0% >= 80% ✅

Proceed with shipping.

#### FAIL — One or more metrics below threshold

Coverage Gate: FAIL ❌

  Lines:     84.0% >= 80% ✅
  Branches:  72.0% >= 80% ❌ (-8.0%)
  Functions: 85.0% >= 80% ✅

BLOCKED: Coverage below threshold.

Uncovered areas requiring attention:
  - src/auth/oauth.ts: branches 45% (missing: error paths lines 23-31, 55-60)
  - src/utils/parser.ts: branches 60% (missing: edge cases lines 88-95)

Action required:
  1. Add tests for uncovered branches listed above
  2. Re-run coverage gate
  3. Ship only after all metrics pass

On failure:

• Block /ship from creating the PR
• List specific files and lines with low coverage
• Suggest which tests to write
• Never allow override without explicit --skip-coverage flag

Integration with /ship

Pre-Ship Hook

The coverage gate runs before any PR creation step in /ship:

/ship workflow:
  1. Lint check
  2. Type check (tsc --noEmit)
  3. Run tests
  4. ▶ COVERAGE GATE ◀  ← This skill
  5. Build verification
  6. Create branch + commit + push
  7. Create PR

If the coverage gate fails at step 4, steps 5-7 are not executed.

Skip Flag

For exceptional cases (hotfixes, documentation):

/ship --skip-coverage

When --skip-coverage is used:

• Log a warning: ⚠️ Coverage gate skipped. Reason must be documented in PR.
• Add [skip-coverage] label to the PR
• Require reason in PR description

Failure Recovery

Common Issues

Gradual Adoption

For projects starting below 80%:

// Start with current baseline, ratchet up over time
{
  "coverage": {
    "thresholds": {
      "lines": 60,       // Current: 58% → target 80%
      "branches": 50,    // Current: 48% → target 80%
      "functions": 65     // Current: 63% → target 80%
    },
    "ratchet": true       // Never allow coverage to decrease
  }
}

Ratchet mode: When enabled, the threshold automatically increases to match the highest coverage ever achieved. Coverage can only go up, never down.

Red Flags

These thoughts mean STOP — you're rationalizing: