@milehimikey/em 1.18.0 → 1.19.0

package/plugin/shared/reference/slice-doc-schema.md

@@ -69,7 +69,7 @@ to decide `frontmatter-invalid` without re-deriving frontmatter-shape rules of i
 | `ratifiedBy` | string | free text (typically a person's name) | written only by `em slice ratify` (MIL-165 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-ratify-file-slice-key---by-name)); joined into `em export`'s `slice.doc.ratifiedBy` (schema `1.8`) and `em slice index`'s Ratified by column |
 | `ratifiedOn` | string | `YYYY-MM-DD` | written only by `em slice ratify` (MIL-165); joined into `em export`'s `slice.doc.ratifiedOn` (schema `1.8`) |
 | `ratifiedRef` | string | full commit sha | written only by `em slice ratify` (MIL-284 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-ratify-file-slice-key---by-name)) when the model directory is inside a git repository: `HEAD` at ratification, the commit whose tree holds the body that was signed (ratify refuses a doc with uncommitted changes so this holds). Absent when ratified before 1.15, outside git, or with `em slice ratify --no-ref` (GH #255 — for a repo whose squash/rebase merges would leave the commit unreachable from the target branch; `--no-ref` also removes a line already present). **An address, not the identity:** valid only while the commit stays reachable; `ratifiedHash` is what identifies the signed content. Cleared by `em slice revise`. Joined into `em export`'s `slice.doc.ratifiedRef` (schema `1.16`). Not a target-repo revision: `em slice conform --at` still names that itself |
-| `ratifiedHash` | string | `sha256:<64 hex>` | written only by `em slice ratify` (MIL-284): `sha256` over the doc body (everything after the frontmatter fence, EOLs normalised) **minus what describes a later version** (GH #253, since 1.17.0): inside `## Open Questions` the heading line, blank lines and every `deferred to v<n>` item are left out, then trailing whitespace is trimmed — so `em slice defer` can record a question on a ratified or shipped doc without moving the hash, while answered `- [x]` history, any `- [ ]`, and every other section stay signed. The signed content's identity without git. A hash recorded before 1.17.0 (whole body) is still read as intact; `em upgrade`'s `ratified-hash-scope` step re-stamps it. Cleared by `em slice revise`. Read by `em validate --slice-ready` (`slice-ready-body-changed-since-ratification`) and by `ratify`'s same-sign-off re-run; joined into `em export`'s `slice.doc.ratifiedHash` (schema `1.16`) |
+| `ratifiedHash` | string | `sha256:<64 hex>` | written only by `em slice ratify` (MIL-284): `sha256` over the **authored text** of the doc body (everything after the frontmatter fence, EOLs normalised). Since 1.19.0 (GH #347) the text strictly between each [generated region](#generated-regions-and-authored-sections)'s two marker lines is left out (the marker lines themselves stay in), so `em slice sync` can refresh a ratified or shipped doc's regions without moving the hash — the regions restate the model, whose contract changes surface through model validation and its pin (`model-versions/v<N>.json`); a doc whose markers don't balance has nothing left out. Since 1.17.0 (GH #253) the doc also leaves out **what describes a later version**: inside `## Open Questions` the heading line, blank lines and every `deferred to v<n>` item, then trailing whitespace is trimmed — so `em slice defer` can record a question on a ratified or shipped doc without moving the hash. Answered `- [x]` history, any `- [ ]`, the region marker lines and every other section stay signed. The signed content's identity without git. A hash in an older scope whose body is intact is still read as intact — recorded by 1.17.0–1.18.x (generated regions inside) or before 1.17.0 (whole body); `em upgrade`'s `ratified-hash-scope` step re-stamps it, and so do `em slice sync` and `em slice defer` when they first write to the doc. Cleared by `em slice revise`. Read by `em validate --slice-ready` (`slice-ready-body-changed-since-ratification`) and by `ratify`'s same-sign-off re-run; joined into `em export`'s `slice.doc.ratifiedHash` (schema `1.16`) |
 | `shippedVersion` | integer | positive integer | written only by `em slice mark-implemented` (MIL-284): the doc's `version:` when the merge was recorded. With `shippedRef`/`shippedOn`/`implementedIn`, joined into `em export`'s `slice.doc.shipped` (schema `1.16`). Additive in 1.15 — `status`/`implementedIn` still carry the lifecycle for every reader |
 | `shippedRef` | string | full commit sha | written only by `em slice mark-implemented` (MIL-284): the doc's `ratifiedRef` at merge time, i.e. the ref the shipped version was signed at; absent when the doc had none (ratified before 1.15, outside git, or with `--no-ref`, GH #255). Same caveat as `ratifiedRef`: an address, valid while reachable — `ratifiedHash` identifies the content |
 | `shippedOn` | string | `YYYY-MM-DD` | written only by `em slice mark-implemented` (MIL-284): the local date of the merge record, or `--on <date>` |
@@ -474,7 +474,7 @@ re-run `em slice sync`.
 | Region | Section | Body |
 |---|---|---|
 | `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, `assigned` for a system-assigned field, else `{{ }}`) |
+| `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 `from command \`A\` (slice "Create")` (GH #344, the same union `fields-completeness/event-field-no-source` checks); `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) — else `{{ }}`) |
 | `em-slice-invariants` | `## Invariants / Business Rules` | one `- **INV-X** — rule` line per model-declared invariant of the slice's commands and events |
 
@@ -506,6 +506,18 @@ generated list never trips `invariants/declared-in-both`. Elaborate each ID belo
 Dependencies, Open Questions. `em` never writes them; `em slice sync` leaves every byte outside
 the region markers untouched (CRLF included).
 
+**Regions and the signature (GH #347, 1.19.0).** `ratifiedHash` covers the authored sections and
+the marker lines, not what sits between the markers. So `em slice sync` runs on a ratified or
+shipped doc like any other and keeps its signature: it rewrites the regions, leaves `ratifiedHash`
+and `ratifiedRef` alone, and prints a `note:` saying so. A hash still in an older scope (1.17.0–1.18.x,
+or pre-1.17 whole-body) whose body is intact is re-stamped in the current scope in the same write —
+same authored text, not a re-signing. A doc whose authored text already fails its hash is synced
+too, with nothing re-stamped (`em validate --check-signed-bodies` still reports it). A scenario
+stub or `{{ }}` Source cell that sync writes into a signed doc's region is reported by `em validate`
+as `slice-doc/generated-region-placeholder` (warning; see
+[validation.md](https://github.com/milehimikey/em/blob/main/docs/validation.md#generated-region-placeholders)): fill the model gap and re-sync, or
+write the scenario in `## Scenarios`, which on a signed doc is the next version (`em slice revise`).
+
 **Scenario grammar (authored, constrained).** Inside `## Scenarios (Given / When / Then)`, each
 case is a block:
 

package/plugin/skills/conform/SKILL.md

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

package/plugin/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-em-version: 1.18.0
+em-version: 1.19.0
 description: >-
   Use when structuring a draft event model into swimlanes and the four patterns (State Change,
   State View, Automation, Translation), evaluating a model's structural completeness, or writing
@@ -245,7 +245,10 @@ For each slice:
    **never hand-edit a generated region.** To change a field, a type, or an invariant, edit the
    `.em`, then **after any model edit run `em slice sync <model>.em`**, which rewrites every
    region in place and leaves everything else byte-for-byte (`em slice sync <model>.em --check`
-   reports a stale doc without writing). **Edit authored sections only**: Intent, Trigger &
+   reports a stale doc without writing). That includes a ratified or shipped doc: `ratifiedHash`
+   covers the authored text only (since em 1.19.0), so sync rewrites its regions, keeps the
+   signature and says so — never `em slice revise` a doc just to sync it; revise only when an
+   authored section has to change. **Edit authored sections only**: Intent, Trigger &
    Actor, `Triggered by`/`Read by`/`Consumed by`, the invariant elaborations below the generated
    list, Scenarios, Alternate & Error Flows, NFRs, Dependencies, Open Questions. Scenarios use the
    constrained shape `em` reads back: a `### Scenario: <title>` heading, then `- **Given:**`,

package/plugin/skills/discover/SKILL.md

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

package/plugin/skills/discover/reference/prd-rubric.md

@@ -63,7 +63,7 @@ All of these are checked by `em discover triage-check`; write the record so they
    group** has only `reference` statements and **no storyline**: `storyline: null` on the group and
    on its statements. It never joins a walkthrough storyline. The report lists reference-only
    groups outside every storyline — operations no walkthrough touches; check these are not CRUD fill.
-8. **One statement per claim.** A statement's normalised quote may not equal, contain or be contained in another statement's quote; the error names both.
+8. **One statement per claim.** A statement's normalised quote may not equal, contain, be contained in, or partially overlap (by character range in the normalised source) another statement's quote; the error names both. Ranges are taken at a quote's first occurrence in the normalised source, so a sentence repeated in the PRD can hide or produce an overlap.
 9. **Quotes are verbatim** (Markdown emphasis marks, smart quotes and whitespace aside) and at
    least 12 characters. A storyline `quote` is the **full** walkthrough span, start to finish.
 

package/plugin/skills/discover/reference/prd-spec-path.md

@@ -85,7 +85,7 @@ event share one slice.
   built only from `reference` statements (operations no walkthrough touches) is reference-only:
   `storyline: null` on the group and on its statements. It never joins a walkthrough storyline,
   and the report lists it outside every storyline for the human to inspect.
-- A claim is quoted once: no statement's quote may equal, contain or be contained in another's. Only `modeled`/`rewritten` walkthrough statements anchor a group; a `question` never does.
+- A claim is quoted once: no statement's quote may equal, contain, be contained in, or partially overlap by character range in the normalised source another's. Only `modeled`/`rewritten` walkthrough statements anchor a group; a `question` never does.
 
 ## Step 4 — Rewrite, don't drop
 

package/plugin/skills/engagement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: engagement
-em-version: 1.18.0
+em-version: 1.19.0
 description: >-
   Use when leading an engagement: building a named set of ratified event-modeling slices
   (`em engagement`) into one independent PR per slice, each against main, by dispatching the
@@ -70,9 +70,13 @@ Run the shared preconditions first (tool check, bundle currency, locate the mode
    fails, STOP and ask the human to add `.claude/worktrees/` to `.gitignore` in its own commit
    on `main`.
 5. **The engagement exists.** `em engagement status <model>.em <slug>`. If there is no such
-   engagement, ask the human which slices it covers (a list, a context, or "everything
+   engagement, ask the human which slices it covers (a list, a context, a storyline, or "everything
    downstream of X") and run `em engagement new <model>.em <slug> --slices a,b,c` (or
-   `--context <C>`, or `--downstream-of <ref>`) `--by "<their name>"`. When `new` warns that the
+   `--context <C>`, `--storyline <name>`, or `--downstream-of <ref>`) `--by "<their name>"`. First check the host
+   repo's PR-title convention (a commitlint config, a PR-title workflow, or the last few merged
+   PR titles) and pass `--pr-title "<template>"` when it differs from the default
+   `<key>: <slice name>`; placeholders are `{key}`, `{slice}` (display name) and `{sliceKey}`
+   (kebab key, usually what a lint wants). When `new` warns that the
    selection has several unconnected components, relay its suggestion (one engagement each)
    and let the human decide before going on.
 
@@ -118,10 +122,13 @@ For each slice the plan lists as not held:
 4. Record it:
    `em engagement set <model>.em <slug> <key> --state building --branch impl/<key> --base <base>`
 5. Dispatch `em-implementer` (`em:em-implementer` under the plugin) on the implementer model.
-   Its prompt is ONLY the slice key, the absolute worktree path and, when the plan's slice
-   carries one, its tracking key (`tracking` in `em engagement plan --json` — GH #241). That
-   field is already resolved: the slice doc's own `tracking:` wins over the engagement's
-   `--tracking`, and it is `null` when neither is set (then say nothing about tracking). It reads
+   Its prompt is ONLY the slice key, the absolute worktree path, the exact pull-request title
+   and, when there is one, the tracking key. The title is the slice's `prTitle` from
+   `em engagement plan --json` (GH #334), already resolved from the engagement's `--pr-title`
+   template or the default: pass it verbatim and never compose one. The tracking key is the
+   plan's `tracking` (GH #241), already resolved: the slice doc's own `tracking:` wins over the
+   engagement's `--tracking`, and it is `null` when neither is set (then say nothing about
+   tracking). Surface any `pr-title-fallback` pre-flight entry to the human. It reads
    its own spec, the constitution and the implement contract. Give it no plan, no other slice,
    and no merge instructions.
 
@@ -133,7 +140,7 @@ When the implementer returns a PR URL (and a per-invariant test map):
    base: `gh pr view <url> --json baseRefName` must be `main`. If not, fix it with
    `gh pr edit <url> --base main`. That is a lead step; the implementer never changes a base.
 2. Dispatch `em-validator` (`em:em-validator`) with the slice key, the worktree path and the same
-   tracking key (when the slice has one). It
+   tracking key (when the slice has one) and the same `prTitle`. It
    returns one PASS/FAIL line per check and `OVERALL: PASS` or a failure.
 3. On `OVERALL: PASS`: `em engagement set <model>.em <slug> <key> --state review`. Dispatch
    `em-reviewer` (`em:em-reviewer`) with the slice key and the PR URL. Dispatch `em-critic`

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling
-em-version: 1.18.0
+em-version: 1.19.0
 description: >-
   Use when the user runs `/em:event-modeling` (with or without a phase name), or wants to resume an
   event-modeling session without specifying which part of the process applies. Reads the model's

package/plugin/skills/implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implement
-em-version: 1.18.0
+em-version: 1.19.0
 description: >-
   Use when building a single ratified event-modeling slice (status: ready-to-implement) into
   merged, tested code — the one phase where the agent builds rather than facilitates. Gates on

package/plugin/skills/implement/reference/implement.md

@@ -35,6 +35,16 @@ every `## Open Questions` checkbox is checked, and no status/version/link incohe
 — `gates` names each of those 4 conditions individually (`docBound`/`frontmatterUsable`/
 `statusReady`/`noUncheckedOpenQuestions`) if you need to say which one is blocking.
 
+`ready` is the named gates, plus error-severity diagnostics scoped to the slice, plus these warning-severity codes:
+
+- `slice-ready-no-doc-bound`, `slice-ready-status-not-ready`, `slice-ready-open-questions-unchecked`: the gates themselves.
+- `binding-missing-file`, `frontmatter-invalid`: the `frontmatterUsable` gate.
+- `both-ends-of-a-flow/*`: a dangling slice is not a complete pattern.
+- `fields-completeness/event-field-no-source`: the `assigned` marker contract (MIL-148).
+- `invariants/public-command-without-invariants`: the API-first readiness requirement (`docs/process.md`).
+
+A warning whose code is in this list blocks; any other warning never does (it stays in `diagnostics`; don't treat it as a blocker). `--strict` promotes advisory rules only.
+
 **`ready: false` means stop** — with one named exception: a slice already `status: implemented`
 with `driftSignal: in-sync` or `uncertified` (MIL-214) also reads `ready: false` (its
 `statusReady` gate fails because nothing is newly ratified), and that specific case is

package/plugin/skills/review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review
-em-version: 1.18.0
+em-version: 1.19.0
 description: >-
   Use when starting em's live browser viewer (`em watch --serve`) so a team can watch a model
   update in real time, or facilitating a SCHEDULED stakeholder walkthrough that steps through
@@ -66,7 +66,9 @@ review:` marker (mirrors `Last conformance:`).
 
 Then, and only then: a slice with nothing left `- [ ]` and no open `issue` →
 `em slice review <model>.em <key> --by <name>` (flips its doc to `status: reviewed` and records
-`reviewedBy:`/`reviewedOn:`). Anything still open stays `draft` — the walkthrough doesn't decide
+`reviewedBy:`/`reviewedOn:`). `em slice review` itself exits 1 on an unchecked Open Question
+(`--allow-open` records a deliberately partial walk; `--again` re-records a review after a body edit).
+Anything still open stays `draft` — the walkthrough doesn't decide
 it, the next session or the open-questions list does.
 
 **The facilitator never ratifies, never offers to ratify, and never suggests ratification in a