@pikku/skills 0.12.33 → 0.12.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.33",
+  "version": "0.12.34",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/skills/pikku-architect/SKILL.md

@@ -3,9 +3,9 @@ name: pikku-architect
 description: >-
   Use to turn one settled milestone note into the technical plan the build is measured against —
   the tables, functions, wires, roles, scopes, screens and scenarios it owes, split into passes and
-  written through `pikku knowledge plan set`. This is a SEPARATE SEAT from the build: the plan is
-  the denominator `pikku knowledge plan progress` divides by, so whoever writes it must not be the
-  one grading themselves against it. TRIGGER when: a milestone note is settled and the next step is
+  written through `pikku knowledge plan set`. The plan is the denominator
+  `pikku knowledge plan progress` divides by, so it is written BEFORE any of the milestone's code
+  exists and never edited afterwards to match what got built. TRIGGER when: a milestone note is settled and the next step is
   planning it, the user asks to plan or architect a milestone, `pikku knowledge plan progress` says
   a milestone has no plan, or pikku-build's App mode reaches a milestone with nothing planned. DO
   NOT TRIGGER when: the milestone notes themselves are still being written (use pikku-knowledge),
@@ -17,18 +17,19 @@ installGroups: [core]
 # Plan one milestone
 
 A milestone note says what the app must DO and how it must feel for the person using it. It
-deliberately does not say how. You are the seat that decides how, once, in writing, before anyone
-builds it.
+deliberately does not say how. This is where how gets decided, once, in writing, before any of
+it is built.
 
-**Why this is a separate seat.** The build agent used to write its own plan. That makes one party
-both author and examiner: it can build a fraction, plan only that fraction, and certify itself
-complete — and `pikku knowledge plan progress` then divides by a denominator the builder chose
-after seeing its own answer. A plan written here, against the note, by someone who is not going to
-build it, is the denominator the builder does not own.
+**Why the plan comes first and stays fixed.** A builder who plans after seeing its own work can
+build a fraction, plan only that fraction, and certify itself complete — `pikku knowledge plan
+progress` then divides by a denominator chosen after the answer. The defence is the ORDER: the plan
+is written against the note, in its own turn, before a single migration for it exists, and is never
+edited afterwards. An item that will not land is deferred with its reason through `plan defer`,
+not rewritten out of the plan. The same agent plans and then builds; nothing hands off.
 
-**One milestone, one plan, then stop.** Do not build in this session. Do not plan the next
-milestone "while you are here" — the notes after this one are still allowed to change, and a plan
-written against a note that later moves is worse than no plan.
+**One milestone, one plan, then build it.** Do not plan the next milestone "while you are here" —
+the notes after this one are still allowed to change, and a plan written against a note that later
+moves is worse than no plan.
 
 ---
 
@@ -38,6 +39,11 @@ The plan reaches disk through `pikku knowledge plan set <milestone> <file>` and
 validates first and names the field that is wrong if it refuses; a plan file written with an editor
 is a plan nothing checked, and the place that discovers that is a finished build.
 
+It is also written ONCE. `plan set` refuses a milestone that already has a plan: the plan is the
+order the build is measured against, and an order that can be rewritten measures nothing. The one
+way down from a written plan is `pikku knowledge plan defer <milestone> <item> --reason <why>`,
+which records what was left out and why.
+
 It is JSON rather than a note on purpose. Everything else under `knowledge/` is prose a human
 reads; this one is consumed field-by-field, and a markdown parser is one more place a misspelt
 heading silently passes. It cannot live INSIDE the milestone note either: that note is frozen once
@@ -260,6 +266,7 @@ cover it — so a role × resource cross product there costs the milestone nothi
 
 ## When you are done
 
-The accepted `plan set` is the end of the seat. Hand the milestone to `pikku-build`, which reads the
-plan with `plan show --for-build`, builds it, and closes the milestone only when
-`pikku knowledge plan progress` is clean. What you wrote is what it is measured against.
+The accepted `plan set` is the end of planning. Go straight on to the build in `pikku-build` §6:
+read the plan with `plan show --for-build`, build it, and close the milestone only when
+`pikku knowledge plan progress` is clean. What you wrote is what you are measured against, so do
+not touch it once the first migration is open.

package/skills/pikku-build/SKILL.md

@@ -19,13 +19,13 @@ installGroups: [core]
 
 ## Which mode
 
-| The situation | Read |
-| --- | --- |
-| A template was just cloned or scaffolded, and the tree still looks like one | `references/post-clone.md` first, then come back |
-| A real product, meant to be picked up by someone else | `references/app.md` — the default |
-| A spike, a throwaway demo, an idea nobody has committed to | `references/quick.md` |
-| A showcase meant to exercise every Pikku surface | `references/platform.md`, which is a delta on top of `references/app.md` |
-| A feature added to an app that already has its knowledge base and milestones | `references/feature.md` |
+| The situation                                                                | Read                                                                     |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| A template was just cloned or scaffolded, and the tree still looks like one  | `references/post-clone.md` first, then come back                         |
+| A real product, meant to be picked up by someone else                        | `references/app.md` — the default                                        |
+| A spike, a throwaway demo, an idea nobody has committed to                   | `references/quick.md`                                                    |
+| A showcase meant to exercise every Pikku surface                             | `references/platform.md`, which is a delta on top of `references/app.md` |
+| A feature added to an app that already has its knowledge base and milestones | `references/feature.md`                                                  |
 
 **App is the default.** A small or toy-sounding app does not make it Quick;
 only an explicit signal of speed or throwaway-ness does. Platform is not "App
@@ -53,9 +53,10 @@ while still planning. Those failures look alarming and are nothing but this.
 
 ## What holds in every mode
 
-- **The branch and the diff are the contract.** There is no plan JSON. A
-  reviewer sees real, compiled, working code: apply is a merge, reject is a
-  `git branch -D`.
+- **The branch and the diff are the contract.** A reviewer sees real, compiled,
+  working code: apply is a merge, reject is a `git branch -D`. The milestone's
+  plan is your own denominator, measured by `pikku knowledge plan progress` —
+  never something a reviewer is handed instead of the code.
 - **Discover before editing.** `yarn pikku meta context --json` returns
   functions, wires, middleware, permissions, workflows, `capabilities` and
   `layout` in one call. Fall back to targeted `meta` commands only for a full
@@ -66,11 +67,13 @@ while still planning. Those failures look alarming and are nothing but this.
   lives in `messages/*.json`.
 - **`pikku all` is the gate.** Run it after touching functions, wirings or
   schemas, and treat its criticals as real.
-- **A milestone is planned by a different seat than the one that builds it.**
+- **A milestone is planned before it is built, and the plan then stays fixed.**
   The plan — tables, functions, wires, roles, scopes, screens, scenarios, in
-  passes — is written through `pikku knowledge plan set` by `pikku-architect`,
-  and `pikku knowledge plan progress` measures the build against it from the
-  generated meta. A builder who writes its own plan is grading itself.
+  passes — is written through `pikku knowledge plan set` (how: `pikku-architect`)
+  in its own turn before any of that milestone's code exists, and
+  `pikku knowledge plan progress` measures the build against it from the
+  generated meta. You plan it and you build it; what you never do is edit the
+  plan afterwards to match what you built — that is grading yourself.
 
 ## What NOT to do
 

package/skills/pikku-build/references/app.md

@@ -81,11 +81,11 @@ A brief saying "the entire UI is German" is about **one** of these. Getting this
 wrong has already shipped a project that can never add a second language, so
 settle all three explicitly before you write code.
 
-| Axis            | What it covers                                                                                                                       | Where it goes                                                                     |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Commit messages.                                    | Nowhere — **always English**, no setting, not negotiable                          |
-| **Meta**        | `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role and persona descriptions        | `metaLocale` in `pikku.config.json`, default `en`                                     |
-| **Product UI**  | Every string the app shows a user                                                                                                    | `messages/<locale>.json`, and `defaultLocale` for what a first-time visitor opens in |
+| Axis            | What it covers                                                                                                                 | Where it goes                                                                        |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Commit messages.                              | Nowhere — **always English**, no setting, not negotiable                             |
+| **Meta**        | `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role and persona descriptions | `metaLocale` in `pikku.config.json`, default `en`                                    |
+| **Product UI**  | Every string the app shows a user                                                                                              | `messages/<locale>.json`, and `defaultLocale` for what a first-time visitor opens in |
 
 **Identifiers are English.** The product's market does not change this and
 neither does `metaLocale`. Identifiers are the surface the generated `#pikku/*`
@@ -218,7 +218,11 @@ defineSystemRole({
 })
 
 definePersonas({
-  visitor: { name: 'Visitor', jobTitle: 'Synthetic health-check user', account: {} },
+  visitor: {
+    name: 'Visitor',
+    jobTitle: 'Synthetic health-check user',
+    account: {},
+  },
   amina: {
     name: 'Amina',
     jobTitle: 'Property owner',
@@ -229,7 +233,8 @@ definePersonas({
   bilal: {
     name: 'Bilal',
     jobTitle: 'Property owner',
-    personality: 'A second owner — exists so "you see yours, not theirs" is testable',
+    personality:
+      'A second owner — exists so "you see yours, not theirs" is testable',
     roles: ['owner'],
     account: {},
   },
@@ -369,10 +374,10 @@ scenarios, split into passes. It is JSON, it lives beside the note, and
 `pikku knowledge plan progress` measures the finished build against it.
 
 **Read `pikku-architect` and follow it.** The plan is the denominator the
-completion check divides by, so a builder who writes their own plan can build a
-fraction, plan only that fraction, and certify itself complete. Fabric answers
-that by giving the plan its own seat; here the defence is the ORDER, and it only
-holds if you keep it: the plan is written against the note in its own turn,
+completion check divides by, so a builder who plans after seeing their own work
+can build a fraction, plan only that fraction, and certify itself complete. The
+defence is the ORDER, and it only holds if you keep it: the plan is written
+against the note in its own turn,
 before any of the code it measures exists, and is never edited afterwards to
 match what you ended up building. An item that will not land is deferred with
 its reason — `plan defer` — not quietly rewritten. Write it before you open a
@@ -396,8 +401,8 @@ no plan, and everything after the current milestone is still allowed to move.
 
 **Per milestone** — plan it (§5a), set its note to `status: dispatched`, do the
 six steps, close it out (§6a), set it to `built`. Do not start the next one
-until §6a passes, §7 is green for this one *and §7a shows its functions
-covered*. A stack of half-milestones cannot be reviewed and cannot be handed
+until §6a passes, §7 is green for this one _and §7a shows its functions
+covered_. A stack of half-milestones cannot be reviewed and cannot be handed
 over, and an uncovered function is a half-milestone whether or not the note says
 `built`.
 
@@ -416,7 +421,7 @@ over, and an uncovered function is a half-milestone whether or not the note says
    Do this generously and do it now: an empty app demos badly and critiques
    badly, and you cannot judge a screen's hierarchy, overflow, or truncation
    against zero rows. Seed rows each persona sees differently — with an ownership
-   rule that means seeding rows for the *second* owner too.
+   rule that means seeding rows for the _second_ owner too.
 3. **Functions.** One `pikkuFunc` per `*.function.ts`. Mark it `expose: true` and
    Pikku generates the typed RPC client and the React Query hooks the UI calls;
    you do NOT write an HTTP route for it. Add `wireHTTP` only for a real REST
@@ -443,8 +448,10 @@ over, and an uncovered function is a half-milestone whether or not the note says
    same as the scenario: a milestone whose screens nobody has seen is not built,
    it is unproven at the one layer scenarios cannot reach. `references/design.md`
    carries how to take the shot when no browser tool is wired up, and what to
-   look for. Then `status: built`, and say in the note what you looked at and
-   what it made you change.
+   look for. Then close it against its plan (§6a) — `pikku knowledge plan
+progress` has to exit zero before anything is `built` — and only then set
+   `status: built`, saying in the note what you looked at and what it made you
+   change.
 
 Rules that are not optional:
 
@@ -464,8 +471,8 @@ Rules that are not optional:
   ```typescript
   export const classifications = {
     payment: {
-      paid_at:  { kind: 'date' },                        // -> Date, not an ISO string
-      metadata: { kind: 'json', tsType: 'PaymentMeta' },  // -> parsed object, not unknown
+      paid_at: { kind: 'date' }, // -> Date, not an ISO string
+      metadata: { kind: 'json', tsType: 'PaymentMeta' }, // -> parsed object, not unknown
     },
   }
   ```
@@ -474,6 +481,7 @@ Rules that are not optional:
   `JSON` column with no entry types as `unknown` (the CLI warns PKU481). Add the
   annotation rather than casting around the generated type. Once the file carries
   manual fields, `db migrate` stops overwriting it.
+
 - A `z.date()` on a function's **input** arrives over RPC as an ISO string, not a
   `Date`. Normalise before calling date methods on it (`new Date(value)`), or it
   throws `.getTime is not a function` at runtime — schema validation accepts the
@@ -542,6 +550,7 @@ Three things it says, and what each one asks of you:
   milestone is two milestones — say so to the user rather than deferring again.
   What you may never do is drop the item silently: the plan is what the next
   person reads to know what this milestone was for.
+
 - **PROBLEMS** — something exists but does not do what was planned. A function
   planned as restricted whose meta says `auth: false`; a `cascade` no migration
   declares; a browser scenario that opens a page and asserts it is still on it.
@@ -550,8 +559,9 @@ Three things it says, and what each one asks of you:
   visible, never blocking.
 
 **Do not set the note to `built` while this exits non-zero**, and do not edit the
-plan to match what you built — `plan set` is the architect's seat, and a builder
-rewriting its own denominator is exactly what the split exists to stop.
+plan to match what you built — the plan was written before the code on purpose,
+and rewriting your own denominator afterwards is exactly what that order exists
+to stop.
 
 ## 7. Prove it — scenarios
 
@@ -566,26 +576,27 @@ import { pikkuScenario } from '#pikku/scenarios'
 
 export const tenantReportsAFaultScenario = pikkuScenario<void, { id: string }>({
   title: 'A tenant reports a fault and the owner sees it',
-  description: 'The report lands on the owning landlord’s queue, and nobody else’s',
+  description:
+    'The report lands on the owning landlord’s queue, and nobody else’s',
   tags: ['scenario', 'maintenance'],
   func: async (_services, _data, { scenario, actors }) => {
     const report = await scenario.do(
       'reports a broken boiler',
       'createMaintenanceReport',
       { summary: 'No hot water' },
-      { actor: actors.chidi },
+      { actor: actors.chidi }
     )
     await scenario.then(
       'appears on the owner’s queue',
       'reportShowsOnQueue',
       { id: report.id },
-      { actor: actors.amina },
+      { actor: actors.amina }
     )
     await scenario.then(
       'is invisible to the other owner',
       'reportIsNotVisible',
       { id: report.id },
-      { actor: actors.bilal },
+      { actor: actors.bilal }
     )
     return { id: report.id }
   },

package/skills/pikku-knowledge/SKILL.md

@@ -266,7 +266,7 @@ Two things about the output matter if you are driving it:
   `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
+`hold` means a profile's own gate is holding the milestone and nothing 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.
 
@@ -282,7 +282,7 @@ pikku knowledge plan progress <milestone>          # what it still owes, read fr
 pikku knowledge plan defer <milestone> <item> -r "<why>"
 ```
 
-`progress` reconciles the plan against pikku's generated meta — set membership, never anyone's status — and exits non-zero while the first pass is short, or while anything already built contradicts the plan. Unbuilt work in a later pass is reported, not blocked; a function that shipped wide open against a planned permission rule blocks from any pass, because that is a hole rather than a backlog. Writing a plan is its own seat: read `pikku-architect`. Building against one is `pikku-build`.
+`progress` reconciles the plan against pikku's generated meta — set membership, never anyone's status — and exits non-zero while the first pass is short, or while anything already built contradicts the plan. Unbuilt work in a later pass is reported, not blocked; a function that shipped wide open against a planned permission rule blocks from any pass, because that is a hole rather than a backlog. How a plan is written is `pikku-architect`; building against one, and the order plan-then-build, is `pikku-build`.
 
 ### A finished milestone is a tombstone