@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/lineage-upgrade-cli.ts

@@ -20,7 +20,7 @@ import { WORKSPACE_UPGRADE_GATE_OP } from "../op/gate-name";
 import { LockError } from "./lineage-lock";
 import { applyStagedUpgrade, describeStaged, stageUpgrade, type ChantRunner, type StagedUpgrade } from "./lineage-upgrade";
 
-const USAGE = "chant workspace upgrade [<scope>] [--to <ref|dir>] [--allow-code] [--dry-run] [--output <patch file>] [--json]";
+const USAGE = "chant workspace upgrade [<scope>] [--to <ref|dir>] [--source <repo>[#<member>]] [--allow-code] [--dry-run] [--output <patch file>] [--json]";
 
 /** The exit code of a gated upgrade: the same as `chant run`'s gated run. */
 export const UPGRADE_GATED_EXIT = 3;
@@ -29,6 +29,8 @@ export interface UpgradeCommandOptions {
   root: string;
   scope?: string;
   to?: string;
+  /** Move the scope to another template (#2551). */
+  source?: string;
   allowCode?: boolean;
   dryRun?: boolean;
   output?: string;
@@ -53,6 +55,7 @@ export async function upgradeCommand(opts: UpgradeCommandOptions): Promise<Upgra
     root: opts.root,
     scope: opts.scope,
     to: opts.to,
+    ...(opts.source !== undefined ? { source: opts.source } : {}),
     allowCode: opts.allowCode,
     runChant: opts.runChant,
   });
@@ -72,7 +75,7 @@ export async function upgradeCommand(opts: UpgradeCommandOptions): Promise<Upgra
       );
     }
     if (!staged.changed && staged.checksOk) {
-      if (!opts.json) console.error(formatSuccess(`scope "${staged.scope}" is already at ${staged.to ?? "its source"}; nothing to upgrade`));
+      if (!opts.json) console.error(formatSuccess(`scope "${staged.gate}" is already at ${staged.to ?? "its source"}; nothing to upgrade`));
       return report("up-to-date", 0);
     }
     if (opts.output) writeFileSync(resolve(opts.output), staged.patch);
@@ -90,11 +93,11 @@ export async function upgradeCommand(opts: UpgradeCommandOptions): Promise<Upgra
       return report("dry-run", 0);
     }
 
-    const gate = staged.scope;
+    const gate = staged.gate;
     const check = await evaluateGate(opts.ledger ?? gitGateLedgerPort({ cwd: staged.repo }), {
       op: WORKSPACE_UPGRADE_GATE_OP,
       gate,
-      description: `upgrade ${staged.template} ${staged.from ?? ""} -> ${staged.to ?? ""} in scope ${staged.scope}`.replace(/\s+/g, " "),
+      description: `upgrade ${staged.template} ${staged.from ?? ""} -> ${staged.to ?? ""} in scope ${staged.member ?? staged.scope}`.replace(/\s+/g, " "),
       planDigest: staged.digest,
       ...(staged.governance ? { approval: staged.governance.approval } : {}),
       ...(opts.now ? { now: opts.now } : {}),
@@ -115,7 +118,7 @@ export async function upgradeCommand(opts: UpgradeCommandOptions): Promise<Upgra
 
     applyStagedUpgrade(staged);
     if (!opts.json) {
-      console.error(formatSuccess(`applied the approved upgrade of "${staged.scope}" (${staged.digest}), approved by ${check.resolution.resolvedBy}. Review and commit it.`));
+      console.error(formatSuccess(`applied the approved upgrade of "${staged.gate}" (${staged.digest}), approved by ${check.resolution.resolvedBy}. Review and commit it.`));
       if (staged.manualSteps.length > 0) {
         console.error(formatInfo(`${staged.manualSteps.length} manual step(s) are open; \`chant workspace check\` fails until each is merged and resolved.`));
       }
@@ -137,6 +140,7 @@ export async function runWorkspaceUpgrade(ctx: CommandContext): Promise<number>
       root: process.cwd(),
       scope: args.extraPositional,
       to: args.migrateTo,
+      source: args.source,
       allowCode: args.allowCode,
       dryRun: args.dryRun,
       output: args.output,

package/src/workspace/lineage-upgrade.test.ts

@@ -110,7 +110,7 @@ describe("chant workspace upgrade", () => {
       expect(staged.written.sort()).toEqual(["README.md", "src/new.ts"]);
       expect(staged.manualSteps).toEqual([]);
       expect(staged.changedPaths).toEqual([LOCK_FILE, "README.md", "src/a.ts", "src/new.ts"]);
-      expect(staged.digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+      expect(staged.digest).toMatch(/^jcs1-sha256:[0-9a-f]{64}$/);
       // The project's tree is untouched until the gate is approved.
       expect(read(proj, "README.md")).toBe("starter\n");
       expect(existsSync(join(proj, "src/new.ts"))).toBe(false);
@@ -571,3 +571,94 @@ describe("chant workspace upgrade with template parameters (#2627)", () => {
     await expect(stageUpgrade({ root: proj, to: "v2.0.0", runChant: passing })).rejects.toThrow(/region has no default/);
   });
 });
+
+describe("chant workspace upgrade of a member scope (#2550)", () => {
+  let ws: string;
+  const declaration = {
+    name: "ws",
+    schema: 1,
+    members: [
+      { name: "shop", dir: "shop", kind: "other", because: "made from a template" },
+      { name: "plain", dir: "plain", kind: "other", because: "written by hand" },
+    ],
+  };
+
+  beforeEach(async () => {
+    ws = join(root, "ws");
+    mkdirSync(ws);
+    git(ws, ["init", "-q", "-b", "main"]);
+    put(ws, "chant.workspace.json", JSON.stringify(declaration));
+    put(ws, "plain/readme.md", "by hand\n");
+    const made = await initFromCommand({ from: `${tpl}@v1.0.0`, path: join(ws, "shop") });
+    expect(made.error).toBeUndefined();
+    git(ws, ["add", "-A"]);
+    git(ws, ["commit", "-q", "-m", "workspace"]);
+  });
+
+  test("upgrades the member from the workspace root, writes only inside it, and gates under the member's name", async () => {
+    release("v2.0.0", { "README.md": "starter v2\n", "src/new.ts": "new\n" });
+    const l = ledger();
+    const result = await upgradeCommand({ root: ws, scope: "shop", to: "v2.0.0", runChant: passing, ledger: l, json: true });
+    expect(result.outcome).toBe("gated");
+    expect(result.exitCode).toBe(3);
+    expect(l.pending[0].gate).toBe("shop");
+    const staged = result.staged!;
+    expect(staged.member).toBe("shop");
+    expect(staged.scope).toBe(".");
+    expect(staged.changedPaths.every((p) => p.startsWith("shop/"))).toBe(true);
+
+    l.approve(staged.digest, new Date().toISOString());
+    const applied = await upgradeCommand({ root: ws, scope: "shop", to: "v2.0.0", runChant: passing, ledger: l, json: true });
+    expect(applied.outcome).toBe("applied");
+    expect(read(ws, "shop/README.md")).toBe("starter v2\n");
+    expect(read(ws, "plain/readme.md")).toBe("by hand\n");
+    expect(readLock(join(ws, "shop"))!.scopes["."].ref).toBe("v2.0.0");
+  });
+
+  test("a member is named by directory too, and a member with no lock is refused with the reason", async () => {
+    release("v2.0.0", { "README.md": "starter v2\n" });
+    const staged = await stageUpgrade({ root: ws, scope: "shop/", to: "v2.0.0", runChant: passing });
+    try {
+      expect(staged.member).toBe("shop");
+    } finally {
+      staged.dispose();
+    }
+    await expect(stageUpgrade({ root: ws, scope: "plain", runChant: passing })).rejects.toThrow(/member "plain" \(plain\) has no \.chant\/workspace\.lock\.json, so it was not made from a template/);
+    await expect(stageUpgrade({ root: ws, scope: "nobody", runChant: passing })).rejects.toThrow(/no .*workspace\.lock\.json/);
+  });
+
+  test("a scope the root lock holds is used as written, even when a member has the same directory", async () => {
+    // The root lock records the member's subtree as a scope: the member's own lock is not consulted.
+    const own = readLock(join(ws, "shop"))!;
+    // The recorded repository is relative to the lock's directory, so point it at the template as the root sees it.
+    const moved = { ...own.scopes["."], source: { ...own.scopes["."].source, url: tpl } } as (typeof own.scopes)["."];
+    writeLock(ws, { lockVersion: own.lockVersion, scopes: { shop: moved } });
+    git(ws, ["rm", "-rq", "--cached", "shop/.chant"]);
+    rmSync(join(ws, "shop/.chant"), { recursive: true });
+    commitProject2();
+    release("v2.0.0", { "README.md": "starter v2\n" });
+    const staged = await stageUpgrade({ root: ws, scope: "shop", to: "v2.0.0", runChant: passing });
+    try {
+      expect(staged.member).toBeUndefined();
+      expect(staged.scope).toBe("shop");
+      expect(staged.written).toEqual(["README.md"]);
+      expect(staged.changedPaths.sort()).toEqual([".chant/workspace.lock.json", "shop/README.md"]);
+    } finally {
+      staged.dispose();
+    }
+  });
+
+  test("a scope made by init --template is refused with its reason", async () => {
+    const lock = readLock(join(ws, "shop"))!;
+    lock.scopes["."] = { ...lock.scopes["."], kind: "template", source: { type: "lexicon", lexicon: "aws", template: "basic" } as never, template: "aws/basic" } as never;
+    writeLock(join(ws, "shop"), lock);
+    git(ws, ["add", "-A"]);
+    git(ws, ["commit", "-q", "-m", "lock"]);
+    await expect(stageUpgrade({ root: ws, scope: "shop", runChant: passing })).rejects.toThrow(/made by `chant init --template` \(aws\/basic\) is refused: .*no versioned source/);
+  });
+
+  function commitProject2(): void {
+    git(ws, ["add", "-A"]);
+    git(ws, ["commit", "-q", "-m", "root lock"]);
+  }
+});

package/src/workspace/lineage-upgrade.ts

@@ -40,7 +40,7 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { ResolvedGateApproval } from "../op/gate-approval";
 import { checkLineage, findingKey, type CheckFinding } from "./lineage-check";
-import { dirLabel, git, parseDirSpec, readTemplateDir, readTemplateTree, recordedDirPath } from "./lineage-init";
+import { dirLabel, git, parseDirSpec, parseTemplateSource, portableUrl, readTemplateDir, readTemplateTree, recordedDirPath } from "./lineage-init";
 import {
   LOCK_FILE,
   LockError,
@@ -60,6 +60,7 @@ import { reportPlan, runChantMigrations, type ChantMigrationReport } from "./cha
 import { readDeclaration, readerVersion, WorkspaceReadError } from "./declaration";
 import { assertCodeAllowed, planMigrations, runMigration, splitMigrations, type LoadedMigration } from "./lineage-migrations";
 import { applyUpstream, type UpdateResult } from "./lineage-update";
+import { pathsInsideNested } from "./nesting";
 import { carryParameters, readManifest, substituteParameters } from "./template-manifest";
 import { repinSubstituted, type RepinnedRecord } from "./template-pins";
 import { workingTree } from "./tree";
@@ -113,7 +114,11 @@ export const spawnChant: ChantRunner = (command, cwd) =>
 export interface UpgradeOptions {
   /** The directory holding `.chant/workspace.lock.json`. */
   root: string;
-  /** The scope to upgrade: `"."` or a vendor scope's directory. */
+  /**
+   * The scope to upgrade: `"."`, a scope of the lock at `root` (a vendor
+   * scope's directory, or a member subtree recorded in it), or the name or
+   * directory of a declared member that keeps a lock of its own (#2550).
+   */
   scope?: string;
   /**
    * The target ref (git) or label (vendor). Defaults to the ref the scope is
@@ -124,6 +129,12 @@ export interface UpgradeOptions {
   to?: string;
   /** Run migrations whose body is code. */
   allowCode?: boolean;
+  /**
+   * `<repo>[#<member>]`: move the scope to this template (#2551). The chain
+   * starts with the new template's bridge migration from the scope's current
+   * template. Needs `to`, and a git scope.
+   */
+  source?: string;
   /** Replaces the child-process build and lint. For tests. */
   runChant?: ChantRunner;
 }
@@ -138,8 +149,15 @@ export interface GovernanceChange {
 }
 
 export interface StagedUpgrade {
+  /** The scope in the lock that was upgraded: `"."` for a member with a lock of its own. */
   scope: string;
+  /** The declared member whose own lock this upgraded, when the scope argument named one. */
+  member?: string;
+  /** What the gate and the proposal branch are named: the member, else the scope. */
+  gate: string;
   template: string;
+  /** Set when the upgrade moves the scope to another template (`--source`, #2551): that template's id. */
+  switchedTo?: string;
   kind: Lineage["kind"];
   /** The pin before and after. */
   from: string | null;
@@ -226,11 +244,13 @@ function instantiate(
  * fail (a server that refuses fetches by commit); the base is then left empty,
  * and every edited file the template changed becomes a manual step.
  */
-function fetchGit(root: string, lineage: Lineage, ref: string): Upstream {
+function fetchGit(root: string, lineage: Lineage, ref: string, onto?: Onto): Upstream {
   const source = lineage.source;
   if (source.type !== "git") throw new UpgradeError("not a git source");
-  const url = source.url.startsWith(".") ? resolve(root, source.url) : source.url;
-  const label = `${source.repo}@${ref}`;
+  const baseUrl = source.url.startsWith(".") ? resolve(root, source.url) : source.url;
+  // With --source (#2551) the target comes from the other template; the base always from the scope's own.
+  const url = onto ? onto.url : baseUrl;
+  const label = `${onto ? onto.repo : source.repo}@${ref}`;
   const scratch = mkdtempSync(join(tmpdir(), "chant-upgrade-"));
   try {
     git(scratch, ["init", "-q"]);
@@ -242,7 +262,7 @@ function fetchGit(root: string, lineage: Lineage, ref: string): Upstream {
       throw new UpgradeError(`could not fetch ${label}${stderr ? `: ${stderr}` : ""}`);
     }
     const commit = git(scratch, ["rev-parse", "FETCH_HEAD^{commit}"]);
-    const target = readTemplateTree(scratch, commit, source.path, label);
+    const target = readTemplateTree(scratch, commit, onto ? onto.path : source.path, label);
 
     const raw = new Map<string, Buffer>();
     const executable = new Set<string>();
@@ -258,7 +278,7 @@ function fetchGit(root: string, lineage: Lineage, ref: string): Upstream {
     const baseCommit = lineage.address?.commit;
     if (baseCommit && baseCommit !== commit) {
       try {
-        git(scratch, ["fetch", "-q", "--depth", "1", url, baseCommit]);
+        git(scratch, ["fetch", "-q", "--depth", "1", baseUrl, baseCommit]);
         const oldLabel = `${source.repo}@${baseCommit.slice(0, 12)}`;
         const old = readTemplateTree(scratch, baseCommit, source.path, oldLabel);
         // The base is rebuilt the way init wrote it: the old version's
@@ -297,7 +317,7 @@ function dirRefusal(lineage: Lineage, why: string): UpgradeError {
   const source = lineage.source as Extract<LineageSource, { type: "dir" }>;
   return new UpgradeError(
     `${why}. The scope was made from the directory ${dirLabel(source.path, source.member)}, which has no git history to rebuild a merge base from. ` +
-      `Upgrade with --to <dir> while ${source.path} still holds the files the scope was made from, or adopt the scope into a git lineage with \`chant workspace adopt-lineage\` (#2551).`,
+      `Upgrade with --to <dir> while ${source.path} still holds the files the scope was made from, or move the scope onto the git repository the directory was copied from with \`chant workspace adopt-lineage --from <repo>[#<member>]\`.`,
   );
 }
 
@@ -359,11 +379,19 @@ function readDir(root: string, lineage: Lineage, to: string | undefined): Upstre
   };
 }
 
-async function fetchUpstream(root: string, lineage: Lineage, ref: string | undefined): Promise<Upstream> {
+/** The template an upgrade moves the scope to (`--source`, #2551). */
+interface Onto {
+  url: string;
+  repo: string;
+  path?: string;
+  id: string;
+}
+
+async function fetchUpstream(root: string, lineage: Lineage, ref: string | undefined, onto?: Onto): Promise<Upstream> {
   const source = lineage.source;
   if (source.type === "git") {
     if (!ref) throw new UpgradeError("the scope records no ref; pass --to <ref>");
-    return fetchGit(root, lineage, ref);
+    return fetchGit(root, lineage, ref, onto);
   }
   if (source.type === "local" || source.type === "archive") {
     const { resolveVendorSource } = await import("../cli/commands/vendor");
@@ -372,7 +400,7 @@ async function fetchUpstream(root: string, lineage: Lineage, ref: string | undef
   }
   if (source.type === "dir") return readDir(root, lineage, ref);
   throw new UpgradeError(
-    `scope made by \`chant init --template\` (${lineage.template}) cannot be upgraded yet: its merge base is the older lexicon's render, which is not available offline. Upgrade git-sourced and vendor scopes for now.`,
+    `scope made by \`chant init --template\` (${lineage.template}) is refused: it came from a lexicon's built-in template, which has no versioned source to fetch, and the merge base would be the render of the chant version that wrote it, which chant cannot rebuild offline. Scopes made by \`chant init --from\` (a git repository or a directory) and \`chant vendor\` scopes upgrade.`,
   );
 }
 
@@ -486,6 +514,40 @@ function chantMemberDirs(dir: string): string[] {
   }
 }
 
+/**
+ * Resolve the scope argument against `root` (#2550). A scope the lock at
+ * `root` holds is used as it is. Otherwise a member the workspace
+ * declaration names (by name or directory) that keeps a lock of its own is
+ * upgraded from its directory, as the project it is, so its patch, gate and
+ * build stay inside it. A member without a lock was not made from a template.
+ */
+export function resolveUpgradeTarget(root: string, scopeArg: string | undefined): { root: string; scope: string; member?: string } {
+  const scope = scopeKey(scopeArg ?? ".");
+  const lock = readLock(root);
+  if (lock?.scopes[scope]) return { root, scope };
+  if (scope !== ".") {
+    let declared: Array<{ name: string; dir: string; kind: string }> = [];
+    try {
+      declared = readDeclaration(workingTree(root)).members;
+    } catch (err) {
+      if (!(err instanceof WorkspaceReadError)) throw err;
+    }
+    const hit = declared.find((m) => m.dir !== "." && (m.name === scopeArg || scopeKey(m.dir) === scope));
+    if (hit?.kind === "workspace") {
+      // A nested workspace upgrades itself; the outer one never writes inside it (D2, #2551).
+      throw new UpgradeError(`member "${hit.name}" is a nested workspace, which upgrades itself: run chant workspace upgrade in ${hit.dir}`);
+    }
+    if (hit) {
+      const memberRoot = join(root, hit.dir);
+      if (readLock(memberRoot)) return { root: memberRoot, scope: ".", member: hit.name };
+      throw new UpgradeError(
+        `member "${hit.name}" (${hit.dir}) has no ${LOCK_FILE}, so it was not made from a template and has nothing to upgrade. \`chant init --from <template> ${hit.dir}\` writes one; \`chant workspace adopt-lineage\` is for an older member.`,
+      );
+    }
+  }
+  return { root, scope };
+}
+
 /**
  * Stage an upgrade: steps 1 to 5 and the digest of step 6. Nothing in the
  * project's tree changes. The caller decides the gate, then applies the patch
@@ -493,8 +555,7 @@ function chantMemberDirs(dir: string): string[] {
  * and always calls `dispose()`.
  */
 export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgrade> {
-  const root = resolve(options.root);
-  const scope = scopeKey(options.scope ?? ".");
+  const { root, scope, member } = resolveUpgradeTarget(resolve(options.root), options.scope);
   const lock = readLock(root);
   if (!lock) throw new UpgradeError(`no ${LOCK_FILE} in ${root}`);
   const lineage = lock.scopes[scope];
@@ -534,16 +595,29 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
     );
   }
 
+  // A move to another template (#2551): a git scope only, and to a named ref.
+  let onto: Onto | undefined;
+  if (options.source !== undefined) {
+    const spec = parseTemplateSource(options.source, root, "--source");
+    if (spec.ref !== undefined) throw new UpgradeError(`--source ${options.source}: name the version with --to, not "@${spec.ref}"`);
+    if (options.to === undefined) throw new UpgradeError("--source moves the scope to another template, so it needs --to <ref>: a version of that template");
+    if (lineage.source.type !== "git") {
+      throw new UpgradeError(`scope "${scope}" has a ${lineage.source.type} source; only a git scope moves to another template. A directory scope moves onto git with chant workspace adopt-lineage first.`);
+    }
+    onto = { url: spec.url, repo: spec.repo, ...(spec.member ? { path: spec.member } : {}), id: spec.id };
+  }
+  const switching = onto !== undefined && onto.id !== lineage.template;
+
   // 1. Fetch. A directory source has no ref: `--to` names the directory.
   const fromDir = lineage.source.type === "dir";
   const ref = fromDir ? undefined : options.to ?? lineage.ref;
-  const upstream = await fetchUpstream(root, lineage, fromDir ? options.to : ref);
+  const upstream = await fetchUpstream(root, lineage, fromDir ? options.to : ref, onto);
 
   // 2. The merge base, offline from here on.
   const base = rebuildBase(join(root, scope), lineage, upstream.base);
 
   // Plan the chain before anything is staged, so a gap refuses early.
-  const plan = lineage.kind === "template" ? planMigrations(lineage, ref, upstream.migrations) : { chain: [] };
+  const plan = lineage.kind === "template" ? planMigrations(lineage, ref, upstream.migrations, onto?.id) : { chain: [] };
   assertCodeAllowed(plan.chain, !!options.allowCode);
 
   // 3. The worktree, inside the project so the project's packages resolve.
@@ -613,6 +687,10 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
     }
     if (upstream.commit) staged.address = { ...staged.address!, commit: upstream.commit, tree: upstream.tree };
     if (upstream.source) staged.source = upstream.source;
+    if (onto) {
+      staged.template = onto.id;
+      staged.source = { type: "git", repo: onto.repo, url: portableUrl(onto.url, root), ...(onto.path ? { path: onto.path } : {}) };
+    }
     writeLock(worktreeProject, next);
     const lockText = renderLock(next);
 
@@ -621,10 +699,23 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
     if (!lockTracked) gitOut(worktree, ["rm", "--cached", "-q", "--ignore-unmatch", "--", lockRepoPath]);
     const patch = gitOut(worktree, ["diff", "--cached", "--binary", "--full-index", "--no-color", "--no-ext-diff", head]);
     const changedPaths = gitOut(worktree, ["diff", "--cached", "--name-only", "-z", head]).split("\0").filter(Boolean).sort();
+    // An upgrade writes inside its scope and the lock that records it, and nowhere else.
+    const outside = changedPaths.filter((p) => scopeRepoPath !== "." && p !== lockRepoPath && p !== scopeRepoPath && !p.startsWith(`${scopeRepoPath}/`));
+    if (outside.length > 0) {
+      throw new UpgradeError(`the upgrade would change ${outside.slice(0, 5).join(", ")}${outside.length > 5 ? ", ..." : ""}, outside the scope "${scopeRepoPath}". An upgrade writes only inside its own scope.`);
+    }
     const lockChanged = !lockTracked && lockText !== readFileSync(join(root, LOCK_FILE), "utf-8");
     const changed = patch.length > 0 || lockChanged;
     const digest = computePlanDigest(UPGRADE_PLAN_KIND, lockTracked ? { scope, patch } : { scope, patch, lock: lockText });
 
+    // The outer workspace never writes inside a nested one (D2, #2551): that one upgrades itself.
+    const inNested = pathsInsideNested(worktreeProject, projectRel, changedPaths);
+    if (inNested.length > 0) {
+      throw new UpgradeError(
+        `the upgrade would change files inside the nested workspace ${inNested[0].member} (${inNested.slice(0, 5).map((p) => p.path).join(", ")}). A nested workspace upgrades itself with its own chant workspace upgrade, and the outer one never writes inside it.`,
+      );
+    }
+
     // Governance: decided by the rules at HEAD, never by the upgraded files.
     const governed = changedPaths.filter(isGovernancePath);
     let governance: GovernanceChange | null = null;
@@ -682,7 +773,10 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
 
     return {
       scope,
+      ...(member !== undefined ? { member } : {}),
+      gate: member ?? scope,
       template: lineage.template,
+      ...(switching ? { switchedTo: onto!.id } : {}),
       kind: lineage.kind,
       from: fromDir ? sourcePin(lineage.source) : lineage.ref ?? null,
       to: fromDir ? sourcePin(staged.source) : staged.ref ?? null,
@@ -781,7 +875,8 @@ export function commitStagedUpgrade(staged: StagedUpgrade, branch: string, messa
 export function describeStaged(staged: StagedUpgrade): string[] {
   const lines: string[] = [];
   const at = (p: string) => (staged.scope === "." ? p : `${staged.scope}/${p}`);
-  lines.push(`${staged.scope}  ${staged.template}  ${staged.from ?? "(no ref)"} -> ${staged.to ?? "(no ref)"}`);
+  lines.push(`${staged.gate}  ${staged.template}  ${staged.from ?? "(no ref)"} -> ${staged.to ?? "(no ref)"}`);
+  if (staged.switchedTo) lines.push(`  template: ${staged.template} -> ${staged.switchedTo}`);
   const chantIds = new Set(staged.chantMigrations.map((m) => m.id));
   for (const id of staged.migrations) if (!chantIds.has(id)) lines.push(`  migration: ${id}`);
   for (const m of staged.chantMigrations) {