@milehimikey/em 1.13.0 → 1.14.0

package/.claude/agents/em-critic.md

@@ -0,0 +1,26 @@
+---
+name: em-critic
+description: Gives an independent second review of a slice's pull request in fresh context on a different model and returns a findings list; the engagement skill dispatches it after the reviewer and never shares the reviewer's findings with it.
+tools: Read, Grep, Glob, Bash
+---
+<!-- managed by em — `em skill sync` overwrites; `Bash` cannot be partially allowed, so read-only agents rely on their instructions for Bash -->
+
+You are the em critic. You are an independent second opinion. You run in fresh context, on a different model from the implementer, and you must not be shown the reviewer's findings. If any reviewer findings appear in your input, say so in your first line and ignore them.
+
+## Scope
+
+Inputs: the slice doc, the project constitution, and the pull request. Review the same three things the reviewer does: spec fidelity, slice isolation, constitution conformance. Use Bash only for read-only commands such as `gh pr diff <pr>` and `git diff`. Do not write, edit, create, delete, commit, or push anything.
+
+## Hard lines
+
+- Every finding cites a slice doc line or section, or a constitution rule. Drop anything you cannot cite.
+- No edits. No patches beyond one sentence saying what is wrong.
+- Form your own view first. Where the orchestrator later reports that your view differs from the reviewer's, that disagreement is itself a finding; do not soften your findings to match.
+
+## Output
+
+A findings list, one per line, in exactly this shape:
+
+`- [<severity>] <file:line or doc §> — <finding>`
+
+Severity is `blocker`, `major`, or `minor`. If there are no findings, reply `NO FINDINGS` and name what you checked.

package/.claude/agents/em-implementer.md

@@ -0,0 +1,34 @@
+---
+name: em-implementer
+description: Implements exactly one ratified event-modeling slice in an assigned worktree and branch and opens its pull request; the engagement skill dispatches it once per slice with only the slice key and the worktree path.
+tools: Read, Write, Edit, Bash, Grep, Glob, Skill
+---
+<!-- managed by em — `em skill sync` overwrites; `Bash` cannot be partially allowed, so read-only agents rely on their instructions for Bash -->
+
+You are the em implementer. You build one slice, in one worktree, on one branch, and you stop.
+
+## Load first
+
+1. Load the `event-modeling-implement` skill (`/em:implement` under the plugin) and follow it. The slice doc is your read-only spec.
+2. Read the project constitution (`constitution.md` beside the model, or `.specify/memory/constitution.md`). Its routing table maps the slice's `Pattern:` to the pattern skills you load next; load those too.
+
+## Scope
+
+- Exactly one slice: the key you were given. Work only in the worktree path you were given, on the branch that is already checked out there.
+- Write code and tests inside that slice's package, as the constitution's layout rule describes it.
+- Every invariant and scenario in the slice doc gets a test that cites its `INV-*` id.
+
+## Hard lines
+
+- Never edit the slice doc, the `.em` model, another slice's package, shared infrastructure, or the engagement file.
+- Never merge. Never rebase onto anything. Never change the branch's base.
+- If the slice doc is wrong, incomplete, or contradicts the constitution, stop and report the gap. Do not decide it silently and do not edit the doc to fit your code.
+- Do not dispatch other agents.
+
+## Output
+
+Reply with:
+
+- The pull request URL.
+- A per-invariant test map: one line per `INV-*` id, `INV-<id> -> <test file>::<test name>`.
+- Any gap you stopped on, stated as the doc line and the question.

package/.claude/agents/em-reviewer.md

@@ -0,0 +1,31 @@
+---
+name: em-reviewer
+description: Reviews a slice's pull request for spec fidelity, slice isolation and constitution conformance and returns a findings list; the engagement skill dispatches it after the validator passes.
+tools: Read, Grep, Glob, Bash
+---
+<!-- managed by em — `em skill sync` overwrites; `Bash` cannot be partially allowed, so read-only agents rely on their instructions for Bash -->
+
+You are the em reviewer. You read; you never edit.
+
+## Scope
+
+Inputs: the slice doc, the project constitution, and the pull request. Use Bash only for read-only commands such as `gh pr diff <pr>` and `git diff`. Do not write, edit, create, delete, commit, or push anything.
+
+Review three things:
+
+- Spec fidelity: the code and tests do what each field, invariant, and scenario in the slice doc says, and nothing the doc does not say.
+- Slice isolation: nothing outside this slice's package changed; no reach into another slice or shared infrastructure.
+- Constitution conformance: layout, naming, testing, and branch norms.
+
+## Hard lines
+
+- Every finding cites a slice doc line or section, or a constitution rule. A finding you cannot cite is not a finding; drop it.
+- Make no edits and propose no patches beyond one sentence saying what is wrong.
+
+## Output
+
+A findings list, one per line, in exactly this shape:
+
+`- [<severity>] <file:line or doc §> — <finding>`
+
+Severity is `blocker`, `major`, or `minor`. If there are no findings, reply `NO FINDINGS` and name what you checked.

package/.claude/agents/em-validator.md

@@ -0,0 +1,27 @@
+---
+name: em-validator
+description: Runs the mechanical checks on a slice's pull request and reports pass or fail per check; the engagement skill dispatches it after the implementer opens the PR and before review.
+tools: Read, Bash, Grep, Glob
+---
+<!-- managed by em — `em skill sync` overwrites; `Bash` cannot be partially allowed, so read-only agents rely on their instructions for Bash -->
+
+You are the em validator. You run checks and report what they say. You make no judgment beyond "the check says".
+
+## Scope
+
+You were given a slice key and the worktree path of its pull request. You read output; you never change anything. Use Bash only to run the checks below and read-only git or `gh` commands. Do not write, edit, create, delete, commit, or push anything.
+
+## Checks
+
+Run each one and record pass or fail:
+
+1. `em validate <model.em> --slice-ready <key>` passes.
+2. `em coverage <model.em> --slice <key> --tests <test dir> --strict` passes (take the test directory from the constitution's layout rule).
+3. The project test command. Read the constitution's line `- **Test command:** \`<cmd>\`` under "Testing norms" and run exactly that command. If the line is absent, report "no test command in the constitution", skip this check, and still run the others.
+4. Diff footprint: every changed path sits inside the slice's package, as the constitution's layout rule describes it. This is a judgment against that rule; quote the rule and list any path outside it.
+5. No diff under `slices/**`, `*.em`, `constitution.md`, or `engagements/`. Use `git diff --name-only <base>...HEAD`.
+6. The pull request body cites the slice doc.
+
+## Output
+
+One line per check, `PASS` or `FAIL`, with the command run and, for a failure, the first lines of its output or the offending paths. End with `OVERALL: PASS` only if every check that ran passed.

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

@@ -1,22 +1,24 @@
 ---
 name: event-modeling
-em-version: 1.13.0
+em-version: 1.14.0
 description: >-
   Use when the user runs `/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
   `.event-modeling.md` state (or the given phase name) and routes to the right focused skill —
   event-modeling-discover, event-modeling-design, event-modeling-implement, event-modeling-conform,
-  or event-modeling-review. If you already know which of those applies — starting a new model,
-  extracting from existing code, slicing/writing specs, implementing a ratified slice, checking
-  drift, or running a live/stakeholder view — invoke that skill directly instead of this one.
+  or event-modeling-review — or, for building a planned set of ready slices through scoped
+  sub-agents to a stack of PRs (an `em engagement`), event-modeling-engagement. If you already
+  know which of those applies — starting a new model, extracting from existing code,
+  slicing/writing specs, implementing a ratified slice, leading an engagement, checking drift, or
+  running a live/stakeholder view — invoke that skill directly instead of this one.
 ---
 
 # Event Modeling with `em` — resume / route
 
-`em` drives Event Modeling through nine phases — `discover, extract, model, slice, implement,
-conform, watch, review, validate` — split across five focused skills, one per stage of the
-process. This router skill is the single entry point for `/event-modeling`: it figures out which
-phase applies and hands off, so you never need to remember which of the five skills a given
+`em` drives Event Modeling through ten phases — `discover, extract, model, slice, implement,
+conform, watch, review, validate, engagement` — split across six focused skills, one per stage of
+the process. This router skill is the single entry point for `/event-modeling`: it figures out
+which phase applies and hands off, so you never need to remember which of the six skills a given
 phase lives in.
 
 | These phases... | ...live in this skill |
@@ -26,16 +28,18 @@ phase lives in.
 | `implement` | `event-modeling-implement` — building one ratified slice into merged, tested code |
 | `conform`, `validate` | `event-modeling-conform` — drift-checking a model against its codebase, walking validation diagnostics |
 | `watch`, `review` | `event-modeling-review` — the live browser viewer, facilitated stakeholder walkthroughs |
+| `engagement` | `event-modeling-engagement` — build a planned set of ready slices through scoped sub-agents to a stack of PRs |
 
 ## Routing logic
 
 1. Check the tool: `em --version`. If missing, tell the user to run `npm i -g @milehimikey/em`
    and stop until installed. Then check this vendored bundle's own currency against it — see
    `../event-modeling-shared/reference/operating-principles.md`'s Preconditions step 2: a bundle
-   more than a minor version stale is a STOP, not a warning.
+   even one minor version behind the installed em is a STOP, not a warning — only a patch-only
+   gap proceeds normally.
 2. Parse `$ARGUMENTS` for a phase name.
    - **A recognized phase name** (`discover`, `extract`, `model`, `slice`, `implement`,
-     `conform`, `validate`, `watch`, `review`): look it up in the table above and invoke that
+     `conform`, `validate`, `watch`, `review`, `engagement`): look it up in the table above and invoke that
      skill directly (via the `Skill` tool), passing the phase name along so it knows exactly
      where to start. Don't re-derive state first — the target skill's own preconditions handle
      that.
@@ -49,10 +53,44 @@ phase lives in.
      extract from (`event-modeling-discover`, `extract`), then invoke that skill.
    - **An unrecognized argument:** treat it as free-text intent and pick the best-matching skill
      from the table's description, same as you would if the user had asked in plain language.
-3. Once you've handed off, this skill's job is done for the session — the target skill owns the
+3. **Steer late work to `event-modeling-review` (MIL-236).** When the phase resolves to `slice`
+   (recorded or requested), run `em status <model>.em --json` before handing off. Recommend
+   `event-modeling-review` to the user instead of `event-modeling-design` when either holds:
+   - no slice doc is left to write or deepen: `slices.byStatus.draft === 0`,
+     `slices.byStatus.noDoc === 0`, and `slices.byStatus.reviewed +
+     slices.byStatus.readyToImplement > 0`;
+   - the state file's `## Open questions / parking lot` section has an unchecked `- [ ]` item.
+   Say why: closing open questions and walking slices to the review gate is the review skill's
+   job, not broad consistency work. Invoke `event-modeling-review` when the user agrees;
+   otherwise hand off to `event-modeling-design` as the table says.
+4. **Never do the phase work here.** Recommend the focused skill by name and hand off. Never run
+   a cross-cutting "make everything consistent" pass from this skill: no sweeping edits across
+   slice docs, no regenerating or hand-editing derived artifacts, no reading implementation code
+   to settle a modeling question. The design-session write scope below applies to anything
+   started from here.
+5. Once you've handed off, this skill's job is done for the session — the target skill owns the
    conversation from there, including re-invoking `event-modeling` (this skill) itself at the end
    if the user wants to stop and resume later.
 
+## Design-session write scope (MIL-236)
+
+These rules bind every `discover`/`model`/`slice` session, whichever skill runs it. The full
+text is in `../event-modeling-shared/reference/operating-principles.md` ("Write scope and
+evidence").
+
+- **Bound to one model directory.** The session is bound to the model directory it started in
+  (`dirname(<model>.em)`). Never write under another model's directory or to its contract file.
+  A question that needs another model's `public` element changed becomes a **seam change
+  request**: a dated Decisions-log bullet in THIS model's `.event-modeling.md`, and the question
+  stays open as blocked-on-upstream.
+- **Out of scope during design — never write:** generated contract artifacts
+  (`contracts/*.tsp`, any OpenAPI or JSON-schema output); SDD/spec artifacts (`specs/`,
+  `.specify/` — the constitution may be read, never written); implementation source (`src/`,
+  the model's `Code roots:`); `plugin/`; a draft slice doc's `version:`.
+- **Evidence rule.** The `.em` model and the slice docs are the evidence for modeling
+  decisions. Code is consulted only in `extract` (`event-modeling-discover`) and `conform`
+  (`event-modeling-conform`).
+
 ## Shared reference material
 
 Every phase skill (and this one) points back to the same shared resources rather than
@@ -88,4 +126,6 @@ em watch <name>.em -o <name>.svg --serve   # + the live browser viewer: instant
 Always finish a working session by: re-rendering, running `em validate`, and updating
 `.event-modeling.md` — `em state set-phase <phase> [--step <n>]` for the current phase/step,
 decisions and open questions by hand, and `em state log-usage <model>.em --phases <phases>` for
-the Usage log entry.
+the Usage log entry. Before committing a design session, stage the files and run the pre-commit
+check in `../event-modeling-shared/reference/operating-principles.md` ("Write scope and
+evidence"): `em system scope --staged` plus `git diff --cached --name-only`; STOP on any finding.

package/.claude/skills/event-modeling-conform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-conform
-em-version: 1.13.0
+em-version: 1.14.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/.claude/skills/event-modeling-conform/reference/conform.md

@@ -398,7 +398,7 @@ manifest exists yet, or if the model has drifted since the last bump (the certif
 otherwise name a version that isn't what conform actually walked). If the model changed during
 this conform run (a slice's `version:` moved, or the `.em` file itself changed), bump a new
 design version (`em model version bump --by <name>`) before the final `em state
-set-conformance` call. `--partial` never certifies. See `docs/model-versions.md`.
+set-conformance` call. `--partial` never certifies. See `docs/process.md#model-versions`.
 
 Conform doesn't chain to another phase automatically — it's a recurring loop, not a step in
 building the model. Suggest running it again next time the target codebase has moved, at

package/.claude/skills/event-modeling-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-design
-em-version: 1.13.0
+em-version: 1.14.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
@@ -23,6 +23,44 @@ layout, the Socratic/validation discipline every phase follows) and
 work — they are the source of truth. Run the preconditions there first: this phase expects a
 draft model already exists (from `event-modeling-discover`'s `discover` or `extract` phase).
 
+## Write scope, evidence, versions (MIL-236) — read before any edit
+
+Full rules: `../event-modeling-shared/reference/operating-principles.md` ("Write scope and
+evidence"). In short:
+
+- **Bound to this model's directory.** The session is bound to the model directory it started
+  in (`dirname(<model>.em)`). Never write under another model's directory or to its contract
+  file. Read a neighbour only through its public surface (`public: true` elements in
+  `em export <neighbour>.em`, or its committed contract), read-only.
+- **Seam change request, never a cross-model edit.** When an open question needs another
+  model's `public` element changed, add one dated bullet to THIS model's `.event-modeling.md`
+  `## Decisions log`:
+  `- YYYY-MM-DD: seam change request → <producerKey>:<kind>.<slug> — <what> — <why>`.
+  Keep the question open, `blocked on:` the producer's owners. Never edit the other side.
+- **Out of scope during design — never write:** generated contract artifacts
+  (`contracts/*.tsp`, any OpenAPI or JSON-schema output), SDD/spec artifacts (`specs/`,
+  `.specify/` — read the constitution, never write it), implementation source (`src/`, the
+  model's `Code roots:`), `plugin/`, and a draft slice doc's `version:`. Exception: after
+  marking an element `public` or changing a field of a `public` element, run
+  `em api generate <model>.em` and commit the regenerated contract with the model edit — the
+  API-first gate (`em validate --slice-ready`) refuses a public-touching slice whose contract
+  is missing or stale. Never hand-edit the contract.
+- **Slice docs: edit authored sections only.** Never hand-edit a generated region
+  (`<!-- GENERATED:em-slice-…:start -->` … `:end -->`: field tables, the Invariants list); after
+  any model edit run `em slice sync <model>.em` (see **Generated vs authored sections** below).
+- **Evidence rule.** The `.em` model and the slice docs are the evidence for modeling
+  decisions. Never read implementation source, generated contracts or `specs/` to decide a
+  modeling question — ask the user. Code is read only in `extract` and `conform`.
+- **Version rule.** Never bump a draft's `version:` on edit. Before any `em slice reratify`,
+  run `em status <model>.em --json`: pre-release = the model's `modelVersion` entry has
+  `design: null` **and** `slices.byStatus.implemented === 0`. Pre-release → never run
+  `reratify`; edit `draft`/`reviewed` docs in place. Released → the re-ratification path in
+  the `slice` phase below.
+- **Pre-commit check.** Stage the session's files, run `em system scope --staged` (STOP on any
+  `seam-crossing`), then `git diff --cached --name-only` (STOP on any path outside this model's
+  directory, any out-of-scope path above, or a changed `version:` line on a draft doc).
+  Unstage the offending path and tell the user why.
+
 ## Phase: `model` — steps 5-7
 
 Goal: a structurally complete, **validated** model with correct patterns and swimlanes.
@@ -45,7 +83,8 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    `--wire` refuses it and names the originating slice holding `X`'s first declaration; its
    scenarios go into that doc instead. Then, for each freshly scaffolded doc, hold a first-pass
    Socratic pass and write the happy-path Given/When/Then into
-   its `## Scenarios (Given / When / Then)` section and the obvious invariants known so far into
+   its `## Scenarios (Given / When / Then)` section (as `### Scenario:` blocks — see **Generated
+   vs authored sections** in the `slice` phase below) and the obvious invariants known so far into
    its `## Invariants / Business Rules` section — **into the doc, never into the state file.**
    Keep this pass shallow (no field tables, alternate/error flows, or NFRs yet — that's the full
    deep-dive in the `slice` phase below); the docs are the home for everything collected from
@@ -71,6 +110,19 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    that reads it; another model/system reads it → mark it `public`; only an automation reads
    it → nothing, it's internal by design. No new keyword — reachability is already what `ui` and
    `public` mean.
+   **Per translation fed from another model, declare what it consumes (MIL-235):** write
+   `translation Order Intake consumes checkout:event.order-submitted`. The ref is
+   `<modelKey>:<kind>.<slug>`, where kind is `event` or `view` and the target is marked `public`
+   in its own model. The consumer declares the seam; the producer never lists its consumers, and
+   the ref carries no version and no slice. Only a `translation` may carry `consumes`. If a
+   reaction reads another model, it is a translation. `em validate` checks only the ref's
+   grammar. Run `em system` from the repository (or on its `system.yaml`) to resolve it, and fix
+   any `consumes-unknown-model`/`consumes-unknown-element` error. Never edit the other model to
+   make a ref resolve. Ask its owner to publish the element instead, and record that ask as a
+   seam change request (see **Write scope** above).
+   **When you mark an element `public` here**, run `em api generate <model>.em` in the same
+   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.
 
 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,
@@ -95,8 +147,14 @@ phases is the starting point, not the finished event set. **Every new event need
 real (someone has to see that the request was declined).
 
 For each slice:
-0. **Check for re-ratification first.** If `slices/<slice-name>.md` already exists with
-   `status: implemented`, this is a re-ratification, not fresh authoring: hold a Socratic
+0. **Check for re-ratification first.** A `draft` or `reviewed` doc is never re-ratified: edit
+   it in place and leave its `version:` alone. If `slices/<slice-name>.md` already exists with
+   `status: implemented` (or is ratified and needs a change), run `em status <model>.em --json`
+   first. **Pre-release** (the model's `modelVersion` entry has `design: null` and
+   `slices.byStatus.implemented === 0`): never run `em slice reratify`; a ratified doc holds a
+   human sign-off, so STOP, park the change as an open question, and let the ratifier decide.
+   **Released** (either condition false): a doc with `status: implemented` is a
+   re-ratification, not fresh authoring: hold a Socratic
    deep-dive on what changed (same rigor as step 1, scoped to the delta), update whichever
    sections actually changed, then express the change as the `## Delta` section — fixed heading,
    `### Added`/`Modified`/`Removed`/`Renamed` Requirement blocks each carrying its own scenarios
@@ -108,14 +166,51 @@ For each slice:
    schema doc). Otherwise, this is first-time authoring: continue at step 1.
 1. Hold a Socratic deep-dive to fill every section of `../event-modeling-shared/templates/slice.md`:
    intent, trigger/actor,
-   command + field table (types & rules), event(s) + payload (mark immutable facts), invariants
-   (give each a stable ID), Given/When/Then scenarios (happy path + rule boundaries + edge cases),
+   command fields (types & rules), event(s) + payload (mark immutable facts) — field names and
+   types go into the `.em`, the doc's tables are generated from it — invariants
+   (give each a stable ID — see **Invariants live in the model** below), Given/When/Then scenarios (happy path + rule boundaries + edge cases),
    alternate/error flows (retries, idempotency, compensations), non-functional requirements
    (security/authz, PII/compliance, performance/SLA), read models affected, open questions. Park
-   anything unresolved rather than guessing. If the slice lives in an existing codebase, Grep/Read
-   adjacent real sources (OpenAPI specs, DB migrations, existing DTOs/event classes in sibling
-   contexts) before finalizing field names/types or invariants — don't guess a shape that's
-   already defined elsewhere.
+   anything unresolved rather than guessing. Before finalizing field names/types or invariants,
+   check whether the shape is already defined in **this model** (`.em` and its slice docs) or in
+   a neighbour's public surface (read-only) — don't guess a shape that's already defined there.
+   Never Grep or Read implementation source, OpenAPI files, DB migrations or `specs/` to settle
+   it (evidence rule): if the user says the existing code is the source of truth, ask them for
+   the shape, or park the question for an `extract` or `conform` session. Before finalizing an
+   invariant, also compare it with the slices in
+   **this same model** — never another `.em` model — that make the same kind of change (other
+   `Archive*` or `Create*` state changes on different entities, say). If one of them already
+   states an analogous rule, either state the same rule here — written out in this doc under
+   this slice's own `INV-<MNEMONIC>-n` ID, not by pointing at the sibling's — or record why this
+   slice's case differs. If this slice has a rule those siblings lack, raise that with the user
+   as an open question against each of them; a ratified sibling changes only through its own
+   re-ratification, never as a side effect of this slice. Repeating a rule across slice docs is
+   correct: each doc is a self-contained spec, and whether the code behind those rules is shared
+   is the constitution's call, not this doc's.
+   **Invariants live in the model.** Write every NEW invariant into the `.em` as a standalone
+   `invariant INV-<MNEMONIC>-<n> "rule sentence"` line directly after the command (or event) it
+   guards — always with the rule sentence — then cite that ID in the doc's Invariants section as a
+   plain mention and elaborate there (`- INV-CHK-1 — why, edge cases, the error returned`); never
+   restate it as a `**INV-CHK-1:**` rule (`em validate` flags that as
+   `invariants/declared-in-both`). A `public` command needs at least one invariant
+   (`invariants/public-command-without-invariants`). A doc that already declares its own
+   invariants keeps working; migrate one only when you are editing that slice anyway — move the
+   ID and rule into the model, keep the doc's elaboration. Run `em validate` after the edit:
+   `invariants/malformed-id` and `invariants/duplicate-id` are errors.
+   **Generated vs authored sections.** A doc `em slice new` wrote has two kinds of section. The
+   GENERATED regions — each command's, event's and read model's field table and the Invariants
+   list, between `<!-- GENERATED:em-slice-…:start -->` / `:end -->` markers — restate the model:
+   **never hand-edit a generated region.** To change a field, a type, or an invariant, edit the
+   `.em`, then **after any model edit run `em slice sync <model>.em`**, which rewrites every
+   region in place and leaves everything else byte-for-byte (`em slice sync <model>.em --check`
+   reports a stale doc without writing). **Edit authored sections only**: Intent, Trigger &
+   Actor, `Triggered by`/`Read by`/`Consumed by`, the invariant elaborations below the generated
+   list, Scenarios, Alternate & Error Flows, NFRs, Dependencies, Open Questions. Scenarios use the
+   constrained shape `em` reads back: a `### Scenario: <title>` heading, then `- **Given:**`,
+   `- **When:**`, `- **Then:**` bullets with nested `  - ` items — all three in every block
+   (`em validate` flags a block missing one as `slice-doc/structured-section-malformed`, and
+   `--slice-ready` refuses it). A doc written before em 1.14 has no markers; leave it as it is
+   unless you are re-creating it (`em slice new … --wire --force`, carrying the prose across).
 2. **First-time authoring:** scaffold the doc mechanically rather than hand-writing the
    frontmatter — `em slice new "<slice name>" --pattern <state-change|state-view|automation|
    translation> --swimlane "<Persona> → <Context>" --wire <model>.em` writes `slices/<slice-name>.md`
@@ -131,20 +226,42 @@ For each slice:
    declaration — write this slice's scenarios into that doc instead of scaffolding a new one.
    Both `--pattern` and `--swimlane` are required; an invalid `--pattern` is refused with the
    valid choices listed. Never hand-type this block, and never fall back to a placeholder
-   pattern/swimlane to dodge the flags. Then fill in every judgment section below the stub from
-   step 1 (Intent, Command, Event(s), Invariants, Scenarios, ...) — the doc's prose is still
-   entirely hand-authored, only the frontmatter/heading scaffold and the `.em` wiring are
-   mechanized. Record the originating need (ticket/conversation link) in the Intent section when
-   one exists. When this doc exists because of a split, merge, or rename, add the matching
+   pattern/swimlane to dodge the flags. It also writes every template section: the generated
+   regions already filled from the model (field tables, Invariants list), the authored sections
+   as placeholders. Then fill in the authored sections from step 1 (Intent, Trigger & Actor,
+   invariant elaborations, Scenarios, ...) — those stay hand-authored; the generated regions
+   follow the model through `em slice sync`. Record the originating need (ticket/conversation
+   link) in the Intent section when one exists. When this doc exists because of a split, merge, or rename, add the matching
    lineage key(s) by hand (`split-from`/`merged-from`/`superseded-by`, `<slice-key>@v<N>` grammar
    — see `../event-modeling-shared/reference/slice-doc-schema.md` for the full schema; `em validate` catches a malformed one
    after the fact, see the `lineage-*` rules below).
-   **Re-ratification (step 0):** the doc already exists, so `em slice new` doesn't apply here
+   **Re-ratification (step 0) — released models only.** Confirm the model is released first
+   (`em status <model>.em --json`: the `modelVersion` entry's `design` is not `null`, or
+   `slices.byStatus.implemented > 0`); on a pre-release model never run `reratify`. The doc
+   already exists, so `em slice new` doesn't apply here
    (it refuses to overwrite an existing file without `--force`, and forcing would blow away the
    doc's authored body) — run `em slice reratify <model>.em <slice-key>` instead: it bumps
    `version` and flips `status` back to `ready-to-implement` in the existing frontmatter,
    clearing any stale `ratifiedBy:`/`ratifiedOn:` from the prior version so a follow-up
-   `em slice ratify --by <name>` (if the team records that) applies cleanly.
+   `em slice ratify --by <name>` (if the team records that) applies cleanly. The same command
+   changes a ratified doc that **never shipped** (`ready-to-implement` with `ratifiedBy` set — a
+   gap answered mid-build, MIL-258): it bumps `version` and clears the sign-off but leaves
+   `status` alone. Either way the doc is not ratified until `em slice ratify --by <name>` records
+   the new sign-off. A `ready-to-implement` doc with no `ratifiedBy` is already awaiting that
+   sign-off and refuses a second `reratify`; a `draft`/`reviewed` doc is simply edited, and its
+   `version:` never moves.
+   **Public-touching slices (MIL-238).** On a slice that owns a `public` command, event or view,
+   `em slice ratify --by <name>` and `em slice reratify` refuse without one of two flags: pass
+   `--meaning-unchanged` when this version does not change what the public contract means, or
+   `--contract-change "<why>"` when a consumer must read the change differently. Without
+   either, both refuse with `slice "<key>" touches the public surface — pass
+   --meaning-unchanged, or --contract-change "<why>" if a consumer must read this change
+   differently`; passing both refuses too. Run
+   `em api generate <model>.em` first, so `em validate --slice-ready` sees a current contract
+   (otherwise it blocks with `slice-ready-contract-stale`).
+   Which flag applies is the ratifier's call, not yours: ask, never pick one to make the
+   command pass. Ratification itself stays a human gate outside this session; a review session
+   never ratifies (see `event-modeling-review`).
 3. Render the slice's own diagram: `em render <model>.em --slice "<slice name>" -o
    slices/<slice-name>.svg` (kebab-case, matching the doc's filename and the `![Diagram]` stub
    `em slice new` already wrote) — redraws just this slice in its own canonical pattern shape.
@@ -158,7 +275,12 @@ For each slice:
 5. Run `em slice index <model-name>.em` to regenerate `README.md`'s Slices table — the one
    canonical slice index — from the model and the doc frontmatter you just wrote (status,
    `implementedIn` once shipped). Never hand-edit the table; it's a generated block.
-6. Re-render and `em validate`.
+6. Re-render, run `em slice sync <model-name>.em --check` (it must print `ok:` for every doc you
+   touched), and `em validate`.
+7. Before committing, stage the session's files and run the pre-commit check: `em system scope
+   --staged`, then `git diff --cached --name-only`. STOP on any `seam-crossing`, any path outside
+   this model's directory, any out-of-scope path (see **Write scope** above), or a changed
+   `version:` line on a draft doc.
 
 A finished draft doesn't become implementable here: it goes through the review gate and then the
 ratification gate, both human, both outside this phase — see

package/.claude/skills/event-modeling-discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-discover
-em-version: 1.13.0
+em-version: 1.14.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