@unbrained/pm-cli 2026.6.19 → 2026.6.21

package/docs/TESTING.md

@@ -52,6 +52,24 @@ quality:static`: every `src/**/*.ts` source file needs a module TSDoc block,
 every exported declaration needs a non-module TSDoc block, and known generated
 boilerplate summaries are rejected.
 
+### Directory-load cap and the `tests/unit` split
+
+`pnpm quality:static` also caps each directory under `src/`, `tests/`, and
+`packages/` at **120 `.ts` files** (`--max-files-per-dir`, default `120`). This
+keeps any single directory navigable and forces load to be partitioned by area
+rather than piling into one folder. `tests/unit/` is therefore split into
+per-area subdirectories (`tests/unit/commands/`, `tests/unit/core/`,
+`tests/unit/cli/`, `tests/unit/mcp/`, `tests/unit/extensions/`, …) instead of a
+single flat directory.
+
+When adding a unit test, place it in the matching `tests/unit/<area>/`
+subdirectory (or merge into an existing spec there); never add a file directly
+to `tests/unit/`. The
+[`static-quality-gate directory-load contract`](../tests/integration/ci-workflow-contract.spec.ts)
+test asserts the live repository stays at or below the cap and that the magic
+number matches the gate default, so drift is caught before CI's `static` gate
+fails.
+
 ## Search Quality Evaluation
 
 `search-advanced` exposes an advisory golden-query harness for relevance drift checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.6.19",
+  "version": "2026.6.21",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -125,7 +125,7 @@
     }
   },
   "dependencies": {
-    "@sentry/node": "^10.58.0",
+    "@sentry/node": "^10.59.0",
     "@toon-format/toon": "^2.3.0",
     "commander": "^14.0.3",
     "fast-glob": "^3.3.3",
@@ -150,7 +150,8 @@
       "brace-expansion": ">=5.0.6",
       "vite": "7.3.5",
       "esbuild": "0.28.1",
-      "@opentelemetry/core": ">=2.8.0"
+      "@opentelemetry/core": ">=2.8.0",
+      "undici": "6.27.0"
     }
   }
 }

package/packages/pm-command-kit/README.md

@@ -70,3 +70,7 @@ Key conventions for authors:
 - `activation.commands` in `manifest.json` lists both package-owned commands and
   existing commands that receive injected flags so the host can lazily activate the
   extension before option validation.
+- Unit tests can validate this package's three command-facing registrations with
+  public SDK helpers: `assertRegisteredCommandContract(...)` for the owned command,
+  `assertRegisteredParserOverride(...)` for parser rewrites, and
+  `assertRegisteredFlags(...)` for the injected `pm list --kit-note` flag.

package/packages/pm-todos/extensions/todos/index.js

@@ -39,6 +39,7 @@ export function activate(api) {
     api.registerImporter("todos", async (context) => runTodosImportFromRuntime(toImportOptions(context.options), context.global), {
         action: "todos-import",
         description: "Import Todo markdown files into pm items.",
+        failure_hints: ["This command reads a directory, not a file. Use --folder <path> to point at the Todo markdown directory."],
         flags: [
             {
                 long: "--folder",
@@ -63,6 +64,7 @@ export function activate(api) {
     api.registerExporter("todos", async (context) => runTodosExportFromRuntime(toExportOptions(context.options), context.global), {
         action: "todos-export",
         description: "Export pm items into Todo markdown files.",
+        failure_hints: ["This command writes a directory of markdown files. Use --folder <path> to choose the destination directory."],
         flags: [
             {
                 long: "--folder",

package/packages/pm-todos/extensions/todos/index.ts

@@ -65,6 +65,7 @@ export function activate(api: ExtensionApi): void {
     {
       action: "todos-import",
       description: "Import Todo markdown files into pm items.",
+      failure_hints: ["This command reads a directory, not a file. Use --folder <path> to point at the Todo markdown directory."],
       flags: [
         {
           long: "--folder",
@@ -93,6 +94,7 @@ export function activate(api: ExtensionApi): void {
     {
       action: "todos-export",
       description: "Export pm items into Todo markdown files.",
+      failure_hints: ["This command writes a directory of markdown files. Use --folder <path> to choose the destination directory."],
       flags: [
         {
           long: "--folder",

package/packages/pm-todos/extensions/todos/runtime.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { CONFIDENCE_TEXT_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, PmCliError, RISK_VALUES, canonicalDocument, commitImportedItem, generateItemId, getActiveExtensionRegistrations, getItemPath, listAllFrontMatter, locateItem, normalizeFrontMatter, normalizeItemId, nowIso, readLocatedItem, readSettings, resolveItemTypeRegistry, resolvePmRoot, runActiveOnReadHooks, runActiveOnWriteHooks, selectImportAuthor, splitFrontMatter, ensureTrackerInitialized, toEstimatedMinutesValue, toImportPriority, toImportStatus, toImportTags, toNonEmptyImportString, writeFileAtomic, } from "../../../../dist/sdk/index.js";
+import { CONFIDENCE_TEXT_VALUES, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, PmCliError, RISK_VALUES, canonicalDocument, commitImportedItem, generateItemId, getActiveExtensionRegistrations, getItemPath, listAllFrontMatter, locateItem, normalizeFrontMatter, normalizeItemId, nowIso, readLocatedItem, readSettings, resolveItemTypeRegistry, resolvePmRoot, runActiveOnReadHooks, runActiveOnWriteHooks, selectImportAuthor, splitFrontMatter, ensureTrackerInitialized, toEstimatedMinutesValue, toImportPriority, toImportStatus, toImportTags, toNonEmptyImportString, writeFileAtomic, } from "../../../../dist/sdk/index.js";
 const DEFAULT_TODOS_FOLDER = ".pm/todos";
 // Shared, behavior-identical value coercers are sourced from the SDK adapter
 // surface; package-specific mappings (lenient timestamps, type-name resolution,
@@ -95,6 +95,189 @@ function toBoolean(value) {
     return undefined;
 }
 const toTags = toImportTags;
+function toLinkScope(value) {
+    return toNonEmptyString(value)?.toLowerCase() === "global" ? "global" : "project";
+}
+function toStringList(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = value
+        .map((entry) => toNonEmptyString(entry))
+        .filter((entry) => entry !== undefined);
+    return entries.length > 0 ? entries : undefined;
+}
+function toStringMap(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const entries = Object.entries(value)
+        .map(([key, entryValue]) => [key.trim(), toNonEmptyString(entryValue)])
+        .filter((entry) => entry[0].length > 0 && entry[1] !== undefined);
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function toNumberMap(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const entries = Object.entries(value)
+        .map(([key, entryValue]) => [key.trim(), toInteger(entryValue)])
+        .filter((entry) => entry[0].length > 0 && entry[1] !== undefined);
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function toDependencyEntries(value, fallbackCreatedAt) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const dependencies = [];
+    for (const entry of value) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        const id = toNonEmptyString(entry.id);
+        if (!id) {
+            continue;
+        }
+        const normalizedKind = toNonEmptyString(entry.kind)?.toLowerCase();
+        const kind = normalizedKind && DEPENDENCY_KIND_VALUES.includes(normalizedKind) ? normalizedKind : "related";
+        dependencies.push({
+            id,
+            kind,
+            created_at: toIsoString(entry.created_at) ?? fallbackCreatedAt,
+            author: toNonEmptyString(entry.author),
+            source_kind: toNonEmptyString(entry.source_kind),
+        });
+    }
+    return dependencies.length > 0 ? dependencies : undefined;
+}
+function toLogEntries(value, fallbackCreatedAt, fallbackAuthor) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = value
+        .map((entry) => {
+        if (typeof entry === "string") {
+            const text = toNonEmptyString(entry);
+            return text
+                ? {
+                    created_at: fallbackCreatedAt,
+                    author: fallbackAuthor,
+                    text,
+                }
+                : undefined;
+        }
+        if (!isRecord(entry)) {
+            return undefined;
+        }
+        const text = toNonEmptyString(entry.text);
+        if (!text) {
+            return undefined;
+        }
+        return {
+            created_at: toIsoString(entry.created_at) ?? fallbackCreatedAt,
+            author: toNonEmptyString(entry.author) ?? fallbackAuthor,
+            text,
+        };
+    })
+        .filter((entry) => entry !== undefined);
+    return entries.length > 0 ? entries : undefined;
+}
+function toLinkedFiles(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = value
+        .map((entry) => {
+        if (typeof entry === "string") {
+            const filePath = toNonEmptyString(entry);
+            return filePath ? { path: filePath, scope: "project" } : undefined;
+        }
+        if (!isRecord(entry)) {
+            return undefined;
+        }
+        const filePath = toNonEmptyString(entry.path);
+        if (!filePath) {
+            return undefined;
+        }
+        return {
+            path: filePath,
+            scope: toLinkScope(entry.scope),
+            note: toNonEmptyString(entry.note),
+        };
+    })
+        .filter((entry) => entry !== undefined);
+    return entries.length > 0 ? entries : undefined;
+}
+function toLinkedDocs(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = value
+        .map((entry) => {
+        if (typeof entry === "string") {
+            const docPath = toNonEmptyString(entry);
+            return docPath ? { path: docPath, scope: "project" } : undefined;
+        }
+        if (!isRecord(entry)) {
+            return undefined;
+        }
+        const docPath = toNonEmptyString(entry.path);
+        if (!docPath) {
+            return undefined;
+        }
+        return {
+            path: docPath,
+            scope: toLinkScope(entry.scope),
+            note: toNonEmptyString(entry.note),
+        };
+    })
+        .filter((entry) => entry !== undefined);
+    return entries.length > 0 ? entries : undefined;
+}
+function toLinkedTests(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = [];
+    for (const entry of value) {
+        if (typeof entry === "string") {
+            const command = toNonEmptyString(entry);
+            if (command) {
+                entries.push({ command, scope: "project" });
+            }
+            continue;
+        }
+        if (!isRecord(entry)) {
+            continue;
+        }
+        const command = toNonEmptyString(entry.command);
+        const testPath = toNonEmptyString(entry.path);
+        if (!command && !testPath) {
+            continue;
+        }
+        const timeoutSeconds = toInteger(entry.timeout_seconds);
+        const pmContextMode = toNormalizedEnum(entry.pm_context_mode, ["schema", "tracker", "auto"]);
+        entries.push({
+            command,
+            path: testPath,
+            scope: toLinkScope(entry.scope),
+            timeout_seconds: timeoutSeconds !== undefined && timeoutSeconds > 0 ? timeoutSeconds : undefined,
+            pm_context_mode: pmContextMode,
+            env_set: toStringMap(entry.env_set),
+            env_clear: toStringList(entry.env_clear),
+            shared_host_safe: toBoolean(entry.shared_host_safe),
+            assert_stdout_contains: toStringList(entry.assert_stdout_contains),
+            assert_stdout_regex: toStringList(entry.assert_stdout_regex),
+            assert_stderr_contains: toStringList(entry.assert_stderr_contains),
+            assert_stderr_regex: toStringList(entry.assert_stderr_regex),
+            assert_stdout_min_lines: toInteger(entry.assert_stdout_min_lines),
+            assert_json_field_equals: toStringMap(entry.assert_json_field_equals),
+            assert_json_field_gte: toNumberMap(entry.assert_json_field_gte),
+            note: toNonEmptyString(entry.note),
+        });
+    }
+    return entries.length > 0 ? entries : undefined;
+}
 function toItemType(value, typeNames) {
     const normalized = toNonEmptyString(value)?.toLowerCase();
     const fallbackType = typeNames.find((entry) => entry.toLowerCase() === "task") ?? typeNames[0] ?? "Task";
@@ -224,13 +407,13 @@ async function importTodoCandidate(candidate, runtime) {
             regression: toBoolean(candidate.frontMatter.regression),
             customer_impact: toNonEmptyString(candidate.frontMatter.customer_impact),
             close_reason: toNonEmptyString(candidate.frontMatter.close_reason),
-            dependencies: Array.isArray(candidate.frontMatter.dependencies) ? candidate.frontMatter.dependencies : undefined,
-            comments: Array.isArray(candidate.frontMatter.comments) ? candidate.frontMatter.comments : undefined,
-            notes: Array.isArray(candidate.frontMatter.notes) ? candidate.frontMatter.notes : undefined,
-            learnings: Array.isArray(candidate.frontMatter.learnings) ? candidate.frontMatter.learnings : undefined,
-            files: Array.isArray(candidate.frontMatter.files) ? candidate.frontMatter.files : undefined,
-            docs: Array.isArray(candidate.frontMatter.docs) ? candidate.frontMatter.docs : undefined,
-            tests: Array.isArray(candidate.frontMatter.tests) ? candidate.frontMatter.tests : undefined,
+            dependencies: toDependencyEntries(candidate.frontMatter.dependencies, createdAt),
+            comments: toLogEntries(candidate.frontMatter.comments, createdAt, runtime.author),
+            notes: toLogEntries(candidate.frontMatter.notes, createdAt, runtime.author),
+            learnings: toLogEntries(candidate.frontMatter.learnings, createdAt, runtime.author),
+            files: toLinkedFiles(candidate.frontMatter.files),
+            docs: toLinkedDocs(candidate.frontMatter.docs),
+            tests: toLinkedTests(candidate.frontMatter.tests),
         }),
         body: candidate.body,
     });
@@ -261,7 +444,7 @@ export async function runTodosImport(options, global) {
         entries = await fs.readdir(sourceFolder, { withFileTypes: true });
     }
     catch {
-        throw new PmCliError(`Todos source folder not found at ${sourceFolder}`, EXIT_CODE.NOT_FOUND);
+        throw new PmCliError(`Todos source folder not found at ${sourceFolder}. Use --folder <path> to point at the directory of Todo markdown files.`, EXIT_CODE.NOT_FOUND);
     }
     const author = selectAuthor(toNonEmptyString(options.author), settings.author_default);
     const message = toNonEmptyString(options.message) ?? "Import from todos markdown";

package/packages/pm-todos/extensions/todos/runtime.ts

@@ -3,6 +3,7 @@ import type { Dirent } from "node:fs";
 import path from "node:path";
 import {
   CONFIDENCE_TEXT_VALUES,
+  DEPENDENCY_KIND_VALUES,
   EXIT_CODE,
   ISSUE_SEVERITY_VALUES,
   PmCliError,
@@ -36,6 +37,10 @@ import {
   type ItemMetadata,
   type ItemStatus,
   type ItemType,
+  type LinkedDoc,
+  type LinkedFile,
+  type LinkedTest,
+  type LogNote,
   type PmSettings,
 } from "../../../../src/sdk/index.js";
 
@@ -194,6 +199,201 @@ function toBoolean(value: unknown): boolean | undefined {
 
 const toTags = toImportTags;
 
+function toLinkScope(value: unknown): "project" | "global" {
+  return toNonEmptyString(value)?.toLowerCase() === "global" ? "global" : "project";
+}
+
+function toStringList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const entries = value
+    .map((entry) => toNonEmptyString(entry))
+    .filter((entry): entry is string => entry !== undefined);
+  return entries.length > 0 ? entries : undefined;
+}
+
+function toStringMap(value: unknown): Record<string, string> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const entries = Object.entries(value)
+    .map(([key, entryValue]) => [key.trim(), toNonEmptyString(entryValue)] as const)
+    .filter((entry): entry is readonly [string, string] => entry[0].length > 0 && entry[1] !== undefined);
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
+function toNumberMap(value: unknown): Record<string, number> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const entries = Object.entries(value)
+    .map(([key, entryValue]) => [key.trim(), toInteger(entryValue)] as const)
+    .filter((entry): entry is readonly [string, number] => entry[0].length > 0 && entry[1] !== undefined);
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
+function toDependencyEntries(value: unknown, fallbackCreatedAt: string): ItemMetadata["dependencies"] {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const dependencies: NonNullable<ItemMetadata["dependencies"]> = [];
+  for (const entry of value) {
+    if (!isRecord(entry)) {
+      continue;
+    }
+    const id = toNonEmptyString(entry.id);
+    if (!id) {
+      continue;
+    }
+    const normalizedKind = toNonEmptyString(entry.kind)?.toLowerCase();
+    const kind =
+      normalizedKind && DEPENDENCY_KIND_VALUES.includes(normalizedKind as (typeof DEPENDENCY_KIND_VALUES)[number])
+        ? (normalizedKind as (typeof DEPENDENCY_KIND_VALUES)[number])
+        : "related";
+    dependencies.push({
+      id,
+      kind,
+      created_at: toIsoString(entry.created_at) ?? fallbackCreatedAt,
+      author: toNonEmptyString(entry.author),
+      source_kind: toNonEmptyString(entry.source_kind),
+    });
+  }
+  return dependencies.length > 0 ? dependencies : undefined;
+}
+
+function toLogEntries(value: unknown, fallbackCreatedAt: string, fallbackAuthor: string): LogNote[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const entries = value
+    .map((entry) => {
+      if (typeof entry === "string") {
+        const text = toNonEmptyString(entry);
+        return text
+          ? {
+              created_at: fallbackCreatedAt,
+              author: fallbackAuthor,
+              text,
+            }
+          : undefined;
+      }
+      if (!isRecord(entry)) {
+        return undefined;
+      }
+      const text = toNonEmptyString(entry.text);
+      if (!text) {
+        return undefined;
+      }
+      return {
+        created_at: toIsoString(entry.created_at) ?? fallbackCreatedAt,
+        author: toNonEmptyString(entry.author) ?? fallbackAuthor,
+        text,
+      };
+    })
+    .filter((entry): entry is LogNote => entry !== undefined);
+  return entries.length > 0 ? entries : undefined;
+}
+
+function toLinkedFiles(value: unknown): LinkedFile[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const entries = value
+    .map((entry) => {
+      if (typeof entry === "string") {
+        const filePath = toNonEmptyString(entry);
+        return filePath ? { path: filePath, scope: "project" } : undefined;
+      }
+      if (!isRecord(entry)) {
+        return undefined;
+      }
+      const filePath = toNonEmptyString(entry.path);
+      if (!filePath) {
+        return undefined;
+      }
+      return {
+        path: filePath,
+        scope: toLinkScope(entry.scope),
+        note: toNonEmptyString(entry.note),
+      };
+    })
+    .filter((entry): entry is LinkedFile => entry !== undefined);
+  return entries.length > 0 ? entries : undefined;
+}
+
+function toLinkedDocs(value: unknown): LinkedDoc[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const entries = value
+    .map((entry) => {
+      if (typeof entry === "string") {
+        const docPath = toNonEmptyString(entry);
+        return docPath ? { path: docPath, scope: "project" } : undefined;
+      }
+      if (!isRecord(entry)) {
+        return undefined;
+      }
+      const docPath = toNonEmptyString(entry.path);
+      if (!docPath) {
+        return undefined;
+      }
+      return {
+        path: docPath,
+        scope: toLinkScope(entry.scope),
+        note: toNonEmptyString(entry.note),
+      };
+    })
+    .filter((entry): entry is LinkedDoc => entry !== undefined);
+  return entries.length > 0 ? entries : undefined;
+}
+
+function toLinkedTests(value: unknown): LinkedTest[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const entries: LinkedTest[] = [];
+  for (const entry of value) {
+    if (typeof entry === "string") {
+      const command = toNonEmptyString(entry);
+      if (command) {
+        entries.push({ command, scope: "project" });
+      }
+      continue;
+    }
+    if (!isRecord(entry)) {
+      continue;
+    }
+    const command = toNonEmptyString(entry.command);
+    const testPath = toNonEmptyString(entry.path);
+    if (!command && !testPath) {
+      continue;
+    }
+    const timeoutSeconds = toInteger(entry.timeout_seconds);
+    const pmContextMode = toNormalizedEnum(entry.pm_context_mode, ["schema", "tracker", "auto"] as const);
+    entries.push({
+      command,
+      path: testPath,
+      scope: toLinkScope(entry.scope),
+      timeout_seconds: timeoutSeconds !== undefined && timeoutSeconds > 0 ? timeoutSeconds : undefined,
+      pm_context_mode: pmContextMode,
+      env_set: toStringMap(entry.env_set),
+      env_clear: toStringList(entry.env_clear),
+      shared_host_safe: toBoolean(entry.shared_host_safe),
+      assert_stdout_contains: toStringList(entry.assert_stdout_contains),
+      assert_stdout_regex: toStringList(entry.assert_stdout_regex),
+      assert_stderr_contains: toStringList(entry.assert_stderr_contains),
+      assert_stderr_regex: toStringList(entry.assert_stderr_regex),
+      assert_stdout_min_lines: toInteger(entry.assert_stdout_min_lines),
+      assert_json_field_equals: toStringMap(entry.assert_json_field_equals),
+      assert_json_field_gte: toNumberMap(entry.assert_json_field_gte),
+      note: toNonEmptyString(entry.note),
+    });
+  }
+  return entries.length > 0 ? entries : undefined;
+}
+
 function toItemType(value: unknown, typeNames: string[]): ItemType {
   const normalized = toNonEmptyString(value)?.toLowerCase();
   const fallbackType = typeNames.find((entry) => entry.toLowerCase() === "task") ?? typeNames[0] ?? "Task";
@@ -342,13 +542,13 @@ async function importTodoCandidate(candidate: ParsedTodoCandidate, runtime: Todo
       regression: toBoolean(candidate.frontMatter.regression),
       customer_impact: toNonEmptyString(candidate.frontMatter.customer_impact),
       close_reason: toNonEmptyString(candidate.frontMatter.close_reason),
-      dependencies: Array.isArray(candidate.frontMatter.dependencies) ? (candidate.frontMatter.dependencies as any[]) : undefined,
-      comments: Array.isArray(candidate.frontMatter.comments) ? (candidate.frontMatter.comments as any[]) : undefined,
-      notes: Array.isArray(candidate.frontMatter.notes) ? (candidate.frontMatter.notes as any[]) : undefined,
-      learnings: Array.isArray(candidate.frontMatter.learnings) ? (candidate.frontMatter.learnings as any[]) : undefined,
-      files: Array.isArray(candidate.frontMatter.files) ? (candidate.frontMatter.files as any[]) : undefined,
-      docs: Array.isArray(candidate.frontMatter.docs) ? (candidate.frontMatter.docs as any[]) : undefined,
-      tests: Array.isArray(candidate.frontMatter.tests) ? (candidate.frontMatter.tests as any[]) : undefined,
+      dependencies: toDependencyEntries(candidate.frontMatter.dependencies, createdAt),
+      comments: toLogEntries(candidate.frontMatter.comments, createdAt, runtime.author),
+      notes: toLogEntries(candidate.frontMatter.notes, createdAt, runtime.author),
+      learnings: toLogEntries(candidate.frontMatter.learnings, createdAt, runtime.author),
+      files: toLinkedFiles(candidate.frontMatter.files),
+      docs: toLinkedDocs(candidate.frontMatter.docs),
+      tests: toLinkedTests(candidate.frontMatter.tests),
     } as ItemMetadata),
     body: candidate.body,
   });
@@ -383,7 +583,10 @@ export async function runTodosImport(options: TodosImportOptions, global: Global
   try {
     entries = await fs.readdir(sourceFolder, { withFileTypes: true });
   } catch {
-    throw new PmCliError(`Todos source folder not found at ${sourceFolder}`, EXIT_CODE.NOT_FOUND);
+    throw new PmCliError(
+      `Todos source folder not found at ${sourceFolder}. Use --folder <path> to point at the directory of Todo markdown files.`,
+      EXIT_CODE.NOT_FOUND,
+    );
   }
 
   const author = selectAuthor(toNonEmptyString(options.author), settings.author_default);

package/dist/cli-bundle/chunks/activity-62I26XZB.js

@@ -1,18 +0,0 @@
-import {
-  _testOnly,
-  runActivity
-} from "./chunk-OURX4WVG.js";
-import "./chunk-QTWWHFI3.js";
-import "./chunk-2RI3BDFK.js";
-import "./chunk-DYZKSIVX.js";
-import "./chunk-X7RKOJXL.js";
-import "./chunk-5NS6TJ2F.js";
-import "./chunk-QSH34DSQ.js";
-import "./chunk-SO2IOH37.js";
-import "./chunk-MTGMNUMJ.js";
-import "./chunk-5QLHQK7V.js";
-export {
-  _testOnly,
-  runActivity
-};
-//# sourceMappingURL=activity-62I26XZB.js.map

package/dist/cli-bundle/chunks/chunk-2RI3BDFK.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../../../../../../core/history/replay.ts"],
-  "sourcesContent": ["/**\n * @module core/history/replay\n *\n * Implements append-only history and replay behavior for Replay.\n */\nimport jsonPatch from \"fast-json-patch\";\nimport { FRONT_MATTER_KEY_ORDER } from \"../shared/constants.js\";\nimport { canonicalDocument } from \"../item/item-format.js\";\nimport { toItemRecord } from \"../item/item-record.js\";\nimport { orderObject, sha256Hex, stableStringify } from \"../shared/serialization.js\";\nimport { hashDocument } from \"./history.js\";\nimport type { HistoryEntry, HistoryPatchOp, ItemDocument, ItemMetadata } from \"../../types/index.js\";\n\n/**\n * Shared history replay/patch mechanics single-sourced for the history, restore,\n * history-redact, and history-repair commands plus the health/validate drift checks.\n *\n * Each command keeps its own thin error-formatting wrapper so the exact CLI error\n * contracts (restore's rich patch-failure context, redact's op tag, history's\n * generic message) are preserved; only the underlying replay/patch logic is shared.\n */\n\nexport interface ReplayDocument {\n  metadata: Record<string, unknown>;\n  body: string;\n}\n\nexport const EMPTY_REPLAY_DOCUMENT: ReplayDocument = {\n  metadata: {},\n  body: \"\",\n};\n\n/**\n * Implements clone empty replay document for the public runtime surface of this module.\n */\nexport function cloneEmptyReplayDocument(): ReplayDocument {\n  return structuredClone(EMPTY_REPLAY_DOCUMENT);\n}\n\n/**\n * Implements replay hash for the public runtime surface of this module.\n */\nexport function replayHash(document: ReplayDocument): string {\n  try {\n    return hashDocument({\n      metadata: document.metadata as unknown as ItemMetadata,\n      body: document.body,\n    });\n  } catch {\n    // Legacy/malformed replay states (for example a stream whose first entry never\n    // established a full `create` document, so the canonicalizer cannot normalize it)\n    // cannot be canonically hashed. Fall back to a deterministic structural hash so\n    // re-anchor and verification stay internally consistent for these streams. Fully\n    // formed documents always take the canonical path above, so valid streams are\n    // unaffected.\n    return sha256Hex(stableStringify({ replay_fallback: true, metadata: document.metadata, body: document.body }));\n  }\n}\n\n/**\n * Implements replay to item document for the public runtime surface of this module.\n */\nexport function replayToItemDocument(document: ReplayDocument): ItemDocument {\n  return {\n    metadata: document.metadata as unknown as ItemMetadata,\n    body: document.body,\n  };\n}\n\n/**\n * Canonicalize an item document into the ordered replay form used when comparing\n * a replayed chain against the on-disk item (restore + history-repair reconciliation).\n */\nexport function toReplayDocument(document: ItemDocument): ReplayDocument {\n  if (!document.metadata || Object.keys(document.metadata).length === 0) {\n    return {\n      metadata: {},\n      body: document.body ?? \"\",\n    };\n  }\n  const canonical = canonicalDocument(document);\n  return {\n    metadata: orderObject(toItemRecord(canonical.metadata), FRONT_MATTER_KEY_ORDER),\n    body: canonical.body,\n  };\n}\n\n/**\n * Implements normalize replay patch path for the public runtime surface of this module.\n */\nexport function normalizeReplayPatchPath(path: string): string {\n  if (path === \"/front_matter\") {\n    return \"/metadata\";\n  }\n  if (path.startsWith(\"/front_matter/\")) {\n    return `/metadata/${path.slice(\"/front_matter/\".length)}`;\n  }\n  return path;\n}\n\nfunction isHistoryPatchOp(value: unknown): value is HistoryPatchOp {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as { op?: unknown }).op === \"string\" &&\n    typeof (value as { path?: unknown }).path === \"string\"\n  );\n}\n\n/**\n * Implements normalize replay patch ops for the public runtime surface of this module.\n */\nexport function normalizeReplayPatchOps(patch: HistoryPatchOp[] | unknown): HistoryPatchOp[] {\n  if (!Array.isArray(patch)) {\n    return [];\n  }\n  return patch.filter(isHistoryPatchOp).map((operation) => ({\n    ...operation,\n    path: normalizeReplayPatchPath(operation.path),\n    from: typeof operation.from === \"string\" ? normalizeReplayPatchPath(operation.from) : undefined,\n  }));\n}\n\nfunction isReplayDocumentShape(value: unknown): value is { metadata: Record<string, unknown>; body: string } {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"metadata\" in value &&\n    \"body\" in value &&\n    typeof (value as { body: unknown }).body === \"string\" &&\n    typeof (value as { metadata: unknown }).metadata === \"object\" &&\n    (value as { metadata: unknown }).metadata !== null\n  );\n}\n\n/**\n * Restricts replay apply result values accepted by command, SDK, and storage contracts.\n */\nexport type ReplayApplyResult =\n  | { ok: true; document: ReplayDocument }\n  | { ok: false; error: unknown };\n\n/**\n * Strictly apply a history patch (front_matter->metadata normalized) to a replay\n * document. Returns a result envelope rather than throwing so each caller can\n * format its own error contract.\n */\nexport function tryApplyReplayPatch(current: ReplayDocument, patch: HistoryPatchOp[]): ReplayApplyResult {\n  try {\n    const normalizedPatch = normalizeReplayPatchOps(patch);\n    const applied = jsonPatch.applyPatch(\n      structuredClone(current),\n      normalizedPatch as jsonPatch.Operation[],\n      true,\n      false,\n    ).newDocument as unknown;\n    if (!isReplayDocumentShape(applied)) {\n      return { ok: false, error: new Error(\"history_replay_invalid_document_shape\") };\n    }\n    return { ok: true, document: { metadata: applied.metadata, body: applied.body } };\n  } catch (error) {\n    return { ok: false, error };\n  }\n}\n\n/**\n * Deterministically verify a history chain: each entry's before_hash must equal\n * the prior replayed after_hash, the patch must strictly apply, and the recorded\n * after_hash must equal the replayed result.\n */\nexport function verifyHistoryChain(entries: HistoryEntry[]): { ok: boolean; errors: string[] } {\n  let replay = cloneEmptyReplayDocument();\n  for (let index = 0; index < entries.length; index += 1) {\n    const entry = entries[index];\n    if (replayHash(replay) !== entry.before_hash) {\n      return {\n        ok: false,\n        errors: [`verify_failed:before_hash_mismatch:entry_${index + 1}`],\n      };\n    }\n    const applied = tryApplyReplayPatch(replay, entry.patch);\n    if (!applied.ok) {\n      return {\n        ok: false,\n        errors: [`verify_failed:patch_apply_failed:entry_${index + 1}`],\n      };\n    }\n    replay = applied.document;\n    if (replayHash(replay) !== entry.after_hash) {\n      return {\n        ok: false,\n        errors: [`verify_failed:after_hash_mismatch:entry_${index + 1}`],\n      };\n    }\n  }\n  return { ok: true, errors: [] };\n}\n\n/**\n * Documents the lenient apply result payload exchanged by command, SDK, and package integrations.\n */\nexport interface LenientApplyResult {\n  document: ReplayDocument;\n  convertedReplaceToAdd: number;\n  skippedOps: number;\n}\n\nfunction tryApplySingleOp(document: unknown, op: HistoryPatchOp): { ok: true; document: unknown } | { ok: false } {\n  try {\n    const applied = jsonPatch.applyPatch(\n      structuredClone(document),\n      [op as jsonPatch.Operation],\n      true,\n      false,\n    ).newDocument as unknown;\n    return { ok: true, document: applied };\n  } catch {\n    return { ok: false };\n  }\n}\n\n/**\n * Apply a legacy patch op-by-op, recovering from drift that strict replay rejects:\n * a `replace` whose path no longer exists is retried as `add`, and any op that\n * still cannot apply against the current replay state is skipped. The resulting\n * document is what the repaired entry's recomputed patch should target.\n */\nexport function lenientApplyReplayPatch(current: ReplayDocument, patch: HistoryPatchOp[]): LenientApplyResult {\n  let working: unknown = structuredClone(current);\n  let convertedReplaceToAdd = 0;\n  let skippedOps = 0;\n\n  for (const op of normalizeReplayPatchOps(patch)) {\n    const direct = tryApplySingleOp(working, op);\n    if (direct.ok) {\n      working = direct.document;\n      continue;\n    }\n    if (op.op === \"replace\") {\n      const asAdd = tryApplySingleOp(working, { ...op, op: \"add\" });\n      if (asAdd.ok) {\n        working = asAdd.document;\n        convertedReplaceToAdd += 1;\n        continue;\n      }\n    }\n    skippedOps += 1;\n  }\n\n  const candidate = working as { metadata?: unknown; body?: unknown };\n  const document: ReplayDocument = {\n    metadata:\n      typeof candidate.metadata === \"object\" && candidate.metadata !== null\n        ? (candidate.metadata as Record<string, unknown>)\n        : {},\n    body: typeof candidate.body === \"string\" ? candidate.body : current.body,\n  };\n  return { document, convertedReplaceToAdd, skippedOps };\n}\n\n/**\n * Documents the reanchor entry detail payload exchanged by command, SDK, and package integrations.\n */\nexport interface ReanchorEntryDetail {\n  index: number;\n  rehashed: boolean;\n  patch_repaired: boolean;\n  converted_replace_to_add: number;\n  skipped_ops: number;\n}\n\n/**\n * Documents the reanchor result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ReanchorResult {\n  entries: HistoryEntry[];\n  finalDocument: ReplayDocument;\n  entriesRehashed: number;\n  entriesPatchRepaired: number;\n  convertedReplaceToAdd: number;\n  skippedOps: number;\n  details: ReanchorEntryDetail[];\n}\n\n/**\n * Re-anchor a drifted history chain: replay every entry from empty, recompute the\n * before/after hashes, and only rewrite a patch when the original op set no longer\n * strictly applies (legacy drift). Clean entries keep their patch verbatim so the\n * on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain.\n */\nexport function reanchorHistoryEntries(entries: HistoryEntry[]): ReanchorResult {\n  let replay = cloneEmptyReplayDocument();\n  const rewritten: HistoryEntry[] = [];\n  const details: ReanchorEntryDetail[] = [];\n  let entriesRehashed = 0;\n  let entriesPatchRepaired = 0;\n  let convertedReplaceToAdd = 0;\n  let skippedOps = 0;\n\n  for (let index = 0; index < entries.length; index += 1) {\n    const entry = entries[index];\n    const beforeHash = replayHash(replay);\n    const strict = tryApplyReplayPatch(replay, entry.patch);\n\n    let next: ReplayDocument;\n    let outPatch: HistoryPatchOp[];\n    let patchRepaired = false;\n    let entryConverted = 0;\n    let entrySkipped = 0;\n\n    if (strict.ok) {\n      next = strict.document;\n      outPatch = entry.patch;\n    } else {\n      const lenient = lenientApplyReplayPatch(replay, entry.patch);\n      next = lenient.document;\n      outPatch = jsonPatch.compare(replay, next) as HistoryPatchOp[];\n      patchRepaired = true;\n      entryConverted = lenient.convertedReplaceToAdd;\n      entrySkipped = lenient.skippedOps;\n      convertedReplaceToAdd += entryConverted;\n      skippedOps += entrySkipped;\n      entriesPatchRepaired += 1;\n    }\n\n    const afterHash = replayHash(next);\n    const rehashed = beforeHash !== entry.before_hash || afterHash !== entry.after_hash;\n    if (rehashed) {\n      entriesRehashed += 1;\n    }\n\n    rewritten.push({\n      ...entry,\n      patch: outPatch,\n      before_hash: beforeHash,\n      after_hash: afterHash,\n    });\n    details.push({\n      index: index + 1,\n      rehashed,\n      patch_repaired: patchRepaired,\n      converted_replace_to_add: entryConverted,\n      skipped_ops: entrySkipped,\n    });\n    replay = next;\n  }\n\n  return {\n    entries: rewritten,\n    finalDocument: replay,\n    entriesRehashed,\n    entriesPatchRepaired,\n    convertedReplaceToAdd,\n    skippedOps,\n    details,\n  };\n}\n\n/**\n * Implements history entries to raw for the public runtime surface of this module.\n */\nexport function historyEntriesToRaw(entries: HistoryEntry[]): string {\n  if (entries.length === 0) {\n    return \"\";\n  }\n  return `${entries.map((entry) => JSON.stringify(entry)).join(\"\\n\")}\\n`;\n}\n"],
-  "mappings": "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",
-  "names": []
-}