@milehimikey/em 1.17.0 → 1.18.0

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

@@ -89,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 |
@@ -262,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.
@@ -398,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
@@ -437,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`
@@ -521,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*`

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.17.0
+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

package/plugin/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-em-version: 1.17.0
+em-version: 1.18.0
 description: >-
   Use when structuring a draft event model into swimlanes and the four patterns (State Change,
   State View, Automation, Translation), evaluating a model's structural completeness, or writing
@@ -66,7 +66,13 @@ evidence"). In short:
 
 Goal: a structurally complete, **validated** model with correct patterns and swimlanes.
 
-1. **Swimlanes & patterns (step 5).** Group events into **contexts** (bounded contexts /
+1. **Swimlanes & patterns (step 5).** **Name the storylines first**: the one main storyline (the
+   end-to-end journey) and the secondary ones (retire a thing, extend an attribute, reorganize).
+   Wrap each one's slices in a `storyline "Name" [source "url"] { slice … }` block (grammar and the
+   optional `after "<storyline>"` timeline clause: `em-dsl.md`) so the diagram gets a band per
+   story and `em render --storyline "Name"` can show one alone; slices keep their file order, and
+   a model can adopt storylines incrementally (`slice-outside-storyline` is only an advisory
+   warning) — but name them before you slice, not after. Then group events into **contexts** (bounded contexts /
    aggregates) — ask which events share a consistency boundary and who owns them. Classify each
    slice as one of the 4 patterns. **Share the slice between every automation or translation and
    the command it triggers** (the reaction — processor/translation — together with the command
@@ -75,7 +81,21 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    directly**. Add `translation` slices for external inputs (externally triggered: external →
    translation → command → event, no slice before) and for the system reacting to its own state
    (internally triggered: read model in the slice before → translation → command → event).
-2. **Elaborate scenarios — first pass (step 6).** Scaffold every slice's doc now, one per
+2. **Storyline review — before any slice doc is scaffolded.** Read the timeline as a story, not a schema
+   (`${CLAUDE_PLUGIN_ROOT}/shared/reference/methodology.md`, "The story, not the schema"; em repo
+   `docs/storyline.md`). Name the **main storyline** (end-to-end happy path) and every
+   **secondary storyline** (retire, extend, reorganize), and group the slices under them; one
+   lifecycle block per entity (N × create/update/archive, one trailing view each) is the CRUD
+   shape — reshape it with the "Reshaping an existing model" checklist. Then the **intent test**
+   per command (would a business person say this name at this step in the story? an endpoint-shaped
+   name fails), the **question test** per view (write the question it answers; no question, no
+   read model; a child view only when its query needs what the parent view lacks), and the
+   **conditional-invariant signal** (invariants or fields that apply only "if `<field>` is set"
+   mean two intents in one command: split it). The `timeline-entity-clustered`,
+   `command-second-intent` and `automation-split-by-outcome` lints are the mechanical half; the
+   1.18.0 design exit gate is `em validate --shape`. Shape the model first, scaffold docs after: a rename,
+   split or merge from the reshape would orphan docs already wired with `--wire`. The `slice` phase is unchanged (timeline order).
+3. **Elaborate scenarios — first pass (step 6).** Scaffold every slice's doc now, one per
    slice, none skipped: `em slice new "<slice name>" --pattern <state-change|state-view|
    automation|translation> --swimlane "<Persona> → <Context>" --wire <model>.em` writes
    `slices/<slice-name>.md` at `status: draft` (the same command, flags, and `--wire`
@@ -96,7 +116,7 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    the one-command fast path: a near-free stub per undocumented slice, wired, in slice order
    (MIL-184) — skip the per-slice `em slice new` calls above and deepen individual docs later
    when the team is ready.
-3. **Evaluate completeness (step 7).** Walk the model: every slice is a **complete** pattern, not a
+4. **Evaluate completeness (step 7).** Walk the model: every slice is a **complete** pattern, not a
    half-slice — **every command has something that triggers it**, every command emits an event,
    **every event is read by a read model**, **every read model has a consumer**, every view has a
    source, every UI is reachable, every connection is
@@ -125,6 +145,19 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    session and stage `contracts/<model key>.tsp` with the model edit — the one derived artifact
    a design session produces, always by the command, never by hand.
 
+5. **Shape exit gate (GH #282).** The model phase ends on the shape lints, not on your judgement
+   of the storyline: run `em validate <model>.em --shape` (add `--json` to read it; exit code is
+   always 0, so read the output). Every finding is either **fixed** in the model, or **accepted**
+   as one bullet in `.event-modeling.md` `## Decisions log`:
+   `- YYYY-MM-DD: shape-accepted: <rule> <refs> — <reason>`
+   The gate passes only when **every remaining finding, waived or not,** has such a bullet. A
+   baseline passed as `--waive-file <path>` (lines `<rule-code> <slice-key>`) only silences the CLI
+   count for an estate; it never replaces the bullet. Re-run until each remaining finding has its
+   bullet. **Refuse to move to the slice phase otherwise** (`em state set-phase slice` waits): the
+   same kind of exit gate as asserting the generated contract above. Do not accept a finding
+   without asking the user for the reason. The gate runs after doc scaffolding, so update or retire
+   wired docs for renamed, merged or split slices.
+
 End of phase: render, update state (`em state set-phase slice` — the mechanical marker the state
 machine expects), and stop. Every slice already has a draft doc ready to receive the deep spec,
 but slicing is deliberate work the team starts when it's ready for it, not this phase's automatic
@@ -140,9 +173,17 @@ events already being settled, so working out of order means re-litigating an ear
 contract mid-spec. Check `README.md`'s Slices table for what's already done (run `em slice index
 <model-name>.em` first if it looks stale).
 
+**Outcomes stay in the slice.** When the deep dive surfaces failure, retry or timeout, add the
+outcome events (`Fulfilment Failed`, `Fulfilment Retry Scheduled`, ...) and their Given/When/Then
+scenarios to the SAME slice, with retry policy and failure handling as invariants in its doc —
+never a sibling slice per control-flow branch (1.18.0 adds the lint `automation-split-by-outcome`). A new slice
+only when a different actor or a different trigger is involved. Canon: Dilger, "one business
+action… two different possible outcomes" and "Linearize it!"; Dymitruk, "a few of these stories
+to show how a command can and cannot succeed".
+
 This is also where **branch / unhappy-path events** are discovered and added to the model — as a
 slice's alternate/error flows surface (a rejection, removal, cancellation, decline, expiry), add
-the corresponding event/slice to the `.em` and re-render. The happy-path spine from earlier
+the outcome event to the same slice unless a different actor or trigger is involved, then re-render. The happy-path spine from earlier
 phases is the starting point, not the finished event set. **Every new event needs its reader too**
 — a rejection or cancellation that nothing projects will warn, and usually the missing piece is
 real (someone has to see that the request was declined).

package/plugin/skills/discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discover
-em-version: 1.17.0
+em-version: 1.18.0
 description: >-
   Use when starting a brand-new event model from scratch — greenfield discovery: brainstorming
   past-tense events, storyboarding the happy path, finding the commands and read models — or when
@@ -22,28 +22,40 @@ layout, the Socratic/validation discipline every phase follows) and
 work — they are the source of truth. Run the preconditions there first.
 
 **Existing system?** Use the `extract` phase below. **New feature inside an existing codebase,
-not a whole-system extraction?** Stay in `discover`, but before locking in command/event names,
-Grep/Read adjacent real sources (OpenAPI specs, DB migrations, existing DTOs/event classes in
-sibling contexts) rather than guessing conventions — same check the `slice` phase applies to
-field tables (`em:design`).
+not a whole-system extraction?** Stay in `discover`, but **only after the storyboard exists**
+(step 2) and before locking in command/event names, Grep/Read adjacent real sources (OpenAPI
+specs, DB migrations, existing DTOs/event classes in sibling contexts) rather than guessing
+conventions — same check the `slice` phase applies to field tables (`em:design`).
+Those sources fill operations no walkthrough touches; they never supply the story.
 
 ## Phase: `discover` — steps 1-4
 
 Goal: a draft model of events, storyboard, commands, and views. Loose is OK; structure comes next.
 
-1. **Brainstorm events (step 1).** Ask the user to name everything that happens, as past-tense
+1. **Brainstorm events (step 1).** Draw the candidate events **from the walkthroughs and
+   journeys** (ask for them first; no walkthrough → *"what does success look like, start to
+   finish?"*): *"what happened, in the story's words?"* — business terms, never table or endpoint
+   vocabulary. Ask the user to name everything that happens, as past-tense
    facts. Probe for missed state changes. For each candidate, apply the **"is it an event?"
    test** (`methodology.md` step 1 — the "would this wake the CEO at 3am" heuristic):
    reject derived values (belong in a read model) and telemetry/activity (not business state).
    Don't silently drop rejections — park them in the state file's Decisions log with why, so
    they aren't re-proposed later. Capture the survivors as a flat list.
-2. **Plot / storyboard (step 2).** Order the events into the narrative. Identify **personas**
+2. **Plot / storyboard (step 2).** Start from the story, not the schema: ask for the spec's
+   **walkthroughs**, use cases and user journeys — or *"what does success look like, start to
+   finish?"* — and build the timeline from those (`methodology.md`, "The story, not the schema").
+   Name the **main storyline** (the end-to-end happy path) and each **secondary storyline**
+   (retire, extend, reorganize) before ordering anything; never one lifecycle block per entity
+   (the CRUD shape). The OpenAPI/migrations/resource reference comes **after** the storyboard,
+   only to fill operations no walkthrough touches. Order the events into the narrative. Identify **personas**
    (actors) and the **UI** screens at each step. Add `persona` declarations and `ui` elements.
    In a **headless/API** model there are no human personas or screens — identify the external
    **callers** at each step instead; declare one persona per caller/role, and its `ui` boxes are
    the API calls (see `methodology.md`).
 3. **Inputs (step 3).** For each event, find the **command** that causes it (imperative name).
-   Form `command → event` slices (State Change pattern). Every command needs a **trigger** in the
+   Form `command → event` slices (State Change pattern). Apply the **intent test**: name the
+   command for the intent a business person would say at this step of the story, not the
+   endpoint that carries it (`methodology.md`, "The story, not the schema"). Every command needs a **trigger** in the
    same breath: the screen the user issues it from (a `ui` in the slice), or — for the Automation
    and Translation patterns — the reaction that triggers it, also in this slice. A command
    nothing points at is a write nobody can start. *"Who does this, and where are they when they
@@ -66,6 +78,29 @@ slice already reads "no doc yet" — no slice docs exist until the `slice` phase
 Tell the user they can stop here and resume with `/em:event-modeling` (or invoke
 `em:design` directly).
 
+## Path: PRD or spec in (a document is the input)
+
+Use this path when the user hands you a **PRD, requirements document or API spec** instead of
+starting from a blank page. **Entry:** `/em:discover` (plugin) or `/em:event-modeling discover`
+(repo skills), with the opening message **`Discover from this PRD/spec: <path>`**. **Read `reference/prd-spec-path.md`
+and `reference/prd-rubric.md` before doing any work on it** — the path is a triage, not a
+transcription: a document describes the system its authors imagined (resources, endpoints,
+stack, quality targets), and a model copied from it comes out as CRUD-per-entity.
+
+The steps, in order (detail in the reference): **0** pull the walkthroughs and name the main and
+secondary **storylines** (the resource/endpoint reference is consulted last); **1** split into
+single-claim statements, each quoting the source verbatim; **2** classify each against the
+shipped rubric, plus the independent *"is this about the business, independent of how it's
+built?"* check; **3** group by reaction (shared trigger + acting system = one slice; failure,
+retry and timeout become outcome events and scenarios of that slice, never new slices); **4**
+rewrite, don't drop (implementation details become business language linked to their source;
+real tech choices and NFRs go to a constraints list that feeds the constitution); **5** record
+`discovery/prd-triage.json` and run `em discover triage-check discovery/prd-triage.json`
+(MCP: `discover_triage_check`) until it passes; **6** every low-confidence or disagreeing
+statement becomes a Socratic question — never an invented answer. Rejections and parked
+statements go in the state file's Decisions log with why, as in step 1. Then continue with
+`discover` steps 1-4 on the surviving groups, with the storylines as the timeline's spine.
+
 ## Phase: `extract` — current-state model of an existing system
 
 Goal: a faithful **current-state** model extracted from an existing system — the as-is sibling

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

@@ -77,7 +77,12 @@ it is fine to finish a round with `# TBD`s still parked.
 
 - **R1 — Candidate events.** Extract (event-driven) or synthesize (procedural) the past-tense
   facts; apply the event test; user confirms/renames/rejects. Ambiguous candidates → `# TBD`.
-- **R2 — Timeline order.** Order the confirmed events into the as-is narrative. Identify the
+- **R2 — Timeline order.** First **name the as-is process(es)** — which business journey does the
+  system run today, and what is its outcome? Take it from the system's walkthroughs, user journeys
+  and docs, and from the people who use it — not from the OpenAPI/migrations/DTO grep, which fills
+  operations no journey touches and comes **after** (`methodology.md`, "The story, not the
+  schema"). Name the main storyline and each secondary one, then order the confirmed events into
+  that as-is narrative, never one block per entity. Identify the
   *actual* actors/callers and the *real* UI or API surfaces (headless systems: still `ui`/`persona`
   — one persona per caller/role, its `ui` boxes are the API calls, per `em-dsl.md`). **First
   `em render` here.**

package/plugin/skills/discover/reference/prd-rubric.md

@@ -0,0 +1,103 @@
+<!-- GENERATED FILE from .claude/skills/event-modeling-discover/reference/prd-rubric.md by scripts/build-plugin.ts — do not hand-edit; run npm run docs:generate -->
+# PRD/spec triage rubric — version 1.0
+
+The shipped classification rubric for the PRD/spec path (`prd-spec-path.md`, step 2). It is data:
+`em discover triage-check` rejects a `discovery/prd-triage.json` whose `rubricVersion` is not the
+version below. Do not edit it per project; a changed rubric ships with a new `rubricVersion` in a
+new `em` release.
+
+## The independent check
+
+Run on every statement in addition to its category: **"Is this about the business, independent of
+how it is built?"** Record the answer as `aboutBusiness` (true/false), answering it separately from
+the category. The table's `aboutBusiness` column is what the category *expects*.
+
+## Categories
+
+| Category id | What it is | aboutBusiness expected | Allowed outcomes |
+|---|---|---|---|
+| `business-fact` | Something that happens or is true in the business; candidate event or field. | true | modeled, rewritten, parked, question |
+| `user-intent` | What an actor wants to accomplish; candidate command with its trigger. | true | modeled, rewritten, parked, question |
+| `information-need` | What an actor needs to see or know to act; candidate read model. | true | modeled, rewritten, parked, question |
+| `actor` | A person, role or calling system; candidate persona. | true | modeled, parked, question |
+| `business-rule` | A constraint the business imposes; candidate invariant or scenario. | true | modeled, rewritten, parked, question |
+| `external-system` | A system outside the boundary; candidate translation slice or constraint. | either | modeled, rewritten, constraint, parked, question |
+| `implementation-detail` | How it is built. Rewritten in business language when it implies a business fact; a real tech choice goes to the constraints list. | false | rewritten, constraint, parked, question |
+| `nfr` | Performance, availability, security, compliance: feeds the constitution, never a slice. | either | constraint, parked, question |
+| `goal-background` | Why the product exists; context for the main storyline, not a slice. | true | parked, rewritten, question |
+| `question` | An open question in the source; becomes a Socratic question, never an invented answer. | either | question, parked |
+| `resource-or-endpoint` | Describes an API resource or endpoint. Rewritten to the intent it serves (one endpoint may carry several); never promoted to a command as-is. | false | rewritten, parked, question |
+
+## Outcomes
+
+`modeled` (joins a slice group as stated), `rewritten` (joins a group in business language, the
+original linked through `quote`), `constraint` (constraints list), `parked` (a `reason`; also a
+Decisions-log entry), `question` (a Socratic `question` for the human). `question` and `parked`
+are allowed for every category: a doubt can always be asked, and an explicitly deferred intent is
+legitimate when its `reason` says so.
+
+## Rules the checker enforces
+
+All of these are checked by `em discover triage-check`; write the record so they hold.
+
+1. **Disagreement is a question.** If `aboutBusiness` contradicts the category's expectation
+   (a `business-fact` that names a table; an `implementation-detail` that states a business
+   fact), the outcome MUST be `question`. Put the proposed rewrite in the question text
+   ("Is this a business fact? proposed: Stock is decremented when a pick is confirmed."); the
+   human resolves it and a later pass records `rewritten`.
+2. **Low confidence is a question.** `confidence: low` means outcome `question`, whatever the category.
+3. **An endpoint is never modeled as-is.** `resource-or-endpoint` is `rewritten` (to the intent it
+   serves), `parked` or `question` — never `modeled`.
+4. **Only modeled and rewritten statements join a slice group.** They carry a declared `group` and
+   the `storyline` of that group. Every other outcome has `group: null` (and `storyline: null`),
+   except that a `question` may name the group it would join once answered (with that group's
+   storyline); that is a pointer only, never an anchor (rule 7).
+5. `rewritten` needs `rewrite`; `parked` needs `reason`; `question` needs `question`; every
+   `constraint` appears in `constraints[]`.
+6. **Provenance is checked, not declared.** Every statement says whether it came from a
+   `walkthrough` or from the `reference` (resource/endpoint reference, operational notes). A
+   `walkthrough` statement's quote must lie inside some storyline's span; a `reference`
+   statement's quote must lie outside every storyline span.
+7. **A group is either anchored or reference-only.** An anchored group names a storyline and has at
+   least one `modeled` or `rewritten` `walkthrough` statement whose quote lies inside that storyline's span (a `question` never anchors: a group anchored by questions only is an error). A **reference-only
+   group** has only `reference` statements and **no storyline**: `storyline: null` on the group and
+   on its statements. It never joins a walkthrough storyline. The report lists reference-only
+   groups outside every storyline — operations no walkthrough touches; check these are not CRUD fill.
+8. **One statement per claim.** A statement's normalised quote may not equal, contain or be contained in another statement's quote; the error names both.
+9. **Quotes are verbatim** (Markdown emphasis marks, smart quotes and whitespace aside) and at
+   least 12 characters. A storyline `quote` is the **full** walkthrough span, start to finish.
+
+## Rubric decisions
+
+- `nfr` expects `aboutBusiness: either`: a retention or audit rule is a business NFR, so the check
+  must not force a disagreement on it.
+- `external-system` also stays `either`: a system outside the boundary can be named in business
+  terms (the payment provider) or technical ones (a queue broker).
+
+The checker cannot judge whether a classification is right, nor whether every claim in the
+walkthrough has a statement; that is what the human review is for.
+
+## Machine-readable copy
+
+The same data as JSON. The checker's built-in copy is asserted identical to this block, and the
+table above is asserted to match it, by `test/prdTriage.test.ts`.
+
+```json
+{
+  "rubricVersion": "1.0",
+  "independentCheck": "Is this about the business, independent of how it is built?",
+  "categories": [
+    { "id": "business-fact", "aboutBusiness": true, "outcomes": ["modeled", "rewritten", "parked", "question"], "meaning": "Something that happens or is true in the business; candidate event or field." },
+    { "id": "user-intent", "aboutBusiness": true, "outcomes": ["modeled", "rewritten", "parked", "question"], "meaning": "What an actor wants to accomplish; candidate command with its trigger." },
+    { "id": "information-need", "aboutBusiness": true, "outcomes": ["modeled", "rewritten", "parked", "question"], "meaning": "What an actor needs to see or know to act; candidate read model." },
+    { "id": "actor", "aboutBusiness": true, "outcomes": ["modeled", "parked", "question"], "meaning": "A person, role or calling system; candidate persona." },
+    { "id": "business-rule", "aboutBusiness": true, "outcomes": ["modeled", "rewritten", "parked", "question"], "meaning": "A constraint the business imposes; candidate invariant or scenario." },
+    { "id": "external-system", "aboutBusiness": "either", "outcomes": ["modeled", "rewritten", "constraint", "parked", "question"], "meaning": "A system outside the boundary; candidate translation slice or constraint." },
+    { "id": "implementation-detail", "aboutBusiness": false, "outcomes": ["rewritten", "constraint", "parked", "question"], "meaning": "How it is built. Rewritten in business language when it implies a business fact; a real tech choice goes to the constraints list." },
+    { "id": "nfr", "aboutBusiness": "either", "outcomes": ["constraint", "parked", "question"], "meaning": "Performance, availability, security, compliance: feeds the constitution, never a slice." },
+    { "id": "goal-background", "aboutBusiness": true, "outcomes": ["parked", "rewritten", "question"], "meaning": "Why the product exists; context for the main storyline, not a slice." },
+    { "id": "question", "aboutBusiness": "either", "outcomes": ["question", "parked"], "meaning": "An open question in the source; becomes a Socratic question, never an invented answer." },
+    { "id": "resource-or-endpoint", "aboutBusiness": false, "outcomes": ["rewritten", "parked", "question"], "meaning": "Describes an API resource or endpoint. Rewritten to the intent it serves (one endpoint may carry several); never promoted to a command as-is." }
+  ]
+}
+```