@unbrained/pm-cli 2026.5.24 → 2026.5.28

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

@@ -7,35 +7,32 @@ import {
   ISSUE_SEVERITY_VALUES,
   PmCliError,
   RISK_VALUES,
-  acquireLock,
-  appendHistoryEntry,
   canonicalDocument,
-  createHistoryEntry,
+  commitImportedItem,
   generateItemId,
   getActiveExtensionRegistrations,
-  getHistoryPath,
   getItemPath,
-  getSettingsPath,
   listAllFrontMatter,
   locateItem,
   normalizeFrontMatter,
   normalizeItemId,
-  normalizeStatusInput,
   nowIso,
-  parseTags,
-  pathExists,
   readLocatedItem,
   readSettings,
-  removeFileIfExists,
   resolveItemTypeRegistry,
   resolvePmRoot,
   runActiveOnReadHooks,
   runActiveOnWriteHooks,
-  serializeItemDocument,
+  selectImportAuthor,
   splitFrontMatter,
+  ensureTrackerInitialized,
+  toEstimatedMinutesValue,
+  toImportPriority,
+  toImportStatus,
+  toImportTags,
+  toNonEmptyImportString,
   writeFileAtomic,
   type GlobalOptions,
-  type ItemDocument,
   type ItemMetadata,
   type ItemStatus,
   type ItemType,
@@ -92,18 +89,16 @@ interface TodosImportRuntime {
 
 type ImportCandidateResult = { id: string; writeWarnings: string[] } | { warning: string };
 
+// Shared, behavior-identical value coercers are sourced from the SDK adapter
+// surface; package-specific mappings (lenient timestamps, type-name resolution,
+// confidence/enum coercion) stay local below.
+const toNonEmptyString = toNonEmptyImportString;
+const toEstimatedMinutes = toEstimatedMinutesValue;
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function toNonEmptyString(value: unknown): string | undefined {
-  if (typeof value !== "string") {
-    return undefined;
-  }
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-}
-
 function toIsoString(value: unknown): string | undefined {
   const raw = toNonEmptyString(value);
   if (!raw) {
@@ -116,19 +111,6 @@ function toIsoString(value: unknown): string | undefined {
   return new Date(timestamp).toISOString();
 }
 
-function toEstimatedMinutes(value: unknown): number | undefined {
-  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
-    return value;
-  }
-  if (typeof value === "string" && value.trim().length > 0) {
-    const parsed = Number(value);
-    if (Number.isFinite(parsed) && parsed >= 0) {
-      return parsed;
-    }
-  }
-  return undefined;
-}
-
 function toInteger(value: unknown): number | undefined {
   if (typeof value === "number" && Number.isInteger(value)) {
     return value;
@@ -142,18 +124,7 @@ function toInteger(value: unknown): number | undefined {
   return undefined;
 }
 
-function toPriority(value: unknown): PriorityValue {
-  if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 4) {
-    return value as PriorityValue;
-  }
-  if (typeof value === "string" && value.trim().length > 0) {
-    const parsed = Number(value);
-    if (Number.isInteger(parsed) && parsed >= 0 && parsed <= 4) {
-      return parsed as PriorityValue;
-    }
-  }
-  return 2;
-}
+const toPriority: (value: unknown) => PriorityValue = toImportPriority;
 
 function toConfidence(value: unknown): ItemMetadata["confidence"] | undefined {
   if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 100) {
@@ -221,19 +192,7 @@ function toBoolean(value: unknown): boolean | undefined {
   return undefined;
 }
 
-function toTags(value: unknown): string[] {
-  if (Array.isArray(value)) {
-    const tags = value
-      .filter((entry): entry is string => typeof entry === "string")
-      .map((entry) => entry.trim().toLowerCase())
-      .filter((entry) => entry.length > 0);
-    return Array.from(new Set(tags)).sort((left, right) => left.localeCompare(right));
-  }
-  if (typeof value === "string") {
-    return parseTags(value);
-  }
-  return [];
-}
+const toTags = toImportTags;
 
 function toItemType(value: unknown, typeNames: string[]): ItemType {
   const normalized = toNonEmptyString(value)?.toLowerCase();
@@ -249,42 +208,14 @@ function toItemType(value: unknown, typeNames: string[]): ItemType {
   return fallbackType;
 }
 
-function toStatus(value: unknown): ItemStatus {
-  const normalized = toNonEmptyString(value);
-  if (normalized) {
-    const canonical = normalizeStatusInput(normalized);
-    if (canonical) {
-      return canonical;
-    }
-  }
-  return "open";
-}
-
-function selectAuthor(explicitAuthor: string | undefined, settingsAuthor: string): string {
-  const candidate = explicitAuthor ?? process.env.PM_AUTHOR ?? settingsAuthor;
-  const trimmed = candidate.trim();
-  return trimmed.length > 0 ? trimmed : "unknown";
-}
-
-function ensureInitHasRun(pmRoot: string): Promise<void> {
-  return pathExists(getSettingsPath(pmRoot)).then((exists) => {
-    if (!exists) {
-      throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
-  });
-}
+const toStatus: (value: unknown) => ItemStatus = toImportStatus;
+const selectAuthor = selectImportAuthor;
+const ensureInitHasRun = ensureTrackerInitialized;
 
 function normalizeBody(body: string): string {
   return body.replace(/^\n+/, "").replace(/\s+$/, "");
 }
 
-function emptyDocument(): ItemDocument {
-  return {
-    metadata: {} as ItemMetadata,
-    body: "",
-  };
-}
-
 function resolveFolderPath(rawPath: string): string {
   return path.isAbsolute(rawPath) ? rawPath : path.resolve(process.cwd(), rawPath);
 }
@@ -417,49 +348,21 @@ async function importTodoCandidate(candidate: ParsedTodoCandidate, runtime: Todo
     body: candidate.body,
   });
 
-  const historyPath = getHistoryPath(runtime.pmRoot, id);
-  let writeWarnings: string[] = [];
-  try {
-    const releaseLock = await acquireLock(runtime.pmRoot, id, runtime.settings.locks.ttl_seconds, runtime.author);
-    try {
-      await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: "toon" }));
-      try {
-        const historyEntry = createHistoryEntry({
-          nowIso: nowIso(),
-          author: runtime.author,
-          op: "import",
-          before: emptyDocument(),
-          after: afterDocument,
-          message: runtime.message,
-        });
-        await appendHistoryEntry(historyPath, historyEntry);
-        writeWarnings = [
-          ...(await runActiveOnWriteHooks({
-            path: itemPath,
-            scope: "project",
-            op: "import",
-          })),
-          ...(await runActiveOnWriteHooks({
-            path: historyPath,
-            scope: "project",
-            op: "import:history",
-          })),
-        ];
-      } catch (error: unknown) {
-        await removeFileIfExists(itemPath);
-        throw error;
-      }
-    } finally {
-      await releaseLock();
-    }
-  } catch (error: unknown) {
-    if (error instanceof PmCliError && error.exitCode === EXIT_CODE.CONFLICT) {
-      return { warning: `todos_import_lock_conflict:${id}` };
-    }
-    throw error;
+  const commit = await commitImportedItem({
+    pmRoot: runtime.pmRoot,
+    id,
+    itemPath,
+    document: afterDocument,
+    author: runtime.author,
+    message: runtime.message,
+    settings: runtime.settings,
+    conflictWarningPrefix: "todos_import_lock_conflict",
+  });
+  if (!commit.committed) {
+    return { warning: commit.conflictWarning };
   }
 
-  return { id, writeWarnings };
+  return { id, writeWarnings: commit.writeWarnings };
 }
 
 export async function runTodosImport(options: TodosImportOptions, global: GlobalOptions): Promise<TodosImportResult> {

package/plugins/pm-claude/README.md

@@ -9,7 +9,7 @@ Native pm CLI integration for Claude Code. Use pm project management tools direc
 | **18 MCP tools** | Full pm surface: context, search, list, get, create, update, claim, release, close, comments, files, docs, test, validate, health, contracts, plan + `pm_run` for everything else |
 | **5 skills** | `pm-workflow`, `pm-developer`, `pm-release`, `pm-audit`, `pm-planner` — auto-loaded as Claude Code skills |
 | **14 slash commands** | Full lifecycle coverage — status, start, close, triage, audit, search, new, list, calendar, developer, planner, release, workflow, init |
-| **3 subagents** | `pm-coordinator` (batch/multi-item), `pm-triage-agent` (duplicate-safe item creation), `pm-verification-agent` (evidence + close readiness), and a `pm-delivery-chain` orchestrator |
+| **4 subagents** | `pm-coordinator` (batch/multi-item), `pm-triage-agent` (duplicate-safe item creation), `pm-verification-agent` (evidence + close readiness), and `pm-delivery-chain` (orchestrated delivery) |
 | **Hybrid TUI tracking** | pm items sync to Claude Code's task panel — pm is the persistent store, the task panel is the live session view |
 | **Session hook** | Injects active pm item summary at session start when pm is initialized (uses native modules, no CLI required) |
 
@@ -29,7 +29,7 @@ claude plugin marketplace add /path/to/pm-cli
 # claude plugin marketplace add unbraind/pm-cli
 ```
 
-This installs all 18 MCP tools, 5 skills, 14 slash commands, 3 subagents, hybrid TUI tracking, and the session hook in one step.
+This installs all 18 MCP tools, 5 skills, 14 slash commands, 4 subagents, hybrid TUI tracking, and the session hook in one step.
 
 ### Option B: Legacy marketplace alias (also works)
 

package/plugins/pm-claude/commands/pm-planner.md

@@ -52,18 +52,4 @@ Run the pm planning loop using native MCP tools. Argument: `$ARGUMENTS` (optiona
 
 ## Living plan mode (`pm_plan`)
 
-If the user wants a Codex-style ExecPlan / Claude Plan Mode / Cursor plan-and-edit flow rather than a flat backlog, use the built-in `Plan` item type via the `pm_plan` MCP tool. It records ordered steps, evidence, decisions, discoveries, validation, and supports materializing steps into real Tasks/Features.
-
-```json
-{ "tool": "pm_plan", "args": { "options": { "subcommand": "create", "title": "Plan title", "scope": "What this plan changes", "harness": "claude-code", "parent": "pm-epic1", "claim": true } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "add-step", "stepTitle": "Read affected files", "dependsOn": "pm-task1" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "stepRef": "plan-step-001", "options": { "subcommand": "complete-step", "stepEvidence": "files reviewed" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "approve" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "materialize", "steps": "plan-step-002,plan-step-003", "materializeType": "Task" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "show", "depth": "deep" } } }
-```
-
-Resume a plan after compaction:
-```json
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "resume", "resumeContext": "step 2 in progress; tests still failing on retry path" } } }
-```
+If the user wants a Codex-style ExecPlan / Claude Plan Mode / Cursor plan-and-edit flow rather than a flat backlog, use the built-in `Plan` item type via the `pm_plan` MCP tool. The canonical lifecycle recipe lives in [Command Reference: Plan Workflow](../../../docs/COMMANDS.md#plan-workflow); this slash command should add only Claude-specific context such as `harness: "claude-code"` and concise `resumeContext` after compaction.

package/plugins/pm-claude/scripts/pm-mcp-server.mjs

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 /**
- * pm-cli native MCP server launcher for Claude Code.
+ * pm-cli native MCP server launcher (Claude Code / Codex plugin).
+ *
+ * GENERATED by scripts/gen-plugin-mcp-wrappers.mjs — do not edit directly.
+ * Edit the template in that generator and re-run it to update both plugins.
  *
  * Resolution order:
  * 1. PM_CLI_MCP_SERVER env var (explicit path)
  * 2. dist/mcp/server.js walking up from this file (repo checkout)
- * 3. npx -y @unbrained/pm-cli@latest pm-mcp (installed via npm)
+ * 3. npx -y --package=@unbrained/pm-cli@latest pm-mcp (installed via npm)
  */
 import { spawn } from "node:child_process";
 import { access } from "node:fs/promises";

package/plugins/pm-claude/skills/pm-planner/SKILL.md

@@ -113,34 +113,16 @@ Set via `pm_create` with `acceptanceCriteria` field or `pm_update` with `options
 
 ## Built-in Plan workflow (`pm_plan` / `pm plan`)
 
-For durable Codex-style ExecPlans, Claude-style Plan Mode, and Cursor-style editable checklists, pm exposes a first-class `Plan` item type plus a `pm plan` command family. Plans are stored as normal pm items under `.agents/pm/plans/`, get the full history hash chain, dependencies, search corpus, and lifecycle tooling.
+For durable Codex-style ExecPlans, Claude-style Plan Mode, and Cursor-style editable checklists, pm exposes a first-class `Plan` item type plus a `pm plan` command family. Use [Command Reference: Plan Workflow](../../../../docs/COMMANDS.md#plan-workflow) as the canonical lifecycle recipe; this skill keeps only Claude-specific routing notes.
 
 ### When to use `pm plan` vs. `pm_create` + tasks
 
 - `pm plan` — when you need a **living, resumable plan** with ordered steps, evidence, decisions, discoveries, validation, and the option to later materialize selected steps as real Tasks. Best for plan-then-execute workflows.
 - `pm_create` (Epic/Feature/Task) — when the work is already decomposed and you just need persistent backlog items.
 
-### Lifecycle (call via `pm_plan` MCP tool)
+### Claude MCP routing
 
-```json
-{ "tool": "pm_plan", "args": { "options": { "subcommand": "create", "title": "Refactor lock retry", "scope": "Improve retry semantics", "harness": "claude-code", "parent": "pm-epic1", "related": "pm-rel1,pm-rel2", "claim": true } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "add-step", "stepTitle": "Read lock.ts", "stepBody": "Understand retry path", "dependsOn": "pm-task1" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "stepRef": "plan-step-001", "options": { "subcommand": "update-step", "stepStatus": "in_progress", "stepEvidence": "started reading lock.ts" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "stepRef": "plan-step-001", "options": { "subcommand": "complete-step", "stepEvidence": "lock.ts read; retry path captured" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "decision", "decisionText": "Use exponential backoff", "decisionRationale": "Avoid thundering herd" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "discovery", "discoveryText": "Found existing util in src/util/retry.ts" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "validation", "validationText": "Coverage gate stays at 100%", "validationCommand": "node scripts/run-tests.mjs coverage" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "approve" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "materialize", "steps": "plan-step-002", "materializeType": "Task", "materializeParent": "pm-epic1" } } }
-```
-
-### Progressive-disclosure reads
-
-```json
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "show", "depth": "brief" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "show", "depth": "standard" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "show", "depth": "deep" } } }
-```
+Call the same lifecycle through the `pm_plan` MCP tool. Use `harness: "claude-code"` on creation, `subcommand: "show"` with `depth: "brief"` for low-token reads, and `subcommand: "resume"` after compaction or handoff.
 
 ### Harness mapping cheatsheet
 

package/plugins/pm-codex/scripts/pm-mcp-server.mjs

@@ -1,4 +1,15 @@
 #!/usr/bin/env node
+/**
+ * pm-cli native MCP server launcher (Claude Code / Codex plugin).
+ *
+ * GENERATED by scripts/gen-plugin-mcp-wrappers.mjs — do not edit directly.
+ * Edit the template in that generator and re-run it to update both plugins.
+ *
+ * Resolution order:
+ * 1. PM_CLI_MCP_SERVER env var (explicit path)
+ * 2. dist/mcp/server.js walking up from this file (repo checkout)
+ * 3. npx -y --package=@unbrained/pm-cli@latest pm-mcp (installed via npm)
+ */
 import { spawn } from "node:child_process";
 import { access } from "node:fs/promises";
 import path from "node:path";
@@ -17,22 +28,20 @@ async function exists(target) {
 
 async function findRepoServer() {
   let cursor = here;
-  for (let depth = 0; depth < 8; depth += 1) {
+  for (let depth = 0; depth < 10; depth += 1) {
     const candidate = path.join(cursor, "dist", "mcp", "server.js");
     if (await exists(candidate)) {
       return candidate;
     }
     const parent = path.dirname(cursor);
-    if (parent === cursor) {
-      break;
-    }
+    if (parent === cursor) break;
     cursor = parent;
   }
   return null;
 }
 
 const explicitServer = process.env.PM_CLI_MCP_SERVER;
-if (explicitServer && await exists(explicitServer)) {
+if (explicitServer && (await exists(explicitServer))) {
   const server = await import(pathToFileURL(explicitServer).href);
   server.startMcpServer();
 } else {
@@ -41,7 +50,7 @@ if (explicitServer && await exists(explicitServer)) {
     const server = await import(pathToFileURL(repoServer).href);
     server.startMcpServer();
   } else {
-    const child = spawn("npx", ["-y", "@unbrained/pm-cli@latest", "pm-mcp"], {
+    const child = spawn("npx", ["-y", "--package=@unbrained/pm-cli@latest", "pm-mcp"], {
       stdio: "inherit",
       env: process.env,
     });

package/plugins/pm-codex/skills/pm-native/SKILL.md

@@ -58,22 +58,10 @@ Most tools accept:
 
 ## Plan workflow (`pm_plan`)
 
-Codex-style living ExecPlans are first-class via the `Plan` item type and the `pm_plan` MCP tool. Plans persist ordered steps, evidence, decisions, discoveries, validation, and resume context so a future stateless agent can pick up the work.
+Codex-style living ExecPlans are first-class via the `Plan` item type and the `pm_plan` MCP tool. Use [Command Reference: Plan Workflow](../../../../docs/COMMANDS.md#plan-workflow) as the canonical lifecycle recipe; this skill keeps only Codex-specific routing notes.
 
 Use `pm_plan` for plan-then-execute workflows; use `pm_create` with type Task/Feature/Epic for already-decomposed backlog work.
 
-```json
-{ "tool": "pm_plan", "args": { "options": { "subcommand": "create", "title": "Refactor lock retry", "scope": "Improve retry semantics under load", "harness": "codex", "parent": "pm-epic1", "claim": true } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "add-step", "stepTitle": "Read lock.ts", "dependsOn": "pm-task1" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "stepRef": "plan-step-001", "options": { "subcommand": "update-step", "stepStatus": "in_progress", "stepEvidence": "started reading lock.ts" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "stepRef": "plan-step-001", "options": { "subcommand": "complete-step", "stepEvidence": "lock.ts read; retry path captured" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "decision", "decisionText": "Use exponential backoff", "decisionRationale": "Avoid thundering herd" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "approve" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "materialize", "steps": "plan-step-002", "materializeType": "Task", "materializeParent": "pm-epic1" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "resume", "resumeContext": "step 2 pending, deps verified" } } }
-{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "show", "depth": "deep" } } }
-```
-
 Invariants:
 
 - One step `in_progress` at a time by default; pass `allowMultipleActive: true` for explicit parallel branches.