@milehimikey/em 1.9.1 → 1.11.0

package/dist/cli.js

@@ -28,12 +28,12 @@ import { validateDocModelConsistency } from "./catalog/docModelConsistencyValida
 import { validateOrphanedSliceDocs } from "./catalog/orphanedSliceDocValidate.js";
 import { validateSliceReady, computeSliceReadyGates } from "./catalog/sliceReadyValidate.js";
 import { detectSliceDocCollisions } from "./catalog/modelCollisionValidate.js";
-import { checkLedger } from "./cli/ledgerCheck.js";
+import { checkLedger, readLedgerWaiverTrailers, applyLedgerWaivers } 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 { resolveSliceStatusFacts, countOpenIssues, resolveConformanceEntry, aggregateInvariantTotals, buildStatusReport, formatStatusText, formatStatusMarkdown, buildStatusBadge, formatConformancePart, } from "./cli/status.js";
+import { resolveSliceStatusFacts, countOpenIssues, resolveConformanceEntry, aggregateInvariantTotals, buildStatusReport, formatStatusText, formatStatusMarkdown, buildStatusBadge, formatConformancePart, findSpecifyRoot, } from "./cli/status.js";
 import { buildStatusJson } from "./emit/statusJson.js";
 import { buildFreshnessJson } from "./emit/freshnessJson.js";
 import { planSkillSyncBundle, applySkillSyncBundle } from "./cli/skillSync.js";
@@ -52,6 +52,7 @@ import { planCatalogArgs } from "./cli/catalog-inputs.js";
 import { runSliceIndex } from "./cli/sliceIndex.js";
 import { runMarkImplemented } from "./cli/markImplemented.js";
 import { runRatify } from "./cli/ratify.js";
+import { runReview } from "./cli/review.js";
 import { runConformSupersede } from "./cli/conformSupersede.js";
 import { buildConformScope, changedPathsSince, resolveSliceDocFacts, seedAsisModel } from "./cli/conformScope.js";
 import { buildSliceDocContent, isSlicePattern, sliceDocKey, SLICE_PATTERNS } from "./cli/sliceNew.js";
@@ -59,13 +60,21 @@ import { wireSliceNote } from "./cli/sliceLink.js";
 import { listModelCommits } from "./cli/changelog-git.js";
 import { buildChangelogDoc } from "./cli/changelogBuild.js";
 import { runReratify } from "./cli/reratify.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 { STATE_FILE_NAME, PHASES, isPhase, loadStateFile, parseState, setPhase, setConformance, setReview, isValidDateString, modelPathMismatch, } from "./cli/stateFile.js";
+import { STARTER_EM, starterEmFor, scaffoldReadme, scaffoldStateFile, scaffoldConstitution } from "./templates.js";
 import { kebabSlug } from "./util/slug.js";
 import { ciWorkflowPath, conformWorkflowPath, buildCiWorkflowFile, buildConformWorkflowFile, ciManagedBody, conformManagedBody, planCiFile, applyCiFile, findUnsafeCiInitArg, CI_WORKFLOW_MARKER, CONFORM_WORKFLOW_MARKER, } from "./cli/ciInit.js";
 import { RULES } from "./model/rules.js";
 import { USAGE_PHASES, isUsagePhase, sortUsagePhases, appendUsageLogEntry, findStateFiles, aggregateUsageReport, formatUsageReportText, } from "./cli/usageLog.js";
 import { buildUsageReportJson } from "./emit/usageReportJson.js";
+import { compileForQuery } from "./query/pipeline.js";
+import { buildQuerySystem } from "./query/system.js";
+import { queryConsumers, queryProducers, queryDownstream, queryUpstream, querySlices, queryInvariant, queryField, queryPath, } from "./query/verbs.js";
+import { formatConsumers, formatProducers, formatClosure, formatSlices, formatInvariant, formatField, formatPath, } from "./query/format.js";
+import { buildQueryJson } from "./emit/queryJson.js";
+import { loadSystem } from "./cli/systemInputs.js";
+import { verifySystem } from "./system/verify.js";
+import { buildSystemJson } from "./emit/systemJson.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
@@ -90,7 +99,9 @@ program
 });
 program
     .command("scaffold")
-    .description("scaffold a full project: <slug>/<slug>.em, README.md, .event-modeling.md " +
+    .description("scaffold a full project: <slug>/<slug>.em, README.md, .event-modeling.md, and " +
+    "constitution.md (the implementation constitution — skipped, with a note, in a spec-kit " +
+    "project, where `.specify/memory/constitution.md` IS that document) " +
     "(see docs/cli.md — for just a starter .em, use `em init`; for a multi-model project, " +
     "pass --under to nest it under a shared parent directory)")
     .argument("<name>", "model display name — kebab-cased for the directory and file names, used as-is for titles/prose")
@@ -114,7 +125,18 @@ program
     writeFileSync(join(dirPath, `${slugName}.em`), starterEmFor(name));
     writeFileSync(join(dirPath, "README.md"), scaffoldReadme(name, slugName));
     writeFileSync(join(dirPath, STATE_FILE_NAME), scaffoldStateFile(name, slugName, today));
+    // MIL-202: the implementation constitution. One document per project, never two — in a
+    // spec-kit project `.specify/memory/constitution.md` already IS that slot, so em defers to it
+    // and writes nothing rather than seeding a second, competing copy beside the model. Same
+    // walk-up resolution `em status` reports with (src/cli/status.ts's resolveConstitution).
+    const specifyRoot = findSpecifyRoot(dirPath);
+    if (!specifyRoot)
+        writeFileSync(join(dirPath, "constitution.md"), scaffoldConstitution(name));
     console.log(`scaffolded ${dirPath}/`);
+    if (specifyRoot) {
+        console.log("note: .specify/ found — the implementation constitution is .specify/memory/constitution.md " +
+            "(spec-kit's file); em writes no second copy");
+    }
 });
 program
     .command("render")
@@ -512,17 +534,56 @@ slice
         ? `marked implemented: ${result.path} (implementedIn: ${prUrl})`
         : `already implemented (no-op): ${result.path}`);
 });
+slice
+    .command("review")
+    .description("flip a slice doc's frontmatter to `status: reviewed` and record `reviewedBy:`/`reviewedOn:` " +
+    "— the FIRST of the two human gates (MIL-201, docs/process.md#the-slice-lifecycle-gates): " +
+    "the room walked this slice and every open question it raised is resolved. Ratification is " +
+    "a separate, later gate (`em slice ratify`). Legal from `status: draft`; idempotent on the " +
+    "same --by/--on pair; refuses to overwrite a different one already recorded; refuses a doc " +
+    "already `ready-to-implement`/`implemented`; never touches `version:` or the doc body")
+    .argument("<file>", "input .em file")
+    .argument("<slice-key>", "slice export key (kebab-case)")
+    .requiredOption("--by <name>", "the reviewer's (or facilitator's) name")
+    .option("--on <date>", "review date, YYYY-MM-DD (default: today)")
+    .action((file, sliceKey, opts) => {
+    const { model, refs, diagnostics } = compileFile(file);
+    printDiagnostics(diagnostics);
+    // Scoped the same way `em slice ratify`/`em slice mark-implemented`/`em export --slice`/
+    // `em validate --slice-ready` are: only an error concerning THIS slice refuses.
+    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 review: slice "${sliceKey}" has errors — fix them first`);
+        process.exit(1);
+    }
+    const today = new Date().toISOString().slice(0, 10);
+    const reviewedOn = opts.on ?? today;
+    if (opts.on !== undefined && !isValidDateString(opts.on)) {
+        console.error(`em slice review: invalid --on date "${opts.on}" — expected YYYY-MM-DD`);
+        process.exit(1);
+    }
+    const result = runReview(model, refs, dirname(file), sliceKey, opts.by, reviewedOn);
+    if (!result.ok) {
+        console.error(`em slice review: ${result.message}`);
+        process.exit(1);
+    }
+    console.log(result.changed
+        ? `reviewed: ${result.path} (reviewedBy: ${opts.by}, reviewedOn: ${reviewedOn})`
+        : `already reviewed (no-op): ${result.path}`);
+});
 slice
     .command("ratify")
     .description("flip a slice doc's frontmatter to `status: ready-to-implement` and record `ratifiedBy:`/" +
-    "`ratifiedOn:` — the handoff sign-off (MIL-165, docs/process.md#what-ratified-means) that " +
-    "makes who ratified, and when, a first-class recorded fact. Idempotent on the same " +
-    "--by/--on pair; refuses to overwrite a different one already recorded; never touches " +
-    "`version:` or the doc body")
+    "`ratifiedOn:` — the handoff sign-off (MIL-165, docs/process.md#the-slice-lifecycle-gates) " +
+    "that makes who ratified, and when, a first-class recorded fact. Refuses a doc that never " +
+    "passed the review gate (`em slice review`) unless --skip-review is passed. Idempotent on " +
+    "the same --by/--on pair; refuses to overwrite a different one already recorded; never " +
+    "touches `version:` or the doc body")
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
     .requiredOption("--by <name>", "the ratifier's name")
     .option("--on <date>", "ratification date, YYYY-MM-DD (default: today)")
+    .option("--skip-review", "ratify without a recorded review — prints a loud notice on stderr")
     .action((file, sliceKey, opts) => {
     const { model, refs, diagnostics } = compileFile(file);
     printDiagnostics(diagnostics);
@@ -539,11 +600,23 @@ slice
         console.error(`em slice ratify: invalid --on date "${opts.on}" — expected YYYY-MM-DD`);
         process.exit(1);
     }
-    const result = runRatify(model, refs, dirname(file), sliceKey, opts.by, ratifiedOn);
+    const result = runRatify(model, refs, dirname(file), sliceKey, opts.by, ratifiedOn, opts.skipReview === true);
     if (!result.ok) {
         console.error(`em slice ratify: ${result.message}`);
         process.exit(1);
     }
+    // Loud, on stderr, exactly when --skip-review is what let this through — the skip is a
+    // visible act in the terminal and in CI logs, and deliberately leaves no trace in the doc.
+    if (result.skippedReviewFrom !== null) {
+        console.error(`notice: --skip-review — ratifying "${sliceKey}" without a recorded review ` +
+            `(status was ${result.skippedReviewFrom})`);
+    }
+    // MIL-198: advisory only, never refuses — ratifying ahead of an upstream slice the model's
+    // own timeline puts before this one (query index `in` adjacency, one hop, other slices only)
+    // is sometimes deliberate; this just makes it visible in the terminal and CI logs.
+    for (const upstream of result.upstreamWarnings) {
+        console.error(`warn: ratifying "${sliceKey}" ahead of upstream slice "${upstream.sliceKey}" (status: ${upstream.status})`);
+    }
     console.log(result.changed
         ? `ratified: ${result.path} (ratifiedBy: ${opts.by}, ratifiedOn: ${ratifiedOn})`
         : `already ratified (no-op): ${result.path}`);
@@ -553,8 +626,9 @@ slice
     .description("bump `version:` and flip a shipped slice doc's frontmatter back to `status: " +
     "ready-to-implement` — the re-ratification mechanical edit (MIL-161, mirrors `em slice " +
     "mark-implemented`). Only applies to a doc at `status: implemented`; clears any stale " +
-    "`ratifiedBy:`/`ratifiedOn:` (they describe the PRIOR version's sign-off) so a follow-up " +
-    "`em slice ratify --by` applies cleanly; never touches `implementedIn:` or the doc body")
+    "`ratifiedBy:`/`ratifiedOn:`/`reviewedBy:`/`reviewedOn:` (they describe the PRIOR version's " +
+    "review and sign-off) so a follow-up `em slice ratify --by` applies cleanly — and needs no " +
+    "fresh review; never touches `implementedIn:` or the doc body")
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
     .action((file, sliceKey) => {
@@ -757,7 +831,14 @@ program
         console.error(`em conform-scope: ${parsed.message}`);
         process.exit(1);
     }
-    const { lastConformance } = parsed.state;
+    // MIL-179: the state file names exactly one model in `Model file:`; a sibling this run
+    // isn't describing (e.g. a `--seed-asis` scratch copy) must not inherit its conformance
+    // record. Same check `em status`'s resolveConformanceEntry runs (PR #116).
+    const stateFileMismatch = modelPathMismatch(parsed.state.modelPath, file);
+    if (stateFileMismatch) {
+        console.error(stateFileMismatch);
+    }
+    const lastConformance = stateFileMismatch ? null : parsed.state.lastConformance;
     const { facts, diagnostics: docDiags } = resolveSliceDocFacts(model, refs, dirname(file));
     printDiagnostics(newDiagnostics(docDiags, diagnostics));
     const skipGit = !!opts.full || lastConformance === null;
@@ -772,6 +853,9 @@ program
     }
     const scope = buildConformScope(facts, lastConformance, changedPaths, !!opts.full);
     const output = { ...scope };
+    if (stateFileMismatch) {
+        output.stateFile = { error: stateFileMismatch };
+    }
     if (opts.seedAsis) {
         output.seeded = seedAsisModel(file);
     }
@@ -1023,6 +1107,9 @@ program
     if (plan.refusals.length > 0)
         process.exitCode = 1;
 });
+function describeLedgerWaiveSource(source) {
+    return source.source === "flag" ? "--waive" : `trailer ${source.commit.slice(0, 7)}`;
+}
 program
     .command("ledger")
     .description("check slice docs' version: field agrees with their content across two git revisions " +
@@ -1030,6 +1117,8 @@ program
     .argument("<file>", "anchor .em file — locates slices/ relative to it; never parsed")
     .option("--from <rev>", "baseline revision")
     .option("--to <rev>", "compare revision (default: current working tree)")
+    .option("--waive <slice-key>", "excuse a doc-content-without-version-bump finding for this slice key (repeatable; MIL-185, " +
+    "see docs/cli.md) — never waives a version regression or bump-without-content-change", (value, previous) => [...previous, value], [])
     .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
     .action((file, opts) => {
     if (!opts.from) {
@@ -1037,18 +1126,30 @@ program
         process.exit(1);
     }
     const to = opts.to ?? null;
-    const result = checkLedger(file, opts.from, to);
+    const rawResult = checkLedger(file, opts.from, to);
+    // Commit trailers apply only to CI/manual runs against a real range — the working-tree
+    // comparison itself (`to === null`) still resolves the trailer range as `from..HEAD`, since
+    // an uncommitted change has no commit to carry a trailer; that gap is `--waive`'s job (see
+    // docs/cli.md).
+    const trailerWaivers = readLedgerWaiverTrailers(file, opts.from, to);
+    const { result, unknownWaivers } = applyLedgerWaivers(rawResult, opts.waive, trailerWaivers);
+    for (const note of unknownWaivers) {
+        console.error(`note: waiver for unknown slice "${note.sliceKey}" ignored`);
+    }
     if (opts.json) {
         process.stdout.write(buildLedgerJson(result, opts.from, to) + "\n");
     }
     else {
         for (const f of result.findings)
             console.log(f.message);
+        for (const w of result.waived)
+            console.log(`waived: ${w.message} (waived by ${describeLedgerWaiveSource(w.waivedBy)})`);
+        const waivedNote = result.waived.length > 0 ? `, ${result.waived.length} waived` : "";
         if (result.findings.length === 0) {
-            console.log(`ok — ledger agrees (${result.checkedCount} slice doc(s) checked)`);
+            console.log(`ok — ledger agrees (${result.checkedCount} slice doc(s) checked${waivedNote})`);
         }
         else {
-            console.log(`${result.findings.length} ledger mismatch(es)`);
+            console.log(`${result.findings.length} ledger mismatch(es)${waivedNote}`);
         }
     }
     // Set the code rather than process.exit(): same rationale as em diff/em glossary — stdout
@@ -1240,6 +1341,207 @@ program
         console.log(formatConformancePart(entry));
     }
 });
+// `em query` (MIL-168): deterministic graph queries over the compiled model — scoped, token-
+// cheap answers instead of a whole-model `em export`. Compiles every input file through the
+// LIGHTER query sub-pipeline (query/pipeline.ts: parse -> normalize -> refs -> validate against
+// an empty grid -> ModelIndex — no layout allocation, no DOT emission), same "refuse on compile
+// errors" gate every JSON surface uses, then hands the built `QuerySystem` to whichever verb
+// function ran (query/verbs.ts) — the exact same functions the MCP `query` tool calls (MCP
+// parity, docs/mcp.md). `<files...>` variadic, multi-model, same as `em status`; refs in output
+// are `<modelKey>:<sliceKey>/<kind>.<slug>`-qualified whenever more than one file is given (see
+// query/system.ts's header for why), bare/unqualified otherwise.
+function compileFilesForQuery(files) {
+    const entries = files.map((file) => {
+        const source = readFileOrExit(file);
+        let compiled;
+        try {
+            compiled = compileForQuery(source, dirname(file));
+        }
+        catch (e) {
+            if (e instanceof ParseError) {
+                console.error(`parse error in ${file} ${e.message}`);
+                process.exit(1);
+            }
+            throw e;
+        }
+        printDiagnosticsFor(file, compiled.diagnostics);
+        if (hasErrors(compiled.diagnostics)) {
+            console.error(`em query: not querying — "${file}" has errors — fix them first`);
+            process.exit(1);
+        }
+        return { file, model: compiled.model, refs: compiled.refs, index: compiled.index };
+    });
+    const system = buildQuerySystem(entries);
+    // MIL-193: a `duplicate-model-key` collision is attributed to the file that had to take the
+    // `~n` suffix (its key is `refs[0]`), printed exactly like that file's own compile warnings.
+    for (const d of system.diagnostics) {
+        const owner = system.entries.find((e) => e.modelKey === d.refs?.[0]);
+        printDiagnosticsFor(owner?.file ?? files.join(", "), [d]);
+    }
+    return system;
+}
+/** Runs one verb end to end: compile every file, call `fn`, then print — text by default,
+ *  `--json` for `emit/queryJson.ts`'s versioned document. A verb-level error (bad/ambiguous ref,
+ *  unknown invariant ID, ...) is `console.error` + exit 1; a legitimately empty result set still
+ *  exits 0 (MIL-168's own contract — "an event with no consumers prints 'none' and exits 0"). */
+function runQueryVerb(files, verb, args, json, fn, formatFn) {
+    const system = compileFilesForQuery(files);
+    const result = fn(system);
+    if (!result.ok) {
+        console.error(result.error);
+        process.exit(1);
+    }
+    if (json)
+        process.stdout.write(buildQueryJson(verb, files, args, result.results) + "\n");
+    else
+        console.log(formatFn(result.results));
+}
+function parseDepthOpt(depth, verb) {
+    if (depth === undefined)
+        return undefined;
+    // Decimal digits only — `Number()` would also accept "1e1", "0x10", " 5", which are not what
+    // a hop count looks like on a command line.
+    if (!/^[1-9][0-9]*$/.test(depth)) {
+        console.error(`em query ${verb}: --depth must be a positive integer`);
+        process.exit(1);
+    }
+    return Number(depth);
+}
+const query = program.command("query").description("deterministic graph queries over the compiled model (MIL-168, see docs/cli.md)");
+query
+    .command("consumers")
+    .description("views/reactions consuming an event, plus their slices")
+    .argument("<files...>", "input .em files")
+    .requiredOption("--event <ref-or-name>", "the event's export ref or display name")
+    .option("--json", "print a JSON document instead of the text report")
+    .action((files, opts) => {
+    runQueryVerb(files, "consumers", { event: opts.event }, opts.json, (s) => queryConsumers(s, opts.event), formatConsumers);
+});
+query
+    .command("producers")
+    .description("commands producing an event, plus their slices and ui triggers")
+    .argument("<files...>", "input .em files")
+    .requiredOption("--event <ref-or-name>", "the event's export ref or display name")
+    .option("--json", "print a JSON document instead of the text report")
+    .action((files, opts) => {
+    runQueryVerb(files, "producers", { event: opts.event }, opts.json, (s) => queryProducers(s, opts.event), formatProducers);
+});
+query
+    .command("downstream")
+    .description("transitive closure along legal edges from an element — impact analysis")
+    .argument("<files...>", "input .em files")
+    .requiredOption("--of <ref-or-name>", "the starting element's export ref or display name")
+    .option("--depth <n>", "limit traversal to n hops (default: unlimited)")
+    .option("--json", "print a JSON document instead of the text report")
+    .action((files, opts) => {
+    const depth = parseDepthOpt(opts.depth, "downstream");
+    runQueryVerb(files, "downstream", { of: opts.of, depth: depth ?? null }, opts.json, (s) => queryDownstream(s, opts.of, depth), formatClosure);
+});
+query
+    .command("upstream")
+    .description("transitive closure against legal-edge direction from an element")
+    .argument("<files...>", "input .em files")
+    .requiredOption("--of <ref-or-name>", "the starting element's export ref or display name")
+    .option("--depth <n>", "limit traversal to n hops (default: unlimited)")
+    .option("--json", "print a JSON document instead of the text report")
+    .action((files, opts) => {
+    const depth = parseDepthOpt(opts.depth, "upstream");
+    runQueryVerb(files, "upstream", { of: opts.of, depth: depth ?? null }, opts.json, (s) => queryUpstream(s, opts.of, depth), formatClosure);
+});
+query
+    .command("slices")
+    .description("filtered slice list — pattern/status/context/persona/tag filters AND-combine")
+    .argument("<files...>", "input .em files")
+    .option("--pattern <p>", "state-change | state-view | automation | translation | unclassified")
+    .option("--status <s>", "the slice's joined doc status (draft, reviewed, ready-to-implement, implemented, ...)")
+    .option("--context <c>", "match a slice with an event in this @Context")
+    .option("--persona <p>", "match a slice with a ui in this @Persona")
+    .option("--tag <t>", "match a slice with an event carrying this tag key")
+    .option("--json", "print a JSON document instead of the text report")
+    .action((files, opts) => {
+    const filters = { pattern: opts.pattern, status: opts.status, context: opts.context, persona: opts.persona, tag: opts.tag };
+    runQueryVerb(files, "slices", filters, opts.json, (s) => querySlices(s, filters), formatSlices);
+});
+query
+    .command("invariant")
+    .description("declaring slice + doc facts for one INV-* id, and (with --tests) its test citations")
+    .argument("<files...>", "input .em files")
+    .requiredOption("--id <inv-id>", "the INV-* id to look up")
+    .option("--tests <dir>", "directory to scan for test files citing this id")
+    .option("--json", "print a JSON document instead of the text report")
+    .action((files, opts) => {
+    if (opts.tests) {
+        if (!existsSync(opts.tests)) {
+            console.error(`em query invariant: --tests directory not found: ${opts.tests}`);
+            process.exit(1);
+        }
+        if (!statSync(opts.tests).isDirectory()) {
+            console.error(`em query invariant: --tests is not a directory: ${opts.tests}`);
+            process.exit(1);
+        }
+    }
+    runQueryVerb(files, "invariant", { id: opts.id, tests: opts.tests ?? null }, opts.json, (s) => queryInvariant(s, opts.id, opts.tests), formatInvariant);
+});
+query
+    .command("field")
+    .description("one field's facts on an element — type, tag/assigned markers, renamed-from chain")
+    .argument("<files...>", "input .em files")
+    .requiredOption("--of <element-ref>", "the element's export ref or display name")
+    .requiredOption("--name <field>", "the field's name")
+    .option("--json", "print a JSON document instead of the text report")
+    .action((files, opts) => {
+    runQueryVerb(files, "field", { of: opts.of, name: opts.name }, opts.json, (s) => queryField(s, opts.of, opts.name), formatField);
+});
+query
+    .command("path")
+    .description("shortest path between two elements through the six legal connection types")
+    .argument("<files...>", "input .em files")
+    .requiredOption("--from <ref-or-name>", "the starting element's export ref or display name")
+    .requiredOption("--to <ref-or-name>", "the ending element's export ref or display name")
+    .option("--json", "print a JSON document instead of the text report")
+    .action((files, opts) => {
+    runQueryVerb(files, "path", { from: opts.from, to: opts.to }, opts.json, (s) => queryPath(s, opts.from, opts.to), formatPath);
+});
+program
+    .command("system")
+    .description("verify a seam manifest (system.yaml) against its models' exports — every `public` event/view " +
+    "bound to a reaction in another model, the cross-model half of \"both ends of a flow\" (MIL-194, see docs/cli.md)")
+    .argument("<manifest>", "seam manifest path (YAML, or JSON); each model's `source` resolves relative to it")
+    // Same reasoning as `em validate`'s allowExcessArguments(false) (MIL-123): a second positional
+    // would be silently dropped, and "one manifest per run" is the whole contract here.
+    .allowExcessArguments(false)
+    .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
+    .action((manifest, opts) => {
+    const loaded = loadSystem(manifest);
+    if (!loaded.ok) {
+        // Same refusal posture as `em export`/`em status`: a manifest that can't be parsed, or a
+        // source that can't be read/compiled, is not a system to verify — no document, exit 1.
+        printSystemDiagnostics(loaded.diagnostics);
+        console.error(`em system: not verifying — ${manifest} could not be loaded; fix the above first`);
+        process.exit(1);
+    }
+    const report = verifySystem(loaded.manifest, loaded.models, manifest);
+    if (opts.json) {
+        // `em validate --json`'s convention: diagnostics still go to stderr in the human format,
+        // the document (which carries the same diagnostics) to stdout; exit code unchanged.
+        printSystemDiagnostics(report.diagnostics);
+        process.stdout.write(buildSystemJson(manifest, loaded.manifestText, report) + "\n");
+    }
+    else {
+        const verified = report.seams.filter((s) => s.status === "verified").length;
+        const failing = report.seams.length - verified;
+        const label = report.name === null ? "system" : `system "${report.name}"`;
+        console.log(`${label}: ${report.models.length} model${report.models.length === 1 ? "" : "s"}, ` +
+            `${report.seams.length} seam${report.seams.length === 1 ? "" : "s"} (${verified} verified, ${failing} failing)`);
+        printSystemDiagnostics(report.diagnostics);
+        if (report.diagnostics.length === 0)
+            console.log("ok — no issues");
+    }
+    // Set the code rather than process.exit(): same rationale as em diff/em ledger — stdout to
+    // a pipe (a --json document) shouldn't risk truncation.
+    if (hasErrors(report.diagnostics))
+        process.exitCode = 1;
+});
 // Shared by install/sync/check: the `.claude/skills/` root 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
@@ -1264,9 +1566,9 @@ program
 });
 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. " +
+    .description("start an MCP (Model Context Protocol) server over stdio (MIL-21) — a structured, agent-" +
+    "facing alternative to shelling out to `em`; see docs/mcp.md for the full, current tool " +
+    "table (the list changes as commands gain MCP parity, so it's not repeated here — MIL-187). " +
     "Equivalent to running the `em-mcp` bin directly")
     .action(async () => {
     // A 3-line wrapper only, for discoverability — the server itself (src/mcp/) never imports
@@ -1288,8 +1590,14 @@ const skill = program
     .description("manage Claude Code skills bundled with em");
 skill
     .command("install")
-    .description("copy the event-modeling skill bundle into .claude/skills/ (event-modeling, event-modeling-discover/-design/-implement/-conform/-review, event-modeling-shared)")
-    .option("-f, --force", "overwrite an existing installation")
+    .description("copy the event-modeling skill bundle into .claude/skills/ (event-modeling, event-modeling-" +
+    "discover/-design/-implement/-conform/-review, event-modeling-shared); across a structural " +
+    "bundle change (e.g. the MIL-157 split of the old single event-modeling/ directory into " +
+    "this six-directory bundle), `em skill sync` is the migration path — --force now performs " +
+    "the same reconcile (MIL-180)")
+    .option("-f, --force", "overwrite an existing installation, reconciling added/updated/removed files within the " +
+    "bundle's own managed directories the same way `em skill sync` does — never touching an " +
+    "unrelated sibling skill (MIL-180)")
     .option("--no-agents-md", "skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)")
     .action(async (opts) => {
     const srcRoot = packagedSkillsRoot();
@@ -1299,6 +1607,31 @@ skill
         console.log(`skill already installed at ${anchor}`);
         console.log("re-run with --force to overwrite");
     }
+    else if (existsSync(anchor)) {
+        // --force on an existing installation (MIL-180): reconcile via the same plan/apply
+        // `em skill sync` uses instead of a raw recursive copy, so a file that no longer exists
+        // in the packaged bundle (e.g. left behind by the MIL-157 6-directory split) is removed
+        // from the vendored copy too. Scoped to EM_ALL_SKILL_BUNDLE_DIRS only, exactly like sync
+        // — an unrelated sibling skill under .claude/skills/ is never walked, never touched.
+        await mkdir(destRoot, { recursive: true });
+        const bundlePlan = planSkillSyncBundle(srcRoot, destRoot, EM_ALL_SKILL_BUNDLE_DIRS);
+        const totalChanges = bundlePlan.reduce((n, { plan }) => n + plan.changes.length, 0);
+        const totalUnchanged = bundlePlan.reduce((n, { plan }) => n + plan.unchangedCount, 0);
+        const removedCount = bundlePlan.reduce((n, { plan }) => n + plan.changes.filter((c) => c.kind === "removed").length, 0);
+        applySkillSyncBundle(bundlePlan, srcRoot, destRoot);
+        for (const { dirName, plan } of bundlePlan) {
+            for (const c of plan.changes)
+                console.log(`${c.kind}: ${dirName}/${c.relPath}`);
+        }
+        if (totalChanges === 0) {
+            console.log(`installed event-modeling skill bundle → ${destRoot} — already up to date (${totalUnchanged} file(s))`);
+        }
+        else {
+            console.log(`installed event-modeling skill bundle → ${destRoot} — ${totalChanges} file(s) changed ` +
+                `(${removedCount} removed), ${totalUnchanged} unchanged`);
+        }
+        console.log("in Claude Code, run /event-modeling to start a guided session");
+    }
     else {
         await mkdir(destRoot, { recursive: true });
         for (const name of EM_ALL_SKILL_BUNDLE_DIRS) {
@@ -1385,11 +1718,11 @@ ci.command("init")
     const files = [
         [
             ciPath,
-            planCiFile(ciPath, buildCiWorkflowFile(model, opts.tests, PKG_VERSION), ciManagedBody(model, opts.tests), CI_WORKFLOW_MARKER, !!opts.force),
+            planCiFile(ciPath, buildCiWorkflowFile(model, opts.tests, PKG_VERSION), ciManagedBody(model, opts.tests, PKG_VERSION), CI_WORKFLOW_MARKER, !!opts.force),
         ],
         [
             conformPath,
-            planCiFile(conformPath, buildConformWorkflowFile(model, PKG_VERSION), conformManagedBody(model), CONFORM_WORKFLOW_MARKER, !!opts.force),
+            planCiFile(conformPath, buildConformWorkflowFile(model, PKG_VERSION), conformManagedBody(model, PKG_VERSION), CONFORM_WORKFLOW_MARKER, !!opts.force),
         ],
     ];
     if (opts.check) {
@@ -1618,6 +1951,12 @@ function printDiagnostics(diags) {
             console.warn(line);
     }
 }
+/** `em system`'s diagnostics carry their own `file` (manifest or model source) — print each in
+ *  the same `<file>: <severity>:<line> <message>` shape printDiagnosticsFor uses. */
+function printSystemDiagnostics(diags) {
+    for (const d of diags)
+        printDiagnosticsFor(d.file, [d]);
+}
 /** Same as printDiagnostics, prefixed with the file each diagnostic came from —
  *  worth doing once N input files can be more than the two `em diff` compares,
  *  where ambiguity about which side a diagnostic belongs to gets materially worse. */