@milehimikey/em 1.19.7 → 1.21.0

package/plugin/skills/discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discover
-em-version: 1.19.7
+em-version: 1.21.0
 description: >-
   Use when starting a brand-new event model from scratch — greenfield discovery: brainstorming
   past-tense events, storyboarding the happy path, finding the commands and read models — or when
@@ -69,7 +69,7 @@ Goal: a draft model of events, storyboard, commands, and views. Loose is OK; str
    **Close the loop before leaving this step:** every event from step 3 must be read by at least one
    read model. Walk the event list and ask, for each one, *"who looks at this, and what do they do
    with it?"* An event with no answer is either missing its read model or shouldn't be recorded —
-   both are worth raising with the user rather than leaving dangling.
+   both are worth raising with the user rather than leaving dangling. Keep the draft in one file with inline `storyline` blocks; the design phase splits it into one file per story (`em storyline split`) once the names are settled.
 
 End of phase: write/refresh the `.em`, render it, update `.event-modeling.md` (steps done,
 decisions, open questions — run `em state set-phase model` rather than hand-editing `Current

package/plugin/skills/discover/reference/extract.md

@@ -97,6 +97,18 @@ it is fine to finish a round with `# TBD`s still parked.
   read model* warnings: real systems do record fire-and-forget events. In an as-is model that is
   a **finding about the system**, not a modelling mistake — never invent a reader to silence it
   (that would be desired state). Park it in the Decisions log and carry the warning.
+  **Expect lookup-style sources too.** A lifted model will faithfully reproduce the projection's
+  lookup joins — a view wired to `from "Order Created"` only because the current query joins the
+  orders table to get `customerName`, not because this view owns any row that event changes. Wire
+  it as-is (current-state-only stance: that join is how the system behaves today); don't fix it
+  here, that would be inventing desired state. Note it as a finding in the Decisions log the same
+  way as an unread event, and leave it for `model`/`slice` to apply the views-as-lookups rule
+  (`../../../shared/reference/methodology.md`, "Views as lookups") once the as-is
+  model is agreed. **Housekeeping handlers are `updates from`, as-is:** when the projection code
+  handles an event only to update or delete a row it already holds (a status flip, a due date
+  moved, an address changed, a row removed), write that event in `updates from "…"`, not `from` —
+  that is what the code does today, it keeps the field tracing complete, and the as-is render then
+  shows the one line that puts work on the list instead of every handler.
 - **R5 — Boundaries & reactions.** Current automations and integrations as-is: schedulers,
   listeners, outbound syncs, inbound webhooks. Model each as a reaction sharing its slice with
   the `command` + `event` it triggers (`reaction → command → event`, per `em-dsl.md`) — the

package/plugin/skills/engagement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: engagement
-em-version: 1.19.7
+em-version: 1.21.0
 description: >-
   Use when leading an engagement: building a named set of ratified event-modeling slices
   (`em engagement`) into one independent PR per slice, each against main, by dispatching the

package/plugin/skills/event-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling
-em-version: 1.19.7
+em-version: 1.21.0
 description: >-
   Use when the user runs `/em:event-modeling` (with or without a phase name), or wants to resume an
   event-modeling session without specifying which part of the process applies. Reads the model's

package/plugin/skills/implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implement
-em-version: 1.19.7
+em-version: 1.21.0
 description: >-
   Use when building a single ratified event-modeling slice (status: ready-to-implement) into
   merged, tested code — the one phase where the agent builds rather than facilitates. Gates on
@@ -53,7 +53,12 @@ routing table (§7) is what names the skill set for each pattern.
 Preconditions (tool check, model location) are the same as every other phase — see
 `${CLAUDE_PLUGIN_ROOT}/shared/reference/operating-principles.md` — but this phase additionally
 requires the target slice to already be ratified; if it isn't, stop and say so rather than
-starting on unratified work.
+starting on unratified work. The one documented exception is **inline ratification** (GH #399,
+`reference/implement.md` §1a): for an internal (non-public-touching, non-engagement) slice whose
+doc is already `reviewed`, drafting code on the same branch ahead of the human's `em slice
+ratify` is sanctioned — provided you never flip the gate yourself and re-confirm
+`--slice-ready` reads `true` before treating the slice as done. `em:engagement` is
+unchanged by this: it still requires every dispatched slice ratified before its branch is cut.
 
 End of phase: PR merged, slice doc flipped to `status: implemented` with `implementedIn`
 filled, `em slice index <model-name>.em` run to refresh `README.md`'s Slices table. Implement

package/plugin/skills/implement/reference/implement.md

@@ -47,15 +47,82 @@ A warning whose code is in this list blocks; any other warning never does — `c
 
 Because of that list, `ready` can be `false` with every `gates` entry `true` (a `both-ends-of-a-flow/*` warning on one of the slice's own elements, say). Don't work it out from `gates`: read **`blockedBy`** (schema `1.5`, GH #377), the codes that flipped `ready`, `[]` exactly when it is `true`, and report those codes with the `false` gates when you hand the slice back.
 
-**`ready: false` means stop** — with one named exception: a slice already `status: implemented`
-with `driftSignal: in-sync` or `uncertified` (MIL-214) also reads `ready: false` (its
-`statusReady` gate fails because nothing is newly ratified), and that specific case is
-re-implementation/repair, not a blocker — see §3's third mode before treating it as one. For
+**`ready: false` means stop** — with two named exceptions. First: a slice already `status:
+implemented` with `driftSignal: in-sync` or `uncertified` (MIL-214) also reads `ready: false`
+(its `statusReady` gate fails because nothing is newly ratified), and that specific case is
+re-implementation/repair, not a blocker — see §3's third mode before treating it as one. Second:
+under **inline ratification** (§1a) a slice doc that's only `status: reviewed` — not yet
+`ready-to-implement` — is a sanctioned starting point for drafting code on the SAME branch, with
+the explicit, non-negotiable condition that you treat nothing as actually ratified, and open
+nothing for merge, until a human has run `em slice ratify` and `--slice-ready` reads `true` for
+real; §1a names exactly which slices qualify and what that condition requires in practice. For
 every other `false`, report which `gates`
 entries are `false` and what `blockedBy` names (and any `diagnostics` entries concerning this
 slice) and hand the slice back to the humans. Never make the gate pass yourself — checking an open-question box, flipping
-`status`, or editing frontmatter are ratification decisions, and ratification happens in a
-facilitated session, not in an implementation branch.
+`status`, or editing frontmatter are ratification decisions, made by a human in a ratification
+session, never by you running `em slice ratify` on their behalf. That session is usually a
+separate doc-only PR, merged before an implementation branch is even cut — but it doesn't have
+to be: **inline ratification** (GH #399, §1a below) lets the session be the PR review of the
+very branch you're implementing on, for internal slices. Either shape, the rule here is the
+same: you never flip the gate yourself, whatever branch you're on.
+
+### 1a. The inline variant: ratifying on the implementation branch
+
+Most of this document assumes the ordinary shape — a slice is already `ready-to-implement` when
+you start, ratified in its own prior PR, and §1's gate reads `true` before you write a line of
+code. **Inline ratification** is the documented alternative
+(`docs/process.md`'s
+["Inline ratification" section](https://github.com/milehimikey/em/blob/main/docs/process.md#inline-ratification-approval-as-the-ratification-session)):
+draft the slice doc *and* build it on the same branch, spec commits first, and let the human's
+review of that one PR be the ratification session — which means you are, deliberately and
+sanctioned, building for most of that branch's life against a doc that reads `ready: false`.
+What doesn't change: you still never flip `status` yourself, never run `em slice ratify` on the
+human's behalf, and never write a word of the ratification record — see §1's second named
+exception for the precise condition this depends on. What's different is sequencing and tiering:
+
+- **Draft the doc first, then build on the same branch.** Commit the slice doc (through the
+  normal `slice` phase), get it reviewed (`em slice review --by`, flipping it to `status:
+  reviewed` — a human has to do this part too, same as always) before any implementation code,
+  even though doc and code will both live on one branch and merge in one PR. Writing code before
+  the doc exists, or before a human has looked at it, is retrofit — the exact failure mode inline
+  mode is named after avoiding — whether or not anyone ever checks for it.
+- **You may keep building past a `reviewed`-but-not-yet-`ready-to-implement` doc, but nothing is
+  ratified until `em slice ratify` actually runs.** `--slice-ready` keeps reading `false` the
+  whole time you're building — that's expected, not a signal to stop, as long as the doc's
+  `status` is `reviewed` (not `draft`: an un-reviewed doc is never a valid base, inline or not).
+  On an inline branch the human typically runs `em slice ratify --no-ref` as part of approving
+  the PR (`--no-ref` because the branch is headed for a squash/rebase merge) — not something you
+  do for them, and not something you should expect to have happened before the PR is up for
+  review. Before you report the slice done, or treat §6's merge-time flip as legitimate,
+  re-check `--slice-ready` yourself and confirm it now reads `true` with `ratifiedBy:` set — if
+  it still doesn't, the slice isn't ratified yet and you say so instead of proceeding.
+- **A post-signature doc edit still trips the hash check.** `ratifiedHash` doesn't know or care
+  which branch it was computed on — if something changes the doc's body after the human has
+  signed it (a gap surfaces, §4), `--slice-ready` and `em slice ratify` both refuse the stale
+  signature exactly as they would across two PRs. Route it through `em slice revise --withdraw`,
+  review, re-ratify (§4) — inline doesn't shortcut that loop, it just means the re-sign happens
+  on the branch you're already on instead of a fresh one.
+- **Not every slice is a candidate.** A slice owning a `public` command, event or view
+  (`isPublicTouchingSlice`) keeps the separate doc PR — the contract is a promise to consumers
+  who never see your implementation diff, and `em slice ratify` already refuses a public-touching
+  slice without `--meaning-unchanged`/`--contract-change` regardless of which branch it runs on.
+  An engagement-dispatched slice is never inline either — engagements structurally need every
+  contract frozen before any implementer branch is cut, so the engagement skill never offers you
+  this shape (it is explicitly unchanged by GH #399 — this is a note for your own judgment
+  outside an engagement, not something to apply inside one).
+- **Pre-ship advisory conform is the loop's natural checkpoint.** Before the PR merges, a human
+  (or you, if asked) can run `em slice conform <model>.em <key> --at <rev> --preview` — the
+  pre-ship, non-certifying mode (GH #400): same doc-resolution and findings-check read as a real
+  certification, legal before the slice has shipped, never writes `conformedVersion:`/
+  `conformedAt:`/`conformedOn:`. It's advisory and ephemeral by default (nothing written unless
+  `--write-findings` is passed) — a cheap "did I just drift from the doc I signed" look before
+  asking for the PR review that will also be the ratification.
+- **The ordering advisory is informational, not yours to act on.** `em refs --check-order`
+  (GH #399) can report whether a commit on this branch touched code before the doc's
+  `ratifiedRef` — a retrofit smoke signal for the human reviewing the PR. It's advisory, never a
+  gate, and nothing in this skill asks you to run it or react to its output; if a human shows you
+  a `code-before-ratification` result, treat it the same as any other gap raised against your
+  work (§4), not as something to silence.
 
 ## 2. Read the spec
 

package/plugin/skills/review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review
-em-version: 1.19.7
+em-version: 1.21.0
 description: >-
   Use when starting em's live browser viewer (`em watch --serve`) so a team can watch a model
   update in real time, or facilitating a SCHEDULED stakeholder walkthrough that steps through
@@ -16,8 +16,16 @@ description: >-
 Start the watcher with `--serve` in the background:
 `em watch <model-name>.em -o <model-name>.svg --serve` (run_in_background). It re-renders on every
 save and pushes an instant reload to the browser over Server-Sent Events. Tell the user to open the
-URL it prints (e.g. `http://localhost:5173/?svg=<model-name>.svg`) and share their screen — updates
-appear the moment you save, with no polling and no idle churn between edits.
+URL it prints and share their screen — updates appear the moment you save, with no polling and no
+idle churn between edits.
+
+What that URL opens depends on the model. A model that declares storylines opens on the
+**storyline canvas** (`http://localhost:5173/map`): every storyline's own diagram in a draggable
+frame, the flow between storylines drawn between frames, reloaded live on every save with the
+layout kept. A frame's **open ›** drills into that storyline — the viewer on its own slices and
+nothing from outside it — and **‹ Storylines** in the header returns to the canvas. A model
+without storylines opens on the timeline (`http://localhost:5173/?svg=<model-name>.svg`). Never
+send a room to the full timeline of a storyline model; the storyline is the unit people read.
 
 The viewer navigates like a map — drag to pan, scroll/pinch to zoom, **Fit** to reset — and its
 **Review mode** steps through slices one at a time (see the `review` phase below). A save that
@@ -35,10 +43,14 @@ speculation.** Don't propose this phase proactively; it exists for facilitated r
 non-engineer stakeholders in the room, not routine model editing.
 
 Start the same live server as `watch`: `em watch <model-name>.em -o <model-name>.svg --serve`
-(run_in_background). Open the printed URL, click **Review mode** in the header, and share the
-screen. Use Prev/Next (or the left/right arrow keys) to step through slices in declaration
-order — each one pans/zooms into view with everything else dimmed, so the room's attention
-tracks one slice at a time.
+(run_in_background). Open the printed URL and share the screen. With storylines, review one
+storyline at a time: open it from the canvas (or start inside it with `--storyline "<name>"`),
+then click **Review mode** in the header — Prev/Next walk that storyline's slices only. Between
+storylines, **‹ Storylines** returns to the canvas, where the arrows between frames are the
+order to take them in. Without storylines, click **Review mode** on the timeline. Use Prev/Next
+(or the left/right arrow keys) to step through slices in declaration order — each one
+pans/zooms into view with everything else dimmed, so the room's attention tracks one slice at
+a time.
 
 **When a State View slice is on screen, ask who reads it (MIL-215):** a person or client in the
 room → the `ui` should draw it; another system → `public`; only an automation → nothing, it's