@pikku/skills 0.12.49 → 0.12.50

package/package.json

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

package/skills/pikku-addon/references/openapi.md

@@ -126,5 +126,5 @@ on their tracker is a public post.
 ## Then
 
 Go back to the mode you were building in (`pikku-build`). The addon is a
-dependency of the app, not the app: plan milestones around what the user wants
+dependency of the app, not the app: plan changes around what the user wants
 to do with the API, and reach the operations through `ref()`.

package/skills/pikku-architect/SKILL.md

@@ -1,16 +1,15 @@
 ---
 name: pikku-architect
 description: >-
-  Use to turn one settled milestone note into the technical plan the build is measured against —
+  Use to turn one claimed changeset into the technical plan its 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`. 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),
-  the plan already exists and the job is to build it (use pikku-build), or the ask is a one-off
-  edit to a working app.
+  written through `pikku knowledge plan set <changeset>`. The plan is the denominator
+  `pikku knowledge plan progress` divides by, so it is written BEFORE any of the changeset's code
+  exists and never edited afterwards to match what got built. TRIGGER when: `pikku changes
+  claim` says a changeset needs a plan, `changes done` or `pikku changes next` refuses one for having no
+  plan, or the user asks to plan or architect a changeset. DO NOT TRIGGER when: the knowledge notes
+  themselves are still being written (use pikku-knowledge), the plan already exists and the job is
+  to build it (use pikku-changes), or the changeset was claimed with no plan needed.
 installGroups: [core]
 agent:
   tools: read, write, edit, bash, grep
@@ -21,45 +20,51 @@ agent:
     verify:
       - id: knowledge-consistent
         command: pikku knowledge validate
-      - id: plan-accepted
-        command: pikku knowledge next --require dispatch,idle
 
 ---
 
-# Plan one milestone
+# Plan one changeset
 
-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. This is where how gets decided, once, in writing, before any of
+A changeset's changes say what the app must DO, in the words of the person who filed them, and the
+knowledge notes say what the app is. Neither says how. This is where how gets decided, once, in writing, before any of
 it is built.
 
 **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
+is written against the changes, 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 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.
+**One changeset, one plan, then build it.** Do not plan another changeset "while you are here" —
+its changes are still allowed to move, and a plan written against work that later moves is worse
+than no plan.
+
+**When a changeset needs one.** `changes claim` decides: a changeset that creates or alters a table,
+or one with many changes, is planned; anything else is put to the configured judge, and a judge that
+fails says plan. The claim prints which, and why. `changes done` then refuses the first change of a
+planned changeset until its plan reads, and the last until the plan's first pass exists; `pikku changes next`
+will not merge it without the plan on its branch.
 
 ---
 
 ## Write nothing by hand
 
-The plan reaches disk through `pikku knowledge plan set <milestone> <file>` and nowhere else. It
+The plan reaches disk through `pikku knowledge plan set <changeset> <file>` and nowhere else —
+`knowledge/plans/<changeset>.plan.json`, where `<changeset>` is the group id the claim printed.
+Commit it on the changeset's branch, before the first change, so it merges with the code it
+describes. It
 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
+It is also written ONCE. `plan set` refuses a changeset 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>`,
+way down from a written plan is `pikku knowledge plan defer <changeset> <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
-its status leaves `proposed`, so rewriting it would change what the builder was told.
+heading silently passes.
 
 ## Send it. Do not go looking.
 
@@ -87,38 +92,41 @@ pikku meta context --json         # what the app already declares
 pikku knowledge plan schema       # the only spec for what you are about to write
 ```
 
-Then read, in the tree: the milestone's own note in full, every note it names on `entities:` and
-`requires:`, the decisions that constrain it, and the migrations already in `db/sqlite/` — those
-say whether your tables are new or an alter.
+Then read the changeset's changes in full (`pikku changes show <n>` for each), every
+knowledge note they touch — the entity notes, and the note a change's `Knowledge:` line names — the
+decisions that constrain them, and the migrations already in `db/sqlite/`: those say whether your
+tables are new or an alter.
 
-**Do not re-interview.** If the note leaves something genuinely undecided, plan the reading that
-builds LESS. A smaller milestone that ships is worth more than a complete one that does not, and
-what you leave out is named in `covers` for the next milestone to pick up.
+**Do not re-interview.** If a change leaves something that alters the schema or a screen genuinely
+undecided, `pikku changes ask` on it and plan the rest; otherwise plan the reading that
+builds LESS. A smaller changeset that ships is worth more than a complete one that does not, and
+what you leave out is named in `covers` for the next changeset to pick up.
 
 ### 2. Decide the passes
 
-A pass is a slice of the milestone that stands up on its own. **Pass 1 is a walking skeleton**: it
+A pass is a slice of the changeset that stands up on its own. **Pass 1 is a walking skeleton**: it
 reaches a real screen, with real functions behind it, proved by a real browser scenario. Everything
 else waits behind it.
 
 This is enforced, not advisory — `plan set` refuses a plan whose pass 1 has no `ui` item, no
 `functions` item, or a pass-1 route with nothing proving it works. The reason is the failure it was
-written against: a milestone that built four unwired functions and no page, and reported itself
+written against: a changeset that built four unwired functions and no page, and reported itself
 finished. A build that runs out of time in pass 2 has shipped something; one that runs out of time
 having built pass 1 across four half-finished layers has shipped nothing.
 
 **Only pass 1 blocks.** `pikku knowledge plan progress` reports a later pass under `deferred` and
 never refuses on it. That is what stops plan size from being fatal — but it is not licence to plan
-a milestone nobody could finish. The question that decides a plan's size is not "what does this
+a changeset nobody could finish. The question that decides a plan's size is not "what does this
 note imply" but **"could a build finish all of this if pass 1 took twice as long as I expect"** — if
-not, it is two milestones. Plan the first, and say in `covers` what you left behind.
+not, it is two changesets. Plan the first, and say in `covers` what you left behind.
 
-**A screen is what pass 1 reaches only when the milestone IS an app.** The note's `surface:` says
-which it is — absent means an app, and `cli`, `mcp`, `agent` and `backend` are the others. On those,
+**A screen is what pass 1 reaches only when the changeset reaches people through an app.** The
+plan's `surface` says which — `app` by default, and `cli`, `mcp`, `agent` and `backend` are the
+others. On those,
 `ui` is legitimately `n/a` (with its reason, like any slot), and pass 1 proves itself one level
 down: a pass-1 function that is actually wired, and a `scenarios.backend` item carrying that
-function's name in its `fn` field. The obligation never lifts, it only moves — read the surface off
-the note before you decide the passes.
+function's name in its `fn` field. The obligation never lifts, it only moves — decide the surface
+before you decide the passes.
 
 ### 3. Say what each slot is, or say why it is nothing
 
@@ -133,7 +141,7 @@ app is the same kind of person" and "nobody thought about roles" must not look a
 ### 4. Write it
 
 ```sh
-pikku knowledge plan set <milestone> /tmp/plan.json
+pikku knowledge plan set <changeset> /tmp/plan.json
 ```
 
 Write the JSON to a file first — the command takes a path, not inline JSON, which is what keeps an
@@ -144,7 +152,7 @@ not read.
 Then confirm what the builder will be handed:
 
 ```sh
-pikku knowledge plan show <milestone> --for-build
+pikku knowledge plan show <changeset> --for-build
 ```
 
 ---
@@ -156,19 +164,19 @@ inventories every function, wire, scope, role, workflow, agent and scenario. Not
 duplicates that — only what codegen cannot infer: **why a thing exists, which pass it belongs to,
 and which knowledge note it discharges.**
 
-### `covers` — which notes this milestone discharges
+### `covers` — which notes this changeset discharges
 
 Every plan claims at least one knowledge note: `note` (its path under `knowledge/`), `hash` (what
 that note's body hashes to right now) and `complete`.
 
-`complete: false` is the honest answer for a note whose claims span several milestones — claim the
-whole of a note only when this milestone genuinely leaves nothing of it unbuilt, because a note
+`complete: false` is the honest answer for a note whose claims span several changesets — claim the
+whole of a note only when this changeset genuinely leaves nothing of it unbuilt, because a note
 marked complete is a note nobody looks at again.
 
 **You do not have to compute the hash.** Write anything twelve characters long and send the plan:
 `plan set` refuses a hash that is not the note's current one and names the correct one, so one
 round trip gets you every hash in the plan. That refusal is the point of the field — a hash that
-was never right makes the note read as edited-since from the moment the milestone ships, and it
+was never right makes the note read as edited-since from the moment the changeset ships, and it
 drops back into a backlog nobody planned.
 
 ### `model` — tables, and what their columns HOLD
@@ -197,7 +205,7 @@ parallel lists are two lists that drift.
 and the client calls it by name, so for nearly every function there is nothing to decide — leave the
 field out. A `wire` is for the exceptions: its own HTTP path via `wireHTTP` (a webhook, a payment
 callback, a public URL another system posts to), a queue job, a channel, a scheduled task, or a
-workflow entry point. Those last two are not alternate URLs — they are what the milestone IS, and a
+workflow entry point. Those last two are not alternate URLs — they are what the changeset IS, and a
 plan that omits them ships a `status` column nothing advances or a job nobody runs.
 
 A wire is also a constraint on the function's SHAPE, not only an address for it. `wireScheduler`
@@ -221,7 +229,7 @@ permission scenario naming it in `fn`** — a rule with no failing case is a cla
 A scope depends ONLY on the session: "may this kind of user do this at all" — `admin:invoices:void`,
 `billing`. It is declared with `wireScope` and granted in `mapSession`, so every name here has to
 end up in pikku's generated scope meta. One that cannot be declared is one the build can never
-finish, and `plan progress` refuses the milestone for as long as it stands.
+finish, and `plan progress` refuses the changeset for as long as it stands.
 
 Ownership is not a scope. "Only the owner of the house may read it" depends on the row being asked
 for, and a scope never sees the row — that is the function's `permission` sentence and lives nowhere
@@ -240,7 +248,7 @@ reach two, and never give a slug to someone who never signs in: a guest checking
 slug as the seller they buy from, on that app's public routes outside `/app`. Once there is more
 than one app, every `ui` item carries its `app` too.
 
-Adding the second frontend is the BUILD's job, at the milestone that first needs it —
+Adding the second frontend is the BUILD's job, at the changeset that first needs it —
 pikku-build's multi-app reference. Your part is recording which app each person is in.
 
 ### `ui` — routes, and what is on them
@@ -254,7 +262,7 @@ counts — an unlinked browser scenario reads as a route nobody proved, and the
 
 `backend`, `browser`, `permission`, each its own slot. Keyed rather than tagged so that a plan with
 four backend scenarios and no browser scenario fails on its SHAPE — a flat list lets that through,
-and that is exactly the milestone that builds an API and ships no screen.
+and that is exactly the changeset that builds an API and ships no screen.
 
 **Every scenario needs `name`: the `pikkuScenario` export it becomes** (`saveEntryScenario`).
 `feature` and `scenario` are prose for a reader, and prose cannot be matched against codegen.
@@ -262,7 +270,7 @@ and that is exactly the milestone that builds an API and ships no screen.
 cannot see.
 
 Permission scenarios default to pass 2 — they harden a journey that has to exist before they can
-cover it — so a role × resource cross product there costs the milestone nothing.
+cover it — so a role × resource cross product there costs the changeset nothing.
 
 ---
 
@@ -270,10 +278,10 @@ cover it — so a role × resource cross product there costs the milestone nothi
 
 `plan set` catches the mechanical failures — a missing slot, a bad hash, a pass 1 with no `ui` item.
 Read your draft back against these six questions, which it cannot ask. Each has cost a real
-milestone; **[references/plan-defects.md](references/plan-defects.md)** carries the case behind every
+changeset; **[references/plan-defects.md](references/plan-defects.md)** carries the case behind every
 one, and is worth opening for any question you cannot answer with a flat yes.
 
-1. **Is this a plan for THIS note?** Every entity the note names appears in a function or a table.
+1. **Is this a plan for THESE changes?** Every entity the changes and their notes name appears in a function or a table.
 2. **Does pass 1 slice, and does the model fit inside it?** Not "pass 1: the data model, pass 2: the
    API" — and `model` holds only the tables pass 1 or 2 actually migrates, because the model slot has
    no passes and a later table is a PROBLEM from the first day.
@@ -283,7 +291,7 @@ one, and is worth opening for any question you cannot answer with a flat yes.
 4. **Does something produce every state and field the plan reads?** For each clause of a description,
    each screen the opening paragraph names, each field you filter or badge on, and each state a
    scenario waits in — name the function that gets the world there. A producer you are reusing is
-   checked against code that already exists; a producer this milestone is adding is checked against
+   checked against code that already exists; a producer this changeset is adding is checked against
    the plan that adds it. What is never allowed is a state with no named producer at all.
 5. **Can two sentences in the plan both be true?** Write a state machine out once as a table in
    `model`, name who sets and reads every clock in it, and say whether saving a child collection
@@ -295,7 +303,8 @@ one, and is worth opening for any question you cannot answer with a flat yes.
 
 ## When you are done
 
-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.
+The accepted `plan set` is the end of planning. Commit the plan file on the changeset's branch, then
+go straight on to the build in `pikku-changes`: read the plan with `plan show --for-build`, build it
+one commit per change, and mark the last change done only when `pikku knowledge plan progress` is
+clean — `changes done` checks the same thing and refuses until it is. What you wrote is what you are
+measured against, so do not touch it once the first migration is open.

package/skills/pikku-architect/references/plan-defects.md

@@ -1,7 +1,7 @@
 # What makes a plan wrong
 
 `plan set` catches the mechanical failures — a missing slot, a bad hash, a pass 1 with no `ui`
-item. These are the ones it cannot, each carried back from a milestone that shipped it. They are
+item. These are the ones it cannot, each carried back from a changeset that shipped it. They are
 grouped by the question that finds them, and the fastest way to use this file is to read the six
 questions and only open the group that worries you.
 
@@ -27,11 +27,11 @@ questions and only open the group that worries you.
 screens" is three passes of nothing working.
 
 **Put in `model` only the tables pass 1 — or at worst pass 2 — actually migrates.** The model
-slot has no passes: every item is checked from the moment the milestone starts, so a table whose
+slot has no passes: every item is checked from the moment the changeset starts, so a table whose
 migration belongs to pass 3 is a PROBLEM from pass 1, and `plan progress` refuses on a problem
-rather than deferring it. A milestone that finishes pass 1 green then cannot be closed, and every
+rather than deferring it. A changeset that finishes pass 1 green then cannot be closed, and every
 fix is outside the build's hands. When a later pass needs its own tables, that is the signal it is
-a second milestone — say so in `covers`.
+a second changeset — say so in `covers`.
 
 ---
 
@@ -46,7 +46,7 @@ scenario cannot perform. Signed-out is a BROWSER fact.
 `saveEntry` returns 200 proves the wire. The one worth planning is the one where a person writes
 something, comes back, and it is still there. A browser scenario that opens a page and asserts it
 is still on it proves the route loads and nothing else — `plan progress` names it a problem and
-refuses the milestone.
+refuses the changeset.
 
 **Write summary and dashboard scenarios as deltas.** The suite runs against a live database nobody
 resets, so "the payment-failed count is zero, then one" is a claim about every run that came
@@ -63,7 +63,7 @@ same way you read it against the functions.
 **Write every refusal as "X, which is `<state>`, is refused because `<rule>`" — then check that
 state against the rule you wrote in the same plan.** A refusal claims two things at once: that the
 rule shuts, and that the described situation reaches the shut state. One plan asked for "a paused
-licence is refused the academy" in the same milestone whose gate admitted `active_until_expired`,
+licence is refused the academy" in the same changeset whose gate admitted `active_until_expired`,
 which is exactly what pausing inside the paid period produces. The scenario could only ever have
 asserted a bug.
 
@@ -77,7 +77,7 @@ decision that nothing records.
 **Every clause of a `feature` or `scenario` description has to be performed by a function** — one
 in this plan, or one already in the meta. Write "when the distributor is removed its companies
 fall back to the direct catalog" with no function that removes a distributor and `plan set`
-accepts it, `plan progress` passes, and the milestone ships a sentence nothing proves. Read each
+accepts it, `plan progress` passes, and the changeset ships a sentence nothing proves. Read each
 description back asking *which function does this*, and cut the half you cannot name.
 
 **Where a scenario calls the same function twice, check it for a per-period guard first.** A
@@ -86,9 +86,9 @@ cannot be performed in a single run however correct the code is. One planned "sh
 second lesson and is nudged about the third" against a function that refuses a second completion
 the same calendar day.
 
-**Every screen the milestone's opening paragraph names is either a `ui` item or a sentence to
+**Every screen the changeset's changes name is either a `ui` item or a sentence to
 cut.** This trap is easier to miss in the summary prose than in the scenarios: a screen named
-there and carried by no `ui` item is invisible to `plan progress`, so the milestone closes green
+there and carried by no `ui` item is invisible to `plan progress`, so the changeset closes green
 with a sentence of itself unbuilt. One promised "the interval control on the admin product form"
 for a form that does not exist anywhere in the app.
 
@@ -99,7 +99,7 @@ mark a product's countries, cannot be proven without amending the plan mid-build
 **Every state a scenario waits in needs the function that leaves the world like that — checked
 against the code ALREADY built.** Three failure shapes, in rising order of cost:
 
-- *Stale*: a staff queue of "paid orders with no invoice yet", where an earlier milestone had
+- *Stale*: a staff queue of "paid orders with no invoice yet", where an earlier changeset had
   moved invoicing to checkout. No order a customer could place was ever in that state; three
   scenarios passed once against old rows, then failed.
 - *Unreachable*: staff asked to "capture the payment on an authorised order" when no function in
@@ -108,13 +108,13 @@ against the code ALREADY built.** Three failure shapes, in rising order of cost:
 - *Wrong person*: a distributor salon owner planned to buy from a catalogue that is scoped by
   distributor and does not show her the product. Actors are not interchangeable.
 
-**A `model` slot saying "this milestone adds no table" has to be true of the DATA the scenarios
+**A `model` slot saying "this changeset adds no table" has to be true of the DATA the scenarios
 read, not only of the entities they name.** One promised a checkout priced by delivery country — a
 shipping rate per country, a VAT rate per country — against an `n/a` model, while the only shipping
 table in the tree (an addon's) carries no country column at all. The builder then chooses between
 altering someone else's table and amending the plan, with neither choice recorded. Wherever a
 description prices, rates or tiers something BY a dimension, say in `model` where that lookup lives:
-a table this milestone adds, a column on one that exists, or config-as-code — and if it is config,
+a table this changeset adds, a column on one that exists, or config-as-code — and if it is config,
 say so and why, exactly as for seed data.
 
 ---
@@ -125,7 +125,7 @@ A plan is read one field at a time, so a contradiction between two descriptions
 check `plan set` makes and is discovered mid-build, with the code already written one of the two
 ways.
 
-**Where the milestone has a state machine — anything with more than two states and a clock — write
+**Where the changeset has a state machine — anything with more than two states and a clock — write
 the transitions out once, in the model slot, as the table they are.** Every scenario description
 then quotes that table instead of restating it from memory. One plan said a cancel on a paid-up
 licence lands in `canceled` in one scenario and `active_until_expired` in the next.
@@ -142,7 +142,7 @@ you look next: either the same reasoning applies to them, or the plan says why i
 
 **Wherever a function writes a set under a parent, say whether a save REPLACES that set or ADDS to
 it.** A product's variants, an order's lines, a company's members: the two produce identical tables
-and identical scenarios, and differ only on the second save. Left unsaid, one milestone shipped an
+and identical scenarios, and differ only on the second save. Left unsaid, one changeset shipped an
 input schema that could not carry a variant's id, so every save re-added the variants it was given
 to update — 1, 2, 4, 8, and by the nineteenth save 262,144 rows, with the suite green throughout.
 Say it in the model slot in the same breath as `onDelete`: that field settles what happens when the

package/skills/pikku-build/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Use to build on Pikku — turning a fresh scaffold into a working app (quick spike, real product,
   or a showcase that exercises every surface), adding a feature to an app that already exists, and
   the one-off cleanup right after a template is cloned. Covers the knowledge base, personas and
-  roles, milestone planning, the scenario that proves each one, theming, multi-app layouts and
+  roles, filing the work as changes and planning each changeset, the scenario that proves each one, theming, multi-app layouts and
   deploying. TRIGGER when: the user asks for an app to be built on Pikku, a freshly scaffolded
   project needs turning into a product, the user asks to add a feature or wire up a new endpoint
   in a working app, or a template was just cloned or scaffolded. DO NOT TRIGGER when: the user
@@ -36,7 +36,7 @@ agent:
 | 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`                                                  |
+| A feature added to an app that already has its knowledge base               | `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
@@ -79,14 +79,14 @@ Say it at once, in one line, and start: this is the obvious first move, not a
 question for the user. Generate the whole spec, however large.
 
 Neither is the app. When the conversion compiles, come back here and carry on
-in the mode the request calls for — App by default — planning milestones around
+in the mode the request calls for — App by default — planning changesets around
 what the user wants to do with the API or the workflow, and reaching the
 generated functions through `ref()`.
 
 ## What holds in every mode
 
 - **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
+  working code: apply is a merge, reject is a `git branch -D`. The changeset'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, and there are two questions, not one.** What THIS
@@ -102,7 +102,7 @@ generated functions through `ref()`.
 - **`capabilities.<type>` reports what this app USES, not what pikku offers.**
   A `false` there is "no wire of this type is declared yet", so the rule below
   about not introducing one is about not widening an app's surface on a whim —
-  it is not a statement that the surface is unavailable. When a milestone's plan
+  it is not a statement that the surface is unavailable. When a changeset's plan
   calls for a scheduled task and `capabilities.scheduler` is `false`, check
   `pikku doc` for the door before concluding you cannot build it.
 - **`metaLocale` in `pikku.config.json` is the language of authored meta** —
@@ -116,7 +116,7 @@ generated functions through `ref()`.
   because codegen refuses before it gets there. Delete those contracts' entries
   from `versions.pikku.json` and re-run; they are re-recorded. Fix the real
   diagnostic first, or you will chase the echo instead. Deleting is right only
-  for a contract first recorded INSIDE the milestone you are building — nothing
+  for a contract first recorded INSIDE the changeset you are building — nothing
   has consumed it, so there is no version to keep. A contract that shipped and
   then genuinely changed shape gets `version: N+1` on its `pikkuFunc({...})`
   followed by `pikku versions update`; delete its entry and you erase a version
@@ -130,10 +130,11 @@ generated functions through `ref()`.
   `addressLine1`, so a value saved through the query builder comes back missing
   with no error anywhere. Follow the columns already in `db/sqlite/`
   (`address_line1`), and check a new one round-trips before building on 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` (how: `pikku-architect`)
-  in its own turn before any of that milestone's code exists, and
+- **A changeset that needs a plan is planned before it is built, and the plan
+  then stays fixed.** `changes claim` says whether it needs one. The plan —
+  tables, functions, wires, roles, scopes, screens, scenarios, in passes — is
+  written through `pikku knowledge plan set <changeset>` (how: `pikku-architect`)
+  in its own turn before any of that changeset'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.
@@ -205,17 +206,17 @@ listed here.
 
 ## What NOT to do
 
-- **Do not skip ahead in App mode.** Knowledge, then people, then milestones,
-  then one milestone at a time — planned, built, proven by a scenario, and
-  closed against its plan before the next starts. The order is the method.
-- **Do not close a milestone your plan says is unfinished.** Build the missing
+- **Do not skip ahead in App mode.** Knowledge, then people, then changes,
+  then one changeset at a time — planned, built, proven by a scenario, and
+  closed against its plan before it merges. The order is the method.
+- **Do not close a changeset your plan says is unfinished.** Build the missing
   item, or defer it with a reason through `pikku knowledge plan defer`. Never
   edit the plan to match what you built, and never drop an item silently.
 - **Do not let a Quick build be mistaken for a real one.** It skips
-  `knowledge/`, milestone planning, design direction and refusal scenarios — say
+  `knowledge/`, changesets and plans, design direction and refusal scenarios — say
   so out loud to the user when you finish, and point at the way out.
 - **Do not introduce a wire of a type whose `capabilities.<type>` is `false`**
-  unless the user asked for it — and an approved milestone plan counts as them
+  unless the user asked for it — and an approved changeset plan counts as them
   asking. A plan the user signed off on authorizes the wires it names, so build
   them and flip the capability, rather than refusing planned work because the
   flag still reads `false` from before the plan.