@opum-ai/lore 0.1.0

package/src/commands/sync.ts

@@ -0,0 +1,371 @@
+/**
+ * commands/sync.ts — `lore sync [paths…] [--dry-run] [--no-index]` (LORE-26, cli-surface §sync).
+ *
+ * The **write** counterpart to `lore check`. For every concept linking Backlog tasks via its
+ * `tasks:` frontmatter: resolves each linked task's live status (`BacklogAdapter.viewTask`),
+ * recomputes the concept's `status` (`core/reconcile.ts`, honoring `[reconcile.overrides]`) and
+ * rewrites it when it changed, and regenerates the `<!-- lore:tasks -->` managed region
+ * (`core/managed-block.ts`) from the same live data. Then — unless `--no-index` — regenerates every
+ * bundle `index.md` (`core/indexes.ts`) and the git-history-derived `log.md` (`core/log.ts`, via the
+ * real `git log`-shelling adapter in `adapters/git.ts`). Every write is a byte-diff against the
+ * current on-disk content first, so a clean tree is a true no-op (AC#1) — and, unless `--dry-run`,
+ * the whole write set is committed **all-or-nothing** via {@link writeManyAtomicOrRollback}
+ * (LORE-120): each file is still written atomically ({@link writeFileAtomic}), but if any write in
+ * the set throws partway through, every file already written *in that same run* is rolled back to
+ * its pre-run bytes (or removed, if it did not exist before) rather than left in a mixed old/new
+ * state. Since this is the one command that can write many files in a single invocation, it is also
+ * the one that needs this cross-file guarantee, on top of `writeFileAtomic`'s own per-file one.
+ *
+
+ * **A linked task id that no longer resolves aborts the whole run before any write** (`not_found`,
+ * exit 3) — every linked task, across every scoped concept, is resolved up front, mirroring
+ * `commands/link.ts`'s "validate before write" precedent: a doc's `status` and managed block must
+ * never be computed from a partially-resolved task set.
+ *
+ * **`lore` is the sole committer of `backlog/`** (ADR-0012, design §2.4): after its own `docs/`
+ * writes, `sync` calls `state.ts`'s {@link commitBacklogIfDirty} to commit whatever is currently
+ * uncommitted under `backlog/`. This is independent of whether `sync` itself changed anything in
+ * `docs/`, and (like every write here) is skipped entirely under `--dry-run`. `link`/`unlink`/
+ * `rename` already commit their own touched files via `commitBacklogFiles` right after writing them
+ * (LORE-49) — nothing is left pending for `sync` on their account. `sync`'s commit step is a
+ * catch-all sweep: it picks up whatever is still dirty under `backlog/` from another source (a
+ * human's direct `backlog task edit`, or a prior run's commit that failed).
+ *
+ * A concept with `tasks:` but no managed-block markers is a fail-loud `validation` error
+ * (`core/managed-block.ts`'s own contract, ADR-0008) — `sync` never guesses or writes a partial
+ * block. A concept with no `tasks:` at all is never touched, and (mirroring `rename.ts`) no
+ * {@link BacklogAdapter} is even constructed unless at least one scoped concept links a task.
+ *
+ * An on-disk `index.md` whose directory no longer holds any concept — directly or via any
+ * descendant, e.g. after a manual `rm`/`mv` outside `lore rename` — is an **orphan**
+ * (`core/indexes.ts`'s {@link orphanedIndexPaths}, LORE-150): `generateIndexes` never emits an entry
+ * for it (only live directories are regenerated), so unlike every other stale file it is never
+ * written. It is still surfaced, distinctly from an "updated" file, in `SyncReport.orphanedIndexes`
+ * and the rendered report — left untouched on disk (deleting a hand-authored file is not this
+ * command's call to make unprompted) but no longer silently unmentioned.
+ */
+
+import { dirname, join } from "node:path";
+import type { BacklogAdapter } from "../adapters/backlog";
+import { realGitAdapter, resolveHeadSha } from "../adapters/git";
+import { type BundleGraph, loadBundle } from "../core/bundle";
+import { type Concept, idFromPath, parseConcept, serializeConcept } from "../core/concept";
+import { generateIndexes, orphanedIndexPaths } from "../core/indexes";
+import { buildLog, type GitAdapter, generateLog } from "../core/log";
+import { regenerateTaskBlock } from "../core/managed-block";
+import { loadProfile, type Profile } from "../core/profile";
+import { type ReconciledStatus, validateReconcileInputs } from "../core/reconcile";
+import { DOCS_DIR } from "../core/scaffold";
+import { EXIT_OK, LoreError, readFileIfPresent, WarningCollector, type Writer } from "../errors";
+import { emit, type OutputContext, type Renderable } from "../output";
+import {
+  type BacklogCommitResult,
+  bunGitSpawn,
+  commitBacklogIfDirty,
+  type GitSpawn,
+  renderBacklogCommitLine,
+} from "../state";
+import { parseCommandArgs } from "./args";
+import { readIndexBytes, readSource } from "./discover";
+import { type AtomicRollbackWrite, assertNoSymlinkInAnyPath, ensureDir, writeManyAtomicOrRollback } from "./fswrite";
+import { gatherReconciliation, linkedConcepts, readReconcileConfig } from "./reconcile-shared";
+
+/** The reserved log file name, excluded from concept scanning (mirrors `rename.ts`'s index handling). */
+const LOG_FILE = "log.md";
+
+/** Options for {@link runSync}; `root`, the streams, and the adapters/seams are injectable for tests. */
+export interface SyncOptions {
+  /** The repo root the `docs/` bundle (and `backlog/`) resolve 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 constructed when at least one scoped concept links a task. */
+  adapter?: BacklogAdapter;
+  /** The git-history adapter (`core/log.ts`) for `log.md`; defaults to the real `git log`-shelling adapter. */
+  gitAdapter?: GitAdapter;
+  /** Resolves `HEAD` to a sha (or `null` with no commits yet); defaults to the real `git rev-parse HEAD`. */
+  resolveHead?: (root: string) => string | null;
+  /** The git-write seam (`state.ts`) for committing `backlog/`; defaults to the real `git` binary. */
+  gitSpawn?: GitSpawn;
+}
+
+/** The parsed form of `lore sync`'s arguments. */
+interface SyncArgs {
+  /** Concept ids/paths to scope reconciliation + managed-block regen to; empty means every concept. Index/log regeneration is always whole-bundle. */
+  paths: string[];
+  /** `--dry-run`: report what would change, write nothing (docs/ or backlog/). */
+  dryRun: boolean;
+  /** `--no-index`: skip both index.md and log.md regeneration. */
+  noIndex: boolean;
+}
+
+/** One written (or, under `--dry-run`, would-be-written) file, for the report. */
+interface ChangedFile {
+  /** Repo-relative POSIX path of the file. */
+  readonly path: string;
+}
+
+/** The `sync.result` payload. */
+export interface SyncReport {
+  /** Every `docs/` file that changed (or would change), ascending. */
+  readonly files: readonly ChangedFile[];
+  /** How many files changed (== `files.length`). */
+  readonly filesChanged: number;
+  /** The `backlog/` commit outcome — always `{committed: false, files: []}` under `--dry-run`. */
+  readonly backlogCommit: BacklogCommitResult;
+  /** Whether this was a `--dry-run` (nothing was written). */
+  readonly dryRun: boolean;
+  /**
+   * Repo-relative paths of on-disk `index.md` files whose directory no longer holds any concept,
+   * directly or via any descendant (LORE-150) — e.g. after a manual `rm`/`mv` outside `lore rename`.
+   * Reported distinctly from `files` (not counted in `filesChanged`): the file is left untouched on
+   * disk, since deleting a hand-authored file is not this command's call to make unprompted, but it
+   * is no longer silently unmentioned either. Always `[]` when `--no-index` skipped index regen.
+   * Ascending.
+   */
+  readonly orphanedIndexes: readonly string[];
+}
+
+/**
+ * Run `lore sync`: reconcile every scoped concept's `status` and managed task block from live
+ * Backlog data, regenerate `index.md`/`log.md` (unless `--no-index`), write every changed file
+ * (unless `--dry-run`), commit any dirty `backlog/` changes, emit the `sync.result`, and return the
+ * exit code.
+ *
+ * @returns `0` on success (a fully clean tree is still `0` — idempotent). Throws (never returns) a
+ *   `not_found` {@link LoreError} (exit `3`) when a linked task id no longer exists, or `validation`/
+ *   `drift` (exit `6`) when reconciliation, the managed block, or the `backlog/` commit fails.
+ */
+export async function runSync(options: SyncOptions): Promise<number> {
+  const parsed = parseSyncArgs(options.args);
+  const docsRoot = join(options.root, DOCS_DIR);
+  const advisories = new WarningCollector();
+  // Loaded unconditionally, before the bundle: loadBundle validates every concept's frontmatter
+  // against this profile (LORE-84), and it runs regardless of reconciliation eligibility, so the
+  // profile can no longer be deferred to the eligibility-gated block below.
+  const profile = loadProfile({ root: options.root });
+  const graph = loadBundle(docsRoot, { warnings: advisories, profile });
+  advisories.flush({ color: options.output.color, stderr: options.stderr });
+
+  const scoped = scopeConcepts(graph, parsed.paths);
+  // This command's precedence for when MULTIPLE local config sources are simultaneously broken:
+  // a malformed .lore/profile.toml now surfaces FIRST, unconditionally — profile loads above,
+  // before loadBundle, so its own parse failure throws before docsRoot is even walked (LORE-84
+  // superseded the pre-LORE-27 "profile loads only when reconciliation is eligible" precedence:
+  // loadBundle needs the same profile for every sync run, eligible or not). backlog/config.yml/
+  // .lore/config.toml SYNTAX errors (readReconcileConfig, a plain read — no semantic check yet)
+  // surface next, then validateReconcileInputs's SEMANTIC checks (a duplicate flow entry, an
+  // invalid override target) — both still conditioned on eligibility (mirrors gatherReconciliation's
+  // own check) so a bundle with nothing to reconcile never pays for either. The resolved,
+  // already-validated config is then passed straight into gatherReconciliation so it is never
+  // read/validated a second time.
+  const eligible = linkedConcepts(scoped).length > 0;
+  const config = eligible ? readReconcileConfig(options.root) : undefined;
+  if (config !== undefined) {
+    validateReconcileInputs(config.flow, config.overrides);
+  }
+  const targets = await gatherReconciliation(options.root, scoped, options.adapter, config);
+
+  // bundle-relative path -> { before: pre-run bytes (undefined if the file didn't exist), after: new
+  // bytes }. `before` is captured here, at diff time, alongside `after` — never re-derived later —
+  // so a mid-run rollback (LORE-120) always restores exactly what was actually on disk before this
+  // run touched it, not a re-read that could itself race against a concurrent edit.
+  const writes = new Map<string, { before: string | undefined; after: string }>();
+  for (const { concept, newStatus, rows } of targets) {
+    const docPath = `${DOCS_DIR}/${concept.path}`;
+    const original = readSource(join(docsRoot, concept.path), docPath);
+    // Derived from the FRESHLY re-read `original` bytes, not the stale in-memory `concept` object
+    // captured (in `targets`, via `gatherReconciliation`) before the async Backlog round-trip: a
+    // concurrent on-disk edit landing on this doc during that round-trip must survive a
+    // status-changing sync write, not be silently discarded in favor of a pre-round-trip snapshot
+    // (LORE-119).
+    const base =
+      newStatus !== null && newStatus !== concept.frontmatter.status
+        ? withUpdatedStatus(concept.path, original, newStatus, profile)
+        : original;
+
+    const final = regenerateTaskBlock(base, rows, { docPath });
+    if (final !== original) {
+      writes.set(concept.path, { before: original, after: final });
+    }
+  }
+
+  const orphanedIndexes = parsed.noIndex ? [] : regenerateIndexAndLog(options, docsRoot, graph, writes);
+
+  if (!parsed.dryRun) {
+    // Swept as a whole BEFORE any write starts (LORE-93 AC#5): ensureDir's own per-call guard
+    // below is reactive — in this loop, it would only refuse once it REACHES a bad target, by
+    // which point earlier targets in the same `writes` map may already be on disk. A single
+    // preflight over every planned path makes the write either fully proceed or refuse before
+    // touching anything.
+    assertNoSymlinkInAnyPath(
+      options.root,
+      [...writes.keys()].map((path) => `${DOCS_DIR}/${path}`),
+    );
+    // All-or-nothing across the whole set (LORE-120): every parent directory is created up front
+    // (mkdir -p is itself idempotent — nothing to roll back there), then the actual byte writes go
+    // through writeManyAtomicOrRollback, which undoes every write already applied in this same run
+    // if a later one throws, rather than leaving an arbitrary prefix of `writes` committed and the
+    // rest not.
+    const rollbackWrites: AtomicRollbackWrite[] = [];
+    for (const [path, { before, after }] of writes) {
+      ensureDir(options.root, dirname(`${DOCS_DIR}/${path}`));
+      rollbackWrites.push({ abs: join(docsRoot, path), relPath: `${DOCS_DIR}/${path}`, before, after });
+    }
+    writeManyAtomicOrRollback(rollbackWrites);
+  }
+
+  let backlogCommit: BacklogCommitResult = { committed: false, files: [] };
+  if (!parsed.dryRun) {
+    const gitSpawn = options.gitSpawn ?? bunGitSpawn(options.root);
+    backlogCommit = await commitBacklogIfDirty(gitSpawn);
+  }
+
+  const files = [...writes.keys()].sort().map((path) => ({ path: `${DOCS_DIR}/${path}` }));
+  const report: SyncReport = {
+    files,
+    filesChanged: files.length,
+    backlogCommit,
+    dryRun: parsed.dryRun,
+    orphanedIndexes: orphanedIndexes.map((path) => `${DOCS_DIR}/${path}`),
+  };
+  emit(reportRenderable(report), options.output, options.stdout);
+  return EXIT_OK;
+}
+
+/**
+ * Re-parse `raw` — the freshly re-read on-disk bytes for the concept at `path` — and re-serialize it
+ * with `status` applied to its frontmatter. Every other frontmatter key and the body come straight
+ * from `raw` itself, never from an earlier in-memory snapshot, so a concurrent on-disk edit made to
+ * the doc between the initial bundle load and this status-changing write survives it (LORE-119). Only
+ * `status` is overwritten — sync's `newStatus` is always the authoritative, live-reconciled value, so
+ * a concurrent edit to `status` itself (were one to land) is still resolved to what Backlog reports,
+ * exactly as an uncontended sync would resolve it.
+ */
+function withUpdatedStatus(path: string, raw: string, status: ReconciledStatus, profile: Profile): string {
+  const fresh = parseConcept(path, raw, { profile });
+  return serializeConcept({ ...fresh, frontmatter: { ...fresh.frontmatter, status } }, { profile });
+}
+
+// ── Index + log regeneration ────────────────────────────────────────────────────
+
+/**
+ * Regenerate every `index.md` and `log.md`, adding an entry to `writes` for each one whose bytes
+ * actually changed, and return the bundle-relative paths of any **orphaned** on-disk `index.md`
+ * files — one whose directory no longer holds a concept, directly or via any descendant (LORE-150) —
+ * so the caller can report them distinctly instead of `generateIndexes` silently never mentioning
+ * them (it only ever emits entries for live directories; a stale disk entry outside that set is
+ * simply absent from its returned map, indistinguishable from "unchanged" without this comparison).
+ * Always whole-bundle, regardless of `[paths…]` scoping — both index regeneration and orphan
+ * detection are inherently global (a hub lists its whole directory; the log is derived from all of
+ * git history).
+ */
+function regenerateIndexAndLog(
+  options: SyncOptions,
+  docsRoot: string,
+  graph: BundleGraph,
+  writes: Map<string, { before: string | undefined; after: string }>,
+): readonly string[] {
+  const diskIndexBytes = readIndexBytes(docsRoot);
+  const regeneratedIndexes = generateIndexes(graph, { existing: diskIndexBytes });
+  for (const [path, bytes] of regeneratedIndexes) {
+    const before = diskIndexBytes.get(path);
+    if (bytes !== before) {
+      writes.set(path, { before, after: bytes });
+    }
+  }
+  const orphaned = orphanedIndexPaths(graph, diskIndexBytes);
+
+  const resolveHead = options.resolveHead ?? resolveHeadSha;
+  const headSha = resolveHead(options.root);
+  const logBytes =
+    headSha === null
+      ? generateLog([], { root: DOCS_DIR })
+      : buildLog(options.gitAdapter ?? realGitAdapter(options.root), { to: headSha }, { root: DOCS_DIR });
+  const existingLog = readFileIfPresent(join(docsRoot, LOG_FILE), `${DOCS_DIR}/${LOG_FILE}`);
+  if (logBytes !== existingLog) {
+    writes.set(LOG_FILE, { before: existingLog, after: logBytes });
+  }
+  return orphaned;
+}
+
+// ── Scoping ────────────────────────────────────────────────────────────────────
+
+/**
+ * Filter `graph`'s concepts to those under one of `paths` (each resolved to a concept id via
+ * {@link idFromPath}, matched as an exact id or a directory prefix); an empty `paths` scopes to
+ * every concept. Index/log regeneration is never scoped this way (see {@link regenerateIndexAndLog}).
+ */
+function scopeConcepts(graph: BundleGraph, paths: readonly string[]): Concept[] {
+  const all = [...graph.concepts.values()];
+  if (paths.length === 0) {
+    return all;
+  }
+  // Strip a trailing slash before deriving the id: idFromPath() preserves it verbatim, and a
+  // trailing "/" (natural from shell tab-completion of a directory) would otherwise never match
+  // any concept id (`c.id === "stories/foo/"` and `c.id.startsWith("stories/foo//")` are both
+  // always false), silently scoping to nothing rather than the whole "stories/foo" directory.
+  const prefixes = paths.map((p) => idFromPath(p.replace(/\/+$/, "")));
+  for (const prefix of prefixes) {
+    if (!all.some((c) => matchesScope(c.id, prefix))) {
+      // A path/id that matches nothing (a typo, a trailing slash that still resolves to no
+      // directory, a concept that was never linked) is a fail-loud usage error, not a silent
+      // empty scope — matching link/unlink/rename's `conceptNotInBundle` precedent: a `lore sync`
+      // that quietly reconciled zero concepts and reported "0 files changed" would read as "already
+      // in sync" when it never looked at the intended target at all.
+      throw new LoreError(
+        "not_found",
+        `no concept found at or under "${prefix}"`,
+        "check the id/path and try again — run `lore query` or `lore graph` to see known concept ids",
+        { path: prefix },
+      );
+    }
+  }
+  return all.filter((c) => prefixes.some((prefix) => matchesScope(c.id, prefix)));
+}
+
+/** Whether `id` is exactly `prefix` or lives under it as a directory prefix. */
+function matchesScope(id: string, prefix: string): boolean {
+  return id === prefix || id.startsWith(`${prefix}/`);
+}
+
+// ── Argument parsing ───────────────────────────────────────────────────────────
+
+/** Parse `sync`'s tokens into `[paths…]`, `--dry-run`, and `--no-index` via the shared parser. */
+function parseSyncArgs(args: readonly string[]): SyncArgs {
+  const { positionals, flags } = parseCommandArgs(args, "sync");
+  return { paths: positionals, dryRun: flags.has("dry-run"), noIndex: flags.has("no-index") };
+}
+
+// ── Output ─────────────────────────────────────────────────────────────────────
+
+/** The per-result-type rendering bundle for `sync` (output.ts dispatches on the mode). */
+function reportRenderable(data: SyncReport): Renderable<SyncReport> {
+  return { kind: "sync.result", data, pretty: render, plain: render };
+}
+
+/**
+ * One line per changed file, one line per orphaned index (distinct from "updated": the file is
+ * reported but not written, LORE-150), the backlog-commit outcome (if any), then a summary line.
+ * (No color: no severities.)
+ */
+function render(data: SyncReport): string {
+  const verb = data.dryRun ? "would update" : "updated";
+  const lines = data.files.map((f) => `${verb} ${f.path}`);
+  for (const path of data.orphanedIndexes) {
+    lines.push(`orphaned index ${path} (no concepts remain under this directory; left untouched)`);
+  }
+  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");
+}

package/src/commands/tasks.ts

@@ -0,0 +1,271 @@
+/**
+ * commands/tasks.ts — `lore tasks <id> [--status <S>]` (cli-surface §tasks).
+ *
+ * The thin, read-only view of a concept's **live** Backlog task rollup: it loads the
+ * `docs/` bundle, resolves the target concept by id, reads that concept's `tasks:`
+ * frontmatter list, and fetches each linked task's CURRENT state from the Backlog
+ * JSON adapter — the same live data `lore sync` materializes into a concept's managed
+ * `<!-- lore:tasks -->` block, but rendered directly here and written nowhere.
+ *
+ * Output follows the uniform CLI modes: the `{schemaVersion, kind: "tasks.rollup",
+ * data}` envelope under `--json` — `data` an object `{ concept, status?, tasks }` whose
+ * `tasks` are `{id, title, status}` rows in the concept's own `tasks:` order (wrapped in
+ * an object, like every sibling list command, so the contract can grow additively) —
+ * and otherwise an aligned text table. `--status <S>` filters the rows to one Backlog
+ * status (case-insensitive match on the configured label) and is echoed back on `status`.
+ *
+ * Failure modes, in the order they can occur:
+ * - a bad flag / missing-or-duplicate `<id>` is a `usage` error (exit 2);
+ * - an `<id>` absent from the bundle is a `not_found` error (exit 3);
+ * - Backlog being unavailable is fail-fast: the adapter's capability probe runs UP FRONT,
+ *   so a missing binary (exit 3) or a stock, non-`--json` binary (exit 6) is reported
+ *   before any per-task read. That ordering is what lets a `viewTask` null AFTER a passing
+ *   probe mean, unambiguously, "this linked id is a dangling reference" — dropped from the
+ *   rollup with a stderr advisory, exit 0 — rather than "Backlog is broken". `orphans`
+ *   (LORE-32) is the dedicated dangling-link report; `tasks` only notes them so its rollup
+ *   shows just the live tasks. A per-task read that *fails* (Backlog drift) still propagates;
+ *   a per-task read that *succeeds* but answers with a DIFFERENT task's id than requested is
+ *   also a hard `not_found` error (exit 3), never silently attributed to the requested row —
+ *   via the same shared guard `commands/link.ts`'s `verifiedViewTask` exports (LORE-183; this
+ *   module no longer hand-maintains its own copy, LORE-125) — the SAME guard `reconcile-shared.ts`'s
+ *   `resolveTaskDetails` (originally LORE-122) now also delegates to (LORE-183), so the
+ *   comparison/`LoreError` lives in exactly one place across `link.ts`/`tasks.ts`/`reconcile-shared.ts`.
+ */
+
+import { join } from "node:path";
+import type { BacklogAdapter } from "../adapters/backlog";
+import { conceptNotInBundle, loadBundle, toRefList } from "../core/bundle";
+import { idFromPath } 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, type OutputContext, type Renderable, renderTaskSummaryRows, type TaskSummaryRow } from "../output";
+import { parseCommandArgs, singleOptionValue, usage } from "./args";
+import { mapWithConcurrency, TASK_DETAILS_CONCURRENCY } from "./concurrency";
+import { dedupeTaskIds, defaultAdapter, verifiedViewTask } from "./link";
+
+/** Options for {@link runTasks}; `root`, the streams, and the adapter are injectable for tests. */
+export interface TasksOptions {
+  /** 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 positional + 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 tasks`'s arguments. */
+interface TasksArgs {
+  /** The target concept id (positional, already {@link idFromPath}-normalized). */
+  id: string;
+  /** The `--status` filter, when given (case-insensitively matched against each task's live status). */
+  status?: string;
+}
+
+/** One row of the rollup: a linked task's live identity + current Backlog status, in `tasks:` order. */
+export type TaskRollupRow = TaskSummaryRow;
+
+/** The `tasks.rollup` payload: the concept, the applied `--status` filter (when any), and the live rows. */
+export interface TaskRollup {
+  /** The resolved concept id whose `tasks:` were rolled up. */
+  readonly concept: string;
+  /** The applied `--status` filter, canonicalized to the matched rows' Backlog casing (raw input when nothing matched); omitted when no filter was given. */
+  readonly status?: string;
+  /** The linked tasks' live data, in the concept's own `tasks:` order (dangling ids dropped). */
+  readonly tasks: readonly TaskRollupRow[];
+}
+
+/**
+ * Run `lore tasks`: parse the arguments, load the bundle, resolve the concept, fetch its
+ * linked tasks' live status from Backlog, emit the `tasks.rollup`, and return `0`. Async
+ * because it drives the Backlog subprocess. See the module docstring for the failure modes.
+ */
+export async function runTasks(options: TasksOptions): Promise<number> {
+  const parsed = parseTasksArgs(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 warnings before the not_found throw below, so an advisory explaining *why* a
+  // file is not a concept survives on exactly the path that most needs it (mirrors `lore context`).
+  advisories.flush({ color: options.output.color, stderr: options.stderr });
+
+  const concept = graph.concepts.get(parsed.id);
+  if (concept === undefined) {
+    throw conceptNotInBundle(parsed.id);
+  }
+
+  const linked = dedupeTaskIds(toRefList(concept.frontmatter.tasks));
+  const tasks = await resolveRollup(linked, parsed.status, options);
+  const status = echoedStatus(parsed.status, tasks);
+  const data: TaskRollup = status === undefined ? { concept: parsed.id, tasks } : { concept: parsed.id, status, tasks };
+
+  emit(tasksRenderable(data), options.output, options.stdout);
+  return EXIT_OK;
+}
+
+/**
+ * The `--status` filter to echo on the envelope. `--status` matches case-insensitively, so echoing the
+ * user's raw input verbatim could disagree in case with every row it selected (`--status done` →
+ * `status: "done"` beside rows whose status is `"Done"`). Canonicalize it to the matched rows' actual
+ * Backlog casing so `data.status` always agrees with the tasks it produced; fall back to the raw filter
+ * only when nothing matched (no row to canonicalize against). `undefined` when no filter was given.
+ */
+function echoedStatus(filter: string | undefined, tasks: readonly TaskRollupRow[]): string | undefined {
+  if (filter === undefined) {
+    return undefined;
+  }
+  return tasks[0]?.status ?? filter;
+}
+
+/**
+ * Resolve every linked task id to its live {@link TaskRollupRow}, filtered to `status` when given.
+ * Returns `[]` without touching Backlog when the concept links nothing (mirrors
+ * `gatherReconciliation` constructing no adapter for an uncoupled concept).
+ *
+ * The Backlog capability probe runs UP FRONT so a missing/incapable binary fails fast (exit 3/6)
+ * before any per-task read — the disambiguation the module docstring relies on. Reads then run
+ * concurrently, bounded to {@link TASK_DETAILS_CONCURRENCY} in flight at once via the shared
+ * {@link mapWithConcurrency} worker-pool (mirroring `resolveTaskDetails`'s own LORE-111 fix, so a
+ * concept whose `tasks:` list links many ids never fans out one Backlog CLI subprocess per id fully
+ * concurrently). Each read's outcome is captured into a settled-result array, in `tasks:` order, so a
+ * second failing read never escapes as an unhandled rejection: the FIRST read that *fails* — in
+ * `tasks:` order — is rethrown as a hard error (Backlog drift), exactly as `lore check`/`sync` treat
+ * it, while a clean `null` — a task Backlog does not know — is soft: dropped from the rollup with a
+ * stderr advisory (`orphans` owns the dangling-link report).
+ *
+ * Each read goes through `commands/link.ts`'s exported {@link verifiedViewTask} (LORE-183), not a
+ * raw `adapter.viewTask` call: it checks the returned detail's own `id` against the id actually
+ * requested at that position (case-insensitively) and throws before this function ever sees a
+ * mismatched detail — `viewTask` is keyed by id, but nothing enforces that the detail it returns
+ * actually carries that id back, and trusting it blindly would let a mismatch silently attribute
+ * another task's title/status to this row. That thrown `LoreError` surfaces here as an ordinary
+ * rejected settle, handled identically to any other failed read (a hard `not_found` failure,
+ * exactly as before LORE-125 folded this module's own copy of the check into the shared helper).
+ * The `--status` filter is applied last, to the live rows only.
+ */
+async function resolveRollup(
+  linked: readonly string[],
+  status: string | undefined,
+  options: TasksOptions,
+): Promise<TaskRollupRow[]> {
+  if (linked.length === 0) {
+    return [];
+  }
+  const adapter = options.adapter ?? defaultAdapter(options.root);
+  await adapter.probe();
+
+  const settled: PromiseSettledResult<Awaited<ReturnType<typeof verifiedViewTask>>>[] = new Array(linked.length);
+  await mapWithConcurrency(
+    linked.map((id, index) => ({ id, index })),
+    TASK_DETAILS_CONCURRENCY,
+    async ({ id, index }) => {
+      try {
+        const value = await verifiedViewTask(adapter, id);
+        settled[index] = { status: "fulfilled", value };
+      } catch (reason) {
+        settled[index] = { status: "rejected", reason };
+      }
+    },
+  );
+  const dangling: string[] = [];
+  const rows: TaskRollupRow[] = [];
+  for (let i = 0; i < linked.length; i++) {
+    const result = settled[i] as PromiseSettledResult<Awaited<ReturnType<typeof verifiedViewTask>>>;
+    if (result.status === "rejected") {
+      // A read that FAILED — Backlog drift, or `verifiedViewTask`'s own id-mismatch guard refusing
+      // an adapter detail that doesn't belong to the requested task — is hard-failed on the first,
+      // in tasks: order, before any partial rollup or advisory is emitted.
+      throw result.reason;
+    }
+    if (result.value === null) {
+      dangling.push(linked[i] as string);
+      continue;
+    }
+    rows.push({ id: result.value.id, title: result.value.title, status: result.value.status });
+  }
+  if (dangling.length > 0) {
+    warnDangling(dangling, options);
+  }
+
+  return status === undefined ? rows : rows.filter((row) => row.status.toLowerCase() === status.toLowerCase());
+}
+
+/**
+ * Advise (on stderr) that one or more `tasks:` ids no longer resolve to a live Backlog task and were
+ * dropped from the rollup — a coupling gap worth surfacing without failing the read (`lore orphans`
+ * is the CI-grade report). Routed through the shared {@link WarningCollector} so it renders with the
+ * exact `warning:`-prefix format and coloring as this command's load advisories and every other lore
+ * warning, rather than a hand-painted line.
+ */
+function warnDangling(ids: readonly string[], options: TasksOptions): void {
+  const noun = ids.length === 1 ? "task" : "tasks";
+  const advisories = new WarningCollector();
+  advisories.add(`${ids.length} linked ${noun} not in Backlog, dropped from the rollup: ${ids.join(", ")}`);
+  advisories.flush({ color: options.output.color, stderr: options.stderr });
+}
+
+// ── Argument parsing ───────────────────────────────────────────────────────────
+
+/**
+ * Parse `tasks`'s tokens into the required `<id>` positional and the value flag `--status <S>` (also
+ * accepting the `--status=value` form). Commander has already resolved Lore's global flags, so a
+ * `--`-prefixed token here is a command flag: an unrecognized one, a repeated/value-less `--status`, a
+ * missing `<id>`, or a second positional is a `usage` error (exit 2). A `--` ends option parsing. The
+ * `<id>` is {@link idFromPath}-normalized so path/`.md`/`./` forms resolve (mirrors `lore context`).
+ */
+function parseTasksArgs(args: readonly string[]): TasksArgs {
+  const parsed = parseCommandArgs(args, "tasks");
+  const positionals = parsed.positionals;
+  const status = singleOptionValue(parsed, "status");
+  if (status === "") {
+    throw usage("--status needs a value", 'pass a value, e.g. `--status "In Progress"`');
+  }
+  if (positionals.length === 0) {
+    throw usage(
+      "`lore tasks` needs a concept id",
+      "give the concept whose task rollup to show, e.g. `lore tasks stories/x`",
+    );
+  }
+  if (positionals.length > 1) {
+    throw usage(`unexpected argument "${positionals[1]}"`, "run `lore tasks <id> [--status <S>]`");
+  }
+  return { id: idFromPath(positionals[0] as string), status };
+}
+
+// ── Output ─────────────────────────────────────────────────────────────────────
+
+/**
+ * The rendering bundle for `tasks` (output.ts dispatches on the mode). `--json` carries the structured
+ * {@link TaskRollup}; the pretty/plain text is an aligned table. The two text modes differ only in the
+ * painted header, so they share one renderer.
+ */
+function tasksRenderable(data: TaskRollup): Renderable<TaskRollup> {
+  return {
+    kind: "tasks.rollup",
+    data,
+    pretty: (d, opts) => renderTable(d, opts.color),
+    plain: (d) => renderTable(d, false),
+  };
+}
+
+/**
+ * A human/pipe-stable rollup: a header naming the concept, its live task count, and the `--status`
+ * filter (when any), then one `  <id>  <status>  <title>` row per live task (columns padded to align).
+ * An empty rollup renders a single explanatory line. ANSI only on the header, and only when `color`.
+ */
+function renderTable(data: TaskRollup, color: boolean): string {
+  const filter = data.status !== undefined ? `, status "${data.status}"` : "";
+  const noun = data.tasks.length === 1 ? "task" : "tasks";
+  const header = paint(`tasks: ${data.concept} — ${data.tasks.length} ${noun}${filter}`, ANSI.green, color);
+  if (data.tasks.length === 0) {
+    return `${header}\n${data.status !== undefined ? "(no linked tasks match that status)" : "(no linked tasks)"}`;
+  }
+  return [header, ...renderTaskSummaryRows(data.tasks)].join("\n");
+}