@milehimikey/em 1.13.0 → 1.14.0

package/dist/cli/upgrade.js

@@ -21,32 +21,55 @@
 // ci-block/constitution check needs. Requires the model directory to be inside a git
 // repository — same requirement `em conform-scope` holds, for the same reason (there is no
 // "changed since when" or "commit per step" without one).
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, realpathSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { PUBLIC_SCALAR_TYPE_NAMES } from "../model/model.js";
+import { findUnresolvedPublicFieldTypes } from "../model/validate.js";
 import { realGit } from "./diff-inputs.js";
 import { resolveSliceDocJoin } from "../catalog/docJoin.js";
 import { validateOrphanedSliceDocs } from "../catalog/orphanedSliceDocValidate.js";
 import { planMigration, verifyMigration } from "./migrateReactionShape.js";
-import { planSkillSyncBundle, applySkillSyncBundle } from "./skillSync.js";
-import { EM_ALL_SKILL_BUNDLE_DIRS, EM_SKILL_ANCHOR_DIR } from "./skillDirs.js";
-import { ciWorkflowPath, conformWorkflowPath, buildCiWorkflowFile, buildConformWorkflowFile, ciManagedBody, conformManagedBody, planCiFile, applyCiFile, CI_WORKFLOW_MARKER, CONFORM_WORKFLOW_MARKER, } from "./ciInit.js";
+import { planSkillSyncBundle, applySkillSyncBundle, planAgentSync, applySkillSync } from "./skillSync.js";
+import { EM_ALL_SKILL_BUNDLE_DIRS, EM_SKILL_ANCHOR_DIR, EM_AGENT_FILES } from "./skillDirs.js";
+import { detectPlugin, checkPlugin, claudePluginsDir, mergePluginSettings, pluginInstallCommands, pluginSettingsEntries } from "./pluginPin.js";
+import { syncAgentsMd } from "./agentsMd.js";
+import { ciWorkflowPath, conformWorkflowPath, buildCiWorkflowFile, buildConformWorkflowFile, buildCiWorkflowFileMulti, buildConformWorkflowFileMulti, ciManagedBody, ciManagedBodyMulti, conformManagedBody, conformManagedBodyMulti, ciModelsFromManifest, planCiFile, applyCiFile, CI_WORKFLOW_MARKER, CONFORM_WORKFLOW_MARKER, } from "./ciInit.js";
 import { findSpecifyRoot } from "./status.js";
-import { scaffoldConstitution } from "../templates.js";
-import { loadStateFile, parseState, setEmVersion, ensureOptionalBullets } from "./stateFile.js";
+import { scaffoldConstitution, scaffoldStateFile } from "../templates.js";
+import { loadStateFile, parseState, setEmVersion, ensureOptionalBullets, resolveStateFilePath } from "./stateFile.js";
 import { fieldLineRegex, normalizeFieldValue, locateFrontmatterInner } from "./frontmatterSurgery.js";
 import { localIsoDate } from "../util/localDate.js";
+import { compile } from "../pipeline.js";
+import { hasErrors } from "../model/validate.js";
+import { LEGACY_SYSTEM_MANIFEST_SCHEMA_VERSION, parseManifest } from "../system/manifest.js";
+import { planManifestMigration } from "../system/migrateManifest.js";
+import { loadSource, SYSTEM_MANIFEST_FILE } from "./systemInputs.js";
 export const UPGRADE_MIN_SUPPORTED_VERSION = "1.6.0";
 // ---- Step 1: skill-bundle — delegates to `em skill sync`'s own plan/apply. ----
 function vendoredSkillsRootOf(repoRoot) {
     return join(repoRoot, ".claude", "skills");
 }
+function vendoredAgentsRootOf(repoRoot) {
+    return join(repoRoot, ".claude", "agents");
+}
+function packagedAgentsRootOf(ctx) {
+    return ctx.packagedAgentsRoot ?? join(ctx.packagedSkillsRoot, "..", "agents");
+}
 function detectSkillBundle(ctx) {
     const vendoredRoot = vendoredSkillsRootOf(ctx.repoRoot);
+    // MIL-231/232: a repo that declares the plugin has no bundle to sync (any stray vendored copy is
+    // the `skill-plugin` step's business, not this one's).
+    if (detectPlugin(ctx.repoRoot))
+        return { applicable: false, reason: "plugin repo — nothing to sync" };
+    // MIL-232: the vendored bundle is about to be removed by `skill-plugin` (ordered first) — syncing it would be a throwaway commit.
+    if (detectSkillPlugin(ctx).applicable)
+        return { applicable: false, reason: "the vendored bundle is migrated to the plugin by skill-plugin — nothing to sync" };
     if (!existsSync(join(vendoredRoot, EM_SKILL_ANCHOR_DIR))) {
         return { applicable: false, reason: "no vendored skill bundle installed at .claude/skills/ — run `em skill install` first if you want one" };
     }
     const bundlePlan = planSkillSyncBundle(ctx.packagedSkillsRoot, vendoredRoot, EM_ALL_SKILL_BUNDLE_DIRS);
-    const totalChanges = bundlePlan.reduce((n, { plan }) => n + plan.changes.length, 0);
+    const agentPlan = planAgentSync(packagedAgentsRootOf(ctx), vendoredAgentsRootOf(ctx.repoRoot), EM_AGENT_FILES);
+    const totalChanges = bundlePlan.reduce((n, { plan }) => n + plan.changes.length, 0) + agentPlan.changes.length;
     if (totalChanges === 0)
         return { applicable: false, reason: "vendored skill bundle already matches the installed em" };
     return { applicable: true, reason: `vendored skill bundle differs from the installed em in ${totalChanges} file(s)` };
@@ -54,11 +77,71 @@ function detectSkillBundle(ctx) {
 function applySkillBundle(ctx) {
     const vendoredRoot = vendoredSkillsRootOf(ctx.repoRoot);
     const bundlePlan = planSkillSyncBundle(ctx.packagedSkillsRoot, vendoredRoot, EM_ALL_SKILL_BUNDLE_DIRS);
-    const totalChanges = bundlePlan.reduce((n, { plan }) => n + plan.changes.length, 0);
+    const vendoredAgents = vendoredAgentsRootOf(ctx.repoRoot);
+    const agentPlan = planAgentSync(packagedAgentsRootOf(ctx), vendoredAgents, EM_AGENT_FILES);
+    const totalChanges = bundlePlan.reduce((n, { plan }) => n + plan.changes.length, 0) + agentPlan.changes.length;
     if (totalChanges === 0)
         return { ok: false, message: "nothing to sync" };
     applySkillSyncBundle(bundlePlan, ctx.packagedSkillsRoot, vendoredRoot);
-    const changedFiles = bundlePlan.flatMap(({ dirName, plan }) => plan.changes.map((c) => join(".claude", "skills", dirName, c.relPath)));
+    applySkillSync(agentPlan, packagedAgentsRootOf(ctx), vendoredAgents);
+    const changedFiles = [
+        ...bundlePlan.flatMap(({ dirName, plan }) => plan.changes.map((c) => join(".claude", "skills", dirName, c.relPath))),
+        ...agentPlan.changes.map((c) => join(".claude", "agents", c.relPath)),
+    ];
+    return { ok: true, changedFiles };
+}
+// ---- Step 1b: skill-plugin (MIL-232, R14) — vendored bundle -> pinned em plugin, one commit. ----
+function detectSkillPlugin(ctx) {
+    const vendoredRoot = vendoredSkillsRootOf(ctx.repoRoot);
+    if (!existsSync(join(vendoredRoot, EM_SKILL_ANCHOR_DIR))) {
+        return { applicable: false, reason: "no vendored skill bundle installed at .claude/skills/ — nothing to migrate to the plugin" };
+    }
+    if (detectPlugin(ctx.repoRoot))
+        return { applicable: false, reason: "plugin already declared in .claude/settings.json" };
+    const settingsPath = join(ctx.repoRoot, ".claude", "settings.json");
+    if (existsSync(settingsPath) && mergePluginSettings(readFileSync(settingsPath, "utf8"), ctx.installedVersion) === null) {
+        return { applicable: false, reason: ".claude/settings.json is not a JSON object — fix it by hand, then re-run em upgrade" };
+    }
+    const e = pluginSettingsEntries(ctx.installedVersion);
+    return {
+        applicable: true,
+        reason: `vendored skill bundle → em plugin: remove ${EM_ALL_SKILL_BUNDLE_DIRS.map((d) => `.claude/skills/${d}`).join(", ")} and any of ${EM_AGENT_FILES.map((f) => `.claude/agents/${f}`).join(", ")}; ` +
+            `add extraKnownMarketplaces["${e.name}"] (github ${e.marketplace.source.repo}@${e.marketplace.source.ref}) and enabledPlugins["${e.enabledKey}"] to .claude/settings.json; ` +
+            `refresh the AGENTS.md managed section with the /em:* skill names`,
+    };
+}
+function applySkillPlugin(ctx) {
+    const settingsPath = join(ctx.repoRoot, ".claude", "settings.json");
+    const existing = existsSync(settingsPath) ? readFileSync(settingsPath, "utf8") : null;
+    // Verify before any write: an unparseable settings.json must not cost the user their skills.
+    const merged = mergePluginSettings(existing, ctx.installedVersion);
+    if (merged === null)
+        return { ok: false, message: ".claude/settings.json is not a JSON object — nothing changed" };
+    const vendoredRoot = vendoredSkillsRootOf(ctx.repoRoot);
+    const changedFiles = [];
+    // Only the bundle's own directories; a sibling skill under .claude/skills/ is never touched.
+    for (const d of EM_ALL_SKILL_BUNDLE_DIRS) {
+        const target = join(vendoredRoot, d);
+        if (!existsSync(target))
+            continue;
+        rmSync(target, { recursive: true, force: true });
+        changedFiles.push(join(".claude", "skills", d));
+    }
+    // MIL-269 (R32): exactly the four em agent files (the plugin ships them as em:em-*); any other
+    // agent in the shared directory is never listed or touched.
+    for (const f of EM_AGENT_FILES) {
+        const target = join(vendoredAgentsRootOf(ctx.repoRoot), f);
+        if (!existsSync(target))
+            continue;
+        rmSync(target, { force: true });
+        changedFiles.push(join(".claude", "agents", f));
+    }
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, merged);
+    changedFiles.push(join(".claude", "settings.json"));
+    const agents = syncAgentsMd(ctx.repoRoot);
+    if (agents.wrote)
+        changedFiles.push("AGENTS.md");
     return { ok: true, changedFiles };
 }
 // ---- Step 2: reaction-shape — delegates to `em migrate`'s own plan/verify/apply. ----
@@ -91,13 +174,40 @@ function applyReactionShape(ctx) {
     writeFileSync(ctx.modelFile, plan.rewritten);
     return { ok: true, changedFiles: [ctx.modelFile] };
 }
-// ---- Step 3: state-file — ensure Model version:/Certified: are present (MIL-218 defaults). ----
-// `Em version:` itself is deliberately NOT this step's job — `runUpgradeApply` always writes it
-// as its own dedicated final commit, whether or not this step ran (module header).
-function detectStateFile(ctx) {
+// ---- Step 3: state-file — scaffold when absent (MIL-257); else ensure Model version:/Certified:
+// are present (MIL-218 defaults). ----
+// `Em version:` itself is deliberately NOT this step's job when the file already exists —
+// `runUpgradeApply` always writes it as its own dedicated final commit, whether or not this step
+// ran (module header). A freshly scaffolded file is written already carrying the installed
+// version (scaffoldStateFile's own `Em version:` fill), so that final commit is then a no-op.
+/** MIL-257: the one human-readable sentence for "the state file exists but `parseState` rejected
+ *  it", naming the file so the `--check` final line / `--apply` refusal is self-explanatory.
+ *  `parseState`'s "missing bullet line(s): ..." reads as `is missing ...`; its format-mismatch
+ *  messages (`"- **X:**" doesn't match ...`) follow a colon instead. */
+export function describeStateFileFailure(path, parseMessage) {
+    return parseMessage.startsWith("missing ") ? `state file ${path} is ${parseMessage}` : `state file ${path}: ${parseMessage}`;
+}
+/** MIL-257: non-null when the state file exists but isn't parseable — shared by `detectStateFile`
+ *  (so the checklist line shows the real cause rather than the migration-tolerant
+ *  `Model version:`/`Certified:` item) and `applyStateFile`. */
+function stateFileParseFailure(ctx) {
     const loaded = loadStateFile(ctx.baseDir);
     if (!loaded.ok)
-        return { applicable: false, reason: loaded.message };
+        return null; // absent — scaffolded, not an error (MIL-257)
+    const parsed = parseState(loaded.text);
+    return parsed.ok ? null : describeStateFileFailure(loaded.path, parsed.message);
+}
+function detectStateFile(ctx) {
+    const loaded = loadStateFile(ctx.baseDir);
+    if (!loaded.ok) {
+        return {
+            applicable: true,
+            reason: `no state file at ${resolveStateFilePath(ctx.baseDir)} — em upgrade will scaffold one (Current phase: discover, Current step: 1, Last conformance/Last stakeholder review: never)`,
+        };
+    }
+    const failure = stateFileParseFailure(ctx);
+    if (failure !== null)
+        return { applicable: false, reason: failure };
     const patched = ensureOptionalBullets(loaded.text, "1970-01-01");
     if (!patched.ok)
         return { applicable: false, reason: patched.message };
@@ -107,9 +217,18 @@ function detectStateFile(ctx) {
 }
 function applyStateFile(ctx) {
     const loaded = loadStateFile(ctx.baseDir);
-    if (!loaded.ok)
-        return { ok: false, message: loaded.message };
     const today = localIsoDate();
+    if (!loaded.ok) {
+        // MIL-257: reuse `em scaffold`'s own generator (templates.ts scaffoldStateFile) rather than a
+        // second one. `Model file:` names the model actually being upgraded (its own basename).
+        const path = resolveStateFilePath(ctx.baseDir);
+        const slug = basename(ctx.modelFile, extname(ctx.modelFile));
+        writeFileSync(path, scaffoldStateFile(ctx.model.name, slug, today, ctx.installedVersion));
+        return { ok: true, changedFiles: [path] };
+    }
+    const failure = stateFileParseFailure(ctx);
+    if (failure !== null)
+        return { ok: false, message: failure };
     const patched = ensureOptionalBullets(loaded.text, today);
     if (!patched.ok)
         return { ok: false, message: patched.message };
@@ -126,32 +245,68 @@ function applyStateFile(ctx) {
 // Not anchored on a literal "em coverage" — the generated line pins an exact version
 // (`npx @milehimikey/em@1.9.0 coverage "..."`, ciInit.ts's own `em` template variable), so
 // "em" and "coverage" are never adjacent in the real file.
-const CI_INIT_ARGS_RE = /\bcoverage "([^"]*)" --tests "([^"]*)" --strict\b/;
-function extractCiInitArgs(emCiContent) {
-    const m = CI_INIT_ARGS_RE.exec(emCiContent);
-    return m ? { model: m[1], testsDir: m[2] } : null;
+const CI_INIT_ARGS_RE = /\bcoverage "([^"]*)" --tests "([^"]*)" --strict\b/g;
+function extractCiInitArgs(emCiContent, repoRoot) {
+    const all = [...emCiContent.matchAll(CI_INIT_ARGS_RE)];
+    if (all.length === 0)
+        return { args: null };
+    const named = [...new Set(all.map((m) => m[1]))];
+    const base = { model: all[0][1], testsDir: all[0][2] };
+    if (named.length < 2)
+        return { args: { ...base, models: null } };
+    // A multi-model block: regenerate it from the manifest, never from a single model.
+    const loaded = ciModelsFromManifest(repoRoot, repoRoot);
+    if (!loaded.ok) {
+        return {
+            args: null,
+            blocked: `em-ci.yml covers ${named.length} models (${named.join(", ")}) but no readable system.yaml sits at the repo root (${loaded.message}) - run \`em ci init <system.yaml>\` by hand if it needs refreshing`,
+        };
+    }
+    return { args: { ...base, models: loaded.models } };
+}
+function ciBlockFiles(args, ctx) {
+    // MIL-231: same plugin signal `em ci init` uses, so the two never disagree about the conform lines.
+    const usePlugin = detectPlugin(ctx.repoRoot) !== null;
+    if (args.models) {
+        return {
+            ci: [buildCiWorkflowFileMulti(SYSTEM_MANIFEST_ARG, args.models, args.testsDir, ctx.installedVersion), ciManagedBodyMulti(args.models, args.testsDir, ctx.installedVersion)],
+            conform: [buildConformWorkflowFileMulti(SYSTEM_MANIFEST_ARG, args.models, ctx.installedVersion, usePlugin), conformManagedBodyMulti(args.models, ctx.installedVersion, usePlugin)],
+        };
+    }
+    return {
+        ci: [buildCiWorkflowFile(args.model, args.testsDir, ctx.installedVersion), ciManagedBody(args.model, args.testsDir, ctx.installedVersion)],
+        conform: [buildConformWorkflowFile(args.model, ctx.installedVersion, usePlugin), conformManagedBody(args.model, ctx.installedVersion, usePlugin)],
+    };
 }
+/** Only used for the generated header's wording on a from-scratch file; `ci-block` only ever
+ *  patches the managed block of a file that already exists, so this never reaches disk there. */
+const SYSTEM_MANIFEST_ARG = "system.yaml";
 function ciBlockPlans(ctx) {
     const ciPath = ciWorkflowPath(ctx.repoRoot);
     const conformPath = conformWorkflowPath(ctx.repoRoot);
     if (!existsSync(ciPath))
         return { ciPath, ciStale: false, conformPath, conformStale: false, args: null };
-    const args = extractCiInitArgs(readFileSync(ciPath, "utf8"));
-    if (!args)
-        return { ciPath, ciStale: false, conformPath, conformStale: false, args: null };
-    const ciStatus = planCiFile(ciPath, buildCiWorkflowFile(args.model, args.testsDir, ctx.installedVersion), ciManagedBody(args.model, args.testsDir, ctx.installedVersion), CI_WORKFLOW_MARKER, false);
+    const extracted = extractCiInitArgs(readFileSync(ciPath, "utf8"), ctx.repoRoot);
+    if (!extracted.args)
+        return { ciPath, ciStale: false, conformPath, conformStale: false, args: null, blocked: "blocked" in extracted ? extracted.blocked : undefined };
+    const args = extracted.args;
+    const multi = args.models !== null;
+    const files = ciBlockFiles(args, ctx);
+    const ciStatus = planCiFile(ciPath, files.ci[0], files.ci[1], CI_WORKFLOW_MARKER, false, multi);
     const ciStale = ciStatus.kind === "stale";
     let conformStale = false;
     if (existsSync(conformPath)) {
-        const conformStatus = planCiFile(conformPath, buildConformWorkflowFile(args.model, ctx.installedVersion), conformManagedBody(args.model, ctx.installedVersion), CONFORM_WORKFLOW_MARKER, false);
+        const conformStatus = planCiFile(conformPath, files.conform[0], files.conform[1], CONFORM_WORKFLOW_MARKER, false, multi);
         conformStale = conformStatus.kind === "stale";
     }
     return { ciPath, ciStale, conformPath, conformStale, args };
 }
 function detectCiBlock(ctx) {
-    const { ciPath, ciStale, conformStale, args } = ciBlockPlans(ctx);
+    const { ciPath, ciStale, conformStale, args, blocked } = ciBlockPlans(ctx);
     if (!existsSync(ciPath))
         return { applicable: false, reason: "no .github/workflows/em-ci.yml — em upgrade never creates one" };
+    if (!args && blocked)
+        return { applicable: false, reason: blocked };
     if (!args)
         return { applicable: false, reason: "can't determine the <model>/--tests arguments em-ci.yml was generated with — run `em ci init <model>` by hand if it needs refreshing" };
     if (!ciStale && !conformStale)
@@ -162,15 +317,15 @@ function applyCiBlock(ctx) {
     const { ciPath, ciStale, conformPath, conformStale, args } = ciBlockPlans(ctx);
     if (!args || (!ciStale && !conformStale))
         return { ok: false, message: "nothing to refresh" };
+    const multi = args.models !== null;
+    const files = ciBlockFiles(args, ctx);
     const changedFiles = [];
     if (ciStale) {
-        const status = planCiFile(ciPath, buildCiWorkflowFile(args.model, args.testsDir, ctx.installedVersion), ciManagedBody(args.model, args.testsDir, ctx.installedVersion), CI_WORKFLOW_MARKER, false);
-        applyCiFile(ciPath, status);
+        applyCiFile(ciPath, planCiFile(ciPath, files.ci[0], files.ci[1], CI_WORKFLOW_MARKER, false, multi));
         changedFiles.push(ciPath);
     }
     if (conformStale) {
-        const status = planCiFile(conformPath, buildConformWorkflowFile(args.model, ctx.installedVersion), conformManagedBody(args.model, ctx.installedVersion), CONFORM_WORKFLOW_MARKER, false);
-        applyCiFile(conformPath, status);
+        applyCiFile(conformPath, planCiFile(conformPath, files.conform[0], files.conform[1], CONFORM_WORKFLOW_MARKER, false, multi));
         changedFiles.push(conformPath);
     }
     return { ok: true, changedFiles };
@@ -199,12 +354,191 @@ function applyConstitution(ctx) {
     writeFileSync(path, scaffoldConstitution(ctx.model.name));
     return { ok: true, changedFiles: [path] };
 }
+// ---- Step 6: ratified-signoff (MIL-259) — `--slice-ready` now requires a recorded `ratifiedBy`,
+// so a doc that reached `ready-to-implement` before sign-offs were recorded (pre-1.8) would
+// suddenly read not-ready. Grandfather exactly those: `version: 1` (never reratified — a
+// reratified doc has `version > 1` and is mid-sign-off, which only a human can resolve; see the
+// `ready-to-implement-no-ratifiedby` human item) with no `ratifiedBy`. A doc with no `version:`
+// at all is treated as version 1 (the schema's default). ----
+export const GRANDFATHERED_RATIFIER = "grandfathered (unsigned before em 1.14)";
+/** Pure text transform: inserts the grandfather sign-off after the `status:` line, using only
+ *  the key lines that are missing (a stray `ratifiedOn:` is kept as-is), in the file's own EOL.
+ *  `null` when the doc isn't a candidate (no frontmatter/status, or `ratifiedBy` already set). */
+export function applyGrandfatherSignoff(raw, ratifiedOn) {
+    const range = locateFrontmatterInner(raw);
+    if (!range)
+        return null;
+    const inner = raw.slice(range.innerStart, range.innerEnd);
+    const statusMatch = fieldLineRegex("status").exec(inner);
+    if (!statusMatch)
+        return null;
+    const byMatch = fieldLineRegex("ratifiedBy").exec(inner);
+    if (byMatch && normalizeFieldValue(byMatch[2]) !== null)
+        return null;
+    const onMatch = fieldLineRegex("ratifiedOn").exec(inner);
+    const statusEnd = statusMatch.index + statusMatch[0].length;
+    const eol = inner.slice(statusEnd).startsWith("\r\n") ? "\r\n" : "\n";
+    const value = `"${GRANDFATHERED_RATIFIER}"`;
+    // Edits against `inner`, applied highest index first so earlier offsets stay valid. A blank
+    // `ratifiedBy:` line is filled in place; missing lines are inserted right after `status:`.
+    const missing = [];
+    if (!byMatch)
+        missing.push(`ratifiedBy: ${value}`);
+    if (!onMatch)
+        missing.push(`ratifiedOn: ${ratifiedOn}`);
+    const edits = [];
+    if (missing.length > 0)
+        edits.push({ index: statusEnd, oldLen: 0, next: eol + missing.join(eol) });
+    if (byMatch)
+        edits.push({ index: byMatch.index, oldLen: byMatch[0].length, next: `${byMatch[1]}${value}` });
+    edits.sort((a, b) => b.index - a.index);
+    let updated = inner;
+    for (const e of edits)
+        updated = updated.slice(0, e.index) + e.next + updated.slice(e.index + e.oldLen);
+    return raw.slice(0, range.innerStart) + updated + raw.slice(range.innerEnd);
+}
+function grandfatherCandidates(ctx) {
+    const seen = new Set();
+    const out = [];
+    for (const d of nonContinuationDocs(ctx)) {
+        if (d.status !== "ready-to-implement" || d.ratifiedBy)
+            continue;
+        if ((d.version ?? 1) !== 1)
+            continue;
+        if (seen.has(d.path))
+            continue;
+        seen.add(d.path);
+        out.push({ key: d.key, path: d.path });
+    }
+    return out.sort((a, b) => a.key.localeCompare(b.key));
+}
+function detectRatifiedSignoff(ctx) {
+    const keys = grandfatherCandidates(ctx).map((c) => c.key);
+    if (keys.length === 0)
+        return { applicable: false, reason: "no version-1 ready-to-implement doc is missing a ratifiedBy" };
+    return {
+        applicable: true,
+        reason: `${keys.length} ready-to-implement doc(s) with no recorded sign-off (--slice-ready now requires one): ${keys.join(", ")} — em upgrade will record ratifiedBy: "${GRANDFATHERED_RATIFIER}"`,
+    };
+}
+function applyRatifiedSignoff(ctx) {
+    const candidates = grandfatherCandidates(ctx);
+    if (candidates.length === 0)
+        return { ok: false, message: "nothing to grandfather" };
+    const today = localIsoDate();
+    const writes = [];
+    for (const c of candidates) {
+        const file = join(ctx.baseDir, c.path);
+        const next = applyGrandfatherSignoff(readFileSync(file, "utf8"), today);
+        if (next === null)
+            return { ok: false, message: `${c.path}: could not locate status: in the frontmatter` };
+        writes.push({ file, text: next });
+    }
+    for (const w of writes)
+        writeFileSync(w.file, w.text);
+    return { ok: true, changedFiles: writes.map((w) => w.file) };
+}
+// ---- Step 7: system-manifest (MIL-235, R3) — system.yaml 1.0 -> 2.0. ----
+// The one mechanical step that writes OTHER models' files: the legacy manifest's seams become
+// `consumes` clauses on each consuming translation and its owners become `owner "…"` on each
+// member model's header, in the same single commit as the manifest rewrite (its `Em-Upgrade:`
+// trailer is what lets MIL-240's scope gate exempt that cross-model change set). Planned by
+// src/system/migrateManifest.ts over export documents; this half finds the manifest, loads the
+// members, verifies every rewritten model still compiles clean, and only then writes anything.
+/** The nearest `system.yaml` from `baseDir` upward, stopping at (and including) `repoRoot`. */
+function findSystemManifest(ctx) {
+    // Real paths on both sides: git reports the repo root symlink-resolved (macOS /var -> /private/var).
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return resolve(p);
+        }
+    };
+    const root = real(ctx.repoRoot);
+    let dir = real(ctx.baseDir);
+    for (;;) {
+        const candidate = join(dir, SYSTEM_MANIFEST_FILE);
+        if (existsSync(candidate))
+            return candidate;
+        if (dir === root)
+            return null;
+        const parent = dirname(dir);
+        const rel = relative(root, parent);
+        if (parent === dir || rel.startsWith("..") || isAbsolute(rel))
+            return null;
+        dir = parent;
+    }
+}
+function loadLegacyManifest(ctx) {
+    const path = findSystemManifest(ctx);
+    if (path === null)
+        return { path: null, reason: `no ${SYSTEM_MANIFEST_FILE} between the model and the repository root` };
+    const text = readFileSync(path, "utf8");
+    const parsed = parseManifest(text);
+    if (!parsed.ok)
+        return { path, reason: `${path} does not parse — run \`em system ${path}\` to see why` };
+    if (parsed.manifest.systemSchemaVersion !== LEGACY_SYSTEM_MANIFEST_SCHEMA_VERSION) {
+        return { path, reason: `${path} is already systemSchemaVersion "${parsed.manifest.systemSchemaVersion}"` };
+    }
+    return { path, text, manifest: parsed.manifest };
+}
+function detectSystemManifest(ctx) {
+    const loaded = loadLegacyManifest(ctx);
+    if (!("manifest" in loaded))
+        return { applicable: false, reason: loaded.reason };
+    const m = loaded.manifest;
+    return {
+        applicable: true,
+        reason: `${loaded.path} is systemSchemaVersion "1.0" — em upgrade will move its ${m.seams.length} seam(s) into \`consumes\` clauses, ` +
+            `its owner(s) onto the ${m.models.length} model header(s), and rewrite it to "2.0"`,
+    };
+}
+function applySystemManifest(ctx) {
+    const loaded = loadLegacyManifest(ctx);
+    if (!("manifest" in loaded))
+        return { ok: false, message: loaded.reason };
+    const baseDir = dirname(loaded.path);
+    const members = [];
+    for (const entry of loaded.manifest.models) {
+        const file = isAbsolute(entry.source) ? entry.source : join(baseDir, entry.source);
+        const source = loadSource(file);
+        if ("error" in source)
+            return { ok: false, message: `model "${entry.key}": ${source.error}` };
+        members.push({ key: entry.key, file, text: source.sourceKind === "em" ? readFileSync(file, "utf8") : null, doc: source.doc });
+    }
+    const plan = planManifestMigration(loaded.text, loaded.manifest, members);
+    if (!plan.ok)
+        return { ok: false, message: plan.message };
+    // Verify before write: every rewritten model must still compile with no errors.
+    for (const f of plan.files) {
+        try {
+            const { diagnostics } = compile(f.text);
+            if (hasErrors(diagnostics))
+                return { ok: false, message: `the rewrite of ${f.file} would introduce validation errors — aborting, nothing written` };
+        }
+        catch (e) {
+            return { ok: false, message: `the rewrite of ${f.file} does not parse (${e.message}) — aborting, nothing written` };
+        }
+    }
+    const reparsed = parseManifest(plan.manifestText);
+    if (!reparsed.ok)
+        return { ok: false, message: `the rewritten ${loaded.path} does not parse as 2.0 — aborting, nothing written` };
+    for (const f of plan.files)
+        writeFileSync(f.file, f.text);
+    writeFileSync(loaded.path, plan.manifestText);
+    return { ok: true, changedFiles: [...plan.files.map((f) => f.file), loaded.path] };
+}
 export const UPGRADE_STEPS = [
+    { id: "skill-plugin", sinceVersion: "1.14.0", detect: detectSkillPlugin, apply: applySkillPlugin },
     { id: "skill-bundle", sinceVersion: "1.7.0", detect: detectSkillBundle, apply: applySkillBundle },
     { id: "reaction-shape", sinceVersion: "1.8.0", detect: detectReactionShape, apply: applyReactionShape },
     { id: "state-file", sinceVersion: "1.13.0", detect: detectStateFile, apply: applyStateFile },
     { id: "ci-block", sinceVersion: "1.9.0", detect: detectCiBlock, apply: applyCiBlock },
     { id: "constitution", sinceVersion: "1.11.0", detect: detectConstitution, apply: applyConstitution },
+    { id: "ratified-signoff", sinceVersion: "1.14.0", detect: detectRatifiedSignoff, apply: applyRatifiedSignoff },
+    { id: "system-manifest", sinceVersion: "1.14.0", detect: detectSystemManifest, apply: applySystemManifest },
 ];
 function elementRefOf(ctx) {
     return (id) => ctx.refs.refById.get(id);
@@ -220,7 +554,7 @@ function nonContinuationDocs(ctx) {
         const { doc, continuationOf } = resolveSliceDocJoin(ctx.model, ctx.refs, slice, key, ctx.baseDir, elementRefOf(ctx));
         if (continuationOf !== null)
             return;
-        results.push({ key, status: doc.status, ratifiedBy: doc.ratifiedBy });
+        results.push({ key, status: doc.status, ratifiedBy: doc.ratifiedBy, version: doc.version, path: doc.path });
     });
     return results;
 }
@@ -251,14 +585,14 @@ function detectContinuationHasOwnDoc(ctx) {
 }
 function detectReadyNoRatifiedBy(ctx) {
     const keys = nonContinuationDocs(ctx)
-        .filter((d) => d.status === "ready-to-implement" && !d.ratifiedBy)
+        .filter((d) => d.status === "ready-to-implement" && !d.ratifiedBy && (d.version ?? 1) > 1)
         .map((d) => d.key)
         .sort();
     if (keys.length === 0)
         return null;
     return {
         id: "ready-to-implement-no-ratifiedby",
-        reason: `${keys.length} ready-to-implement doc(s) with no ratifiedBy: ${keys.join(", ")} — run \`em slice ratify --by <name>\` on each`,
+        reason: `${keys.length} ready-to-implement doc(s) with no ratifiedBy (version > 1, reratified and awaiting a fresh sign-off): ${keys.join(", ")} — run \`em slice ratify --by <name>\` on each`,
     };
 }
 function detectCoverageScopeDefault(ctx) {
@@ -301,6 +635,36 @@ function detectPredates16(ctx) {
         reason: `${plan.refusals.length} old-shape reaction site(s) can't be auto-migrated — run \`em migrate\` by hand, resolve the refusal(s), then re-run \`em upgrade\``,
     };
 }
+/** MIL-237: strict public types (briefing R7). Lists every field of a `public` element (or of a
+ *  declared type reachable from one) whose type is not in the fixed public type table and names
+ *  no declared type — the same set `em validate`'s `public-field-type-unresolved` errors on.
+ *  Detect-only: choosing the right type (or dropping `public`) is a modeling decision. */
+function detectPublicFieldTypesUnresolved(ctx) {
+    const found = findUnresolvedPublicFieldTypes(ctx.model);
+    if (found.length === 0)
+        return null;
+    const items = found.map((f) => `${f.owner.name}.${f.field}: ${f.type ?? "(no type)"}`);
+    return {
+        id: "public-field-types-unresolved",
+        reason: `${found.length} public field(s) without a public type: ${items.join(", ")} — give each a type from ` +
+            `${PUBLIC_SCALAR_TYPE_NAMES.join(", ")}, \`X[]\`, or a declared \`type\` (em 1.14 strict public types), or drop \`public\``,
+    };
+}
+/** MIL-232: the machine-level plugin registration is per user and cannot be done by `em upgrade`.
+ *  Fires when the `skill-plugin` step is pending (it will declare the plugin), or when the repo
+ *  declares the plugin at the installed version but the machine registry lacks it. */
+function detectPluginInstallLocally(ctx) {
+    const commands = pluginInstallCommands(ctx.installedVersion);
+    const snippet = `run \`${commands.join(" && ")}\` on each developer machine and in CI (the generated em-ci.yml does it)`;
+    if (detectSkillPlugin(ctx).applicable) {
+        return { id: "plugin-install-locally", reason: `the em plugin will be declared in .claude/settings.json but is registered per machine — after --apply, ${snippet}` };
+    }
+    const check = checkPlugin(ctx.repoRoot, ctx.installedVersion, claudePluginsDir());
+    if (check && check.findings.some((f) => f.code === "plugin-not-installed-locally")) {
+        return { id: "plugin-install-locally", reason: `the em plugin is declared but not registered on this machine — ${snippet}` };
+    }
+    return null;
+}
 const HUMAN_DETECTORS = [
     detectNoModelVersion,
     detectContinuationHasOwnDoc,
@@ -308,6 +672,8 @@ const HUMAN_DETECTORS = [
     detectCoverageScopeDefault,
     detectUnratifiedConstitution,
     detectPredates16,
+    detectPublicFieldTypesUnresolved,
+    detectPluginInstallLocally,
 ];
 export function detectHumanItems(ctx) {
     return HUMAN_DETECTORS.map((d) => d(ctx)).filter((x) => x !== null);
@@ -360,11 +726,17 @@ export function hasGitIdentity(repoRoot, runGit = realGit) {
     const email = runGit(["-C", repoRoot, "config", "user.email"]);
     return name.status === 0 && name.stdout.trim().length > 0 && email.status === 0 && email.stdout.trim().length > 0;
 }
-function gitCommitAll(repoRoot, message, runGit) {
+/** The commit trailer key every `em upgrade --apply` commit carries (MIL-235, R2):
+ *  `Em-Upgrade: <step-id>` (or `em-version` for the final stamp commit). Readers use
+ *  `git log --format=%(trailers:key=Em-Upgrade,valueonly)` — MIL-240's scope gate exempts files
+ *  changed only by such commits, since a mechanical migration may legitimately span models. */
+export const EM_UPGRADE_TRAILER = "Em-Upgrade";
+function gitCommitAll(repoRoot, message, trailerValue, runGit) {
     const add = runGit(["-C", repoRoot, "add", "-A"]);
     if (add.status !== 0)
         return { ok: false, message: `git add failed: ${(add.stderr || "").trim() || "unknown error"}` };
-    const commit = runGit(["-C", repoRoot, "commit", "-m", message]);
+    // Second `-m` = its own paragraph, which git reads as the trailer block.
+    const commit = runGit(["-C", repoRoot, "commit", "-m", message, "-m", `${EM_UPGRADE_TRAILER}: ${trailerValue}`]);
     if (commit.status !== 0)
         return { ok: false, message: `git commit failed: ${(commit.stderr || "").trim() || "unknown error"}` };
     return { ok: true };
@@ -383,14 +755,14 @@ function gitDiscardAll(repoRoot, runGit) {
 export function detectUpgrade(ctx) {
     const loaded = loadStateFile(ctx.baseDir);
     let recorded = null;
+    // MIL-257: an ABSENT state file is no longer an error — the `state-file` step scaffolds it — so
+    // `stateFileError` is `null` for it (the pending step's own reason carries the detail). It is
+    // set only for a file that exists but doesn't parse, and now names the file.
     let stateFileError = null;
-    if (!loaded.ok) {
-        stateFileError = loaded.message;
-    }
-    else {
+    if (loaded.ok) {
         const parsed = parseState(loaded.text);
         if (!parsed.ok)
-            stateFileError = parsed.message;
+            stateFileError = describeStateFileFailure(loaded.path, parsed.message);
         else
             recorded = parsed.state.emVersion;
     }
@@ -404,7 +776,7 @@ export function detectUpgrade(ctx) {
 }
 /**
  * `--apply`: detect, then apply every applicable mechanical step in fixed order, one commit
- * each (`em upgrade: <step-id> (<from> → <to>)`), stopping at the first failure with every
+ * each (`em upgrade: <step-id> (<from> → <to>)`, trailer `Em-Upgrade: <step-id>`), stopping at the first failure with every
  * prior commit intact and the failed step's own partial writes discarded. On full success,
  * writes `Em version: <to>` as one final commit — always, even when every step above was a
  * no-op, UNLESS the bullet already reads `<to>` (idempotent second run makes zero commits).
@@ -440,7 +812,7 @@ export function applyUpgrade(ctx, runGit = realGit) {
             return { ok: false, message: `em upgrade: step "${step.id}" failed — ${result.message}`, report, applied };
         }
         const message = `em upgrade: ${step.id} (${report.from.version} → ${report.to})`;
-        const commitResult = gitCommitAll(ctx.repoRoot, message, runGit);
+        const commitResult = gitCommitAll(ctx.repoRoot, message, step.id, runGit);
         if (!commitResult.ok) {
             return { ok: false, message: `em upgrade: step "${step.id}" applied but failed to commit — ${commitResult.message}`, report, applied };
         }
@@ -454,7 +826,7 @@ export function applyUpgrade(ctx, runGit = realGit) {
         if (stamped.ok && stamped.text !== loaded.text) {
             writeFileSync(loaded.path, stamped.text);
             const message = `em upgrade: em-version (${report.from.version} → ${report.to})`;
-            const commitResult = gitCommitAll(ctx.repoRoot, message, runGit);
+            const commitResult = gitCommitAll(ctx.repoRoot, message, "em-version", runGit);
             if (!commitResult.ok) {
                 return { ok: false, message: `em upgrade: writing Em version: failed to commit — ${commitResult.message}`, report, applied };
             }
@@ -463,14 +835,26 @@ export function applyUpgrade(ctx, runGit = realGit) {
     }
     return { ok: true, report, applied, emVersionCommit };
 }
+/** MIL-257: every cause that makes `--check` exit 1, each as one sentence, so the final line
+ *  always says why. Empty when there is no hard incompatibility. */
+export function hardIncompatibilityReasons(report) {
+    const reasons = [];
+    if (report.stateFileError !== null)
+        reasons.push(report.stateFileError);
+    for (const h of report.human)
+        if (h.id === "predates-1.6")
+            reasons.push(`predates-1.6: ${h.reason}`);
+    return reasons;
+}
 /** `--check` (what CI runs): exit-worthiness only — no writes. Hard incompatibilities are the
- *  ONLY thing that makes this fail: an unparseable/missing state file, or a `predates-1.6` human
- *  item (an old reaction shape `em migrate` itself refuses to touch). Every other human item —
- *  including the ordinary "some steps are applicable" case — is advisory, same as running
- *  `em upgrade` without `--apply` at all. */
+ *  ONLY thing that makes this fail: a state file that exists but is unparseable (a MISSING one is
+ *  scaffolded by the `state-file` step, MIL-257, so it is a pending step, not a failure), or a
+ *  `predates-1.6` human item (an old reaction shape `em migrate` itself refuses to touch). Every
+ *  other human item — including the ordinary "some steps are applicable" case — is advisory, same
+ *  as running `em upgrade` without `--apply` at all. `reasons` (MIL-257) is why `ok` is false. */
 export function checkUpgrade(ctx) {
     const report = detectUpgrade(ctx);
-    const hardIncompatibility = report.stateFileError !== null || report.human.some((h) => h.id === "predates-1.6");
-    return { ok: !hardIncompatibility, report };
+    const reasons = hardIncompatibilityReasons(report);
+    return { ok: reasons.length === 0, report, reasons };
 }
 //# sourceMappingURL=upgrade.js.map