@hassangameryt/freeflow 0.8.0 → 0.9.0

package/skills/track-work/scripts/lib/store.mjs

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { execFile as execFileCallback } from "node:child_process";
 import { lstat, mkdir, readdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 
@@ -30,12 +30,14 @@ async function gitCommand(root, args) {
   }
 }
 
-async function assertGitSafePath(root, path) {
+async function assertGitSafePath(root, path, { directory = false } = {}) {
   const repository = await gitCommand(root, ["rev-parse", "--show-toplevel"]);
   if (!repository.ok) return;
   const repositoryRoot = canonicalPath(repository.stdout.trim());
   const relativePath = relative(repositoryRoot, canonicalPath(path)).split(sep).join("/");
-  const ignored = await gitCommand(repositoryRoot, ["check-ignore", "--no-index", "-q", "--", relativePath]);
+  // A trailing slash lets a directory-only rule such as `.freeflow/*/` match a folder that does not exist yet.
+  const ignorePath = directory ? `${relativePath}/` : relativePath;
+  const ignored = await gitCommand(repositoryRoot, ["check-ignore", "--no-index", "-q", "--", ignorePath]);
   if (!ignored.ok) fail("unignored-path", `Record path is not ignored by Git: ${relativePath}`);
   const tracked = await gitCommand(repositoryRoot, ["ls-files", "--error-unmatch", "--", relativePath]);
   if (tracked.ok) fail("tracked-path", `Record path is already tracked by Git: ${relativePath}`);
@@ -67,21 +69,49 @@ async function assertNoSymlinkPath(target, stopAt) {
   }
 }
 
+/** The marker a project store keeps at its root; see registry.mjs. */
+export const STORE_MARKER = "store.json";
+
+/** In a tasks directory: the highest task number a removal took away, so numbering never goes back. */
+export const LAST_TASK_NUMBER = ".last-task-number";
+
+/** Whether root is a project store: its store.json is the registry's marker, not some other file of that name. */
+function isStore(root) {
+  try {
+    const marker = JSON.parse(readFileSync(join(root, STORE_MARKER), "utf8"));
+    return marker?.version === 1 && typeof marker.project === "string";
+  } catch {
+    return false;
+  }
+}
+
+/** A repository keeps its records in .freeflow/tasks; a project store, marked by store.json, in tasks. */
 export function taskRoot(root) {
-  return resolve(root, ".freeflow", "tasks");
+  return isStore(root) ? resolve(root, "tasks") : resolve(root, ".freeflow", "tasks");
+}
+
+/** The project store holding an absolute record path (<store>/tasks/<task>/record.md), or undefined. */
+export function storeOf(recordPath) {
+  const store = dirname(dirname(dirname(resolve(recordPath))));
+  return basename(dirname(dirname(resolve(recordPath)))) === "tasks" && isStore(store) ? store : undefined;
 }
 
+/**
+ * The path with every symlink resolved, including for a path that does not exist yet: the nearest existing ancestor is
+ * resolved and the rest appended. Git reports canonical paths, so comparisons with it need the same form.
+ */
 function canonicalPath(path) {
   const candidate = resolve(path);
-  try {
-    return realpathSync(candidate);
-  } catch {
-    const parent = dirname(candidate);
-    if (parent === candidate) return candidate;
+  const missing = [];
+  let current = candidate;
+  for (;;) {
     try {
-      return join(realpathSync(parent), basename(candidate));
+      return join(realpathSync(current), ...missing);
     } catch {
-      return candidate;
+      const parent = dirname(current);
+      if (parent === current) return candidate;
+      missing.unshift(basename(current));
+      current = parent;
     }
   }
 }
@@ -137,15 +167,16 @@ export async function readInput(inputPath, cwd = process.cwd()) {
   }
 }
 
-async function nextTaskNumber(tasks) {
+export async function nextTaskNumber(tasks) {
   let entries = [];
   try {
     entries = await readdir(tasks, { withFileTypes: true });
   } catch (error) {
     if (error?.code !== "ENOENT") throw error;
   }
-  // Numbers are never reused, so an old reference to a deleted task cannot point at a new one.
-  let highest = 0;
+  // Numbers are never reused, so an old reference to a deleted task cannot point at a new one; a removal records the
+  // highest number it took away (LAST_TASK_NUMBER), since its directory is gone.
+  let highest = Number((await readFile(join(tasks, LAST_TASK_NUMBER), "utf8").catch(() => "0")).trim()) || 0;
   for (const entry of entries) {
     const match = /^task-(\d{3,})-/.exec(entry.name);
     if (entry.isDirectory() && match) highest = Math.max(highest, Number(match[1]));
@@ -155,7 +186,7 @@ async function nextTaskNumber(tasks) {
 
 export async function createRecordPath(root, taskName, slug) {
   const tasks = taskRoot(root);
-  await assertGitSafePath(root, tasks);
+  await assertGitSafePath(root, tasks, { directory: true });
   await mkdir(tasks, { recursive: true });
   await assertNoSymlinkPath(tasks, canonicalPath(root));
   const number = await nextTaskNumber(tasks);

package/skills/track-work/scripts/lib/views.mjs

@@ -1,4 +1,12 @@
-import { activeDecisionBlocks, blockLines, parseDocument, sectionContentLines } from "./document.mjs";
+import {
+  activeDecisionBlocks,
+  blockLines,
+  fieldValue,
+  findEntity,
+  hasField,
+  parseDocument,
+  sectionContentLines,
+} from "./document.mjs";
 
 function trimTrailing(lines) {
   const result = [...lines];
@@ -35,6 +43,47 @@ export function renderResume(text) {
 
   chunks.push(joinChunk(document.lines.slice(current.headingIndex, current.end), newline));
   chunks.push(joinChunk(document.lines.slice(future.headingIndex, future.end), newline));
+  const index = historyIndexLines(document);
+  if (index.length) {
+    chunks.push(
+      joinChunk(
+        [
+          "## History index",
+          "",
+          "Closed History, one line per entry. Read an entry with `view entry <ID>`.",
+          "",
+          ...index,
+        ],
+        newline,
+      ),
+    );
+  }
   chunks.push(joinChunk(document.lines.slice(notes.headingIndex, document.lines.length), newline));
   return `${chunks.filter(Boolean).join(`${newline}${newline}`)}${newline}`;
 }
+
+function hasCorrections(document, block) {
+  return blockLines(document, block).some((line) => /^#####\s+Corrections\s*$/.test(line));
+}
+
+function indexLine(document, block) {
+  const state = fieldValue(block, "State");
+  let label = `${block.id} ${state}`;
+  if (state === "superseded" && hasField(block, "Superseded by")) label += ` by ${fieldValue(block, "Superseded by")}`;
+  if (hasField(block, "Recorded")) label += ", recorded retroactively";
+  const corrected = hasCorrections(document, block) ? " (corrected)" : "";
+  return `- ${label} — ${block.title}${corrected}`;
+}
+
+function historyIndexLines(document) {
+  const { decisions, checkpoints, slices } = document.history;
+  const closedDecisions = decisions.blocks.filter((block) => fieldValue(block, "State") !== "active");
+  return [...closedDecisions, ...checkpoints.blocks, ...slices.blocks].map((block) => indexLine(document, block));
+}
+
+export function renderEntries(text, ids) {
+  const document = parseDocument(text);
+  const { newline } = document;
+  const blocks = ids.map((id) => findEntity(document, id));
+  return `${blocks.map((block) => joinChunk(blockLines(document, block), newline)).join(`${newline}${newline}`)}${newline}`;
+}

package/skills/track-work/scripts/working-record.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
+import { existsSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { cwd } from "node:process";
-import { dirname, isAbsolute, sep } from "node:path";
-import { canonicalLines, joinLines, slugify } from "./lib/format.mjs";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { WORK_AGREEMENT_HEADING, canonicalLines, joinLines, slugify } from "./lib/format.mjs";
 import { parseDocument, validateDocument } from "./lib/document.mjs";
 import { runTransition } from "./lib/transitions.mjs";
 import {
@@ -12,9 +13,13 @@ import {
   readInput,
   readRecord,
   resolveRecordPath,
+  storeOf,
   writeInitialAtomically,
 } from "./lib/store.mjs";
-import { renderFull, renderResume } from "./lib/views.mjs";
+import { renderEntries, renderFull, renderResume } from "./lib/views.mjs";
+import { checkEvidencePointers, renderRecover } from "./lib/recover.mjs";
+import { PROJECT_LINK, Registry, TASK_ID, removalText, startCommand } from "./lib/registry.mjs";
+import { searchRecords } from "./lib/search.mjs";
 
 const ROOT_HELP =
   "--record is resolved against --root, which defaults to the current directory; an absolute --record path finds its own root.";
@@ -23,11 +28,15 @@ function usage() {
   return [
     "Usage:",
     "  working-record.mjs init --root <path> --name <task name> [--input <file|->]",
-    "  working-record.mjs view resume|full --record <record.md>",
+    "  working-record.mjs view resume|recover|full --record <record.md>",
+    "  working-record.mjs view entry <ID> [<ID> ...] --record <record.md>",
     "  working-record.mjs validate --record <record.md>",
     "  working-record.mjs <slice|checkpoint|decision|task> <operation> ...",
+    "  working-record.mjs project <new|link|show|list|remove> ...",
+    "  working-record.mjs task <create|import|search|env|here|fanout|remove> ...",
     "",
     ROOT_HELP,
+    "A registered task's ID (such as my-project/task-003) may be given as --record.",
   ].join("\n");
 }
 
@@ -63,16 +72,71 @@ const COMMAND_HELP = new Map([
     "task",
     [
       "Usage: working-record.mjs task <operation> ...",
-      "Operations: task set-state.",
+      "Operations: task set-state; and for projects: task create, task import, task search, task env, task here, task fanout, task remove.",
       "Run working-record.mjs <group> <operation> --help for options and input fields.",
     ].join("\n"),
   ],
   [
     "init",
-    "Usage: init --root <path> --name <task name> [--input <file|->]\nInput: Goal and Next useful action required; the seven Current Context headings and Recovery sources are accepted, and every line must sit under one of them. The record starts active. Use --input - to read Markdown fragments from stdin.",
+    "Usage: init --root <path> --name <task name> [--input <file|->]\nInput: Goal and Next useful action required; the seven Current Context headings, Work agreement (written only when given) and Recovery sources are accepted, and every line must sit under one of them. The record starts active. Use --input - to read Markdown fragments from stdin.",
+  ],
+  [
+    "view",
+    "Usage: view resume|recover|full --record <record.md>\n       view entry <ID> [<ID> ...] --record <record.md>\nresume: the header, Current Context, active Decisions, Current Work, Future Work, a one-line index of closed History, and Notes. recover: the resume view, then each defining artifact and Recovery source with its trigger, whether it resolves and its size, then live Git state and where it disagrees with the record: what recovery after context loss reads first. entry: the named S-NNN, C-NNN, or D-NNN entries exactly as stored. full: the file exactly as stored, valid or not.",
+  ],
+  [
+    "validate",
+    "Usage: validate --record <record.md> [--strict]\nChecks the record's structure, and whether the pointers in Material updates resolve: files (from the repository root or the task folder) and commits. An unresolved pointer is a warning, since it may name a planned path or a commit not fetched yet; with --strict, one on an Evidence or Result line fails. Pointers outside the repository are listed, not checked.",
+  ],
+  [
+    "project",
+    "Usage: working-record.mjs project <operation> ...\nOperations: project new, project link, project show, project list, project remove.\nA project groups tasks; its records live in a store under the Freeflow home (FREEFLOW_HOME, default ~/.freeflow), outside any repository. Create or link a project only when the user asks.",
+  ],
+  [
+    "project new",
+    "Usage: project new --name <name> [--cwd <directory>] [--worktrees <directory>]\nCreates the project and links the repository containing --cwd (default: the current directory) to it. --worktrees is where fan-out puts children's worktrees (default: the repository's parent directory).",
+  ],
+  [
+    "project link",
+    "Usage: project link --name <name> [--cwd <directory>] [--worktrees <directory>]\nLinks another repository to an existing project; --worktrees changes where fan-out puts worktrees.",
+  ],
+  [
+    "task env",
+    "Usage: task env --id <task-id> [--primary <directory>] [--add-dir <directory>] [--remove-dir <directory>]\nPrints where the task's work happens: its primary directory with its current Git branch, and additional directories. The options change it; change it only when the user asks.",
+  ],
+  [
+    "task here",
+    "Usage: task here [--cwd <directory>]\nPrints the registered tasks whose primary directory contains the directory, deepest first.",
+  ],
+  [
+    "task fanout",
+    "Usage: task fanout --parent <task-id> --title <title> --goal <goal> [--path <directory>] [--base <ref>] [--agent <command>]\nCreates a child of the task, a Git worktree for it on branch <project>/<task-NNN>-<slug> (at <worktrees>/<repo>-<slug> unless --path), copies .freeflow/local.json into it when it has none, and makes the worktree the child's directory. The user then starts a session there: --agent is the command that starts this host's agent (such as claude or codex), and the output ends with a command for the user to paste into a new terminal.",
+  ],
+  [
+    "project show",
+    "Usage: project show [--cwd <directory>] [--name <project>]\nPrints a project and its tasks: ID, title, parent, and whether a session owns it. Without --name, the project linked to the repository containing --cwd.",
+  ],
+  ["project list", "Usage: project list\nPrints every project: name, number of tasks, and linked repositories."],
+  [
+    "project remove",
+    "Usage: project remove --name <project>\nMoves the project's store (every task's record) to the trash under the Freeflow home, removes the project and its tasks from the registry, and removes its .freeflow/project links. Git worktrees and branches stay; the output gives the commands to remove them. Run it only when the user asked to remove that project. Never empty the trash: the user does.",
+  ],
+  [
+    "task remove",
+    "Usage: task remove --id <task ID>\nMoves the task's record, and its children's, to the trash under the Freeflow home and removes them from the registry. Task numbers are never reused. Git worktrees and branches stay; the output gives the commands to remove them. Run it only when the user asked to remove that task. Never empty the trash: the user does.",
+  ],
+  [
+    "task create",
+    "Usage: task create --title <title> --goal <goal> [--parent <task-id>] [--cwd <directory>]\nCreates a registered record in the project linked to --cwd, or with --parent a child of that task in its project, and prints its ID and path. A child has no children.",
+  ],
+  [
+    "task import",
+    "Usage: task import --record <record.md> --project <name>\nMoves an unregistered record's task directory into the project's store, with the next free number, and registers it. Ask the user first.",
+  ],
+  [
+    "task search",
+    "Usage: task search --query <text> (--id <task-id> --scope task|tree|project | --project <name>)\nPrints matching lines with the record, entry heading and state. tree is the task's root (its parent, or itself) and the root's children. Read-only.",
   ],
-  ["view", "Usage: view resume|full --record <record.md>"],
-  ["validate", "Usage: validate --record <record.md>"],
   [
     "slice propose",
     "Usage: slice propose --record <record.md> --title <title> --input <file|->\nInput: Intended result required; Type, Expected evidence, and Dependencies optional. Commands set State; input never includes it. Use --input - to read the fragment from stdin.",
@@ -155,7 +219,7 @@ function parseOptions(args) {
       continue;
     }
     if (options[token] !== undefined) throw new CliError(`Duplicate option: ${token}`);
-    if (token === "--help") {
+    if (token === "--help" || token === "--strict") {
       options[token] = true;
       continue;
     }
@@ -172,7 +236,7 @@ function allowedOptions(command, operation) {
   const withNextAction = new Set([...common, "--next-action"]);
   if (command === "init") return new Set(["--root", "--name", "--input", "--help"]);
   if (command === "view") return new Set(["--root", "--record", "--view", "--help"]);
-  if (command === "validate") return new Set(["--root", "--record", "--help"]);
+  if (command === "validate") return new Set(["--root", "--record", "--strict", "--help"]);
   if (command === "slice") {
     if (operation === "propose") return new Set([...common, "--title"]);
     if (operation === "start" || operation === "start-direct") return new Set([...withNextAction, "--title"]);
@@ -195,6 +259,22 @@ function allowedOptions(command, operation) {
   }
   if (command === "task" && operation === "set-state")
     return new Set(["--root", "--record", "--state", "--next-action", "--help"]);
+  if (command === "task" && operation === "create")
+    return new Set(["--title", "--goal", "--parent", "--cwd", "--help"]);
+  if (command === "task" && operation === "import") return new Set(["--record", "--project", "--help"]);
+  if (command === "task" && operation === "search")
+    return new Set(["--query", "--id", "--scope", "--project", "--help"]);
+  if (command === "task" && operation === "env")
+    return new Set(["--id", "--primary", "--add-dir", "--remove-dir", "--help"]);
+  if (command === "task" && operation === "here") return new Set(["--cwd", "--help"]);
+  if (command === "task" && operation === "fanout")
+    return new Set(["--parent", "--title", "--goal", "--path", "--base", "--cwd", "--agent", "--help"]);
+  if (command === "project" && (operation === "new" || operation === "link"))
+    return new Set(["--name", "--cwd", "--worktrees", "--help"]);
+  if (command === "project" && operation === "show") return new Set(["--cwd", "--name", "--help"]);
+  if (command === "project" && operation === "list") return new Set(["--help"]);
+  if (command === "task" && operation === "remove") return new Set(["--id", "--help"]);
+  if (command === "project" && operation === "remove") return new Set(["--name", "--help"]);
   return null;
 }
 
@@ -220,6 +300,8 @@ function rootOption(options) {
     const marker = `${sep}.freeflow${sep}tasks${sep}`;
     const index = record.lastIndexOf(marker);
     if (index > 0) return record.slice(0, index);
+    const store = storeOf(record);
+    if (store) return store;
   }
   return cwd();
 }
@@ -230,6 +312,7 @@ function initialContent(skeletonLines, input) {
   const targets = new Map();
   const names = [
     "Goal",
+    WORK_AGREEMENT_HEADING,
     "What defines this task",
     "Settled",
     "Tentative",
@@ -261,6 +344,9 @@ function initialContent(skeletonLines, input) {
     if (/^## /.test(inputLines[index])) throw new CliError(`Unknown initialization heading: ${inputLines[index]}`);
   }
   const output = [...skeletonLines];
+  // The skeleton has no Work agreement heading: it is written only when the input gives one.
+  if (targets.has(WORK_AGREEMENT_HEADING))
+    output.splice(output.indexOf("### What defines this task"), 0, `### ${WORK_AGREEMENT_HEADING}`, "");
   for (const name of names) {
     const content = targets.get(name);
     if (!content) continue;
@@ -299,25 +385,158 @@ async function readExisting(options) {
   return { root, ...loaded };
 }
 
+/** Projects, registered tasks and search, through the registry under the Freeflow home. */
+async function runRegistry(command, operation, options) {
+  const registry = new Registry();
+  const where = options["--cwd"] ?? cwd();
+  // Where the user can browse the project's records, when the project link was made.
+  const browse = async () => {
+    const link = resolve(await registry.repoRoot(where), PROJECT_LINK);
+    return existsSync(link) ? ` The user can browse its records at ${link}.` : "";
+  };
+  if (command === "project" && operation === "new")
+    return `Project ${await registry.createProject(requireOption(options, "--name"), where, options["--worktrees"])} created and linked to ${await registry.repoRoot(where)}.${await browse()}\n`;
+  if (command === "project" && operation === "link")
+    return `${await registry.repoRoot(where)} linked to project ${await registry.linkProject(requireOption(options, "--name"), where, options["--worktrees"])}.${await browse()}\n`;
+  // Removal moves records to the trash; nothing here empties it, which is the user's to do (Task 006).
+  if (command === "task" && operation === "remove")
+    return `${removalText(await registry.removeTask(requireOption(options, "--id")), registry.trash)}\n`;
+  if (command === "project" && operation === "remove")
+    return `${removalText(await registry.removeProject(requireOption(options, "--name")), registry.trash)}\n`;
+  if (command === "project" && operation === "list") {
+    const data = await registry.read();
+    const projects = Object.entries(data.projects);
+    if (!projects.length) return "No projects.\n";
+    const count = (slug) => Object.values(data.tasks).filter((task) => task.project === slug).length;
+    return `${projects.map(([slug, project]) => `- ${project.name} (${slug}): ${count(slug)} task(s); repositories ${project.repos.join(", ")}`).join("\n")}\n`;
+  }
+  if (command === "project" && operation === "show") {
+    const found = options["--name"] ? await registry.project(options["--name"]) : await registry.projectFor(where);
+    if (!found)
+      return options["--name"]
+        ? `No project named ${options["--name"]}.\n`
+        : `No project is linked to ${await registry.repoRoot(where)}.\n`;
+    const lines = [`Project ${found.project.name} (${found.slug}), store ${found.project.store}`];
+    for (const { id, task } of await registry.projectTasks(found.slug))
+      lines.push(
+        `- ${id} — ${task.title} (${task.record})${task.parent ? `, child of ${task.parent}` : ""}${task.owner ? `, owned by session ${task.owner.session}` : ""}`,
+      );
+    return `${lines.join("\n")}\n`;
+  }
+  if (operation === "create") {
+    const title = requireOption(options, "--title");
+    const goal = requireOption(options, "--goal");
+    const parent = options["--parent"];
+    const slug = parent ? (await registry.task(parent))?.project : (await registry.projectFor(where))?.slug;
+    if (!slug)
+      throw new CliError(parent ? `No task ${parent}.` : `No project is linked to ${await registry.repoRoot(where)}.`);
+    const primary = parent ? undefined : await registry.repoRoot(where);
+    const created = await registry.createTask(slug, title, goal, parent, primary);
+    return `${created.id}\n${created.record}\n`;
+  }
+  if (operation === "import") {
+    const record = resolve(requireOption(options, "--record"));
+    const moved = await registry.importRecord(requireOption(options, "--project"), record);
+    return `${moved.id}\n${moved.record}\n`;
+  }
+  if (operation === "env") {
+    const id = requireOption(options, "--id");
+    if (options["--primary"] || options["--add-dir"] || options["--remove-dir"])
+      await registry.setEnvironment(id, {
+        primary: options["--primary"],
+        add: options["--add-dir"],
+        remove: options["--remove-dir"],
+      });
+    const env = await registry.environment(id);
+    if (!env.primary) return `${id} has no recorded directory.\n`;
+    const facts =
+      env.exists === false
+        ? ["missing"]
+        : [env.worktree ? "Git worktree" : "", env.branch ? `branch ${env.branch}` : ""];
+    const state = facts.filter(Boolean).join(", ");
+    return `${[`primary: ${env.primary}${state ? ` (${state})` : ""}`, ...env.directories.map((dir) => `also: ${dir}`)].join("\n")}\n`;
+  }
+  if (operation === "here") {
+    const found = await registry.here(where);
+    if (!found.length) return `No registered task works in ${resolve(where)}.\n`;
+    return `${found.map(({ id, task }) => `${id} — ${task.title} (${task.environment.primary})`).join("\n")}\n`;
+  }
+  if (operation === "fanout") {
+    const result = await registry.fanout(
+      requireOption(options, "--parent"),
+      requireOption(options, "--title"),
+      requireOption(options, "--goal"),
+      { path: options["--path"], base: options["--base"], cwd: where },
+    );
+    if (result.error) throw new CliError(result.error);
+    return `${result.id}\n${result.path}\nbranch ${result.branch}${result.copiedConfig ? "; copied .freeflow/local.json" : ""}\nNext: open a new terminal and run:\n  ${startCommand(result.path, options["--agent"])}${options["--agent"] ? "" : " (then start the agent there)"}\n`;
+  }
+  if (operation === "search") {
+    const query = requireOption(options, "--query");
+    let records;
+    if (options["--id"]) records = await registry.scope(options["--id"], options["--scope"] ?? "task");
+    else {
+      const slug = (await registry.read()).projects[options["--project"] ?? ""] ? options["--project"] : undefined;
+      if (!slug) throw new CliError("Give --id with --scope, or --project with a project's slug.");
+      records = (await registry.projectTasks(slug)).map(({ id, task }) => [id, task.record]);
+    }
+    return `${await searchRecords(records, query)}\n`;
+  }
+  throw new CliError(`Unknown command: ${command} ${operation}`);
+}
+
 async function runCore(command, rest) {
   const { options, positionals } = parseOptions(rest);
   const operation = positionals[0];
   if (options["--help"]) return commandHelp(command, operation);
   validateCommandOptions(command, operation, options);
+  if (
+    command === "project" ||
+    (command === "task" && ["create", "import", "search", "env", "here", "fanout", "remove"].includes(operation))
+  )
+    return runRegistry(command, operation, options);
+  // A registered task's ID stands for its record's path.
+  if (typeof options["--record"] === "string" && TASK_ID.test(options["--record"])) {
+    const task = await new Registry().task(options["--record"]);
+    if (!task) throw new CliError(`No task ${options["--record"]} in the registry.`);
+    options["--record"] = task.record;
+  }
   if (command === "init") return initialize(options);
   if (command === "view") {
-    if (positionals.length > 1) throw new CliError("View accepts only resume or full");
     const view = positionals[0] ?? options["--view"];
-    if (!view || !["resume", "full"].includes(view)) throw new CliError("View must be resume or full");
+    if (!view || !["resume", "recover", "full", "entry"].includes(view))
+      throw new CliError("View must be resume, recover, full, or entry");
+    const ids = positionals.slice(1);
+    if (view === "entry") {
+      if (!ids.length) throw new CliError("View entry needs at least one S-NNN, C-NNN, or D-NNN ID");
+      const invalid = ids.find((id) => !/^[SCD]-\d{3,}$/.test(id));
+      if (invalid) throw new CliError(`Not an entry ID: ${invalid}`);
+    } else if (ids.length) throw new CliError(`View ${view} accepts no further arguments`);
     const loaded = await readExisting(options);
     if (view === "full") return renderFull(loaded.text);
+    if (view === "entry") return renderEntries(loaded.text, ids);
+    if (view === "recover") return renderRecover(loaded.text, { root: loaded.root, recordPath: loaded.path });
     return renderResume(loaded.text);
   }
   if (command === "validate") {
     if (positionals.length) throw new CliError("Validate does not accept positional arguments");
     const loaded = await readExisting(options);
     validateDocument(parseDocument(loaded.text));
-    return `valid\n${displayPath(loaded.root, loaded.path)}\n`;
+    const pointers = checkEvidencePointers(loaded.text, { root: loaded.root, recordPath: loaded.path });
+    const outside = pointers.outside.length
+      ? `\n${pointers.outside.length} evidence pointer(s) outside the repository, not checked:\n${pointers.outside.map((each) => `- ${each}`).join("\n")}`
+      : "";
+    // Unresolved pointers warn: a record may name a planned path or a commit not fetched yet. --strict fails on those
+    // an Evidence or Result line claims exist.
+    const unresolved = options["--strict"] ? pointers.warnings : [...pointers.problems, ...pointers.warnings];
+    const warnings = unresolved.length
+      ? `\n${unresolved.length} pointer(s) in Material updates do not resolve here (a planned path, or a commit not fetched?):\n${unresolved.map((each) => `- ${each}`).join("\n")}`
+      : "";
+    if (options["--strict"] && pointers.problems.length)
+      throw new CliError(
+        `Evidence pointers on Evidence or Result lines do not resolve:\n${pointers.problems.map((each) => `- ${each}`).join("\n")}${warnings}${outside}`,
+      );
+    return `valid\n${displayPath(loaded.root, loaded.path)}\n${pointers.checked} evidence pointer(s) checked${warnings}${outside}\n`;
   }
   if (positionals.length !== 1) throw new CliError(`Expected one operation for ${command}`);
   const loaded = await readExisting(options);