@pikku/skills 0.12.49 → 0.12.50

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

@@ -4,7 +4,7 @@ A scenario is a user journey run as one of your personas, over the real transpor
 persona's session. It is the only kind of test worth writing here, because a passing one proves the
 app works the way a signed-in person experiences it.
 
-The traps below all cost a real milestone a red run, and most of them are invisible on the run that
+The traps below all cost a real changeset a red run, and most of them are invisible on the run that
 introduces them. Read the section that matches what you are writing.
 
 1. [The shape of a scenario](#the-shape-of-a-scenario)
@@ -20,8 +20,8 @@ introduces them. Read the section that matches what you are writing.
 
 ## The shape of a scenario
 
-Three ship in `packages/functions/test/scenarios/` — keep them green — and every milestone's gherkin
-block from §5 becomes one more.
+Three ship in `packages/functions/test/scenarios/` — keep them green — and every scenario a
+changeset's plan names becomes one more.
 
 ```typescript
 import { pikkuScenario } from '#pikku/scenarios'
@@ -83,7 +83,7 @@ how the value stays inspectable when the step's output is what the scenario retu
 **Only `const`/`let`, `if`/`else`, `switch`, `for..of`, `return`, `throw` and workflow calls
 survive.** A counting `for` is refused by PKU679, and so is a `for..of` whose iterable is written
 inline — it must be a named identifier or a field (`data.items`). Bind the seat numbers, the ids,
-the rows to a `const` above the loop and iterate that. One milestone here lost a codegen round to
+the rows to a `const` above the loop and iterate that. One changeset here lost a codegen round to
 each half of that rule, because the first half does not imply the second.
 
 **Write each scenario's setup out in full rather than sharing a local helper.** A helper holding
@@ -137,7 +137,7 @@ one that archives a product unarchives it, the one that cancels a plan restarts
 second run starts where its first one stopped.
 
 **Run the suite twice and require the second run green.** A suite that only passes on a fresh
-database is a suite that passes once. Two corollaries, both of which cost a milestone a red run:
+database is a suite that passes once. Two corollaries, both of which cost a changeset a red run:
 
 - **Name nothing a setup step might already own.** `setsUpHerCompany` returns the company that actor
   already has rather than renaming it, so a later step passed the literal name it had asked for and
@@ -160,11 +160,11 @@ when a sweep surprises you, the next rule in the calendar is the first place to
 
 ## Steps rot as the app grows
 
-A step is shared, so it is the one thing in the suite that a milestone which never mentions it can
+A step is shared, so it is the one thing in the suite that a changeset which never mentions it can
 break. Whatever a step selects by, ask what ELSE will match it after the suite has run a hundred
 times.
 
-**Drive a new step from both sides in the milestone that adds it.** A step is only as proven as its
+**Drive a new step from both sides in the changeset that adds it.** A step is only as proven as its
 best-exercised branch: one here read the wrong field off a raw invocation (`attempt.data`; the
 payload is `attempt.body`), so its found-case could never pass — invisible for as long as every
 caller asked for ABSENCE.
@@ -175,9 +175,9 @@ moment a second function produces X: a renewal job that raised invoices broke th
 scenarios that had been green for months.
 
 **A selector on IDENTITY alone rots the same way once rows gain a lifecycle.** One reused the first
-licence assigned to an email regardless of its state, which was correct until a new milestone's
+licence assigned to an email regardless of its state, which was correct until a new changeset's
 refusal scenarios left that actor holding cancelled ones — it then handed back a dead licence, read
-as success, and failed a scenario two milestones older at a step that needed a live one.
+as success, and failed a scenario two changesets older at a step that needed a live one.
 
 **A step's input is a recorded contract, and it does not take a version.** Widening one — an extra
 optional field so a step can name a particular row — trips PKU861 exactly like a function's does,
@@ -218,10 +218,10 @@ Both are screen defects before they are test defects: a field whose label change
 and a list whose rows are indistinguishable to anyone on the phone to support.
 
 **A route nested under an existing screen is unreachable until its parent renders an `Outlet`.** A
-milestone added `/app/academy/$slug` under an `/app/academy` that already had a component of its
+changeset added `/app/academy/$slug` under an `/app/academy` that already had a component of its
 own; the parent swallowed the child, so the editor's URL rendered the list — every link, every route
 file and every type check looked right, and the only thing that noticed was a browser scenario that
-OPENED the child path and found the parent's controls on screen. When a milestone deepens a path an
+OPENED the child path and found the parent's controls on screen. When a changeset deepens a path an
 earlier one already owns, split the parent into a layout (`Outlet`) and an `index` route in the same
 change, and make one scenario open the child by path rather than reach it by clicking.
 
@@ -248,9 +248,9 @@ environment's `appUrls` map, so there is no second environment to run.
 browser pass needs the environment's `appUrl` and a browser driver installed — without them the run
 fails fast rather than half-running.
 
-**Run the whole suite, not the milestone's own scenarios.** The milestone's scenarios are the ones
+**Run the whole suite, not the changeset's own scenarios.** The changeset's scenarios are the ones
 you wrote to pass; the regression lives in someone else's. Tightening what "archived" means is a
-one-function change that reads as local and quietly breaks the milestone-01 scenario nobody re-ran.
+one-function change that reads as local and quietly breaks the first changeset's scenario nobody re-ran.
 
 **Restart the server after adding a function.** Hot reload does not register a new RPC and does not
 re-run `afterStart`, so a fresh function answers 404 and anything provisioned at boot is missing —
@@ -272,9 +272,9 @@ That writes `coverage/scenario-coverage.json` — which functions each journey e
 no scenario touches has never been run by anything but you, by hand, once.** It compiles, it
 typechecks, `pikku all` is happy, and nobody has proven it does what it says.
 
-Run it **as each milestone closes**, not once at the end. Coverage read per milestone is a short
-list you can act on — the milestone you just built either covered its own functions or it did not.
-Read for the first time after ten milestones it is a wall of red that nobody triages, and the honest
+Run it **as each changeset closes**, not once at the end. Coverage read per changeset is a short
+list you can act on — the changeset you just built either covered its own functions or it did not.
+Read for the first time after ten changesets it is a wall of red that nobody triages, and the honest
 response to a wall of red is to ignore it.
 
 Every gap is one of three things, and naming which is the point of looking:
@@ -285,8 +285,8 @@ Every gap is one of three things, and naming which is the point of looking:
 - **A function that should not exist** — nothing reaches it because nothing needs it. Delete it. An
   unused exposed function is also reachable over `POST /rpc/:rpcName`, so this is a security finding,
   not only dead weight.
-- **Genuinely deferred** — real, not yet reachable from the UI. Say so in the milestone note that
-  will cover it, so the gap is a decision rather than a hole.
+- **Genuinely deferred** — real, not yet reachable from the UI. File it as a change, so the gap is
+  a decision rather than a hole.
 
-Report the number when you hand the milestone over. A number nobody says out loud is a number nobody
+Report the number when you hand the changeset over. A number nobody says out loud is a number nobody
 acts on.

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

@@ -1,6 +1,6 @@
 # Shipping, and staying Fabric-ready
 
-Read this when the milestones are built and the scenarios are green — it is
+Read this when the changes queue is empty and the scenarios are green — it is
 the last phase, and nothing in it is needed before then.
 
 ## Ship it — open source, no platform
@@ -128,8 +128,8 @@ bun run build                     # every frontend workspace, type-checked
 ```
 
 Keep `--coverage` on the release run even though you have been reading it per
-milestone (§7a). Each of those readings only covered the functions that
-milestone added; this is the first time the whole surface is measured at once,
+changeset (§7a). Each of those readings only covered the functions that
+changeset added; this is the first time the whole surface is measured at once,
 and it is where a function orphaned by a later refactor shows up.
 
 **The last two lines are not optional, and one of them is easy to talk yourself
@@ -168,15 +168,15 @@ Everything above is open source. This is the contract that keeps
 - **One `definePersonas` call**, every persona reachable through exactly one
   frontend. Fabric materialises these as its virtual users; a persona nobody
   serves imports as a person with no way in.
-- **`knowledge/` passes `validate`, with every milestone at `built`.** This is
+- **`knowledge/` passes `validate`, and `pikku knowledge gaps` lists nothing.** This is
   the part Fabric itself reads and continues from.
-- **Every `built` milestone passes `pikku knowledge plan progress`.** A note that
-  says `built` is a claim; the plan reconciled against the generated meta is the
-  check. Anything the first pass still owes is either built now or deferred with
+- **Every plan under `knowledge/plans/` passes `pikku knowledge plan progress`.**
+  A merged changeset is a claim; the plan reconciled against the generated meta
+  is the check. Anything the first pass still owes is either built now or deferred with
   its reason on the record; anything the check calls a problem — something that
   exists and does not do what was planned — is fixed, whatever pass it came from,
   because deferring it defers a hole rather than the work.
-- **Every milestone has a passing scenario**, including its refusals.
+- **Every changeset has a passing scenario**, including its refusals.
 - **Permissions live in the `permissions` field**, not in function bodies and not
   in the frontends. A check hidden in a component does not survive a new client.
 - **Nothing hardcodes a host, a port, or a `process.env` read inside a

package/skills/pikku-changes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-changes
-description: 'Work a Fabric project''s changes queue — the todo list someone filed by circling things on a deployed stage. Covers `pikku fabric changes next|claim|show|ask|reply|shot|done`: waiting for work without polling, asking instead of guessing, saying why an item is left undone, offering options as images, one commit per item. TRIGGER when: the user says "run the pikkufabric changes", "run the changes against <stage>", "work the changes (queue)", "watch the changes", "pick up the changes", names a change by its #number, or you are otherwise idle in a checkout linked to a Fabric project (`pikku fabric config` shows one). DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage — use pikku-fabric for those.'
+description: 'Work a project''s changes queue — the todo list someone filed by circling things on a deployed stage. Covers `pikku changes wait|claim|show|ask|reply|shot|done`: waiting for work without polling, asking instead of guessing, saying why an item is left undone, offering options as images, one commit per item. TRIGGER when: the user says "run the pikkufabric changes", "run the changes against <stage>", "work the changes (queue)", "watch the changes", "pick up the changes", names a change by its #number, or you are otherwise idle in a checkout with open changes (`pikku changes list`). DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage — use pikku-fabric for those.'
 installGroups: [fabric]
 ---
 
@@ -10,60 +10,107 @@ Someone walked the deployed app and circled things. Each item is their words, a
 screenshot of what they saw, and the elements the circle enclosed. You have the repo.
 Empty the queue without making them regret filing.
 
-Run every command from the checkout: the project comes from its git remote (`pikku fabric config` shows which).
+Run every command from the checkout. The queue lives in it (`.git/pikku-changes.json`, shared by every
+worktree). When you are logged in to Fabric and the checkout is linked to a project (`pikku fabric config`
+shows which), every write is also registered with Fabric.
 `--json` works on all of them. Items are addressed as `2`, `#2` or their uuid.
 
-## Which stage
-
-The queue is per project. "Against develop" or a pasted stage URL narrows it:
-`--stage` takes a branch, the stage URL (as filed, path optional) or a stage id. With
-no stage named, work the whole project. An unknown name prints the stages there are.
+**Launched by `pikku changes next`?** `pikku changes next` picks one agent: a merge conflict or a changeset with no plan
+goes back to a changes agent; open changes go to a changes agent; a pikku version bump goes to an
+upgrade agent, and knowledge no change builds yet (`pikku knowledge gaps`) to a knowledge agent — both
+of those only file changes. A change filed for a gap ends its body with the gap's `Knowledge:` line.
+As a changes agent, your work file already lists every open change. Skip the loop below,
+group them into changesets, and take one: claim it, build it, mark its items done, stop. `pikku changes next --loop`
+starts a fresh agent for the next one, so nothing you hold in context carries over — whatever the next
+changeset needs to know goes in a commit or a `reply`.
 
 ## The loop
 
 **Never poll.** No `sleep` loops, no repeated `list`, no re-running `show` to see if
-something changed. `next` does the waiting and exits only when there is work.
+something changed. `wait` does the waiting and exits only when there is work.
 
-1. Start `next` as a **background** command, and stop there until it exits:
+1. Start `wait` as a **background** command, and stop there until it exits:
 
    ```bash
-   pikku fabric changes next --stage develop --claim --claimed-by claude-code
+   pikku changes wait --claim --claimed-by claude-code
    ```
 
    It waits out the grace window (a just-filed item is held about a minute so a batch
    being typed arrives together), claims what is ready as one group, prints it, and
    exits. It also wakes when someone answers a question you asked under that
-   `--claimed-by`. It is woken by fabric's change events the moment an item is filed
-   or answered, and sleeps exactly until a held item becomes claimable; when the event
-   stream is unavailable it falls back to checking every `--interval` seconds.
+   `--claimed-by`. It checks every `--interval` seconds.
 
 2. When it exits, read the exit code:
 
    | code | meaning                                                | do                                              |
    | ---- | ------------------------------------------------------ | ----------------------------------------------- |
    | 0    | work printed (claimed, and/or `Answered`)              | work it, then step 3                            |
-   | 2    | `--timeout`/`--once` found nothing                     | stop, or restart `next`                         |
+   | 2    | `--timeout`/`--once` found nothing                     | stop, or restart `wait`                         |
    | 3    | session refused                                        | tell the user to run `pikku fabric login`; stop |
-   | 1    | anything else (bad `--stage`, fabric down for minutes) | report the message; stop                        |
+   | 1    | anything else                                          | report the message; stop                        |
 
 3. For each item: `show` → fix → commit → `done`; or `ask` and move on; or `reply`
-   saying why you are leaving it. Then start `next` again, in the background.
+   saying why you are leaving it. Then start `wait` again, in the background.
 
 Without `--claim` it only reports what is claimable; claim it yourself:
 
 ```bash
-pikku fabric changes claim --change-ids 3,4 --title "Checkout pass" --claimed-by claude-code
+pikku changes claim --change-ids 3,4 --title "Checkout pass" --claimed-by claude-code
 ```
 
 A `claim` refused with a 409 says per item why — held for the filer, inside another
 group's lease, done — and when a held or leased item is **claimable at** (a local
 `HH:MM`; `list` and `show` print the same). An item inside someone else's live lease
-cannot be taken. For held items, run `next --claim` rather than retrying. The lease is 30 minutes
+cannot be taken. For held items, run `wait --claim` rather than retrying. The lease is 30 minutes
 (`--lease-minutes`); an abandoned claim returns to the queue by itself.
 
+## Changesets
+
+Group related items into changesets and claim each one as a group, saying which tables it touches —
+the entity notes' `resource:` lines name them:
+
+```bash
+pikku changes claim --change-ids 1,3 --title "Waitlist" --claimed-by pi --creates waitlist --reads booking
+```
+
+The claim says whether the changeset needs a plan, and why: one that creates or alters a table, or
+has many changes, always does; anything else goes to the judge configured with
+`PIKKU_PLAN_JUDGE_URL` (any endpoint answering `{verdict, reason}` to `{question, context}`), and a
+judge that fails says plan. With no judge configured only the fixed rules apply. `--needs-plan
+true|false` overrides all of it.
+
+A planned changeset is planned before any code, with the pikku-architect skill:
+`pikku knowledge plan set <groupId> <file>` writes `knowledge/plans/<groupId>.plan.json`; commit it on
+the changeset's branch. `done` refuses the first change until the plan reads and the last until
+`pikku knowledge plan progress <groupId>` is clean, and `pikku changes next` will not merge a planned
+changeset whose branch has no plan.
+
+Build each changeset on its own branch, `changeset/<slug>`, cut from the branch you started on, one
+commit per item (see Committing), and mark each item `done`. Launched by `pikku changes next`, stop there:
+it merges finished changesets itself, as one `--no-ff` commit with a `Changeset:` trailer, and if the
+merge conflicts it hands that back to an agent to resolve on the changeset's branch. Working by hand,
+merge it yourself from the branch it goes into:
+
+```bash
+pikku changes merge --group-id <id>
+```
+
+Never `git merge` a changeset branch yourself — a fast-forward leaves no changeset commit, and
+`changes merge` refuses a branch that is already in.
+
+Changesets that create or alter tables go one at a time; one that reads a table waits for the
+changeset creating it; the rest can run side by side. On the local queue, `claim` refuses a changeset
+that would break that order, and `done` refuses a commit that adds a migration under `db/` when its
+changeset declared no `--creates`/`--alters`.
+
+When other agents are working changesets at the same time (your work says so), claim with
+`--worktree`: it creates `changeset/<slug>` in its own checkout beside the repo and prints the path.
+Build and commit there and run `done` there; the merge removes the worktree. If the claim is refused because of a running changeset, claim one that does not
+clash, or stop.
+
 ## Reading an item
 
-`pikku fabric changes show 3` gives, most trustworthy first:
+`pikku changes show 3` gives, most trustworthy first:
 
 1. **Their words.** The title and body are the requirement. Everything else is evidence.
 2. **The screenshot.** What they saw, at their width, with their data. When the other
@@ -84,11 +131,11 @@ One decision, in their vocabulary, with the choices as `--option` flags — each
 a button. Include "hold until I check" when it is real. Batch questions per group.
 
 ```bash
-pikku fabric changes ask --change-id 3 --question "Make the total stand out — which way?" \
+pikku changes ask --change-id 3 --question "Make the total stand out — which way?" \
   --option "Bigger" --option "Move it above the delivery line" --author-name claude-code
 ```
 
-Then **park it** and move on. The answer wakes `next` (same `--claimed-by`); it prints
+Then **park it** and move on. The answer wakes `wait` (same `--claimed-by`); it prints
 under `Answered`, and `show` has the reply.
 
 If the answer is visual and you can build it, build each variant, screenshot all of
@@ -96,7 +143,7 @@ them in one pass at one width (baseline included), and attach them — the panel
 `--kind option` shots into a pick-one:
 
 ```bash
-pikku fabric changes shot --change-id 3 --label "Bigger" --kind option --image a.png
+pikku changes shot --change-id 3 --label "Bigger" --kind option --image a.png
 ```
 
 `--kind evidence` is a picture that proves something, shown inline.
@@ -112,7 +159,7 @@ item's status exactly where it was:
 - you could not reproduce it — attach what you saw.
 
 ```bash
-pikku fabric changes reply 3 --message "Cannot reproduce on develop @ a91c4e2 — this is what I see." \
+pikku changes reply 3 --message "Cannot reproduce on develop @ a91c4e2 — this is what I see." \
   --image seen.png --image-label "develop @ a91c4e2" --author-name claude-code
 ```
 
@@ -135,12 +182,11 @@ Scope names the screen they were looking at, not the file you edited.
 ## Finishing
 
 ```bash
-pikku fabric changes done --change-id 7 --note "What you did, for whoever reads the thread"
+pikku changes done --change-id 7 --note "What you did, for whoever reads the thread"
 ```
 
-Branch and commit default to the checkout you are in — run it there, never type a sha.
+Branch and commit default to the checkout you are in — run it there, never type a sha. `done` finds the item's commit by its `Change-Id` trailer, so close items in any order.
 An item you decided not to do is not `done`: `reply` with why and leave it for a
 human to dismiss.
 
-Writes need the `changes:project:write` scope; `list`, `show` and `next` without
-`--claim` are reads.
+Registering writes with Fabric needs the `changes:project:write` scope.

package/skills/pikku-knowledge/SKILL.md

@@ -4,11 +4,11 @@ description: >-
   Use when writing, reading, reorganising or validating a project's knowledge/ directory — the
   notes that say what the app is, in the language its users use. Covers the Open Knowledge Format
   note (path-as-identity markdown, YAML frontmatter, only `type` required), the app-project
-  profile's sections (milestones, entities, decisions, questions, wishlist) and what each answers,
-  milestone status/entities/gherkin rules, the `resource:` URI scheme tying a note to its code,
-  what is NOT a knowledge base, and `pikku knowledge validate|index`. TRIGGER when: user asks to
+  profile's sections (entities, decisions, questions, wishlist) and what each answers, how notes
+  become changes (`pikku knowledge gaps`), the changeset plan, the `resource:` URI scheme tying a
+  note to its code, what is NOT a knowledge base, and `pikku knowledge validate|index|gaps`. TRIGGER when: user asks to
   write down a decision, requirement, entity or open question; asks what the app does or is; asks
-  about knowledge/, notes, milestones, an index.md, or a diagram, callout or decision block; or
+  about knowledge/, notes, an index.md, or a diagram, callout or decision block; or
   hands over a product brief to record. DO NOT TRIGGER when: user asks what functions, routes,
   tables or permissions exist (that is `pikku meta` / `pikku info`, never a note), or to write a
   scenario test (use pikku-scenario).
@@ -75,7 +75,7 @@ Frontmatter fields:
 
 | Field         | Meaning                                                                                                                 |
 | ------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `type`        | **The only required field.** One of `milestone`, `entity`, `decision`, `note`, `overview`. Lowercase — every gate compares it literally, and `milestone` is the exact string `readMilestones` filters on, so a near-miss is a note no command can see. |
+| `type`        | **The only required field.** One of `entity`, `decision`, `note`, `overview`. Lowercase — every gate compares it literally, so a near-miss is a note no command can see. |
 | `title`       | What to call the note in a listing. Falls back to the first heading, then the filename.                                 |
 | `description` | One line, used as the note's subtitle in a section index.                                                               |
 | `resource`    | Comma-separated `<kind>:<id>` URIs — the code this note is about. See below.                                            |
@@ -91,9 +91,6 @@ Plain markdown links between notes — `[revocation](../decisions/revocation-end
 ```
 knowledge/
   index.md                                  # type: overview — the map
-  milestones/
-    index.md
-    01-the-daily-entry.md                   # type: milestone
   entities/
     index.md
     entry.md                                # type: entity
@@ -115,7 +112,6 @@ Each section answers exactly one question, which is what lets a reader find a no
 
 | Section               | The question it answers                                            |
 | --------------------- | ------------------------------------------------------------------ |
-| `milestones/`         | What is one buildable piece of this app, and what proves it works? |
 | `entities/`           | What is this thing, in the words users use for it?                 |
 | `decisions/`          | What was chosen, and what does that rule out?                      |
 | `decisions/security/` | Who may do what?                                                   |
@@ -124,36 +120,31 @@ Each section answers exactly one question, which is what lets a reader find a no
 
 **Create a section the turn you have a note for it** — never a scaffold of empty directories, and never a section without its own `index.md`. A section index says in one line what belongs in it; that sentence is the reason the file exists, so `pikku knowledge index` writes only the note listing and leaves your prose alone.
 
-## Milestones
-
-A milestone is the one note type that is a piece of _work_ rather than a fact, so it alone carries state and size. It lives in `knowledge/milestones/` and nowhere else: `readMilestones` matches on that directory literally, so the same note under another section is invisible to every gate and command below.
+## Work is changes, not notes
 
-````markdown
----
-type: milestone
-title: The daily entry
-description: An owner writes one entry per day, and sees it on the day.
-status: proposed
-entities: entry, day
-resource: func:createEntry
----
+The base says what the app IS. What still has to be built is not written here: it is filed as
+**changes** on the project's queue (`pikku changes file`), grouped into changesets, and built
+one commit per change — the pikku-changes skill. A note never carries status, size or a gherkin
+block; a behaviour the app must have is a sentence in the note it is about.
 
-# The daily entry
+```bash
+pikku knowledge gaps            # the notes no change builds yet
+```
 
-An owner writes at most one entry per day. Writing again replaces it.
+`gaps` compares the notes against the plans of merged changesets and the changes already filed:
 
-```gherkin
-Given 'owner' has no entry for today
-When 'owner' writes one
-Then it appears on today's day
-And writing again replaces it rather than adding a second
-```
-````
+- **`uncovered`** — no plan covers the note.
+- **`changed`** — the note was edited after the changeset that built it merged.
+- **`partial`** — it merged with items deferred; they are listed.
+- **`removed`** — code a merged changeset built for the note is gone from the generated meta.
+- **`deleted`** — the note is gone and the code a changeset built for it is not.
 
-- **`status`** is `proposed` → `dispatched` → `built`. Nothing else — `MILESTONE_STATUSES` is those three, and every gate compares them literally, so an invented status fails `validate` rather than degrading. Only `proposed` is dispatchable. A profile may add one of its own ahead of `proposed` for work that is written down but must not be built yet; that is the profile's to define and validate, not core's.
-- **`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 milestone 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.
+The first three are work: file a change for each, and end its body with the gap's
+`Knowledge: <note>@<hash>` line so it is not filed again. The last two mean the code and the
+knowledge disagree about something that was built — read `git log` for who removed it and why, then
+either bring the knowledge into line (edit or delete the note, or file a change that removes the
+code) or file a change that restores it. When you cannot tell which, file the change and ask on it.
+`pikku changes next` hands open gaps to a knowledge agent when there is nothing else to do.
 
 ## Showing it
 
@@ -230,7 +221,7 @@ These are all things that exist somewhere better, so a note is always the copy t
 | Do not write                        | Because it lives in                                        |
 | ----------------------------------- | ---------------------------------------------------------- |
 | a `personas/` section               | `definePersonas()` in the project's own code               |
-| a `scenarios/` section              | the gherkin block inside the milestone it belongs to       |
+| a `scenarios/` section              | the `scenarios` of the plan for the changeset that builds it |
 | a `permissions/` section            | a decision note under `decisions/security/`                |
 | a list of tables, columns or routes | `pikku meta` — the generated schema _is_ the schema        |
 | a changelog                         | `CHANGELOG.md` at the repo root                            |
@@ -249,66 +240,35 @@ pikku knowledge index           # refresh every index.md
 pikku knowledge index --check   # report stale indexes without writing (CI gate)
 ```
 
-`validate` reports: notes with no `type`, a missing `knowledge/index.md`, a section with no `index.md`, notes flat at the root, sections that duplicate what the project already declares, milestones with a bad or missing `status`, milestones over three entities, milestones with no gherkin block or a first-person one, `decision` fences that state no `chosen:` or rule nothing out, and every `resource:` that no longer resolves. Errors fail the command; warnings do not.
+`validate` reports: notes with no `type`, a missing `knowledge/index.md`, a section with no `index.md`, notes flat at the root, sections that duplicate what the project already declares, plans under `knowledge/plans/` that do not read or contradict themselves, `decision` fences that state no `chosen:` or rule nothing out, and every `resource:` that no longer resolves. Errors fail the command; warnings do not.
 
 `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.
+### The changeset plan
 
-`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.
-
-### 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:
+A changeset that creates or alters a table, or that the judge says needs one, is planned before any
+of its code. The **plan** — JSON at `knowledge/plans/<changeset>.plan.json`, committed on the
+changeset's branch — says what has to exist for it, which notes it `covers`, and is what a finished
+build is measured against:
 
 ```bash
 pikku knowledge plan schema                        # the format, in full
-pikku knowledge plan set <milestone> <file>        # validate and write it
-pikku knowledge plan show <milestone> --for-build  # the ordered work a build follows
-pikku knowledge plan progress <milestone>          # what it still owes, read from .pikku/
-pikku knowledge plan defer <milestone> <item> -r "<why>"
+pikku knowledge plan set <changeset> <file>        # validate and write it
+pikku knowledge plan show <changeset> --for-build  # the ordered work a build follows
+pikku knowledge plan progress <changeset>          # what it still owes, read from .pikku/
+pikku knowledge plan defer <changeset> <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. 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
-
-**Once a milestone reaches `built`, its note and its plan are closed. Do not edit either.** Not to correct the wording, not to fold in what the build actually turned out to need, not to add the item everyone agrees should have been there. A finished milestone is the record of what was agreed and what was measured against it, and a record that can be revised afterwards measures nothing.
-
-This is the rule the shape of the thing already implies. `progress` reconciles a plan against generated meta and fails when what shipped contradicts it — a check with no force at all if the losing side of the contradiction may simply be rewritten. `attempts:` brakes a note nothing can satisfy, and refunds that budget when the note's content really changes; a `built` note that keeps changing is that brake removed. Both only work while the plan stays still.
+`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 is `pikku-changes`, whose `done` refuses the last change of a planned changeset until `progress` is clean.
 
-So when a `built` milestone turns out to be wrong or incomplete, **the answer is always a new note, never an edit to the old one**:
+### A merged plan is a tombstone
 
-- It needed more than it said → a new milestone, which may name the old one.
-- It was built differently than planned → that is what `progress` is for. Reconcile forward, or record a decision saying why the plan was not the right shape.
-- It was simply wrong → a decision note that supersedes it. The wrong milestone stays where it is; a base whose history is edited cannot answer *why* anything is the way it is, which is most of what a base is for.
+**Once a changeset merges, its plan is closed. Do not edit it.** Not to correct the wording, not to fold in what the build actually turned out to need. A merged plan is the record of what was agreed and what was measured against it, and a record that can be revised afterwards measures nothing.
 
-The exception, and it is narrow: bookkeeping the loop owns. `statusAt:` and `attempts:` are written by whatever moved the note, at any status, and are bookkeeping rather than content. Nothing else about a `built` note moves again.
+Notes are different: they say what the app is now, so they change whenever it does. Editing a note a merged changeset covered is exactly how new work arrives — `gaps` reads it as `changed`, and it is filed again.
 
 ## Profiles built on this one
 
 OKF permits frontmatter fields a reader does not know, and the parser ignores them rather than failing. That is the extension point: a tool layered on Pikku can add its own sections and fields on top of everything above without forking the format.
 
-Fabric is the one that exists. It adds `decisions/design/` — rules about how the app looks and behaves — a `screens/` section, and a `design:` field on a milestone pointing at the design options it was built from. Both are Fabric's to validate; `pikku knowledge validate` passes them through untouched. Everything else in this skill is the same in both.
+Fabric is the one that exists. It adds `decisions/design/` — rules about how the app looks and behaves — and a `screens/` section. Both are Fabric's to validate; `pikku knowledge validate` passes them through untouched. Everything else in this skill is the same in both.