oc-bug-check

# Bug Check

**On first invocation, read `references/orchestrator.md` and follow its welcome protocol.**

Fast pre-commit QA gate. Runs in under 2 minutes. Catches the bugs, type errors,
test failures, and anti-patterns that shouldn't make it into a commit — before they
cost real debugging time downstream.

This is NOT oc-code-auditor. Code-auditor runs a deep tri-agent sweep (Auditor → Fixer →
Verifier) that takes 30+ minutes and produces a graded report. Bug-check is the metal
detector at the door — fast, blunt, binary: every check resolves to **PASS** or **FAIL**.
Individual checks may emit advisory **WARN** notes (e.g. "no test suite detected")
that are surfaced in the report but do not affect the gate verdict — only FAIL blocks
the commit.

## /oc-bugcheck — Command Reference

```
BUG CHECK COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  GATE
  /oc-bugcheck              Run all checks on staged/changed files
  /oc-bugcheck run          Same as /oc-bugcheck
  /oc-bugcheck run --all    Run on entire codebase (not just changes)
  /oc-bugcheck fix          Auto-fix what's fixable (lint, formatting)

  CONFIG
  /oc-bugcheck config       Show or edit check configuration
  /oc-bugcheck config strict    Enable strict mode (zero warnings allowed)
  /oc-bugcheck config lenient   Allow warnings, block only on errors

  REPORT
  /oc-bugcheck report       Show last run results from checkpoint
  /oc-bugcheck history      Show pass/fail trend from checkpoint

  OVERRIDE
  /oc-bugcheck bypass       Skip gate this once (logs the bypass in checkpoint)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Runs automatically before /oc-git-commit and /oc-git-sync.
```

---

## Session Persistence (Checkpoint Protocol)

Checkpoint: `{project-dir}/.checkpoints/oc-bug-check.checkpoint.json`

### Resume on Start

When `/oc-bugcheck` is invoked:
1. Check for checkpoint
2. If exists: show last verdict, streak, carried debt count
3. If carried debt > 0: surface bypassed issues before running new checks
4. Run the check suite (no "continue/restart" prompt — oc-bug-check always runs fresh)

Bug-check differs from other opchain skills: there's no "resume" decision. The gate
always runs the full check suite. The checkpoint provides context (streak, debt, history),
not resumable state.

---

## How This Skill Fits the Pipeline

```
oc-app-architect /oc-build ──► BUG-CHECK (gate) ──► oc-git-ops /oc-commit ──► oc-deploy-ops
                              │
                         ┌────┴────┐
                         │         │
                      PASS →    FAIL →
                    proceed    block commit,
                    silently   show what broke
```

**Auto-invocation:** oc-git-ops calls oc-bug-check before every `/oc-git-commit` and `/oc-git-sync`.
If oc-bug-check fails, the commit is blocked with a clear failure report. The user can
override with `/oc-bugcheck bypass` (logged, not silent).

**Relationship to oc-code-auditor:** Bug-check is a subset. It runs the checks that are
fast enough for every commit. Code-auditor's deep sweep runs before deploy (gate) or
on demand (ad-hoc). They complement, not compete:

| | Bug Check | Code Auditor |
|---|---|---|
| **When** | Every commit | Before deploy, on demand |
| **Speed** | <2 min | 30+ min |
| **Depth** | Surface: types, lint, tests, patterns | Deep: tri-agent, security, architecture |
| **Verdict** | PASS / FAIL (binary) | Grade A-F (nuanced) |
| **Fixes** | Auto-fix lint/format | Fixer → Verifier loop |
| **Scope** | Changed files by default | Full codebase |

---

## The Check Suite

Seven checks, run in order. Each produces PASS, WARN, or FAIL.

### Check 1: Type Safety

```bash
npx tsc --noEmit
```

| Result | Verdict |
|---|---|
| Exit 0 | PASS |
| Type errors | FAIL — list errors with file:line |

**Why it blocks:** Type errors propagate. A wrong type in a utility function breaks
every consumer. Catching at commit is 10x cheaper than catching at runtime.

### Check 2: Lint

```bash
npx eslint . --ext .ts,.tsx --max-warnings 0
```

| Result | Verdict |
|---|---|
| Exit 0, no warnings | PASS |
| Warnings only | WARN (pass in lenient mode, fail in strict) |
| Errors | FAIL — list errors with file:line |

**Auto-fixable?** Yes. `/oc-bugcheck fix` runs `eslint --fix` and `prettier --write`.

### Check 3: Test Suite

```bash
npx vitest run --reporter=verbose 2>&1
```

| Result | Verdict |
|---|---|
| All pass | PASS (report count: "42 tests passed") |
| Any fail | FAIL — list failing test names + assertion errors |
| No tests found | WARN — "No test suite detected" |

**Why no tests is a warning, not a pass:** Zero tests means zero regression protection.
The warning nudges toward coverage without blocking early-stage commits.

### Check 4: Anti-Pattern Scan

Fast grep-based checks for patterns that indicate bugs, not style preferences:

```bash
# console.log in production code (not test files)
grep -rn "console\.log\b" --include="*.ts" --include="*.tsx" \
  --exclude-dir=test --exclude-dir=__tests__ --exclude-dir=node_modules src/

# Debugger statements
grep -rn "debugger" --include="*.ts" --include="*.tsx" \
  --exclude-dir=node_modules src/

# TODO/FIXME/HACK in changed files
git diff --cached --name-only | xargs grep -n "TODO\|FIXME\|HACK" 2>/dev/null

# .only on test files (focused tests that skip the rest)
grep -rn "\.only\b" --include="*.test.*" --include="*.spec.*" \
  --exclude-dir=node_modules .

# any type in TypeScript (explicit any, not inferred)
grep -rn ": any\b\|as any\b\|<any>" --include="*.ts" --include="*.tsx" \
  --exclude-dir=node_modules --exclude="*.d.ts" src/

# @ts-ignore / @ts-nocheck
grep -rn "@ts-ignore\|@ts-nocheck\|@ts-expect-error" --include="*.ts" --include="*.tsx" \
  --exclude-dir=node_modules src/

# Empty catch blocks
grep -rn "catch.*{[[:space:]]*}" --include="*.ts" --include="*.tsx" \
  --exclude-dir=node_modules src/
```

| Pattern | Verdict | Rationale |
|---|---|---|
| `console.log` in src/ | WARN | Debug artifact,