pi-rnd 0.2.1

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "pi-rnd",
+  "version": "0.2.1",
+  "description": "Scientific-method R&D orchestration for PI Coding Agent — methodology skills, subagent definitions, /rnd-start pipeline, /rnd-doctor, and a composable tool_call gate registry",
+  "type": "module",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "prepack": "tsc"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://tangled.org/oleksify.me/pi-rnd.git"
+  },
+  "bugs": {
+    "url": "https://tangled.org/oleksify.me/pi-rnd/issues"
+  },
+  "homepage": "https://tangled.org/oleksify.me/pi-rnd",
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "rnd",
+    "orchestration",
+    "scientific-method",
+    "subagents"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@tintinweb/pi-subagents": "^0.7.3"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist/",
+    "agents/",
+    "skills/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/skills/fp-practices/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: fp-practices
+description: "Use alongside KISS practices to guide agents toward functional programming patterns — pure functions, data transformations, composition, command-query separation, and immutability"
+effort: low
+---
+
+# Functional Programming Practices
+
+## Overview
+
+Concrete rules for writing code in a functional style. These complement KISS practices — KISS prevents over-engineering, FP practices guide _how_ to structure the code that remains.
+
+**Core principle:** Separate what you compute from what you do. Pure logic in, effects out.
+
+## 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 `fp-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 FP rules in the discovery context passed to the Planner
+
+**Language detection heuristics:**
+
+| Files present | Load |
+|---|---|
+| `*.sh`, `*.bash`, `Makefile` | `bash.md` |
+| `*.ex`, `*.exs`, `mix.exs` | `elixir.md` |
+| `*.js`, `*.ts`, `*.jsx`, `*.tsx`, `*.css`, `*.html` | `javascript.md` |
+| `*.py`, `pyproject.toml`, `requirements.txt` | `python.md` |
+| `*.lean`, `lakefile.lean` | `lean.md` |
+| `*.svelte`, `svelte.config.*` | `svelte.md` |
+| `*.kk`, `koka.json` | `koka.md` |
+| `mix.exs` with `:postgrex` or `:ecto`, or `*.sql` files | `postgresql.md` |
+| DuckDB usage, `*.duckdb` files, or analytical/data tasks | `duckdb.md` |
+
+**Overriding:** Projects can ship their own `fp-practices` skill in `.pi/skills/fp-practices/SKILL.md` to override these defaults with project-specific rules.
+
+## The Rules
+
+### 1. Pure Functions First
+
+A pure function takes inputs and returns outputs. It does not read globals, write files, call APIs, or mutate arguments.
+
+**Do:**
+- Write the computation as a pure function that takes data and returns data
+- Push side effects (I/O, database, network) to the caller or the edges of the system
+- Pass dependencies as arguments, not through closures over mutable state
+
+**Don't:**
+- Mix computation and I/O in the same function — a function that calculates a price AND saves it to the database does two things
+- Read environment variables or config inside business logic — pass the values in
+- Use `Date.now()`, `Math.random()`, or other non-deterministic calls inside pure logic — inject them as arguments
+
+### 2. Data Transformations Over Mutation
+
+Express logic as a pipeline of transformations on data, not a sequence of mutations on state.
+
+**Do:**
+- Use map, filter, reduce (or language equivalents) to transform collections
+- Return new data structures instead of modifying existing ones
+- Chain transformations: `input |> validate |> transform |> format`
+
+**Don't:**
+- Build up results with `let result = []; for (...) { result.push(...) }` when `items.map(...)` works
+- Mutate function arguments — if you need to change shape, return a new object
+- Use index-based loops when the intent is "transform each item" — map expresses intent better
+
+### 3. Composition Over Inheritance
+
+Build behavior by combining small, focused functions — not by extending class hierarchies.
+
+**Do:**
+- Write small functions that do one thing and compose them: `const process = compose(validate, transform, save)`
+- Use higher-order functions (functions that take or return functions) for shared behavior
+- Prefer data + functions over objects + methods — a plain object with helper functions is often simpler than a class
+
+**Don't:**
+- Create class hierarchies for code reuse — use composition instead
+- Add `extends` or `super` when a function parameter achieves the same thing
+- Build "base classes" that child classes override — pass behavior as functions
+
+### 4. Command-Query Separation
+
+A function either returns data (query) or causes an effect (command). Never both.
+
+**Do:**
+- Functions that compute or look up data should return the result and have no side effects
+- Functions that perform effects (save, send, delete) should not return computed data — return only success/failure status if needed
+- Separate "decide what to do" (pure) from "do it" (effectful)
+
+**Don't:**
+- Write `getOrCreate` functions that both query and mutate — split into `find` + `create`
+- Return a value AND log/save/send as a side effect in the same function
+- Mix validation (pure) with rejection actions (effectful) — validate first, act on the result
+
+### 5. Immutability by Default
+
+Declare bindings as immutable unless mutation is specifically needed.
+
+**Do:**
+- Use `const` (JS/TS), `val` (Kotlin), `let` (Swift/Rust), or the immutable equivalent in your language
+- Use spread/destructuring to create modified copies: `{...user, name: newName}`
+- Prefer `readonly` types in TypeScript for function parameters
+
+**Don't:**
+- Use `let`/`var` when the value is assigned once and never changed
+- Mutate arrays in place (`push`, `splice`) when `map`/`filter`/`concat` works
+- Reassign variables to track state through a function — restructure as a pipeline instead
+
+### 6. Polish: Consistency and Organization
+
+**Do:**
+- Use one naming convention for pure functions across modules: either `verb_noun` or `noun_verb` as the language dictates — don't mix `computeTotal`/`total_compute` styles within the same codebase
+- Extract helpers shared by two or more call sites to a single canonical location — don't let the same pure transformation live in multiple modules with slight variations
+- Group pure functions by the domain they operate on, not alphabetically — `user_*` functions together, `order_*` together; alphabetical grouping hides cohesion
+
+**Don't:**
+- Duplicate a pure transformation across modules to avoid adding a shared helper file — copy-pasted logic drifts and causes silent inconsistencies at the wave level
+- Mix domain-level functions and low-level utility functions in the same module without clear separation — readers should be able to find all business logic in one place and all plumbing in another
+
+## When to Break These Rules
+
+These rules have legitimate exceptions:
+
+- **Performance-critical loops** — mutation in a tight loop is acceptable when measured profiling shows the functional version is too slow
+- **Language idioms** — if the language strongly favors imperative style (Go, C), adapt the principles to the idiom rather than fighting it
+- **Framework constraints** — React hooks, ORM callbacks, and similar framework patterns may require mutation or mixed command-query; follow the framework's conventions
+- **Startup/initialization code** — building up configuration objects during app boot is naturally imperative; don't force it into a pipeline

package/skills/fp-practices/bash.md

@@ -0,0 +1,114 @@
+# Bash — FP Patterns
+
+Bash-specific patterns for the five FP rules in SKILL.md. Assumes `set -euo pipefail`.
+
+## 1. Pipe Composition
+
+Express multi-step transformations as pipelines of named functions.
+
+**Do:**
+```bash
+parse_csv()    { cut -d',' -f1; }
+strip_blanks() { grep -v '^[[:space:]]*$'; }
+uppercase()    { tr '[:lower:]' '[:upper:]'; }
+
+process_names() { parse_csv | strip_blanks | uppercase; }
+```
+
+**Don't:** accumulate into a `result` variable with repeated `result=$(echo "$result" | ...)` — that hides the transformation and is harder to test each stage.
+
+## 2. Immutability — `local -r`
+
+Use `local -r` for any binding assigned once. Documents intent; prevents accidental reassignment.
+
+**Do:**
+```bash
+normalize_path() {
+  local -r raw="$1"
+  local -r trimmed="${raw%/}"
+  printf '%s\n' "${trimmed:-/}"
+}
+```
+
+**Don't:** use bare `local path="$1"` and then mutate `path` in the same function — each step should produce a new named binding.
+
+## 3. Higher-Order Functions — map / filter / reduce
+
+Implement the pattern as functions that accept a function name and read stdin line-by-line.
+
+```bash
+set -euo pipefail
+
+map_lines() {     # map_lines fn < input
+  local -r fn="$1"
+  while IFS= read -r line; do "$fn" "$line"; done
+}
+
+filter_lines() {  # filter_lines fn < input
+  local -r fn="$1"
+  while IFS= read -r line; do
+    "$fn" "$line" && printf '%s\n' "$line" || true
+  done
+}
+
+reduce_lines() {  # reduce_lines fn init < input
+  local -r fn="$1"; local acc="${2:-}"
+  while IFS= read -r line; do acc="$("$fn" "$acc" "$line")"; done
+  printf '%s\n' "$acc"
+}
+```
+
+**Usage:**
+```bash
+double()   { printf '%d\n' "$(( $1 * 2 ))"; }
+positive() { (( $1 > 0 )); }
+sum()      { printf '%d\n' "$(( $1 + $2 ))"; }
+
+printf '1\n2\n3\n' | map_lines double      # 2 4 6
+printf '1\n-2\n3\n' | filter_lines positive # 1 3
+printf '1\n2\n3\n' | reduce_lines sum 0    # 6
+```
+
+## 4. Side-Effect Isolation
+
+Keep computation pure; push all I/O to the outermost caller.
+
+**Do:**
+```bash
+build_report() { local -r name="$1" count="$2"; printf '%s: %d\n' "$name" "$count"; }
+write_report()  { build_report "$(hostname)" 42 > "$1"; }
+```
+
+**Don't:** mix `printf` output with `> file` redirections inside the same function — a function that both computes and writes cannot be tested without the filesystem.
+
+## 5. Pure Function Conventions
+
+A pure bash function takes positional arguments, prints its result to stdout, and reads no globals.
+
+**Do:**
+```bash
+slugify() {
+  local -r input="$1"
+  printf '%s\n' "${input// /-}" | tr '[:upper:]' '[:lower:]'
+}
+```
+
+**Don't:** write results into global variables (`SLUG=...`) and expect callers to read them — use stdout so callers capture with `$()`.
+
+## 6. Command-Query Separation
+
+A function either prints data (query) or causes an effect (command) — not both.
+
+**Do:**
+```bash
+user_exists() { local -r n="$1"; getent passwd "$n" > /dev/null; }  # query
+create_user()  { local -r n="$1"; useradd "$n"; }                    # command
+```
+
+**Don't:**
+```bash
+ensure_user() {
+  useradd "$1" 2>/dev/null || true   # command
+  id -u "$1"                         # query — mixed
+}
+```

package/skills/fp-practices/duckdb.md

@@ -0,0 +1,116 @@
+# DuckDB — FP Patterns
+
+DuckDB-specific patterns for the five FP rules in SKILL.md.
+
+## 1. CTEs as Analytical Pipeline Stages
+
+Decompose multi-step analysis into named CTEs rather than nested subqueries.
+
+**Do:**
+```sql
+WITH
+  raw AS (SELECT * FROM read_parquet('events/*.parquet')),
+  filtered AS (
+    SELECT user_id, event_type, ts
+    FROM raw WHERE event_type IN ('purchase', 'refund')
+  ),
+  enriched AS (
+    SELECT f.*, u.country FROM filtered f JOIN users u USING (user_id)
+  )
+SELECT country, count(*) AS total FROM enriched
+GROUP BY country ORDER BY total DESC;
+```
+
+**Don't:** write a single deeply-nested `SELECT` — each logical step should be a named CTE that can be read and replaced independently.
+
+## 2. Window Functions as Pure Transformations
+
+Window functions add computed columns without mutating rows — treat them as row-level pure functions.
+
+**Do:**
+```sql
+WITH sales AS (SELECT * FROM read_csv('sales.csv')),
+ranked AS (
+  SELECT *,
+    row_number() OVER (PARTITION BY region ORDER BY revenue DESC) AS rank,
+    sum(revenue)  OVER (PARTITION BY region) AS region_total
+  FROM sales
+)
+SELECT * FROM ranked WHERE rank <= 10;
+```
+
+**Don't:** use correlated subqueries to compute running totals or ranks — window functions express the same intent with no side effects and are vectorized by DuckDB.
+
+## 3. QUALIFY for Declarative Row Filtering
+
+Use `QUALIFY` to filter on window results in a single pass — no wrapping subquery needed.
+
+**Do:**
+```sql
+SELECT user_id, session_id, started_at,
+  row_number() OVER (PARTITION BY user_id ORDER BY started_at DESC) AS rn
+FROM sessions
+QUALIFY rn = 1;
+```
+
+**Don't:** wrap in a subquery just to reference the window alias: `SELECT * FROM (...) t WHERE t.rn = 1`.
+
+## 4. list_transform / list_filter / list_reduce
+
+DuckDB list functions are map/filter/reduce for nested arrays — use them instead of unnest-aggregate roundtrips.
+
+**Do:**
+```sql
+SELECT order_id,
+  list_transform(items, x -> x.price * x.qty) AS line_totals,
+  list_reduce(list_transform(items, x -> x.price * x.qty), (a, b) -> a + b) AS total,
+  list_filter(items, x -> x.category = 'electronics') AS electronics
+FROM orders;
+```
+
+**Don't:** unnest, aggregate with GROUP BY, then rejoin — list functions handle this in a single pass.
+
+## 5. read_parquet / read_csv as Pure Sources
+
+Treat file-reading functions as pure sources. Query them directly; never stage into temp tables.
+
+**Do:**
+```sql
+WITH src AS (
+  SELECT * FROM read_parquet('s3://bucket/data/**/*.parquet', hive_partitioning = true)
+)
+SELECT year, month, sum(amount) FROM src GROUP BY year, month;
+```
+
+**Don't:** `CREATE TABLE tmp AS SELECT ...` then query `tmp` — temp tables add mutable state and require cleanup.
+
+## 6. Struct Operations as Record Transformations
+
+Bundle related columns into typed structs and transform them as values.
+
+**Do:**
+```sql
+SELECT id,
+  struct_pack(lat := lat, lon := lon) AS location,
+  struct_pack(open := open_price, close := close_price,
+              delta := close_price - open_price) AS ohlc
+FROM market_data;
+```
+
+**Don't:** carry many loose columns through every CTE stage — structs make the pipeline's shape explicit and prevent column-name collisions.
+
+## 7. Command-Query Separation
+
+Queries return data; writes mutate state. Keep them separate.
+
+**Do:**
+```sql
+-- query: returns relation, no side effects
+SELECT product_id, sum(quantity) AS sold FROM read_parquet('orders.parquet') GROUP BY 1;
+
+-- command: isolated write
+COPY (SELECT product_id, sum(quantity) AS sold FROM read_parquet('orders.parquet') GROUP BY 1)
+TO 'summary.parquet' (FORMAT PARQUET);
+```
+
+**Don't:** mix `INSERT INTO` inside a CTE that also returns rows — a CTE that both mutates and queries violates CQS and makes the pipeline non-reproducible.

package/skills/fp-practices/elixir.md

@@ -0,0 +1,115 @@
+# Elixir — FP Patterns
+
+Idiomatic Elixir: data flowing through transformations, pattern matching over branching, explicit effect boundaries.
+
+## 1. Pipe Operator Composition
+
+Use `|>` to express a data transformation pipeline. Each step is a named function — readable, testable, reorderable.
+
+**Do:**
+```elixir
+def process_order(params) do
+  params
+  |> validate_fields()
+  |> normalize_currency()
+  |> apply_discounts()
+  |> build_order_struct()
+end
+```
+
+**Don't:** nest as `build_order_struct(apply_discounts(normalize_currency(validate_fields(params))))` — unreadable and hard to insert a step.
+
+## 2. Pattern Matching Over Conditionals
+
+Match on the shape and values of data directly in function heads and `case` expressions instead of if/else chains.
+
+**Do:**
+```elixir
+def handle_result({:ok, user}),    do: render_user(user)
+def handle_result({:error, :not_found}), do: {:error, "User not found"}
+def handle_result({:error, reason}),     do: {:error, "Unexpected: #{reason}"}
+```
+
+**Don't:**
+```elixir
+def handle_result(result) do
+  if elem(result, 0) == :ok do
+    render_user(elem(result, 1))
+  else
+    {:error, "failed"}
+  end
+end
+```
+
+## 3. `with` Blocks for Happy-Path Chaining
+
+Use `with` to sequence operations that each return `{:ok, value}` or `{:error, reason}`, short-circuiting on the first failure.
+
+**Do:**
+```elixir
+def create_account(params) do
+  with {:ok, email}   <- validate_email(params.email),
+       {:ok, user}    <- Repo.insert(%User{email: email}),
+       {:ok, _token}  <- Mailer.send_welcome(user) do
+    {:ok, user}
+  end
+end
+```
+
+**Don't:** nest `case` expressions or use `try/rescue` for expected failures — `with` keeps the happy path linear and the error handling in one place.
+
+## 4. GenServer as Effect Boundary
+
+Keep business logic in pure functions; use GenServer only to sequence effects and hold state.
+
+**Do:**
+```elixir
+# Pure logic — easy to unit test
+defmodule Cart do
+  def add_item(%__MODULE__{} = cart, item), do: %{cart | items: [item | cart.items]}
+  def total(%__MODULE__{items: items}),     do: Enum.sum_by(items, & &1.price)
+end
+
+# Effect boundary — wraps state + persistence
+defmodule CartServer do
+  use GenServer
+  def handle_call({:add, item}, _from, cart), do: {:reply, :ok, Cart.add_item(cart, item)}
+  def handle_call(:total, _from, cart),       do: {:reply, Cart.total(cart), cart}
+end
+```
+
+**Don't:** put `Repo.insert/1` or HTTP calls inside the pure module — separate computation from effects so core logic is testable without starting a process.
+
+## 5. Structs as Immutable Values
+
+Transformations return new structs; the original is never mutated.
+
+**Do:**
+```elixir
+defmodule Invoice do
+  defstruct [:id, :amount, :status]
+  def mark_paid(%__MODULE__{} = inv),    do: %{inv | status: :paid}
+  def apply_tax(%__MODULE__{} = inv, r), do: %{inv | amount: inv.amount * (1 + r)}
+end
+
+invoice
+|> Invoice.apply_tax(0.2)
+|> Invoice.mark_paid()
+```
+
+**Don't:** use plain maps with string keys for structured domain data — structs catch misspelled keys at compile time and make pipelines self-documenting.
+
+## 6. Higher-Order Functions with Enum / Stream
+
+Prefer `Enum`/`Stream` over explicit recursion. Use `Stream` for lazy evaluation of large sequences.
+
+**Do:**
+```elixir
+active_totals =
+  orders
+  |> Stream.filter(& &1.status == :active)
+  |> Stream.map(& &1.total)
+  |> Enum.sum()
+```
+
+**Don't:** accumulate manually with `Enum.reduce` when a `filter |> map |> sum` chain expresses the intent clearly.

package/skills/fp-practices/javascript.md

@@ -0,0 +1,119 @@
+# JavaScript / TypeScript — FP Patterns
+
+JS/TS-specific patterns for the five FP rules in SKILL.md.
+
+## 1. Array Method Chains
+
+Express multi-step data transformations as chained array methods rather than loops with accumulated state.
+
+**Do:**
+```js
+const activeUserNames = users
+  .filter(u => u.active)
+  .map(u => u.name)
+  .sort();
+```
+
+**Don't:** accumulate with a `for` loop and a mutable `result` array — that hides transformation intent and makes each stage invisible.
+
+## 2. Immutable Object Patterns
+
+Produce new values instead of mutating inputs. Use spread for shallow copies; `structuredClone` for deep clones.
+
+**Do:**
+```js
+const updated = { ...user, lastLogin: Date.now() };
+
+const deepCopy = structuredClone(nestedConfig);
+deepCopy.server.port = 9000;
+```
+
+**Don't:** mutate function arguments — callers cannot reason about their object after the call.
+
+Use `Object.freeze` for module-level constants:
+
+```js
+export const DEFAULT_OPTIONS = Object.freeze({ timeout: 5000, retries: 3 });
+```
+
+## 3. TypeScript Readonly and `as const`
+
+Encode immutability in the type system so mutations are caught at compile time.
+
+**Do:**
+```ts
+function process(items: readonly string[]): readonly string[] {
+  return items.map(s => s.trim());
+}
+
+type Config = Readonly<{
+  host: string;
+  port: number;
+}>;
+```
+
+Use `as const` to narrow literal types and prevent widening:
+
+```ts
+const DIRECTIONS = ['north', 'south', 'east', 'west'] as const;
+type Direction = typeof DIRECTIONS[number]; // 'north' | 'south' | 'east' | 'west'
+```
+
+**Don't:** accept `string[]` when the function only reads — use `readonly string[]` so TS enforces the contract at every call site.
+
+## 4. Higher-Order Functions
+
+Pass behavior as arguments to keep logic composable and independently testable.
+
+**Do:**
+```ts
+const applyDiscount =
+  (rate: number) =>
+  (price: number): number =>
+    price * (1 - rate);
+
+const tenPercent = applyDiscount(0.1);
+const prices = [100, 200, 300].map(tenPercent); // [90, 180, 270]
+```
+
+**Don't:** repeat the discount formula at every call site — a curried function is reusable and the rate is explicit in the name.
+
+## 5. Composition Utilities
+
+Build complex transforms from small, single-purpose functions rather than nesting calls.
+
+**Do:**
+```ts
+const pipe =
+  <T>(...fns: Array<(x: T) => T>) =>
+  (x: T): T =>
+    fns.reduce((acc, fn) => fn(acc), x);
+
+const normalizeEmail = pipe(
+  (s: string) => s.trim(),
+  (s: string) => s.toLowerCase(),
+  (s: string) => s.replace(/\s+/g, ''),
+);
+```
+
+**Don't:** nest calls three-deep — `f(g(h(x)))` obscures application order and makes inserting steps awkward.
+
+## 6. Command-Query Separation in Async Code
+
+Pure data transformations are synchronous functions. Async functions contain I/O effects. Keep them separate.
+
+**Do:**
+```ts
+// Query (pure, sync)
+function buildPayload(order: Order): ApiPayload {
+  return { id: order.id, total: order.lines.reduce((s, l) => s + l.price, 0) };
+}
+
+// Command (effectful, async)
+async function submitOrder(order: Order): Promise<void> {
+  const payload = buildPayload(order);  // pure step first
+  await api.post('/orders', payload);
+}
+```
+
+**Don't:** mix computation and I/O in a single async function — the pure transform cannot be unit-tested without mocking the network.