@milehimikey/em 1.12.0 → 1.13.1

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling
-em-version: 1.12.0
+em-version: 1.13.1
 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,10 @@ 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
+   even one minor version behind the installed em is a STOP, not a warning — only a patch-only
+   gap proceeds normally.
 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.1
 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/process.md#model-versions`.
 
 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.1
 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,
@@ -107,7 +115,16 @@ For each slice:
    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.
+   already defined elsewhere. Before finalizing an invariant, also compare it with the slices in
+   **this same model** — never another `.em` model — that make the same kind of change (other
+   `Archive*` or `Create*` state changes on different entities, say). If one of them already
+   states an analogous rule, either state the same rule here — written out in this doc under
+   this slice's own `INV-<MNEMONIC>-n` ID, not by pointing at the sibling's — or record why this
+   slice's case differs. If this slice has a rule those siblings lack, raise that with the user
+   as an open question against each of them; a ratified sibling changes only through its own
+   re-ratification, never as a side effect of this slice. Repeating a rule across slice docs is
+   correct: each doc is a self-contained spec, and whether the code behind those rules is shared
+   is the constitution's call, not this doc's.
 2. **First-time authoring:** scaffold the doc mechanically rather than hand-writing the
    frontmatter — `em slice new "<slice name>" --pattern <state-change|state-view|automation|
    translation> --swimlane "<Persona> → <Context>" --wire <model>.em` writes `slices/<slice-name>.md`
@@ -136,7 +153,12 @@ For each slice:
    doc's authored body) — run `em slice reratify <model>.em <slice-key>` instead: it bumps
    `version` and flips `status` back to `ready-to-implement` in the existing frontmatter,
    clearing any stale `ratifiedBy:`/`ratifiedOn:` from the prior version so a follow-up
-   `em slice ratify --by <name>` (if the team records that) applies cleanly.
+   `em slice ratify --by <name>` (if the team records that) applies cleanly. The same command
+   changes a ratified doc that **never shipped** (`ready-to-implement` with `ratifiedBy` set — a
+   gap answered mid-build, MIL-258): it bumps `version` and clears the sign-off but leaves
+   `status` alone. Either way the doc is not ratified until `em slice ratify --by <name>` records
+   the new sign-off. A `ready-to-implement` doc with no `ratifiedBy` is already awaiting that
+   sign-off and refuses a second `reratify`; a `draft`/`reviewed` doc is simply edited.
 3. Render the slice's own diagram: `em render <model>.em --slice "<slice name>" -o
    slices/<slice-name>.svg` (kebab-case, matching the doc's filename and the `![Diagram]` stub
    `em slice new` already wrote) — redraws just this slice in its own canonical pattern shape.

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.1
 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.1
 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
@@ -21,11 +21,14 @@ land a one-time foundation PR holding every model event (plus the shared interfa
 slices only ever import contracts, never invent or reach into a sibling's; build in dependency
 order from `em query upstream`, not timeline order; treat the slice doc as
 the spec (read-only, except the merge-time `status`/`implementedIn` flip); implement exactly one
-slice doc per PR — a `covers:` doc's two keys ship together in that one PR, an `again` view
-instance gets its own; ship the endpoint a
+slice doc per PR — a `covers:` doc's two keys ship together in that one PR, and an `again` view
+instance is a continuation of its originating slice (no doc, status, or PR of its own — it
+ships in the originating doc's PR); ship the endpoint a
 `ui`-triggered command or `ui`-consumed view obligates, and surface — never invent — one the
 model doesn't show; surface every gap to the user instead of deciding it silently; cover every
-`INV-<MNEMONIC>-n` and every scenario with tests; in spec-kit projects, allocate via
+`INV-<MNEMONIC>-n` and every scenario with tests, proving the citations before merge with
+`em coverage <model>.em --slice <key> --tests <dir> --strict` (the default form skips a
+`ready-to-implement` slice); in spec-kit projects, allocate via
 em-sdd-bridge (redirect mode) and never run `/speckit.specify`.
 
 **Gate: no constitution, no first slice.** The constitution is the project's ratified house rules

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
@@ -151,6 +157,12 @@ undocumented ordering, a contradiction with adjacent code. The discipline:
   your recommendation. The human resolves it — at the model, where the resolution lands as an
   answered open question or a small ratified delta alongside your fix, so the decision is
   recorded instead of buried in an implementation diff.
+- **How a delta is ratified on a doc that never shipped** (it is `ready-to-implement` with
+  `ratifiedBy` set): once the human has answered, the doc changes by `em slice reratify
+  <model>.em <slice-key>` (bumps `version:`, clears the old sign-off, leaves `status` alone),
+  the answer is written into the doc, and the human re-signs with `em slice ratify <model>.em
+  <slice-key> --by <name>`. That is the human's step, not yours — you never run `ratify`, and
+  the doc is not ratified again until they do; resume the build after that.
 - **Never edit the ratified doc to record your own answer**, and never quietly pick a behavior
   a business person could have an opinion on. Silent divergence is the failure mode the whole
   conformance loop exists to catch — don't manufacture it.
@@ -177,8 +189,14 @@ or seem small — see §10.
 - The PR description cites exactly one slice doc (plus its `covers:` keys, if any) and lists
   that doc's invariants alongside the tests that cover them.
 - Every `INV-<MNEMONIC>-n` invariant has at least one test that cites its ID — checked mechanically by
-  `em coverage <model>.em --tests <dir>` (MIL-130); run it (add `--strict` in CI) rather than
-  eyeballing citations by hand.
+  `em coverage <model>.em --slice <slice-key> --tests <dir> --strict` (MIL-130, MIL-255); run it
+  before merge rather than eyeballing citations by hand. `--slice` is what makes this check the
+  slice under build: the default form, `em coverage <model>.em --tests <dir>`, counts only slices
+  already flipped to `implemented` (MIL-207), and your slice is still `ready-to-implement` until
+  the §6 flip — so the default form reports it `inScope: false`, checks nothing, and exits 0. It
+  is a regression check for shipped slices, not the definition-of-done check. (`--include-ready`
+  is no substitute: it counts every ratified slice, so `--strict` fails on slices nobody has
+  started.) A continuation key resolves to its originating slice's doc. If it exits 1 with "not in scope", the slice's doc is not `ready-to-implement`/`implemented` — nothing was checked, so stop and surface it rather than treating the run as a pass.
 - Every scenario in `## Scenarios (Given / When / Then)` exists as a passing test; rejection
   scenarios assert the doc's named rejection reason.
 - Alternate/error flows (idempotency included) are covered by tests.

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.1
 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,17 +49,27 @@ 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
 em slice review <file> <slice-key>                            # flip a slice doc's frontmatter to `status: reviewed` and record `reviewedBy:`/`reviewedOn:` — the FIRST of the two human gates (MIL-201, docs/process.md#the-slice-lifecycle-gates): the room walked this slice and every open question it raised is resolved. Ratification is a separate, later gate (`em slice ratify`). Legal from `status: draft`; idempotent on the same --by/--on pair; refuses to overwrite a different one already recorded; refuses a doc already `ready-to-implement`/`implemented`; never touches `version:` or the doc body
 em slice review <file> <slice-key> --by <name>                # the reviewer's (or facilitator's) name
 em slice review <file> <slice-key> --on <date>                # review date, YYYY-MM-DD (default: today, local date)
-em slice ratify <file> <slice-key>                            # flip a slice doc's frontmatter to `status: ready-to-implement` and record `ratifiedBy:`/`ratifiedOn:` — the handoff sign-off (MIL-165, docs/process.md#the-slice-lifecycle-gates) that makes who ratified, and when, a first-class recorded fact. Refuses a doc that never passed the review gate (`em slice review`) unless --skip-review is passed. Idempotent on the same --by/--on pair; refuses to overwrite a different one already recorded; never touches `version:` or the doc body
+em slice ratify <file> <slice-key>                            # flip a slice doc's frontmatter to `status: ready-to-implement` and record `ratifiedBy:`/`ratifiedOn:` — the handoff sign-off (MIL-165, docs/process.md#the-slice-lifecycle-gates) that makes who ratified, and when, a first-class recorded fact. The review gate is a check on the doc's current `status:`, not on whether `reviewedBy:`/`reviewedOn:` are populated: a doc at `reviewed` or `ready-to-implement` passes (the latter is where `em slice reratify` leaves a doc, so the follow-up ratify needs no --skip-review); any other status — a `draft` that never went through `em slice review` — is refused unless --skip-review is passed. Idempotent on the same --by/--on pair; refuses to overwrite a different one already recorded; never touches `version:` or the doc body
 em slice ratify <file> <slice-key> --by <name>                # the ratifier's name
 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 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`). Applies to a doc at `status: implemented`, or (MIL-258) to a `ready-to-implement` doc that is ratified but not yet shipped — there it bumps `version:` and clears the sign-off but leaves `status:` alone; a `ready-to-implement` doc with no `ratifiedBy:` refuses (awaiting `em slice ratify --by`). 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, ...)
@@ -102,8 +123,9 @@ em ledger <file> --from <rev>                                 # baseline revisio
 em ledger <file> --to <rev>                                   # compare revision (default: current working tree)
 em ledger <file> --waive <slice-key>                          # excuse a doc-content-without-version-bump finding for this slice key (repeatable; MIL-185, see docs/cli.md) — never waives a version regression or bump-without-content-change
 em ledger <file> --json                                       # print a JSON document instead of the text report (see docs/cli.md)
-em coverage <file>                                            # check that every INV-* invariant ID cited in an implemented slice doc is cited by a test under --tests <dir> (MIL-130/MIL-207) — mechanizes reference/implement.md's definition-of-done citation check; advisory by default, --strict for CI; --include-ready also counts ready-to-implement docs (forward-looking report); a continuation slice (an `again` view instance with no doc of its own, MIL-208) is excluded from the report — its invariants, if any, live in the originating slice's own doc
+em coverage <file>                                            # check that every INV-* invariant ID cited in an implemented slice doc is cited by a test under --tests <dir> (MIL-130/MIL-207) — mechanizes reference/implement.md's definition-of-done citation check; advisory by default, --strict for CI; --include-ready also counts ready-to-implement docs (forward-looking report); a continuation slice (an `again` view instance with no doc of its own, MIL-208) is excluded from the report — its invariants, if any, live in the originating slice's own doc; --slice <key> scopes the report to one slice whatever its status (MIL-255), the pre-merge definition-of-done check
 em coverage <file> --tests <dir>                              # directory to scan recursively for test files citing invariant IDs
+em coverage <file> --slice <key>                              # only this slice (export key), whether ready-to-implement or implemented — no --include-ready needed; --strict then fails on this slice's uncited invariants, or if the slice is not in scope (draft/reviewed/unbound: nothing checked) (MIL-255)
 em coverage <file> --strict                                   # exit non-zero if any invariant ID has zero citations (CI)
 em coverage <file> --include-ready                            # also count ready-to-implement docs, not just implemented (MIL-207)
 em coverage <file> --json                                     # print a JSON document instead of the text report (see docs/cli.md)
@@ -117,6 +139,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
@@ -163,8 +189,12 @@ em skill check [path]                                         # check the vendor
 em skill check [path] --json                                  # print a JSON document instead of the text report (see docs/cli.md)
 em ci init <model>                                            # install .github/workflows/em-ci.yml (PR gates: em validate, em slice index --check, em coverage --strict, em ledger, em skill check, em glossary --fail-on-conflicts, plus a push-triggered status-badge rebuild) and em-conform.yml (scheduled, advisory-only conformance cadence) — same install discipline as `em skill install`: marker-delimited, idempotent, --check for CI self-verification (MIL-166, see docs/ci.md)
 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> -f, --force                                # replace an existing workflow file that has no GENERATED markers, or a managed block generated for a different model
 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 (an existing but unparseable state file, an un-migratable .em shape) — writes nothing; what CI runs; the final line says why
+em upgrade <file> --json                                      # print a JSON document instead of text (dry-run/--check only, never with --apply)
 ```
 <!-- GENERATED:cli:end -->
 
@@ -270,6 +300,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 +719,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.