@milehimikey/em 1.8.1 → 1.9.0

package/dist/cli.js

@@ -15,6 +15,7 @@ import { serializeBuilds, watchFile } from "./render/watch.js";
 import { startLiveServer } from "./render/serve.js";
 import { formatDiagnostic, hasErrors } from "./model/validate.js";
 import { buildExport, buildSliceExport } from "./emit/json.js";
+import { buildTypeSpec } from "./emit/typespec.js";
 import { buildValidateJson, buildSliceReadyJson, buildValidateListJson, collectMarkers } from "./emit/validateJson.js";
 import { buildDiffJson } from "./emit/diffJson.js";
 import { diffModels, formatModelDiff, hasChanges } from "./model/diff.js";
@@ -24,16 +25,22 @@ import { validateLineage } from "./catalog/lineageValidate.js";
 import { validateFrontmatterCoherence } from "./catalog/frontmatterCoherenceValidate.js";
 import { validateNoteBindings } from "./catalog/noteBindingValidate.js";
 import { validateDocModelConsistency } from "./catalog/docModelConsistencyValidate.js";
+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 { planMigration, verifyMigration } from "./cli/migrateReactionShape.js";
 import { buildLedgerJson } from "./emit/ledgerJson.js";
 import { buildCoverageReport } from "./cli/coverage.js";
 import { buildCoverageJson } from "./emit/coverageJson.js";
-import { planSkillSync, applySkillSync } from "./cli/skillSync.js";
-import { checkSkillSync } from "./cli/skillCheck.js";
+import { resolveSliceStatusFacts, countOpenIssues, resolveConformanceEntry, aggregateInvariantTotals, buildStatusReport, formatStatusText, formatStatusMarkdown, buildStatusBadge, formatConformancePart, } from "./cli/status.js";
+import { buildStatusJson } from "./emit/statusJson.js";
+import { buildFreshnessJson } from "./emit/freshnessJson.js";
+import { planSkillSyncBundle, applySkillSyncBundle } from "./cli/skillSync.js";
+import { checkSkillSyncBundle } from "./cli/skillCheck.js";
 import { buildSkillCheckJson } from "./emit/skillCheckJson.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 { createServer as createMcpServer } from "./mcp/server.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { syncAgentsMd } from "./cli/agentsMd.js";
@@ -44,13 +51,21 @@ 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 { runConformSupersede } from "./cli/conformSupersede.js";
 import { buildConformScope, changedPathsSince, resolveSliceDocFacts, seedAsisModel } from "./cli/conformScope.js";
 import { buildSliceDocContent, isSlicePattern, sliceDocKey, SLICE_PATTERNS } from "./cli/sliceNew.js";
-import { listModelCommits, readFileAtCommit } from "./cli/changelog-git.js";
-import { buildChangelog, parseDecisionsLog } from "./emit/changelog.js";
+import { 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 { 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";
 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
@@ -76,25 +91,30 @@ program
 program
     .command("scaffold")
     .description("scaffold a full project: <slug>/<slug>.em, README.md, .event-modeling.md " +
-    "(see docs/cli.md — for just a starter .em, use `em init`)")
+    "(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")
     .option("-f, --force", "overwrite the directory's contents if it already exists")
+    .option("--under <dir>", "parent directory to scaffold into — writes <dir>/<slug>/ instead of ./<slug>/, the " +
+    "supported multi-model layout (docs/cli.md, \"Multi-model projects\"): one directory per " +
+    "model, so each model's slices/ never collides with a sibling model's")
     .action(async (name, opts) => {
     if (name.includes('"') || name.includes("{{")) {
         console.error(`em scaffold: name must not contain '"' or '{{' (breaks the generated .em/README/state files): ${name}`);
         process.exit(1);
     }
-    const dirName = kebabSlug(name);
-    if (existsSync(dirName) && !opts.force) {
-        console.error(`refusing to overwrite ${dirName}/ (use --force)`);
+    const slugName = kebabSlug(name);
+    const dirPath = opts.under ? join(opts.under, slugName) : slugName;
+    if (existsSync(dirPath) && !opts.force) {
+        console.error(`refusing to overwrite ${dirPath}/ (use --force)`);
         process.exit(1);
     }
-    await mkdir(dirName, { recursive: true });
+    await mkdir(dirPath, { recursive: true });
     const today = new Date().toISOString().slice(0, 10);
-    writeFileSync(join(dirName, `${dirName}.em`), starterEmFor(name));
-    writeFileSync(join(dirName, "README.md"), scaffoldReadme(name, dirName));
-    writeFileSync(join(dirName, STATE_FILE_NAME), scaffoldStateFile(name, dirName, today));
-    console.log(`scaffolded ${dirName}/`);
+    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));
+    console.log(`scaffolded ${dirPath}/`);
 });
 program
     .command("render")
@@ -211,6 +231,31 @@ 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)) {
+        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}`);
+    }
+    else {
+        process.stdout.write(generated.text + "\n");
+    }
+});
 program
     .command("diff")
     .description("compare two models structurally (two files, or one file across git revisions)")
@@ -366,6 +411,8 @@ slice
     .requiredOption("--pattern <pattern>", `slice pattern: ${SLICE_PATTERNS.join(" | ")}`)
     .requiredOption("--swimlane <swimlane>", 'swimlane, e.g. "Persona → Context"')
     .option("-f, --force", "overwrite the file if it already exists")
+    .option("--wire <model-file>", "also insert the `note \"slices/<key>.md\"` line onto the slice's primary element in this " +
+    ".em file (matched by export key), instead of just printing it to paste by hand (MIL-161)")
     .action((name, opts) => {
     if (!isSlicePattern(opts.pattern)) {
         console.error(`em slice new: invalid --pattern "${opts.pattern}" — expected one of: ${SLICE_PATTERNS.join(", ")}`);
@@ -378,11 +425,35 @@ slice
         console.error(`refusing to overwrite ${path} (use --force)`);
         process.exit(1);
     }
+    // Resolve (never write anything yet) BEFORE touching the doc file, so a --wire failure
+    // (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;
+    if (opts.wire) {
+        const { model, refs, diagnostics, source } = compileFile(opts.wire);
+        printDiagnostics(diagnostics);
+        if (hasErrors(diagnostics)) {
+            console.error(`em slice new --wire: not wiring — fix the errors in ${opts.wire} above`);
+            process.exit(1);
+        }
+        const result = wireSliceNote(source, model, refs, key, opts.pattern, path);
+        if (!result.ok) {
+            console.error(`em slice new --wire: ${result.message}`);
+            process.exit(1);
+        }
+        wired = result;
+    }
     mkdirSync(dir, { recursive: true });
     writeFileSync(path, buildSliceDocContent(name, key, opts.pattern, opts.swimlane));
     console.log(`wrote ${path}`);
-    console.log(`add this to the slice's primary element in the .em file:`);
-    console.log(`  note "${path}"`);
+    if (wired) {
+        writeFileSync(opts.wire, wired.content);
+        console.log(`wired ${path} onto ${wired.elementName} in slice "${wired.sliceName}" (${opts.wire})`);
+    }
+    else {
+        console.log(`add this to the slice's primary element in the .em file:`);
+        console.log(`  note "${path}"`);
+    }
 });
 slice
     .command("index")
@@ -441,6 +512,68 @@ slice
         ? `marked implemented: ${result.path} (implementedIn: ${prUrl})`
         : `already implemented (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")
+    .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)")
+    .action((file, sliceKey, opts) => {
+    const { model, refs, diagnostics } = compileFile(file);
+    printDiagnostics(diagnostics);
+    // Scoped the same way `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 ratify: slice "${sliceKey}" has errors — fix them first`);
+        process.exit(1);
+    }
+    const today = new Date().toISOString().slice(0, 10);
+    const ratifiedOn = opts.on ?? today;
+    if (opts.on !== undefined && !isValidDateString(opts.on)) {
+        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);
+    if (!result.ok) {
+        console.error(`em slice ratify: ${result.message}`);
+        process.exit(1);
+    }
+    console.log(result.changed
+        ? `ratified: ${result.path} (ratifiedBy: ${opts.by}, ratifiedOn: ${ratifiedOn})`
+        : `already ratified (no-op): ${result.path}`);
+});
+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 " +
+    "`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")
+    .argument("<file>", "input .em file")
+    .argument("<slice-key>", "slice export key (kebab-case)")
+    .action((file, sliceKey) => {
+    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 reratify: slice "${sliceKey}" has errors — fix them first`);
+        process.exit(1);
+    }
+    const result = runReratify(model, refs, dirname(file), sliceKey);
+    if (!result.ok) {
+        console.error(`em slice reratify: ${result.message}`);
+        process.exit(1);
+    }
+    console.log(`reratified: ${result.path} (version: ${result.newVersion}, status: ready-to-implement)`);
+});
 program
     .command("changelog")
     .description("render a model's git history as a business-readable ledger (see docs/cli.md)")
@@ -535,6 +668,69 @@ state
     }
     writeStateUpdate(dir, "em state set-review", (text, today) => setReview(text, date, today));
 });
+state
+    .command("log-usage")
+    .description("append one Usage log line — phase(s) touched + em validate's diagnostic categories hit, " +
+    "deduped and canonically formatted (MIL-161, docs/usage-data.md) — the mechanical half of " +
+    "'save state at the end of every session' that used to be run-validate-then-hand-format; " +
+    "state file resolved next to <file>, same convention as em conform-scope")
+    .argument("<file>", "input .em file")
+    .requiredOption("--phases <list>", `comma-separated phase(s) touched this session: ${USAGE_PHASES.join(", ")}`)
+    .action((file, opts) => {
+    const rawPhases = opts.phases
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (rawPhases.length === 0) {
+        console.error("em state log-usage: --phases must name at least one phase");
+        process.exit(1);
+    }
+    const invalid = rawPhases.filter((p) => !isUsagePhase(p));
+    if (invalid.length > 0) {
+        console.error(`em state log-usage: invalid phase(s) ${invalid.map((p) => `"${p}"`).join(", ")} — expected one of: ${USAGE_PHASES.join(", ")}`);
+        process.exit(1);
+    }
+    const phases = sortUsagePhases(rawPhases);
+    const { model, diagnostics, refs } = compileFile(file);
+    const allDiagnostics = computeAllDiagnostics(file, model, refs, diagnostics);
+    const categorySet = new Set(allDiagnostics.map((d) => RULES[d.code].usageCategory));
+    const categories = categorySet.size > 0 ? [...categorySet].sort() : ["none"];
+    const loaded = loadStateFile(dirname(file));
+    if (!loaded.ok) {
+        console.error(loaded.message);
+        process.exit(1);
+    }
+    const today = new Date().toISOString().slice(0, 10);
+    const result = appendUsageLogEntry(loaded.text, today, phases, categories);
+    if (!result.ok) {
+        console.error(`em state log-usage: ${result.message}`);
+        process.exit(1);
+    }
+    writeFileSync(loaded.path, result.text);
+    console.log(`wrote ${loaded.path} — phases: ${phases.join(", ")} — validate: ${categories.join(", ")}`);
+});
+program
+    .command("usage-report")
+    .description("aggregate every .event-modeling.md's Usage log under [root] into phase/diagnostic-category " +
+    "tallies (MIL-161) — replaces docs/usage-data.md's hand-rolled grep/awk/sort pipeline; a " +
+    "logged line that doesn't match the canonical em state log-usage format is reported under " +
+    "unparseableLines rather than silently mistallied or dropped")
+    .argument("[root]", "directory to search recursively for .event-modeling.md files", ".")
+    .option("--json", "print a JSON document instead of the text report")
+    .action((root, opts) => {
+    const files = findStateFiles(root);
+    const entries = files.map((relPath) => ({
+        file: relPath,
+        text: readFileSync(join(root, relPath), "utf8"),
+    }));
+    const report = aggregateUsageReport(root, entries);
+    if (opts.json) {
+        process.stdout.write(buildUsageReportJson(report) + "\n");
+    }
+    else {
+        console.log(formatUsageReportText(report));
+    }
+});
 program
     .command("conform-scope")
     .description("mechanize conform phase step 1 (reference/conform.md): map the target repo's changed paths " +
@@ -581,6 +777,35 @@ program
     }
     console.log(JSON.stringify(output, null, 2));
 });
+program
+    .command("conform-supersede")
+    .description("stamp a conformance report with a \"superseded as of <rev>\" banner once its findings have " +
+    "been ruled on (MIL-164, docs/process.md#what-ratified-means) — the companion step to run " +
+    "at ratification time so a reader following the report's file:line citations knows they " +
+    "describe an ancestor of the current model. Additive-only splice, never a rewrite of the " +
+    "report; idempotent on the same --as-of/--findings/--on stamp; refuses if the report " +
+    "doesn't exist")
+    .argument("<file>", "input .em file (used only to resolve the report path's base directory)")
+    .argument("<report-path>", "path to the conformance report, relative to the model's directory")
+    .requiredOption("--as-of <rev>", "the revision this ruling was made against — same value passed to `em state set-conformance`")
+    .requiredOption("--findings <spec>", 'which finding number(s) this stamps as ruled, e.g. "1-3" or "1,2,4"')
+    .option("--on <date>", "ruling date, YYYY-MM-DD (default: today)")
+    .action((file, reportPath, opts) => {
+    const today = new Date().toISOString().slice(0, 10);
+    const on = opts.on ?? today;
+    if (opts.on !== undefined && !isValidDateString(opts.on)) {
+        console.error(`em conform-supersede: invalid --on date "${opts.on}" — expected YYYY-MM-DD`);
+        process.exit(1);
+    }
+    const result = runConformSupersede(dirname(file), reportPath, opts.asOf, opts.findings, on);
+    if (!result.ok) {
+        console.error(`em conform-supersede: ${result.message}`);
+        process.exit(1);
+    }
+    console.log(result.changed
+        ? `stamped superseded: ${result.path} (as of ${opts.asOf}, findings ${opts.findings}, on ${on})`
+        : `already stamped (no-op): ${result.path}`);
+});
 program
     .command("watch")
     .description("re-render on every save")
@@ -670,19 +895,7 @@ program
     "(MIL-128, see docs/cli.md); exit codes are unchanged")
     .action((file, opts) => {
     const { model, diagnostics, refs } = compileFile(file);
-    // Lineage-ref resolution (MIL-84), frontmatter-coherence (MIL-85), note-binding
-    // mismatches (MIL-126), and doc↔model consistency (MIL-124) are validate's fs-aware
-    // rules — every other check above is a pure function of the .em source. All four read
-    // slices/*.md alongside the model. Doc↔model consistency is deliberately validate-only
-    // (unlike note-binding, which `em render` also folds in) — it's a conform-phase concern,
-    // not something every render needs to recheck.
-    const allDiagnostics = [
-        ...diagnostics,
-        ...validateLineage(model, refs, dirname(file)),
-        ...validateFrontmatterCoherence(model, refs, dirname(file)),
-        ...validateNoteBindings(model, refs, dirname(file)),
-        ...validateDocModelConsistency(model, refs, dirname(file)),
-    ];
+    const allDiagnostics = computeAllDiagnostics(file, model, refs, diagnostics);
     if (opts.sliceReady) {
         // MIL-87: a targeted, single-slice readiness gate, not part of the unconditional
         // diagnostic set above (see sliceReadyValidate.ts's header for why). Folds in MIL-85's
@@ -899,15 +1112,147 @@ program
     if (opts.strict && report.uncoveredCount > 0)
         process.exitCode = 1;
 });
-// Shared by install/sync/check: the skill directory bundled with whatever em package is
+program
+    .command("status")
+    .description("deterministic state-of-the-system rollup over one or more .em models: slices by " +
+    "lifecycle status, driftSignal breakdown, invariant coverage totals (with --tests), " +
+    "open issue markers + unchecked Open Questions, and last-conformance commits-behind-HEAD " +
+    "(MIL-163, see docs/cli.md)")
+    .argument("<files...>", "input .em files")
+    .option("--tests <dir>", "directory to scan for INV-* test citations — enables invariant coverage totals")
+    .option("--repo <path>", "git repo to compute commits-behind-HEAD in (default: each model's own directory)")
+    .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
+    .option("--md", "print a markdown block suited for README embedding")
+    .option("--badge", "print a generated SVG badge")
+    .option("-o, --out <path>", "write output to a file instead of stdout")
+    .action((files, opts) => {
+    const modesSelected = [opts.json, opts.md, opts.badge].filter(Boolean).length;
+    if (modesSelected > 1) {
+        console.error("em status: --json, --md, and --badge are mutually exclusive");
+        process.exit(1);
+    }
+    if (opts.tests) {
+        if (!existsSync(opts.tests)) {
+            console.error(`em status: --tests directory not found: ${opts.tests}`);
+            process.exit(1);
+        }
+        if (!statSync(opts.tests).isDirectory()) {
+            console.error(`em status: --tests is not a directory: ${opts.tests}`);
+            process.exit(1);
+        }
+    }
+    const compiled = [];
+    let anyErrors = false;
+    for (const file of files) {
+        const { model, refs, diagnostics } = compileFile(file);
+        printDiagnosticsFor(file, diagnostics);
+        if (hasErrors(diagnostics))
+            anyErrors = true;
+        compiled.push({ file, model, refs });
+    }
+    if (anyErrors) {
+        console.error("em status: not reporting status — fix the errors above");
+        process.exit(1);
+    }
+    const sliceFacts = [];
+    const factsByFile = new Map();
+    const statusDiagnostics = [];
+    // MIL-160: a multi-model run is exactly the case where two `.em` files could share a
+    // directory and collide on a slice key — checked once, up front, over every compiled
+    // input (never fatal, same "warn, don't block" posture as the doc-join diagnostics below).
+    const collisions = detectSliceDocCollisions(compiled.map(({ file, refs }) => ({ file, sliceKeys: refs.sliceKeys })));
+    for (const d of collisions) {
+        const file = d.refs?.[2] ?? files[0];
+        printDiagnosticsFor(file, [d]);
+        statusDiagnostics.push({ file, ...d });
+    }
+    let openIssuesCount = 0;
+    const coverageReports = [];
+    for (const { file, model, refs } of compiled) {
+        const baseDir = dirname(file);
+        const { facts, diagnostics: docDiags } = resolveSliceStatusFacts(file, model, refs, baseDir);
+        printDiagnosticsFor(file, docDiags);
+        sliceFacts.push(...facts);
+        factsByFile.set(file, facts);
+        for (const d of docDiags)
+            statusDiagnostics.push({ file, ...d });
+        // MIL-183: a slices/*.md file left behind by a rename/removal, matching no current
+        // slice's key or `covers:` declaration — same "fold into status's diagnostics list" as
+        // every other doc-join warning above.
+        const orphanDiags = validateOrphanedSliceDocs(model, refs, baseDir);
+        printDiagnosticsFor(file, orphanDiags);
+        for (const d of orphanDiags)
+            statusDiagnostics.push({ file, ...d });
+        openIssuesCount += countOpenIssues(model);
+        if (opts.tests)
+            coverageReports.push(buildCoverageReport(model, refs, baseDir, opts.tests));
+    }
+    const invariants = opts.tests ? aggregateInvariantTotals(opts.tests, coverageReports) : null;
+    // MIL-164: slice-PRs-behind-HEAD is scoped per model — THIS model's own facts, not the
+    // merged `sliceFacts` above (which spans every input file when several are given).
+    const conformance = compiled.map(({ file }) => {
+        const facts = factsByFile.get(file) ?? [];
+        const sliceDocFacts = facts.map((f) => ({ key: f.key, status: f.rawStatus, implementedIn: f.implementedIn }));
+        return resolveConformanceEntry(file, opts.repo, sliceDocFacts);
+    });
+    const report = buildStatusReport(files, sliceFacts, openIssuesCount, invariants, conformance, statusDiagnostics);
+    let output;
+    if (opts.json)
+        output = buildStatusJson(report);
+    else if (opts.md)
+        output = formatStatusMarkdown(report);
+    else if (opts.badge)
+        output = buildStatusBadge(report);
+    else
+        output = formatStatusText(report);
+    if (opts.out) {
+        writeFileSync(opts.out, output + "\n");
+        console.log(`wrote ${opts.out}`);
+    }
+    else {
+        process.stdout.write(output + "\n");
+    }
+});
+program
+    .command("freshness")
+    .description("standalone freshness signal for one model's conformance record (MIL-164): \"last conformed " +
+    "<rev> — N commits and M slice-PRs behind HEAD\", computed from the same conform-scope " +
+    "machinery `em status`'s conformance clause uses — for when you want just this fact, no " +
+    "full state-of-the-system rollup (see docs/cli.md)")
+    .argument("<file>", "input .em file")
+    .option("--repo <path>", "git repo to compute behind-HEAD in (default: the model's own directory)")
+    .option("--json", "print a JSON document instead of the text line")
+    .action((file, opts) => {
+    const { model, refs, diagnostics } = compileFile(file);
+    printDiagnostics(diagnostics);
+    if (hasErrors(diagnostics)) {
+        console.error("em freshness: not reporting freshness — fix the errors above");
+        process.exit(1);
+    }
+    const baseDir = dirname(file);
+    const { facts, diagnostics: docDiags } = resolveSliceDocFacts(model, refs, baseDir);
+    printDiagnostics(docDiags);
+    const entry = resolveConformanceEntry(file, opts.repo, facts);
+    if (opts.json) {
+        process.stdout.write(buildFreshnessJson(entry) + "\n");
+    }
+    else {
+        console.log(formatConformancePart(entry));
+    }
+});
+// 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
-// PKG_VERSION) and the skill directory a consumer repo vendors it into.
-function packagedSkillDir() {
-    return join(dirname(fileURLToPath(import.meta.url)), "..", ".claude", "skills", "event-modeling");
+// PKG_VERSION) and the `.claude/skills/` root a consumer repo vendors it into. The em skill
+// itself lives under several named directories inside this root (MIL-157, src/cli/skillDirs.ts)
+// rather than being this whole root's only occupant — install/sync/check only ever touch those
+// named directories, never the root wholesale, so an unrelated skill already vendored alongside
+// em's is never at risk.
+function packagedSkillsRoot() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", ".claude", "skills");
 }
-function vendoredSkillDir(repoRoot) {
-    return join(resolve(repoRoot), ".claude", "skills", "event-modeling");
+function vendoredSkillsRoot(repoRoot) {
+    return join(resolve(repoRoot), ".claude", "skills");
 }
 program
     .command("contract")
@@ -915,7 +1260,7 @@ program
     "agent-neutral discovery path for any agent that can run a shell, not just Claude Code " +
     "(MIL-129); see docs/cli.md")
     .action(() => {
-    process.stdout.write(readContract(packagedSkillDir()));
+    process.stdout.write(readContract(join(packagedSkillsRoot(), "event-modeling-implement")));
 });
 program
     .command("mcp")
@@ -943,20 +1288,23 @@ const skill = program
     .description("manage Claude Code skills bundled with em");
 skill
     .command("install")
-    .description("copy the event-modeling skill into .claude/skills/event-modeling/")
+    .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")
     .option("--no-agents-md", "skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)")
     .action(async (opts) => {
-    const src = packagedSkillDir();
-    const dest = vendoredSkillDir(process.cwd());
-    if (existsSync(dest) && !opts.force) {
-        console.log(`skill already installed at ${dest}`);
+    const srcRoot = packagedSkillsRoot();
+    const destRoot = vendoredSkillsRoot(process.cwd());
+    const anchor = join(destRoot, EM_SKILL_ANCHOR_DIR);
+    if (existsSync(anchor) && !opts.force) {
+        console.log(`skill already installed at ${anchor}`);
         console.log("re-run with --force to overwrite");
     }
     else {
-        await mkdir(join(process.cwd(), ".claude", "skills"), { recursive: true });
-        await cp(src, dest, { recursive: true });
-        console.log(`installed event-modeling skill → ${dest}`);
+        await mkdir(destRoot, { recursive: true });
+        for (const name of EM_ALL_SKILL_BUNDLE_DIRS) {
+            await cp(join(srcRoot, name), join(destRoot, name), { recursive: true });
+        }
+        console.log(`installed event-modeling skill bundle → ${destRoot}`);
         console.log("in Claude Code, run /event-modeling to start a guided session");
     }
     if (opts.agentsMd !== false) {
@@ -965,22 +1313,26 @@ skill
 });
 skill
     .command("sync")
-    .description("update the vendored .claude/skills/event-modeling/ copy in [path] to match the installed " +
-    "em package (overwrites unconditionally; local edits are never merged, MIL-93)")
+    .description("update the vendored .claude/skills/ event-modeling skill bundle in [path] to match the " +
+    "installed em package (overwrites unconditionally; local edits are never merged, MIL-93)")
     .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) => {
-    const packagedDir = packagedSkillDir();
-    const vendoredDir = vendoredSkillDir(path);
-    const plan = planSkillSync(packagedDir, vendoredDir);
-    if (plan.changes.length === 0) {
-        console.log(`up to date — ${vendoredDir} already matches the installed skill (${plan.unchangedCount} file(s))`);
+    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);
+    if (totalChanges === 0) {
+        console.log(`up to date — ${vendoredRoot} already matches the installed skill bundle (${totalUnchanged} file(s))`);
     }
     else {
-        applySkillSync(plan, packagedDir, vendoredDir);
-        for (const c of plan.changes)
-            console.log(`${c.kind}: ${c.relPath}`);
-        console.log(`synced ${vendoredDir} — ${plan.changes.length} file(s) changed, ${plan.unchangedCount} unchanged`);
+        applySkillSyncBundle(bundlePlan, packagedRoot, vendoredRoot);
+        for (const { dirName, plan } of bundlePlan) {
+            for (const c of plan.changes)
+                console.log(`${c.kind}: ${dirName}/${c.relPath}`);
+        }
+        console.log(`synced ${vendoredRoot} — ${totalChanges} file(s) changed, ${totalUnchanged} unchanged`);
     }
     if (opts.agentsMd !== false) {
         console.log(agentsMdMessage(syncAgentsMd(resolve(path))));
@@ -988,16 +1340,16 @@ skill
 });
 skill
     .command("check")
-    .description("check the vendored .claude/skills/event-modeling/ copy in [path] for drift against the " +
-    "installed em package; exits non-zero on any mismatch (CI-ready, MIL-93)")
+    .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)")
     .argument("[path]", "consumer repo root", ".")
     .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
     .action((path, opts) => {
-    const packagedDir = packagedSkillDir();
-    const vendoredDir = vendoredSkillDir(path);
-    const result = checkSkillSync(packagedDir, vendoredDir, PKG_VERSION);
+    const packagedRoot = packagedSkillsRoot();
+    const vendoredRoot = vendoredSkillsRoot(path);
+    const result = checkSkillSyncBundle(packagedRoot, vendoredRoot, PKG_VERSION, EM_SKILL_DIR_NAMES, EM_SHARED_DIR_NAMES);
     if (opts.json) {
-        process.stdout.write(buildSkillCheckJson(result, vendoredDir, PKG_VERSION) + "\n");
+        process.stdout.write(buildSkillCheckJson(result, vendoredRoot, PKG_VERSION) + "\n");
     }
     else {
         for (const f of result.findings)
@@ -1009,6 +1361,76 @@ skill
     if (!result.ok)
         process.exitCode = 1;
 });
+const ci = program.command("ci").description("scaffold/check the CI enforcement preset (MIL-166, see docs/ci.md)");
+ci.command("init")
+    .description("install .github/workflows/em-ci.yml (PR gates: em validate, em slice index --check, em " +
+    "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")
+    .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("--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);
+    if (unsafe) {
+        console.error(`em ci init: argument must not contain '"', '\`', '$', or a newline (breaks the ` +
+            `generated workflow's shell steps): ${unsafe}`);
+        process.exit(1);
+    }
+    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), CI_WORKFLOW_MARKER, !!opts.force),
+        ],
+        [
+            conformPath,
+            planCiFile(conformPath, buildConformWorkflowFile(model, PKG_VERSION), conformManagedBody(model), CONFORM_WORKFLOW_MARKER, !!opts.force),
+        ],
+    ];
+    if (opts.check) {
+        let drift = false;
+        for (const [path, status] of files) {
+            if (status.kind === "create") {
+                console.log(`missing: ${path} — run \`em ci init ${model}\` to create it`);
+                drift = true;
+            }
+            else if (status.kind === "missing-markers") {
+                console.log(`can't verify: ${path} exists without GENERATED markers (re-run with --force to replace it)`);
+                drift = true;
+            }
+            else if (status.kind === "stale") {
+                console.log(`stale: ${path} — run \`em ci init ${model}\` and commit the result`);
+                drift = true;
+            }
+            else {
+                console.log(`ok: ${path}`);
+            }
+        }
+        console.log(drift ? "em ci init --check: drift found" : "ok — both workflow files match the current preset");
+        if (drift)
+            process.exitCode = 1;
+        return;
+    }
+    mkdirSync(dirname(ciPath), { recursive: true });
+    for (const [path, status] of files) {
+        applyCiFile(path, status);
+        if (status.kind === "create")
+            console.log(`installed ${path}`);
+        else if (status.kind === "stale")
+            console.log(`updated ${path}`);
+        else if (status.kind === "would-replace")
+            console.log(`replaced ${path} (--force)`);
+        else if (status.kind === "missing-markers")
+            console.log(`${path} already exists — re-run with --force to overwrite`);
+        else
+            console.log(`${path} already up to date`);
+    }
+});
 // Exported so dev tooling (e.g. scripts/generate-skill-docs.ts) can introspect the registered
 // commands/options without triggering a real CLI run. Guarded the same way Node's CJS
 // `require.main === module` used to: only actually parse argv when this file is the process's
@@ -1050,6 +1472,25 @@ function compileFile(file, opts = {},
         throw e;
     }
 }
+/** Lineage-ref resolution (MIL-84), frontmatter-coherence (MIL-85), note-binding mismatches
+ *  (MIL-126), doc↔model consistency (MIL-124), and orphaned slice docs (MIL-183) are `em
+ *  validate`'s fs-aware rules — every other diagnostic in `diagnostics` (from `compileFile`) is a
+ *  pure function of the .em source. All five read `slices/*.md` alongside the model. Doc↔model
+ *  consistency and orphaned-slice-doc are deliberately validate-only (unlike note-binding, which
+ *  `em render` also folds in) — both are conform-phase concerns, not something every render needs
+ *  to recheck. Shared by `em validate` and `em state log-usage` (MIL-161) — the latter needs the
+ *  exact same diagnostic set `em validate --json` would report, since its whole job is logging
+ *  which categories fired. */
+function computeAllDiagnostics(file, model, refs, diagnostics) {
+    return [
+        ...diagnostics,
+        ...validateLineage(model, refs, dirname(file)),
+        ...validateFrontmatterCoherence(model, refs, dirname(file)),
+        ...validateNoteBindings(model, refs, dirname(file)),
+        ...validateDocModelConsistency(model, refs, dirname(file)),
+        ...validateOrphanedSliceDocs(model, refs, dirname(file)),
+    ];
+}
 /** Read a file's text, or exit with a clear error — shared by `em diff` (both forms) and
  *  `em glossary`, which each read one or more plain `.em` files off disk before compiling. */
 function readFileOrExit(file) {
@@ -1083,76 +1524,6 @@ function readAtRevision(file, rev) {
     }
     return result.content;
 }
-/**
- * Build the `em changelog` markdown document for an already-resolved commit
- * list (oldest -> newest). Compiles every revision once; per-revision
- * warnings are deliberately never printed (historical revisions can be noisy)
- * — only a compile *failure* (parse error or validation error, same
- * threshold `em diff` uses) surfaces, as that entry's error note, never a
- * crash. Diffs are computed against the previous *parseable* revision, so a
- * single bad revision in the middle of the walk doesn't break every entry
- * after it. Content is read at each commit's own path (`readFileAtCommit`),
- * so the walk survives renames.
- */
-function buildChangelogDoc(file, repoRoot, commits) {
-    const models = [];
-    const refsList = [];
-    const errors = [];
-    for (const c of commits) {
-        const rev = readFileAtCommit(repoRoot, c);
-        if (!rev.ok) {
-            models.push(null);
-            refsList.push(null);
-            errors.push(rev.message);
-            continue;
-        }
-        try {
-            const { model, refs, diagnostics } = compile(rev.content);
-            if (hasErrors(diagnostics)) {
-                models.push(null);
-                refsList.push(null);
-                errors.push(`validation errors at ${c.shortHash} — fix with \`em validate\` at that revision`);
-            }
-            else {
-                models.push(model);
-                refsList.push(refs);
-                errors.push(null);
-            }
-        }
-        catch (e) {
-            models.push(null);
-            refsList.push(null);
-            errors.push(e instanceof ParseError ? `parse error: ${e.message}` : e instanceof Error ? e.message : String(e));
-        }
-    }
-    const entries = [];
-    let prevParseable = -1;
-    commits.forEach((c, i) => {
-        const base = { shortHash: c.shortHash, date: c.date, subject: c.subject };
-        if (i === 0) {
-            entries.push({ ...base, diff: null });
-        }
-        else if (!models[i]) {
-            entries.push({ ...base, diff: null, error: errors[i] });
-        }
-        else if (prevParseable === -1) {
-            entries.push({ ...base, diff: null, error: `no earlier parseable revision to diff against (${commits[0].shortHash}: ${errors[0]})` });
-        }
-        else {
-            entries.push({
-                ...base,
-                diff: diffModels(models[prevParseable], models[i], refsList[prevParseable], refsList[i]),
-            });
-        }
-        if (models[i])
-            prevParseable = i;
-    });
-    const intro = models[0] ? { slices: models[0].slices.length, elements: models[0].elements.length } : null;
-    const introError = models[0] ? undefined : (errors[0] ?? undefined);
-    const stateFile = join(dirname(file), STATE_FILE_NAME);
-    const decisions = existsSync(stateFile) ? parseDecisionsLog(readFileSync(stateFile, "utf8")) : [];
-    return buildChangelog(entries, decisions, { file, intro, introError });
-}
 /** Shared body for both `em diff` forms: compile both sides, gate on errors, print, exit-code. */
 function runDiff(oldSource, oldLabel, newSource, newLabel, exitCode, json, lineage) {
     const oldResult = compileSource(oldSource, oldLabel);