@pikku/skills 0.12.27 → 0.12.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.27",
+  "version": "0.12.28",
   "description": "The Pikku agent skills — the instruction set coding agents read to build, wire and deploy Pikku projects",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/skills/pikku-knowledge/SKILL.md

@@ -141,7 +141,8 @@ And writing again replaces it rather than adding a second
 ```
 ````
 
-- **`status`** is `proposed` → `dispatched` → `built`. Nothing else. Every gate compares it literally.
+- **`status`** is `designing` → `proposed` → `dispatched` → `built`. Nothing else. Every gate compares it literally. `designing` sits BEFORE `proposed`: the slice is written down but must not be built yet, because whoever is being shown its looks has not picked one. Only `proposed` is dispatchable, so the two cannot be one status without a slice being built out from under the person still choosing.
+- **`statusAt:` and `attempts:` are bookkeeping, not content — never hand-edit them.** A loop driving this base writes both. `statusAt:` is stamped by whatever moved the status, and is what makes "how long has this been building?" answerable; the file's mtime is not the transition time, because a note is edited after dispatch for all sorts of reasons. `attempts:` is `seat@hash` entries recording which seat has already tried to move this note forward, against the content it was trying to move — it is the loop's only brake, and clearing it by hand hands back a budget that exists to stop a note nothing can satisfy being rewritten forever. Rewriting the note's real content refunds that budget on its own, which is the point: an answer that changes the note is what unsticks it.
 - **`entities`** lists what the slice touches, **at most three**. Past three it is not one buildable piece — split it.
 - **The scenario is a fenced `gherkin` block, in the third person.** `Given 'owner' has no entry` — never `Given I have no entry`. A quoted word _means a persona_, which is what lets a reader (and a test) tell who is acting. First person hides that, so it is rejected. The console draws the keywords as a column and each quoted persona as a chip, so a first-person scenario is visibly a block with no personas in it.
 
@@ -243,6 +244,32 @@ pikku knowledge index --check   # report stale indexes without writing (CI gate)
 
 `index` rewrites only the block between `<!-- pikku:knowledge-index -->` markers, creating a scaffolded `index.md` for a section that has none. It is idempotent — running it twice changes nothing.
 
+### What to do next
+
+```bash
+pikku knowledge next            # the one thing to do next, derived from what is on disk
+```
+
+`next` is a pure read: it looks at the notes and answers with exactly one action —
+`repair-note`, `write-plan`, `ask-user`, `dispatch`, `hold`, or `idle`. Nothing has to
+be armed by whoever noticed a transition, so calling it twice is free and a state
+nobody anticipated is a missing answer rather than a run that quietly stops.
+
+Two things about the output matter if you are driving it:
+
+- **`reason` is machine wording.** It names the note, the frontmatter key and what the
+  gate wanted. Never repeat it to a person — they have not seen a note and it will read
+  as gibberish about files.
+- **`ask-user` carries a `question` as well.** That IS the version for a person: a
+  `header`, the question in the language of their app, and `options` when the answer
+  comes from a closed vocabulary (which `status:` it is, which `surface:` it is).
+  `options` is empty when the answer is free text, and an empty list means offer free
+  text — never invent choices to fill it.
+
+`hold` means a profile's own gate is holding the milestone and no seat this loop knows
+about can clear it. It names the hold and the notes it is about; what to do then
+belongs to that profile, not here.
+
 ### The milestone plan
 
 A milestone note says what the app must DO. Its **plan** — JSON beside the note, not prose — says what has to exist for it, and is what a finished build is measured against:

package/skills/pikku-kysely/SKILL.md

@@ -4,12 +4,13 @@ description: >-
   Use when WRITING KYSELY QUERIES (select/join/aggregate/insert/update/delete) inside a Pikku
   function body, or when setting up SQL database services with Kysely. Covers the query builder
   API (joins, aggregates + groupBy/having, returning, sql template, expression builder, $if,
-  transactions, jsonArrayFrom relation helpers) AND @pikku/kysely service setup (channel stores,
+  transactions, jsonArrayFrom relation helpers), HOW MANY ROUND TRIPS a function body costs and how to
+  collapse sequential awaits into one statement, AND @pikku/kysely service setup (channel stores,
   workflow services, secret services, AI storage, deployment services). TRIGGER when: writing any
   non-trivial kysely query (a join, an aggregate/count/sum, groupBy, subquery, transaction, or
   conditional query), the injected `kysely` service is used in a function body, or code uses
-  PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, or the user asks
-  about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB or Redis-backed
+  PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, a function body
+  awaits more than one query, or the user asks about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB or Redis-backed
   services (use pikku-service-backends).
 installGroups: [core]
 ---
@@ -119,6 +120,109 @@ await kysely.transaction().execute(async (trx) => {
 })
 ```
 
+## One statement, not five
+
+**Count the `await`s in the function body before you finish it.** In a deployed
+stage the database is not in the process — every terminal (`.execute()`,
+`.executeTakeFirst()`) is a network hop, and five in a row is five latencies the
+caller waits through in series. This is the single most common thing wrong with a
+generated function body, and it never shows up locally against a socket on the
+same machine.
+
+**Sequential is only correct when the second query needs the first one's
+VALUES.** Everything else is one of these four:
+
+**1. Independent reads → `Promise.all`.** Nothing about the SQL changes; they
+just stop queuing behind each other.
+
+```typescript
+// Three hops, in series
+const item = await kysely.selectFrom('item').where('id','=',id).selectAll().executeTakeFirst()
+const bins = await kysely.selectFrom('bin').where('warehouseId','=',wid).selectAll().execute()
+const moves = await kysely.selectFrom('stockMove').where('itemId','=',id).selectAll().execute()
+
+// One hop's worth of latency
+const [item, bins, moves] = await Promise.all([
+  kysely.selectFrom('item').where('id','=',id).selectAll().executeTakeFirst(),
+  kysely.selectFrom('bin').where('warehouseId','=',wid).selectAll().execute(),
+  kysely.selectFrom('stockMove').where('itemId','=',id).selectAll().execute(),
+])
+```
+
+**2. Parent, then its children → `jsonArrayFrom` / `jsonObjectFrom`.** A loop
+containing an `await` is an N+1: one query per row, so the cost is the size of the
+result set rather than the size of the code. **Never `await` inside a `for`/`map`
+over rows you just fetched.** The relation helpers in the cookbook above collapse
+it into one statement that returns the nested shape your output schema already
+wants.
+
+```typescript
+// N+1 — one extra hop per warehouse
+const warehouses = await kysely.selectFrom('warehouse').selectAll().execute()
+for (const w of warehouses) {
+  w.bins = await kysely.selectFrom('bin').where('warehouseId','=',w.id).selectAll().execute()
+}
+// One hop — see NESTED DATA above
+```
+
+If the shape genuinely cannot be nested, fetch the children in **one** query with
+`where('warehouseId', 'in', warehouses.map((w) => w.id))` and group them in JS.
+Two hops beats N.
+
+**3. Read, decide, write → one write that returns.** A `select` to check
+existence followed by an `insert` is both two hops and a race — another request
+can insert between them. `returning()` and `onConflict` do it in one statement,
+and what comes back tells you which branch happened.
+
+```typescript
+// Two hops and a race
+const existing = await kysely.selectFrom('item').where('sku','=',sku).select('id').executeTakeFirst()
+if (existing) throw new ConflictError()
+await kysely.insertInto('item').values({ sku, name }).execute()
+
+// One hop, and the database arbitrates
+const created = await kysely
+  .insertInto('item')
+  .values({ sku, name })
+  .onConflict((oc) => oc.column('sku').doNothing())
+  .returning(['id', 'sku'])
+  .executeTakeFirst()
+if (!created) throw new ConflictError()
+```
+
+The same applies to fetch-then-update: `updateTable(...).where(...).returning(...)`
+in one call, and `undefined` back means the row was not there — that is your
+`NotFoundError`, not a reason for a preceding `select`. Many single-row inserts
+are one `.values([...])` with an array.
+
+**4. A read that only feeds the next query's `where` → a subquery or a CTE.**
+If the first result never reaches the response and never reaches JS, it should
+never have crossed the wire.
+
+```typescript
+// Two hops — the ids are only ever used as a filter
+const ids = await kysely.selectFrom('bin').where('warehouseId','=',wid).select('id').execute()
+const stock = await kysely.selectFrom('stock').where('binId','in', ids.map((b) => b.id)).selectAll().execute()
+
+// One hop
+const stock = await kysely
+  .selectFrom('stock')
+  .where('binId', 'in', (eb) =>
+    eb.selectFrom('bin').select('bin.id').where('bin.warehouseId', '=', wid)
+  )
+  .selectAll()
+  .execute()
+```
+
+`.with('name', (db) => ...)` builds a CTE when the same intermediate is needed
+twice inside one statement. A total alongside a page is a window function —
+`eb.fn.countAll<number>().over().as('total')` — not a second `count` query.
+
+**A transaction does NOT reduce round trips.** It adds `BEGIN` and `COMMIT` around
+whatever is inside it. Reach for it when several writes must land together or not
+at all; never as a way to make sequential queries cheaper, and never wrapped round
+reads that only needed `Promise.all`.
+
 Pikku provides SQL database services through six packages:
 
 - `@pikku/kysely` — Base service implementations (database-agnostic), the serialize plugins, `createAuditedKysely` and the `pikkuSchemas` helpers