pi-rnd 0.2.1

package/skills/fp-practices/koka.md

@@ -0,0 +1,120 @@
+# Koka — FP Patterns
+
+Koka-specific patterns. Leverages algebraic effects, Perceus reference counting, and FBIP-aware functional style.
+
+## 1. Algebraic Effects as Composition Primitives
+
+Declare effects explicitly; compose operations through effect types rather than hidden state.
+
+**Do:**
+```koka
+effect log
+  fun emit(msg: string): ()
+
+effect storage
+  fun get(key: string): maybe<string>
+  fun put(key: string, value: string): ()
+
+fun process(key: string): <log,storage> string
+  emit("processing " ++ key)
+  match get(key)
+    Just(v) -> v
+    Nothing -> { put(key, "default"); "default" }
+```
+
+**Don't:** use mutable globals or hidden IO to thread context — `<log,storage>` makes dependencies explicit and composable.
+
+## 2. Effect Handlers as Dependency Injection
+
+Swap implementations by swapping handlers — no interface objects needed.
+
+**Do:**
+```koka
+fun with-mock-storage(action: () -> <storage|e> a): e a
+  var store := []
+  with handler
+    fun get(k) = store.lookup(k)
+    fun put(k, v) = store := store ++ [(k, v)]
+  action()
+
+fun with-file-storage(path: string, action: () -> <storage|e> a): <io|e> a
+  with handler
+    fun get(k) = file-read(path ++ "/" ++ k).ok
+    fun put(k, v) = file-write(path ++ "/" ++ k, v)
+  action()
+```
+
+**Don't:** pass `StorageImpl` objects as arguments and match on variants — handlers achieve the same substitution with less boilerplate.
+
+## 3. Value Types and Immutability (Perceus)
+
+Prefer values over references; Perceus makes in-place mutation safe for uniquely owned values.
+
+**Do:**
+```koka
+struct config
+  host: string
+  port: int
+  timeout: int
+
+fun with-timeout(c: config, t: int): config
+  Config(c.host, c.port, t)   // Perceus reuses storage when c is unique
+```
+
+**Don't:** thread `ref<config>` through the call stack — use `ref` only when mutation is the explicit intent.
+
+## 4. FBIP-Aware Functional Style
+
+Recursive algorithms over unique structures reuse memory automatically (Functional But In-Place).
+
+**Do:**
+```koka
+fun map-list(xs: list<a>, f: a -> e b): e list<b>
+  match xs
+    Nil        -> Nil
+    Cons(h, t) -> Cons(f(h), map-list(t, f))
+// Perceus reuses the Cons cell when xs is unique — zero allocation.
+```
+
+**Don't:** introduce an explicit accumulator when the input is consumed — let the compiler exploit uniqueness for zero-copy reuse.
+
+## 5. Higher-Order Functions with Effect Types
+
+Effect polymorphism lets HOFs compose without wrapping or lifting.
+
+**Do:**
+```koka
+fun filter(xs: list<a>, pred: a -> <e> bool): <e> list<a>
+  match xs
+    Nil        -> Nil
+    Cons(h, t) ->
+      val rest = filter(t, pred)
+      if pred(h) then Cons(h, rest) else rest
+
+fun pipeline(items: list<string>): <log,storage> list<string>
+  items.filter(fn(s) { emit(s); s.length > 3 })
+```
+
+**Don't:** monomorphise HOF signatures to `io` when the actual effects are narrower — use effect variables so callers compose freely.
+
+## 6. Effect-Based Command-Query Separation
+
+Separate queries (pure or read-only effects) from commands (write effects).
+
+**Do:**
+```koka
+// Query: read-only effect
+fun current-user(): <auth> user
+  auth/whoami()
+
+// Command: write effects
+fun grant-role(u: user, role: string): <storage,log> ()
+  storage/put("roles/" ++ u.name, role)
+  log/emit("granted " ++ role ++ " to " ++ u.name)
+
+// Composition keeps concerns separate
+fun promote(name: string): <auth,storage,log> ()
+  grant-role(current-user(), "admin")
+```
+
+**Don't:** mix read and write operations in one function — keep them separate so queries are usable in pure contexts.

package/skills/fp-practices/lean.md

@@ -0,0 +1,120 @@
+# Lean 4 — FP Patterns
+
+## 1. Dependent Types for Data Integrity
+
+Encode invariants in types so violations are compile-time errors, not runtime panics.
+
+**Do:**
+```lean
+def NonEmpty (α : Type) := { xs : List α // xs ≠ [] }
+
+def head (xs : NonEmpty α) : α :=
+  match xs.val, xs.property with
+  | x :: _, _ => x
+  | [], h     => absurd rfl h
+
+def BoundedNat (n : Nat) := { k : Nat // k < n }
+```
+
+**Don't:** use bare `List` and add runtime `if xs.isEmpty then panic!` — the type carries no proof, so callers can't trust safety without reading the implementation.
+
+## 2. Structure / Inductive Types as Immutable Data
+
+Prefer `structure` for product types, `inductive` for sum types. Both are immutable; update via `{ s with field := v }`.
+
+**Do:**
+```lean
+structure Point where
+  x : Float
+  y : Float
+  deriving Repr
+
+def translate (p : Point) (dx dy : Float) : Point :=
+  { p with x := p.x + dx, y := p.y + dy }
+
+inductive Shape
+  | circle  (center : Point) (r : Float)
+  | rect    (topLeft : Point) (w h : Float)
+```
+
+**Don't:** define a class with mutable fields (`var`) for pure data — record update syntax is enough, and mutable classes break referential transparency.
+
+## 3. Pure Functions and `where` Clauses
+
+Keep top-level definitions pure; factor helper logic into `where` clauses to avoid polluting the module namespace.
+
+**Do:**
+```lean
+def normalise (xs : List Float) : List Float :=
+  if total == 0.0 then xs else xs.map (· / total)
+  where total := xs.foldl (· + ·) 0.0
+```
+
+**Don't:** split a pure transformation into multiple top-level `def`s only meaningful together — `where` keeps helpers co-located and signals they are not public API.
+
+## 4. Do Notation for Monadic Composition
+
+Use `do`/`let`/`←` to sequence monadic steps without nesting. Reserve `IO` for actual I/O; keep business logic pure.
+
+**Do:**
+```lean
+def readAndDouble (path : String) : IO Nat := do
+  let contents ← IO.FS.readFile path
+  let n := contents.trim.toNat!
+  pure (n * 2)
+
+def pureDouble (n : Nat) : Nat := n * 2   -- pure, unit-testable
+```
+
+**Don't:** nest `>>=` manually for multi-step IO — do-notation is idiomatic Lean 4. Don't put pure computations inside `IO` unless they genuinely perform I/O.
+
+## 5. Pattern Matching Over Conditionals
+
+Use exhaustive `match` instead of chains of `if/else`. The compiler enforces totality; missing cases become errors.
+
+**Do:**
+```lean
+inductive Color | red | green | blue deriving BEq
+
+def complementOf : Color → Color
+  | .red   => .cyan
+  | .green => .magenta
+  | .blue  => .yellow
+
+def describe : Option String → String
+  | some s => s!"Value: {s}"
+  | none   => "Empty"
+```
+
+**Don't:** write `if c == .red then ... else if c == .green then ...` — exhaustiveness is not checked; new constructors silently fall to the `else` branch.
+
+## 6. IO Boundary Separation
+
+Pure computation belongs outside `IO`. Pass values in, return values out; side effects live at the boundary.
+
+**Do:**
+```lean
+-- Pure: compose, test in isolation
+def buildReport (entries : List String) : String :=
+  entries.map (s!"- {·}") |>.intercalate "\n"
+
+-- Effectful: only the narrow boundary touches IO
+def writeReport (path : String) (entries : List String) : IO Unit := do
+  IO.FS.writeFile path (buildReport entries)
+```
+
+**Don't:** mix `IO.println` calls with business logic — it couples computation to output, making the function impossible to unit-test without capturing stdout.
+
+## 7. Tactic Composition
+
+Lean 4 proofs are programs. Compose tactics in `by` blocks; use `<;>` to broadcast a tactic to all remaining goals.
+
+**Do:**
+```lean
+theorem add_comm_zero (n : Nat) : n + 0 = n := by
+  induction n with
+  | zero      => rfl
+  | succ n ih => simp [Nat.succ_add, ih]
+```
+
+**Don't:** use `sorry` as a permanent placeholder — it makes theorems unsound and lets downstream proofs compile while being logically broken.

package/skills/fp-practices/postgresql.md

@@ -0,0 +1,120 @@
+# PostgreSQL — FP Patterns
+
+## 1. CTEs as Named Pipeline Stages
+
+Express multi-step transformations as a chain of named CTEs instead of nested subqueries.
+
+**Do:**
+```sql
+WITH
+  active_orders AS (
+    SELECT id, customer_id, total FROM orders WHERE status = 'active'
+  ),
+  with_discounts AS (
+    SELECT ao.id, ao.customer_id,
+           ao.total * (1 - COALESCE(d.pct, 0)) AS discounted_total
+    FROM active_orders ao LEFT JOIN discounts d USING (customer_id)
+  ),
+  aggregated AS (
+    SELECT customer_id, SUM(discounted_total) AS revenue
+    FROM with_discounts GROUP BY customer_id
+  )
+SELECT * FROM aggregated ORDER BY revenue DESC;
+```
+
+**Don't:** nest subqueries three levels deep — each level hides its stage name and makes independent testing impossible.
+
+## 2. Set-Based Operations Over Row-by-Row Cursors
+
+Operate on entire result sets; avoid `FETCH`/`LOOP` cursors.
+
+**Do:**
+```sql
+UPDATE orders
+SET    status = 'fulfilled'
+FROM   shipments
+WHERE  orders.id = shipments.order_id
+  AND  shipments.delivered_at IS NOT NULL;
+```
+
+**Don't:**
+```sql
+FOR rec IN SELECT * FROM orders LOOP          -- one row at a time
+  IF EXISTS (SELECT 1 FROM shipments WHERE order_id = rec.id ...) THEN
+    UPDATE orders SET status = 'fulfilled' WHERE id = rec.id;
+  END IF;
+END LOOP;
+```
+
+## 3. IMMUTABLE / STABLE / VOLATILE Annotations
+
+Declare the correct volatility so the planner can cache and inline results.
+
+**Do:**
+```sql
+-- Pure math → IMMUTABLE: no DB access, same inputs always give same output
+CREATE FUNCTION tax_rate(region TEXT) RETURNS NUMERIC
+  LANGUAGE sql IMMUTABLE PARALLEL SAFE
+  RETURN CASE region WHEN 'EU' THEN 0.20 ELSE 0.10 END;
+
+-- Reads rows, stable within a statement → STABLE
+CREATE FUNCTION user_email(uid UUID) RETURNS TEXT
+  LANGUAGE sql STABLE
+  RETURN (SELECT email FROM users WHERE id = uid);
+```
+
+**Don't:** leave functions as `VOLATILE` (the default) when they only read data — the planner re-executes them per row instead of caching.
+
+## 4. Window Functions as Pure Transformations
+
+Compute derived columns without subqueries or self-joins.
+
+**Do:**
+```sql
+SELECT order_id, customer_id, amount,
+  SUM(amount)  OVER w                      AS customer_total,
+  RANK()       OVER (w ORDER BY amount DESC) AS rank_by_value,
+  amount / NULLIF(SUM(amount) OVER w, 0)   AS share
+FROM orders
+WINDOW w AS (PARTITION BY customer_id);
+```
+
+**Don't:** use correlated subqueries for running totals or ranks — they execute once per row and cannot compose without re-scanning.
+
+## 5. Pure SQL Functions
+
+Write functions as SQL expressions, not procedural routines, when no control flow is needed.
+
+**Do:**
+```sql
+CREATE FUNCTION full_name(first TEXT, last TEXT) RETURNS TEXT
+  LANGUAGE sql IMMUTABLE PARALLEL SAFE
+  RETURN trim(first || ' ' || last);
+
+CREATE FUNCTION fiscal_quarter(d DATE) RETURNS INT
+  LANGUAGE sql IMMUTABLE PARALLEL SAFE
+  RETURN EXTRACT(QUARTER FROM d)::INT;
+```
+
+**Don't:** wrap simple expressions in `PL/pgSQL` `BEGIN … END` — the planner cannot inline procedural bodies, losing IMMUTABLE caching.
+
+## 6. Command-Query Separation
+
+Read-only queries use SQL functions; mutations use procedures or explicit DML.
+
+**Do:**
+```sql
+-- Query: pure SELECT, no side-effects
+CREATE FUNCTION orders_for_customer(cid UUID)
+  RETURNS SETOF orders LANGUAGE sql STABLE
+  RETURN SELECT * FROM orders WHERE customer_id = cid;
+
+-- Command: procedure that mutates, returns nothing
+CREATE PROCEDURE cancel_order(oid UUID) LANGUAGE sql
+  BEGIN ATOMIC
+    UPDATE orders SET status = 'cancelled', updated_at = now()
+    WHERE id = oid;
+  END;
+```
+
+**Don't:** return rows AND mutate in the same function — such functions cannot be called inside read-only transactions (`SET TRANSACTION READ ONLY`).

package/skills/fp-practices/python.md

@@ -0,0 +1,120 @@
+# Python — FP Patterns
+
+Python-specific patterns for the five FP rules in SKILL.md. Idiomatic Python — not Haskell translated to Python.
+
+## 1. Generators Over Eager Lists
+
+Prefer generators and `itertools` for transformations. They compose without materializing intermediate collections.
+
+**Do:**
+```python
+from itertools import islice
+
+def active_names(users): return (u.name for u in users if u.active)
+def first_ten_active(users): return list(islice(active_names(users), 10))
+```
+
+**Don't:** build an intermediate list just to take a prefix — `[u.name for u in users][:10]` allocates the full result when you only need 10.
+
+## 2. Comprehensions as Transformations
+
+Use list/dict/set comprehensions as data transformation expressions, not as substitutes for imperative loops with side effects.
+
+**Do:**
+```python
+counts = {word: text.count(word) for word in vocabulary}
+evens  = [x for x in numbers if x % 2 == 0]
+unique = {x.lower() for x in tags}
+```
+
+**Don't:**
+```python
+# comprehension with side effects — this is a loop in disguise
+[print(x) for x in items]       # Don't: use a for loop instead
+[results.append(f(x)) for x in items]  # Don't: just write the for loop
+```
+
+## 3. functools — Partial Application and Caching
+
+Use `functools.partial` to specialize functions, `reduce` for folds, and `lru_cache` to memoize pure functions.
+
+**Do:**
+```python
+from functools import partial, reduce, lru_cache
+
+add_tax = partial(round, ndigits=2)
+total   = reduce(lambda acc, x: acc + x.price, cart, 0.0)
+@lru_cache(maxsize=256)
+def fib(n: int) -> int:
+    return n if n < 2 else fib(n - 1) + fib(n - 2)
+```
+
+**Don't:** write a custom `Memoize` class or `_cache` dict when `lru_cache` handles it. Don't use `reduce` for simple sums — `sum()` is clearer.
+
+## 4. Frozen Dataclasses as Values
+
+Use `@dataclass(frozen=True)` for value objects. Frozen instances are hashable, safe to use as dict keys, and cannot be mutated after construction.
+
+**Do:**
+```python
+from dataclasses import dataclass, replace
+
+@dataclass(frozen=True)
+class Point:
+    x: float
+    y: float
+
+origin  = Point(0.0, 0.0)
+shifted = replace(origin, x=1.0)   # new Point; origin unchanged
+```
+
+**Don't:** use `@dataclass` (mutable) for domain values that should be immutable — mutation bugs surface late and are hard to trace.
+
+## 5. NamedTuple for Lightweight Records
+
+Use `typing.NamedTuple` for simple immutable records. Cheaper than `@dataclass(frozen=True)` and supports tuple unpacking.
+
+**Do:**
+```python
+from typing import NamedTuple
+
+class Rect(NamedTuple):
+    width: float
+    height: float
+    def area(self) -> float:
+        return self.width * self.height
+
+w, h = Rect(3.0, 4.0)   # tuple unpacking works
+```
+
+**Don't:** use plain `tuple` with positional indices — `rect[0] * rect[1]` breaks silently when the layout changes.
+
+## 6. Type Hints for Immutability Intent
+
+Use `Sequence`, `Mapping`, and `frozenset` in signatures to signal read-only intent. Use `Final` for module-level constants.
+
+**Do:**
+```python
+from typing import Final, Sequence, Mapping
+
+MAX_RETRIES: Final = 3
+def summarize(items: Sequence[str]) -> Mapping[str, int]:
+    return {item: len(item) for item in items}
+```
+
+**Don't:** annotate parameters as `list` or `dict` when the function only reads them — `Sequence`/`Mapping` signals the contract and prevents accidental mutation.
+
+## 7. Command-Query Separation
+
+A function either returns a value (query) or causes a side effect (command) — not both.
+
+**Do:**
+```python
+def load_config(path: str) -> dict:              # query — pure read
+    with open(path) as f: return json.load(f)
+
+def save_config(path: str, cfg: dict) -> None:   # command — write only
+    with open(path, "w") as f: json.dump(cfg, f)
+```
+
+**Don't:** write a function that both persists data and returns it — the caller cannot use the output without triggering the side effect.

package/skills/fp-practices/svelte.md

@@ -0,0 +1,114 @@
+# Svelte 5 — FP Patterns
+
+Svelte 5-specific patterns for pure component logic using runes. Assumes Svelte 5 with runes mode.
+
+## 1. $derived as Pure Computation
+
+`$derived` is the runes equivalent of a pure function applied to reactive inputs. Never put side effects inside `$derived`.
+
+**Do:**
+```svelte
+<script>
+  let { items } = $props();
+  const total = $derived(items.reduce((sum, item) => sum + item.price, 0));
+  const discounted = $derived(total > 100 ? total * 0.9 : total);
+</script>
+```
+
+**Don't:** put mutations or async calls inside `$derived` — use `$effect` for side effects and keep `$derived` to pure transformations only.
+
+## 2. Pure Helper Functions for Component Logic
+
+Extract multi-step transformations into plain functions outside the `<script>` block. Pure functions are testable without mounting a component.
+
+**Do:**
+```svelte
+<script>
+  function filterActive(items) {
+    return items.filter(i => i.active);
+  }
+
+  function sortByName(items) {
+    return [...items].sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  let { items } = $props();
+  const visible = $derived(sortByName(filterActive(items)));
+</script>
+```
+
+**Don't:** inline multi-step logic directly in `$derived` expressions — extract named functions so each transformation is separately testable.
+
+## 3. Immutable State Patterns with $state
+
+Treat `$state` values as immutable: replace the whole value rather than mutating in place. Mutation bypasses Svelte's reactivity for nested objects.
+
+**Do:**
+```svelte
+<script>
+  let todos = $state([]);
+
+  function addTodo(text) {
+    todos = [...todos, { id: crypto.randomUUID(), text, done: false }];
+  }
+
+  function toggleTodo(id) {
+    todos = todos.map(t => t.id === id ? { ...t, done: !t.done } : t);
+  }
+</script>
+```
+
+**Don't:** call `.push()`, `.splice()`, or assign to `array[index]` directly — mutations bypass Svelte's reactivity tracking for object and array values.
+
+## 4. Reactive Pipelines via $derived Chains
+
+Compose a sequence of transformations as a chain of `$derived` values, each named for the stage it represents.
+
+**Do:**
+```svelte
+<script>
+  let { orders } = $props();
+  const pending     = $derived(orders.filter(o => o.status === 'pending'));
+  const sorted      = $derived([...pending].sort((a, b) => a.createdAt - b.createdAt));
+  const displayRows = $derived(sorted.map(o => ({ ...o, label: `#${o.id}` })));
+</script>
+```
+
+**Don't:** merge all transformation steps into a single large `$derived` expression — named stages make the data flow readable and each stage independently inspectable.
+
+## 5. Snippet Composition
+
+Use snippets (`{#snippet}`) as composable, pure rendering units. Pass data in; emit markup out. Treat snippets like pure functions from data to markup.
+
+**Do:**
+```svelte
+{#snippet badge(label, variant)}
+  <span class="badge badge--{variant}">{label}</span>
+{/snippet}
+
+{#each items as item}
+  {@render badge(item.status, item.urgent ? 'danger' : 'info')}
+{/each}
+```
+
+**Don't:** write duplicated inline markup for the same visual pattern — extract it into a named snippet and `@render` it with arguments.
+
+## 6. Command-Query Separation in Event Handlers
+
+Event handlers are commands (they cause mutations). `$derived` values are queries (they compute from state). Never compute derived data inside an event handler.
+
+**Do:**
+```svelte
+<script>
+  let items = $state([]);
+  const count    = $derived(items.length);           // query
+  const hasItems = $derived(items.length > 0);       // query
+
+  function removeItem(id) {                          // command
+    items = items.filter(i => i.id !== id);
+  }
+</script>
+```
+
+**Don't:** compute derived values (counts, labels, totals) inside event handlers — those computations belong in `$derived` so they stay in sync automatically.
+

package/skills/kiss-practices/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: kiss-practices
+description: Language-specific KISS (Keep It Simple) rules to prevent over-engineering. Load during Phase 0 discovery — detect project languages and read only the relevant files from the skill directory.
+effort: low
+---
+
+# KISS Practices
+
+## General Rules (always apply)
+
+- Don't add features nobody asked for
+- Don't add error handling for scenarios that can't happen — trust internal code and framework guarantees
+- Don't create abstractions for one-time operations — three similar lines is better than a premature helper
+- Don't design for hypothetical future requirements — solve today's problem
+- Don't add backwards-compatibility shims — just change the code
+- Don't wrap framework calls in service layers unless there's real business logic to encapsulate
+- Simple, readable code beats clever, compact code
+- Validate at system boundaries (user input, external APIs), not at every internal function
+
+## How to Use
+
+**During Phase 0 (Discovery):**
+1. Detect which languages/frameworks are present in the project (by file extensions, config files, or dependencies)
+2. Read only the relevant language files from the `kiss-practices` skill directory (skill is auto-injected via PI's skill discovery — sibling `.md` files are in the same directory as this file)
+3. Include the language-specific KISS rules in the discovery context passed to the Planner
+
+**Language detection heuristics:**
+
+| Files present | Load |
+|---|---|
+| `*.ex`, `*.exs`, `mix.exs` | `elixir.md` |
+| `*.js`, `*.ts`, `*.jsx`, `*.tsx`, `*.css`, `*.html` | `javascript.md` |
+| `*.svelte`, `svelte.config.*` | `svelte.md` |
+| `*.py`, `pyproject.toml`, `requirements.txt` | `python.md` |
+| `*.sh`, `*.bash`, `Makefile` | `bash.md` |
+| `*.md`, `CLAUDE.md`, `README.md` | `markdown.md` |
+| `mix.exs` with `:postgrex` or `:ecto`, or `*.sql` files | `postgresql.md` |
+| DuckDB usage, `*.duckdb` files, or analytical/data tasks | `duckdb.md` |
+| `*.kk`, `koka.json` | `koka.md` |
+
+**Overriding:** Projects can ship their own `kiss-practices` skill in `.pi/skills/kiss-practices/SKILL.md` to override these defaults with project-specific rules.