@milehimikey/em 1.19.6 → 1.20.0

package/dist/cli/watchStoryline.js

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MIT
+// Testable core of `em watch --serve --storyline <name>` (GH #309, deferred from #277):
+// resolving the --storyline argument against the model (the exact same resolution `em render
+// --storyline` and `em engagement`'s own `--storyline` selector use — findStoryline, GH #348's
+// case/whitespace-insensitive match) and the live viewer's storyline-picker entries. Factored
+// out of cli.ts's `watch` action, which starts a long-running file watcher and isn't itself
+// unit-testable, mirroring src/cli/render-inputs.ts's existing split for `em render`'s own
+// `--slice`/`--storyline`.
+import { kebabSlug } from "../util/slug.js";
+import { findStoryline } from "../model/storylines.js";
+/** Flat (no subdirectory) filename for a storyline's live-serve subset SVG, written alongside
+ *  the full model's own output file. Flat, unlike `em render --storyline`'s `storylines/`
+ *  convention, because the live viewer's `?svg=` allowlist (serve.ts / viewer.html) accepts a
+ *  bare filename only — never a path with a separator. */
+export function storylineFileFor(name) {
+    return `storyline-${kebabSlug(name)}.svg`;
+}
+/** The live viewer's storyline-picker entries (GH #309): "Full model" plus one per declared
+ *  storyline, `current` marking whichever file THIS render is — so the same list, computed
+ *  once per build, embeds into every output file with only `current` differing. `[]` (no
+ *  picker) when the model declares none. */
+export function storylineVariants(model, outFile, currentFile) {
+    const declared = model.storylines ?? [];
+    if (declared.length === 0)
+        return [];
+    return [
+        { name: "Full model", file: outFile, current: currentFile === outFile },
+        ...declared.map((st) => {
+            const file = storylineFileFor(st.name);
+            return { name: st.name, file, current: currentFile === file };
+        }),
+    ];
+}
+/** Resolve `--storyline <name>` against the model — `{ none: true }` when the flag wasn't
+ *  given at all. Same validation `em render --storyline` reports on an unknown name: lists
+ *  every declared storyline, so a typo is correctable without opening the .em file. Uses
+ *  findStoryline directly (not render/storylineDiagram.ts's resolveStorylineArg) only because
+ *  that helper's error text is hardcoded to "em render --storyline" — the lookup itself (GH
+ *  #348's case/whitespace-insensitive match) is the one `em render`, `em engagement
+ *  --storyline` and this all share; this is not a second resolution. */
+export function resolveWatchStoryline(model, name) {
+    if (name === undefined)
+        return { none: true };
+    const storyline = findStoryline(model, name);
+    if (storyline)
+        return { storyline };
+    const declared = model.storylines ?? [];
+    const known = declared.map((s) => `"${s.name}"`).join(", ");
+    return {
+        error: declared.length === 0
+            ? `em watch --storyline: this model declares no storylines`
+            : `em watch --storyline: no storyline "${name}" (declared: ${known})`,
+    };
+}
+//# sourceMappingURL=watchStoryline.js.map

package/dist/cli/watchStoryline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchStoryline.js","sourceRoot":"","sources":["../../src/cli/watchStoryline.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,wFAAwF;AACxF,6FAA6F;AAC7F,+FAA+F;AAC/F,8FAA8F;AAC9F,4FAA4F;AAC5F,2FAA2F;AAC3F,2BAA2B;AAG3B,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD;;;0DAG0D;AAC1D,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,aAAa,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;AAC5C,CAAC;AAED;;;4CAG4C;AAC5C,MAAM,UAAU,iBAAiB,CAAC,KAAsB,EAAE,OAAe,EAAE,WAAmB;IAC5F,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC;IACxC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,OAAO;QACL,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,EAAE;QACvE,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE;YACrB,MAAM,IAAI,GAAG,gBAAgB,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YACvC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,EAAE,CAAC;QAChE,CAAC,CAAC;KACH,CAAC;AACJ,CAAC;AAID;;;;;;wEAMwE;AACxE,MAAM,UAAU,qBAAqB,CAAC,KAAsB,EAAE,IAAwB;IACpF,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC9C,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC7C,IAAI,SAAS;QAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC;IACxC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5D,OAAO;QACL,KAAK,EACH,QAAQ,CAAC,MAAM,KAAK,CAAC;YACnB,CAAC,CAAC,yDAAyD;YAC3D,CAAC,CAAC,uCAAuC,IAAI,gBAAgB,KAAK,GAAG;KAC1E,CAAC;AACJ,CAAC"}

package/dist/cli.js

@@ -14,11 +14,14 @@ import { renderDot, layoutDot, composeSvg, writeRendered, formatFromPath } from
 import { buildSliceDiagram } from "./render/sliceDiagram.js";
 import { resolveSliceArg, defaultSliceOut, defaultStorylineOut } from "./cli/render-inputs.js";
 import { buildStorylineDiagram, resolveStorylineArg } from "./render/storylineDiagram.js";
+import { embedStorylinePicker } from "./render/storylinePicker.js";
+import { resolveWatchStoryline, storylineFileFor, storylineVariants } from "./cli/watchStoryline.js";
 import { resolveSliceKey } from "./model/resolveSlice.js";
 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 { buildDocJsonExport } from "./emit/docJson.js";
 import { generateContract, runApiCheck, formatApiCheckText } from "./cli/api.js";
 import { buildApiCheckJson } from "./emit/apiCheckJson.js";
 import { buildValidateJson, buildShapeJson, buildSliceReadyJson, buildValidateListJson, collectMarkers } from "./emit/validateJson.js";
@@ -50,7 +53,7 @@ import { planMigration, verifyMigration } from "./cli/migrateReactionShape.js";
 import { buildLedgerJson } from "./emit/ledgerJson.js";
 import { buildRefsJson } from "./emit/refsJson.js";
 import { buildShapeReport, formatShapeText } from "./cli/shape.js";
-import { applyRefWaivers, checkRefs, readWaiveFile } from "./cli/refsCheck.js";
+import { applyRefWaivers, checkRatificationOrder, checkRefs, readWaiveFile } from "./cli/refsCheck.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";
@@ -89,9 +92,9 @@ import { listModelCommits } from "./cli/changelog-git.js";
 import { buildChangelogDoc } from "./cli/changelogBuild.js";
 import { runRevise } from "./cli/revise.js";
 import { runDefer, runDeferFromIssue } from "./cli/defer.js";
-import { runSliceConform } from "./cli/sliceConform.js";
+import { runSliceConform, runSliceConformPreview, writePreviewFindings, resolveFindingsForReport, findingsFilesOf, unruledAcrossFiles, } from "./cli/sliceConform.js";
 import { checkPrdTriage, buildCheckPrdTriageJson, renderPrdTriageMarkdown, validatePrdTriage } from "./cli/prdTriage.js";
-import { checkFindingsFile, buildCheckFindingsJson, lookupFindingsBesideReport, unruledFindingsInScope, FINDING_LOCI } from "./cli/findings.js";
+import { checkFindingsFile, buildCheckFindingsJson, 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";
@@ -283,9 +286,35 @@ program
     .option("--slice <key>", "export only this slice's object (pattern/fields/doc) instead of the whole model (export " +
     "key, MIL-128) — refuses only if THIS slice has an error; an unrelated slice's breakage " +
     "elsewhere in the model doesn't block it (see docs/cli.md)")
+    .option("--doc-json", "emit the structured slice-doc export (GH #401) instead of the model snapshot: per slice the " +
+    "frontmatter join plus the parsed sections as data (fields, invariants, scenarios, error " +
+    "flows, open questions) and a model-level invariant catalog. Own schema version; whole " +
+    "model only (does not combine with --slice)")
+    .option("--include-html", "with --doc-json, include each slice doc's rendered HTML body (excluded by default; the " +
+    "authored body never appears in a plain export)")
     .action((file, opts) => {
     const { model, refs, diagnostics, source } = compileFile(file);
     printDiagnostics(diagnostics);
+    if (opts.docJson) {
+        if (opts.slice) {
+            console.error("em export --doc-json: exports the whole model and does not combine with --slice");
+            process.exit(1);
+        }
+        if (hasErrors(diagnostics)) {
+            console.error("not exporting: fix the errors above");
+            process.exit(1);
+        }
+        const exportedDoc = buildDocJsonExport(model, refs, diagnostics, source, file, { includeHtml: opts.includeHtml });
+        printDiagnostics(newDiagnostics(exportedDoc.diagnostics, diagnostics));
+        if (opts.out) {
+            writeFileSync(opts.out, exportedDoc.text + "\n");
+            console.log(`wrote ${opts.out}`);
+        }
+        else {
+            process.stdout.write(exportedDoc.text + "\n");
+        }
+        return;
+    }
     if (opts.slice) {
         // Scoped export deliberately does NOT reuse the whole-model error guard below: the
         // ticket's own motivation for `--slice` is an agent implementing one already-ratified
@@ -1088,7 +1117,10 @@ slice
     "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 " +
     "conformance/<date>[-<name>]-findings.json file matching --at still has an unruled finding in scope " +
-    "for this slice; --skip-findings-check overrides with a loud notice.")
+    "for this slice; --skip-findings-check overrides with a loud notice. GH #400: --preview runs the " +
+    "same doc-resolution and findings-check read for a slice that hasn't shipped yet — the shipped/" +
+    "implementedIn gates are waived and NOTHING is ever written to the doc; output is ephemeral " +
+    "(text or --json) unless --write-findings opts into persisting a normal findings file.")
     .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 — or, when what was exercised is not a commit " +
@@ -1096,12 +1128,31 @@ slice
     "`<kind>:<id>` such as build:1234 or deploy:eu-1-2026-10-15 (GH #261); recorded verbatim, skipped by git-reachability checks")
     .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")
+    .option("--preview", "GH #400: pre-ship advisory mode — waives the shipped-status/`implementedIn:` gates, writes NOTHING to the " +
+    "doc (no conformedVersion/conformedAt/conformedOn, ever); ephemeral by default, --write-findings opts " +
+    "into persisting a normal findings file. --skip-findings-check has no effect in this mode (preview " +
+    "never refuses on findings)")
+    .option("--write-findings", "with --preview: persist the preview's own unruled findings as conformance/<on>-<slice-key>-preview-findings.json")
+    .option("--json", "with --preview: print a JSON document instead of the text report")
     .action((file, sliceKey, opts) => {
+    if (opts.writeFindings === true && opts.preview !== true) {
+        console.error("em slice conform: --write-findings only applies with --preview");
+        process.exit(1);
+    }
+    if (opts.json === true && opts.preview !== true) {
+        console.error("em slice conform: --json only applies with --preview");
+        process.exit(1);
+    }
+    if (opts.preview === true && opts.skipFindingsCheck === true) {
+        console.error("em slice conform: --skip-findings-check has no effect with --preview (preview never blocks on findings)");
+        process.exit(1);
+    }
     const { model, refs, diagnostics } = compileFile(file);
     printDiagnostics(diagnostics);
     sliceKey = resolveSliceOrExit("em slice conform", model, refs, sliceKey);
     // Scoped the same way `em slice ratify`/`em slice revise`/`em slice mark-implemented` are:
-    // only an error concerning THIS slice refuses.
+    // only an error concerning THIS slice refuses. Not waived by --preview — an erroring model
+    // isn't a fact worth previewing against either.
     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`);
@@ -1113,6 +1164,44 @@ slice
         console.error(`em slice conform: invalid --on date "${opts.on}" — expected YYYY-MM-DD`);
         process.exit(1);
     }
+    if (opts.preview === true) {
+        const baseDir = dirname(file);
+        const result = runSliceConformPreview(model, refs, baseDir, sliceKey, opts.at);
+        if (!result.ok) {
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, message: result.message }, null, 2));
+            }
+            else {
+                console.error(`em slice conform --preview: ${result.message}`);
+            }
+            process.exit(1);
+        }
+        const writtenTo = opts.writeFindings === true ? writePreviewFindings(baseDir, file, sliceKey, result.at, on, result.unruledFindings) : null;
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                preview: true,
+                slice: sliceKey,
+                path: result.path,
+                status: result.status,
+                version: result.version,
+                at: result.at,
+                findingsFiles: result.findingsFiles,
+                unruledFindings: result.unruledFindings,
+                writtenTo,
+            }, null, 2));
+        }
+        else {
+            const findingsNote = result.unruledFindings.length === 0
+                ? result.findingsFiles.length === 0
+                    ? `no conformance findings file matches --at ${result.at} (conformance/<date>[-<name>]-findings.json with that revision)`
+                    : `no unruled conformance findings in scope (checked: ${result.findingsFiles.join(", ")})`
+                : `${result.unruledFindings.length} unruled conformance finding(s) in scope (id ${result.unruledFindings.map((f) => f.id).join(", ")}) in ${result.findingsFiles.join(", ")}`;
+            console.log(`preview: ${result.path} (status: ${result.status ?? "(empty)"}) @ ${result.at} — ${findingsNote}`);
+            console.log(writtenTo !== null ? `wrote: ${writtenTo}` : "ephemeral — nothing written; pass --write-findings to persist a snapshot");
+        }
+        return;
+    }
     const result = runSliceConform(model, refs, dirname(file), sliceKey, opts.at, on, opts.skipFindingsCheck === true);
     if (!result.ok) {
         console.error(`em slice conform: ${result.message}`);
@@ -1228,9 +1317,10 @@ state
     .command("set-conformance")
     .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 " +
+    "finding in the findings JSON beside --report, or, when that is absent, in every findings " +
+    "file at the report's own revision (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 " +
+    "notice. Without a findings JSON beside --report and none at the report's revision: 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, ".")
@@ -1266,28 +1356,31 @@ state
             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}`);
+    let unruledTotal = 0;
+    let unruledDescribe = "";
+    const resolved = resolveFindingsForReport(modelDir, opts.report, revision);
+    if (resolved.kind === "invalid") {
+        console.error(`em state set-conformance: ${resolved.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 ` +
+    else if (resolved.kind === "none") {
+        console.error(`warn: no findings JSON found beside ${opts.report} (and no same-revision file) — 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 counted = unruledAcrossFiles(findingsFilesOf(resolved), inScope);
+        unruledTotal = counted.total;
+        unruledDescribe = counted.describe;
     }
     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`);
+    if (unruledTotal > 0 && !partialFlag) {
+        console.error(`em state set-conformance: ${unruledTotal} unruled conformance finding(s) among implemented slices ` +
+            `in ${unruledDescribe} — rule on them (\`em conform-supersede --locus --by\`) or pass --partial`);
         process.exit(1);
     }
-    const recordPartial = partialFlag && unruled.length > 0;
+    const recordPartial = partialFlag && unruledTotal > 0;
     if (recordPartial) {
-        console.error(`notice: conformance marker recorded as PARTIAL — ${unruled.length} finding(s) unruled`);
+        console.error(`notice: conformance marker recorded as PARTIAL — ${unruledTotal} finding(s) unruled`);
     }
     const today = localIsoDate();
     // MIL-218 ruling D: a FULL (non-`--partial`) marker also certifies the current design
@@ -1302,7 +1395,8 @@ state
     // is where that problem gets its own diagnostic.
     let certifiedVersion = null;
     if (!recordPartial && compiledForCertify) {
-        const findingsPath = lookup.kind === "found" ? lookup.path : null;
+        const readFiles = findingsFilesOf(resolved);
+        const findingsPath = readFiles ? readFiles.map((f) => f.path).join(", ") : 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}`);
@@ -1517,7 +1611,8 @@ program
     "report; idempotent on the same --as-of/--findings/--on stamp; refuses if the report " +
     "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 " +
+    "sibling conformance/<date>-findings.json, when one exists (refuses, naming them, when only " +
+    "other findings files exist at the report's revision; 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")
@@ -1632,10 +1727,24 @@ program
     .option("--keep-empty-lanes", "keep the API lane even when empty")
     .option("--serve", "serve a live viewer with instant push-reload (no polling)")
     .option("--port <n>", "port for --serve (default 5173)", (v) => parseInt(v, 10))
+    .option("--storyline <name>", "GH #309 (deferred from #277): filter the live view to one storyline's subset — the same " +
+    "subset `em render --storyline` draws (its own slices in order, plus dimmed stub columns " +
+    "for what they read from outside it and the `after` end state). Whenever the model " +
+    "declares any storylines the viewer also offers a picker to switch to the full model or " +
+    "another declared storyline, live, without restarting. An unknown name errors, listing " +
+    "the declared storylines; requires --serve")
     .action(async (file, opts) => {
     const out = opts.out ?? defaultOut(file, opts.format ?? "svg");
     const fmt = opts.format ?? formatFromPath(out);
+    if (opts.storyline !== undefined && !opts.serve) {
+        console.error("em watch: --storyline applies only with --serve");
+        process.exit(1);
+    }
     let server;
+    // The file the printed live-view URL points at — basename(out) (the full model) unless
+    // --storyline resolves, in which case build() below points it at that storyline's own
+    // subset file instead (GH #309).
+    let liveFile = basename(out);
     // serializeBuilds: chokidar can fire several events for one save (and an
     // editor's write can land while a slow png/pdf render is still in flight) —
     // overlapping builds would race each other writing the same output file.
@@ -1656,7 +1765,40 @@ program
                 server?.notifyError(first ? formatDiagnostic(first).trim() : "model has errors — see terminal");
                 return;
             }
-            await renderDot(dot, model, grid, out, fmt, dirname(file));
+            // GH #309: --storyline is validated on every build, same as `em render --storyline`
+            // (resolveWatchStoryline shares findStoryline's resolution) — a save that renames or
+            // drops the storyline must not kill the watcher.
+            const resolved = resolveWatchStoryline(model, opts.storyline);
+            if ("error" in resolved) {
+                console.error(resolved.error);
+                server?.notifyError(resolved.error);
+                return;
+            }
+            if (opts.serve && fmt === "svg") {
+                const baseDir = dirname(file);
+                const outDir = dirname(out);
+                const outFile = basename(out);
+                liveFile = "storyline" in resolved ? storylineFileFor(resolved.storyline.name) : outFile;
+                // The full model, always rendered to `out` (unchanged default) — carries the
+                // storyline-picker metadata (a no-op when the model declares none) so the viewer can
+                // offer it regardless of whether --storyline was passed.
+                const fullRaw = await layoutDot(dot);
+                const fullSvg = embedStorylinePicker(composeSvg(fullRaw, model, grid, baseDir, outDir), storylineVariants(model, outFile, liveFile));
+                await writeRendered(fullSvg, out, "svg");
+                // Every declared storyline's own subset (GH #277's `em render --storyline` subset,
+                // reused verbatim) — rendered alongside the full model on every build, independent of
+                // --storyline, so the viewer's picker always has somewhere to navigate to.
+                for (const st of model.storylines ?? []) {
+                    const sub = buildStorylineDiagram(model, st, { keepEmptyLanes: opts.keepEmptyLanes });
+                    const subFile = storylineFileFor(st.name);
+                    const subRaw = await layoutDot(sub.dot);
+                    const subSvg = embedStorylinePicker(composeSvg(subRaw, sub.model, sub.grid, baseDir, outDir), storylineVariants(model, outFile, subFile));
+                    await writeRendered(subSvg, join(outDir, subFile), "svg");
+                }
+            }
+            else {
+                await renderDot(dot, model, grid, out, fmt, dirname(file));
+            }
             console.log(`rendered ${out} (${Date.now() - started}ms)`);
             server?.notify();
         }
@@ -1674,7 +1816,7 @@ program
             // The viewer inlines SVG only — for png/pdf watches there's nothing
             // live to embed, so don't print a ?svg= URL that can't work.
             if (fmt === "svg") {
-                console.log(`→ live view: ${server.url}/?svg=${encodeURIComponent(basename(out))}`);
+                console.log(`→ live view: ${server.url}/?svg=${encodeURIComponent(liveFile)}`);
                 console.log("  open it in a browser and share your screen");
             }
             else {
@@ -1932,6 +2074,10 @@ program
     .requiredOption("--reachable-from <rev>", "the branch or commit every ref must be an ancestor of (e.g. origin/main)")
     .option("--waive <slice-key>", "excuse this slice's non-ancestor/unresolved/undecidable results from the exit code (repeatable); still reported", (value, previous) => [...previous, value], [])
     .option("--waive-file <path>", "a baseline file of slice keys to waive, one per line (`#` comments allowed); missing file = no waivers")
+    .option("--check-order", "advisory-only (GH #399): for every slice doc with a ratifiedRef, report whether a commit between the branch's " +
+    "fork point and ratifiedRef already touched code other than the doc itself — a retrofit signal for inline " +
+    "ratification (spec written to describe code that already exists). History is rewritable, so this NEVER " +
+    "affects the exit code or `ok`, and is never a validate gate — see docs/process.md's inline-ratification section")
     .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
     .action((file, opts) => {
     const { model, refs } = compileFile(file);
@@ -1947,8 +2093,11 @@ program
     }
     if (result.shallow)
         console.error("warn: shallow clone — every ref is undecidable; check out with fetch-depth: 0");
+    // GH #399: computed only with --check-order, and never folded into `result`/`result.ok` —
+    // it is a sibling report, not a new ref field, and must never move the exit code (R5).
+    const orderResults = opts.checkOrder ? checkRatificationOrder(model, refs, dirname(file), result.target, result.shallow) : null;
     if (opts.json) {
-        process.stdout.write(buildRefsJson(result, file) + "\n");
+        process.stdout.write(buildRefsJson(result, file, orderResults) + "\n");
     }
     else {
         for (const r of result.results) {
@@ -1965,8 +2114,19 @@ program
         else {
             console.log(`${bad} ref(s) not reachable from ${opts.reachableFrom} (${result.checkedRefs} checked on ${result.checkedDocs} doc(s)${waivedNote})`);
         }
+        if (orderResults) {
+            console.log("");
+            console.log("ratification order (advisory — never affects exit code):");
+            if (orderResults.length === 0) {
+                console.log("  no slice doc carries a ratifiedRef to check");
+            }
+            for (const o of orderResults) {
+                console.log(`  ${o.status.padEnd(23)} ${o.sliceKey} ratifiedRef: ${o.ratifiedRef}${o.detail ? ` — ${o.detail}` : ""}`);
+            }
+        }
     }
     // Set the code rather than process.exit(): stdout to a pipe shouldn't risk truncation.
+    // `orderResults` never participates — advisory only, per R5.
     if (!result.ok)
         process.exitCode = 1;
 });