[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M796TGKXAF9S7XASCZ5Q5VQ1":3,"skill-same:01M796TGKXAF9S7XASCZ5Q5VQ1":63},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":43,"commitSha":44,"skillDirectory":45,"forksCount":14,"repositoryHtmlUrl":46,"repositoryHomepageUrl":6,"ownerHtmlUrl":47,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":48,"install":49,"resources":62},"01M796TGKXAF9S7XASCZ5Q5VQ1","invariant-guard",null,"Correctness-first: forces writing the function contract, loop invariant, termination argument, and edge cases BEFORE code. Catches Boyer-Moore, leftmost binary search, QuickSelect traps.","Elogic360\u002Fsoftware-factory","Elogic360","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F156535519?v=4","01M74NH3F0RB13PWB7JZDE2V80","elogic360","01M74NH3FPC65082MDZVMFHDM3",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002FElogic360\u002Fsoftware-factory\u002Fblob\u002Fmain\u002Fintegrations\u002Fantigravity-skills\u002Fskills\u002Finvariant-guard\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: invariant-guard\ndescription: \"Correctness-first: forces writing the function contract, loop invariant, termination argument, and edge cases BEFORE code. Catches Boyer-Moore, leftmost binary search, QuickSelect traps.\"\nrisk: safe\nsource: community\nsource_repo: morsechimwai\u002Flemmaly\nsource_type: community\ndate_added: \"2026-05-26\"\nauthor: morsechimwai\ntags: [algorithms, correctness, loop-invariants, contracts, edge-cases, verification]\ntools: [claude-code, antigravity, cursor, gemini-cli, codex-cli]\nlicense: \"Apache-2.0\"\nlicense_source: \"https:\u002F\u002Fgithub.com\u002Fmorsechimwai\u002Flemmaly\u002Fblob\u002Fmain\u002FLICENSE\"\n---\n\n# invariant-guard — Correctness-First Coding\n\nThe 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 `\u003C` and `≤`. It just does not write these down before producing code, so it ships subtle correctness bugs that tests do not catch.\n\ninvariant-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.\n\n**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.\n\n## When to Use This Skill\n\nUse **invariant-guard** when writing or reviewing algorithms where the obvious implementation is subtly wrong:\n\n- Postcondition stronger than the loop's natural invariant: Boyer–Moore majority, Floyd's cycle detection, leftmost vs any binary search, QuickSelect partition.\n- In-place mutation with read+write pointers: dedup-in-place, partition, rotate.\n- Recursion with multiple parameters or accumulator state.\n- Off-by-one suspects with duplicates, empty inputs, boundary values.\n- Iterative refinements that must terminate: fixed-point, Newton, EM.\n- Any function where you catch yourself thinking \"I know this algorithm\" — the trap is usually in the contract, not the loop body.\n\nPairs with `lemmaly` (picks the algorithm) and `mathguard` (picks the math). Load `invariant-guard` *after* the algorithm has been chosen and *before* the loop body is written.\n\n## The Iron Law\n\n```text\nNO LOOP OR RECURSION WITHOUT A WRITTEN INVARIANT AND TERMINATION ARGUMENT\n```\n\nIf 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.\n\n## Non-negotiable rules\n\n1. **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:\n   - \"At loop top: `result` contains the sum of `a[0..i)`.\"\n   - \"At loop top: `lo ≤ target_position ≤ hi`.\"\n   - \"At loop top: `seen` contains every element processed so far; `dups` contains every element that appeared at least twice.\"\n\n   If you cannot write the invariant in one sentence, you have not designed the loop yet.\n\n2. **Every loop gets a one-line termination argument.** Name the quantity that strictly decreases (or strictly increases toward a bound) on every iteration. Examples:\n   - \"`hi − lo` strictly decreases each iteration.\"\n   - \"`i` increases by 1 and is bounded above by `n`.\"\n   - \"`stack.length` strictly decreases each pop; nothing pushes inside this branch.\"\n\n   No termination argument, no loop.\n\n3. **Every recursion gets an explicit base case and a measure.** Before writing a recursive function, state:\n   - The base case(s) — the smallest inputs that return without recursing.\n   - The measure — a non-negative integer that strictly decreases on every recursive call (e.g. `len(xs)`, `hi − lo`, `depth`, `n`).\n   - The combination — how the recursive results combine into the answer.\n\n   No base case + measure, no recursion. (Mutual recursion: state the measure across the cycle.)\n\n4. **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:\n   - Empty input (`[]`, `\"\"`, `null`, `undefined`, `None`).\n   - Singleton (`[x]`).\n   - All-equal elements.\n   - Already-sorted \u002F reverse-sorted input.\n   - Duplicates (when uniqueness is assumed).\n   - Negative numbers, zero, exactly the boundary value.\n   - Integer overflow \u002F underflow at the type max\u002Fmin.\n   - NaN, ±Infinity, `-0`, denormals (for floats).\n   - Off-by-one boundaries: index 0, index n−1, index n, length 0, length 1.\n   - Concurrent modification while iterating.\n\n   The cases that apply must each have a one-phrase expected behavior written down.\n\n5. **Make illegal states unreachable, not just unhandled.** Prefer encoding constraints in types and structure so the wrong state cannot be constructed:\n   - Sum type over boolean flag soup (`Loading | Loaded(data) | Error(msg)` not `{loading, data, error}`).\n   - Newtype for IDs that must not be swapped (`UserId` vs `OrderId`).\n   - Non-empty list type when the function requires at least one element.\n   - Parsed value at the boundary, not validated repeatedly downstream (parse-don't-validate).\n\n   If the language cannot encode it, write the invariant as a comment and assert it at the boundary.\n\n## The pre-write protocol\n\nBefore producing non-trivial code that has loops, recursion, or non-trivial state, your message must contain — in this order:\n\n1. **Function contract** — preconditions, postconditions, and what the function returns. One line each.\n2. **Loop invariants** — one per loop. (Rule 1.)\n3. **Termination arguments** — one per loop or recursion. (Rules 2, 3.)\n4. **Base cases and measure** — for recursion. (Rule 3.)\n5. **Edge case table** — bullets, one per applicable case, with expected behavior. (Rule 4.)\n6. **Illegal states made unrepresentable** — name the types or asserts that enforce invariants. (Rule 5.)\n7. **The code.**\n8. **Self-check** — one line per loop confirming the invariant holds at top, body preserves it, and exit implies postcondition.\n\nIf any of 1–6 is missing, do not emit code.\n\n## Worked trap — Boyer–Moore majority vote\n\nThis is the canonical \"the trap is in the contract, not the loop body\" case.\n\n**Naive baseline (what gets shipped without the skill):**\n\n```typescript\nfunction findMajority(arr: number[]): number | null {\n  if (arr.length === 0) return null;\n  let candidate = arr[0], count = 0;\n  for (const x of arr) {\n    if (count === 0) candidate = x;\n    if (x === candidate) count++; else count--;\n  }\n  return candidate;   \u002F\u002F BUG: returns the candidate even when no majority exists\n}\n```\n\nThis 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.\n\n**Why the protocol catches it.** Writing **step 1 (function contract)** forces the postcondition in plain language:\n\n> Returns `x` iff `count(x, arr) > arr.length \u002F 2`; else `null`.\n\nThen writing **step 2 (loop invariant)** forces the invariant of the voting pass:\n\n> If a strict majority element exists in `arr`, it equals `candidate` when the loop exits.\n\nThese 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.\n\n**Correct implementation that survives the protocol:**\n\n```typescript\nfunction findMajority(arr: number[]): number | null {\n  if (arr.length === 0) return null;\n  \u002F\u002F Pass 1: vote.\n  let candidate = arr[0], count = 0;\n  \u002F\u002F inv: if a strict majority exists in arr, it equals candidate at every count===0 reset.\n  for (const x of arr) {\n    if (count === 0) candidate = x;\n    if (x === candidate) count++; else count--;\n  }\n  \u002F\u002F Pass 2: verify — the voting invariant is strictly weaker than the postcondition.\n  let tally = 0;\n  \u002F\u002F inv: tally = count of candidate in arr[0..i).\n  for (const x of arr) if (x === candidate) tally++;\n  return tally * 2 > arr.length ? candidate : null;\n}\n```\n\n**Pattern to generalize.** The same trap appears in:\n\n- **Floyd's cycle detection** — finding the meeting point tells you a cycle exists, *not* where it starts. You need a second walk.\n- **Two-pointer \"find any\"** vs **\"find leftmost\"** — the loop invariant for one does not satisfy the postcondition of the other.\n- **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.\n- **DP with reconstruction** — the table tells you the optimum value; reconstructing the optimum path needs separate invariants on the choice array.\n\nIn 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.**\n\n## Canonical example — binary search for the leftmost match\n\nMost \"I know binary search\" implementations are written for \"find any match.\" The trap is the postcondition.\n\n**Problem.** Given a sorted array with duplicates, return the index of the **leftmost** occurrence of `target`, or `-1`.\n\n### Without the protocol — returns any match\n\n```ts\nfunction leftmost(a: number[], target: number): number {\n  let lo = 0, hi = a.length - 1;\n  while (lo \u003C= hi) {\n    const mid = (lo + hi) >> 1;\n    if (a[mid] === target) return mid;       \u002F\u002F returns ANY occurrence\n    if (a[mid] \u003C target) lo = mid + 1; else hi = mid - 1;\n  }\n  return -1;\n}\n\u002F\u002F leftmost([1,2,2,2,3], 2) → may return 2, not 1\n```\n\nThe 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.\n\n### With the protocol — contract-driven leftmost\n\n```ts\nfunction leftmost(a: number[], target: number): number {\n  \u002F\u002F contract:\n  \u002F\u002F   pre:  a is sorted ascending\n  \u002F\u002F   post: returns smallest i with a[i] === target, or -1 if absent\n  let lo = 0, hi = a.length;                 \u002F\u002F half-open [lo, hi)\n  \u002F\u002F inv: every index \u003C lo has a[i] \u003C target; every index ≥ hi has a[i] > target OR is past leftmost match\n  \u002F\u002F term: hi - lo strictly halves each iteration\n  while (lo \u003C hi) {\n    const mid = (lo + hi) >> 1;\n    if (a[mid] \u003C target) lo = mid + 1; else hi = mid;\n  }\n  \u002F\u002F exit: lo === hi, and by invariant lo is the leftmost index where a[lo] >= target\n  return lo \u003C a.length && a[lo] === target ? lo : -1;\n}\n```\n\nSame loop shape. The difference is the contract was written first — and the loop body was chosen to maintain an invariant that *implies* the postcondition.\n\n## Common invariant patterns to reach for\n\n| Loop \u002F algorithm shape | Canonical invariant | Termination |\n|---|---|---|\n| Linear scan accumulating | `acc = f(a[0..i))` at top | `i` increases by 1, bounded by `n` |\n| Two-pointer (sorted) | `target (if any) lies in a[lo..hi]` | `hi − lo` strictly decreases |\n| Binary search | `target (if present) ∈ a[lo..hi]` and `a[lo..hi]` non-empty | `hi − lo` strictly halves |\n| Sliding window | window `[l..r)` satisfies the constraint; answer ≥ best so far | `r` advances at least once per outer iter |\n| BFS | every node at distance \u003C d has been popped; queue contains some at distance d | strict node count decrease per pop |\n| DFS \u002F recursion on tree | result for subtree rooted at v = combine(children results) | depth (or remaining nodes) strictly decreases |\n| Divide and conquer | result on `a[lo..hi]` = combine(results on the two halves) | `hi − lo` strictly halves |\n| Greedy with priority queue | extracted item is globally optimal for the remaining problem | heap size strictly decreases per extract |\n| Union-Find op | `find(x)` always returns the canonical root of x's component | tree height bounded by O(log n) (with rank) |\n| In-place partition | `a[0..i)` \u003C pivot; `a[i..j)` ≥ pivot; `a[j..n)` unseen | `n − j` strictly decreases |\n\n## Edge case table — defaults to consider\n\n| Input shape | Cases to check |\n|---|---|\n| Array \u002F list | empty, singleton, all-equal, sorted, reversed, with duplicates |\n| String | empty, single char, all whitespace, unicode (surrogates, combining), bytes vs code points |\n| Integer | 0, 1, −1, MIN, MAX, MAX − 1, near overflow in arithmetic, division by 0 |\n| Float | 0.0, −0.0, NaN, ±Inf, denormal, exact comparison should be ε-based |\n| Map \u002F dict | empty, missing key (default vs error), key collision semantics |\n| Tree \u002F graph | empty, single node, cycle (if undirected), self-loop, multigraph, disconnected |\n| Stream \u002F iterator | empty, infinite, single yield, exception mid-iteration |\n| Time \u002F date | DST transition, leap second\u002Fday, timezone offset, epoch boundary |\n| Concurrent | empty contention, single thread, max contention, cancellation mid-op |\n\n## Output discipline\n\nCode you emit must:\n\n- Have one comment per loop stating the invariant (use `\u002F\u002F inv:` or `# inv:`).\n- Have one comment per recursion stating the base case and measure.\n- Handle every edge case you listed in step 5, or explicitly delegate (\"throws on empty — caller responsibility\").\n- Assert preconditions at function entry when the language supports it cheaply.\n- Use types (sum types, newtypes, non-empty, non-null) over runtime checks where the language allows.\n\n## When to escalate or redirect\n\n- 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.\n- The technique is mathematical (probabilistic, FFT, geometry) — load **`mathguard`**; invariants for approximate algorithms include ε-bounds, not equality.\n- The code is concurrent — invariants must account for interleaving; explicitly state \"single-threaded only\" if that is the assumption.\n\n## Rationalizations to watch for\n\n| Excuse | Reality |\n| --- | --- |\n| \"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. |\n| \"I traced it in my head, it works.\" | Mental tracing skips edge cases. Write the invariant; check it implies the postcondition. |\n| \"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. |\n| \"Tests will catch it.\" | Tests catch the examples you thought of. The trap is the example you did not. Postconditions catch all examples. |\n| \"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. |\n| \"Adding a verification pass feels redundant.\" | Boyer–Moore voting + verification is still O(n). \"Feels redundant\" is the rationalization that ships the bug. |\n\n## Red flags — STOP and write the invariant first\n\n- About to write `while (...)` without having stated what is true on entry.\n- About to write `if (i === n − 1)` or `if (i === n)` — boundary suspicious, restate the invariant.\n- About to recurse without naming the base case in this message.\n- About to write `\u002F\u002F TODO: handle empty` — handle it now or change the type so empty is impossible.\n- About to use `==` on floats.\n- About to compare across signed\u002Funsigned or across types where overflow rolls.\n- About to silently swallow an error in the middle of a loop (\"just continue\").\n- Tests pass but you did not actually state what the function guarantees.\n- \"It works on the examples I tried.\"\n\n## Verification checklist\n\nBefore claiming the function is correct:\n\n- [ ] Every loop has a one-line `\u002F\u002F inv:` comment in code.\n- [ ] Every loop has a termination argument written down (in comment or PR description).\n- [ ] Every recursion names its base case and measure in code.\n- [ ] The function's postcondition is written and is implied by the exit state of the last loop.\n- [ ] Every applicable edge case from the table has a test or an explicit \"delegated to caller\" note.\n- [ ] At least one test exercises each non-trivial boundary (empty, singleton, max, off-by-one).\n- [ ] Illegal states the function rejects are either unrepresentable in the type, or asserted at entry.\n- [ ] For approximate\u002Frandomized algorithms (escalated to mathguard): ε-bounds are part of the postcondition, not equality.\n\nCannot check every box? The code is example-correct, not behavior-correct. Either fill the gap or downgrade the function's claimed contract.\n\n## Limitations\n\n- **Not an automated prover.** invariant-guard requires the author to *write* invariants; it does not mechanically check them. Pair with property-based tests for stronger evidence.\n- **Concurrency is out of scope by default.** Stated invariants assume single-threaded execution unless explicitly extended; multi-threaded reasoning needs additional happens-before \u002F linearizability arguments.\n- **Float and overflow edge cases are language-specific.** The edge-case table is a checklist, not a substitute for understanding your language's numeric semantics.\n- **Will slow down trivial code.** For one-liners that obviously cannot fail, the protocol is overhead; reserve it for non-trivial loops, recursion, and in-place mutation.\n- **Documentation is the only enforcement.** If the author skips writing the invariants, this skill cannot detect that — pair with code review or a PR template that asks for the contract.\n\n## The thesis, in one line\n\n> **Tests verify examples. Invariants verify behavior. AI assistants ship example-correct, behavior-wrong code by default. invariant-guard makes them reason about behavior first.**\n\n## Related Skills\n\n- `lemmaly` — algorithm choice must be settled before invariants; load lemmaly first if the algorithm family is unclear.\n- `mathguard` — ε-bounded postconditions for approximate \u002F randomized algorithms.\n- `complexity-cuts` — if 3+ optimization transformations have failed tests, the bug is a missing contract, not a missing optimization — escalate here.\n","# invariant-guard — Correctness-First Coding\n\nThe 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 `\u003C` and `≤`. It just does not write these down before producing code, so it ships subtle correctness bugs that tests do not catch.\n\ninvariant-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.\n\n**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.\n\n## When to Use This Skill\n\nUse **invariant-guard** when writing or reviewing algorithms where the obvious implementation is subtly wrong:\n\n- Postcondition stronger than the loop's natural invariant: Boyer–Moore majority, Floyd's cycle detection, leftmost vs any binary search, QuickSelect partition.\n- In-place mutation with read+write pointers: dedup-in-place, partition, rotate.\n- Recursion with multiple parameters or accumulator state.\n- Off-by-one suspects with duplicates, empty inputs, boundary values.\n- Iterative refinements that must terminate: fixed-point, Newton, EM.\n- Any function where you catch yourself thinking \"I know this algorithm\" — the trap is usually in the contract, not the loop body.\n\nPairs with `lemmaly` (picks the algorithm) and `mathguard` (picks the math). Load `invariant-guard` *after* the algorithm has been chosen and *before* the loop body is written.\n\n## The Iron Law\n\n```text\nNO LOOP OR RECURSION WITHOUT A WRITTEN INVARIANT AND TERMINATION ARGUMENT\n```\n\nIf 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.\n\n## Non-negotiable rules\n\n1. **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:\n   - \"At loop top: `result` contains the sum of `a[0..i)`.\"\n   - \"At loop top: `lo ≤ target_position ≤ hi`.\"\n   - \"At loop top: `seen` contains every element processed so far; `dups` contains every element that appeared at least twice.\"\n\n   If you cannot write the invariant in one sentence, you have not designed the loop yet.\n\n2. **Every loop gets a one-line termination argument.** Name the quantity that strictly decreases (or strictly increases toward a bound) on every iteration. Examples:\n   - \"`hi − lo` strictly decreases each iteration.\"\n   - \"`i` increases by 1 and is bounded above by `n`.\"\n   - \"`stack.length` strictly decreases each pop; nothing pushes inside this branch.\"\n\n   No termination argument, no loop.\n\n3. **Every recursion gets an explicit base case and a measure.** Before writing a recursive function, state:\n   - The base case(s) — the smallest inputs that return without recursing.\n   - The measure — a non-negative integer that strictly decreases on every recursive call (e.g. `len(xs)`, `hi − lo`, `depth`, `n`).\n   - The combination — how the recursive results combine into the answer.\n\n   No base case + measure, no recursion. (Mutual recursion: state the measure across the cycle.)\n\n4. **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:\n   - Empty input (`[]`, `\"\"`, `null`, `undefined`, `None`).\n   - Singleton (`[x]`).\n   - All-equal elements.\n   - Already-sorted \u002F reverse-sorted input.\n   - Duplicates (when uniqueness is assumed).\n   - Negative numbers, zero, exactly the boundary value.\n   - Integer overflow \u002F underflow at the type max\u002Fmin.\n   - NaN, ±Infinity, `-0`, denormals (for floats).\n   - Off-by-one boundaries: index 0, index n−1, index n, length 0, length 1.\n   - Concurrent modification while iterating.\n\n   The cases that apply must each have a one-phrase expected behavior written down.\n\n5. **Make illegal states unreachable, not just unhandled.** Prefer encoding constraints in types and structure so the wrong state cannot be constructed:\n   - Sum type over boolean flag soup (`Loading | Loaded(data) | Error(msg)` not `{loading, data, error}`).\n   - Newtype for IDs that must not be swapped (`UserId` vs `OrderId`).\n   - Non-empty list type when the function requires at least one element.\n   - Parsed value at the boundary, not validated repeatedly downstream (parse-don't-validate).\n\n   If the language cannot encode it, write the invariant as a comment and assert it at the boundary.\n\n## The pre-write protocol\n\nBefore producing non-trivial code that has loops, recursion, or non-trivial state, your message must contain — in this order:\n\n1. **Function contract** — preconditions, postconditions, and what the function returns. One line each.\n2. **Loop invariants** — one per loop. (Rule 1.)\n3. **Termination arguments** — one per loop or recursion. (Rules 2, 3.)\n4. **Base cases and measure** — for recursion. (Rule 3.)\n5. **Edge case table** — bullets, one per applicable case, with expected behavior. (Rule 4.)\n6. **Illegal states made unrepresentable** — name the types or asserts that enforce invariants. (Rule 5.)\n7. **The code.**\n8. **Self-check** — one line per loop confirming the invariant holds at top, body preserves it, and exit implies postcondition.\n\nIf any of 1–6 is missing, do not emit code.\n\n## Worked trap — Boyer–Moore majority vote\n\nThis is the canonical \"the trap is in the contract, not the loop body\" case.\n\n**Naive baseline (what gets shipped without the skill):**\n\n```typescript\nfunction findMajority(arr: number[]): number | null {\n  if (arr.length === 0) return null;\n  let candidate = arr[0], count = 0;\n  for (const x of arr) {\n    if (count === 0) candidate = x;\n    if (x === candidate) count++; else count--;\n  }\n  return candidate;   \u002F\u002F BUG: returns the candidate even when no majority exists\n}\n```\n\nThis 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.\n\n**Why the protocol catches it.** Writing **step 1 (function contract)** forces the postcondition in plain language:\n\n> Returns `x` iff `count(x, arr) > arr.length \u002F 2`; else `null`.\n\nThen writing **step 2 (loop invariant)** forces the invariant of the voting pass:\n\n> If a strict majority element exists in `arr`, it equals `candidate` when the loop exits.\n\nThese 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.\n\n**Correct implementation that survives the protocol:**\n\n```typescript\nfunction findMajority(arr: number[]): number | null {\n  if (arr.length === 0) return null;\n  \u002F\u002F Pass 1: vote.\n  let candidate = arr[0], count = 0;\n  \u002F\u002F inv: if a strict majority exists in arr, it equals candidate at every count===0 reset.\n  for (const x of arr) {\n    if (count === 0) candidate = x;\n    if (x === candidate) count++; else count--;\n  }\n  \u002F\u002F Pass 2: verify — the voting invariant is strictly weaker than the postcondition.\n  let tally = 0;\n  \u002F\u002F inv: tally = count of candidate in arr[0..i).\n  for (const x of arr) if (x === candidate) tally++;\n  return tally * 2 > arr.length ? candidate : null;\n}\n```\n\n**Pattern to generalize.** The same trap appears in:\n\n- **Floyd's cycle detection** — finding the meeting point tells you a cycle exists, *not* where it starts. You need a second walk.\n- **Two-pointer \"find any\"** vs **\"find leftmost\"** — the loop invariant for one does not satisfy the postcondition of the other.\n- **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.\n- **DP with reconstruction** — the table tells you the optimum value; reconstructing the optimum path needs separate invariants on the choice array.\n\nIn 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.**\n\n## Canonical example — binary search for the leftmost match\n\nMost \"I know binary search\" implementations are written for \"find any match.\" The trap is the postcondition.\n\n**Problem.** Given a sorted array with duplicates, return the index of the **leftmost** occurrence of `target`, or `-1`.\n\n### Without the protocol — returns any match\n\n```ts\nfunction leftmost(a: number[], target: number): number {\n  let lo = 0, hi = a.length - 1;\n  while (lo \u003C= hi) {\n    const mid = (lo + hi) >> 1;\n    if (a[mid] === target) return mid;       \u002F\u002F returns ANY occurrence\n    if (a[mid] \u003C target) lo = mid + 1; else hi = mid - 1;\n  }\n  return -1;\n}\n\u002F\u002F leftmost([1,2,2,2,3], 2) → may return 2, not 1\n```\n\nThe 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.\n\n### With the protocol — contract-driven leftmost\n\n```ts\nfunction leftmost(a: number[], target: number): number {\n  \u002F\u002F contract:\n  \u002F\u002F   pre:  a is sorted ascending\n  \u002F\u002F   post: returns smallest i with a[i] === target, or -1 if absent\n  let lo = 0, hi = a.length;                 \u002F\u002F half-open [lo, hi)\n  \u002F\u002F inv: every index \u003C lo has a[i] \u003C target; every index ≥ hi has a[i] > target OR is past leftmost match\n  \u002F\u002F term: hi - lo strictly halves each iteration\n  while (lo \u003C hi) {\n    const mid = (lo + hi) >> 1;\n    if (a[mid] \u003C target) lo = mid + 1; else hi = mid;\n  }\n  \u002F\u002F exit: lo === hi, and by invariant lo is the leftmost index where a[lo] >= target\n  return lo \u003C a.length && a[lo] === target ? lo : -1;\n}\n```\n\nSame loop shape. The difference is the contract was written first — and the loop body was chosen to maintain an invariant that *implies* the postcondition.\n\n## Common invariant patterns to reach for\n\n| Loop \u002F algorithm shape | Canonical invariant | Termination |\n|---|---|---|\n| Linear scan accumulating | `acc = f(a[0..i))` at top | `i` increases by 1, bounded by `n` |\n| Two-pointer (sorted) | `target (if any) lies in a[lo..hi]` | `hi − lo` strictly decreases |\n| Binary search | `target (if present) ∈ a[lo..hi]` and `a[lo..hi]` non-empty | `hi − lo` strictly halves |\n| Sliding window | window `[l..r)` satisfies the constraint; answer ≥ best so far | `r` advances at least once per outer iter |\n| BFS | every node at distance \u003C d has been popped; queue contains some at distance d | strict node count decrease per pop |\n| DFS \u002F recursion on tree | result for subtree rooted at v = combine(children results) | depth (or remaining nodes) strictly decreases |\n| Divide and conquer | result on `a[lo..hi]` = combine(results on the two halves) | `hi − lo` strictly halves |\n| Greedy with priority queue | extracted item is globally optimal for the remaining problem | heap size strictly decreases per extract |\n| Union-Find op | `find(x)` always returns the canonical root of x's component | tree height bounded by O(log n) (with rank) |\n| In-place partition | `a[0..i)` \u003C pivot; `a[i..j)` ≥ pivot; `a[j..n)` unseen | `n − j` strictly decreases |\n\n## Edge case table — defaults to consider\n\n| Input shape | Cases to check |\n|---|---|\n| Array \u002F list | empty, singleton, all-equal, sorted, reversed, with duplicates |\n| String | empty, single char, all whitespace, unicode (surrogates, combining), bytes vs code points |\n| Integer | 0, 1, −1, MIN, MAX, MAX − 1, near overflow in arithmetic, division by 0 |\n| Float | 0.0, −0.0, NaN, ±Inf, denormal, exact comparison should be ε-based |\n| Map \u002F dict | empty, missing key (default vs error), key collision semantics |\n| Tree \u002F graph | empty, single node, cycle (if undirected), self-loop, multigraph, disconnected |\n| Stream \u002F iterator | empty, infinite, single yield, exception mid-iteration |\n| Time \u002F date | DST transition, leap second\u002Fday, timezone offset, epoch boundary |\n| Concurrent | empty contention, single thread, max contention, cancellation mid-op |\n\n## Output discipline\n\nCode you emit must:\n\n- Have one comment per loop stating the invariant (use `\u002F\u002F inv:` or `# inv:`).\n- Have one comment per recursion stating the base case and measure.\n- Handle every edge case you listed in step 5, or explicitly delegate (\"throws on empty — caller responsibility\").\n- Assert preconditions at function entry when the language supports it cheaply.\n- Use types (sum types, newtypes, non-empty, non-null) over runtime checks where the language allows.\n\n## When to escalate or redirect\n\n- 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.\n- The technique is mathematical (probabilistic, FFT, geometry) — load **`mathguard`**; invariants for approximate algorithms include ε-bounds, not equality.\n- The code is concurrent — invariants must account for interleaving; explicitly state \"single-threaded only\" if that is the assumption.\n\n## Rationalizations to watch for\n\n| Excuse | Reality |\n| --- | --- |\n| \"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. |\n| \"I traced it in my head, it works.\" | Mental tracing skips edge cases. Write the invariant; check it implies the postcondition. |\n| \"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. |\n| \"Tests will catch it.\" | Tests catch the examples you thought of. The trap is the example you did not. Postconditions catch all examples. |\n| \"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. |\n| \"Adding a verification pass feels redundant.\" | Boyer–Moore voting + verification is still O(n). \"Feels redundant\" is the rationalization that ships the bug. |\n\n## Red flags — STOP and write the invariant first\n\n- About to write `while (...)` without having stated what is true on entry.\n- About to write `if (i === n − 1)` or `if (i === n)` — boundary suspicious, restate the invariant.\n- About to recurse without naming the base case in this message.\n- About to write `\u002F\u002F TODO: handle empty` — handle it now or change the type so empty is impossible.\n- About to use `==` on floats.\n- About to compare across signed\u002Funsigned or across types where overflow rolls.\n- About to silently swallow an error in the middle of a loop (\"just continue\").\n- Tests pass but you did not actually state what the function guarantees.\n- \"It works on the examples I tried.\"\n\n## Verification checklist\n\nBefore claiming the function is correct:\n\n- [ ] Every loop has a one-line `\u002F\u002F inv:` comment in code.\n- [ ] Every loop has a termination argument written down (in comment or PR description).\n- [ ] Every recursion names its base case and measure in code.\n- [ ] The function's postcondition is written and is implied by the exit state of the last loop.\n- [ ] Every applicable edge case from the table has a test or an explicit \"delegated to caller\" note.\n- [ ] At least one test exercises each non-trivial boundary (empty, singleton, max, off-by-one).\n- [ ] Illegal states the function rejects are either unrepresentable in the type, or asserted at entry.\n- [ ] For approximate\u002Frandomized algorithms (escalated to mathguard): ε-bounds are part of the postcondition, not equality.\n\nCannot check every box? The code is example-correct, not behavior-correct. Either fill the gap or downgrade the function's claimed contract.\n\n## Limitations\n\n- **Not an automated prover.** invariant-guard requires the author to *write* invariants; it does not mechanically check them. Pair with property-based tests for stronger evidence.\n- **Concurrency is out of scope by default.** Stated invariants assume single-threaded execution unless explicitly extended; multi-threaded reasoning needs additional happens-before \u002F linearizability arguments.\n- **Float and overflow edge cases are language-specific.** The edge-case table is a checklist, not a substitute for understanding your language's numeric semantics.\n- **Will slow down trivial code.** For one-liners that obviously cannot fail, the protocol is overhead; reserve it for non-trivial loops, recursion, and in-place mutation.\n- **Documentation is the only enforcement.** If the author skips writing the invariants, this skill cannot detect that — pair with code review or a PR template that asks for the contract.\n\n## The thesis, in one line\n\n> **Tests verify examples. Invariants verify behavior. AI assistants ship example-correct, behavior-wrong code by default. invariant-guard makes them reason about behavior first.**\n\n## Related Skills\n\n- `lemmaly` — algorithm choice must be settled before invariants; load lemmaly first if the algorithm family is unclear.\n- `mathguard` — ε-bounded postconditions for approximate \u002F randomized algorithms.\n- `complexity-cuts` — if 3+ optimization transformations have failed tests, the bug is a missing contract, not a missing optimization — escalate here.\n",{"name":5,"risk":24,"tags":25,"tools":32,"author":38,"source":39,"license":15,"date_added":40,"description":7,"source_repo":41,"source_type":39,"license_source":42},"safe",[26,27,28,29,30,31],"algorithms","correctness","loop-invariants","contracts","edge-cases","verification",[33,34,35,36,37],"claude-code","antigravity","cursor","gemini-cli","codex-cli","morsechimwai","community","2026-05-26","morsechimwai\u002Flemmaly","https:\u002F\u002Fgithub.com\u002Fmorsechimwai\u002Flemmaly\u002Fblob\u002Fmain\u002FLICENSE","main","c475fc64e94e803b50d14a791dfee8853fbb2c5c","integrations\u002Fantigravity-skills\u002Fskills\u002Finvariant-guard","https:\u002F\u002Fgithub.com\u002FElogic360\u002Fsoftware-factory","https:\u002F\u002Fgithub.com\u002FElogic360","2026-11-08 22:21:22",{"source":8,"skillName":5,"commands":50,"prompt":60,"zipAvailable":61},[51,54,57],{"tool":52,"command":53},"npx","npx skills add Elogic360\u002Fsoftware-factory --skill invariant-guard",{"tool":55,"command":56},"bunx","bunx skills add Elogic360\u002Fsoftware-factory --skill invariant-guard",{"tool":58,"command":59},"pnpm","pnpm dlx skills add Elogic360\u002Fsoftware-factory --skill invariant-guard","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FElogic360\u002Fsoftware-factory\u002Fblob\u002Fmain\u002Fintegrations\u002Fantigravity-skills\u002Fskills\u002Finvariant-guard\u002FSKILL.md",true,[],[64,71,78,85,92,99],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M79G206MT3J6S0GY3C45P2KV","vss-summarize-video","Use to summarize a recorded video via the LVS summarization microservice (HITL-gated) with a VLM fallback. Not for report generation or live RTSP captioning.","https:\u002F\u002Fgithub.com\u002FElogic360\u002Fsoftware-factory\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-summarize-video\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M79G1WN63PGRE8CKD47WEBQ5","vss-setup-video-analytics-api","Use to deploy the vss-video-analytics-api REST service standalone (config-source, data-log bind, Elasticsearch, optional Kafka). Not for full warehouse deploy.","https:\u002F\u002Fgithub.com\u002FElogic360\u002Fsoftware-factory\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-setup-video-analytics-api\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M79G1S9F7VY3EF6H53PRP5AN","vss-setup-behavior-analytics","Use to deploy the vss-behavior-analytics service standalone (entrypoint, config-source, optional calibration). Not for the full warehouse deploy.","https:\u002F\u002Fgithub.com\u002FElogic360\u002Fsoftware-factory\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-setup-behavior-analytics\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M79G1N1S1Y27PFZPYMNK1MTQ","vss-search-archive","Use this skill to run top-level VSS fusion search on archived video, or to ingest video files \u002F RTSP streams for search. Do NOT use for ad-hoc visual Q&A (use vss-ask-video), live captioning (use vss-deploy-dense-captioning), or video summarization and reports (use vss-summarize-video).","https:\u002F\u002Fgithub.com\u002FElogic360\u002Fsoftware-factory\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-search-archive\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M79G1H6WN0Q6C0VCAXCZX6B7","vss-query-analytics","Use this skill when reading video-analytics metrics, incidents, alerts, and sensor data via the VA-MCP server (port 9901). Not for live VLM or incident-range narrative reports.","https:\u002F\u002Fgithub.com\u002FElogic360\u002Fsoftware-factory\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-query-analytics\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":19},"01M79G1DYPNXQS7QHZ0AAF5FX5","vss-manage-video-io-storage","Use to call the VIOS REST API (sensor list, timelines, clip extraction, snapshots, add\u002Fdelete sensors and streams). Not for VLM inference or search.","https:\u002F\u002Fgithub.com\u002FElogic360\u002Fsoftware-factory\u002Fblob\u002Fmain\u002Fskills\u002Fnvidia\u002Fvss-manage-video-io-storage\u002FSKILL.md",[],[]]