@milehimikey/em 1.19.6 → 1.20.0

package/plugin/skills/conform/reference/conform.md

@@ -40,7 +40,9 @@ difference is what you do with what you find: extract *builds* a model from the
    (or the status the user says corresponds to shipped code) for whichever slices are in scope.
    Checking a `draft` or `ready-to-implement` slice against code is a wasted walk — ratified or
    not, nobody has built to it yet; tell the user and skip it rather than reporting "drift"
-   against it.
+   against it. (GH #400: the ONE exception is a deliberate pre-ship advisory run — see
+   `--preview` under step 5 below — not a reason to treat this precondition as optional for an
+   ordinary post-ship sweep.)
 3. The codebase to check: the state file's **Existing system refs** (populated during
    `extract`, if this model came from one) or ask the user for the repo path if not set. Record
    it if missing. In a headless/scheduled run with no user to ask, default to the repository
@@ -336,6 +338,32 @@ been through this) instead of just trusting `implementedIn`. Legal only for `sta
 with a link, and itself refuses if an unruled finding for that slice still exists at this
 revision — the mechanical proof this step comes only after rulings, not before.
 
+**Pre-ship advisory mode: `--preview` (GH #400).** The certify step above is legal only for a
+**shipped** slice (`status: implemented`/`shippedVersion:` + `implementedIn:`) — precondition 2
+reflects that this phase ordinarily walks shipped code. `--preview` is the deliberate exception:
+the SAME doc-resolution and findings-check read, legal for a slice that hasn't shipped yet
+(the shipped/`implementedIn:` preconditions are waived), and it **never writes anything** —
+no `conformedVersion`/`conformedAt`/`conformedOn`, ever, regardless of outcome:
+
+```
+em slice conform <model-name>.em <slice-key> --at <target-repo revision> --preview
+```
+
+Use this to run a conform sweep against your OWN implementing branch before it merges — catching
+spec/code drift while you can still fix it on the same branch, rather than after shipping. The
+walk itself (steps 1-4 above) is unchanged; only the certify step's preconditions differ. Output
+is ephemeral by default (nothing is written, not even to `conformance/`); pass
+`--write-findings` to persist the run's own unruled findings as a normal
+`conformance/<date>-<slice-key>-preview-findings.json` (this is deliberate — `docs/cli.md`'s
+`em slice conform --preview` section documents the exact shape and naming). Know before opting
+in: the written file has no sibling report (`report` is synthetic), so `em conform-supersede`
+refuses to rule on it — unruled entries in it gate certify/`set-conformance` at that revision
+until you rule them in the file by hand, delete the snapshot, or author the sibling report.
+`em state set-conformance` and the unruled-findings gates are unaffected by
+this mode either way: a default preview run writes nothing for them to read, so it can never
+block a later certify or `set-conformance` call. There is no `--slice-ready` integration for this
+mode yet.
+
 End of run: update the state file's `Last conformance:` marker with
 
 ```
@@ -343,7 +371,7 @@ em state set-conformance <target-repo revision> --report conformance/YYYY-MM-DD-
 ```
 
 — the revision is the one you just diffed against, so the next run's scope starts from here.
-The command writes the exact format step 1 parses back out; never hand-edit the bullet.
+The command writes the exact format step 1 parses back out; never hand-edit the bullet. Gates read every same-revision findings file (the report's own `-findings.json` first, else every file whose `revision` matches). The same-revision lookup uses the report's OWN revision (its `Target repo: … @ <rev>` header line; the caller's `<rev>` / `--as-of` only when the report has none).
 **Refuses (MIL-214) while any `implemented` slice still has an unruled finding** in the findings
 JSON beside the report — rule on every finding first (or certify what's already ruled via `em
 slice conform` above), or pass `--partial` to record the marker with a loud notice instead
@@ -364,7 +392,7 @@ a ruling you're only banner-stamping after the fact), run the same command witho
 em conform-supersede <model-name>.em conformance/YYYY-MM-DD-report.md --as-of <target-repo revision> --findings <spec>
 ```
 
-— stamping the report with a "superseded as of `<rev>`" banner so a later reader who finds it
+— a ruling is written to the file the report names (`<x>-report.md` <-> `<x>-findings.json`; with only per-slice files at that revision, pass the per-slice report or it refuses; `--as-of` is NOT the lookup key — the report's own `Target repo: … @ <rev>` header revision is, and `--as-of` only when the report has none) — stamping the report with a "superseded as of `<rev>`" banner so a later reader who finds it
 (a search hit, a bookmark, a link from an old PR description) sees immediately that its
 file:line citations describe an ancestor of the current model, not its current state. This is
 what keeps a superseded report an honest piece of history rather than a silently-misleading
@@ -380,7 +408,7 @@ each call adds its own stamp rather than overwriting the last.
   the gitignoring (`*-asis.em`, idempotent) mechanically, never built up from nothing and never
   hand-maintained. It's regenerated every conform run.
 - **Report location:** `conformance/<YYYY-MM-DD>-report.md` in the model directory. One file
-  per run; don't overwrite a prior date's report.
+  per run; don't overwrite a prior date's report. Its findings go in the same-stem `-findings.json`; gates read every same-revision findings file, so per-slice runs may write `<date>-<name>-findings.json`, and a ruling is written to the file the report names. The same-revision lookup uses the report's OWN revision (its `Target repo: … @ <rev>` header line; the caller's `<rev>` / `--as-of` only when the report has none).
 - **Red note wording:** `issue "conformance: <what's wrong, plainly>"` — plain enough that
   whoever ratifies it later understands the claim without re-reading the report.
 - **Naming/matching rules:** same past-tense-event / imperative-command / thing-shown-view

package/plugin/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-em-version: 1.19.6
+em-version: 1.20.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
@@ -89,10 +89,14 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    shape — reshape it with the "Reshaping an existing model" checklist. Then the **intent test**
    per command (would a business person say this name at this step in the story? an endpoint-shaped
    name fails), the **question test** per view (write the question it answers; no question, no
-   read model; a child view only when its query needs what the parent view lacks), and the
+   read model; a child view only when its query needs what the parent view lacks), the
+   **views-as-lookups check** per `from "E"` on a view (does E add, change or remove a row here? if
+   it only fills a column, put the column on the event that creates the row and drop E — see
+   `${CLAUDE_PLUGIN_ROOT}/shared/reference/methodology.md`, "Views as lookups"), and the
    **conditional-invariant signal** (invariants or fields that apply only "if `<field>` is set"
    mean two intents in one command: split it). The `timeline-entity-clustered`,
-   `command-second-intent` and `automation-split-by-outcome` lints are the mechanical half; the
+   `command-second-intent`, `automation-split-by-outcome` and `view-lookup-source` lints are the
+   mechanical half (the last one only catches the cross-context cases — do the check by eye too); the
    1.18.0 design exit gate is `em validate --shape`. Shape the model first, scaffold docs after: a rename,
    split or merge from the reshape would orphan docs already wired with `--wire`. The `slice` phase is unchanged (timeline order).
 3. **Elaborate scenarios — first pass (step 6).** Scaffold every slice's doc now, one per
@@ -131,6 +135,13 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    that reads it; another model/system reads it → mark it `public`; only an automation reads
    it → nothing, it's internal by design. No new keyword — reachability is already what `ui` and
    `public` mean.
+   **Per `view`, also ask whether each of its sources earns its place (GH #398):** for every
+   `from "E"` on the view, does E add, change or remove a row here — or only fill a column on a
+   row some other event already created? The latter is the views-as-lookups smell (methodology
+   reference, "Views as lookups"): drop E as a source and have the event that creates the row
+   carry the field instead. `view-lookup-source` flags the cross-context instances of this
+   mechanically; a lookup from the view's own context (no `@Context` mismatch to key on) only
+   this by-eye check catches.
    **Per translation fed from another model, declare what it consumes (MIL-235):** write
    `translation Order Intake consumes checkout:event.order-submitted`. The ref is
    `<modelKey>:<kind>.<slug>`, where kind is `event` or `view` and the target is marked `public`

package/plugin/skills/discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discover
-em-version: 1.19.6
+em-version: 1.20.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/extract.md

@@ -97,6 +97,14 @@ it is fine to finish a round with `# TBD`s still parked.
   read model* warnings: real systems do record fire-and-forget events. In an as-is model that is
   a **finding about the system**, not a modelling mistake — never invent a reader to silence it
   (that would be desired state). Park it in the Decisions log and carry the warning.
+  **Expect lookup-style sources too.** A lifted model will faithfully reproduce the projection's
+  lookup joins — a view wired to `from "Order Created"` only because the current query joins the
+  orders table to get `customerName`, not because this view owns any row that event changes. Wire
+  it as-is (current-state-only stance: that join is how the system behaves today); don't fix it
+  here, that would be inventing desired state. Note it as a finding in the Decisions log the same
+  way as an unread event, and leave it for `model`/`slice` to apply the views-as-lookups rule
+  (`../../../shared/reference/methodology.md`, "Views as lookups") once the as-is
+  model is agreed.
 - **R5 — Boundaries & reactions.** Current automations and integrations as-is: schedulers,
   listeners, outbound syncs, inbound webhooks. Model each as a reaction sharing its slice with
   the `command` + `event` it triggers (`reaction → command → event`, per `em-dsl.md`) — the

package/plugin/skills/engagement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: engagement
-em-version: 1.19.6
+em-version: 1.20.0
 description: >-
   Use when leading an engagement: building a named set of ratified event-modeling slices
   (`em engagement`) into one independent PR per slice, each against main, by dispatching the

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling
-em-version: 1.19.6
+em-version: 1.20.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.19.6
+em-version: 1.20.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
@@ -53,7 +53,12 @@ routing table (§7) is what names the skill set for each pattern.
 Preconditions (tool check, model location) are the same as every other phase — see
 `${CLAUDE_PLUGIN_ROOT}/shared/reference/operating-principles.md` — but this phase additionally
 requires the target slice to already be ratified; if it isn't, stop and say so rather than
-starting on unratified work.
+starting on unratified work. The one documented exception is **inline ratification** (GH #399,
+`reference/implement.md` §1a): for an internal (non-public-touching, non-engagement) slice whose
+doc is already `reviewed`, drafting code on the same branch ahead of the human's `em slice
+ratify` is sanctioned — provided you never flip the gate yourself and re-confirm
+`--slice-ready` reads `true` before treating the slice as done. `em:engagement` is
+unchanged by this: it still requires every dispatched slice ratified before its branch is cut.
 
 End of phase: PR merged, slice doc flipped to `status: implemented` with `implementedIn`
 filled, `em slice index <model-name>.em` run to refresh `README.md`'s Slices table. Implement

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

@@ -47,15 +47,82 @@ A warning whose code is in this list blocks; any other warning never does — `c
 
 Because of that list, `ready` can be `false` with every `gates` entry `true` (a `both-ends-of-a-flow/*` warning on one of the slice's own elements, say). Don't work it out from `gates`: read **`blockedBy`** (schema `1.5`, GH #377), the codes that flipped `ready`, `[]` exactly when it is `true`, and report those codes with the `false` gates when you hand the slice back.
 
-**`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
-re-implementation/repair, not a blocker — see §3's third mode before treating it as one. For
+**`ready: false` means stop** — with two named exceptions. First: 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
+re-implementation/repair, not a blocker — see §3's third mode before treating it as one. Second:
+under **inline ratification** (§1a) a slice doc that's only `status: reviewed` — not yet
+`ready-to-implement` — is a sanctioned starting point for drafting code on the SAME branch, with
+the explicit, non-negotiable condition that you treat nothing as actually ratified, and open
+nothing for merge, until a human has run `em slice ratify` and `--slice-ready` reads `true` for
+real; §1a names exactly which slices qualify and what that condition requires in practice. For
 every other `false`, report which `gates`
 entries are `false` and what `blockedBy` names (and any `diagnostics` entries concerning this
 slice) and hand the slice back to the humans. Never make the gate pass yourself — checking an open-question box, flipping
-`status`, or editing frontmatter are ratification decisions, and ratification happens in a
-facilitated session, not in an implementation branch.
+`status`, or editing frontmatter are ratification decisions, made by a human in a ratification
+session, never by you running `em slice ratify` on their behalf. That session is usually a
+separate doc-only PR, merged before an implementation branch is even cut — but it doesn't have
+to be: **inline ratification** (GH #399, §1a below) lets the session be the PR review of the
+very branch you're implementing on, for internal slices. Either shape, the rule here is the
+same: you never flip the gate yourself, whatever branch you're on.
+
+### 1a. The inline variant: ratifying on the implementation branch
+
+Most of this document assumes the ordinary shape — a slice is already `ready-to-implement` when
+you start, ratified in its own prior PR, and §1's gate reads `true` before you write a line of
+code. **Inline ratification** is the documented alternative
+(`docs/process.md`'s
+["Inline ratification" section](https://github.com/milehimikey/em/blob/main/docs/process.md#inline-ratification-approval-as-the-ratification-session)):
+draft the slice doc *and* build it on the same branch, spec commits first, and let the human's
+review of that one PR be the ratification session — which means you are, deliberately and
+sanctioned, building for most of that branch's life against a doc that reads `ready: false`.
+What doesn't change: you still never flip `status` yourself, never run `em slice ratify` on the
+human's behalf, and never write a word of the ratification record — see §1's second named
+exception for the precise condition this depends on. What's different is sequencing and tiering:
+
+- **Draft the doc first, then build on the same branch.** Commit the slice doc (through the
+  normal `slice` phase), get it reviewed (`em slice review --by`, flipping it to `status:
+  reviewed` — a human has to do this part too, same as always) before any implementation code,
+  even though doc and code will both live on one branch and merge in one PR. Writing code before
+  the doc exists, or before a human has looked at it, is retrofit — the exact failure mode inline
+  mode is named after avoiding — whether or not anyone ever checks for it.
+- **You may keep building past a `reviewed`-but-not-yet-`ready-to-implement` doc, but nothing is
+  ratified until `em slice ratify` actually runs.** `--slice-ready` keeps reading `false` the
+  whole time you're building — that's expected, not a signal to stop, as long as the doc's
+  `status` is `reviewed` (not `draft`: an un-reviewed doc is never a valid base, inline or not).
+  On an inline branch the human typically runs `em slice ratify --no-ref` as part of approving
+  the PR (`--no-ref` because the branch is headed for a squash/rebase merge) — not something you
+  do for them, and not something you should expect to have happened before the PR is up for
+  review. Before you report the slice done, or treat §6's merge-time flip as legitimate,
+  re-check `--slice-ready` yourself and confirm it now reads `true` with `ratifiedBy:` set — if
+  it still doesn't, the slice isn't ratified yet and you say so instead of proceeding.
+- **A post-signature doc edit still trips the hash check.** `ratifiedHash` doesn't know or care
+  which branch it was computed on — if something changes the doc's body after the human has
+  signed it (a gap surfaces, §4), `--slice-ready` and `em slice ratify` both refuse the stale
+  signature exactly as they would across two PRs. Route it through `em slice revise --withdraw`,
+  review, re-ratify (§4) — inline doesn't shortcut that loop, it just means the re-sign happens
+  on the branch you're already on instead of a fresh one.
+- **Not every slice is a candidate.** A slice owning a `public` command, event or view
+  (`isPublicTouchingSlice`) keeps the separate doc PR — the contract is a promise to consumers
+  who never see your implementation diff, and `em slice ratify` already refuses a public-touching
+  slice without `--meaning-unchanged`/`--contract-change` regardless of which branch it runs on.
+  An engagement-dispatched slice is never inline either — engagements structurally need every
+  contract frozen before any implementer branch is cut, so the engagement skill never offers you
+  this shape (it is explicitly unchanged by GH #399 — this is a note for your own judgment
+  outside an engagement, not something to apply inside one).
+- **Pre-ship advisory conform is the loop's natural checkpoint.** Before the PR merges, a human
+  (or you, if asked) can run `em slice conform <model>.em <key> --at <rev> --preview` — the
+  pre-ship, non-certifying mode (GH #400): same doc-resolution and findings-check read as a real
+  certification, legal before the slice has shipped, never writes `conformedVersion:`/
+  `conformedAt:`/`conformedOn:`. It's advisory and ephemeral by default (nothing written unless
+  `--write-findings` is passed) — a cheap "did I just drift from the doc I signed" look before
+  asking for the PR review that will also be the ratification.
+- **The ordering advisory is informational, not yours to act on.** `em refs --check-order`
+  (GH #399) can report whether a commit on this branch touched code before the doc's
+  `ratifiedRef` — a retrofit smoke signal for the human reviewing the PR. It's advisory, never a
+  gate, and nothing in this skill asks you to run it or react to its output; if a human shows you
+  a `code-before-ratification` result, treat it the same as any other gap raised against your
+  work (§4), not as something to silence.
 
 ## 2. Read the spec
 

package/plugin/skills/review/SKILL.md

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