@milehimikey/em 1.13.1 → 1.14.1

package/plugin/skills/engagement/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: engagement
+em-version: 1.14.1
+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.
+---
+<!-- GENERATED FILE from .claude/skills/event-modeling-engagement/SKILL.md by scripts/build-plugin.ts — do not hand-edit; run npm run docs:generate -->
+
+# Event Modeling — engagement (lead session)
+
+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.
+
+**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
+(`${CLAUDE_PLUGIN_ROOT}/skills/implement/reference/implement.md`) for its one slice; that contract is
+theirs, not yours.
+
+The sub-agents are `em-implementer`, `em-validator`, `em-reviewer` and `em-critic`. Under the
+plugin their dispatch names are `em:em-implementer`, `em:em-validator`, `em:em-reviewer` and
+`em:em-critic`. In a vendored repo they live in `.claude/agents/`; if they are missing, STOP and
+tell the user to run `em skill sync` (or `em upgrade`).
+
+Throughout, `<model>.em` is the model file and `<slug>` the engagement's name. Every command
+below is real; run it as written.
+
+## 1. Preconditions — STOP on each
+
+Run the shared preconditions first (tool check, bundle currency, locate the model):
+`${CLAUDE_PLUGIN_ROOT}/shared/reference/operating-principles.md` ("Preconditions"). Then:
+
+1. **Constitution ratified.** `em status <model>.em` names the constitution (`constitution.md`
+   beside the model, or `.specify/memory/constitution.md`). STOP if it is missing or its
+   `ratifiedBy:` is empty (spec-kit: no `**Ratified**:` footer). Say so and point at
+   `em:implement`'s §7; never draft house rules to get moving.
+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>,
+   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
+   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
+   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
+   selection has several unconnected components, relay its suggestion (one engagement each)
+   and let the human decide before going on.
+
+## 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:
+
+> "Ceiling N from the plan; proceed?"
+
+Ask it once per engagement. If the human names a lower number, use it for this session. **Never
+ask "which slice first"**: the levels decide the order, and the ceiling decides how many at once.
+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:
+
+1. Take `base` from the plan for this slice: `main`, or `impl/<upstream>`. **Never the current
+   HEAD**, 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.
+3. Cut the worktree yourself:
+   `git worktree add .claude/worktrees/<key> -b impl/<key> <base>`
+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 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.
+
+## 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.
+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
+   `em-reviewer` (`em:em-reviewer`) with the slice key and the PR URL. Dispatch `em-critic`
+   (`em:em-critic`) with the same two inputs, on the critic model, in fresh context. **Never
+   show the critic the reviewer's findings.** When the critic is `codex`, run the
+   prerequisite checks and the `codex exec` invocation in `reference/engagement.md` ("Codex
+   critic") in a fresh `.claude/worktrees/review-<pr>`, treat its output file as the critic's findings, and
+   fall back to `em-critic` (saying so in the evidence bundle) if any prerequisite fails.
+4. Compare the two findings lists. A blocker or major finding raised by only one of the two is
+   itself a finding for the human (record it in the evidence bundle).
+5. **Findings go back to the SAME implementer.** On a validator FAIL, or any `blocker`/`major`
+   finding: `em engagement set <model>.em <slug> <key> --state building`, then continue the same
+   implementer agent (same session, same branch, same worktree) with the failing check lines or
+   the findings. Never start a fresh implementer for it, and never fix the code yourself. When
+   it reports back, go back to step 4.1: the validator always re-runs before review does. If the
+   same finding survives two rounds, stop the loop and put it in the evidence bundle for the
+   human.
+6. `minor` findings do not loop. They go in the evidence bundle.
+
+## 5. Hand the human the stack, bottom first
+
+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.
+
+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:
+   `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
+   `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.
+
+## 7. Gaps
+
+When the implementer stops on a gap (the doc is wrong, incomplete, or contradicts the
+constitution), follow the gap protocol (`reference/engagement.md`):
+
+1. `em engagement set <model>.em <slug> <key> --state gap`.
+2. Add the question as a dated bullet under the model's `.event-modeling.md`
+   `## Open questions / parking lot`:
+   `- [ ] YYYY-MM-DD: <key> — <the question, citing the doc line> — source: engagement <slug>`.
+3. Continue with the other slices. Leave the gap slice's dependents unstarted, and tell the
+   human which they are. The doc is fixed in a design session, never in this one.
+
+## 8. End
+
+1. `em state log-usage <model>.em --phases engagement`.
+2. `em engagement status <model>.em <slug>`. When it reports `closable: true` (every slice
+   `merged` or `gap`), run `em engagement close <model>.em <slug>`. Otherwise leave it open: the
+   next lead session resumes from the Ledger.
+3. Report: what merged (PR links), what is awaiting merge, what is held and why, each gap with
+   its question, and every unresolved reviewer or critic disagreement.
+
+## Never do
+
+| 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 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 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

@@ -0,0 +1,144 @@
+<!-- GENERATED FILE from .claude/skills/event-modeling-engagement/reference/engagement.md by scripts/build-plugin.ts — do not hand-edit; run npm run docs:generate -->
+# Engagement reference — the lead session's rules
+
+The `em:engagement` skill's steps refer here by name. The commands are documented in
+full in `docs/cli.md` (`em engagement`) and the file format in `docs/engagement-schema.md`;
+neither is vendored, and this file repeats only what the lead needs mid-session.
+
+## The Ledger state machine
+
+Every Ledger write is `em engagement set <model>.em <slug> <key> --state <state> [--branch <b>]
+[--base <b>] [--pr <url>]`. The command accepts any state at any time, so the order below is the
+skill's discipline, not something em enforces. The exceptions em does enforce: setting the same
+state and values again is a no-op, `merged` is terminal (every later `set` is refused), and a
+closed engagement refuses every `set`.
+
+| State | Set at | Means | Next |
+|---|---|---|---|
+| `planned` | `em engagement new` | Selected; nothing cut yet | `building` (step 3) or `held` |
+| `building` | step 3, after `git worktree add` (with `--branch impl/<key> --base <base>`); step 4.5 when findings go back | The implementer owns the worktree | `validating`, or `gap` |
+| `validating` | step 4.1 (with `--pr <url>` the first time) | `em-validator` is running on the PR | `review` on PASS, `building` on FAIL |
+| `review` | step 4.3 | `em-reviewer` and `em-critic` are reading the PR | `awaiting-merge`, or `building` on blocker/major findings |
+| `awaiting-merge` | step 5 | Handed to the human with its evidence bundle | `merged` |
+| `merged` | step 6.3, after the human merges (also inferred, never written, once the doc reads `status: implemented`) | Terminal | — |
+| `held` | only when the human asks to park a slice (`heldBy: human`) | A human hold; the plan's own computed holds are separate (`planHeld`) and never written | `planned` when the human releases it |
+| `gap` | step 7 | The implementer stopped on a question the doc must answer | Stays `gap`; the slice comes back in a later engagement once its doc is re-ratified |
+
+`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.
+
+## The evidence bundle (step 5)
+
+Hand the human one block per PR, bottom-first, 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>)
+
+Validator (em-validator, <model>):
+| Check | Result |
+|---|---|
+| `em validate <model>.em --slice-ready <key>` | PASS |
+| `em coverage <model>.em --slice <key> --tests <dir> --strict` | PASS |
+| test command `<cmd>` | PASS |
+| diff footprint inside the slice package | PASS |
+| no diff under `slices/**`, `*.em`, `constitution.md`, `engagements/` | PASS |
+| PR body cites the slice doc | PASS |
+
+Reviewer (em-reviewer, <model>): <findings list verbatim, or NO FINDINGS>
+Critic (em-critic, <model>): <findings list verbatim, or NO FINDINGS>
+Disagreements: <each blocker/major raised by one and not the other, or "none">
+Rounds: <how many times findings went back to the implementer>; unresolved: <findings that
+survived two rounds, or "none">
+
+Per-invariant tests (from em-implementer):
+- INV-<id> -> <test file>::<test name>
+```
+
+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
+constitution. The implementer stops and reports it as the doc line plus the question.
+
+1. `em engagement set <model>.em <slug> <key> --state gap`. Leave the worktree and branch as they
+   are.
+2. Append one bullet to `.event-modeling.md` under `## Open questions / parking lot`:
+   `- [ ] YYYY-MM-DD: <key> — <question, citing the doc line> — source: engagement <slug>`
+   (today's local date).
+3. Every slice downstream of the gap stays unstarted. Name them to the human.
+4. Carry on with every other startable slice. Never answer the question yourself, never edit the
+   doc, and never let the implementer guess.
+
+The question is answered in a design session (`em:design`), which re-ratifies the
+doc. The slice is then built in a later engagement.
+
+## Model selection
+
+Models come from the constitution's `- **Agent models:** implementer=<model>, validator=<model>,
+reviewer=<model>, critic=<model|codex>` line, or from the defaults when the line is absent:
+implementer=sonnet, validator=sonnet, reviewer=sonnet, critic=opus. Pass the model with each
+dispatch; the agent definitions fix none.
+
+**The critic never runs on the implementer's model.** If the line names the same model for both,
+STOP before the first critic dispatch and tell the human. A critic on the implementer's model
+shares its blind spots, which defeats its purpose. Proceed without a critic only if the human
+says so, and record that choice in the final report.
+
+## Codex critic
+
+When the constitution's agent-models line says `critic=codex`, the critic runs through Codex instead
+of as the `em-critic` sub-agent. Its findings use the same list shape, and every rule above applies
+to them unchanged: fresh context, no access to the reviewer's findings, and disagreement is a
+finding. The Claude critic path is untouched.
+
+**Prerequisites (check; never write).** Any miss is reported to the human, the Claude critic
+(`em-critic`) runs for that PR instead, and the evidence bundle says "critic: codex unavailable
+(<reason>), ran em-critic":
+
+1. `command -v codex` succeeds.
+2. The project is trusted in Codex: `~/.codex/config.toml` has a `[projects."<repo root>"]` table with
+   `trust_level = "trusted"`. Read it; never add it. Trust is the human's to grant.
+3. If the project keeps `.codex/rules`, it is present in the review checkout. A repo without
+   `.codex/` is fine: the invocation below needs no rules file, and the lead never creates one.
+
+**Invocation** (flags verified against `codex exec --help`, codex-cli 0.159.1). Cut the review
+worktree at the PR head, save the diff, then run Codex read-only:
+
+```
+git worktree add --detach .claude/worktrees/review-<pr> <pr-head-sha>
+gh pr diff <pr> > <scratch>/pr-<pr>.diff
+codex exec --cd .claude/worktrees/review-<pr> --sandbox read-only --ephemeral \
+  --add-dir <scratch> -o <scratch>/critic-<pr>.txt "<prompt>" < /dev/null
+```
+
+`< /dev/null` is required: without it `codex exec` waits on stdin ("Reading additional input from
+stdin...") and hangs. `-o` (`--output-last-message`) writes only the final message to the file.
+The prompt gives the slice doc path, the constitution path and the diff path, says it is read-only,
+and asks for ONLY the `em-critic` list: `- [<severity>] <file:line or doc §> — <finding>`
+(`blocker`|`major`|`minor`), every finding citing a slice doc line or constitution rule, or
+`NO FINDINGS` naming what was checked. Do not pass the reviewer's findings.
+
+**Parse.** The output file is the critic's findings: keep lines matching `^- \[(blocker|major|minor)\] `
+or the `NO FINDINGS` line. If the file is missing, empty, or has neither, treat it as a failed run:
+report it and fall back to `em-critic`. Then continue with step 4 onward exactly as for the Claude
+critic. Remove the review worktree afterwards (`git worktree remove --force`).

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

@@ -0,0 +1,132 @@
+---
+name: event-modeling
+em-version: 1.14.1
+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
+  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.
+---
+<!-- GENERATED FILE from .claude/skills/event-modeling/SKILL.md by scripts/build-plugin.ts — do not hand-edit; run npm run docs:generate -->
+
+# Event Modeling with `em` — resume / route
+
+`em` drives Event Modeling through ten phases — `discover, extract, model, slice, implement,
+conform, watch, review, validate, engagement` — split across six focused skills, one per stage of
+the process. This router skill is the single entry point for `/em:event-modeling`: it figures out
+which phase applies and hands off, so you never need to remember which of the six skills a given
+phase lives in.
+
+| These phases... | ...live in this skill |
+|---|---|
+| `discover`, `extract` | `em:discover` — starting a new model, or extracting a current-state model from an existing codebase |
+| `model`, `slice` | `em:design` — structuring the model into swimlanes/patterns, writing deep slice specs |
+| `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 |
+
+## Routing logic
+
+1. Check the tool: `em --version`. If missing, tell the user to run `npm i -g @milehimikey/em`
+   and stop until installed. Then check this vendored bundle's own currency against it — see
+   `${CLAUDE_PLUGIN_ROOT}/shared/reference/operating-principles.md`'s Preconditions step 2: a bundle
+   even one minor version behind the installed em is a STOP, not a warning — only a patch-only
+   gap proceeds normally.
+2. Parse `$ARGUMENTS` for a phase name.
+   - **A recognized phase name** (`discover`, `extract`, `model`, `slice`, `implement`,
+     `conform`, `validate`, `watch`, `review`, `engagement`): look it up in the table above and invoke that
+     skill directly (via the `Skill` tool), passing the phase name along so it knows exactly
+     where to start. Don't re-derive state first — the target skill's own preconditions handle
+     that.
+   - **No argument:** locate the model (an `.event-modeling.md`/`*.em` pair in the working
+     directory, or one level down under `models/<slug>/` for a multi-model project — see
+     `${CLAUDE_PLUGIN_ROOT}/shared/reference/operating-principles.md`). If found, run
+     `em state read <dir>` and read its `phase` field as JSON — don't parse the state file's
+     bullets by hand. Map that phase through the table above and invoke the matching skill,
+     telling it to resume at the recorded `step` too. If no model exists yet, ask the user
+     whether this is a new model (`em:discover`, `discover`) or an existing system to
+     extract from (`em:discover`, `extract`), then invoke that skill.
+   - **An unrecognized argument:** treat it as free-text intent and pick the best-matching skill
+     from the table's description, same as you would if the user had asked in plain language.
+3. **Steer late work to `em:review` (MIL-236).** When the phase resolves to `slice`
+   (recorded or requested), run `em status <model>.em --json` before handing off. Recommend
+   `em:review` to the user instead of `em:design` when either holds:
+   - no slice doc is left to write or deepen: `slices.byStatus.draft === 0`,
+     `slices.byStatus.noDoc === 0`, and `slices.byStatus.reviewed +
+     slices.byStatus.readyToImplement > 0`;
+   - the state file's `## Open questions / parking lot` section has an unchecked `- [ ]` item.
+   Say why: closing open questions and walking slices to the review gate is the review skill's
+   job, not broad consistency work. Invoke `em:review` when the user agrees;
+   otherwise hand off to `em:design` as the table says.
+4. **Never do the phase work here.** Recommend the focused skill by name and hand off. Never run
+   a cross-cutting "make everything consistent" pass from this skill: no sweeping edits across
+   slice docs, no regenerating or hand-editing derived artifacts, no reading implementation code
+   to settle a modeling question. The design-session write scope below applies to anything
+   started from here.
+5. Once you've handed off, this skill's job is done for the session — the target skill owns the
+   conversation from there, including re-invoking `em:event-modeling` (this skill) itself at the end
+   if the user wants to stop and resume later.
+
+## Design-session write scope (MIL-236)
+
+These rules bind every `discover`/`model`/`slice` session, whichever skill runs it. The full
+text is in `${CLAUDE_PLUGIN_ROOT}/shared/reference/operating-principles.md` ("Write scope and
+evidence").
+
+- **Bound to one model directory.** The session is bound to the model directory it started in
+  (`dirname(<model>.em)`). Never write under another model's directory or to its contract file.
+  A question that needs another model's `public` element changed becomes a **seam change
+  request**: a dated Decisions-log bullet in THIS model's `.event-modeling.md`, and the question
+  stays open as blocked-on-upstream.
+- **Out of scope during design — never write:** generated contract artifacts
+  (`contracts/*.tsp`, any OpenAPI or JSON-schema output); SDD/spec artifacts (`specs/`,
+  `.specify/` — the constitution may be read, never written); implementation source (`src/`,
+  the model's `Code roots:`); `plugin/`; a draft slice doc's `version:`.
+- **Evidence rule.** The `.em` model and the slice docs are the evidence for modeling
+  decisions. Code is consulted only in `extract` (`em:discover`) and `conform`
+  (`em:conform`).
+
+## Shared reference material
+
+Every phase skill (and this one) points back to the same shared resources rather than
+duplicating them — read them once, they apply everywhere:
+
+- `${CLAUDE_PLUGIN_ROOT}/shared/reference/operating-principles.md` — the Socratic/validation discipline
+  every phase follows, the preconditions above in full, and the project layout these skills
+  create (including multi-model projects).
+- `${CLAUDE_PLUGIN_ROOT}/shared/reference/methodology.md` — the 7 steps and 4 patterns (Event Modeling
+  methodology).
+- `${CLAUDE_PLUGIN_ROOT}/shared/reference/em-dsl.md` — `em`'s DSL grammar, CLI reference, and the full
+  `em validate` rule catalog.
+- `${CLAUDE_PLUGIN_ROOT}/shared/templates/*.md` — the slice/state/model-readme/conformance-report
+  templates every phase scaffolds from.
+
+## em command reference (quick)
+
+<!-- GENERATED:cli-quick:start -- run `npm run docs:generate` to refresh, do not hand-edit -->
+```bash
+em --version
+em init <name>.em                          # optional starter scaffold
+em scaffold <name>                         # full project: <slug>/<slug>.em, README.md, .event-modeling.md
+em validate <name>.em                      # check rules; exit 0 if clean/warnings only
+em render <name>.em -o <name>.svg          # render (svg/png/pdf by extension)
+em render <name>.em --emit-dot             # inspect generated Graphviz DOT
+em render <name>.em --slice "<slice-name>" -o slices/<slug>.svg   # this slice's own diagram
+em watch <name>.em -o <name>.svg           # re-render on save (run in background)
+em watch <name>.em -o <name>.svg --serve   # + the live browser viewer: instant push-reload, pan/zoom (--port N)
+                                            #   click "Review mode" for a slice-by-slice storyboard walkthrough
+```
+<!-- GENERATED:cli-quick:end -->
+
+Always finish a working session by: re-rendering, running `em validate`, and updating
+`.event-modeling.md` — `em state set-phase <phase> [--step <n>]` for the current phase/step,
+decisions and open questions by hand, and `em state log-usage <model>.em --phases <phases>` for
+the Usage log entry. Before committing a design session, stage the files and run the pre-commit
+check in `${CLAUDE_PLUGIN_ROOT}/shared/reference/operating-principles.md` ("Write scope and
+evidence"): `em system scope --staged` plus `git diff --cached --name-only`; STOP on any finding.

package/plugin/skills/implement/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: implement
+em-version: 1.14.1
+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
+  readiness, treats the slice doc as the read-only spec, surfaces gaps instead of deciding them
+  silently, and requires tests traceable to the doc's invariants and scenarios.
+---
+<!-- GENERATED FILE from .claude/skills/event-modeling-implement/SKILL.md by scripts/build-plugin.ts — do not hand-edit; run npm run docs:generate -->
+
+# Event Modeling — implement
+
+Goal: turn a single `ready-to-implement` slice into merged, verified code — the one phase where
+the agent builds rather than facilitates.
+
+**Read `reference/implement.md` before doing any implement work and follow it as the
+contract.** In short: gate on `em validate <model>.em --slice-ready <key>` (stop and hand
+back if it fails — never edit the doc to make the gate pass); read the project's implementation
+constitution before writing code and stay inside its rules; before a project's first slice PR,
+land a one-time foundation PR holding every model event (plus the shared interface shell) so
+slices only ever import contracts, never invent or reach into a sibling's; build in dependency
+order from `em query upstream`, not timeline order; treat the slice doc as
+the spec (read-only, except the merge-time `status`/`implementedIn` flip); implement exactly one
+slice doc per PR — a `covers:` doc's two keys ship together in that one PR, and an `again` view
+instance is a continuation of its originating slice (no doc, status, or PR of its own — it
+ships in the originating doc's PR); ship the endpoint a
+`ui`-triggered command or `ui`-consumed view obligates, and surface — never invent — one the
+model doesn't show; surface every gap to the user instead of deciding it silently; cover every
+`INV-<MNEMONIC>-n` and every scenario with tests, proving the citations before merge with
+`em coverage <model>.em --slice <key> --tests <dir> --strict` (the default form skips a
+`ready-to-implement` slice); in spec-kit projects, allocate via
+em-sdd-bridge (redirect mode) and never run `/speckit.specify`.
+
+**Gate: no constitution, no first slice.** The constitution is the project's ratified house rules
+— stack and architectural shape (including which implementation skill each slice pattern routes
+to), code style, testing norms, NFR baselines, review/merge norms. It lives at
+`.specify/memory/constitution.md` in a spec-kit project, otherwise `constitution.md` beside the
+model; `em status` reports which, and whether it's there. If it's missing — or its `ratifiedBy:`
+is empty, meaning nobody has signed it off — run `reference/implement.md` §7 ("Before the first
+slice: the constitution") first: ask its questions conversationally, write the answers in, and
+have a human ratify them. Don't decide the project's stack or style yourself to get moving.
+
+That contract applies to any implementing agent, whether or not the session started from
+`/em:event-modeling` — `em contract` prints it to stdout with no `.claude/` awareness required, for
+an agent that can run a shell but isn't Claude Code.
+
+If the project ships pattern-specific implementation skills (for example an Axon/DCB skill set
+keyed on a slice doc's `pattern:` frontmatter), route by the slice's pattern and follow those —
+`reference/implement.md` §2 explains where that hand-off happens, and the constitution's
+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.
+
+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
+doesn't chain to another phase — run it once per ratified slice; `em:conform`'s
+`conform` phase later checks the result against the model.