@lvlup-sw/axiom 0.2.0

package/skills/harden/references/error-patterns.md

@@ -0,0 +1,180 @@
+# Error Patterns Reference
+
+Taxonomy of error handling patterns, anti-patterns, and severity guidance for the `harden` skill. Use this reference when classifying catch blocks and evaluating error propagation.
+
+## Silent Catch Taxonomy
+
+Four categories of catch block behavior, ordered from most dangerous to least:
+
+### 1. Empty Catch (Severity: HIGH)
+
+```typescript
+// Pattern: catch body is empty or contains only whitespace
+try { riskyOperation(); } catch (e) {}
+try { riskyOperation(); } catch { }
+```
+
+**Why it matters:** Errors are completely invisible. The operation appears to succeed when it failed. Downstream code operates on incorrect assumptions.
+
+**Action:** Must add error handling. At minimum, log with context and re-throw if the caller needs to know.
+
+### 2. Log-Only (Severity: MEDIUM)
+
+```typescript
+// Pattern: catch logs but takes no corrective action
+try { riskyOperation(); } catch (e) { console.log(e); }
+try { riskyOperation(); } catch (e) { logger.warn('failed', e); }
+```
+
+**Why it matters:** The error is visible in logs but the system continues as if nothing happened. If the operation was important, downstream code operates on stale or missing data.
+
+**Action:** Evaluate whether the operation needs recovery. If yes, add recovery logic. If the operation is truly optional, document why in a comment.
+
+### 3. Swallow-and-Default (Severity: MEDIUM to HIGH)
+
+```typescript
+// Pattern: catch replaces the result with a default value
+try { config = loadConfig(); } catch { config = DEFAULT_CONFIG; }
+try { data = fetchRemote(); } catch { data = cachedData; }
+```
+
+**Why it matters:** The system silently switches to degraded behavior. The operator has no visibility into the fallback. If the default is incorrect or stale, the system produces wrong results while appearing healthy.
+
+**Severity escalation:** HIGH when the default can cause data loss or incorrect behavior. MEDIUM when the default is safe but operators should know.
+
+**Action:** Log the fallback activation. Add metrics or health checks that surface degraded mode.
+
+### 4. Catch-and-Rethrow-Generic (Severity: MEDIUM)
+
+```typescript
+// Pattern: catch wraps the error but loses context
+try { riskyOperation(); } catch (e) { throw new Error('Operation failed'); }
+// vs. correct:
+try { riskyOperation(); } catch (e) { throw new Error('Failed to load user config', { cause: e }); }
+```
+
+**Why it matters:** The original error's stack trace, message, and context are lost. Debugging requires reproducing the issue rather than reading the error chain.
+
+**Action:** Preserve the cause chain using `{ cause: e }`. Include what operation failed and why in the wrapper message.
+
+---
+
+## Error Context Checklist
+
+Every error message should answer these four questions:
+
+| Question | Example (Good) | Example (Bad) |
+|----------|----------------|---------------|
+| **What failed?** | "Failed to read workflow state for feature-123" | "Read failed" |
+| **Why did it fail?** | "File not found at /tmp/state/feature-123.json" | "Error occurred" |
+| **What to do about it?** | "Ensure the workflow was initialized with `init`" | (nothing) |
+| **Cause chain?** | `new Error('...', { cause: originalError })` | `new Error(originalError.message)` |
+
+### Context Completeness Scoring
+
+- **4/4 questions answered:** Excellent error — no finding
+- **3/4 questions answered:** Acceptable — LOW finding if missing "what to do"
+- **2/4 questions answered:** Incomplete — MEDIUM finding
+- **1/4 or 0/4 questions answered:** Poor — HIGH finding (effectively opaque)
+
+---
+
+## Fallback Anti-Patterns
+
+### Silent Degradation (Severity: HIGH)
+
+The system switches to a less capable mode without any signal to the operator.
+
+```typescript
+// Anti-pattern: silent mode switch
+function getStore() {
+  if (!configuredStore) {
+    return new InMemoryStore(); // Silently degrades to non-persistent store
+  }
+  return configuredStore;
+}
+```
+
+**Fix:** Log when fallback activates. Add a health check endpoint or metric that surfaces degraded state.
+
+### Invisible Mode Switches (Severity: HIGH)
+
+```typescript
+// Anti-pattern: behavior changes silently based on error
+let mode = 'full';
+try { await connectToService(); } catch { mode = 'limited'; }
+// Rest of code behaves differently but nothing signals the switch
+```
+
+**Fix:** Make mode visible via logging, metrics, or return value. Callers should know they're operating in degraded mode.
+
+### Best-Effort Without Signaling (Severity: MEDIUM)
+
+```typescript
+// Anti-pattern: best-effort with no visibility
+async function syncData() {
+  try { await pushToRemote(data); } catch { /* best effort */ }
+}
+```
+
+**Fix:** Even best-effort operations should log failures. The operator needs to know sync is failing so they can investigate and fix the root cause.
+
+---
+
+## Promise Rejection Patterns
+
+### Swallowed Rejections (Severity: HIGH)
+
+```typescript
+// Pattern: promise rejection silently consumed
+promise.catch(() => {});
+promise.catch(() => undefined);
+someAsyncFn().catch(() => {});
+```
+
+**Why it matters:** Same as empty catch — the error is invisible. Worse in async contexts because the failure may surface much later as corrupted state.
+
+### Unhandled Rejection Handlers (Severity: MEDIUM)
+
+```typescript
+// Pattern: global handler as a band-aid
+process.on('unhandledRejection', (err) => {
+  console.error('Unhandled rejection:', err);
+});
+```
+
+**Why it matters:** Global handlers are a safety net, not a solution. Each rejection should be handled at the call site with appropriate recovery or propagation.
+
+**Action:** Keep the global handler as a safety net, but fix each unhandled rejection at its source.
+
+### Fire-and-Forget Without Error Handling (Severity: MEDIUM)
+
+```typescript
+// Pattern: async call started but never awaited and no catch
+sendAnalytics(event); // Returns a promise, never awaited
+cleanupTempFiles();   // Async, failure silently ignored
+```
+
+**Fix:** Either await and handle the error, or explicitly catch and log:
+```typescript
+sendAnalytics(event).catch(err => logger.warn('Analytics send failed', { err }));
+```
+
+**Exception:** Non-critical telemetry and observability side-effects (e.g., `emitGateEvent(...)`, `sendAnalytics(event)`) may be allowed to fail silently when all of: (1) the call is clearly annotated as fire-and-forget, (2) failure cannot affect primary execution correctness, and (3) the scope is limited to observability. Do not flag these as findings.
+
+---
+
+## Severity Summary
+
+| Pattern | Default Severity | Escalation Condition |
+|---------|-----------------|---------------------|
+| Empty catch | HIGH | Always HIGH |
+| Log-only catch | MEDIUM | HIGH if operation affects data integrity |
+| Swallow-and-default | MEDIUM | HIGH if default can cause data loss |
+| Catch-and-rethrow-generic | MEDIUM | HIGH if error is user-facing or triggers retry |
+| Silent degradation | HIGH | Always HIGH |
+| Invisible mode switch | HIGH | Always HIGH |
+| Best-effort without signaling | MEDIUM | HIGH if operation is data-critical |
+| Swallowed promise rejection | HIGH | Always HIGH |
+| Unhandled rejection handler as fix | MEDIUM | HIGH if in production critical path |
+| Fire-and-forget | MEDIUM | HIGH if operation has side effects |

package/skills/harden/references/resilience-checklist.md

@@ -0,0 +1,82 @@
+# Resilience Checklist
+
+Structured checklist for evaluating operational resilience. Each section covers a resilience concern with pass/fail criteria. Use during the qualitative assessment phase of the `harden` skill.
+
+---
+
+## Resource Management
+
+Verify that every acquired resource has a corresponding release, and that long-lived collections are bounded.
+
+| # | Check | Pass Criteria | Fail Criteria |
+|---|-------|---------------|---------------|
+| R-1 | Bounded caches | Every `Map`, `Set`, or array used as a cache has a documented max size and eviction policy (LRU, TTL, or explicit `.clear()` on lifecycle events) | Collection grows without limit; no `.delete()`, `.clear()`, or size check nearby |
+| R-2 | Connection pools | Database and HTTP connections use pooling with max connections configured; pools are drained on shutdown | Connections opened per-request without pooling, or pool has no max size |
+| R-3 | File handle lifecycle | File handles opened in `try` are closed in `finally` (or use `using`/`await using` with disposable pattern); error paths close handles too | File opened in try, closed only on success path; error path leaks the handle |
+| R-4 | Event listener cleanup | Listeners registered with `.on()` or `.addEventListener()` are removed with `.off()` / `.removeEventListener()` when the owner is disposed | Listeners accumulate without removal, causing memory leaks and duplicate processing |
+| R-5 | Stream lifecycle | Streams are `.end()`ed or `.destroy()`ed on both success and error paths; pipeline errors trigger cleanup | Stream left open on error, causing resource leak or hanging process |
+
+---
+
+## Timeout Patterns
+
+Verify that every external call is bounded by a timeout.
+
+| # | Check | Pass Criteria | Fail Criteria |
+|---|-------|---------------|---------------|
+| T-1 | HTTP timeout | Every `fetch()` or HTTP client call has a `signal` (AbortController) or `timeout` option configured | `fetch()` called without timeout; could hang indefinitely on network issues |
+| T-2 | Database query timeout | Database queries have statement-level or connection-level timeouts configured | Queries can run unbounded; a slow query blocks the connection pool |
+| T-3 | File system timeout | Long-running file operations (directory walks, large reads) have either a timeout or are chunked | Unbounded `readdir` on large directories or `readFile` on potentially huge files |
+| T-4 | AbortController usage | AbortController signals are wired correctly — controller created, signal passed, abort called on timeout/cancellation | AbortController created but signal never passed to the operation, or abort never called |
+| T-5 | IPC/subprocess timeout | Child processes and IPC calls have timeouts; hung processes are killed | `child_process.exec` without timeout; process could hang forever |
+
+---
+
+## Retry Patterns
+
+Verify that retry logic is bounded and uses appropriate backoff.
+
+| # | Check | Pass Criteria | Fail Criteria |
+|---|-------|---------------|---------------|
+| Y-1 | Maximum attempts | Every retry loop has a configured max attempt count (typically 3-5 for transient failures) | `while (true) { try ... catch { continue } }` with no attempt counter |
+| Y-2 | Exponential backoff | Retry delays increase exponentially (e.g., 100ms, 200ms, 400ms, 800ms) rather than fixed intervals | Fixed delay between retries (e.g., always `sleep(1000)`) or no delay at all |
+| Y-3 | Jitter | Retry delays include random jitter to prevent thundering herd on shared resources | All instances retry at exactly the same intervals, causing load spikes |
+| Y-4 | Circuit breaker | For services with sustained failures, a circuit breaker stops retrying and fails fast after N consecutive failures | System retries indefinitely against a down service, wasting resources and delaying fallback |
+| Y-5 | Idempotency awareness | Retried operations are safe to repeat (idempotent) or use deduplication keys | Non-idempotent operations (e.g., payment charges) retried without deduplication |
+
+---
+
+## Concurrency Safety
+
+Verify that concurrent access to shared state is safe.
+
+| # | Check | Pass Criteria | Fail Criteria |
+|---|-------|---------------|---------------|
+| C-1 | Mutex / lock patterns | Shared mutable state accessed by concurrent operations is protected by a mutex, lock, or serialization queue | Two async operations can interleave reads and writes to the same state |
+| C-2 | Compare-and-swap (CAS) | State updates that depend on current value use CAS or optimistic locking patterns | Read-then-write without checking that the value hasn't changed between read and write |
+| C-3 | Single-instance guards | Operations that must run exactly once (initialization, migration) have guard mechanisms (flags, locks, or idempotency checks) | Initialization can run concurrently from two entry points, causing duplicate setup or race conditions |
+| C-4 | Async iteration safety | Collections are not mutated during async iteration (`for await ... of`) | Array/Map modified while being iterated, causing skipped or duplicate items |
+| C-5 | Promise.all error handling | `Promise.all` failures are handled (consider `Promise.allSettled` when partial success is acceptable) | One rejection in `Promise.all` causes all results to be lost; no partial success handling |
+
+---
+
+## Graceful Degradation
+
+Verify that the system handles partial failures without cascading collapse.
+
+| # | Check | Pass Criteria | Fail Criteria |
+|---|-------|---------------|---------------|
+| G-1 | Partial failure tolerance | System continues operating when a non-critical subsystem fails; critical path is isolated from optional features | Single subsystem failure takes down the entire system |
+| G-2 | Feature flags for degraded mode | Degraded behavior can be toggled via configuration without code deployment; operators can disable failing features | Degraded mode requires a code change and redeployment to activate |
+| G-3 | Health check accuracy | Health endpoints reflect actual system state, including degraded subsystems | Health check returns "healthy" while a critical subsystem is down |
+| G-4 | Bulkhead isolation | Independent request paths don't share failure domains; one slow endpoint doesn't block others | All requests share a single thread pool or connection pool; one slow path starves others |
+| G-5 | Load shedding | System rejects excess load with clear error (429/503) rather than accepting and timing out | System accepts all requests regardless of capacity, causing timeouts and cascading failures |
+
+---
+
+## How to Use This Checklist
+
+1. **Scope:** Apply to the files/modules specified in the harden skill invocation
+2. **Evaluate:** For each check, determine Pass or Fail based on the criteria
+3. **Report:** Failed checks become findings with the severity from the corresponding dimension (DIM-7 for resource/timeout/retry/concurrency, DIM-2 for degradation visibility)
+4. **Prioritize:** HIGH findings (unbounded growth, missing timeouts on critical paths, no retry limits) before MEDIUM (suboptimal patterns that don't risk failure)

package/skills/scan/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: scan
+description: "Run deterministic pattern checks against backend code. Use when you need mechanical detection of known anti-patterns, code smells, or structural issues. Triggers: 'scan code', 'check patterns', 'run checks', or /axiom:scan. Do NOT use for qualitative architecture review — use axiom:critique instead."
+user-invokable: true
+metadata:
+  author: lvlup-sw
+  version: 0.1.0
+  category: assessment
+  dimensions:
+    - pluggable
+---
+
+# Scan Skill
+
+## Overview
+
+Deterministic check engine that runs grep patterns and structural analysis against backend code. Accepts a `scope` argument (file path, directory path, or cwd) and a `dimensions` argument (comma-separated dimension list or "all") to control which checks execute.
+
+This skill performs purely mechanical detection — it matches known patterns, counts structural violations, and reports findings with exact file locations. It does not make qualitative judgments about architecture or design. Other skills (like `axiom:critique`) handle subjective assessment and invoke `scan` when they need deterministic evidence.
+
+See `@skills/scan/references/check-catalog.md` for scan-specific execution guidance including ordering, batching, and exclusions.
+
+## Triggers
+
+Activate this skill when:
+- User says "scan code", "check patterns", "run checks", or "detect anti-patterns"
+- User runs `/axiom:scan`
+- Another axiom skill requests deterministic pattern detection
+- User wants mechanical verification of known code smells
+
+Do not activate this skill when:
+- User wants qualitative architecture review — use `axiom:critique` instead
+- User wants a full quality audit — use `axiom:audit` instead
+- User needs subjective design feedback rather than pattern matching
+
+## Process
+
+### Step 1: Load Check Catalog
+
+Load the canonical check definitions from `@skills/backend-quality/references/deterministic-checks.md`. This file defines every grep pattern, structural check, and their associated dimensions and severities.
+
+### Step 2: Load Project-Specific Checks (Optional)
+
+If `.axiom/checks.md` exists in the project root, load additional project-specific check definitions. These follow the same format as the canonical catalog and are merged into the check set. If the file does not exist, silently skip this step.
+
+### Step 3: Filter by Requested Dimensions
+
+Apply the `dimensions` argument to filter the merged check set:
+- If `dimensions` is `"all"` or omitted, run every check in the catalog
+- If `dimensions` is a comma-separated list (e.g., `"topology,observability"`), only run checks tagged with those dimensions
+- Invalid dimension names produce an actionable error message listing valid dimensions
+
+### Step 4: Execute Checks
+
+For each check in the filtered set, run the grep or structural pattern against the resolved `scope`:
+- Execute grep patterns using the exact expressions from the catalog
+- Run structural analysis checks (file counts, nesting depth, import graphs)
+- Collect all matches with file path, line number, and matched content
+- Record checks that produced zero matches as passing
+
+### Step 5: Format Findings
+
+Format each match as a finding per `@skills/backend-quality/references/findings-format.md`. Every finding produced by this skill is marked `deterministic: true` to distinguish mechanical detections from qualitative assessments.
+
+### Step 6: Group and Output
+
+Output findings grouped by dimension, then by severity (HIGH, MEDIUM, LOW) within each dimension. Include:
+- Total checks run and total findings
+- Per-dimension summary with finding counts
+- Individual findings with file location, matched pattern, and remediation hint
+
+## Error Handling
+
+- **Invalid patterns:** If a grep pattern from the catalog fails to compile or execute, report the specific pattern and error message. Do not silently skip — the user needs to know which check is broken so they can fix the catalog entry.
+- **Empty scope:** If the resolved scope contains no files to scan (empty directory, nonexistent path), return a "nothing to scan" message with the resolved path. Do not treat this as a failure.
+- **Missing `.axiom/checks.md`:** Silently skip project-specific check loading. This file is optional and its absence is expected for projects that have not customized their check set.
+- **Permission errors:** If a file cannot be read due to permissions, log the file path and continue scanning remaining files.
+
+## Output Format
+
+All findings use the standard format from `@skills/backend-quality/references/findings-format.md` with one addition: every finding includes `deterministic: true` to signal that it was produced by mechanical pattern matching, not qualitative judgment.
+
+```yaml
+dimension: observability
+severity: MEDIUM
+deterministic: true
+file: src/handlers/query.ts
+line: 42
+pattern: readEvents
+match: "const items = await readEvents(stream)"
+remediation: "Move raw event reads out of query handlers — use a read model projection instead"
+```
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Make qualitative judgments about matches | Report the match and let critique/review skills interpret |
+| Skip checks that produce many matches | Report all matches — downstream skills handle prioritization |
+| Suppress false positives silently | Report them and let the user tune exclusions in `.axiom/checks.md` |
+| Run checks outside the requested scope | Respect the scope boundary strictly |
+| Invent patterns not in the catalog | Only run checks defined in the canonical or project-specific catalogs |

package/skills/scan/references/check-catalog.md

@@ -0,0 +1,68 @@
+# Check Catalog — Scan Execution Guidance
+
+Scan-specific guidance for executing the deterministic checks defined in the canonical catalog at `@skills/backend-quality/references/deterministic-checks.md`. This document covers execution order, performance strategies, and result interpretation.
+
+## Execution Order
+
+Run checks from cheapest to most expensive. This lets you fail fast on simple violations before investing time in structural analysis.
+
+1. **Simple grep patterns** (fast, single-pass text matching) — string literals, regex against individual files
+2. **Multi-file grep patterns** (fast, but touches more files) — cross-file import checks, naming conventions
+3. **Structural analysis** (slower, requires parsing or counting) — nesting depth, cyclomatic complexity proxies, file size checks
+4. **Cross-reference checks** (slowest, requires building dependency graphs) — unused exports, circular imports, missing test coverage mapping
+
+Within each tier, run checks in dimension order (DIM-1 through DIM-7) for predictable output grouping.
+
+## Timeout Guidance
+
+- **Per-check timeout:** 30 seconds for any individual grep or structural check. If a single pattern takes longer, report it as a timeout finding rather than blocking the entire scan.
+- **Total scan timeout:** 5 minutes for a full "all dimensions" scan on a typical repository. For monorepos or very large codebases, recommend running dimension-by-dimension.
+- **Early termination:** If a scope contains more than 10,000 files after exclusions, warn the user and suggest narrowing the scope before proceeding.
+
+## Batch Strategies
+
+Running patterns one at a time is wasteful when scanning large codebases. Use these strategies to reduce I/O overhead:
+
+- **Combined grep:** Where multiple patterns target the same file set and dimension, combine them into a single grep invocation using alternation (`pattern1\|pattern2\|pattern3`). Parse the output to attribute matches back to individual checks.
+- **File-type grouping:** Group checks by their `--include` glob (e.g., all `*.ts` checks together, all `*.py` checks together) to avoid re-traversing the directory tree.
+- **Scope pre-filtering:** Resolve the file list once via `find` or glob expansion, then run all grep patterns against the pre-filtered list rather than letting each grep re-walk the tree.
+- **Parallel execution:** When the check set is large, run independent dimension groups in parallel. D1 checks have no dependency on D3 checks, so they can execute concurrently.
+
+## Default Exclusions
+
+Always exclude these paths and file types from scanning unless the user explicitly overrides:
+
+- `node_modules/` — third-party dependencies, not project code
+- `dist/` — build output, generated from source
+- `.git/` — version control internals
+- `build/` — alternative build output directory
+- `coverage/` — test coverage reports
+- `*.min.js`, `*.min.css` — minified assets
+- Binary files (images, fonts, compiled artifacts) — not scannable as text
+- Generated files (`*.generated.ts`, `*.g.ts`, `*.pb.ts`) — produced by code generators, not authored
+
+These exclusions prevent false positives from non-authored code and keep scan times reasonable.
+
+## Interpreting Results
+
+### True Positives
+
+A match against a catalog pattern in authored code is a true positive. Report it with the full context: file path, line number, matched text, and the remediation hint from the catalog entry.
+
+### False Positives
+
+Some patterns intentionally cast a wide net. Common false positive scenarios:
+
+- **Test files:** Patterns that detect anti-patterns in production code may match intentional test doubles or test assertions. The catalog should tag checks with `exclude-tests: true` where appropriate.
+- **Comments and documentation:** A grep pattern may match a comment explaining why a pattern is avoided. Context lines (-B/-A) help the user distinguish these.
+- **Legacy code with suppression markers:** If a file contains `// axiom-ignore-next-line` or `// axiom-ignore: <check-id>`, skip that specific match. This is the project-level false positive suppression mechanism.
+
+When in doubt, report the match. It is better to surface a false positive that the user can dismiss than to silently hide a true violation. Users can add exclusions to `.axiom/checks.md` to suppress recurring false positives.
+
+### Zero Matches
+
+A check that produces zero matches is a passing check. Record it in the summary as passed — this gives the user confidence that the dimension was actually evaluated, not just skipped.
+
+## Cross-Reference
+
+The canonical check definitions (patterns, dimensions, severities, remediation hints) live in `@skills/backend-quality/references/deterministic-checks.md`. This file is the single source of truth for what to check. The scan skill does not define its own patterns — it only defines how to execute them efficiently.

package/skills/verify/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: verify
+description: "Validate test quality by finding test-production divergence, mock overuse, and schema drift. Use when evaluating test suite health or after discovering a bug that tests missed. Triggers: 'check tests', 'test quality', 'verify contracts', or /axiom:verify. Do NOT use for architecture review — use axiom:critique instead."
+user-invokable: true
+metadata:
+  author: lvlup-sw
+  version: 0.1.0
+  category: assessment
+  dimensions:
+    - test-fidelity
+    - contracts
+---
+
+# Verify — Test Validation
+
+## Overview
+
+Test validation skill covering DIM-4 (Test Fidelity) and DIM-3 (Contracts) from the backend quality dimension taxonomy. Verify finds the gap between what your tests claim to prove and what they actually exercise — the space where bugs hide behind passing suites.
+
+This skill focuses on two complementary concerns:
+
+- **Test Fidelity (DIM-4):** Do tests exercise actual production behavior, or do they test a parallel universe of mocks and test-only wiring?
+- **Contracts (DIM-3):** Do schemas, types, and API boundaries stay in sync between declaration and usage?
+
+## Triggers
+
+Activate this skill when:
+- Evaluating test suite health after a milestone
+- A bug was found that existing tests should have caught
+- Reviewing test quality during code review
+- Investigating why tests pass but production breaks
+- Checking schema/contract integrity after API changes
+
+Do NOT activate when:
+- Reviewing architecture, coupling, or SOLID compliance — use `axiom:critique`
+- Investigating error handling or observability — use `axiom:harden`
+- Looking for dead code or vestigial patterns — use `axiom:distill`
+
+## Process
+
+### Step 1: Load Dimension Definitions
+
+Load the relevant dimension definitions from `@skills/backend-quality/references/dimensions.md` — specifically the DIM-4 (Test Fidelity) and DIM-3 (Contracts) sections. These define the invariants, detectable signals, and severity guides for each dimension.
+
+### Step 2: Run Deterministic Checks
+
+Run `axiom:scan` targeting the Test Fidelity and Contracts dimensions. This surfaces mechanical findings — grep-detectable patterns like:
+- `describe.skip` / `it.skip` without issue references
+- More than 3 `vi.mock()` or `jest.mock()` calls in a single test file
+- `as Type` assertions without preceding type guards
+- Schema fields referenced in code but absent from Zod/JSON schema definitions
+
+### Step 3: Layer Qualitative Assessment
+
+On top of deterministic findings, apply human-judgment assessment for patterns that require understanding intent:
+
+- **Test-production divergence:** Compare test setup and factory functions against production initialization code. Are tests creating instances the same way production does? Different instances of shared resources, different initialization order, different configuration, and different wiring are all divergence signals.
+
+- **Mock fidelity:** Are mocks placed at true infrastructure boundaries only (HTTP, database, filesystem)? More than 3 mocks in a single test is a smell — it usually means the test is operating at the wrong layer. Check whether mocks verify behavior (what happened) or implementation (how it happened).
+
+- **Missing integration tests:** Identify cross-cutting concerns tested only with unit tests. Shared state, event propagation, multi-module workflows, and initialization sequences need integration-level coverage.
+
+- **Schema/contract drift:** Look for types removed but still read at runtime, breaking API changes without versioning, and Zod schemas that have diverged from their TypeScript type counterparts. See `@skills/verify/references/contract-testing.md` for detailed detection approaches.
+
+- **Test coverage gap analysis:** Are tests exercising only the happy path? Look for missing error paths, boundary cases, empty inputs, and concurrent scenarios.
+
+For detailed patterns and taxonomy, see `@skills/verify/references/test-antipatterns.md`.
+
+### Step 4: Output Findings
+
+Format all findings per `@skills/backend-quality/references/findings-format.md`. Each finding must include:
+- Dimension (DIM-3 or DIM-4)
+- Severity (HIGH, MEDIUM, LOW)
+- Evidence (file:line references)
+- Explanation and optional suggestion
+
+## The "Passing Tests, Broken System" Problem
+
+High test counts and high coverage percentages can create false confidence when tests do not exercise production paths. A suite of thousands of tests proves nothing if every test creates its own isolated world that diverges from how the system actually runs.
+
+**Canonical example — the EventStore divergence bug:** 4192 tests passed while the system silently lost events. The root cause: tests created and consumed events through the same EventStore instance, but production wired two separate instances that were never connected. Every test exercised a path that did not exist in production. The tests were not wrong in isolation — they were wrong in aggregate, testing a topology that production never used.
+
+This is the most dangerous class of test failure: the test suite becomes a confidence generator rather than a defect detector. Verify exists to find these gaps before they become production incidents.
+
+**Warning signs:**
+- Test setup differs from production startup sequence
+- All tests use in-memory implementations of dependencies that production resolves differently
+- No test exercises the actual wiring/initialization path
+- Tests mock the very thing they should be testing
+
+## Error Handling
+
+- **Empty scope:** If no files match the provided scope (or no scope is provided), output an informative message: "No files in scope for verify analysis. Provide a file path, directory, or glob pattern." Do not produce empty findings.
+- **No test files found:** If the scope contains source code but no test files, report this as a DIM-4 finding (severity depends on context).
+- **Parse failures:** If a file cannot be parsed for schema analysis, log and skip with a note in the output.
+
+## References
+
+- Dimension definitions: `@skills/backend-quality/references/dimensions.md`
+- Finding output format: `@skills/backend-quality/references/findings-format.md`
+- Test antipattern catalog: `@skills/verify/references/test-antipatterns.md`
+- Contract testing guide: `@skills/verify/references/contract-testing.md`