@milehimikey/em 1.12.0 → 1.13.0

package/dist/cli.js

@@ -15,8 +15,8 @@ import { buildSliceDiagram } from "./render/sliceDiagram.js";
 import { resolveSliceArg, defaultSliceOut } from "./cli/render-inputs.js";
 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 { formatDiagnostic, hasErrors, publicViewsWithoutInModelReader } from "./model/validate.js";
+import { buildExport, buildSliceExport, GENERATOR_VERSION } 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";
@@ -28,6 +28,7 @@ import { validateFrontmatterCoherence } from "./catalog/frontmatterCoherenceVali
 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 { detectSliceDocCollisions } from "./catalog/modelCollisionValidate.js";
 import { checkLedger, readLedgerWaiverTrailers, applyLedgerWaivers } from "./cli/ledgerCheck.js";
@@ -35,9 +36,11 @@ import { planMigration, verifyMigration } from "./cli/migrateReactionShape.js";
 import { buildLedgerJson } from "./emit/ledgerJson.js";
 import { buildCoverageReport, resolveScopedSlices } from "./cli/coverage.js";
 import { buildCoverageJson } from "./emit/coverageJson.js";
-import { resolveSliceStatusFacts, countOpenIssues, resolveConformanceEntry, aggregateInvariantTotals, buildStatusReport, formatStatusText, formatStatusMarkdown, buildStatusBadge, formatConformancePart, findSpecifyRoot, } from "./cli/status.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 { buildMetricsJson } from "./emit/metricsJson.js";
 import { planSkillSyncBundle, applySkillSyncBundle } from "./cli/skillSync.js";
 import { checkSkillSyncBundle } from "./cli/skillCheck.js";
 import { buildSkillCheckJson } from "./emit/skillCheckJson.js";
@@ -57,15 +60,22 @@ import { runRatify } from "./cli/ratify.js";
 import { runReview } from "./cli/review.js";
 import { runConformSupersede } from "./cli/conformSupersede.js";
 import { buildConformScope, changedPathsSince, resolveSliceDocFacts, seedAsisModel } from "./cli/conformScope.js";
-import { buildSliceDocContent, isSlicePattern, sliceDocKey, SLICE_PATTERNS } from "./cli/sliceNew.js";
+import { buildSliceDocContent, buildStubDocContent, isSlicePattern, sliceDocKey, SLICE_PATTERNS } from "./cli/sliceNew.js";
 import { wireSliceNote } from "./cli/sliceLink.js";
+import { isStubStatus, runStubAll, STUB_STATUSES } from "./cli/sliceStubAll.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, modelPathMismatch, } from "./cli/stateFile.js";
+import { runSliceConform } from "./cli/sliceConform.js";
+import { checkFindingsFile, buildCheckFindingsJson, lookupFindingsBesideReport, unruledFindingsInScope, FINDING_LOCI } from "./cli/findings.js";
+import { STATE_FILE_NAME, PHASES, isPhase, loadStateFile, parseState, setPhase, setConformance, setModelVersion, setCertified, setEmVersion, setReview, isValidDateString, modelPathMismatch, } from "./cli/stateFile.js";
+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 { resolveRepoRoot, detectUpgrade, applyUpgrade, checkUpgrade } from "./cli/upgrade.js";
+import { buildUpgradeJson } from "./emit/upgradeJson.js";
+import { isOlder } from "./util/semver.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";
@@ -126,7 +136,7 @@ program
     const today = localIsoDate();
     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));
+    writeFileSync(join(dirPath, STATE_FILE_NAME), scaffoldStateFile(name, slugName, today, PKG_VERSION));
     // MIL-202: the implementation constitution. One document per project, never two — in a
     // spec-kit project `.specify/memory/constitution.md` already IS that slot, so em defers to it
     // and writes nothing rather than seeding a second, competing copy beside the model. Same
@@ -437,6 +447,9 @@ slice
     .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)")
+    .option("--stub", "write a near-free stub instead: same 5 frontmatter keys, but a one-line placeholder body " +
+    "instead of the diagram-image stub and every judgment section (MIL-184) — deepen it later " +
+    "by re-running without --stub and -f")
     .action((name, opts) => {
     if (!isSlicePattern(opts.pattern)) {
         console.error(`em slice new: invalid --pattern "${opts.pattern}" — expected one of: ${SLICE_PATTERNS.join(", ")}`);
@@ -468,7 +481,10 @@ slice
         wired = result;
     }
     mkdirSync(dir, { recursive: true });
-    writeFileSync(path, buildSliceDocContent(name, key, opts.pattern, opts.swimlane));
+    const content = opts.stub
+        ? buildStubDocContent(name, opts.pattern, opts.swimlane)
+        : buildSliceDocContent(name, key, opts.pattern, opts.swimlane);
+    writeFileSync(path, content);
     console.log(`wrote ${path}`);
     if (wired) {
         writeFileSync(opts.wire, wired.content);
@@ -479,6 +495,59 @@ slice
         console.log(`  note "${path}"`);
     }
 });
+slice
+    .command("stub-all")
+    .description("scaffold + wire a near-free stub (`em slice new --stub`'s content, MIL-184) for every " +
+    "slice in <file> with no resolvable doc — the fast path to status coloring for an " +
+    "exploratory/backbone model without hand-running `slice new` per slice. Skips a " +
+    "continuation slice (MIL-208, it has no doc of its own), an already-documented slice, and " +
+    "a slice whose pattern can't be classified")
+    .argument("<file>", "input .em file")
+    .option("--status <status>", `target status for every stub: ${STUB_STATUSES.join(" | ")}`, "draft")
+    .option("--by <name>", "identity for reviewedBy/ratifiedBy — required unless --status draft")
+    .option("--implemented-in <url>", "PR/commit URL for implementedIn — required with --status implemented")
+    .option("--dry-run", "list what would be stubbed/wired without writing anything")
+    .action((file, opts) => {
+    if (!isStubStatus(opts.status)) {
+        console.error(`em slice stub-all: invalid --status "${opts.status}" — expected one of: ${STUB_STATUSES.join(", ")}`);
+        process.exit(1);
+    }
+    if (opts.status !== "draft" && !opts.by) {
+        console.error(`em slice stub-all: --status ${opts.status} requires --by <name>`);
+        process.exit(1);
+    }
+    if (opts.status === "implemented" && !opts.implementedIn) {
+        console.error("em slice stub-all: --status implemented requires --implemented-in <url>");
+        process.exit(1);
+    }
+    const { model, refs, diagnostics, source } = compileFile(file);
+    printDiagnostics(diagnostics);
+    if (hasErrors(diagnostics)) {
+        console.error("em slice stub-all: not stubbing — fix the errors above");
+        process.exit(1);
+    }
+    mkdirSync(join(dirname(file), "slices"), { recursive: true });
+    const result = runStubAll(model, refs, dirname(file), source, {
+        status: opts.status,
+        by: opts.by ?? null,
+        on: localIsoDate(),
+        implementedInUrl: opts.implementedIn ?? null,
+        dryRun: opts.dryRun === true,
+    });
+    for (const outcome of result.outcomes) {
+        if (outcome.kind === "skip") {
+            console.log(`skip ${outcome.sliceKey} — ${outcome.reason}`);
+            continue;
+        }
+        const verb = opts.dryRun ? "would stub" : "stubbed";
+        const wireNote = outcome.wired ? `wired onto ${outcome.elementName}` : "already wired";
+        console.log(`${verb} ${outcome.path} (${outcome.sliceKey}, pattern: ${outcome.pattern}, swimlane: "${outcome.swimlane}", ` +
+            `status: ${outcome.status}, ${wireNote})`);
+    }
+    if (!opts.dryRun && result.source !== source) {
+        writeFileSync(file, result.source);
+    }
+});
 slice
     .command("index")
     .description("rewrite the model's sibling README.md's GENERATED Slices table from `em export`'s slice " +
@@ -587,7 +656,7 @@ slice
     .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")
     .action((file, sliceKey, opts) => {
-    const { model, refs, diagnostics } = compileFile(file);
+    const { model, refs, diagnostics, source } = 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.
@@ -622,6 +691,7 @@ slice
     console.log(result.changed
         ? `ratified: ${result.path} (ratifiedBy: ${opts.by}, ratifiedOn: ${ratifiedOn})`
         : `already ratified (no-op): ${result.path}`);
+    warnModelVersionDrift(dirname(file), model, refs, source, `ratifying "${sliceKey}"`);
 });
 slice
     .command("reratify")
@@ -634,7 +704,7 @@ slice
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
     .action((file, sliceKey) => {
-    const { model, refs, diagnostics } = compileFile(file);
+    const { model, refs, diagnostics, source } = 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.
@@ -648,7 +718,60 @@ slice
         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) {
+        console.error(`warn: reratifying "${sliceKey}" whose v${result.newVersion - 1} was never certified`);
+    }
+    if (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)`);
+    warnModelVersionDrift(dirname(file), model, refs, source, `reratifying "${sliceKey}"`);
+});
+slice
+    .command("conform")
+    .description("record per-slice-per-version conformance certification: sets `conformedVersion:`/" +
+    "`conformedAt:`/`conformedOn:` on a slice doc (MIL-214) — the fact `driftSignal: in-sync` " +
+    "now depends on. Legal only for `status: implemented` with an `implementedIn:` link. " +
+    "Idempotent on the same (version, --at) pair; a different --at simply overwrites (a " +
+    "later re-certification is normal — there's no way for em to tell 'later' from 'earlier' " +
+    "for an arbitrary revision string, so there's no --force to reach for). Refuses when the " +
+    "newest conformance/*-findings.json matching --at still has an unruled finding in scope " +
+    "for this slice; --skip-findings-check overrides with a loud notice.")
+    .argument("<file>", "input .em file")
+    .argument("<slice-key>", "slice export key (kebab-case)")
+    .requiredOption("--at <rev>", "the target-repo revision this certification sweep diffed against")
+    .option("--on <date>", "certification date, YYYY-MM-DD (default: today, local date)")
+    .option("--skip-findings-check", "certify even with unruled findings in scope — prints a loud notice on stderr")
+    .action((file, sliceKey, opts) => {
+    const { model, refs, diagnostics } = compileFile(file);
+    printDiagnostics(diagnostics);
+    // Scoped the same way `em slice ratify`/`em slice reratify`/`em slice mark-implemented` 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 conform: slice "${sliceKey}" has errors — fix them first`);
+        process.exit(1);
+    }
+    const today = localIsoDate();
+    const on = opts.on ?? today;
+    if (opts.on !== undefined && !isValidDateString(opts.on)) {
+        console.error(`em slice conform: invalid --on date "${opts.on}" — expected YYYY-MM-DD`);
+        process.exit(1);
+    }
+    const result = runSliceConform(model, refs, dirname(file), sliceKey, opts.at, on, opts.skipFindingsCheck === true);
+    if (!result.ok) {
+        console.error(`em slice conform: ${result.message}`);
+        process.exit(1);
+    }
+    if (result.skippedFindingsCheck !== null) {
+        console.error(`notice: --skip-findings-check — certifying "${sliceKey}" with ${result.skippedFindingsCheck.length} ` +
+            `unruled conformance finding(s) still in scope (id ${result.skippedFindingsCheck.join(", ")})`);
+    }
+    console.log(result.changed
+        ? `certified: ${result.path} (conformedVersion: ${result.version}, conformedAt: ${opts.at}, conformedOn: ${on})`
+        : `already certified (no-op): ${result.path}`);
 });
 program
     .command("changelog")
@@ -673,23 +796,45 @@ program
     }
 });
 const STATE_DIR_HELP = "model directory containing .event-modeling.md, or a direct path to that file (default: current directory)";
-/** Shared by every `em state` writer: load, apply the pure patch, write, report — the only
- *  difference between set-phase/set-conformance/set-review is which `mutate` closure they pass. */
-function writeStateUpdate(dirOrFile, cmdLabel, mutate) {
+/** Shared by every `em state` writer: load, apply the pure patch, stamp `Em version:` to the
+ *  running em (MIL-219 ruling A — every state-file writer refreshes it, since each is already
+ *  rewriting the file), write, report — the only difference between set-phase/set-conformance/
+ *  set-review/set-model-version is which `mutate` closure they pass. `today` defaults to
+ *  `localIsoDate()`; a caller that also needs to stamp a SECOND artifact (MIL-218: `em state
+ *  set-conformance`'s model-version certify step) with the exact same date passes it in
+ *  explicitly, computed once, rather than each call independently reading the clock and risking
+ *  a midnight-rollover mismatch between the two. The `Em version:` stamp is best-effort — a
+ *  failure there (should never happen: `Model file:` is one of the six bullets a successful
+ *  `loadStateFile`+`mutate` already proves is present) falls back to `mutate`'s own output rather
+ *  than losing the write the caller actually asked for. */
+function writeStateUpdate(dirOrFile, cmdLabel, mutate, today = localIsoDate()) {
     const loaded = loadStateFile(dirOrFile);
     if (!loaded.ok) {
         console.error(loaded.message);
         process.exit(1);
     }
-    const today = localIsoDate();
     const result = mutate(loaded.text, today);
     if (!result.ok) {
         console.error(`${cmdLabel}: ${result.message}`);
         process.exit(1);
     }
-    writeFileSync(loaded.path, result.text);
+    const stamped = setEmVersion(result.text, PKG_VERSION, today);
+    writeFileSync(loaded.path, stamped.ok ? stamped.text : result.text);
     console.log(`wrote ${loaded.path}`);
 }
+/** MIL-218 ruling C: the one-line advisory `em slice ratify`/`reratify` print when the write
+ *  they just made pushed the slice-version vector (or, in principle, the `.em` content hash —
+ *  never true for these two commands, which only ever edit a slice doc's frontmatter, but
+ *  checked anyway so this helper stays the one true predicate) past the last bumped design
+ *  version. Silent when no manifest exists at all (`drift.current === null`) — a repo that
+ *  never bumped a design version has nothing to be stale against, same silence
+ *  `model-version-stale` (rules.ts) holds. Never refuses; advisory only. */
+function warnModelVersionDrift(baseDir, model, refs, source, cmdLabel) {
+    const drift = modelVersionDrift(baseDir, model, refs, source);
+    if (drift.current === null || (!drift.hashChanged && drift.slicesChanged.length === 0))
+        return;
+    console.error(`warn: ${cmdLabel} moved the model past v${drift.current} — run \`em model version bump\` to record it`);
+}
 const state = program
     .command("state")
     .description("read/write the state file's mechanical fields deterministically (see docs/cli.md)");
@@ -725,12 +870,95 @@ state
 });
 state
     .command("set-conformance")
-    .description("rewrite Last conformance: (and Last updated:) in the exact format reference/conform.md parses")
+    .description("rewrite Last conformance: (and Last updated:) in the exact format reference/conform.md " +
+    "parses. Refuses (MIL-214) while any `implemented` slice has an unruled conformance " +
+    "finding in the findings JSON beside --report (a `slice: null` finding blocks every " +
+    "slice); --partial records the marker with a ` (partial)` suffix instead, with a loud " +
+    "notice. Without a findings JSON beside --report: warns once and records the marker as " +
+    "given (migration path for a report predating `em conform-findings`)")
     .argument("<revision>", "target-repo revision just diffed against")
     .argument("[dir]", STATE_DIR_HELP, ".")
     .requiredOption("--report <path>", "path to the conformance report just written")
+    .option("--partial", "record the marker as PARTIAL even though some in-scope findings are still unruled")
     .action((revision, dir, opts) => {
-    writeStateUpdate(dir, "em state set-conformance", (text, today) => setConformance(text, revision, opts.report, today));
+    const loaded = loadStateFile(dir);
+    if (!loaded.ok) {
+        console.error(loaded.message);
+        process.exit(1);
+    }
+    const parsed = parseState(loaded.text);
+    if (!parsed.ok) {
+        console.error(`em state set-conformance: ${parsed.message}`);
+        process.exit(1);
+    }
+    const modelDir = dirname(loaded.path);
+    const modelFile = join(modelDir, parsed.state.modelPath);
+    // The "in scope" set for the findings gate below — every `implemented` slice, per the
+    // ruling. Best-effort: a model that doesn't exist or doesn't compile cleanly can't tell us
+    // its implemented slices, so the gate is skipped (not refused) in that case rather than
+    // blocking a state-file operation on an unrelated model problem — `em validate` is where
+    // that problem gets its own diagnostic. Also the compiled model MIL-218's certify step
+    // needs below (kept, not just the derived `inScope` set, since certify needs the model/refs
+    // themselves — never re-compiled a second time).
+    let inScope = new Set();
+    let compiledForCertify = null;
+    if (existsSync(modelFile)) {
+        const compiled = compileFile(modelFile);
+        if (!hasErrors(compiled.diagnostics)) {
+            const { facts } = resolveSliceDocFacts(compiled.model, compiled.refs, modelDir);
+            inScope = new Set(facts.filter((f) => f.status === "implemented").map((f) => f.key));
+            compiledForCertify = { model: compiled.model, refs: compiled.refs, source: compiled.source };
+        }
+    }
+    let unruled = [];
+    const lookup = lookupFindingsBesideReport(modelDir, opts.report);
+    if (lookup.kind === "invalid") {
+        console.error(`em state set-conformance: ${lookup.message}`);
+        process.exit(1);
+    }
+    else if (lookup.kind === "absent") {
+        console.error(`warn: no findings JSON found beside ${opts.report} — recording the marker without verifying every ` +
+            "finding is ruled (migration path for a report written before `em conform-findings`)");
+    }
+    else {
+        unruled = unruledFindingsInScope(lookup.doc.findings, inScope);
+    }
+    const partialFlag = opts.partial === true;
+    if (unruled.length > 0 && !partialFlag) {
+        console.error(`em state set-conformance: ${unruled.length} unruled conformance finding(s) among implemented slices ` +
+            `(id ${unruled.map((f) => f.id).join(", ")}) — rule on them (\`em conform-supersede --locus --by\`) or pass --partial`);
+        process.exit(1);
+    }
+    const recordPartial = partialFlag && unruled.length > 0;
+    if (recordPartial) {
+        console.error(`notice: conformance marker recorded as PARTIAL — ${unruled.length} finding(s) unruled`);
+    }
+    const today = localIsoDate();
+    // MIL-218 ruling D: a FULL (non-`--partial`) marker also certifies the current design
+    // version's model-versions/*.json manifest. Checked (and, on success, WRITTEN) before the
+    // `Last conformance:` bullet below — a refusal here (no manifest yet, or the vector has
+    // drifted since it was bumped) must leave the state file untouched, same "refuse before any
+    // write" discipline every other em command holds; never leaves `Last conformance:` updated
+    // with no matching `Certified:` to show for it. Best-effort, same posture as the `inScope`
+    // computation above, for exactly one case: a model that doesn't compile cleanly can't be
+    // certified against, so certification is silently SKIPPED (not a `set-conformance` failure)
+    // rather than blocking the conformance marker on an unrelated model problem — `em validate`
+    // is where that problem gets its own diagnostic.
+    let certifiedVersion = null;
+    if (!recordPartial && compiledForCertify) {
+        const findingsPath = lookup.kind === "found" ? lookup.path : null;
+        const certifyResult = runCertifyModelVersion(modelDir, compiledForCertify.model, compiledForCertify.refs, compiledForCertify.source, revision, today, opts.report, findingsPath);
+        if (!certifyResult.ok) {
+            console.error(`em state set-conformance: ${certifyResult.message}`);
+            process.exit(1);
+        }
+        certifiedVersion = certifyResult.version;
+        console.log(`certified: ${certifyResult.path} (v${certifyResult.version} @ ${revision})`);
+    }
+    writeStateUpdate(dir, "em state set-conformance", (text, t) => setConformance(text, revision, opts.report, t, recordPartial), today);
+    if (certifiedVersion !== null) {
+        writeStateUpdate(dir, "em state set-conformance", (text, t) => setCertified(text, certifiedVersion, revision, t, t), today);
+    }
 });
 state
     .command("set-review")
@@ -767,8 +995,8 @@ state
         process.exit(1);
     }
     const phases = sortUsagePhases(rawPhases);
-    const { model, diagnostics, refs } = compileFile(file);
-    const allDiagnostics = computeAllDiagnostics(file, model, refs, diagnostics);
+    const { model, diagnostics, refs, source } = compileFile(file);
+    const allDiagnostics = computeAllDiagnostics(file, model, refs, diagnostics, source);
     const categorySet = new Set(allDiagnostics.map((d) => RULES[d.code].usageCategory));
     const categories = categorySet.size > 0 ? [...categorySet].sort() : ["none"];
     const loaded = loadStateFile(dirname(file));
@@ -785,6 +1013,67 @@ state
     writeFileSync(loaded.path, result.text);
     console.log(`wrote ${loaded.path} — phases: ${phases.join(", ")} — validate: ${categories.join(", ")}`);
 });
+const model = program.command("model").description("model-level version: design version + certified version (see docs/model-versions.md)");
+const modelVersionCmd = model.command("version").description("bump/inspect the model's design version (MIL-218)");
+modelVersionCmd
+    .command("bump")
+    .description("bump the model's design version: write model-versions/v<N+1>.json (sibling of slices/, " +
+    "conformance/) and rewrite the state file's `Model version:` bullet (MIL-218). Refuses " +
+    "when the state file is missing (run `em scaffold` first), when --by is empty, and when " +
+    "nothing has changed since the current version (same model content hash AND same " +
+    "slice-version vector) unless --force — a no-op bump is the one case --force is right for.")
+    .argument("<file>", "input .em file")
+    .requiredOption("--by <name>", "the bumper's name")
+    .option("--on <date>", "bump date, YYYY-MM-DD (default: today, local date)")
+    .option("--force", "bump even though nothing has changed since the current version")
+    .action((file, opts) => {
+    const baseDir = dirname(file);
+    const loaded = loadStateFile(baseDir);
+    if (!loaded.ok) {
+        console.error(`em model version bump: no state file — run \`em scaffold\` first (${loaded.message})`);
+        process.exit(1);
+    }
+    if (opts.on !== undefined && !isValidDateString(opts.on)) {
+        console.error(`em model version bump: invalid --on date "${opts.on}" — expected YYYY-MM-DD`);
+        process.exit(1);
+    }
+    const today = localIsoDate();
+    const on = opts.on ?? today;
+    const { model: compiledModel, refs, diagnostics, source } = compileFile(file);
+    printDiagnostics(diagnostics);
+    if (hasErrors(diagnostics)) {
+        console.error(`em model version bump: "${file}" has errors — fix them first`);
+        process.exit(1);
+    }
+    const result = runModelVersionBump(baseDir, basename(file), compiledModel, refs, source, opts.by, on, GENERATOR_VERSION, opts.force === true);
+    if (!result.ok) {
+        console.error(`em model version bump: ${result.message}`);
+        process.exit(1);
+    }
+    writeStateUpdate(baseDir, "em model version bump", (text, t) => setModelVersion(text, result.version, t), today);
+    console.log(`bumped: ${result.path} (v${result.version})`);
+});
+modelVersionCmd
+    .command("show")
+    .description("print the model's current design version and the most recently certified version, if any " +
+    "(model-versions/*.json — MIL-218)")
+    .argument("<file>", "input .em file")
+    .option("--json", "print a JSON document instead of text")
+    .action((file, opts) => {
+    const baseDir = dirname(file);
+    const design = latestModelVersionNumber(baseDir);
+    const certifiedFound = findCertifiedVersion(baseDir);
+    const certified = certifiedFound
+        ? { version: certifiedFound.version, at: certifiedFound.certified.at, on: certifiedFound.certified.on }
+        : null;
+    if (opts.json) {
+        console.log(JSON.stringify({ file, design, certified }, null, 2));
+    }
+    else {
+        console.log(`design version: ${design ?? "none"}`);
+        console.log(`certified: ${certified ? `v${certified.version} @ ${certified.at} (${certified.on})` : "never"}`);
+    }
+});
 program
     .command("usage-report")
     .description("aggregate every .event-modeling.md's Usage log under [root] into phase/diagnostic-category " +
@@ -870,12 +1159,17 @@ program
     "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")
+    "doesn't exist. --locus/--by (MIL-214, both required together) additionally record the " +
+    "ruling itself — locus/resolvedBy/resolvedOn — on the findings named by --findings in the " +
+    "sibling conformance/<date>-findings.json, when one exists (warns once and stamps the " +
+    "banner only when it doesn't — the migration path for a report predating em conform-findings)")
     .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, local date)")
+    .option("--locus <locus>", `who/what the named finding(s) say is wrong: ${FINDING_LOCI.join(" | ")} (requires --by)`)
+    .option("--by <name>", "who ruled on the named finding(s) (requires --locus)")
     .action((file, reportPath, opts) => {
     const today = localIsoDate();
     const on = opts.on ?? today;
@@ -883,15 +1177,57 @@ program
         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 ((opts.locus !== undefined) !== (opts.by !== undefined)) {
+        console.error("em conform-supersede: --locus and --by must be given together");
+        process.exit(1);
+    }
+    if (opts.locus !== undefined && !FINDING_LOCI.includes(opts.locus)) {
+        console.error(`em conform-supersede: invalid --locus "${opts.locus}" — expected one of: ${FINDING_LOCI.join(", ")}`);
+        process.exit(1);
+    }
+    const ruling = opts.locus !== undefined && opts.by !== undefined ? { locus: opts.locus, by: opts.by } : undefined;
+    const result = runConformSupersede(dirname(file), reportPath, opts.asOf, opts.findings, on, ruling);
     if (!result.ok) {
         console.error(`em conform-supersede: ${result.message}`);
         process.exit(1);
     }
+    if (result.findingsRuling.kind === "no-findings-file") {
+        console.error(`warn: ${result.findingsRuling.warning}`);
+    }
+    else if (result.findingsRuling.kind === "applied") {
+        console.log(result.findingsRuling.changed
+            ? `ruled: ${result.findingsRuling.path} (finding(s) ${result.findingsRuling.ids.join(", ")} -> locus: ${opts.locus}, by: ${opts.by})`
+            : `already ruled (no-op): ${result.findingsRuling.path}`);
+    }
     console.log(result.changed
         ? `stamped superseded: ${result.path} (as of ${opts.asOf}, findings ${opts.findings}, on ${on})`
         : `already stamped (no-op): ${result.path}`);
 });
+const conformFindings = program.command("conform-findings").description("read-only checks for the conformance findings record (MIL-214)");
+conformFindings
+    .command("check")
+    .description("shape-validate a conformance/<date>-findings.json file (findingsSchemaVersion, required " +
+    "fields, enum values, ids sorted+unique, a ruled finding carries resolvedBy+resolvedOn) — " +
+    "exit 1 on shape errors. The conform skill writes this file directly alongside its report; " +
+    "this is how a headless run verifies what it just wrote.")
+    .argument("<path>", "path to a conformance/<date>-findings.json file")
+    .option("--json", "print a JSON document instead of the text report")
+    .action((path, opts) => {
+    const result = checkFindingsFile(path);
+    if (opts.json) {
+        console.log(buildCheckFindingsJson(result));
+    }
+    else if (result.ok) {
+        console.log(`ok — ${result.path}: ${result.findingsCount} finding(s), shape valid`);
+    }
+    else {
+        console.error(`em conform-findings check: ${result.path} — shape errors:`);
+        for (const e of result.errors)
+            console.error(`  - ${e}`);
+    }
+    if (!result.ok)
+        process.exit(1);
+});
 program
     .command("watch")
     .description("re-render on every save")
@@ -980,8 +1316,8 @@ program
     .option("--json", "print a JSON document instead of text — works on a model WITH errors, unlike `em export` " +
     "(MIL-128, see docs/cli.md); exit codes are unchanged")
     .action((file, opts) => {
-    const { model, diagnostics, refs } = compileFile(file);
-    const allDiagnostics = computeAllDiagnostics(file, model, refs, diagnostics);
+    const { model, diagnostics, refs, source } = compileFile(file);
+    const allDiagnostics = computeAllDiagnostics(file, model, refs, diagnostics, source);
     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
@@ -1265,11 +1601,11 @@ program
     const compiled = [];
     let anyErrors = false;
     for (const file of files) {
-        const { model, refs, diagnostics } = compileFile(file);
+        const { model, refs, diagnostics, source } = compileFile(file);
         printDiagnosticsFor(file, diagnostics);
         if (hasErrors(diagnostics))
             anyErrors = true;
-        compiled.push({ file, model, refs });
+        compiled.push({ file, model, refs, source });
     }
     if (anyErrors) {
         console.error("em status: not reporting status — fix the errors above");
@@ -1326,7 +1662,13 @@ program
         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);
+    // MIL-218: one model-version entry per input file.
+    const modelVersion = compiled.map(({ file, model, refs, source }) => resolveModelVersionStatusEntry(file, model, refs, source));
+    // MIL-219: one em-version entry per input file whose state file resolved.
+    const emVersion = compiled
+        .map(({ file }) => resolveEmVersionStatusEntry(file, PKG_VERSION))
+        .filter((e) => e !== null);
+    const report = buildStatusReport(files, sliceFacts, openIssuesCount, invariants, conformance, statusDiagnostics, modelVersion, emVersion);
     let output;
     if (opts.json)
         output = buildStatusJson(report);
@@ -1371,6 +1713,32 @@ program
         console.log(formatConformancePart(entry));
     }
 });
+program
+    .command("metrics")
+    .description("the pilot metrics named in advance by the register, computed from git history alone " +
+    "(MIL-170): ratification turnaround (reviewed -> ratified -> implemented), conform-cycle " +
+    "cadence + finding counts, and status-vs-reality disagreement over time — plus a fourth, " +
+    "reported as not computable from history (see docs/usage-data.md). `<file>` is an anchor " +
+    ".em file, used only to locate slices/, conformance/, and .event-modeling.md relative to " +
+    "it — same convention as em ledger; never parsed or compiled")
+    .argument("<file>", "anchor .em file")
+    .requiredOption("--from <rev>", "baseline revision")
+    .option("--to <rev>", "compare revision (default: HEAD)")
+    .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
+    .action((file, opts) => {
+    const to = opts.to ?? "HEAD";
+    const computed = computeMetrics(file, opts.from, to);
+    if (!computed.ok) {
+        console.error(computed.message);
+        process.exit(1);
+    }
+    if (opts.json) {
+        process.stdout.write(buildMetricsJson(computed.result) + "\n");
+    }
+    else {
+        console.log(formatMetricsText(computed.result));
+    }
+});
 // `em query` (MIL-168): deterministic graph queries over the compiled model — scoped, token-
 // cheap answers instead of a whole-model `em export`. Compiles every input file through the
 // LIGHTER query sub-pipeline (query/pipeline.ts: parse -> normalize -> refs -> validate against
@@ -1721,6 +2089,18 @@ skill
             console.log(f.message);
         console.log(result.ok ? `ok — vendored skill matches em ${PKG_VERSION}` : `${result.findings.length} mismatch(es)`);
     }
+    // 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
+    // one, is silently skipped; that's `em upgrade`'s own hard-incompatibility case to report,
+    // not this command's). Always stderr, independent of --json/exit code — advisory only, and
+    // this command's own exit code stays about skill-bundle drift, never about this.
+    const loaded = loadStateFile(resolve(path));
+    if (loaded.ok) {
+        const parsed = parseState(loaded.text);
+        if (parsed.ok && isOlder(parsed.state.emVersion, PKG_VERSION)) {
+            console.error(`warn: recorded Em version (${parsed.state.emVersion}) is behind installed em (${PKG_VERSION}) — run \`em upgrade\``);
+        }
+    }
     // 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)
@@ -1796,6 +2176,105 @@ ci.command("init")
             console.log(`${path} already up to date`);
     }
 });
+program
+    .command("upgrade")
+    .description("bring a model repo authored under an older em (1.6 forward) up to the installed version: " +
+    "an ordered list of mechanical steps (skill bundle, reaction shape, state-file bullets, " +
+    "generated CI blocks, constitution scaffold) plus a human list of things no command can " +
+    "safely decide by itself (MIL-219, see docs/upgrading.md). Dry-run by default; --apply " +
+    "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("--json", "print a JSON document instead of text (dry-run/--check only, never with --apply)")
+    .action((file, opts) => {
+    if (opts.apply && opts.check) {
+        console.error("em upgrade: --apply and --check are mutually exclusive");
+        process.exit(1);
+    }
+    const { model, refs, diagnostics, source } = compileFile(file);
+    printDiagnostics(diagnostics);
+    // Deliberately does NOT refuse on hasErrors(diagnostics), unlike every other command that
+    // compiles a model first: the old pre-1.7.1 two-slice reaction shape `reaction-shape`
+    // migrates is itself a validation ERROR under the current rules (MIL-120 changed what
+    // `em validate` accepts) — refusing here would make that step, and the `predates-1.6` human
+    // item, unreachable for exactly the repos that need them. Every step/human-detector either
+    // reads the raw source directly (reaction-shape/predates-1.6, via planMigration) or a
+    // best-effort compiled model that's still structurally usable even with validation errors
+    // present (compile() never throws for a semantic error, only a parse error — already
+    // handled by compileFile() above).
+    if (hasErrors(diagnostics)) {
+        console.error(`em upgrade: "${file}" has validation errors — proceeding anyway (this is often exactly what needs upgrading)`);
+    }
+    void source; // compileFile's own source read; steps re-read from disk themselves (module header)
+    const baseDir = dirname(file);
+    const repoRootResult = resolveRepoRoot(baseDir);
+    if (!repoRootResult.ok) {
+        console.error(repoRootResult.message);
+        process.exit(1);
+    }
+    const ctx = {
+        modelFile: file,
+        baseDir,
+        repoRoot: repoRootResult.repoRoot,
+        installedVersion: PKG_VERSION,
+        packagedSkillsRoot: packagedSkillsRoot(),
+        model,
+        refs,
+    };
+    if (opts.check) {
+        const { ok, report } = 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");
+        if (!ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (opts.apply) {
+        const result = applyUpgrade(ctx);
+        for (const s of result.applied) {
+            if (s.applied)
+                console.log(`applied: ${s.id} — ${s.changedFiles.join(", ")} (${s.commit})`);
+            else
+                console.log(`skipped: ${s.id}`);
+        }
+        if (!result.ok) {
+            console.error(result.message);
+            process.exit(1);
+        }
+        if (result.emVersionCommit)
+            console.log(`recorded: ${result.emVersionCommit}`);
+        else
+            console.log("Em version: already up to date — no commit needed");
+        for (const h of result.report.human)
+            console.log(`human: ${h.id}: ${h.reason}`);
+        return;
+    }
+    const report = detectUpgrade(ctx);
+    if (opts.json) {
+        console.log(buildUpgradeJson(file, report));
+        return;
+    }
+    console.log(`em upgrade: from ${report.from.version}${report.from.inferred ? ` (inferred: ${report.from.basis})` : ""} → to ${report.to}`);
+    if (report.stateFileError)
+        console.log(`state file: ${report.stateFileError}`);
+    console.log("Steps:");
+    for (const s of report.steps) {
+        console.log(`  [${s.applicable ? "x" : " "}] ${s.id} (since ${s.sinceVersion}): ${s.reason}`);
+    }
+    console.log("Human:");
+    if (report.human.length === 0)
+        console.log("  (none)");
+    for (const h of report.human)
+        console.log(`  ${h.id}: ${h.reason}`);
+    const applicableCount = report.steps.filter((s) => s.applicable).length;
+    console.log(`${applicableCount} step(s) applicable, ${report.human.length} human item(s) — re-run with --apply to apply mechanical steps`);
+});
 // 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
@@ -1838,15 +2317,17 @@ function compileFile(file, opts = {},
     }
 }
 /** 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) {
+ *  (MIL-126), doc↔model consistency (MIL-124), orphaned slice docs (MIL-183), and model-version
+ *  staleness (MIL-218) are `em validate`'s fs-aware rules — every other diagnostic in
+ *  `diagnostics` (from `compileFile`) is a pure function of the .em source. All six read
+ *  `slices/*.md`/`model-versions/*.json` alongside the model. Doc↔model consistency,
+ *  orphaned-slice-doc, and model-version-stale are deliberately validate-only (unlike
+ *  note-binding, which `em render` also folds in) — all three 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. `source` is the `.em` file's
+ *  own text — only `validateModelVersionStale` reads it (the modelHash comparison). */
+function computeAllDiagnostics(file, model, refs, diagnostics, source) {
     return [
         ...diagnostics,
         ...validateLineage(model, refs, dirname(file)),
@@ -1854,6 +2335,7 @@ function computeAllDiagnostics(file, model, refs, diagnostics) {
         ...validateNoteBindings(model, refs, dirname(file)),
         ...validateDocModelConsistency(model, refs, dirname(file)),
         ...validateOrphanedSliceDocs(model, refs, dirname(file)),
+        ...validateModelVersionStale(model, refs, dirname(file), source),
     ];
 }
 /** Read a file's text, or exit with a clear error — shared by `em diff` (both forms) and
@@ -1953,16 +2435,22 @@ function printDivergences(model) {
         console.log(`  divergence :${el.line} slice "${slice.name}" ${el.kind} "${el.name}": ${el.divergence}`);
     }
 }
-/** Print only elements marked `public`: slice, kind, name, line — for an integration-surface audit. */
+/** Print only elements marked `public`: slice, kind, name, line — for an integration-surface
+ *  audit. A `public` view also gets a "(no in-model reader)" note (MIL-215) when no `ui`/
+ *  reaction anywhere on its timeline reads it — an audit hint, not a warning: a genuinely
+ *  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"));
     if (pub.length === 0) {
         console.log("no public elements");
         return;
     }
+    const noReader = publicViewsWithoutInModelReader(model);
     for (const el of pub) {
         const slice = model.slices[el.sliceIndex];
-        console.log(`  public :${el.line} slice "${slice.name}" ${el.kind} "${el.name}"`);
+        const note = el.kind === "view" && noReader.has(el.logicalId) ? " (no in-model reader)" : "";
+        console.log(`  public :${el.line} slice "${slice.name}" ${el.kind} "${el.name}"${note}`);
     }
 }
 /** Diagnostics in `all` not already present (by reference identity) in `already` — avoids