@milehimikey/em 1.7.1 → 1.8.0

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

@@ -12,62 +12,93 @@ 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 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)
+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)
 ```
 <!-- GENERATED:cli:end -->
 
-Install if missing: `npm i -g @milehimikey/em`. PNG works with no system deps; PDF needs
-`rsvg-convert`.
+Install if missing: `npm i -g @milehimikey/em`. SVG, PNG, and PDF all work with no system
+deps; only rarer formats (ps, eps, ...) need `rsvg-convert`.
 
 ---
 
@@ -97,9 +128,9 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
 | Keyword | Band | Meaning | Tag | Extra clauses |
 |---|---|---|---|---|
 | `ui` | persona | screen / interface | `@Persona` | `note`, `issue`, `divergence`, `{ fields }` |
-| `command` | API | state-changing request | — | `note`, `issue`, `divergence`, `{ fields }` |
+| `command` | API | state-changing request | — | `note`, `issue`, `divergence`, `renamed from`, `{ 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 }` |
+| `event` | context | recorded fact (past tense) | `@Context` | `note`, `issue`, `divergence`, `public`, `tag`, `renamed from`, `{ fields }` |
 | `processor` / `automation` / `saga` / `translation` | automation | system reaction / adapter | — | `from "…"`, `note`, `issue`, `divergence`, `{ fields }` |
 
 ### Clauses
@@ -148,6 +179,30 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   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.
+- **`tag`** (events only): declares a DCB (Dynamic Consistency Boundary) tag key. Three forms:
+  a trailing `tag` on a field line inside the event's `{ … }` block (`priceId: UUID tag`, or
+  typeless `priceId tag`) — an identity tag, key defaults to the field's own name; a bare field
+  whose ENTIRE text is just `tag` is a field named `tag`, not a clause. `tag <key> from a, b`
+  (composite, ≥2 bare/unquoted field names — unlike a view's quoted `from`). `tag <key>
+  external "text"` (external — the string is documentation only, never parsed). Composite/
+  external clauses are element-level: write them as a trailing clause on the event (same
+  family as `note`/`issue`), or as one or more standalone `tag ...` lines immediately following
+  the event inside the slice body (attaches to the most recently declared element, which must
+  be an event); multiple accumulate. `tag` anywhere on a command/view/`ui`/`type` field, or an
+  element-level `tag` clause on a non-event, is a parse error. `em export` carries every tag
+  key under the event's `tags` array (`{ key, kind, fields, description }`); `em validate`
+  flags a composite tag naming an unknown field and a duplicate tag key on one event.
+- **`renamed from "Old1", "Old2"`** (events and commands only): records the prior name(s) an
+  element, or one of its fields, was known as — codegen metadata for converting
+  already-stored payloads instead of an upcaster chain. Element-level trails the element's own
+  name (same trailing-clause family as `@Context`/`public`); field-level trails a field's type,
+  or the bare name of a typeless field, inside the `{ … }` block — event/command fields only, a
+  parse error on a view/`ui`/automation-kind field or a `type` field. The list is quoted,
+  comma-separated, most-recent-old-name first. Inside one inline `{ … }` block, a bare quoted
+  field name immediately after a renamed field is read as a CONTINUATION of that list, not a
+  new field — give the quoted-name field a type, or write fields one per line, to avoid the
+  ambiguity. `em export` carries it as `renamedFrom: string[] | null` on both the element and
+  each field. **`em diff` does not read this clause** — a rename still reports as remove+add.
 - **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
@@ -463,6 +518,10 @@ 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. |
+| `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. |
+| `doc-model-pattern-mismatch` | warning | Doc/model pattern mismatch | Fix the doc's `pattern:` frontmatter to match the model, or restructure the slice to match the doc. |
 | `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. |
@@ -477,9 +536,15 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `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. |
+| `note-binding-dangling` | warning | Dangling cross-slice note | Create the doc at that path, or fix/remove the note. |
+| `note-binding-extra` | warning | Extra doc-binding note, ignored | Remove the note, or point it at the slice's actual bound doc. |
+| `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. |
 | `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. |
+| `tag-duplicate-key` | error | Duplicate tag key | Rename one of the tags so every key on the event is unique. |
 | `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 | Move the `ui` to the slice that displays the read model, or drop it. |

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

@@ -23,8 +23,8 @@ reaction-shares-a-slice-with-its-command shape — still applies.
 
 ## Setup
 
-1. Run the SKILL.md preconditions (tool check, model location) and scaffold the standard
-   project layout if no model exists yet.
+1. Run the SKILL.md preconditions (tool check, model location). If no model exists yet, run
+   `em scaffold <model-name>` (see SKILL.md's "Project layout this skill creates").
 2. **Agree the scope line first**: which system, which part, what's out of bounds. Write it to
    the state file's Session inputs.
 3. Record in the state file: `Source mode` (after detection, below) and
@@ -126,8 +126,9 @@ 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 "no doc yet" — no slice
-   docs exist until the `slice` phase writes them).
+   Run `em slice index <model-name>.em` to seed `README.md`'s **Slices table** — every slice,
+   its AST-derived 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

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

@@ -22,18 +22,22 @@ with this skill.)
 ## 1. Gate: verify readiness before starting
 
 ```bash
-em validate <model>.em --slice-ready <slice-key>
+em validate <model>.em --slice-ready <slice-key> --json
 ```
 
 `<slice-key>` is the slice's export key — the kebab-case slug of its name (`"Place Order"` →
-`place-order`). Exit 0 means: the slice has a doc bound via `note "slices/<key>.md"`, its
-frontmatter is usable, `status: ready-to-implement`, every `## Open Questions` checkbox is
-checked, and no status/version/link incoherence is flagged.
-
-**Non-zero exit means stop.** Report which checks failed and hand the slice back to the humans.
-Never make the gate pass yourself — checking an open-question box, flipping `status`, or
-editing frontmatter are ratification decisions, and ratification happens in a facilitated
-session, not in an implementation branch.
+`place-order`). Read the JSON document's `ready` field — don't infer it from the exit code or
+any printed text. `ready: true` means: the slice has a doc bound via `note "slices/<key>.md"`,
+its frontmatter is usable, `status: ready-to-implement`, every `## Open Questions` checkbox is
+checked, and no status/version/link incoherence is flagged — `gates` names each of those 4
+conditions individually (`docBound`/`frontmatterUsable`/`statusReady`/
+`noUncheckedOpenQuestions`) if you need to say which one is blocking.
+
+**`ready: false` means stop.** Report which `gates` entries are `false` (and any `diagnostics`
+entries concerning this slice) and hand the slice back to the humans. Never make the gate pass
+yourself — checking an open-question box, flipping `status`, or editing frontmatter are
+ratification decisions, and ratification happens in a facilitated session, not in an
+implementation branch.
 
 ## 2. Read the spec
 
@@ -43,7 +47,7 @@ Read `slices/<slice-key>.md` end to end — every section is load-bearing:
 |---|---|
 | frontmatter `pattern:` | Which of the four patterns' implementation shapes to build (State Change / State View / Automation / Translation) |
 | Command / Event field tables | The contracts — names, types, validation rules, immutable-fact markers |
-| `## Invariants / Business Rules` (INV-n IDs) | The non-negotiable rules; every one needs a test citing its ID |
+| `## Invariants / Business Rules` (`INV-<MNEMONIC>-n` IDs) | The non-negotiable rules; every one needs a test citing its ID |
 | `## Scenarios (Given / When / Then)` | The acceptance tests, already written — compile them, don't reinvent them |
 | `## Alternate & Error Flows` | Retries, idempotency, compensations — real requirements, not appendix |
 | `## Non-Functional Requirements` | Authz, PII, performance — implement or consciously surface, never skip |
@@ -51,9 +55,10 @@ Read `slices/<slice-key>.md` end to end — every section is load-bearing:
 
 For timeline context, read the slice's surroundings in the `.em` (what triggers it, what
 consumes its output) — the slice's own diagram (`slices/<slice-key>.svg`) shows its canonical
-pattern shape. For machine-readable facts, use `em export <model>.em` rather than parsing the
-DSL or the doc's frontmatter yourself: it carries the slice's `pattern`, element refs, fields,
-and the joined doc metadata (`slice.doc.status`, `version`, `driftSignal`).
+pattern shape. For machine-readable facts, use `em export <model>.em --slice <slice-key>`
+rather than parsing the DSL or the doc's frontmatter yourself: it returns just this slice's
+object — `pattern`, element refs, fields, and the joined doc metadata (`slice.doc.status`,
+`version`, `driftSignal`) — without piping the whole model's export to find one `slice.doc`.
 
 If the project ships pattern-specific implementation skills (for example an Axon/DCB skill
 set keyed on a slice doc's `pattern:` frontmatter), route by the slice's pattern and follow
@@ -91,7 +96,9 @@ undocumented ordering, a contradiction with adjacent code. The discipline:
 
 ## 5. Definition of done
 
-- Every `INV-n` invariant has at least one test that cites its ID.
+- Every `INV-<MNEMONIC>-n` invariant has at least one test that cites its ID — checked mechanically by
+  `em coverage <model>.em --tests <dir>` (MIL-130); run it (add `--strict` in CI) rather than
+  eyeballing citations by hand.
 - Every scenario in `## Scenarios (Given / When / Then)` exists as a passing test; rejection
   scenarios assert the doc's named rejection reason.
 - Alternate/error flows (idempotency included) are covered by tests.
@@ -112,12 +119,17 @@ implementedIn: <PR or commit URL>
 This is supply-loop mechanics, not ratification — it's the one edit an implementing agent makes
 to a slice doc, and it's why `em ledger` deliberately excludes these two fields from what
 counts as content. **Do not bump `version:`** — versions bump only when a delta is ratified;
-a bump here is a ledger defect. In bridge-equipped projects,
-`npx -p em-sdd-bridge em-sdd-mark-implemented <slice-key> <pr-url>` does the flip for you.
+a bump here is a ledger defect.
+
+`em slice mark-implemented <model>.em <slice-key> <pr-url>` does the flip for you (MIL-103) —
+resolves the doc via the same note-binding join `--slice-ready` uses, is idempotent on a re-run
+with the same URL, and refuses (never silently overwrites) if the doc is already `implemented`
+with a different URL. Prefer it over hand-editing the doc's frontmatter.
 
-Then update the model's `README.md` slice index if the project keeps one, so the one canonical
-slice table reflects the new status and link. The `implementedIn` link is what the `conform`
-phase later uses to anchor drift-checking — leaving it empty blinds the loop.
+Then, if the project keeps a model README (from `templates/model-readme.md`), run
+`em slice index <model-name>.em` so its generated Slices table reflects the new status and
+link — never hand-edit that table. The `implementedIn` link is what the `conform` phase later
+uses to anchor drift-checking — leaving it empty blinds the loop.
 
 ## 7. Spec-kit projects: the SDD adapter
 
@@ -141,9 +153,9 @@ plan/tasks as FEATURE_SPEC. The rules that keep redirect mode safe:
 - `/speckit.plan` and `/speckit.tasks` may run against the slice doc directly; the preset's
   redirect preambles map spec-kit's section vocabulary onto the slice doc's sections.
 - **Emission fallback**: where redirect can't work (Windows checkouts without symlink
-  privileges, two-doc pattern-pair bundles, a toolchain that mutates its spec files), run the
-  bridge without `--symlink` to render `spec.md` from the slice doc. The generated file is a
-  rendering — never hand-edit it; regenerate it from the slice doc instead.
+  privileges, a toolchain that mutates its spec files), run the bridge without `--symlink` to
+  render `spec.md` from the slice doc. The generated file is a rendering — never hand-edit it;
+  regenerate it from the slice doc instead.
 - Everything under `specs/NNN-*/` is an **ephemeral work container** — one per change effort,
   discardable; the PR is the durable record of the effort, the slice doc the durable
   definition of the behavior.

package/.claude/skills/event-modeling/templates/model-readme.md

@@ -10,8 +10,9 @@ em watch {{model-name}}.em -o {{model-name}}.svg --serve   # re-render + instant
 # then open the URL it prints (http://localhost:5173/?svg={{model-name}}.svg) and share the screen
 ```
 
-No server? Run `em watch {{model-name}}.em -o {{model-name}}.svg` and open
-`live.html?svg={{model-name}}.svg` in a browser (polls ~2s; share the screen).
+Pan/zoom to navigate the diagram (drag, scroll; **Fit** resets), and click **Review mode** in
+the header for a slice-by-slice walkthrough. If a save fails to render, the viewer keeps the
+last good diagram and shows an error banner until the next successful load.
 
 Static render: `em render {{model-name}}.em -o {{model-name}}.svg`
 
@@ -32,11 +33,13 @@ never connected to one another.
 
 ## Slices
 <!-- The canonical slice index — the ONE place slices are enumerated (the state file
-     points here rather than keeping its own copy). Keep it in sync as slice docs are
-     written and as statuses move. -->
+     points here rather than keeping its own copy). Generated — run
+     `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 |
 |---|-------|---------|--------|----------------|------------|
-| 1 | {{Slice Name}} | {{Pattern}} | {{no doc yet / draft / reviewed / ready-to-implement / implemented}} | {{PR/commit link once implemented, else —}} | [slices/{{slice-name}}.md](slices/{{slice-name}}.md) |
+<!-- GENERATED:slices:end -->
 
 ## Status
 See [`.event-modeling.md`](.event-modeling.md) for current phase, decisions, and open questions.

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

@@ -29,6 +29,12 @@ The three lineage keys only apply when this doc was produced by a split, merge,
 delete them otherwise; most slices never carry them. Grammar: `<slice-key>@v<N>`, where
 `<slice-key>` is the referenced slice's kebab-case filename stem.
 
+`covers` only applies when this doc is also the ratified doc for a DIFFERENT slice — typically
+the bare `view` half of the two-slice Automation/Translation shape, which has nothing of its own
+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.
+
 Full machine schema — required-vs-optional keys per `status`, value types/enums, the
 unknown-key policy — is documented in docs/slice-doc-schema.md.
 
@@ -49,6 +55,10 @@ implementedIn: {{PR/commit link — fill in once status is `implemented`}}
 # split-from: <slice-key>@v<N>
 # merged-from: <slice-key>@v<N>, <slice-key>@v<N>
 # superseded-by: <slice-key>@v<N>, <slice-key>@v<N>
+# Cross-slice coverage — only when this doc also covers another slice with no doc of its own
+# (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>
 ---
 # Slice: {{Slice Name}}
 
@@ -68,7 +78,7 @@ implementedIn: {{PR/commit link — fill in once status is `implemented`}}
 **v{{X}} → v{{Y}}, ratified {{date}}** — {{one-line summary of the ratified change}}
 
 ### Added
-#### Requirement: {{title}} ({{stable ID, e.g. an INV-n from Invariants below}})
+#### 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** {{...}}
@@ -132,15 +142,19 @@ an event directly.}}
 - **Freshness / consistency expectation:** {{real-time | eventual | on-demand}}
 
 ## Invariants / Business Rules
-<!-- What must ALWAYS hold. Give each a stable ID so tests and code can reference it. -->
-- **INV-1:** {{rule that the command enforces; violation ⇒ rejection}}
-- **INV-2:** {{...}}
+<!-- What must ALWAYS hold. Give each a stable ID so tests and code can reference it:
+     `INV-<MNEMONIC>-<n>`, where `<MNEMONIC>` is a short (2-4 letter/digit), slice-unique
+     abbreviation of this slice's key (e.g. slice `checkout` -> `INV-CHK-1`) — see
+     docs/slice-doc-schema.md. Add a letter suffix for a closely-related sub-invariant
+     (`INV-CHK-3a`). -->
+- **INV-{{MNEMONIC}}-1:** {{rule that the command enforces; violation ⇒ rejection}}
+- **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-1)** — Given {{state}}, When {{command}}, Then {{rejected with reason}}; no event.
+- **Rejected (INV-{{MNEMONIC}}-1)** — Given {{state}}, When {{command}}, Then {{rejected with reason}}; no event.
 - **{{Edge case}}** — Given {{...}}, When {{...}}, Then {{...}}.
 
 ## Alternate & Error Flows

package/README.md

@@ -7,7 +7,9 @@ AI to write and edit as it is for a person, and `em validate` keeps either one h
 
 ![An order-fulfillment event model rendered by em](https://raw.githubusercontent.com/milehimikey/em/main/examples/order-fulfillment.svg)
 
-The source for that diagram is [about 70 lines of text](examples/order-fulfillment.em).
+The source for that diagram is [about 70 lines of text](examples/order-fulfillment.em) — or
+see it as a [full project](examples/order-fulfillment/), slice docs and all, for a guided
+tour of the rest of the toolchain.
 
 ## Install
 
@@ -15,9 +17,9 @@ The source for that diagram is [about 70 lines of text](examples/order-fulfillme
 npm install -g @milehimikey/em
 ```
 
-Requires Node ≥ 18. SVG and PNG rendering are fully self-contained (Graphviz runs as
-bundled WebAssembly); nothing else to install. PDF is optional — see
-[docs/dependencies.md](docs/dependencies.md).
+Requires Node ≥ 18. SVG, PNG, and PDF rendering are all fully self-contained (Graphviz runs
+as bundled WebAssembly); nothing else to install. Only rarer formats (ps, eps, ...) need an
+optional system dependency — see [docs/dependencies.md](docs/dependencies.md).
 
 ## Quickstart
 

package/dist/catalog/docJoin.d.ts

@@ -1,7 +1,29 @@
 import { Slice } from "../model/model.js";
 import { Diagnostic } from "../model/validate.js";
 import { DriftSignalKind } from "./driftSignal.js";
-import { SliceRef } from "./sliceDoc.js";
+import { SliceDoc, SliceRef } from "./sliceDoc.js";
+export declare const NOTE_SLICE_PATH: RegExp;
+/** One cross-binding candidate's resolution against `sliceKey`'s ratification requirement:
+ *  the target file doesn't exist, exists but its frontmatter isn't usable, exists and is usable
+ *  but doesn't list `sliceKey` in its `covers:` (doesn't carry the `doc` — nothing downstream
+ *  needs it), or ratifies (does carry `doc`, the parse the caller needs next). */
+export type CrossCandidateResolution = {
+    status: "missing";
+} | {
+    status: "unusable";
+} | {
+    status: "unratified";
+} | {
+    status: "ratified";
+    doc: SliceDoc;
+};
+/**
+ * Resolves a single `slices/<candidateKey>.md` cross-binding candidate — the exact ratification
+ * predicate `resolveSliceDocJoin`'s cross-binding search (MIL-121) applies, extracted so
+ * `noteBindingValidate.ts` (MIL-126) can classify a *non*-winning candidate's reason without
+ * re-deriving what "ratifies" means. One source of truth for both.
+ */
+export declare function resolveCrossCandidate(baseDir: string, candidateKey: string, sliceKey: string): CrossCandidateResolution;
 export type DocReason = "no-doc-bound" | "binding-missing-file" | "frontmatter-invalid" | null;
 /** A slice's export-facing doc join — always a non-null object (never JSON `null`), matching
  *  every other optional field in `em export`'s style: explicit-null-on-a-stable-key, never a
@@ -9,8 +31,11 @@ export type DocReason = "no-doc-bound" | "binding-missing-file" | "frontmatter-i
  *  cleanly; otherwise it names which of the three broken states applies. */
 export interface SliceDocExport {
     found: boolean;
-    /** The conventional path (`slices/<sliceKey>.md`), always present regardless of `found` —
-     *  the path a doc would need to exist at, and (when `found`) the path it was read from. */
+    /** The bound doc's path — the conventional `slices/<sliceKey>.md` for the ordinary canonical
+     *  binding, or (MIL-121) a different slice's canonical path when this slice's doc join
+     *  resolved to a ratified cross-binding instead. Always present regardless of `found` — when
+     *  nothing is bound (or bound-but-unratified), it's still the conventional path this slice's
+     *  own doc would need to exist at. */
     path: string;
     reason: DocReason;
     status: string | null;