@milehimikey/em 1.6.1 → 1.7.1

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

@@ -1,28 +1,26 @@
 ---
 name: event-modeling
+em-version: 1.7.1
 description: >-
-  Guide a user and their team through building rigorous Event Models with the `em` CLI, using
-  the 7 steps of Event Modeling and the 4 patterns (State Change, State View, Automation,
-  Translation), and produce implementation-ready slice design documents. Use when the user wants
-  to event-model a business process or system, do event modeling / event storming, design slices,
-  build or edit an `.em` model, run the em tool, extract / reverse-engineer a current-state
-  event model from an existing system or codebase (event-driven or legacy/procedural), or check
-  a ratified model for drift against the codebase that implements it. Works in resumable phases
-  via an argument: `discover` (steps 1-4, greenfield), `extract` (current-state model of an
-  existing system), `model` (steps 5-7), `slice` (deep slice specs), `conform` (drift check
-  against the codebase), plus `watch` and `validate`. With no argument it resumes from the saved
-  state file.
+  Use when the user wants to event-model a business process or system: building, editing,
+  updating, or maintaining a model — extending or detailing an existing one into slices,
+  extracting a current-state model from an existing codebase, implementing a ratified slice, or
+  checking a model for drift against the code. Drives the `em` CLI through resumable phases —
+  discover, extract, model, slice, implement, conform, watch, review, validate — or resumes
+  automatically with no argument.
 ---
 
 # Event Modeling with `em`
 
 You are facilitating an Event Modeling session. Your job is to **extract an accurate model from
 the user through Socratic questioning** — never to invent the domain. You drive the `em` CLI to
-render the model live, and you produce implementation-ready slice design docs.
+render the model live, and you produce implementation-ready slice docs.
 
 Read `reference/methodology.md` (the 7 steps + 4 patterns) and `reference/em-dsl.md` (DSL syntax and
 validation rules) before doing real work — they are the source of truth. Templates live in
-`templates/`.
+`templates/`. References to `docs/*.md` throughout this skill mean the
+[em repository's docs](https://github.com/milehimikey/em/tree/main/docs) — they are not
+vendored alongside this skill.
 
 ## Operating principles (every phase)
 
@@ -55,23 +53,24 @@ validation rules) before doing real work — they are the source of truth. Templ
   keep a sub-flow that detours into another context together, not parked at the end of the model).
   Declare every instance after the first with
   **`view X again from "..."`** — `again` instances are exempt from the duplicate-name warning even
-  when referenced, and each reference resolves to the right instance. Slice order matters: a
-  reaction must be directly followed by its command slice, and a read slice must not be immediately
-  followed by a command slice (see `em-dsl.md`).
+  when referenced, and each reference resolves to the right instance. A reaction's command is
+  wired by same-slice presence, exactly like `ui → command` — no positional/adjacency rule to get
+  right (see `em-dsl.md`).
   See `reference/methodology.md` (State View) and `reference/em-dsl.md`.
 - **Never connect two instances of one read model.** The repeat is a timeline device, not a flow:
   continuity is implied by the shared name, and the events arriving at each instance are what show
   it changing. An arrow between instances says the read model feeds itself, and is an error.
 - **Every slice is a COMPLETE pattern, never a half-slice.** A State Change is
   `ui → command → event`; a State View is `event → read model → ui` (or `→ reaction`). So: a
-  command needs something that **triggers** it (the `ui` it's issued from, or the reaction in the
-  slice before it), its event needs a **reader**, and that read model needs a **consumer** of its
-  own. A command nothing points at is a write nobody can start; an event nothing projects is a
-  write nobody can see; a read model nothing displays is information dropped on the floor. Write
-  the whole chain together rather than sweeping up dangling ends later. Reactions don't count as
-  readers of *events* — they read views. **Every instance** of a repeated read model needs its own
-  consumer: if you repeat a view next to an event just to keep the arrow short, bring its screen
-  along, or don't add the instance.
+  command needs something that **triggers** it (the `ui` it's issued from, or the reaction that
+  triggers it, also in this slice), its event needs a **reader**, and that read model needs a
+  **consumer** of its own. A command nothing points at is a write nobody can start; a reaction
+  that triggers no command is a decision the system never acts on; an event nothing projects is
+  a write nobody can see; a read model nothing displays is information dropped on the floor.
+  Write the whole chain together rather than sweeping up dangling ends later. Reactions don't
+  count as readers of *events* — they read views. **Every instance** of a repeated read model
+  needs its own consumer: if you repeat a view next to an event just to keep the arrow short,
+  bring its screen along, or don't add the instance.
 - **Only six connections are legal:** `ui → command`, `command → event`, `event → read model`,
   `read model → ui`, `read model → reaction`, `reaction → command`. Reaching for anything else —
   above all `command → read model` (the CQRS violation) or `read model → command` — means the model
@@ -79,8 +78,8 @@ validation rules) before doing real work — they are the source of truth. Templ
 - **Validate continuously.** Run `em validate` and fix errors/warnings as you go (see DSL ref).
 - **Save state at the end of every session** so work resumes cleanly. Also append one line to
   the Usage log: the phase(s) touched and the `em validate` diagnostic *categories* that fired
-  (rule name only, e.g. "read model nothing consumes" — never the full message or domain
-  content). This is the team's only usage signal today (`docs/usage-data.md`) — keep it cheap
+  (the exact fixed strings from `docs/usage-data.md`, e.g. "read model has no consumer" —
+  never the full message or domain content). This is the team's only usage signal today (`docs/usage-data.md`) — keep it cheap
   and habitual, not a task to skip.
 
 ## Preconditions (run first)
@@ -146,8 +145,9 @@ phase applies to field tables, below.
 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
    same breath: the screen the user issues it from (a `ui` in the slice), or — for the Automation
-   and Translation patterns — the reaction in the slice before it. A command nothing points at is
-   a write nobody can start. *"Who does this, and where are they when they do it?"*
+   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
+   do it?"*
 4. **Outputs (step 4).** Identify the **read models / views** consumers need and wire them with
    `from "Event"` (State View pattern), each with the screen (or reaction) that consumes it — a
    read model nothing displays is information dropped on the floor. In a **headless/API** model
@@ -190,23 +190,23 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
 
 1. **Swimlanes & patterns (step 5).** 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. **Split every automation _and every translation_ across two
-   slices** (the reaction — processor/translation — plus its read model in one slice; the
-   triggered command + its event in the *next* slice). A translation or automation is a reaction:
-   it **triggers a command and never records an event directly**. Add `translation` slices for
-   external inputs (externally triggered: external → translation → command → event) and for the
-   system reacting to its own state (internally triggered: read model → translation → command →
-   event).
+   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
+   and event it produces; the read model it watches, if any, stays in the slice before). A
+   translation or automation is a reaction: it **triggers a command and never records an event
+   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).** For each slice, capture the happy-path
    Given/When/Then and the obvious invariants as short notes. (The full spec is the `slice` phase.)
 3. **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
-   one of the six legal pairs, and automations **and translations** split correctly (each reaction
-   triggers a command — none wired straight to an event). Run `em validate` and resolve all errors
-   and warnings — but check the reaction→command→event split by hand, since `em validate` does
-   **not** flag a translation/automation that emits an event directly (see `reference/em-dsl.md`).
+   one of the six legal pairs, and every automation **and** translation triggers a command (none
+   wired straight to an event, none with no command at all). Run `em validate` and resolve all
+   errors and warnings — it catches a reaction wired straight to an event too now (see
+   `reference/em-dsl.md`), so a clean run covers this case.
    For an unread event, don't just bolt on a view to silence the warning: ask the user who looks at
    this fact and what they do with it. The honest answers are "here's the read model we missed" or
    "nobody — so why are we recording it", and both improve the model.
@@ -226,6 +226,16 @@ 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
+   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
+   (see `templates/slice.md` and `docs/slice-doc-schema.md#delta-section-grammar-and-lifecycle`)
+   — **overwriting** whatever the section held before, never appending to it. Then continue at
+   step 2 to bump `version` and flip `status` back to `ready-to-implement`, leaving
+   `implementedIn` naming the prior version's PR (intended drift signal, not a bug — see the
+   schema doc). Otherwise, this is first-time authoring: continue at step 1.
 1. Hold a Socratic deep-dive to fill every section of `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),
@@ -235,19 +245,51 @@ For each slice:
    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.
-2. Write the doc to `slices/<slice-name>.md` (kebab-case the slice name). Record the originating
+2. Write the doc to `slices/<slice-name>.md` (kebab-case the slice name), with the YAML
+   frontmatter block at the very top — all five of `schemaVersion`/`pattern`/`swimlane`/
+   `status`/`version` (kebab-case `pattern` value, `schemaVersion: 1`, `version` starting at
+   `1`; omitting any of the five makes the doc `frontmatter-invalid` to `em export` and the
+   readiness gate), plus `implementedIn` once shipped — the canonical, machine-read
+   metadata dialect (`- **Status:** ...` bullet lines are legacy/accepted input only; never
+   write new docs that way). When this doc exists because of a split, merge, or rename, add the
+   matching lineage key(s) too (`split-from`/`merged-from`/`superseded-by`, `<slice-key>@v<N>`
+   grammar — see `docs/slice-doc-schema.md` for the full schema). On a re-ratification (step 0),
+   bump `version` and flip `status` here instead of setting them fresh. Record the originating
    need (ticket/conversation link) in the Intent section when one exists.
 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) — redraws just this slice
    in its own canonical pattern shape, and add `![Diagram](./<slice-name>.svg)` near the top of
-   the doc, right after the metadata bullet list.
+   the doc, right after the `# Slice:` heading (below the frontmatter block).
 4. Wire it into the `.em`: add `note "slices/<slice-name>.md"` to the slice's primary element
    (the command for State Change, the view for State View, the processor for Automation, the
    translation for Translation).
-5. Update `README.md`'s slice index — the one canonical slice table (`draft` →
-   `ready-to-implement`, later `implemented` once shipped, with `Implemented in:` filled in).
+5. Update `README.md`'s slice index — the one canonical slice table (`draft` → `reviewed` →
+   `ready-to-implement`, later `implemented` once shipped, with its Implemented-in link
+   filled in).
 6. Re-render and `em validate`.
 
+When a slice is **ratified** — a human flips its `status` to `ready-to-implement` with every
+open question resolved — it's ready to hand to an implementer. Confirm with
+`em validate <model>.em --slice-ready <key>`, and point whoever (or whatever) implements it
+at `reference/implement.md`.
+
+## Phase: `implement` — build one ratified slice
+
+Goal: turn a single `ready-to-implement` slice into merged, verified code — the one phase
+where the agent builds rather than facilitates.
+
+**Read `reference/implement.md` before doing any implement work and follow it as the
+contract.** In short: gate on `em validate <model>.em --slice-ready <key>` (stop and hand
+back if it fails — never edit the doc to make the gate pass); treat the slice doc as the
+spec (read-only, except the merge-time `status`/`implementedIn` flip); surface every gap to
+the user instead of deciding it silently; cover every INV-n and every scenario with tests;
+in spec-kit projects, allocate via em-sdd-bridge (redirect mode) and never run
+`/speckit.specify`.
+
+End of phase: PR merged, slice doc flipped to `status: implemented` with `implementedIn`
+filled, `README.md`'s slice index updated. Implement doesn't chain to another phase — run it
+once per ratified slice; `conform` later checks the result against the model.
+
 ## Phase: `conform` — drift check against the codebase
 
 Goal: check a **ratified** model (and its slice docs) against the codebase that implements it,
@@ -322,8 +364,8 @@ rule (see `reference/em-dsl.md`) and proposing the fix. Apply fixes on agreement
 
 | Diagnostic | Fix |
 |---|---|
-| automation/translation shares a slice with a command | Split the command into the next slice |
-| **command has nothing that triggers it** | Add the `ui` it's issued from — or, if the system issues it, the reaction in the slice before it. Ask *"who does this, and where are they when they do it?"* |
+| reaction triggers no command | Add the command it issues, in this same slice, or an explicit `arrow` to one elsewhere |
+| **command has nothing that triggers it** | Add the `ui` it's issued from — or, if the system issues it, the reaction that triggers it, also in this slice. Ask *"who does this, and where are they when they do it?"* |
 | **read model has no consumer** | Add the screen that displays it, or the reaction that watches it. If it's a repeat added only to shorten an arrow and nothing looks at it there, drop the instance |
 | read model has no source | Add the missing `from "Event"` |
 | command produces no event | Give the command its event, or drop the command |
@@ -337,15 +379,17 @@ relevant element over a `# TBD` comment — it shows up as a red marker on the r
 `em validate` tracks it as an open-issue warning, so it isn't lost once rendered. `em validate
 --list-issues` gives a quick sweep of everything still open.
 
-Then do one check `em validate` can't: scan every `translation`/`processor`/`automation` slice and
-confirm none contains an `event` — each reaction must trigger a `command` in the next slice
-(`reaction → command → event`). If you find a reaction wired straight to an event, split it into
-two slices and route it through a command.
+`em validate` now catches a reaction wired straight to an event too — any reaction with no
+`command` in its own slice, and no explicit arrow to one, warns "triggers no command". A
+`translation`/`processor`/`automation` should always trigger a `command` in its own slice
+(`reaction → command → event`); if one instead records an event directly, route it through a
+command instead.
 
 ---
 
 ## em command reference (quick)
 
+<!-- GENERATED:cli-quick:start -- run `npm run docs:generate` to refresh, do not hand-edit -->
 ```bash
 em --version
 em init <name>.em                          # optional starter scaffold
@@ -357,6 +401,7 @@ em watch <name>.em -o <name>.svg           # re-render on save (run in backgroun
 em watch <name>.em -o <name>.svg --serve   # + live viewer with instant push-reload (--port N)
                                             #   click "Review mode" for a slice-by-slice storyboard walkthrough
 ```
+<!-- GENERATED:cli-quick:end -->
 
 Always finish a working session by: re-rendering, running `em validate`, and updating
 `.event-modeling.md` with the current phase/step, decisions, open questions, and a Usage log

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

@@ -34,10 +34,11 @@ difference is what you do with what you find: extract *builds* a model from the
 
 1. A canonical `.em` model with a state file (`.event-modeling.md`), reachable the same way the
    SKILL.md preconditions locate it.
-2. The model should be ratified for the slices you're about to check — `slice` docs at
-   `implemented` (or the status the user says corresponds to shipped code) for whichever slices
-   are in scope. Checking a `draft` or `ready-to-implement` slice against code is a wasted walk;
-   tell the user and skip it rather than reporting "drift" against a doc nobody built to yet.
+2. The slices you're about to check should be **implemented** — docs at `status: implemented`
+   (or the status the user says corresponds to shipped code) for whichever slices are in scope.
+   Checking a `draft` or `ready-to-implement` slice against code is a wasted walk — ratified or
+   not, nobody has built to it yet; tell the user and skip it rather than reporting "drift"
+   against it.
 3. The codebase to check: the state file's **Existing system refs** (populated during
    `extract`, if this model came from one) or ask the user for the repo path if not set. Record
    it if missing. In a headless/scheduled run with no user to ask, default to the repository
@@ -56,7 +57,7 @@ named invariants, Given/When/Then scenarios). Conform checks all three surfaces
 |---|---|---|---|
 | **Structural** — `.em` ↔ code | slices/elements/fields/flow | `em` (deterministic) | `em diff --json` on canonical vs. an as-is scratch model |
 | **Spec** — slice doc ↔ code | field rules not enforced, named invariants (`INV-*`) without enforcement/test sites, GWT scenarios without test sites | you (judgment) | per-slice evidence walk: each checkable claim in the doc mapped to a code/test site by name (`INV-CHK-4` → its enforcement site + its test) |
-| **Internal** — slice doc ↔ `.em` | the doc's header metadata (Pattern, Status) or its Command/Event/Read Model sections and field tables disagreeing with the model's own elements/fields | you (judgment, v1) | cross-check the doc's structured sections against the slice's model elements |
+| **Internal** — slice doc ↔ `.em` | the doc's frontmatter (`pattern:`, `status:`) or its Command/Event/Read Model sections and field tables disagreeing with the model's own elements/fields | you (judgment, v1) | cross-check the doc's structured sections against the slice's model elements |
 
 The internal surface is deterministically checkable in principle (structured doc sections +
 `{ fields }` blocks) — promoting it to an `em validate` rule is a natural follow-up; file it as
@@ -74,7 +75,7 @@ authoritative.
 Default: **diff-scoped.** Read the state file's `Last conformance:` marker (date + target-repo
 revision). If it's set, run `git diff --name-only <recorded-revision>..HEAD` from the target
 repo's root to list the changed paths (`git log` alone prints commit subjects, not paths), then
-map those paths to slices (via each slice doc's known code locations, `Implemented in:` links,
+map those paths to slices (via each slice doc's known code locations, `implementedIn:` links,
 or a quick Grep if those are stale) — that's your in-scope set. If the marker reads `never`
 (first run) or the user passes `--full`, scope is every `implemented` slice.
 
@@ -112,6 +113,18 @@ For each slice in scope:
      3). If it does, this is not a fresh finding to litigate: classify it as **Accepted
      divergence** (step 4) and cite the annotation text as the evidence. This is the specific,
      per-element, ratified counterpart to the idiom-level bullet above.
+   - **Unpropagated deltas (MIL-85):** before treating any slice-level finding as drift, check
+     that slice's `doc.driftSignal` in `em export --json` (see `docs/slice-doc-schema.md`'s
+     "`status` under re-ratification" section for the mechanics). `"unpropagated-delta"` means
+     the slice was re-ratified (a new
+     `version`, `status` flipped back off `implemented`) but `implementedIn` still names the
+     *prior* version's PR — the code you're evidence-walking is that prior version, on purpose.
+     Do not diff it against the newer doc content and do not report a mismatch as Real drift or
+     a Model gap; classify it as **Unpropagated delta** (step 4) instead and stop — the finding
+     is "this delta hasn't shipped yet," not a defect in the shipped code. `"implemented-
+     without-link"` (status: implemented, no link at all) is a genuine coherence problem, but
+     it's already surfaced by `em validate`'s `frontmatter-coherence-implemented-without-link`
+     warning — don't re-raise it here as a separate conform finding.
 3. Write what you found into the scratch model (`<model-name>-asis.em`, see below). **Seed the
    scratch model as a copy of the canonical `.em` and replace only the in-scope slices** with
    the as-is picture, leaving out-of-scope slices byte-identical. This is not an optimization:
@@ -178,6 +191,12 @@ step 2 — sorts into exactly one class:
   `.em`/`em export` for a spec/internal finding). This is what the annotation is *for*: a
   reasoned, ratified deviation stops being re-reported as drift on every run. Cite the
   annotation text, not fresh judgment — that judgment already happened when it was written.
+- **Unpropagated delta** (MIL-85) — the slice's `doc.driftSignal` (`em export --json`) is
+  `"unpropagated-delta"`: a ratified version bump hasn't shipped yet, so `implementedIn` still
+  names prior work on purpose. Distinct from Accepted divergence — this is a structurally-
+  derived, deterministic signal (`status`/`implementedIn` coherence), not a human-authored
+  `divergence` annotation; keep the two separate so a reader can tell which mechanism produced
+  which finding. Cite `slice.doc.driftSignal` and `slice.doc.version` together as evidence.
 - **Extraction uncertainty** — no evidence either way. Never reported as drift or a gap.
 
 Every classification must cite the evidence recorded in step 2 (or the `em diff` entry, for
@@ -203,8 +222,11 @@ End of run: update the state file's `Last conformance:` marker, exact format:
 ```
 
 The revision is the one you just diffed against, so the next run's scope starts from here —
-step 1 parses this line, so keep the format exact. If any proposals were ratified and applied,
-log a Decisions entry noting what changed and why.
+step 1 parses this line, so keep the format exact. **The marker only advances with the human
+in the loop**: in an interactive session, update it after walking the report with the user; a
+headless/scheduled run writes the report but never the marker (nobody ratified the outcome),
+so the next run re-walks the same span — see `docs/ci.md`. If any proposals were ratified and
+applied, log a Decisions entry noting what changed and why.
 
 ## Conventions