@milehimikey/em 1.7.1 → 1.8.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: MIT
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from "node:fs";
 import { cp, mkdir } from "node:fs/promises";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -11,30 +11,46 @@ import { ParseError } from "./parser/parser.js";
 import { renderDot, layoutDot, composeSvg, writeRendered, formatFromPath } from "./render/render.js";
 import { buildSliceDiagram } from "./render/sliceDiagram.js";
 import { resolveSliceArg, defaultSliceOut } from "./cli/render-inputs.js";
-import { watchFile } from "./render/watch.js";
+import { serializeBuilds, watchFile } from "./render/watch.js";
 import { startLiveServer } from "./render/serve.js";
 import { formatDiagnostic, hasErrors } from "./model/validate.js";
-import { buildExport } from "./emit/json.js";
+import { buildExport, buildSliceExport } from "./emit/json.js";
+import { buildValidateJson, buildSliceReadyJson, buildValidateListJson, collectMarkers } from "./emit/validateJson.js";
 import { buildDiffJson } from "./emit/diffJson.js";
 import { diffModels, formatModelDiff, hasChanges } from "./model/diff.js";
 import { planDiffArgs, resolveRevision, resolveDocAtRevision } from "./cli/diff-inputs.js";
 import { readSliceDoc } from "./catalog/readSliceDoc.js";
 import { validateLineage } from "./catalog/lineageValidate.js";
 import { validateFrontmatterCoherence } from "./catalog/frontmatterCoherenceValidate.js";
-import { validateSliceReady } from "./catalog/sliceReadyValidate.js";
+import { validateNoteBindings } from "./catalog/noteBindingValidate.js";
+import { validateDocModelConsistency } from "./catalog/docModelConsistencyValidate.js";
+import { validateSliceReady, computeSliceReadyGates } from "./catalog/sliceReadyValidate.js";
 import { checkLedger } from "./cli/ledgerCheck.js";
+import { planMigration, verifyMigration } from "./cli/migrateReactionShape.js";
 import { buildLedgerJson } from "./emit/ledgerJson.js";
+import { buildCoverageReport } from "./cli/coverage.js";
+import { buildCoverageJson } from "./emit/coverageJson.js";
 import { planSkillSync, applySkillSync } from "./cli/skillSync.js";
 import { checkSkillSync } from "./cli/skillCheck.js";
 import { buildSkillCheckJson } from "./emit/skillCheckJson.js";
+import { readContract } from "./cli/contract.js";
+import { createServer as createMcpServer } from "./mcp/server.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { syncAgentsMd } from "./cli/agentsMd.js";
 import { buildGlossary, detectKindConflicts, detectFieldTypeConflicts, hasConflicts, formatGlossarySummary, formatConflictLine, } from "./model/glossary.js";
 import { buildGlossaryJson } from "./emit/glossaryJson.js";
 import { planGlossaryArgs } from "./cli/glossary-inputs.js";
 import { buildCatalog } from "./catalog/build.js";
 import { planCatalogArgs } from "./cli/catalog-inputs.js";
+import { runSliceIndex } from "./cli/sliceIndex.js";
+import { runMarkImplemented } from "./cli/markImplemented.js";
+import { buildConformScope, changedPathsSince, resolveSliceDocFacts, seedAsisModel } from "./cli/conformScope.js";
+import { buildSliceDocContent, isSlicePattern, sliceDocKey, SLICE_PATTERNS } from "./cli/sliceNew.js";
 import { listModelCommits, readFileAtCommit } from "./cli/changelog-git.js";
 import { buildChangelog, parseDecisionsLog } from "./emit/changelog.js";
-import { STARTER_EM } from "./templates.js";
+import { STATE_FILE_NAME, PHASES, isPhase, loadStateFile, parseState, setPhase, setConformance, setReview, isValidDateString, } from "./cli/stateFile.js";
+import { STARTER_EM, starterEmFor, scaffoldReadme, scaffoldStateFile } from "./templates.js";
+import { kebabSlug } from "./util/slug.js";
 const program = new Command();
 // Single source of truth for the version (also read by src/emit/json.ts for
 // `generator.version` in `em export`): package.json, one level up from both
@@ -57,6 +73,29 @@ program
     writeFileSync(file, STARTER_EM);
     console.log(`wrote ${file}`);
 });
+program
+    .command("scaffold")
+    .description("scaffold a full project: <slug>/<slug>.em, README.md, .event-modeling.md " +
+    "(see docs/cli.md — for just a starter .em, use `em init`)")
+    .argument("<name>", "model display name — kebab-cased for the directory and file names, used as-is for titles/prose")
+    .option("-f, --force", "overwrite the directory's contents if it already exists")
+    .action(async (name, opts) => {
+    if (name.includes('"') || name.includes("{{")) {
+        console.error(`em scaffold: name must not contain '"' or '{{' (breaks the generated .em/README/state files): ${name}`);
+        process.exit(1);
+    }
+    const dirName = kebabSlug(name);
+    if (existsSync(dirName) && !opts.force) {
+        console.error(`refusing to overwrite ${dirName}/ (use --force)`);
+        process.exit(1);
+    }
+    await mkdir(dirName, { recursive: true });
+    const today = new Date().toISOString().slice(0, 10);
+    writeFileSync(join(dirName, `${dirName}.em`), starterEmFor(name));
+    writeFileSync(join(dirName, "README.md"), scaffoldReadme(name, dirName));
+    writeFileSync(join(dirName, STATE_FILE_NAME), scaffoldStateFile(name, dirName, today));
+    console.log(`scaffolded ${dirName}/`);
+});
 program
     .command("render")
     .description("transpile a model and render it (or emit DOT)")
@@ -72,10 +111,15 @@ program
         console.error("em render: --slice cannot be combined with --emit-dot");
         process.exit(1);
     }
-    const { dot, model, grid, diagnostics } = compileFile(file, {
+    const { dot, model, grid, diagnostics, refs } = compileFile(file, {
         keepEmptyLanes: opts.keepEmptyLanes,
     });
-    printDiagnostics(diagnostics);
+    // MIL-126: note-binding mismatches read slices/*.md alongside the model, so (like
+    // validateLineage/validateFrontmatterCoherence in `em validate`) they're computed here
+    // rather than living in compile()'s pure diagnostics. Always warning-severity — folding
+    // them in never changes whether rendering proceeds below.
+    const allDiagnostics = [...diagnostics, ...validateNoteBindings(model, refs, dirname(file))];
+    printDiagnostics(allDiagnostics);
     warnMissingNotes(file, model);
     if (opts.emitDot) {
         if (opts.out) {
@@ -87,7 +131,7 @@ program
         }
         return;
     }
-    if (hasErrors(diagnostics)) {
+    if (hasErrors(allDiagnostics)) {
         console.error("not rendering: fix the errors above");
         process.exit(1);
     }
@@ -119,9 +163,40 @@ program
     .description("export a versioned JSON snapshot of the normalized model")
     .argument("<file>", "input .em file")
     .option("-o, --out <path>", "write to a file instead of stdout")
+    .option("--slice <key>", "export only this slice's object (pattern/fields/doc) instead of the whole model (export " +
+    "key, MIL-128) — refuses only if THIS slice has an error; an unrelated slice's breakage " +
+    "elsewhere in the model doesn't block it (see docs/cli.md)")
     .action((file, opts) => {
     const { model, refs, diagnostics, source } = compileFile(file);
     printDiagnostics(diagnostics);
+    if (opts.slice) {
+        // Scoped export deliberately does NOT reuse the whole-model error guard below: the
+        // ticket's own motivation for `--slice` is an agent implementing one already-ratified
+        // slice while the rest of a large, still-WIP model has unrelated errors — the same
+        // "don't gate on breakage elsewhere" call `--slice-ready` already made (see its own
+        // scoping comment above). Only an error that concerns THIS slice (bare key, or an
+        // element ref prefixed `<key>/`) refuses.
+        const key = opts.slice;
+        const scopedErrors = diagnostics.filter((d) => d.severity === "error" && d.refs?.some((r) => r === key || r.startsWith(`${key}/`)));
+        if (scopedErrors.length > 0) {
+            console.error(`not exporting: slice "${key}" has errors — fix them first`);
+            process.exit(1);
+        }
+        const sliceExport = buildSliceExport(model, refs, diagnostics, source, file, key);
+        if (!sliceExport.found) {
+            console.error(`em export --slice: no slice with export key "${key}" in this model`);
+            process.exit(1);
+        }
+        printDiagnostics(newDiagnostics(sliceExport.diagnostics, diagnostics));
+        if (opts.out) {
+            writeFileSync(opts.out, sliceExport.text + "\n");
+            console.log(`wrote ${opts.out}`);
+        }
+        else {
+            process.stdout.write(sliceExport.text + "\n");
+        }
+        return;
+    }
     if (hasErrors(diagnostics)) {
         console.error("not exporting: fix the errors above");
         process.exit(1);
@@ -277,6 +352,95 @@ program
     const sliceWord = result.slices === 1 ? "slice" : "slices";
     console.log(`wrote ${opts.out}/ (${result.models} ${modelWord}, ${result.slices} ${sliceWord})`);
 });
+// Namespace for slice-doc authoring/maintenance subcommands: `new` (MIL-97, scaffolds a fresh
+// slice doc's frontmatter) and `index` (MIL-98, regenerates the model README's Slices table)
+// share the `em slice <verb>` shape rather than living as separate top-level commands.
+const slice = program.command("slice").description("author and maintain slice docs");
+slice
+    .command("new")
+    .description("scaffold a fresh slices/<key>.md doc — the 5 frontmatter keys required at `status: draft` " +
+    "plus the `# Slice:` heading and diagram-image stub; judgment sections (Intent, " +
+    "Scenarios, Open Questions, ...) stay hand-authored (see docs/slice-doc-schema.md, " +
+    "templates/slice.md)")
+    .argument("<name>", "slice display name (e.g. \"Request Payment\") — kebab-cased for the filename")
+    .requiredOption("--pattern <pattern>", `slice pattern: ${SLICE_PATTERNS.join(" | ")}`)
+    .requiredOption("--swimlane <swimlane>", 'swimlane, e.g. "Persona → Context"')
+    .option("-f, --force", "overwrite the file if it already exists")
+    .action((name, opts) => {
+    if (!isSlicePattern(opts.pattern)) {
+        console.error(`em slice new: invalid --pattern "${opts.pattern}" — expected one of: ${SLICE_PATTERNS.join(", ")}`);
+        process.exit(1);
+    }
+    const key = sliceDocKey(name);
+    const dir = "slices";
+    const path = join(dir, `${key}.md`);
+    if (existsSync(path) && !opts.force) {
+        console.error(`refusing to overwrite ${path} (use --force)`);
+        process.exit(1);
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, buildSliceDocContent(name, key, opts.pattern, opts.swimlane));
+    console.log(`wrote ${path}`);
+    console.log(`add this to the slice's primary element in the .em file:`);
+    console.log(`  note "${path}"`);
+});
+slice
+    .command("index")
+    .description("rewrite the model's sibling README.md's GENERATED Slices table from `em export`'s slice " +
+    "facts (key, pattern, doc status/implementedIn) — the hand-maintained table is deprecated")
+    .argument("<file>", "input .em file")
+    .option("--check", "verify the table is current; exit non-zero on drift without writing (CI)")
+    .action((file, opts) => {
+    const { model, diagnostics, refs } = compileFile(file);
+    printDiagnostics(diagnostics);
+    if (hasErrors(diagnostics)) {
+        console.error("not indexing: fix the errors above");
+        process.exit(1);
+    }
+    const result = runSliceIndex(model, refs, file, !!opts.check);
+    printDiagnostics(newDiagnostics(result.table.diagnostics, diagnostics));
+    if (!result.ok) {
+        console.error(result.message);
+        process.exit(1);
+    }
+    if (result.wrote) {
+        console.log(`wrote ${result.readmePath}`);
+    }
+    else {
+        console.log(`ok — ${result.readmePath}'s Slices table is already up to date`);
+    }
+});
+slice
+    .command("mark-implemented")
+    .description("flip a slice doc's frontmatter to `status: implemented` / `implementedIn: <pr-url>` — the " +
+    "one edit an implementing agent makes to a ratified doc at merge (MIL-103, replaces the " +
+    "em-sdd-bridge `em-sdd-mark-implemented` script; see reference/implement.md §6). " +
+    "Idempotent on the same URL; refuses to overwrite a different one; never touches `version:` " +
+    "or the doc body")
+    .argument("<file>", "input .em file")
+    .argument("<slice-key>", "slice export key (kebab-case)")
+    .argument("<pr-url>", "merged PR (or commit) URL")
+    .action((file, sliceKey, prUrl) => {
+    const { model, refs, diagnostics } = compileFile(file);
+    printDiagnostics(diagnostics);
+    // Scoped the same way `em export --slice`/`em validate --slice-ready` are: only an error
+    // concerning THIS slice (bare key, or an element ref prefixed `<key>/`) refuses — an
+    // unrelated slice's breakage elsewhere in a large, still-WIP model doesn't block marking
+    // this one implemented.
+    const scopedErrors = diagnostics.filter((d) => d.severity === "error" && d.refs?.some((r) => r === sliceKey || r.startsWith(`${sliceKey}/`)));
+    if (scopedErrors.length > 0) {
+        console.error(`em slice mark-implemented: slice "${sliceKey}" has errors — fix them first`);
+        process.exit(1);
+    }
+    const result = runMarkImplemented(model, refs, dirname(file), sliceKey, prUrl);
+    if (!result.ok) {
+        console.error(`em slice mark-implemented: ${result.message}`);
+        process.exit(1);
+    }
+    console.log(result.changed
+        ? `marked implemented: ${result.path} (implementedIn: ${prUrl})`
+        : `already implemented (no-op): ${result.path}`);
+});
 program
     .command("changelog")
     .description("render a model's git history as a business-readable ledger (see docs/cli.md)")
@@ -299,6 +463,124 @@ program
         process.stdout.write(markdown + "\n");
     }
 });
+const STATE_DIR_HELP = "model directory containing .event-modeling.md, or a direct path to that file (default: current directory)";
+/** Shared by every `em state` writer: load, apply the pure patch, write, report — the only
+ *  difference between set-phase/set-conformance/set-review is which `mutate` closure they pass. */
+function writeStateUpdate(dirOrFile, cmdLabel, mutate) {
+    const loaded = loadStateFile(dirOrFile);
+    if (!loaded.ok) {
+        console.error(loaded.message);
+        process.exit(1);
+    }
+    const today = new Date().toISOString().slice(0, 10);
+    const result = mutate(loaded.text, today);
+    if (!result.ok) {
+        console.error(`${cmdLabel}: ${result.message}`);
+        process.exit(1);
+    }
+    writeFileSync(loaded.path, result.text);
+    console.log(`wrote ${loaded.path}`);
+}
+const state = program
+    .command("state")
+    .description("read/write the state file's mechanical fields deterministically (see docs/cli.md)");
+state
+    .command("read")
+    .description("print the state file's mechanical fields as JSON")
+    .argument("[dir]", STATE_DIR_HELP, ".")
+    .action((dir) => {
+    const loaded = loadStateFile(dir);
+    if (!loaded.ok) {
+        console.error(loaded.message);
+        process.exit(1);
+    }
+    const parsed = parseState(loaded.text);
+    if (!parsed.ok) {
+        console.error(`em state read: ${parsed.message}`);
+        process.exit(1);
+    }
+    console.log(JSON.stringify(parsed.state, null, 2));
+});
+state
+    .command("set-phase")
+    .description("rewrite Current phase: (and Last updated:); --step also rewrites Current step:")
+    .argument("<phase>", `phase: ${PHASES.join(" | ")}`)
+    .argument("[dir]", STATE_DIR_HELP, ".")
+    .option("--step <n>", "also set Current step: to this value")
+    .action((phase, dir, opts) => {
+    if (!isPhase(phase)) {
+        console.error(`em state set-phase: invalid phase "${phase}" — expected one of: ${PHASES.join(", ")}`);
+        process.exit(1);
+    }
+    writeStateUpdate(dir, "em state set-phase", (text, today) => setPhase(text, phase, today, opts.step));
+});
+state
+    .command("set-conformance")
+    .description("rewrite Last conformance: (and Last updated:) in the exact format reference/conform.md parses")
+    .argument("<revision>", "target-repo revision just diffed against")
+    .argument("[dir]", STATE_DIR_HELP, ".")
+    .requiredOption("--report <path>", "path to the conformance report just written")
+    .action((revision, dir, opts) => {
+    writeStateUpdate(dir, "em state set-conformance", (text, today) => setConformance(text, revision, opts.report, today));
+});
+state
+    .command("set-review")
+    .description("rewrite Last stakeholder review: (and Last updated:)")
+    .argument("<date>", "review date, YYYY-MM-DD")
+    .argument("[dir]", STATE_DIR_HELP, ".")
+    .action((date, dir) => {
+    if (!isValidDateString(date)) {
+        console.error(`em state set-review: invalid date "${date}" — expected YYYY-MM-DD`);
+        process.exit(1);
+    }
+    writeStateUpdate(dir, "em state set-review", (text, today) => setReview(text, date, today));
+});
+program
+    .command("conform-scope")
+    .description("mechanize conform phase step 1 (reference/conform.md): map the target repo's changed paths " +
+    "since Last conformance: to slices via each slice doc's implementedIn, JSON to stdout — " +
+    "--seed-asis also seeds the <model>-asis.em scratch model (see docs/cli.md)")
+    .argument("<file>", "input .em file")
+    .requiredOption("--repo <path>", "path to (or inside) the target codebase's git repository")
+    .option("--full", "ignore Last conformance:/changed paths; scope every implemented slice")
+    .option("--seed-asis", "write <model>-asis.em as a byte copy of the canonical model and ensure it's gitignored")
+    .action((file, opts) => {
+    const { model, diagnostics, refs } = compileFile(file);
+    printDiagnostics(diagnostics);
+    if (hasErrors(diagnostics)) {
+        console.error("not scoping: fix the errors above");
+        process.exit(1);
+    }
+    const loaded = loadStateFile(dirname(file));
+    if (!loaded.ok) {
+        console.error(loaded.message);
+        process.exit(1);
+    }
+    const parsed = parseState(loaded.text);
+    if (!parsed.ok) {
+        console.error(`em conform-scope: ${parsed.message}`);
+        process.exit(1);
+    }
+    const { lastConformance } = parsed.state;
+    const { facts, diagnostics: docDiags } = resolveSliceDocFacts(model, refs, dirname(file));
+    printDiagnostics(newDiagnostics(docDiags, diagnostics));
+    const skipGit = !!opts.full || lastConformance === null;
+    let changedPaths = [];
+    if (!skipGit) {
+        const result = changedPathsSince(opts.repo, lastConformance.revision);
+        if (!result.ok) {
+            console.error(result.message);
+            process.exit(1);
+        }
+        changedPaths = result.paths;
+    }
+    const scope = buildConformScope(facts, lastConformance, changedPaths, !!opts.full);
+    const output = { ...scope };
+    if (opts.seedAsis) {
+        output.seeded = seedAsisModel(file);
+    }
+    console.log(JSON.stringify(output, null, 2));
+});
 program
     .command("watch")
     .description("re-render on every save")
@@ -312,16 +594,24 @@ program
     const out = opts.out ?? defaultOut(file, opts.format ?? "svg");
     const fmt = opts.format ?? formatFromPath(out);
     let server;
-    const build = async () => {
+    // serializeBuilds: chokidar can fire several events for one save (and an
+    // editor's write can land while a slow png/pdf render is still in flight) —
+    // overlapping builds would race each other writing the same output file.
+    const build = serializeBuilds(async () => {
         const started = Date.now();
         try {
-            const { dot, model, grid, diagnostics } = compileFile(file, {
-                keepEmptyLanes: opts.keepEmptyLanes,
-            });
+            const { dot, model, grid, diagnostics } = compileFile(file, { keepEmptyLanes: opts.keepEmptyLanes }, 
+            // A bad save must not kill the watcher: the error is reported below
+            // and pushed to the live view's banner instead.
+            { survive: true });
             printDiagnostics(diagnostics);
             warnMissingNotes(file, model);
             if (hasErrors(diagnostics)) {
                 console.error("skipped render (errors above)");
+                // The shared screen must say WHY it's stale, not silently show an
+                // outdated model — push the first error into the viewer's banner.
+                const first = diagnostics.find((d) => d.severity === "error");
+                server?.notifyError(first ? formatDiagnostic(first).trim() : "model has errors — see terminal");
                 return;
             }
             await renderDot(dot, model, grid, out, fmt, dirname(file));
@@ -330,16 +620,25 @@ program
         }
         catch (e) {
             reportError(e);
+            server?.notifyError(e instanceof Error ? e.message : String(e));
         }
-    };
+    });
     await build();
     if (opts.serve) {
         try {
             // Serve the directory the SVG is written to — that's what the browser
             // fetches, and note "..." links inside the SVG resolve relative to it.
             server = await startLiveServer({ dir: dirname(resolve(out)), port: opts.port });
-            console.log(`→ live view: ${server.url}/?svg=${encodeURIComponent(basename(out))}`);
-            console.log("  open it in a browser and share your screen");
+            // The viewer inlines SVG only — for png/pdf watches there's nothing
+            // live to embed, so don't print a ?svg= URL that can't work.
+            if (fmt === "svg") {
+                console.log(`→ live view: ${server.url}/?svg=${encodeURIComponent(basename(out))}`);
+                console.log("  open it in a browser and share your screen");
+            }
+            else {
+                console.log(`→ serving ${dirname(resolve(out))} at ${server.url}`);
+                console.log("  (the live viewer needs an .svg output — add -o <name>.svg to use it)");
+            }
         }
         catch (e) {
             reportError(e);
@@ -350,6 +649,8 @@ program
     // the .em file. The glob still fires for docs authored after watch starts.
     watchFile([file, join(dirname(file), "slices", "*.md")], build);
     console.log(`watching ${file} … (ctrl-c to stop)`);
+    if (!opts.serve)
+        console.log("tip: add --serve for the live browser view");
 });
 program
     .command("validate")
@@ -365,25 +666,33 @@ program
     .option("--fail-on-issues", "exit non-zero if the model has any open `issue`s (opt-in — issues are warnings and don't block by default)")
     .option("--slice-ready <key>", "readiness gate for one slice (export key): status ready-to-implement, doc resolvable via " +
     "note binding, zero unchecked Open Questions — exits non-zero if not ready (MIL-87)")
+    .option("--json", "print a JSON document instead of text — works on a model WITH errors, unlike `em export` " +
+    "(MIL-128, see docs/cli.md); exit codes are unchanged")
     .action((file, opts) => {
     const { model, diagnostics, refs } = compileFile(file);
-    // Lineage-ref resolution (MIL-84) and frontmatter-coherence (MIL-85) are validate's
-    // fs-aware rules — every other check above is a pure function of the .em source. Both
-    // read slices/*.md alongside the model.
+    // Lineage-ref resolution (MIL-84), frontmatter-coherence (MIL-85), note-binding
+    // mismatches (MIL-126), and doc↔model consistency (MIL-124) are validate's fs-aware
+    // rules — every other check above is a pure function of the .em source. All four read
+    // slices/*.md alongside the model. Doc↔model consistency is deliberately validate-only
+    // (unlike note-binding, which `em render` also folds in) — it's a conform-phase concern,
+    // not something every render needs to recheck.
     const allDiagnostics = [
         ...diagnostics,
         ...validateLineage(model, refs, dirname(file)),
         ...validateFrontmatterCoherence(model, refs, dirname(file)),
+        ...validateNoteBindings(model, refs, dirname(file)),
+        ...validateDocModelConsistency(model, refs, dirname(file)),
     ];
     if (opts.sliceReady) {
         // MIL-87: a targeted, single-slice readiness gate, not part of the unconditional
         // diagnostic set above (see sliceReadyValidate.ts's header for why). Folds in MIL-85's
-        // frontmatter-coherence findings for free by filtering allDiagnostics' own refs, rather
-        // than re-deriving that classification here.
+        // frontmatter-coherence findings, MIL-126's note-binding-mismatch findings, AND MIL-124's
+        // doc-model-consistency findings for free by filtering allDiagnostics' own refs, rather
+        // than re-deriving any of those classifications here.
         //
         // "Concerns this slice" means a ref that either IS the bare slice key (lineage,
-        // frontmatter-coherence, and this module's own diagnostics all tag that way) OR starts
-        // with `<sliceKey>/` (every element-level ref from computeRefs()/model/validate.ts,
+        // frontmatter-coherence, note-binding, and this module's own diagnostics all tag that
+        // way) OR starts with `<sliceKey>/` (every element-level ref from computeRefs()/model/validate.ts,
         // e.g. an unknown-event error on a view inside this slice). An earlier version gated on
         // "any error anywhere in the model," which silently failed the check — with zero
         // diagnostics printed — on an unrelated slice's breakage; scoping to this slice alone
@@ -395,21 +704,46 @@ program
         const scoped = combined.filter((d) => d.refs?.some((r) => r === key || r.startsWith(`${key}/`)));
         printDiagnostics(scoped);
         const ready = scoped.length === 0;
-        console.log(ready ? `slice "${key}" is ready-to-implement` : `slice "${key}" is NOT ready-to-implement`);
+        if (opts.json) {
+            // MIL-128: the 4 named gates (see computeSliceReadyGates) plus the same `scoped`
+            // diagnostics and `ready` verdict driving the exit code below — replaces both the
+            // scraped warning prose and the two hand-parsed English sentences.
+            const gates = computeSliceReadyGates(model, refs, dirname(file), key);
+            process.stdout.write(buildSliceReadyJson(file, key, gates, scoped, ready) + "\n");
+        }
+        else {
+            console.log(ready ? `slice "${key}" is ready-to-implement` : `slice "${key}" is NOT ready-to-implement`);
+        }
         if (!ready)
             process.exit(1);
         return;
     }
     if (opts.listIssues || opts.listDivergences || opts.listPublic) {
-        if (opts.listIssues)
-            printIssues(model);
-        if (opts.listDivergences)
-            printDivergences(model);
-        if (opts.listPublic)
-            printPublicElements(model);
         // Errors still fail the run below — surface them rather than exiting
         // non-zero with nothing but the list on screen.
-        printDiagnostics(allDiagnostics.filter((d) => d.severity === "error"));
+        const errorsOnly = allDiagnostics.filter((d) => d.severity === "error");
+        if (opts.json) {
+            const markers = collectMarkers(model, refs, {
+                issues: opts.listIssues,
+                divergences: opts.listDivergences,
+                public: opts.listPublic,
+            });
+            printDiagnostics(errorsOnly);
+            process.stdout.write(buildValidateListJson(file, markers, errorsOnly) + "\n");
+        }
+        else {
+            if (opts.listIssues)
+                printIssues(model);
+            if (opts.listDivergences)
+                printDivergences(model);
+            if (opts.listPublic)
+                printPublicElements(model);
+            printDiagnostics(errorsOnly);
+        }
+    }
+    else if (opts.json) {
+        printDiagnostics(allDiagnostics);
+        process.stdout.write(buildValidateJson(file, allDiagnostics) + "\n");
     }
     else {
         printDiagnostics(allDiagnostics);
@@ -421,6 +755,61 @@ program
     if (opts.failOnIssues && model.elements.some((el) => el.issue))
         process.exit(1);
 });
+program
+    .command("migrate")
+    .description("rewrite the old two-slice Automation/Translation shape into the merged single-slice " +
+    "shape MIL-120 made canonical (see docs/cli.md)")
+    .argument("<file>", "input .em file")
+    .option("--write", "apply the rewrite to the file (default: dry run — report only, write nothing)")
+    .action((file, opts) => {
+    const source = readFileOrExit(file);
+    let plan;
+    try {
+        plan = planMigration(source);
+    }
+    catch (e) {
+        if (e instanceof ParseError) {
+            console.error(`parse error in ${file} ${e.message}`);
+            process.exit(1);
+        }
+        throw e;
+    }
+    if (plan.changes.length === 0 && plan.refusals.length === 0) {
+        console.log(`nothing to migrate — ${file} has no old two-slice Automation/Translation shape`);
+        return;
+    }
+    if (plan.changes.length > 0) {
+        const verify = verifyMigration(source, plan.rewritten);
+        if (!verify.ok) {
+            console.error(`em migrate: aborting — the rewrite would introduce ${verify.newErrors.length} new error(s):`);
+            for (const d of verify.newErrors)
+                console.error(`  ${formatDiagnostic(d)}`);
+            console.error(`${file} left untouched`);
+            process.exit(1);
+        }
+    }
+    for (const c of plan.changes)
+        console.log(c.message);
+    for (const r of plan.refusals)
+        console.log(r.message);
+    if (plan.changes.length === 0) {
+        console.log(`0 site(s) migrated, ${plan.refusals.length} refused`);
+    }
+    else if (opts.write) {
+        writeFileSync(file, plan.rewritten);
+        const refusedNote = plan.refusals.length > 0 ? `, ${plan.refusals.length} refused` : "";
+        console.log(`wrote ${file} — ${plan.changes.length} site(s) migrated${refusedNote}`);
+    }
+    else {
+        const refusedNote = plan.refusals.length > 0 ? `; ${plan.refusals.length} refused` : "";
+        console.log(`${plan.changes.length} site(s) would migrate (dry run — re-run with --write to apply)${refusedNote}`);
+    }
+    // A refusal always means the file still needs a human, whether or not other sites in the
+    // same run migrated cleanly — same "set exitCode, don't truncate stdout" rationale as
+    // em ledger/em diff, even though migrate's own output is never large.
+    if (plan.refusals.length > 0)
+        process.exitCode = 1;
+});
 program
     .command("ledger")
     .description("check slice docs' version: field agrees with their content across two git revisions " +
@@ -454,6 +843,62 @@ program
     if (result.findings.length > 0)
         process.exitCode = 1;
 });
+program
+    .command("coverage")
+    .description("check that every INV-* invariant ID cited in a ready-to-implement/implemented slice doc " +
+    "is cited by a test under --tests <dir> (MIL-130) — mechanizes reference/implement.md's " +
+    "definition-of-done citation check; advisory by default, --strict for CI")
+    .argument("<file>", "input .em file")
+    .requiredOption("--tests <dir>", "directory to scan recursively for test files citing invariant IDs")
+    .option("--strict", "exit non-zero if any invariant ID has zero citations (CI)")
+    .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
+    .action((file, opts) => {
+    const { model, diagnostics, refs } = compileFile(file);
+    printDiagnostics(diagnostics);
+    if (hasErrors(diagnostics)) {
+        console.error("em coverage: model has errors — fix them first");
+        process.exit(1);
+    }
+    if (!existsSync(opts.tests)) {
+        console.error(`em coverage: --tests directory not found: ${opts.tests}`);
+        process.exit(1);
+    }
+    if (!statSync(opts.tests).isDirectory()) {
+        console.error(`em coverage: --tests is not a directory: ${opts.tests}`);
+        process.exit(1);
+    }
+    const report = buildCoverageReport(model, refs, dirname(file), opts.tests);
+    if (opts.json) {
+        process.stdout.write(buildCoverageJson(file, opts.tests, report) + "\n");
+    }
+    else {
+        for (const slice of report.slices) {
+            if (!slice.inScope)
+                continue;
+            console.log(`slice "${slice.key}" (${slice.status}):`);
+            if (slice.invariants.length === 0) {
+                console.log(`  (no INV-* invariant IDs found in the doc body)`);
+                continue;
+            }
+            for (const inv of slice.invariants) {
+                if (inv.cited) {
+                    console.log(`  cited     ${inv.id}`);
+                    for (const c of inv.citations)
+                        console.log(`              ${c.file}:${c.line}`);
+                }
+                else {
+                    console.log(`  uncovered ${inv.id}`);
+                }
+            }
+        }
+        console.log(`${report.totalInvariants} invariant(s) checked, ${report.uncoveredCount} uncovered`);
+    }
+    // Advisory by default (exit 0 even with uncovered IDs) — --strict is the opt-in CI gate,
+    // same "set exitCode, don't truncate stdout" rationale as em ledger/em diff for the --json
+    // form, and consistent for the text form too.
+    if (opts.strict && report.uncoveredCount > 0)
+        process.exitCode = 1;
+});
 // Shared by install/sync/check: the skill directory bundled with whatever em package is
 // actually running (works whether em was installed from npm or run from a checkout, and
 // regardless of a symlinked global install — see pkgDir's own resolution above for
@@ -464,6 +909,35 @@ function packagedSkillDir() {
 function vendoredSkillDir(repoRoot) {
     return join(resolve(repoRoot), ".claude", "skills", "event-modeling");
 }
+program
+    .command("contract")
+    .description("print the packaged implementation contract (reference/implement.md) to stdout — the " +
+    "agent-neutral discovery path for any agent that can run a shell, not just Claude Code " +
+    "(MIL-129); see docs/cli.md")
+    .action(() => {
+    process.stdout.write(readContract(packagedSkillDir()));
+});
+program
+    .command("mcp")
+    .description("start an MCP (Model Context Protocol) server over stdio, exposing validate/slice_ready/" +
+    "list_markers/export_model/export_slice/coverage/contract as tools (MIL-21) — a " +
+    "structured, agent-facing alternative to shelling out to `em`; see docs/mcp.md. " +
+    "Equivalent to running the `em-mcp` bin directly")
+    .action(async () => {
+    // A 3-line wrapper only, for discoverability — the server itself (src/mcp/) never imports
+    // this file or commander, matching the ticket's "outside the CLI core" constraint. The
+    // `em-mcp` bin (package.json) starts the identical server the same way.
+    await createMcpServer().connect(new StdioServerTransport());
+});
+/** One line reporting what `syncAgentsMd` did, shared by `skill install`/`skill sync` so both
+ *  commands describe the AGENTS.md write in the same words. */
+function agentsMdMessage(result) {
+    if (result.created)
+        return `created ${result.path} with the agent-contract section (MIL-129)`;
+    if (result.wrote)
+        return `updated the agent-contract section in ${result.path}`;
+    return `${result.path} already has an up-to-date agent-contract section`;
+}
 const skill = program
     .command("skill")
     .description("manage Claude Code skills bundled with em");
@@ -471,36 +945,46 @@ skill
     .command("install")
     .description("copy the event-modeling skill into .claude/skills/event-modeling/")
     .option("-f, --force", "overwrite an existing installation")
+    .option("--no-agents-md", "skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)")
     .action(async (opts) => {
     const src = packagedSkillDir();
     const dest = vendoredSkillDir(process.cwd());
     if (existsSync(dest) && !opts.force) {
         console.log(`skill already installed at ${dest}`);
         console.log("re-run with --force to overwrite");
-        return;
     }
-    await mkdir(join(process.cwd(), ".claude", "skills"), { recursive: true });
-    await cp(src, dest, { recursive: true });
-    console.log(`installed event-modeling skill → ${dest}`);
-    console.log("in Claude Code, run /event-modeling to start a guided session");
+    else {
+        await mkdir(join(process.cwd(), ".claude", "skills"), { recursive: true });
+        await cp(src, dest, { recursive: true });
+        console.log(`installed event-modeling skill → ${dest}`);
+        console.log("in Claude Code, run /event-modeling to start a guided session");
+    }
+    if (opts.agentsMd !== false) {
+        console.log(agentsMdMessage(syncAgentsMd(process.cwd())));
+    }
 });
 skill
     .command("sync")
     .description("update the vendored .claude/skills/event-modeling/ copy in [path] to match the installed " +
     "em package (overwrites unconditionally; local edits are never merged, MIL-93)")
     .argument("[path]", "consumer repo root", ".")
-    .action(async (path) => {
+    .option("--no-agents-md", "skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)")
+    .action(async (path, opts) => {
     const packagedDir = packagedSkillDir();
     const vendoredDir = vendoredSkillDir(path);
     const plan = planSkillSync(packagedDir, vendoredDir);
     if (plan.changes.length === 0) {
         console.log(`up to date — ${vendoredDir} already matches the installed skill (${plan.unchangedCount} file(s))`);
-        return;
     }
-    applySkillSync(plan, packagedDir, vendoredDir);
-    for (const c of plan.changes)
-        console.log(`${c.kind}: ${c.relPath}`);
-    console.log(`synced ${vendoredDir} — ${plan.changes.length} file(s) changed, ${plan.unchangedCount} unchanged`);
+    else {
+        applySkillSync(plan, packagedDir, vendoredDir);
+        for (const c of plan.changes)
+            console.log(`${c.kind}: ${c.relPath}`);
+        console.log(`synced ${vendoredDir} — ${plan.changes.length} file(s) changed, ${plan.unchangedCount} unchanged`);
+    }
+    if (opts.agentsMd !== false) {
+        console.log(agentsMdMessage(syncAgentsMd(resolve(path))));
+    }
 });
 skill
     .command("check")
@@ -538,12 +1022,18 @@ if (isMainModule(import.meta.url)) {
     });
 }
 // ---- helpers ----
-function compileFile(file, opts = {}) {
+function compileFile(file, opts = {}, 
+// `em watch` must OUTLIVE a bad save — a mid-edit syntax error killing the
+// watcher (and the --serve live view with it) is a session-ending failure.
+// One-shot commands keep the exit-with-message behavior.
+{ survive = false } = {}) {
     let source;
     try {
         source = readFileSync(file, "utf8");
     }
     catch {
+        if (survive)
+            throw new Error(`cannot read ${file}`);
         console.error(`cannot read ${file}`);
         process.exit(1);
     }
@@ -552,6 +1042,8 @@ function compileFile(file, opts = {}) {
     }
     catch (e) {
         if (e instanceof ParseError) {
+            if (survive)
+                throw new Error(`parse error in ${file} ${e.message}`);
             console.error(`parse error in ${file} ${e.message}`);
             process.exit(1);
         }
@@ -657,7 +1149,7 @@ function buildChangelogDoc(file, repoRoot, commits) {
     });
     const intro = models[0] ? { slices: models[0].slices.length, elements: models[0].elements.length } : null;
     const introError = models[0] ? undefined : (errors[0] ?? undefined);
-    const stateFile = join(dirname(file), ".event-modeling.md");
+    const stateFile = join(dirname(file), STATE_FILE_NAME);
     const decisions = existsSync(stateFile) ? parseDecisionsLog(readFileSync(stateFile, "utf8")) : [];
     return buildChangelog(entries, decisions, { file, intro, introError });
 }