@milehimikey/em 1.12.0 → 1.13.0

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling
-em-version: 1.12.0
+em-version: 1.13.0
 description: >-
   Use when the user runs `/event-modeling` (with or without a phase name), or wants to resume an
   event-modeling session without specifying which part of the process applies. Reads the model's
@@ -30,7 +30,9 @@ phase lives in.
 ## Routing logic
 
 1. Check the tool: `em --version`. If missing, tell the user to run `npm i -g @milehimikey/em`
-   and stop until installed.
+   and stop until installed. Then check this vendored bundle's own currency against it — see
+   `../event-modeling-shared/reference/operating-principles.md`'s Preconditions step 2: a bundle
+   more than a minor version stale is a STOP, not a warning.
 2. Parse `$ARGUMENTS` for a phase name.
    - **A recognized phase name** (`discover`, `extract`, `model`, `slice`, `implement`,
      `conform`, `validate`, `watch`, `review`): look it up in the table above and invoke that

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-conform
-em-version: 1.12.0
+em-version: 1.13.0
 description: >-
   Use when checking a ratified event model (and its slice docs) for drift against the codebase
   that implements it — advisory only, never a gate, never an unprompted edit — or when walking
@@ -33,18 +33,29 @@ or doc; write the as-is picture into that scratch model (`<model-name>-asis.em`,
 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; run `em state set-conformance
-<revision> --report <path>` to update the state file's `Last conformance:` marker.
+`conformance/<date>-report.md` **and its structured twin `conformance/<date>-findings.json`**
+(one entry per finding, `em conform-findings check <path>` to verify) with proposed `issue
+"conformance: …"` red notes; apply only the 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.
 
 Ruling on a finding is a human gate, like ratifying a slice
 (docs/process.md#the-slice-lifecycle-gates): the sweep gathers evidence and proposes, a person
-decides, and `em state set-conformance` records the decision — never run it on your own judgment.
+decides, and `em conform-supersede ... --locus <model|doc|code|none> --by <name>` records the
+ruling on the findings record (and stamps the report) — never rule on your own judgment. Once
+every finding touching a slice is ruled, `em slice conform <model-name>.em <key> --at <rev>`
+certifies that version of the slice.
 
-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.
+End of phase: state file's `Last conformance:` marker updated (via `em state set-conformance` —
+refuses while any `implemented` slice still has an unruled finding; `--partial` escapes with a
+loud notice), 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.
+
+A full (non-`--partial`) `em state set-conformance` also **certifies the model's current design
+version** (MIL-218, `docs/process.md#model-versions`) — it refuses if no design version has ever
+been bumped ("bump a model version first") or if the model changed during this run without a
+re-bump; run `em model version bump <model-name>.em --by <name>` before the final `em state
+set-conformance` call if either applies.
 
 ## Phase: `validate`
 

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

@@ -234,10 +234,22 @@ step 2 — sorts into exactly one class:
   which finding. Cite `slice.doc.driftSignal` and `slice.doc.version` together as evidence.
 - **Extraction uncertainty** — no evidence either way. Never reported as drift or a gap.
 
+**Read-model exposure (MIL-215).** Two rulings apply the classes above to a `view`'s exposure —
+whether it ships a query endpoint — instead of leaving each case to fresh judgment:
+
+- An **internal view** (no `ui` reads it, and it isn't marked `public`) implemented as
+  criteria-sourced state (a reaction's own read, no materialized projection — the general idiom
+  step 2 already names) or as an unexposed projection is **Conformant, never dead code to
+  flag**. It's the read operation the model draws to say an automation or translation *must*
+  read, not an endpoint promise; don't propose deleting it.
+- An **endpoint in code on a view the model shows no `ui` reading and no `public` marking** is a
+  **Model gap** — "add the `ui` or remove the endpoint" — **never Real drift to delete**.
+  Nobody decided whether that view is exposed; deleting the code decides it for them.
+
 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
+### 5. Report + findings record + proposals
 
 Write `conformance/<YYYY-MM-DD>-report.md` in the model directory, from
 `../../event-modeling-shared/templates/conformance-report.md`. For a real-drift or model-gap finding, propose a
@@ -250,6 +262,71 @@ 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`.
 
+**Also write the findings JSON (MIL-214).** Alongside the report, write
+`conformance/<YYYY-MM-DD>-findings.json` — one entry per `### n.` finding, ids matching the
+report's own numbering. Shape (`findingsSchemaVersion: "1.0"`, additive-only, 2-space indent,
+keys sorted, findings sorted by `id`, trailing newline):
+
+```json
+{
+  "findingsSchemaVersion": "1.0",
+  "model": "checkout.em",
+  "report": "conformance/YYYY-MM-DD-report.md",
+  "revision": "<target-repo revision>",
+  "findings": [
+    {
+      "id": 1,
+      "surface": "structural",
+      "class": "Real drift",
+      "slice": "checkout",
+      "evidence": "code shows X at path/to/File.kt:42",
+      "locus": null,
+      "resolvedBy": null,
+      "resolvedOn": null
+    }
+  ]
+}
+```
+
+`surface` is one of `structural` (`.em` <-> code — step 3's diff), `spec` (slice doc <-> code —
+step 2's invariant/scenario walk), `internal` (slice doc <-> `.em` — step 2's `doc-model-*`
+diagnostics), or `other`. `class` is the step-4 classification verbatim (Real drift, Model gap,
+Internal inconsistency, Accepted divergence, Unpropagated delta, Extraction uncertainty). `slice`
+is the concerned slice's export key, or `null` for a finding that isn't attributable to one
+(counts as in-scope for every slice's unruled-findings check). `locus`/`resolvedBy`/`resolvedOn`
+start `null` — a later `em conform-supersede --locus --by` call fills them in once a human rules.
+Run `em conform-findings check conformance/YYYY-MM-DD-findings.json` before ending the session —
+a headless run's mechanical proof it wrote a valid record.
+
+**Ruling on a finding (MIL-214) — once the user decides.** Run, per finding or batch of findings
+ruled the same way:
+
+```
+em conform-supersede <model-name>.em conformance/YYYY-MM-DD-report.md --as-of <target-repo revision> \
+  --findings <spec> --locus <model|doc|code|none> --by <name>
+```
+
+— this records `locus`/`resolvedBy`/`resolvedOn` on the named findings in the JSON (refusing to
+silently overwrite an already-different `locus`) AND stamps the report's "superseded as of `<rev>`"
+banner in the same call (see below). `locus: code` on an unresolved finding is the carrier for
+"the spec is right, the code is wrong" — no doc delta required for that case any more; `locus:
+model` means fix the `.em` (apply the proposed red note, or a stronger edit the user chose
+instead); `locus: doc` means the slice doc needs a delta/re-ratification; `locus: none` covers
+Accepted divergence/Unpropagated delta/Extraction uncertainty, where nothing needs to change.
+
+**Certifying a slice, once every finding touching it is ruled (MIL-214).** For each in-scope
+slice with no unruled findings left:
+
+```
+em slice conform <model-name>.em <slice-key> --at <target-repo revision>
+```
+
+— records `conformedVersion`/`conformedAt`/`conformedOn` on that slice's doc, so
+`driftSignal` reads `in-sync` again (it reads `uncertified` for an implemented slice that's never
+been through this) instead of just trusting `implementedIn`. Legal only for `status: implemented`
+with a link, and itself refuses if an unruled finding for that slice still exists at this
+revision — the mechanical proof this step comes only after rulings, not before.
+
 End of run: update the state file's `Last conformance:` marker with
 
 ```
@@ -258,14 +335,21 @@ em state set-conformance <target-repo revision> --report conformance/YYYY-MM-DD-
 
 — 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.
+**Refuses (MIL-214) while any `implemented` slice still has an unruled finding** in the findings
+JSON beside the report — rule on every finding first (or certify what's already ruled via `em
+slice conform` above), or pass `--partial` to record the marker with a loud notice instead
+(`notice: conformance marker recorded as PARTIAL — N finding(s) unruled`) when the team
+deliberately wants to advance the marker without finishing every ruling this session.
 **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
+after walking the report with the user; a headless/scheduled run writes the report and findings
+JSON 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.
 
-**Superseding the report you just walked (MIL-164).** Once the user has ruled on this run's
-findings, also run:
+**Superseding the report you just walked (MIL-164).** The `--locus`/`--by` call above already
+stamps the report's banner in the same call when a ruling was recorded; if a finding's ruling
+doesn't need `--locus`/`--by` recorded (a migration-path report predating the findings JSON, or
+a ruling you're only banner-stamping after the fact), run the same command without them:
 
 ```
 em conform-supersede <model-name>.em conformance/YYYY-MM-DD-report.md --as-of <target-repo revision> --findings <spec>
@@ -298,10 +382,23 @@ each call adds its own stamp rather than overwriting the last.
 ## 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.
+been diffed (step 3), every finding is classified with cited evidence (step 4), the report AND
+its findings JSON are written (step 5), the state file's `Last conformance:` marker is updated
+(or deliberately left as `--partial`), and the user has seen the report and said which proposals
+(if any) to apply and which findings resolve to which locus. Applied proposals get re-rendered
+and re-validated before you call the run done.
+
+A full (non-`--partial`) `em state set-conformance` does one more thing (MIL-218): it also
+**certifies** the model's current design version — writes `certified: { at, on, report,
+findings }` into that version's `model-versions/v<N>.json` manifest, and rewrites the state
+file's `Certified:` bullet. This is the "conform ran clean against version N" fact a
+stakeholder or a release note can point at. It only works on an already-**bumped** design
+version — `em state set-conformance` refuses (pointing at `em model version bump`) if no
+manifest exists yet, or if the model has drifted since the last bump (the certification would
+otherwise name a version that isn't what conform actually walked). If the model changed during
+this conform run (a slice's `version:` moved, or the `.em` file itself changed), bump a new
+design version (`em model version bump --by <name>`) before the final `em state
+set-conformance` call. `--partial` never certifies. See `docs/model-versions.md`.
 
 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

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-design
-em-version: 1.12.0
+em-version: 1.13.0
 description: >-
   Use when structuring a draft event model into swimlanes and the four patterns (State Change,
   State View, Automation, Translation), evaluating a model's structural completeness, or writing
@@ -51,7 +51,11 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    deep-dive in the `slice` phase below); the docs are the home for everything collected from
    here on, not yet implementation-ready specs. Because every doc already exists by the time the
    `slice` phase begins, its own step 2 scaffolding call is then a no-op — that phase picks up
-   at its step 1's deeper pass.
+   at its step 1's deeper pass. For a purely exploratory/backbone-mapping model that only needs
+   status coloring right now (not a full spec per slice yet), `em slice stub-all <model>.em` is
+   the one-command fast path: a near-free stub per undocumented slice, wired, in slice order
+   (MIL-184) — skip the per-slice `em slice new` calls above and deepen individual docs later
+   when the team is ready.
 3. **Evaluate completeness (step 7).** Walk the model: every slice is a **complete** pattern, not a
    half-slice — **every command has something that triggers it**, every command emits an event,
    **every event is read by a read model**, **every read model has a consumer**, every view has a
@@ -63,6 +67,10 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    For an unread event, don't just bolt on a view to silence the warning: ask the user who looks at
    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.
+   **Per `view`, also ask who reads it (MIL-215):** a person or client reads it → draw the `ui`
+   that reads it; another model/system reads it → mark it `public`; only an automation reads
+   it → nothing, it's internal by design. No new keyword — reachability is already what `ui` and
+   `public` mean.
 
 End of phase: render, update state (`em state set-phase slice` — the mechanical marker the state
 machine expects), and stop. Every slice already has a draft doc ready to receive the deep spec,

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-discover
-em-version: 1.12.0
+em-version: 1.13.0
 description: >-
   Use when starting a brand-new event model from scratch — greenfield discovery: brainstorming
   past-tense events, storyboarding the happy path, finding the commands and read models — or when

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-implement
-em-version: 1.12.0
+em-version: 1.13.0
 description: >-
   Use when building a single ratified event-modeling slice (status: ready-to-implement) into
   merged, tested code — the one phase where the agent builds rather than facilitates. Gates on

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

@@ -35,9 +35,10 @@ every `## Open Questions` checkbox is checked, and no status/version/link incohe
 `statusReady`/`noUncheckedOpenQuestions`) if you need to say which one is blocking.
 
 **`ready: false` means stop** — with one named exception: a slice already `status: implemented`
-with `driftSignal: in-sync` also reads `ready: false` (its `statusReady` gate fails because
-nothing is newly ratified), and that specific case is re-implementation/repair, not a blocker —
-see §3's third mode before treating it as one. For every other `false`, report which `gates`
+with `driftSignal: in-sync` or `uncertified` (MIL-214) also reads `ready: false` (its
+`statusReady` gate fails because nothing is newly ratified), and that specific case is
+re-implementation/repair, not a blocker — see §3's third mode before treating it as one. For
+every other `false`, report which `gates`
 entries are `false` (and any `diagnostics` entries concerning this slice) and hand the slice
 back to the humans. Never make the gate pass yourself — checking an open-question box, flipping
 `status`, or editing frontmatter are ratification decisions, and ratification happens in a
@@ -86,7 +87,9 @@ section — and the routing from it is mechanical, not a technical choice you ma
   translation, a view read only by a reaction) means internal-only: no endpoint. If one seems
   needed anyway, that's a gap to surface (§4), not a technical choice to make mid-implementation
   — adding a route the model doesn't show is exactly the kind of silent divergence §4 exists to
-  catch.
+  catch. An endpoint on a view the model shows no `ui` reading is a gap to surface the same way
+  (MIL-215) — conform will classify it as a **model gap**, never drift to delete, once you flag
+  it (`../../event-modeling-conform/reference/conform.md`, Flow step 4).
 - **`public` events and views** are the model's published integration surface: their shape is a
   contract, not an implementation detail. `em validate --list-public` lists them; `em typespec`
   is the POC generator for a downstream schema. Changing a public element's shape is a ratified
@@ -122,8 +125,11 @@ Check the doc's `version:` and `## Delta` section (or `em export`'s `slice.doc.d
   the people who've edited it (generated-then-owned); regeneration is legal only for slices
   whose code never merged.
 - **Re-implementation / repair** (`status: implemented`, `implementedIn` set, `driftSignal:
-  in-sync` — `--slice-ready` reports `ready: false` purely because `statusReady` fails, with no
-  other gate false and no doc content changed): the doc hasn't changed, but the shipped code
+  in-sync` **or** `uncertified` (MIL-214 — certification status is orthogonal to whether the doc
+  changed; most shipped slices sit at `uncertified` until a conform sweep certifies them, which
+  doesn't change which mode this is) — `--slice-ready` reports `ready: false` purely because
+  `statusReady` fails, with no other gate false and no doc content changed): the doc hasn't
+  changed, but the shipped code
   needs rebuilding or fixing — deleted code, a reverted PR, a bug in behavior the doc already
   specifies. **The doc is still the spec.** The gate's `false` here means "nothing new is
   ratified," not "stop" — it is not license to self-initiate: proceed only when a human has

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-review
-em-version: 1.12.0
+em-version: 1.13.0
 description: >-
   Use when starting em's live browser viewer (`em watch --serve`) so a team can watch a model
   update in real time, or facilitating a SCHEDULED stakeholder walkthrough that steps through
@@ -39,6 +39,10 @@ screen. Use Prev/Next (or the left/right arrow keys) to step through slices in d
 order — each one pans/zooms into view with everything else dimmed, so the room's attention
 tracks one slice at a time.
 
+**When a State View slice is on screen, ask who reads it (MIL-215):** a person or client in the
+room → the `ui` should draw it; another system → `public`; only an automation → nothing, it's
+internal by design and needs no endpoint.
+
 **Live capture:** when a stakeholder raises something unresolved, add `issue "..."` to the
 relevant element in the `.em` file and save — exactly the same mechanism `event-modeling-conform`
 uses for any other issue. The browser updates over the existing SSE push within moments, without

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

@@ -49,6 +49,12 @@ em slice new <name> --pattern <pattern>                       # slice pattern: s
 em slice new <name> --swimlane <swimlane>                     # swimlane, e.g. "Persona → Context"
 em slice new <name> -f, --force                               # overwrite the file if it already exists
 em slice new <name> --wire <model-file>                       # also insert the `note "slices/<key>.md"` line onto the slice's primary element in this .em file (matched by export key), instead of just printing it to paste by hand (MIL-161)
+em slice new <name> --stub                                    # write a near-free stub instead: same 5 frontmatter keys, but a one-line placeholder body instead of the diagram-image stub and every judgment section (MIL-184) — deepen it later by re-running without --stub and -f
+em slice stub-all <file>                                      # scaffold + wire a near-free stub (`em slice new --stub`'s content, MIL-184) for every slice in <file> with no resolvable doc — the fast path to status coloring for an exploratory/backbone model without hand-running `slice new` per slice. Skips a continuation slice (MIL-208, it has no doc of its own), an already-documented slice, and a slice whose pattern can't be classified
+em slice stub-all <file> --status <status>                    # target status for every stub: draft | reviewed | ready-to-implement | implemented
+em slice stub-all <file> --by <name>                          # identity for reviewedBy/ratifiedBy — required unless --status draft
+em slice stub-all <file> --implemented-in <url>               # PR/commit URL for implementedIn — required with --status implemented
+em slice stub-all <file> --dry-run                            # list what would be stubbed/wired without writing anything
 em slice index <file>                                         # rewrite the model's sibling README.md's GENERATED Slices table from `em export`'s slice facts (key, pattern, doc status/implementedIn) — the hand-maintained table is deprecated
 em slice index <file> --check                                 # verify the table is current; exit non-zero on drift without writing (CI)
 em slice mark-implemented <file> <slice-key> <pr-url>         # flip a slice doc's frontmatter to `status: implemented` / `implementedIn: <pr-url>` — the one edit an implementing agent makes to a ratified doc at merge (MIL-103, replaces the em-sdd-bridge `em-sdd-mark-implemented` script; see reference/implement.md §6). Idempotent on the same URL; refuses to overwrite a different one; never touches `version:` or the doc body
@@ -60,6 +66,10 @@ em slice ratify <file> <slice-key> --by <name>                # the ratifier's n
 em slice ratify <file> <slice-key> --on <date>                # ratification date, YYYY-MM-DD (default: today, local date)
 em slice ratify <file> <slice-key> --skip-review              # ratify without a recorded review — prints a loud notice on stderr
 em slice reratify <file> <slice-key>                          # bump `version:` and flip a shipped slice doc's frontmatter back to `status: ready-to-implement` — the re-ratification mechanical edit (MIL-161, mirrors `em slice mark-implemented`). Only applies to a doc at `status: implemented`; clears any stale `ratifiedBy:`/`ratifiedOn:`/`reviewedBy:`/`reviewedOn:` (they describe the PRIOR version's review and sign-off) so a follow-up `em slice ratify --by` applies cleanly — and needs no fresh review; never touches `implementedIn:` or the doc body
+em slice conform <file> <slice-key>                           # record per-slice-per-version conformance certification: sets `conformedVersion:`/`conformedAt:`/`conformedOn:` on a slice doc (MIL-214) — the fact `driftSignal: in-sync` now depends on. Legal only for `status: implemented` with an `implementedIn:` link. Idempotent on the same (version, --at) pair; a different --at simply overwrites (a later re-certification is normal — there's no way for em to tell 'later' from 'earlier' for an arbitrary revision string, so there's no --force to reach for). Refuses when the newest conformance/*-findings.json matching --at still has an unruled finding in scope for this slice; --skip-findings-check overrides with a loud notice.
+em slice conform <file> <slice-key> --at <rev>                # the target-repo revision this certification sweep diffed against
+em slice conform <file> <slice-key> --on <date>               # certification date, YYYY-MM-DD (default: today, local date)
+em slice conform <file> <slice-key> --skip-findings-check     # certify even with unruled findings in scope — prints a loud notice on stderr
 em changelog <file>                                           # render a model's git history as a business-readable ledger (see docs/cli.md)
 em changelog <file> --from <rev>                              # start the walk at this revision (inclusive)
 em changelog <file> --to <rev>                                # end the walk at this revision (inclusive; default HEAD)
@@ -67,21 +77,32 @@ em changelog <file> -o, --out <path>                          # write to a file
 em state read [dir]                                           # print the state file's mechanical fields as JSON
 em state set-phase <phase> [dir]                              # rewrite Current phase: (and Last updated:); --step also rewrites Current step:
 em state set-phase <phase> [dir] --step <n>                   # also set Current step: to this value
-em state set-conformance <revision> [dir]                     # rewrite Last conformance: (and Last updated:) in the exact format reference/conform.md parses
+em state set-conformance <revision> [dir]                     # rewrite Last conformance: (and Last updated:) in the exact format reference/conform.md parses. Refuses (MIL-214) while any `implemented` slice has an unruled conformance finding in the findings JSON beside --report (a `slice: null` finding blocks every slice); --partial records the marker with a ` (partial)` suffix instead, with a loud notice. Without a findings JSON beside --report: warns once and records the marker as given (migration path for a report predating `em conform-findings`)
 em state set-conformance <revision> [dir] --report <path>     # path to the conformance report just written
+em state set-conformance <revision> [dir] --partial           # record the marker as PARTIAL even though some in-scope findings are still unruled
 em state set-review <date> [dir]                              # rewrite Last stakeholder review: (and Last updated:)
 em state log-usage <file>                                     # append one Usage log line — phase(s) touched + em validate's diagnostic categories hit, deduped and canonically formatted (MIL-161, docs/usage-data.md) — the mechanical half of 'save state at the end of every session' that used to be run-validate-then-hand-format; state file resolved next to <file>, same convention as em conform-scope
 em state log-usage <file> --phases <list>                     # comma-separated phase(s) touched this session: discover, extract, model, slice, implement, conform, review, validate, watch
+em model version bump <file>                                  # bump the model's design version: write model-versions/v<N+1>.json (sibling of slices/, conformance/) and rewrite the state file's `Model version:` bullet (MIL-218). Refuses when the state file is missing (run `em scaffold` first), when --by is empty, and when nothing has changed since the current version (same model content hash AND same slice-version vector) unless --force — a no-op bump is the one case --force is right for.
+em model version bump <file> --by <name>                      # the bumper's name
+em model version bump <file> --on <date>                      # bump date, YYYY-MM-DD (default: today, local date)
+em model version bump <file> --force                          # bump even though nothing has changed since the current version
+em model version show <file>                                  # print the model's current design version and the most recently certified version, if any (model-versions/*.json — MIL-218)
+em model version show <file> --json                           # print a JSON document instead of text
 em usage-report [root]                                        # aggregate every .event-modeling.md's Usage log under [root] into phase/diagnostic-category tallies (MIL-161) — replaces docs/usage-data.md's hand-rolled grep/awk/sort pipeline; a logged line that doesn't match the canonical em state log-usage format is reported under unparseableLines rather than silently mistallied or dropped
 em usage-report [root] --json                                 # print a JSON document instead of the text report
 em conform-scope <file>                                       # mechanize conform phase step 1 (reference/conform.md): map the target repo's changed paths since Last conformance: to slices via each slice doc's implementedIn, JSON to stdout — --seed-asis also seeds the <model>-asis.em scratch model (see docs/cli.md)
 em conform-scope <file> --repo <path>                         # path to (or inside) the target codebase's git repository
 em conform-scope <file> --full                                # ignore Last conformance:/changed paths; scope every implemented slice
 em conform-scope <file> --seed-asis                           # write <model>-asis.em as a byte copy of the canonical model and ensure it's gitignored
-em conform-supersede <file> <report-path>                     # stamp a conformance report with a "superseded as of <rev>" banner once its findings have been ruled on (MIL-164, docs/process.md#what-ratified-means) — the companion step to run at ratification time so a reader following the report's file:line citations knows they describe an ancestor of the current model. Additive-only splice, never a rewrite of the report; idempotent on the same --as-of/--findings/--on stamp; refuses if the report doesn't exist
+em conform-supersede <file> <report-path>                     # stamp a conformance report with a "superseded as of <rev>" banner once its findings have been ruled on (MIL-164, docs/process.md#what-ratified-means) — the companion step to run at ratification time so a reader following the report's file:line citations knows they describe an ancestor of the current model. Additive-only splice, never a rewrite of the report; idempotent on the same --as-of/--findings/--on stamp; refuses if the report doesn't exist. --locus/--by (MIL-214, both required together) additionally record the ruling itself — locus/resolvedBy/resolvedOn — on the findings named by --findings in the sibling conformance/<date>-findings.json, when one exists (warns once and stamps the banner only when it doesn't — the migration path for a report predating em conform-findings)
 em conform-supersede <file> <report-path> --as-of <rev>       # the revision this ruling was made against — same value passed to `em state set-conformance`
 em conform-supersede <file> <report-path> --findings <spec>   # which finding number(s) this stamps as ruled, e.g. "1-3" or "1,2,4"
 em conform-supersede <file> <report-path> --on <date>         # ruling date, YYYY-MM-DD (default: today, local date)
+em conform-supersede <file> <report-path> --locus <locus>     # who/what the named finding(s) say is wrong: model | doc | code | none (requires --by)
+em conform-supersede <file> <report-path> --by <name>         # who ruled on the named finding(s) (requires --locus)
+em conform-findings check <path>                              # shape-validate a conformance/<date>-findings.json file (findingsSchemaVersion, required fields, enum values, ids sorted+unique, a ruled finding carries resolvedBy+resolvedOn) — exit 1 on shape errors. The conform skill writes this file directly alongside its report; this is how a headless run verifies what it just wrote.
+em conform-findings check <path> --json                       # print a JSON document instead of the text report
 em watch <file>                                               # re-render on every save
 em watch <file> -o, --out <path>                              # output path (extension picks the format)
 em watch <file> -T, --format <fmt>                            # output format (svg, png, pdf, ...)
@@ -117,6 +138,10 @@ em status <files> -o, --out <path>                            # write output to
 em freshness <file>                                           # standalone freshness signal for one model's conformance record (MIL-164): "last conformed <rev> — N commits and M slice-PRs behind HEAD", computed from the same conform-scope machinery `em status`'s conformance clause uses — for when you want just this fact, no full state-of-the-system rollup (see docs/cli.md)
 em freshness <file> --repo <path>                             # git repo to compute behind-HEAD in (default: the model's own directory)
 em freshness <file> --json                                    # print a JSON document instead of the text line
+em metrics <file>                                             # the pilot metrics named in advance by the register, computed from git history alone (MIL-170): ratification turnaround (reviewed -> ratified -> implemented), conform-cycle cadence + finding counts, and status-vs-reality disagreement over time — plus a fourth, reported as not computable from history (see docs/usage-data.md). `<file>` is an anchor .em file, used only to locate slices/, conformance/, and .event-modeling.md relative to it — same convention as em ledger; never parsed or compiled
+em metrics <file> --from <rev>                                # baseline revision
+em metrics <file> --to <rev>                                  # compare revision (default: HEAD)
+em metrics <file> --json                                      # print a JSON document instead of the text report (see docs/cli.md)
 em query consumers <files>                                    # views/reactions consuming an event, plus their slices
 em query consumers <files> --event <ref-or-name>              # the event's export ref or display name
 em query consumers <files> --json                             # print a JSON document instead of the text report
@@ -165,6 +190,10 @@ em ci init <model>                                            # install .github/
 em ci init <model> --tests <dir>                              # test directory the coverage/status steps scan for INV-* citations
 em ci init <model> -f, --force                                # replace an existing workflow file that has no GENERATED markers
 em ci init <model> --check                                    # verify both files match the current preset; exit non-zero on drift without writing (CI)
+em upgrade <file>                                             # bring a model repo authored under an older em (1.6 forward) up to the installed version: an ordered list of mechanical steps (skill bundle, reaction shape, state-file bullets, generated CI blocks, constitution scaffold) plus a human list of things no command can safely decide by itself (MIL-219, see docs/upgrading.md). Dry-run by default; --apply makes one git commit per applicable step, refusing on a dirty working tree
+em upgrade <file> --apply                                     # apply every applicable mechanical step, one git commit each, then a final `Em version:` commit
+em upgrade <file> --check                                     # exit non-zero only on a hard incompatibility (unparseable state file, an un-migratable .em shape) — writes nothing; what CI runs
+em upgrade <file> --json                                      # print a JSON document instead of text (dry-run/--check only, never with --apply)
 ```
 <!-- GENERATED:cli:end -->
 
@@ -270,6 +299,14 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   this model). `em export` carries it as `public: true`/`false`; `em diff` reports a flip as
   `event marked public`/`event unmarked public` (the entry cites the element's kind, so a
   view flip reads `view "X"`); `em validate --list-public` audits the whole public surface.
+  **Exposure of a read model (MIL-215) is three cases, no dedicated keyword:** a person/client
+  reads it → draw the `ui` that reads it (ships the endpoint); another model/system reads it →
+  `public` (a cross-model contract, verified by `em system <manifest>`, not `em validate`); only
+  an automation reads it → nothing — internal by design, the read a reaction is required to
+  make, not an endpoint. `em validate --list-public` flags a `public` view with no `ui`/reaction
+  reading it anywhere in this model as an audit note ("no in-model reader"), not a warning — a
+  cross-model `public` view's reader legitimately lives outside this file (see "`em validate`
+  rules" below).
 - **`tag`** (events only): declares a DCB (Dynamic Consistency Boundary) tag key. Three forms:
   a trailing `tag` on a field line inside the event's `{ … }` block (`priceId: UUID tag`, or
   typeless `priceId tag`) — an identity tag, key defaults to the field's own name; a bare field
@@ -681,6 +718,7 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `lineage-version-impossible` | error | Impossible lineage version | Fix the referenced version, or ratify the target slice first. |
 | `loops-to-forward` | error | `loops-to` target not earlier on the timeline | Point `loops-to` at an earlier view, or use `from` on a later `view … again` instance instead. |
 | `loops-to-unresolved` | error | `loops-to` target unresolved | Name a view that exists, or declare it before this event. |
+| `model-version-stale` | warning | Model version stale | Run `em model version bump` to record the current model content/slice-version vector. |
 | `note-binding-dangling` | warning | Dangling cross-slice note | Create the doc at that path, or fix/remove the note. |
 | `note-binding-extra` | warning | Extra doc-binding note, ignored | Remove the note, or point it at the slice's actual bound doc. |
 | `note-binding-unratified` | warning | Unratified cross-slice note | Add `covers: <this-slice-key>` to that doc's frontmatter, or correct the note's path. |

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

@@ -77,7 +77,17 @@ right here as `reference/slice-doc-schema.md` (kept in sync with the em repo's
 
 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
+2. Check this vendored skill bundle's own currency (MIL-219): read this file's `em-version:`
+   frontmatter stamp (or any sibling skill's SKILL.md — they're stamped together) and compare it
+   to `em --version` from step 1. **If the installed em is ahead by a minor version or more
+   (1.9.x → 1.11.x, or any major bump), STOP** — don't proceed with discover/model/slice/
+   implement/conform/review work on this stamp. Tell the user the vendored bundle is stale and to
+   run `em skill sync` (refresh the bundle only) or `em upgrade` (the bundle plus the model
+   repo's other mechanical migrations, docs/upgrading.md) before continuing. A patch-only gap
+   (1.11.2 → 1.11.4) is never worth stopping over — proceed normally. This matters because a
+   stale bundle silently follows old rules: an agent reading superseded preconditions/gates
+   can hand back work that looks right by last week's contract and wrong by this week's.
+3. Locate the model. Look for an existing `<dir>/.event-modeling.md` and `*.em` in the working
    directory, or — for a multi-model project laid out per the convention below — one level down
    inside a `models/` subfolder (each model gets its own `models/<slug>/` directory; check each
    candidate for its own `.event-modeling.md`/`*.em` pair). If found, run `em state read <dir>`
@@ -85,12 +95,12 @@ right here as `reference/slice-doc-schema.md` (kept in sync with the em repo's
    conformance, last review) as JSON — don't parse the bullets by hand. If not, and the phase
    needs one, ask the user for the model name and where to create it (a lone model goes at the
    project root; one of several goes under `models/`, per "Multi-model projects" below).
-3. If you're not sure which phase applies, or the user gave no phase, use `em state read <dir>`'s
+4. If you're not sure which phase applies, or the user gave no phase, use `em state read <dir>`'s
    `phase`/`step` to resume the recorded phase/step — or invoke the `event-modeling` skill, which
    does exactly this and routes to the right skill. If no model exists, propose starting
    `discover` (greenfield, `event-modeling-discover`) or `extract` (modeling an existing system,
    also `event-modeling-discover`).
-4. Populate the state file's Participants section at session start. For a live workshop, ask for
+5. 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.
 

package/.claude/skills/event-modeling-shared/reference/slice-doc-schema.md

@@ -69,6 +69,9 @@ to decide `frontmatter-invalid` without re-deriving frontmatter-shape rules of i
 | `ratifiedOn` | string | `YYYY-MM-DD` | written only by `em slice ratify` (MIL-165); joined into `em export`'s `slice.doc.ratifiedOn` (schema `1.8`) |
 | `owner` | string | free text (typically a person or team name) | hand-filled — no `em` command writes it; joined into `em export`'s `slice.doc.owner` (schema `1.9`, MIL-171), `em slice index`'s Owner column, and `em status`'s per-slice `owners[]` |
 | `tracking` | string | free text (typically an external ticket/issue URL) | hand-filled — no `em` command writes it; joined into `em export`'s `slice.doc.tracking` (schema `1.9`, MIL-171) and `em slice index`'s Tracking column. This is the exact field `em-tracker-bridge` reads to find the ticket mirroring this slice — `em` only stores and displays it, it never talks to a tracker itself |
+| `conformedVersion` | integer | positive integer | written only by `em slice conform` (MIL-214 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-conform-file-slice-key---at-rev)): this slice's `version:` at the time a conform sweep last certified it. Joined into `em export`'s `slice.doc.conformedVersion` (schema `1.13`); paired with `version` to compute `slice.doc.driftSignal`'s `"uncertified"` case |
+| `conformedAt` | string | free text (a target-repo revision, NOT a `<slice-key>@v<N>` lineage ref) | written only by `em slice conform` (MIL-214): the revision that certification sweep diffed against. Joined into `em export`'s `slice.doc.conformedAt` (schema `1.13`) and `em slice index`'s Conformed column |
+| `conformedOn` | string | `YYYY-MM-DD` | written only by `em slice conform` (MIL-214). Joined into `em export`'s `slice.doc.conformedOn` (schema `1.13`) |
 
 Five keys — `schemaVersion`/`pattern`/`swimlane`/`status`/`version` — are what
 `hasUsableFrontmatter()` requires: a doc omitting any of them is `frontmatter-invalid` to
@@ -89,6 +92,7 @@ convention, not parser-enforced.
 | `reviewedBy`, `reviewedOn` | optional in every state — present once `em slice review` (MIL-201) has run at least once; a doc that never went through the review gate, or was hand-flipped to `reviewed`, simply omits both. `em slice ratify` never clears them; `em slice reratify` does (they describe the version that shipped) |
 | `ratifiedBy`, `ratifiedOn` | optional in every state — present once `em slice ratify` (MIL-165) has run at least once; a doc predating this feature, or ratified by hand, simply omits both |
 | `owner`, `tracking` | optional in every state — hand-filled whenever a team wants a who-holds-this / external-tracker link; most docs never carry either (MIL-171) |
+| `conformedVersion`, `conformedAt`, `conformedOn` | optional in every state — present once `em slice conform` (MIL-214) has run at least once for the CURRENT version; a doc that's never been through a conform sweep, or whose `version` has since bumped past what was certified, simply has none of the three (or a stale triple — see `driftSignal`'s `uncertified` case below) |
 
 `em export`'s slice-doc join (MIL-91) is the first `em` command to mechanically check the
 required row above: a bound doc missing any of `schemaVersion`/`pattern`/`swimlane`/`status`/
@@ -101,6 +105,32 @@ No `em` command fails a build over this table. `em validate`'s frontmatter-coher
 (never fails) on the one combination checkable without git history: `status: implemented` with
 no `implementedIn` link at all.
 
+## Stub docs
+
+`em slice new --stub` and `em slice stub-all` (MIL-184, ruled 2026-09-08 on GH #128 — see that
+issue for the fuller design rationale) write a **stub**: the exact same 5 required-at-`status:
+draft` frontmatter keys above, but a one-line placeholder body (`_Stub — deepen with the slice
+phase (see slice-doc-schema.md)._`) instead of the diagram-image stub and every judgment section
+(Intent, Command, Scenarios, Open Questions, …) a full slice doc eventually carries.
+
+A stub is not a lesser doc, frontmatter-wise — it's a real doc with a real `status`, parsed and
+joined by `em export`/`em catalog`/`em status`/`em slice index` exactly like a fully-written one,
+because it's the same frontmatter dialect. The doc stays the single source of truth for
+`status`; a stub is just the cheapest possible way to give a slice one before anyone's ready to
+write the real spec.
+
+**A stub CAN pass `em validate --slice-ready`.** That gate checks four things (`computeSliceReadyGates`,
+[validation.md#slice-readiness](https://github.com/milehimikey/em/blob/main/docs/validation.md#slice-readiness)): a doc is bound, its frontmatter
+is usable, `status` is `ready-to-implement`, and its Open Questions count has none unchecked. A
+stub with no `## Open Questions` section at all has `openQuestionsTotal: 0` (see
+[Open Questions section: lifecycle](#open-questions-section-lifecycle) below) — zero unchecked is
+vacuously true — so a stub escalated to `ready-to-implement` (`em slice stub-all --status
+ready-to-implement --by <name>`) passes cleanly. The readiness gate is frontmatter-plus-checkbox-
+count only; it has no opinion about whether Intent/Command/Scenarios/Invariants were ever
+written. Demanding that content is the `slice` phase's (and, for a live walkthrough, the review
+skill's) job, not a machine gate's — see `../.claude/skills/event-modeling-design/SKILL.md` and
+`../.claude/skills/event-modeling-review/SKILL.md`.
+
 ## Lineage: grammar and cardinality
 
 Grammar: `<slice-key>@v<N>` — `<slice-key>` is the referenced slice's kebab-case filename stem

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

@@ -31,7 +31,14 @@ Replace bracketed placeholders; delete guidance comments before finishing.
 ## 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. -->
+     every field below for every finding. Order doesn't matter; classification does.
+
+     MIL-214: this section's structured twin is `conformance/{{YYYY-MM-DD}}-findings.json`,
+     written ALONGSIDE this report (not after it) — one JSON entry per `### n.` finding below,
+     `id` matching `{{n}}`. See reference/conform.md step 5 for the exact shape and the write-then-
+     `em conform-findings check`-it discipline. A later `em conform-supersede --locus --by` call
+     records the ruling on both the JSON (locus/resolvedBy/resolvedOn) and this report's banner
+     in one call. -->
 
 ### {{n}}. {{Short finding title}}
 

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

@@ -7,10 +7,13 @@ Keep it current at the end of every working session.
 # Event Modeling Progress — {{Model Name}}
 
 - **Model file:** `{{model-name}}.em`
+- **Em version:** {{X.Y.Z}}
 - **Current phase:** {{discover | extract | model | slice | implement | conform | review | validate}}
 - **Current step:** {{1–7, see methodology; or extraction round R1–R7}}
 - **Last updated:** {{YYYY-MM-DD}}
 - **Last conformance:** {{YYYY-MM-DD @ <target-repo revision> — report: conformance/<date>-report.md | never}}
+- **Model version:** {{N | none}}
+- **Certified:** {{v<N> @ <target-repo revision> (YYYY-MM-DD) | never}}
 - **Last stakeholder review:** {{YYYY-MM-DD — attendees: see Participants | never}}
 
 ## Session inputs

package/README.md

@@ -118,6 +118,7 @@ built this way.
 | [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 CI recipes: validate `.em` changes, run conformance on a schedule |
+| [docs/upgrading.md](docs/upgrading.md) | Bring a model repo forward across em releases: `em upgrade`, release by release |
 | [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/catalog/docJoin.d.ts

@@ -73,6 +73,15 @@ export interface SliceDocExport {
      *  em-tracker-bridge reads to find the mirrored ticket — its name/shape here is a cross-tool
      *  contract, not just an internal display field. */
     tracking: string | null;
+    /** MIL-214: this slice's `version:` at the time a conform sweep last certified it (frontmatter
+     *  `conformedVersion:`), written only by `em slice conform` — null when never certified. */
+    conformedVersion: number | null;
+    /** MIL-214: the target repo's revision that certification sweep diffed against (frontmatter
+     *  `conformedAt:`), written only by `em slice conform` — null when never certified. */
+    conformedAt: string | null;
+    /** MIL-214: the local date that certification was recorded (frontmatter `conformedOn:`),
+     *  written only by `em slice conform` — null when never certified. */
+    conformedOn: string | null;
 }
 export interface SliceDocJoinResult {
     doc: SliceDocExport;