@use-the-fork/spindle 0.0.0-stage → 0.0.1

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/style-debug-artifacts.md

@@ -0,0 +1,144 @@
+---
+title: Debug Artifacts Left in Production Code
+impact: HIGH
+impactDescription: "console.log, dd(), dump(), var_dump — AI's exploratory leftovers ship to production"
+tags: style, debug, ai-fingerprint, cleanup
+---
+
+## Debug Artifacts Left in Production Code
+
+**Impact: HIGH (console.log, dd(), dump(), var_dump — AI's exploratory leftovers ship to production)**
+
+`console.log("here")`, `console.log("got user", user)`, `dd($order)`, `dump($result)`, `var_dump($payload)`, `print_r($data)`, `echo $error` — these are the breadcrumbs left from when the developer (or AI) was debugging. They ship to production and:
+
+- Leak sensitive data into stdout / log aggregators (PII, tokens)
+- Bloat production logs to the point you can't grep for real signal
+- `dd()` literally halts execution — if it reaches prod, your endpoint returns "1" + var_dump output instead of JSON
+
+AI is particularly bad about this because the model tends to add `console.log("got result", x)` "to help with debugging" and rarely removes it before "finalising" the function.
+
+## Incorrect
+
+```typescript
+// ❌ Debug artifacts left in
+
+async function processPayment(order: Order, token: string): Promise<Charge> {
+  console.log("processPayment start", order.id); // shipped
+  console.log("token", token); // SHIPS THE TOKEN
+  const charge = await stripe.charges.create({/* ... */});
+  console.log("got charge", charge); // shipped
+  return charge;
+}
+```
+
+```php
+// ❌ Same in PHP
+public function processWebhook(Request $request): JsonResponse
+{
+    $payload = $request->json()->all();
+    dd($payload);                                                 // halts execution; returns a debug page
+    // …rest never runs
+}
+
+public function calculateTax(Order $order): Money
+{
+    dump($order);                                                 // prints to stdout in production
+    print_r($order->items);
+    $taxRate = 0.06;
+    var_dump($taxRate);
+    return $order->subtotal->multiplied($taxRate);
+}
+```
+
+**Why it's slop:**
+
+- `dd()` in a controller is an outage — the request never completes
+- `console.log('token', token)` is a credentials leak; on serverless logs, every Stripe call ships the token to CloudWatch
+- `dump()` / `var_dump()` show up in HTTP responses if not in a CLI context (especially during `artisan tinker` or test failures)
+- A repo with 50+ stray `console.log` in production paths signals nobody is reading their own code before merging
+
+## Correct
+
+```typescript
+// ✅ No debug; if logging matters, use the proper logger with context
+import { logger } from "@/lib/logger";
+
+async function processPayment(order: Order, token: string): Promise<Charge> {
+  // Real logger — structured, redacts secrets, levels enforced
+  const log = logger.child({ orderId: order.id });
+  log.info("payment.start");
+
+  const charge = await stripe.charges.create({/* ... */});
+
+  log.info("payment.success", { chargeId: charge.id, amountCents: charge.amount });
+  return charge;
+}
+```
+
+```php
+// ✅ Structured logging at the boundary; no debug() calls
+
+public function processWebhook(Request $request): JsonResponse
+{
+    Log::withContext([
+        'webhook_id' => $request->header('Stripe-Webhook-Id'),
+        'event_type' => $request->json('type'),
+    ])->info('webhook.received');
+
+    // … actual handling …
+
+    return response()->json(['ok' => true]);
+}
+```
+
+**Why it reads human:**
+
+- A logger with structured fields and levels (info/warn/error) — not stdout spam
+- Tokens / secrets get redacted by the logger (or not logged at all)
+- The log lines are intentional, useful for production debugging, and won't break the response
+
+## When debug calls in production code ARE warranted
+
+Rare. Usually zero. Specific cases:
+
+- **Logs in well-defined CLI scripts** that are _meant_ to be verbose: a one-off data migration script can use `echo` / `console.log` freely
+- **Test-only files** (`*.test.ts`, `*Test.php`) — fine to keep debug there during development
+- **Explicit `if (DEBUG_MODE) console.log(...)`** wrapped behind a feature flag — fine, but rare in practice
+
+Production controllers, services, jobs, listeners, middleware: **zero raw debug calls**.
+
+## Detection
+
+```bash
+# JavaScript / TypeScript — console.log in production code
+grep -rEn '\bconsole\.(log|debug|info|warn)\(' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' \
+  src/ resources/js/ 2>/dev/null \
+  | grep -v -E '\.test\.|\.spec\.|/__tests__/|/scripts/'
+
+# PHP — debug helpers
+grep -rEn '\b(dd|dump|var_dump|print_r|var_export)\s*\(' --include='*.php' \
+  app/ 2>/dev/null
+
+# CI gate — block PRs that introduce debug artifacts
+NEW_DEBUG=$(git diff --diff-filter=ACM origin/main...HEAD -- 'app/**/*.php' 'src/**/*.ts' \
+  | grep -E '^\+.*\b(console\.log|dd\(|dump\(|var_dump\(|print_r\()')
+test -z "$NEW_DEBUG" || { echo "Debug artifacts in PR:"; echo "$NEW_DEBUG"; exit 1; }
+```
+
+Oxlint configuration (`.oxlintrc.json`):
+
+```json
+{
+  "rules": {
+    "no-console": ["error", { "allow": ["warn", "error"] }]
+  }
+}
+```
+
+Mago's `no-debug-symbols` flags PHP debug calls such as `var_dump`, `print_r`, and `dd`:
+
+```bash
+mago lint --only no-debug-symbols
+```
+
+Reference: [Laravel Logging docs](https://laravel.com/docs/logging) · [Oxlint no-console](https://oxc.rs/docs/guide/usage/linter/rules/eslint/no-console.html) · [Mago no-debug-symbols](https://mago.carthage.software/1.59.0/en/tools/linter/rules/#no-debug-symbols) · [Pino structured logging](https://github.com/pinojs/pino)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/style-hyper-consistent.md

@@ -0,0 +1,84 @@
+---
+title: Hyper-Consistent Formatting
+impact: MEDIUM
+impactDescription: "A codebase where every file looks linter-perfect is suspiciously not-human"
+tags: style, formatting, ai-fingerprint
+---
+
+## Hyper-Consistent Formatting
+
+**Impact: MEDIUM (A codebase where every file looks linter-perfect is suspiciously not-human)**
+
+Real codebases have geology — older files use older conventions, busy modules have rushed sections, 2am hotfix code has different spacing than carefully-reviewed weeks. AI-generated code is **uniformly polished**: every function the same length, every blank line in the same place, every import alphabetized, no styling drift anywhere. This isn't a hallmark of quality — it's a hallmark of generation.
+
+The fingerprint is **uniformity at scale**. One file looking pristine is fine. A 2000-line PR where every file is identically pristine, across files that should have different velocity histories, is a strong AI signal.
+
+## What it looks like
+
+The PR diff shows:
+
+- Every PHP file has exactly 4-space indent, exactly one blank line between methods, exactly two blank lines between class members, every parameter aligned identically
+- Every TS file has the same import-grouping pattern, named imports always alphabetised, every arrow function body wrapped identically
+- No `// HACK:` / `// XXX:` / late-night comments anywhere
+- No commented-out code (clean — but also no signs of someone exploring)
+- Identical commit-message structure across 50 commits
+- All files use the same paradigm (e.g., every function is an arrow function; every class uses constructor property promotion) even in places where the existing codebase mixed styles
+
+## Why this matters
+
+Code geology is a tool for the next developer:
+
+- **Different ages tell different stories** — "this section is from 2022, before we switched to..."
+- **`// HACK:` markers signal known fragility** that hasn't been worth refactoring
+- **Commented-out code reveals exploration** — "we tried X, didn't work, kept the option in case"
+- **Velocity differences** show which paths were rushed and might harbour bugs
+
+A repo with no geology forces every reader to start fresh — no inherited context, no "the team didn't bother fixing this, it works fine" signal. AI-generated codebases are flat: every line treated as equally important.
+
+## The "all green field" tell
+
+Hyper-consistency is most suspicious in **brownfield additions** — i.e., when AI adds code to a codebase that has its own conventions. Real engineers either:
+
+- **Match the existing style** (consistent with the surrounding 50 files)
+- **Refactor the surrounding files** alongside their change (drift announces itself in the diff)
+- **Introduce a deliberate change** with an explanation ("new files use the new pattern; old files updated as touched")
+
+AI typically does the first poorly — it picks "the most recent convention" or "the most popular convention from training data" rather than matching the actual codebase. Result: the new files are linter-perfect by some standard, but inconsistent with the surrounding codebase.
+
+## What "human formatting" looks like
+
+You won't catch this with a linter. It's a feel:
+
+- Some files have slightly off blank-line spacing where someone hit enter twice
+- Imports sometimes group "stuff I added recently" at the top
+- One file has 6-space indent inside a heredoc because the dev didn't fight prettier on it
+- A function has an extra blank line before a tricky if-branch where the author paused to think
+- A 2-line comment is in mid-sentence-case because someone typed it angry
+
+These tiny artifacts are how humans write code. Their absence — especially across many files at once — is the slop.
+
+## Detection
+
+There's no automatic detector. The signal is human-judgment:
+
+1. **Run the diff through `git diff --stat`** — many files changed at once is normal; many files all with the same line-count profile is suspicious
+2. **`git log --author` distribution** — if the diff is from one author but covers 30 files in one commit, raise an eyebrow
+3. **Compare new files to surrounding files** — does the indentation, import order, brace style match the existing convention?
+4. **Search for `// HACK:` / `// XXX:` markers** in the new files — their _absence_ is the signal:
+
+   ```bash
+   git diff origin/main...HEAD -- '*.ts' '*.php' | grep -E '// HACK:|// XXX:|// FIXME' || echo "NO HACK/XXX MARKERS"
+   ```
+
+5. **Mixed-paradigm check** — in a TS PR, count `function` declarations vs arrow functions; in a PHP PR, count `final class` vs `class`. A sudden swing is a tell.
+
+## What to do
+
+If a PR looks hyper-consistent:
+
+- Ask the author: "Was this AI-assisted? Walk me through the section in `OrderService` line 80." Their ability to explain the _intent_, not just the code, separates "AI-written, human-reviewed" from "AI-written, accepted-as-is".
+- Sample a few functions and ask: "What's the trade-off you chose here?" If they shrug, the code wasn't really written by them.
+
+The goal isn't to ban AI assistance — it's to make sure the author owns the code they ship.
+
+Reference: Internal: [`style-no-hack-scars`](style-no-hack-scars.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/style-no-hack-scars.md

@@ -0,0 +1,113 @@
+---
+title: No HACK Scars — Suspiciously Pristine Code
+impact: MEDIUM
+impactDescription: "Real codebases have geology; absence of any '// HACK:' / '// XXX:' markers is itself a tell"
+tags: style, geology, ai-fingerprint
+---
+
+## No HACK Scars — Suspiciously Pristine Code
+
+**Impact: MEDIUM (Real codebases have geology; absence of any '// HACK:' / '// XXX:' markers is itself a tell)**
+
+A real codebase has _scars_. `// HACK:` comments where someone went around the type system to ship. `// XXX:` markers where the engineer noticed something fishy but had to ship. Files with a "we tried it the right way; this is the workaround until Stripe v2" note. These markers signal:
+
+- A human engineered the code, hit a real constraint, and acknowledged the trade-off
+- The team agreed to ship with the trade-off rather than over-engineer
+- A future engineer is being warned
+
+AI-generated codebases are flat: no `// HACK:`, no `// XXX:`, no "we know this is wrong but" markers. Every line presented as equally polished. The _absence_ of scars is the slop signal — real systems don't look like this.
+
+## The pattern
+
+You can audit a repo's "humanity" by looking for these markers:
+
+```bash
+git grep -E '// (HACK|XXX|NOTE|GOTCHA|HMMMM|WTF)' | wc -l
+```
+
+A repo with 50 of these is alive. A repo with zero across a 50K-line codebase is either:
+
+- A library that was rigorously reviewed across many years (rare)
+- An AI-generated codebase passing as human (more common)
+
+You're not looking for high counts — you're looking for **some**. Two or three `// HACK:` markers in 5K LoC is healthy.
+
+## What healthy scars look like
+
+```php
+// ✅ Real human marker — explains the constraint
+public function chargeCustomer(int $cents, string $token): string
+{
+    // HACK: Stripe v1 SDK doesn't expose retry headers; manually parse from Response
+    // until we migrate to v2 (tracked in #1842).
+    try {
+        return $this->stripe->charges->create([...])->id;
+    } catch (RateLimitException $e) {
+        $retryAfter = (int) ($e->getResponse()->headers['Retry-After'] ?? 30);
+        sleep($retryAfter);
+        return $this->stripe->charges->create([...])->id;
+    }
+}
+```
+
+```typescript
+// ✅ XXX marker that warns the next reader
+function parseEnvNumber(key: string): number {
+  const raw = process.env[key];
+  // XXX: parseInt('1.5') === 1, parseFloat('1.5e10') === 15000000000 — fine for us
+  // because we only use this for ports and integer caps. Audit before reusing.
+  return parseInt(raw ?? "0", 10);
+}
+```
+
+```php
+// ✅ NOTE marker capturing tribal knowledge
+class OrderObserver
+{
+    public function creating(Order $order): void
+    {
+        // NOTE: tax_amount must be set BEFORE Stripe charge; the webhook handler
+        // re-reads this row and expects it to be non-zero.
+        $order->tax_amount = TaxCalculator::for($order);
+    }
+}
+```
+
+These tell the next engineer: _"someone thought about this; the workaround is intentional; if you change it, here's the context."_
+
+## What absence looks like
+
+Five files, 600 lines, all in a PR:
+
+- Every method has the same length and shape
+- Every error path is the same `try { ... } catch (e) { console.error(e); }`
+- No comments about edge cases, browser quirks, library bugs, race conditions
+- No `// HACK:` / `// XXX:` / `// NOTE:` anywhere
+- Every variable has a "perfect" name
+
+That's not human. Real production code dealing with real third parties has scars.
+
+## What to do when you find pristine-looking code
+
+This rule is harder to action than to detect. Recommended response:
+
+1. **Pair-review with the author** — ask them to walk you through one of the "perfect" sections. If they can articulate the _why_ (and the trade-offs they considered), it's fine. If they can't, treat it as AI-assisted code that needs deeper review.
+2. **Run mutation testing on the new code** — Stryker (TS) / Infection (PHP). Mirror-tests die fast.
+3. **Sample edge cases** — try inputs the AI wouldn't have thought of (empty string, very long string, Unicode, negative numbers, future dates, leap years). If the code falls over on basics, the polish was cosmetic.
+
+## Detection
+
+```bash
+# Count scars in the existing repo (the baseline)
+git grep -cE '// (HACK|XXX|NOTE|GOTCHA|WTF|FIXME)' -- '*.ts' '*.tsx' '*.php' '*.js' '*.jsx' 2>/dev/null | head
+
+# Same, but for the PR diff only — if a 1000-line PR adds zero scars, suspicious
+git diff origin/main...HEAD -- '*.ts' '*.tsx' '*.php' | \
+  grep -cE '^\+.*// (HACK|XXX|NOTE|GOTCHA|WTF)'
+```
+
+A PR adding > 500 LoC with zero `HACK:` / `XXX:` / `NOTE:` is unusual. Real engineering on real systems leaves these.
+
+**Note:** this rule cuts both ways. Don't _add_ a `// HACK:` just to look human. Add them when you actually have a hack to mark. The signal is genuine, not performative.
+
+Reference: Internal: [`style-hyper-consistent`](style-hyper-consistent.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/style-trivial-boilerplate.md

@@ -0,0 +1,191 @@
+---
+title: Trivial Boilerplate
+impact: MEDIUM
+impactDescription: "Pattern-matched boilerplate that hides intent and inflates line count"
+tags: style, boilerplate, ai-fingerprint, readability
+---
+
+## Trivial Boilerplate
+
+**Impact: MEDIUM (Pattern-matched boilerplate that hides intent and inflates line count)**
+
+The class of "code that says less than the underlying expression". Common AI variants:
+
+- `if (x) return true; else return false;` — when `return x` does it
+- `return x === true ? true : false;` — ditto
+- `const isPaid: boolean = order.status === 'paid';` — TS infers `boolean` already; the annotation is noise
+- `const name: string = 'asyraf';` — TS infers `string`
+- `await Promise.resolve(value)` — when `value` is already non-Promise
+- `try { await fn(); } catch (e) { throw e; }` — pass-through catch
+- `[...array]` to "make a copy" when the next operation doesn't mutate
+
+Each is a small AI fingerprint. A few are fine. A repo with many of them across files reads as model-generated.
+
+## Incorrect
+
+```typescript
+// ❌ if-true-false
+function isPaid(order: Order): boolean {
+  if (order.status === "paid") {
+    return true;
+  } else {
+    return false;
+  }
+}
+
+// ❌ Ternary returning the booleans it was given
+function isCompleted(order: Order): boolean {
+  return order.status === "completed" ? true : false;
+}
+
+// ❌ Redundant type annotations on obvious literals
+const name: string = "asyraf";
+const age: number = 30;
+const isActive: boolean = true;
+const orders: Order[] = await db.orders.find(); // db.orders.find() return type IS Order[]
+
+// ❌ Pass-through catch
+async function processPayment(order: Order): Promise<Charge> {
+  try {
+    return await stripe.charges.create({/* ... */});
+  } catch (e) {
+    throw e; // catch literally does nothing
+  }
+}
+
+// ❌ Unnecessary await + Promise.resolve
+async function formatName(user: User): Promise<string> {
+  return await Promise.resolve(`${user.first} ${user.last}`);
+}
+
+// ❌ Spread to "copy" — but nothing mutates
+function totalsFor(items: Item[]): number {
+  const copied = [...items]; // unused: the next op doesn't mutate
+  return copied.reduce((s, i) => s + i.price, 0);
+}
+```
+
+```php
+// ❌ PHP equivalents
+public function isPaid(Order $order): bool
+{
+    if ($order->status === 'paid') {
+        return true;
+    } else {
+        return false;
+    }
+}
+
+public function processWebhook(Request $request): JsonResponse
+{
+    try {
+        return $this->handle($request);
+    } catch (\Exception $e) {
+        throw $e;                                  // pass-through
+    }
+}
+```
+
+**Why it's slop:**
+
+- Each line carries no information beyond the simpler form
+- The `try { ... } catch (e) { throw e; }` is the most embarrassing — six tokens to do nothing
+- Type annotations on inferred literals fight the type system instead of using it
+- A reader's eyes have to traverse "what does this expand to?" rather than read the expression directly
+
+## Correct
+
+```typescript
+// ✅ Direct expressions
+function isPaid(order: Order): boolean {
+  return order.status === "paid";
+}
+
+function isCompleted(order: Order): boolean {
+  return order.status === "completed";
+}
+
+// ✅ Let TS infer
+const name = "asyraf";
+const age = 30;
+const isActive = true;
+const orders = await db.orders.find();
+
+// ✅ No catch when not handling
+async function processPayment(order: Order): Promise<Charge> {
+  return stripe.charges.create({/* ... */});
+}
+
+// ✅ No need to await a non-Promise
+function formatName(user: User): string {
+  return `${user.first} ${user.last}`;
+}
+
+// ✅ No spread when nothing mutates
+function totalsFor(items: Item[]): number {
+  return items.reduce((s, i) => s + i.price, 0);
+}
+```
+
+```php
+// ✅ PHP equivalents
+public function isPaid(Order $order): bool
+{
+    return $order->status === 'paid';
+}
+
+public function processWebhook(Request $request): JsonResponse
+{
+    return $this->handle($request);
+}
+```
+
+**Why it reads human:**
+
+- Each expression does exactly the work; nothing extra
+- Type inference does its job; the type annotations are added where they earn their place (function signatures, public APIs)
+- No pass-through catch; if an error needs handling, it's handled
+
+## When annotations / spreads ARE worth it
+
+A few cases:
+
+- **Public-API parameters / returns** — explicit types document the contract: `function add(a: number, b: number): number`
+- **Complex inferred types** — annotate when the inferred type is hard to read
+- **Boundary code** — `as const`, `satisfies`, or explicit annotations on configuration objects help downstream type narrowing
+- **Spread when you actually want a copy** — before sorting, before mutating, before passing to a function that mutates
+
+The trivial-boilerplate test: **does removing the construct change the program's Behavior or the reader's understanding?** If no, remove.
+
+## Detection
+
+```bash
+# if-true-false
+grep -rEnB1 -A2 'if\s*\([^)]+\)\s*\{?\s*$' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.php' \
+  src/ app/ 2>/dev/null | grep -B2 -A1 'return true\b' | grep -A2 'else' | head
+
+# Pass-through catch
+grep -rEnB0 -A1 'catch\s*\([^)]*\)\s*\{' --include='*.ts' --include='*.tsx' --include='*.php' \
+  src/ app/ 2>/dev/null | grep -B1 '^\s*throw\b'
+
+# Ternary returning booleans
+grep -rEn '\?\s*true\s*:\s*false\b' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.php' \
+  src/ app/
+
+# Redundant type annotations on string/number/boolean literals (TS)
+grep -rEn ':\s*(string|number|boolean)\s*=\s*("[^"]*"|[0-9]+|true|false)' --include='*.ts' --include='*.tsx' src/
+```
+
+Oxlint configuration (`.oxlintrc.json`):
+
+```json
+{
+  "rules": {
+    "no-useless-return": "error",
+    "no-useless-catch": "error",
+    "no-unneeded-ternary": "error"
+  }
+}
+```
+
+Reference: [Oxlint no-useless-catch](https://oxc.rs/docs/guide/usage/linter/rules/eslint/no-useless-catch.html) · [Oxlint no-unneeded-ternary](https://oxc.rs/docs/guide/usage/linter/rules/eslint/no-unneeded-ternary.html) · [Oxlint no-useless-return](https://oxc.rs/docs/guide/usage/linter/rules/eslint/no-useless-return.html) · [PHP-CS-Fixer rules](https://cs.symfony.com/) · Internal: [`defensive-generic-catch`](defensive-generic-catch.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/test-doesnt-throw.md

@@ -0,0 +1,132 @@
+---
+title: "Doesn't Throw" Tests
+impact: HIGH
+impactDescription: "Tests that assert nothing meaningful; pass even when the function does the wrong thing"
+tags: testing, weak-assertions, ai-fingerprint
+---
+
+## "Doesn't Throw" Tests
+
+**Impact: HIGH (Tests that assert nothing meaningful; pass even when the function does the wrong thing)**
+
+A test that calls the function and then asserts the function didn't throw is barely a test. It verifies one of the weakest possible properties — "the program didn't crash" — and gives false confidence in coverage. AI often defaults to this pattern because it's the easiest way to make a test pass.
+
+A real test verifies a specific outcome. "Didn't throw" is an outcome only in the narrowest cases (you specifically want to verify a thrown error from a previous bug is now absent).
+
+## Incorrect
+
+```typescript
+// ❌ Tests that just verify "the call completes"
+
+describe("OrderService", () => {
+  it("places an order", async () => {
+    const service = new OrderService();
+    await expect(service.place(makeValidOrder())).resolves.not.toThrow();
+  });
+
+  it("exports users", async () => {
+    const service = new UserExportService();
+    const result = await service.export();
+    expect(result).toBeDefined(); // weak: undefined is the only failure mode caught
+  });
+
+  it("handles empty input", () => {
+    const result = sum([]);
+    expect(result).not.toBeNull(); // passes for 0, NaN, '', false, anything except null/undefined
+  });
+});
+```
+
+```php
+// ❌ Same pattern in PHPUnit / Pest
+test('it places an order', function () {
+    $service = new OrderService();
+
+    expect(fn () => $service->place(makeValidOrder()))->not->toThrow();
+});
+
+test('export returns something', function () {
+    $result = (new UserExportService())->export();
+    expect($result)->not->toBeNull();
+});
+```
+
+**Why it's slop:**
+
+- "Doesn't throw" tells you nothing about whether the right thing happened
+- `place(order)` could return without throwing AND not actually place the order
+- `export()` could return `undefined` (the test fails) OR `null` (test fails) OR an empty array, a misleading "true", etc. — the test catches only the narrowest failure
+- `not.toBeNull()` passes for `0`, `''`, `NaN`, `false` — all of which are usually bugs
+
+## Correct — assert what should happen
+
+```typescript
+// ✅ Specific outcomes
+
+describe("OrderService", () => {
+  it("place(order) persists the order and returns the saved row with status=pending", async () => {
+    const service = new OrderService(db);
+    const order = makeValidOrder({ total: 100_00 });
+
+    const saved = await service.place(order);
+
+    expect(saved.id).toBeDefined();
+    expect(saved.status).toBe("pending");
+    expect(saved.total).toBe(100_00);
+    expect(await db.orders.findById(saved.id)).toMatchObject({ status: "pending" });
+  });
+
+  it("exports all active users to CSV", async () => {
+    await db.users.insertMany([
+      { email: "a@b.com", active: true },
+      { email: "c@d.com", active: false },
+      { email: "e@f.com", active: true },
+    ]);
+
+    const csv = await new UserExportService(db).export();
+
+    expect(csv).toContain("a@b.com");
+    expect(csv).toContain("e@f.com");
+    expect(csv).not.toContain("c@d.com"); // inactive should be excluded
+  });
+
+  it("sum([]) returns 0", () => {
+    expect(sum([])).toBe(0);
+  });
+});
+```
+
+**Why it reads human:**
+
+- Each test verifies a specific, named outcome
+- Bugs are detected: changing `status: 'pending'` to `'paid'` would fail the test; returning all users (not just active) would fail; `sum([])` returning `NaN` would fail
+- Test names describe the _Behavior_, not the _function called_
+
+## When "doesn't throw" IS legitimate
+
+Rarely:
+
+- **Smoke tests** for a never-throws contract on a public API (one or two tests; not the bulk of the suite)
+- **Regression tests** for a specific previously-thrown error: "after fix #123, calling X with Y no longer throws"
+
+In these cases, name the test clearly: `it('does not throw on empty input — regression for #123')`.
+
+## Detection
+
+```bash
+# Tests whose only assertion is "not.toThrow" or "not.toBeNull"
+grep -rEn '\.not\.toThrow\(|\.not\.toBeNull\(|\.toBeDefined\(' \
+  --include='*.test.ts' --include='*.spec.ts' --include='*.test.tsx' src/ tests/ \
+  | head -30
+
+# PHPUnit / Pest equivalents
+grep -rEn '\bexpect\(.*\)->not->toThrow\(\)|->assertNotNull\(\$result\)' \
+  --include='*Test.php' --include='*.test.php' tests/
+
+# Heuristic: test files where the ratio of weak assertions to strong assertions is high
+# (manual review of files with > 5 weak assertions)
+```
+
+A few weak assertions are fine. A test suite dominated by them is a slop fingerprint.
+
+Reference: [Martin Fowler — Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html) · Internal: [`test-mock-everything`](test-mock-everything.md), [`test-mirror-implementation`](test-mirror-implementation.md)