@opum-ai/lore 0.1.0

package/src/commands/rename.ts

@@ -0,0 +1,585 @@
+/**
+ * commands/rename.ts — `lore rename <oldId> <newId> [--dry-run]`.
+ *
+ * The thin, side-effecting layer over the pure inbound-rewrite engine (cli-surface §rename,
+ * LORE-35 AC#2): it parses the command's own arguments, loads the `docs/` bundle graph, asks
+ * {@link rewriteInbound} for the move plan — relocate the concept and repoint every inbound
+ * cross-link and frontmatter ref — regenerates the affected `index.md` listing blocks against the
+ * post-rename graph, writes the changed files, moves the renamed file and deletes its old path
+ * (unless `--dry-run`), renders the report, and returns the exit code. All file I/O lives here;
+ * every link/ref judgement lives in `core/rewrite.ts`, and the byte-stable concept serialization
+ * in `core/concept.ts`.
+ *
+ * Index regeneration composes on top of the rewrite: the renamed concept's old directory loses a
+ * listing entry and its new directory gains one, so the bundle's `index.md` hubs are regenerated
+ * from the **post-rename** graph ({@link generateIndexes}) and spliced into the already-rewritten
+ * index bytes — only index files whose bytes actually change are written, so an unrelated, already
+ * canonical hub is never churned.
+ *
+ * **Renaming a concept linked to Backlog tasks (LORE-24, ADR-0009 §2) also moves each linked
+ * task's `doc:<conceptId>` label and `--doc` path** to the new id/path, via `commands/link.ts`'s
+ * {@link moveBackRefs} — the file move commits first (it needs no Backlog round-trip and never
+ * depends on the back-ref move's outcome), then the per-task Backlog edits run, so a Backlog
+ * failure can never strand an already-renamed file. A concept with no `tasks:` entries never
+ * constructs a `BacklogAdapter` at all — renaming an unlinked doc has exactly the same
+ * zero-Backlog-dependency behavior it always did. `--dry-run` skips the Backlog move entirely
+ * (it previews the file-level plan only, not a Backlog-side preview).
+ *
+ * A bad flag, a missing/duplicate id, or a `newId` that escapes the `docs/` bundle root (checked
+ * at argument-parsing time, before any bundle load, as defense-in-depth alongside
+ * `rewriteInbound`'s own identical engine-layer guard — LORE-78/LORE-79/LORE-80) is a `usage`
+ * error (exit 2); an absent `oldId` a `not_found` (exit 3, from the engine); an already-taken
+ * `newId` a `conflict` (exit 5); a failed back-ref move is `drift` (exit 6, same as
+ * `link`/`unlink`) — all funnel through the router's one error seam like every command.
+ *
+ * Every retargeted inbound link is still repointed to the new location — `rename` DELETES the old
+ * file, so skipping a retarget would leave a genuinely dangling link, never an option. But when the
+ * link's visible text still names the OLD id (a citation left over from before the rename), that
+ * would silently leave the prose and the link disagreeing. The engine flags each such
+ * {@link LinkTextMismatch} in the plan; this command renders one stderr `warning:` line per mismatch
+ * via {@link renderLinkTextMismatchWarning} (LORE-262) — purely advisory, no effect on the retarget
+ * or the exit code.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join, posix, win32 } from "node:path";
+import type { BacklogAdapter } from "../adapters/backlog";
+import { type BundleGraph, buildGraph, loadBundle, toRefList, UNREADABLE_DIRECTORY_WARNING } from "../core/bundle";
+import { type Concept, idFromPath, parseConcept } from "../core/concept";
+import { generateIndexes, INDEX_BLOCK_BEGIN, INDEX_BLOCK_END, locateManagedBlock } from "../core/indexes";
+import { loadProfile, type Profile } from "../core/profile";
+import {
+  escapesRoot,
+  isDriveRelative,
+  type RewritePlan,
+  renderLinkTextMismatchWarning,
+  resolvesToRoot,
+  rewriteInbound,
+} from "../core/rewrite";
+import { DOCS_DIR } from "../core/scaffold";
+import { EXIT_CODES, EXIT_OK, LoreError, WarningCollector, type Writer } from "../errors";
+import { emit, type OutputContext, type Renderable } from "../output";
+import { type BacklogCommitResult, commitBacklogFiles, type GitSpawn, renderBacklogCommitLine } from "../state";
+import { assertNotReservedStem, parseCommandArgs, usage } from "./args";
+import { canonicalIdentity, readIndexBytes } from "./discover";
+import { assertNoSymlinkInAnyPath, ensureDir, moveFile, writeFileOverwriting } from "./fswrite";
+import {
+  assertNoCommaInId,
+  assertNoLabelCaseCollision,
+  dedupeTaskIds,
+  defaultAdapter,
+  type MovedBackRef,
+  moveBackRefs,
+} from "./link";
+
+/** The reserved index file name, regenerated from the post-rename graph rather than spliced as a link. */
+const INDEX_FILE = "index.md";
+
+/** Options for {@link runRename}; `root` and the streams are injectable for tests. */
+export interface RenameOptions {
+  /** The repo root the `docs/` bundle resolves against. */
+  root: string;
+  /** The resolved output mode/color (from `output.ts`). */
+  output: OutputContext;
+  /** The command's normalized positional + flag tokens from Commander. */
+  args: readonly string[];
+  /** stdout sink; defaults to `process.stdout`. */
+  stdout?: Writer;
+  /** stderr sink for bundle-load advisories; defaults to `process.stderr`. */
+  stderr?: Writer;
+  /** The Backlog adapter; defaults to the real `backlog` binary on PATH. Only ever constructed (and only ever injected in tests) when the renamed concept has `tasks:` entries. */
+  adapter?: BacklogAdapter;
+  /** The git-write seam (`state.ts`) for committing `backlog/` after the back-reference move; defaults to the real `git` binary. Only used when the concept is linked and not a `--dry-run`. Injected in tests. */
+  gitSpawn?: GitSpawn;
+}
+
+/** The parsed form of `lore rename`'s arguments. */
+interface RenameArgs {
+  /** The concept id (or path) to rename from. */
+  oldId: string;
+  /** The concept id (or path) to rename to. */
+  newId: string;
+  /** `--dry-run`: report what would change, write nothing. */
+  dryRun: boolean;
+}
+
+/** One written file, for the report. */
+interface ChangedFile {
+  /** Repo-relative POSIX path of the written file. */
+  readonly path: string;
+}
+
+/** The `rename.result` payload: the relocation and the files written. */
+export interface RenameReport {
+  /** The renamed file's old repo-relative path. */
+  readonly from: string;
+  /** The renamed file's new repo-relative path. */
+  readonly to: string;
+  /** Every file written (the moved file, repointed inbound files, regenerated indexes), ascending. */
+  readonly files: readonly ChangedFile[];
+  /** How many files changed (== `files.length`). */
+  readonly filesChanged: number;
+  /** Every linked task's back-reference move outcome (empty when the concept had no `tasks:`, or under `--dry-run`, which never attempts the Backlog move). */
+  readonly backRefs: readonly MovedBackRef[];
+  /** The `backlog/` commit outcome — `{committed: false, files: []}` when no back-reference was moved (unlinked concept, `--dry-run`, or every task already current). */
+  readonly backlogCommit: BacklogCommitResult;
+  /** Whether this was a `--dry-run` (nothing was written). */
+  readonly dryRun: boolean;
+}
+
+/**
+ * Run `lore rename`: parse the arguments, load the bundle, plan the move + inbound rewrite,
+ * regenerate the affected indexes, write the changed files and relocate the renamed file (unless
+ * `--dry-run`), move every linked task's Backlog back-reference to the new id/path, emit the
+ * `rename.result`, and return the exit code. A bad flag or duplicate id throws a `usage`
+ * {@link LoreError} (exit `2`); an absent `oldId` a `not_found` (exit `3`); a taken `newId` a
+ * `conflict` (exit `5`); a failed back-reference move `drift` (exit `6`).
+ */
+export async function runRename(options: RenameOptions): Promise<number> {
+  const parsed = parseRenameArgs(options.args);
+  const oldId = idFromPath(parsed.oldId);
+  const newId = idFromPath(parsed.newId);
+  if (oldId === newId) {
+    throw new LoreError("usage", "the old and new id are the same", "pass a different target id to rename to", {
+      id: oldId,
+    });
+  }
+  // A concept may not be renamed FROM or ONTO a reserved, machine-owned file name (index.md/log.md):
+  // those are regenerated wholesale, so renaming away from one would silently delete it (LORE-81) and
+  // renaming onto one would silently clobber the relocated content. Mirrors supersede.ts's identical
+  // two-sided check.
+  assertNotReservedStem(oldId, "rename from");
+  assertNotReservedStem(newId, "rename to");
+
+  const docsRoot = join(options.root, DOCS_DIR);
+  const advisories = new WarningCollector();
+  // Loaded once and threaded through every downstream serialize/re-parse (rewriteInbound below,
+  // buildPostRenameGraph's own re-parse) so a rewritten concept is never written under one profile
+  // and re-read under another (LORE-88) — before this fix, only this initial load honored a
+  // project's custom `.lore/profile.toml` (LORE-84); rewriteInbound's internal serialize/re-parse
+  // silently fell back to the built-in default, which could reject an inbound concept whose custom-
+  // profile-shaped frontmatter (e.g. a scalar `tasks:` field) is perfectly valid under the project's
+  // own schema.
+  const profile = loadProfile({ root: options.root });
+  const graph = loadBundle(docsRoot, { warnings: advisories, profile });
+  // Flushed immediately (not at the end, as this command previously did) so a skipped-directory
+  // warning naming the exact path/reason survives on the fail-loud path below it feeds (LORE-82),
+  // mirroring how `context.ts`/`graph.ts` flush before a load-warning-explained not_found throw.
+  advisories.flush({ color: options.output.color, stderr: options.stderr });
+  // rewriteInbound can only repoint the inbound links it can SEE — a directory `loadBundle` had to
+  // skip (unreadable) may hide a concept that links to `oldId`, so committing this rewrite would
+  // silently report success while leaving that concept's link stale/broken. Refuse rather than
+  // guess: the graph is not the complete bundle, so no rewrite over it is safe to commit (LORE-82).
+  if (advisories.has(UNREADABLE_DIRECTORY_WARNING)) {
+    throw new LoreError(
+      "validation",
+      "the bundle graph is incomplete: an unreadable directory was skipped while loading it",
+      "fix filesystem permissions on the directory named in the warning above and retry — rename cannot safely rewrite inbound links without a complete view of the bundle",
+      { docsRoot },
+    );
+  }
+
+  // Plan the move + inbound rewrite (throws not_found if oldId is absent / conflict if newId is a
+  // concept), then regenerate the index hubs against the post-rename graph and merge them over the
+  // plan's writes (index regen wins).
+  const plan = rewriteInbound(graph, oldId, newId, { move: true, profile });
+  // The engine's conflict check is graph-only; guard the filesystem too, so a target that collides
+  // with a NON-concept file (a hand-written index, a doc with no/invalid frontmatter) or with a
+  // concept differing only in case (which a case-sensitive `Map.has` misses) is never overwritten.
+  // A target resolving to the *same* inode as the source is a legitimate case-only rename, allowed.
+  assertTargetFree(plan, docsRoot);
+
+  // Every retargeted inbound link is still repointed exactly as before (LORE-262 AC#2 — no
+  // regression); a link whose visible text still names the OLD id is additionally called out as a
+  // stderr warning so the author can review the prose, rather than the mismatch shipping silently
+  // (LORE-262 AC#1). Skipping the retarget instead is not an option here: `lore rename` DELETES the
+  // old file, so a skipped link would become a genuinely dangling one — worse than a stale-reading
+  // text. A FRESH collector, not `advisories` — that one was already flushed above (LORE-82's
+  // ordering), and `flush()` is non-draining, so reusing it here would re-print the earlier
+  // bundle-load warnings a second time.
+  if (plan.textMismatches.length > 0) {
+    const mismatchWarnings = new WarningCollector();
+    for (const mismatch of plan.textMismatches) {
+      mismatchWarnings.add(renderLinkTextMismatchWarning(mismatch));
+    }
+    mismatchWarnings.flush({ color: options.output.color, stderr: options.stderr });
+  }
+
+  // The Backlog back-ref move's own preconditions, checked up front (before any write) — but only
+  // when the move will actually be attempted: a linked concept (an unlinked rename never touches
+  // Backlog) that isn't a `--dry-run` (which previews the file-level plan only and never attempts
+  // the Backlog-side move either — see below). Mirrors link.ts's `!noBackRef` scoping.
+  const oldConcept = graph.concepts.get(oldId) as Concept;
+  const linkedTasks = dedupeTaskIds(toRefList(oldConcept.frontmatter.tasks));
+  if (linkedTasks.length > 0 && !parsed.dryRun) {
+    assertNoCommaInId(newId, "rename to");
+    assertNoLabelCaseCollision(graph, newId, oldId, "rename to");
+  }
+
+  const writes = mergeIndexWrites(plan, graph, docsRoot, profile);
+
+  if (!parsed.dryRun) {
+    commitWrites(writes, plan, docsRoot, options.root);
+  }
+
+  // Move every linked task's Backlog back-reference LAST — mirrors link.ts's write-order fix: the
+  // file rename needs no Backlog round-trip and never depends on the back-ref move's outcome, so
+  // committing it first means a Backlog failure can never strand an already-renamed file. Skipped
+  // entirely (no BacklogAdapter even constructed) when the concept has no `tasks:` — renaming an
+  // unlinked doc keeps its historical zero-Backlog-dependency behavior — and under `--dry-run`,
+  // which previews the file-level plan only, not a Backlog-side one.
+  let backRefs: readonly MovedBackRef[] = [];
+  let editedTaskFiles: readonly string[] = [];
+  // `plan.rename` is never actually `null` here — `rewriteInbound` above is always called with
+  // `move: true` — but the check is kept (mirrors `assertTargetFree`'s identical guard) so this
+  // stays correct by construction rather than by the caller's current behavior, should a future
+  // change ever make `move` conditional in this function.
+  if (plan.rename !== null && !parsed.dryRun && linkedTasks.length > 0) {
+    const adapter = options.adapter ?? defaultAdapter(options.root);
+    const moved = await moveBackRefs(
+      adapter,
+      linkedTasks,
+      oldId,
+      newId,
+      `${DOCS_DIR}/${plan.rename.from}`,
+      `${DOCS_DIR}/${plan.rename.to}`,
+    );
+    backRefs = moved.outcomes;
+    editedTaskFiles = moved.editedFiles;
+  }
+
+  // Commit exactly the task files the back-reference move edited — lore is the sole committer of
+  // `backlog/` (ADR-0012, design §3.6), so a `rename` no longer leaves them uncommitted until the
+  // next `lore sync`. Scoped to `editedTaskFiles`, so an unlinked/`--dry-run` rename or an
+  // all-`already-current` move (empty) commits nothing and an unrelated dirty `backlog/` edit is
+  // never swept in (ADR-0012 §1).
+  const backlogCommit = await commitBacklogFiles(editedTaskFiles, options, RENAME_COMMIT_MESSAGE);
+
+  // commitBacklogFiles captures a commit failure into backlogCommit.error rather than throwing, so
+  // the report emit below always runs on the write path — a git failure no longer skips it
+  // (previously it threw here, dropping the report). Load advisories were already flushed right
+  // after loadBundle (LORE-82), not repeated here (flush is non-draining — a second call would
+  // re-print the same warnings).
+  const report = buildReport(plan, writes, backRefs, backlogCommit, parsed.dryRun);
+  emit(reportRenderable(report), options.output, options.stdout);
+  return backRefs.some((b) => b.backRef === "failed") || backlogCommit.error !== undefined ? EXIT_CODES.drift : EXIT_OK;
+}
+
+/** The `git`-authored commit message for `lore rename`'s `backlog/` writes (moving each linked task's `doc:` label/`--doc` path). */
+const RENAME_COMMIT_MESSAGE = "chore(backlog): move doc back-references (lore rename)";
+
+// ── Filesystem commit ──────────────────────────────────────────────────────────
+
+/**
+ * Reject a rename whose destination is already occupied on disk by anything other than the source
+ * file itself. The engine's `graph.concepts.has(to)` guard is case-sensitive and concept-only; this
+ * closes the two gaps it leaves on a case-insensitive filesystem and against non-concept files. A
+ * destination that resolves to the **same physical file** as the source is a case-only rename and
+ * is permitted (the relocation renames the inode rather than clobbering it).
+ *
+ * This is a PLAN-TIME check only — it runs once, well before `commitWrites` below actually moves
+ * anything, so it cannot see a destination created during that (potentially I/O-heavy) window
+ * (LORE-132). It still fires early for the common case (fail fast, before any write), but the
+ * guarantee that a raced-in destination is never silently clobbered comes from `moveFile`
+ * (`fswrite.ts`)'s own immediately-before-the-syscall re-check, not from this function.
+ */
+function assertTargetFree(plan: RewritePlan, docsRoot: string): void {
+  if (plan.rename === null) {
+    return;
+  }
+  const absTo = join(docsRoot, plan.rename.to);
+  const absFrom = join(docsRoot, plan.rename.from);
+  if (existsSync(absTo) && canonicalIdentity(absTo) !== canonicalIdentity(absFrom)) {
+    throw new LoreError(
+      "conflict",
+      `cannot rename to "${plan.rename.to}": a file already exists at that path`,
+      "choose a target path that is not already taken (concept or not), or remove the conflicting file",
+      { path: `${DOCS_DIR}/${plan.rename.to}` },
+    );
+  }
+}
+
+/**
+ * Commit the planned writes to disk. Every target is swept for a symlinked ancestor (or, for the
+ * in-place rewrites, a symlinked final component too — {@link writeFileOverwriting} is a plain
+ * `writeFileSync`, which follows a symlink at the final path segment, unlike {@link moveFile}'s
+ * `renameSync`, which atomically replaces whatever is at the destination without ever dereferencing
+ * it) BEFORE any single write begins (LORE-93 AC#5) — `ensureDir`'s own per-call guard alone would
+ * only refuse once the loop below REACHES a bad target, by which point earlier targets in the same
+ * plan may already be on disk. Parent directories are then created (so a target in a brand-new
+ * category directory does not fail with ENOENT), the in-place rewrites are written, and the renamed
+ * file is relocated **last** by {@link moveFile} — its new bytes are written into the source path
+ * and then the inode is renamed, which is atomic and safe even for a case-only rename on a
+ * case-insensitive filesystem. {@link moveFile} itself re-verifies the destination immediately
+ * before that rename (LORE-132), so a destination that appeared after {@link assertTargetFree}'s
+ * earlier plan-time check runs is refused with the same `conflict` rather than silently replaced.
+ * (A mid-commit IO failure UNRELATED to a symlink can still leave the bundle partially rewritten —
+ * cross-file transactional rollback for that case is a shared concern with `lore replace`, deferred;
+ * the preflight sweep above only closes the symlink-specific gap.)
+ */
+function commitWrites(writes: Map<string, string>, plan: RewritePlan, docsRoot: string, root: string): void {
+  const movedTo = plan.rename?.to;
+  // `writes` already carries the moved file's new bytes keyed at `plan.rename.to` (RewritePlan's
+  // own contract) — only `plan.rename.from` (the source, written-then-renamed) isn't a `writes` key.
+  const targets = [...writes.keys()].map((path) => `${DOCS_DIR}/${path}`);
+  if (plan.rename !== null) {
+    targets.push(`${DOCS_DIR}/${plan.rename.from}`);
+  }
+  assertNoSymlinkInAnyPath(root, targets);
+
+  for (const [path, bytes] of writes) {
+    if (path === movedTo) {
+      continue; // the moved file is relocated below, not written at its new path here
+    }
+    const abs = join(docsRoot, path);
+    ensureDir(root, dirname(`${DOCS_DIR}/${path}`));
+    writeFileOverwriting(abs, bytes, `${DOCS_DIR}/${path}`);
+  }
+  if (plan.rename !== null) {
+    const absFrom = join(docsRoot, plan.rename.from);
+    const absTo = join(docsRoot, plan.rename.to);
+    ensureDir(root, dirname(`${DOCS_DIR}/${plan.rename.to}`));
+    // Write the new bytes into the source file, then rename the source to its destination — never
+    // write-new-then-delete-old, which would destroy a case-only rename's single inode.
+    writeFileOverwriting(absFrom, writes.get(plan.rename.to) ?? "", `${DOCS_DIR}/${plan.rename.from}`);
+    moveFile(absFrom, absTo, `${DOCS_DIR}/${plan.rename.to}`);
+  }
+}
+
+// ── Index regeneration ───────────────────────────────────────────────────────────
+
+/**
+ * Merge the plan's concept rewrites with the regenerated `index.md` hubs, returning the final
+ * `path → bytes` writes (bundle-relative paths, ascending). Index regeneration runs over the
+ * **post-rename** graph and splices into the already-rewritten index bytes, so a hub whose listing
+ * gains/loses the renamed concept is updated while its frontmatter and prose are preserved; a hub
+ * whose regenerated bytes equal the on-disk bytes is dropped, so an unrelated canonical index is
+ * never written.
+ */
+function mergeIndexWrites(
+  plan: RewritePlan,
+  graph: BundleGraph,
+  docsRoot: string,
+  profile: Profile,
+): Map<string, string> {
+  const planByPath = new Map(plan.writes.map((w) => [w.path, w.bytes] as const));
+
+  // Current on-disk bytes of every index file, the determinism seam generateIndexes splices into —
+  // overridden by the plan's rewritten bytes where a (concept) index was already repointed.
+  const diskIndexBytes = readIndexBytes(docsRoot);
+  const existing = new Map(diskIndexBytes);
+  for (const [path, bytes] of planByPath) {
+    if (posix.basename(path) === INDEX_FILE) {
+      existing.set(path, bytes);
+    }
+  }
+
+  const postRename = buildPostRenameGraph(graph, plan, profile);
+  const regenerated = generateIndexes(postRename, { existing });
+
+  // Start from the plan's writes, then let index regeneration win for any index path. An index
+  // whose regenerated bytes equal what is already on disk is a no-op and is skipped.
+  const writes = new Map(planByPath);
+  for (const [path, bytes] of regenerated) {
+    if (bytes === diskIndexBytes.get(path)) {
+      writes.delete(path); // unchanged hub — drop a plan entry too (none expected) and don't write
+    } else {
+      writes.set(path, bytes);
+    }
+  }
+
+  // A cross-directory rename can empty a directory of its last concept; generateIndexes only emits
+  // an index for a directory that still holds a concept, so that directory's on-disk index.md keeps
+  // a now-dead link to the moved file in its machine-owned block. Regenerate those to an empty
+  // listing so no stale link survives in a managed region.
+  if (plan.rename !== null) {
+    for (const dir of emptiedDirs(plan.rename.from, postRename)) {
+      const indexPath = `${dir}/${INDEX_FILE}`;
+      const disk = diskIndexBytes.get(indexPath);
+      if (disk === undefined || regenerated.has(indexPath)) {
+        continue; // no such index, or it was already regenerated (the dir still has concepts)
+      }
+      const emptied = spliceEmptyListing(disk);
+      if (emptied !== disk) {
+        writes.set(indexPath, emptied);
+      }
+    }
+  }
+  return new Map([...writes].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)));
+}
+
+/**
+ * The ancestor directories of `fromPath` (its directory up to, but excluding, the bundle root) that
+ * hold no concept after the rename — the directories a cross-directory move may have emptied. The
+ * root is excluded because generateIndexes always regenerates the root index.
+ */
+function emptiedDirs(fromPath: string, postRename: BundleGraph): string[] {
+  const concepts = [...postRename.concepts.values()];
+  const dirs: string[] = [];
+  let dir = posix.dirname(fromPath);
+  while (dir !== "" && dir !== "." && dir !== "/") {
+    const prefix = `${dir}/`;
+    if (!concepts.some((c) => c.path.startsWith(prefix))) {
+      dirs.push(dir);
+    }
+    dir = posix.dirname(dir);
+  }
+  return dirs;
+}
+
+/**
+ * Replace an index file's managed listing block with an **empty** listing (the same bytes
+ * generateIndexes emits for a concept-less directory), preserving every other byte. Returns the
+ * input unchanged when it carries no managed block (nothing lore owns to regenerate).
+ */
+function spliceEmptyListing(content: string): string {
+  const bounds = locateManagedBlock(content, INDEX_BLOCK_BEGIN, INDEX_BLOCK_END);
+  if (bounds === null) {
+    return content;
+  }
+  const block = `${INDEX_BLOCK_BEGIN}\n\n${INDEX_BLOCK_END}`;
+  const tail = content.slice(bounds.end);
+  const spliced = content.slice(0, bounds.start) + block + tail;
+  return tail === "" ? `${spliced}\n` : spliced;
+}
+
+/**
+ * Rebuild the bundle graph as it will be **after** the rename, so index regeneration lists the
+ * renamed concept at its new path. Every concept the plan rewrote is re-parsed from its new bytes
+ * (the moved concept from its new path, so it re-ids to `newId`); every untouched concept is
+ * carried over verbatim. The plan's bytes came from a validating serialize against `profile` — the
+ * SAME profile passed here (LORE-88) — so re-parse cannot fail.
+ */
+function buildPostRenameGraph(graph: BundleGraph, plan: RewritePlan, profile: Profile): BundleGraph {
+  const newBytesByPath = new Map(plan.writes.map((w) => [w.path, w.bytes] as const));
+  const movedFrom = plan.rename?.from;
+  const movedTo = plan.rename?.to;
+
+  const concepts: Concept[] = [];
+  for (const concept of graph.concepts.values()) {
+    if (concept.path === movedFrom && movedTo !== undefined) {
+      concepts.push(parseConcept(movedTo, newBytesByPath.get(movedTo) ?? "", { profile })); // moved → new path/id
+    } else {
+      const rewritten = newBytesByPath.get(concept.path);
+      concepts.push(rewritten === undefined ? concept : parseConcept(concept.path, rewritten, { profile }));
+    }
+  }
+  return buildGraph(concepts);
+}
+
+// ── Argument parsing ───────────────────────────────────────────────────────────
+
+/**
+ * Reject a `newId` that would resolve outside the `docs/` bundle root, confining the destination
+ * at the ARGUMENT-PARSING layer — before {@link runRename}'s body runs at all — as defense-in-depth
+ * alongside {@link rewriteInbound}'s own identical engine-layer guard (LORE-80), and with a clearer
+ * `usage` error (exit 2) here versus its `validation` (exit 6), mirroring `new.ts`'s
+ * `resolveOutPath` in spirit (fail fast at the earliest possible point, don't rely on a downstream
+ * engine's own guard). The algorithm itself mirrors LORE-80's `escapesRoot`/`assertConfinedToBundle`,
+ * not `resolveOutPath`: `rename` operates on bundle-relative concept ids, not real filesystem paths,
+ * so there is no `resolve`+`relative`-against-a-real-directory step that fits here — `escapesRoot`
+ * is reused (not re-derived) from `core/rewrite.ts` for that reason, keeping the one
+ * security-sensitive segment walk in a single place. Called from {@link parseRenameArgs} itself
+ * (LORE-78) rather than by its caller, so a confined `newId` is `parseRenameArgs`'s own guarantee,
+ * not a follow-up check `runRename` happens to make (LORE-79's original call site).
+ *
+ * Checked on the RAW `newId` (before {@link idFromPath} runs), mirroring `assertConfinedToBundle`'s
+ * own documented reasoning for checking pre-normalize.
+ */
+function assertDestinationConfined(newId: string): void {
+  if (
+    posix.isAbsolute(newId) ||
+    win32.isAbsolute(newId) ||
+    escapesRoot(newId) ||
+    isDriveRelative(newId) ||
+    resolvesToRoot(newId)
+  ) {
+    throw usage(
+      `newId "${newId}" resolves outside the docs/ bundle root`,
+      "pass a destination id that stays inside docs/ (no absolute path, no `..` segments, not empty or self-cancelling)",
+      { id: newId },
+    );
+  }
+}
+
+/**
+ * Parse `rename`'s tokens into its two positionals (`<oldId> <newId>`) and `--dry-run`, via the
+ * shared {@link parseCommandArgs} parser (mirrors `commands/supersede.ts`/`commands/link.ts`'s
+ * parsers). Positional arity is validated here since it differs per command. `newId` is also
+ * confined to the `docs/` bundle root here (LORE-78) — before this function returns, so a
+ * traversal/absolute destination never reaches `runRename`'s body as a "parsed" value.
+ */
+function parseRenameArgs(args: readonly string[]): RenameArgs {
+  const { positionals, flags } = parseCommandArgs(args, "rename");
+
+  const oldId = positionals[0];
+  if (oldId === undefined) {
+    throw usage("`lore rename` needs an old and a new id", "run `lore rename <oldId> <newId>`");
+  }
+  const newId = positionals[1];
+  if (newId === undefined) {
+    throw usage("`lore rename` needs a new id", "pass the target id, e.g. `lore rename stories/old stories/new`");
+  }
+  if (positionals.length > 2) {
+    throw usage(
+      `unexpected argument "${positionals[2]}"`,
+      "pass exactly an old and a new id; scope nothing else (rename rewrites the whole bundle)",
+    );
+  }
+  assertDestinationConfined(newId);
+  return { oldId, newId, dryRun: flags.has("dry-run") };
+}
+
+// ── Output ─────────────────────────────────────────────────────────────────────
+
+/** Assemble the {@link RenameReport} from the plan, the merged writes, the back-ref move outcomes, and the `backlog/` commit outcome (repo-relative display paths). */
+function buildReport(
+  plan: RewritePlan,
+  writes: Map<string, string>,
+  backRefs: readonly MovedBackRef[],
+  backlogCommit: BacklogCommitResult,
+  dryRun: boolean,
+): RenameReport {
+  const files = [...writes.keys()].map((path) => ({ path: `${DOCS_DIR}/${path}` }));
+  return {
+    from: plan.rename ? `${DOCS_DIR}/${plan.rename.from}` : "",
+    to: plan.rename ? `${DOCS_DIR}/${plan.rename.to}` : "",
+    files,
+    filesChanged: files.length,
+    backRefs,
+    backlogCommit,
+    dryRun,
+  };
+}
+
+/** The per-result-type rendering bundle for `rename` (output.ts dispatches on the mode). */
+function reportRenderable(data: RenameReport): Renderable<RenameReport> {
+  return {
+    kind: "rename.result",
+    data,
+    pretty: (report) => render(report),
+    plain: (report) => render(report),
+  };
+}
+
+/** The relocation line, one line per other changed file, one per moved back-reference, then a summary. (No color: no severities.) */
+function render(data: RenameReport): string {
+  const verb = data.dryRun ? "would rename" : "renamed";
+  const lines = [`${verb} ${data.from} -> ${data.to}`];
+  for (const file of data.files) {
+    if (file.path !== data.to) {
+      lines.push(`${data.dryRun ? "would update" : "updated"} ${file.path}`);
+    }
+  }
+  for (const b of data.backRefs) {
+    const suffix = b.error !== undefined ? ` (${b.error})` : "";
+    lines.push(`back-ref ${b.task}: ${b.backRef}${suffix}`);
+  }
+  const commitLine = renderBacklogCommitLine(data.backlogCommit);
+  if (commitLine !== undefined) {
+    lines.push(commitLine);
+  }
+  const noun = data.filesChanged === 1 ? "file" : "files";
+  lines.push(`${data.filesChanged} ${noun} changed${data.dryRun ? " (dry-run)" : ""}`);
+  return lines.join("\n");
+}