@opum-ai/lore 0.1.0 → 0.2.0

package/src/commands/orphans.ts

@@ -1,457 +0,0 @@
-/**
- * commands/orphans.ts — `lore orphans [--tasks-only | --docs-only] [--limit <n>]` (cli-surface §orphans).
- *
- * The read-only, **bidirectional** doc↔task coupling report: the CI/agent signal that the
- * coupling `lore link`/`sync` maintain has gaps. Two directions, one envelope:
- *
- *   - **orphanTasks** — tasks with **no owning doc**: no concept lists the task in its `tasks:`
- *     frontmatter AND the task carries no `doc:<conceptId>` back-reference label AND (LORE-261) no
- *     ancestor in its Backlog `parentTaskId` chain is owned either — a subtask of an already-linked
- *     parent task is not reported, since linking the parent does not stamp each subtask with its own
- *     back-reference (see {@link hasOwnedAncestor}). Work that exists in Backlog but is documented
- *     nowhere, at any level of its parent/subtask hierarchy.
- *   - **danglingLinks** — docs whose linked task **vanished**: a `tasks:` id the current-branch
- *     Backlog snapshot no longer knows. A doc pointing at a task that has been deleted or renamed.
- *
- * ## One snapshot, pure set arithmetic — not a per-task probe
- *
- * Unlike `lore tasks` (which `viewTask`s each of *one* concept's linked ids), `orphans` spans the
- * whole bundle, so it reads Backlog **once**: `adapter.listTasks()` returns the current-branch
- * on-disk truth across every status (backlog-cli-contract.md §: `task list --json` — "Never
- * `backlog board`"), and both directions fall out of set arithmetic against the loaded graph:
- * `orphanTasks` from the snapshot minus the forward `tasks:` set (and the `doc:` labels the snapshot
- * itself carries), `danglingLinks` from each concept's `tasks:` minus the snapshot's known ids. No
- * N+1 per-id reads.
- *
- * ## A report, never a gate
- *
- * The Backlog capability probe runs UP FRONT (fail-fast: a missing binary is `not_found`/exit 3, a
- * stock non-`--json` binary is `validation`/exit 6), and the single `listTasks()` either returns the
- * snapshot or throws hard drift (exit 6) — there is no soft-null path here, because a dangling link
- * is the *content* of the report, not an advisory swallowed on the way to a rollup. Everything after
- * the snapshot is pure, so `orphans` always returns exit `0` (ADR-0007: `orphans` is a detection
- * report, not a coherence gate — even a non-empty report is exit 0). Only a *usage* error (a bad
- * flag / a stray positional), a *bundle* failure (unreadable/malformed `docs/`), or the *probe/read*
- * failure above throws, funneling through the router's one error seam like every command.
- *
- * ## Scope boundary
- *
- * "No owning doc" is the *literal* surface definition: **any** `doc:` label exempts a task, even one
- * pointing at a since-removed concept (a `doc:`→dead-concept is a third asymmetry, out of this
- * command's two-direction scope). Broken doc→doc cross-links are `lore check`'s job (its link/anchor
- * pass), not repeated here. An **archived** Backlog task reads identically to a deleted one through the
- * JSON adapter — archiving moves it to `backlog/archive/tasks/`, dropping it from BOTH `task list` and
- * `task view` (ADR-0002 keeps lore to that JSON-only surface, so the archive directory is deliberately
- * never consulted) — so a doc still linking an archived task surfaces here as a dangling link, exactly
- * as `lore tasks` drops that same id from its rollup. That is intentional and consistent, not a
- * distinction lore could draw. Output follows the uniform CLI modes: the `{schemaVersion, kind:
- * "orphans.report", data}` envelope under `--json` — `data` an object `{ orphanTasks?, danglingLinks? }`
- * (object-wrapped so the contract can grow additively; the section a flag excludes is **omitted**, not
- * emitted empty, so `--docs-only --json` never shows a misleading `orphanTasks: []`) — and otherwise an
- * aligned text report.
- *
- * ## Bounded output (cli-contract §3)
- *
- * `orphans` is named alongside `query`/`graph`/`context` as a read-heavy command that must cap its
- * output rather than dump an unbounded snapshot into a CI log or an agent's context window. Its two
- * sections are independent (an unrelated task backlog and an unrelated doc set), so each is capped —
- * and reports its own `total`/`shown`/`truncated` — separately against the same `--limit` (default
- * {@link DEFAULT_ORPHANS_LIMIT}), mirroring `query`'s single-section shape once per section.
- */
-
-import { join } from "node:path";
-import type { BacklogAdapter, BacklogTask } from "../adapters/backlog";
-import { loadBundle, toRefList } from "../core/bundle";
-import type { Concept } from "../core/concept";
-import { loadProfile } from "../core/profile";
-import { DOCS_DIR } from "../core/scaffold";
-import { ANSI, EXIT_OK, paint, WarningCollector, type Writer } from "../errors";
-import {
-  emit,
-  maxLen,
-  type OutputContext,
-  type Renderable,
-  renderTaskSummaryRows,
-  renderTruncationLine,
-  type TaskSummaryRow,
-  truncation,
-} from "../output";
-import { assertFlagAtMostOnce, parseCommandArgs, singleOptionValue, usage } from "./args";
-import { dedupeTaskIds, defaultAdapter } from "./link";
-
-/** Options for {@link runOrphans}; `root`, the streams, and the adapter are injectable for tests. */
-export interface OrphansOptions {
-  /** The repo root the `docs/` bundle and the Backlog adapter resolve against. */
-  root: string;
-  /** The resolved output mode/color (from `output.ts`). */
-  output: OutputContext;
-  /** The command's normalized flag tokens from Commander. */
-  args: readonly string[];
-  /** stdout sink; defaults to `process.stdout`. */
-  stdout?: Writer;
-  /** stderr sink for advisory warnings; defaults to `process.stderr`. */
-  stderr?: Writer;
-  /** The Backlog adapter; defaults to the real `backlog` binary resolved against `root`. Injected for tests. */
-  adapter?: BacklogAdapter;
-}
-
-/** The parsed form of `lore orphans`'s arguments — the two mutually-exclusive section filters, plus the cap. */
-interface OrphansArgs {
-  /** `--tasks-only`: report only the orphan-task side (omit `danglingLinks`). */
-  readonly tasksOnly: boolean;
-  /** `--docs-only`: report only the dangling-link side (omit `orphanTasks`). */
-  readonly docsOnly: boolean;
-  /** `--limit` (at most once); `undefined` falls back to {@link DEFAULT_ORPHANS_LIMIT}. */
-  readonly limit?: number;
-}
-
-/** One task with no owning doc: its live identity + current Backlog status, from the Backlog snapshot. */
-export type OrphanTask = TaskSummaryRow;
-
-/** One dangling doc→task link: a concept and the `tasks:` id Backlog no longer knows. */
-export interface DanglingLink {
-  /** The owning concept's id (`"stories/bulk-archive-orders"`). */
-  readonly concept: string;
-  /** The vanished task id, echoed **verbatim** as the concept's `tasks:` frontmatter wrote it (Backlog has no record to re-case it). */
-  readonly task: string;
-}
-
-/**
- * The `orphans.report` payload. Both keys are optional: a run with no flag carries both, `--tasks-only`
- * carries only the orphan-task fields, `--docs-only` only the dangling-link fields. An excluded section
- * is entirely absent (not `[]`) so a consumer can tell "not requested" from "requested, found none".
- *
- * Each section carries its own `total`/`shown`/`truncated` (cli-contract §3) rather than one combined
- * triple — `orphanTasks` and `danglingLinks` count unrelated things (a task backlog vs. a doc set), so a
- * single combined cap would make one section's truncation state say nothing about the other.
- */
-export interface OrphansReport {
-  /** Tasks with no owning doc, sorted by id (case-insensitive), capped to `--limit`. Omitted under `--docs-only`. */
-  readonly orphanTasks?: readonly OrphanTask[];
-  /** The full count of orphan tasks before the `--limit` cap. Present iff {@link orphanTasks} is. */
-  readonly orphanTasksTotal?: number;
-  /** The number of orphan tasks actually returned (`orphanTasksShown <= orphanTasksTotal`). */
-  readonly orphanTasksShown?: number;
-  /** `true` when the `--limit` cap dropped orphan tasks. */
-  readonly orphanTasksTruncated?: boolean;
-  /** Docs whose linked task vanished, sorted by (concept, task), capped to `--limit`. Omitted under `--tasks-only`. */
-  readonly danglingLinks?: readonly DanglingLink[];
-  /** The full count of dangling links before the `--limit` cap. Present iff {@link danglingLinks} is. */
-  readonly danglingLinksTotal?: number;
-  /** The number of dangling links actually returned (`danglingLinksShown <= danglingLinksTotal`). */
-  readonly danglingLinksShown?: number;
-  /** `true` when the `--limit` cap dropped dangling links. */
-  readonly danglingLinksTruncated?: boolean;
-}
-
-/**
- * Run `lore orphans`: parse the flags, load the bundle, take the one Backlog snapshot, compute both
- * coupling-gap directions by set arithmetic, emit the `orphans.report`, and return `0`. Async because
- * it drives the Backlog subprocess. See the module docstring for the failure modes.
- */
-export async function runOrphans(options: OrphansOptions): Promise<number> {
-  const parsed = parseOrphansArgs(options.args);
-  const docsRoot = join(options.root, DOCS_DIR);
-  const advisories = new WarningCollector();
-  const profile = loadProfile({ root: options.root });
-  const graph = loadBundle(docsRoot, { warnings: advisories, profile });
-  // Flush load advisories (e.g. a file skipped for a malformed header) before any Backlog I/O, so a
-  // "why isn't this a concept" note survives even if the snapshot read below throws (mirrors `lore tasks`).
-  advisories.flush({ color: options.output.color, stderr: options.stderr });
-
-  const adapter = options.adapter ?? defaultAdapter(options.root);
-  // Probe UP FRONT (fail-fast 3/6) before the snapshot, so an incapable binary is reported as such and
-  // never mistaken for "the project has zero tasks" — the disambiguation the report's meaning relies on.
-  await adapter.probe();
-  const snapshot = await adapter.listTasks();
-
-  emit(orphansRenderable(computeOrphans(graph.concepts.values(), snapshot, parsed)), options.output, options.stdout);
-  return EXIT_OK;
-}
-
-/**
- * The pure heart of the command: from the bundle's concepts and one Backlog snapshot, derive both
- * coupling-gap directions and apply the section filter. Kept side-effect-free (a plain iterable of
- * concepts + the snapshot array in, a report out) so it is exercised directly in tests without a bundle
- * or a subprocess.
- *
- * A single pass over the concepts builds the forward `tasks:` set (for the orphan-task test) and the
- * flat list of every `(concept, taskId)` reference (for the dangling test) at once; `orphanTasks` then
- * filters the snapshot and `danglingLinks` filters the references, both against case-insensitive id
- * sets. Both outputs are sorted for a deterministic, diff-stable report.
- */
-export function computeOrphans(
-  concepts: Iterable<Concept>,
-  snapshot: readonly BacklogTask[],
-  parsed: OrphansArgs,
-): OrphansReport {
-  const referenced = new Set<string>(); // lower-cased task ids any concept forward-links
-  const references: DanglingLink[] = []; // every (concept, taskId) pair, for the dangling test
-  for (const concept of concepts) {
-    for (const task of dedupeTaskIds(toRefList(concept.frontmatter.tasks))) {
-      referenced.add(task.toLowerCase());
-      references.push({ concept: concept.id, task });
-    }
-  }
-
-  const known = new Set(snapshot.map((task) => task.id.toLowerCase())); // lower-cased ids Backlog knows
-  const byId = new Map(snapshot.map((task) => [task.id.toLowerCase(), task])); // for the parent-chain walk below
-  const orphanTasks = snapshot
-    .filter(
-      (task) =>
-        !referenced.has(task.id.toLowerCase()) && !hasDocLabel(task) && !hasOwnedAncestor(task, referenced, byId),
-    )
-    .map((task): OrphanTask => ({ id: task.id, title: task.title, status: task.status }))
-    .sort((a, b) => compareLower(a.id, b.id));
-  const danglingLinks = references
-    .filter((ref) => !known.has(ref.task.toLowerCase()))
-    .sort((a, b) => compareLower(a.concept, b.concept) || compareLower(a.task, b.task));
-
-  const limit = parsed.limit ?? DEFAULT_ORPHANS_LIMIT;
-
-  // Compute both directions unconditionally (both are cheap and share the same inputs), then omit the
-  // section a flag excluded — omission, not an empty array, is how the envelope says "not requested".
-  // Each section is capped to `limit` independently and carries its own total/shown/truncated (§3):
-  // the two counts are unrelated, so one combined cap would make one section's truncation state say
-  // nothing about the other.
-  const report: {
-    orphanTasks?: OrphanTask[];
-    orphanTasksTotal?: number;
-    orphanTasksShown?: number;
-    orphanTasksTruncated?: boolean;
-    danglingLinks?: DanglingLink[];
-    danglingLinksTotal?: number;
-    danglingLinksShown?: number;
-    danglingLinksTruncated?: boolean;
-  } = {};
-  if (!parsed.docsOnly) {
-    const shown = orphanTasks.slice(0, limit);
-    report.orphanTasks = shown;
-    report.orphanTasksTotal = orphanTasks.length;
-    report.orphanTasksShown = shown.length;
-    report.orphanTasksTruncated = shown.length < orphanTasks.length;
-  }
-  if (!parsed.tasksOnly) {
-    const shown = danglingLinks.slice(0, limit);
-    report.danglingLinks = shown;
-    report.danglingLinksTotal = danglingLinks.length;
-    report.danglingLinksShown = shown.length;
-    report.danglingLinksTruncated = shown.length < danglingLinks.length;
-  }
-  return report;
-}
-
-/** The default `--limit` when none is given, matching `query`'s cap (cli-surface §orphans). */
-export const DEFAULT_ORPHANS_LIMIT = 20;
-
-/** Whether a task claims an owning doc via a `doc:<conceptId>` back-reference label (case-insensitive). */
-function hasDocLabel(task: BacklogTask): boolean {
-  return task.labels.some((label) => label.toLowerCase().startsWith("doc:"));
-}
-
-/**
- * LORE-261: exempt a Backlog **subtask** from the orphan report when an ancestor in its
- * `parentTaskId` chain is already owned — forward-referenced by some concept's `tasks:` list, or
- * itself carrying a `doc:` label. Linking a parent task to a Story does not stamp every subtask
- * with its own back-reference (one `backlog task edit` per task — ADR-0009 §2), so without this
- * walk a correctly-coupled Story's subtasks would all read as false-positive orphans (the Meridian
- * stress test: 8 reported instead of the intended 2).
- *
- * This is **orphans-side hierarchy awareness**, chosen over a link-side cascade (`lore link` writing
- * a `doc:` label onto every subtask): the `--json` adapter already carries `parentTaskId` on every
- * task in the SAME `listTasks()` snapshot this command already reads (no extra per-task `view`
- * call, preserving the "one snapshot" design above), and a cascade would go stale the instant a new
- * subtask is added after the parent was linked — this walk instead recomputes fresh on every run.
- *
- * Only the task's **ancestors** are walked (never siblings or descendants) — starting at
- * `task.parentTaskId`, not `task` itself, since the caller already tested the task's own
- * reference/label directly. A parent absent from the current snapshot (deleted, archived, or
- * renamed out from under a stale `parentTaskId`) grants no exemption — a subtask under a vanished
- * ancestor is reported, matching how `orphans` already treats an archived task as gone everywhere
- * else (module docstring, "Scope boundary"). A visited-id set guards a corrupt or cyclic parent
- * chain: a cycle yields `false` (not owned, so still reported) rather than looping forever — this
- * is the fail-toward-reporting side of AC#3's no-false-negatives requirement.
- */
-function hasOwnedAncestor(
-  task: BacklogTask,
-  referenced: ReadonlySet<string>,
-  byId: ReadonlyMap<string, BacklogTask>,
-): boolean {
-  const visited = new Set<string>([task.id.toLowerCase()]);
-  let parentId = task.parentTaskId;
-  while (parentId !== null) {
-    const key = parentId.toLowerCase();
-    if (visited.has(key)) {
-      return false; // a cycle/self-reference in the parent chain — fail toward "still reported"
-    }
-    visited.add(key);
-    const parent = byId.get(key);
-    if (parent === undefined) {
-      return false; // the ancestor isn't in the current-branch snapshot — no exemption to grant
-    }
-    if (referenced.has(key) || hasDocLabel(parent)) {
-      return true;
-    }
-    parentId = parent.parentTaskId;
-  }
-  return false;
-}
-
-/** Case-insensitive string order, locale-independent, for the report's deterministic sort. */
-function compareLower(a: string, b: string): number {
-  const x = a.toLowerCase();
-  const y = b.toLowerCase();
-  return x < y ? -1 : x > y ? 1 : 0;
-}
-
-// ── Argument parsing ───────────────────────────────────────────────────────────
-
-/**
- * Parse `orphans`'s tokens: the two boolean switches `--tasks-only` / `--docs-only`, the value flag
- * `--limit <n>` (also accepting `--limit=<n>`), and nothing else. Commander has already resolved
- * lore's global flags, so a `--`-prefixed token here is a command flag; an unrecognized one, a
- * positional (orphans takes none), a repeated or value-bearing `--tasks-only`/`--docs-only`, passing
- * **both** section filters, or a repeated/value-less/non-integer/too-large/non-positive `--limit` is a
- * `usage` error (exit 2). A `--` ends option parsing (after which any token is a stray positional).
- */
-function parseOrphansArgs(args: readonly string[]): OrphansArgs {
-  const parsed = parseCommandArgs(args, "orphans");
-  assertFlagAtMostOnce(parsed, "tasks-only");
-  assertFlagAtMostOnce(parsed, "docs-only");
-  if (parsed.positionals.length > 0) {
-    throw usage(`unexpected argument "${parsed.positionals[0]}"`, "orphans takes no positional arguments");
-  }
-  const tasksOnly = parsed.flags.has("tasks-only");
-  const docsOnly = parsed.flags.has("docs-only");
-  const rawLimit = singleOptionValue(parsed, "limit");
-  if (rawLimit === "") {
-    throw usage("--limit needs a value", "pass a value, e.g. `--limit 20`");
-  }
-  const limit = rawLimit === undefined ? undefined : parseCount("--limit", rawLimit);
-  if (tasksOnly && docsOnly) {
-    throw usage(
-      "--tasks-only and --docs-only are mutually exclusive",
-      "pass at most one of them, or neither for the full report",
-    );
-  }
-  return { tasksOnly, docsOnly, limit };
-}
-
-/**
- * Parse `--limit`'s value as a positive integer. Rejects a non-digit run (`Number()` would coerce
- * `"1.5"`/`"0x2"`/`" 2 "`/`"1e3"`), `0` (a zero cap returns nothing useful), and a precision-losing
- * `> 2^53` run — mirroring `query`'s `--limit` guard so every capped command accepts counts identically.
- */
-function parseCount(flag: string, value: string): number {
-  if (!/^\d+$/.test(value)) {
-    throw usage(`invalid ${flag} "${value}"`, `pass an integer ≥ 1, e.g. \`${flag} 20\``);
-  }
-  const count = Number.parseInt(value, 10);
-  if (!Number.isSafeInteger(count)) {
-    throw usage(`${flag} "${value}" is too large`, "pass a smaller integer");
-  }
-  if (count < 1) {
-    throw usage(`invalid ${flag} "${value}"`, `pass an integer ≥ 1, e.g. \`${flag} 20\``);
-  }
-  return count;
-}
-
-// ── Output ─────────────────────────────────────────────────────────────────────
-
-/**
- * The rendering bundle for `orphans` (output.ts dispatches on the mode). `--json` carries the structured
- * {@link OrphansReport}; the pretty/plain text is an aligned report. The two text modes differ only in the
- * painted header, so they share one renderer.
- */
-function orphansRenderable(data: OrphansReport): Renderable<OrphansReport> {
-  return {
-    kind: "orphans.report",
-    data,
-    pretty: (d, opts) => renderReport(d, opts.color),
-    plain: (d) => renderReport(d, false),
-  };
-}
-
-/** The narrow-it hint on each section's §3 truncation line — the one actionable way to see more of it. */
-const LIMIT_HINT = "raise --limit to see more";
-
-/**
- * A human/pipe-stable report: a header summarizing the requested sections' **total** counts, then one
- * aligned block per non-empty section (`  <id>  <status>  <title>` for orphan tasks; `  <concept>  ->
- * <task>` for dangling links), each followed by its own §3 truncation footer when `--limit` dropped
- * rows. When every requested section is empty, a single all-clear line stands in for the blocks. ANSI
- * only on the header, and only when `color`.
- */
-function renderReport(data: OrphansReport, color: boolean): string {
-  const { orphanTasks, danglingLinks } = data;
-  const counts: string[] = [];
-  if (orphanTasks !== undefined) {
-    const total = data.orphanTasksTotal as number;
-    counts.push(`${total} orphan ${total === 1 ? "task" : "tasks"}`);
-  }
-  if (danglingLinks !== undefined) {
-    const total = data.danglingLinksTotal as number;
-    counts.push(`${total} dangling ${total === 1 ? "link" : "links"}`);
-  }
-  const lines = [paint(`orphans: ${counts.join(", ")}`, ANSI.green, color)];
-
-  if (orphanTasks !== undefined && orphanTasks.length > 0) {
-    lines.push("", "tasks with no owning doc:");
-    // A per-item loop, not `lines.push(...renderTaskSummaryRows(orphanTasks))` — spreading a large
-    // array into a function-call argument list has its own engine argument-count ceiling, the same
-    // class of RangeError the spread-free `maxLen` (below and in output.ts) was written to avoid.
-    for (const row of renderTaskSummaryRows(orphanTasks)) {
-      lines.push(row);
-    }
-    const footer = renderTruncationLine(
-      truncation(data.orphanTasksTotal as number, data.orphanTasksShown as number, LIMIT_HINT),
-    );
-    if (footer !== "") {
-      lines.push(footer);
-    }
-  }
-  if (danglingLinks !== undefined && danglingLinks.length > 0) {
-    const conceptWidth = maxLen(danglingLinks, (link) => link.concept.length);
-    lines.push("", "docs with a vanished linked task:");
-    for (const link of danglingLinks) {
-      lines.push(`  ${link.concept.padEnd(conceptWidth)}  -> ${link.task}`);
-    }
-    const footer = renderTruncationLine(
-      truncation(data.danglingLinksTotal as number, data.danglingLinksShown as number, LIMIT_HINT),
-    );
-    if (footer !== "") {
-      lines.push(footer);
-    }
-  }
-
-  const allClear = allClearLine(orphanTasks, danglingLinks);
-  if (allClear !== undefined) {
-    lines.push(allClear);
-  }
-  return lines.join("\n");
-}
-
-/**
- * The all-clear line when every **requested** section is empty, else `undefined` (a section had entries,
- * so its block already stands on its own). Crucially, the phrasing asserts cleanliness ONLY for the
- * sections that were actually computed: under `--tasks-only`/`--docs-only` the excluded side (an
- * `undefined` argument) was never checked, so it is left out of the sentence rather than falsely
- * declared clean. At least one side is always requested (the parser rejects both flags), so the line is
- * never empty.
- */
-function allClearLine(
-  orphanTasks: readonly OrphanTask[] | undefined,
-  danglingLinks: readonly DanglingLink[] | undefined,
-): string | undefined {
-  if ((orphanTasks?.length ?? 0) > 0 || (danglingLinks?.length ?? 0) > 0) {
-    return undefined;
-  }
-  const clauses: string[] = [];
-  if (orphanTasks !== undefined) {
-    clauses.push("every task has an owning doc");
-  }
-  if (danglingLinks !== undefined) {
-    clauses.push("every linked task is live");
-  }
-  return `(none — ${clauses.join(", ")})`;
-}

package/src/commands/path.ts

@@ -1,67 +0,0 @@
-/** `lore path`: bounded deterministic paths across exact authored typed edges. */
-
-import type { BacklogAdapter } from "../adapters/backlog";
-import { loadRetrievalGraph, type RetrievalGraphLoader } from "../core/retrieval";
-import { findPaths } from "../core/traversal";
-import { EXIT_OK, LoreError, WarningCollector, type Writer } from "../errors";
-import { emit, type OutputContext } from "../output";
-import { parseCommandArgs, usage, workspaceSelection } from "./args";
-import {
-  assertKnownEdgeKinds,
-  normalizeEndpointId,
-  parseEndpointKind,
-  parseTraversalFlags,
-  pathRenderable,
-} from "./traversal";
-
-export interface PathCommandOptions {
-  readonly root: string;
-  readonly output: OutputContext;
-  readonly args: readonly string[];
-  readonly stdout?: Writer;
-  readonly stderr?: Writer;
-  readonly adapter?: BacklogAdapter;
-  readonly retrieval?: RetrievalGraphLoader;
-}
-
-export async function runPath(options: PathCommandOptions): Promise<number> {
-  const parsed = parseCommandArgs(options.args, "path");
-  const workspace = workspaceSelection(parsed);
-  if (parsed.positionals.length !== 2) {
-    throw usage(
-      "path needs exactly <from> and <to>",
-      "run `lore path <from> <to> --from-kind <kind> --to-kind <kind> --direction <direction>`",
-    );
-  }
-  const fromKind = parseEndpointKind(parsed, "from-kind");
-  const toKind = parseEndpointKind(parsed, "to-kind");
-  const flags = parseTraversalFlags(parsed);
-  const advisories = new WarningCollector();
-  const loaded = await (options.retrieval ?? loadRetrievalGraph)({
-    root: options.root,
-    warnings: advisories,
-    adapter: options.adapter,
-    includeTraversal: true,
-    ...(workspace !== undefined ? { workspace } : {}),
-  });
-  try {
-    advisories.flush({ color: options.output.color, stderr: options.stderr });
-    if (loaded.traversal === undefined) throw new LoreError("validation", "traversal snapshot was not loaded");
-    assertKnownEdgeKinds(loaded.traversal, flags.edgeKinds);
-    const data = findPaths(loaded.traversal, {
-      from: {
-        kind: fromKind,
-        id: normalizeEndpointId(parsed.positionals[0] as string, fromKind, workspace !== undefined),
-      },
-      to: {
-        kind: toKind,
-        id: normalizeEndpointId(parsed.positionals[1] as string, toKind, workspace !== undefined),
-      },
-      ...flags,
-    });
-    emit(pathRenderable(data), options.output, options.stdout);
-    return EXIT_OK;
-  } finally {
-    await loaded.dispose?.();
-  }
-}

package/src/commands/provenance.ts

@@ -1,68 +0,0 @@
-/** `lore provenance`: exact retained-snapshot record evidence. */
-
-import type { BacklogAdapter } from "../adapters/backlog";
-import { findRetainedProvenance, type ProvenanceResult, type RetainedFactKind } from "../core/snapshot";
-import { resolveSnapshotScope } from "../core/snapshot-runtime";
-import type { SnapshotScopeSelection } from "../core/snapshot-store";
-import { loadSnapshot } from "../core/snapshot-store";
-import { WarningCollector, type Writer } from "../errors";
-import { emit, type OutputContext, type Renderable } from "../output";
-import { parseCommandArgs, singleOptionValue, usage, workspaceSelection } from "./args";
-
-export interface ProvenanceCommandOptions {
-  readonly root: string;
-  readonly output: OutputContext;
-  readonly args: readonly string[];
-  readonly stdout?: Writer;
-  readonly stderr?: Writer;
-  readonly adapter?: BacklogAdapter;
-  readonly resolveScope?: () => SnapshotScopeSelection | Promise<SnapshotScopeSelection>;
-}
-
-export async function runProvenance(options: ProvenanceCommandOptions): Promise<number> {
-  const parsed = parseCommandArgs(options.args, "provenance");
-  const workspace = workspaceSelection(parsed);
-  if (parsed.positionals.length !== 1)
-    throw usage("provenance needs exactly one <id>", "run `lore provenance <id> --kind <kind> --snapshot <selector>`");
-  const kind = parseKind(singleOptionValue(parsed, "kind"));
-  const selector = singleOptionValue(parsed, "snapshot");
-  if (selector === undefined || selector.trim() === "")
-    throw usage("--snapshot needs a value", "pass an exact retained snapshot key or unambiguous commit");
-  const advisories = new WarningCollector();
-  const selection = workspace === undefined ? {} : { workspace: workspace.manifestPath };
-  const scope =
-    options.resolveScope === undefined
-      ? await resolveSnapshotScope({ root: options.root, selection, warnings: advisories, adapter: options.adapter })
-      : await options.resolveScope();
-  const snapshot = loadSnapshot(options.root, scope, selector.trim());
-  const data = findRetainedProvenance(snapshot, {
-    id: parsed.positionals[0] as string,
-    kind,
-    repositories: workspace?.memberIds ?? [],
-  });
-  advisories.flush({ color: options.output.color, stderr: options.stderr });
-  emit(provenanceRenderable(data), options.output, options.stdout);
-  return 0;
-}
-
-function parseKind(value: string | undefined): RetainedFactKind {
-  if (value !== "concept" && value !== "task" && value !== "edge")
-    throw usage("--kind must be concept, task, or edge", "pass the retained fact kind explicitly");
-  return value;
-}
-
-function provenanceRenderable(data: ProvenanceResult): Renderable<ProvenanceResult> {
-  return { kind: "provenance.result", data, pretty: renderProvenance, plain: renderProvenance };
-}
-
-function renderProvenance(data: ProvenanceResult): string {
-  const source = data.fact.provenance;
-  return [
-    `${data.fact.kind} ${data.fact.id} @ ${data.snapshot.snapshotKey}`,
-    `repository ${source.memberId ?? source.repositoryScopeKey}`,
-    `commit ${source.gitCommit ?? "uncommitted"}`,
-    `export ${source.exportDigest}`,
-    `record ${source.recordKey}`,
-    `source ${source.sourcePath ?? "none"}`,
-  ].join("\n");
-}