@milehimikey/em 1.20.0 → 1.22.0

package/plugin/shared/reference/em-dsl.md

@@ -16,14 +16,15 @@ 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)
 em render <file> -o, --out <path>                                   # output path (extension picks the format)
 em render <file> -T, --format <fmt>                                 # output format (svg, png, pdf, ...)
 em render <file> --slice <name>                                     # render only this slice, redrawn in its own canonical pattern shape (default out: slices/<kebab-slug>.svg)
-em render <file> --storyline <name>                                 # render only this storyline: its slices in order, preceded by dimmed stub columns for what they read from outside it (and the end state of a storyline it comes `after`) (default out: storylines/<kebab-slug>.svg)
+em render <file> --storyline <name>                                 # render only this storyline: its own slices in order, nothing from outside it (default out: storylines/<kebab-slug>.svg)
+em render <file> --map                                              # render every storyline to storylines/<kebab-slug>.svg plus a draggable canvas of them all, with the flow between storylines, at storylines/map.html (-o picks the html path)
 em render <file> --emit-dot                                         # print the generated DOT instead of rendering
 em render <file> --keep-empty-lanes                                 # keep the API lane even when empty
 em export <file>                                                    # export a versioned JSON snapshot of the normalized model
@@ -37,6 +38,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)
@@ -71,6 +74,7 @@ em slice stub-all <file> --implemented-in <url>                     # PR/commit
 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 index <file> --full                                        # every lifecycle column (reviewed/ratified/owner/tracking/implemented/conformed) instead of the reader's five
 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). Applies only to a `ready-to-implement` doc (MIL-277: a `draft`/`reviewed` doc refuses — ratify first). Also records the shipped version beside the link (MIL-284): `shippedVersion:`, `shippedRef:` (the doc's `ratifiedRef:`, when it has one) and `shippedOn:`, and opens the next version as a `draft` when an Open Question was deferred to it (MIL-283). Idempotent on the same URL — also after that draft opened; refuses to overwrite a different one; never touches the doc body except to re-open those deferred questions
 em slice mark-implemented <file> <slice-key> <pr-url> --on <date>   # merge date recorded as `shippedOn:`, YYYY-MM-DD (default: today, local date; MIL-284)
 em slice mark-implemented <file> <slice-key> <pr-url> --json        # print a JSON document instead of text: { path, changed, implementedIn, nextDraft: { version, reopened[] } | null } (GH #285)
@@ -141,6 +145,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
@@ -241,17 +250,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
@@ -276,15 +291,25 @@ em mcp                                                              # start an M
 em skill install                                                    # copy the event-modeling skill bundle into .claude/skills/ (event-modeling, event-modeling-discover/-design/-implement/-conform/-review, event-modeling-shared); across a structural bundle change (e.g. the MIL-157 split of the old single event-modeling/ directory into this six-directory bundle), `em skill sync` is the migration path — --force now performs the same reconcile (MIL-180)
 em skill install -f, --force                                        # overwrite an existing installation, reconciling added/updated/removed files within the bundle's own managed directories the same way `em skill sync` does — never touching an unrelated sibling skill (MIL-180)
 em skill install --no-agents-md                                     # skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)
+em skill install --skills-dir <dir>                                 # where the vendored skill bundle lives, relative to the repo root (default .claude/skills; .agents/skills when that exists and .claude/skills does not — GH #412)
+em skill install --agents-dir <dir>                                 # where the four em sub-agent definitions live, relative to the repo root (default .claude/agents, or .agents/agents beside an .agents/skills bundle — GH #412)
 em skill sync [path]                                                # update the vendored .claude/skills/ event-modeling skill bundle in [path] to match the installed em package (overwrites unconditionally; local edits are never merged, MIL-93)
 em skill sync [path] --no-agents-md                                 # skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)
+em skill sync [path] --skills-dir <dir>                             # where the vendored skill bundle lives, relative to the repo root (default .claude/skills; .agents/skills when that exists and .claude/skills does not — GH #412)
+em skill sync [path] --agents-dir <dir>                             # where the four em sub-agent definitions live, relative to the repo root (default .claude/agents, or .agents/agents beside an .agents/skills bundle — GH #412)
 em skill check [path]                                               # check [path]'s em skills for drift against the installed em package: the em Claude Code plugin's pin (settings + this machine's marketplace registry) when the repo declares it, and the vendored .claude/skills/ bundle when present; exits non-zero on any mismatch (CI-ready, MIL-93, MIL-231)
 em skill check [path] --json                                        # print a JSON document instead of the text report (see docs/cli.md)
 em skill check [path] --ci                                          # also fail (exit 1) when the declared plugin is not registered on this machine (implied by CI=true in the environment); without it that finding prints the install commands on stderr and exits 0
+em skill check [path] --skills-dir <dir>                            # where the vendored skill bundle lives, relative to the repo root (default .claude/skills; .agents/skills when that exists and .claude/skills does not — GH #412)
+em skill check [path] --agents-dir <dir>                            # where the four em sub-agent definitions live, relative to the repo root (default .claude/agents, or .agents/agents beside an .agents/skills bundle — GH #412)
 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). Give it a system.yaml (or its directory) instead of a model to cover every model in the system: one workflow, per-model jobs, a conform matrix (MIL-233)
 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, or a managed block generated for a different set of models
 em ci init <model> --check                                          # verify both files match the current preset; exit non-zero on drift without writing (CI)
+em storyline split <file>                                           # move each inline `storyline "X" { … }` block into its own storyline model file <slug>/<slug>.em (a `storyline "X" [source]` header, then the block's slices) and leave the one-line declaration `storyline "X" [after "Y"]` in the root (GH #421). Slice docs stay under the root's slices/. A storyline declared in several blocks is left alone (merge them first)
+em storyline split <file> --storyline <name>                        # split only this storyline
+em storyline split <file> --dry-run                                 # print what would be written without touching anything
+em storyline split <file> -f, --force                               # overwrite a storyline model file that already exists
 em storyline suggest <file>                                         # advisory (GH #290): propose `storyline` blocks for a model that has none — one per distinct slice `source "url"`, the remaining slices grouped by the view-instance chains (`again`) they feed — printed as a unified diff on stdout (apply with `patch -p1` or `git apply`); never writes the model
 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
@@ -311,12 +336,14 @@ context Name                     # an event swimlane row (bounded context / aggr
 storyline "Name" [source "url"] [after "Other"] {   # optional chapter grouping slices (see Storylines)
   slice "Name" { ... }
 }
+storyline "Name" [after "Other"] [in "path.em"]      # a storyline MODEL: its slices live in <slug>/<slug>.em (see Storylines)
 
 slice "Name" [source "url"] {    # one vertical time step (a column); source is optional
   ui   Free Text @Persona        # screen; @Persona picks its row (defaults to first/"User")
   command Free Text              # state-changing request (API band)
   invariant INV-ORD-1 "Rule"     # rule guarding the command/event just above (see Clauses)
   view Free Text from "Event A", "Event B"   # read model fed by event(s)
+  view Free Text from "Event A" updates from "Event B", "Event C"   # B, C keep rows current: read, never drawn (see Clauses)
   view Free Text again from "Event C"        # later instance of an evolving read model (see Clauses)
   event Free Text @Context       # recorded fact; @Context picks its row (defaults to "Domain")
   processor Free Text from "View"   # automation; aliases: automation | saga | translation
@@ -360,6 +387,14 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   previous instance of V that also reads E), and EVERY site needs a reader at or after it (add `view V again from "E"`
   after the last site, or `event-unread` warns for that site). The same name in a different context
   is still a `duplicate-name` warning.
+- **`updates from "Event", …`** (views only, GH #414): the subset of a view's sources that only keep a
+  row current or remove it (a due date moved, an address changed, a loan returned). They are folded
+  into the view's `from` for every check — `derived from`, completeness, the generated built-from
+  list — but never drawn as arrows: the diagram shows the line from the event that puts work on the
+  list, and lists the rest under "Kept current by". The author chooses the triggers: `view Holds To
+  Fulfill from "Hold Placed", "Tool Returned" updates from "Hold Collected", "Hold Cancelled"`.
+  Valid on an `again` instance too. A to-do view with more than one or two inbound arrows is missing
+  this split.
 - **`again`** (views only): `view <Name> again [from "Event", …]` declares a later instance of an
   already-declared read model — the forward-only device for a view that evolves as later events
   land. Instances are ONE logical view: the first declaration owns the `note` binding; each
@@ -550,8 +585,15 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   Slices keep their file-order timeline position; a slice outside any storyline is allowed;
   storylines don't nest and a repeated name continues that storyline (its slices join it; a continuation may not add or change
   `source`/`after` — parse error). The full render draws a
-  labelled band above the slice headers; `em render --storyline "Name"` draws one story alone, with the
-  elements it reads from outside as dimmed stub columns. `em export` carries `slice.storyline` and
+  labelled band above the slice headers; `em render --storyline "Name"` draws one story alone — its own
+  slices only, nothing from outside it — and `em render <root>.em --map` puts every story's real
+  diagram on one draggable canvas with the flow between stories (`after` thick, reads dashed and
+  labelled). **Storyline models (GH #421):** `storyline "Name" [after "Other"] [in "path.em"]` with no
+  body declares a storyline whose slices live in `<slug>/<slug>.em` — a file that starts with
+  `storyline "Name" [source "url"]` and holds slice blocks only — with its docs in `<slug>/slices/`;
+  the root is the compile unit (always give em the root), and `em storyline split <root>.em` turns
+  inline blocks into files, moving each story's docs. A storyline that reads another declares `after`
+  it (`storyline-reads-without-after`). `em export` carries `slice.storyline` and
   `model.storylines[]`; `em query slices --storyline`; `em slice index` adds a Storyline column. Once
   any storyline exists a slice outside every one is the advisory warning `slice-outside-storyline`.
   `after "<other>"` reads the storyline as if its slices followed the referenced storyline's last
@@ -877,6 +919,7 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 <!-- GENERATED:validate-rules:start -- run `npm run docs:generate` to refresh, do not hand-edit -->
 | Code | Severity | Title | Fix |
 |---|---|---|---|
+| `again-restates-sources` | warning | Continuation restates sources an earlier instance already read | Name only the events that changed the view since the previous instance on the `again` line; the view's field sources are the union across instances, so nothing is lost (docs/dsl.md#view--again). |
 | `alternative-events-no-command` | error | Alternative events without a command | Add the command whose decision records one of the alternatives, in the same slice. |
 | `arrow-backward` | error | Backward arrow | Restructure so the target comes later. |
 | `arrow-unresolved-source` | error | Arrow source unresolved | Fix the arrow's source name. |
@@ -917,6 +960,7 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `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. |
 | `frontmatter-invalid` | warning | Invalid or missing frontmatter | Add the required frontmatter keys, or add a frontmatter block. |
+| `frontmatter-status-unrecognized` | warning | Unrecognized slice status | Set `status:` to one of draft, reviewed, ready-to-implement, implemented. |
 | `grid-collision` | error | Band collision | Split the colliding elements into separate slices. |
 | `invariant-without-scenario` | warning | Invariant cited by no scenario | Cite the INV id in the Given/When/Then (or title) of the scenario that exercises it, or add one. |
 | `invariants/declared-in-both` | warning | Invariant declared in the model and in a slice doc | Keep the model's `invariant` line; in the doc, cite the ID and elaborate instead of restating it as a `**INV-…:**` rule. |
@@ -960,6 +1004,7 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `storyline-after-cycle` | error | Storyline `after` cycle | Remove an `after` clause so no storyline comes after itself. |
 | `storyline-after-out-of-order` | error | Backward timeline (storyline declared above the one it comes after) | Move the storyline block below the storyline it comes `after`, or restructure the feed. |
 | `storyline-after-unknown` | error | `after` names an unknown storyline | Name a storyline declared in this model, or drop the `after` clause. |
+| `storyline-reads-without-after` | warning | Storyline reads another without declaring `after` it | Add `after "<the storyline it reads>"` to the reading storyline (or to one between them); if the two stories are parallel on purpose, accept it on the shape exit gate (docs/storyline.md). |
 | `system-manifest-invalid` | error | Seam manifest invalid | Fix the manifest: `systemSchemaVersion: "2.0"`, `models:` with a readable `source` per model, and nothing else (`seams:`/`owner:` moved into the models — run `em upgrade`). |
 | `system-manifest-outdated` | warning | Seam manifest is schema 1.0 | Run `em upgrade <model>.em --apply` once: it moves `seams:` into `consumes` clauses and `owner:` onto each model header, and rewrites the manifest to 2.0. |
 | `system-model-key-mismatch` | error | Manifest model key differs from the export's `model.key` | Rename the manifest's `models:` key to the computed key the message prints. |

package/plugin/shared/reference/methodology.md

@@ -219,7 +219,11 @@ drift into **CRUD laid on a timeline**; these rules stop that. Quoted lines are
   reorganize are **secondary storylines** (chapters; Dilger: "one linear flow from left to right. No
   exceptions… Linearize it!", "Model one process at a time, each with its own clear ending"). Never one
   lifecycle block per entity. Name the main and every secondary storyline; a `storyline "Name" { … }`
-  block groups the slices (`dsl.md`, Storylines).
+  block groups the slices (`dsl.md`, Storylines). **A storyline is the unit a reader consumes, so it
+  is the unit an author edits too (GH #421):** the root model lists the storylines and their flow
+  (`storyline "Name" [after "Other"]`), and each story's slices live in `<slug>/<slug>.em` with its
+  docs in `<slug>/slices/`. Draft with inline blocks if that is faster, then `em storyline split
+  <root>.em` once the storylines are named — before docs are wired, so nothing moves twice.
 - **Build from walkthroughs first.** The story already lives in the spec's walkthroughs, use cases and
   user journeys. Build the timeline from those; the resource/API reference (OpenAPI, endpoint tables,
   migrations) fills only the operations no walkthrough touches, and is read last. Headless: a persona
@@ -333,12 +337,41 @@ drift into **CRUD laid on a timeline**; these rules stop that. Quoted lines are
   `view-lookup-source` is the mechanical, advisory half — it catches the cross-context cases with a few
   false positives; a within-context lookup (`Tool Checked Out` read only to learn whose loan a later
   event concerns) is invisible to it, so this check still has to be done by eye.
+  **Then split what is left into trigger and housekeeping** (Dilger: show the line from the event
+  that triggers the automation, not every event that touches its read model; GH #414). Of the
+  events a view legitimately reads, only the ones that **put work on the list** are the story — they
+  go in `from` and are drawn. Every event that merely **keeps a row current or removes it** (a due
+  date moved, an address changed, a loan returned) goes in `updates from`: still a source for
+  `derived from`, completeness and the generated built-from list, never an arrow. Write the to-do
+  list as `view Overdue Loans To Notify from "Tool Checked Out" updates from "Loan Extended",
+  "Neighbor Email Changed", "Tool Returned"`. The author chooses the triggers — `Holds To Fulfill`
+  keeps two (`from "Hold Placed", "Tool Returned"`) because both put a fulfillable hold on the
+  list. **Per-view check:** *which of these events is the reason this row appears? That is `from`;
+  everything else is `updates from`.* The render's "Kept current by" legend is the readback: if a
+  to-do view shows more than one or two inbound arrows, the split is missing. A State View that is
+  not a to-do list gets the same treatment — its screen's story is the event that creates the row.
 - **Write side: children belong in the parent's context** when the child's invariants are checks against
   the parent. A sub-resource schema shared across parent types is one event per parent on the parent's
   context, not a shared aggregate — check the spec's event reference, not its resource section. Where
   two slices record the same fact, repeat the event bare (same name, same context). *(em ruling)*
 - **Repeat the view after every command that changes it** (`again`, span-1 — see State View above), so
-  the reader sees the information arrive rather than a view at the end.
+  the reader sees the information arrive rather than a view at the end. **A continuation names only
+  what changed:** `view X again from "E"` lists the event(s) that changed the view since the previous
+  instance — never the originating instance's whole source list again. Field sources are the union
+  across instances, so restating loses nothing and only draws the same arrows twice;
+  `again-restates-sources` (GH #424) is the mechanical half.
+- **Storylines read as stories** (owner rulings 2026-11-03, after Dilger). (1) **A storyline that reads
+  another declares `after` it:** an event of story A feeding a view of story B means B comes after A
+  in the telling — write `storyline "B" after "A"` (or on a storyline between them); two stories that
+  really run in parallel read nothing from each other. `storyline-reads-without-after` (GH #420) is
+  the mechanical half. (2) **Review each story on its own render and on the canvas, never on the
+  full timeline:** `em render <root>.em --map` draws every storyline's real diagram as a frame with
+  the flow between stories (`after` thick, reads dashed and labelled by event); the full timeline is
+  for `em diff` and ordering checks, not for reading. A storyline render shows only the storyline —
+  nothing from outside it is drawn, so an inbound arrow you miss there is a connector on the canvas.
+  (3) **Housekeeping is not drawn** (`updates from`, above) and **continuations name only what
+  changed** (above): together these are what keeps a story's render to one line per cause. *(em
+  ruling, built on Dilger's "the line from the event that triggers it")*
 - **Outcomes are events of one slice** (Dilger: "One decision. One event. One state change."; one
   action with two outcomes is the legitimate exception): alternative events on one context in one slice
   (`event A | B @Ctx`, GH #278), failure as a scenario first, a chapter only when core (it changes what the user does next, or has

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/shared/reference/slice-doc-schema.md

@@ -57,7 +57,7 @@ to decide `frontmatter-invalid` without re-deriving frontmatter-shape rules of i
 | `schemaVersion` | integer | `1` (current dialect version) | its *value* is not read back by any `em` command today (reserved) — but its *presence* is required by `hasUsableFrontmatter()`: a doc omitting it is `frontmatter-invalid` (see below) |
 | `pattern` | string | `state-change` \| `state-view` \| `automation` \| `translation` | authored/informational only — `em catalog` and `em export` both derive pattern from the `.em` AST instead (`em export`'s `slice.pattern`, schema `1.4`) |
 | `swimlane` | string | free text, `<Persona> → <Context>` | display-only |
-| `status` | string, case-insensitive | `draft` \| `reviewed` \| `ready-to-implement` \| `implemented` | written by `em slice review` (→ `reviewed`, MIL-201), `em slice ratify`/`em slice reratify` (→ `ready-to-implement`) and `em slice mark-implemented` (→ `implemented`); read by `em catalog`, `em render`/`em watch` header coloring; joined into `em export`'s `slice.doc.status` (schema `1.4`); paired with `implementedIn` to compute `slice.doc.driftSignal` (schema `1.5`, MIL-85) and `em validate`'s frontmatter-coherence check (MIL-85 — see [validation.md#frontmatter-coherence](https://github.com/milehimikey/em/blob/main/docs/validation.md#frontmatter-coherence)) |
+| `status` | string, case-insensitive | `draft` \| `reviewed` \| `ready-to-implement` \| `implemented` | written by `em slice review` (→ `reviewed`, MIL-201), `em slice ratify`/`em slice reratify` (→ `ready-to-implement`) and `em slice mark-implemented` (→ `implemented`); read by `em catalog`, `em render`/`em watch` header coloring; joined into `em export`'s `slice.doc.status` (schema `1.4`); paired with `implementedIn` to compute `slice.doc.driftSignal` (schema `1.5`, MIL-85) and `em validate`'s frontmatter-coherence check (MIL-85 — see [validation.md#frontmatter-coherence](https://github.com/milehimikey/em/blob/main/docs/validation.md#frontmatter-coherence)); any other value is read as written but `em validate` warns `frontmatter-status-unrecognized` (GH #411) |
 | `version` | integer | positive integer, starts at `1` | joined into `em export`'s `slice.doc.version` (schema `1.4`, MIL-91) |
 | `implementedIn` | string | free text (PR/commit link) | joined into `em export`'s `slice.doc.implementedIn` (schema `1.4`, MIL-91); paired with `status` to compute `slice.doc.driftSignal` (schema `1.5`, MIL-85) and `em validate`'s frontmatter-coherence check (MIL-85 — see [validation.md#frontmatter-coherence](https://github.com/milehimikey/em/blob/main/docs/validation.md#frontmatter-coherence)) |
 | `split-from` | single ref | `<slice-key>@v<N>` | joined into `em export`'s `slice.doc.splitFrom` (schema `1.4`, MIL-91) and `em diff`'s `slice-added` entries (schema `1.6`, MIL-84); current-tree referential checks by `em validate` (MIL-84 — see [validation.md#lineage](https://github.com/milehimikey/em/blob/main/docs/validation.md#lineage)) |
@@ -473,6 +473,7 @@ re-run `em slice sync`.
 
 | Region | Section | Body |
 |---|---|---|
+| `em-slice-story` | right under `![Diagram](…)` | one line: `Step N of M in **<Storyline>** · after <Prev> · before <Next> · <Pattern>` (Prev and Next link to the neighbouring slices' docs; a continuation neighbour is named, not linked) — where the slice sits in its story; the one region `em slice sync` inserts when missing on an unsigned doc (see `em slice sync` in the CLI reference) |
 | `em-slice-command` | `## Command / Input` | `**Command:** \`Name\`` + `\| Field \| Type \| Required \| Rules / Validation \|` (Required is `no` for a `name?: Type` field) |
 | `em-slice-event` | `## Event(s) Emitted` | `**Event:** \`Name\` → context \`Ctx\`` + `\| Field \| Type \| Immutable Fact? \| Source / Notes \|` (Source: the same-slice command field it is copied from; failing that, the command from another slice that also records the event, written `not supplied by this command (from \`A\`, slice "Create")` (GH #344 / #362, the same union `fields-completeness/event-field-no-source` checks; worded as a statement about this slice, since the repeat's own command does not take the field); `assigned` for a system-assigned field, else `{{ }}`) |
 | `em-slice-view` | `## Read Model / View` | `- **View:** \`Name\` built from events: …` (the union across the originating and every `again` instance; each later event is annotated `(via "<slice>")` with the slice of the instance that adds it) + `\| Field \| Type \| Source / Notes \|` (Source: the source event, from that union, carrying the field, `Derived` for a `derived` field, `Collection of \`T\`, fed by …` for a `T[] derived from …` field — followed by one neutral Given/Then scenario stub per named event under the table, to copy into `## Scenarios` and complete there (the region itself stays read-only); `em slice sync` retires a stub once an authored scenario covers that field and event, by the stub's `<field> after <Event>` title or by a Given naming the event with the field named in the block (GH #368), and drops the `Scenario stubs for` line when none is left — else `{{ }}`) |

package/plugin/shared/templates/model-readme.md

@@ -32,14 +32,22 @@ Change slice is paired with the State View slice that projects its event. A read
 along the timeline (`view X again`) shows the same projection at a later point; the instances are
 never connected to one another.
 
+## Storylines
+<!-- Generated — `em slice index {{model-name}}.em` writes one row per storyline between the
+     markers (count, implemented, diagram); the canvas is `em render {{model-name}}.em --map`. -->
+<!-- GENERATED:storylines:start -->
+| Storyline | Slices | Implemented | Diagram |
+|-----------|--------|-------------|---------|
+<!-- GENERATED:storylines:end -->
+
 ## Slices
 <!-- The canonical slice index — the ONE place slices are enumerated (the state file
      points here rather than keeping its own copy). Generated — run
      `em slice index {{model-name}}.em` to (re)write the table below from the model and its
      slice docs; never hand-edit between the markers. -->
 <!-- GENERATED:slices:start -->
-| # | Slice | Pattern | Status | Reviewed by | Ratified by | Owner | Tracking | Implemented in | Design doc |
-|---|-------|---------|--------|-------------|-------------|-------|----------|----------------|------------|
+| # | Slice | Pattern | Status | Design doc |
+|---|-------|---------|--------|------------|
 <!-- GENERATED:slices:end -->
 
 ## Status

package/plugin/shared/templates/slice.md

@@ -80,6 +80,10 @@ implementedIn: {{PR/commit link — fill in once status is `implemented`}}
 
 ![Diagram](./{{slice-name}}.svg)
 
+<!-- GENERATED:em-slice-story:start — generated from the model by `em slice sync`; do not hand-edit -->
+_Run `em slice sync` to place this slice in its story._
+<!-- GENERATED:em-slice-story:end -->
+
 <!-- Only on re-ratification of an already-`implemented` slice — omit this whole section on a
      slice's first version (v1 has no delta yet). The heading is always the literal `## Delta`,
      never `## Delta: vX → vY` — hop metadata is a display line inside the section instead (see
@@ -170,7 +174,9 @@ an event directly.}}
      own rows, a lookup of some other entity's name/email/etc. so it can display it — that is the
      views-as-lookups smell (methodology reference, "Views as lookups"): the field belongs on the
      event that creates this view's row instead, copied from state the command/decider already
-     reads to enforce its own invariants. Fix the `.em`, not the prose. -->
+     reads to enforce its own invariants. Fix the `.em`, not the prose. The built-from list names
+     every source, trigger and housekeeping alike; in the `.em` only the triggering event(s) sit in
+     `from`, the rest in `updates from` (methodology reference, "trigger and housekeeping"). -->
 <!-- GENERATED:em-slice-view:start — generated from the model by `em slice sync`; do not hand-edit -->
 - **View:** `{{View Name}}` built from events: {{"Event A", "Event B"}}
 

package/plugin/skills/conform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conform
-em-version: 1.20.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