@milehimikey/em 1.7.2 → 1.8.0

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling
-em-version: 1.7.2
+em-version: 1.8.0
 description: >-
   Use when the user wants to event-model a business process or system: building, editing,
   updating, or maintaining a model — extending or detailing an existing one into slices,
@@ -77,21 +77,23 @@ vendored alongside this skill.
   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 append one line to
-  the Usage log: the phase(s) touched and the `em validate` diagnostic *categories* that fired
-  (the exact fixed strings from `docs/usage-data.md`, e.g. "read model has no consumer" —
-  never the full message or domain content). This is the team's only usage signal today (`docs/usage-data.md`) — keep it cheap
-  and habitual, not a task to skip.
+  the Usage log: the phase(s) touched and the diagnostic *categories* that fired — run `em
+  validate <model>.em --json` and dedupe each diagnostic's `usageCategory` field directly
+  (never the full message or domain content). This is the team's only usage signal today
+  (`docs/usage-data.md`) — keep it cheap and habitual, not a task to skip.
 
 ## Preconditions (run first)
 
 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 a `models/` subfolder). If found, read the state file. If not, and the phase
-   needs one, ask the user for the model name and where to create it.
-3. Parse the argument (`$ARGUMENTS`) to pick the phase below. With **no argument**, read the
-   state file and resume the recorded phase/step; if no model exists, propose starting `discover`
-   (greenfield) or `extract` (modeling an existing system).
+   directory (or a `models/` subfolder). 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.
+3. Parse the argument (`$ARGUMENTS`) to pick the phase below. With **no argument**, use
+   `em state read <dir>`'s `phase`/`step` to resume the recorded phase/step; if no model exists,
+   propose starting `discover` (greenfield) or `extract` (modeling an existing system).
 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.
@@ -102,7 +104,6 @@ vendored alongside this skill.
 <model-name>/
   <model-name>.em          # the model (slice docs linked via note "...")
   <model-name>.svg         # render target for em watch
-  live.html                # file:// auto-refresh viewer (copy of templates/live.html, verbatim)
   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)
@@ -111,14 +112,19 @@ vendored alongside this skill.
   <model-name>-asis.em     # conform-phase scratch model, regenerated per run — git-ignore this
 ```
 
-When creating a new model, scaffold the directory and copy the templates in (filling the
-placeholders). Copy `live.html` **verbatim** — it takes the SVG name from its URL query
-(`live.html?svg=<model-name>.svg`), so there's nothing to edit. You may use `em init` for a
-starter `.em`, but usually you'll build it up from the discovery conversation instead. Fill
-template placeholders — never leave `{{...}}` in delivered files. The `conformance/` directory
-and `<model-name>-asis.em` only appear once the `conform` phase runs; add the pattern `*-asis.em`
-to the repository's `.gitignore` the first time one is created (see `reference/conform.md`) —
-it's scratch, never committed.
+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 below. 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
+`reference/conform.md`) — it's scratch, never committed.
 
 ---
 
@@ -160,8 +166,10 @@ phase applies to field tables, below.
    both are worth raising with the user rather than leaving dangling.
 
 End of phase: write/refresh the `.em`, render it, update `.event-modeling.md` (steps done,
-decisions, open questions) and `README.md`'s slice index. Tell the user they can stop here and
-resume with `/event-modeling model`.
+decisions, open questions — run `em state set-phase model` rather than hand-editing `Current
+phase:`), and run `em slice index <model-name>.em` to seed `README.md`'s Slices table (every
+slice already reads "no doc yet" — no slice docs exist until the `slice` phase writes them).
+Tell the user they can stop here and resume with `/event-modeling model`.
 
 ## Phase: `extract` — current-state model of an existing system
 
@@ -181,8 +189,9 @@ state).
 - **Current-state-only:** park unknowns as `# TBD` comments in the `.em`, mirrored in the state
   file's Open Questions — never guess intended design.
 
-End of phase: validated as-is model; state file updated (source mode, rounds, decisions) and
-`README.md`'s slice index seeded; then chain to `/event-modeling model` (steps 5-7).
+End of phase: validated as-is model; state file updated (source mode, rounds, decisions; `em
+state set-phase model` for `Current phase:`); run `em slice index <model-name>.em` to seed
+`README.md`'s Slices table; then chain to `/event-modeling model` (steps 5-7).
 
 ## Phase: `model` — steps 5-7
 
@@ -211,12 +220,14 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    this fact and what they do with it. The honest answers are "here's the read model we missed" or
    "nobody — so why are we recording it", and both improve the model.
 
-End of phase: render, update state, suggest `/event-modeling slice` to write implementation specs.
+End of phase: render, update state (`em state set-phase slice`), suggest `/event-modeling slice`
+to write implementation specs.
 
 ## Phase: `slice` — deep slice documents
 
 Goal: implementation-ready specs. Go slice by slice (let the user pick order, or follow the
-timeline). Check `README.md`'s slice index for what's already done.
+timeline). Check `README.md`'s Slices table for what's already done (run `em slice index
+<model-name>.em` first if it looks stale).
 
 This is also where **branch / unhappy-path events** are discovered and added to the model — as a
 slice's alternate/error flows surface (a rejection, removal, cancellation, decline, expiry), add
@@ -245,27 +256,36 @@ For each slice:
    adjacent real sources (OpenAPI specs, DB migrations, existing DTOs/event classes in sibling
    contexts) before finalizing field names/types or invariants — don't guess a shape that's
    already defined elsewhere.
-2. Write the doc to `slices/<slice-name>.md` (kebab-case the slice name), with the YAML
-   frontmatter block at the very top — all five of `schemaVersion`/`pattern`/`swimlane`/
-   `status`/`version` (kebab-case `pattern` value, `schemaVersion: 1`, `version` starting at
-   `1`; omitting any of the five makes the doc `frontmatter-invalid` to `em export` and the
-   readiness gate), plus `implementedIn` once shipped — the canonical, machine-read
-   metadata dialect (`- **Status:** ...` bullet lines are legacy/accepted input only; never
-   write new docs that way). When this doc exists because of a split, merge, or rename, add the
-   matching lineage key(s) too (`split-from`/`merged-from`/`superseded-by`, `<slice-key>@v<N>`
-   grammar — see `docs/slice-doc-schema.md` for the full schema). On a re-ratification (step 0),
-   bump `version` and flip `status` here instead of setting them fresh. Record the originating
-   need (ticket/conversation link) in the Intent section when one exists.
+2. **First-time authoring:** scaffold the doc mechanically rather than hand-writing the
+   frontmatter — `em slice new "<slice name>" --pattern <state-change|state-view|automation|
+   translation> --swimlane "<Persona> → <Context>"` writes `slices/<slice-name>.md`
+   (kebab-cased to match, via the same slugging `em` uses everywhere else) with the canonical
+   `schemaVersion`/`pattern`/`swimlane`/`status: draft`/`version: 1` frontmatter — exactly the
+   five keys `em export` and the readiness gate require, no more — and the `# Slice:` heading +
+   diagram-image stub already in place. Both `--pattern` and `--swimlane` are required; an
+   invalid `--pattern` is refused with the valid choices listed. Never hand-type this block, and
+   never fall back to a placeholder pattern/swimlane to dodge the flags. Then fill in every
+   judgment section below the stub from step 1 (Intent, Command, Event(s), Invariants,
+   Scenarios, ...) — the doc's prose is still entirely hand-authored, only the frontmatter/
+   heading scaffold is mechanized. Record the originating need (ticket/conversation link) in the
+   Intent section when one exists. When this doc exists because of a split, merge, or rename,
+   add the matching lineage key(s) by hand (`split-from`/`merged-from`/`superseded-by`,
+   `<slice-key>@v<N>` grammar — see `docs/slice-doc-schema.md` for the full schema).
+   **Re-ratification (step 0):** the doc already exists, so `em slice new` doesn't apply here
+   (it refuses to overwrite an existing file without `--force`, and forcing would blow away the
+   doc's authored body) — bump `version` and flip `status` back to `ready-to-implement` by hand
+   in the existing frontmatter instead.
 3. Render the slice's own diagram: `em render <model>.em --slice "<slice name>" -o
-   slices/<slice-name>.svg` (kebab-case, matching the doc's filename) — redraws just this slice
-   in its own canonical pattern shape, and add `![Diagram](./<slice-name>.svg)` near the top of
-   the doc, right after the `# Slice:` heading (below the frontmatter block).
-4. Wire it into the `.em`: add `note "slices/<slice-name>.md"` to the slice's primary element
-   (the command for State Change, the view for State View, the processor for Automation, the
-   translation for Translation).
-5. Update `README.md`'s slice index — the one canonical slice table (`draft` → `reviewed` →
-   `ready-to-implement`, later `implemented` once shipped, with its Implemented-in link
-   filled in).
+   slices/<slice-name>.svg` (kebab-case, matching the doc's filename and the `![Diagram]` stub
+   `em slice new` already wrote) — redraws just this slice in its own canonical pattern shape.
+4. Wire it into the `.em`: `em slice new` (step 2) printed the exact `note
+   "slices/<slice-name>.md"` line to add to the slice's primary element (the command for State
+   Change, the view for State View, the processor for Automation, the translation for
+   Translation) — `em slice new` only writes the new doc file, never edits the `.em` source
+   itself, so add that line by hand.
+5. Run `em slice index <model-name>.em` to regenerate `README.md`'s Slices table — the one
+   canonical slice index — from the model and the doc frontmatter you just wrote (status,
+   `implementedIn` once shipped). Never hand-edit the table; it's a generated block.
 6. Re-render and `em validate`.
 
 When a slice is **ratified** — a human flips its `status` to `ready-to-implement` with every
@@ -282,13 +302,14 @@ where the agent builds rather than facilitates.
 contract.** In short: gate on `em validate <model>.em --slice-ready <key>` (stop and hand
 back if it fails — never edit the doc to make the gate pass); treat the slice doc as the
 spec (read-only, except the merge-time `status`/`implementedIn` flip); surface every gap to
-the user instead of deciding it silently; cover every INV-n and every scenario with tests;
+the user instead of deciding it silently; cover every INV-<MNEMONIC>-n and every scenario with tests;
 in spec-kit projects, allocate via em-sdd-bridge (redirect mode) and never run
 `/speckit.specify`.
 
 End of phase: PR merged, slice doc flipped to `status: implemented` with `implementedIn`
-filled, `README.md`'s slice index updated. Implement doesn't chain to another phase — run it
-once per ratified slice; `conform` later checks the result against the model.
+filled, `em slice index <model-name>.em` run to refresh `README.md`'s Slices table. Implement
+doesn't chain to another phase — run it once per ratified slice; `conform` later checks the
+result against the model.
 
 ## Phase: `conform` — drift check against the codebase
 
@@ -300,31 +321,35 @@ and report where they've drifted — advisory only, never a gate, never an unpro
 stance guardrails (evidence-first, uncertainty is never drift, propose-don't-edit). It reuses
 `extract`'s sourcing/mode rules for reading the target codebase rather than duplicating them.
 
-In short: for each in-scope slice, gather code evidence *before* comparing to the model or doc;
-write the as-is picture into a scratch model (`<model-name>-asis.em`, reusing the canonical
-model's names wherever the code matches them); run `em diff <model-name>.em
+In short: run `em conform-scope <model-name>.em --repo <target-repo-path> --seed-asis` to
+compute the in-scope slice set (diff-scoped by default, via `Last conformance:` + the target
+repo's changed paths mapped through each slice doc's `implementedIn:`) and seed the scratch
+model in one step; for each in-scope slice, gather code evidence *before* comparing to the model
+or doc; write the as-is picture into that scratch model (`<model-name>-asis.em`, reusing the
+canonical model's names wherever the code matches them); run `em diff <model-name>.em
 <model-name>-asis.em --json` and let `em` decide the structural deltas; classify every finding
 (real drift / model gap / internal inconsistency / uncertainty) with cited evidence; write
 `conformance/<date>-report.md` with proposed `issue "conformance: …"` red notes; apply only the
-proposals the user ratifies, then re-render and validate; update the state file's
-`Last conformance:` marker.
+proposals the user ratifies, then re-render and validate; run `em state set-conformance
+<revision> --report <path>` to update the state file's `Last conformance:` marker.
 
-End of phase: state file's `Last conformance:` marker updated, Decisions log entry if any
+End of phase: state file's `Last conformance:` marker updated (via `em state set-conformance`),
+Decisions log entry if any
 proposals were applied. Conform doesn't chain to another phase — it's a recurring loop, run
 again whenever the codebase has moved.
 
 ## Phase: `watch` — live team view
 
-**Recommended (instant push, no polling):** start the watcher with `--serve` in the background:
+Start the watcher with `--serve` in the background:
 `em watch <model-name>.em -o <model-name>.svg --serve` (run_in_background). It re-renders on every
 save and pushes an instant reload to the browser over Server-Sent Events. Tell the user to open the
 URL it prints (e.g. `http://localhost:5173/?svg=<model-name>.svg`) and share their screen — updates
-appear the moment you save, with no idle churn between edits.
+appear the moment you save, with no polling and no idle churn between edits.
 
-**No-server fallback (`file://`):** if the user prefers not to run a server, start the plain watcher
-`em watch <model-name>.em -o <model-name>.svg` (run_in_background) and have them open the copied
-`live.html?svg=<model-name>.svg` in a browser. It polls every ~2s and reloads without flicker. No
-editing of `live.html` is needed — the `?svg=` query picks the model.
+The viewer navigates like a map — drag to pan, scroll/pinch to zoom, **Fit** to reset — and its
+**Review mode** steps through slices one at a time (see the `review` phase). A save that fails to
+render never blanks the shared screen: the last good diagram stays up, an error banner explains
+what went wrong, and the viewer recovers on its own at the next successful render.
 
 ## Phase: `review` — stakeholder walkthrough
 
@@ -349,8 +374,8 @@ losing the current slice or resetting review mode.
 
 Wrap-up: run `em validate --list-issues` to sweep everything captured during the session and
 walk each one with the user, same as any open issue. Update the state file's Participants
-section with who attended, and set a `Last stakeholder review:` marker (mirrors `Last
-conformance:`).
+section with who attended, and run `em state set-review <date>` to set the `Last stakeholder
+review:` marker (mirrors `Last conformance:`).
 
 End of phase: state file's `Last stakeholder review:` marker updated, every issue captured
 live triaged (resolved on the spot, moved to Open questions / parking lot, or left open on
@@ -393,16 +418,18 @@ command instead.
 ```bash
 em --version
 em init <name>.em                          # optional starter scaffold
+em scaffold <name>                         # full project: <slug>/<slug>.em, README.md, .event-modeling.md
 em validate <name>.em                      # check rules; exit 0 if clean/warnings only
 em render <name>.em -o <name>.svg          # render (svg/png/pdf by extension)
 em render <name>.em --emit-dot             # inspect generated Graphviz DOT
 em render <name>.em --slice "<slice-name>" -o slices/<slug>.svg   # this slice's own diagram
 em watch <name>.em -o <name>.svg           # re-render on save (run in background)
-em watch <name>.em -o <name>.svg --serve   # + live viewer with instant push-reload (--port N)
+em watch <name>.em -o <name>.svg --serve   # + the live browser viewer: instant push-reload, pan/zoom (--port N)
                                             #   click "Review mode" for a slice-by-slice storyboard walkthrough
 ```
 <!-- GENERATED:cli-quick:end -->
 
 Always finish a working session by: re-rendering, running `em validate`, and updating
-`.event-modeling.md` with the current phase/step, decisions, open questions, and a Usage log
-entry (phases touched + validate diagnostic categories hit).
+`.event-modeling.md` — `em state set-phase <phase> [--step <n>]` for the current phase/step,
+decisions and open questions by hand, and a Usage log entry (phases touched + validate
+diagnostic categories hit).

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

@@ -72,12 +72,34 @@ authoritative.
 
 ### 1. Scope
 
-Default: **diff-scoped.** Read the state file's `Last conformance:` marker (date + target-repo
-revision). If it's set, run `git diff --name-only <recorded-revision>..HEAD` from the target
-repo's root to list the changed paths (`git log` alone prints commit subjects, not paths), then
-map those paths to slices (via each slice doc's known code locations, `implementedIn:` links,
-or a quick Grep if those are stale) — that's your in-scope set. If the marker reads `never`
-(first run) or the user passes `--full`, scope is every `implemented` slice.
+Run `em conform-scope <model-name>.em --repo <target-repo-path>` — it mechanizes everything
+about scoping that's deterministic: parsing `Last conformance:` (via the same state-file reader
+`em state read` uses), running `git diff --name-only <revision>..HEAD` in the target repo, and
+mapping each changed path to a slice via that slice doc's `implementedIn:` link (a bare/embedded
+repo-relative path that's a prefix of or equal to the changed path — a URL-only `implementedIn`,
+e.g. a PR link, deterministically matches nothing). It prints one JSON document
+(`docs/cli.md`'s conform-scope section documents the envelope):
+
+```json
+{ "lastConformance": { "date": "...", "revision": "..." } | null,
+  "changedPaths": ["..."],
+  "candidateSlices": [ { "key": "checkout", "matchedBy": "implementedIn", "paths": ["..."] } ],
+  "unmappedPaths": ["..."] }
+```
+
+Default: **diff-scoped** — `lastConformance` set, `--full` not passed — `candidateSlices` is
+your in-scope set for step 2. If `lastConformance` is `null` (first run) or you pass `--full`,
+`em conform-scope` scopes every `implemented` slice instead (`matchedBy: "full"`,
+`changedPaths`/`unmappedPaths` both empty) — the tool makes this call for you, no need to
+special-case it yourself.
+
+**`unmappedPaths` is your judgment queue, not a dead end.** A changed path the tool couldn't
+place mechanically (`implementedIn` stale, a URL-only link, code that moved) still might belong
+to an in-scope slice — a quick Grep for the path's obvious symbols against the slice docs/model
+vocabulary is exactly the judgment call this phase reserves for you (`em conform-scope` never
+guesses on purpose). Fold anything you place this way into your in-scope set alongside
+`candidateSlices`; leave genuinely unplaceable paths out of scope but note them in the report's
+run metadata rather than silently dropping them.
 
 Cost containment here is cadence, not a trigger condition — diff-scoped-by-default is what
 keeps a recurring conform run cheap; don't invent a smarter trigger.
@@ -125,9 +147,11 @@ For each slice in scope:
      without-link"` (status: implemented, no link at all) is a genuine coherence problem, but
      it's already surfaced by `em validate`'s `frontmatter-coherence-implemented-without-link`
      warning — don't re-raise it here as a separate conform finding.
-3. Write what you found into the scratch model (`<model-name>-asis.em`, see below). **Seed the
-   scratch model as a copy of the canonical `.em` and replace only the in-scope slices** with
-   the as-is picture, leaving out-of-scope slices byte-identical. This is not an optimization:
+3. Write what you found into the scratch model (`<model-name>-asis.em`, see below) — start it
+   with `em conform-scope <model-name>.em --repo <target-repo-path> --seed-asis`, which
+   byte-copies the canonical `.em` to `<model-name>-asis.em` and ensures `*-asis.em` is
+   gitignored (idempotent — safe to pass on every run). **Then replace only the in-scope
+   slices** with the as-is picture, leaving out-of-scope slices byte-identical. This is not an optimization:
    `em diff` matches slices by name, so a scratch model containing *only* the in-scope slices
    reports every other canonical slice as `slice-removed` plus one `element-removed` per
    element — a phantom-removal flood on every diff-scoped run, which is the exact false drift
@@ -215,26 +239,27 @@ stays auditable) but don't ask the user to ratify what's already ratified. **You
 canonical model or a slice doc unprompted** — walk the report with the user, apply only the
 proposals they approve, then re-render and `em validate`.
 
-End of run: update the state file's `Last conformance:` marker, exact format:
+End of run: update the state file's `Last conformance:` marker with
 
 ```
-- **Last conformance:** YYYY-MM-DD @ <target-repo revision> — report: conformance/YYYY-MM-DD-report.md
+em state set-conformance <target-repo revision> --report conformance/YYYY-MM-DD-report.md
 ```
 
-The revision is the one you just diffed against, so the next run's scope starts from here —
-step 1 parses this line, so keep the format exact. **The marker only advances with the human
-in the loop**: in an interactive session, update it after walking the report with the user; a
-headless/scheduled run writes the report but never the marker (nobody ratified the outcome),
-so the next run re-walks the same span — see `docs/ci.md`. If any proposals were ratified and
-applied, log a Decisions entry noting what changed and why.
+— the revision is the one you just diffed against, so the next run's scope starts from here.
+The command writes the exact format step 1 parses back out; never hand-edit the bullet.
+**The marker only advances with the human in the loop**: in an interactive session, run it
+after walking the report with the user; a headless/scheduled run writes the report but never
+the marker (nobody ratified the outcome), so the next run re-walks the same span — see
+`docs/ci.md`. If any proposals were ratified and applied, log a Decisions entry noting what
+changed and why.
 
 ## Conventions
 
 - **Scratch model:** `<model-name>-asis.em`, written **next to** the canonical model (same
   directory as `.event-modeling.md`). Always seeded as a copy of the canonical model with only
-  the in-scope slices rewritten (step 2), never built up from nothing. It's regenerated every
-  conform run — add the pattern `*-asis.em` to the repository's `.gitignore` (create the entry
-  if there isn't one) so it never gets committed.
+  the in-scope slices rewritten (step 2) — `em conform-scope --seed-asis` does the seeding and
+  the gitignoring (`*-asis.em`, idempotent) mechanically, never built up from nothing and never
+  hand-maintained. It's regenerated every conform run.
 - **Report location:** `conformance/<YYYY-MM-DD>-report.md` in the model directory. One file
   per run; don't overwrite a prior date's report.
 - **Red note wording:** `issue "conformance: <what's wrong, plainly>"` — plain enough that