@milehimikey/em 1.6.0 → 1.7.0

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

@@ -1,28 +1,32 @@
 ---
 name: event-modeling
+em-version: 1.7.0
 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
+  Translation), and produce implementation-ready slice docs. 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.
+  existing system), `model` (steps 5-7), `slice` (deep slice specs), `implement` (build one
+  ratified slice into code, following the bundled agent guide), `conform` (drift check
+  against the codebase), plus `watch`, `review` (stakeholder walkthrough), and `validate`.
+  With no argument it resumes from the saved state file.
 ---
 
 # 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)
 
@@ -79,8 +83,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)
@@ -226,6 +230,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 +249,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,
@@ -346,6 +392,7 @@ two slices and route it through a command.
 
 ## 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 +404,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
 

package/.claude/skills/event-modeling/reference/em-dsl.md

@@ -10,20 +10,61 @@ Keep `.em` files focused on **structure**; put deep design in markdown linked vi
 
 ## CLI
 
+<!-- GENERATED:cli:start -- run `npm run docs:generate` to refresh, do not hand-edit -->
 ```bash
-em init [file]                 # scaffold a starter model.em (default: model.em); -f to overwrite
-em render <file> -o out.svg    # render (extension picks format: svg, png, pdf)
-em render <file> --emit-dot    # print the Graphviz DOT instead of rendering
-em render <file> --keep-empty-lanes   # keep the API lane even when empty
-em render <file> --slice "<slice-name>" -o slices/<slug>.svg   # this slice's own diagram
-em watch  <file> -o out.svg    # re-render on every save (file-based)
-em watch  <file> -o out.svg --serve   # + localhost live viewer, instant SSE push-reload (--port N)
-em validate <file>             # check event-modeling rules; exit 0 if only warnings/clean
-em validate <file> --list-issues       # print only open `issue "..."` clauses (slice, element, line, text)
-em validate <file> --list-divergences  # print only `divergence "..."` clauses (slice, element, line, text)
-em validate <file> --list-public       # print only events marked `public` (slice, name, line)
-em validate <file> --fail-on-issues    # opt-in CI gate: exit non-zero while any issue remains open
+em --version                              # print the installed em version
+em init [file]                            # scaffold a starter .em model
+em init [file] -f, --force                # overwrite if the file exists
+em render <file>                          # transpile a model and render it (or emit DOT)
+em render <file> -o, --out <path>         # output path (extension picks the format)
+em render <file> -T, --format <fmt>       # output format (svg, png, pdf, ...)
+em render <file> --slice <name>           # render only this slice, redrawn in its own canonical pattern shape (default out: slices/<kebab-slug>.svg)
+em render <file> --emit-dot               # print the generated DOT instead of rendering
+em render <file> --keep-empty-lanes       # keep the API lane even when empty
+em export <file>                          # export a versioned JSON snapshot of the normalized model
+em export <file> -o, --out <path>         # write to a file instead of stdout
+em diff <old> [new]                       # compare two models structurally (two files, or one file across git revisions)
+em diff <old> [new] --from <rev>          # diff <old> against this git revision instead of a second file
+em diff <old> [new] --to <rev>            # diff against this git revision instead of the current file (requires --from)
+em diff <old> [new] --exit-code           # exit 1 if the models differ, 0 if identical (git-diff convention)
+em diff <old> [new] --json                # print a JSON document instead of the text report (see docs/cli.md)
+em glossary <files>                       # cross-model glossary of terms, with consistency checks across models (see docs/cli.md)
+em glossary <files> --json                # print the full glossary document instead of the text report
+em glossary <files> -o, --out <path>      # write the JSON document to a file instead of stdout (requires --json)
+em glossary <files> --list-conflicts      # print only the conflict lines, no summary
+em glossary <files> --fail-on-conflicts   # exit non-zero if any cross-model term conflicts were found (opt-in — conflicts are warnings and don't block by default)
+em catalog <files>                        # generate a browsable static HTML catalog site over one or more .em models (see docs/cli.md)
+em catalog <files> -o, --out <dir>        # output directory
+em catalog <files> -T, --format <fmt>     # diagram format embedded in the catalog (svg or png)
+em catalog <files> --title <text>         # catalog site title
+em catalog <files> --keep-empty-lanes     # keep the API lane even when empty
+em changelog <file>                       # render a model's git history as a business-readable ledger (see docs/cli.md)
+em changelog <file> --from <rev>          # start the walk at this revision (inclusive)
+em changelog <file> --to <rev>            # end the walk at this revision (inclusive; default HEAD)
+em changelog <file> -o, --out <path>      # write to a file instead of stdout
+em watch <file>                           # re-render on every save
+em watch <file> -o, --out <path>          # output path (extension picks the format)
+em watch <file> -T, --format <fmt>        # output format (svg, png, pdf, ...)
+em watch <file> --keep-empty-lanes        # keep the API lane even when empty
+em watch <file> --serve                   # serve a live viewer with instant push-reload (no polling)
+em watch <file> --port <n>                # port for --serve (default 5173)
+em validate <file>                        # check a model against event-modeling rules
+em validate <file> --list-issues          # print only open `issue` diagnostics (slice, element, line, text)
+em validate <file> --list-divergences     # print only accepted-divergence annotations (slice, element, line, text) — never fails the build
+em validate <file> --list-public          # print only events and views marked `public` (slice, kind, name, line) — an integration-surface audit, never fails the build
+em validate <file> --fail-on-issues       # exit non-zero if the model has any open `issue`s (opt-in — issues are warnings and don't block by default)
+em validate <file> --slice-ready <key>    # readiness gate for one slice (export key): status ready-to-implement, doc resolvable via note binding, zero unchecked Open Questions — exits non-zero if not ready (MIL-87)
+em ledger <file>                          # check slice docs' version: field agrees with their content across two git revisions (opt-in CI check, MIL-89 — never part of `em validate`, see docs/ci.md)
+em ledger <file> --from <rev>             # baseline revision
+em ledger <file> --to <rev>               # compare revision (default: current working tree)
+em ledger <file> --json                   # print a JSON document instead of the text report (see docs/cli.md)
+em skill install                          # copy the event-modeling skill into .claude/skills/event-modeling/
+em skill install -f, --force              # overwrite an existing installation
+em skill sync [path]                      # update the vendored .claude/skills/event-modeling/ copy in [path] to match the installed em package (overwrites unconditionally; local edits are never merged, MIL-93)
+em skill check [path]                     # check the vendored .claude/skills/event-modeling/ copy in [path] for drift against the installed em package; exits non-zero on any mismatch (CI-ready, MIL-93)
+em skill check [path] --json              # print a JSON document instead of the text report (see docs/cli.md)
 ```
+<!-- GENERATED:cli:end -->
 
 Install if missing: `npm i -g @milehimikey/em`. PNG works with no system deps; PDF needs
 `rsvg-convert`.
@@ -57,15 +98,23 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
 |---|---|---|---|---|
 | `ui` | persona | screen / interface | `@Persona` | `note`, `issue`, `divergence`, `{ fields }` |
 | `command` | API | state-changing request | — | `note`, `issue`, `divergence`, `{ fields }` |
-| `view` | API | read model / projection | — | `from "Event"…`, `note`, `issue`, `divergence`, `{ fields }` |
+| `view` | API | read model / projection | — | `from "Event"…`, `note`, `issue`, `divergence`, `public`, `{ fields }` |
 | `event` | context | recorded fact (past tense) | `@Context` | `note`, `issue`, `divergence`, `public`, `{ fields }` |
 | `processor` / `automation` / `saga` / `translation` | automation | system reaction / adapter | — | `from "…"`, `note`, `issue`, `divergence`, `{ fields }` |
 
 ### Clauses
-- **Tags:** `@Persona` only on `ui`; `@Context` only on `event`. Undeclared tags auto-create a row.
+- **Tags:** `@Persona` only on `ui`; `@Context` only on `event`. Undeclared tags auto-create a
+  row. Multi-word tags need no quoting — the tag captures everything after `@` to end of line
+  (`ui Ticket Queue @Customer Service` matches `persona Customer Service`).
 - **`from "X"`** on views/automations declares the source(s); names are quoted, comma-separated.
   Matching is case-insensitive and whitespace-normalized. A `from` may never point at an event or
   view that first appears in a LATER slice (forward-only timeline — validation error).
+  Kinds never cross: a view's `from` resolves ONLY to events; a reaction's `from` resolves ONLY
+  to read models — naming an event on a reaction is a validation error even though the event
+  exists. Feed an event to a reaction by projecting it into a view first (the automation's
+  "to-do list") and pointing the reaction at that view. Name that view after the pending work
+  (`Payments To Process`), never after the triggering event — a view reusing the event's name
+  collides in the shared namespace and draws a duplicate-name warning.
 - **`again`** (views only): `view <Name> again [from "Event", …]` declares a later instance of an
   already-declared read model — the forward-only device for a view that evolves as later events
   land. Instances are ONE logical view: the first declaration owns the `note` binding; each
@@ -89,13 +138,16 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   Raises **no** `em validate` warning by design; use `--list-divergences` to audit. `em diff
   --json` carries it forward as `acceptedDivergence` on the affected change/removal entry, so
   `conform` can cite an already-ratified deviation instead of re-flagging it as drift every run.
-- **`public`** (events only): marks this event as part of the published integration surface
-  (e.g. an AsyncAPI contract), as opposed to an internal-only fact. Plain structural flag, no
-  free text and no diagram marker (same posture as `again`). Write it as the last token on the
-  line, optionally right before a trailing `@Context` — `event X @Context public` or
-  `event X public @Context` both work. `em export` carries it as `public: true`/`false`;
-  `em diff` reports a flip as `event marked public`/`event unmarked public`;
-  `em validate --list-public` audits which events are public.
+- **`public`** (events and views): marks the element as part of the published integration
+  surface — a published event contract (e.g. AsyncAPI), or a view whose read API/response
+  shape external consumers depend on — as opposed to an internal-only fact or projection.
+  Plain structural flag, no free text and no diagram marker (same posture as `again`). Write
+  it as the last token on the line; on an event, optionally right before a trailing
+  `@Context` — `event X @Context public` or `event X public @Context` both work. A `public`
+  element is exempt from the unread-event / unconsumed-view warnings (its consumer is outside
+  this model). `em export` carries it as `public: true`/`false`; `em diff` reports a flip as
+  `event marked public`/`event unmarked public` (the entry cites the element's kind, so a
+  view flip reads `view "X"`); `em validate --list-public` audits the whole public surface.
 - **Fields:** `command Place Order { orderId: UUID, items: LineItem[], customerId }` — inline or
   one-per-line. Types are free text (no semantic checking) UNLESS the type string names a
   declared `type` (see Named types below), in which case it resolves to a structured
@@ -328,6 +380,12 @@ slice "Read Quote — created" {
    (`type Node { child: Node }`, or the same shape across several types). Break the cycle, or
    route the self/mutual reference through an array (`children: Node[]`) if the data is
    genuinely tree-shaped.
+9. **Lineage-ref errors** (slice-doc frontmatter, fs-aware) — a
+   `split-from`/`merged-from`/`superseded-by` ref with malformed `<slice-key>@v<N>` grammar, a
+   self-reference or cycle, a `superseded-by` naming a slice absent from the current model, or
+   a ref naming a version higher than the target's own `version:`. A `split-from`/`merged-from`
+   naming a key absent from the tree is deliberately silent — that's the normal state after a
+   real split/merge (see the four `lineage-*` codes in the table below).
 
 **Warnings (should fix):**
 1. **Automation/translation shares slice with its command** — both `automation`/`processor` and
@@ -342,8 +400,10 @@ slice "Read Quote — created" {
 4. **Command without event** — every command should record at least one event.
 5. **Event nobody reads** — the mirror of (4): recording an event no read model projects is a
    write with no reader. Follow every write slice with the read slice that consumes its event.
-   Counts as read when a `view` names it in `from` (any `again` instance will do), when a
-   fieldless-`from` view sits in its slice, or via an explicit `event -> view` arrow.
+   Counts as read when a `view` names it in `from` (any `again` instance will do), when a view
+   with no `from` of its own sits in its slice, or via an explicit `event -> view` arrow.
+   (Events marked `public` are exempt — their reader is outside the model; same for a
+   `public` view and the no-consumer warning.)
 6. **Read model without source** — add `from "Event"` or place the view in a slice with an event.
 7. **Duplicate name** — the same name defined N times; references resolve to the first. Rename.
    (A duplicate `type` name always warns, unlike a duplicate element name — there's no
@@ -358,11 +418,73 @@ slice "Read Quote — created" {
     command in the same slice. Only checked once BOTH the event and at least one same-slice
     command declare `{ fields }`. This is the payoff of the fields feature for slicing rigor:
     once fields are written down, `em validate` checks that data flows forward consistently.
+11. **Event with no producing command** — a fact with no traceable cause; add the command that
+    records it (either order within the slice), or an explicit `arrow` from one.
+12. **Two same-named `translation`s reading different producers** — rename one; fires
+    unconditionally (unlike the duplicate-name warning), since the confusion is in reading
+    the model, not resolving a reference.
+13. **Frontmatter coherence** (slice docs, fs-aware) — `status: implemented` with no
+    `implementedIn` link at all. The re-ratification mismatch (status flipped back while
+    `implementedIn` names the prior PR) is deliberately never flagged — it's the drift
+    signal, not incoherence.
+14. **Doc-join problems** (`em export`/`--slice-ready`) — `binding-missing-file` (a
+    `note "slices/<key>.md"` binding pointing at a file that doesn't exist) and
+    `frontmatter-invalid` (the doc exists but lacks a frontmatter block or a required key).
 
 `divergence "text"` is deliberately NOT in this list — it raises no warning at all, since it
 records a deviation already reasoned through and accepted, not something to fix. Use
 `em validate --list-divergences` to audit them on demand.
 
+### Full rule code reference
+
+Every rule above (and every fs-aware check `em validate` layers on top — lineage, frontmatter
+coherence) has a stable `code`, generated below from the same registry `em` itself validates
+against (`src/model/rules.ts`) — a new rule shows up here the moment it's registered, whether or
+not the prose above has caught up yet. `--slice-ready <key>`-only codes are excluded; see
+`docs/cli.md#em-validate-file` in the
+[em repository](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-validate-file).
+
+<!-- GENERATED:validate-rules:start -- run `npm run docs:generate` to refresh, do not hand-edit -->
+| Code | Severity | Title | Fix |
+|---|---|---|---|
+| `arrow-backward` | error | Backward arrow | Restructure so the target comes later. |
+| `arrow-unresolved-source` | error | Arrow source unresolved | Fix the arrow's source name. |
+| `arrow-unresolved-target` | error | Arrow target unresolved | Fix the arrow's target name. |
+| `automation-shares-slice-with-command` | warning | Automation shares slice with its command | Put the triggered command in the next slice. |
+| `binding-missing-file` | warning | Doc binding points at a missing file | Create the slice doc, or fix the `note` path. |
+| `both-ends-of-a-flow/command-no-event` | warning | Command without event | Add the event this command records. |
+| `both-ends-of-a-flow/command-untriggered` | warning | Command with no trigger | Add a `ui` in this slice, or a reaction in the previous slice. |
+| `both-ends-of-a-flow/event-unproduced` | warning | Event with no producing command | Add the command that records it, or an explicit arrow from one. |
+| `both-ends-of-a-flow/event-unread` | warning | Event nobody reads | Project it into a view, or reconsider recording it. |
+| `both-ends-of-a-flow/ui-unbacked` | warning | `ui` with no read model or command | Add a `view` it displays, or the command it triggers. |
+| `both-ends-of-a-flow/view-unconsumed` | warning | Read model with no consumer | Add a `ui` or reaction that consumes it, or drop this instance. |
+| `connection-legality/illegal-pair` | error | Illegal connection | Only ui→command→event→view→ui and view→reaction→command are legal — the message names the missing step. |
+| `duplicate-element-ref` | warning | Duplicate element ref | Rename the element so its export ref is unique. |
+| `duplicate-name` | warning | Duplicate name | Rename one of the duplicates. |
+| `duplicate-slice-name` | warning | Duplicate slice name | Rename the slice so its export key is unique. |
+| `duplicate-type-name` | warning | Duplicate type name | Rename one of the duplicate `type` declarations. |
+| `duplicate-type-ref` | warning | Duplicate type ref | Rename the type so its export ref is unique. |
+| `fields-completeness/event-field-no-source` | warning | Event field not from a command | Add the field to a command in the slice, or remove it from the event. |
+| `fields-completeness/view-field-no-source` | warning | View field with no source | Add the field to a source event, or remove it from the view. |
+| `frontmatter-coherence-implemented-without-link` | warning | Implemented without a link | Add `implementedIn` once the slice ships. |
+| `frontmatter-invalid` | warning | Invalid or missing frontmatter | Add the required frontmatter keys, or add a frontmatter block. |
+| `grid-collision` | error | Band collision | Split the colliding elements into separate slices. |
+| `lineage-forward-dangling` | error | Dangling forward lineage ref | Fix the key, or remove the stale successor. |
+| `lineage-ref-cycle` | error | Lineage cycle | Break the cycle — a slice can't be its own ancestor. |
+| `lineage-ref-malformed` | error | Malformed lineage ref | Fix the value to `<slice-key>@v<N>`, or remove it. |
+| `lineage-version-impossible` | error | Impossible lineage version | Fix the referenced version, or ratify the target slice first. |
+| `open-issue` | warning | Open issue | Resolve the question, then remove the `issue` clause. |
+| `reaction-from-future-view` | error | Backward timeline (reaction reads a future view) | Declare the view in or before the reaction's slice. |
+| `reaction-from-unresolved` | error | Unknown read-model source | Project the event into a view first, or fix the `from` reference. |
+| `translation-name-collision` | warning | Translation name reused for different producers | Use a distinct name per producer to avoid confusion. |
+| `type-cycle` | error | Cyclic type reference | Break the cycle, or route the self/mutual reference through an array. |
+| `ui-shares-slice-with-automation` | warning | `ui` shares slice with a reaction, no command | Move the `ui` to the read-model slice, or to the slice with the command this triggers. |
+| `view-again-without-earlier` | error | `again` without an earlier declaration | Declare the view plainly the first time it appears. |
+| `view-from-future-event` | error | Backward timeline (view reads a future event) | Move the source to a later `view X again` instance. |
+| `view-from-unresolved` | error | Unknown event source | Fix the `from` reference to name an existing event. |
+| `view-no-source` | warning | Read model without source | Add `from "Event"`, or place the view in a slice with an event. |
+<!-- GENERATED:validate-rules:end -->
+
 **Design rules that keep models valid:**
 - One element per band per slice (multiple personas/contexts are fine — they're different rows).
 - Every `command` slice includes its `event`. Every `view` has a `from` source.

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

@@ -124,7 +124,8 @@ accepted case, and each one is worth naming explicitly as a finding); every unkn
 `# TBD`; and the user has confirmed the model reflects today's behavior. Then:
 
 1. State file: set phase progress (extraction rounds checked), log the completion decision.
-   Seed `README.md`'s **slice index** (every slice, pattern, status `none`).
+   Seed `README.md`'s **slice index** (every slice, pattern, status "no doc yet" — no slice
+   docs exist until the `slice` phase writes them).
 2. The extracted model **replaces `discover`** — suggest `/event-modeling model` next
    (steps 5-7: swimlanes, patterns, completeness). Desired-state changes belong *after* the
    as-is model is agreed — as normal `model`/`slice` evolution, clearly separated from