@milehimikey/em 1.21.0 → 1.22.0

package/plugin/shared/reference/operating-principles.md

@@ -174,25 +174,36 @@ including sessions started from bare `/em: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 (`em:design` and `em: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
-`em: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 (`em:design`), `conformance/<date>-report.md`
+reports from the `conform` phase (`em: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 `em:conform`'s
+`reference/conform.md`) — it's scratch, never committed.
 
 ### Multi-model projects
 

package/plugin/skills/conform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conform
-em-version: 1.21.0
+em-version: 1.22.0
 description: >-
   Use when checking a ratified event model (and its slice docs) for drift against the codebase
   that implements it — advisory only, never a gate, never an unprompted edit — or when walking
@@ -29,9 +29,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/plugin/skills/conform/reference/conform.md

@@ -95,7 +95,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": ["..."] }
 ```
 
@@ -105,6 +105,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
@@ -120,6 +134,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**:
@@ -140,6 +179,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
@@ -162,8 +215,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
@@ -406,7 +466,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
@@ -448,6 +513,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
@@ -458,6 +530,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/plugin/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-em-version: 1.21.0
+em-version: 1.22.0
 description: >-
   Use when structuring a draft event model into swimlanes and the four patterns (State Change,
   State View, Automation, Translation), evaluating a model's structural completeness, or writing

package/plugin/skills/discover/SKILL.md

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

package/plugin/skills/engagement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: engagement
-em-version: 1.21.0
+em-version: 1.22.0
 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/plugin/skills/engagement/reference/engagement.md

@@ -48,6 +48,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/plugin/skills/event-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling
-em-version: 1.21.0
+em-version: 1.22.0
 description: >-
   Use when the user runs `/em: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/plugin/skills/implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implement
-em-version: 1.21.0
+em-version: 1.22.0
 description: >-
   Use when building a single ratified event-modeling slice (status: ready-to-implement) into
   merged, tested code — the one phase where the agent builds rather than facilitates. Gates on
@@ -29,8 +29,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/plugin/skills/implement/reference/implement.md

@@ -301,6 +301,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/plugin/skills/review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review
-em-version: 1.21.0
+em-version: 1.22.0
 description: >-
   Use when starting em's live browser viewer (`em watch --serve`) so a team can watch a model
   update in real time, or facilitating a SCHEDULED stakeholder walkthrough that steps through