@milehimikey/em 1.14.2 → 1.16.0

package/dist/cli.js

@@ -13,6 +13,7 @@ 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 { resolveSliceKey } from "./model/resolveSlice.js";
 import { serializeBuilds, watchFile } from "./render/watch.js";
 import { startLiveServer } from "./render/serve.js";
 import { formatDiagnostic, hasErrors, publicViewsWithoutInModelReader } from "./model/validate.js";
@@ -75,8 +76,8 @@ import { wireSliceNote } from "./cli/sliceLink.js";
 import { isStubStatus, runStubAll, STUB_STATUSES } from "./cli/sliceStubAll.js";
 import { listModelCommits } from "./cli/changelog-git.js";
 import { buildChangelogDoc } from "./cli/changelogBuild.js";
-import { runReratify } from "./cli/reratify.js";
-import { runDefer } from "./cli/defer.js";
+import { runRevise } from "./cli/revise.js";
+import { runDefer, runDeferFromIssue } from "./cli/defer.js";
 import { runSliceConform } from "./cli/sliceConform.js";
 import { checkFindingsFile, buildCheckFindingsJson, lookupFindingsBesideReport, unruledFindingsInScope, FINDING_LOCI } from "./cli/findings.js";
 import { STATE_FILE_NAME, PHASES, isPhase, loadStateFile, parseState, setPhase, setConformance, setModelVersion, setCertified, setEmVersion, setReview, isValidDateString, modelPathMismatch, } from "./cli/stateFile.js";
@@ -246,7 +247,7 @@ program
         // "don't gate on breakage elsewhere" call `--slice-ready` already made (see its own
         // scoping comment above). Only an error that concerns THIS slice (bare key, or an
         // element ref prefixed `<key>/`) refuses.
-        const key = opts.slice;
+        const key = resolveSliceOrExit("em export --slice", model, refs, opts.slice);
         const scopedErrors = diagnostics.filter((d) => d.severity === "error" && d.refs?.some((r) => r === key || r.startsWith(`${key}/`)));
         if (scopedErrors.length > 0) {
             console.error(`not exporting: slice "${key}" has errors — fix them first`);
@@ -571,6 +572,8 @@ slice
         process.exit(1);
     }
     const check = opts.check === true;
+    if (key !== undefined)
+        key = resolveSliceOrExit("em slice sync", model, refs, key);
     const outcome = runSliceSync(model, refs, dirname(file), key, check);
     if (!outcome.ok) {
         console.error(`em slice sync: ${outcome.message}`);
@@ -672,14 +675,23 @@ slice
     "one edit an implementing agent makes to a ratified doc at merge (MIL-103, replaces the " +
     "em-sdd-bridge `em-sdd-mark-implemented` script; see reference/implement.md §6). " +
     "Applies only to a `ready-to-implement` doc (MIL-277: a `draft`/`reviewed` doc refuses — " +
-    "ratify first). Idempotent on the same URL; refuses to overwrite a different one; never " +
-    "touches `version:` or the doc body")
+    "ratify first). Also records the shipped version beside the link (MIL-284): `shippedVersion:`, " +
+    "`shippedRef:` (the doc's `ratifiedRef:`, when it has one) and `shippedOn:`, and opens the next " +
+    "version as a `draft` when an Open Question was deferred to it (MIL-283). Idempotent on " +
+    "the same URL — also after that draft opened; refuses to overwrite a different one; never touches " +
+    "the doc body except to re-open those deferred questions")
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
     .argument("<pr-url>", "merged PR (or commit) URL")
-    .action((file, sliceKey, prUrl) => {
+    .option("--on <date>", "merge date recorded as `shippedOn:`, YYYY-MM-DD (default: today, local date; MIL-284)")
+    .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`);
+        process.exit(1);
+    }
     const { model, refs, diagnostics } = compileFile(file);
     printDiagnostics(diagnostics);
+    sliceKey = resolveSliceOrExit("em slice mark-implemented", model, refs, sliceKey);
     // Scoped the same way `em export --slice`/`em validate --slice-ready` are: only an error
     // concerning THIS slice (bare key, or an element ref prefixed `<key>/`) refuses — an
     // unrelated slice's breakage elsewhere in a large, still-WIP model doesn't block marking
@@ -689,7 +701,7 @@ slice
         console.error(`em slice mark-implemented: slice "${sliceKey}" has errors — fix them first`);
         process.exit(1);
     }
-    const result = runMarkImplemented(model, refs, dirname(file), sliceKey, prUrl);
+    const result = runMarkImplemented(model, refs, dirname(file), sliceKey, prUrl, opts.on ?? localIsoDate());
     if (!result.ok) {
         console.error(`em slice mark-implemented: ${result.message}`);
         process.exit(1);
@@ -697,6 +709,11 @@ slice
     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`);
+    }
 });
 slice
     .command("review")
@@ -713,6 +730,7 @@ slice
     .action((file, sliceKey, opts) => {
     const { model, refs, diagnostics } = compileFile(file);
     printDiagnostics(diagnostics);
+    sliceKey = resolveSliceOrExit("em slice review", model, refs, sliceKey);
     // Scoped the same way `em slice ratify`/`em slice mark-implemented`/`em export --slice`/
     // `em validate --slice-ready` are: only an error concerning THIS slice refuses.
     const scopedErrors = diagnostics.filter((d) => d.severity === "error" && d.refs?.some((r) => r === sliceKey || r.startsWith(`${sliceKey}/`)));
@@ -745,11 +763,13 @@ slice
     "`ratifiedOn:` — the handoff sign-off (MIL-165, docs/process.md#the-slice-lifecycle-gates) " +
     "that makes who ratified, and when, a first-class recorded fact. The review gate is a check " +
     "on the doc's current `status:`, not on whether `reviewedBy:`/`reviewedOn:` are populated: " +
-    "a doc at `reviewed` or `ready-to-implement` passes (the latter is where `em slice " +
-    "reratify` leaves a doc, so the follow-up ratify needs no --skip-review); any other status " +
+    "a doc at `reviewed` passes; a `ready-to-implement` doc only when the same signer is " +
+    "completing their own record (since 1.15.0, MIL-283 — a new sign-off is a new version: " +
+    "`em slice revise`); any other status " +
     "— a `draft` that never went through `em slice review` — is refused unless --skip-review " +
     "is passed. Idempotent on " +
-    "the same --by/--on pair; refuses to overwrite a different one already recorded; never " +
+    "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")
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
@@ -768,6 +788,7 @@ slice
     }
     const { model, refs, diagnostics, source } = compileFile(file);
     printDiagnostics(diagnostics);
+    sliceKey = resolveSliceOrExit("em slice ratify", model, refs, sliceKey);
     // Scoped the same way `em slice mark-implemented`/`em export --slice`/`em validate
     // --slice-ready` are: only an error concerning THIS slice refuses.
     const scopedErrors = diagnostics.filter((d) => d.severity === "error" && d.refs?.some((r) => r === sliceKey || r.startsWith(`${sliceKey}/`)));
@@ -803,64 +824,83 @@ slice
         : `already ratified (no-op): ${result.path}`);
     warnModelVersionDrift(dirname(file), model, refs, source, `ratifying "${sliceKey}"`);
 });
+/** MIL-283: `em slice revise` and its deprecated alias `em slice reratify` share one action. */
+function reviseAction(commandName) {
+    return (file, sliceKey, opts) => {
+        if (commandName === "reratify") {
+            console.error("notice: `em slice reratify` is deprecated since 1.15.0 — it is `em slice revise`, and the result is a " +
+                "`draft` of the next version (not an unsigned `ready-to-implement`). Review and ratify it like v1.");
+        }
+        if (opts.meaningUnchanged || opts.contractChange !== undefined) {
+            console.error(`notice: --meaning-unchanged/--contract-change are not taken by \`em slice ${commandName}\` since 1.15.0 — the ` +
+                "API-first confirmation belongs to the ratification of the new version (`em slice ratify --by ... --meaning-unchanged`)");
+        }
+        const { model, refs, diagnostics, source } = compileFile(file);
+        printDiagnostics(diagnostics);
+        sliceKey = resolveSliceOrExit(`em slice ${commandName}`, model, refs, sliceKey);
+        // Scoped the same way `em slice ratify`/`em slice mark-implemented`/`em export --slice`/
+        // `em validate --slice-ready` are: only an error concerning THIS slice refuses.
+        const scopedErrors = diagnostics.filter((d) => d.severity === "error" && d.refs?.some((r) => r === sliceKey || r.startsWith(`${sliceKey}/`)));
+        if (scopedErrors.length > 0) {
+            console.error(`em slice ${commandName}: slice "${sliceKey}" has errors — fix them first`);
+            process.exit(1);
+        }
+        const result = runRevise(model, refs, dirname(file), sliceKey, opts.withdraw === true);
+        if (!result.ok) {
+            console.error(`em slice ${commandName}: ${result.message}`);
+            process.exit(1);
+        }
+        // MIL-214: advisory only, never refuses — see revise.ts's reviseAdvisory. Both warnings can
+        // fire together (a shipped version that was never certified AND still carries unruled findings).
+        if (result.advisory?.neverCertified) {
+            console.error(`warn: revising "${sliceKey}" whose shipped v${result.newVersion - 1} was never certified`);
+        }
+        if (result.advisory && result.advisory.unruledFindingsCount > 0) {
+            console.error(`warn: revising "${sliceKey}" with ${result.advisory.unruledFindingsCount} unruled conformance finding(s) on the shipped version`);
+        }
+        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`;
+        console.log(`revised: ${result.path} (status: draft, version: ${result.newVersion} — ${what})`);
+        if (result.reopened > 0)
+            console.log(`re-opened ${result.reopened} deferred question(s)`);
+        if (result.injected > 0)
+            console.log(`injected ${result.injected} queued question(s) into Open Questions (queue cleared)`);
+        warnModelVersionDrift(dirname(file), model, refs, source, `revising "${sliceKey}"`);
+    };
+}
+const REVISE_DESCRIPTION = "open the next version of a slice doc as a `draft` (MIL-283): bumps `version:`, flips `status:` to " +
+    "`draft`, clears the prior version's review and sign-off (`reviewedBy/On`, `ratifiedBy/On/Ref/Hash`, " +
+    "`meaningConfirmed`/`contractChange`) and re-opens the questions deferred to the new version. The " +
+    "shipped version stays shipped: `implementedIn:` and the `shipped*` keys are untouched (written first on " +
+    "a doc shipped before 1.15). Applies to `status: implemented` (the shipped case) and to a ratified " +
+    "`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)";
+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")
+    .action(reviseAction("revise"));
 slice
     .command("reratify")
-    .description("bump `version:` and flip a shipped slice doc's frontmatter back to `status: " +
-    "ready-to-implement` — the re-ratification mechanical edit (MIL-161, mirrors `em slice " +
-    "mark-implemented`). Applies to a doc at `status: implemented`, or (MIL-258) to a " +
-    "`ready-to-implement` doc that is ratified but not yet shipped — there it bumps `version:` " +
-    "and clears the sign-off but leaves `status:` alone; a `ready-to-implement` doc with no " +
-    "`ratifiedBy:` refuses (awaiting `em slice ratify --by`). Clears any stale " +
-    "`ratifiedBy:`/`ratifiedOn:`/`reviewedBy:`/`reviewedOn:` (they describe the PRIOR version's " +
-    "review and sign-off) so a follow-up `em slice ratify --by` applies cleanly — and needs no " +
-    "fresh review; never touches `implementedIn:` or the doc body")
+    .description("DEPRECATED alias of `em slice revise` (MIL-283, since 1.15.0; removed in a later minor). Until 1.14 this " +
+    "left the doc at an unsigned `ready-to-implement`; it now opens a `draft` of the next version like `revise`. " +
+    "The --meaning-unchanged/--contract-change flags are accepted and ignored with a notice — the API-first " +
+    "confirmation is taken by `em slice ratify` on the new version")
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
-    .option("--meaning-unchanged", "API-first sign-off (MIL-238): the new 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 the new version differently, and why — records " +
-    "`contractChange: \"<why>\"`")
-    .action((file, sliceKey, opts) => {
-    const flags = parseMeaningFlags(opts.meaningUnchanged, opts.contractChange);
-    if (!flags.ok) {
-        console.error(`em slice reratify: ${flags.message}`);
-        process.exit(1);
-    }
-    const { model, refs, diagnostics, source } = compileFile(file);
-    printDiagnostics(diagnostics);
-    // Scoped the same way `em slice ratify`/`em slice mark-implemented`/`em export --slice`/
-    // `em validate --slice-ready` are: only an error concerning THIS slice refuses.
-    const scopedErrors = diagnostics.filter((d) => d.severity === "error" && d.refs?.some((r) => r === sliceKey || r.startsWith(`${sliceKey}/`)));
-    if (scopedErrors.length > 0) {
-        console.error(`em slice reratify: slice "${sliceKey}" has errors — fix them first`);
-        process.exit(1);
-    }
-    const result = runReratify(model, refs, dirname(file), sliceKey, flags.confirmation);
-    if (!result.ok) {
-        console.error(`em slice reratify: ${result.message}`);
-        process.exit(1);
-    }
-    // MIL-214: advisory only, never refuses — see reratify.ts's reratifyAdvisory. Both warnings
-    // can fire together (a version that was never certified AND still carries unruled findings).
-    if (result.advisory?.neverCertified) {
-        console.error(`warn: reratifying "${sliceKey}" whose v${result.newVersion - 1} was never certified`);
-    }
-    if (result.advisory && result.advisory.unruledFindingsCount > 0) {
-        console.error(`warn: reratifying "${sliceKey}" has ${result.advisory.unruledFindingsCount} unruled conformance finding(s)`);
-    }
-    if (result.kind === "unshipped") {
-        // MIL-258: nothing was flipped — say what DID happen, and that the new version is unsigned.
-        console.log(`reratified: ${result.path} (version: ${result.newVersion - 1} -> ${result.newVersion}, sign-off cleared, ` +
-            `status unchanged: ready-to-implement${confirmationSuffix(flags.confirmation)}) — not ratified until ` +
-            `\`em slice ratify --by <name>\` records the new sign-off`);
-    }
-    else {
-        console.log(`reratified: ${result.path} (version: ${result.newVersion}, status: ready-to-implement${confirmationSuffix(flags.confirmation)})`);
-    }
-    if (result.reopened > 0)
-        console.log(`re-opened ${result.reopened} deferred question(s)`);
-    warnModelVersionDrift(dirname(file), model, refs, source, `reratifying "${sliceKey}"`);
-});
+    .option("--meaning-unchanged", "ignored since 1.15.0 (see above)")
+    .option("--contract-change <why>", "ignored since 1.15.0 (see above)")
+    .option("--withdraw", "see `em slice revise --withdraw`")
+    .action(reviseAction("reratify"));
 slice
     .command("defer")
     .description("record a question this version will not answer as deferred to a later version (MIL-275): " +
@@ -868,12 +908,19 @@ slice
     "v<current>: <decision>; deferred to v<n> (<date>[, <by>])` so `--slice-ready` passes without a " +
     "guess, and mirrors it into `.event-modeling.md` (the parking lot and a dated Decisions-log " +
     "bullet; the file must exist, it is never created). Idempotent; `em slice reratify` re-opens " +
-    "the item when it bumps to v<n>")
+    "the item when it bumps to v<n>. With --from-issue <text> instead of <question> (MIL-281): " +
+    "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")
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
-    .argument("<question>", "text identifying the unchecked Open Question (case-sensitive substring)")
+    .argument("[question]", "text identifying the unchecked Open Question (case-sensitive substring); omit when using --from-issue")
     .requiredOption("--until <version>", "the version that must answer it, v<n> (greater than the doc's version)")
     .requiredOption("--decision <text>", "what this version does instead")
+    .option("--from-issue <text>", "defer a captured `issue \"...\"` on this slice instead of a doc Open Question (case-sensitive substring of its text)")
     .option("--by <name>", "who deferred it")
     .option("--on <date>", "deferral date, YYYY-MM-DD (default: today, local date)")
     .action((file, sliceKey, question, opts) => {
@@ -881,24 +928,47 @@ slice
         console.error(`em slice defer: invalid --on date "${opts.on}" — expected YYYY-MM-DD`);
         process.exit(1);
     }
+    if ((question === undefined) === (opts.fromIssue === undefined)) {
+        console.error('em slice defer: pass either "<question>" or --from-issue <text>, not both and not neither');
+        process.exit(1);
+    }
     const { model, refs, diagnostics } = compileFile(file);
     printDiagnostics(diagnostics);
+    sliceKey = resolveSliceOrExit("em slice defer", model, refs, sliceKey);
     const scopedErrors = diagnostics.filter((d) => d.severity === "error" && d.refs?.some((r) => r === sliceKey || r.startsWith(`${sliceKey}/`)));
     if (scopedErrors.length > 0) {
         console.error(`em slice defer: slice "${sliceKey}" has errors — fix them first`);
         process.exit(1);
     }
-    const result = runDefer(model, refs, dirname(file), sliceKey, {
-        question,
-        until: opts.until,
-        decision: opts.decision,
-        by: opts.by,
-        on: opts.on ?? localIsoDate(),
-    });
+    const common = { until: opts.until, decision: opts.decision, by: opts.by, on: opts.on ?? localIsoDate() };
+    if (opts.fromIssue !== undefined) {
+        const result = runDeferFromIssue(model, refs, dirname(file), file, sliceKey, opts.fromIssue, common);
+        if (!result.ok) {
+            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})`
+            : `already deferred (no-op): ${result.path}`);
+        return;
+    }
+    const result = runDefer(model, refs, dirname(file), sliceKey, { question: question, ...common });
     if (!result.ok) {
         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})`
         : `already deferred (no-op): ${result.path}`);
@@ -907,7 +977,8 @@ slice
     .command("conform")
     .description("record per-slice-per-version conformance certification: sets `conformedVersion:`/" +
     "`conformedAt:`/`conformedOn:` on a slice doc (MIL-214) — the fact `driftSignal: in-sync` " +
-    "now depends on. Legal only for `status: implemented` with an `implementedIn:` link. " +
+    "now depends on. Legal only for a shipped slice (`status: implemented`, or any status with " +
+    "a `shippedVersion:` — MIL-283) with an `implementedIn:` link; `conformedVersion:` is the shipped version. " +
     "Idempotent on the same (version, --at) pair; a different --at simply overwrites (a " +
     "later re-certification is normal — there's no way for em to tell 'later' from 'earlier' " +
     "for an arbitrary revision string, so there's no --force to reach for). Refuses when the " +
@@ -921,7 +992,8 @@ slice
     .action((file, sliceKey, opts) => {
     const { model, refs, diagnostics } = compileFile(file);
     printDiagnostics(diagnostics);
-    // Scoped the same way `em slice ratify`/`em slice reratify`/`em slice mark-implemented` are:
+    sliceKey = resolveSliceOrExit("em slice conform", model, refs, sliceKey);
+    // Scoped the same way `em slice ratify`/`em slice revise`/`em slice mark-implemented` are:
     // only an error concerning THIS slice refuses.
     const scopedErrors = diagnostics.filter((d) => d.severity === "error" && d.refs?.some((r) => r === sliceKey || r.startsWith(`${sliceKey}/`)));
     if (scopedErrors.length > 0) {
@@ -1080,7 +1152,7 @@ state
         const compiled = compileFile(modelFile);
         if (!hasErrors(compiled.diagnostics)) {
             const { facts } = resolveSliceDocFacts(compiled.model, compiled.refs, modelDir);
-            inScope = new Set(facts.filter((f) => f.status === "implemented").map((f) => f.key));
+            inScope = new Set(facts.filter((f) => f.shipped).map((f) => f.key));
             compiledForCertify = { model: compiled.model, refs: compiled.refs, source: compiled.source };
         }
     }
@@ -1514,7 +1586,10 @@ program
         // R34 (MIL-268): one shared verdict helper for this flag, the MCP `slice_ready` tool, and
         // `em engagement plan`.
         const contractInput = { file, source, diagnostics };
-        const key = opts.sliceReady;
+        // GH #237: an unresolvable input goes through as typed so the gate reports its own
+        // `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);
         if (opts.json) {
@@ -1711,11 +1786,8 @@ program
     let onlyKey;
     let continuationOfKey = null;
     if (opts.slice !== undefined) {
-        const target = resolveCoverageSliceKey(model, refs, opts.slice);
-        if (!target) {
-            console.error(`em coverage --slice: no slice with export key "${opts.slice}" in this model`);
-            process.exit(1);
-        }
+        const resolved = resolveSliceOrExit("em coverage --slice", model, refs, opts.slice);
+        const target = resolveCoverageSliceKey(model, refs, resolved);
         onlyKey = target.key;
         continuationOfKey = target.continuationOf;
     }
@@ -1873,7 +1945,7 @@ program
     // merged `sliceFacts` above (which spans every input file when several are given).
     const conformance = compiled.map(({ file }) => {
         const facts = factsByFile.get(file) ?? [];
-        const sliceDocFacts = facts.map((f) => ({ key: f.key, status: f.rawStatus, implementedIn: f.implementedIn }));
+        const sliceDocFacts = facts.map((f) => ({ key: f.key, status: f.rawStatus, implementedIn: f.implementedIn, shipped: f.shipped }));
         return resolveConformanceEntry(file, opts.repo, sliceDocFacts);
     });
     // MIL-218: one model-version entry per input file.
@@ -2131,6 +2203,7 @@ engagement
     .option("--downstream-of <ref>", "a slice key, element ref, or display name: it and everything downstream of it (loops-to excluded)")
     .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("--force", "overwrite an existing engagement file with this slug")
     .action((file, slug, opts) => {
     const fail = (m) => {
@@ -2148,7 +2221,7 @@ 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, created: localIsoDate() });
+    const result = buildNewEngagement({ file, model, refs, baseDir: dirname(file) }, { slug, selector, parallel, createdBy: opts.by ?? null, tracking: opts.tracking ?? null, created: localIsoDate() });
     if (!result.ok)
         return fail(result.message);
     if (existsSync(path) && !opts.force)
@@ -2159,6 +2232,16 @@ engagement
     writeFileSync(path, result.text);
     console.log(`wrote ${path} (${result.units.length} slice${result.units.length === 1 ? "" : "s"}: ${result.units.join(", ")})`);
 });
+/** GH #237: resolve a `<slice-key>` argument (export key, display name, or unique prefix —
+ *  docs/cli.md "Slice keys") to the canonical export key, or print the resolver's error and exit 1. */
+function resolveSliceOrExit(command, model, refs, input) {
+    const resolved = resolveSliceKey(model, refs, input);
+    if (!resolved.ok) {
+        console.error(`${command}: ${resolved.message}`);
+        process.exit(1);
+    }
+    return resolved.key;
+}
 /** Compile `file` with the full `em validate` diagnostic set — what `engagement plan` needs for
  *  each slice's `--slice-ready` verdict (R34). */
 function engagementModelInput(file) {
@@ -2169,7 +2252,7 @@ function engagementModelInput(file) {
 engagement
     .command("plan")
     .description("the engagement's build plan: dependency levels over model.edges (loops-to excluded), and per " +
-    "slice its readiness, branch impl/<key>, base (main or impl/<upstream>), and any hold")
+    "slice its readiness, branch impl/<key>, base (always main — MIL-280), and any hold")
     .argument("<file>", "input .em file")
     .argument("<slug>", "engagement slug")
     .option("--json", "print a JSON document instead of text (same document as the MCP engagement_plan tool)")
@@ -2201,6 +2284,11 @@ engagement
     if (!loaded.ok)
         return fail(loaded.message);
     const { model, refs } = compileFile(file);
+    // GH #237: an input that resolves to no slice goes through as typed, so the engagement's own
+    // "is not in engagement" refusal (which names what the Ledger holds) still speaks.
+    const resolved = resolveSliceKey(model, refs, key);
+    if (resolved.ok)
+        key = resolved.key;
     const result = applyEngagementSet({ file, model, refs, baseDir: dirname(file) }, slug, loaded.text, loaded.file, { key, ...opts });
     if (!result.ok)
         return fail(result.message);