@milehimikey/em 1.13.1 → 1.14.1

package/.claude/skills/event-modeling-shared/reference/operating-principles.md

@@ -73,6 +73,67 @@ right here as `reference/slice-doc-schema.md` (kept in sync with the em repo's
   hand-run `em validate --json` and format the line yourself. This is the team's only usage
   signal today (`docs/usage-data.md`) — keep it cheap and habitual, not a task to skip.
 
+## Write scope and evidence (MIL-236)
+
+These bind every design session — `discover`, `model`, `slice` — whichever skill runs it,
+including sessions started from bare `/event-modeling`.
+
+- **Write scope: one model directory.** The session is bound to the model directory it started
+  in: `dirname(<model>.em)`, which holds `slices/`, `model-versions/`, `conformance/`,
+  `contracts/`, `.event-modeling.md` and `README.md`. Never write under another model's
+  directory or to another model's contract file (`<model dir>/contracts/<model key>.tsp`). When
+  you need a neighbour, read only its public surface, read-only: the elements with
+  `public: true` in `em export <neighbour>.em`, or its committed contract file. Never open the
+  neighbour's slice docs or state file.
+- **Seam change request instead of a cross-model edit.** When resolving an open question needs
+  another model's `public` element changed (a field added, renamed, retyped; an element made
+  `public`), record it in THIS model's `.event-modeling.md` `## Decisions log` as one dated
+  bullet, exactly this shape (`em changelog` reads only dated bullets):
+
+  ```
+  - YYYY-MM-DD: seam change request → <producerKey>:<kind>.<slug> — <what> — <why>
+  ```
+
+  `<producerKey>:<kind>.<slug>` is the same ref a `consumes` clause uses (`kind` is `event` or
+  `view`; write `command` for a public command). Leave the open question open with
+  `blocked on: <producerKey> owners (seam change request YYYY-MM-DD)`, and tell the user to take
+  the request to the producer's owners. Never edit the other side.
+- **Out of scope during design — never write these:**
+  - generated contract artifacts: `contracts/*.tsp`, any OpenAPI or JSON-schema output;
+  - SDD/spec artifacts: `specs/`, `.specify/` (read `.specify/memory/constitution.md` when a
+    slice needs the house rules; never write it);
+  - implementation source: `src/`, and any path under the model's `Code roots:` bullet;
+  - `plugin/` (the generated skill plugin);
+  - a draft slice doc's `version:` (see the version rule below).
+
+  One exception, and only this one: when the session marks an element `public` (or changes a
+  field of a `public` element), run `em api generate <model>.em` before handing slices to
+  ratification. The API-first gate (`em validate --slice-ready`) refuses a public-touching
+  slice whose contract is missing or stale, so the regenerated `contracts/<model key>.tsp` is
+  committed with the model edit. Never hand-edit it.
+- **Evidence rule.** The `.em` model and the slice docs are the evidence for every modeling
+  decision. Never open implementation source, generated contracts, or `specs/` to settle a
+  modeling question; ask the user. Code is consulted only in `extract`
+  (`event-modeling-discover`) and `conform` (`event-modeling-conform`), where reading it is the
+  point.
+- **Version rule: never bump a draft's `version:` on edit.** A `draft`/`reviewed` doc is edited
+  in place. Check the release state with `em status <model>.em --json`: the model is
+  **pre-release** when its `modelVersion` entry has `design: null` and
+  `slices.byStatus.implemented === 0`. Pre-release: never run `em slice reratify`; edit
+  `draft`/`reviewed` docs in place and leave `version:` as it is. A pre-release doc that is
+  already ratified (`ready-to-implement` with `ratifiedBy`) carries a human sign-off: STOP,
+  record the needed change as an open question, and let the ratifier decide. Released (either
+  condition false): changing an `implemented` or ratified doc goes through `em slice reratify`
+  (see `event-modeling-design`).
+- **Pre-commit check (STOP on any finding).** Stage the session's files, then run both:
+  1. `em system scope --staged` from the repository root. Any `seam-crossing` error → STOP:
+     unstage the other model's files and record a seam change request instead.
+  2. `git diff --cached --name-only`. Any path outside the bound model directory, or any
+     out-of-scope path above (`contracts/*.tsp` except the regenerated exception, OpenAPI /
+     JSON-schema output, `specs/`, `.specify/`, `src/`, code roots, `plugin/`), or a draft
+     doc whose `version:` line changed (`git diff --cached -- <doc>`) → STOP: unstage it and
+     tell the user what was touched and why it is out of scope.
+
 ## Preconditions (run first)
 
 1. Check the tool: `em --version`. If missing, tell the user to run `npm i -g @milehimikey/em`

package/.claude/skills/event-modeling-shared/reference/slice-doc-schema.md

@@ -67,6 +67,8 @@ to decide `frontmatter-invalid` without re-deriving frontmatter-shape rules of i
 | `reviewedOn` | string | `YYYY-MM-DD` | written only by `em slice review` (MIL-201); joined into `em export`'s `slice.doc.reviewedOn` (schema `1.11`) |
 | `ratifiedBy` | string | free text (typically a person's name) | written only by `em slice ratify` (MIL-165 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-ratify-file-slice-key---by-name)); joined into `em export`'s `slice.doc.ratifiedBy` (schema `1.8`) and `em slice index`'s Ratified by column |
 | `ratifiedOn` | string | `YYYY-MM-DD` | written only by `em slice ratify` (MIL-165); joined into `em export`'s `slice.doc.ratifiedOn` (schema `1.8`) |
+| `meaningConfirmed` | boolean | `true` | written only by `em slice ratify`/`reratify --meaning-unchanged` (MIL-238 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-ratify-file-slice-key---by-name)): the API-first sign-off on a public-touching slice — this version does not change what the public contract means. Joined into `em export`'s `slice.doc.meaningConfirmed` (schema `1.15`; `false` when absent) |
+| `contractChange` | string | quoted free text (`contractChange: "<why>"`) | written only by `em slice ratify`/`reratify --contract-change "<why>"` (MIL-238): the API-first sign-off on a public-touching slice — why a consumer must read this change differently. Joined into `em export`'s `slice.doc.contractChange` (schema `1.15`, quotes stripped; `null` when absent) |
 | `owner` | string | free text (typically a person or team name) | hand-filled — no `em` command writes it; joined into `em export`'s `slice.doc.owner` (schema `1.9`, MIL-171), `em slice index`'s Owner column, and `em status`'s per-slice `owners[]` |
 | `tracking` | string | free text (typically an external ticket/issue URL) | hand-filled — no `em` command writes it; joined into `em export`'s `slice.doc.tracking` (schema `1.9`, MIL-171) and `em slice index`'s Tracking column. This is the exact field `em-tracker-bridge` reads to find the ticket mirroring this slice — `em` only stores and displays it, it never talks to a tracker itself |
 | `conformedVersion` | integer | positive integer | written only by `em slice conform` (MIL-214 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-conform-file-slice-key---at-rev)): this slice's `version:` at the time a conform sweep last certified it. Joined into `em export`'s `slice.doc.conformedVersion` (schema `1.13`); paired with `version` to compute `slice.doc.driftSignal`'s `"uncertified"` case |
@@ -90,7 +92,8 @@ convention, not parser-enforced.
 | `split-from`, `merged-from`, `superseded-by` | optional in every state — present only on docs created by a split/merge, or on a doc that has been retired |
 | `covers` | optional in every state — present only on a doc that deliberately also serves another slice (MIL-121, see below); most docs never carry it |
 | `reviewedBy`, `reviewedOn` | optional in every state — present once `em slice review` (MIL-201) has run at least once; a doc that never went through the review gate, or was hand-flipped to `reviewed`, simply omits both. `em slice ratify` never clears them; `em slice reratify` does (they describe the version that shipped) |
-| `ratifiedBy`, `ratifiedOn` | optional in every state — present once `em slice ratify` (MIL-165) has run at least once; a doc predating this feature, or ratified by hand, simply omits both |
+| `ratifiedBy`, `ratifiedOn` | optional in every state, but `ready-to-implement` needs `ratifiedBy` to pass `em validate --slice-ready` (`slice-ready-not-ratified`, MIL-259) — present once `em slice ratify` (MIL-165) has run; `em slice reratify` clears both. `em upgrade` (`ratified-signoff`, 1.14) grandfathers a `version: 1` `ready-to-implement` doc that never had one by writing `ratifiedBy: "grandfathered (unsigned before em 1.14)"` and `ratifiedOn:` the upgrade date |
+| `meaningConfirmed`, `contractChange` | optional in every state, at most one present — written right after `ratifiedOn:` by `em slice ratify` and right after `version:` by `em slice reratify` (MIL-238). On a **public-touching** slice (one owning a `public` command, event or view) both commands refuse without `--meaning-unchanged` or `--contract-change "<why>"`, so a doc ratified on 1.14+ carries one; elsewhere either is optional. `em slice reratify` clears both before writing its own (they describe the prior version, same as `reviewedBy`/`ratifiedBy`). `em status` counts public-touching `ready-to-implement`/`implemented` docs with neither (`publicSlicesUnconfirmed`) |
 | `owner`, `tracking` | optional in every state — hand-filled whenever a team wants a who-holds-this / external-tracker link; most docs never carry either (MIL-171) |
 | `conformedVersion`, `conformedAt`, `conformedOn` | optional in every state — present once `em slice conform` (MIL-214) has run at least once for the CURRENT version; a doc that's never been through a conform sweep, or whose `version` has since bumped past what was certified, simply has none of the three (or a stale triple — see `driftSignal`'s `uncertified` case below) |
 
@@ -119,13 +122,13 @@ because it's the same frontmatter dialect. The doc stays the single source of tr
 `status`; a stub is just the cheapest possible way to give a slice one before anyone's ready to
 write the real spec.
 
-**A stub CAN pass `em validate --slice-ready`.** That gate checks four things (`computeSliceReadyGates`,
+**A stub CAN pass `em validate --slice-ready`.** That gate checks six things (`computeSliceReadyGates`,
 [validation.md#slice-readiness](https://github.com/milehimikey/em/blob/main/docs/validation.md#slice-readiness)): a doc is bound, its frontmatter
-is usable, `status` is `ready-to-implement`, and its Open Questions count has none unchecked. A
+is usable, `status` is `ready-to-implement`, it carries a `ratifiedBy` (MIL-259), its Open Questions count has none unchecked, and — for a slice owning a `public` element — the model's contract is current (MIL-238; nothing in the doc). A
 stub with no `## Open Questions` section at all has `openQuestionsTotal: 0` (see
 [Open Questions section: lifecycle](#open-questions-section-lifecycle) below) — zero unchecked is
 vacuously true — so a stub escalated to `ready-to-implement` (`em slice stub-all --status
-ready-to-implement --by <name>`) passes cleanly. The readiness gate is frontmatter-plus-checkbox-
+ready-to-implement --by <name>`, which records the ratifier) passes cleanly. The readiness gate is frontmatter-plus-checkbox-
 count only; it has no opinion about whether Intent/Command/Scenarios/Invariants were ever
 written. Demanding that content is the `slice` phase's (and, for a live walkthrough, the review
 skill's) job, not a machine gate's — see `../.claude/skills/event-modeling-design/SKILL.md` and
@@ -347,6 +350,106 @@ stale reads as current, unlike git which is honestly historical), and forces eve
 work out which delta is the live one — exactly the ambiguity `driftSignal` (MIL-85, below) is
 built to avoid.
 
+## Invariants
+
+Since MIL-265 the **model is the preferred place to declare an invariant**: an `invariant
+INV-<MNEMONIC>-<n> "rule"` line after the command or event it guards (see
+[dsl.md](dsl.md#invariants)) carries the ID and the one-line rule sentence. The doc's
+`## Invariants / Business Rules` section then **cites** each model-declared ID and elaborates —
+why the rule exists, what a violation looks like, edge cases, the error returned:
+
+```markdown
+## Invariants / Business Rules
+- INV-ORD-1 — a zero-total cart is rejected before payment is attempted
+  - the check runs on the server; the UI's own check is a convenience only
+```
+
+Write the citation as a plain mention (`- INV-ORD-1 — …`), not with the declaring label
+`**INV-ORD-1:**` — restating a model-declared ID with that label is
+`invariants/declared-in-both` (a warning pointing at the migration). Ownership follows the model:
+a model-declared ID belongs to the slice of the element that declares it, for `em coverage` and
+`em query invariant`, whatever any doc says.
+
+**Doc declaration is still honoured.** A doc that declares its own invariants
+(`- **INV-CHK-1:** rule`, or a 1.13 doc's bare `- **INV-1:** rule`) keeps working exactly as
+before: for every ID the model does not declare, the doc-body reader (`## Invariants` and
+`## Delta` sections, top-level bullet/subheading lines only — MIL-149/155) is the fallback.
+A doc mentioning an `INV-…` ID that neither the model nor any doc declares gets
+`invariants/doc-cites-undeclared`. See [validation.md](https://github.com/milehimikey/em/blob/main/docs/validation.md#invariants).
+
+## Generated regions and authored sections
+
+Since MIL-266 a slice doc has two kinds of section.
+
+**Generated regions** restate the model, and `em` writes them. Each is wrapped in a pair of html
+markers; `em slice new --wire` fills them from the `.em`, and `em slice sync <model>.em` refreshes
+them in place after any model edit. Never hand-edit between the markers — change the model and
+re-run `em slice sync`.
+
+| Region | Section | Body |
+|---|---|---|
+| `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-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
+the element's slug (`em-slice-event-order-placed`). A kind the slice lacks keeps its one region
+with a "has no …" line, so adding the first element later is a plain `em slice sync`. The
+`**Command:**`/`**Event:**`/`- **View:**` marker lines sit inside the regions, so the
+[doc-model consistency](https://github.com/milehimikey/em/blob/main/docs/validation.md#doc-model-consistency) check reads them as before (and,
+inside a generated `em-slice-view` region, now compares the view's field table too).
+
+```markdown
+## Command / Input
+<!-- GENERATED:em-slice-command:start — generated from the model by `em slice sync`; do not hand-edit -->
+**Command:** `Submit Order`
+
+| Field | Type | Required | Rules / Validation |
+|-------|------|----------|--------------------|
+| total | decimal | yes | — |
+| note | text | no | — |
+<!-- GENERATED:em-slice-command:end -->
+```
+
+The invariants list uses `**INV-X** — rule`, not the declaring label `**INV-X:**`, so a
+generated list never trips `invariants/declared-in-both`. Elaborate each ID below the region
+(after the `<!-- elaborate below this list; IDs are declared in the model -->` comment).
+
+**Authored sections** are everything else — Intent, Trigger & Actor, Trigger, `**Read by:**`,
+`Consumed by`/freshness, the invariant elaborations, Scenarios, Alternate & Error Flows, NFRs,
+Dependencies, Open Questions. `em` never writes them; `em slice sync` leaves every byte outside
+the region markers untouched (CRLF included).
+
+**Scenario grammar (authored, constrained).** Inside `## Scenarios (Given / When / Then)`, each
+case is a block:
+
+```markdown
+### Scenario: Non-positive total is rejected (INV-CHK-1)
+- **Given:**
+  - a basket whose total is 0
+- **When:**
+  - the customer submits the order
+- **Then:**
+  - the command is rejected with a validation error
+  - no event is recorded
+```
+
+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`
+(`{ title, given, when, then }[]`, `null` when the doc has none). A block missing any of the
+three is `slice-doc/structured-section-malformed`, as is a region whose markers don't balance or
+whose table header differs from the template's — a warning in `em validate`, and a blocker
+(`slice-ready-structured-section-malformed`) under `--slice-ready`. See
+[validation.md](https://github.com/milehimikey/em/blob/main/docs/validation.md#structured-sections).
+
+**Migration.** Nothing is required: a doc with no region markers and no `### Scenario:` heading
+(every doc written before 1.14) stays valid, is never flagged, and `em slice sync` skips it with a
+note. To adopt regions, re-create the doc with `em slice new "<name>" … --wire <model>.em --force`
+and carry the authored prose across, or paste the marker pairs in by hand and run
+`em slice sync`.
+
 ## Open Questions section: lifecycle
 
 `## Open Questions` (MIL-87 for the counting mechanics; MIL-156 for this lifecycle) had no
@@ -376,6 +479,14 @@ diverges from git, grows unboundedly over a long-lived slice's life, and forces
 work out which resolutions are still relevant to the *current* version versus leftover from a
 prior one — exactly the ambiguity a live, current-version-only section avoids.
 
+**Deferral marker (MIL-275).** A question this version will not answer is not left `- [ ]` and
+not deleted: `em slice defer` checks it and rewrites it as `- [x] <original> — v<current>:
+<decision>; deferred to v<n> (<date>[, <by>])`. The `deferred to v<n>` marker is what
+`em slice reratify` reads: when a bump reaches v<n> it rewrites each such item back to
+`- [ ] <original>`, so the question must be resolved or re-deferred before `--slice-ready` passes
+again. The prune rule above does not apply to a deferred item before v<n> (it stays as the
+record); once reopened it is an ordinary open question.
+
 **Not a parsing/grammar change.** `countOpenQuestions()` (`sliceDoc.ts`) and
 `slice-ready-open-questions-unchecked` (`sliceReadyValidate.ts`,
 [validation.md#slice-readiness](https://github.com/milehimikey/em/blob/main/docs/validation.md#slice-readiness)) are unaffected: both already
@@ -400,7 +511,7 @@ frontmatter-coherence check (MIL-85) deliberately never flags this combination
 
 **An unshipped version has nothing to flip back** (MIL-258). A ratified doc that has not shipped
 yet (`status: ready-to-implement` with `ratifiedBy:` set) changes the same way: `em slice
-reratify` bumps `version:` and clears `ratifiedBy`/`ratifiedOn`/`reviewedBy`/`reviewedOn`, but
+reratify` bumps `version:` and clears `ratifiedBy`/`ratifiedOn`/`reviewedBy`/`reviewedOn` (and `meaningConfirmed`/`contractChange`, MIL-238), but
 leaves `status` at `ready-to-implement` (and any `implementedIn` as it was — an absent one stays
 absent). This is the path for an answered gap mid-build. In both cases the new version is not
 ratified until `em slice ratify --by <name>` records the sign-off. A `ready-to-implement` doc with

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

@@ -23,7 +23,10 @@ NAMED human and an ISO date, hand-filled at sign-off (no `em` command writes thi
 unratified, says so, and does not proceed on unilateral style or stack decisions for a first slice.
 
 `em status` reports this document as present or absent per model — existence only. em never reads
-or validates its content, and nothing here is machine-parsed.
+or validates its content, and the CLI parses nothing here. Three lines are read as plain text by
+the engagement skill and its sub-agents, so keep their exact shape: `- **Test command:**` (the
+validator), `- **Merge strategy:**` and `- **Agent models:**` (the engagement skill). In a spec-kit
+project they merge under the same headings in `.specify/memory/constitution.md`.
 -->
 
 ---
@@ -86,6 +89,10 @@ table is the only routing rule.
   with rejection scenarios asserting the doc's named rejection reason.
 - **Test naming convention:** {{the exact pattern, e.g. `INV-ORD-3: rejects a second submit`}}
 - **What "green" means:** {{the command CI runs}}
+- **Test command:** `{{the one command that runs the tests, e.g. ./gradlew test}}`
+  What the `em-validator` sub-agent runs. Keep exactly this shape: one line, the command in
+  backticks. Absent, the validator reports "no test command in the constitution" and runs only the
+  em checks.
 
 ## NFR baselines
 
@@ -113,6 +120,16 @@ it is silent, these apply.
   amend** — a `covers:` doc ships as one PR for both keys; a read model is one doc, so a later
   `again` instance is a continuation of the doc that first declared it, not a PR of its own. See
   the agent guide's §5/§10.
+- **Merge strategy:** merge-commits-when-stacked
+  {{**How do PRs merge, and what happens when one PR depends on another?** Merge commits whenever
+  a dependent PR is open; squash only a PR with no open dependent (implement contract §8 rule 2a).
+  Keep this exact line: it is the only value the engagement skill accepts, and it refuses to run
+  without it.}}
+- **Agent models:** implementer=sonnet, validator=sonnet, reviewer=sonnet, critic=opus
+  {{**Which model runs each em sub-agent?** Keep this exact line shape, with the defaults shown or
+  your own choices. The critic must run on a different model from the implementer; `critic=codex`
+  selects the Codex critic. Absent, the engagement skill states these defaults once and
+  proceeds.}}
 - **At merge:** run `em slice mark-implemented <model>.em <slice-key> <pr-url>` — the one edit an
   implementing agent makes to a ratified slice doc, run by {{the PR author | CI}}. Never bump
   `version:`; that moves only when a delta is ratified.

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

@@ -36,9 +36,10 @@ to write up. Delete it otherwise; most docs never carry it. Requires a matching
 bind anything. Plain slice keys, comma-separated — not the `<slice-key>@v<N>` ref grammar above.
 
 `ratifiedBy`/`ratifiedOn` record who ratified this doc's current `status`/`version`, and when —
-don't hand-fill these; run `em slice ratify <model>.em {{this-slice-name}} --by "<name>"` at the
+don't hand-fill these; run `em slice ratify <model> <key> --by <name>` at the
 handoff gate instead (docs/process.md#what-ratified-means), which flips `status` to
 `ready-to-implement` and writes both in one edit.
+public-touching slice: add --meaning-unchanged, or --contract-change "<why>"; run em api generate first.
 
 `owner`/`tracking` are optional and, unlike `ratifiedBy`/`ratifiedOn`, hand-filled — no `em`
 command writes either. `owner` is free text naming who (a person or team) holds this slice;
@@ -121,13 +122,18 @@ state we react to). Either way, name the command this reaction triggers — reac
 an event directly.}}
 
 ## Command / Input
-<!-- For State Change, and the command half of an Automation or Translation (reactions trigger a
-     command in this same slice). Omit for pure State View slices. -->
+<!-- GENERATED region (MIL-266): the table between the markers is written from the model —
+     `em slice new` fills it, `em slice sync <model>.em` refreshes it after any model edit. Never
+     hand-edit inside the markers: change the `.em` and re-run `em slice sync`. Required = `no`
+     for a field written `name?: Type`. A slice with several commands gets one region per command
+     (`em-slice-command-<command-slug>`); a pure State View slice's region says it has none. -->
+<!-- GENERATED:em-slice-command:start — generated from the model by `em slice sync`; do not hand-edit -->
 **Command:** `{{Command Name}}`
 
 | Field | Type | Required | Rules / Validation |
 |-------|------|----------|--------------------|
 | {{field}} | {{Type}} | {{yes/no}} | {{constraints, formats, ranges}} |
+<!-- GENERATED:em-slice-command:end -->
 
 ## Trigger
 <!-- What issues this slice's command. Required: a command nothing points at is a write nobody
@@ -136,63 +142,82 @@ an event directly.}}
 **Triggered by:** {{screen `X` @Persona | processor `Y`, also in this slice}}
 
 ## Event(s) Emitted
-<!-- The immutable facts recorded. List each event and its payload. -->
+<!-- The immutable facts recorded. The marker line and payload table are a GENERATED region (one
+     per event; `em-slice-event-<event-slug>` when the slice records several): Source / Notes
+     names the command field a value is copied from, `assigned` for a system-assigned field, or
+     `{{ }}` where the model cannot tell. `**Read by:**` below the region is authored. -->
+<!-- GENERATED:em-slice-event:start — generated from the model by `em slice sync`; do not hand-edit -->
 **Event:** `{{Event Name}}` → context `{{Context}}`
+
+| Field | Type | Immutable Fact? | Source / Notes |
+|-------|------|-----------------|----------------|
+| {{field}} | {{Type}} | {{yes/no}} | {{where the value comes from}} |
+<!-- GENERATED:em-slice-event:end -->
 **Read by:** {{which read model projects this event, and in which slice}}
 <!-- Required, not optional. Every event must be read by a read model — an event nothing
      projects is a write nobody can see, and `em validate` warns on it. A reaction consuming
      it does NOT count: reactions read views, not events. If the honest answer is "nothing
      reads it", that's a question for the business, not a field to leave blank. -->
 
-| Field | Type | Immutable Fact? | Source / Notes |
-|-------|------|-----------------|----------------|
-| {{field}} | {{Type}} | {{yes/no}} | {{where the value comes from}} |
-
 ## Read Model / View
-<!-- For State View slices, and any read model this slice produces or feeds. -->
+<!-- For State View slices, and any read model this slice produces or feeds. The `- **View:**`
+     line and field table are a GENERATED region (one per read model; `em-slice-view-<view-slug>`
+     when there are several): Source / Notes names the source event a field is copied from, or
+     `Derived` for a field marked `derived` in the `.em` (docs/dsl.md#derived-fields) — say how
+     it is derived in prose below the region. `{{ }}` marks a field the model cannot trace. -->
+<!-- GENERATED:em-slice-view:start — generated from the model by `em slice sync`; do not hand-edit -->
 - **View:** `{{View Name}}` built from events: {{"Event A", "Event B"}}
+
+| Field | Type | Source / Notes |
+|-------|------|----------------|
+| {{field}} | {{Type}} | {{which event field it's copied from, or `Derived: <rule>`}} |
+<!-- GENERATED:em-slice-view:end -->
 - **Consumed by:** {{which UI screen (or API-caller persona), or reaction}}
 <!-- "Consumed by" is required, not optional. A read model nothing displays or watches is
      information projected out of the system and then dropped, and `em validate` warns. Every
      instance of a repeated view needs its own consumer, not just the last one. -->
 - **Freshness / consistency expectation:** {{real-time | eventual | on-demand}}
 
-| Field | Type | Source / Notes |
-|-------|------|-----------------|
-| {{field}} | {{Type}} | {{which event field it's copied from, or `Derived: <plain-language rule>` for a value computed from which events have landed (a status stepping through states, a computed rank, a flag two events can flip) — a field written as `Derived:` here should ALSO carry the `derived` marker (bare `derived`, or `derived from "Event A", "Event B"` naming the events the rule depends on) on the view's field in the `.em`, so `em export`/the model know the field exists too, not just this doc (docs/dsl.md#derived-fields)}} |
-
 ## Invariants / Business Rules
+<!-- IDs and rule sentences are declared in the MODEL (MIL-265): an `invariant INV-<MNEMONIC>-<n>
+     "rule"` line after the command or event it guards (docs/dsl.md#invariants). The list between
+     the markers is GENERATED from those lines (`em slice sync`); never edit it. Below it, cite
+     each ID as a plain mention and elaborate — `- INV-CHK-1 — why it holds, edge cases, the error
+     a violation returns` — never re-declare it with the `**INV-CHK-1:**` label
+     (`invariants/declared-in-both`). A rule not (yet) in the model may still be declared below
+     with that label; em reads it as the fallback. -->
 <!-- What must ALWAYS hold. Give each a stable ID so tests and code can reference it:
      `INV-<MNEMONIC>-<n>`, where `<MNEMONIC>` is a short (2-4 letter/digit), slice-unique
      abbreviation of this slice's key (e.g. slice `checkout` -> `INV-CHK-1`) — see
-     ../reference/slice-doc-schema.md. Add a letter suffix for a closely-related sub-invariant
-     (`INV-CHK-3a`). Keep the rule statement itself to one line. If it needs more — why the rule
-     exists, what "violation" looks like in practice, an edge case worth calling out — add that as
-     a nested bullet under the rule instead of one long run-on sentence: this section renders as
-     HTML (`em catalog`/`em render`/`em watch`), and a nested bullet stays visually distinct where
-     a wrapped sentence collapses into a wall of text. The ID must stay on the rule's own
-     top-level bullet line — `em coverage` extracts INV IDs from that line only, never from a
-     nested elaboration bullet underneath it. -->
-- **INV-{{MNEMONIC}}-1:** {{rule that the command enforces; violation ⇒ rejection}}
-  - {{optional: rationale, edge-case detail, or what "violation" means here — its own bullet}}
-- **INV-{{MNEMONIC}}-2:** {{...}}
+     ../reference/slice-doc-schema.md. Keep the rule statement itself to one line. If it needs
+     more — why the rule exists, what "violation" looks like in practice, an edge case worth
+     calling out — add that as a nested bullet under the elaboration line instead of one long
+     run-on sentence: this section renders as HTML (`em catalog`/`em render`/`em watch`), and a
+     nested bullet stays visually distinct where a wrapped sentence collapses into a wall of
+     text. The ID must stay on the top-level bullet line — `em coverage` extracts INV IDs from
+     that line only, never from a nested elaboration bullet underneath it. -->
+<!-- GENERATED:em-slice-invariants:start — generated from the model by `em slice sync`; do not hand-edit -->
+- **INV-{{MNEMONIC}}-1** — {{rule, as declared by `invariant INV-{{MNEMONIC}}-1 "rule"` in the model}}
+<!-- GENERATED:em-slice-invariants:end -->
+<!-- elaborate below this list; IDs are declared in the model -->
+- INV-{{MNEMONIC}}-1 — {{elaboration of the model-declared rule: why it holds, what a violation looks like, the error returned}}
+  - {{optional: edge-case detail — its own bullet}}
+- **INV-{{MNEMONIC}}-2:** {{a rule not yet in the model, declared here as the fallback — move it into the model when you can}}
 
 ## Scenarios (Given / When / Then)
-<!-- The executable specification. Cover the happy path AND the key rule boundaries. Each
-     scenario is a case-label bullet with Given/When/Then as nested sub-bullets — not one run-on
-     sentence — so the case reads as distinct beats once rendered instead of a dense paragraph. -->
-- **Happy path**
-  - **Given:** {{starting state / prior events}}
-  - **When:** {{command/trigger}}
-  - **Then:** {{event(s) recorded}} and {{resulting read-model change}}.
-- **Rejected (INV-{{MNEMONIC}}-1)**
-  - **Given:** {{state}}
-  - **When:** {{command}}
-  - **Then:** rejected with reason; no event.
-- **{{Edge case}}**
-  - **Given:** {{...}}
-  - **When:** {{...}}
-  - **Then:** {{...}}
+<!-- The executable specification — authored, in a constrained shape `em` reads back (`em export
+     --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`. -->
+### Scenario: Happy path
+- **Given:**
+  - {{starting state / prior events}}
+- **When:**
+  - {{command/trigger}}
+- **Then:**
+  - {{event(s) recorded}}
+  - {{resulting read-model change}}
 
 ## Alternate & Error Flows
 <!-- Failure paths, retries, compensations, timeouts, idempotency. -->

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

@@ -48,7 +48,11 @@ Keep it current at the end of every working session.
 
 ## Decisions log
 <!-- Resolved choices, with the reasoning, so they aren't re-litigated. In a live workshop,
-     attribute each entry to the participant who made the call (see Participants above). -->
+     attribute each entry to the participant who made the call (see Participants above).
+     Every entry is a dated bullet ("- YYYY-MM-DD: ..."); em changelog skips any other line.
+     Seam change request (a needed change to another model's public element; never edit that
+     model, keep the open question blocked on its owners):
+     - YYYY-MM-DD: seam change request → <producerKey>:<kind>.<slug> — <what> — <why> -->
 - {{YYYY-MM-DD}}: {{decision}} — {{why}} — by {{participant, if a live workshop}}
 
 ## Usage log

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "em-1-14-1",
+  "owner": {
+    "name": "Mike Key"
+  },
+  "description": "em v1.14.1: the Event Modeling skill bundle and MCP server as a Claude Code plugin.",
+  "plugins": [
+    {
+      "name": "em",
+      "source": "./plugin",
+      "description": "Event Modeling with em: discover, design, implement, conform, review and engagement skills over a slice-first text DSL, plus the em MCP server."
+    }
+  ]
+}

package/README.md

@@ -38,12 +38,19 @@ em diff model.em --from HEAD~1   # what this change did to the model
 em changelog model.em     # the model's git history as a business ledger
 ```
 
-A system of several models — one per team or sub-department, each in its own directory — gets
-the same treatment across model boundaries: a seam manifest (`system.yaml`) declares which
-model's `public` event feeds which other model's Translation slice, and `em system system.yaml`
-verifies every binding against the models' exports and emits the org-level context map
-([docs/cli.md](docs/cli.md#em-system-manifest); worked example in
-[examples/multi-model/](examples/multi-model/)).
+A system of several models — one per team or bounded context, each in its own directory —
+gets the same treatment across model boundaries. A producer marks the commands, events and
+views other teams depend on `public`, and `em api generate` writes them as the model's own
+TypeSpec contract (`contracts/<model>.tsp`). A consumer declares what it reads on its own side,
+`translation Order Intake consumes checkout:event.order-submitted`. `em system` finds the
+models (a `system.yaml` listing them, or discovery of every `.em` in the repo), resolves every
+`consumes` against the producers' public surface, fails when a consumer still reads a field its
+producer dropped, and emits the org-level context map. `em system codeowners` puts every
+consuming team on the producer's contract file in CODEOWNERS, so a contract change cannot merge
+without them, and two gates hold the line: `--slice-ready` will not hand off a slice whose
+contract is stale, and `em system scope` fails a PR that changes a contract and its consumer
+together ([docs/process.md](docs/process.md#seams-between-models-who-does-what); worked example
+in [examples/multi-model/](examples/multi-model/)).
 
 A model is a list of slices — vertical time steps, read left to right — whose elements land
 in swimlane rows:
@@ -90,16 +97,23 @@ flowchart LR
 
 ## Model with AI
 
-`em` ships a Claude Code skill bundle — one router skill plus five focused, SDLC-stage skills
+`em` ships a Claude Code skill bundle — one router skill plus six focused, SDLC-stage skills
 (discover/extract, model/slice, implement, conform/validate, watch/review) — that runs a
 facilitated Event Modeling session: the AI asks the questions, you supply the domain, and the
 model renders live as it grows.
 
+Install it as the `em` Claude Code plugin, pinned to the release you run (two commands, once per
+machine; replace `1.14.0` with your `em --version`):
+
 ```bash
-em skill install          # copy the skill bundle into .claude/skills/
+claude plugin marketplace add milehimikey/em@v1.14.0 --scope project
+claude plugin install em@em-1-14-0 --scope project
 ```
 
-Then run `/event-modeling` in Claude Code. The same bundle also runs the reverse direction:
+Then run `/em:event-modeling` in Claude Code. The older vendored route (`em skill install`,
+which copies the bundle into `.claude/skills/`) still works but is deprecated since 1.14;
+`em upgrade --apply` moves a vendored repo to the pinned plugin in one commit. The same bundle
+also runs the reverse direction:
 `extract` derives a model from a system that already exists, and `conform` checks a model
 against the code implementing it and reports where they've drifted. See
 [docs/ai-workflow.md](docs/ai-workflow.md) for the phases and what a session produces, and the
@@ -112,12 +126,12 @@ built this way.
 |---|---|
 | [docs/tutorial.md](docs/tutorial.md) | Learn the tool by building a model from scratch |
 | [docs/workflow.md](docs/workflow.md) | The model lifecycle: specify, gate, hand off, track change, detect drift |
-| [docs/process.md](docs/process.md) | Who does what: where humans are required, where agents work with review |
+| [docs/process.md](docs/process.md) | Who does what: where humans are required, where agents work with review, and the seam lifecycle between models |
 | [docs/patterns.md](docs/patterns.md) | The four Event Modeling patterns and their DSL shapes |
 | [docs/dsl.md](docs/dsl.md) | Full DSL reference: keywords, `from`, `again`, fields, notes |
 | [docs/cli.md](docs/cli.md) | Every command and flag |
 | [docs/validation.md](docs/validation.md) | Every rule `em validate` checks, and the fixes |
-| [docs/ci.md](docs/ci.md) | Copy-paste CI recipes: validate `.em` changes, run conformance on a schedule |
+| [docs/ci.md](docs/ci.md) | Copy-paste CI recipes: validate `.em` changes, the multi-model gates, run conformance on a schedule |
 | [docs/upgrading.md](docs/upgrading.md) | Bring a model repo forward across em releases: `em upgrade`, release by release |
 | [docs/timeline.md](docs/timeline.md) | The Two Laws of the Timeline |
 | [docs/ai-workflow.md](docs/ai-workflow.md) | The Claude Code skill: install, phases, artifacts |

package/dist/catalog/apiFirst.d.ts

@@ -0,0 +1,28 @@
+import { NormalizedModel, Slice } from "../model/model.js";
+import { RefsResult } from "../model/refs.js";
+import { Diagnostic } from "../model/validate.js";
+/** True when `slice` owns at least one `public` command, event or view. */
+export declare function slicePublicTouching(slice: Slice): boolean;
+/** `slicePublicTouching` by export key; false for an unknown key. */
+export declare function isPublicTouchingSlice(model: NormalizedModel, refs: RefsResult, sliceKey: string): boolean;
+/** What the contract-currency check needs beyond the compiled model: the `.em` path as the
+ *  caller was given it (the contract path is built from it, as `em api generate` does), its
+ *  source text, and the compile diagnostics. */
+export interface ContractCheckInput {
+    file: string;
+    source: string;
+    diagnostics: Diagnostic[];
+}
+export type ContractState = "current" | "missing" | "stale";
+export interface ContractStatus {
+    state: ContractState;
+    /** The contract path, built from `file` exactly as `em api generate` builds it. */
+    contractPath: string;
+}
+/**
+ * Is the committed contract current? `missing` when the file does not exist; `stale` when its
+ * text differs from the freshly generated text — or when the model cannot be generated from at
+ * all (a public field with no resolvable type raises `public-field-type-unresolved`, which
+ * `em api generate` refuses on; the contract cannot be current then either).
+ */
+export declare function contractStatus(model: NormalizedModel, refs: RefsResult, input: ContractCheckInput): ContractStatus;

package/dist/catalog/apiFirst.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: MIT
+// The API-first design exit gate (MIL-238, briefing R10): the two facts `em validate
+// --slice-ready`, `em slice ratify`/`reratify` and `em status` all share.
+//
+//  - "public-touching slice": a slice owning at least one `public` command, event or view —
+//    the elements `em api generate` puts on the model's contract (emit/api.ts).
+//  - "contract current": `<modelDir>/contracts/<modelKey>.tsp` exists and its text equals what
+//    `em api generate` would write from the current model. A plain text comparison (R12): the
+//    generated header carries no source hash, so an internal-only `.em` edit never makes the
+//    contract stale. Generation reuses `generateContract` (src/cli/api.ts) in-process — the same
+//    builder `em api generate`/`em api check` call, never a shell-out.
+import { existsSync, readFileSync } from "node:fs";
+import { computeModelKey } from "../model/qualifiedRef.js";
+import { contractPathFor, generateContract } from "../cli/api.js";
+const CONTRACT_KINDS = new Set(["command", "event", "view"]);
+/** True when `slice` owns at least one `public` command, event or view. */
+export function slicePublicTouching(slice) {
+    return slice.elements.some((el) => el.public === true && CONTRACT_KINDS.has(el.kind));
+}
+/** `slicePublicTouching` by export key; false for an unknown key. */
+export function isPublicTouchingSlice(model, refs, sliceKey) {
+    const i = refs.sliceKeys.indexOf(sliceKey);
+    return i !== -1 && slicePublicTouching(model.slices[i]);
+}
+/**
+ * Is the committed contract current? `missing` when the file does not exist; `stale` when its
+ * text differs from the freshly generated text — or when the model cannot be generated from at
+ * all (a public field with no resolvable type raises `public-field-type-unresolved`, which
+ * `em api generate` refuses on; the contract cannot be current then either).
+ */
+export function contractStatus(model, refs, input) {
+    // generateContract reads only model/refs/diagnostics from its compile argument.
+    const compiled = { model, refs, diagnostics: input.diagnostics };
+    let generated;
+    try {
+        generated = generateContract(input.file, input.source, compiled);
+    }
+    catch {
+        // Generation needs a resolvable public type per field; without one the contract can't be
+        // regenerated, so it can't be current. Path is still the conventional one.
+        const fallback = contractPathFor(input.file, computeModelKey(model, input.file));
+        return { state: existsSync(fallback) ? "stale" : "missing", contractPath: fallback };
+    }
+    if (!existsSync(generated.contractPath))
+        return { state: "missing", contractPath: generated.contractPath };
+    const committed = readFileSync(generated.contractPath, "utf8");
+    return { state: committed === generated.text ? "current" : "stale", contractPath: generated.contractPath };
+}
+//# sourceMappingURL=apiFirst.js.map

package/dist/catalog/apiFirst.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiFirst.js","sourceRoot":"","sources":["../../src/catalog/apiFirst.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,qFAAqF;AACrF,0EAA0E;AAC1E,EAAE;AACF,4FAA4F;AAC5F,gFAAgF;AAChF,+FAA+F;AAC/F,8FAA8F;AAC9F,6FAA6F;AAC7F,iGAAiG;AACjG,uEAAuE;AAEvE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAInD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAElE,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAElF,2EAA2E;AAC3E,MAAM,UAAU,mBAAmB,CAAC,KAAY;IAC9C,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,KAAK,IAAI,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;AACxF,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,qBAAqB,CAAC,KAAsB,EAAE,IAAgB,EAAE,QAAgB;IAC9F,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3C,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC;AAmBD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAsB,EAAE,IAAgB,EAAE,KAAyB;IAChG,gFAAgF;IAChF,MAAM,QAAQ,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAuD,CAAC;IACtH,IAAI,SAA8C,CAAC;IACnD,IAAI,CAAC;QACH,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,yFAAyF;QACzF,2EAA2E;QAC3E,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACjF,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;IACvF,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,YAAY,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC,YAAY,EAAE,CAAC;IAC3G,MAAM,SAAS,GAAG,YAAY,CAAC,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC/D,OAAO,EAAE,KAAK,EAAE,SAAS,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,CAAC,YAAY,EAAE,CAAC;AAC7G,CAAC"}