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

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/comments-placeholder.md

@@ -0,0 +1,130 @@
+---
+title: Placeholder Comments Left In
+impact: CRITICAL
+impactDescription: "Reveals AI-generated code that was never completed; ships unfinished work as 'done'"
+tags: comments, placeholder, todo, ai-fingerprint
+---
+
+## Placeholder Comments Left In
+
+**Impact: CRITICAL (Reveals AI-generated code that was never completed; ships unfinished work as 'done')**
+
+Common AI-generated placeholders that should never reach `main`:
+
+```
+// implementation
+// implementation here
+// your code here
+// helper function
+// TODO: implement
+// TODO: implement this
+// TODO: add error handling
+// TODO: implement validation
+// FIXME: figure out edge case
+// HACK: temporary
+// placeholder
+// add your logic here
+```
+
+These mean the AI produced scaffolding the developer was supposed to fill in. If they reach the PR, they signal the author shipped without reading.
+
+Distinct from properly-tagged debt markers — a `// TODO(#1234, asyraf): rewrite after Stripe v2 migration` with an owner, ticket, and concrete unblocking condition is _not_ slop. That's tracked debt.
+
+## Incorrect
+
+```php
+// ❌ Placeholder comments shipped as 'done'
+
+public function calculateRefund(Order $order): Money
+{
+    // TODO: implement
+    return Money::zero();
+}
+
+public function process(Order $order): void
+{
+    // Validate the order
+    // TODO: add validation
+
+    $this->charge($order);
+
+    // helper function
+    // TODO: implement error handling
+}
+```
+
+```typescript
+// ❌ Same in TS
+function exportUsers(): User[] {
+  // your code here
+  return [];
+}
+
+function handlePayment(token: string) {
+  // implementation
+  // TODO: implement
+}
+```
+
+**Why it's slop:**
+
+- The function name promises a Behavior the body doesn't deliver
+- Reviewers usually skip past `// TODO` without realising the function is empty
+- These slip through tests because the placeholder body type-checks
+- If genuinely intended as future work, it belongs in the issue tracker, not the source file
+
+## Correct
+
+```php
+// ✅ Either implement, or fail loud, or remove the method entirely
+
+public function calculateRefund(Order $order): Money
+{
+    throw new BadMethodCallException(
+        'Refund calculation not yet implemented — see #1842 for the policy spec.'
+    );
+}
+
+// ✅ Or genuine, tracked work-in-progress with owner + ticket:
+// TODO(#1842, asyraf): cap refunds at original-charge-minus-shipping
+public function calculateRefund(Order $order): Money
+{
+    return $order->total->subtract($order->shippingCost);
+}
+```
+
+```typescript
+// ✅ Fail loud so the gap is impossible to ship past
+function exportUsers(): User[] {
+  throw new Error("exportUsers: not implemented (see #420)");
+}
+```
+
+**Why it reads human:**
+
+- An empty function body that throws is impossible to merge by accident; tests will catch it
+- A tracked `TODO` with `(#issue, @owner)` is real debt, not abandoned scaffolding
+- A human author either implements the function or explicitly fails — they don't ship "Returns nothing for now"
+
+## Detection
+
+```bash
+# Common AI placeholders — match only when prefixed by a comment marker
+# (without the required prefix, the regex would flood on class names like "ServiceImplementation").
+grep -rEn --include='*.php' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' \
+  '(//|/\*|#)\s*(implementation|implementation here|your code here|helper function|placeholder|add your logic|add error handling|add validation)\b' \
+  app/ src/ 2>/dev/null
+
+# Bare TODO/FIXME (without ticket reference)
+grep -rEn --include='*.php' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' \
+  '(TODO|FIXME)([^(#]|$)' app/ src/ 2>/dev/null | grep -v '#[0-9]'
+
+# Combined: TODOs lacking issue references — CI gate
+NEW=$(git diff --name-only --diff-filter=ACM origin/main...HEAD)
+BARE=$(echo "$NEW" | xargs grep -EnH '\b(TODO|FIXME)\b' 2>/dev/null | grep -v '#[0-9]')
+test -z "$BARE" || { echo "Bare TODO/FIXME found — add (#issue, @owner):"; echo "$BARE"; exit 1; }
+```
+
+See also `technical-debt`'s `process-todo-fixme-aging` rule — the broader policy for tracked debt markers.
+
+Reference: Internal: [`comments-narration`](comments-narration.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/defensive-generic-catch.md

@@ -0,0 +1,153 @@
+---
+title: Generic catch Blocks That Don't Distinguish Errors
+impact: CRITICAL
+impactDescription: "82% of AI PRs (OX Security) — masks bugs as 'handled', breaks observability, kills debuggability"
+tags: defensive-programming, error-handling, ai-fingerprint
+---
+
+## Generic catch Blocks That Don't Distinguish Errors
+
+**Impact: CRITICAL (82% of AI PRs per OX Security study; masks bugs as 'handled', breaks observability, kills debuggability)**
+
+The single most-cited AI anti-pattern in 2025 research. Try/catch wrapped around code, with a generic catch that logs and swallows. Looks responsible. Is the opposite — it hides bugs and converts loud failures into silent corruption.
+
+Real error handling distinguishes:
+
+- **What can throw** (specific exception types)
+- **What's recoverable** (catch, retry, fall back)
+- **What's a bug** (re-throw, let it propagate)
+
+A bare `catch (e) { console.error(e); }` does none of this. It says "if anything goes wrong, I'll keep going" — and "anything" includes programmer errors that should crash so they're noticed.
+
+## Incorrect
+
+```php
+// ❌ Generic catch that swallows everything
+
+public function processPayment(Order $order): bool
+{
+    try {
+        $charge = $this->stripe->charges->create([
+            'amount'   => $order->total->cents(),
+            'currency' => 'usd',
+            'source'   => $order->paymentToken,
+        ]);
+        $order->update(['stripe_charge_id' => $charge->id, 'status' => 'paid']);
+        return true;
+    } catch (Exception $e) {
+        Log::error('Payment failed: ' . $e->getMessage());
+        return false;
+    }
+}
+```
+
+```typescript
+// ❌ Same TS pattern
+async function exportUsers(): Promise<User[]> {
+  try {
+    const users = await api.fetchAllUsers();
+    return users;
+  } catch (e) {
+    console.error("Export failed:", e);
+    return [];
+  }
+}
+```
+
+**Why it's slop:**
+
+- `Exception $e` catches _everything_, including `TypeError` (programmer bug) and `OutOfMemoryError` (system crash) — those should not be "handled" by logging and continuing
+- Returning `false` / `[]` lets the caller think the operation succeeded with no data, masking a real failure
+- `Log::error` lacks context — what was the order? what user? what amount? Future debugger has no anchor
+- A real Stripe error (card declined) gets the same treatment as a typo in the code
+
+## Correct
+
+```php
+// ✅ Catch specifically; re-throw what you don't understand
+
+public function processPayment(Order $order): void
+{
+    try {
+        $charge = $this->stripe->charges->create([
+            'amount'   => $order->total->cents(),
+            'currency' => 'usd',
+            'source'   => $order->paymentToken,
+        ]);
+        $order->update(['stripe_charge_id' => $charge->id, 'status' => 'paid']);
+    } catch (CardException $e) {
+        // Customer-facing failure — known, expected
+        $order->update(['status' => 'declined', 'decline_reason' => $e->getStripeCode()]);
+        throw new PaymentDeclined($e->getStripeCode(), previous: $e);
+    } catch (RateLimitException $e) {
+        // Transient — caller retries
+        throw new TransientPaymentFailure(retryAfterSeconds: 30, previous: $e);
+    }
+    // Any other exception propagates: TypeError, OutOfMemoryError, etc.
+    // — those are bugs we WANT to know about.
+}
+```
+
+```typescript
+// ✅ Specific errors, propagate the unknown
+async function exportUsers(): Promise<User[]> {
+  try {
+    return await api.fetchAllUsers();
+  } catch (e) {
+    if (e instanceof AbortError) {
+      // Caller aborted; that's a feature, not a failure
+      throw e;
+    }
+    if (e instanceof RateLimitError) {
+      await sleep(e.retryAfterMs);
+      return api.fetchAllUsers(); // one retry
+    }
+    // Network / parse / bug — propagate; don't return [] (the caller would think it succeeded with no users)
+    throw e;
+  }
+}
+```
+
+**Why it reads human:**
+
+- Each `catch` branch handles a specific, named condition with a specific remediation
+- Unknown errors propagate — the system fails loud, observability catches them, on-call wakes up before customers do
+- No silent "return false" / "return empty array" — caller can't accidentally treat failure as empty success
+
+## The "what would I want at 2am?" test
+
+When debugging a production incident, you want:
+
+- **Errors at the right loudness** — bugs crash with stack traces; expected failures have domain-specific exceptions you can grep
+- **Context, not just the message** — order ID, user ID, request ID, all in the log line
+- **No silent corruption** — a "successful" call that returned no data is the worst kind of failure
+
+The generic-catch pattern fails all three.
+
+## Detection
+
+```bash
+# Bare catches in PHP
+grep -rEn 'catch\s*\(\s*\\?Exception\b' --include='*.php' app/
+
+# Bare catches in TS / JS
+grep -rEn '\}\s*catch\s*\(\s*[a-zA-Z_]+\s*\)\s*\{' --include='*.ts' --include='*.tsx' --include='*.js' src/
+
+# Catch blocks that only log and continue
+grep -rEnB1 'console\.error\(.*\)\s*;\s*$' --include='*.ts' --include='*.tsx' src/
+
+# PHP equivalent
+grep -rEnB1 'Log::(error|warning)\(.*\)' --include='*.php' app/Http/ app/Services/
+
+# Linter rules
+# Oxlint: enable no-empty for empty blocks and typescript/no-explicit-any for explicit any
+# These checks do not detect catch blocks that only log and continue.
+# Mago: detect empty PHP catch bodies
+mago lint --only no-empty-catch-clause
+```
+
+Mago's `no-empty-catch-clause` does not flag non-empty log-and-continue handlers. Review those manually. For catches that cannot match a known exception, the analyzer offers `check-dead-catch`, which requires `check-throws`; both default to `false`. These options check exception flow, not whether a catch is too broad, and undocumented throws can limit their accuracy.
+
+A small handful of generic catches is fine (e.g., at HTTP boundaries with structured logging). **Density** is the signal — > 5 generic catches in a single service is the AI fingerprint.
+
+Reference: [Oxlint no-empty](https://oxc.rs/docs/guide/usage/linter/rules/eslint/no-empty.html) · [Oxlint typescript/no-explicit-any](https://oxc.rs/docs/guide/usage/linter/rules/typescript/no-explicit-any.html) · [Mago no-empty-catch-clause](https://mago.carthage.software/1.59.0/en/tools/linter/rules/#no-empty-catch-clause) · [Mago analyzer configuration](https://mago.carthage.software/1.59.0/en/tools/analyzer/configuration-reference/) · Internal: [`defensive-impossible-null`](defensive-impossible-null.md), [`defensive-missing-real`](defensive-missing-real.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/defensive-impossible-null.md

@@ -0,0 +1,157 @@
+---
+title: Null Checks for Impossible Nulls
+impact: HIGH
+impactDescription: "Defensive code in places that can't fail; clutters the path and signals model didn't trust the type system"
+tags: defensive-programming, null-checks, type-safety, ai-fingerprint
+---
+
+## Null Checks for Impossible Nulls
+
+**Impact: HIGH (Defensive code in places that can't fail; clutters the path and signals model didn't trust the type system)**
+
+When the type system or surrounding code already guarantees a value is non-null, a defensive null check adds noise and tells the reader "the author wasn't sure". Common cases:
+
+- A non-nullable parameter (typed `User $user`, not `?User $user`) — can't be null
+- After `Model::findOrFail()` — never returns null (throws on miss)
+- After a non-null assertion in the previous line
+- Inside a `forEach` / `map` loop where the iterable can't contain null
+
+The pattern signals the model defaulted to "check everything for safety" without reading the types around it.
+
+## Incorrect
+
+```php
+// ❌ Null check after findOrFail — findOrFail throws if not found
+
+public function show(int $id): View
+{
+    $user = User::findOrFail($id);
+
+    if ($user === null) {
+        abort(404);
+    }
+
+    return view('users.show', compact('user'));
+}
+
+// ❌ Null check on a non-nullable parameter
+
+public function notify(User $user, string $message): void  // $user is required
+{
+    if ($user === null) {
+        return;
+    }
+    Mail::to($user)->send(new GenericNotification($message));
+}
+
+// ❌ Null check repeated in same function
+public function process(Order $order): void
+{
+    if ($order === null) return;
+    $items = $order->items;
+    if ($order === null) return;     // already checked above; flow can't make it null
+    foreach ($items as $item) {
+        if ($order === null) return; // still impossible
+        // ...
+    }
+}
+```
+
+```typescript
+// ❌ TS: defensive checks the compiler already enforced
+
+function greet(user: User): string {
+  // `user: User` — non-null in type system
+  if (!user) return ""; // dead branch; TS would error
+  return `Hi, ${user.name}`;
+}
+
+// ❌ Defensive after a guard
+function process(user: User | null): void {
+  if (!user) return; // narrows to User
+  if (user) {
+    // always true after the guard
+    doStuff(user);
+  }
+}
+
+// ❌ Optional chaining on a definitely-defined value
+const userId = currentUser.id; // currentUser is non-nullable here
+console.log(currentUser?.email); // ?. is unnecessary
+```
+
+**Why it's slop:**
+
+- The dead branch is dead — never executes; reviewers must mentally rule it out
+- Signals the author didn't trust the type system
+- `findOrFail` is well-known Laravel API; checking its result for null says "I read the docs but don't believe them"
+- Stacking redundant guards in one function (the third example) is unmistakable
+
+## Correct
+
+```php
+// ✅ Trust findOrFail — it throws, doesn't return null
+
+public function show(int $id): View
+{
+    return view('users.show', [
+        'user' => User::findOrFail($id),
+    ]);
+}
+
+// ✅ Non-nullable parameter — no check needed
+public function notify(User $user, string $message): void
+{
+    Mail::to($user)->send(new GenericNotification($message));
+}
+```
+
+```typescript
+// ✅ Trust the types
+function greet(user: User): string {
+  return `Hi, ${user.name}`;
+}
+
+// ✅ Single guard; TS narrows the type below
+function process(user: User | null): void {
+  if (!user) return;
+  doStuff(user); // TS knows user is User here
+}
+
+// ✅ No optional chaining when not optional
+console.log(currentUser.email);
+```
+
+**Why it reads human:**
+
+- Each line carries weight; no dead branches
+- Type system does the work, not runtime checks
+- Reader can scan past the function without ruling out impossible paths
+
+## When null checks ARE warranted
+
+- **At trust boundaries** — input from HTTP/queue/file, before the type narrows
+- **On nullable returns** from third-party libraries (e.g., `Eloquent::find()` returns `?Model`)
+- **In `try {} catch` flows** where the value might be partially constructed
+- **When the type really IS nullable** — `?User $user` parameters that the caller can leave empty
+
+The test: **does the type say it could be null?** If yes, check. If no, trust.
+
+## Detection
+
+```bash
+# Null checks immediately after findOrFail in PHP — a recognisable AI signature
+# (Two-pass: find files with findOrFail, then look for null checks inside them.)
+grep -rl 'findOrFail' --include='*.php' app/ | xargs grep -EnB1 'if\s*\(\s*\$[a-zA-Z_]+\s*===?\s*null\s*\)' 2>/dev/null
+
+# TS: optional chaining on values typed as non-null
+# (best caught via TS strict mode: noUncheckedIndexedAccess + strictNullChecks)
+npx tsc --noEmit --strict
+
+# PHP: run Mago's type analyzer, not just its syntax-based linter
+mago analyze
+```
+
+Use Mago's analyzer for PHP type analysis and inspect its diagnostics alongside the guard and surrounding control flow. Detection depends on the available type information, framework stubs, and configured ignores or baseline; a clean run does not prove every null check necessary. For TypeScript, retain strict type checking and manually verify redundant guards.
+
+Reference: [Mago analyzer configuration](https://mago.carthage.software/1.59.0/en/tools/analyzer/configuration-reference/) · [Mago analyzer command reference](https://mago.carthage.software/1.59.0/en/tools/analyzer/command-reference/) · [TS strict mode](https://www.typescriptlang.org/tsconfig#strict) · Internal: [`defensive-generic-catch`](defensive-generic-catch.md), [`defensive-missing-real`](defensive-missing-real.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/defensive-missing-real.md

@@ -0,0 +1,157 @@
+---
+title: Defensive in the Wrong Places — Missing the Real Defenses
+impact: CRITICAL
+impactDescription: "Code looks safe but the *actual* failure modes (network, queues, races) are unprotected"
+tags: defensive-programming, timeouts, resilience, ai-fingerprint
+---
+
+## Defensive in the Wrong Places — Missing the Real Defenses
+
+**Impact: CRITICAL (Code looks safe but the actual failure modes — network, queues, races — are unprotected)**
+
+OX Security 2025: **76% of AI-assisted PRs miss timeouts on external calls**. The same PRs are full of impossible null checks and generic try/catch. The pattern is: defensive in places that don't need it; not defensive in places that do.
+
+What AI often misses (the failure modes that actually take down production):
+
+- **No timeouts on outbound HTTP** — a slow third-party API hangs your request indefinitely
+- **No retry policy + jitter** — a transient blip cascades into a customer-visible failure
+- **No idempotency keys on payment/order creation** — a network retry creates duplicate charges
+- **No rate-limit checks before hitting an external API** — banned by Stripe / Shopify / etc.
+- **No circuit breaker** — keeps hammering a known-down dependency, queue backs up
+- **No locking / unique constraint** — race condition double-spends inventory
+- **No backpressure on workers** — queue grows unbounded; OOM
+
+These are the defenses that matter. A robust system has these; the dramatic-looking try/catch and null checks don't replace them.
+
+## Incorrect
+
+```php
+// ❌ Defensive theatre: try/catch wraps the wrong thing; real risks unprotected
+
+public function syncOrder(string $orderId): void
+{
+    try {
+        // No timeout — could hang for minutes
+        $response = Http::get("https://api.shopify.com/orders/{$orderId}");
+        $data = $response->json();
+
+        if ($data === null) {            // impossible — Http returns array or throws
+            Log::error('Sync failed');
+            return;
+        }
+
+        // No idempotency — if this retries, we create duplicates
+        Order::create($data);
+    } catch (Exception $e) {
+        Log::error('Sync failed: ' . $e->getMessage());
+    }
+}
+```
+
+```typescript
+// ❌ Same pattern in TS
+async function syncOrder(orderId: string): Promise<void> {
+  try {
+    // No timeout; no retry; no backoff
+    const res = await fetch(`https://api.shopify.com/orders/${orderId}`);
+    const data = await res.json();
+
+    if (!data) {
+      // impossible if res.json() resolved
+      console.error("Sync failed");
+      return;
+    }
+
+    await db.orders.create({ data });
+  } catch (e) {
+    console.error(e); // swallow
+  }
+}
+```
+
+**Why it's slop:**
+
+- The `if ($data === null)` is dead defence; the actual failure mode is "Shopify takes 90s to respond and our request timeout hits us first"
+- The try/catch swallows real failures but doesn't add the things that prevent them
+- Retried calls create duplicate orders (idempotency missing)
+- Looks responsible; isn't
+
+## Correct
+
+```php
+// ✅ The real defences — timeouts, idempotency, retry with backoff, circuit-break
+
+public function syncOrder(string $orderId): void
+{
+    $response = Http::timeout(10)                                  // hard timeout
+        ->retry(times: 3, sleepMilliseconds: 200, when: fn ($e) =>
+            $e instanceof ConnectionException || $e->getCode() === 429)
+        ->get("https://api.shopify.com/orders/{$orderId}");
+
+    $response->throw();   // throw on 4xx/5xx — let it propagate
+
+    Order::updateOrCreate(
+        ['shopify_id' => $orderId],                                // idempotency via unique key
+        $response->json()
+    );
+}
+```
+
+```typescript
+// ✅ TS with AbortController for timeout + retry policy
+async function syncOrder(orderId: string): Promise<void> {
+  const data = await fetchWithRetry(`https://api.shopify.com/orders/${orderId}`, {
+    timeoutMs: 10_000,
+    retries: 3,
+    retryOnStatus: [429, 502, 503, 504],
+  });
+
+  // Idempotent upsert by external id (unique index on shopify_id)
+  await db.orders.upsert({
+    where: { shopify_id: orderId },
+    create: data,
+    update: data,
+  });
+}
+```
+
+**Why it reads human:**
+
+- The actual failure modes (slow third party, transient errors, duplicate retries) are each addressed
+- Errors NOT covered by retry propagate — observability/alerts catch them
+- The idempotency key (`shopify_id`) prevents duplicate orders even under retry storms
+- The "try/catch" is gone — it added no value here
+
+## The real-defences checklist
+
+For any code that talks to the outside world, ask:
+
+- [ ] **Timeout** on every outbound call (HTTP, DB, queue, cache)?
+- [ ] **Retry** policy: how many, with what backoff, on which error types?
+- [ ] **Idempotency**: if the call is retried, will it create duplicate side effects?
+- [ ] **Rate limit** awareness: am I tracking my own request rate or relying on the upstream's error?
+- [ ] **Circuit breaker** for known-down dependencies (or at least a backoff cap)?
+- [ ] **Locking / unique constraints** on writes that could race?
+- [ ] **Backpressure** on workers reading from a queue?
+- [ ] **Real errors propagated** to observability instead of swallowed?
+
+A try/catch that doesn't add any of these isn't a defense. It's theatre.
+
+## Detection
+
+```bash
+# HTTP calls without explicit timeout (Laravel Http facade)
+grep -rEn 'Http::get\(|Http::post\(|Http::put\(|Http::delete\(' --include='*.php' app/ \
+  | grep -v 'timeout('
+
+# fetch() calls without AbortController / signal
+grep -rEn 'await fetch\(' --include='*.ts' --include='*.tsx' --include='*.js' src/ \
+  | grep -vE 'signal:|AbortController'
+
+# create() / insert() without idempotency check (rough — manual review)
+grep -rEn '(Order|Charge|Payment)::create\(' --include='*.php' app/
+```
+
+A repo can pass every other rule in this skill and still ship the wrong defenses. **This rule is the one to take seriously on payment, checkout, and integration code paths.**
+
+Reference: [Stripe — Idempotent Requests](https://docs.stripe.com/api/idempotent_requests) · [Hystrix / Resilience4j circuit breaker patterns](https://github.com/resilience4j/resilience4j) · OX Security study · Internal: [`defensive-generic-catch`](defensive-generic-catch.md)