@milehimikey/em 1.2.0 → 1.4.0

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

@@ -5,11 +5,13 @@ description: >-
   the 7 steps of Event Modeling and the 4 patterns (State Change, State View, Automation,
   Translation), and produce implementation-ready slice design documents. Use when the user wants
   to event-model a business process or system, do event modeling / event storming, design slices,
-  build or edit an `.em` model, run the em tool, or extract / reverse-engineer a current-state
-  event model from an existing system or codebase (event-driven or legacy/procedural). Works in
-  resumable phases via an argument: `discover` (steps 1-4, greenfield), `extract` (current-state
-  model of an existing system), `model` (steps 5-7), `slice` (deep slice specs), plus `watch` and
-  `validate`. With no argument it resumes from the saved state file.
+  build or edit an `.em` model, run the em tool, extract / reverse-engineer a current-state
+  event model from an existing system or codebase (event-driven or legacy/procedural), or check
+  a ratified model for drift against the codebase that implements it. Works in resumable phases
+  via an argument: `discover` (steps 1-4, greenfield), `extract` (current-state model of an
+  existing system), `model` (steps 5-7), `slice` (deep slice specs), `conform` (drift check
+  against the codebase), plus `watch` and `validate`. With no argument it resumes from the saved
+  state file.
 ---
 
 # Event Modeling with `em`
@@ -28,7 +30,8 @@ validation rules) before doing real work — they are the source of truth. Templ
   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.
+  `.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
@@ -63,6 +66,9 @@ validation rules) before doing real work — they are the source of truth. Templ
 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).
+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 this skill creates
 
@@ -74,13 +80,19 @@ validation rules) before doing real work — they are the source of truth. Templ
   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, 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.
+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.
 
 ---
 
@@ -88,6 +100,10 @@ template placeholders — never leave `{{...}}` in delivered files.
 
 Goal: a draft model of events, storyboard, commands, and views. Loose is OK; structure comes next.
 **Existing system?** Use `extract` instead (next section) — discover is for greenfield modeling.
+**New feature inside an existing codebase?** Stay in `discover`, but before locking in
+command/event names, Grep/Read adjacent real sources (OpenAPI specs, DB migrations, existing
+DTOs/event classes in sibling contexts) rather than guessing conventions — same check `slice`
+phase applies to field tables, below.
 
 1. **Brainstorm events (step 1).** Ask the user to name everything that happens, as past-tense
    facts. Probe for missed state changes. For each candidate, apply the **"is it an event?"
@@ -109,8 +125,8 @@ Goal: a draft model of events, storyboard, commands, and views. Loose is OK; str
    `reference/methodology.md`).
 
 End of phase: write/refresh the `.em`, render it, update `.event-modeling.md` (steps done,
-decisions, open questions, slice inventory). Tell the user they can stop here and resume with
-`/event-modeling model`.
+decisions, open questions) and `README.md`'s slice index. Tell the user they can stop here and
+resume with `/event-modeling model`.
 
 ## Phase: `extract` — current-state model of an existing system
 
@@ -130,8 +146,8 @@ 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, slice
-inventory); then chain to `/event-modeling model` (steps 5-7).
+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).
 
 ## Phase: `model` — steps 5-7
 
@@ -160,7 +176,7 @@ End of phase: render, update state, suggest `/event-modeling slice` to write imp
 ## Phase: `slice` — deep slice documents
 
 Goal: implementation-ready specs. Go slice by slice (let the user pick order, or follow the
-timeline). Check the state file's slice inventory for what's already done.
+timeline). Check `README.md`'s slice index for what's already done.
 
 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
@@ -171,15 +187,44 @@ For each slice:
 1. Hold a Socratic deep-dive to fill every section of `templates/slice.md`: intent, trigger/actor,
    command + field table (types & rules), event(s) + payload (mark immutable facts), invariants
    (give each a stable ID), Given/When/Then scenarios (happy path + rule boundaries + edge cases),
-   alternate/error flows (retries, idempotency, compensations), read models affected, open
-   questions. Park anything unresolved rather than guessing.
-2. Write the doc to `slices/<slice-name>.md` (kebab-case the slice name).
+   alternate/error flows (retries, idempotency, compensations), non-functional requirements
+   (security/authz, PII/compliance, performance/SLA), read models affected, open questions. Park
+   anything unresolved rather than guessing. If the slice lives in an existing codebase, Grep/Read
+   adjacent real sources (OpenAPI specs, DB migrations, existing DTOs/event classes in sibling
+   contexts) before finalizing field names/types or invariants — don't guess a shape that's
+   already defined elsewhere.
+2. Write the doc to `slices/<slice-name>.md` (kebab-case the slice name). Record the originating
+   need (ticket/conversation link) in the Intent section when one exists.
 3. 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).
-4. Update `README.md`'s slice index and the state file's slice inventory (`draft` → `ready-to-implement`).
+4. Update `README.md`'s slice index — the one canonical slice table (`draft` →
+   `ready-to-implement`, later `implemented` once shipped, with `Implemented in:` filled in).
 5. Re-render and `em validate`.
 
+## Phase: `conform` — drift check against the codebase
+
+Goal: check a **ratified** model (and its slice docs) against the codebase that implements it,
+and report where they've drifted — advisory only, never a gate, never an unprompted edit.
+
+**Read `reference/conform.md` before doing any conform work** — it carries the full flow
+(scope, evidence-first verification, `em diff --json`, classification, report) and the
+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
+<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.
+
+End of phase: state file's `Last conformance:` marker updated, 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:
@@ -199,6 +244,11 @@ Run `em validate <model-name>.em` and walk through each diagnostic with the user
 rule (see `reference/em-dsl.md`) and proposing the fix (e.g. split an automation's command into
 the next slice, add a missing `from`, give a command its event). Apply fixes on agreement.
 
+For anything genuinely unresolved rather than a rule violation, prefer `issue "text"` on the
+relevant element over a `# TBD` comment — it shows up as a red marker on the rendered diagram and
+`em validate` tracks it as an open-issue warning, so it isn't lost once rendered. `em validate
+--list-issues` gives a quick sweep of everything still open.
+
 Then do one check `em validate` can't: scan every `translation`/`processor`/`automation` slice and
 confirm none contains an `event` — each reaction must trigger a `command` in the next slice
 (`reaction → command → event`). If you find a reaction wired straight to an event, split it into

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

@@ -0,0 +1,228 @@
+# Conform Phase — Drift Detection Against the Codebase
+
+Read this **before doing any conform work**. It governs the `conform` phase: checking a
+**ratified** model (and its slice docs) against the codebase that is supposed to implement it,
+and reporting where they've drifted apart. Conform reuses `extract`'s sourcing/mode rules
+(`reference/extract.md`) for reading the target codebase rather than duplicating them — the
+difference is what you do with what you find: extract *builds* a model from the code; conform
+*compares* code evidence against a model that already exists.
+
+## Stance — advisory-only, evidence-first
+
+- **Advisory-only.** Conform never gates anything and never edits the canonical model or a
+  slice doc on its own initiative. It proposes; the user ratifies. There is no such thing as
+  an auto-applied conformance fix.
+- **Evidence-first, not model-first.** For every slice you check, gather code evidence —
+  handler/event/projection/endpoint sites, invariant-enforcement sites, scenario-test sites —
+  **before** you compare anything to the model or doc. Read the doc and model first to know
+  *what to look for*, but write down what the code actually shows before you judge whether it
+  matches. Anchoring bias is the failure mode this rule exists to block: "the model says X" is
+  never allowed to substitute for "the code shows X at `path/to/File.kt:42`".
+- **Uncertainty is never drift.** If you can't find evidence either way — the code path is
+  unclear, the test is ambiguous, you ran out of budget — that's an **uncertainty**, reported
+  in its own section, never folded into a drift or gap finding. A false positive here is worse
+  than a missed one; it's what burns the loop's credibility.
+- **Anchored, not blind.** You read the canonical model's vocabulary before walking the code,
+  and you reuse its slice/element names wherever the code genuinely matches them. This trades
+  some independence for precision: naming a scratch model's elements from scratch (blind
+  extraction) would report wholesale slice add/remove noise from naming alone the moment your
+  synonym for an existing element doesn't match the model's — the exact false-drift failure
+  mode this phase exists to avoid. The guardrail against anchoring bias is the evidence-first
+  rule above, not independence from the model's vocabulary.
+
+## Preconditions
+
+1. A canonical `.em` model with a state file (`.event-modeling.md`), reachable the same way the
+   SKILL.md preconditions locate it.
+2. The model should be ratified for the slices you're about to check — `slice` docs at
+   `implemented` (or the status the user says corresponds to shipped code) for whichever slices
+   are in scope. Checking a `draft` or `ready-to-implement` slice against code is a wasted walk;
+   tell the user and skip it rather than reporting "drift" against a doc nobody built to yet.
+3. The codebase to check: the state file's **Existing system refs** (populated during
+   `extract`, if this model came from one) or ask the user for the repo path if not set. Record
+   it if missing. In a headless/scheduled run with no user to ask, default to the repository
+   the model lives in (if it contains the implementation) and state that assumption in the
+   report's run metadata.
+4. Confirm `em --version` works (same check as every other phase) — you'll run `em diff`. The
+   phase needs `em diff --json`; if the flag errors as unknown, the installed `em` predates it
+   — say so and stop rather than falling back to eyeballing the two models.
+
+## The three conformance surfaces
+
+The model isn't just the `.em` — slice docs carry the detailed spec (field tables with rules,
+named invariants, Given/When/Then scenarios). Conform checks all three surfaces that can drift:
+
+| Surface | What drifts | Who checks | How |
+|---|---|---|---|
+| **Structural** — `.em` ↔ code | slices/elements/fields/flow | `em` (deterministic) | `em diff --json` on canonical vs. an as-is scratch model |
+| **Spec** — slice doc ↔ code | field rules not enforced, named invariants (`INV-*`) without enforcement/test sites, GWT scenarios without test sites | you (judgment) | per-slice evidence walk: each checkable claim in the doc mapped to a code/test site by name (`INV-CHK-4` → its enforcement site + its test) |
+| **Internal** — slice doc ↔ `.em` | the doc's header metadata (Pattern, Status) or its Command/Event/Read Model sections and field tables disagreeing with the model's own elements/fields | you (judgment, v1) | cross-check the doc's structured sections against the slice's model elements |
+
+The internal surface is deterministically checkable in principle (structured doc sections +
+`{ fields }` blocks) — promoting it to an `em validate` rule is a natural follow-up; file it as
+its own issue rather than growing this phase's scope. For now it's agent judgment, same as spec.
+
+**Internal inconsistency is its own class, not drift.** When a doc and the `.em` disagree with
+each other, neither one is "the code" — you don't know which is stale. Report it as internal
+inconsistency and let the user decide which side is right; don't guess by treating one as
+authoritative.
+
+## Flow
+
+### 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, `Implemented in:` 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.
+
+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.
+
+### 2. Anchored, evidence-first verification (per in-scope slice)
+
+For each slice in scope:
+
+1. Read the slice's **doc** (`slices/<slice-name>.md`) alongside its elements in the `.em`.
+   This tells you the vocabulary to anchor on and the claims to check — not the answer.
+2. Walk the code and **record evidence before comparing**:
+   - **Structural:** the handler, event class(es), projection(s), endpoint(s) that implement
+     this slice.
+   - **Spec:** for every named invariant (`INV-*`) in the doc, its enforcement site and its
+     test site (by name/path, both or neither — a half-found invariant is an uncertainty, not
+     a pass). Scenarios are budgeted: map Given/When/Then scenarios to individual test sites
+     when the in-scope slice count is small (roughly ≤5) or the user asks for that depth;
+     otherwise record slice-level scenario-test presence and say so in the report — per-scenario
+     mapping across a full model roughly doubles the walk. Where the doc doesn't name
+     invariants/scenarios individually, fall back to slice-level test presence (some vs. none)
+     rather than inventing IDs the doc never gave you.
+   - **Legitimate non-materialized views:** an automation's watched view may have no
+     materialized projection in code — a direct event handler with criteria-sourced state is
+     the same pattern expressed in the code idiom (extract.md's R5 reaction rules). That is
+     NOT structural drift; note the idiom in the evidence log instead of reporting the view
+     as missing.
+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:
+   `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
+   this phase exists to avoid. It also keeps the scratch model compilable (see step 3). Within
+   the slices you do rewrite, **reuse the canonical model's slice and element names wherever
+   the code genuinely matches them** — the canonical model is the vocabulary anchor. Give a
+   new name only to code behavior the model doesn't cover at all. Record the mapping decision
+   for every element you name this way (e.g. `CartItemAdded` code class ↔ `"Cart Item Added"`
+   model event) so it's auditable, not a silent judgment call. **Match the canonical model's field granularity:** declare `{ fields }`
+   in the scratch model only where the canonical model declares them (if the canonical model
+   puts fields on commands but not events, so does the scratch model — writing code-derived
+   event fields there would flood the diff with `field-added` noise). Schema claims at finer
+   granularity than the `.em` declares — e.g. event fields documented only in a slice doc's
+   table — are checked on the **spec surface** against the doc, not smuggled into the
+   structural diff.
+4. Cross-check the doc's header metadata and Command/Event/Read Model sections against the
+   slice's actual `.em` elements and fields for the internal surface — this doesn't need code
+   evidence, just doc-vs-`.em` reading. Narrative sections (Intent, Open Questions, notes)
+   count too when the contradiction is unambiguous — a stale sentence that flatly contradicts
+   the `.em` is an internal inconsistency; a vague or interpretable one is not a finding.
+
+Do this for every in-scope slice before moving on to diffing. The evidence you record here is
+what every finding in the report will cite — file paths, not vibes.
+
+### 3. Deterministic diff
+
+First `em validate <model-name>-asis.em`. `em diff` refuses when either side has validation
+*errors* (warnings are fine), so a scratch model that doesn't compile stops the run cold. The
+usual cause is a slice that depends on one you rewrote incompletely — a `view X again` whose
+first declaration you dropped, or an automation `from` a read model that no longer exists.
+Seeding from the canonical model (step 2) prevents this; if it still fails, **fix the scratch
+model and report the failure as a tooling problem in the run metadata — never as drift.** A
+model you couldn't compile is an uncertainty about your own scratch file, not a finding
+against the codebase.
+
+Then run `em diff <model-name>.em <model-name>-asis.em --json`. `em`, not you, decides what
+structurally differs — don't re-derive by eye what the tool already computed. Parse the JSON
+(`docs/cli.md`'s diff section documents the envelope: `diffSchemaVersion`, `counts`, `changes`,
+`removals`, every optional `ChangeEntry` field explicit-`null` when unused) and use it as the
+structural-surface findings directly.
+
+### 4. Classify
+
+Every finding — structural deltas from step 3, plus spec- and internal-surface findings from
+step 2 — sorts into exactly one class:
+
+- **Real drift** — code evidence contradicts the model or doc.
+- **Model gap** — code evidence shows behavior neither the model nor the doc covers.
+- **Internal inconsistency** — the doc and the `.em` disagree with each other (surface 3 only).
+- **Extraction uncertainty** — no evidence either way. Never reported as drift or a gap.
+
+Every classification must cite the evidence recorded in step 2 (or the `em diff` entry, for
+structural findings) — a finding with no citation isn't ready to report.
+
+### 5. Report + proposals
+
+Write `conformance/<YYYY-MM-DD>-report.md` in the model directory, from
+`templates/conformance-report.md`. For a real-drift or model-gap finding, propose a
+ready-to-apply red note — `issue "conformance: <text>"` on the right element, written out in
+the report exactly as it should be pasted into the `.em` — when a model-side marker is the
+right fix; when the fix is purely doc wording (or the finding is an internal inconsistency
+with no clear side to flag), omit the red note and say why instead. **You never edit the
+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:
+
+```
+- **Last conformance:** YYYY-MM-DD @ <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. 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.
+- **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
+  whoever ratifies it later understands the claim without re-reading the report.
+- **Naming/matching rules:** same past-tense-event / imperative-command / thing-shown-view
+  naming discipline as the rest of the skill (`methodology.md`'s Socratic stance) — you're
+  matching code to existing names here, not inventing new ones except for genuinely uncovered
+  behavior.
+
+## Completion & handoff
+
+Conform is complete when: every in-scope slice has been walked (step 2), the scratch model has
+been diffed (step 3), every finding is classified with cited evidence (step 4), the report is
+written (step 5), the state file's `Last conformance:` marker is updated, and the user has seen
+the report and said which proposals (if any) to apply. Applied proposals get re-rendered and
+re-validated before you call the run done.
+
+Conform doesn't chain to another phase automatically — it's a recurring loop, not a step in
+building the model. Suggest running it again next time the target codebase has moved, at
+whatever cadence the user wants (see `docs/ci.md` for a scheduled-run recipe).
+
+## Anti-patterns
+
+- **Blind extraction** — deriving the as-is scratch model with no sight of the canonical
+  model's vocabulary. Loses the anchor and produces naming-driven false drift.
+- **A scratch model holding only the in-scope slices** — `em diff` reads every omitted
+  canonical slice as removed, so a diff-scoped run drowns in phantom removals. Seed from the
+  canonical model and rewrite only the slices you walked.
+- **Reporting uncertainty as drift** — "I couldn't find the enforcement site" is an
+  uncertainty, never a finding against the model.
+- **Editing the model or a slice doc without ratification** — conform proposes; the user
+  applies. No exceptions, even for an "obviously correct" fix.
+- **Treating scenario/test absence as a build failure** — a missing test site is a spec-surface
+  finding to report and classify, not a reason to stop the run or block anything. Conform is
+  advisory; there's no gate here.
+- **Re-deriving what `em diff` already decided** — once you have the JSON, use it; don't
+  eyeball the two `.em` files yourself looking for structural differences the tool already
+  computed for you.

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

@@ -18,6 +18,8 @@ em render <file> --keep-empty-lanes   # keep the API lane even when empty
 em watch  <file> -o out.svg    # re-render on every save (file-based)
 em watch  <file> -o out.svg --serve   # + localhost live viewer, instant SSE push-reload (--port N)
 em validate <file>             # check event-modeling rules; exit 0 if only warnings/clean
+em validate <file> --list-issues       # print only open `issue "..."` clauses (slice, element, line, text)
+em validate <file> --fail-on-issues    # opt-in CI gate: exit non-zero while any issue remains open
 ```
 
 Install if missing: `npm i -g @milehimikey/em`. PNG works with no system deps; PDF needs
@@ -48,11 +50,11 @@ arrow From Element -> To Element    # explicit cross-slice edge (overrides infer
 ### Element kinds (8 keywords, nothing else)
 | Keyword | Band | Meaning | Tag | Extra clauses |
 |---|---|---|---|---|
-| `ui` | persona | screen / interface | `@Persona` | `note`, `{ fields }` |
-| `command` | API | state-changing request | — | `note`, `{ fields }` |
-| `view` | API | read model / projection | — | `from "Event"…`, `note`, `{ fields }` |
-| `event` | context | recorded fact (past tense) | `@Context` | `note`, `{ fields }` |
-| `processor` / `automation` / `saga` / `translation` | automation | system reaction / adapter | — | `from "…"`, `note`, `{ fields }` |
+| `ui` | persona | screen / interface | `@Persona` | `note`, `issue`, `{ fields }` |
+| `command` | API | state-changing request | — | `note`, `issue`, `{ fields }` |
+| `view` | API | read model / projection | — | `from "Event"…`, `note`, `issue`, `{ fields }` |
+| `event` | context | recorded fact (past tense) | `@Context` | `note`, `issue`, `{ fields }` |
+| `processor` / `automation` / `saga` / `translation` | automation | system reaction / adapter | — | `from "…"`, `note`, `issue`, `{ fields }` |
 
 ### Clauses
 - **Tags:** `@Persona` only on `ui`; `@Context` only on `event`. Undeclared tags auto-create a row.
@@ -69,6 +71,11 @@ arrow From Element -> To Element    # explicit cross-slice edge (overrides infer
   `from`/`arrow` — plain repeats are only warning-free while unreferenced.
 - **`note "path.md"`** on ANY element links a markdown doc. Relative to the `.em` file. Renders as
   a clickable marker in SVG and a legend entry in PNG/PDF. **This is how slice docs attach.**
+- **`issue "text"`** on ANY element flags an open question inline — the diagram-visible red
+  sticky note. Renders as a red corner marker (opposite corner from `note`, so both can coexist
+  on one element) plus a legend entry; `em validate` warns on every open issue. **Prefer this
+  over a `# TBD` comment for anything that should show up on the rendered diagram** — `# TBD` is
+  invisible once rendered, `issue` isn't.
 - **Fields:** `command Place Order { orderId: UUID, items: LineItem[], customerId }` — inline or
   one-per-line. Types are free text (no semantic checking). Keep these light; full field specs
   with rules live in the slice doc.
@@ -197,6 +204,16 @@ slice "Read Quote — created"   { view Quote from "QuoteCreated"  translation S
 2. **Command without event** — every command should record at least one event.
 3. **Read model without source** — add `from "Event"` or place the view in a slice with an event.
 4. **Duplicate name** — the same name defined N times; references resolve to the first. Rename.
+5. **Open issue** — an element carries `issue "text"`; resolve the question, then remove the
+   clause. `em validate --list-issues` prints just these; `--fail-on-issues` (opt-in) makes CI
+   fail while any remain open.
+6. **View field with no source** — a `view` field whose name matches no field on any instance
+   of its source events. Only checked once BOTH the view and at least one source event declare
+   `{ fields }`.
+7. **Event field not from a command** — an `event` field whose name matches no field on any
+   command in the same slice. Only checked once BOTH the event and at least one same-slice
+   command declare `{ fields }`. This is the payoff of the fields feature for slicing rigor:
+   once fields are written down, `em validate` checks that data flows forward consistently.
 
 **Design rules that keep models valid:**
 - One element per band per slice (multiple personas/contexts are fine — they're different rows).

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

@@ -94,8 +94,9 @@ one for a sprawling one. Record any deviation in the Decisions log.
 - Inline `.em` comment on its own line directly above (or trailing) the element it concerns:
   `# TBD: <specific question about current behavior>`. Comments are native DSL syntax — they
   render and validate cleanly.
-- Mirror every `# TBD` 1:1 as a checkbox in the state file's **Open questions / parking lot**,
-  and remove both together when resolved.
+- Mirror every `# TBD` 1:1 as a checkbox in the state file's **Open questions / parking lot** —
+  add `source`/`blocked on`/`revisit` metadata when known — and remove both together when
+  resolved.
 - A `# TBD` is only ever resolved by a confirmed current-state fact — never replaced by a
   guessed element.
 
@@ -105,8 +106,8 @@ Extraction is complete when: the model renders; `em validate` is clean (or remai
 are consciously accepted in the Decisions log); every unknown is a parked `# 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 the **Slice inventory** (every slice, pattern, doc status `none`).
+1. State file: set phase progress (extraction rounds checked), log the completion decision.
+   Seed `README.md`'s **slice index** (every slice, pattern, status `none`).
 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/methodology.md

@@ -163,6 +163,9 @@ 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?"*
+- **Existing codebase:** before finalizing field names/types, check adjacent real sources
+  (OpenAPI specs, DB migrations, existing DTOs/event classes in sibling contexts) rather than
+  guessing — mirrors `extract.md`'s whole-system grounding, applied per-slice.
 - Output: rich slice docs linked into the `.em` via `note "slices/<name>.md"`.
 
 ### Step 7 — Evaluate Completeness  *(model)*
@@ -192,9 +195,11 @@ The stance inversion, stated authoritatively: **extraction captures how the syst
 today — faithfully, warts included — and never invents future or desired state.** Step 1's
 anti-current-system caution is suspended for the duration; the "is it an event?" filter is
 not — derived values and telemetry are still rejected even when the current system emits them.
-Unknown or ambiguous current behavior is parked (`# TBD` in the `.em`, mirrored in the state
-file's Open Questions), never guessed. Desired-state improvements belong to the `model` and
-`slice` phases, after the as-is picture is agreed.
+Unknown or ambiguous current behavior is parked, never guessed — mirrored in the state file's
+Open Questions, and on the element itself with `issue "text"` when it should also show up on the
+rendered diagram (preferred over a bare `# TBD` comment, which is invisible once rendered).
+Desired-state improvements belong to the `model` and `slice` phases, after the as-is picture is
+agreed.
 
 Procedure, source modes (event-driven vs. procedural synthesis), and the round-by-round loop:
 `reference/extract.md`.
@@ -208,3 +213,6 @@ Procedure, source modes (event-driven vs. procedural synthesis), and the round-b
 - Mirror the model back after each increment and **re-render** so the team sees it evolve.
 - Park unresolved questions in the state file instead of guessing.
 - Name things crisply: events past-tense, commands imperative, views as the thing-shown.
+- **Live workshop, one chat interface:** route through a single human proxy who relays questions
+  to the room and reports answers back; attribute every answer/decision in the Decisions log to
+  the named participant who gave it (see the state file's Participants section).

package/.claude/skills/event-modeling/templates/conformance-report.md

@@ -0,0 +1,69 @@
+<!--
+Conformance report skeleton. One per conform run, stored at
+<model-name>/conformance/<YYYY-MM-DD>-report.md (see reference/conform.md).
+Fill every section; leave "none" rather than deleting a section with nothing to report.
+Replace bracketed placeholders; delete guidance comments before finishing.
+-->
+
+# Conformance Report — {{Model Name}} — {{YYYY-MM-DD}}
+
+- **Model:** `{{model-name}}.em`
+- **Target repo:** {{repo path or URL}} @ `{{revision}}`
+- **Previous conformance revision:** {{prior target-repo revision, or "never (first run)"}}
+- **Scope:** {{full | diff-scoped since <prior revision>}}
+- **Slices checked:** {{comma-separated slice names, or "all implemented slices"}}
+- **Slices skipped (not yet implemented):** {{list, or "none"}}
+
+## Summary
+
+| Surface | Real drift | Model gap | Internal inconsistency | Uncertainty |
+|---|---|---|---|---|
+| Structural | {{n}} | {{n}} | — | {{n}} |
+| Spec | {{n}} | {{n}} | — | {{n}} |
+| Internal | — | — | {{n}} | {{n}} |
+
+{{One or two sentences: overall read — clean, mostly clean with N items, or notably drifted.}}
+
+## Findings
+
+<!-- One subsection per finding. Group however reads clearest (by slice, or by surface) but keep
+     every field below for every finding. Order doesn't matter; classification does. -->
+
+### {{n}}. {{Short finding title}}
+
+- **Surface:** {{structural | spec | internal}}
+- **Classification:** {{real drift | model gap | internal inconsistency}}
+- **Slice:** {{slice name}}
+- **Evidence:** {{file path(s) and line/symbol, or the `em diff --json` entry (type + name)}}
+- **Claim:** {{what the model/doc says vs. what the code/doc shows — the actual disagreement}}
+- **Proposed red note:** `issue "conformance: {{text}}"` on {{element}} (slice "{{slice}}")
+  <!-- Omit this line entirely for internal-inconsistency findings with no clear side to flag,
+       or when the finding doesn't warrant a red note (say why instead). -->
+
+## Scenario / invariant coverage
+
+<!-- Per in-scope slice: every named invariant and every GWT scenario the doc claims, mapped to
+     its enforcement/test site. Leave a cell explicitly blank/"none found" rather than omitting
+     the row — gaps are the point of this table. -->
+
+### {{Slice Name}}
+
+| Claim | Type | Enforcement site | Test site | Status |
+|---|---|---|---|---|
+| {{INV-XXX-1 or scenario title}} | {{invariant \| scenario}} | {{file path / symbol, or "none found"}} | {{file path / symbol, or "none found"}} | {{covered \| gap \| uncertain}} |
+
+## Uncertainties
+
+<!-- Listed separately from Findings — these are NOT drift. No evidence either way; say what was
+     missing (time, clarity, an ambiguous test) so a follow-up run can pick it up. -->
+
+- **{{structural | spec | internal}}** — {{what's uncertain}} — {{slice}} — {{why: e.g. "couldn't locate the test for INV-CHK-3, only its enforcement site"}}
+
+<!-- Tag each with its surface so these reconcile against the Summary table's Uncertainty column. -->
+
+## Applied this run
+
+<!-- Filled in AFTER the user reviews Findings and says what to apply. Leave "none yet — awaiting
+     ratification" until that conversation happens. -->
+
+{{List of ratified proposals actually applied to the `.em`/slice docs, or "none yet — awaiting ratification".}}

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

@@ -22,10 +22,12 @@ Static render: `em render {{model-name}}.em -o {{model-name}}.svg`
 - **Translation** — External input (or Read Model) → Translation → (next slice) Command → Event
 
 ## Slices
-<!-- Keep this index in sync as slice docs are written. -->
-| # | Slice | Pattern | Design doc |
-|---|-------|---------|------------|
-| 1 | {{Slice Name}} | {{Pattern}} | [slices/{{slice-name}}.md](slices/{{slice-name}}.md) |
+<!-- 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. -->
+| # | Slice | Pattern | Status | Design doc |
+|---|-------|---------|--------|------------|
+| 1 | {{Slice Name}} | {{Pattern}} | {{none / draft / reviewed / ready-to-implement / implemented}} | [slices/{{slice-name}}.md](slices/{{slice-name}}.md) |
 
 ## Status
 See [`.event-modeling.md`](.event-modeling.md) for current phase, decisions, and open questions.

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

@@ -9,10 +9,12 @@ Replace the bracketed placeholders; delete guidance comments before finishing.
 
 - **Pattern:** {{State Change | State View | Automation | Translation}}
 - **Swimlane:** {{Persona/Actor}} → {{Context/Aggregate}}
-- **Status:** {{draft | reviewed | ready-to-implement}}
+- **Status:** {{draft | reviewed | ready-to-implement | implemented}}
+- **Implemented in:** {{PR/commit link — fill in once status is `implemented`}}
 
 ## Intent
-{{Why this slice exists — the user or business goal it serves, in one or two sentences.}}
+{{Why this slice exists — the user or business goal it serves, in one or two sentences. Note the
+originating ticket/conversation link here if one exists.}}
 
 ## Trigger & Actor
 {{Who or what initiates this slice and under what circumstances. For automations, the watched
@@ -61,6 +63,13 @@ an event directly.}}
 - {{e.g. external call fails → retry policy / compensating event}}
 - {{idempotency: what happens if the command/event arrives twice?}}
 
+## Non-Functional Requirements
+<!-- Short checklist. Idempotency is covered above under Alternate & Error Flows — not repeated
+     here. -->
+- **Security / authz:** {{who may invoke this; role/permission checks — or "none"}}
+- **PII & compliance:** {{personal data touched, retention/consent constraints — or "none"}}
+- **Performance / SLA:** {{latency/throughput expectation — or "none"}}
+
 ## Dependencies & Read Models Affected
 - **Upstream events this slice relies on:** {{...}}
 - **Downstream read models / slices affected:** {{...}}