@milehimikey/em 1.14.2 → 1.15.0

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

@@ -120,12 +120,12 @@ including sessions started from bare `/em:event-modeling`.
 - **Version rule: never bump a draft's `version:` on edit.** A `draft`/`reviewed` doc is edited
   in place. Check the release state with `em status <model>.em --json`: the model is
   **pre-release** when its `modelVersion` entry has `design: null` and
-  `slices.byStatus.implemented === 0`. Pre-release: never run `em slice reratify`; edit
+  `slices.byStatus.shipped === 0`. Pre-release: never run `em slice revise`; edit
   `draft`/`reviewed` docs in place and leave `version:` as it is. A pre-release doc that is
   already ratified (`ready-to-implement` with `ratifiedBy`) carries a human sign-off: STOP,
   record the needed change as an open question, and let the ratifier decide. Released (either
-  condition false): changing an `implemented` or ratified doc goes through `em slice reratify`
-  (see `em:design`).
+  condition false): changing a shipped or ratified doc goes through `em slice revise`, which
+  opens the next version as a `draft` (see `em:design`).
 - **Pre-commit check (STOP on any finding).** Stage the session's files, then run both:
   1. `em system scope --staged` from the repository root. Any `seam-crossing` error → STOP:
      unstage the other model's files and record a seam change request instead.

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

@@ -68,8 +68,13 @@ to decide `frontmatter-invalid` without re-deriving frontmatter-shape rules of i
 | `reviewedOn` | string | `YYYY-MM-DD` | written only by `em slice review` (MIL-201); joined into `em export`'s `slice.doc.reviewedOn` (schema `1.11`) |
 | `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`) |
-| `meaningConfirmed` | boolean | `true` | written only by `em slice ratify`/`reratify --meaning-unchanged` (MIL-238 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-ratify-file-slice-key---by-name)): the API-first sign-off on a public-touching slice — this version does not change what the public contract means. Joined into `em export`'s `slice.doc.meaningConfirmed` (schema `1.15`; `false` when absent) |
-| `contractChange` | string | quoted free text (`contractChange: "<why>"`) | written only by `em slice ratify`/`reratify --contract-change "<why>"` (MIL-238): the API-first sign-off on a public-touching slice — why a consumer must read this change differently. Joined into `em export`'s `slice.doc.contractChange` (schema `1.15`, quotes stripped; `null` when absent) |
+| `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 or outside git. Cleared by `em slice reratify`. 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) — the signed content's identity without git. Cleared by `em slice reratify`. Read by `em validate --slice-ready` (`slice-ready-body-changed-since-ratification`); 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 |
+| `shippedOn` | string | `YYYY-MM-DD` | written only by `em slice mark-implemented` (MIL-284): the local date of the merge record, or `--on <date>` |
+| `meaningConfirmed` | boolean | `true` | written only by `em slice ratify --meaning-unchanged` (MIL-238 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-ratify-file-slice-key---by-name)): the API-first sign-off on a public-touching slice — this version does not change what the public contract means. Joined into `em export`'s `slice.doc.meaningConfirmed` (schema `1.15`; `false` when absent) |
+| `contractChange` | string | quoted free text (`contractChange: "<why>"`) | written only by `em slice ratify --contract-change "<why>"` (MIL-238): the API-first sign-off on a public-touching slice — why a consumer must read this change differently. Joined into `em export`'s `slice.doc.contractChange` (schema `1.15`, quotes stripped; `null` when absent) |
 | `owner` | string | free text (typically a person or team name) | hand-filled — no `em` command writes it; joined into `em export`'s `slice.doc.owner` (schema `1.9`, MIL-171), `em slice index`'s Owner column, and `em status`'s per-slice `owners[]` |
 | `tracking` | string | free text (typically an external ticket/issue URL) | hand-filled — no `em` command writes it; joined into `em export`'s `slice.doc.tracking` (schema `1.9`, MIL-171) and `em slice index`'s Tracking column. This is the exact field `em-tracker-bridge` reads to find the ticket mirroring this slice — `em` only stores and displays it, it never talks to a tracker itself |
 | `conformedVersion` | integer | positive integer | written only by `em slice conform` (MIL-214 — see [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-conform-file-slice-key---at-rev)): this slice's `version:` at the time a conform sweep last certified it. Joined into `em export`'s `slice.doc.conformedVersion` (schema `1.13`); paired with `version` to compute `slice.doc.driftSignal`'s `"uncertified"` case |
@@ -246,7 +251,7 @@ straight through to the originating slice's own doc, exactly the way a ratified
 binding resolves a covered slice — same `doc.found`/`status`/`driftSignal`, plus a
 `continuationOf: <originating-key>` field naming why. `em export`, `em status`, `em coverage`,
 `em slice index`, `em catalog`, and the render pipeline's Slice Status legend all resolve a
-continuation slice this way; `em slice ratify`/`review`/`reratify`/`mark-implemented` and
+continuation slice this way; `em slice ratify`/`review`/`revise`/`mark-implemented` and
 `em slice new --wire` refuse on one outright, naming the originating slice to act on instead —
 a continuation slice has no status/ratification of its own to flip.
 
@@ -483,7 +488,7 @@ prior one — exactly the ambiguity a live, current-version-only section avoids.
 **Deferral marker (MIL-275).** A question this version will not answer is not left `- [ ]` and
 not deleted: `em slice defer` checks it and rewrites it as `- [x] <original> — v<current>:
 <decision>; deferred to v<n> (<date>[, <by>])`. The `deferred to v<n>` marker is what
-`em slice reratify` reads: when a bump reaches v<n> it rewrites each such item back to
+`em slice revise` (and `mark-implemented`, which opens v<n> at merge when something is deferred to it) reads: when the doc reaches v<n> it rewrites each such item back to
 `- [ ] <original>`, so the question must be resolved or re-deferred before `--slice-ready` passes
 again. The prune rule above does not apply to a deferred item before v<n> (it stays as the
 record); once reopened it is an ordinary open question.
@@ -498,26 +503,51 @@ actually happened on re-ratification).
 
 ## `status` under re-ratification
 
-When a new version is ratified for a slice whose previous version already shipped, `status`
-tracks the **current version's** implementation state, not a running "has this ever shipped"
-flag. Ratifying v2 on an `implemented` slice flips `status` back to `ready-to-implement`, while
-`implementedIn` keeps naming the v1 PR until v2 ships. That deliberate mismatch — version 2,
-implemented-link still pointing at v1's work — is not staleness, it's the **drift signal**: a
-reader, `em export`'s `slice.doc.driftSignal` (`"unpropagated-delta"`, schema `1.5`, MIL-85), and
-the event-modeling skill's `conform` phase all read it the same way — a ratified delta hasn't
-shipped yet, not a fresh finding against the still-live v1 code. `em validate`'s
-frontmatter-coherence check (MIL-85) deliberately never flags this combination — only
-`status: implemented` with no `implementedIn` link at all is checkable incoherence; see
+Since 1.15.0 (MIL-283) two separate facts live in the frontmatter, and every reader knows which
+one it is asking about:
+
+- **`status` is the working state** of the doc's current `version:` — `draft`, `reviewed`,
+  `ready-to-implement`, `implemented`.
+- **The shipped record is what is in production**: `shippedVersion:`/`shippedRef:`/`shippedOn:`
+  (written by `em slice mark-implemented`, MIL-284) together with `implementedIn:`. For a doc
+  shipped before 1.15 — no `shippedVersion:` — the read-both rule applies: `status: implemented`
+  means "shipped at the current `version:`". The one function that answers "has a version of this
+  slice shipped, and which" is `shippedRecordOf()` (`src/catalog/sliceDoc.ts`); `em export`
+  publishes its answer as `slice.doc.shipped`.
+
+So a shipped slice can be a `draft` again. `em slice revise <key>`
+([cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-revise-file-slice-key)) opens v<N+1> as `status: draft`, bumps
+`version:`, clears the prior version's review and sign-off, and leaves `implementedIn`/`shipped*`
+alone — v<N> stays shipped. `em slice mark-implemented` does the same automatically at merge when a
+question was deferred to v<N+1> (`em slice defer`), so known work is on the list the moment the
+previous version lands. Version 2 then takes both human gates like version 1 did: `em slice review
+--by`, then `em slice ratify --by` (which records a fresh `ratifiedRef`/`ratifiedHash`).
+
+The deliberate mismatch — `version: 2` open while `implementedIn`/`shippedVersion` still name v1's
+work — is not staleness, it's the **drift signal**: `em export`'s `slice.doc.driftSignal` is
+`"unpropagated-delta"` whenever `version` is past the shipped version (MIL-85/283), and the
+event-modeling skill's `conform` phase reads it as "a delta hasn't shipped yet", not a fresh finding
+against the still-live v1 code. `em validate`'s frontmatter-coherence check (MIL-85) never flags it;
+only a shipped slice with no `implementedIn` link at all is checkable incoherence
+(`implemented-without-link`); see
 [validation.md#frontmatter-coherence](https://github.com/milehimikey/em/blob/main/docs/validation.md#frontmatter-coherence).
 
-**An unshipped version has nothing to flip back** (MIL-258). A ratified doc that has not shipped
-yet (`status: ready-to-implement` with `ratifiedBy:` set) changes the same way: `em slice
-reratify` bumps `version:` and clears `ratifiedBy`/`ratifiedOn`/`reviewedBy`/`reviewedOn` (and `meaningConfirmed`/`contractChange`, MIL-238), but
-leaves `status` at `ready-to-implement` (and any `implementedIn` as it was — an absent one stays
-absent). This is the path for an answered gap mid-build. In both cases the new version is not
-ratified until `em slice ratify --by <name>` records the sign-off. A `ready-to-implement` doc with
-no `ratifiedBy` is awaiting that sign-off, so a second `reratify` refuses rather than
-double-bump; `draft`/`reviewed` docs are not ratified and are simply edited.
+**Which readers decide on the shipped record, not `status`** (MIL-283): `em status`'s
+`byStatus.shipped` count and its conformance scope, `em coverage --strict`'s default scope, `em
+conform-scope` / `em conform-supersede`'s in-scope slices, `em slice conform` (legal when shipped;
+`conformedVersion:` is the **shipped** version), the engagement Ledger's inferred `merged` and its
+outside-upstream hold, `em upgrade`'s pre-release signal, `em slice ratify`'s upstream advisory, and
+`driftSignal`. `byStatus.implemented`, the render/legend colouring and `--slice-ready` still read the
+working `status` — that is what they are about.
+
+**A ratified version that never shipped** (`status: ready-to-implement` with `ratifiedBy:` set — a
+gap answered mid-build) is revised the same way: `draft`, `version + 1`, sign-off cleared; the
+ratification of v<N> is withdrawn and nothing shipped, so no shipped record is written. **A
+`ready-to-implement` doc with no `ratifiedBy`** is the leftover of a pre-1.15 `reratify` (which
+bumped the version and left the doc unsigned at that status); no command produces it any more and
+`em slice ratify` no longer accepts it — `em slice revise` reopens it as a `draft` at the same
+version, and the normal road follows. `draft`/`reviewed` docs are not ratified and are simply
+edited; `revise` refuses them ("the next version is already open").
 
 Pair a re-ratification with a `## Delta` section (see
 [Delta section: grammar and lifecycle](#delta-section-grammar-and-lifecycle) above) recording
@@ -527,10 +557,11 @@ the ratified change in typed operation blocks, so it's reviewable without openin
 see [cli.md#em-ledger-file](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-ledger-file)) checks that `version:` and a slice doc's
 content (body + lineage refs) always change together across two git revisions — a version bump
 with no real content change, or a content change with no version bump, is a ledger bug.
-It **deliberately excludes `status`/`implementedIn`** from what counts as "content" for exactly
-the reason this section explains: a re-ratification legitimately flips `status` and leaves
-`implementedIn` naming prior work, with no version bump of its own — including either field in
-the comparison would flag every ordinary lifecycle transition as a false positive.
+It **deliberately excludes `status`/`implementedIn`** (and the `shipped*` keys) from what counts
+as "content" for exactly the reason this section explains: a lifecycle transition legitimately
+moves `status` and leaves `implementedIn`/`shippedVersion` naming prior work, with no version bump
+of its own — including those fields in the comparison would flag every ordinary lifecycle
+transition as a false positive.
 
 ## Unknown keys
 
@@ -564,7 +595,7 @@ legacy form; they're frontmatter-only from the day they were introduced.
 - [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-render-file) — slice status colors
 - [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-catalog-files) — pattern / doc lookup
 - [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-ratify-file-slice-key---by-name) — `em slice ratify`, the mechanized ratification act (`ratifiedBy`/`ratifiedOn`, schema `1.8`, MIL-165)
-- [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-reratify-file-slice-key) — `em slice reratify`, the mechanized re-ratification version bump/status flip (MIL-161)
+- [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-slice-revise-file-slice-key) — `em slice revise`, which opens the next version as a draft (the successor of `reratify`)
 - [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-export-file) — the `em export` join (`slice.pattern`/`slice.doc`, schema `1.4`, MIL-91), including `owner`/`tracking` (schema `1.9`, MIL-171)
 - [cli.md](https://github.com/milehimikey/em/blob/main/docs/cli.md#em-diff-old-new) — the `em diff` lineage annotation (schema `1.6`, MIL-84)
 - [validation.md#lineage](https://github.com/milehimikey/em/blob/main/docs/validation.md#lineage) — `em validate`'s lineage-ref resolution (MIL-84)

package/plugin/shared/templates/constitution.md

@@ -24,9 +24,9 @@ NAMED human and an ISO date, hand-filled at sign-off (no `em` command writes thi
 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
+or validates its content, and the CLI parses nothing here. Two 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
+validator) and `- **Agent models:**` (the engagement skill). In a spec-kit
 project they merge under the same headings in `.specify/memory/constitution.md`.
 -->
 
@@ -121,11 +121,9 @@ it is silent, these apply.
   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.}}
+- **Merge strategy:** {{squash | merge commit | rebase — the project's own choice. Every slice PR
+  is cut from and targets `main` (implement contract §8 rule 2), so no PR ever depends on
+  another and any strategy works; em reads nothing from this line.}}
 - **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`

package/plugin/skills/conform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conform
-em-version: 1.14.2
+em-version: 1.15.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.14.2
+em-version: 1.15.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
@@ -52,10 +52,10 @@ evidence"). In short:
 - **Evidence rule.** The `.em` model and the slice docs are the evidence for modeling
   decisions. Never read implementation source, generated contracts or `specs/` to decide a
   modeling question — ask the user. Code is read only in `extract` and `conform`.
-- **Version rule.** Never bump a draft's `version:` on edit. Before any `em slice reratify`,
+- **Version rule.** Never bump a draft's `version:` on edit. Before any `em slice revise`,
   run `em status <model>.em --json`: pre-release = the model's `modelVersion` entry has
-  `design: null` **and** `slices.byStatus.implemented === 0`. Pre-release → never run
-  `reratify`; edit `draft`/`reviewed` docs in place. Released → the re-ratification path in
+  `design: null` **and** `slices.byStatus.shipped === 0`. Pre-release → never run
+  `revise`; edit `draft`/`reviewed` docs in place. Released → the revision path in
   the `slice` phase below.
 - **Pre-commit check.** Stage the session's files, run `em system scope --staged` (STOP on any
   `seam-crossing`), then `git diff --cached --name-only` (STOP on any path outside this model's
@@ -152,7 +152,7 @@ For each slice:
    it in place and leave its `version:` alone. If `slices/<slice-name>.md` already exists with
    `status: implemented` (or is ratified and needs a change), run `em status <model>.em --json`
    first. **Pre-release** (the model's `modelVersion` entry has `design: null` and
-   `slices.byStatus.implemented === 0`): never run `em slice reratify`; a ratified doc holds a
+   `slices.byStatus.shipped === 0`): never run `em slice revise`; a ratified doc holds a
    human sign-off, so STOP, park the change as an open question, and let the ratifier decide.
    **Released** (either condition false): a doc with `status: implemented` is a
    re-ratification, not fresh authoring: hold a Socratic
@@ -213,6 +213,11 @@ For each slice:
    `--slice-ready` refuses it). A doc written before em 1.14 has no markers; leave it as it is
    unless you are re-creating it (`em slice new … --wire --force`, carrying the prose across).
    A question this version will not answer is deferred with `em slice defer <model> <key> "<question>" --until v<n> --decision "<what this version does>"` — never left `- [ ]`, never deleted, never answered by guessing.
+   When the question lives on the diagram as an `issue "..."` note rather than on the doc, use
+   `em slice defer <model> <key> --from-issue "<text>" --until v<n> --decision "<what this version does>"`
+   instead: it writes the deferred item into the doc's Open Questions and removes the note in one
+   step. A question that is *answered* is an edit to the authored section plus deleting the note —
+   never a deferral.
 2. **First-time authoring:** scaffold the doc mechanically rather than hand-writing the
    frontmatter — `em slice new "<slice name>" --pattern <state-change|state-view|automation|
    translation> --swimlane "<Persona> → <Context>" --wire <model>.em` writes `slices/<slice-name>.md`
@@ -237,23 +242,29 @@ For each slice:
    lineage key(s) by hand (`split-from`/`merged-from`/`superseded-by`, `<slice-key>@v<N>` grammar
    — see `${CLAUDE_PLUGIN_ROOT}/shared/reference/slice-doc-schema.md` for the full schema; `em validate` catches a malformed one
    after the fact, see the `lineage-*` rules below).
-   **Re-ratification (step 0) — released models only.** Confirm the model is released first
+   **Revision (step 0) — released models only.** Confirm the model is released first
    (`em status <model>.em --json`: the `modelVersion` entry's `design` is not `null`, or
-   `slices.byStatus.implemented > 0`); on a pre-release model never run `reratify`. The doc
+   `slices.byStatus.shipped > 0`); on a pre-release model never run `revise`. The doc
    already exists, so `em slice new` doesn't apply here
    (it refuses to overwrite an existing file without `--force`, and forcing would blow away the
-   doc's authored body) — run `em slice reratify <model>.em <slice-key>` instead: it bumps
-   `version` and flips `status` back to `ready-to-implement` in the existing frontmatter,
-   clearing any stale `ratifiedBy:`/`ratifiedOn:` from the prior version so a follow-up
-   `em slice ratify --by <name>` (if the team records that) applies cleanly. The same command
-   changes a ratified doc that **never shipped** (`ready-to-implement` with `ratifiedBy` set — a
-   gap answered mid-build, MIL-258): it bumps `version` and clears the sign-off but leaves
-   `status` alone. Either way the doc is not ratified until `em slice ratify --by <name>` records
-   the new sign-off. A `ready-to-implement` doc with no `ratifiedBy` is already awaiting that
-   sign-off and refuses a second `reratify`; a `draft`/`reviewed` doc is simply edited, and its
-   `version:` never moves.
+   doc's authored body) — run `em slice revise <model>.em <slice-key>` instead (MIL-283): it
+   opens the next version as a **`draft`** in the existing frontmatter — `version` bumped,
+   `status: draft`, the prior version's review and sign-off cleared — while the shipped version
+   stays shipped in the shipped record (`implementedIn:`/`shippedVersion:`, untouched). If a
+   question was deferred to this version, `em slice mark-implemented` already opened the draft
+   at merge and the question is back on the list; `revise` then refuses ("the next version is
+   already open") and you simply edit. The same command revises a ratified doc that **never
+   shipped** (`ready-to-implement` with `ratifiedBy` set — a gap answered mid-build): the
+   ratification is withdrawn and the draft opens. Either way the new version is a new spec:
+   write the delta into `## Delta`, walk it in a review session (`em slice review --by`), and
+   only then does `em slice ratify --by <name>` sign it. **Commit before ratifying (MIL-284):**
+   `em slice ratify` records the commit and body hash it signs and refuses a doc with uncommitted
+   changes — finish the doc's edits (deferrals included: `em slice defer` rewrites a body line, so
+   a deferral after sign-off trips `slice-ready-body-changed-since-ratification`), commit, then
+   ratify. A `draft`/`reviewed` doc is simply edited, and its `version:` never moves.
    **Public-touching slices (MIL-238).** On a slice that owns a `public` command, event or view,
-   `em slice ratify --by <name>` and `em slice reratify` refuse without one of two flags: pass
+   `em slice ratify --by <name>` refuses without one of two flags (`revise` takes neither — the
+   confirmation belongs to the new version's ratification): pass
    `--meaning-unchanged` when this version does not change what the public contract means, or
    `--contract-change "<why>"` when a consumer must read the change differently. Without
    either, both refuse with `slice "<key>" touches the public surface — pass

package/plugin/skills/discover/SKILL.md

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

package/plugin/skills/engagement/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: engagement
-em-version: 1.14.2
+em-version: 1.15.0
 description: >-
   Use when leading an engagement: building a named set of ratified event-modeling slices
-  (`em engagement`) into a stack of PRs by dispatching the em-implementer, em-validator,
-  em-reviewer and em-critic sub-agents, level by level, and handing the human the stack
-  bottom-first to merge. The lead session orchestrates and never writes slice code itself. To
-  build one slice by hand, use em:implement instead.
+  (`em engagement`) into one independent PR per slice, each against main, by dispatching the
+  em-implementer, em-validator, em-reviewer and em-critic sub-agents, level by level, and handing
+  the human each PR with its evidence as it passes review. The lead session orchestrates and never
+  writes slice code itself. To build one slice by hand, use em:implement instead.
 ---
 <!-- GENERATED FILE from .claude/skills/event-modeling-engagement/SKILL.md by scripts/build-plugin.ts — do not hand-edit; run npm run docs:generate -->
 
@@ -14,12 +14,20 @@ description: >-
 
 Goal: take an engagement (a named chunk of the model, `<model dir>/engagements/<slug>.md`) from
 its plan to merged PRs. You are the **lead**: you cut worktrees, dispatch scoped sub-agents,
-record every step in the Ledger with `em engagement set`, and hand the human a stack of PRs to
-merge bottom-first. You never write slice code, never merge, and never rebase a slice branch.
+record every step in the Ledger with `em engagement set`, and hand the human one PR per slice,
+each cut from and targeting `main`, to merge in any order. You never write slice code, never
+merge, and never rebase a slice branch.
+
+An engagement is a *related set* of isolated slices — a workflow, a lifecycle — built together.
+It is not a stack: no slice branch is ever cut from another slice's branch, and no PR ever
+targets another PR (MIL-280). The foundation PR (implement.md §8) already holds every event, and
+a slice never reaches into a sibling's code (§8 rule 3), so each PR compiles, tests and merges
+on its own. Levels order the work for the human's review and your dispatch; they never gate a
+merge.
 
 **Read `reference/engagement.md` before the first dispatch.** It holds the Ledger state machine,
-the evidence bundle format, the retarget check, the gap protocol and the model-selection rule
-this file uses by name. Each sub-agent runs `em:implement`'s contract
+the evidence bundle format, the gap protocol and the model-selection rule this file uses by
+name. Each sub-agent runs `em:implement`'s contract
 (`${CLAUDE_PLUGIN_ROOT}/skills/implement/reference/implement.md`) for its one slice; that contract is
 theirs, not yours.
 
@@ -43,21 +51,17 @@ Run the shared preconditions first (tool check, bundle currency, locate the mode
 2. **Foundation PR merged.** Ask the human for the foundation PR (implement.md §8) and confirm it
    has merged into `main` (`gh pr view <n> --json state` shows `MERGED`). STOP if there is none
    or it is still open. No slice branch is cut before it lands.
-3. **Merge strategy.** The constitution's "Review and merge norms" must carry the line
-   `- **Merge strategy:** merge-commits-when-stacked`. STOP if the line is absent or names any
-   other value: tell the human the engagement needs that norm and point at the constitution
-   template's "Review and merge norms" prompt
-   (`${CLAUDE_PLUGIN_ROOT}/shared/templates/constitution.md`). The constitution is the human's to
-   amend and ratify, never yours.
-4. **Agent models.** Read the line `- **Agent models:** implementer=<model>,
+3. **Agent models.** Read the line `- **Agent models:** implementer=<model>,
    validator=<model>, reviewer=<model>, critic=<model|codex>`. If it is absent, say once:
    "no Agent models line — using implementer=sonnet, validator=sonnet, reviewer=sonnet,
    critic=opus", and proceed. Apply the model-selection rule in `reference/engagement.md`
-   (the critic never runs on the implementer's model).
-5. **Worktrees are ignored.** `git check-ignore -q .claude/worktrees/x` must succeed. If it
+   (the critic never runs on the implementer's model). A constitution that still carries a
+   `- **Merge strategy:**` line from em ≤ 1.14.2 is fine: the line is ignored, never a reason to
+   stop — PRs merge with whatever strategy the project uses.
+4. **Worktrees are ignored.** `git check-ignore -q .claude/worktrees/x` must succeed. If it
    fails, STOP and ask the human to add `.claude/worktrees/` to `.gitignore` in its own commit
    on `main`.
-6. **The engagement exists.** `em engagement status <model>.em <slug>`. If there is no such
+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
    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
@@ -67,9 +71,9 @@ Run the shared preconditions first (tool check, bundle currency, locate the mode
 ## 2. Plan and confirm the ceiling once
 
 Run `em engagement plan <model>.em <slug>` (`--json` when you need the fields). Present it in
-plain terms: each level, its width against the ceiling (`parallel`), each slice's branch and
-base, and every held slice with its reason (`not-ready`, `upstream-outside-engagement-unmerged`,
-`multiple-unmerged-upstreams`, or `human`). Then ask exactly one question:
+plain terms: each level, its width against the ceiling (`parallel`), each slice's branch (every
+base is `main`), and every held slice with its reason (`not-ready`,
+`upstream-outside-engagement-unmerged`, or `human`). Then ask exactly one question:
 
 > "Ceiling N from the plan; proceed?"
 
@@ -79,13 +83,14 @@ A held slice is never started; the plan releases it when its hold clears.
 
 ## 3. Per level: cut the worktree, then dispatch the implementer
 
-Work level by level, in order. A slice in level n+1 starts only when its upstream has reached
-`awaiting-merge` or `merged`, so the base it is cut from no longer moves. Within a level, keep up
-to the ceiling of slices in flight (`building`, `validating` or `review`) at once, dispatched in
-parallel. For each slice the plan lists as not held:
+Work level by level, in order: a level's slices are dispatched before the next level's, so the
+human sees upstream slices first. Nothing in level n+1 waits for a merge — every slice is cut
+from `main`. Keep up to the ceiling of slices in flight (`building`, `validating` or `review`)
+at once, dispatched in parallel; when a slot frees, take the next not-held slice in level order.
+For each slice the plan lists as not held:
 
-1. Take `base` from the plan for this slice: `main`, or `impl/<upstream>`. **Never the current
-   HEAD**, and never a branch you picked yourself.
+1. Take `base` from the plan for this slice. It is always `main`. **Never the current HEAD**,
+   never another slice's branch, and never a branch you picked yourself.
 2. If `impl/<key>` already exists (`git rev-parse --verify --quiet impl/<key>`) or
    `.claude/worktrees/<key>` already exists, STOP for that slice and report it. Never delete,
    reuse or reset someone's branch.
@@ -95,17 +100,16 @@ parallel. For each slice the plan lists as not held:
    `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 and the absolute worktree path. It reads its own spec, the
-   constitution and the implement contract. Give it no plan, no other slice, and no merge or
-   stacking instructions.
+   constitution and the implement contract. Give it no plan, no other slice, and no merge
+   instructions.
 
 ## 4. Validate, review, criticise
 
 When the implementer returns a PR URL (and a per-invariant test map):
 
 1. `em engagement set <model>.em <slug> <key> --state validating --pr <url>`. Check the PR's
-   base: `gh pr view <url> --json baseRefName` must equal the Ledger's base. If not, fix it
-   with `gh pr edit <url> --base <base>`. That is a lead step; the implementer never changes a
-   base.
+   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 and the worktree path. 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
@@ -126,36 +130,31 @@ When the implementer returns a PR URL (and a per-invariant test map):
    human.
 6. `minor` findings do not loop. They go in the evidence bundle.
 
-## 5. Hand the human the stack, bottom first
+## 5. Hand the human each PR as it passes
 
 When a slice passes review: `em engagement set <model>.em <slug> <key> --state awaiting-merge`.
-Hand the human the PRs bottom-first, lowest level first, each with its evidence bundle
-(`reference/engagement.md`): the validator table, the reviewer's and critic's findings and any
-disagreement, and the per-invariant test map. Tell them, every time:
-
-- merge bottom-first, with a **merge commit** while any PR stacks on this one (implement.md §8
-  rule 2a). Squash is forbidden in that state;
-- delete the head branch on merge, so GitHub retargets the PRs that stacked on it.
+Hand the human the PR with its evidence bundle (`reference/engagement.md`): the validator table,
+the reviewer's and critic's findings and any disagreement, and the per-invariant test map. Every
+PR is independent — against `main`, carrying only its own slice — so the human merges them in
+any order, with the project's usual merge strategy (squash included), and nothing else needs
+retargeting or restacking. Suggest level order (upstream slices first) because it reads better,
+not because anything depends on it.
 
 You never merge.
 
 ## 6. After each human merge
 
 1. Update `main` in your own checkout: `git switch main && git pull --ff-only`.
-2. **Retarget check** (`reference/engagement.md`): `gh pr list --base impl/<key> --state open`
-   must be empty. For each PR still listed (the head branch was not deleted),
-   `gh pr edit <n> --base main`. Then record the new base on each dependent, keeping its state:
-   `em engagement set <model>.em <slug> <dependent> --state <its state> --base main`.
-3. `em engagement set <model>.em <slug> <key> --state merged`, then remove the worktree:
+2. `em engagement set <model>.em <slug> <key> --state merged`, then remove the worktree:
    `git worktree remove .claude/worktrees/<key>`.
-4. When every slice of a level is `merged` or `gap`, open one follow-up PR for that level from
+3. When every slice of a level is `merged` or `gap`, open one follow-up PR for that level from
    `main`: `git switch -c engagement/<slug>-level-<n> main`, run
    `em slice mark-implemented <model>.em <key> <pr-url>` for each slice merged in the level,
    then `em slice index <model>.em`, commit, and `gh pr create --base main`. The human merges it
    like any other PR.
-5. Recompute: `em engagement plan <model>.em <slug>`. Merges release holds
-   (`multiple-unmerged-upstreams` drops to one upstream, a base moves to `main`). Continue with
-   step 3 for anything newly startable.
+4. Recompute: `em engagement plan <model>.em <slug>`. A merge can release an
+   `upstream-outside-engagement-unmerged` hold once that upstream's doc reads `implemented`.
+   Continue with step 3 for anything newly startable.
 
 ## 7. Gaps
 
@@ -183,11 +182,12 @@ constitution), follow the gap protocol (`reference/engagement.md`):
 | Rule | Because |
 |---|---|
 | Never hand-edit `engagements/<slug>.md` | `em engagement set` and `close` are the only write paths; the Ledger table is generated |
-| Never restack or rebase a slice branch | Merge commits make restacking unnecessary; a rebase rewrites history a dependent was cut from |
-| Never squash a PR with an open dependent | It strands the dependent's history (implement.md §8 rule 2a) |
+| Never cut a slice branch from another slice's branch, or make a PR target another PR | Every slice PR is cut from and targets `main` (MIL-280); a stack turns isolated slices into one landing and adds merge ceremony the contract never needed |
+| Never rebase a slice branch | The branch is the implementer's; the lead orchestrates and records, it does not rewrite history |
 | Never run the implementer's work yourself | The lead orchestrates; code comes from a scoped implementer working from its own read of the spec |
 | Never dispatch beyond the ceiling | The ceiling was confirmed once for the engagement; exceeding it breaks that agreement |
-| Never cut a slice branch from the current HEAD | The base comes from the plan; any other base stacks the PR on the wrong history |
-| Never merge a PR | The human merges, bottom-first |
+| Never cut a slice branch from the current HEAD | The base is `main` from the plan; the lead's HEAD may be anything |
+| Never hold a PR back for an upstream merge | Slices do not depend on each other's branches (§8 rules 2 and 3); level order is for reading, not gating |
+| Never merge a PR | The human merges, in any order |
 | Never show the critic the reviewer's findings | The critic's value is an independent view; disagreement is a finding |
 | Never start a held slice, or ask "which slice first" | The plan decides order and holds; the human confirms only the ceiling |

package/plugin/skills/engagement/reference/engagement.md

@@ -27,17 +27,17 @@ closed engagement refuses every `set`.
 `em engagement close <model>.em <slug>` succeeds only when every slice is `merged` (recorded or
 inferred) or `gap`; `em engagement status` reports this as `closable`.
 
-A dependent's base changes once, when its upstream merges: record it with the dependent's
-current state and `--base main` (step 6.2), so the Ledger matches the PR's real base.
+Every slice's `base` is `main` (MIL-280): recorded once at `building`, never changed. A Ledger
+that still shows an `impl/<upstream>` base came from em ≤ 1.14.2; `plan` reports `main` and the
+next `set` on that slice should record `--base main`.
 
 ## The evidence bundle (step 5)
 
-Hand the human one block per PR, bottom-first, in this shape:
+Hand the human one block per PR as it passes review, in this shape:
 
 ```markdown
 ### <level n> · `<key>` · <PR URL>
-Base: `<base>` · Ledger: awaiting-merge · Stacked on it: <PR URLs of open dependents, or "none">
-Merge with: a merge commit (<a dependent is open | squash allowed: no open dependent>)
+Base: `main` · Ledger: awaiting-merge · Independent: merges in any order with the project's usual strategy
 
 Validator (em-validator, <model>):
 | Check | Result |
@@ -61,20 +61,6 @@ Per-invariant tests (from em-implementer):
 
 Copy the agents' lines verbatim; never summarise a finding away.
 
-## The retarget check (step 6.2)
-
-GitHub retargets every open PR whose base was a merged head branch to the merged PR's base, but
-only when that head branch is deleted. After each merge of `impl/<key>`:
-
-1. `gh pr list --base impl/<key> --state open --json number,headRefName` must return `[]`.
-2. For each PR it does list, run `gh pr edit <number> --base main`. Then record it:
-   `em engagement set <model>.em <slug> <dependent> --state <its current state> --base main`.
-3. Confirm with `gh pr view <number> --json baseRefName`.
-
-Because the lower PR merged with a merge commit, the dependent's diff against `main` shrinks to
-its own commits by itself. Never rebase it. If its diff still shows the upstream's commits, the
-lower PR was squashed: STOP and tell the human. Restacking that PR is their decision.
-
 ## The gap protocol (step 7)
 
 A gap is a question only the model can answer: the doc is wrong, incomplete, or contradicts the

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

@@ -1,13 +1,13 @@
 ---
 name: event-modeling
-em-version: 1.14.2
+em-version: 1.15.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
   `.event-modeling.md` state (or the given phase name) and routes to the right focused skill —
   em:discover, em:design, em:implement, em:conform,
   or em:review — or, for building a planned set of ready slices through scoped
-  sub-agents to a stack of PRs (an `em engagement`), em:engagement. If you already
+  sub-agents to one PR per slice against main (an `em engagement`), em:engagement. If you already
   know which of those applies — starting a new model, extracting from existing code,
   slicing/writing specs, implementing a ratified slice, leading an engagement, checking drift, or
   running a live/stakeholder view — invoke that skill directly instead of this one.
@@ -29,7 +29,7 @@ phase lives in.
 | `implement` | `em:implement` — building one ratified slice into merged, tested code |
 | `conform`, `validate` | `em:conform` — drift-checking a model against its codebase, walking validation diagnostics |
 | `watch`, `review` | `em:review` — the live browser viewer, facilitated stakeholder walkthroughs |
-| `engagement` | `em:engagement` — build a planned set of ready slices through scoped sub-agents to a stack of PRs |
+| `engagement` | `em:engagement` — build a planned set of ready slices through scoped sub-agents to one PR per slice, each against main |
 
 ## Routing logic
 

package/plugin/skills/implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implement
-em-version: 1.14.2
+em-version: 1.15.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