@milehimikey/em 1.16.1 → 1.18.0

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,26 +21,36 @@ 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";
 import { readSliceDoc } from "./catalog/readSliceDoc.js";
 import { validateLineage } from "./catalog/lineageValidate.js";
 import { validateFrontmatterCoherence } from "./catalog/frontmatterCoherenceValidate.js";
+import { validateSignedBodies } from "./catalog/signedBodyValidate.js";
 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 { validateInvariants } from "./catalog/invariantsValidate.js";
 import { computeSliceReadiness } from "./catalog/sliceReadyValidate.js";
-import { applyEngagementClose, applyEngagementSet, buildNewEngagement, 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, engagementMembersFor, engagementPlanFor, engagementStatusFor, formatEngagementPlanText, formatEngagementStatusText, } from "./cli/engagement.js";
 import { LEDGER_STATES, engagementPath, loadEngagement, readOpenEngagements } from "./cli/engagementFile.js";
-import { buildEngagementPlanJson, buildEngagementStatusJson } from "./emit/engagementJson.js";
+import { buildEngagementFoundationJson, buildEngagementPlanJson, buildEngagementStatusJson } from "./emit/engagementJson.js";
+import { checkFoundation, formatFoundationText } from "./cli/engagementFoundation.js";
 import { detectSliceDocCollisions } from "./catalog/modelCollisionValidate.js";
 import { checkLedger, readLedgerWaiverTrailers, applyLedgerWaivers } from "./cli/ledgerCheck.js";
 import { planMigration, verifyMigration } from "./cli/migrateReactionShape.js";
 import { buildLedgerJson } from "./emit/ledgerJson.js";
+import { 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";
 import { resolveSliceStatusFacts, countOpenIssues, resolveConformanceEntry, aggregateInvariantTotals, buildStatusReport, formatStatusText, formatStatusMarkdown, buildStatusBadge, formatConformancePart, findSpecifyRoot, resolveModelVersionStatusEntry, resolveEmVersionStatusEntry, } from "./cli/status.js";
@@ -64,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";
@@ -79,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";
@@ -86,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";
@@ -101,6 +114,16 @@ import { runCodeowners } from "./system/codeowners.js";
 import { buildCodeownersJson } from "./emit/codeownersJson.js";
 import { verifySystem } from "./system/verify.js";
 import { buildSystemJson } from "./emit/systemJson.js";
+/** GH #253: the trailing note `em slice defer` prints after `deferred: …` on a ratified/shipped
+ *  doc — the item went into the signed body, outside `ratifiedHash`, and when the stamp was still
+ *  in the pre-1.17 whole-body scope it was re-stamped in the same edit (body unchanged). */
+function deferSignedNote(result) {
+    if (!result.signed)
+        return "";
+    return result.restamped
+        ? " — appended to the signed doc's Open Questions, outside ratifiedHash; ratifiedHash re-stamped to the 1.17 scope (body unchanged)"
+        : " — appended to the signed doc's Open Questions, outside ratifiedHash";
+}
 const program = new Command();
 // Single source of truth for the version (also read by src/emit/json.ts for
 // `generator.version` in `em export`): package.json, one level up from both
@@ -175,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) => {
@@ -182,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,
     });
@@ -206,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) {
@@ -525,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);
@@ -539,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) {
@@ -684,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`);
@@ -706,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
@@ -727,6 +785,7 @@ slice
     .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)")
     .action((file, sliceKey, opts) => {
     const { model, refs, diagnostics } = compileFile(file);
     printDiagnostics(diagnostics);
@@ -738,6 +797,11 @@ 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)) {
@@ -770,17 +834,26 @@ slice
     "is passed. Idempotent on " +
     "the same --by/--on pair; refuses to overwrite a different one already recorded, and (MIL-284) a " +
     "same-pair re-run on a doc whose body moved after sign-off; never " +
-    "touches `version:` or the doc body")
+    "touches `version:` or the doc body. Inside a git work tree also records `ratifiedRef:` (HEAD, " +
+    "refusing a doc with uncommitted changes) and always `ratifiedHash:`; with --no-ref (GH #255) " +
+    "only the hash — for a repo whose squash/rebase merges would leave the ref unreachable — and " +
+    "git is not consulted")
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
     .requiredOption("--by <name>", "the ratifier's name")
+    .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("--skip-review", "ratify without a recorded review — prints a loud notice on stderr")
+    .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 — " +
     "records `meaningConfirmed: true`; required (or --contract-change) on a slice touching a `public` element")
     .option("--contract-change <why>", "API-first sign-off (MIL-238): a consumer must read this change differently, and why — records " +
     "`contractChange: \"<why>\"`")
     .action((file, sliceKey, opts) => {
+    // commander: `--no-ref` sets `opts.ref === false`; unset leaves it undefined (ref recorded).
+    const noRef = opts.ref === false;
     const flags = parseMeaningFlags(opts.meaningUnchanged, opts.contractChange);
     if (!flags.ok) {
         console.error(`em slice ratify: ${flags.message}`);
@@ -796,13 +869,18 @@ 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)) {
         console.error(`em slice ratify: invalid --on date "${opts.on}" — expected YYYY-MM-DD`);
         process.exit(1);
     }
-    const result = runRatify(model, refs, dirname(file), sliceKey, opts.by, ratifiedOn, opts.skipReview === true, flags.confirmation);
+    const result = runRatify(model, refs, dirname(file), sliceKey, opts.by, ratifiedOn, opts.skipReview === true, flags.confirmation, undefined, noRef);
     if (!result.ok) {
         console.error(`em slice ratify: ${result.message}`);
         process.exit(1);
@@ -820,7 +898,8 @@ slice
         console.error(`warn: ratifying "${sliceKey}" ahead of upstream slice "${upstream.sliceKey}" (status: ${upstream.status})`);
     }
     console.log(result.changed
-        ? `ratified: ${result.path} (ratifiedBy: ${opts.by}, ratifiedOn: ${ratifiedOn}${confirmationSuffix(flags.confirmation)})`
+        ? `ratified: ${result.path} (ratifiedBy: ${opts.by}, ratifiedOn: ${ratifiedOn}${confirmationSuffix(flags.confirmation)})` +
+            (noRef ? " — ratifiedHash only, no ratifiedRef (--no-ref)" : "")
         : `already ratified (no-op): ${result.path}`);
     warnModelVersionDrift(dirname(file), model, refs, source, `ratifying "${sliceKey}"`);
 });
@@ -845,7 +924,7 @@ function reviseAction(commandName) {
             console.error(`em slice ${commandName}: slice "${sliceKey}" has errors — fix them first`);
             process.exit(1);
         }
-        const result = runRevise(model, refs, dirname(file), sliceKey, opts.withdraw === true);
+        const result = runRevise(model, refs, dirname(file), sliceKey, opts.withdraw === true, opts.keepVersion === true);
         if (!result.ok) {
             console.error(`em slice ${commandName}: ${result.message}`);
             process.exit(1);
@@ -861,8 +940,14 @@ 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`
-                : `v${result.newVersion} was never signed; reopened as draft at the same version`;
+                ? 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"
+                    ? 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)
             console.log(`re-opened ${result.reopened} deferred question(s)`);
@@ -879,15 +964,19 @@ const REVISE_DESCRIPTION = "open the next version of a slice doc as a `draft` (M
     "`ready-to-implement` doc (ratification withdrawn, never shipped); a `ready-to-implement` doc with no " +
     "`ratifiedBy:` reopens as draft at the same version; `draft`/`reviewed` refuse — the next version is " +
     "already open. The new version then takes the normal road: `em slice review --by`, `em slice ratify --by`. " +
-    "Questions queued by `em slice defer` for the new version (GH #236) are injected into its Open Questions. " +
     "A ratified, never-shipped doc REFUSES without --withdraw (revising withdraws the only implementable version; " +
-    "queue a question with `em slice defer` instead)";
+    "record a question with `em slice defer` instead — it sits outside the hash, GH #253). " +
+    "With --keep-version (GH #262) a ratified, never-shipped doc " +
+    "reopens as a draft at the SAME `version:` — same status flip and sign-off clearing, no bump — for a project that " +
+    "holds every slice at its initial version until a first release; refused on a shipped doc";
 slice
     .command("revise")
     .description(REVISE_DESCRIPTION)
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
     .option("--withdraw", "GH #236: required on a ratified, never-shipped doc — confirms withdrawing the ratification of the only implementable version")
+    .option("--keep-version", "GH #262: reopen a ratified, never-shipped doc as a draft at the same `version:` (no bump) — a correction before a first " +
+    "release, not a delta; refused on a shipped doc, whose version must stay distinct from the next one")
     .action(reviseAction("revise"));
 slice
     .command("reratify")
@@ -912,9 +1001,11 @@ slice
     "promotes the single open `issue \"...\"` on the slice's own elements containing <text> into " +
     "the doc's Open Questions as that same deferred item, mirrors it, and removes the `issue` " +
     "clause from the .em — the one-command path for a question raised in a review session. " +
-    "On a RATIFIED (`ready-to-implement` + `ratifiedBy:`) or shipped (`implemented`) doc (GH #236) the " +
-    "doc is NOT edited — its body is the signed spec — and the question is queued in `.event-modeling.md` " +
-    "for v<N+1>; `em slice revise` / `mark-implemented` inject it into the next draft")
+    "On a RATIFIED (`ready-to-implement` + `ratifiedBy:`) or shipped (`implemented`) doc (GH #253) the " +
+    "already-deferred `[x]` item is APPENDED to the doc's Open Questions — `ratifiedHash` excludes the " +
+    "section heading and its `deferred to v<n>` items, so the signature, `--slice-ready` and ratify's " +
+    "re-run stay valid, and the question is visible in the ratified doc; a pre-1.17 whole-body hash is " +
+    "re-stamped in the same edit. Refuses a doc whose body already fails its hash")
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
     .argument("[question]", "text identifying the unchecked Open Question (case-sensitive substring); omit when using --from-issue")
@@ -947,14 +1038,8 @@ slice
             console.error(`em slice defer: ${result.message}`);
             process.exit(1);
         }
-        if (result.queued) {
-            console.log(result.changed
-                ? `queued, not edited: ${result.path} stays as ratified (v${result.queued.docVersion}) — issue "${result.issue}" → ${opts.until} queued for ${sliceKey}@v${result.queued.forVersion} in .event-modeling.md; issue clause removed from ${file}:${result.modelLine}`
-                : `already queued (no-op): ${result.path}`);
-            return;
-        }
         console.log(result.changed
-            ? `deferred: ${result.path} (issue "${result.issue}" → ${opts.until}; issue clause removed from ${file}:${result.modelLine})`
+            ? `deferred: ${result.path} (issue "${result.issue}" → ${opts.until}; issue clause removed from ${file}:${result.modelLine})${deferSignedNote(result)}`
             : `already deferred (no-op): ${result.path}`);
         return;
     }
@@ -963,14 +1048,8 @@ slice
         console.error(`em slice defer: ${result.message}`);
         process.exit(1);
     }
-    if (result.queued) {
-        console.log(result.changed
-            ? `queued, not edited: ${result.path} stays as ratified (v${result.queued.docVersion}) — "${question}" → ${opts.until} queued for ${sliceKey}@v${result.queued.forVersion} in .event-modeling.md; \`em slice revise\` or \`mark-implemented\` injects it into the next draft`
-            : `already queued (no-op): ${result.path}`);
-        return;
-    }
     console.log(result.changed
-        ? `deferred: ${result.path} (${question} → ${opts.until})`
+        ? `deferred: ${result.path} (${question} → ${opts.until})${deferSignedNote(result)}`
         : `already deferred (no-op): ${result.path}`);
 });
 slice
@@ -986,7 +1065,9 @@ slice
     "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")
+    .requiredOption("--at <rev>", "the target-repo revision this certification sweep diffed against — or, when what was exercised is not a commit " +
+    "that stays reachable (a per-PR environment under squash/rebase merges, a build or image), an opaque " +
+    "`<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")
     .action((file, sliceKey, opts) => {
@@ -1474,6 +1555,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")
@@ -1563,11 +1683,68 @@ program
     "note binding, zero unchecked Open Questions, a recorded ratifiedBy, and — for a slice " +
     "touching a `public` element — a current contracts/<model key>.tsp; exits non-zero if not " +
     "ready (MIL-87, MIL-259, MIL-238)")
+    .option("--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);
-    const allDiagnostics = computeAllDiagnostics(file, model, refs, diagnostics, source);
+    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
@@ -1592,13 +1769,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);
-        printDiagnostics(scoped);
+        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, ...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) + "\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`);
@@ -1617,7 +1798,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,
@@ -1638,15 +1819,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);
@@ -1709,6 +1890,55 @@ program
 function describeLedgerWaiveSource(source) {
     return source.source === "flag" ? "--waive" : `trailer ${source.commit.slice(0, 7)}`;
 }
+program
+    .command("refs")
+    .description("check that every commit a slice doc records — `ratifiedRef:`, `shippedRef:`, a bare `conformedAt:` — still " +
+    "resolves and is reachable from a branch (GH #258): per doc, per field, `ancestor` / `not-ancestor` / " +
+    "`unresolved` / `undecidable` (a shallow clone never passes). Squash and rebase merges orphan the PR-branch HEAD " +
+    "ratify recorded; nothing else in em resolves a ref. Opt-in CI check, like `em ledger` — never part of `em validate`. " +
+    "Local object store only, no network. Kinded `conformedAt` values (build:…) are skipped; docs with no ref fields are not reported")
+    .argument("<file>", "model .em file (compiled for its slice keys; its directory locates slices/ and the repository)")
+    .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("--json", "print a JSON document instead of the text report (see docs/cli.md)")
+    .action((file, opts) => {
+    const { model, refs } = compileFile(file);
+    const outcome = checkRefs(model, refs, dirname(file), opts.reachableFrom);
+    if (!outcome.ok) {
+        console.error(`em refs: ${outcome.message}`);
+        process.exit(1);
+    }
+    const fileKeys = opts.waiveFile ? readWaiveFile(opts.waiveFile) : [];
+    const { result, unknownWaivers } = applyRefWaivers(outcome.result, opts.waive, fileKeys, opts.waiveFile ?? null);
+    for (const note of unknownWaivers) {
+        console.error(`note: waiver for slice "${note.sliceKey}" (${note.source.source === "flag" ? "--waive" : note.source.path}) has nothing to excuse — ignored`);
+    }
+    if (result.shallow)
+        console.error("warn: shallow clone — every ref is undecidable; check out with fetch-depth: 0");
+    if (opts.json) {
+        process.stdout.write(buildRefsJson(result, file) + "\n");
+    }
+    else {
+        for (const r of result.results) {
+            console.log(`  ${r.status.padEnd(12)} ${r.sliceKey} ${r.field}: ${r.ref}${r.detail ? ` — ${r.detail}` : ""}`);
+        }
+        for (const w of result.waived) {
+            console.log(`  waived       ${w.sliceKey} ${w.field}: ${w.ref} (${w.status}; waived by ${w.waivedBy.source === "flag" ? "--waive" : w.waivedBy.path})`);
+        }
+        const bad = result.results.filter((r) => r.status !== "ancestor").length;
+        const waivedNote = result.waived.length > 0 ? `, ${result.waived.length} waived` : "";
+        if (bad === 0) {
+            console.log(`ok — every recorded ref is reachable from ${opts.reachableFrom} (${result.checkedRefs} ref(s) on ${result.checkedDocs} doc(s)${waivedNote})`);
+        }
+        else {
+            console.log(`${bad} ref(s) not reachable from ${opts.reachableFrom} (${result.checkedRefs} checked on ${result.checkedDocs} doc(s)${waivedNote})`);
+        }
+    }
+    // Set the code rather than process.exit(): stdout to a pipe shouldn't risk truncation.
+    if (!result.ok)
+        process.exitCode = 1;
+});
 program
     .command("ledger")
     .description("check slice docs' version: field agrees with their content across two git revisions " +
@@ -1958,7 +2188,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);
@@ -2145,9 +2375,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
@@ -2266,6 +2497,34 @@ engagement
     }
     process.stdout.write((opts.json ? buildEngagementPlanJson(result.plan) : formatEngagementPlanText(result.plan)) + "\n");
 });
+engagement
+    .command("foundation")
+    .description("GH #240: is the foundation PR (implement.md §8) actually in the code for the events this engagement's slices " +
+    "emit and consume? A text scan of --code: an event is present when a file carries an identifier derived from " +
+    "its name (OrderPlaced / order_placed / ORDER_PLACED / order-placed), its model fields and tag fields are then " +
+    "looked for in those files. Per event: present | incomplete (missing-field / missing-tag, named) | missing-event " +
+    "— so \"foundation absent\" and \"foundation incomplete\" are different reports. Exits 1 unless every event is " +
+    "present. Proves the contract was written down, not that it type-checks")
+    .argument("<file>", "input .em file")
+    .argument("<slug>", "engagement slug")
+    .requiredOption("--code <dir>", "the target repository (or the directory the constitution's \"where a slice's code lives\" rule points at)")
+    .option("--json", "print a JSON document instead of text (same document as the MCP engagement_foundation tool)")
+    .action((file, slug, opts) => {
+    if (!existsSync(opts.code) || !statSync(opts.code).isDirectory()) {
+        console.error(`em engagement foundation: --code ${opts.code} is not a directory`);
+        process.exit(1);
+    }
+    const { model, refs } = compileFile(file);
+    const members = engagementMembersFor({ file, model, refs, baseDir: dirname(file) }, slug);
+    if (!members.ok) {
+        console.error(`em engagement foundation: ${members.message}`);
+        process.exit(1);
+    }
+    const check = checkFoundation(model, members.members, members.idx, opts.code);
+    process.stdout.write((opts.json ? buildEngagementFoundationJson(file, slug, check) : formatFoundationText(slug, check)) + "\n");
+    if (!check.ok)
+        process.exitCode = 1;
+});
 engagement
     .command("set")
     .description("the only write path to the Ledger: set one slice's state (and optionally branch/base/pr); " +
@@ -2343,6 +2602,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
@@ -2769,7 +3091,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,
@@ -2840,6 +3162,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: " +
@@ -2851,7 +3197,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);
@@ -2886,12 +3238,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}`);
@@ -2904,10 +3258,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);
@@ -2919,6 +3276,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);
@@ -2931,16 +3289,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