@milehimikey/em 1.17.0 → 1.18.1

package/dist/cli.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from "node:fs";
 import { cp, mkdir } from "node:fs/promises";
-import { basename, dirname, extname, join, resolve } from "node:path";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { compile } from "./pipeline.js";
@@ -12,7 +12,8 @@ import { continuationOf } from "./model/continuation.js";
 import { ParseError } from "./parser/parser.js";
 import { renderDot, layoutDot, composeSvg, writeRendered, formatFromPath } from "./render/render.js";
 import { buildSliceDiagram } from "./render/sliceDiagram.js";
-import { resolveSliceArg, defaultSliceOut } from "./cli/render-inputs.js";
+import { resolveSliceArg, defaultSliceOut, defaultStorylineOut } from "./cli/render-inputs.js";
+import { buildStorylineDiagram, resolveStorylineArg } from "./render/storylineDiagram.js";
 import { resolveSliceKey } from "./model/resolveSlice.js";
 import { serializeBuilds, watchFile } from "./render/watch.js";
 import { startLiveServer } from "./render/serve.js";
@@ -20,7 +21,7 @@ import { formatDiagnostic, hasErrors, publicViewsWithoutInModelReader } from "./
 import { buildExport, buildSliceExport, GENERATOR_VERSION } from "./emit/json.js";
 import { generateContract, runApiCheck, formatApiCheckText } from "./cli/api.js";
 import { buildApiCheckJson } from "./emit/apiCheckJson.js";
-import { buildValidateJson, buildSliceReadyJson, buildValidateListJson, collectMarkers } from "./emit/validateJson.js";
+import { buildValidateJson, buildShapeJson, buildSliceReadyJson, buildValidateListJson, collectMarkers } from "./emit/validateJson.js";
 import { buildDiffJson } from "./emit/diffJson.js";
 import { diffModels, formatModelDiff, hasChanges } from "./model/diff.js";
 import { planDiffArgs, realGit, resolveRevision, resolveDocAtRevision } from "./cli/diff-inputs.js";
@@ -34,7 +35,12 @@ import { validateOrphanedSliceDocs } from "./catalog/orphanedSliceDocValidate.js
 import { validateModelVersionStale } from "./catalog/modelVersionValidate.js";
 import { validateInvariants } from "./catalog/invariantsValidate.js";
 import { computeSliceReadiness } from "./catalog/sliceReadyValidate.js";
-import { applyEngagementClose, applyEngagementSet, buildNewEngagement, engagementMembersFor, engagementPlanFor, engagementStatusFor, formatEngagementPlanText, formatEngagementStatusText, } from "./cli/engagement.js";
+import { checkRosterForWrite, findRosterAbove, loadRoster, ROSTER_FILE } from "./roster/roster.js";
+import { observeSigners, renderRoster } from "./roster/init.js";
+import { rosterContextFor } from "./roster/context.js";
+import { computeModelKey } from "./model/qualifiedRef.js";
+import { checkRoster, formatRosterCheck, buildRosterCheckJson, grandfatheredNotice } from "./roster/check.js";
+import { applyEngagementClose, applyEngagementSet, buildNewEngagement, buildUnitIndex, effectiveTracking, engagementMembersFor, engagementPlanFor, engagementStatusFor, formatEngagementPlanText, formatEngagementStatusText, } from "./cli/engagement.js";
 import { LEDGER_STATES, engagementPath, loadEngagement, readOpenEngagements } from "./cli/engagementFile.js";
 import { buildEngagementFoundationJson, buildEngagementPlanJson, buildEngagementStatusJson } from "./emit/engagementJson.js";
 import { checkFoundation, formatFoundationText } from "./cli/engagementFoundation.js";
@@ -43,6 +49,7 @@ import { checkLedger, readLedgerWaiverTrailers, applyLedgerWaivers } from "./cli
 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 { buildCoverageReport, resolveScopedSlices, resolveCoverageSliceKey } from "./cli/coverage.js";
 import { buildCoverageJson } from "./emit/coverageJson.js";
@@ -68,7 +75,7 @@ import { planGlossaryArgs } from "./cli/glossary-inputs.js";
 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 { formatNextDraftNotice, runMarkImplemented } from "./cli/markImplemented.js";
 import { runRatify, parseMeaningFlags, meaningConfirmationLine } from "./cli/ratify.js";
 import { runReview } from "./cli/review.js";
 import { runConformSupersede } from "./cli/conformSupersede.js";
@@ -83,6 +90,7 @@ 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 { checkPrdTriage, buildCheckPrdTriageJson, renderPrdTriageMarkdown, validatePrdTriage } from "./cli/prdTriage.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";
@@ -90,6 +98,7 @@ import { STARTER_EM, starterEmFor, scaffoldReadme, scaffoldStateFile, scaffoldCo
 import { kebabSlug } from "./util/slug.js";
 import { ciWorkflowPath, conformWorkflowPath, buildCiWorkflowFile, buildConformWorkflowFile, buildCiWorkflowFileMulti, buildConformWorkflowFileMulti, ciManagedBody, ciManagedBodyMulti, conformManagedBody, conformManagedBodyMulti, ciModelsFromManifest, describeOtherModels, describeSetChange, fileBlockModels, planCiFile, applyCiFile, findUnsafeCiInitArg, CI_WORKFLOW_MARKER, CONFORM_WORKFLOW_MARKER, } from "./cli/ciInit.js";
 import { resolveRepoRoot, detectUpgrade, applyUpgrade, checkUpgrade } from "./cli/upgrade.js";
+import { buildStorylineSuggestion } from "./cli/storylineSuggest.js";
 import { buildUpgradeJson } from "./emit/upgradeJson.js";
 import { isOlder } from "./util/semver.js";
 import { RULES } from "./model/rules.js";
@@ -189,6 +198,9 @@ program
     .option("-T, --format <fmt>", "output format (svg, png, pdf, ...)")
     .option("--slice <name>", "render only this slice, redrawn in its own canonical pattern shape " +
     "(default out: slices/<kebab-slug>.svg)")
+    .option("--storyline <name>", "render only this storyline: its slices in order, preceded by dimmed stub columns for what " +
+    "they read from outside it (and the end state of a storyline it comes `after`) " +
+    "(default out: storylines/<kebab-slug>.svg)")
     .option("--emit-dot", "print the generated DOT instead of rendering")
     .option("--keep-empty-lanes", "keep the API lane even when empty")
     .action(async (file, opts) => {
@@ -196,6 +208,10 @@ program
         console.error("em render: --slice cannot be combined with --emit-dot");
         process.exit(1);
     }
+    if (opts.storyline !== undefined && (opts.slice !== undefined || opts.emitDot)) {
+        console.error(`em render: --storyline cannot be combined with ${opts.slice !== undefined ? "--slice" : "--emit-dot"}`);
+        process.exit(1);
+    }
     const { dot, model, grid, diagnostics, refs } = compileFile(file, {
         keepEmptyLanes: opts.keepEmptyLanes,
     });
@@ -220,6 +236,22 @@ program
         console.error("not rendering: fix the errors above");
         process.exit(1);
     }
+    if (opts.storyline !== undefined) {
+        const found = resolveStorylineArg(model, opts.storyline);
+        if ("error" in found) {
+            console.error(found.error);
+            process.exit(1);
+        }
+        const out = opts.out ?? defaultStorylineOut(file, found.storyline.name);
+        const fmt = opts.format ?? formatFromPath(out);
+        await mkdir(dirname(out), { recursive: true }); // storylines/ may not exist yet
+        const sub = buildStorylineDiagram(model, found.storyline, { keepEmptyLanes: opts.keepEmptyLanes });
+        const raw = await layoutDot(sub.dot);
+        const svg = composeSvg(raw, sub.model, sub.grid, dirname(file), dirname(out));
+        await writeRendered(svg, out, fmt);
+        console.log(`rendered ${out}`);
+        return;
+    }
     if (opts.slice !== undefined) {
         const lookup = resolveSliceArg(opts.slice, model.slices);
         if ("error" in lookup) {
@@ -539,6 +571,7 @@ slice
     // MIL-266: with a model in hand (--wire), the doc's generated regions are filled from it;
     // without one they carry the template's placeholders until `em slice sync` fills them.
     let regions;
+    let alternatives = [];
     if (opts.wire) {
         const { model, refs, diagnostics, source } = compileFile(opts.wire);
         printDiagnostics(diagnostics);
@@ -553,11 +586,13 @@ slice
         }
         wired = result;
         regions = buildSliceRegions(model, [refs.sliceKeys.indexOf(key)]);
+        const sliceEvents = model.slices[refs.sliceKeys.indexOf(key)].elements.filter((e) => e.kind === "event");
+        alternatives = sliceEvents.filter((e) => e.alternativeGroup !== undefined).map((e) => e.name);
     }
     mkdirSync(dir, { recursive: true });
     const content = opts.stub
         ? buildStubDocContent(name, opts.pattern, opts.swimlane)
-        : buildSliceDocContent(name, key, opts.pattern, opts.swimlane, regions);
+        : buildSliceDocContent(name, key, opts.pattern, opts.swimlane, regions, alternatives);
     writeFileSync(path, content);
     console.log(`wrote ${path}`);
     if (wired) {
@@ -698,6 +733,7 @@ slice
     .argument("<slice-key>", "slice export key (kebab-case)")
     .argument("<pr-url>", "merged PR (or commit) URL")
     .option("--on <date>", "merge date recorded as `shippedOn:`, YYYY-MM-DD (default: today, local date; MIL-284)")
+    .option("--json", "print a JSON document instead of text: { path, changed, implementedIn, nextDraft: { version, reopened[] } | null } (GH #285)")
     .action((file, sliceKey, prUrl, opts) => {
     if (opts.on !== undefined && !isValidDateString(opts.on)) {
         console.error(`em slice mark-implemented: invalid --on date "${opts.on}" — expected YYYY-MM-DD`);
@@ -720,13 +756,21 @@ slice
         console.error(`em slice mark-implemented: ${result.message}`);
         process.exit(1);
     }
+    if (opts.json) {
+        console.log(JSON.stringify({
+            path: result.path,
+            changed: result.changed,
+            implementedIn: prUrl,
+            nextDraft: result.openedDraft ? { version: result.openedDraft.version, reopened: result.openedDraft.titles } : null,
+        }, null, 2));
+        return;
+    }
     console.log(result.changed
         ? `marked implemented: ${result.path} (implementedIn: ${prUrl})`
         : `already implemented (no-op): ${result.path}`);
-    if (result.ok && result.openedDraft) {
-        console.log(`opened draft v${result.openedDraft.version}: ${result.path} — re-opened ${result.openedDraft.reopened} deferred question(s)` +
-            (result.openedDraft.injected > 0 ? `, injected ${result.openedDraft.injected} queued question(s) (GH #236)` : "") +
-            `; v${result.openedDraft.version - 1} stays shipped`);
+    if (result.openedDraft) {
+        console.log("");
+        console.log(formatNextDraftNotice(result.path, result.openedDraft, prUrl));
     }
 });
 slice
@@ -735,12 +779,16 @@ slice
     "— the FIRST of the two human gates (MIL-201, docs/process.md#the-slice-lifecycle-gates): " +
     "the room walked this slice and every open question it raised is resolved. Ratification is " +
     "a separate, later gate (`em slice ratify`). Legal from `status: draft`; idempotent on the " +
-    "same --by/--on pair; refuses to overwrite a different one already recorded; refuses a doc " +
-    "already `ready-to-implement`/`implemented`; never touches `version:` or the doc body")
+    "same --by/--on pair; refuses to overwrite a different one already recorded (--again re-records " +
+    "it); refuses a doc with an unchecked `## Open Questions` item unless --allow-open (GH #333); " +
+    "refuses a doc already `ready-to-implement`/`implemented`; never touches `version:` or the doc body")
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
     .requiredOption("--by <name>", "the reviewer's (or facilitator's) name")
     .option("--on <date>", "review date, YYYY-MM-DD (default: today, local date)")
+    .option("--roster <path>", "ratifier roster to check --by against (GH #259; default: the nearest ratifiers.yaml above the model, none = unrestricted)")
+    .option("--again", "re-record reviewedBy/reviewedOn on a doc already `status: reviewed` (prints old -> new); still refused on ready-to-implement/implemented")
+    .option("--allow-open", "record the review although `## Open Questions` has unchecked items (a deliberately partial walk); prints a notice with the open count")
     .action((file, sliceKey, opts) => {
     const { model, refs, diagnostics } = compileFile(file);
     printDiagnostics(diagnostics);
@@ -752,19 +800,32 @@ slice
         console.error(`em slice review: slice "${sliceKey}" has errors — fix them first`);
         process.exit(1);
     }
+    const rosterRefused = checkRosterForWrite(loadRoster(dirname(file), opts.roster, rosterContextFor(model, file)), "reviewers", opts.by, model, refs.sliceKeys.indexOf(sliceKey), computeModelKey(model, file));
+    if (rosterRefused !== null) {
+        console.error(`em slice review: ${rosterRefused}`);
+        process.exit(1);
+    }
     const today = localIsoDate();
     const reviewedOn = opts.on ?? today;
     if (opts.on !== undefined && !isValidDateString(opts.on)) {
         console.error(`em slice review: invalid --on date "${opts.on}" — expected YYYY-MM-DD`);
         process.exit(1);
     }
-    const result = runReview(model, refs, dirname(file), sliceKey, opts.by, reviewedOn);
+    const result = runReview(model, refs, dirname(file), sliceKey, opts.by, reviewedOn, {
+        again: opts.again === true,
+        allowOpen: opts.allowOpen === true,
+    });
     if (!result.ok) {
         console.error(`em slice review: ${result.message}`);
         process.exit(1);
     }
+    if (result.allowedOpen !== undefined) {
+        console.error(`notice: --allow-open — reviewing "${sliceKey}" with ${result.allowedOpen} unchecked Open Questions item(s)`);
+    }
     console.log(result.changed
-        ? `reviewed: ${result.path} (reviewedBy: ${opts.by}, reviewedOn: ${reviewedOn})`
+        ? result.previous
+            ? `re-reviewed: ${result.path} (reviewedBy: ${result.previous.by} -> ${opts.by}, reviewedOn: ${result.previous.on} -> ${reviewedOn})`
+            : `reviewed: ${result.path} (reviewedBy: ${opts.by}, reviewedOn: ${reviewedOn})`
         : `already reviewed (no-op): ${result.path}`);
 });
 /** MIL-238: `, meaningConfirmed: true` / `, contractChange: "<why>"` for a success line, or "". */
@@ -794,6 +855,7 @@ slice
     .option("--no-ref", "record ratifiedHash: only, no ratifiedRef: (GH #255) — the signed content keeps its identity, nothing " +
     "points at a commit a squash or rebase merge would orphan; the uncommitted-changes check does not apply")
     .option("--on <date>", "ratification date, YYYY-MM-DD (default: today, local date)")
+    .option("--roster <path>", "ratifier roster to check --by against (GH #259; default: the nearest ratifiers.yaml above the model, none = unrestricted)")
     .option("--skip-review", "ratify without a recorded review — prints a loud notice on stderr and records `reviewSkipped: <status>` on the doc " +
     "(GH #260) so the bypass is visible to later readers, `em export` and `--slice-ready --json`; cleared by `em slice revise`")
     .option("--meaning-unchanged", "API-first sign-off (MIL-238): this version does not change what the public contract means — " +
@@ -818,6 +880,11 @@ slice
         console.error(`em slice ratify: slice "${sliceKey}" has errors — fix them first`);
         process.exit(1);
     }
+    const rosterRefused = checkRosterForWrite(loadRoster(dirname(file), opts.roster, rosterContextFor(model, file)), "ratifiers", opts.by, model, refs.sliceKeys.indexOf(sliceKey), computeModelKey(model, file));
+    if (rosterRefused !== null) {
+        console.error(`em slice ratify: ${rosterRefused}`);
+        process.exit(1);
+    }
     const today = localIsoDate();
     const ratifiedOn = opts.on ?? today;
     if (opts.on !== undefined && !isValidDateString(opts.on)) {
@@ -884,9 +951,13 @@ function reviseAction(commandName) {
         const what = result.kind === "shipped"
             ? `v${result.newVersion - 1} stays shipped; v${result.newVersion} opened as draft`
             : result.kind === "unshipped"
-                ? `ratification of v${result.newVersion - 1} withdrawn (never shipped); v${result.newVersion} opened as draft`
+                ? result.shippedVersion !== null
+                    ? `ratification of v${result.newVersion - 1} withdrawn; v${result.shippedVersion} stays shipped; v${result.newVersion} opened as draft`
+                    : `ratification of v${result.newVersion - 1} withdrawn (never shipped); v${result.newVersion} opened as draft`
                 : result.kind === "unshipped-kept"
-                    ? `ratification of v${result.newVersion} withdrawn (never shipped); reopened as draft at the same version (--keep-version)`
+                    ? result.shippedVersion !== null
+                        ? `ratification of v${result.newVersion} withdrawn; v${result.shippedVersion} stays shipped; reopened as draft at the same version (--keep-version)`
+                        : `ratification of v${result.newVersion} withdrawn (never shipped); reopened as draft at the same version (--keep-version)`
                     : `v${result.newVersion} was never signed; reopened as draft at the same version`;
         console.log(`revised: ${result.path} (status: draft, version: ${result.newVersion} — ${what})`);
         if (result.reopened > 0)
@@ -1495,6 +1566,45 @@ conformFindings
     if (!result.ok)
         process.exit(1);
 });
+const discover = program.command("discover").description("checks for the discover skill's records (GH #295)");
+discover
+    .command("triage-check")
+    .description("validate a discovery/prd-triage.json (prdTriageSchemaVersion 1.0): shape, the shipped rubric " +
+    "version, every statement/storyline quote appearing verbatim in the input document, and every " +
+    "statement carrying a category, an outcome and (modeled/rewritten) a group + storyline — exit 1 " +
+    "on errors. The discover skill writes this file directly; this is how a headless run verifies it.")
+    .argument("<file>", "path to a discovery/prd-triage.json file")
+    .option("--source <path>", "the input PRD/spec to check quotes against (default: the file's own `source`, relative to it)")
+    .option("--markdown", "after a passing check, print the Markdown view of the record instead of the summary")
+    .option("--json", "print a JSON document instead of the text report")
+    .action((file, opts) => {
+    const result = checkPrdTriage(file, { source: opts.source });
+    if (opts.json) {
+        console.log(buildCheckPrdTriageJson(result));
+    }
+    else if (result.ok) {
+        if (opts.markdown) {
+            const shape = validatePrdTriage(JSON.parse(readFileSync(file, "utf8")));
+            if (shape.ok)
+                process.stdout.write(renderPrdTriageMarkdown(shape.doc, shape.referenceOnlyGroups));
+        }
+        else {
+            console.log(`ok — ${result.path}: ${result.storylines} storyline(s), ${result.groups} group(s), ${result.statements} statement(s), quotes verbatim in ${relative(process.cwd(), result.source) || result.source}`);
+            if (result.referenceOnlyGroups.length > 0) {
+                console.log("reference-only groups — operations no walkthrough touches; check these are not CRUD fill:");
+                for (const g of result.referenceOnlyGroups)
+                    console.log(`  - ${g}`);
+            }
+        }
+    }
+    else {
+        console.error(`em discover triage-check: ${result.path} — 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")
@@ -1587,24 +1697,65 @@ program
     .option("--require-ratified-hash", "with --slice-ready (GH #256): strict mode — a ready-to-implement doc with no `ratifiedHash:` is NOT ready " +
     "(`slice-ready-missing-ratified-hash`, error; `ready: false` in --json). Off by default so docs ratified " +
     "before em 1.15 keep passing; turn it on once legacy docs are re-ratified")
+    .option("--strict", "promote advisory lints (GH #293: scenario-quality warnings) to errors: they fail the run and, with --slice-ready, block readiness")
+    .option("--roster <path>", "with --slice-ready (GH #259): the ratifier roster to check `ratifiedBy` against (default: the nearest " +
+    "ratifiers.yaml above the model; none = unrestricted). A name the roster does not permit for the slice's " +
+    "context is `ratified-by-not-in-roster` (error)")
     .option("--check-signed-bodies", "opt-in (GH #257): compare every slice doc that records a `ratifiedHash:` — ready, implemented, any status — " +
     "to its body; a mismatch is `slice-body-changed-since-ratification` (error). A pre-1.17 whole-body hash with an " +
     "intact body passes; a deferral written by `em slice defer` is outside the hash. The one check that still " +
     "watches a shipped doc's signed content")
+    .option("--shape", "GH #282: run only the advisory shape-family lints (storyline shape) and print rule / count / first ref / docs " +
+    "anchor; exit 0 always. With --json: `shapeSchemaVersion` 1.0 with per-rule finding arrays")
+    .option("--waive-file <path>", "with --shape: a baseline file (`<rule-code> <slice-key>` per line, or a bare slice key for every shape rule; `#` comments) whose shape findings are listed " +
+    "as waived and not counted; missing file = no waivers")
     .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) => {
+    if (opts.roster !== undefined && !opts.sliceReady) {
+        console.error("em validate: --roster applies only with --slice-ready <key>");
+        process.exit(1);
+    }
     if (opts.requireRatifiedHash && !opts.sliceReady) {
         console.error("em validate: --require-ratified-hash applies only with --slice-ready <key>");
         process.exit(1);
     }
+    if (opts.waiveFile && !opts.shape) {
+        console.error("em validate: --waive-file applies only with --shape");
+        process.exit(1);
+    }
+    if (opts.shape && opts.strict) {
+        console.error("em validate: --strict applies only without --shape (shape findings never gate)");
+        process.exit(1);
+    }
+    if (opts.shape && (opts.sliceReady || opts.listIssues || opts.listDivergences || opts.listPublic || opts.failOnIssues || opts.checkSignedBodies)) {
+        console.error("em validate: --shape cannot be combined with --slice-ready, --list-*, --fail-on-issues or --check-signed-bodies");
+        process.exit(1);
+    }
     const { model, diagnostics, refs, source } = compileFile(file);
+    if (opts.shape) {
+        const all = computeAllDiagnostics(file, model, refs, diagnostics, source);
+        const report = buildShapeReport(all, opts.waiveFile ? readWaiveFile(opts.waiveFile) : []);
+        const modelErrors = all.filter((d) => d.severity === "error").length;
+        for (const k of report.staleWaivers)
+            console.error(`note: waiver "${k}" (${opts.waiveFile}) excuses no shape finding — ignored`);
+        if (opts.json)
+            process.stdout.write(buildShapeJson(file, report, modelErrors) + "\n");
+        else
+            console.log(formatShapeText(report, modelErrors));
+        return;
+    }
     // GH #257: an opt-in addition to the unconditional set, so --json, the text report and the
     // exit code all see it the same way every other diagnostic is seen.
     const allDiagnostics = [
         ...computeAllDiagnostics(file, model, refs, diagnostics, source),
         ...(opts.checkSignedBodies ? validateSignedBodies(model, refs, dirname(file)) : []),
     ];
+    // GH #293: --strict promotes advisory lints to errors (the --slice-ready branch below does
+    // its own promotion inside computeSliceReadiness, from the unpromoted set).
+    const reported = opts.strict && !opts.sliceReady
+        ? allDiagnostics.map((d) => RULES[d.code]?.advisory ? { ...d, severity: "error" } : d)
+        : allDiagnostics;
     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
@@ -1629,15 +1780,17 @@ program
         // `slice-ready-unknown-slice` error (carrying the resolver's message).
         const resolved = resolveSliceKey(model, refs, opts.sliceReady);
         const key = resolved.ok ? resolved.key : opts.sliceReady;
-        const { scoped, ready, result } = computeSliceReadiness(model, refs, dirname(file), key, contractInput, allDiagnostics, {
+        const { scoped, advisories, ready, result } = computeSliceReadiness(model, refs, dirname(file), key, contractInput, allDiagnostics, {
             requireRatifiedHash: opts.requireRatifiedHash === true,
+            strict: opts.strict === true,
+            rosterPath: opts.roster,
         });
-        printDiagnostics(scoped);
+        printDiagnostics([...scoped, ...advisories]);
         if (opts.json) {
             // MIL-128: the named gates (see computeSliceReadyGates) plus the same `scoped`
             // diagnostics and `ready` verdict driving the exit code below — replaces both the
             // scraped warning prose and the two hand-parsed English sentences.
-            process.stdout.write(buildSliceReadyJson(file, key, result?.gates ?? null, scoped, ready, result?.continuationOf ?? null, result?.reviewSkipped ?? null) + "\n");
+            process.stdout.write(buildSliceReadyJson(file, key, result?.gates ?? null, scoped, ready, result?.continuationOf ?? null, result?.reviewSkipped ?? null, advisories) + "\n");
         }
         else {
             console.log(ready ? `slice "${key}" is ready-to-implement` : `slice "${key}" is NOT ready-to-implement`);
@@ -1656,7 +1809,7 @@ program
     if (opts.listIssues || opts.listDivergences || opts.listPublic) {
         // Errors still fail the run below — surface them rather than exiting
         // non-zero with nothing but the list on screen.
-        const errorsOnly = allDiagnostics.filter((d) => d.severity === "error");
+        const errorsOnly = reported.filter((d) => d.severity === "error");
         if (opts.json) {
             const markers = collectMarkers(model, refs, {
                 issues: opts.listIssues,
@@ -1677,15 +1830,15 @@ program
         }
     }
     else if (opts.json) {
-        printDiagnostics(allDiagnostics);
-        process.stdout.write(buildValidateJson(file, allDiagnostics) + "\n");
+        printDiagnostics(reported);
+        process.stdout.write(buildValidateJson(file, reported) + "\n");
     }
     else {
-        printDiagnostics(allDiagnostics);
-        if (allDiagnostics.length === 0)
+        printDiagnostics(reported);
+        if (reported.length === 0)
             console.log("ok — no issues");
     }
-    if (hasErrors(allDiagnostics))
+    if (hasErrors(reported))
         process.exit(1);
     if (opts.failOnIssues && model.elements.some((el) => el.issue))
         process.exit(1);
@@ -2046,7 +2199,7 @@ program
         .filter((e) => e !== null);
     // MIL-239 (R11): the nearest system.yaml above the first input file, consumer-adaptation counted.
     const system = statusSystemBlock(files[0], realGit, (m) => console.error(`warn: em status: ${m}`));
-    const report = buildStatusReport(files, sliceFacts, openIssuesCount, invariants, conformance, statusDiagnostics, modelVersion, emVersion, system, readOpenEngagements(files));
+    const report = buildStatusReport(files, sliceFacts, openIssuesCount, invariants, conformance, statusDiagnostics, modelVersion, emVersion, system, readOpenEngagements(files), loadRoster(dirname(files[0])).state);
     let output;
     if (opts.json)
         output = buildStatusJson(report);
@@ -2233,9 +2386,10 @@ query
     .option("--context <c>", "match a slice with an event in this @Context")
     .option("--persona <p>", "match a slice with a ui in this @Persona")
     .option("--tag <t>", "match a slice with an event carrying this tag key")
+    .option("--storyline <name>", "match a slice declared in this `storyline` block")
     .option("--json", "print a JSON document instead of the text report")
     .action((files, opts) => {
-    const filters = { pattern: opts.pattern, status: opts.status, context: opts.context, persona: opts.persona, tag: opts.tag };
+    const filters = { pattern: opts.pattern, status: opts.status, context: opts.context, persona: opts.persona, tag: opts.tag, storyline: opts.storyline };
     runQueryVerb(files, "slices", filters, opts.json, (s) => querySlices(s, filters), formatSlices);
 });
 query
@@ -2294,6 +2448,7 @@ engagement
     .option("--parallel <n>", "how many slices of one level may be in flight at once", "3")
     .option("--by <name>", "who created the engagement (createdBy)")
     .option("--tracking <key>", "an issue-tracker key or URL the slice PRs cite (a slice doc's own tracking: wins)")
+    .option("--pr-title <template>", "PR title template for the slice PRs; {key} = tracking key, {slice} = slice name, {sliceKey} = slice key (default \"{key}: {slice}\", or \"{slice}\" without a key)")
     .option("--force", "overwrite an existing engagement file with this slug")
     .action((file, slug, opts) => {
     const fail = (m) => {
@@ -2311,13 +2466,20 @@ engagement
     const parallel = /^\d+$/.test(opts.parallel) ? Number(opts.parallel) : NaN;
     const { model, refs } = compileFile(file);
     const path = engagementPath(file, slug);
-    const result = buildNewEngagement({ file, model, refs, baseDir: dirname(file) }, { slug, selector, parallel, createdBy: opts.by ?? null, tracking: opts.tracking ?? null, created: localIsoDate() });
+    const result = buildNewEngagement({ file, model, refs, baseDir: dirname(file) }, { slug, selector, parallel, createdBy: opts.by ?? null, tracking: opts.tracking ?? null, prTitle: opts.prTitle ?? null, created: localIsoDate() });
     if (!result.ok)
         return fail(result.message);
     if (existsSync(path) && !opts.force)
         fail(`engagement "${slug}" already exists (${path}) — pass --force to overwrite`);
     if (result.warning)
         console.error(result.warning);
+    if (opts.prTitle !== undefined && opts.prTitle.includes("{key}")) {
+        const uidx = buildUnitIndex(model, refs, dirname(file));
+        const keyless = result.units.filter((u) => effectiveTracking(uidx.docTracking.get(u) ?? null, opts.tracking?.trim() || null) === null);
+        if (keyless.length > 0) {
+            console.error(`em engagement new: --pr-title uses {key}; slices without a tracking key fall back to the default title "{slice}" (the slice name): ${keyless.join(", ")} — pass --tracking or set tracking: in the slice docs`);
+        }
+    }
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, result.text);
     console.log(`wrote ${path} (${result.units.length} slice${result.units.length === 1 ? "" : "s"}: ${result.units.join(", ")})`);
@@ -2459,6 +2621,69 @@ engagement
     writeFileSync(loaded.path, result.text);
     console.log(`closed engagement "${slug}" (${loaded.path})`);
 });
+const rosterCommand = program
+    .command("roster")
+    .description("the optional ratifier roster (ratifiers.yaml, GH #259) -- who may sign slice docs");
+rosterCommand
+    .command("init")
+    .description("write ratifiers.yaml beside the model, seeded from the names already recorded in the slice docs' " +
+    "`ratifiedBy:`/`reviewedBy:` (whole-model entries; narrow them with `contexts:` by hand). Refuses " +
+    "to overwrite an existing file unless --force; `em upgrade`'s grandfathered placeholder is not a name")
+    .argument("<file>", "input .em file")
+    .option("--roster <path>", "write the roster here instead of <model dir>/ratifiers.yaml")
+    .option("--force", "overwrite an existing roster file")
+    .action((file, opts) => {
+    const { model, refs, diagnostics } = compileFile(file);
+    printDiagnostics(diagnostics);
+    const target = opts.roster ?? join(dirname(file), ROSTER_FILE);
+    if (existsSync(target) && !opts.force) {
+        console.error(`em roster init: ${target} already exists -- pass --force to overwrite it`);
+        process.exit(1);
+    }
+    // A roster already governing this model from higher up would be shadowed by a nearer one.
+    const governing = findRosterAbove(dirname(file));
+    if (governing !== null && resolve(governing) !== resolve(target) && !opts.force) {
+        console.error(`em roster init: ${governing} already governs this model -- writing ${target} would shadow it; pass --force to write it anyway`);
+        process.exit(1);
+    }
+    const observed = observeSigners(model, refs, dirname(file));
+    if (observed.ratifiers.length === 0 && observed.reviewers.length === 0) {
+        const gfNone = grandfatheredNotice(observed.grandfathered);
+        if (gfNone)
+            console.log(gfNone);
+        console.error("em roster init: no ratifiedBy/reviewedBy names found in the slice docs -- write ratifiers.yaml by hand (docs/slice-doc-schema.md#who-may-ratify)");
+        process.exit(1);
+    }
+    writeFileSync(target, renderRoster(observed), "utf8");
+    console.log(`wrote ${target} (${observed.ratifiers.length} ratifier(s), ${observed.reviewers.length} reviewer(s))`);
+    const gf = grandfatheredNotice(observed.grandfathered);
+    if (gf)
+        console.log(gf);
+});
+rosterCommand
+    .command("check")
+    .description("check EVERY slice doc's recorded signers against the ratifier roster (GH #259) - `ratifiedBy` on " +
+    "ready-to-implement and implemented docs, `reviewedBy` on any doc - the whole-model CI gate that " +
+    "`--slice-ready <key>` (one ready slice) is not. Exit 1 on any violation or an invalid roster; no " +
+    "roster file = nothing to check, exit 0. The `grandfathered ...` placeholder is exempt (counted)")
+    .argument("<file>", "input .em file")
+    .option("--roster <path>", "roster to check against (default: the nearest ratifiers.yaml above the model)")
+    .option("--json", "print a JSON document (per-doc results, diagnostics with refs); exit codes unchanged")
+    .action((file, opts) => {
+    const { model, refs } = compileFile(file);
+    const loaded = loadRoster(dirname(file), opts.roster, rosterContextFor(model, file));
+    const report = checkRoster(model, refs, dirname(file), file, loaded);
+    printDiagnostics(report.diagnostics);
+    if (opts.json) {
+        process.stdout.write(buildRosterCheckJson(file, report) + "\n");
+    }
+    else {
+        for (const line of formatRosterCheck(report))
+            console.log(line);
+    }
+    if (!report.ok)
+        process.exitCode = 1;
+});
 const systemCommand = program
     .command("system")
     // `--json` exists on both `em system` and `em system codeowners`: parent options are only
@@ -2885,7 +3110,7 @@ ci.command("init")
         files = [
             [
                 ciPath,
-                planCiFile(ciPath, buildCiWorkflowFile(model, opts.tests, PKG_VERSION), ciManagedBody(model, opts.tests, PKG_VERSION), CI_WORKFLOW_MARKER, !!opts.force),
+                planCiFile(ciPath, buildCiWorkflowFile(model, opts.tests, PKG_VERSION, findRosterAbove(dirname(resolve(model))) !== null), ciManagedBody(model, opts.tests, PKG_VERSION, findRosterAbove(dirname(resolve(model))) !== null), CI_WORKFLOW_MARKER, !!opts.force),
             ],
             [
                 conformPath,
@@ -2956,6 +3181,30 @@ ci.command("init")
             console.log(`${path} already up to date`);
     }
 });
+const storylineCmd = program.command("storyline").description("storyline blocks (GH #277): advisory helpers for adopting them");
+storylineCmd
+    .command("suggest")
+    .description("advisory (GH #290): propose `storyline` blocks for a model that has none — one per distinct slice " +
+    "`source \"url\"`, the remaining slices grouped by the view-instance chains (`again`) they feed — " +
+    "printed as a unified diff on stdout (apply with `patch -p1` or `git apply`); never writes the model")
+    .argument("<file>", "input .em model file")
+    .action((file) => {
+    const { model, diagnostics, source: text } = compileFile(file);
+    printDiagnostics(diagnostics);
+    const s = buildStorylineSuggestion(model, text, file);
+    if (s.patch === "") {
+        console.error(`em storyline suggest: nothing to propose for ${file}`);
+        return;
+    }
+    for (const st of s.storylines) {
+        console.error(`storyline "${st.name}" — ${st.sliceIndexes.length} slice(s), from ${st.basis === "source" ? `source ${st.source}` : "a view-instance chain"}`);
+    }
+    if (s.ungrouped.length > 0) {
+        console.error(`left outside every storyline (${s.ungrouped.length}): ${s.ungrouped.map((i) => model.slices[i].name).join(", ")}`);
+    }
+    console.error("review the patch below and apply it by hand — nothing was written");
+    process.stdout.write(s.patch);
+});
 program
     .command("upgrade")
     .description("bring a model repo authored under an older em (1.6 forward) up to the installed version: " +
@@ -2967,7 +3216,13 @@ program
     .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 (an existing but unparseable state file, an un-migratable .em shape) — writes nothing; what CI runs; the final line says why")
     .option("--json", "print a JSON document instead of text (dry-run/--check only, never with --apply)")
+    .option("--fold-continuations", "also run the opt-in fold-continuations step (stack consecutive continuations of one view into the first; continuationOf, doc join and index rows unchanged)")
+    .option("--to-sugar", "(implies --fold-continuations; without --apply it is a dry run listing exactly what would fold): fold continuations into their host command slice as `view X again … shown on` lines — CHANGES continuationOf and the doc join to `<host>--again` and removes the folded slices' index rows")
     .action((file, opts) => {
+    if ((opts.foldContinuations || opts.toSugar) && opts.check) {
+        console.error("em upgrade: --fold-continuations / --to-sugar do not combine with --check");
+        process.exit(1);
+    }
     if (opts.apply && opts.check) {
         console.error("em upgrade: --apply and --check are mutually exclusive");
         process.exit(1);
@@ -3002,12 +3257,14 @@ program
         packagedAgentsRoot: packagedAgentsRoot(),
         model,
         refs,
+        ...(opts.foldContinuations ? { foldContinuations: true } : {}),
+        ...(opts.toSugar ? { toSugar: true } : {}),
     };
     if (opts.check) {
         const { ok, report, reasons } = checkUpgrade(ctx);
         console.error(`em upgrade --check: from ${report.from.version}${report.from.inferred ? ` (inferred: ${report.from.basis})` : ""} → to ${report.to}`);
         for (const s of report.steps) {
-            console.error(`  [${s.applicable ? "x" : " "}] ${s.id} (since ${s.sinceVersion}): ${s.reason}`);
+            console.error(`  [${s.optIn ? "~" : s.applicable ? "x" : " "}] ${s.id} (since ${s.sinceVersion}): ${s.reason}`);
         }
         for (const h of report.human)
             console.error(`  human: ${h.id}: ${h.reason}`);
@@ -3020,10 +3277,13 @@ program
     if (opts.apply) {
         const result = applyUpgrade(ctx);
         for (const s of result.applied) {
-            if (s.applied)
+            if (s.applied) {
                 console.log(`applied: ${s.id} — ${s.changedFiles.join(", ")} (${s.commit})`);
+                for (const n of s.notes ?? [])
+                    console.log(`  note: ${n}`);
+            }
             else
-                console.log(`skipped: ${s.id}`);
+                console.log(`skipped: ${s.id}${result.report.steps.find((x) => x.id === s.id)?.optIn ? " (opt-in: not requested by a flag)" : ""}`);
         }
         if (!result.ok) {
             console.error(result.message);
@@ -3035,6 +3295,7 @@ program
             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}`);
+        printUpgradeShapeSection(file);
         return;
     }
     const report = detectUpgrade(ctx);
@@ -3047,16 +3308,31 @@ program
         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(`  [${s.optIn ? "~" : 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`);
+    const applicableCount = report.steps.filter((s) => s.applicable && !s.optIn).length;
+    const optInCount = report.steps.filter((s) => s.optIn).length;
+    console.log(`${applicableCount} step(s) applicable${optInCount > 0 ? ` (+${optInCount} opt-in, marked [~], not applied by --apply)` : ""}, ${report.human.length} human item(s) — re-run with --apply to apply mechanical steps`);
+    printUpgradeShapeSection(file);
 });
+/** GH #290: the closing section of `em upgrade`'s text report — `em validate --shape` over the model as it
+ *  stands, so an estate sees how many advisory shape findings it carries. Never writes a waive file:
+ *  baselining shapes you accept is a decision (`--waive-file`, and a `shape-accepted:` Decisions-log bullet). */
+function printUpgradeShapeSection(file) {
+    const { model, diagnostics, refs, source } = compileFile(file);
+    const all = computeAllDiagnostics(file, model, refs, diagnostics, source);
+    const report = buildShapeReport(all, []);
+    console.log("");
+    console.log("Shape (em validate --shape, advisory):");
+    console.log(formatShapeText(report, all.filter((d) => d.severity === "error").length));
+    console.log("Record each shape you accept as `shape-accepted: <rule> <refs> — <reason>` in `.event-modeling.md` `## Decisions log`; " +
+        "to baseline an estate, run `em validate " + file + " --shape --waive-file <path>` (em upgrade writes no waive file).");
+}
 // 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