@milehimikey/em 1.17.0 → 1.18.0

package/plugin/shared/reference/em-dsl.md

@@ -23,6 +23,7 @@ em render <file>                                                    # transpile
 em render <file> -o, --out <path>                                   # output path (extension picks the format)
 em render <file> -T, --format <fmt>                                 # output format (svg, png, pdf, ...)
 em render <file> --slice <name>                                     # render only this slice, redrawn in its own canonical pattern shape (default out: slices/<kebab-slug>.svg)
+em render <file> --storyline <name>                                 # render only this storyline: its slices in order, preceded by dimmed stub columns for what they read from outside it (and the end state of a storyline it comes `after`) (default out: storylines/<kebab-slug>.svg)
 em render <file> --emit-dot                                         # print the generated DOT instead of rendering
 em render <file> --keep-empty-lanes                                 # keep the API lane even when empty
 em export <file>                                                    # export a versioned JSON snapshot of the normalized model
@@ -69,13 +70,16 @@ em slice index <file>                                               # rewrite th
 em slice index <file> --check                                       # verify the table is current; exit non-zero on drift without writing (CI)
 em slice mark-implemented <file> <slice-key> <pr-url>               # flip a slice doc's frontmatter to `status: implemented` / `implementedIn: <pr-url>` — the one edit an implementing agent makes to a ratified doc at merge (MIL-103, replaces the em-sdd-bridge `em-sdd-mark-implemented` script; see reference/implement.md §6). Applies only to a `ready-to-implement` doc (MIL-277: a `draft`/`reviewed` doc refuses — ratify first). Also records the shipped version beside the link (MIL-284): `shippedVersion:`, `shippedRef:` (the doc's `ratifiedRef:`, when it has one) and `shippedOn:`, and opens the next version as a `draft` when an Open Question was deferred to it (MIL-283). Idempotent on the same URL — also after that draft opened; refuses to overwrite a different one; never touches the doc body except to re-open those deferred questions
 em slice mark-implemented <file> <slice-key> <pr-url> --on <date>   # merge date recorded as `shippedOn:`, YYYY-MM-DD (default: today, local date; MIL-284)
+em slice mark-implemented <file> <slice-key> <pr-url> --json        # print a JSON document instead of text: { path, changed, implementedIn, nextDraft: { version, reopened[] } | null } (GH #285)
 em slice review <file> <slice-key>                                  # flip a slice doc's frontmatter to `status: reviewed` and record `reviewedBy:`/`reviewedOn:` — the FIRST of the two human gates (MIL-201, docs/process.md#the-slice-lifecycle-gates): the room walked this slice and every open question it raised is resolved. Ratification is a separate, later gate (`em slice ratify`). Legal from `status: draft`; idempotent on the same --by/--on pair; refuses to overwrite a different one already recorded; refuses a doc already `ready-to-implement`/`implemented`; never touches `version:` or the doc body
 em slice review <file> <slice-key> --by <name>                      # the reviewer's (or facilitator's) name
 em slice review <file> <slice-key> --on <date>                      # review date, YYYY-MM-DD (default: today, local date)
+em slice review <file> <slice-key> --roster <path>                  # ratifier roster to check --by against (GH #259; default: the nearest ratifiers.yaml above the model, none = unrestricted)
 em slice ratify <file> <slice-key>                                  # flip a slice doc's frontmatter to `status: ready-to-implement` and record `ratifiedBy:`/`ratifiedOn:` — the handoff sign-off (MIL-165, docs/process.md#the-slice-lifecycle-gates) that makes who ratified, and when, a first-class recorded fact. The review gate is a check on the doc's current `status:`, not on whether `reviewedBy:`/`reviewedOn:` are populated: a doc at `reviewed` passes; a `ready-to-implement` doc only when the same signer is completing their own record (since 1.15.0, MIL-283 — a new sign-off is a new version: `em slice revise`); any other status — a `draft` that never went through `em slice review` — is refused unless --skip-review is passed. Idempotent on the same --by/--on pair; refuses to overwrite a different one already recorded, and (MIL-284) a same-pair re-run on a doc whose body moved after sign-off; never touches `version:` or the doc body. Inside a git work tree also records `ratifiedRef:` (HEAD, refusing a doc with uncommitted changes) and always `ratifiedHash:`; with --no-ref (GH #255) only the hash — for a repo whose squash/rebase merges would leave the ref unreachable — and git is not consulted
 em slice ratify <file> <slice-key> --by <name>                      # the ratifier's name
 em slice ratify <file> <slice-key> --no-ref                         # record ratifiedHash: only, no ratifiedRef: (GH #255) — the signed content keeps its identity, nothing points at a commit a squash or rebase merge would orphan; the uncommitted-changes check does not apply
 em slice ratify <file> <slice-key> --on <date>                      # ratification date, YYYY-MM-DD (default: today, local date)
+em slice ratify <file> <slice-key> --roster <path>                  # ratifier roster to check --by against (GH #259; default: the nearest ratifiers.yaml above the model, none = unrestricted)
 em slice ratify <file> <slice-key> --skip-review                    # ratify without a recorded review — prints a loud notice on stderr and records `reviewSkipped: <status>` on the doc (GH #260) so the bypass is visible to later readers, `em export` and `--slice-ready --json`; cleared by `em slice revise`
 em slice ratify <file> <slice-key> --meaning-unchanged              # API-first sign-off (MIL-238): this version does not change what the public contract means — records `meaningConfirmed: true`; required (or --contract-change) on a slice touching a `public` element
 em slice ratify <file> <slice-key> --contract-change <why>          # API-first sign-off (MIL-238): a consumer must read this change differently, and why — records `contractChange: "<why>"`
@@ -129,6 +133,10 @@ em conform-supersede <file> <report-path> --locus <locus>           # who/what t
 em conform-supersede <file> <report-path> --by <name>               # who ruled on the named finding(s) (requires --locus)
 em conform-findings check <path>                                    # shape-validate a conformance/<date>-findings.json file (findingsSchemaVersion, required fields, enum values, ids sorted+unique, a ruled finding carries resolvedBy+resolvedOn) — exit 1 on shape errors. The conform skill writes this file directly alongside its report; this is how a headless run verifies what it just wrote.
 em conform-findings check <path> --json                             # print a JSON document instead of the text report
+em discover triage-check <file>                                     # validate a discovery/prd-triage.json (prdTriageSchemaVersion 1.0): shape, the shipped rubric version, every statement/storyline quote appearing verbatim in the input document, and every statement carrying a category, an outcome and (modeled/rewritten) a group + storyline — exit 1 on errors. The discover skill writes this file directly; this is how a headless run verifies it.
+em discover triage-check <file> --source <path>                     # the input PRD/spec to check quotes against (default: the file's own `source`, relative to it)
+em discover triage-check <file> --markdown                          # after a passing check, print the Markdown view of the record instead of the summary
+em discover triage-check <file> --json                              # print a JSON document instead of the text report
 em watch <file>                                                     # re-render on every save
 em watch <file> -o, --out <path>                                    # output path (extension picks the format)
 em watch <file> -T, --format <fmt>                                  # output format (svg, png, pdf, ...)
@@ -142,7 +150,11 @@ em validate <file> --list-public                                    # print only
 em validate <file> --fail-on-issues                                 # exit non-zero if the model has any open `issue`s (opt-in — issues are warnings and don't block by default)
 em validate <file> --slice-ready <key>                              # readiness gate for one slice (export key): status ready-to-implement, doc resolvable via note binding, zero unchecked Open Questions, a recorded ratifiedBy, and — for a slice touching a `public` element — a current contracts/<model key>.tsp; exits non-zero if not ready (MIL-87, MIL-259, MIL-238)
 em validate <file> --require-ratified-hash                          # with --slice-ready (GH #256): strict mode — a ready-to-implement doc with no `ratifiedHash:` is NOT ready (`slice-ready-missing-ratified-hash`, error; `ready: false` in --json). Off by default so docs ratified before em 1.15 keep passing; turn it on once legacy docs are re-ratified
+em validate <file> --strict                                         # promote advisory lints (GH #293: scenario-quality warnings) to errors: they fail the run and, with --slice-ready, block readiness
+em validate <file> --roster <path>                                  # with --slice-ready (GH #259): the ratifier roster to check `ratifiedBy` against (default: the nearest ratifiers.yaml above the model; none = unrestricted). A name the roster does not permit for the slice's context is `ratified-by-not-in-roster` (error)
 em validate <file> --check-signed-bodies                            # opt-in (GH #257): compare every slice doc that records a `ratifiedHash:` — ready, implemented, any status — to its body; a mismatch is `slice-body-changed-since-ratification` (error). A pre-1.17 whole-body hash with an intact body passes; a deferral written by `em slice defer` is outside the hash. The one check that still watches a shipped doc's signed content
+em validate <file> --shape                                          # GH #282: run only the advisory shape-family lints (storyline shape) and print rule / count / first ref / docs anchor; exit 0 always. With --json: `shapeSchemaVersion` 1.0 with per-rule finding arrays
+em validate <file> --waive-file <path>                              # with --shape: a baseline file (`<rule-code> <slice-key>` per line, or a bare slice key for every shape rule; `#` comments) whose shape findings are listed as waived and not counted; missing file = no waivers
 em validate <file> --json                                           # print a JSON document instead of text — works on a model WITH errors, unlike `em export` (MIL-128, see docs/cli.md); exit codes are unchanged
 em migrate <file>                                                   # rewrite the old two-slice Automation/Translation shape into the merged single-slice shape MIL-120 made canonical (see docs/cli.md)
 em migrate <file> --write                                           # apply the rewrite to the file (default: dry run — report only, write nothing)
@@ -196,6 +208,7 @@ em query slices <files> --status <s>                                # the slice'
 em query slices <files> --context <c>                               # match a slice with an event in this @Context
 em query slices <files> --persona <p>                               # match a slice with a ui in this @Persona
 em query slices <files> --tag <t>                                   # match a slice with an event carrying this tag key
+em query slices <files> --storyline <name>                          # match a slice declared in this `storyline` block
 em query slices <files> --json                                      # print a JSON document instead of the text report
 em query invariant <files>                                          # declaring slice + doc facts for one INV-* id, and (with --tests) its test citations
 em query invariant <files> --id <inv-id>                            # the INV-* id to look up
@@ -230,6 +243,12 @@ em engagement set <file> <slug> <key> --pr <url>                    # the slice'
 em engagement status <file> <slug>                                  # the Ledger joined with each slice doc's current status, plus whether the engagement is closable
 em engagement status <file> <slug> --json                           # print a JSON document instead of text (same document as the MCP engagement_status tool)
 em engagement close <file> <slug>                                   # set status: closed — refuses unless every slice is merged (recorded or inferred) or gap
+em roster init <file>                                               # write ratifiers.yaml beside the model, seeded from the names already recorded in the slice docs' `ratifiedBy:`/`reviewedBy:` (whole-model entries; narrow them with `contexts:` by hand). Refuses to overwrite an existing file unless --force; `em upgrade`'s grandfathered placeholder is not a name
+em roster init <file> --roster <path>                               # write the roster here instead of <model dir>/ratifiers.yaml
+em roster init <file> --force                                       # overwrite an existing roster file
+em roster check <file>                                              # check EVERY slice doc's recorded signers against the ratifier roster (GH #259) - `ratifiedBy` on ready-to-implement and implemented docs, `reviewedBy` on any doc - the whole-model CI gate that `--slice-ready <key>` (one ready slice) is not. Exit 1 on any violation or an invalid roster; no roster file = nothing to check, exit 0. The `grandfathered ...` placeholder is exempt (counted)
+em roster check <file> --roster <path>                              # roster to check against (default: the nearest ratifiers.yaml above the model)
+em roster check <file> --json                                       # print a JSON document (per-doc results, diagnostics with refs); exit codes unchanged
 em system [target]                                                  # verify a system — every model's `consumes` refs resolved against the other models' `public` events/views, the cross-model half of "both ends of a flow" (MIL-194/MIL-235, see docs/cli.md). Reads system.yaml when given (or found in the directory), else discovers every *.em in the repo
 em system [target] --json                                           # print a JSON document instead of the text report (see docs/cli.md)
 em system codeowners [target]                                       # generate (or --check) the managed CODEOWNERS block that routes review: each model's team on its design directory, and every team that `consumes` a model's public surface on that model's contract file (MIL-234, see docs/ci.md and docs/cli.md)
@@ -254,10 +273,13 @@ em ci init <model>                                                  # install .g
 em ci init <model> --tests <dir>                                    # test directory the coverage/status steps scan for INV-* citations
 em ci init <model> -f, --force                                      # replace an existing workflow file that has no GENERATED markers, or a managed block generated for a different set of models
 em ci init <model> --check                                          # verify both files match the current preset; exit non-zero on drift without writing (CI)
+em storyline suggest <file>                                         # advisory (GH #290): propose `storyline` blocks for a model that has none — one per distinct slice `source "url"`, the remaining slices grouped by the view-instance chains (`again`) they feed — printed as a unified diff on stdout (apply with `patch -p1` or `git apply`); never writes the model
 em upgrade <file>                                                   # bring a model repo authored under an older em (1.6 forward) up to the installed version: an ordered list of mechanical steps (skill bundle, reaction shape, state-file bullets, generated CI blocks, constitution scaffold) plus a human list of things no command can safely decide by itself (MIL-219, see docs/upgrading.md). Dry-run by default; --apply makes one git commit per applicable step, refusing on a dirty working tree
 em upgrade <file> --apply                                           # apply every applicable mechanical step, one git commit each, then a final `Em version:` commit
 em upgrade <file> --check                                           # exit non-zero only on a hard incompatibility (an existing but unparseable state file, an un-migratable .em shape) — writes nothing; what CI runs; the final line says why
 em upgrade <file> --json                                            # print a JSON document instead of text (dry-run/--check only, never with --apply)
+em upgrade <file> --fold-continuations                              # also run the opt-in fold-continuations step (stack consecutive continuations of one view into the first; continuationOf, doc join and index rows unchanged)
+em upgrade <file> --to-sugar                                        # (implies --fold-continuations; without --apply it is a dry run listing exactly what would fold): fold continuations into their host command slice as `view X again … shown on` lines — CHANGES continuationOf and the doc join to `<host>--again` and removes the folded slices' index rows
 ```
 <!-- GENERATED:cli:end -->
 
@@ -274,6 +296,10 @@ model "Name" [owner "Team"]      # diagram title; optional owning team(s), quote
 persona Name                     # a UI swimlane row (actor)
 context Name                     # an event swimlane row (bounded context / aggregate)
 
+storyline "Name" [source "url"] [after "Other"] {   # optional chapter grouping slices (see Storylines)
+  slice "Name" { ... }
+}
+
 slice "Name" [source "url"] {    # one vertical time step (a column); source is optional
   ui   Free Text @Persona        # screen; @Persona picks its row (defaults to first/"User")
   command Free Text              # state-changing request (API band)
@@ -296,7 +322,7 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
 | `ui` | persona | screen / interface | `@Persona` | `note`, `issue`, `divergence`, `{ fields }` |
 | `command` | API | state-changing request | — | `note`, `issue`, `divergence`, `renamed from`, `{ fields }`, standalone `invariant` line |
 | `view` | API | read model / projection | — | `from "Event"…`, `note`, `issue`, `divergence`, `public`, `{ fields }` |
-| `event` | context | recorded fact (past tense) | `@Context` | `note`, `issue`, `divergence`, `public`, `tag`, `renamed from`, `loops-to`, field-level `assigned`, `{ fields }`, standalone `invariant` line |
+| `event` | context | recorded fact (past tense); `event A \| B @Context` = alternative outcomes of ONE command, one slice, one shared cell | `@Context` | `note`, `issue`, `divergence`, `public`, `tag`, `renamed from`, `loops-to`, field-level `assigned`, `{ fields }`, standalone `invariant` line |
 | `processor` / `automation` / `saga` / `translation` | automation | system reaction / adapter | — | `from "…"`, `note`, `issue`, `divergence`, `{ fields }`; `translation` only: `consumes` |
 
 ### Clauses
@@ -312,6 +338,15 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   "to-do list") and pointing the reaction at that view. Name that view after the pending work
   (`Payments To Process`), never after the triggering event — a view reusing the event's name
   collides in the shared namespace and draws a duplicate-name warning.
+- **One event recorded by several commands** (two intents, one fact — `Create Product` and
+  `Create Product Variant` both ending in `Product Created`): repeat the event BARE in the later
+  slice with the same name and context. A bare repeat of an event with the same name and context is
+  ONE logical event — no `duplicate-name`, no marker (`again` stays view-only). The repeat inherits
+  the first declaration's fields, element-level `tag` clauses and `public`; declaring different ones
+  is the error `shared-event-field-mismatch`. A view's `from "E"` draws an arrow from every recording
+  site at or before it, and EVERY site needs a reader at or after it (add `view V again from "E"`
+  after the last site, or `event-unread` warns for that site). The same name in a different context
+  is still a `duplicate-name` warning.
 - **`again`** (views only): `view <Name> again [from "Event", …]` declares a later instance of an
   already-declared read model — the forward-only device for a view that evolves as later events
   land. Instances are ONE logical view: the first declaration owns the `note` binding; each
@@ -443,7 +478,11 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   into doc-only prose** — the marker keeps `em export`/the model aware the field exists (the
   `doc-model-field-mismatch` doc↔model check does not compare view field tables at all today —
   see the slice template's field-table guidance — so this is an export-side win specifically,
-  not yet a doc-drift check).
+  not yet a doc-drift check). **Collection fields (GH #288):** a view field typed `T[]` for a
+  declared `type T`, with `derived from "Child Created", "Child Deleted"`, embeds a child entity:
+  each field of `T` must trace to a named event (`fields-completeness/view-field-no-source`
+  otherwise). No add/remove/key clauses — `em slice sync` writes a `Collection of` note plus
+  one Given/Then scenario stub per named event in the view region (copy into `## Scenarios`), and `em export` sets `collection: true`.
 - **Fields:** `command Place Order { orderId: UUID, items: LineItem[], customerId }` — inline or
   one-per-line. Types are free text (no semantic checking) UNLESS the type string names a
   declared `type` (see Named types below), in which case it resolves to a structured
@@ -472,6 +511,22 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   of relying on prose. Purely metadata — no visual marker, not validated. Don't confuse it with
   an element's `note "path.md"` (a markdown file link, not a URL).
 
+- **`storyline "Name" [source "url"] [after "Other"] { slice … }`** (GH #277) groups slices into a
+  named chapter — the main journey, and secondary stories (retire a product, extend an attribute).
+  Slices keep their file-order timeline position; a slice outside any storyline is allowed;
+  storylines don't nest and a repeated name continues that storyline (its slices join it; a continuation may not add or change
+  `source`/`after` — parse error). The full render draws a
+  labelled band above the slice headers; `em render --storyline "Name"` draws one story alone, with the
+  elements it reads from outside as dimmed stub columns. `em export` carries `slice.storyline` and
+  `model.storylines[]`; `em query slices --storyline`; `em slice index` adds a Storyline column. Once
+  any storyline exists a slice outside every one is the advisory warning `slice-outside-storyline`.
+  `after "<other>"` reads the storyline as if its slices followed the referenced storyline's last
+  slice: `from`/`again`/reaction `from` resolve against the composed timeline (referenced → this), the
+  forward-only checks use it, a backward feed into the referenced storyline, an `after` cycle
+  (`storyline-after-cycle`), an unknown target (`storyline-after-unknown`) or a storyline declared above
+  the one it comes after when a flow would draw right-to-left (`storyline-after-out-of-order`) is an
+  error. Without `after`, file order is the only timeline.
+
 ### Named types
 
 `type Name { field: Type, ... }` declares a reusable structured shape at the top level (any
@@ -634,8 +689,9 @@ slice "Read Quote — created" {
   **prefer `view X again`** for every instance after the first (see Clauses) — **each instance
   carries its own consumer** (the `ui` that reads it, or a reaction), not just the last one. `again`
   instances are exempt from the duplicate-name warning even when referenced, and each reference
-  resolves to the right instance — a plain repeat only stays warning-free while nothing references it by name, and
-  resolves to the *first* declaration when something does. **Wire each event to a read model exactly
+  resolves to the right instance — a plain repeat of a view only stays warning-free while nothing references it by name, and
+  resolves to the *first* declaration when something does (the exception is a same-context event
+  repeat, which is one logical event — see above). **Wire each event to a read model exactly
   once:** a repeated instance's `from` lists only the **new** events since the previous instance
   (not cumulative), or the event draws a duplicate arrow to the same read model at every repeat. (An
   event may still feed several *different* read models, once each.)
@@ -656,6 +712,13 @@ consumer is an obligation to ship an endpoint, no `ui` means internal-only, and
 the published integration surface — see `reference/implement.md`'s "Interface obligations"
 paragraph in the `event-modeling-implement` skill (§2).
 
+- **Continuations without ceremony (GH #287).** Several `view X again` lines may share one
+  continuation slice (they stack in the `api` cell); `view X again from "E"` written inside a
+  command's own slice is sugar for a synthesized continuation column right after it (one column per host slice, lines stacked; key
+  `<slice-key>--again`, no doc, not in `em slice index`; consumer = the slice's first `ui`,
+  or `shown on "Screen"` — required in a reaction slice with no `ui`); and a continuation slice may omit its name — it is auto-named
+  `"<View> View: <Event>"`. Instances still never connect.
+
 ### Reaction wiring — no positional gotcha
 
 A reaction's command is inferred from **same-slice presence**, exactly like `ui -> command`: put
@@ -676,7 +739,13 @@ it to the slice that displays the read model, or drop it.
 
 **Errors (must fix):**
 1. **Band collision** — two elements of the same band in one slice (e.g. two `command`s, or two
-   `ui`s in the *same* persona row). Split them into separate slices/personas.
+   `ui`s in the *same* persona row). Split them into separate slices/personas. Two events on one
+   context that are alternative outcomes of one command are NOT a split: write
+   `event A | B @Context` (identical payloads) or `oneof { event A @Context { … }  event B @Context { … } }`
+   (own fields/clauses per alternative) — one slice, one shared cell, one command, one shared context; each
+   alternative is a full event, and a standalone `invariant` after them binds to all.
+   Alternatives with no command in the slice are an error (`alternative-events-no-command`), and the same
+   command repeated across slices warns (`command-repeated-across-slices`).
 2. **Unknown event source** — `view X from "Event"` where the event doesn't exist anywhere.
 3. **Unknown read-model source** — `processor X from "View"` where the view doesn't exist.
 4. **Arrow endpoint mismatch** — `arrow A -> B` where A or B matches no element name.
@@ -774,9 +843,11 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 <!-- GENERATED:validate-rules:start -- run `npm run docs:generate` to refresh, do not hand-edit -->
 | Code | Severity | Title | Fix |
 |---|---|---|---|
+| `alternative-events-no-command` | error | Alternative events without a command | Add the command whose decision records one of the alternatives, in the same slice. |
 | `arrow-backward` | error | Backward arrow | Restructure so the target comes later. |
 | `arrow-unresolved-source` | error | Arrow source unresolved | Fix the arrow's source name. |
 | `arrow-unresolved-target` | error | Arrow target unresolved | Fix the arrow's target name. |
+| `automation-split-by-outcome` | warning | Reaction split into one slice per outcome | Model one Automation slice recording the outcomes as alternative events — `event A | B @Context` (docs/patterns.md#automation). |
 | `binding-missing-file` | warning | Doc binding points at a missing file | Create the slice doc, or fix the `note` path. |
 | `both-ends-of-a-flow/command-no-event` | warning | Command without event | Add the event this command records. |
 | `both-ends-of-a-flow/command-untriggered` | warning | Command with no trigger | Add a `ui` or the reaction that issues it, both in this slice. |
@@ -786,6 +857,8 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `both-ends-of-a-flow/ui-unbacked` | warning | `ui` with no read model or command | Add a `view` it displays, or the command it triggers. |
 | `both-ends-of-a-flow/view-unconsumed` | warning | Read model with no consumer | Add a `ui` or reaction that consumes it, or drop this instance. |
 | `code-spans-seam` | warning | Code change spans a seam | Keep one code module per model and change the two sides of a seam in separate change sets. |
+| `command-repeated-across-slices` | warning | Command repeated across slices | Merge the slices: one command with several outcomes is one slice — `event A | B @Context`. |
+| `command-second-intent` | warning | Command carries a second intent | Split the conditional rule set into its own command; both commands may record the same event (a bare repeat of the event is legal). |
 | `connection-legality/illegal-pair` | error | Illegal connection | Only ui→command→event→view→ui and view→reaction→command are legal — the message names the missing step. |
 | `consumer-not-adapted` | error | Consuming translation no longer matches the producer's public element | Update the translation's field block to the producer's current fields (a renamed field names its new name in the message). Additive producer changes never raise this — consumers tolerate unknown fields. |
 | `consumes-unknown-element` | error | `consumes` names no public element of that model | Point the ref at an element the producer marks `public` (`em export` lists them), or ask the producer to publish it. |
@@ -798,6 +871,8 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `doc-model-element-not-in-model` | warning | Doc names an element the model doesn't have | Add the element to the model, or fix/remove it in the doc. |
 | `doc-model-field-mismatch` | warning | Doc/model field mismatch | Reconcile the field table with the model's fields — names and types. |
 | `doc-model-pattern-mismatch` | warning | Doc/model pattern mismatch | Fix the doc's `pattern:` frontmatter to match the model, or restructure the slice to match the doc. |
+| `doc-names-unfed-event` | warning | Doc names an event its view does not read | Add the event to the view's `from` in the model (if the edge is real), or fix the doc's Source column / scenario. |
+| `doc-omits-fed-event` | warning | Doc omits an event its view reads | Mention the event in the view's Source column (run `em slice sync`), or drop it from the view's `from`. |
 | `duplicate-element-ref` | warning | Duplicate element ref | Rename the element so its export ref is unique. |
 | `duplicate-model-key` | warning | Duplicate model key | Give each model a unique `model "Name"` so its key (and every cross-model ref) is stable. |
 | `duplicate-name` | warning | Duplicate name | Rename one of the duplicates. |
@@ -809,6 +884,7 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `frontmatter-coherence-implemented-without-link` | warning | Implemented without a link | Add `implementedIn` once the slice ships. |
 | `frontmatter-invalid` | warning | Invalid or missing frontmatter | Add the required frontmatter keys, or add a frontmatter block. |
 | `grid-collision` | error | Band collision | Split the colliding elements into separate slices. |
+| `invariant-without-scenario` | warning | Invariant cited by no scenario | Cite the INV id in the Given/When/Then (or title) of the scenario that exercises it, or add one. |
 | `invariants/declared-in-both` | warning | Invariant declared in the model and in a slice doc | Keep the model's `invariant` line; in the doc, cite the ID and elaborate instead of restating it as a `**INV-…:**` rule. |
 | `invariants/doc-cites-undeclared` | warning | Slice doc cites an undeclared invariant | Declare the ID in the model (or in a slice doc's Invariants section), or fix the citation. |
 | `invariants/duplicate-id` | error | Duplicate invariant ID | Give each model-declared invariant its own ID — a rule is declared once, on the element it guards. |
@@ -833,18 +909,27 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `public-name-not-unique` | error | Two public elements of one kind share a name | Rename one of them (or drop `public` from one): a consumer's `consumes <model>:<kind>.<slug>` must name exactly one element. |
 | `reaction-from-future-view` | error | Backward timeline (reaction reads a future view) | Declare the view in or before the reaction's slice. |
 | `reaction-from-unresolved` | error | Unknown read-model source | Project the event into a view first, or fix the `from` reference. |
+| `retry-slice-of` | warning | Slice only retries another command | Re-fire the same reaction via `view … again from` the retry-scheduled event; a different actor's override is its own slice with its own command (docs/patterns.md#automation). |
+| `scenario-then-not-outcome` | warning | Scenario's Then names no event or rejection | Make the Then bullets name the event(s) the command records, or the rejection/error it returns. |
+| `scenario-when-not-command` | warning | Scenario's When does not name the slice's command | Make the When bullet name the slice's command (for a reaction slice: the command, the reaction element, or a view of the slice) — each scenario exercises exactly one command. For a Translation, naming the translation element satisfies it. |
 | `seam-consumer-not-reaction` | error | Seam consumer is not a reaction | Point `to` at a translation/automation element (or a slice containing exactly one). |
 | `seam-crossing` | error | Change set alters a contract and its consumer together | Split the change set: land the producer's public-surface change first, then adapt the consuming model in a later change. Review on the contract file is the only override. |
 | `seam-crossing-greenfield` | warning | New public surface lands with its first consumer | Nothing to fix: a public element no consumer was bound to at the base revision is new surface, not a crossing. Later changes to it are crossings. |
 | `seam-duplicate` | warning | Duplicate seam | Remove the repeated `from`/`to` pair. |
 | `seam-endpoint-unresolved` | error | Seam endpoint does not resolve | Fix the ref to an element the named model actually exports (`em export` lists every ref), or re-declare the seam after a rename. |
 | `seam-source-not-public` | error | Seam source is not `public` | Mark the event/view `public` in its model, or point the seam at the element that is. |
+| `shared-event-field-mismatch` | error | Shared event declared with different fields, tags or public | Repeat the event bare to inherit the first declaration's fields, tags and public, or make them identical. |
 | `slice-doc/structured-section-malformed` | warning | Malformed structured section | Balance the `<!-- GENERATED:em-slice-…:start -->`/`:end -->` markers (re-create the doc with `em slice new --force` if they are lost), restore the template's table header and run `em slice sync`, and give every `### Scenario:` block a Given, When and Then bullet. |
+| `slice-outside-storyline` | warning | Slice outside every storyline | Move the slice inside one of the model's `storyline` blocks (advisory: storylines can be adopted incrementally). |
+| `storyline-after-cycle` | error | Storyline `after` cycle | Remove an `after` clause so no storyline comes after itself. |
+| `storyline-after-out-of-order` | error | Backward timeline (storyline declared above the one it comes after) | Move the storyline block below the storyline it comes `after`, or restructure the feed. |
+| `storyline-after-unknown` | error | `after` names an unknown storyline | Name a storyline declared in this model, or drop the `after` clause. |
 | `system-manifest-invalid` | error | Seam manifest invalid | Fix the manifest: `systemSchemaVersion: "2.0"`, `models:` with a readable `source` per model, and nothing else (`seams:`/`owner:` moved into the models — run `em upgrade`). |
 | `system-manifest-outdated` | warning | Seam manifest is schema 1.0 | Run `em upgrade <model>.em --apply` once: it moves `seams:` into `consumes` clauses and `owner:` onto each model header, and rewrites the manifest to 2.0. |
 | `system-model-key-mismatch` | error | Manifest model key differs from the export's `model.key` | Rename the manifest's `models:` key to the computed key the message prints. |
 | `tag-composite-unknown-field` | error | Composite tag names an unknown field | Fix the field name, or add it to the event's fields. |
 | `tag-duplicate-key` | error | Duplicate tag key | Rename one of the tags so every key on the event is unique. |
+| `timeline-entity-clustered` | warning | Lifecycle-per-entity shape (storyline order) | If these are create/update/archive steps on one entity, order the slices by the business journey, interleaving contexts as the story does; if they are steps of one journey, show a screen (a view) after each step. See docs/storyline.md. |
 | `translation-name-collision` | warning | Translation name reused for different producers | Use a distinct name per producer to avoid confusion. |
 | `type-cycle` | error | Cyclic type reference | Break the cycle, or route the self/mutual reference through an array. |
 | `ui-shares-slice-with-automation` | warning | `ui` shares slice with a reaction | Move the `ui` to the slice that displays the read model, or drop it. |

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.