@milehimikey/em 1.13.0 → 1.14.0

package/dist/cli.js

@@ -17,11 +17,12 @@ import { serializeBuilds, watchFile } from "./render/watch.js";
 import { startLiveServer } from "./render/serve.js";
 import { formatDiagnostic, hasErrors, publicViewsWithoutInModelReader } from "./model/validate.js";
 import { buildExport, buildSliceExport, GENERATOR_VERSION } from "./emit/json.js";
-import { buildTypeSpec } from "./emit/typespec.js";
+import { generateContract, runApiCheck, formatApiCheckText } from "./cli/api.js";
+import { buildApiCheckJson } from "./emit/apiCheckJson.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 { planDiffArgs, realGit, 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";
@@ -29,23 +30,30 @@ import { validateNoteBindings } from "./catalog/noteBindingValidate.js";
 import { validateDocModelConsistency } from "./catalog/docModelConsistencyValidate.js";
 import { validateOrphanedSliceDocs } from "./catalog/orphanedSliceDocValidate.js";
 import { validateModelVersionStale } from "./catalog/modelVersionValidate.js";
-import { validateSliceReady, computeSliceReadyGates } from "./catalog/sliceReadyValidate.js";
+import { validateInvariants } from "./catalog/invariantsValidate.js";
+import { computeSliceReadiness } from "./catalog/sliceReadyValidate.js";
+import { applyEngagementClose, applyEngagementSet, buildNewEngagement, engagementPlanFor, engagementStatusFor, formatEngagementPlanText, formatEngagementStatusText, } from "./cli/engagement.js";
+import { LEDGER_STATES, engagementPath, loadEngagement, readOpenEngagements } from "./cli/engagementFile.js";
+import { buildEngagementPlanJson, buildEngagementStatusJson } from "./emit/engagementJson.js";
 import { detectSliceDocCollisions } from "./catalog/modelCollisionValidate.js";
 import { checkLedger, readLedgerWaiverTrailers, applyLedgerWaivers } from "./cli/ledgerCheck.js";
 import { planMigration, verifyMigration } from "./cli/migrateReactionShape.js";
 import { buildLedgerJson } from "./emit/ledgerJson.js";
-import { buildCoverageReport, resolveScopedSlices } from "./cli/coverage.js";
+import { buildCoverageReport, resolveScopedSlices, resolveCoverageSliceKey } from "./cli/coverage.js";
 import { buildCoverageJson } from "./emit/coverageJson.js";
 import { resolveSliceStatusFacts, countOpenIssues, resolveConformanceEntry, aggregateInvariantTotals, buildStatusReport, formatStatusText, formatStatusMarkdown, buildStatusBadge, formatConformancePart, findSpecifyRoot, resolveModelVersionStatusEntry, resolveEmVersionStatusEntry, } from "./cli/status.js";
 import { buildStatusJson } from "./emit/statusJson.js";
 import { buildFreshnessJson } from "./emit/freshnessJson.js";
 import { computeMetrics, formatMetricsText } from "./cli/metrics.js";
+import { runSystemScope } from "./cli/scopeInputs.js";
+import { buildScopeJson } from "./emit/scopeJson.js";
 import { buildMetricsJson } from "./emit/metricsJson.js";
-import { planSkillSyncBundle, applySkillSyncBundle } from "./cli/skillSync.js";
-import { checkSkillSyncBundle } from "./cli/skillCheck.js";
+import { planSkillSyncBundle, applySkillSyncBundle, planAgentSync, applySkillSync } from "./cli/skillSync.js";
+import { checkSkillSyncBundle, checkAgentFiles } from "./cli/skillCheck.js";
 import { buildSkillCheckJson } from "./emit/skillCheckJson.js";
+import { checkPlugin, claudePluginsDir, detectPlugin, pluginInstallCommands } from "./cli/pluginPin.js";
 import { readContract } from "./cli/contract.js";
-import { EM_SKILL_DIR_NAMES, EM_SHARED_DIR_NAMES, EM_ALL_SKILL_BUNDLE_DIRS, EM_SKILL_ANCHOR_DIR } from "./cli/skillDirs.js";
+import { EM_SKILL_DIR_NAMES, EM_SHARED_DIR_NAMES, EM_ALL_SKILL_BUNDLE_DIRS, EM_SKILL_ANCHOR_DIR, EM_AGENT_FILES } from "./cli/skillDirs.js";
 import { createServer as createMcpServer } from "./mcp/server.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { syncAgentsMd } from "./cli/agentsMd.js";
@@ -56,11 +64,13 @@ 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 { runRatify } from "./cli/ratify.js";
+import { runRatify, parseMeaningFlags, meaningConfirmationLine } 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, buildStubDocContent, isSlicePattern, sliceDocKey, SLICE_PATTERNS } from "./cli/sliceNew.js";
+import { buildSliceSyncJson, formatSliceSync, runSliceSync, sliceSyncFailed } from "./cli/sliceSync.js";
+import { buildSliceRegions } from "./catalog/sliceSections.js";
 import { wireSliceNote } from "./cli/sliceLink.js";
 import { isStubStatus, runStubAll, STUB_STATUSES } from "./cli/sliceStubAll.js";
 import { listModelCommits } from "./cli/changelog-git.js";
@@ -72,7 +82,7 @@ import { STATE_FILE_NAME, PHASES, isPhase, loadStateFile, parseState, setPhase,
 import { findCertifiedVersion, latestModelVersionNumber, modelVersionDrift, runCertifyModelVersion, runModelVersionBump, } from "./cli/modelVersion.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 { ciWorkflowPath, conformWorkflowPath, buildCiWorkflowFile, buildConformWorkflowFile, buildCiWorkflowFileMulti, buildConformWorkflowFileMulti, ciManagedBody, ciManagedBodyMulti, conformManagedBody, conformManagedBodyMulti, ciModelsFromManifest, describeOtherModels, describeSetChange, fileBlockModels, planCiFile, applyCiFile, findUnsafeCiInitArg, CI_WORKFLOW_MARKER, CONFORM_WORKFLOW_MARKER, } from "./cli/ciInit.js";
 import { resolveRepoRoot, detectUpgrade, applyUpgrade, checkUpgrade } from "./cli/upgrade.js";
 import { buildUpgradeJson } from "./emit/upgradeJson.js";
 import { isOlder } from "./util/semver.js";
@@ -84,7 +94,9 @@ 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 { gitProducerCommit, loadSystem, statusSystemBlock, SYSTEM_MANIFEST_FILE } from "./cli/systemInputs.js";
+import { runCodeowners } from "./system/codeowners.js";
+import { buildCodeownersJson } from "./emit/codeownersJson.js";
 import { verifySystem } from "./system/verify.js";
 import { buildSystemJson } from "./emit/systemJson.js";
 const program = new Command();
@@ -95,7 +107,10 @@ const PKG_VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.me
 program
     .name("em")
     .description("Event Modeling CLI — slice-first DSL rendered as a strict Graphviz grid")
-    .version(PKG_VERSION);
+    .version(PKG_VERSION)
+    // Program options (`--version`) only before the subcommand name: `em system codeowners --json`
+    // must reach the subcommand (MIL-234), and `em system` has its own `--json`.
+    .enablePositionalOptions();
 program
     .command("init")
     .description("scaffold a starter .em model")
@@ -265,30 +280,67 @@ program
         process.stdout.write(exported.text + "\n");
     }
 });
-program
-    .command("typespec")
-    .description("EXPERIMENTAL/POC (MIL-159): generate a TypeSpec contract for a model's commands, public " +
-    "events, and public views (see docs/cli.md)")
-    .argument("<file>", "input .em file")
-    .option("-o, --out <path>", "write to a file instead of stdout")
-    .action((file, opts) => {
-    const { model, refs, diagnostics, source } = compileFile(file);
-    printDiagnostics(diagnostics);
-    if (hasErrors(diagnostics)) {
+/** `em api generate` (and its deprecated `em typespec` alias): compile, refuse on errors,
+ *  write `<modelDir>/contracts/<modelKey>.tsp` (R6) — or `-o`, or stdout. */
+function runApiGenerate(file, opts) {
+    const compiled = compileFile(file);
+    const { source } = compiled;
+    printDiagnostics(compiled.diagnostics);
+    if (hasErrors(compiled.diagnostics)) {
         console.error("not generating: fix the errors above");
         process.exit(1);
     }
-    const generated = buildTypeSpec(model, refs, diagnostics, source, file);
-    printDiagnostics(newDiagnostics(generated.diagnostics, diagnostics));
-    for (const note of generated.unmappedTypes)
-        console.error(`note: ${note}`);
-    if (opts.out) {
-        writeFileSync(opts.out, generated.text + "\n");
-        console.log(`wrote ${opts.out}`);
+    const generated = generateContract(file, source, compiled, opts.out);
+    printDiagnostics(newDiagnostics(generated.diagnostics, compiled.diagnostics));
+    if (opts.stdout) {
+        process.stdout.write(generated.text);
+        return;
     }
-    else {
-        process.stdout.write(generated.text + "\n");
+    mkdirSync(dirname(generated.contractPath), { recursive: true });
+    writeFileSync(generated.contractPath, generated.text);
+    console.log(`wrote ${generated.contractPath}`);
+}
+const api = program
+    .command("api")
+    .description("the model-owned TypeSpec contract for its `public` surface (MIL-237, see docs/cli.md)");
+api
+    .command("generate")
+    .description("write the TypeSpec contract for the model's public commands, events and views to " +
+    "<model dir>/contracts/<model key>.tsp")
+    .argument("<file>", "input .em file")
+    .option("-o, --out <path>", "write to this path instead of <model dir>/contracts/<model key>.tsp")
+    .option("--stdout", "print the contract instead of writing it")
+    .action((file, opts) => runApiGenerate(file, opts));
+api
+    .command("check")
+    .description("is the committed contract current? With --base, annotate each public-surface change since " +
+    "that revision additive or breaking (annotation only — exits 1 only when stale)")
+    .argument("<file>", "input .em file")
+    .option("--base <rev>", "git revision to diff the public surface against")
+    .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
+    .action((file, opts) => {
+    const outcome = runApiCheck(file, opts.base);
+    printDiagnostics(outcome.diagnostics);
+    if (!outcome.ok) {
+        console.error(outcome.message);
+        process.exit(1);
     }
+    if (opts.json)
+        process.stdout.write(buildApiCheckJson(outcome.report) + "\n");
+    else
+        for (const line of formatApiCheckText(outcome.report))
+            console.log(line);
+    if (!outcome.report.current)
+        process.exitCode = 1;
+});
+program
+    .command("typespec")
+    .description("DEPRECATED alias of `em api generate --stdout` (use em api generate)")
+    .argument("<file>", "input .em file")
+    .option("-o, --out <path>", "write to a file instead of stdout")
+    .action((file, opts) => {
+    console.error("warn: em typespec is deprecated — use em api generate");
+    runApiGenerate(file, opts.out ? { out: opts.out } : { stdout: true });
 });
 program
     .command("diff")
@@ -437,9 +489,11 @@ program
 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 " +
+    .description("scaffold a fresh slices/<key>.md doc — the 5 frontmatter keys required at `status: draft`, " +
+    "the `# Slice:` heading and diagram-image stub, then every template section: the generated " +
+    "regions (command/event/view field tables, Invariants) filled from the model with --wire " +
+    "(template placeholders otherwise — `em slice sync` fills them), the authored sections " +
+    "(Intent, Scenarios, Open Questions, ...) with placeholder bullets (see " +
     ".claude/skills/event-modeling-shared/reference/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(" | ")}`)
@@ -466,6 +520,9 @@ slice
     // (no matching slice, ambiguous primary element, already wired) leaves nothing written at
     // all rather than a doc with no wiring and a non-zero exit.
     let wired = null;
+    // MIL-266: with a model in hand (--wire), the doc's generated regions are filled from it;
+    // without one they carry the template's placeholders until `em slice sync` fills them.
+    let regions;
     if (opts.wire) {
         const { model, refs, diagnostics, source } = compileFile(opts.wire);
         printDiagnostics(diagnostics);
@@ -479,11 +536,12 @@ slice
             process.exit(1);
         }
         wired = result;
+        regions = buildSliceRegions(model, [refs.sliceKeys.indexOf(key)]);
     }
     mkdirSync(dir, { recursive: true });
     const content = opts.stub
         ? buildStubDocContent(name, opts.pattern, opts.swimlane)
-        : buildSliceDocContent(name, key, opts.pattern, opts.swimlane);
+        : buildSliceDocContent(name, key, opts.pattern, opts.swimlane, regions);
     writeFileSync(path, content);
     console.log(`wrote ${path}`);
     if (wired) {
@@ -495,6 +553,39 @@ slice
         console.log(`  note "${path}"`);
     }
 });
+slice
+    .command("sync")
+    .description("regenerate the GENERATED regions (command/event/view field tables, the Invariants list) of " +
+    "existing slice docs in place from the model, authored sections untouched (MIL-266); docs " +
+    "without regions are skipped with a note. --check never writes and exits 1 when a doc is stale")
+    .argument("<model-file>", "the .em model whose bound slice docs to sync")
+    .argument("[key]", "only the doc this slice's export key resolves to")
+    .option("--check", "report ok / stale / no-regions per doc without writing; exit 1 when any is stale")
+    .option("--json", "print the machine-readable report (sliceSyncSchemaVersion 1.0)")
+    .action((file, key, opts) => {
+    const { model, refs, diagnostics } = compileFile(file);
+    printDiagnostics(diagnostics.filter((d) => d.severity === "error"));
+    if (hasErrors(diagnostics)) {
+        console.error(`em slice sync: not syncing — fix the errors in ${file} above`);
+        process.exit(1);
+    }
+    const check = opts.check === true;
+    const outcome = runSliceSync(model, refs, dirname(file), key, check);
+    if (!outcome.ok) {
+        console.error(`em slice sync: ${outcome.message}`);
+        process.exit(1);
+    }
+    const { out, err } = formatSliceSync(outcome.docs, check);
+    for (const line of err)
+        console.error(line);
+    if (opts.json)
+        process.stdout.write(buildSliceSyncJson(file, outcome.docs) + "\n");
+    else
+        for (const line of out)
+            console.log(line);
+    if (sliceSyncFailed(outcome.docs, check))
+        process.exit(1);
+});
 slice
     .command("stub-all")
     .description("scaffold + wire a near-free stub (`em slice new --stub`'s content, MIL-184) for every " +
@@ -642,12 +733,20 @@ slice
         ? `reviewed: ${result.path} (reviewedBy: ${opts.by}, reviewedOn: ${reviewedOn})`
         : `already reviewed (no-op): ${result.path}`);
 });
+/** MIL-238: `, meaningConfirmed: true` / `, contractChange: "<why>"` for a success line, or "". */
+function confirmationSuffix(c) {
+    return c ? `, ${meaningConfirmationLine(c)}` : "";
+}
 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#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 " +
+    "that makes who ratified, and when, a first-class recorded fact. The review gate is a check " +
+    "on the doc's current `status:`, not on whether `reviewedBy:`/`reviewedOn:` are populated: " +
+    "a doc at `reviewed` or `ready-to-implement` passes (the latter is where `em slice " +
+    "reratify` leaves a doc, so the follow-up ratify needs no --skip-review); any other status " +
+    "— a `draft` that never went through `em slice review` — is refused 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")
@@ -655,7 +754,16 @@ slice
     .requiredOption("--by <name>", "the ratifier's name")
     .option("--on <date>", "ratification date, YYYY-MM-DD (default: today, local date)")
     .option("--skip-review", "ratify without a recorded review — prints a loud notice on stderr")
+    .option("--meaning-unchanged", "API-first sign-off (MIL-238): this version does not change what the public contract means — " +
+    "records `meaningConfirmed: true`; required (or --contract-change) on a slice touching a `public` element")
+    .option("--contract-change <why>", "API-first sign-off (MIL-238): a consumer must read this change differently, and why — records " +
+    "`contractChange: \"<why>\"`")
     .action((file, sliceKey, opts) => {
+    const flags = parseMeaningFlags(opts.meaningUnchanged, opts.contractChange);
+    if (!flags.ok) {
+        console.error(`em slice ratify: ${flags.message}`);
+        process.exit(1);
+    }
     const { model, refs, diagnostics, source } = compileFile(file);
     printDiagnostics(diagnostics);
     // Scoped the same way `em slice mark-implemented`/`em export --slice`/`em validate
@@ -671,7 +779,7 @@ 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, opts.skipReview === true);
+    const result = runRatify(model, refs, dirname(file), sliceKey, opts.by, ratifiedOn, opts.skipReview === true, flags.confirmation);
     if (!result.ok) {
         console.error(`em slice ratify: ${result.message}`);
         process.exit(1);
@@ -689,7 +797,7 @@ slice
         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})`
+        ? `ratified: ${result.path} (ratifiedBy: ${opts.by}, ratifiedOn: ${ratifiedOn}${confirmationSuffix(flags.confirmation)})`
         : `already ratified (no-op): ${result.path}`);
     warnModelVersionDrift(dirname(file), model, refs, source, `ratifying "${sliceKey}"`);
 });
@@ -697,13 +805,25 @@ slice
     .command("reratify")
     .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 " +
+    "mark-implemented`). Applies to a doc at `status: implemented`, or (MIL-258) to a " +
+    "`ready-to-implement` doc that is ratified but not yet shipped — there it bumps `version:` " +
+    "and clears the sign-off but leaves `status:` alone; a `ready-to-implement` doc with no " +
+    "`ratifiedBy:` refuses (awaiting `em slice ratify --by`). Clears any stale " +
     "`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) => {
+    .option("--meaning-unchanged", "API-first sign-off (MIL-238): the new version does not change what the public contract means — " +
+    "records `meaningConfirmed: true`; required (or --contract-change) on a slice touching a `public` element")
+    .option("--contract-change <why>", "API-first sign-off (MIL-238): a consumer must read the new version differently, and why — records " +
+    "`contractChange: \"<why>\"`")
+    .action((file, sliceKey, opts) => {
+    const flags = parseMeaningFlags(opts.meaningUnchanged, opts.contractChange);
+    if (!flags.ok) {
+        console.error(`em slice reratify: ${flags.message}`);
+        process.exit(1);
+    }
     const { model, refs, diagnostics, source } = compileFile(file);
     printDiagnostics(diagnostics);
     // Scoped the same way `em slice ratify`/`em slice mark-implemented`/`em export --slice`/
@@ -713,20 +833,28 @@ slice
         console.error(`em slice reratify: slice "${sliceKey}" has errors — fix them first`);
         process.exit(1);
     }
-    const result = runReratify(model, refs, dirname(file), sliceKey);
+    const result = runReratify(model, refs, dirname(file), sliceKey, flags.confirmation);
     if (!result.ok) {
         console.error(`em slice reratify: ${result.message}`);
         process.exit(1);
     }
     // MIL-214: advisory only, never refuses — see reratify.ts's reratifyAdvisory. Both warnings
     // can fire together (a version that was never certified AND still carries unruled findings).
-    if (result.advisory.neverCertified) {
+    if (result.advisory?.neverCertified) {
         console.error(`warn: reratifying "${sliceKey}" whose v${result.newVersion - 1} was never certified`);
     }
-    if (result.advisory.unruledFindingsCount > 0) {
+    if (result.advisory && result.advisory.unruledFindingsCount > 0) {
         console.error(`warn: reratifying "${sliceKey}" has ${result.advisory.unruledFindingsCount} unruled conformance finding(s)`);
     }
-    console.log(`reratified: ${result.path} (version: ${result.newVersion}, status: ready-to-implement)`);
+    if (result.kind === "unshipped") {
+        // MIL-258: nothing was flipped — say what DID happen, and that the new version is unsigned.
+        console.log(`reratified: ${result.path} (version: ${result.newVersion - 1} -> ${result.newVersion}, sign-off cleared, ` +
+            `status unchanged: ready-to-implement${confirmationSuffix(flags.confirmation)}) — not ratified until ` +
+            `\`em slice ratify --by <name>\` records the new sign-off`);
+    }
+    else {
+        console.log(`reratified: ${result.path} (version: ${result.newVersion}, status: ready-to-implement${confirmationSuffix(flags.confirmation)})`);
+    }
     warnModelVersionDrift(dirname(file), model, refs, source, `reratifying "${sliceKey}"`);
 });
 slice
@@ -1309,10 +1437,12 @@ program
     .allowExcessArguments(false)
     .option("--list-issues", "print only open `issue` diagnostics (slice, element, line, text)")
     .option("--list-divergences", "print only accepted-divergence annotations (slice, element, line, text) — never fails the build")
-    .option("--list-public", "print only events and views marked `public` (slice, kind, name, line) — an integration-surface audit, never fails the build")
+    .option("--list-public", "print only commands, events and views marked `public` (slice, kind, name, line) — an integration-surface audit, never fails the build")
     .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)")
+    "note binding, zero unchecked Open Questions, a recorded ratifiedBy, and — for a slice " +
+    "touching a `public` element — a current contracts/<model key>.tsp; exits non-zero if not " +
+    "ready (MIL-87, MIL-259, MIL-238)")
     .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) => {
@@ -1333,17 +1463,18 @@ program
         // diagnostics printed — on an unrelated slice's breakage; scoping to this slice alone
         // matches the ticket's own scenario (check one slice while the rest of a large model is
         // still WIP) and this module's own "single-slice" framing.
-        const readyDiagnostics = validateSliceReady(model, refs, dirname(file), opts.sliceReady);
-        const combined = [...allDiagnostics, ...readyDiagnostics];
+        // MIL-238: the API-first gate needs the model path as given (the contract path is built
+        // from it, as `em api generate` does), its source, and the compile diagnostics.
+        // R34 (MIL-268): one shared verdict helper for this flag, the MCP `slice_ready` tool, and
+        // `em engagement plan`.
+        const contractInput = { file, source, diagnostics };
         const key = opts.sliceReady;
-        const scoped = combined.filter((d) => d.refs?.some((r) => r === key || r.startsWith(`${key}/`)));
+        const { scoped, ready, result } = computeSliceReadiness(model, refs, dirname(file), key, contractInput, allDiagnostics);
         printDiagnostics(scoped);
-        const ready = scoped.length === 0;
         if (opts.json) {
-            // MIL-128: the 4 named gates (see computeSliceReadyGates) plus the same `scoped`
+            // MIL-128: the 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 result = computeSliceReadyGates(model, refs, dirname(file), key);
             process.stdout.write(buildSliceReadyJson(file, key, result?.gates ?? null, scoped, ready, result?.continuationOf ?? null) + "\n");
         }
         else {
@@ -1509,9 +1640,13 @@ program
     "definition-of-done citation check; advisory by default, --strict for CI; " +
     "--include-ready also counts ready-to-implement docs (forward-looking report); a " +
     "continuation slice (an `again` view instance with no doc of its own, MIL-208) is excluded " +
-    "from the report — its invariants, if any, live in the originating slice's own doc")
+    "from the report — its invariants, if any, live in the originating slice's own doc; " +
+    "--slice <key> scopes the report to one slice whatever its status (MIL-255), the " +
+    "pre-merge definition-of-done check")
     .argument("<file>", "input .em file")
     .requiredOption("--tests <dir>", "directory to scan recursively for test files citing invariant IDs")
+    .option("--slice <key>", "only this slice (export key), whether ready-to-implement or implemented — no --include-ready needed; " +
+    "--strict then fails on this slice's uncited invariants, or if the slice is not in scope (draft/reviewed/unbound: nothing checked) (MIL-255)")
     .option("--strict", "exit non-zero if any invariant ID has zero citations (CI)")
     .option("--include-ready", "also count ready-to-implement docs, not just implemented (MIL-207)")
     .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
@@ -1524,11 +1659,25 @@ program
     }
     const baseDir = dirname(file);
     const includeReady = !!opts.includeReady;
+    // MIL-255: resolve --slice before anything else — an unknown key is an error (never a
+    // vacuously passing empty report), and a continuation key (MIL-208) scopes to its
+    // originating slice, which the output names (matching `em validate --slice-ready`).
+    let onlyKey;
+    let continuationOfKey = null;
+    if (opts.slice !== undefined) {
+        const target = resolveCoverageSliceKey(model, refs, opts.slice);
+        if (!target) {
+            console.error(`em coverage --slice: no slice with export key "${opts.slice}" in this model`);
+            process.exit(1);
+        }
+        onlyKey = target.key;
+        continuationOfKey = target.continuationOf;
+    }
     // MIL-207: a missing --tests dir is only a defect when something is actually in scope to
     // check — cheap to know without touching the test tree (resolveScopedSlices never reads
     // --tests). A fresh scaffold (or a doc-only ratification PR, with the MIL-207 default scope)
     // has zero implemented docs, so there's nothing yet for a test to cite.
-    const anyInScope = resolveScopedSlices(model, refs, baseDir, includeReady).some((s) => s.inScope);
+    const anyInScope = resolveScopedSlices(model, refs, baseDir, includeReady, onlyKey).some((s) => s.inScope);
     if (!existsSync(opts.tests)) {
         if (anyInScope) {
             console.error(`em coverage: --tests directory not found: ${opts.tests}`);
@@ -1540,17 +1689,36 @@ program
         console.error(`em coverage: --tests is not a directory: ${opts.tests}`);
         process.exit(1);
     }
-    const report = buildCoverageReport(model, refs, baseDir, opts.tests, includeReady);
+    const report = buildCoverageReport(model, refs, baseDir, opts.tests, includeReady, onlyKey);
+    // MIL-255: a scoped slice whose doc is draft/reviewed/unbound/unusable is out of scope — the
+    // same way the unscoped report treats it — but under --strict "nothing was checked" must not
+    // exit 0, or the pre-merge check passes vacuously (the very bug --slice exists to fix). So:
+    // advisory (no --strict) prints the note on stdout and exits 0; --strict prints it on stderr
+    // and exits 1 (also in --json mode, whose document shape is unchanged — consumers read the
+    // slice's `inScope` alongside `ok`). An in-scope doc with zero invariants stays a pass.
+    const unchecked = onlyKey === undefined ? undefined : report.slices.find((sl) => !sl.inScope);
+    const uncheckedNote = unchecked
+        ? `slice "${unchecked.key}" is not in scope (${unchecked.status ?? unchecked.docReason ?? "no doc"}) — nothing checked; only ready-to-implement/implemented docs are checked`
+        : null;
+    if (uncheckedNote !== null && (opts.strict || !opts.json)) {
+        (opts.strict ? console.error : console.log)(uncheckedNote);
+    }
     if (opts.json) {
-        process.stdout.write(buildCoverageJson(file, opts.tests, report, includeReady) + "\n");
+        const sliceScope = opts.slice === undefined ? null : { requested: opts.slice, continuationOf: continuationOfKey };
+        process.stdout.write(buildCoverageJson(file, opts.tests, report, includeReady, sliceScope) + "\n");
     }
     else {
+        if (continuationOfKey !== null) {
+            console.log(`slice "${opts.slice}" is a continuation of "${continuationOfKey}" — checking "${continuationOfKey}"`);
+        }
         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)`);
+                // MIL-255: said as "checked" so an in-scope doc defining zero invariants (a legitimate
+                // pass) is distinguishable from the "not in scope — nothing checked" case above.
+                console.log(`  (checked — the doc defines 0 INV-* invariant IDs)`);
                 continue;
             }
             for (const inv of slice.invariants) {
@@ -1569,7 +1737,7 @@ program
     // 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)
+    if (opts.strict && (report.uncoveredCount > 0 || uncheckedNote !== null))
         process.exitCode = 1;
 });
 program
@@ -1668,7 +1836,9 @@ program
     const emVersion = compiled
         .map(({ file }) => resolveEmVersionStatusEntry(file, PKG_VERSION))
         .filter((e) => e !== null);
-    const report = buildStatusReport(files, sliceFacts, openIssuesCount, invariants, conformance, statusDiagnostics, modelVersion, emVersion);
+    // MIL-239 (R11): the nearest system.yaml above the first input file, consumer-adaptation counted.
+    const system = statusSystemBlock(files[0], realGit, (m) => console.error(`warn: em status: ${m}`));
+    const report = buildStatusReport(files, sliceFacts, openIssuesCount, invariants, conformance, statusDiagnostics, modelVersion, emVersion, system, readOpenEngagements(files));
     let output;
     if (opts.json)
         output = buildStatusJson(report);
@@ -1900,37 +2070,180 @@ query
     .action((files, opts) => {
     runQueryVerb(files, "path", { from: opts.from, to: opts.to }, opts.json, (s) => queryPath(s, opts.from, opts.to), formatPath);
 });
-program
+const engagement = program
+    .command("engagement")
+    .description("a named chunk of the model built as one stack of slice PRs: its levelled build plan and its " +
+    "in-flight Ledger (MIL-268, see docs/cli.md and docs/engagement-schema.md)");
+engagement
+    .command("new")
+    .description("write <model dir>/engagements/<slug>.md — frontmatter (slices, parallel ceiling) plus the " +
+    "generated Ledger table; selection by --slices, --context, or --downstream-of (exactly one)")
+    .argument("<file>", "input .em file")
+    .argument("<slug>", "engagement slug (kebab-case; the file name)")
+    .option("--slices <keys>", "comma-separated slice export keys")
+    .option("--context <name>", "every slice with an event in this context")
+    .option("--downstream-of <ref>", "a slice key, element ref, or display name: it and everything downstream of it (loops-to excluded)")
+    .option("--parallel <n>", "how many slices of one level may be in flight at once", "3")
+    .option("--by <name>", "who created the engagement (createdBy)")
+    .option("--force", "overwrite an existing engagement file with this slug")
+    .action((file, slug, opts) => {
+    const fail = (m) => {
+        console.error(`em engagement new: ${m}`);
+        process.exit(1);
+    };
+    const given = [opts.slices, opts.context, opts.downstreamOf].filter((v) => v !== undefined).length;
+    if (given !== 1)
+        fail("pass exactly one of --slices, --context, --downstream-of");
+    const selector = opts.slices !== undefined
+        ? { kind: "slices", keys: opts.slices.split(",").map((k) => k.trim()).filter((k) => k !== "") }
+        : opts.context !== undefined
+            ? { kind: "context", context: opts.context }
+            : { kind: "downstream-of", ref: opts.downstreamOf };
+    const parallel = /^\d+$/.test(opts.parallel) ? Number(opts.parallel) : NaN;
+    const { model, refs } = compileFile(file);
+    const path = engagementPath(file, slug);
+    const result = buildNewEngagement({ file, model, refs, baseDir: dirname(file) }, { slug, selector, parallel, createdBy: opts.by ?? null, created: localIsoDate() });
+    if (!result.ok)
+        return fail(result.message);
+    if (existsSync(path) && !opts.force)
+        fail(`engagement "${slug}" already exists (${path}) — pass --force to overwrite`);
+    if (result.warning)
+        console.error(result.warning);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, result.text);
+    console.log(`wrote ${path} (${result.units.length} slice${result.units.length === 1 ? "" : "s"}: ${result.units.join(", ")})`);
+});
+/** Compile `file` with the full `em validate` diagnostic set — what `engagement plan` needs for
+ *  each slice's `--slice-ready` verdict (R34). */
+function engagementModelInput(file) {
+    const { model, refs, diagnostics, source } = compileFile(file);
+    const allDiagnostics = computeAllDiagnostics(file, model, refs, diagnostics, source);
+    return { file, model, refs, baseDir: dirname(file), contract: { file, source, diagnostics }, allDiagnostics };
+}
+engagement
+    .command("plan")
+    .description("the engagement's build plan: dependency levels over model.edges (loops-to excluded), and per " +
+    "slice its readiness, branch impl/<key>, base (main or impl/<upstream>), and any hold")
+    .argument("<file>", "input .em file")
+    .argument("<slug>", "engagement slug")
+    .option("--json", "print a JSON document instead of text (same document as the MCP engagement_plan tool)")
+    .action((file, slug, opts) => {
+    const result = engagementPlanFor(engagementModelInput(file), slug);
+    if (!result.ok) {
+        console.error(`em engagement plan: ${result.message}`);
+        process.exit(1);
+    }
+    process.stdout.write((opts.json ? buildEngagementPlanJson(result.plan) : formatEngagementPlanText(result.plan)) + "\n");
+});
+engagement
+    .command("set")
+    .description("the only write path to the Ledger: set one slice's state (and optionally branch/base/pr); " +
+    "idempotent; merged is terminal; --state held records a human hold")
+    .argument("<file>", "input .em file")
+    .argument("<slug>", "engagement slug")
+    .argument("<key>", "slice export key")
+    .requiredOption("--state <state>", `one of: ${LEDGER_STATES.join(" | ")}`)
+    .option("--branch <name>", "the slice's branch")
+    .option("--base <name>", "the branch the slice's PR targets")
+    .option("--pr <url>", "the slice's PR URL")
+    .action((file, slug, key, opts) => {
+    const fail = (m) => {
+        console.error(`em engagement set: ${m}`);
+        process.exit(1);
+    };
+    const loaded = loadEngagement(file, slug);
+    if (!loaded.ok)
+        return fail(loaded.message);
+    const { model, refs } = compileFile(file);
+    const result = applyEngagementSet({ file, model, refs, baseDir: dirname(file) }, slug, loaded.text, loaded.file, { key, ...opts });
+    if (!result.ok)
+        return fail(result.message);
+    if (!result.changed) {
+        console.log(`no change: ${key} is already ${result.entry.state} (${loaded.path})`);
+        return;
+    }
+    writeFileSync(loaded.path, result.text);
+    console.log(`set ${key}: ${result.entry.state} (${loaded.path})`);
+});
+engagement
+    .command("status")
+    .description("the Ledger joined with each slice doc's current status, plus whether the engagement is closable")
+    .argument("<file>", "input .em file")
+    .argument("<slug>", "engagement slug")
+    .option("--json", "print a JSON document instead of text (same document as the MCP engagement_status tool)")
+    .action((file, slug, opts) => {
+    const { model, refs } = compileFile(file);
+    const result = engagementStatusFor({ file, model, refs, baseDir: dirname(file) }, slug);
+    if (!result.ok) {
+        console.error(`em engagement status: ${result.message}`);
+        process.exit(1);
+    }
+    process.stdout.write((opts.json ? buildEngagementStatusJson(result.status) : formatEngagementStatusText(result.status)) + "\n");
+});
+engagement
+    .command("close")
+    .description("set status: closed — refuses unless every slice is merged (recorded or inferred) or gap")
+    .argument("<file>", "input .em file")
+    .argument("<slug>", "engagement slug")
+    .action((file, slug) => {
+    const fail = (m) => {
+        console.error(`em engagement close: ${m}`);
+        process.exit(1);
+    };
+    const { model, refs } = compileFile(file);
+    const status = engagementStatusFor({ file, model, refs, baseDir: dirname(file) }, slug);
+    if (!status.ok)
+        return fail(status.message);
+    const loaded = loadEngagement(file, slug);
+    if (!loaded.ok)
+        return fail(loaded.message);
+    const result = applyEngagementClose(slug, loaded.text, status.status);
+    if (!result.ok)
+        return fail(result.message);
+    if (!result.changed) {
+        console.log(`no change: engagement "${slug}" is already closed (${loaded.path})`);
+        return;
+    }
+    writeFileSync(loaded.path, result.text);
+    console.log(`closed engagement "${slug}" (${loaded.path})`);
+});
+const systemCommand = 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")
+    // `--json` exists on both `em system` and `em system codeowners`: parent options are only
+    // recognized before the subcommand name, so the subcommand owns the one that follows it.
+    .enablePositionalOptions()
+    .description("verify a system — every model's `consumes` refs resolved against the other models' `public` " +
+    "events/views, the cross-model half of \"both ends of a flow\" (MIL-194/MIL-235, see docs/cli.md). " +
+    "Reads system.yaml when given (or found in the directory), else discovers every *.em in the repo")
+    .argument("[target]", "a system.yaml path, or a directory (its system.yaml if present, else discovery); default: the working directory")
     // 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.
+    // would be silently dropped, and "one system 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);
+    .action((target, opts) => {
+    const shown = target ?? ".";
+    const loaded = loadSystem(shown);
     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`);
+        console.error(`em system: not verifying — ${shown} could not be loaded; fix the above first`);
         process.exit(1);
     }
-    const report = verifySystem(loaded.manifest, loaded.models, manifest);
+    const report = verifySystem(loaded.manifest, loaded.models, loaded.manifestPath, loaded.diagnostics, { producerCommit: gitProducerCommit() });
     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");
+        process.stdout.write(buildSystemJson(loaded, 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}"`;
+        const via = loaded.discovery ? ` (discovered under ${loaded.discovery.root} — no ${SYSTEM_MANIFEST_FILE})` : "";
         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)`);
+            `${report.seams.length} seam${report.seams.length === 1 ? "" : "s"} (${verified} verified, ${failing} failing)${via}`);
         printSystemDiagnostics(report.diagnostics);
         if (report.diagnostics.length === 0)
             console.log("ok — no issues");
@@ -1940,6 +2253,96 @@ program
     if (hasErrors(report.diagnostics))
         process.exitCode = 1;
 });
+systemCommand
+    .command("codeowners")
+    .description("generate (or --check) the managed CODEOWNERS block that routes review: each model's team on its " +
+    "design directory, and every team that `consumes` a model's public surface on that model's " +
+    "contract file (MIL-234, see docs/ci.md and docs/cli.md)")
+    .argument("[target]", "a system.yaml path, or a directory (its system.yaml if present, else discovery); default: the working directory")
+    .allowExcessArguments(false)
+    .option("-o, --output <path>", "the CODEOWNERS file to splice into (default: the first of CODEOWNERS, .github/CODEOWNERS, docs/CODEOWNERS that exists, else CODEOWNERS at the repo root)")
+    .option("--check", "verify the committed file already carries the generated block; never writes, exit 1 on drift (CI)")
+    .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
+    .action((target, opts) => {
+    const shown = target ?? ".";
+    const result = runCodeowners(shown, { output: opts.output, write: !opts.check });
+    if (!result.ok) {
+        console.error(`em system codeowners: ${result.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    for (const note of result.plan.notes)
+        console.error(`note: ${note}`);
+    if (opts.json) {
+        process.stdout.write(buildCodeownersJson(result.file, result.plan.entries, result.status) + "\n");
+    }
+    else if (opts.check) {
+        const hint = `run \`em system codeowners${target ? ` ${target}` : ""}${opts.output ? ` -o ${opts.output}` : ""}\` and commit the result`;
+        if (result.status === "ok")
+            console.log(`ok: ${result.file} carries the generated block`);
+        else if (result.status === "missing")
+            console.log(`missing: ${result.file} does not exist — ${hint}`);
+        else if (result.status === "no-markers")
+            console.log(`no-markers: ${result.file} has no GENERATED:em-codeowners block — ${hint}`);
+        else
+            console.log(`stale: ${result.file} differs from the generated block — ${hint}`);
+    }
+    else {
+        const verb = result.status === "created" ? "installed" : result.status === "updated" ? "updated" : "already up to date:";
+        console.log(`${verb} ${result.file} (${result.plan.entries.length} entr${result.plan.entries.length === 1 ? "y" : "ies"})`);
+    }
+    // --check never writes and fails on anything but ok (same vocabulary as `em ci init --check`).
+    if (opts.check && result.status !== "ok")
+        process.exitCode = 1;
+});
+const scopeCommand = systemCommand
+    .command("scope")
+    .description("check a change set against the seams (MIL-240): fail only when it alters a producer's public surface " +
+    "(or contract file) AND a consuming model's design dir together (`seam-crossing`); warn on other " +
+    "multi-model change sets. Files changed only by `Em-Upgrade:` commits are exempt. There is no " +
+    "override - review on the contract file is the gate (see docs/cli.md, docs/ci.md)")
+    .argument("[target]", "a system.yaml path, or a directory (its system.yaml if present, else discovery); default: the working directory")
+    .allowExcessArguments(false)
+    .option("--base <rev>", "the change set committed since <rev> (merge-base form, <rev>...HEAD); CI passes the PR base")
+    .option("--staged", "also (or only) check what is staged right now; never exempted")
+    .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
+    .action((target, opts) => {
+    const shown = target ?? ".";
+    const run = runSystemScope(shown, { base: opts.base, staged: opts.staged });
+    if (!run.ok) {
+        printSystemDiagnostics(run.diagnostics);
+        console.error(run.message);
+        process.exit(1);
+    }
+    const { facts, report } = run;
+    // `--json` is also an option of the parent `system` command, which swallows it before this
+    // subcommand sees it: read the merged options.
+    const json = scopeCommand.optsWithGlobals().json === true;
+    const printFindings = () => {
+        for (const d of report.diagnostics) {
+            const line = `${d.file}: ${d.severity} [${d.code}] ${d.message}`;
+            if (d.severity === "error")
+                console.error(line);
+            else
+                console.warn(line);
+        }
+    };
+    if (json) {
+        printFindings();
+        process.stdout.write(buildScopeJson(facts, report) + "\n");
+    }
+    else {
+        const range = [facts.base !== null ? `since ${facts.base}` : null, facts.staged ? "staged" : null].filter(Boolean).join(" + ");
+        console.log(`scope ${range}: ${facts.changedPaths.length} changed path${facts.changedPaths.length === 1 ? "" : "s"}, ` +
+            `${report.touched.length} model${report.touched.length === 1 ? "" : "s"} touched` +
+            (facts.exemptPaths.length > 0 ? `, ${facts.exemptPaths.length} exempt (Em-Upgrade)` : ""));
+        printFindings();
+        if (report.diagnostics.length === 0)
+            console.log("ok - no issues");
+    }
+    if (report.crossings > 0)
+        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
@@ -1954,6 +2357,14 @@ function packagedSkillsRoot() {
 function vendoredSkillsRoot(repoRoot) {
     return join(resolve(repoRoot), ".claude", "skills");
 }
+// MIL-269 (R32): the four em sub-agent definitions live in `.claude/agents/`, a directory shared
+// with the consumer's own agents - install/sync/check only ever handle the fixed EM_AGENT_FILES.
+function packagedAgentsRoot() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", ".claude", "agents");
+}
+function vendoredAgentsRoot(repoRoot) {
+    return join(resolve(repoRoot), ".claude", "agents");
+}
 program
     .command("contract")
     .description("print the packaged implementation contract (reference/implement.md) to stdout — the " +
@@ -1985,9 +2396,27 @@ function agentsMdMessage(result) {
         return `updated the agent-contract section in ${result.path}`;
     return `${result.path} already has an up-to-date agent-contract section`;
 }
+/** MIL-231: `em skill install`/`sync` keep working but the vendored bundle is deprecated in favour of
+ *  the em plugin. One stderr line naming the two-command install; the exit code is untouched. */
+function warnVendoredDeprecated() {
+    console.error(`warn: the vendored skill bundle is deprecated since em 1.14 — install the em plugin instead: ${pluginInstallCommands(PKG_VERSION).join(" && ")}`);
+}
 const skill = program
     .command("skill")
     .description("manage Claude Code skills bundled with em");
+// MIL-269: reconcile the four `.claude/agents/em-*.md` files (create the directory if absent);
+// byte-exact restore, never touches any other file there.
+function installAgentFiles(repoRoot) {
+    const packaged = packagedAgentsRoot();
+    const vendored = vendoredAgentsRoot(repoRoot);
+    const plan = planAgentSync(packaged, vendored, EM_AGENT_FILES);
+    if (plan.changes.length === 0)
+        return;
+    applySkillSync(plan, packaged, vendored);
+    for (const c of plan.changes)
+        console.log(`${c.kind}: agents/${c.relPath}`);
+    console.log(`installed em sub-agent definitions → ${vendored} (${plan.changes.length} file(s))`);
+}
 skill
     .command("install")
     .description("copy the event-modeling skill bundle into .claude/skills/ (event-modeling, event-modeling-" +
@@ -2000,6 +2429,7 @@ skill
     "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) => {
+    warnVendoredDeprecated();
     const srcRoot = packagedSkillsRoot();
     const destRoot = vendoredSkillsRoot(process.cwd());
     const anchor = join(destRoot, EM_SKILL_ANCHOR_DIR);
@@ -2031,6 +2461,7 @@ skill
                 `(${removedCount} removed), ${totalUnchanged} unchanged`);
         }
         console.log("in Claude Code, run /event-modeling to start a guided session");
+        installAgentFiles(process.cwd());
     }
     else {
         await mkdir(destRoot, { recursive: true });
@@ -2039,6 +2470,7 @@ skill
         }
         console.log(`installed event-modeling skill bundle → ${destRoot}`);
         console.log("in Claude Code, run /event-modeling to start a guided session");
+        installAgentFiles(process.cwd());
     }
     if (opts.agentsMd !== false) {
         console.log(agentsMdMessage(syncAgentsMd(process.cwd())));
@@ -2051,20 +2483,29 @@ skill
     .argument("[path]", "consumer repo root", ".")
     .option("--no-agents-md", "skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)")
     .action(async (path, opts) => {
+    warnVendoredDeprecated();
     const packagedRoot = packagedSkillsRoot();
     const vendoredRoot = vendoredSkillsRoot(path);
     const bundlePlan = planSkillSyncBundle(packagedRoot, vendoredRoot, 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 skillChanges = bundlePlan.reduce((n, { plan }) => n + plan.changes.length, 0);
+    // MIL-269 (R32): the fixed agent-file list, never the shared .claude/agents/ directory as a whole.
+    const packagedAgents = packagedAgentsRoot();
+    const vendoredAgents = vendoredAgentsRoot(path);
+    const agentPlan = planAgentSync(packagedAgents, vendoredAgents, EM_AGENT_FILES);
+    const totalChanges = skillChanges + agentPlan.changes.length;
+    const totalUnchanged = bundlePlan.reduce((n, { plan }) => n + plan.unchangedCount, 0) + agentPlan.unchangedCount;
     if (totalChanges === 0) {
         console.log(`up to date — ${vendoredRoot} already matches the installed skill bundle (${totalUnchanged} file(s))`);
     }
     else {
         applySkillSyncBundle(bundlePlan, packagedRoot, vendoredRoot);
+        applySkillSync(agentPlan, packagedAgents, vendoredAgents);
         for (const { dirName, plan } of bundlePlan) {
             for (const c of plan.changes)
                 console.log(`${c.kind}: ${dirName}/${c.relPath}`);
         }
+        for (const c of agentPlan.changes)
+            console.log(`${c.kind}: agents/${c.relPath}`);
         console.log(`synced ${vendoredRoot} — ${totalChanges} file(s) changed, ${totalUnchanged} unchanged`);
     }
     if (opts.agentsMd !== false) {
@@ -2073,21 +2514,55 @@ skill
 });
 skill
     .command("check")
-    .description("check the vendored .claude/skills/ event-modeling skill bundle in [path] for drift against " +
-    "the installed em package; exits non-zero on any mismatch (CI-ready, MIL-93)")
+    .description("check [path]'s em skills for drift against the installed em package: the em Claude Code plugin's " +
+    "pin (settings + this machine's marketplace registry) when the repo declares it, and the vendored " +
+    ".claude/skills/ bundle when present; exits non-zero on any mismatch (CI-ready, MIL-93, MIL-231)")
     .argument("[path]", "consumer repo root", ".")
     .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
+    .option("--ci", "also fail (exit 1) when the declared plugin is not registered on this machine (implied by CI=true in the environment); " +
+    "without it that finding prints the install commands on stderr and exits 0")
     .action((path, opts) => {
     const packagedRoot = packagedSkillsRoot();
     const vendoredRoot = vendoredSkillsRoot(path);
-    const result = checkSkillSyncBundle(packagedRoot, vendoredRoot, PKG_VERSION, EM_SKILL_DIR_NAMES, EM_SHARED_DIR_NAMES);
+    const ciMode = !!opts.ci || process.env.CI === "true";
+    // MIL-231: the plugin signal (a pinned marketplace in .claude/settings*.json) sits beside the
+    // vendored signal (the anchor directory). Plugin only -> only the plugin is checked; vendored
+    // only -> exactly the pre-1.14 behavior; both -> both; neither -> skill-check-not-installed.
+    const pluginCheck = checkPlugin(resolve(path), PKG_VERSION, claudePluginsDir());
+    const vendoredPresent = existsSync(join(vendoredRoot, EM_SKILL_ANCHOR_DIR));
+    const vendored = pluginCheck && !vendoredPresent
+        ? { findings: [], ok: true }
+        : checkSkillSyncBundle(packagedRoot, vendoredRoot, PKG_VERSION, EM_SKILL_DIR_NAMES, EM_SHARED_DIR_NAMES);
+    // MIL-269 (R32): the four agent files, only when the vendored bundle is present (a plugin-only
+    // repo ships them via the plugin); checked by fixed name, never the shared directory.
+    const agents = vendoredPresent
+        ? checkAgentFiles(packagedAgentsRoot(), vendoredAgentsRoot(path), EM_AGENT_FILES)
+        : { findings: [], ok: true };
+    const findings = [...vendored.findings, ...agents.findings, ...(pluginCheck?.findings ?? [])];
+    const failing = findings.filter((f) => f.code !== "plugin-not-installed-locally" || ciMode);
+    const ok = failing.length === 0;
+    const result = { findings, ok };
     if (opts.json) {
-        process.stdout.write(buildSkillCheckJson(result, vendoredRoot, PKG_VERSION) + "\n");
+        process.stdout.write(buildSkillCheckJson(result, vendoredRoot, PKG_VERSION, pluginCheck?.plugin ?? null) + "\n");
     }
     else {
-        for (const f of result.findings)
-            console.log(f.message);
-        console.log(result.ok ? `ok — vendored skill matches em ${PKG_VERSION}` : `${result.findings.length} mismatch(es)`);
+        for (const f of findings) {
+            if (f.code === "plugin-not-installed-locally" && !ciMode)
+                console.error(f.message);
+            else
+                console.log(f.message);
+        }
+        if (!ok)
+            console.log(`${failing.length} mismatch(es)`);
+        else {
+            if (!pluginCheck || vendoredPresent)
+                console.log(`ok — vendored skill matches em ${PKG_VERSION}`);
+            if (pluginCheck) {
+                const unregistered = findings.some((f) => f.code === "plugin-not-installed-locally");
+                console.log(`ok — em plugin ${pluginCheck.plugin.name} (${pluginCheck.plugin.ref}) matches em ${PKG_VERSION}` +
+                    (unregistered ? " (not registered on this machine - see the install commands on stderr)" : ""));
+            }
+        }
     }
     // MIL-219 ruling A: `em skill check` also warns when [path]'s own state file records an
     // `Em version:` behind the installed em — best-effort (no state file, or an unparseable
@@ -2103,7 +2578,7 @@ skill
     }
     // Set the code rather than process.exit(): same rationale as em ledger/em diff — stdout to
     // a pipe (a --json document) shouldn't risk truncation.
-    if (!result.ok)
+    if (!ok)
         process.exitCode = 1;
 });
 const ci = program.command("ci").description("scaffold/check the CI enforcement preset (MIL-166, see docs/ci.md)");
@@ -2112,10 +2587,12 @@ ci.command("init")
     "coverage --strict, em ledger, em skill check, em glossary --fail-on-conflicts, plus a " +
     "push-triggered status-badge rebuild) and em-conform.yml (scheduled, advisory-only " +
     "conformance cadence) — same install discipline as `em skill install`: marker-delimited, " +
-    "idempotent, --check for CI self-verification (MIL-166, see docs/ci.md)")
-    .argument("<model>", "anchor .em file the coverage/ledger/slice-index/status steps point at")
+    "idempotent, --check for CI self-verification (MIL-166, see docs/ci.md). Give it a " +
+    "system.yaml (or its directory) instead of a model to cover every model in the system: one " +
+    "workflow, per-model jobs, a conform matrix (MIL-233)")
+    .argument("<model>", "anchor .em file the coverage/ledger/slice-index/status steps point at, or a system.yaml (or a directory holding one) to cover every model in it")
     .option("--tests <dir>", "test directory the coverage/status steps scan for INV-* citations", "test")
-    .option("-f, --force", "replace an existing workflow file that has no GENERATED markers")
+    .option("-f, --force", "replace an existing workflow file that has no GENERATED markers, or a managed block generated for a different set of models")
     .option("--check", "verify both files match the current preset; exit non-zero on drift without writing (CI)")
     .action((model, opts) => {
     const unsafe = findUnsafeCiInitArg(model) ?? findUnsafeCiInitArg(opts.tests);
@@ -2127,20 +2604,55 @@ ci.command("init")
     const repoRoot = process.cwd();
     const ciPath = ciWorkflowPath(repoRoot);
     const conformPath = conformWorkflowPath(repoRoot);
-    const files = [
-        [
-            ciPath,
-            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, PKG_VERSION), CONFORM_WORKFLOW_MARKER, !!opts.force),
-        ],
-    ];
+    // MIL-231: a repo that declares the em plugin gets a conform workflow that installs the plugin
+    // and runs /em:conform; any other repo keeps the vendored install lines.
+    const usePlugin = detectPlugin(repoRoot) !== null;
+    // MIL-233: a system manifest (a .yaml/.yml file, or a directory) covers every model in it;
+    // anything else is the single-model form, unchanged.
+    const isDir = existsSync(model) && statSync(model).isDirectory();
+    const manifestForm = isDir || /\.ya?ml$/i.test(model);
+    let files;
+    if (manifestForm) {
+        const loaded = ciModelsFromManifest(model, repoRoot);
+        if (!loaded.ok) {
+            console.error(`em ci init: ${loaded.message}`);
+            process.exit(1);
+        }
+        files = [
+            [
+                ciPath,
+                planCiFile(ciPath, buildCiWorkflowFileMulti(model, loaded.models, opts.tests, PKG_VERSION), ciManagedBodyMulti(loaded.models, opts.tests, PKG_VERSION), CI_WORKFLOW_MARKER, !!opts.force, true),
+            ],
+            [
+                conformPath,
+                planCiFile(conformPath, buildConformWorkflowFileMulti(model, loaded.models, PKG_VERSION, usePlugin), conformManagedBodyMulti(loaded.models, PKG_VERSION, usePlugin), CONFORM_WORKFLOW_MARKER, !!opts.force, true),
+            ],
+        ];
+    }
+    else {
+        files = [
+            [
+                ciPath,
+                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, usePlugin), conformManagedBody(model, PKG_VERSION, usePlugin), CONFORM_WORKFLOW_MARKER, !!opts.force),
+            ],
+        ];
+    }
+    // MIL-256 (#174) / MIL-233: a managed block is identified by the SET of models it names. A
+    // disjoint set - or a single-model argument against a multi-model block - is its own
+    // condition: never `stale`, never silently replaced.
+    const otherModels = (status, path) => describeOtherModels(path, status);
     if (opts.check) {
         let drift = false;
         for (const [path, status] of files) {
-            if (status.kind === "create") {
+            if (status.kind === "other-models" || status.kind === "replace-models") {
+                console.log(`different models: ${otherModels(status, path)}`);
+                drift = true;
+            }
+            else if (status.kind === "create") {
                 console.log(`missing: ${path} — run \`em ci init ${model}\` to create it`);
                 drift = true;
             }
@@ -2149,7 +2661,11 @@ ci.command("init")
                 drift = true;
             }
             else if (status.kind === "stale") {
-                console.log(`stale: ${path} — run \`em ci init ${model}\` and commit the result`);
+                const marker = path === ciPath ? CI_WORKFLOW_MARKER : CONFORM_WORKFLOW_MARKER;
+                const change = manifestForm
+                    ? describeSetChange(fileBlockModels(status.current, marker), fileBlockModels(status.content, marker))
+                    : null;
+                console.log(`stale: ${path} — run \`em ci init ${model}\` and commit the result${change ? ` (${change})` : ""}`);
                 drift = true;
             }
             else {
@@ -2161,10 +2677,22 @@ ci.command("init")
             process.exitCode = 1;
         return;
     }
+    // Refuse before writing anything, so a refusal on one file never leaves the other updated.
+    const refused = files.filter(([, s]) => s.kind === "other-models");
+    if (refused.length > 0) {
+        for (const [path, status] of refused) {
+            if (status.kind === "other-models")
+                console.error(`em ci init: ${otherModels(status, path)}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
     mkdirSync(dirname(ciPath), { recursive: true });
     for (const [path, status] of files) {
         applyCiFile(path, status);
-        if (status.kind === "create")
+        if (status.kind === "replace-models")
+            console.log(`replaced ${path} (--force; was generated for ${status.previous.join(", ")})`);
+        else if (status.kind === "create")
             console.log(`installed ${path}`);
         else if (status.kind === "stale")
             console.log(`updated ${path}`);
@@ -2185,7 +2713,7 @@ program
     "makes one git commit per applicable step, refusing on a dirty working tree")
     .argument("<file>", "input .em model file")
     .option("--apply", "apply every applicable mechanical step, one git commit each, then a final `Em version:` commit")
-    .option("--check", "exit non-zero only on a hard incompatibility (unparseable state file, an un-migratable .em shape) — writes nothing; what CI runs")
+    .option("--check", "exit non-zero only on a hard incompatibility (an existing but unparseable state file, an un-migratable .em shape) — writes nothing; what CI runs; the final line says why")
     .option("--json", "print a JSON document instead of text (dry-run/--check only, never with --apply)")
     .action((file, opts) => {
     if (opts.apply && opts.check) {
@@ -2219,18 +2747,20 @@ program
         repoRoot: repoRootResult.repoRoot,
         installedVersion: PKG_VERSION,
         packagedSkillsRoot: packagedSkillsRoot(),
+        packagedAgentsRoot: packagedAgentsRoot(),
         model,
         refs,
     };
     if (opts.check) {
-        const { ok, report } = checkUpgrade(ctx);
+        const { ok, report, reasons } = checkUpgrade(ctx);
         console.error(`em upgrade --check: from ${report.from.version}${report.from.inferred ? ` (inferred: ${report.from.basis})` : ""} → to ${report.to}`);
         for (const s of report.steps) {
             console.error(`  [${s.applicable ? "x" : " "}] ${s.id} (since ${s.sinceVersion}): ${s.reason}`);
         }
         for (const h of report.human)
             console.error(`  human: ${h.id}: ${h.reason}`);
-        console.error(ok ? "ok — no hard incompatibility" : "em upgrade --check: hard incompatibility found");
+        // MIL-257: the final line always says why (previously visible only via --json).
+        console.error(ok ? "ok — no hard incompatibility" : `em upgrade --check: hard incompatibility found: ${reasons.join("; ")}`);
         if (!ok)
             process.exitCode = 1;
         return;
@@ -2336,6 +2866,7 @@ function computeAllDiagnostics(file, model, refs, diagnostics, source) {
         ...validateDocModelConsistency(model, refs, dirname(file)),
         ...validateOrphanedSliceDocs(model, refs, dirname(file)),
         ...validateModelVersionStale(model, refs, dirname(file), source),
+        ...validateInvariants(model, refs, dirname(file)),
     ];
 }
 /** Read a file's text, or exit with a clear error — shared by `em diff` (both forms) and
@@ -2441,7 +2972,7 @@ function printDivergences(model) {
  *  cross-model `public` view's reader legitimately lives outside this file (see
  *  `publicViewsWithoutInModelReader`'s own header for why this stays advisory). */
 function printPublicElements(model) {
-    const pub = model.elements.filter((el) => el.public && (el.kind === "event" || el.kind === "view"));
+    const pub = model.elements.filter((el) => el.public && (el.kind === "command" || el.kind === "event" || el.kind === "view"));
     if (pub.length === 0) {
         console.log("no public elements");
         return;