@milehimikey/em 1.16.1 → 1.18.0

package/plugin/shared/reference/methodology.md

@@ -145,6 +145,17 @@ command** — it never records an event directly.
   duplicated name.
 - Socratic prompts: *"What should happen without a human? What condition triggers it? What work
   list does the processor watch? What command does it fire? What if it fails or retries?"*
+- **Outcomes are events of the SAME slice.** Success, failure, retry-scheduled and timeout are
+  outcome events of the one command (`Fulfilment Succeeded` / `Fulfilment Failed` / `Fulfilment
+  Retry Scheduled`), not sibling slices per control-flow branch (1.18.0 adds the
+  lint `automation-split-by-outcome`). Retry policy and failure handling are invariants and scenarios
+  in that slice's doc. A new slice only when a different actor or a different trigger is
+  involved. Canon: Dilger, "one business action… two different possible outcomes"
+  (`PaymentIssued` / `PaymentFailed`); a failure that continues the story is "Linearized" as a
+  later chapter linked to the originating event, never a branch; it reads the failure event
+  through a view or a reaction (Law 1 forbids event-to-event arrows). A retry is the processor's
+  to-do view reading the retry-scheduled event (`view X again`), so the same reaction re-fires. Same rule for State Change: one
+  command, several outcome events, one slice.
 
 ### 4. Translation
 **Boundary crossing → command → event, the reaction and what it triggers together in one slice.**
@@ -194,6 +205,260 @@ The `em` shape only tracks the second question — trigger source doesn't change
 
 ---
 
+## The story, not the schema
+
+A model is a story of what success looks like, not a data model (Dymitruk, *What is Event Modeling*: a
+story "on a time line and with no branching"; commands capture intent, "as opposed to simply saving form
+data to a table"; "all information has to have an origin and a destination"). Models drafted from a spec
+drift into **CRUD laid on a timeline**; these rules stop that. Quoted lines are the canon; rulings marked
+*(em ruling)* are em's own — neither Dymitruk nor Dilger states a child-entity rule or bans "Update" or
+"Set" by name. Full write-up with the canon quotes: `docs/storyline.md`.
+
+- **One journey per process, start to finish.** The timeline holds one business journey per process,
+  ending in an outcome. The **main storyline** is the end-to-end happy path; retire, extend and
+  reorganize are **secondary storylines** (chapters; Dilger: "one linear flow from left to right. No
+  exceptions… Linearize it!", "Model one process at a time, each with its own clear ending"). Never one
+  lifecycle block per entity. Name the main and every secondary storyline; a `storyline "Name" { … }`
+  block groups the slices (`dsl.md`, Storylines).
+- **Build from walkthroughs first.** The story already lives in the spec's walkthroughs, use cases and
+  user journeys. Build the timeline from those; the resource/API reference (OpenAPI, endpoint tables,
+  migrations) fills only the operations no walkthrough touches, and is read last. Headless: a persona
+  per API caller, and that caller's journey is the story.
+- **The CRUD shape.** N entities × (create, update, archive), one trailing view per entity, no read
+  across contexts. Recognise it in your own output. Both models below validate; only the second is a
+  story:
+  ```em
+  model "Catalog (CRUD shape)"
+
+  persona Merchandiser
+
+  context Product
+
+  slice "Create Product" {
+    ui Product Form @Merchandiser
+    command Create Product
+    event Product Created @Product
+  }
+
+  slice "Update Product" {
+    ui Product Form @Merchandiser
+    command Update Product
+    event Product Updated @Product
+  }
+
+  slice "Archive Product" {
+    ui Product Form @Merchandiser
+    command Archive Product
+    event Product Archived @Product
+  }
+
+  slice "Products" {
+    view Products from "Product Created", "Product Updated", "Product Archived"
+    ui Product List @Merchandiser
+  }
+  ```
+  ```em
+  model "Catalog (storyline shape)"
+
+  persona Merchandiser
+
+  context Product
+
+  storyline "Bring a product to market" {
+    slice "Create Product" {
+      ui Product Form @Merchandiser
+      command Create Product
+      event Product Created @Product
+    }
+
+    slice "Catalog" {
+      view Catalog from "Product Created"
+      ui Browse Catalog @Merchandiser
+    }
+
+    slice "Set Price" {
+      ui Pricing Panel @Merchandiser
+      command Set Price
+      event Price Set @Product
+    }
+
+    slice "Catalog with Price" {
+      view Catalog again from "Price Set"
+      ui Browse Catalog @Merchandiser
+    }
+  }
+
+  storyline "Retire a product" after "Bring a product to market" {
+    slice "Retire Product" {
+      ui Pricing Panel @Merchandiser
+      command Retire Product
+      event Product Retired @Product
+    }
+
+    slice "Catalog without Product" {
+      view Catalog again from "Product Retired"
+      ui Browse Catalog @Merchandiser
+    }
+  }
+  ```
+  The `timeline-entity-clustered` lint is the mechanical half (it fires only once two or more
+  contexts are written; this one-entity pair stays silent); once any storyline exists,
+  `slice-outside-storyline` flags slices left outside one.
+- **Commands name intent, not endpoints** (Dilger: "Name by intent", "Every command has a reason"). One
+  endpoint may carry several intents. Signal of two intents in one command: invariants or field rules
+  that apply only "if `<field>` is set" — split it, and both commands may record the same event
+  (`CreateProduct` / `CreateProductVariant`, same `POST /products`, same `ProductCreated`). **Intent
+  test:** if a storyline step reads awkwardly with the command's name, the command is named after the
+  endpoint. `command-second-intent` and `command-repeated-across-slices` are the mechanical half.
+- **A read model is one information need** (Dilger: "Every Read Model answers a question. No question,
+  no Read Model."). **Question test:** write the question each view answers; add a view only when no
+  existing one answers it. A nested route hints the child belongs in the parent's view; the real test
+  is whether the query needs information the parent view lacks. Child with references only → the parent
+  view carries ids; child with its own data → embedded in the parent view; child queried without the
+  parent id → its own view. Aggregate rules decide write-side consistency, never read models. *(em
+  ruling)*
+- **Write side: children belong in the parent's context** when the child's invariants are checks against
+  the parent. A sub-resource schema shared across parent types is one event per parent on the parent's
+  context, not a shared aggregate — check the spec's event reference, not its resource section. Where
+  two slices record the same fact, repeat the event bare (same name, same context). *(em ruling)*
+- **Repeat the view after every command that changes it** (`again`, span-1 — see State View above), so
+  the reader sees the information arrive rather than a view at the end.
+- **Outcomes are events of one slice** (Dilger: "One decision. One event. One state change."; one
+  action with two outcomes is the legitimate exception): alternative events on one context in one slice
+  (`event A | B @Ctx`, GH #278), failure as a scenario first, a chapter only when core (it changes what the user does next, or has
+  its own actor/SLA). Stated once for
+  automations in the Automation pattern (`docs/patterns.md#automation`); `automation-split-by-outcome`
+  and `retry-slice-of` are the mechanical half. Two forms, alternatives always on one context: inline `event A | B @Ctx`
+  (shared clauses and fields) and `oneof { … }` (each alternative keeps its own fields and clauses):
+  ```em
+  model "Payments"
+
+  persona Customer
+
+  context Payment
+
+  slice "Settle Payment" {
+    ui Pay Screen @Customer
+    command Settle Payment
+    event Payment Issued | Payment Failed @Payment { paymentId: UUID }
+  }
+
+  slice "Payment Status" {
+    view Payment Status from "Payment Issued", "Payment Failed"
+    ui Payment Result @Customer
+  }
+
+  slice "Refund Payment" {
+    ui Refund Screen @Customer
+    command Refund Payment
+    oneof {
+      event Refund Issued @Payment { paymentId: UUID, amount: Decimal }
+      event Refund Declined @Payment { paymentId: UUID, reason: String }
+    }
+  }
+
+  slice "Refund Status" {
+    view Refund Status from "Refund Issued", "Refund Declined"
+    ui Refund Result @Customer
+  }
+  ```
+- **One event, two commands.** When two commands record the same fact, repeat the event bare
+  (`event X @Ctx`, same name and context) in the second slice: it inherits the first declaration, no
+  marker needed. Declaring different fields is `shared-event-field-mismatch`. (The arrow set for a
+  shared event read by a repeated view is under review: GH #328.)
+  ```em
+  model "Ordering"
+
+  persona Customer
+
+  context Sales
+
+  slice "Place Order" {
+    ui Checkout @Customer
+    command Place Order
+    event Order Placed @Sales { orderId: UUID }
+  }
+
+  slice "Order Status" {
+    view Order Status from "Order Placed"
+    ui Track Order @Customer
+  }
+
+  slice "Reorder" {
+    ui Reorder Button @Customer
+    command Reorder
+    event Order Placed @Sales
+  }
+
+  slice "Order Status after Reorder" {
+    view Order Status again from "Order Placed"
+    ui Track Order @Customer
+  }
+  ```
+  Combined with alternatives: when one alternative is a shared repeat, use `oneof` and write that
+  alternative bare so it inherits its fields (an inline line's fields would be copied onto every
+  alternative and mismatch):
+  ```em
+  model "Payments"
+
+  persona Customer
+
+  context Payment
+
+  slice "Settle Payment" {
+    ui Pay Screen @Customer
+    command Settle Payment
+    oneof {
+      event Payment Issued @Payment { paymentId: UUID }
+      event Payment Failed @Payment { paymentId: UUID, reason: String }
+    }
+  }
+
+  slice "Payment Status" {
+    view Payment Status from "Payment Issued", "Payment Failed"
+    ui Payment Result @Customer
+  }
+
+  slice "Retry Payment" {
+    ui Retry Screen @Customer
+    command Retry Payment
+    oneof {
+      event Payment Issued @Payment
+      event Payment Retry Declined @Payment { paymentId: UUID }
+    }
+  }
+
+  slice "Payment Status after Retry" {
+    view Payment Status again from "Payment Issued", "Payment Retry Declined"
+    ui Payment Result @Customer
+  }
+  ```
+- **Reference-only PRD groups sit outside storylines.** A group that only carries reference material
+  (#327) is not a journey; leave it out of every `storyline` block.
+- **Business terms in the events.** "If your Event Model doesn't reflect terms used by business experts —
+  especially in the recorded Events — that's a red flag." (Dilger, *Seven insights*.)
+
+### Reshaping an existing model
+
+The upgrade path for a CRUD-shaped model. After each step run `em validate`.
+
+`em storyline suggest <model>.em` proposes the `storyline` blocks as a diff (advisory, never
+writes); `em upgrade` offers `collapse-alternative-events` and the opt-in `fold-continuations`.
+
+1. Name the processes (list each spec's walkthroughs or journeys, not endpoints): the main storyline and each secondary one.
+2. Reorder the slices into those stories and wrap each in a `storyline` block (`after "…"` where one
+   follows another); a slice that fits no story is a deletion candidate.
+3. Intent test per command: rename to the business intent; split any command with "if X is set" rules.
+4. Apply the information-need test to each read model and fold children into parents: merge views
+   answering the same question; add one only for an unanswered one.
+5. Move child-entity events onto the parent's context when the child's invariants check the parent.
+6. Repeat each view (`again`, span-1) after every command that changes it; drop the lone trailing view.
+7. Fold success/failure slice pairs into one slice with alternative events.
+8. Tooling, last: `em validate` (and `em validate --shape`, the 1.18.0 design exit gate), `em slice sync
+   --check` then `em slice sync`, `em slice index`, and regenerate TypeSpec/contracts last.
+
+---
+
 ## The 7 steps
 
 Run them in order. The skill groups them into phases: **discover = 1–4**, **model = 5–7**,
@@ -257,6 +522,9 @@ dedicated `slice` phase writes the full rich spec (see `../templates/slice.md`).
 - Prompts: *"Given what starting state, when this command/trigger fires, then what event(s)
   result? What must always be true? What are the failure paths? Which fields are essential and
   what are their rules?"*
+- **Failure, retry, timeout surface here?** Add the outcome events and the scenarios to the
+  SAME slice, never a new slice per branch (Dymitruk: "a few of these stories to show how a
+  command can and cannot succeed" — Given/When/Then scenarios first).
 - **Existing codebase:** before finalizing field names/types, check adjacent real sources
   (OpenAPI specs, DB migrations, existing DTOs/event classes in sibling contexts) rather than
   guessing — mirrors `extract.md`'s whole-system grounding, applied per-slice.

package/plugin/shared/reference/slice-doc-schema.md

@@ -68,17 +68,18 @@ to decide `frontmatter-invalid` without re-deriving frontmatter-shape rules of i
 | `reviewedOn` | string | `YYYY-MM-DD` | written only by `em slice review` (MIL-201); joined into `em export`'s `slice.doc.reviewedOn` (schema `1.11`) |
 | `ratifiedBy` | string | free text (typically a person's name) | written only by `em slice ratify` (MIL-165 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-ratify-file-slice-key---by-name)); joined into `em export`'s `slice.doc.ratifiedBy` (schema `1.8`) and `em slice index`'s Ratified by column |
 | `ratifiedOn` | string | `YYYY-MM-DD` | written only by `em slice ratify` (MIL-165); joined into `em export`'s `slice.doc.ratifiedOn` (schema `1.8`) |
-| `ratifiedRef` | string | full commit sha | written only by `em slice ratify` (MIL-284 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-ratify-file-slice-key---by-name)) when the model directory is inside a git repository: `HEAD` at ratification, the commit whose tree holds the body that was signed (ratify refuses a doc with uncommitted changes so this holds). Absent when ratified before 1.15 or outside git. Cleared by `em slice reratify`. Joined into `em export`'s `slice.doc.ratifiedRef` (schema `1.16`). Not a target-repo revision: `em slice conform --at` still names that itself |
-| `ratifiedHash` | string | `sha256:<64 hex>` | written only by `em slice ratify` (MIL-284): `sha256` over the doc body (everything after the frontmatter fence, EOLs normalised) — the signed content's identity without git. Cleared by `em slice reratify`. Read by `em validate --slice-ready` (`slice-ready-body-changed-since-ratification`); joined into `em export`'s `slice.doc.ratifiedHash` (schema `1.16`) |
+| `ratifiedRef` | string | full commit sha | written only by `em slice ratify` (MIL-284 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-ratify-file-slice-key---by-name)) when the model directory is inside a git repository: `HEAD` at ratification, the commit whose tree holds the body that was signed (ratify refuses a doc with uncommitted changes so this holds). Absent when ratified before 1.15, outside git, or with `em slice ratify --no-ref` (GH #255 — for a repo whose squash/rebase merges would leave the commit unreachable from the target branch; `--no-ref` also removes a line already present). **An address, not the identity:** valid only while the commit stays reachable; `ratifiedHash` is what identifies the signed content. Cleared by `em slice revise`. Joined into `em export`'s `slice.doc.ratifiedRef` (schema `1.16`). Not a target-repo revision: `em slice conform --at` still names that itself |
+| `ratifiedHash` | string | `sha256:<64 hex>` | written only by `em slice ratify` (MIL-284): `sha256` over the doc body (everything after the frontmatter fence, EOLs normalised) **minus what describes a later version** (GH #253, since 1.17.0): inside `## Open Questions` the heading line, blank lines and every `deferred to v<n>` item are left out, then trailing whitespace is trimmed — so `em slice defer` can record a question on a ratified or shipped doc without moving the hash, while answered `- [x]` history, any `- [ ]`, and every other section stay signed. The signed content's identity without git. A hash recorded before 1.17.0 (whole body) is still read as intact; `em upgrade`'s `ratified-hash-scope` step re-stamps it. Cleared by `em slice revise`. Read by `em validate --slice-ready` (`slice-ready-body-changed-since-ratification`) and by `ratify`'s same-sign-off re-run; joined into `em export`'s `slice.doc.ratifiedHash` (schema `1.16`) |
 | `shippedVersion` | integer | positive integer | written only by `em slice mark-implemented` (MIL-284): the doc's `version:` when the merge was recorded. With `shippedRef`/`shippedOn`/`implementedIn`, joined into `em export`'s `slice.doc.shipped` (schema `1.16`). Additive in 1.15 — `status`/`implementedIn` still carry the lifecycle for every reader |
-| `shippedRef` | string | full commit sha | written only by `em slice mark-implemented` (MIL-284): the doc's `ratifiedRef` at merge time, i.e. the ref the shipped version was signed at; absent when the doc had none |
+| `shippedRef` | string | full commit sha | written only by `em slice mark-implemented` (MIL-284): the doc's `ratifiedRef` at merge time, i.e. the ref the shipped version was signed at; absent when the doc had none (ratified before 1.15, outside git, or with `--no-ref`, GH #255). Same caveat as `ratifiedRef`: an address, valid while reachable — `ratifiedHash` identifies the content |
 | `shippedOn` | string | `YYYY-MM-DD` | written only by `em slice mark-implemented` (MIL-284): the local date of the merge record, or `--on <date>` |
 | `meaningConfirmed` | boolean | `true` | written only by `em slice ratify --meaning-unchanged` (MIL-238 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-ratify-file-slice-key---by-name)): the API-first sign-off on a public-touching slice — this version does not change what the public contract means. Joined into `em export`'s `slice.doc.meaningConfirmed` (schema `1.15`; `false` when absent) |
 | `contractChange` | string | quoted free text (`contractChange: "<why>"`) | written only by `em slice ratify --contract-change "<why>"` (MIL-238): the API-first sign-off on a public-touching slice — why a consumer must read this change differently. Joined into `em export`'s `slice.doc.contractChange` (schema `1.15`, quotes stripped; `null` when absent) |
+| `reviewSkipped` | string | a `status` value (`draft`, …) | written only by `em slice ratify --skip-review` (GH #260 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-ratify-file-slice-key---by-name)), and only when the bypass is what let the ratification through: the status the doc was ratified from. A ratification that passed the review gate writes nothing. Cleared by `em slice revise` with the rest of the sign-off. Joined into `em export`'s `slice.doc.reviewSkipped` (schema `1.18`, `null` when absent) and `em validate --slice-ready --json`'s top-level `reviewSkipped` (schema `1.3`) |
 | `owner` | string | free text (typically a person or team name) | hand-filled — no `em` command writes it; joined into `em export`'s `slice.doc.owner` (schema `1.9`, MIL-171), `em slice index`'s Owner column, and `em status`'s per-slice `owners[]` |
 | `tracking` | string | free text (typically an external ticket/issue URL) | hand-filled — no `em` command writes it; joined into `em export`'s `slice.doc.tracking` (schema `1.9`, MIL-171) and `em slice index`'s Tracking column. This is the exact field `em-tracker-bridge` reads to find the ticket mirroring this slice — `em` only stores and displays it, it never talks to a tracker itself |
 | `conformedVersion` | integer | positive integer | written only by `em slice conform` (MIL-214 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-conform-file-slice-key---at-rev)): this slice's `version:` at the time a conform sweep last certified it. Joined into `em export`'s `slice.doc.conformedVersion` (schema `1.13`); paired with `version` to compute `slice.doc.driftSignal`'s `"uncertified"` case |
-| `conformedAt` | string | free text (a target-repo revision, NOT a `<slice-key>@v<N>` lineage ref) | written only by `em slice conform` (MIL-214): the revision that certification sweep diffed against. Joined into `em export`'s `slice.doc.conformedAt` (schema `1.13`) and `em slice index`'s Conformed column |
+| `conformedAt` | string | a target-repo revision, or `<kind>:<id>` (NOT a `<slice-key>@v<N>` lineage ref) | written only by `em slice conform` (MIL-214): the revision that certification sweep diffed against — or, since 1.17.0 (GH #261), an opaque identifier with an explicit kind (`build:1234`, `deploy:eu-1-2026-10-15`) for what was exercised when that is not a commit that stays reachable (a PR-branch HEAD under squash/rebase merges). A bare value is git (`parseConformedAt()`); reachability checks skip a kinded value. Joined into `em export`'s `slice.doc.conformedAt` (schema `1.13`) and `em slice index`'s Conformed column |
 | `conformedOn` | string | `YYYY-MM-DD` | written only by `em slice conform` (MIL-214). Joined into `em export`'s `slice.doc.conformedOn` (schema `1.13`) |
 
 Five keys — `schemaVersion`/`pattern`/`swimlane`/`status`/`version` — are what
@@ -88,6 +89,68 @@ over an omission — it reports). `implementedIn` and the lineage keys are the g
 optional ones; `implementedIn`'s required-once-implemented rule in the table below is
 convention, not parser-enforced.
 
+## Who may ratify
+
+The schema records *who* signed (`reviewedBy`, `ratifiedBy`) but, by default, accepts any
+non-empty name: who is allowed to sign is the host repo's decision. A host that wants em to
+enforce it supplies an optional **roster**, `ratifiers.yaml`, beside the model. See
+[examples/order-fulfillment/ratifiers.yaml](https://github.com/milehimikey/em/blob/main/examples/order-fulfillment/ratifiers.yaml).
+
+```yaml
+rosterSchemaVersion: "1.0"
+ratifiers:
+  - name: Aaron McKay
+    contexts: [Product, Attribute]   # omit = the whole model
+  - name: Mike Key
+  - name: Dana Lee
+    models: [pim]                    # omit = every model the roster governs
+reviewers:                           # optional; same shape, checked by `em slice review --by`
+  - name: Mike Key
+```
+
+- **Schema.** `rosterSchemaVersion` is required (`"1.0"`); at least one of `ratifiers:` /
+  `reviewers:` is required; each is a non-empty list of `{ name, contexts?, models? }`. Unknown
+  keys are errors (`roster-invalid`). A missing `ratifiers:` / `reviewers:` key leaves that role
+  unrestricted.
+- **Placement.** The nearest `ratifiers.yaml` walking up from the model's directory, stopping at
+  the nearest directory holding `.git` (or the filesystem root). If no `.git` exists anywhere
+  above the model, only the model's own directory is searched. `--roster <path>` on `ratify`,
+  `review`, `validate --slice-ready`, `roster check` overrides discovery; a path that does not
+  exist is an error, never "no roster".
+- **A slice's contexts** are the contexts of its **events** plus the contexts of the events its
+  **views read** - each view instance's **own** `from`, never a union across the read model's
+  instances (adding a later `again` instance never changes an earlier slice's contexts). A
+  continuation slice also takes its originating instance's own `from`. A slice with neither has no
+  context and is permitted only by entries without `contexts`.
+  A continuation fed from a different context than its originating view (e.g. `tool-shows-on-loan` =
+  Loan + Tool) therefore needs a ratifier permitted for every one of those contexts, so a team with
+  one lead per context needs a joint or whole-model roster entry for such slices.
+- **An entry permits a slice** when it applies to the model and either has no `contexts` or lists
+  **every** context of the slice: a cross-context slice needs a ratifier who may sign for all of
+  them (a leading `@` is tolerated in `contexts`).
+- **Per-model scoping.** `models: [<modelKey>]` (the key `em export` reports as `model.key`) limits
+  an entry to those models; an entry without it applies to every model the roster governs. Context
+  names are matched **per model** against that model's declared contexts, so a shared root roster
+  needs `models:` whenever the models' ratifiers differ. A `models:` key the enclosing
+  `system.yaml` does not list is `roster-invalid`.
+- **Validation against the model.** A `contexts:` entry the model does not declare (case-sensitive)
+  is `roster-invalid`, naming the context; only entries that apply to the model are checked.
+- **File absent: today's behaviour**, no warning. **File present but invalid: fail closed** -
+  `ratify` and `review` refuse, `--slice-ready` and `roster check` report `roster-invalid`.
+- **`grandfathered (unsigned before em 1.14)`** is em's own migration marker (`em upgrade`'s
+  `ratified-signoff`), not a signer: exempt from the `--slice-ready` check and from `roster check`
+  (which counts it) until the slice is re-ratified - but only the **exact** string, and only on a
+  doc with no `ratifiedHash` (the state `em upgrade` leaves). `grandfathered by X`, or the marker on
+  a doc that carries a hash, is a signer and is checked.
+- **Where it is enforced.** At write time by `em slice ratify` / `em slice review` (the refusal
+  lists the permitted names); at check time by `em validate --slice-ready <key>`
+  (`ratified-by-not-in-roster`, error - one `ready-to-implement` slice, ratifier only) and by
+  `em roster check <model>` (every doc, `ratifiedBy` on `ready-to-implement` and `implemented`,
+  `reviewedBy` on any), the command `em ci init` wires into CI when a roster exists - see
+  [ci.md](ci.md#ratifier-roster-gate). `em status` reports `roster: present|absent|invalid`.
+- `em roster init <model>` seeds the file from the names already in the docs
+  ([cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-roster-init-file)).
+
 ## Required vs optional, by `status`
 
 | Key | draft | reviewed | ready-to-implement | implemented |
@@ -99,6 +162,7 @@ convention, not parser-enforced.
 | `covers` | optional in every state — present only on a doc that deliberately also serves another slice (MIL-121, see below); most docs never carry it |
 | `reviewedBy`, `reviewedOn` | optional in every state — present once `em slice review` (MIL-201) has run at least once; a doc that never went through the review gate, or was hand-flipped to `reviewed`, simply omits both. `em slice ratify` never clears them; `em slice reratify` does (they describe the version that shipped) |
 | `ratifiedBy`, `ratifiedOn` | optional in every state, but `ready-to-implement` needs `ratifiedBy` to pass `em validate --slice-ready` (`slice-ready-not-ratified`, MIL-259) — present once `em slice ratify` (MIL-165) has run; `em slice reratify` clears both. `em upgrade` (`ratified-signoff`, 1.14) grandfathers a `version: 1` `ready-to-implement` doc that never had one by writing `ratifiedBy: "grandfathered (unsigned before em 1.14)"` and `ratifiedOn:` the upgrade date |
+| `reviewSkipped` | optional in every state — present only when `em slice ratify --skip-review` is what let the ratification through (GH #260); the value is the status it skipped from. Written right after `ratifiedOn:`; cleared by `em slice revise` with the rest of the sign-off. Absent on every ratification that passed the review gate, and on docs ratified with `--skip-review` before 1.17.0 |
 | `meaningConfirmed`, `contractChange` | optional in every state, at most one present — written right after `ratifiedOn:` by `em slice ratify` and right after `version:` by `em slice reratify` (MIL-238). On a **public-touching** slice (one owning a `public` command, event or view) both commands refuse without `--meaning-unchanged` or `--contract-change "<why>"`, so a doc ratified on 1.14+ carries one; elsewhere either is optional. `em slice reratify` clears both before writing its own (they describe the prior version, same as `reviewedBy`/`ratifiedBy`). `em status` counts public-touching `ready-to-implement`/`implemented` docs with neither (`publicSlicesUnconfirmed`) |
 | `owner`, `tracking` | optional in every state — hand-filled whenever a team wants a who-holds-this / external-tracker link; most docs never carry either (MIL-171) |
 | `conformedVersion`, `conformedAt`, `conformedOn` | optional in every state — present once `em slice conform` (MIL-214) has run at least once for the CURRENT version; a doc that's never been through a conform sweep, or whose `version` has since bumped past what was certified, simply has none of the three (or a stale triple — see `driftSignal`'s `uncertified` case below) |
@@ -260,6 +324,21 @@ the union of events every later `again` instance of that view reads via `from`,
 order — so implementing the read model from one export never means walking every `again`
 slice's doc by hand to assemble the full event list.
 
+The generated `em-slice-view` region follows the same rule (GH #280, 1.18.0): its `built from
+events:` line lists the union of `from` across the originating instance and every `again`
+instance (originating first, then timeline order, deduped), and each field's `from event` note
+resolves against that union (each later event annotated `(via "<slice>")` with its instance's slice) — whichever instance's slice the doc is bound to. `em slice sync`
+rewrites existing view regions accordingly.
+
+**Synthesized continuations (GH #287).** A `view X again` line written inside a command's own slice
+is lifted into a continuation column right after it. That column is a continuation like any other
+(`continuationOf` names the view's originating slice, `alsoReads` counts its events) but exists
+only as sugar over the host slice's text: its export key is `<host-slice-key>--again` (one column per host slice, its lifted lines stacked),
+it never has a doc, and `em slice index` lists no row for it. A slice key never contains `/` (the slug generator emits single dashes only, so `--` cannot occur in a hand-written key); the `/` in an element ref `<slice-key>/<kind>.<slug>` is always the first and only one. A hand-written continuation slice
+may also hold several `again` views, and may omit its name (auto-named `"<View> View: <Event>"`).
+When one slice stacks views of different read models, `continuationOf` names the originating
+slice of the FIRST view; the others are listed in their originating slices' `alsoReads` (with this slice's key as `atSlice`).
+
 **Authoring convention:** a continuation's behavior belongs in the originating doc's own
 `## Scenarios (Given / When / Then)` section — one scenario per event a later `again` instance
 feeds — rather than in a doc of its own; no new frontmatter is needed to record it.
@@ -396,7 +475,7 @@ re-run `em slice sync`.
 |---|---|---|
 | `em-slice-command` | `## Command / Input` | `**Command:** \`Name\`` + `\| Field \| Type \| Required \| Rules / Validation \|` (Required is `no` for a `name?: Type` field) |
 | `em-slice-event` | `## Event(s) Emitted` | `**Event:** \`Name\` → context \`Ctx\`` + `\| Field \| Type \| Immutable Fact? \| Source / Notes \|` (Source: the same-slice command field it is copied from, `assigned` for a system-assigned field, else `{{ }}`) |
-| `em-slice-view` | `## Read Model / View` | `- **View:** \`Name\` built from events: …` + `\| Field \| Type \| Source / Notes \|` (Source: the source event carrying the field, `Derived` for a `derived` field, else `{{ }}`) |
+| `em-slice-view` | `## Read Model / View` | `- **View:** \`Name\` built from events: …` (the union across the originating and every `again` instance; each later event is annotated `(via "<slice>")` with the slice of the instance that adds it) + `\| Field \| Type \| Source / Notes \|` (Source: the source event, from that union, carrying the field, `Derived` for a `derived` field, `Collection of \`T\`, fed by …` for a `T[] derived from …` field — followed by one neutral Given/Then scenario stub per named event under the table, to copy into `## Scenarios` and complete there (the region itself stays read-only) — else `{{ }}`) |
 | `em-slice-invariants` | `## Invariants / Business Rules` | one `- **INV-X** — rule` line per model-declared invariant of the slice's commands and events |
 
 A slice with several elements of one kind gets one region per element, the name suffixed with
@@ -435,12 +514,22 @@ case is a block:
 - **Given:**
   - a basket whose total is 0
 - **When:**
-  - the customer submits the order
+  - the customer issues PlaceOrder
 - **Then:**
   - the command is rejected with a validation error
   - no event is recorded
 ```
 
+**Scenario quality (citation convention).** A scenario is tied to exactly one command: its When
+names the slice's command (a reaction slice: the command it triggers), its Then names an event
+the slice records or a rejection/error, and it **cites the `INV-…` ids it exercises** anywhere in
+the block (the title above, or a Given/When/Then bullet). Every invariant declared for the slice
+(an `invariant` line in the model, or the doc's Invariants section) should be cited by at least one
+scenario. `em validate` advises on all three — `scenario-when-not-command`,
+`scenario-then-not-outcome`, `invariant-without-scenario` — see
+[validation.md](https://github.com/milehimikey/em/blob/main/docs/validation.md#scenario-quality). Older bullet-format scenarios are checked too; a doc with no scenarios is never
+flagged.
+
 A `### Scenario: <title>` heading, then the three column-0 bullets `- **Given:**`, `- **When:**`,
 `- **Then:**`, each with nested `  - ` items (text after the label on the same line counts as a
 first item). `em export --json` publishes the parsed blocks as `slice.doc.scenarios`
@@ -491,7 +580,11 @@ not deleted: `em slice defer` checks it and rewrites it as `- [x] <original> —
 `em slice revise` (and `mark-implemented`, which opens v<n> at merge when something is deferred to it) reads: when the doc reaches v<n> it rewrites each such item back to
 `- [ ] <original>`, so the question must be resolved or re-deferred before `--slice-ready` passes
 again. The prune rule above does not apply to a deferred item before v<n> (it stays as the
-record); once reopened it is an ordinary open question.
+record); once reopened it is an ordinary open question. A deferred item describes v<n>, not the
+version that was signed, so it sits **outside `ratifiedHash`** (GH #253, with the section heading
+and its blank lines; see the `ratifiedHash` row above) — which is what lets `em slice defer` write
+one into a ratified or shipped doc. Every other line of the section — an answered `- [x]`, a hand-added
+`- [ ]` — is inside the hash and moves it.
 
 **Not a parsing/grammar change.** `countOpenQuestions()` (`sliceDoc.ts`) and
 `slice-ready-open-questions-unchecked` (`sliceReadyValidate.ts`,
@@ -515,6 +608,13 @@ one it is asking about:
   slice shipped, and which" is `shippedRecordOf()` (`src/catalog/sliceDoc.ts`); `em export`
   publishes its answer as `slice.doc.shipped`.
 
+**Reading a PR that shows `status: draft`.** When `mark-implemented` opened the next version
+(`status: draft`, `version: <N+1>`), the diff of that slice doc does not say "never marked": the
+`shippedVersion: <N>` / `implementedIn:` lines **are** the record that v<N> was implemented, and
+`status:` is the state of v<N+1>. The command prints a notice naming both
+([cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-mark-implemented-file-slice-key-pr-url)), and `em status` lists the slice
+as `implemented (v<N>) · draft v<N+1> open` rather than a bare `draft`.
+
 So a shipped slice can be a `draft` again. `em slice revise <key>`
 ([cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-revise-file-slice-key)) opens v<N+1> as `status: draft`, bumps
 `version:`, clears the prior version's review and sign-off, and leaves `implementedIn`/`shipped*`
@@ -522,6 +622,10 @@ alone — v<N> stays shipped. `em slice mark-implemented` does the same automati
 question was deferred to v<N+1> (`em slice defer`), so known work is on the list the moment the
 previous version lands. Version 2 then takes both human gates like version 1 did: `em slice review
 --by`, then `em slice ratify --by` (which records a fresh `ratifiedRef`/`ratifiedHash`).
+A ratified doc that never shipped may instead be reopened at the **same** `version:` with
+`em slice revise --withdraw --keep-version` (GH #262) — a correction before a first release, not a
+delta, so no `## Delta` is owed; the status flip and sign-off clearing are the same. Refused on a
+shipped doc: the shipped version keeps its number.
 
 The deliberate mismatch — `version: 2` open while `implementedIn`/`shippedVersion` still name v1's
 work — is not staleness, it's the **drift signal**: `em export`'s `slice.doc.driftSignal` is
@@ -546,14 +650,17 @@ ratification of v<N> is withdrawn and nothing shipped, so no shipped record is w
 withdraws the only implementable version, `em slice revise` **refuses it without `--withdraw`**
 (GH #236).
 
-**Questions found against a ratified or shipped version are queued, not written into the body**
-(GH #236). `ratifiedHash` covers the whole body, `## Open Questions` included, so `em slice defer` on
-a `ready-to-implement` + `ratifiedBy:` or `implemented` doc does not edit the doc: it records the
-question in the model's `.event-modeling.md` as queued for `<key>@v<N+1>` (exact bullet shape in
-[cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-defer-file-slice-key-question)), keeping `ratifiedHash` and `--slice-ready`
-valid. When v<N+1> opens as a draft — `mark-implemented` at merge, or `revise` — each queued item is
-injected into that draft's `## Open Questions` (unchecked, carrying its decision) and the queue is
-cleared. `em export` reports the waiting count as `slice.doc.queuedForNext` (schema `1.17`). **A
+**Questions found against a ratified or shipped version are written into the body, outside the
+hash** (GH #253, superseding GH #236's 1.16 queue). `ratifiedHash` leaves out the `## Open Questions`
+heading and its `deferred to v<n>` items, so `em slice defer` on a `ready-to-implement` +
+`ratifiedBy:` or `implemented` doc appends the already-deferred item
+`- [x] <question> — v<N>: <decision>; deferred to v<n> (<date>[, <by>])` to the doc — visible to
+every reader of the ratified doc — and `ratifiedHash`, `--slice-ready` and `ratify`'s re-run all
+stay valid. When v<n> opens as a draft — `mark-implemented` at merge, or `revise` — the item is
+reopened as `- [ ] <question>` exactly as a pre-ratification deferral is. A question `em slice
+defer` queued in `.event-modeling.md` under 1.16.x is still injected when the next draft opens, and
+`em upgrade`'s `ratified-hash-scope` step moves any leftover into its doc. `em export` reports the
+work waiting on later versions as `slice.doc.queuedForNext` (schema `1.17`). **A
 `ready-to-implement` doc with no `ratifiedBy`** is the leftover of a pre-1.15 `reratify` (which
 bumped the version and left the doc unsigned at that status); no command produces it any more and
 `em slice ratify` no longer accepts it — `em slice revise` reopens it as a `draft` at the same

package/plugin/shared/templates/slice.md

@@ -210,15 +210,23 @@ an event directly.}}
      --json` → slice.doc.scenarios). Cover the happy path AND the key rule boundaries, one block
      per case: a `### Scenario: <title>` heading, then exactly the three column-0 bullets
      `- **Given:**`, `- **When:**`, `- **Then:**`, each with its beats as nested `  - ` bullets.
-     A block missing any of the three is flagged `slice-doc/structured-section-malformed`. -->
+     A block missing any of the three is flagged `slice-doc/structured-section-malformed`.
+     Quality (advisory warnings): each scenario is tied to exactly ONE command — its When names
+     this slice's command (a reaction slice: the reaction, its view, or the command it triggers); its Then names an event (or a stated no-op)
+     this slice records, or a rejection/error; and it CITES the INV ids it exercises (in the
+     title or any bullet). Every INV declared for the slice should be cited by some scenario
+     (`scenario-when-not-command`, `scenario-then-not-outcome`, `invariant-without-scenario`). -->
 ### Scenario: Happy path
 - **Given:**
   - {{starting state / prior events}}
 - **When:**
-  - {{command/trigger}}
+  - {{the command, by name}}
 - **Then:**
-  - {{event(s) recorded}}
+  - {{the event(s) recorded, by name}}
   - {{resulting read-model change}}
+<!-- Add one block per rule boundary, citing the INV id in the title, e.g.
+     `### Scenario: Non-positive total is rejected (INV-CHK-1)` — When names the command, Then
+     names the rejection. -->
 
 ## Alternate & Error Flows
 <!-- Failure paths, retries, compensations, timeouts, idempotency. -->

package/plugin/skills/conform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conform
-em-version: 1.16.1
+em-version: 1.18.0
 description: >-
   Use when checking a ratified event model (and its slice docs) for drift against the codebase
   that implements it — advisory only, never a gate, never an unprompted edit — or when walking
@@ -45,7 +45,8 @@ Ruling on a finding is a human gate, like ratifying a slice
 decides, and `em conform-supersede ... --locus <model|doc|code|none> --by <name>` records the
 ruling on the findings record (and stamps the report) — never rule on your own judgment. Once
 every finding touching a slice is ruled, `em slice conform <model-name>.em <key> --at <rev>`
-certifies that version of the slice.
+certifies that version of the slice (`--at build:<id>` / `deploy:<id>` when the swept commit
+will not stay reachable — a PR branch under squash/rebase merges; GH #261).
 
 End of phase: state file's `Last conformance:` marker updated (via `em state set-conformance` —
 refuses while any `implemented` slice still has an unruled finding; `--partial` escapes with a

package/plugin/skills/conform/reference/conform.md

@@ -320,8 +320,15 @@ slice with no unruled findings left:
 
 ```
 em slice conform <model-name>.em <slice-key> --at <target-repo revision>
+em slice conform <model-name>.em <slice-key> --at <kind>:<id>      # e.g. build:1234 — what the sweep exercised, when its commit will not stay reachable (GH #261)
 ```
 
+If you certified from a pull-request branch and the repo squash- or rebase-merges, the branch
+HEAD will dangle once the branch is deleted. Either pass a commit the target branch will keep
+(the merge commit) or record the deployment/build you actually swept as `--at build:<id>` /
+`--at deploy:<id>` / `--at env:<id>` — and write the same string as the findings file's
+`revision`, so the findings-check gate still matches.
+
 — records `conformedVersion`/`conformedAt`/`conformedOn` on that slice's doc, so
 `driftSignal` reads `in-sync` again (it reads `uncertified` for an implemented slice that's never
 been through this) instead of just trusting `implementedIn`. Legal only for `status: implemented`