@milehimikey/em 1.21.0 → 1.22.1

package/.claude/agents/em-implementer.md

@@ -18,6 +18,16 @@ You are the em implementer. You build one slice, in one worktree, on one branch,
 - Write code and tests inside that slice's package, as the constitution's layout rule describes it.
 - Every invariant and scenario in the slice doc gets a test that cites its `INV-*` id.
 
+## Bindings file
+
+Part of this slice's definition of done, in the same PR: write or update `conformance/bindings/<slice-key>.yaml`, beside the model, per `docs/bindings.md`'s schema — you just wrote the code, you know which file and identifier anchors each element and each `INV-*` invariant's enforcement and test sites. It's a plain file you author like any other in your PR; no `em` command writes it. Before you report the slice done, verify it:
+
+```
+em conform bindings check <model>.em --repo <path> --slice <slice-key> --exit-code
+```
+
+Exit 0 is required. If it fails, fix the bindings file — a wrong `ref`, a stale `file`/`identifier` pair — never report the slice done with a failing binding.
+
 ## Tracking key
 
 If your prompt carries a tracking key (an issue-tracker key such as `PROJ-123`, or a URL), the lead has already resolved it for this slice: the slice doc's own `tracking:` wins over the engagement's. Use it as given:

package/.claude/agents/em-validator.md

@@ -22,6 +22,7 @@ Run each one and record pass or fail:
 5. No diff under `slices/**`, `*.em`, `constitution.md`, or `engagements/`. Use `git diff --name-only <base>...HEAD`.
 6. The pull request body cites the slice doc.
 7. The pull request title equals the title you were given, exactly (`gh pr view <pr> --json title`). A mismatch fails the check and quotes both. If no title was given, skip this check and say so.
+8. `conformance/bindings/<key>.yaml` exists beside the model, and `em conform bindings check <model.em> --repo <worktree path> --slice <key> --exit-code` exits 0 (GH #450).
 
 ## Output
 

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling
-em-version: 1.21.0
+em-version: 1.22.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

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-conform
-em-version: 1.21.0
+em-version: 1.22.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
@@ -28,9 +28,12 @@ duplicating them.
 In short: run `em conform-scope <model-name>.em --repo <target-repo-path> --seed-asis` to
 compute the in-scope slice set (diff-scoped by default, via `Last conformance:` + the target
 repo's changed paths mapped through each slice doc's `implementedIn:`) and seed the scratch
-model in one step; for each in-scope slice, gather code evidence *before* comparing to the model
-or doc; write the as-is picture into that scratch model (`<model-name>-asis.em`, reusing the
-canonical model's names wherever the code matches them); run `em diff <model-name>.em
+model in one step; for each in-scope slice, check for a `conformance/bindings/<key>.yaml` first
+(GH #450) — verify it with `em conform bindings check` and scope the walk through it when it
+exists, backfill it from this walk's own evidence when it doesn't — then gather code evidence
+*before* comparing to the model or doc; write the as-is picture into that scratch model
+(`<model-name>-asis.em`, reusing the canonical model's names wherever the code matches them);
+run `em diff <model-name>.em
 <model-name>-asis.em --json` and let `em` decide the structural deltas; classify every finding
 (real drift / model gap / internal inconsistency / uncertainty) with cited evidence; write
 `conformance/<date>-report.md` **and its structured twin `conformance/<date>-findings.json`**

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

@@ -94,7 +94,7 @@ e.g. a PR link, deterministically matches nothing). It prints one JSON document
 ```json
 { "lastConformance": { "date": "...", "revision": "..." } | null,
   "changedPaths": ["..."],
-  "candidateSlices": [ { "key": "checkout", "matchedBy": "implementedIn", "paths": ["..."] } ],
+  "candidateSlices": [ { "key": "checkout", "matchedBy": "implementedIn", "paths": ["..."], "file": null } ],
   "unmappedPaths": ["..."] }
 ```
 
@@ -104,6 +104,20 @@ your in-scope set for step 2. If `lastConformance` is `null` (first run) or you
 `changedPaths`/`unmappedPaths` both empty) — the tool makes this call for you, no need to
 special-case it yourself.
 
+**Storyline models (GH #451).** A model may split its storylines into their own files — a root
+declares `storyline "Name" [after "Other"]` with no body, and the storyline's slices live in
+`<slug>/<slug>.em` (`docs/dsl.md`'s "Storyline models" section). `em conform-scope` already
+compiles the root plus every storyline file it declares as ONE model
+(the same way every other `em` command does — a storyline file never compiles on its own), so
+scoping via `implementedIn` needs no special handling. What DOES change: each `candidateSlice`'s
+`file` names the storyline file that slice's body lives in — posix, relative to the model's
+directory — or `null` for a slice in the root file. This is which physical file you anchor on in
+step 2 and which scratch file you write the as-is picture into in step 3 (`--seed-asis` seeds one
+scratch file per physical file, not just the root — see there). Don't confuse a slice's `file`
+with its doc's path: slice docs for a storyline model live under that storyline's own
+`slices/` folder, but `em` finds them by key across every folder regardless, so doc resolution
+itself needs no extra care.
+
 **`unmappedPaths` is your judgment queue, not a dead end.** A changed path the tool couldn't
 place mechanically (`implementedIn` stale, a URL-only link, code that moved) still might belong
 to an in-scope slice — a quick Grep for the path's obvious symbols against the slice docs/model
@@ -119,6 +133,31 @@ keeps a recurring conform run cheap; don't invent a smarter trigger.
 
 For each slice in scope:
 
+**Check for an existing bindings file first (GH #450).** `conformance/bindings/<slice-key>.yaml`,
+beside the model, records this slice's own prior evidence — file and identifier per model
+element, and per `INV-*` invariant's enforcement/test sites (`docs/bindings.md`'s schema). Two
+cases, mutually exclusive:
+
+- **It exists:** verify it before walking anything by hand —
+  `em conform bindings check <model-name>.em --repo <target-repo-path> --slice <slice-key>`.
+  A binding that still checks out is evidence you don't need to re-derive; **scope the rest of
+  this slice's walk through it** — re-read only what the check reports failing (`file not
+  found`/`identifier not found`, an unknown `ref`) plus whatever `em conform-scope`'s
+  `changedPaths` (step 1) says moved since `implementedIn`. This is what turns a recurring
+  conform walk incremental instead of a full re-derivation every time — don't throw that away by
+  re-walking evidence the file already gives you clean.
+- **It doesn't exist:** the common shape for a slice an external or ticket-driven implementer
+  shipped without ever running `em` (`docs/bindings.md` is written so that implementer can still
+  author one by hand from its own ticket spec; this backfill is the safety net for the ones that
+  didn't, or for any slice that shipped before GH #450). Walk the slice normally (the numbered
+  steps below) and, once you've gathered that evidence, **write
+  `conformance/bindings/<slice-key>.yaml` from it** — the same file an implementer would have
+  written, now backfilled from your conform evidence instead of from the implementer's own
+  knowledge of the code. This is advisory tooling catching up a gap, not a model or doc edit: it
+  needs no ratification and doesn't change this phase's advisory-only stance (see "Stance"
+  above) — you're recording where code already lives, not deciding what it should do. From the
+  next conform run on, this slice follows the "it exists" branch above.
+
 1. Read the slice's **doc** (`slices/<slice-name>.md`) alongside its elements in the `.em`.
    This tells you the vocabulary to anchor on and the claims to check — not the answer.
 2. Walk the code and **record evidence before comparing**:
@@ -139,6 +178,20 @@ For each slice in scope:
      as missing. This is the *general*, idiom-level version of the next bullet — prefer citing
      an actual `divergence` annotation when the element carries one; fall back to this idiom
      note only when it doesn't.
+   - **`updates from` sources (GH #451) — housekeeping evidence, not trigger evidence.** A view
+     declared `view X from "A" updates from "B", "C"` (`docs/dsl.md`'s `updates from` section)
+     splits its sources into what put a row on the list (`from`) and what keeps an existing row
+     current or removes it (`updates from`). The two need different evidence: a `from` source is
+     what an automation/processor reacting to this view should fire on, or what a reader expects
+     to see a NEW row appear for — missing evidence there is the usual structural/spec drift. A
+     `updates from` source is expected to have an update/delete handler for the SAME row, never a
+     "new item created" or "automation triggered" site — don't report the absence of trigger-type
+     evidence for an `updates from` source as drift; that is literally what the clause says it
+     isn't. `em export`'s `from` list is the union of both (so `em diff`'s structural comparison
+     sees every source regardless of which list it's in — folding `from`/`updates from` into each
+     other is NOT itself a structural change `em diff` would catch), but the *diagram* draws no
+     arrow for an `updates from` source and the *evidence walk* above should read the same way:
+     check it as "does this row get kept current/removed", not "does this cause a new row".
    - **Accepted divergences:** before treating any finding as drift, check whether the
      relevant canonical element already carries a `divergence "..."` annotation (visible in
      the `.em`, in `em export --json`'s `divergence` field, or — for a structural finding — as
@@ -161,8 +214,15 @@ For each slice in scope:
 3. Write what you found into the scratch model (`<model-name>-asis.em`, see below) — start it
    with `em conform-scope <model-name>.em --repo <target-repo-path> --seed-asis`, which
    byte-copies the canonical `.em` to `<model-name>-asis.em` and ensures `*-asis.em` is
-   gitignored (idempotent — safe to pass on every run). **Then replace only the in-scope
-   slices** with the as-is picture, leaving out-of-scope slices byte-identical. This is not an optimization:
+   gitignored (idempotent — safe to pass on every run). **Storyline models (GH #451):** when the
+   slice you're rewriting has a non-null `file` in step 1's `candidateSlices` (its body lives in
+   a storyline file, not the root), `--seed-asis` also wrote a scratch copy of THAT file — the
+   `seeded.storylineFiles` entry naming it — and the copied root's declaration already points at
+   it. Edit that storyline file's own `-asis` sibling, never `<model-name>-asis.em` (it has no
+   body for that slice to rewrite) and never the canonical storyline file (that corrupts the
+   real model, not a scratch copy). **Then replace only the in-scope slices** with the as-is
+   picture, leaving out-of-scope slices byte-identical, in whichever scratch file(s) hold them.
+   This is not an optimization:
    `em diff` matches slices by name, so a scratch model containing *only* the in-scope slices
    reports every other canonical slice as `slice-removed` plus one `element-removed` per
    element — a phantom-removal flood on every diff-scoped run, which is the exact false drift
@@ -405,7 +465,12 @@ each call adds its own stamp rather than overwriting the last.
   directory as `.event-modeling.md`). Always seeded as a copy of the canonical model with only
   the in-scope slices rewritten (step 2) — `em conform-scope --seed-asis` does the seeding and
   the gitignoring (`*-asis.em`, idempotent) mechanically, never built up from nothing and never
-  hand-maintained. It's regenerated every conform run.
+  hand-maintained. It's regenerated every conform run. **Storyline models (GH #451):** a split
+  model gets ONE scratch file per physical file — `<model-name>-asis.em` for the root, plus a
+  `-asis` sibling for every storyline file the root declares (`seeded.storylineFiles` names
+  them) — never just the root; the copied root's `in` clause already points at each sibling, so
+  `em diff <model-name>.em <model-name>-asis.em` reads the whole scratch set as one model, same
+  as the canonical root reads the whole canonical set.
 - **Report location:** `conformance/<YYYY-MM-DD>-report.md` in the model directory. One file
   per run; don't overwrite a prior date's report. Its findings go in the same-stem `-findings.json`; gates read every same-revision findings file, so per-slice runs may write `<date>-<name>-findings.json`, and a ruling is written to the file the report names. The same-revision lookup uses the report's OWN revision (its `Target repo: … @ <rev>` header line; the caller's `<rev>` / `--as-of` only when the report has none).
 - **Red note wording:** `issue "conformance: <what's wrong, plainly>"` — plain enough that
@@ -447,6 +512,13 @@ whatever cadence the user wants (see `docs/ci.md` for a scheduled-run recipe).
 - **A scratch model holding only the in-scope slices** — `em diff` reads every omitted
   canonical slice as removed, so a diff-scoped run drowns in phantom removals. Seed from the
   canonical model and rewrite only the slices you walked.
+- **Editing a storyline file's canonical copy as if it were the scratch model (GH #451)** — for
+  a slice whose `file` isn't the root, the scratch copy is that storyline file's OWN `-asis`
+  sibling (`seeded.storylineFiles`), never `<model-name>-asis.em` (no body there to rewrite) and
+  never the canonical storyline file itself (that's the model, not a scratch copy of it).
+- **Treating an `updates from` source like a `from` source during the evidence walk** — a
+  missing "new row appears" or "automation fires" site is not drift for a source the view only
+  lists under `updates from`; check it for row-update/removal evidence instead (step 2).
 - **Reporting uncertainty as drift** — "I couldn't find the enforcement site" is an
   uncertainty, never a finding against the model.
 - **Editing the model or a slice doc without ratification** — conform proposes; the user
@@ -457,6 +529,12 @@ whatever cadence the user wants (see `docs/ci.md` for a scheduled-run recipe).
 - **Re-deriving what `em diff` already decided** — once you have the JSON, use it; don't
   eyeball the two `.em` files yourself looking for structural differences the tool already
   computed for you.
+- **Re-deriving evidence a verified bindings file already gives you (GH #450)** — when
+  `em conform bindings check` passes for a slice's `conformance/bindings/<key>.yaml`, walking
+  every element and invariant by hand anyway defeats the point of the file; scope through it
+  (step 2) instead.
+- **Skipping the backfill because a slice has no bindings file** — the absence is the signal to
+  write one from this walk's own evidence, not a reason to leave the gap for next time.
 - **Re-litigating an accepted divergence** — a non-null `acceptedDivergence` on a diff entry
   (or a `divergence` annotation on the element behind a spec/internal finding) means this exact
   question was already reasoned through and ratified. Classify it as Accepted divergence and

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-design
-em-version: 1.21.0
+em-version: 1.22.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
@@ -234,7 +234,10 @@ For each slice:
 1. Hold a Socratic deep-dive to fill every section of `../event-modeling-shared/templates/slice.md`:
    intent, trigger/actor,
    command fields (types & rules), event(s) + payload (mark immutable facts) — field names and
-   types go into the `.em`, the doc's tables are generated from it — invariants
+   types go into the `.em`, the doc's tables are generated from it (on a `public` element, a
+   field's type must be the fixed scalar table, a declared `type`, a declared identity `scalar`,
+   or a declared `enum` — see `em-dsl.md`'s Strict public types/Identity scalars/Enums
+   sections) — invariants
    (give each a stable ID — see **Invariants live in the model** below), Given/When/Then scenarios (happy path + rule boundaries + edge cases),
    alternate/error flows (retries, idempotency, compensations), non-functional requirements
    (security/authz, PII/compliance, performance/SLA), read models affected, open questions. Park

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-discover
-em-version: 1.21.0
+em-version: 1.22.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-engagement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-engagement
-em-version: 1.21.0
+em-version: 1.22.1
 description: >-
   Use when leading an engagement: building a named set of ratified event-modeling slices
   (`em engagement`) into one independent PR per slice, each against main, by dispatching the

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

@@ -47,6 +47,7 @@ Validator (em-validator, <model>):
 | diff footprint inside the slice package | PASS |
 | no diff under `slices/**`, `*.em`, `constitution.md`, `engagements/` | PASS |
 | PR body cites the slice doc | PASS |
+| `conformance/bindings/<key>.yaml` exists + `em conform bindings check --slice <key> --exit-code` | PASS |
 
 Reviewer (em-reviewer, <model>): <findings list verbatim, or NO FINDINGS>
 Critic (em-critic, <model>): <findings list verbatim, or NO FINDINGS>

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-implement
-em-version: 1.21.0
+em-version: 1.22.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
@@ -28,8 +28,10 @@ ships in the originating doc's PR); ship the endpoint a
 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, 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`.
+`ready-to-implement` slice); write or update the slice's `conformance/bindings/<key>.yaml`
+(GH #450, `docs/bindings.md`'s schema) and verify it with `em conform bindings check <model>.em
+--repo <path> --slice <key> --exit-code` before calling the slice done; 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
 — stack and architectural shape (including which implementation skill each slice pattern routes

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

@@ -300,6 +300,20 @@ or seem small — see §10.
   you didn't touch the `.em`, so this only fails if something else broke).
 - Nothing between the slice doc and the code was committed as a source of truth (see §9 —
   work containers are ephemeral; generated or symlinked specs are renderings).
+- **The slice's bindings file is written or updated** (GH #450): `conformance/bindings/<slice-
+  key>.yaml`, beside the model, per [`docs/bindings.md`](https://github.com/milehimikey/em/blob/main/docs/bindings.md)'s
+  schema. You just wrote the code — you know which file and identifier anchors each element
+  this slice's doc declares (`ref: <kind>.<slug>`, bare, no `<slice-key>/` prefix) and each
+  `INV-<MNEMONIC>-n` invariant's enforcement and test sites. This is a file contract, not an
+  `em`-run write: author or hand-edit the YAML directly, the same way you'd write any other file
+  in your PR. Verify it before calling the slice done:
+  ```bash
+  em conform bindings check <model>.em --repo <path> --slice <slice-key> --exit-code
+  ```
+  Exit 0 is required — fix the file (a wrong `ref`, a stale `file`/`identifier` pair) rather than
+  shipping a binding that doesn't check out. A continuation key (§5, an `again` view instance)
+  has no bindings file of its own; its elements and invariants are bound inside the originating
+  slice's file alongside the rest of that doc's bindings.
 
 ## 6. At merge: the lifecycle flip
 

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-review
-em-version: 1.21.0
+em-version: 1.22.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

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

@@ -15,7 +15,7 @@ Keep `.em` files focused on **structure**; put deep design in markdown linked vi
 em --version                                                        # print the installed em version
 em init [file]                                                      # scaffold a starter .em model
 em init [file] -f, --force                                          # overwrite if the file exists
-em scaffold <name>                                                  # scaffold a full project: <slug>/<slug>.em, README.md, .event-modeling.md, and constitution.md (the implementation constitution — skipped, with a note, in a spec-kit project, where `.specify/memory/constitution.md` IS that document) (see docs/cli.md — for just a starter .em, use `em init`; for a multi-model project, pass --under to nest it under a shared parent directory)
+em scaffold <name>                                                  # scaffold a full project: <slug>/<slug>.em, README.md, .event-modeling.md, and constitution.md (the implementation constitution — skipped, with a note, in a spec-kit project, where `.specify/memory/constitution.md` IS that document), plus the standard slices/, contracts/, model-versions/ and conformance/bindings/ directories (each seeded with a one-line README naming what lands there and which command writes it, instead of a .gitkeep) (see docs/cli.md — for just a starter .em, use `em init`; for a multi-model project, pass --under to nest it under a shared parent directory)
 em scaffold <name> -f, --force                                      # overwrite the directory's contents if it already exists
 em scaffold <name> --under <dir>                                    # parent directory to scaffold into — writes <dir>/<slug>/ instead of ./<slug>/, the supported multi-model layout (docs/cli.md, "Multi-model projects"): one directory per model, so each model's slices/ never collides with a sibling model's
 em render <file>                                                    # transpile a model and render it (or emit DOT)
@@ -37,6 +37,8 @@ em api generate <file> --stdout                                     # print the
 em api check <file>                                                 # is the committed contract current? With --base, annotate each public-surface change since that revision additive or breaking (annotation only — exits 1 only when stale)
 em api check <file> --base <rev>                                    # git revision to diff the public surface against
 em api check <file> --json                                          # print a JSON document instead of the text report (see docs/cli.md)
+em api surface <file>                                               # the model's public commands, events, views and reachable declared types as a versioned JSON document for companion tools (GH #448, see docs/cli.md)
+em api surface <file> --json                                        # print a JSON document instead of the text listing (see docs/cli.md)
 em typespec <file>                                                  # DEPRECATED alias of `em api generate --stdout` (use em api generate)
 em typespec <file> -o, --out <path>                                 # write to a file instead of stdout
 em diff <old> [new]                                                 # compare two models structurally (two files, or one file across git revisions)
@@ -142,6 +144,11 @@ em conform-supersede <file> <report-path> --locus <locus>           # who/what t
 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 conform bindings check <file>                                    # verify every per-slice bindings manifest (conformance/bindings/<slice-key>.yaml, see docs/bindings.md): each bound element's `ref` resolves against the compiled model, and each bound `file` exists under --repo and contains its `identifier` as a plain substring (grep-level only, never code-parsed — language-agnostic). Distinct failure kinds: an unknown `--slice` key, a missing bindings file, malformed YAML, an unknown slice named inside a file, and an unknown element ref. Advisory only — exit code stays 0 unless --exit-code is given and a binding failed (the opt-in CI gate, same posture as `em refs --reachable-from`).
+em conform bindings check <file> --repo <path>                      # path to the target codebase (bound `file`s resolve relative to it; never required to be a git repository)
+em conform bindings check <file> --slice <key>                      # check only this slice's bindings file (default: every conformance/bindings/*.yaml)
+em conform bindings check <file> --json                             # print a JSON document instead of the text report
+em conform bindings check <file> --exit-code                        # exit 1 if any binding failed (git-diff convention) — the opt-in CI gate
 em discover triage-check <file>                                     # validate a discovery/prd-triage.json (prdTriageSchemaVersion 1.0): shape, the shipped rubric version, every statement/storyline quote appearing verbatim in the input document, and every statement carrying a category, an outcome and (modeled/rewritten) a group + storyline — exit 1 on errors. The discover skill writes this file directly; this is how a headless run verifies it.
 em discover triage-check <file> --source <path>                     # the input PRD/spec to check quotes against (default: the file's own `source`, relative to it)
 em discover triage-check <file> --markdown                          # after a passing check, print the Markdown view of the record instead of the summary
@@ -242,17 +249,23 @@ em engagement new <file> <slug> --parallel <n>                      # how many s
 em engagement new <file> <slug> --by <name>                         # who created the engagement (createdBy)
 em engagement new <file> <slug> --tracking <key>                    # an issue-tracker key or URL the slice PRs cite (a slice doc's own tracking: wins)
 em engagement new <file> <slug> --pr-title <template>               # PR title template for the slice PRs; {key} = tracking key, {slice} = slice name, {sliceKey} = slice key (default "{key}: {slice}", or "{slice}" without a key)
+em engagement new <file> <slug> --context-doc <path>                # repo-relative path to a document implementers need beyond the slice doc — the constitution, an NFR doc, an ADR (repeatable; GH #455)
 em engagement new <file> <slug> --force                             # overwrite an existing engagement file with this slug
 em engagement plan <file> <slug>                                    # the engagement's build plan: dependency levels over model.edges (loops-to excluded), and per slice its readiness, branch impl/<key>, base (always main — MIL-280), and any hold
 em engagement plan <file> <slug> --json                             # print a JSON document instead of text (same document as the MCP engagement_plan tool)
 em engagement foundation <file> <slug>                              # GH #240: is the foundation PR (implement.md §8) actually in the code for the events this engagement's slices emit and consume? A text scan of --code: an event is present when a file carries an identifier derived from its name (OrderPlaced / order_placed / ORDER_PLACED / order-placed), its model fields and tag fields are then looked for in those files. Per event: present | incomplete (missing-field / missing-tag, named) | missing-event — so "foundation absent" and "foundation incomplete" are different reports. Exits 1 unless every event is present. Proves the contract was written down, not that it type-checks
 em engagement foundation <file> <slug> --code <dir>                 # the target repository (or the directory the constitution's "where a slice's code lives" rule points at)
 em engagement foundation <file> <slug> --json                       # print a JSON document instead of text (same document as the MCP engagement_foundation tool)
-em engagement set <file> <slug> <key>                               # the only write path to the Ledger: set one slice's state (and optionally branch/base/pr); idempotent; merged is terminal; --state held records a human hold
-em engagement set <file> <slug> <key> --state <state>               # one of: planned | building | validating | review | awaiting-merge | merged | held | gap
-em engagement set <file> <slug> <key> --branch <name>               # the slice's branch
-em engagement set <file> <slug> <key> --base <name>                 # the branch the slice's PR targets
-em engagement set <file> <slug> <key> --pr <url>                    # the slice's PR URL
+em engagement brief <file> <slug>                                   # GH #454: a deterministic, self-contained per-slice work brief for implementers em does not control (a ticket-driven cloud agent) — the bound slice doc verbatim (or the model's own elements when there is none), model context from the edge list, the public-contract surface, a definition-of-done (bindings manifest skeleton + conform check + isolation + PR title), and the engagement's context: documents. One brief per engagement slice unless --slice narrows it
+em engagement brief <file> <slug> --slice <key>                     # only this slice's brief (export key, display name, or unique prefix)
+em engagement brief <file> <slug> --inline-context                  # embed each context document's full text instead of just its path
+em engagement brief <file> <slug> --json                            # print a JSON document instead of text (same document as the MCP engagement_brief tool)
+em engagement set <file> <slug> [key]                               # the only write path to the Ledger: set one slice's state (and optionally branch/base/pr); idempotent; merged is terminal; --state held records a human hold. Or, on its own (no slice key), --context-doc replaces the engagement-level context: list (GH #455)
+em engagement set <file> <slug> [key] --state <state>               # one of: planned | building | validating | review | awaiting-merge | merged | held | gap
+em engagement set <file> <slug> [key] --branch <name>               # the slice's branch
+em engagement set <file> <slug> [key] --base <name>                 # the branch the slice's PR targets
+em engagement set <file> <slug> [key] --pr <url>                    # the slice's PR URL
+em engagement set <file> <slug> [key] --context-doc <path>          # repo-relative path to a document implementers need beyond the slice doc (repeatable; replaces the whole engagement-level context: list; GH #455)
 em engagement status <file> <slug>                                  # the Ledger joined with each slice doc's current status, plus whether the engagement is closable
 em engagement status <file> <slug> --json                           # print a JSON document instead of text (same document as the MCP engagement_status tool)
 em engagement close <file> <slug>                                   # set status: closed — refuses unless every slice is merged (recorded or inferred) or gap
@@ -339,6 +352,8 @@ slice "Name" [source "url"] {    # one vertical time step (a column); source is
 arrow From Element -> To Element    # explicit cross-slice edge (overrides inferred flow)
 
 type Name { field: Type, ... }      # named structured type, reusable from any field (see Named types)
+scalar Name: base                   # identity alias over a public scalar table entry (see Named types)
+enum Name { member, ... }           # closed named value set, reusable from any field (see Named types)
 ```
 
 ### Element kinds (8 keywords, nothing else)
@@ -607,6 +622,31 @@ how tree/recursive data (categories, org charts, comment threads, BOMs) gets exp
 fields and ordinary element fields alike) — `{ name, ref, array }` when resolved, `null`
 otherwise. `em diff` tracks types added/removed and field changes on surviving types.
 
+**Identity scalars** (GH #477): `scalar Name: base` declares an identity alias over one public
+scalar table entry (`base`, case-insensitive) — so a `public` field can carry a domain name on
+the wire (`orderId: OrderId`) instead of degrading to the bare table type (`uuid`) to satisfy
+[Strict public types](#strict-public-types). Reference it bare or `Name[]`, same as a declared
+`type`; on a `public` element it satisfies the strict table directly, on an internal element it
+resolves opportunistically. `em validate` errors on an unknown `base`, a redeclared name, or a
+name colliding with a declared `type` (either direction). `em api generate` declares a used
+scalar once, after the table scalars, extending the formatted table scalar
+(`scalar OrderId extends Uuid;`) or the core type (`scalar Sku extends string;`) — a model with
+no `scalar` emits unchanged. `em export` adds `model.scalars[]` and an additive `scalarRef` field
+key, mutually exclusive with `typeRef`.
+
+**Enums** (GH #478): `enum Name { member, … }` declares a closed, named value set — members are
+bare identifiers or quoted strings, in declaration order. Reference it bare or `Name[]`, same
+as a declared `type`/`scalar`; on a `public` element it satisfies the strict table directly, on
+an internal element it resolves opportunistically. `em validate` errors on an empty enum, a
+case-insensitive duplicate member, a redeclared name, or a name colliding with a declared
+`type`/`scalar` (either direction). `em api generate` declares a used enum once, members in
+declaration order (`enum OrderStatus { placed, shipped }`), after the scalar declarations and
+before type blocks — a member that isn't a bare TypeSpec identifier emits as a quoted string
+literal; a model with no `enum` emits unchanged. `em export` adds `model.enums[]` and an
+additive `enumRef` field key, mutually exclusive with both `typeRef` and `scalarRef`. `em api
+check --base` judges a surviving enum's member changes by role: removed/renamed is breaking on
+an output, added is breaking on an input, additive on a pure output.
+
 ### Swimlane band order (top → bottom)
 Header row → **Automation** (only if used) → **persona** rows (in declared order) → **API**
 (commands + views share this lane) → **context** rows (in declared order).
@@ -937,11 +977,17 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `doc-names-unfed-event` | warning | Doc names an event its view does not read | Add the event to the view's `from` in the model (if the edge is real), or fix the doc's Source column / scenario. |
 | `doc-omits-fed-event` | warning | Doc omits an event its view reads | Mention the event in the view's Source column (run `em slice sync`), or drop it from the view's `from`. |
 | `duplicate-element-ref` | warning | Duplicate element ref | Rename the element so its export ref is unique. |
+| `duplicate-enum-ref` | warning | Duplicate enum ref | Rename the enum so its export ref is unique. |
 | `duplicate-model-key` | warning | Duplicate model key | Give each model a unique `model "Name"` so its key (and every cross-model ref) is stable. |
 | `duplicate-name` | warning | Duplicate name | Rename one of the duplicates. |
+| `duplicate-scalar-ref` | warning | Duplicate scalar ref | Rename the scalar so its export ref is unique. |
 | `duplicate-slice-name` | warning | Duplicate slice name | Rename the slice so its export key is unique. |
 | `duplicate-type-name` | warning | Duplicate type name | Rename one of the duplicate `type` declarations. |
 | `duplicate-type-ref` | warning | Duplicate type ref | Rename the type so its export ref is unique. |
+| `enum-duplicate-member` | error | Enum duplicate member | Remove or rename the duplicate member — members are compared case-insensitively. |
+| `enum-duplicate-name` | error | Enum duplicate name | Declare the enum once; rename or remove the duplicate `enum` block. |
+| `enum-empty` | error | Empty enum | Give the enum at least one member, or remove the declaration. |
+| `enum-name-collision` | error | Enum/type/scalar name collision | Rename the `enum` or the colliding `type`/`scalar` so the names no longer collide — a name can't mean both at once. |
 | `fields-completeness/event-field-no-source` | warning | Event field not from a command | Add the field to a command that records the event (in any slice), mark it assigned if the handler sets it, or remove it from the event. |
 | `fields-completeness/view-field-no-source` | warning | View field with no source | Add the field to a source event, or remove it from the view. |
 | `frontmatter-coherence-implemented-without-link` | warning | Implemented without a link | Add `implementedIn` once the slice ships. |
@@ -974,6 +1020,9 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `reaction-from-future-view` | error | Backward timeline (reaction reads a future view) | Declare the view in or before the reaction's slice. |
 | `reaction-from-unresolved` | error | Unknown read-model source | Project the event into a view first, or fix the `from` reference. |
 | `retry-slice-of` | warning | Slice only retries another command | Re-fire the same reaction via `view … again from` the retry-scheduled event; a different actor's override is its own slice with its own command (docs/patterns.md#automation). |
+| `scalar-duplicate-name` | error | Scalar duplicate name | Declare the scalar once; rename or remove the duplicate `scalar` line. |
+| `scalar-type-name-collision` | error | Scalar/type name collision | Rename the `scalar` or the `type` so the two names no longer collide — a name can't mean both at once. |
+| `scalar-unknown-base` | error | Scalar unknown base | Point `base` at one of the public scalar table's names (string, text, int, long, decimal, boolean, uuid, date, datetime, duration, bytes), case-insensitive. |
 | `scenario-then-not-outcome` | warning | Scenario's Then names no event or rejection | Make the Then bullets name the event(s) the command records, or the rejection/error it returns. |
 | `scenario-when-not-command` | warning | Scenario's When does not name the slice's command | Make the When bullet name the slice's command (for a reaction slice: the command, the reaction element, or a view of the slice) — each scenario exercises exactly one command. For a Translation, naming the translation element satisfies it. |
 | `seam-consumer-not-reaction` | error | Seam consumer is not a reaction | Point `to` at a translation/automation element (or a slice containing exactly one). |

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

@@ -173,25 +173,36 @@ including sessions started from bare `/event-modeling`.
   <model-name>.svg         # render target for em watch
   README.md                # overview + slice index (from templates/model-readme.md)
   .event-modeling.md       # resumable state (from templates/state.md)
+  constitution.md          # implementation constitution (skipped, with a note, in a spec-kit project)
   slices/<slice-name>.md   # one rich slice doc per slice (from templates/slice.md)
-  conformance/<date>-report.md
-                           # conform-phase reports (from templates/conformance-report.md)
+  contracts/<model-name>.tsp
+                           # `em api generate`'s generated TypeSpec contract — never hand-edit
+  model-versions/v<N>.json # `em model version bump`'s design-version snapshots
+  conformance/
+    <date>-report.md       # conform-phase reports (from templates/conformance-report.md)
+    bindings/<slice-key>.yaml
+                           # per-slice bindings manifests (`em conform bindings check`, GH #449)
   <model-name>-asis.em     # conform-phase scratch model, regenerated per run — git-ignore this
 ```
 
-When creating a new model, run `em scaffold <model-name>` — it creates `<model-name>/` and
-writes all three starter files in one step (`<model-name>.em`, `README.md`,
-`.event-modeling.md`), filling the Model Name/model-name placeholders and the state file's
-mechanical fields (model path, `Current phase: discover`, `Current step: 1`, dates) for you, so
-there's nothing left to hand-copy or fill in. Refuses if `<model-name>/` already exists; pass
-`--force` to overwrite. You'll
-usually replace the scaffolded `.em`'s content as the discovery conversation builds up the real
-model — it starts out as the same starter model `em init` writes, titled from `<model-name>`.
-`slices/*.md` and `conformance/` aren't part of `em scaffold`; they come from the `slice` and
-`conform` phases (`event-modeling-design` and `event-modeling-conform`). The `conformance/`
-directory and `<model-name>-asis.em` only appear once the `conform` phase runs; `em conform-scope
---seed-asis` creates `<model-name>-asis.em` and gitignores `*-asis.em` for you (see
-`event-modeling-conform`'s `reference/conform.md`) — it's scratch, never committed.
+When creating a new model, run `em scaffold <model-name>` — it creates `<model-name>/`, writes
+the four starter files in one step (`<model-name>.em`, `README.md`, `.event-modeling.md`,
+`constitution.md`), filling the Model Name/model-name placeholders and the state file's
+mechanical fields (model path, `Current phase: discover`, `Current step: 1`, dates) for you, and
+also creates the standard `slices/`, `contracts/`, `model-versions/` and `conformance/bindings/`
+directories — each seeded with a one-line README (never a `.gitkeep`) naming what lands there and
+which command writes it. There's nothing left to hand-copy or fill in. Refuses if
+`<model-name>/` already exists; pass `--force` to overwrite. You'll usually replace the
+scaffolded `.em`'s content as the discovery conversation builds up the real model — it starts out
+as the same starter model `em init` writes, titled from `<model-name>`.
+Those directories exist from the start, but their real content doesn't — `slices/*.md` slice
+docs come from the `slice` phase (`event-modeling-design`), `conformance/<date>-report.md`
+reports from the `conform` phase (`event-modeling-conform`), and `contracts/*.tsp` /
+`model-versions/*.json` / `conformance/bindings/*.yaml` only once `em api generate` / `em model
+version bump` / an implementing agent's bindings manifest actually run. `<model-name>-asis.em` is
+separate conform-phase scratch, not part of the scaffold at all; `em conform-scope --seed-asis`
+creates it and gitignores `*-asis.em` for you (see `event-modeling-conform`'s
+`reference/conform.md`) — it's scratch, never committed.
 
 ### Multi-model projects
 

package/.claude-plugin/marketplace.json

@@ -1,9 +1,9 @@
 {
-  "name": "em-1-21-0",
+  "name": "em-1-22-1",
   "owner": {
     "name": "Mike Key"
   },
-  "description": "em v1.21.0: the Event Modeling skill bundle and MCP server as a Claude Code plugin.",
+  "description": "em v1.22.1: the Event Modeling skill bundle and MCP server as a Claude Code plugin.",
   "plugins": [
     {
       "name": "em",