@milehimikey/em 1.8.1 → 1.9.0

package/.claude/skills/{event-modeling → event-modeling-shared}/reference/em-dsl.md

@@ -1,4 +1,4 @@
-<!-- DSL behavior change? Update BOTH docs/dsl.md and .claude/skills/event-modeling/reference/em-dsl.md -->
+<!-- DSL behavior change? Update BOTH docs/dsl.md and .claude/skills/event-modeling-shared/reference/em-dsl.md -->
 
 # `em` DSL Reference & Cheatsheet
 
@@ -12,88 +12,118 @@ Keep `.em` files focused on **structure**; put deep design in markdown linked vi
 
 <!-- GENERATED:cli:start -- run `npm run docs:generate` to refresh, do not hand-edit -->
 ```bash
-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 scaffold <name>                                          # scaffold a full project: <slug>/<slug>.em, README.md, .event-modeling.md (see docs/cli.md — for just a starter .em, use `em init`)
-em scaffold <name> -f, --force                              # overwrite the directory's contents if it already 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 export <file> --slice <key>                              # export only this slice's object (pattern/fields/doc) instead of the whole model (export key, MIL-128) — refuses only if THIS slice has an error; an unrelated slice's breakage elsewhere in the model doesn't block it (see docs/cli.md)
-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 slice new <name>                                         # scaffold a fresh slices/<key>.md doc — the 5 frontmatter keys required at `status: draft` plus the `# Slice:` heading and diagram-image stub; judgment sections (Intent, Scenarios, Open Questions, ...) stay hand-authored (see docs/slice-doc-schema.md, templates/slice.md)
-em slice new <name> --pattern <pattern>                     # slice pattern: state-change | state-view | automation | translation
-em slice new <name> --swimlane <swimlane>                   # swimlane, e.g. "Persona → Context"
-em slice new <name> -f, --force                             # overwrite the file if it already exists
-em slice index <file>                                       # rewrite the model's sibling README.md's GENERATED Slices table from `em export`'s slice facts (key, pattern, doc status/implementedIn) — the hand-maintained table is deprecated
-em slice index <file> --check                               # verify the table is current; exit non-zero on drift without writing (CI)
-em slice mark-implemented <file> <slice-key> <pr-url>       # flip a slice doc's frontmatter to `status: implemented` / `implementedIn: <pr-url>` — the one edit an implementing agent makes to a ratified doc at merge (MIL-103, replaces the em-sdd-bridge `em-sdd-mark-implemented` script; see reference/implement.md §6). Idempotent on the same URL; refuses to overwrite a different one; never touches `version:` or the doc body
-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 state read [dir]                                         # print the state file's mechanical fields as JSON
-em state set-phase <phase> [dir]                            # rewrite Current phase: (and Last updated:); --step also rewrites Current step:
-em state set-phase <phase> [dir] --step <n>                 # also set Current step: to this value
-em state set-conformance <revision> [dir]                   # rewrite Last conformance: (and Last updated:) in the exact format reference/conform.md parses
-em state set-conformance <revision> [dir] --report <path>   # path to the conformance report just written
-em state set-review <date> [dir]                            # rewrite Last stakeholder review: (and Last updated:)
-em conform-scope <file>                                     # mechanize conform phase step 1 (reference/conform.md): map the target repo's changed paths since Last conformance: to slices via each slice doc's implementedIn, JSON to stdout — --seed-asis also seeds the <model>-asis.em scratch model (see docs/cli.md)
-em conform-scope <file> --repo <path>                       # path to (or inside) the target codebase's git repository
-em conform-scope <file> --full                              # ignore Last conformance:/changed paths; scope every implemented slice
-em conform-scope <file> --seed-asis                         # write <model>-asis.em as a byte copy of the canonical model and ensure it's gitignored
-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 validate <file> --json                                   # print a JSON document instead of text — works on a model WITH errors, unlike `em export` (MIL-128, see docs/cli.md); exit codes are unchanged
-em migrate <file>                                           # rewrite the old two-slice Automation/Translation shape into the merged single-slice shape MIL-120 made canonical (see docs/cli.md)
-em migrate <file> --write                                   # apply the rewrite to the file (default: dry run — report only, write nothing)
-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 coverage <file>                                          # check that every INV-* invariant ID cited in a ready-to-implement/implemented slice doc is cited by a test under --tests <dir> (MIL-130) — mechanizes reference/implement.md's definition-of-done citation check; advisory by default, --strict for CI
-em coverage <file> --tests <dir>                            # directory to scan recursively for test files citing invariant IDs
-em coverage <file> --strict                                 # exit non-zero if any invariant ID has zero citations (CI)
-em coverage <file> --json                                   # print a JSON document instead of the text report (see docs/cli.md)
-em contract                                                 # print the packaged implementation contract (reference/implement.md) to stdout — the agent-neutral discovery path for any agent that can run a shell, not just Claude Code (MIL-129); see docs/cli.md
-em mcp                                                      # start an MCP (Model Context Protocol) server over stdio, exposing validate/slice_ready/list_markers/export_model/export_slice/coverage/contract as tools (MIL-21) — a structured, agent-facing alternative to shelling out to `em`; see docs/mcp.md. Equivalent to running the `em-mcp` bin directly
-em skill install                                            # copy the event-modeling skill into .claude/skills/event-modeling/
-em skill install -f, --force                                # overwrite an existing installation
-em skill install --no-agents-md                             # skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)
-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 sync [path] --no-agents-md                         # skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)
-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)
+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 scaffold <name>                                            # scaffold a full project: <slug>/<slug>.em, README.md, .event-modeling.md (see docs/cli.md — for just a starter .em, use `em init`; for a multi-model project, pass --under to nest it under a shared parent directory)
+em scaffold <name> -f, --force                                # overwrite the directory's contents if it already exists
+em scaffold <name> --under <dir>                              # parent directory to scaffold into — writes <dir>/<slug>/ instead of ./<slug>/, the supported multi-model layout (docs/cli.md, "Multi-model projects"): one directory per model, so each model's slices/ never collides with a sibling model's
+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 export <file> --slice <key>                                # export only this slice's object (pattern/fields/doc) instead of the whole model (export key, MIL-128) — refuses only if THIS slice has an error; an unrelated slice's breakage elsewhere in the model doesn't block it (see docs/cli.md)
+em typespec <file>                                            # EXPERIMENTAL/POC (MIL-159): generate a TypeSpec contract for a model's commands, public events, and public views (see docs/cli.md)
+em typespec <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 slice new <name>                                           # scaffold a fresh slices/<key>.md doc — the 5 frontmatter keys required at `status: draft` plus the `# Slice:` heading and diagram-image stub; judgment sections (Intent, Scenarios, Open Questions, ...) stay hand-authored (see docs/slice-doc-schema.md, templates/slice.md)
+em slice new <name> --pattern <pattern>                       # slice pattern: state-change | state-view | automation | translation
+em slice new <name> --swimlane <swimlane>                     # swimlane, e.g. "Persona → Context"
+em slice new <name> -f, --force                               # overwrite the file if it already exists
+em slice new <name> --wire <model-file>                       # also insert the `note "slices/<key>.md"` line onto the slice's primary element in this .em file (matched by export key), instead of just printing it to paste by hand (MIL-161)
+em slice index <file>                                         # rewrite the model's sibling README.md's GENERATED Slices table from `em export`'s slice facts (key, pattern, doc status/implementedIn) — the hand-maintained table is deprecated
+em slice index <file> --check                                 # verify the table is current; exit non-zero on drift without writing (CI)
+em slice mark-implemented <file> <slice-key> <pr-url>         # flip a slice doc's frontmatter to `status: implemented` / `implementedIn: <pr-url>` — the one edit an implementing agent makes to a ratified doc at merge (MIL-103, replaces the em-sdd-bridge `em-sdd-mark-implemented` script; see reference/implement.md §6). Idempotent on the same URL; refuses to overwrite a different one; never touches `version:` or the doc body
+em slice ratify <file> <slice-key>                            # flip a slice doc's frontmatter to `status: ready-to-implement` and record `ratifiedBy:`/`ratifiedOn:` — the handoff sign-off (MIL-165, docs/process.md#what-ratified-means) that makes who ratified, and when, a first-class recorded fact. Idempotent on the same --by/--on pair; refuses to overwrite a different one already recorded; never touches `version:` or the doc body
+em slice ratify <file> <slice-key> --by <name>                # the ratifier's name
+em slice ratify <file> <slice-key> --on <date>                # ratification date, YYYY-MM-DD (default: today)
+em slice reratify <file> <slice-key>                          # bump `version:` and flip a shipped slice doc's frontmatter back to `status: ready-to-implement` — the re-ratification mechanical edit (MIL-161, mirrors `em slice mark-implemented`). Only applies to a doc at `status: implemented`; clears any stale `ratifiedBy:`/`ratifiedOn:` (they describe the PRIOR version's sign-off) so a follow-up `em slice ratify --by` applies cleanly; never touches `implementedIn:` or the doc body
+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 state read [dir]                                           # print the state file's mechanical fields as JSON
+em state set-phase <phase> [dir]                              # rewrite Current phase: (and Last updated:); --step also rewrites Current step:
+em state set-phase <phase> [dir] --step <n>                   # also set Current step: to this value
+em state set-conformance <revision> [dir]                     # rewrite Last conformance: (and Last updated:) in the exact format reference/conform.md parses
+em state set-conformance <revision> [dir] --report <path>     # path to the conformance report just written
+em state set-review <date> [dir]                              # rewrite Last stakeholder review: (and Last updated:)
+em state log-usage <file>                                     # append one Usage log line — phase(s) touched + em validate's diagnostic categories hit, deduped and canonically formatted (MIL-161, docs/usage-data.md) — the mechanical half of 'save state at the end of every session' that used to be run-validate-then-hand-format; state file resolved next to <file>, same convention as em conform-scope
+em state log-usage <file> --phases <list>                     # comma-separated phase(s) touched this session: discover, extract, model, slice, implement, conform, review, validate, watch
+em usage-report [root]                                        # aggregate every .event-modeling.md's Usage log under [root] into phase/diagnostic-category tallies (MIL-161) — replaces docs/usage-data.md's hand-rolled grep/awk/sort pipeline; a logged line that doesn't match the canonical em state log-usage format is reported under unparseableLines rather than silently mistallied or dropped
+em usage-report [root] --json                                 # print a JSON document instead of the text report
+em conform-scope <file>                                       # mechanize conform phase step 1 (reference/conform.md): map the target repo's changed paths since Last conformance: to slices via each slice doc's implementedIn, JSON to stdout — --seed-asis also seeds the <model>-asis.em scratch model (see docs/cli.md)
+em conform-scope <file> --repo <path>                         # path to (or inside) the target codebase's git repository
+em conform-scope <file> --full                                # ignore Last conformance:/changed paths; scope every implemented slice
+em conform-scope <file> --seed-asis                           # write <model>-asis.em as a byte copy of the canonical model and ensure it's gitignored
+em conform-supersede <file> <report-path>                     # stamp a conformance report with a "superseded as of <rev>" banner once its findings have been ruled on (MIL-164, docs/process.md#what-ratified-means) — the companion step to run at ratification time so a reader following the report's file:line citations knows they describe an ancestor of the current model. Additive-only splice, never a rewrite of the report; idempotent on the same --as-of/--findings/--on stamp; refuses if the report doesn't exist
+em conform-supersede <file> <report-path> --as-of <rev>       # the revision this ruling was made against — same value passed to `em state set-conformance`
+em conform-supersede <file> <report-path> --findings <spec>   # which finding number(s) this stamps as ruled, e.g. "1-3" or "1,2,4"
+em conform-supersede <file> <report-path> --on <date>         # ruling date, YYYY-MM-DD (default: today)
+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 validate <file> --json                                     # print a JSON document instead of text — works on a model WITH errors, unlike `em export` (MIL-128, see docs/cli.md); exit codes are unchanged
+em migrate <file>                                             # rewrite the old two-slice Automation/Translation shape into the merged single-slice shape MIL-120 made canonical (see docs/cli.md)
+em migrate <file> --write                                     # apply the rewrite to the file (default: dry run — report only, write nothing)
+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 coverage <file>                                            # check that every INV-* invariant ID cited in a ready-to-implement/implemented slice doc is cited by a test under --tests <dir> (MIL-130) — mechanizes reference/implement.md's definition-of-done citation check; advisory by default, --strict for CI
+em coverage <file> --tests <dir>                              # directory to scan recursively for test files citing invariant IDs
+em coverage <file> --strict                                   # exit non-zero if any invariant ID has zero citations (CI)
+em coverage <file> --json                                     # print a JSON document instead of the text report (see docs/cli.md)
+em status <files>                                             # deterministic state-of-the-system rollup over one or more .em models: slices by lifecycle status, driftSignal breakdown, invariant coverage totals (with --tests), open issue markers + unchecked Open Questions, and last-conformance commits-behind-HEAD (MIL-163, see docs/cli.md)
+em status <files> --tests <dir>                               # directory to scan for INV-* test citations — enables invariant coverage totals
+em status <files> --repo <path>                               # git repo to compute commits-behind-HEAD in (default: each model's own directory)
+em status <files> --json                                      # print a JSON document instead of the text report (see docs/cli.md)
+em status <files> --md                                        # print a markdown block suited for README embedding
+em status <files> --badge                                     # print a generated SVG badge
+em status <files> -o, --out <path>                            # write output to a file instead of stdout
+em freshness <file>                                           # standalone freshness signal for one model's conformance record (MIL-164): "last conformed <rev> — N commits and M slice-PRs behind HEAD", computed from the same conform-scope machinery `em status`'s conformance clause uses — for when you want just this fact, no full state-of-the-system rollup (see docs/cli.md)
+em freshness <file> --repo <path>                             # git repo to compute behind-HEAD in (default: the model's own directory)
+em freshness <file> --json                                    # print a JSON document instead of the text line
+em contract                                                   # print the packaged implementation contract (reference/implement.md) to stdout — the agent-neutral discovery path for any agent that can run a shell, not just Claude Code (MIL-129); see docs/cli.md
+em mcp                                                        # start an MCP (Model Context Protocol) server over stdio, exposing validate/slice_ready/list_markers/export_model/export_slice/coverage/contract as tools (MIL-21) — a structured, agent-facing alternative to shelling out to `em`; see docs/mcp.md. Equivalent to running the `em-mcp` bin directly
+em skill install                                              # copy the event-modeling skill bundle into .claude/skills/ (event-modeling, event-modeling-discover/-design/-implement/-conform/-review, event-modeling-shared)
+em skill install -f, --force                                  # overwrite an existing installation
+em skill install --no-agents-md                               # skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)
+em skill sync [path]                                          # update the vendored .claude/skills/ event-modeling skill bundle in [path] to match the installed em package (overwrites unconditionally; local edits are never merged, MIL-93)
+em skill sync [path] --no-agents-md                           # skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)
+em skill check [path]                                         # check the vendored .claude/skills/ event-modeling skill bundle 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)
+em ci init <model>                                            # install .github/workflows/em-ci.yml (PR gates: em validate, em slice index --check, em coverage --strict, em ledger, em skill check, em glossary --fail-on-conflicts, plus a push-triggered status-badge rebuild) and em-conform.yml (scheduled, advisory-only conformance cadence) — same install discipline as `em skill install`: marker-delimited, idempotent, --check for CI self-verification (MIL-166, see docs/ci.md)
+em ci init <model> --tests <dir>                              # test directory the coverage/status steps scan for INV-* citations
+em ci init <model> -f, --force                                # replace an existing workflow file that has no GENERATED markers
+em ci init <model> --check                                    # verify both files match the current preset; exit non-zero on drift without writing (CI)
 ```
 <!-- GENERATED:cli:end -->
 
@@ -530,6 +560,7 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `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. |
+| `cross-model-slice-doc-collision` | warning | Colliding slice doc path across models | Give each model its own directory (see docs/cli.md, "Multi-model projects"). |
 | `doc-model-element-not-in-doc` | warning | Model element the doc doesn't mention | Add the matching marker to the doc, or remove the element from the model. |
 | `doc-model-element-not-in-model` | warning | Doc names an element the model doesn't have | Add the element to the model, or fix/remove it in the doc. |
 | `doc-model-field-mismatch` | warning | Doc/model field mismatch | Reconcile the field table with the model's fields — names and types. |
@@ -553,6 +584,7 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `note-binding-unratified` | warning | Unratified cross-slice note | Add `covers: <this-slice-key>` to that doc's frontmatter, or correct the note's path. |
 | `note-binding-unusable` | warning | Cross-slice note to a doc with unusable frontmatter | Fix that doc's frontmatter, or fix/remove the note. |
 | `open-issue` | warning | Open issue | Resolve the question, then remove the `issue` clause. |
+| `orphaned-slice-doc` | warning | Orphaned slice doc | Rename it to a current slice's key, add `covers:` (plus a `note` binding) to attach it to a live slice, or delete it. |
 | `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. |
 | `tag-composite-unknown-field` | error | Composite tag names an unknown field | Fix the field name, or add it to the event's fields. |

package/.claude/skills/{event-modeling → event-modeling-shared}/reference/methodology.md

@@ -213,9 +213,10 @@ state change anyone can think of. No commands, no UI yet — just facts.
     User Clicked Button, User Viewed Page, User Logged In.
 - Model the process the business **needs**, not how the current system happens to work. Existing
   system behavior is a common source of fake events — screens and tables leaking in as facts.
-  (**Extract mode inverts this**: in the skill's `extract` phase the existing system *is* the
-  subject and this caution is deliberately suspended — see the "Extract" section below and
-  `reference/extract.md`. The derived-value and telemetry filters still apply there.)
+  (**Extract mode inverts this**: in the `event-modeling-discover` skill's `extract` phase the
+  existing system *is* the subject and this caution is deliberately suspended — see the
+  "Extract" section below and `event-modeling-discover`'s own `reference/extract.md`. The
+  derived-value and telemetry filters still apply there.)
 - Output: a flat list of candidate `event` names.
 
 ### Step 2 — The Plot / Storyboard  *(discover)*
@@ -251,7 +252,7 @@ or automation never records an event directly; it triggers a command.
 ### Step 6 — Elaborate Scenarios  *(model first pass, slice deep pass)*
 For each slice, write **Given / When / Then** scenarios and surface **invariants**, **critical
 fields**, and **alternate / error flows**. In the `model` phase do a light first pass; the
-dedicated `slice` phase writes the full rich spec (see `templates/slice.md`).
+dedicated `slice` phase writes the full rich spec (see `../templates/slice.md`).
 - Prompts: *"Given what starting state, when this command/trigger fires, then what event(s)
   result? What must always be true? What are the failure paths? Which fields are essential and
   what are their rules?"*
@@ -311,7 +312,7 @@ Desired-state improvements belong to the `model` and `slice` phases, after the a
 agreed.
 
 Procedure, source modes (event-driven vs. procedural synthesis), and the round-by-round loop:
-`reference/extract.md`.
+the `event-modeling-discover` skill's own `reference/extract.md`.
 
 ---
 

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

@@ -0,0 +1,147 @@
+# Operating principles, preconditions, and project layout (every phase)
+
+Shared by every `event-modeling-*` skill. Read this before doing any work in any phase — it's
+the discipline and mechanics that don't change no matter which phase you're facilitating.
+`methodology.md` (the 7 steps + 4 patterns) and `em-dsl.md` (DSL syntax and validation rules) in
+this same directory are the other two shared references; read them too before doing real work —
+they, together with this doc, are the source of truth every phase skill builds on. Templates
+live in `templates/`, a sibling of this `reference/` directory. References to `docs/*.md`
+throughout these skills mean the
+[em repository's docs](https://github.com/milehimikey/em/tree/main/docs) — they are not
+vendored alongside these skills.
+
+## Operating principles
+
+- **Socratic, one question at a time.** Ask focused questions; use `AskUserQuestion` for tight
+  multiple-choice decisions. Never assume a domain fact — extract it. Prefer "who/why/what-if/
+  what-must-always-be-true/how-do-you-know" over yes-no.
+- **Don't guess — park it.** Unresolved items go into the Open Questions list in
+  `.event-modeling.md`, not into invented model content. Note the source, blocker, and revisit
+  date when known — cheap now, useful when you come back to it.
+- **Happy path first; branches belong to slicing.** Steps 1-7 build the **happy-path spine**.
+  Alternate, unhappy, and exception-path events (rejections, removals, cancellations,
+  expirations, declines) are **not** enumerated as a separate discover/model task — they
+  surface during the `slice` phase as each slice's alternate/error flows and rule-boundary
+  scenarios, and any new branch events get added to the `.em` then. Never list "draft the
+  branch events" as a discover/model to-do or ask the user to do it before slicing.
+- **Reflect and re-render.** After each meaningful increment, update the `.em` file, re-render,
+  and show the user what changed. Encourage running the live view (`watch`) so a team can follow.
+- **Keep the `.em` structural; put depth in `note` docs.** The diagram holds flow; invariants,
+  fields, and scenarios live in `slices/*.md` linked via `note "slices/<name>.md"`.
+- **Headless/API models still use `ui`.** If the system is headless (clients call an API, not
+  screens), declare a persona per external caller/role (e.g. `IntegratorAPI`) and treat its `ui`
+  boxes as API calls, not screens: writes are `ui → command → event` and reads are
+  `read model → ui`, exactly like any other State Change/State View slice — no separate trigger
+  slice. `translation` stays reserved for genuine reactions and real external-system boundaries,
+  not a synchronous request/response call. Internal-only commands/views with no public route carry
+  no `ui` at all — they follow the ordinary Automation pattern instead. **Repeat read models**
+  across slices so the timeline flows left-to-right — put each repeat **right after the event that feeds it**, sourcing
+  only that one adjacent event, so every arrow is short (a read model far from its source events
+  draws a long arrow whose head lands columns away, making the *write* slice read as dangling —
+  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. 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 `methodology.md` (State View) and `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 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
+  is missing an **element**, not an arrow.
+- **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 log a Usage log
+  line: `em state log-usage <model>.em --phases <phase1,phase2,...>` computes and dedupes the
+  diagnostic *categories* that fired for you and appends the canonically-formatted line — never
+  hand-run `em validate --json` and format the line yourself. This is the team's only usage
+  signal today (`docs/usage-data.md`) — keep it cheap and habitual, not a task to skip.
+
+## Preconditions (run first)
+
+1. Check the tool: `em --version`. If missing, tell the user to run `npm i -g @milehimikey/em`
+   and stop until installed.
+2. Locate the model. Look for an existing `<dir>/.event-modeling.md` and `*.em` in the working
+   directory, or — for a multi-model project laid out per the convention below — one level down
+   inside a `models/` subfolder (each model gets its own `models/<slug>/` directory; check each
+   candidate for its own `.event-modeling.md`/`*.em` pair). If found, run `em state read <dir>`
+   to read the state file's mechanical fields (model path, phase, step, last updated, last
+   conformance, last review) as JSON — don't parse the bullets by hand. If not, and the phase
+   needs one, ask the user for the model name and where to create it (a lone model goes at the
+   project root; one of several goes under `models/`, per "Multi-model projects" below).
+3. If you're not sure which phase applies, or the user gave no phase, use `em state read <dir>`'s
+   `phase`/`step` to resume the recorded phase/step — or invoke the `event-modeling` skill, which
+   does exactly this and routes to the right skill. If no model exists, propose starting
+   `discover` (greenfield, `event-modeling-discover`) or `extract` (modeling an existing system,
+   also `event-modeling-discover`).
+4. Populate the state file's Participants section at session start. For a live workshop, ask for
+   a single human proxy to relay questions to the room, and attribute every answer/decision in
+   the Decisions log to a named participant.
+
+## Project layout these skills create
+
+```
+<model-name>/
+  <model-name>.em          # the model (slice docs linked via note "...")
+  <model-name>.svg         # render target for em watch
+  README.md                # overview + slice index (from templates/model-readme.md)
+  .event-modeling.md       # resumable state (from templates/state.md)
+  slices/<slice-name>.md   # one rich slice doc per slice (from templates/slice.md)
+  conformance/<date>-report.md
+                           # conform-phase reports (from templates/conformance-report.md)
+  <model-name>-asis.em     # conform-phase scratch model, regenerated per run — git-ignore this
+```
+
+When creating a new model, run `em scaffold <model-name>` — it creates `<model-name>/` and
+writes all three starter files in one step (`<model-name>.em`, `README.md`,
+`.event-modeling.md`), filling the Model Name/model-name placeholders and the state file's
+mechanical fields (model path, `Current phase: discover`, `Current step: 1`, dates) for you, so
+there's nothing left to hand-copy or fill in. Refuses if `<model-name>/` already exists; pass
+`--force` to overwrite. You'll
+usually replace the scaffolded `.em`'s content as the discovery conversation builds up the real
+model — it starts out as the same starter model `em init` writes, titled from `<model-name>`.
+`slices/*.md` and `conformance/` aren't part of `em scaffold`; they come from the `slice` and
+`conform` phases (`event-modeling-design` and `event-modeling-conform`). The `conformance/`
+directory and `<model-name>-asis.em` only appear once the `conform` phase runs; `em conform-scope
+--seed-asis` creates `<model-name>-asis.em` and gitignores `*-asis.em` for you (see
+`event-modeling-conform`'s `reference/conform.md`) — it's scratch, never committed.
+
+### Multi-model projects
+
+Slice docs resolve at a fixed path — `slices/<slug>.md`, sibling of the `.em` file that
+declares the slice — with no model namespace anywhere, so **one directory per model** is the
+whole guardrail against two models' slice names colliding. For more than one model, nest each
+one's directory (the exact layout above) under a shared `models/` parent instead of scattering
+them at the project root:
+
+```
+models/
+  checkout/
+    checkout.em
+    slices/...
+  fulfillment/
+    fulfillment.em
+    slices/...
+```
+
+Run `em scaffold <model-name> --under models` for each model — it creates `models/<slug>/`
+directly rather than a two-step `cd models && em scaffold <model-name>`. See
+[docs/cli.md, "Multi-model projects"](https://github.com/milehimikey/em/blob/main/docs/cli.md#multi-model-projects)
+for the full rationale, and why slice keys stay unqualified (no `<model>/<slice>` prefix) —
+directory isolation alone is sufficient. Two `.em` files sharing a directory with colliding
+slice keys don't go undetected: `em status`/`em catalog`, the two commands that ever compile
+more than one model in a run, raise a `cross-model-slice-doc-collision` warning naming both
+files — treat that warning as a sign the models need separating, not a false positive.

package/.claude/skills/{event-modeling → event-modeling-shared}/templates/model-readme.md

@@ -37,8 +37,8 @@ never connected to one another.
      `em slice index {{model-name}}.em` to (re)write the table below from the model and its
      slice docs; never hand-edit between the markers. -->
 <!-- GENERATED:slices:start -->
-| # | Slice | Pattern | Status | Implemented in | Design doc |
-|---|-------|---------|--------|----------------|------------|
+| # | Slice | Pattern | Status | Ratified by | Owner | Tracking | Implemented in | Design doc |
+|---|-------|---------|--------|-------------|-------|----------|----------------|------------|
 <!-- GENERATED:slices:end -->
 
 ## Status

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

@@ -35,6 +35,17 @@ to write up. Delete it otherwise; most docs never carry it. Requires a matching
 `note "slices/{{this-slice-name}}.md"` on an element in the OTHER slice — this key alone doesn't
 bind anything. Plain slice keys, comma-separated — not the `<slice-key>@v<N>` ref grammar above.
 
+`ratifiedBy`/`ratifiedOn` record who ratified this doc's current `status`/`version`, and when —
+don't hand-fill these; run `em slice ratify <model>.em {{this-slice-name}} --by "<name>"` at the
+handoff gate instead (docs/process.md#what-ratified-means), which flips `status` to
+`ready-to-implement` and writes both in one edit.
+
+`owner`/`tracking` are optional and, unlike `ratifiedBy`/`ratifiedOn`, hand-filled — no `em`
+command writes either. `owner` is free text naming who (a person or team) holds this slice;
+`tracking` is a URL into an external tracker (Jira, Linear, ...) mirroring it — the exact field
+`em-tracker-bridge` reads to find the mirrored ticket. `em` only stores and displays both; it
+never talks to a tracker itself. Delete both otherwise; most docs never carry them.
+
 Full machine schema — required-vs-optional keys per `status`, value types/enums, the
 unknown-key policy — is documented in docs/slice-doc-schema.md.
 
@@ -59,6 +70,9 @@ implementedIn: {{PR/commit link — fill in once status is `implemented`}}
 # (e.g. the view-only half of a two-slice Automation/Translation, MIL-121); delete otherwise.
 # Plain slice keys, comma-separated. See docs/slice-doc-schema.md#cross-slice-coverage-covers.
 # covers: <slice-key>, <slice-key>
+# Ownership / tracking — optional, hand-filled (no `em` command writes either); delete otherwise.
+# owner: <person or team>
+# tracking: <ticket URL>
 ---
 # Slice: {{Slice Name}}
 
@@ -81,7 +95,9 @@ implementedIn: {{PR/commit link — fill in once status is `implemented`}}
 #### Requirement: {{title}} ({{stable ID, e.g. an INV-{{MNEMONIC}}-n from Invariants below}})
 {{requirement text — same voice as an Invariants entry}}
 ##### Scenario: {{name}}
-- **GIVEN** {{...}} **WHEN** {{...}} **THEN** {{...}}
+- **Given:** {{...}}
+- **When:** {{...}}
+- **Then:** {{...}}
 
 ### Modified
 <!-- Same shape as Added — the stable ID names the requirement that changed. -->
@@ -146,16 +162,33 @@ an event directly.}}
      `INV-<MNEMONIC>-<n>`, where `<MNEMONIC>` is a short (2-4 letter/digit), slice-unique
      abbreviation of this slice's key (e.g. slice `checkout` -> `INV-CHK-1`) — see
      docs/slice-doc-schema.md. Add a letter suffix for a closely-related sub-invariant
-     (`INV-CHK-3a`). -->
+     (`INV-CHK-3a`). Keep the rule statement itself to one line. If it needs more — why the rule
+     exists, what "violation" looks like in practice, an edge case worth calling out — add that as
+     a nested bullet under the rule instead of one long run-on sentence: this section renders as
+     HTML (`em catalog`/`em render`/`em watch`), and a nested bullet stays visually distinct where
+     a wrapped sentence collapses into a wall of text. The ID must stay on the rule's own
+     top-level bullet line — `em coverage` extracts INV IDs from that line only, never from a
+     nested elaboration bullet underneath it. -->
 - **INV-{{MNEMONIC}}-1:** {{rule that the command enforces; violation ⇒ rejection}}
+  - {{optional: rationale, edge-case detail, or what "violation" means here — its own bullet}}
 - **INV-{{MNEMONIC}}-2:** {{...}}
 
 ## Scenarios (Given / When / Then)
-<!-- The executable specification. Cover the happy path AND the key rule boundaries. -->
-- **Happy path** — Given {{starting state / prior events}}, When {{command/trigger}},
-  Then {{event(s) recorded}} and {{resulting read-model change}}.
-- **Rejected (INV-{{MNEMONIC}}-1)** — Given {{state}}, When {{command}}, Then {{rejected with reason}}; no event.
-- **{{Edge case}}** — Given {{...}}, When {{...}}, Then {{...}}.
+<!-- The executable specification. Cover the happy path AND the key rule boundaries. Each
+     scenario is a case-label bullet with Given/When/Then as nested sub-bullets — not one run-on
+     sentence — so the case reads as distinct beats once rendered instead of a dense paragraph. -->
+- **Happy path**
+  - **Given:** {{starting state / prior events}}
+  - **When:** {{command/trigger}}
+  - **Then:** {{event(s) recorded}} and {{resulting read-model change}}.
+- **Rejected (INV-{{MNEMONIC}}-1)**
+  - **Given:** {{state}}
+  - **When:** {{command}}
+  - **Then:** rejected with reason; no event.
+- **{{Edge case}}**
+  - **Given:** {{...}}
+  - **When:** {{...}}
+  - **Then:** {{...}}
 
 ## Alternate & Error Flows
 <!-- Failure paths, retries, compensations, timeouts, idempotency. -->
@@ -174,5 +207,15 @@ an event directly.}}
 - **Downstream read models / slices affected:** {{...}}
 
 ## Open Questions
-<!-- Park unresolved items here instead of guessing. Mirror them into .event-modeling.md. -->
+<!-- Park unresolved items here instead of guessing. Mirror them into .event-modeling.md.
+
+     Lifecycle across versions: while THIS version is still being worked, a resolved item
+     (`- [x]`) can stay checked here as a visible record of what's already been decided this
+     round. On the same commit that ratifies the NEXT version (bumps `version`, rewrites
+     `## Delta` above) — prune every already-checked item from this list; keep only what's still
+     open, plus anything new the delta itself surfaced. Same "replace, never accumulate" stance
+     as `## Delta`, for the same reason: an ever-growing scroll of resolved questions goes stale
+     exactly like an accumulating Delta log would, and full history already lives in git
+     (`git log -p slices/<name>.md`) — this section is a live worklist, not an audit trail. See
+     docs/slice-doc-schema.md#open-questions-section-lifecycle. -->
 - [ ] {{question}}