lemmaly 0.1.0

package/skills/complexity-cuts/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: complexity-cuts
+description: Use when refactoring existing code that has poor Big-O — nested loops, O(n^2)+ scans, repeated work, redundant allocations, blown memory, or stated symptoms like "this is slow on large inputs", "times out", "OOM", "too much memory", "reduce complexity", "optimize this algorithm". Targets time and space complexity of code that already exists. For preventing bad complexity before code is written, use lemmaly. For math-level optimizations (Bloom, HLL, FFT, JL projection), escalate to mathguard.
+metadata:
+  priority: 2
+  role: corrective
+  pathPatterns:
+    - '**/*.{js,jsx,ts,tsx,mjs,cjs}'
+    - '**/*.py'
+    - '**/*.sql'
+    - '**/*.java'
+    - '**/*.cs'
+    - '**/*.go'
+    - '**/*.rs'
+    - '**/*.{cpp,cc,cxx,hpp,hh,hxx}'
+    - '**/*.php'
+    - '**/*.rb'
+  bashPatterns:
+    - 'slow'
+    - 'timeout'
+    - 'oom'
+    - 'optimize'
+  chainTo:
+    - skill: lemmaly
+      when: 'about to write new code instead of fixing existing'
+    - skill: invariant-guard
+      when: '3+ transformations have failed tests — likely a missing contract, not a missing optimization'
+    - skill: mathguard
+      when: 'classical floor reached and approximate/probabilistic structure could help'
+  retrieval:
+    aliases:
+      - optimize-bigo
+      - fix-n-squared
+      - lower-complexity
+    intents:
+      - optimize slow code
+      - reduce big-o
+      - fix n+1 query
+      - lower memory usage
+---
+
+# complexity-cuts — Lower Big-O on Existing Code
+
+lemmaly prevents bad complexity before code is written. complexity-cuts fixes it after the fact: code already exists, it works, but its time or space complexity is worse than necessary.
+
+**Violating the letter of these rules is violating the spirit of the skill.** Adapting "just a little" is how a faster-but-wrong rewrite ships.
+
+## The Iron Law
+
+```text
+NO TRANSFORMATION WITHOUT EXISTING TESTS GREEN BEFORE AND AFTER
+```
+
+If the code has no tests, you write a characterization test first (golden input → current output). Then transform. Then verify the test still passes. If you skip this, the optimization can silently break callers — and faster-but-wrong is worse than slow-and-right.
+
+## Non-negotiable rules
+
+1. **State current and target Big-O before touching code.** In one line:
+   - Current: `time = O(?)`, `space = O(?)`
+   - Target: `time = O(?)`, `space = O(?)`
+   - Dominant input dimension (n = what, how large in practice)
+
+   If you cannot state current Big-O, you do not yet understand the code. Read more.
+
+2. **Identify the bottleneck, do not guess.** Point to the exact line(s) responsible for the dominant term. Nested loop? Repeated linear scan? Recomputation? Allocation inside a hot loop? The fix lives there, not elsewhere.
+
+3. **One transformation at a time, with a verify-revert-stop loop.** The loop is:
+
+   1. Apply exactly one transformation from the playbook.
+   2. Run the existing test suite (or the characterization test you wrote per the Iron Law).
+   3. If any test breaks: **revert immediately.** Do not patch the test. Do not patch around the failure. Revert.
+   4. Count reverts on this piece of code. If **3 reverts in a row**, STOP optimizing. The bottleneck is wrong, the transformation is wrong, or the code has invariants you have not modeled. Escalate to `invariant-guard` and write the missing contract — do not try a fourth transformation.
+   5. Only after a transformation lands green: pick the next one.
+
+   Stacked changes hide regressions. Patched tests hide regressions louder.
+
+4. **Preserve semantics exactly.** Lower complexity must not change outputs, ordering guarantees, stability, or error behavior. If the optimization requires a semantic change (e.g. unordered output), call it out explicitly and confirm it is acceptable.
+
+5. **No invented numbers.** Never write "10x faster" or "saves 200MB" without measuring. Write `<measured: TBD>` and move on, or actually measure with a representative input.
+
+6. **Always report the measured speedup ratio after a transformation lands.** Once the new code is green, run a representative benchmark (same input, same machine, warm cache) and report `before → after` plus the ratio as `N× faster` (or `N× less memory`). One line, attached to the diff:
+
+   ```text
+   p50:  186 ms → 1.1 ms   (169× faster, n=20,000, 200 samples)
+   ```
+
+   If you cannot measure (e.g. the win is purely asymptotic on inputs you don't have), say so explicitly: `asymptotic only, no measurement — O(n²) → O(n)`. Never silently skip this step. The speedup ratio is the headline number reviewers and downstream readers will quote — make sure it exists and is honest.
+
+## The transformation playbook
+
+The vast majority of real-world Big-O wins come from a small set of moves. Try them in this order:
+
+### Time-complexity reductions
+
+| Smell | Fix | Typical win |
+|---|---|---|
+| `for x in A: if x in B` where B is list/array | Convert B to `Set`/`Map` once | O(n·m) → O(n+m) |
+| Nested loop computing pairs/joins | Hash-join on the key; index by lookup field | O(n·m) → O(n+m) |
+| Repeated `.find` / `.indexOf` / `.includes` inside a loop | Precompute index `Map<key, item>` outside loop | O(n^2) → O(n) |
+| Repeated recomputation of same value | Memoize / cache by input key | O(n·f(n)) → O(n + f(n)) |
+| Sort inside a loop | Sort once outside | O(n^2 log n) → O(n log n) |
+| Linear scan for min/max/median repeatedly | Heap / sorted structure | O(n·k) → O(n log k) |
+| Recursive recomputation (naive Fibonacci shape) | Memoize, or convert to iterative DP | exponential → O(n) |
+| String concatenation in a loop (some langs) | Use builder / `join` / `array.push` then join | O(n^2) → O(n) |
+| Repeated regex compile in loop | Compile once outside | constant-factor, large |
+| Counting / grouping via nested loop | Single pass with `Counter` / `Map<k, count>` | O(n^2) → O(n) |
+| Sliding-window written as nested loop | Two-pointer / windowed sum | O(n^2) → O(n) |
+| Repeated prefix sums | Precompute prefix array, O(1) range queries | O(n·q) → O(n+q) |
+| Pairwise distance / containment checks on intervals | Sort + sweep line | O(n^2) → O(n log n) |
+| Top-K via full sort | Heap of size K | O(n log n) → O(n log k) |
+| Repeated set membership in loop body | `Set` once, reuse | O(n·m) → O(n) |
+| `await` inside a `for` over independent items | `Promise.all` / batched concurrency | wall-clock O(n·latency) → O(latency) |
+| ORM query inside a loop (N+1) | `IN (...)` / `select_related` / bulk fetch | O(n) round-trips → O(1) |
+
+### Space-complexity reductions
+
+| Smell | Fix | Typical win |
+|---|---|---|
+| Materializing whole list/array just to iterate | Generator / iterator / stream | O(n) → O(1) |
+| Building intermediate arrays via chained `.map().filter().map()` on huge data | Single-pass loop or lazy pipeline | k·O(n) → O(n) (often O(1) extra) |
+| Caching every intermediate result of a recursion | Rolling window (keep last k states) | O(n) → O(k) |
+| Storing parents/visited for graph traversal when only count needed | Bitset / counter only | O(n) → O(1) |
+| Copying input to mutate | In-place mutation when caller allows | O(n) → O(1) |
+| Reading entire file before processing | Stream line-by-line / chunked | O(file) → O(chunk) |
+| Deep-clone for safety in a loop | Clone once, or use structural sharing / immutables | O(n·m) → O(n+m) |
+| Holding references that prevent GC (closures, listeners, caches) | Bound the cache (LRU), remove listeners, scope closures tightly | unbounded → bounded |
+| Loading full result set from DB | Cursor / pagination / streaming query | O(rows) → O(page) |
+| `JSON.parse(JSON.stringify(x))` for cloning | `structuredClone` or targeted copy | O(n) work and allocation removed |
+
+### When you cannot lower asymptotic Big-O
+
+Sometimes O(n log n) really is the floor. Then move to constant-factor wins:
+- Replace pointer-chasing structures with contiguous arrays (cache locality).
+- Hoist invariants out of loops.
+- Avoid allocation in the hot loop (reuse buffers).
+- Prefer typed arrays / native containers over boxed objects for numeric work.
+- Batch syscalls / I/O.
+
+State explicitly: "Asymptotic floor is O(n log n); applying constant-factor optimizations only."
+
+## Required workflow
+
+For each piece of code you optimize:
+
+1. **Measure or estimate current Big-O.** Write it down.
+2. **Identify the bottleneck line(s).** Point at them.
+3. **Pick one transformation from the playbook.** Name it.
+4. **Apply it.** One change.
+5. **Verify behavior.** Tests pass, or outputs match on a representative input.
+6. **State new Big-O.** Time and space.
+7. **Repeat if more wins exist and are worth the complexity cost.**
+
+## Canonical example — workflow vs no-workflow
+
+The same optimization with and without the verify-revert-stop loop.
+
+**Bottleneck.** `getOrdersWithUsers()` runs 10s on 10k orders. Cause: `users.find(u => u.id === o.userId)` inside the map → O(n·m).
+
+<Bad>
+
+```ts
+// No workflow: change semantics + the optimization in one go
+export function getOrdersWithUsers(orders, users) {
+  const userById = Object.fromEntries(users.map(u => [u.id, u]));
+  return orders
+    .map(o => ({ ...o, user: userById[o.userId] }))
+    .filter(o => o.user); // silently drops orders whose user was deleted
+}
+```
+
+Faster, *and* changes the result set. Existing tests catch it — but the diff also "fixes" a flaky test by removing the assertion that checked the old behavior. Ships green. Breaks the billing report two weeks later.
+
+</Bad>
+
+<Good>
+
+```ts
+// Workflow applied:
+//   Bottleneck: orders.map → users.find  (line 14)
+//   Current: time = O(n·m), space = O(1)
+//   Target:  time = O(n+m), space = O(m)
+//   Transformation: precompute index Map<userId, User> outside the loop
+//   Semantic risk: None — orders with missing users still emit `user: undefined` exactly as before
+//   Reverts so far: 0
+
+export function getOrdersWithUsers(orders, users) {
+  const userById = new Map(users.map(u => [u.id, u]));
+  return orders.map(o => ({ ...o, user: userById.get(o.userId) }));
+}
+```
+
+One transformation. Existing tests stay untouched. Run them. If green, ship. If red, revert (don't patch). After 3 reverts, stop and load `invariant-guard` — the bottleneck is wrong, or the function has a contract no one wrote down.
+
+</Good>
+
+## Output discipline
+
+When proposing or applying an optimization, your message must contain — in this order:
+
+1. **Bottleneck** — file:line and one-sentence reason.
+2. **Current complexity** — `time = O(?)`, `space = O(?)`.
+3. **Transformation** — name from the playbook (or describe it if novel).
+4. **New complexity** — `time = O(?)`, `space = O(?)`.
+5. **Semantic risk** — anything callers might notice (ordering, stability, error timing). "None" is a valid answer if true.
+6. **Measured speedup** — `before → after` with the ratio as `N× faster` (or `asymptotic only` if not measured). One line, honest numbers.
+7. **The diff.**
+
+If any of 1–6 is missing, the optimization is not ready to apply.
+
+## Stop conditions — do not optimize further when
+
+- Asymptotic Big-O already matches a known lower bound for the problem.
+- The input is provably small and bounded (n < ~100 and not on a hot path).
+- The optimization would obscure correctness or harm readability without a measured win.
+- The bottleneck is I/O or external service latency, not CPU/memory — go fix that instead.
+
+Premature optimization past these points adds risk without payoff.
+
+## Rationalizations to watch for
+
+These are real verbatim thoughts captured from a controlled test where the model produced a correct optimization but skipped the workflow that would document it for reviewers:
+
+| Excuse | Reality |
+| --- | --- |
+| "I already solved this in my head — just paste the diff and add labels after." | Retrofitted labels lie about the reasoning order. Write bottleneck → complexity → transformation → diff in that order, or you are writing fiction. |
+| "Stating the current Big-O is busywork — everyone can see the nested loop." | If everyone can see it, writing one line costs nothing. If only you can see it, you just saved the reviewer's time. |
+| "Semantic risk is None, skip that step." | "None" is a valid answer — but write it. The next reader does not know which guarantees you considered. |
+| "I'll do all three transformations in one diff." | Stacked transformations hide regressions. One transformation, verify, repeat. |
+| "It's just a small refactor, the workflow is overkill." | Then it takes 30 seconds. The cases where you skip the workflow are the ones where you miss the optimization next to the obvious one. |
+| "I'll measure later." | Later is `<measured: TBD>` forever. Either measure now or accept the asymptotic argument as the only claim. |
+
+If any of these sound familiar mid-edit: stop, restart the seven-step output discipline.
+
+## Red flags — STOP
+
+- Optimizing without stating current Big-O.
+- "This should be faster" without identifying a specific bottleneck line.
+- Stacking multiple transformations before verifying any one of them.
+- Claiming a speedup without measuring or without an asymptotic argument.
+- Lowering complexity by silently changing output semantics.
+- Rewriting code that runs once at startup with n = 12.
+
+All of these mean: back up, restate the rules, start the workflow over.
+
+## Verification checklist
+
+Before claiming an optimization is complete:
+
+- [ ] Existing tests (or a written characterization test) were green BEFORE the transformation.
+- [ ] Exactly one transformation was applied.
+- [ ] Tests are green AFTER the transformation.
+- [ ] No test was modified, weakened, or skipped to make it pass.
+- [ ] Current Big-O and target Big-O are stated in the diff or PR description.
+- [ ] Semantic risk is written down ("None" is valid if true).
+- [ ] Measured speedup ratio is reported as `before → after · N× faster` (or explicitly marked `asymptotic only` if no measurement was possible).
+- [ ] If a measured claim was made (e.g. "3x faster"), the measurement command is included.
+- [ ] Revert count on this code is < 3.
+
+Cannot check every box? The optimization is not done. Either revert or finish the gap — do not ship a half-verified speedup.

package/skills/invariant-guard/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: invariant-guard
+description: Use when writing or reviewing algorithms where the obvious implementation is subtly wrong — postcondition stronger than the loop's natural invariant (Boyer–Moore majority, Floyd cycle, leftmost vs any binary search, QuickSelect partition); in-place mutation with read+write pointers (dedup-in-place, partition, rotate); recursion with multiple parameters or accumulator state; off-by-one suspects with duplicates, empty inputs, boundary values; iterative refinements that must terminate (fixed-point, Newton, EM); any function where you catch yourself thinking "I know this algorithm" — the trap is usually in the contract, not the loop body. Forces writing the function contract (especially the postcondition) and loop invariant BEFORE code. Pairs with lemmaly (picks the algorithm) and mathguard (picks the math).
+metadata:
+  priority: 2
+  role: correctness
+  pathPatterns:
+    - '**/*.{js,jsx,ts,tsx,mjs,cjs}'
+    - '**/*.py'
+    - '**/*.go'
+    - '**/*.rs'
+    - '**/*.java'
+    - '**/*.kt'
+    - '**/*.cs'
+    - '**/*.{cpp,cc,cxx,hpp,hh,hxx}'
+    - '**/*.php'
+    - '**/*.rb'
+    - '**/*.{sh,bash}'
+  chainTo:
+    - skill: lemmaly
+      when: 'algorithm choice is unsettled — pick the family first, then prove it'
+    - skill: mathguard
+      when: 'invariants involve ε-bounds (approximate / randomized algorithms)'
+  retrieval:
+    aliases:
+      - loop-invariants
+      - correctness-first
+      - postcondition-first
+    intents:
+      - prove the algorithm is correct
+      - write loop invariants
+      - handle edge cases
+      - off-by-one safety
+---
+
+# invariant-guard — Correctness-First Coding
+
+The model knows what a loop invariant is. It knows recursion needs a base case. It knows about empty lists, integer overflow, and the difference between `<` and `≤`. It just does not write these down before producing code, so it ships subtle correctness bugs that tests do not catch.
+
+invariant-guard fixes the behavior. State the invariants. State the base case. State the termination argument. State the edge cases. Then write the code — and verify that the code maintains what you stated.
+
+**Violating the letter of these rules is violating the spirit of the skill.** "I know this algorithm" is the exact rationalization that ships off-by-one and missing-postcondition bugs.
+
+## The Iron Law
+
+```text
+NO LOOP OR RECURSION WITHOUT A WRITTEN INVARIANT AND TERMINATION ARGUMENT
+```
+
+If you cannot write the invariant in one sentence, you have not designed the loop. Write code anyway and you are coding by guess — and the bug will be in the case you did not enumerate.
+
+## Non-negotiable rules
+
+1. **Every loop gets a one-line invariant.** Before writing any loop, state in one sentence what is true at the top of every iteration. Examples:
+   - "At loop top: `result` contains the sum of `a[0..i)`."
+   - "At loop top: `lo ≤ target_position ≤ hi`."
+   - "At loop top: `seen` contains every element processed so far; `dups` contains every element that appeared at least twice."
+
+   If you cannot write the invariant in one sentence, you have not designed the loop yet.
+
+2. **Every loop gets a one-line termination argument.** Name the quantity that strictly decreases (or strictly increases toward a bound) on every iteration. Examples:
+   - "`hi − lo` strictly decreases each iteration."
+   - "`i` increases by 1 and is bounded above by `n`."
+   - "`stack.length` strictly decreases each pop; nothing pushes inside this branch."
+
+   No termination argument, no loop.
+
+3. **Every recursion gets an explicit base case and a measure.** Before writing a recursive function, state:
+   - The base case(s) — the smallest inputs that return without recursing.
+   - The measure — a non-negative integer that strictly decreases on every recursive call (e.g. `len(xs)`, `hi − lo`, `depth`, `n`).
+   - The combination — how the recursive results combine into the answer.
+
+   No base case + measure, no recursion. (Mutual recursion: state the measure across the cycle.)
+
+4. **List edge cases before writing, not after.** For every function operating on a collection or number, list which of these apply and how they behave:
+   - Empty input (`[]`, `""`, `null`, `undefined`, `None`).
+   - Singleton (`[x]`).
+   - All-equal elements.
+   - Already-sorted / reverse-sorted input.
+   - Duplicates (when uniqueness is assumed).
+   - Negative numbers, zero, exactly the boundary value.
+   - Integer overflow / underflow at the type max/min.
+   - NaN, ±Infinity, `-0`, denormals (for floats).
+   - Off-by-one boundaries: index 0, index n−1, index n, length 0, length 1.
+   - Concurrent modification while iterating.
+
+   The cases that apply must each have a one-phrase expected behavior written down.
+
+5. **Make illegal states unreachable, not just unhandled.** Prefer encoding constraints in types and structure so the wrong state cannot be constructed:
+   - Sum type over boolean flag soup (`Loading | Loaded(data) | Error(msg)` not `{loading, data, error}`).
+   - Newtype for IDs that must not be swapped (`UserId` vs `OrderId`).
+   - Non-empty list type when the function requires at least one element.
+   - Parsed value at the boundary, not validated repeatedly downstream (parse-don't-validate).
+
+   If the language cannot encode it, write the invariant as a comment and assert it at the boundary.
+
+## The pre-write protocol
+
+Before producing non-trivial code that has loops, recursion, or non-trivial state, your message must contain — in this order:
+
+1. **Function contract** — preconditions, postconditions, and what the function returns. One line each.
+2. **Loop invariants** — one per loop. (Rule 1.)
+3. **Termination arguments** — one per loop or recursion. (Rules 2, 3.)
+4. **Base cases and measure** — for recursion. (Rule 3.)
+5. **Edge case table** — bullets, one per applicable case, with expected behavior. (Rule 4.)
+6. **Illegal states made unrepresentable** — name the types or asserts that enforce invariants. (Rule 5.)
+7. **The code.**
+8. **Self-check** — one line per loop confirming the invariant holds at top, body preserves it, and exit implies postcondition.
+
+If any of 1–6 is missing, do not emit code.
+
+## Worked trap — Boyer–Moore majority vote
+
+This is the canonical "the trap is in the contract, not the loop body" case. Every step of the protocol either catches the bug or fails to — observe which.
+
+**Naive baseline (what gets shipped without the skill):**
+
+```typescript
+function findMajority(arr: number[]): number | null {
+  if (arr.length === 0) return null;
+  let candidate = arr[0], count = 0;
+  for (const x of arr) {
+    if (count === 0) candidate = x;
+    if (x === candidate) count++; else count--;
+  }
+  return candidate;   // BUG: returns the candidate even when no majority exists
+}
+```
+
+This implementation fails on `[1,2,3]` (returns `3`, expected `null`) and `[2,2,1,1]` (returns `1`, expected `null`). The voting loop is correct; the postcondition is wrong.
+
+**Why the protocol catches it.** Writing **step 1 (function contract)** forces the postcondition in plain language:
+
+> Returns `x` iff `count(x, arr) > arr.length / 2`; else `null`.
+
+Then writing **step 2 (loop invariant)** forces the invariant of the voting pass:
+
+> If a strict majority element exists in `arr`, it equals `candidate` when the loop exits.
+
+These two statements are not equivalent. The loop invariant guarantees "if a majority exists, it is the candidate" — not "the candidate is a majority." Once you write both down, the gap is visible: you need a second pass to verify, or the postcondition is unmet.
+
+**Correct implementation that survives the protocol:**
+
+```typescript
+function findMajority(arr: number[]): number | null {
+  if (arr.length === 0) return null;
+  // Pass 1: vote.
+  let candidate = arr[0], count = 0;
+  // inv: if a strict majority exists in arr, it equals candidate at every count===0 reset.
+  for (const x of arr) {
+    if (count === 0) candidate = x;
+    if (x === candidate) count++; else count--;
+  }
+  // Pass 2: verify — the voting invariant is strictly weaker than the postcondition.
+  let tally = 0;
+  // inv: tally = count of candidate in arr[0..i).
+  for (const x of arr) if (x === candidate) tally++;
+  return tally * 2 > arr.length ? candidate : null;
+}
+```
+
+**Pattern to generalize.** The same trap appears in:
+
+- **Floyd's cycle detection** — finding the meeting point tells you a cycle exists, *not* where it starts. You need a second walk.
+- **Two-pointer "find any"** vs **"find leftmost"** — the loop invariant for one does not satisfy the postcondition of the other.
+- **QuickSelect partition** — the loop returns a position; the postcondition is that the element at that position is the k-th smallest. Off by one in the partition invariant silently breaks it.
+- **DP with reconstruction** — the table tells you the optimum value; reconstructing the optimum path needs separate invariants on the choice array.
+
+In every case: **write the postcondition first; write the loop invariant second; check that the second implies the first. If not, you are missing a pass, a check, or an auxiliary state.**
+
+## Canonical example — binary search for the leftmost match
+
+Most "I know binary search" implementations are written for "find any match." The trap is the postcondition.
+
+**Problem.** Given a sorted array with duplicates, return the index of the **leftmost** occurrence of `target`, or `-1`.
+
+<Bad>
+
+```ts
+function leftmost(a: number[], target: number): number {
+  let lo = 0, hi = a.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    if (a[mid] === target) return mid;       // ❌ returns ANY occurrence
+    if (a[mid] < target) lo = mid + 1; else hi = mid - 1;
+  }
+  return -1;
+}
+// leftmost([1,2,2,2,3], 2) → may return 2, not 1
+```
+
+The loop invariant ("target lies in a[lo..hi] if anywhere") is satisfied. But the postcondition ("returned index is the *smallest* i with a[i] === target") is strictly stronger. The loop body's early return abandons the search before reaching the leftmost.
+
+</Bad>
+
+<Good>
+
+```ts
+function leftmost(a: number[], target: number): number {
+  // contract:
+  //   pre:  a is sorted ascending
+  //   post: returns smallest i with a[i] === target, or -1 if absent
+  let lo = 0, hi = a.length;                 // half-open [lo, hi)
+  // inv: every index < lo has a[i] < target; every index ≥ hi has a[i] > target OR is past leftmost match
+  // term: hi - lo strictly halves each iteration
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (a[mid] < target) lo = mid + 1; else hi = mid;
+  }
+  // exit: lo === hi, and by invariant lo is the leftmost index where a[lo] >= target
+  return lo < a.length && a[lo] === target ? lo : -1;
+}
+```
+
+</Good>
+
+Same loop shape. The difference is the contract was written first — and the loop body was chosen to maintain an invariant that *implies* the postcondition.
+
+## Common invariant patterns to reach for
+
+| Loop / algorithm shape | Canonical invariant | Termination |
+|---|---|---|
+| Linear scan accumulating | `acc = f(a[0..i))` at top | `i` increases by 1, bounded by `n` |
+| Two-pointer (sorted) | `target (if any) lies in a[lo..hi]` | `hi − lo` strictly decreases |
+| Binary search | `target (if present) ∈ a[lo..hi]` and `a[lo..hi]` non-empty | `hi − lo` strictly halves |
+| Sliding window | window `[l..r)` satisfies the constraint; answer ≥ best so far | `r` advances at least once per outer iter |
+| BFS | every node at distance < d has been popped; queue contains some at distance d | strict node count decrease per pop |
+| DFS / recursion on tree | result for subtree rooted at v = combine(children results) | depth (or remaining nodes) strictly decreases |
+| Divide and conquer | result on `a[lo..hi]` = combine(results on the two halves) | `hi − lo` strictly halves |
+| Greedy with priority queue | extracted item is globally optimal for the remaining problem | heap size strictly decreases per extract |
+| Union-Find op | `find(x)` always returns the canonical root of x's component | tree height bounded by O(log n) (with rank) |
+| In-place partition | `a[0..i)` < pivot; `a[i..j)` ≥ pivot; `a[j..n)` unseen | `n − j` strictly decreases |
+
+## Edge case table — defaults to consider
+
+| Input shape | Cases to check |
+|---|---|
+| Array / list | empty, singleton, all-equal, sorted, reversed, with duplicates |
+| String | empty, single char, all whitespace, unicode (surrogates, combining), bytes vs code points |
+| Integer | 0, 1, −1, MIN, MAX, MAX − 1, near overflow in arithmetic, division by 0 |
+| Float | 0.0, −0.0, NaN, ±Inf, denormal, exact comparison should be ε-based |
+| Map / dict | empty, missing key (default vs error), key collision semantics |
+| Tree / graph | empty, single node, cycle (if undirected), self-loop, multigraph, disconnected |
+| Stream / iterator | empty, infinite, single yield, exception mid-iteration |
+| Time / date | DST transition, leap second/day, timezone offset, epoch boundary |
+| Concurrent | empty contention, single thread, max contention, cancellation mid-op |
+
+## Output discipline
+
+Code you emit must:
+
+- Have one comment per loop stating the invariant (use `// inv:` or `# inv:`).
+- Have one comment per recursion stating the base case and measure.
+- Handle every edge case you listed in step 5, or explicitly delegate ("throws on empty — caller responsibility").
+- Assert preconditions at function entry when the language supports it cheaply.
+- Use types (sum types, newtypes, non-empty, non-null) over runtime checks where the language allows.
+
+## When to escalate or redirect
+
+- The function is performance-critical and you have not picked the algorithm — go back to **lemmaly** first; pick the algorithm, then state its invariants here.
+- The technique is mathematical (probabilistic, FFT, geometry) — load **mathguard**; invariants for approximate algorithms include ε-bounds, not equality.
+- The code is concurrent — invariants must account for interleaving; explicitly state "single-threaded only" if that is the assumption.
+
+## Rationalizations to watch for
+
+These are real verbatim thoughts captured from a controlled test where confidence in a "well-known algorithm" caused the model to ship a Boyer–Moore implementation that was wrong on `[1,2,3]` and `[2,2,1,1]`:
+
+| Excuse | Reality |
+| --- | --- |
+| "I know this algorithm — single pass, done." | Knowing the loop ≠ knowing the contract. The trap usually lives in the postcondition the loop does not enforce. |
+| "I traced it in my head, it works." | Mental tracing skips edge cases. Write the invariant; check it implies the postcondition. |
+| "Edge cases are obvious." | Then write them down in 30 seconds. If they are obvious, the table is cheap. If they are not, the table just saved you. |
+| "Tests will catch it." | Tests catch the examples you thought of. The trap is the example you did not. Postconditions catch all examples. |
+| "The postcondition is implied." | If it were, the natural loop invariant would equal it. When they differ (Boyer–Moore, leftmost search, QuickSelect), you need a second pass, an extra check, or auxiliary state. |
+| "Adding a verification pass feels redundant." | Boyer–Moore voting + verification is still O(n). "Feels redundant" is the rationalization that ships the bug. |
+
+If any of these sound familiar mid-thought: stop, write the contract and the invariant, check that one implies the other.
+
+## Red flags — STOP and write the invariant first
+
+- About to write `while (...)` without having stated what is true on entry.
+- About to write `if (i === n − 1)` or `if (i === n)` — boundary suspicious, restate the invariant.
+- About to recurse without naming the base case in this message.
+- About to write `// TODO: handle empty` — handle it now or change the type so empty is impossible.
+- About to use `==` on floats.
+- About to compare across signed/unsigned or across types where overflow rolls.
+- About to silently swallow an error in the middle of a loop ("just continue").
+- Tests pass but you did not actually state what the function guarantees.
+- "It works on the examples I tried."
+
+All of these mean: stop, restart the eight-step protocol, write the invariant, then write the code.
+
+## Verification checklist
+
+Before claiming the function is correct:
+
+- [ ] Every loop has a one-line `// inv:` comment in code.
+- [ ] Every loop has a termination argument written down (in comment or PR description).
+- [ ] Every recursion names its base case and measure in code.
+- [ ] The function's postcondition is written and is implied by the exit state of the last loop.
+- [ ] Every applicable edge case from the table has a test or an explicit "delegated to caller" note.
+- [ ] At least one test exercises each non-trivial boundary (empty, singleton, max, off-by-one).
+- [ ] Illegal states the function rejects are either unrepresentable in the type, or asserted at entry.
+- [ ] For approximate/randomized algorithms (escalated to mathguard): ε-bounds are part of the postcondition, not equality.
+
+Cannot check every box? The code is example-correct, not behavior-correct. Either fill the gap or downgrade the function's claimed contract.
+
+## The thesis, in one line
+
+> **Tests verify examples. Invariants verify behavior. AI assistants ship example-correct, behavior-wrong code by default. invariant-guard makes them reason about behavior first.**