@milehimikey/em 1.2.0 → 1.3.0

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

@@ -28,7 +28,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 +64,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
 
@@ -88,6 +92,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 +117,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 +138,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 +168,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,13 +179,19 @@ 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: `watch` — live team view
@@ -199,6 +213,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/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/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:** {{...}}

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

@@ -18,6 +18,11 @@ Keep it current at the end of every working session.
 - **Source mode:** {{greenfield | extract-event-driven | extract-procedural}}
 - **Existing system refs:** {{repo paths, event-schema/topic locations, docs — or "n/a"}}
 
+## Participants
+<!-- Populate at session start. Live workshop: one human proxy relays questions to the room;
+     attribute every answer/decision in the Decisions log to a named participant here. -->
+- {{Name}} — {{role}} — {{domain area}}
+
 ## Extraction progress (existing-system models only — delete for greenfield)
 - [ ] R1. Candidate events (extracted/synthesized, filtered, confirmed)
 - [ ] R2. Timeline order (as-is narrative, actors/callers, first render)
@@ -37,14 +42,18 @@ Keep it current at the end of every working session.
 - [ ] 7. Evaluate completeness (`em validate` clean)
 
 ## Decisions log
-<!-- Resolved choices, with the reasoning, so they aren't re-litigated. -->
-- {{YYYY-MM-DD}}: {{decision}} — {{why}}
+<!-- Resolved choices, with the reasoning, so they aren't re-litigated. In a live workshop,
+     attribute each entry to the participant who made the call (see Participants above). -->
+- {{YYYY-MM-DD}}: {{decision}} — {{why}} — by {{participant, if a live workshop}}
 
 ## Open questions / parking lot
-<!-- Unresolved items to bring back to the user. Never guess these. -->
-- [ ] {{question}}
+<!-- Unresolved items to bring back to the user. Never guess these. Metadata is optional and
+     flat — add only what's known: source (ticket/conversation that spawned it), blocked on
+     (who/what), revisit (when). -->
+- [ ] {{question}} — source: {{ticket/conversation link, optional}} — blocked on: {{who/what, optional}} — revisit: {{when, optional}}
 
 ## Slice inventory
-| Slice | Pattern | Doc status |
-|-------|---------|------------|
-| {{Slice Name}} | {{State Change/View/Automation/Translation}} | {{none / draft / reviewed / ready-to-implement}} |
+<!-- Deliberately NOT a table: the canonical slice index (slice, pattern, status, doc link)
+     lives in README.md's "Slices" section — one source of truth, updated there. This file
+     only tracks resumable session state. -->
+See `README.md` → **Slices** for the slice index and per-slice doc status.

package/README.md

@@ -75,6 +75,7 @@ built this way.
 | [docs/dsl.md](docs/dsl.md) | Full DSL reference: keywords, `from`, `again`, fields, notes |
 | [docs/cli.md](docs/cli.md) | Every command and flag |
 | [docs/validation.md](docs/validation.md) | Every rule `em validate` checks, and the fixes |
+| [docs/ci.md](docs/ci.md) | Copy-paste GitHub Actions recipe: validate `.em` changes in CI |
 | [docs/timeline.md](docs/timeline.md) | The Two Laws of the Timeline |
 | [docs/ai-workflow.md](docs/ai-workflow.md) | The Claude Code skill: install, phases, artifacts |
 | [docs/dependencies.md](docs/dependencies.md) | What's bundled vs. what needs a system install |

package/dist/cli/diff-inputs.d.ts

@@ -0,0 +1,44 @@
+/** Resolved `em diff` invocation, or a user-facing `error` for an invalid form. */
+export type DiffPlan = {
+    error: string;
+} | {
+    form: "files";
+    oldFile: string;
+    newFile: string;
+} | {
+    form: "git";
+    file: string;
+    from: string;
+    to?: string;
+};
+/**
+ * Validate the `em diff` argument/flag combination. Pure — no I/O. The two forms
+ * (two files, or one file across git revisions) are mutually exclusive.
+ */
+export declare function planDiffArgs(oldFile: string, newFile: string | undefined, opts: {
+    from?: string;
+    to?: string;
+}): DiffPlan;
+/** The slice of a `spawnSync` result `resolveRevision` reads; lets tests inject a fake git. */
+export interface GitResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type GitRunner = (args: string[]) => GitResult;
+/** Default runner: really invokes `git` (array args — no shell, no injection). */
+export declare const realGit: GitRunner;
+/** File content at a git revision, or a user-facing `message` for each failure mode. */
+export type RevisionResult = {
+    ok: true;
+    content: string;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Resolve `file`'s content at git revision `rev` via `git show <rev>:<repo-relative-path>`.
+ * The git runner is injectable so the not-a-repo / not-tracked / bad-rev branches are
+ * unit-testable without a real repository.
+ */
+export declare function resolveRevision(file: string, rev: string, runGit?: GitRunner): RevisionResult;

package/dist/cli/diff-inputs.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+// Testable input handling for `em diff`: argument-form validation and
+// git-revision resolution, factored out of cli.ts so the branching logic can be
+// unit-tested without spawning a subprocess or a real git repo (cli.ts keeps the
+// process.exit/console wiring; see test/diff-inputs.test.ts).
+import { spawnSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+/**
+ * Validate the `em diff` argument/flag combination. Pure — no I/O. The two forms
+ * (two files, or one file across git revisions) are mutually exclusive.
+ */
+export function planDiffArgs(oldFile, newFile, opts) {
+    if (opts.from) {
+        if (newFile) {
+            return {
+                error: "em diff: cannot combine two file arguments with --from/--to — use one form or the other",
+            };
+        }
+        return { form: "git", file: oldFile, from: opts.from, to: opts.to };
+    }
+    if (opts.to) {
+        return { error: "em diff: --to requires --from" };
+    }
+    if (!newFile) {
+        return {
+            error: "em diff: provide two files (`em diff old.em new.em`) or one file with --from <rev>",
+        };
+    }
+    return { form: "files", oldFile, newFile };
+}
+/** Default runner: really invokes `git` (array args — no shell, no injection). */
+export const realGit = (args) => {
+    const r = spawnSync("git", args, { encoding: "utf8" });
+    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+};
+/**
+ * Resolve `file`'s content at git revision `rev` via `git show <rev>:<repo-relative-path>`.
+ * The git runner is injectable so the not-a-repo / not-tracked / bad-rev branches are
+ * unit-testable without a real repository.
+ */
+export function resolveRevision(file, rev, runGit = realGit) {
+    const abs = resolve(file);
+    const toplevel = runGit(["-C", dirname(abs), "rev-parse", "--show-toplevel"]);
+    if (toplevel.status !== 0) {
+        return { ok: false, message: `em diff: ${file} is not inside a git repository (needed for --from/--to)` };
+    }
+    const repoRoot = toplevel.stdout.trim();
+    const lsFiles = runGit(["-C", repoRoot, "ls-files", "--full-name", "--", abs]);
+    const relPath = lsFiles.stdout.trim().split("\n")[0];
+    if (!relPath) {
+        return { ok: false, message: `em diff: ${file} is not tracked by git in ${repoRoot}` };
+    }
+    const show = runGit(["-C", repoRoot, "show", `${rev}:${relPath}`]);
+    if (show.status !== 0) {
+        return {
+            ok: false,
+            message: `em diff: cannot read ${relPath} at revision "${rev}": ${(show.stderr || "").trim() || "unknown git error"}`,
+        };
+    }
+    return { ok: true, content: show.stdout };
+}
+//# sourceMappingURL=diff-inputs.js.map

package/dist/cli/diff-inputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-inputs.js","sourceRoot":"","sources":["../../src/cli/diff-inputs.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -11,12 +11,19 @@ import { renderDot, formatFromPath } from "./render/render.js";
 import { watchFile } from "./render/watch.js";
 import { startLiveServer } from "./render/serve.js";
 import { formatDiagnostic, hasErrors } from "./model/validate.js";
+import { buildExport } from "./emit/json.js";
+import { diffModels, formatModelDiff, hasChanges } from "./model/diff.js";
+import { planDiffArgs, resolveRevision } from "./cli/diff-inputs.js";
 import { STARTER_EM } from "./templates.js";
 const program = new Command();
+// Single source of truth for the version (also read by src/emit/json.ts for
+// `generator.version` in `em export`): package.json, one level up from both
+// src/ and dist/.
+const PKG_VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
 program
     .name("em")
     .description("Event Modeling CLI — slice-first DSL rendered as a strict Graphviz grid")
-    .version("1.2.0");
+    .version(PKG_VERSION);
 program
     .command("init")
     .description("scaffold a starter .em model")
@@ -63,6 +70,54 @@ program
     await renderDot(dot, model, out, fmt, dirname(file));
     console.log(`rendered ${out}`);
 });
+program
+    .command("export")
+    .description("export a versioned JSON snapshot of the normalized model")
+    .argument("<file>", "input .em file")
+    .option("-o, --out <path>", "write to a file instead of stdout")
+    .action((file, opts) => {
+    const { model, diagnostics, source } = compileFile(file);
+    printDiagnostics(diagnostics);
+    if (hasErrors(diagnostics)) {
+        console.error("not exporting: fix the errors above");
+        process.exit(1);
+    }
+    const exported = buildExport(model, diagnostics, source, file);
+    printDiagnostics(exported.diagnostics.filter((d) => !diagnostics.includes(d)));
+    if (opts.out) {
+        writeFileSync(opts.out, exported.text + "\n");
+        console.log(`wrote ${opts.out}`);
+    }
+    else {
+        process.stdout.write(exported.text + "\n");
+    }
+});
+program
+    .command("diff")
+    .description("compare two models structurally (two files, or one file across git revisions)")
+    .argument("<old>", "old model file — or the file to diff, when using --from")
+    .argument("[new]", "new model file (omit when using --from/--to)")
+    .option("--from <rev>", "diff <old> against this git revision instead of a second file")
+    .option("--to <rev>", "diff against this git revision instead of the current file (requires --from)")
+    .option("--exit-code", "exit 1 if the models differ, 0 if identical (git-diff convention)")
+    .action((oldFile, newFile, opts) => {
+    const plan = planDiffArgs(oldFile, newFile, opts);
+    if ("error" in plan) {
+        console.error(plan.error);
+        process.exit(1);
+    }
+    if (plan.form === "files") {
+        const oldSource = readFileOrExit(plan.oldFile);
+        const newSource = readFileOrExit(plan.newFile);
+        runDiff(oldSource, plan.oldFile, newSource, plan.newFile, opts.exitCode);
+        return;
+    }
+    const oldSource = readAtRevision(plan.file, plan.from);
+    const oldLabel = `${plan.file}@${plan.from}`;
+    const newSource = plan.to ? readAtRevision(plan.file, plan.to) : readFileOrExit(plan.file);
+    const newLabel = plan.to ? `${plan.file}@${plan.to}` : plan.file;
+    runDiff(oldSource, oldLabel, newSource, newLabel, opts.exitCode);
+});
 program
     .command("watch")
     .description("re-render on every save")
@@ -116,13 +171,25 @@ program
     .command("validate")
     .description("check a model against event-modeling rules")
     .argument("<file>", "input .em file")
-    .action((file) => {
-    const { diagnostics } = compileFile(file);
-    printDiagnostics(diagnostics);
+    .option("--list-issues", "print only open `issue` diagnostics (slice, element, line, text)")
+    .option("--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)")
+    .action((file, opts) => {
+    const { model, diagnostics } = compileFile(file);
+    if (opts.listIssues) {
+        printIssues(model);
+        // Errors still fail the run below — surface them rather than exiting
+        // non-zero with nothing but the issue list on screen.
+        printDiagnostics(diagnostics.filter((d) => d.severity === "error"));
+    }
+    else {
+        printDiagnostics(diagnostics);
+        if (diagnostics.length === 0)
+            console.log("ok — no issues");
+    }
     if (hasErrors(diagnostics))
         process.exit(1);
-    if (diagnostics.length === 0)
-        console.log("ok — no issues");
+    if (opts.failOnIssues && model.elements.some((el) => el.issue))
+        process.exit(1);
 });
 const skill = program
     .command("skill")
@@ -160,7 +227,7 @@ function compileFile(file, opts = {}) {
         process.exit(1);
     }
     try {
-        return compile(source, opts);
+        return { ...compile(source, opts), source };
     }
     catch (e) {
         if (e instanceof ParseError) {
@@ -170,6 +237,53 @@ function compileFile(file, opts = {}) {
         throw e;
     }
 }
+/** Read a file's text, or exit with a clear error — used by `em diff`'s two-file form. */
+function readFileOrExit(file) {
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        console.error(`cannot read ${file}`);
+        process.exit(1);
+    }
+}
+/** Parse+normalize source text for `em diff`, exiting with a labeled parse error on failure. */
+function compileSource(source, label) {
+    try {
+        return compile(source);
+    }
+    catch (e) {
+        if (e instanceof ParseError) {
+            console.error(`parse error in ${label} ${e.message}`);
+            process.exit(1);
+        }
+        throw e;
+    }
+}
+/** Resolve `file`'s content at a git revision, exiting with a clear error on any git failure. */
+function readAtRevision(file, rev) {
+    const result = resolveRevision(file, rev);
+    if (!result.ok) {
+        console.error(result.message);
+        process.exit(1);
+    }
+    return result.content;
+}
+/** Shared body for both `em diff` forms: compile both sides, gate on errors, print, exit-code. */
+function runDiff(oldSource, oldLabel, newSource, newLabel, exitCode) {
+    const oldResult = compileSource(oldSource, oldLabel);
+    const newResult = compileSource(newSource, newLabel);
+    printDiagnostics(oldResult.diagnostics);
+    printDiagnostics(newResult.diagnostics);
+    if (hasErrors(oldResult.diagnostics) || hasErrors(newResult.diagnostics)) {
+        console.error("not diffing: fix the errors above");
+        process.exit(1);
+    }
+    const diff = diffModels(oldResult.model, newResult.model);
+    console.log(formatModelDiff(diff));
+    if (exitCode && hasChanges(diff))
+        process.exit(1);
+}
 function defaultOut(file, fmt) {
     const base = basename(file, extname(file));
     return `${base}.${fmt}`;
@@ -183,6 +297,18 @@ function warnMissingNotes(file, model) {
         }
     }
 }
+/** Print only the open `issue "text"` diagnostics: slice, element, line, text — for CI. */
+function printIssues(model) {
+    const withIssues = model.elements.filter((el) => el.issue);
+    if (withIssues.length === 0) {
+        console.log("no open issues");
+        return;
+    }
+    for (const el of withIssues) {
+        const slice = model.slices[el.sliceIndex];
+        console.log(`  issue :${el.line} slice "${slice.name}" ${el.kind} "${el.name}": ${el.issue}`);
+    }
+}
 function printDiagnostics(diags) {
     if (diags.length === 0)
         return;