@unbrained/pm-cli 2026.7.1 → 2026.7.3

package/docs/EXTENSIONS.md

@@ -86,7 +86,7 @@ Package roots declare resources in `package.json` under `pm`:
 
 Installation activates `pm.extensions`. `pm.docs`, `pm.examples`, `pm.assets`, and `pm.prompts` are catalog metadata (metadata-only — they are discovered and surfaced in the catalog but not executed). Declare agent-facing prompt/slash-command markdown under `pm.prompts` and non-code assets (images, skills, fixtures) under `pm.assets`; their conventional roots are `prompts/` (also `.agents/pm/prompts/`) and `assets/` (also `.agents/pm/assets/`).
 
-`pm package init` emits a root extension (`"extensions": ["."]`) authored **and loaded** as TypeScript (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)): a typed `index.ts`, a strict type-check-only `tsconfig.json`, and `typecheck`/`test` scripts, with the manifest `entry` pointing at `./index.ts` itself. pm loads that `.ts` entry directly via Node's native type stripping (Node >=22.18), so there is no build step — run `npm install` (for the peer SDK and type-checking) before `pm install`. The generated README shows how to author exported command/hook definitions with the SDK [define* builders](../.agents/pm/decisions/pm-3mph.toon). The default `--capability commands` scaffold registers a starter command and a colocated `node:test` suite. `--capability hooks` keeps the starter command and adds an `after_command` lifecycle hook plus SDK testing coverage with `assertRegisteredHook` and `runRegisteredHookForTest`, giving package authors a runnable template for reacting to pm mutations when project management is context management. `--capability search` keeps the starter command and adds a deterministic search provider/vector-store adapter pair plus SDK tests with `assertRegisteredSearchProvider`, `assertRegisteredVectorStoreAdapter`, `runRegisteredSearchProviderForTest`, and `runRegisteredVectorStoreAdapterForTest`, giving retrieval packages a copyable context-management primitive without external services. `--capability importers` keeps the starter command and adds paired import/export command registrations plus SDK tests with `assertRegisteredImporter`, `assertRegisteredExporter`, `runRegisteredImporterForTest`, and `runRegisteredExporterForTest`, giving integration packages a copyable context-movement primitive for synchronizing external project systems; the generated manifest declares both `importers` and `schema` because the starter includes schema-governed flag metadata. `--capability schema` keeps the starter command and registers a custom item type, item field, and migration via `api.registerItemTypes`, `api.registerItemFields`, and `api.registerMigration`, with SDK tests using `assertRegisteredItemType`, `assertRegisteredItemField`, `assertRegisteredMigration`, and `runRegisteredMigrationForTest`; it deliberately omits `activation.commands` because a custom item type is a global contribution that built-in commands (`pm create <type>`, `pm list`, `pm validate`) must see, so pm activates it conservatively for every command. `--capability profile` keeps the starter command and registers a complete project-profile archetype — item types, custom statuses, fields, a per-type workflow, config knobs, a create template, and package recommendations — via `api.registerProfile`, with an SDK test using the harness-bound `assertProfile` (the public `assertRegisteredProfile`); like the schema starter it omits `activation.commands` because the contributed profile is resolved by the built-in `pm profile list/show/apply` commands (granted by the same `schema` capability, since a profile is a schema+config bundle), so pm activates it conservatively for every command and `pm profile apply <name>` tailors a fresh tracker in one shot. The remaining four capabilities complete the matrix to one starter per SDK registration surface. `--capability renderers` keeps the starter command and adds a `toon` output renderer override via `api.registerRenderer` (scoped to its own command — it returns `null` to pass other output through to pm's default renderer) plus SDK tests with `assertRegisteredRendererOverride` and `runRegisteredRendererOverrideForTest`. `--capability parser` adds a parser override via `api.registerParser` that rewrites the command's parsed options before its handler runs (a deprecated `--shout`→`--upper` alias rewrite); the starter command declares the matching `--shout`/`--upper` flags and surfaces the normalized value so the override is runnable end to end through `pm <command> --shout`, and the manifest also declares `schema` because flag metadata is schema-governed, with SDK tests using `assertRegisteredParserOverride` and `runRegisteredParserOverrideForTest`. `--capability preflight` adds a preflight override via `api.registerPreflight` over pm's pre-run migration/format gate decision (a safe no-op echo by default) plus SDK tests with `assertRegisteredPreflightOverride` and `runRegisteredPreflightOverrideForTest`. `--capability services` overrides the built-in `output_format` service via `api.registerService` (scoped to its own command, passing other commands' output through) plus SDK tests with `assertRegisteredServiceOverride` and `runRegisteredServiceOverrideForTest`. Starter manifests use the same least-privilege policy metadata as pure first-party command packages: `trusted: true`, `sandbox_profile: "strict"`, and explicit `false` permissions for `fs_read`, `fs_write`, `network`, `env_read`, `env_write`, and `process_spawn`. Larger packages may point at nested extension directories after declaring runtime dependencies, relaxing only the permissions they actually need, and validating with `pm package doctor`, which additionally emits the advisory `extension_schema_narrow_activation` warning when a package registers custom item types/fields yet declares narrow `activation.commands` (the schema footgun above), recommending the field be dropped so the type stays globally available.
+`pm package init` emits a root extension (`"extensions": ["."]`) authored **and loaded** as TypeScript (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)): a typed `index.ts`, a strict type-check-only `tsconfig.json`, and `typecheck`/`test` scripts, with the manifest `entry` pointing at `./index.ts` itself. pm loads that `.ts` entry directly via Node's native type stripping (Node >=22.18), so there is no build step — run `npm install` (for the peer SDK and type-checking) before `pm install`. The generated README shows how to author exported command/hook definitions with the SDK [define* builders](../.agents/pm/decisions/pm-3mph.toon). `--capability` selects one of ten starters — one per SDK registration surface (`commands`, `hooks`, `search`, `importers`, `schema`, `profile`, `renderers`, `parser`, `preflight`, `services`) — each keeping a runnable starter command and adding the surface's registration plus a colocated `node:test` suite built on the matching SDK `assertRegistered*`/`runRegistered*ForTest` helpers. The full per-capability matrix (what each starter registers, which starters also declare `schema` because flag metadata is schema-governed, and why `schema`/`profile` omit `activation.commands` so their global contributions activate conservatively for every command) lives in [SDK.md — Minimal Command Extension](./SDK.md#minimal-command-extension). Starter manifests use the same least-privilege policy metadata as pure first-party command packages: `trusted: true`, `sandbox_profile: "strict"`, and explicit `false` permissions for `fs_read`, `fs_write`, `network`, `env_read`, `env_write`, and `process_spawn`. Larger packages may point at nested extension directories after declaring runtime dependencies, relaxing only the permissions they actually need, and validating with `pm package doctor`, which additionally emits the advisory `extension_schema_narrow_activation` warning when a package registers custom item types/fields yet declares narrow `activation.commands` (the schema footgun above), recommending the field be dropped so the type stays globally available.
 
 Package tests can pair `readPmPackageManifest(packageRoot)` with
 `assertPackageManifest(manifest, { resources: ... })` from
@@ -217,17 +217,17 @@ Supported capabilities:
 
 First-party package exemplars:
 
-- `pm-beads`: beads JSON/JSONL importer/exporter package with generated command contracts.
-- `pm-calendar`: calendar view package for schedule/context surfaces.
-- `pm-command-kit`: command capability exemplar for `registerCommand`, `registerFlags`, and `registerParser`.
-- `pm-governance-audit`: governance hook exemplar for compact read/write sidecar logs.
-- `pm-guide-shell`: guide-topic package for bundled workflow docs.
-- `pm-kanban`: archetype exemplar shipping a complete Kanban continuous-flow profile (Card type, flow fields, and a `ProjectProfileDefinition`) on public SDK primitives.
-- `pm-lifecycle-hooks`: default-inert lifecycle hook registration.
-- `pm-linked-test-adapters`: linked-test run-management adapters and reporters.
-- `pm-search-advanced`: deterministic local search provider registration.
-- `pm-templates`: reusable create-template package.
-- `pm-todos`: todo import/export package with generated command contracts.
+- [`pm-beads`](../packages/pm-beads/README.md): beads JSON/JSONL importer/exporter package with generated command contracts.
+- [`pm-calendar`](../packages/pm-calendar/README.md): calendar view package for schedule/context surfaces.
+- [`pm-command-kit`](../packages/pm-command-kit/README.md): command capability exemplar for `registerCommand`, `registerFlags`, and `registerParser`.
+- [`pm-governance-audit`](../packages/pm-governance-audit/README.md): governance hook exemplar for compact read/write sidecar logs.
+- [`pm-guide-shell`](../packages/pm-guide-shell/README.md): guide-topic package for bundled workflow docs.
+- [`pm-kanban`](../packages/pm-kanban/README.md): archetype exemplar shipping a complete Kanban continuous-flow profile (Card type, flow fields, and a `ProjectProfileDefinition`) on public SDK primitives.
+- [`pm-lifecycle-hooks`](../packages/pm-lifecycle-hooks/README.md): default-inert lifecycle hook registration.
+- [`pm-linked-test-adapters`](../packages/pm-linked-test-adapters/README.md): linked-test run-management adapters and reporters.
+- [`pm-search-advanced`](../packages/pm-search-advanced/README.md): deterministic local search provider registration.
+- [`pm-templates`](../packages/pm-templates/README.md): reusable create-template package.
+- [`pm-todos`](../packages/pm-todos/README.md): todo import/export package with generated command contracts.
 
 ## Governance Policy
 

package/docs/ONBOARDING.md

@@ -14,7 +14,7 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon), [pm-oh5
 
 ## Prerequisites
 
-- Node.js 20 or newer
+- Node.js 22.18 or newer
 - pnpm 10 or newer
 - Git + GitHub CLI (`gh`) authenticated for this repository
 
@@ -74,6 +74,8 @@ pm validate --check-resolution --check-history-drift
 
 ## Real Tracker Workflow (Canonical Loop)
 
+The canonical loop is maintained in [AGENT_GUIDE.md](AGENT_GUIDE.md) — this is the condensed contributor version.
+
 1) Orient and dedupe
 
 ```bash
@@ -141,7 +143,7 @@ pnpm release:pipeline
 ```bash
 pm health --check-only
 pm validate --check-resolution --check-history-drift
-pm normalize --dry-run --json
+pm normalize --dry-run --json   # requires the governance-audit package
 pm package doctor --project --detail summary
 pm contracts --command <command> --flags-only --json
 ```

package/docs/README.md

@@ -61,6 +61,8 @@ pm guide release --json
 
 Community files:
 
+- [Agent operating rules](../AGENTS.md)
+- [Product requirements](../PRD.md)
 - [Contributing](../CONTRIBUTING.md)
 - [Security](../SECURITY.md)
 - [Code of Conduct](../CODE_OF_CONDUCT.md)

package/docs/examples/starter-extension/README.md

@@ -36,28 +36,29 @@ cd .agents/pm/extensions/starter-extension
 npm install
 cd -
 
-# 3) Install/activate in project scope
-pm extension --install --project .agents/pm/extensions/starter-extension
+# 3) Install/activate in project scope (package-first vocabulary;
+#    `pm extension --install` remains as a compatibility form)
+pm install .agents/pm/extensions/starter-extension --project
 
 # 4) Run a starter command
 pm starter ping --name "agent"
 
 # 5) Reload extension modules after edits
-pm extension --reload --project
+pm package --reload --project
 
 # 6) Optional watch-mode semantics
-pm extension --reload --project --watch
+pm package --reload --project --watch
 
 # 7) Verify runtime health
-pm extension --doctor --project --detail summary
+pm package doctor --project --detail summary
 ```
 
 Expected outcomes:
 
 - `pm starter ping` returns deterministic output (plain text when starter service overrides output formatting).
-- `extension --doctor` shows `details.summary.status` as `ok` or `warn`.
+- `pm package doctor` shows `details.summary.status` as `ok` or `warn`.
 - If `warn`, inspect `details.summary.warning_codes` and `details.triage.remediation`.
-- `extension --reload` returns deterministic load/activation diagnostics for cache-busted imports.
+- `pm package --reload` returns deterministic load/activation diagnostics for cache-busted imports.
 
 ## Policy-Restricted Variant
 
@@ -65,15 +66,15 @@ To test governance controls with this extension:
 
 1. Set `settings.extensions.policy.mode` to `warn` or `enforce`.
 2. Block one surface (for example `commands.override`).
-3. Re-run `pm extension --doctor --detail summary`.
+3. Re-run `pm package doctor --detail summary`.
 
 You should see `extension_policy_*` warnings and policy counters in `details.triage`.
 
 ## CI-Friendly Verification Commands
 
 ```bash
-pm contracts --command extension --flags-only --json
-pm extension --doctor --project --detail summary --strict-exit
+pm contracts --command package --flags-only --json
+pm package doctor --project --detail summary --strict-exit
 node scripts/run-tests.mjs test -- tests/unit/extension-loader.spec.ts tests/unit/extension-command.spec.ts
 ```
 

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "1.4.0"
+    "version": "1.4.1"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
-      "description": "Native pm CLI integration for Claude Code — 25 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "1.4.0",
+      "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
+      "version": "1.4.1",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.7.1",
+  "version": "2026.7.3",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -133,7 +133,7 @@
     }
   },
   "dependencies": {
-    "@sentry/node": "^10.62.0",
+    "@sentry/node": "^10.63.0",
     "@toon-format/toon": "^2.3.0",
     "commander": "^15.0.0",
     "fast-glob": "^3.3.3",

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

@@ -88,6 +88,19 @@ interface ItemTypeRegistry {
   type_to_folder: Record<string, string>;
 }
 
+interface BeadsImportRuntime {
+  sdk: BeadsSdkModule;
+  pmRoot: string;
+  settings: PmSettings;
+  typeRegistry: ItemTypeRegistry;
+  preserveSourceIds: boolean;
+  author: string;
+  message: string;
+}
+
+type BeadsImportLineResult = { id: string; writeWarnings: string[] } | { warning: string };
+type ParsedBeadsLine = { record: BeadsRecord } | { warning: string } | null;
+
 interface BeadsSdkModule {
   DEPENDENCY_KIND_VALUES: readonly Dependency["kind"][];
   EXIT_CODE: {
@@ -135,50 +148,73 @@ interface BeadsSdkModule {
   toNonEmptyImportString: (value: unknown) => string | undefined;
 }
 
-async function loadBeadsSdkModule(): Promise<BeadsSdkModule> {
+const BEADS_SDK_ARRAY_EXPORTS = [
+  "DEPENDENCY_KIND_VALUES",
+] as const satisfies readonly (keyof BeadsSdkModule)[];
+
+const BEADS_SDK_FUNCTION_EXPORTS = [
+  "PmCliError",
+  "canonicalDocument",
+  "commitImportedItem",
+  "ensureTrackerInitialized",
+  "generateItemId",
+  "getActiveExtensionRegistrations",
+  "getItemPath",
+  "isTimestampLiteral",
+  "locateItem",
+  "normalizeFrontMatter",
+  "normalizeItemId",
+  "normalizeRawItemId",
+  "nowIso",
+  "pathExists",
+  "readSettings",
+  "resolveItemTypeRegistry",
+  "resolvePmRoot",
+  "runActiveOnReadHooks",
+  "selectImportAuthor",
+  "toEstimatedMinutesValue",
+  "toImportPriority",
+  "toImportStatus",
+  "toImportTags",
+  "toNonEmptyImportString",
+] as const satisfies readonly (keyof BeadsSdkModule)[];
+
+function resolveBeadsSdkModulePath(): string {
   const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
   const hasConfiguredPackageRoot = typeof envRoot === "string" && envRoot.trim().length > 0;
-  const packageRoot =
-    hasConfiguredPackageRoot
-      ? path.resolve(envRoot.trim())
-      : path.resolve(CURRENT_RUNTIME_ROOT, "../../../..");
-  const modulePath = hasConfiguredPackageRoot
+  const packageRoot = hasConfiguredPackageRoot ? path.resolve(envRoot.trim()) : path.resolve(CURRENT_RUNTIME_ROOT, "../../../..");
+  return hasConfiguredPackageRoot
     ? path.join(packageRoot, "dist", "sdk", "index.js")
     : path.join(packageRoot, "src", "sdk", "index.ts");
+}
+
+function hasBeadsSdkArrayExports(loaded: Partial<BeadsSdkModule>): boolean {
+  return BEADS_SDK_ARRAY_EXPORTS.every((key) => Array.isArray(loaded[key]));
+}
+
+function hasBeadsSdkFunctionExports(loaded: Partial<BeadsSdkModule>): boolean {
+  return BEADS_SDK_FUNCTION_EXPORTS.every((key) => typeof loaded[key] === "function");
+}
+
+function hasBeadsSdkExitCodeExports(loaded: Partial<BeadsSdkModule>): boolean {
+  return (
+    typeof loaded.EXIT_CODE === "object" &&
+    loaded.EXIT_CODE !== null &&
+    typeof loaded.EXIT_CODE.NOT_FOUND === "number" &&
+    typeof loaded.EXIT_CODE.USAGE === "number"
+  );
+}
+
+function isBeadsSdkModule(loaded: Partial<BeadsSdkModule>): loaded is BeadsSdkModule {
+  return hasBeadsSdkArrayExports(loaded) && hasBeadsSdkFunctionExports(loaded) && hasBeadsSdkExitCodeExports(loaded);
+}
+
+async function loadBeadsSdkModule(): Promise<BeadsSdkModule> {
+  const modulePath = resolveBeadsSdkModulePath();
   try {
     const loaded = (await import(pathToFileURL(modulePath).href)) as Partial<BeadsSdkModule>;
-    if (
-      Array.isArray(loaded.DEPENDENCY_KIND_VALUES) &&
-      typeof loaded.EXIT_CODE === "object" &&
-      loaded.EXIT_CODE !== null &&
-      typeof loaded.EXIT_CODE.NOT_FOUND === "number" &&
-      typeof loaded.EXIT_CODE.USAGE === "number" &&
-      typeof loaded.PmCliError === "function" &&
-      typeof loaded.canonicalDocument === "function" &&
-      typeof loaded.commitImportedItem === "function" &&
-      typeof loaded.ensureTrackerInitialized === "function" &&
-      typeof loaded.generateItemId === "function" &&
-      typeof loaded.getActiveExtensionRegistrations === "function" &&
-      typeof loaded.getItemPath === "function" &&
-      typeof loaded.isTimestampLiteral === "function" &&
-      typeof loaded.locateItem === "function" &&
-      typeof loaded.normalizeFrontMatter === "function" &&
-      typeof loaded.normalizeItemId === "function" &&
-      typeof loaded.normalizeRawItemId === "function" &&
-      typeof loaded.nowIso === "function" &&
-      typeof loaded.pathExists === "function" &&
-      typeof loaded.readSettings === "function" &&
-      typeof loaded.resolveItemTypeRegistry === "function" &&
-      typeof loaded.resolvePmRoot === "function" &&
-      typeof loaded.runActiveOnReadHooks === "function" &&
-      typeof loaded.selectImportAuthor === "function" &&
-      typeof loaded.toEstimatedMinutesValue === "function" &&
-      typeof loaded.toImportPriority === "function" &&
-      typeof loaded.toImportStatus === "function" &&
-      typeof loaded.toImportTags === "function" &&
-      typeof loaded.toNonEmptyImportString === "function"
-    ) {
-      return loaded as BeadsSdkModule;
+    if (isBeadsSdkModule(loaded)) {
+      return loaded;
     }
   } catch (error: unknown) {
     throw new Error(`builtin-beads failed to load SDK exports from ${modulePath}.`, { cause: error });
@@ -186,19 +222,15 @@ async function loadBeadsSdkModule(): Promise<BeadsSdkModule> {
   throw new Error(`builtin-beads failed to load SDK exports from ${modulePath}.`);
 }
 
+const beadsSdk = await loadBeadsSdkModule();
+
 const {
   DEPENDENCY_KIND_VALUES,
   EXIT_CODE,
   PmCliError,
-  canonicalDocument,
-  commitImportedItem,
   ensureTrackerInitialized,
-  generateItemId,
   getActiveExtensionRegistrations,
-  getItemPath,
   isTimestampLiteral,
-  locateItem,
-  normalizeFrontMatter,
   normalizeItemId,
   normalizeRawItemId,
   nowIso,
@@ -213,7 +245,7 @@ const {
   toImportStatus,
   toImportTags,
   toNonEmptyImportString,
-} = await loadBeadsSdkModule();
+} = beadsSdk;
 
 // Shared, behavior-identical value coercers are sourced from the SDK adapter
 // surface; package-specific mappings (timestamps, item types, dependencies,
@@ -451,36 +483,49 @@ function toLinkedTests(value: unknown): LinkedTest[] | undefined {
       if (c) tests.push({ command: c, scope: "project" });
       continue;
     }
-    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-      continue;
-    }
-    const candidate = entry as Record<string, unknown>;
-    const command = toNonEmptyString(candidate.command) ?? toNonEmptyString(candidate.test);
-    const p = toNonEmptyString(candidate.path);
-    if (!command && !p) continue;
-
-    let timeout: number | undefined;
-    if (typeof candidate.timeout_seconds === "number" && Number.isFinite(candidate.timeout_seconds)) {
-      timeout = candidate.timeout_seconds;
-    } else if (typeof candidate.timeout_seconds === "string") {
-      const parsed = Number(candidate.timeout_seconds);
-      if (Number.isFinite(parsed) && parsed >= 0) {
-        timeout = parsed;
-      }
+    const linkedTest = toLinkedTestFromRecord(entry);
+    if (linkedTest) {
+      tests.push(linkedTest);
     }
-
-    tests.push({
-      command,
-      path: p,
-      scope: toNonEmptyString(candidate.scope) === "global" ? "global" : "project",
-      timeout_seconds: timeout,
-      note: toNonEmptyString(candidate.note),
-    });
   }
 
   return tests.length > 0 ? tests : undefined;
 }
 
+function toLinkedTestTimeout(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+    return value;
+  }
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const parsed = Number(trimmed);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+function toLinkedTestFromRecord(value: unknown): LinkedTest | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const candidate = value as Record<string, unknown>;
+  const command = toNonEmptyString(candidate.command) ?? toNonEmptyString(candidate.test);
+  const p = toNonEmptyString(candidate.path);
+  if (!command && !p) {
+    return undefined;
+  }
+  return {
+    command,
+    path: p,
+    scope: toNonEmptyString(candidate.scope) === "global" ? "global" : "project",
+    timeout_seconds: toLinkedTestTimeout(candidate.timeout_seconds),
+    note: toNonEmptyString(candidate.note),
+  };
+}
+
 function toLinkedDocs(value: unknown): LinkedDoc[] | undefined {
   if (typeof value === "string") {
     const p = toNonEmptyString(value);
@@ -596,6 +641,114 @@ async function resolveBeadsSource(rawPath: string | undefined): Promise<{
   );
 }
 
+function parseBeadsLine(line: string, lineNumber: number): ParsedBeadsLine {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed) as unknown;
+  } catch {
+    return { warning: `beads_import_invalid_jsonl_line:${lineNumber}` };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { warning: `beads_import_invalid_record:${lineNumber}` };
+  }
+  return { record: parsed as BeadsRecord };
+}
+
+async function resolveBeadsImportId(record: BeadsRecord, runtime: BeadsImportRuntime): Promise<string> {
+  const rawId = toNonEmptyString(record.id);
+  return rawId
+    ? normalizeImportedId(rawId, runtime.settings.id_prefix, runtime.preserveSourceIds)
+    : await runtime.sdk.generateItemId(runtime.pmRoot, runtime.settings.id_prefix);
+}
+
+function buildBeadsImportedBody(record: BeadsRecord): string {
+  const rawBody = toNonEmptyString(record.body) ?? "";
+  const design = toNonEmptyString(record.design);
+  const externalRef = toNonEmptyString(record.external_ref);
+  let finalBody = rawBody;
+  if (design) {
+    finalBody += (finalBody ? "\n\n" : "") + "## Design\n\n" + design;
+  }
+  if (externalRef) {
+    finalBody += (finalBody ? "\n\n" : "") + "## External Reference\n" + externalRef;
+  }
+  return finalBody;
+}
+
+async function importBeadsRecord(record: BeadsRecord, lineNumber: number, runtime: BeadsImportRuntime): Promise<BeadsImportLineResult> {
+  const title = toNonEmptyString(record.title);
+  if (!title) {
+    return { warning: `beads_import_missing_title:${lineNumber}` };
+  }
+
+  const createdAt = toIsoString(record.created_at) ?? nowIso();
+  const updatedAt = toIsoString(record.updated_at) ?? createdAt;
+  const id = await resolveBeadsImportId(record, runtime);
+  const typeMapping = toItemType(record.issue_type ?? record.type);
+  const type = typeMapping.type;
+  const closedAt = toIsoString(record.closed_at);
+  const assignee = toNonEmptyString(record.assignee) ?? toNonEmptyString(record.owner);
+  const frontMatter = runtime.sdk.normalizeFrontMatter({
+    id,
+    title,
+    description: toNonEmptyString(record.description) ?? "",
+    type,
+    source_type: typeMapping.sourceType,
+    status: toStatus(record.status),
+    priority: toPriority(record.priority),
+    tags: toTags(record.tags ?? record.labels),
+    created_at: createdAt,
+    updated_at: updatedAt,
+    deadline: toIsoString(record.due_at ?? record.deadline),
+    closed_at: closedAt,
+    assignee,
+    source_owner: toNonEmptyString(record.owner),
+    author: toNonEmptyString(record.author) ?? toNonEmptyString(record.created_by) ?? runtime.author,
+    estimated_minutes: toEstimatedMinutes(record.estimated_minutes),
+    acceptance_criteria: toNonEmptyString(record.acceptance_criteria),
+    design: toNonEmptyString(record.design),
+    external_ref: toNonEmptyString(record.external_ref),
+    close_reason: toNonEmptyString(record.close_reason),
+    dependencies: toDependencies(record.dependencies, createdAt, runtime.settings.id_prefix, runtime.preserveSourceIds),
+    comments: toLogEntries(record.comments, createdAt, runtime.author),
+    notes: toLogEntries(record.notes, createdAt, runtime.author),
+    learnings: toLogEntries(record.learnings, createdAt, runtime.author),
+    files: toLinkedFiles(record.files),
+    tests: toLinkedTests(record.tests),
+    docs: toLinkedDocs(record.docs),
+  });
+  const afterDocument = runtime.sdk.canonicalDocument({
+    metadata: frontMatter,
+    body: buildBeadsImportedBody(record),
+  });
+  const existing = await runtime.sdk.locateItem(
+    runtime.pmRoot,
+    id,
+    runtime.settings.id_prefix,
+    runtime.settings.item_format,
+    runtime.typeRegistry.type_to_folder,
+  );
+  if (existing) {
+    return { warning: `beads_import_item_exists:${id}` };
+  }
+  const itemPath = runtime.sdk.getItemPath(runtime.pmRoot, type, id, "toon", runtime.typeRegistry.type_to_folder);
+  const commit = await runtime.sdk.commitImportedItem({
+    pmRoot: runtime.pmRoot,
+    id,
+    itemPath,
+    document: afterDocument,
+    author: runtime.author,
+    message: runtime.message,
+    settings: runtime.settings,
+    conflictWarningPrefix: "beads_import_lock_conflict",
+  });
+  return commit.committed ? { id, writeWarnings: commit.writeWarnings } : { warning: commit.conflictWarning };
+}
+
 export async function runBeadsImport(options: BeadsImportOptions, global: GlobalOptions): Promise<BeadsImportResult> {
   const pmRoot = resolvePmRoot(process.cwd(), global.path);
   await ensureInitHasRun(pmRoot);
@@ -621,115 +774,35 @@ export async function runBeadsImport(options: BeadsImportOptions, global: Global
   const ids: string[] = [];
   let imported = 0;
   let skipped = 0;
+  const runtime: BeadsImportRuntime = {
+    sdk: beadsSdk,
+    pmRoot,
+    settings,
+    typeRegistry,
+    preserveSourceIds,
+    author,
+    message,
+  };
 
   for (let index = 0; index < lines.length; index += 1) {
     const lineNumber = index + 1;
-    const line = lines[index].trim();
-    if (line.length === 0) {
-      continue;
-    }
-
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(line) as unknown;
-    } catch {
-      warnings.push(`beads_import_invalid_jsonl_line:${lineNumber}`);
-      skipped += 1;
-      continue;
-    }
-
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-      warnings.push(`beads_import_invalid_record:${lineNumber}`);
-      skipped += 1;
-      continue;
-    }
-    const record = parsed as BeadsRecord;
-
-    const title = toNonEmptyString(record.title);
-    if (!title) {
-      warnings.push(`beads_import_missing_title:${lineNumber}`);
-      skipped += 1;
+    const parsed = parseBeadsLine(lines[index], lineNumber);
+    if (!parsed) {
       continue;
     }
-
-    const createdAt = toIsoString(record.created_at) ?? nowIso();
-    const updatedAt = toIsoString(record.updated_at) ?? createdAt;
-    const id = toNonEmptyString(record.id)
-      ? normalizeImportedId(toNonEmptyString(record.id) as string, settings.id_prefix, preserveSourceIds)
-      : await generateItemId(pmRoot, settings.id_prefix);
-    const typeMapping = toItemType(record.issue_type ?? record.type);
-    const type = typeMapping.type;
-    const closedAt = toIsoString(record.closed_at);
-    const assignee = toNonEmptyString(record.assignee) ?? toNonEmptyString(record.owner);
-    const frontMatter = normalizeFrontMatter({
-      id,
-      title,
-      description: toNonEmptyString(record.description) ?? "",
-      type,
-      source_type: typeMapping.sourceType,
-      status: toStatus(record.status),
-      priority: toPriority(record.priority),
-      tags: toTags(record.tags ?? record.labels),
-      created_at: createdAt,
-      updated_at: updatedAt,
-      deadline: toIsoString(record.due_at ?? record.deadline),
-      closed_at: closedAt,
-      assignee,
-      source_owner: toNonEmptyString(record.owner),
-      author: toNonEmptyString(record.author) ?? toNonEmptyString(record.created_by) ?? author,
-      estimated_minutes: toEstimatedMinutes(record.estimated_minutes),
-      acceptance_criteria: toNonEmptyString(record.acceptance_criteria),
-      design: toNonEmptyString(record.design),
-      external_ref: toNonEmptyString(record.external_ref),
-      close_reason: toNonEmptyString(record.close_reason),
-      dependencies: toDependencies(record.dependencies, createdAt, settings.id_prefix, preserveSourceIds),
-      comments: toLogEntries(record.comments, createdAt, author),
-      notes: toLogEntries(record.notes, createdAt, author),
-      learnings: toLogEntries(record.learnings, createdAt, author),
-      files: toLinkedFiles(record.files),
-      tests: toLinkedTests(record.tests),
-      docs: toLinkedDocs(record.docs),
-    });
-    const rawBody = toNonEmptyString(record.body) ?? "";
-    const design = toNonEmptyString(record.design);
-    const externalRef = toNonEmptyString(record.external_ref);
-    let finalBody = rawBody;
-    if (design) {
-      finalBody += (finalBody ? "\n\n" : "") + "## Design\n\n" + design;
-    }
-    if (externalRef) {
-      finalBody += (finalBody ? "\n\n" : "") + "## External Reference\n" + externalRef;
-    }
-    const afterDocument = canonicalDocument({
-      metadata: frontMatter,
-      body: finalBody,
-    });
-    const existing = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
-    if (existing) {
-      warnings.push(`beads_import_item_exists:${id}`);
+    if ("warning" in parsed) {
+      warnings.push(parsed.warning);
       skipped += 1;
       continue;
     }
-    const itemPath = getItemPath(pmRoot, type, id, "toon", typeRegistry.type_to_folder);
-
-    const commit = await commitImportedItem({
-      pmRoot,
-      id,
-      itemPath,
-      document: afterDocument,
-      author,
-      message,
-      settings,
-      conflictWarningPrefix: "beads_import_lock_conflict",
-    });
-    if (!commit.committed) {
-      warnings.push(commit.conflictWarning);
+    const importedLine = await importBeadsRecord(parsed.record, lineNumber, runtime);
+    if ("warning" in importedLine) {
+      warnings.push(importedLine.warning);
       skipped += 1;
       continue;
     }
-    warnings.push(...commit.writeWarnings);
-
-    ids.push(id);
+    warnings.push(...importedLine.writeWarnings);
+    ids.push(importedLine.id);
     imported += 1;
   }