@milehimikey/em 1.17.0 → 1.18.1

package/.claude/skills/event-modeling-shared/reference/methodology.md

@@ -144,6 +144,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.**
@@ -193,6 +204,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**,
@@ -256,6 +521,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/.claude/skills/event-modeling-shared/reference/slice-doc-schema.md

@@ -88,6 +88,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 |
@@ -261,6 +323,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.
@@ -397,7 +474,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
@@ -436,12 +513,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`
@@ -520,6 +607,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*`

package/.claude/skills/event-modeling-shared/templates/slice.md

@@ -209,15 +209,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/.claude-plugin/marketplace.json

@@ -1,9 +1,9 @@
 {
-  "name": "em-1-17-0",
+  "name": "em-1-18-1",
   "owner": {
     "name": "Mike Key"
   },
-  "description": "em v1.17.0: the Event Modeling skill bundle and MCP server as a Claude Code plugin.",
+  "description": "em v1.18.1: the Event Modeling skill bundle and MCP server as a Claude Code plugin.",
   "plugins": [
     {
       "name": "em",

package/dist/catalog/docModelConsistencyValidate.js

@@ -62,7 +62,10 @@ import { pushDiag } from "../model/rules.js";
 import { classifySlicePattern, slicePatternLabel } from "./classify.js";
 import { resolveSliceDocJoin } from "./docJoin.js";
 import { readSliceDoc } from "./readSliceDoc.js";
+import { checkScenarioQuality } from "./scenarioQualityValidate.js";
 import { findStructuredSectionProblems, splitCells } from "./sliceSections.js";
+import { parseScenariosLenient } from "./scenarios.js";
+import { viewSourceNames } from "../model/continuation.js";
 const COMMAND_MARKER = /^\*\*Command:\*\*\s*`([^`]+)`\s*$/;
 const EVENT_MARKER = /^\*\*Event:\*\*\s*`([^`]+)`(?:\s*→\s*context\s*`[^`]+`\s*)?$/;
 const VIEW_MARKER = /^-\s*\*\*View:\*\*\s*`([^`]+)`/;
@@ -240,6 +243,8 @@ export function validateDocModelConsistency(model, refs, baseDir) {
                 message: `slice doc "${docPath}" (slice "${ownerKey}"): ${problem}`,
             });
         }
+        // GH #293: scenario-quality advisories (catalog/scenarioQualityValidate.ts).
+        checkScenarioQuality(diags, parsed.body, docPath, sliceIndices, ownerKey, model, refs, baseDir);
         const markers = parseDocMarkers(parsed.body);
         const coveredNames = sliceIndices.map((i) => model.slices[i].name);
         for (const kind of ["command", "event", "view"]) {
@@ -263,6 +268,7 @@ export function validateDocModelConsistency(model, refs, baseDir) {
             checkRosterDirections(diags, kind, docPath, docByName, modelByName, ownerSlice, ownerKey, coveredNames, model, refs);
             checkFields(diags, kind, docPath, docByName, modelByName, model, refs);
         }
+        checkViewFeeds(diags, parsed, docPath, markers, sliceIndices, ownerSlice, model, refs);
     }
     return diags;
 }
@@ -368,4 +374,158 @@ function checkFields(diags, kind, docPath, docByName, modelByName, model, refs)
         }
     }
 }
+// GH #294 (MIL-245): a State View doc's claims about WHICH EVENTS feed the view, against the
+// model's `from` union (`viewSourceNames`, across `again` instances). Two advisory warnings:
+//   doc-names-unfed-event — the doc's field-table Source column (or, when the doc has exactly one
+//     view, a scenario Given/Then item) names an event that exists in the model but is not among
+//     the view's sources (the toolshed case: prose anticipated an edge the model never drew).
+//   doc-omits-fed-event — the model feeds the view an event the doc body never mentions.
+// Event names are found by scanning text for the model's own event names (longest first, word-
+// bounded, case-insensitive), so a name embedded in a longer event name is not double-counted.
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Normalized names of the model events mentioned in `text`. */
+function mentionedEvents(text, eventNames) {
+    const found = new Set();
+    let rest = text;
+    for (const name of [...eventNames].sort((a, b) => b.length - a.length)) {
+        const re = new RegExp(`(?<![\\p{L}\\p{N}])${escapeRe(name).replace(/\s+/g, "\\s+")}(?![\\p{L}\\p{N}])`, "giu");
+        if (re.test(rest)) {
+            found.add(normalizeName(name));
+            re.lastIndex = 0;
+            rest = rest.replace(re, " ");
+        }
+    }
+    return found;
+}
+/** The text of every cell in the Source column of the first field table in lines[start, end). */
+function sourceColumnCells(lines, start, end) {
+    for (let i = start; i < end - 1; i++) {
+        if (!TABLE_ROW.test(lines[i]) || !TABLE_ROW.test(lines[i + 1]))
+            continue;
+        const sep = splitCells(lines[i + 1]);
+        if (sep.length === 0 || !sep.every((c) => TABLE_SEPARATOR_CELL.test(c)))
+            continue;
+        const header = splitCells(lines[i]);
+        if (normalizeName(header[0] ?? "") !== "field")
+            continue;
+        const col = header.findIndex((c) => normalizeName(c).startsWith("source"));
+        if (col < 0)
+            return [];
+        const cells = [];
+        for (let j = i + 2; j < end && TABLE_ROW.test(lines[j]); j++) {
+            const c = splitCells(lines[j])[col];
+            if (c && !PLACEHOLDER.test(c))
+                cells.push({ text: c, idx: j });
+        }
+        return cells;
+    }
+    return [];
+}
+/** Given/Then items (with a body line index) of every scenario, via the shared lenient reader
+ *  (`### Scenario:` blocks, the older bullet format, `## Delta` blocks, wrapped lines). The reader
+ *  carries only a block's heading line, so an item's line is found by searching forward from it
+ *  for the item's opening text. */
+function scenarioGivenThenLines(body, lines) {
+    const out = [];
+    const scenarios = parseScenariosLenient(body);
+    scenarios.forEach((sc, k) => {
+        // search only inside this block: from its heading to the next scenario's heading
+        const from = sc.line - 1;
+        const to = k + 1 < scenarios.length ? scenarios[k + 1].line - 1 : lines.length;
+        for (const item of [...sc.given, ...sc.then]) {
+            let idx = from;
+            for (let j = from; j < to; j++) {
+                // a wrapped item is joined with spaces by the reader, so compare against the item's
+                // opening: the physical line's own text (label and bullet stripped) must begin it
+                const seg = lines[j].replace(/^\s*[-*]\s+(\*\*(?:Given|When|Then):\*\*\s*)?/, "").trim();
+                if (seg !== "" && item.startsWith(seg.slice(0, 24))) {
+                    idx = j;
+                    break;
+                }
+            }
+            out.push({ text: item, idx });
+        }
+    });
+    return out;
+}
+function checkViewFeeds(diags, doc, docPath, markers, sliceIndices, ownerSlice, model, refs) {
+    const docViews = markers.filter((m) => m.kind === "view");
+    if (docViews.length === 0)
+        return;
+    const lines = doc.body.split(/\r?\n/);
+    const lineOffset = doc.raw.split(/\r?\n/).length - lines.length;
+    const eventNames = model.elements.filter((e) => e.kind === "event").map((e) => e.name);
+    if (eventNames.length === 0)
+        return;
+    const modelViews = new Map();
+    for (const i of sliceIndices) {
+        for (const el of model.slices[i].elements) {
+            if (el.kind !== "view")
+                continue;
+            const key = normalizeName(el.name);
+            if (!modelViews.has(key))
+                modelViews.set(key, el);
+        }
+    }
+    const matched = docViews.filter((m) => modelViews.has(normalizeName(m.name)));
+    const bodyMentions = mentionedEvents(doc.body, eventNames);
+    // Scenario text attaches to a view only when the doc has exactly one matched view AND the doc's
+    // own slice is the State View that holds it — a State Change doc that `covers:` a view slice, or
+    // a merged reaction doc with a to-do view, writes scenarios about its command, not the view.
+    const ownsView = (el) => classifySlicePattern(ownerSlice) === "state-view" && model.slices[el.sliceIndex] === ownerSlice;
+    const scenarioLines = matched.length === 1 && ownsView(modelViews.get(normalizeName(matched[0].name))) ? scenarioGivenThenLines(doc.body, lines) : [];
+    for (const marker of matched) {
+        const view = modelViews.get(normalizeName(marker.name));
+        const sources = viewSourceNames(model, view);
+        const fed = new Set(sources.map(normalizeName));
+        const refsOut = [refs.sliceKeys[view.sliceIndex], refs.refById.get(view.id)];
+        let end = lines.length;
+        for (let j = marker.bodyLine + 1; j < lines.length; j++) {
+            if (/^##\s/.test(lines[j]) || matchMarker(lines[j])) {
+                end = j;
+                break;
+            }
+        }
+        // event -> body line index of its first mention
+        const named = new Map();
+        const note = (text, idx) => {
+            for (const e of mentionedEvents(text, eventNames))
+                if (!named.has(e))
+                    named.set(e, idx);
+        };
+        // the view marker's own built-from prose (the marker line and its wrapped continuation) —
+        // only in the State View doc that owns the view; a reaction doc's to-do-view prose also
+        // describes what its rows drop on, which is not a claim about the view's feed.
+        if (ownsView(view)) {
+            for (let j = marker.bodyLine; j < end && (j === marker.bodyLine || lines[j].trim() !== ""); j++)
+                note(lines[j], j);
+        }
+        for (const c of sourceColumnCells(lines, marker.bodyLine + 1, end))
+            note(c.text, c.idx);
+        for (const sl of scenarioLines)
+            note(sl.text, sl.idx);
+        for (const [key, mentionIdx] of named) {
+            if (fed.has(key))
+                continue;
+            const ev = model.elements.find((e) => e.kind === "event" && normalizeName(e.name) === key);
+            pushDiag(diags, "doc-names-unfed-event", {
+                message: `slice doc "${docPath}" (view \`${marker.name}\`, line ${mentionIdx + 1 + lineOffset}) names event "${ev.name}", but view "${view.name}" does not read it (from: ${sources.map((n) => `"${n}"`).join(", ") || "—"}) — add \`from "${ev.name}"\` to the view if the edge is real, or fix the doc`,
+                line: view.line,
+                refs: refsOut,
+            });
+        }
+        const eventKeys = new Set(eventNames.map(normalizeName));
+        for (const name of view.from ?? []) {
+            if (!eventKeys.has(normalizeName(name)) || bodyMentions.has(normalizeName(name)))
+                continue;
+            pushDiag(diags, "doc-omits-fed-event", {
+                message: `view "${view.name}" reads event "${name}", but slice doc "${docPath}" never mentions it — list it in the view's Source column (run \`em slice sync\`) or drop it from the view's from`,
+                line: view.line,
+                refs: refsOut,
+            });
+        }
+    }
+}
 //# sourceMappingURL=docModelConsistencyValidate.js.map