@milehimikey/em 1.16.1 → 1.18.0

package/plugin/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-em-version: 1.16.1
+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.16.1
+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." }
+  ]
+}
+```

package/plugin/skills/discover/reference/prd-spec-path.md

@@ -0,0 +1,172 @@
+<!-- GENERATED FILE from .claude/skills/event-modeling-discover/reference/prd-spec-path.md by scripts/build-plugin.ts — do not hand-edit; run npm run docs:generate -->
+# PRD/spec path — a document is the input
+
+Read this **before doing any work on a PRD, requirements document or API spec**, together with
+`prd-rubric.md` (the shipped classification rubric).
+
+**Entry:** `/em:discover` (plugin) or `/em:event-modeling discover` (repo skills), with the opening
+message **`Discover from this PRD/spec: <path>`**. This is the exact entry the eval protocol's
+arm C cites. The path is a **triage**: a document
+describes the system its authors imagined (resources, endpoints, stack, quality targets). Handed
+one cold, the failure modes are over-decomposition along control flow, implementation flavour,
+and CRUD-per-entity models shaped like the resource reference. The steps below prevent all three
+by making every claim in the document earn its place in the model, visibly.
+
+**Stance.** You are still extracting the domain from people, not inventing it. The document is
+evidence. Anything it does not say, or says ambiguously, is a question (step 6), never a guess.
+
+Setup: run the shared preconditions (`../../../shared/reference/operating-principles.md`),
+agree the input path with the user, and create `discovery/` next to the model. Record the input
+path in the state file's Session inputs.
+
+## Step 0 — Walkthroughs become storylines
+
+Before splitting anything, find the document's **walkthroughs**: a PRD's user stories and
+journeys, an API spec's Walkthroughs / use-case / "getting started" section.
+
+- The **end-to-end journey** is the **main storyline** — the happy path, on a timeline, with no
+  branching ("a story of what success looks like"). Every other walkthrough is a **secondary
+  storyline** (retire, extend, reorganize...). Exactly one is main.
+- The timeline is built from these. The resource/endpoint reference is consulted **last**, only to
+  fill operations no walkthrough touches.
+- No walkthrough at all? Ask: *"what does success look like, start to finish?"* and have the
+  human first add the answer to the source document (or to a `discovery/walkthroughs.md` companion
+  that then becomes the triage `source`); a quote that is not in the source is rejected by design.
+  Do not synthesize a journey from the endpoint list.
+- Record each storyline in `storylines[]` with its `id`, `name`, `main`, and `quote` — the **full**
+  walkthrough span, start to finish success story, verbatim (not its first sentence: the checker
+  anchors every group to this span). These become the design phase's `storyline` blocks, so the provenance travels
+  (`../../em:design/SKILL.md`, step 5; syntax in `../../../shared/reference/em-dsl.md`).
+
+## Step 1 — Split into single-claim statements
+
+Split the input into **single-claim statements** — one fact, rule, need or description each. A
+sentence with "and" usually holds two. Number them `S1`, `S2`, ... in source order. Each carries a
+`quote` copied **verbatim** from the document (whitespace, Markdown emphasis marks and smart
+quotes may differ; words may not; at least 12 characters). You may reword later (step 4) but never
+in `quote`: the checker searches the document for it, and a quote it cannot find is an invented
+claim. Every statement also records `provenance`: `walkthrough` for a claim made inside a
+walkthrough span, `reference` for one from the resource/endpoint reference or operational notes.
+**Every claim in a walkthrough gets a statement** — the carrier collecting, the delivery being
+confirmed, the return before the due date — so nothing in the story is silently dropped; the
+checker cannot see a missing one, so walk each walkthrough sentence by sentence.
+
+## Step 2 — Classify
+
+For each statement set:
+
+- `category` — one id from `prd-rubric.md`.
+- `aboutBusiness` — the independent check: *"is this about the business, independent of how it is
+  built?"* Answer it separately from the category, without looking at the category.
+- `confidence` — `high` or `low`. Any doubt: `low` (a low-confidence statement is always a question).
+
+When `aboutBusiness` contradicts what the category expects (the rubric's `aboutBusiness expected`
+column), that disagreement is data, not judgement: the outcome MUST be `question` (step 4, step 6).
+
+A `resource-or-endpoint` statement is **never promoted to a command as-is**: ask which intent(s)
+the resource serves (one endpoint may carry several intents) and rewrite to those (step 4).
+
+## Step 3 — Group by reaction
+
+A **group** is one future slice. Statements sharing a **trigger** and an **acting system** are one
+group (`groups[]`: `id`, `name`, `trigger`, `actor`, `storyline`). Follow the merged reaction
+shape (`../../../shared/reference/methodology.md`): a reaction, its command and its
+event share one slice.
+
+- **Failure, retry and timeout statements are not new slices.** They become outcome events and
+  Given/When/Then scenarios of the slice whose trigger they belong to; set `scenarioOf` to that
+  group's id.
+- **Storyline check.** A statement joins the storyline whose **journey it advances**, not the
+  entity it mentions. A "Product" sentence in the retire walkthrough belongs to "Retire a
+  product", not to a Product lifecycle.
+- One group per trigger-and-actor; never one group per entity or per endpoint.
+- **A group is anchored or reference-only, never both.** An anchored group names a storyline and
+  holds at least one `walkthrough` statement quoted from inside that storyline's span. A group
+  built only from `reference` statements (operations no walkthrough touches) is reference-only:
+  `storyline: null` on the group and on its statements. It never joins a walkthrough storyline,
+  and the report lists it outside every storyline for the human to inspect.
+- A claim is quoted once: no statement's quote may equal, contain or be contained in another's. Only `modeled`/`rewritten` walkthrough statements anchor a group; a `question` never does.
+
+## Step 4 — Rewrite, don't drop
+
+Nothing is silently discarded.
+
+- An **implementation detail that implies a business fact** (*"the service writes a row to
+  `stock_levels` when a pick is confirmed"*): classify it `implementation-detail` with
+  `aboutBusiness: false` — they agree, so it is `rewritten`, with the business-language form in
+  `rewrite` (*"Stock is decremented when a pick is confirmed"*); the original stays in `quote`,
+  which is the link to its source. If you classified the same sentence `business-fact` but the
+  independent check says `false`, they **disagree**: the outcome is `question`, with 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`.
+- A **real technology choice or NFR** (*"must run on Postgres"*, *"p95 under 300 ms"*) gets outcome
+  `constraint` and an entry in `constraints[]` listing its statement ids. That list feeds the
+  project's constitution: hand it to the constitution's owner (the skills read the constitution,
+  never write it); it never becomes a slice.
+- Anything else you set aside is `parked` with a `reason`, **and** recorded in the state file's
+  Decisions log with why (the same rule as rejected events in `discover` step 1), so it is not
+  re-proposed later.
+
+## Step 5 — Record
+
+Write `discovery/prd-triage.json` (UTF-8, 2-space indent):
+
+```json
+{
+  "prdTriageSchemaVersion": "1.0",
+  "rubricVersion": "1.0",
+  "source": "prd.md",
+  "storylines": [{ "id": "L1", "name": "Order to delivery", "main": true, "quote": "A customer places an order. We pick and ship it, and they get a tracking link." }],
+  "groups": [{ "id": "G1", "name": "Place Order", "trigger": "customer submits checkout", "actor": "Storefront", "storyline": "L1" }],
+  "statements": [
+    { "id": "S1", "quote": "A customer places an order.", "category": "user-intent", "aboutBusiness": true, "confidence": "high", "provenance": "walkthrough", "outcome": "modeled", "group": "G1", "storyline": "L1" },
+    { "id": "S2", "quote": "must respond within 300 ms", "category": "nfr", "aboutBusiness": false, "confidence": "high", "provenance": "reference", "outcome": "constraint", "group": null, "storyline": null },
+    { "id": "S3", "quote": "writes a row to stock_levels", "category": "business-fact", "aboutBusiness": false, "confidence": "high", "provenance": "reference", "outcome": "question", "group": null, "storyline": null, "question": "Is this a business fact? proposed: Stock is decremented when a pick is confirmed." }
+  ],
+  "constraints": [{ "id": "C1", "text": "Checkout responds within 300 ms", "statements": ["S2"] }]
+}
+```
+
+Per statement: `id`, `quote`, `category`, `aboutBusiness`, `confidence`, `provenance`, `outcome`
+(`modeled | rewritten | constraint | parked | question`), `group` and `storyline` (set for
+`modeled`/`rewritten`, otherwise `null`), plus `rewrite` / `reason` / `question` /
+`scenarioOf` where the outcome needs them. **Every statement has a category and an outcome;
+every modeled or rewritten statement has a group.** The rules the checker enforces are listed in
+`prd-rubric.md` ("Rules the checker enforces"): disagreement and low confidence are questions, an
+endpoint is never modeled, group and storyline only for modeled/rewritten (otherwise `null`),
+provenance verified against the storyline spans (a `walkthrough` quote lies inside one, a
+`reference` quote outside all), no shared quotes, and every group either anchored by a walkthrough
+statement inside its storyline's span or reference-only (`"storyline": null` on the group and its
+statements, listed in the report outside every storyline).
+
+Then run, and fix until it passes:
+
+```
+em discover triage-check discovery/prd-triage.json        # MCP: discover_triage_check
+em discover triage-check discovery/prd-triage.json --markdown > discovery/prd-triage.md
+```
+
+`--markdown` prints the human-readable view (storylines, slice groups with their statements,
+constraints, parked, questions); save it next to the JSON. The checker verifies shape, the rubric
+version, verbatim quotes, and the outcome rules; **it cannot judge whether your classification is
+right**, whether every walkthrough claim has a statement, or whether the Decisions-log entry for
+each parked or rejected statement was actually written (that entry is prose-only and unchecked) —
+that is what the human review is for. Read the report's **reference-only groups** list: those
+are operations no walkthrough touches; check they are not CRUD fill. Also confirm each
+**storyline quote really is a walkthrough span**: storyline spans are self-declared and the
+checker cannot know which sections of the document are walkthroughs. The `--markdown` view lists
+the storylines with their quotes for exactly this review.
+
+## Step 6 — Questions, never inventions
+
+Every `low` confidence statement, every statement where `aboutBusiness` contradicts the
+category's expectation, and every `question` category statement gets outcome `question` and a
+Socratic `question` (a disagreement's question carries the proposed rewrite). Ask them one concern at a time, in the story's words. Record each answer in the state
+file and update the record (the statement is re-classified; re-run the checker). If the document
+and the human disagree, the human wins and the disagreement is a Decisions-log entry.
+
+## Hand-off
+
+Continue with `discover` steps 1-4 (`../SKILL.md`) on the surviving groups: the storylines are the
+timeline's spine, each group seeds one slice, and the constraints list goes to the project
+constitution. `discovery/prd-triage.json` stays in the repo as provenance for the model.

package/plugin/skills/engagement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: engagement
-em-version: 1.16.1
+em-version: 1.18.0
 description: >-
   Use when leading an engagement: building a named set of ratified event-modeling slices
   (`em engagement`) into one independent PR per slice, each against main, by dispatching the
@@ -48,9 +48,17 @@ Run the shared preconditions first (tool check, bundle currency, locate the mode
    beside the model, or `.specify/memory/constitution.md`). STOP if it is missing or its
    `ratifiedBy:` is empty (spec-kit: no `**Ratified**:` footer). Say so and point at
    `em:implement`'s §7; never draft house rules to get moving.
-2. **Foundation PR merged.** Ask the human for the foundation PR (implement.md §8) and confirm it
-   has merged into `main` (`gh pr view <n> --json state` shows `MERGED`). STOP if there is none
-   or it is still open. No slice branch is cut before it lands.
+2. **Foundation is in the code.** Do not ask the human whether the foundation PR (implement.md
+   §8) landed — check: `em engagement foundation <model>.em <slug> --code <repo root>` (GH #240;
+   `--json` when you need the fields). It reports every event the engagement's slices emit or
+   consume as `present`, `incomplete` (which fields, which tag fields are missing — named), or
+   `missing-event`. Any `missing-event`: STOP — the foundation has not landed for that event; ask
+   for the foundation PR and confirm it merged into `main` (`gh pr view <n> --json state` shows
+   `MERGED`), then re-run. Any `incomplete`: **one question to the human**, listing every gap the
+   report names (an implementer never discovers these alone) — the fix is a foundation follow-up
+   on `main`, never a slice PR. All `present`: go on. No slice branch is cut before this is clean.
+   The check is a text scan of the target tree, not a compiler: a `present` event may still fail
+   to type-check in the slice PR, and that is the slice PR's job to surface.
 3. **Agent models.** Read the line `- **Agent models:** implementer=<model>,
    validator=<model>, reviewer=<model>, critic=<model|codex>`. If it is absent, say once:
    "no Agent models line — using implementer=sonnet, validator=sonnet, reviewer=sonnet,
@@ -73,12 +81,23 @@ Run the shared preconditions first (tool check, bundle currency, locate the mode
 Run `em engagement plan <model>.em <slug>` (`--json` when you need the fields). Present it in
 plain terms: each level, its width against the ceiling (`parallel`), each slice's branch (every
 base is `main`), and every held slice with its reason (`not-ready`,
-`upstream-outside-engagement-unmerged`, or `human`). Then ask exactly one question:
+`upstream-outside-engagement-unmerged`, or `human`). Then the plan's **`pre-flight:` block** (GH
+#239): the model-wide gaps the engagement's slices share — a `repeated-invariant` with no single
+enforcing slice, an `event-without-tag` whose consistency boundary is undeclared, a
+`shared-trigger` (one `ui`, two slices, no endpoint owner), a `doc-model-mismatch`, a `shape` (a
+`em validate --shape` lint fires on the slices; the answer is a `shape-accepted: <rule> <refs> —
+<reason>` bullet in `.event-modeling.md` `## Decisions log`, or a model fix). These are
+exactly what every implementer would otherwise stop on and report separately. Put them to the
+human **in the same single question round** as the ceiling, one bullet each with the slices it
+spans, and ask for a ruling on each (the answer goes where it belongs: the model, the foundation
+PR, a slice doc, or `.event-modeling.md` for a deferral). Then ask exactly one question:
 
 > "Ceiling N from the plan; proceed?"
 
 Ask it once per engagement. If the human names a lower number, use it for this session. **Never
 ask "which slice first"**: the levels decide the order, and the ceiling decides how many at once.
+A pre-flight finding never holds a slice: if the human says "proceed anyway" on one, dispatch
+and make sure each implementer's brief carries the ruling, so no agent rediscovers it.
 A held slice is never started; the plan releases it when its hold clears.
 
 ## 3. Per level: cut the worktree, then dispatch the implementer
@@ -155,7 +174,10 @@ You never merge.
    `main`: `git switch -c engagement/<slug>-level-<n> main`, run
    `em slice mark-implemented <model>.em <key> <pr-url>` for each slice merged in the level,
    then `em slice index <model>.em`, commit, and `gh pr create --base main`. The human merges it
-   like any other PR.
+   like any other PR. If `mark-implemented` printed `opened draft v<n+1>` for a slice, its doc in
+   this PR reads `status: draft`: say so in the hand-back and paste the command's notice into the PR
+   body — `shippedVersion:`/`implementedIn:` are the record that v<n> was implemented, `status:` is
+   the next version's state, so the reviewer does not read it as a slice that was never marked.
 4. Recompute: `em engagement plan <model>.em <slug>`. A merge can release an
    `upstream-outside-engagement-unmerged` hold once that upstream's doc reads `implemented`.
    Continue with step 3 for anything newly startable.

package/plugin/skills/engagement/reference/engagement.md

@@ -75,11 +75,12 @@ constitution. The implementer stops and reports it as the doc line plus the ques
 4. Carry on with every other startable slice. Never answer the question yourself, never edit the
    doc, and never let the implementer guess.
 
-A question the build can finish without (it does not block the slice) is not a gap: queue it with
+A question the build can finish without (it does not block the slice) is not a gap: defer it with
 `em slice defer <model>.em <key> "<question>" --until v<n> --decision "<what this version does>"`
-(GH #236). On a ratified doc that never edits the body — `ratifiedHash` and `--slice-ready` stay
-green — and records the question in `.event-modeling.md` for `<key>@v<N+1>`; `mark-implemented`
-at merge opens v<N+1> as a draft with it in Open Questions. Never write the `- [ ]` into the
+(GH #253). On a ratified doc that appends the already-deferred `- [x]` item to the doc's Open
+Questions, outside `ratifiedHash` — the hash and `--slice-ready` stay green, and the question is
+visible in the ratified doc; `mark-implemented` at merge opens v<n> as a draft with it reopened
+as `- [ ]`. Never write a `- [ ]` into the
 ratified doc, and do not run `em slice revise` for it (an unshipped ratified doc refuses
 `revise` without `--withdraw`).
 

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

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

package/plugin/skills/implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implement
-em-version: 1.16.1
+em-version: 1.18.0
 description: >-
   Use when building a single ratified event-modeling slice (status: ready-to-implement) into
   merged, tested code — the one phase where the agent builds rather than facilitates. Gates on