@milehimikey/em 1.13.1 → 1.14.1

package/plugin/shared/templates/conformance-report.md

@@ -0,0 +1,85 @@
+<!-- GENERATED FILE from .claude/skills/event-modeling-shared/templates/conformance-report.md by scripts/build-plugin.ts — do not hand-edit; run npm run docs:generate -->
+<!--
+Conformance report skeleton. One per conform run, stored at
+<model-name>/conformance/<YYYY-MM-DD>-report.md (see reference/conform.md).
+Fill every section; leave "none" rather than deleting a section with nothing to report.
+Replace bracketed placeholders; delete guidance comments before finishing.
+-->
+
+# Conformance Report — {{Model Name}} — {{YYYY-MM-DD}}
+
+- **Model:** `{{model-name}}.em`
+- **Target repo:** {{repo path or URL}} @ `{{revision}}`
+- **Previous conformance revision:** {{prior target-repo revision, or "never (first run)"}}
+- **Scope:** {{full | diff-scoped since <prior revision>}}
+- **Slices checked:** {{comma-separated slice names, or "all implemented slices"}}
+- **Slices skipped (not yet implemented):** {{list, or "none"}}
+
+## Summary
+
+| Surface | Real drift | Model gap | Internal inconsistency | Accepted divergence | Unpropagated delta | Uncertainty |
+|---|---|---|---|---|---|---|
+| Structural | {{n}} | {{n}} | — | {{n}} | {{n}} | {{n}} |
+| Spec | {{n}} | {{n}} | — | {{n}} | {{n}} | {{n}} |
+| Internal | — | — | {{n}} | {{n}} | — | {{n}} |
+
+**Unpropagated delta** — a slice re-ratified past its shipped version (`slice.doc.driftSignal:
+"unpropagated-delta"` in `em export --json`): a known state, not a code defect. See
+`reference/conform.md` step 4.
+
+{{One or two sentences: overall read — clean, mostly clean with N items, or notably drifted.}}
+
+## Findings
+
+<!-- One subsection per finding. Group however reads clearest (by slice, or by surface) but keep
+     every field below for every finding. Order doesn't matter; classification does.
+
+     MIL-214: this section's structured twin is `conformance/{{YYYY-MM-DD}}-findings.json`,
+     written ALONGSIDE this report (not after it) — one JSON entry per `### n.` finding below,
+     `id` matching `{{n}}`. See reference/conform.md step 5 for the exact shape and the write-then-
+     `em conform-findings check`-it discipline. A later `em conform-supersede --locus --by` call
+     records the ruling on both the JSON (locus/resolvedBy/resolvedOn) and this report's banner
+     in one call. -->
+
+### {{n}}. {{Short finding title}}
+
+- **Surface:** {{structural | spec | internal}}
+- **Classification:** {{real drift | model gap | internal inconsistency | accepted divergence | unpropagated delta}}
+- **Slice:** {{slice name}}
+- **Evidence:** {{file path(s) and line/symbol, or the `em diff --json` entry (type + name) —
+  for accepted divergence, the `divergence "..."` annotation text itself; for unpropagated
+  delta, `slice.doc.driftSignal` and `slice.doc.version` from `em export --json`}}
+- **Claim:** {{what the model/doc says vs. what the code/doc shows — the actual disagreement}}
+- **Proposed red note:** `issue "conformance: {{text}}"` on {{element}} (slice "{{slice}}")
+  <!-- Omit this line entirely for internal-inconsistency findings with no clear side to flag,
+       for any accepted-divergence or unpropagated-delta finding (already ratified, or already
+       a known pending-ship state — don't propose re-ratifying either), or when the finding
+       doesn't warrant a red note (say why instead). -->
+
+## Scenario / invariant coverage
+
+<!-- Per in-scope slice: every named invariant and every GWT scenario the doc claims, mapped to
+     its enforcement/test site. Leave a cell explicitly blank/"none found" rather than omitting
+     the row — gaps are the point of this table. -->
+
+### {{Slice Name}}
+
+| Claim | Type | Enforcement site | Test site | Status |
+|---|---|---|---|---|
+| {{INV-XXX-1 or scenario title}} | {{invariant \| scenario}} | {{file path / symbol, or "none found"}} | {{file path / symbol, or "none found"}} | {{covered \| gap \| uncertain}} |
+
+## Uncertainties
+
+<!-- Listed separately from Findings — these are NOT drift. No evidence either way; say what was
+     missing (time, clarity, an ambiguous test) so a follow-up run can pick it up. -->
+
+- **{{structural | spec | internal}}** — {{what's uncertain}} — {{slice}} — {{why: e.g. "couldn't locate the test for INV-CHK-3, only its enforcement site"}}
+
+<!-- Tag each with its surface so these reconcile against the Summary table's Uncertainty column. -->
+
+## Applied this run
+
+<!-- Filled in AFTER the user reviews Findings and says what to apply. Leave "none yet — awaiting
+     ratification" until that conversation happens. -->
+
+{{List of ratified proposals actually applied to the `.em`/slice docs, or "none yet — awaiting ratification".}}

package/plugin/shared/templates/constitution.md

@@ -0,0 +1,136 @@
+<!-- GENERATED FILE from .claude/skills/event-modeling-shared/templates/constitution.md by scripts/build-plugin.ts — do not hand-edit; run npm run docs:generate -->
+<!--
+The implementation constitution: the house rules an implementing agent follows on EVERY slice —
+stack, code style, testing norms, NFR baselines, review norms. It answers "how do we build things
+here" once, so no slice doc has to repeat it and no agent has to invent it. Slice docs say WHAT to
+build; this says HOW it gets built here.
+
+Where this document lives:
+  - No SDD tool: `constitution.md` beside the model — `em scaffold` writes it there.
+  - spec-kit project (a `.specify/` directory exists anywhere above the model): the document IS
+    `.specify/memory/constitution.md`. em writes no second copy; the sections below merge into
+    that file under these same headings, never overwriting text already there, and ratification is
+    recorded in spec-kit's own `**Ratified**:` footer line instead of the frontmatter below.
+
+How it gets filled: not by an agent guessing. Each section opens with the question a short
+facilitated conversation asks before the first slice is implemented — the procedure is "Before the
+first slice: the constitution" in the `em:implement` skill's `reference/implement.md`
+(`em contract` prints it). Replace each `{{...}}` block with the real answers; delete the guidance
+comments and any row that doesn't apply.
+
+Ratification: `ratifiedBy:`/`ratifiedOn:` are the same identity discipline slice docs use — a
+NAMED human and an ISO date, hand-filled at sign-off (no `em` command writes this file).
+**A constitution with an empty `ratifiedBy:` is a draft**: an implementing agent treats it as
+unratified, says so, and does not proceed on unilateral style or stack decisions for a first slice.
+
+`em status` reports this document as present or absent per model — existence only. em never reads
+or validates its content, and the CLI parses nothing here. Three lines are read as plain text by
+the engagement skill and its sub-agents, so keep their exact shape: `- **Test command:**` (the
+validator), `- **Merge strategy:**` and `- **Agent models:**` (the engagement skill). In a spec-kit
+project they merge under the same headings in `.specify/memory/constitution.md`.
+-->
+
+---
+schemaVersion: 1
+ratifiedBy:
+ratifiedOn:
+---
+# {{Project Name}} — implementation constitution
+
+The house rules for how implementation happens in this project. They bound every "purely
+technical choice" an implementing agent would otherwise make alone.
+
+## Stack and architectural shape
+
+> **What do we build on, what shape does the code take, and which implementation skill or
+> approach does each slice pattern route to?**
+
+- **Languages / runtimes:** {{e.g. Kotlin 2.x on JVM 21; TypeScript 5 on Node 24}}
+- **Frameworks / platform:** {{web framework, persistence, messaging, build tool}}
+- **Architectural pattern:** {{e.g. event-sourced CQRS with vertical slices; layered service over
+  a relational store; functional core / imperative shell}}
+- **Where a slice's code lives:** {{one package per slice, per context, ...}}
+- **Interface conventions:** {{resource style — REST/RPC/GraphQL, etc.; error/rejection mapping;
+  versioning; auth at the edge — the shape every `ui`-triggered command or `ui`-consumed view's
+  endpoint follows, decided once here rather than invented per slice}}
+
+Routing — which implementation skill or approach each of the four slice patterns uses:
+
+| Pattern | Skill / approach |
+|---|---|
+| State Change | {{e.g. the `axon-*` skill set — axon-entity-patterns, then axon-entity-testing}} |
+| State View | {{e.g. the `axon-*` skill set — axon-projection-patterns, then axon-projection-testing}} |
+| Automation | {{e.g. the `axon-*` skill set — axon-policy-patterns, then axon-policy-testing}} |
+| Translation | {{e.g. the `axon-*` skill set — axon-translation-patterns}} |
+
+An agent implementing a slice reads the doc's `pattern:` frontmatter and follows that row — this
+table is the only routing rule.
+
+## Code style
+
+> **What does "idiomatic" mean in this codebase — formatting, naming, module layout?**
+
+- **Formatter / linter:** {{the tool and the command that runs it — never hand-format against it}}
+- **Naming:** {{commands, events, handlers, files, test names}}
+- **Module layout:** {{what lives in which file/package, and what may not import what}}
+- **Idiomatic here means:** {{the two or three habits a new contributor most often gets wrong}}
+
+## Testing norms
+
+> **What must be tested for each slice pattern, where do those tests live, and how are they named
+> so `em coverage` can trace invariant IDs?**
+
+- **Levels required per pattern:** {{e.g. State Change — decider unit tests plus a
+  given/when/then fixture test; State View — projection tests; Automation / Translation —
+  reaction tests, including a negative case}}
+- **Invariant tests:** {{where they live}} — every `INV-<MNEMONIC>-n` in a slice doc needs at least
+  one test **citing that exact ID** in its name or a comment, so
+  `em coverage <model>.em --tests <dir>` can trace it.
+- **Scenario tests:** {{where they live}} — one per `## Scenarios (Given / When / Then)` entry,
+  with rejection scenarios asserting the doc's named rejection reason.
+- **Test naming convention:** {{the exact pattern, e.g. `INV-ORD-3: rejects a second submit`}}
+- **What "green" means:** {{the command CI runs}}
+- **Test command:** `{{the one command that runs the tests, e.g. ./gradlew test}}`
+  What the `em-validator` sub-agent runs. Keep exactly this shape: one line, the command in
+  backticks. Absent, the validator reports "no test command in the constitution" and runs only the
+  em checks.
+
+## NFR baselines
+
+> **What standing non-functional defaults does every slice inherit — authz, PII, performance,
+> observability?**
+
+- **Authorization model:** {{who may issue which commands, how it's enforced, and where}}
+- **PII / data handling:** {{what is sensitive, what may be logged, retention}}
+- **Performance defaults:** {{latency / throughput budgets that apply unless a slice says otherwise}}
+- **Observability:** {{logging, metrics, tracing every slice is expected to emit}}
+
+A slice doc's own `## Non-Functional Requirements` section overrides these for that slice; where
+it is silent, these apply.
+
+## Review and merge norms
+
+> **Who reviews an implementation PR, what blocks a merge, and how does the slice doc's status
+> flip fit in?**
+
+- **Reviewers:** {{who — a team, a CODEOWNERS rule, the slice's ratifier}}
+- **What blocks a merge:** {{e.g. a failing suite, an uncovered invariant, a gap that belongs back
+  at the model}}
+- **Branch / commit conventions:** {{...}} — name only branch naming and commit-message style
+  here. **One slice doc = one PR is the implement contract's rule, not this document's to
+  amend** — a `covers:` doc ships as one PR for both keys; a read model is one doc, so a later
+  `again` instance is a continuation of the doc that first declared it, not a PR of its own. See
+  the agent guide's §5/§10.
+- **Merge strategy:** merge-commits-when-stacked
+  {{**How do PRs merge, and what happens when one PR depends on another?** Merge commits whenever
+  a dependent PR is open; squash only a PR with no open dependent (implement contract §8 rule 2a).
+  Keep this exact line: it is the only value the engagement skill accepts, and it refuses to run
+  without it.}}
+- **Agent models:** implementer=sonnet, validator=sonnet, reviewer=sonnet, critic=opus
+  {{**Which model runs each em sub-agent?** Keep this exact line shape, with the defaults shown or
+  your own choices. The critic must run on a different model from the implementer; `critic=codex`
+  selects the Codex critic. Absent, the engagement skill states these defaults once and
+  proceeds.}}
+- **At merge:** run `em slice mark-implemented <model>.em <slice-key> <pr-url>` — the one edit an
+  implementing agent makes to a ratified slice doc, run by {{the PR author | CI}}. Never bump
+  `version:`; that moves only when a delta is ratified.

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

@@ -0,0 +1,46 @@
+<!-- GENERATED FILE from .claude/skills/event-modeling-shared/templates/model-readme.md by scripts/build-plugin.ts — do not hand-edit; run npm run docs:generate -->
+# {{Model Name}}
+
+{{One-paragraph description of the business process(es) this event model covers.}}
+
+## Live view
+While modeling, run the live view so the team can watch the diagram update:
+
+```bash
+em watch {{model-name}}.em -o {{model-name}}.svg --serve   # re-render + instant push-reload
+# then open the URL it prints (http://localhost:5173/?svg={{model-name}}.svg) and share the screen
+```
+
+Pan/zoom to navigate the diagram (drag, scroll; **Fit** resets), and click **Review mode** in
+the header for a slice-by-slice walkthrough. If a save fails to render, the viewer keeps the
+last good diagram and shows an error banner until the next successful load.
+
+Static render: `em render {{model-name}}.em -o {{model-name}}.svg`
+
+## Patterns legend
+- **State Change** — UI → Command → Event
+- **State View** — Event(s) → Read Model → UI
+- **Automation** — Read Model (slice before) → Processor + Command → Event, together
+- **Translation** — External input (or Read Model, slice before) → Translation + Command → Event, together
+
+Between them these are the only legal connections: `ui → command`, `command → event`,
+`event → read model`, `read model → ui`, `read model → reaction`, `reaction → command`. A command
+never reaches a read model directly — the event goes between them. Every slice is joined up at
+both ends: something triggers each command (the screen it's issued from, or the reaction that
+triggers it, also in this slice), and every event a command records is read by some read model — so each State
+Change slice is paired with the State View slice that projects its event. A read model repeated
+along the timeline (`view X again`) shows the same projection at a later point; the instances are
+never connected to one another.
+
+## 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 |
+|---|-------|---------|--------|-------------|-------------|-------|----------|----------------|------------|
+<!-- GENERATED:slices:end -->
+
+## Status
+See [`.event-modeling.md`](.event-modeling.md) for current phase, decisions, and open questions.

package/plugin/shared/templates/slice.md

@@ -0,0 +1,251 @@
+<!-- GENERATED FILE from .claude/skills/event-modeling-shared/templates/slice.md by scripts/build-plugin.ts — do not hand-edit; run npm run docs:generate -->
+<!--
+Rich slice design document. One per slice, stored in <model>/slices/<slice-name>.md and
+linked from the .em model with:  note "slices/<slice-name>.md"  on the slice's defining element.
+Fill every section through Socratic questioning. Leave "Open Questions" rather than guessing.
+Replace the bracketed placeholders; delete guidance comments before finishing.
+
+The frontmatter below is the canonical, machine-read metadata dialect — `em`'s own parser
+(src/catalog/sliceDoc.ts) reads `status:`, `version:`, `pattern:`, and the lineage keys
+(`split-from:`/`merged-from:`/`superseded-by:`) from it. `pattern` is kebab-case
+(state-change/state-view/automation/translation) even though the skill's prose always says
+"State Change"/"State View"/etc. — the frontmatter value is a machine key, not a display label.
+Older docs using a `- **Status:** ...` bullet line instead of frontmatter still parse (legacy/
+accepted input), but new docs should always use this frontmatter form; `version` and lineage
+have no legacy form — frontmatter-only from day one.
+
+`version` is this slice's own ratified-content version — starts at `1`, bumps when a delta is
+ratified — distinct from `schemaVersion`, which versions the frontmatter dialect itself, not
+this slice. When a ratified change lands on an already-`implemented` slice: bump `version`,
+flip `status` back to `ready-to-implement` (it tracks the CURRENT version's implementation
+state — `implementedIn` legitimately keeps naming the PRIOR version's PR until the new version
+ships; that mismatch is an intended drift signal, not a bug), and fill in the `## Delta` section
+below with this hop's change, replacing whatever it held before (it always shows only the latest
+hop — full history lives in git, same-commit-ratification convention). Full grammar — the fixed
+heading, the four operation subsections, why the heading never varies, the replace-not-accumulate
+lifecycle — is documented in ../reference/slice-doc-schema.md#delta-section-grammar-and-lifecycle; treat
+it the same Socratic way as every other section here, don't generate it mechanically.
+
+The three lineage keys only apply when this doc was produced by a split, merge, or rename —
+delete them otherwise; most slices never carry them. Grammar: `<slice-key>@v<N>`, where
+`<slice-key>` is the referenced slice's kebab-case filename stem.
+
+`covers` only applies when this doc is also the ratified doc for a DIFFERENT slice — typically
+the bare `view` half of the two-slice Automation/Translation shape, which has nothing of its own
+to write up. Delete it otherwise; most docs never carry it. Requires a matching
+`note "slices/{{this-slice-name}}.md"` on an element in the OTHER slice — this key alone doesn't
+bind anything. Plain slice keys, comma-separated — not the `<slice-key>@v<N>` ref grammar above.
+
+`ratifiedBy`/`ratifiedOn` record who ratified this doc's current `status`/`version`, and when —
+don't hand-fill these; run `em slice ratify <model> <key> --by <name>` at the
+handoff gate instead (docs/process.md#what-ratified-means), which flips `status` to
+`ready-to-implement` and writes both in one edit.
+public-touching slice: add --meaning-unchanged, or --contract-change "<why>"; run em api generate first.
+
+`owner`/`tracking` are optional and, unlike `ratifiedBy`/`ratifiedOn`, hand-filled — no `em`
+command writes either. `owner` is free text naming who (a person or team) holds this slice;
+`tracking` is a URL into an external tracker (Jira, Linear, ...) mirroring it — the exact field
+`em-tracker-bridge` reads to find the mirrored ticket. `em` only stores and displays both; it
+never talks to a tracker itself. Delete both otherwise; most docs never carry them.
+
+Full machine schema — required-vs-optional keys per `status`, value types/enums, the
+unknown-key policy — is documented in ../reference/slice-doc-schema.md.
+
+The diagram below is generated, not hand-drawn: `em render <model>.em --slice "{{Slice Name}}"
+-o slices/{{slice-name}}.svg` (kebab-case the slice name to match this doc's own filename).
+-->
+
+---
+schemaVersion: 1
+pattern: {{state-change | state-view | automation | translation}}
+swimlane: {{Persona/Actor}} → {{Context/Aggregate}}
+status: {{draft | reviewed | ready-to-implement | implemented}}
+version: 1
+implementedIn: {{PR/commit link — fill in once status is `implemented`}}
+# Lineage — only when this doc exists because of a split, merge, or rename (delete these three
+# lines otherwise). Grammar: <slice-key>@v<N>. See
+# ../reference/slice-doc-schema.md#lineage-grammar-and-cardinality.
+# split-from: <slice-key>@v<N>
+# merged-from: <slice-key>@v<N>, <slice-key>@v<N>
+# superseded-by: <slice-key>@v<N>, <slice-key>@v<N>
+# Cross-slice coverage — only when this doc also covers another slice with no doc of its own
+# (e.g. the view-only half of a two-slice Automation/Translation, MIL-121); delete otherwise.
+# Plain slice keys, comma-separated. See ../reference/slice-doc-schema.md#cross-slice-coverage-covers.
+# covers: <slice-key>, <slice-key>
+# Ownership / tracking — optional, hand-filled (no `em` command writes either); delete otherwise.
+# owner: <person or team>
+# tracking: <ticket URL>
+---
+# Slice: {{Slice Name}}
+
+![Diagram](./{{slice-name}}.svg)
+
+<!-- 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
+     ../reference/slice-doc-schema.md#delta-section-grammar-and-lifecycle for why). Replace this
+     section's content wholesale on the next re-ratification — it shows only the latest hop, not
+     an accumulating log. Omit any of the four subsections below with no entries this hop; keep
+     the remaining ones in this order (Added/Modified/Removed/Renamed). `Renamed` is for a
+     requirement/invariant renamed within this slice, not a substitute for the frontmatter
+     `split-from`/`merged-from`/`superseded-by` lineage keys above, which record the slice-doc
+     itself splitting, merging, or being renamed. -->
+## Delta
+**v{{X}} → v{{Y}}, ratified {{date}}** — {{one-line summary of the ratified change}}
+
+### Added
+#### Requirement: {{title}} ({{stable ID, e.g. an INV-{{MNEMONIC}}-n from Invariants below}})
+{{requirement text — same voice as an Invariants entry}}
+##### Scenario: {{name}}
+- **Given:** {{...}}
+- **When:** {{...}}
+- **Then:** {{...}}
+
+### Modified
+<!-- Same shape as Added — the stable ID names the requirement that changed. -->
+
+### Removed
+#### Requirement: {{title}} ({{stable ID}})
+{{why it was removed}}
+
+### Renamed
+- {{old title}} ({{old ID}}) → {{new title}} ({{new ID}})
+
+## Intent
+{{Why this slice exists — the user or business goal it serves, in one or two sentences. Note the
+originating ticket/conversation link here if one exists.}}
+
+## Trigger & Actor
+{{Who or what initiates this slice and under what circumstances. For automations, the watched
+read model and the triggering condition. For translations, state the trigger form: externally
+triggered (the external system/source feeding us) or internally triggered (the read model whose
+state we react to). Either way, name the command this reaction triggers — reactions never record
+an event directly.}}
+
+## Command / Input
+<!-- GENERATED region (MIL-266): the table between the markers is written from the model —
+     `em slice new` fills it, `em slice sync <model>.em` refreshes it after any model edit. Never
+     hand-edit inside the markers: change the `.em` and re-run `em slice sync`. Required = `no`
+     for a field written `name?: Type`. A slice with several commands gets one region per command
+     (`em-slice-command-<command-slug>`); a pure State View slice's region says it has none. -->
+<!-- GENERATED:em-slice-command:start — generated from the model by `em slice sync`; do not hand-edit -->
+**Command:** `{{Command Name}}`
+
+| Field | Type | Required | Rules / Validation |
+|-------|------|----------|--------------------|
+| {{field}} | {{Type}} | {{yes/no}} | {{constraints, formats, ranges}} |
+<!-- GENERATED:em-slice-command:end -->
+
+## Trigger
+<!-- What issues this slice's command. Required: a command nothing points at is a write nobody
+     can start. Either the screen the user acts on (a `ui` in this slice), or the reaction that
+     issues it (an automation/processor/translation, also in this slice). -->
+**Triggered by:** {{screen `X` @Persona | processor `Y`, also in this slice}}
+
+## Event(s) Emitted
+<!-- The immutable facts recorded. The marker line and payload table are a GENERATED region (one
+     per event; `em-slice-event-<event-slug>` when the slice records several): Source / Notes
+     names the command field a value is copied from, `assigned` for a system-assigned field, or
+     `{{ }}` where the model cannot tell. `**Read by:**` below the region is authored. -->
+<!-- GENERATED:em-slice-event:start — generated from the model by `em slice sync`; do not hand-edit -->
+**Event:** `{{Event Name}}` → context `{{Context}}`
+
+| Field | Type | Immutable Fact? | Source / Notes |
+|-------|------|-----------------|----------------|
+| {{field}} | {{Type}} | {{yes/no}} | {{where the value comes from}} |
+<!-- GENERATED:em-slice-event:end -->
+**Read by:** {{which read model projects this event, and in which slice}}
+<!-- Required, not optional. Every event must be read by a read model — an event nothing
+     projects is a write nobody can see, and `em validate` warns on it. A reaction consuming
+     it does NOT count: reactions read views, not events. If the honest answer is "nothing
+     reads it", that's a question for the business, not a field to leave blank. -->
+
+## Read Model / View
+<!-- For State View slices, and any read model this slice produces or feeds. The `- **View:**`
+     line and field table are a GENERATED region (one per read model; `em-slice-view-<view-slug>`
+     when there are several): Source / Notes names the source event a field is copied from, or
+     `Derived` for a field marked `derived` in the `.em` (docs/dsl.md#derived-fields) — say how
+     it is derived in prose below the region. `{{ }}` marks a field the model cannot trace. -->
+<!-- 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"}}
+
+| Field | Type | Source / Notes |
+|-------|------|----------------|
+| {{field}} | {{Type}} | {{which event field it's copied from, or `Derived: <rule>`}} |
+<!-- GENERATED:em-slice-view:end -->
+- **Consumed by:** {{which UI screen (or API-caller persona), or reaction}}
+<!-- "Consumed by" is required, not optional. A read model nothing displays or watches is
+     information projected out of the system and then dropped, and `em validate` warns. Every
+     instance of a repeated view needs its own consumer, not just the last one. -->
+- **Freshness / consistency expectation:** {{real-time | eventual | on-demand}}
+
+## Invariants / Business Rules
+<!-- IDs and rule sentences are declared in the MODEL (MIL-265): an `invariant INV-<MNEMONIC>-<n>
+     "rule"` line after the command or event it guards (docs/dsl.md#invariants). The list between
+     the markers is GENERATED from those lines (`em slice sync`); never edit it. Below it, cite
+     each ID as a plain mention and elaborate — `- INV-CHK-1 — why it holds, edge cases, the error
+     a violation returns` — never re-declare it with the `**INV-CHK-1:**` label
+     (`invariants/declared-in-both`). A rule not (yet) in the model may still be declared below
+     with that label; em reads it as the fallback. -->
+<!-- What must ALWAYS hold. Give each a stable ID so tests and code can reference it:
+     `INV-<MNEMONIC>-<n>`, where `<MNEMONIC>` is a short (2-4 letter/digit), slice-unique
+     abbreviation of this slice's key (e.g. slice `checkout` -> `INV-CHK-1`) — see
+     ../reference/slice-doc-schema.md. Keep the rule statement itself to one line. If it needs
+     more — why the rule exists, what "violation" looks like in practice, an edge case worth
+     calling out — add that as a nested bullet under the elaboration line instead of one long
+     run-on sentence: this section renders as HTML (`em catalog`/`em render`/`em watch`), and a
+     nested bullet stays visually distinct where a wrapped sentence collapses into a wall of
+     text. The ID must stay on the top-level bullet line — `em coverage` extracts INV IDs from
+     that line only, never from a nested elaboration bullet underneath it. -->
+<!-- GENERATED:em-slice-invariants:start — generated from the model by `em slice sync`; do not hand-edit -->
+- **INV-{{MNEMONIC}}-1** — {{rule, as declared by `invariant INV-{{MNEMONIC}}-1 "rule"` in the model}}
+<!-- GENERATED:em-slice-invariants:end -->
+<!-- elaborate below this list; IDs are declared in the model -->
+- INV-{{MNEMONIC}}-1 — {{elaboration of the model-declared rule: why it holds, what a violation looks like, the error returned}}
+  - {{optional: edge-case detail — its own bullet}}
+- **INV-{{MNEMONIC}}-2:** {{a rule not yet in the model, declared here as the fallback — move it into the model when you can}}
+
+## Scenarios (Given / When / Then)
+<!-- The executable specification — authored, in a constrained shape `em` reads back (`em export
+     --json` → slice.doc.scenarios). Cover the happy path AND the key rule boundaries, one block
+     per case: a `### Scenario: <title>` heading, then exactly the three column-0 bullets
+     `- **Given:**`, `- **When:**`, `- **Then:**`, each with its beats as nested `  - ` bullets.
+     A block missing any of the three is flagged `slice-doc/structured-section-malformed`. -->
+### Scenario: Happy path
+- **Given:**
+  - {{starting state / prior events}}
+- **When:**
+  - {{command/trigger}}
+- **Then:**
+  - {{event(s) recorded}}
+  - {{resulting read-model change}}
+
+## Alternate & Error Flows
+<!-- Failure paths, retries, compensations, timeouts, idempotency. -->
+- {{e.g. external call fails → retry policy / compensating event}}
+- {{idempotency: what happens if the command/event arrives twice?}}
+
+## Non-Functional Requirements
+<!-- Short checklist. Idempotency is covered above under Alternate & Error Flows — not repeated
+     here. -->
+- **Security / authz:** {{who may invoke this; role/permission checks — or "none"}}
+- **PII & compliance:** {{personal data touched, retention/consent constraints — or "none"}}
+- **Performance / SLA:** {{latency/throughput expectation — or "none"}}
+
+## Dependencies & Read Models Affected
+- **Upstream events this slice relies on:** {{...}}
+- **Downstream read models / slices affected:** {{...}}
+
+## Open Questions
+<!-- Park unresolved items here instead of guessing. Mirror them into .event-modeling.md.
+
+     Lifecycle across versions: while THIS version is still being worked, a resolved item
+     (`- [x]`) can stay checked here as a visible record of what's already been decided this
+     round. On the same commit that ratifies the NEXT version (bumps `version`, rewrites
+     `## Delta` above) — prune every already-checked item from this list; keep only what's still
+     open, plus anything new the delta itself surfaced. Same "replace, never accumulate" stance
+     as `## Delta`, for the same reason: an ever-growing scroll of resolved questions goes stale
+     exactly like an accumulating Delta log would, and full history already lives in git
+     (`git log -p slices/<name>.md`) — this section is a live worklist, not an audit trail. See
+     ../reference/slice-doc-schema.md#open-questions-section-lifecycle. -->
+- [ ] {{question}}

package/plugin/shared/templates/state.md

@@ -0,0 +1,77 @@
+<!-- GENERATED FILE from .claude/skills/event-modeling-shared/templates/state.md by scripts/build-plugin.ts — do not hand-edit; run npm run docs:generate -->
+<!--
+Resumable progress state for an event model. Stored as <model>/.event-modeling.md
+The skill reads this on `/em:event-modeling` (no arg) to resume where you left off.
+Keep it current at the end of every working session.
+-->
+
+# Event Modeling Progress — {{Model Name}}
+
+- **Model file:** `{{model-name}}.em`
+- **Em version:** {{X.Y.Z}}
+- **Current phase:** {{discover | extract | model | slice | implement | conform | review | validate}}
+- **Current step:** {{1–7, see methodology; or extraction round R1–R7}}
+- **Last updated:** {{YYYY-MM-DD}}
+- **Last conformance:** {{YYYY-MM-DD @ <target-repo revision> — report: conformance/<date>-report.md | never}}
+- **Model version:** {{N | none}}
+- **Certified:** {{v<N> @ <target-repo revision> (YYYY-MM-DD) | never}}
+- **Last stakeholder review:** {{YYYY-MM-DD — attendees: see Participants | never}}
+
+## Session inputs
+- **Scope line:** {{one-line description of what's in/out of bounds for this model}}
+- **PRD / spec reference:** {{path, link, or "none"}}
+- **Headless/API model:** {{yes | no}}
+- **Source mode:** {{greenfield | extract-event-driven | extract-procedural}}
+- **Existing system refs:** {{repo paths, event-schema/topic locations, docs — or "n/a"}}
+
+## Participants
+<!-- Populate at session start. Live workshop: one human proxy relays questions to the room;
+     attribute every answer/decision in the Decisions log to a named participant here. -->
+- {{Name}} — {{role}} — {{domain area}}
+
+## Extraction progress (existing-system models only — delete for greenfield)
+- [ ] R1. Candidate events (extracted/synthesized, filtered, confirmed)
+- [ ] R2. Timeline order (as-is narrative, actors/callers, first render)
+- [ ] R3. Commands / inputs
+- [ ] R4. Read models / outputs (validate from here)
+- [ ] R5. Boundaries & reactions (reaction shares its slice with the command it triggers)
+- [ ] R6. Gap & TBD reconciliation
+- [ ] R7. Convergence (render + validate clean, user confirmed as-is)
+
+## Steps completed
+- [ ] 1. Brainstorm events
+- [ ] 2. Plot / storyboard (personas + UI)
+- [ ] 3. Inputs (commands)
+- [ ] 4. Outputs (read models)
+- [ ] 5. Swimlanes & apply patterns
+- [ ] 6. Elaborate scenarios
+- [ ] 7. Evaluate completeness (`em validate` clean)
+
+## Decisions log
+<!-- Resolved choices, with the reasoning, so they aren't re-litigated. In a live workshop,
+     attribute each entry to the participant who made the call (see Participants above).
+     Every entry is a dated bullet ("- YYYY-MM-DD: ..."); em changelog skips any other line.
+     Seam change request (a needed change to another model's public element; never edit that
+     model, keep the open question blocked on its owners):
+     - YYYY-MM-DD: seam change request → <producerKey>:<kind>.<slug> — <what> — <why> -->
+- {{YYYY-MM-DD}}: {{decision}} — {{why}} — by {{participant, if a live workshop}}
+
+## Usage log
+<!-- The team's only usage signal today (see docs/usage-data.md) — cheap and coarse on purpose.
+     One line per session: phase(s) touched, and validate diagnostic *categories* hit (one of
+     the exact fixed strings in docs/usage-data.md#categories, e.g. "read model has no
+     consumer" — never the full instance message or any domain content). Append, never edit
+     past entries. -->
+- {{YYYY-MM-DD}}: phases: {{discover | extract | model | slice | implement | conform | review | validate | watch, ...}} — validate: {{diagnostic category (docs/usage-data.md#categories), ... | none}}
+
+## Open questions / parking lot
+<!-- Unresolved items to bring back to the user. Never guess these. Metadata is optional and
+     flat — add only what's known: source (ticket/conversation that spawned it), blocked on
+     (who/what), revisit (when). -->
+- [ ] {{question}} — source: {{ticket/conversation link, optional}} — blocked on: {{who/what, optional}} — revisit: {{when, optional}}
+
+## Slice inventory
+<!-- Deliberately NOT a table: the canonical slice index (slice, pattern, status, doc link)
+     lives in README.md's "Slices" section — one source of truth, updated there. This file
+     only tracks resumable session state. -->
+See `README.md` → **Slices** for the slice index and per-slice doc status.