@unbrained/pm-cli 2026.5.18 → 2026.5.27

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

@@ -4,36 +4,31 @@ import {
   DEPENDENCY_KIND_VALUES,
   EXIT_CODE,
   PmCliError,
-  acquireLock,
-  appendHistoryEntry,
   canonicalDocument,
-  createHistoryEntry,
+  commitImportedItem,
   generateItemId,
   getActiveExtensionRegistrations,
-  getHistoryPath,
   getItemPath,
-  getSettingsPath,
   isTimestampLiteral,
   locateItem,
   normalizeFrontMatter,
   normalizeItemId,
   normalizeRawItemId,
-  normalizeStatusInput,
   nowIso,
-  parseTags,
   pathExists,
   readSettings,
-  removeFileIfExists,
   resolveItemTypeRegistry,
   resolvePmRoot,
   runActiveOnReadHooks,
-  runActiveOnWriteHooks,
-  serializeItemDocument,
-  writeFileAtomic,
+  ensureTrackerInitialized,
+  selectImportAuthor,
+  toEstimatedMinutesValue,
+  toImportPriority,
+  toImportStatus,
+  toImportTags,
+  toNonEmptyImportString,
   type Dependency,
   type GlobalOptions,
-  type ItemDocument,
-  type ItemMetadata,
   type ItemStatus,
   type ItemType,
   type LinkedDoc,
@@ -102,13 +97,13 @@ interface BeadsRecord extends Record<string, unknown> {
   docs?: unknown;
 }
 
-function toNonEmptyString(value: unknown): string | undefined {
-  if (typeof value !== "string") {
-    return undefined;
-  }
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-}
+// Shared, behavior-identical value coercers are sourced from the SDK adapter
+// surface; package-specific mappings (timestamps, item types, dependencies,
+// linked artifacts) stay local below.
+const toNonEmptyString = toNonEmptyImportString;
+const toEstimatedMinutes = toEstimatedMinutesValue;
+const toPriority = toImportPriority;
+const toTags = toImportTags;
 
 function toIsoString(value: unknown): string | undefined {
   const raw = toNonEmptyString(value);
@@ -121,47 +116,6 @@ function toIsoString(value: unknown): string | undefined {
   return raw;
 }
 
-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 toPriority(value: unknown): 0 | 1 | 2 | 3 | 4 {
-  const fallback: 0 | 1 | 2 | 3 | 4 = 2;
-  if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 4) {
-    return value as 0 | 1 | 2 | 3 | 4;
-  }
-  if (typeof value === "string" && value.trim().length > 0) {
-    const parsed = Number(value);
-    if (Number.isInteger(parsed) && parsed >= 0 && parsed <= 4) {
-      return parsed as 0 | 1 | 2 | 3 | 4;
-    }
-  }
-  return fallback;
-}
-
-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 [];
-}
-
 function toItemType(value: unknown): { type: ItemType; sourceType?: string } {
   const raw = toNonEmptyString(value);
   const normalized = raw?.toLowerCase();
@@ -185,16 +139,7 @@ function toItemType(value: unknown): { type: ItemType; sourceType?: string } {
   }
 }
 
-function toStatus(value: unknown): ItemStatus {
-  const normalized = toNonEmptyString(value);
-  if (normalized) {
-    const canonical = normalizeStatusInput(normalized);
-    if (canonical) {
-      return canonical;
-    }
-  }
-  return "open";
-}
+const toStatus: (value: unknown) => ItemStatus = toImportStatus;
 
 function toDependencyKind(value: unknown): { kind: Dependency["kind"]; sourceKind?: string } {
   const raw = toNonEmptyString(value);
@@ -452,26 +397,8 @@ function toLinkedDocs(value: unknown): LinkedDoc[] | undefined {
   return docs.length > 0 ? docs : undefined;
 }
 
-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);
-    }
-  });
-}
-
-function emptyDocument(): ItemDocument {
-  return {
-    metadata: {} as ItemMetadata,
-    body: "",
-  };
-}
+const selectAuthor = selectImportAuthor;
+const ensureInitHasRun = ensureTrackerInitialized;
 
 function resolveInputPath(rawPath: string): string {
   return path.isAbsolute(rawPath) ? rawPath : path.resolve(process.cwd(), rawPath);
@@ -667,48 +594,22 @@ export async function runBeadsImport(options: BeadsImportOptions, global: Global
     }
     const itemPath = getItemPath(pmRoot, type, id, "toon", typeRegistry.type_to_folder);
 
-    const historyPath = getHistoryPath(pmRoot, id);
-    try {
-      const releaseLock = await acquireLock(pmRoot, id, settings.locks.ttl_seconds, author);
-      try {
-        await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: "toon" }));
-        try {
-          const entry = createHistoryEntry({
-            nowIso: nowIso(),
-            author,
-            op: "import",
-            before: emptyDocument(),
-            after: afterDocument,
-            message,
-          });
-          await appendHistoryEntry(historyPath, entry);
-          warnings.push(
-            ...(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) {
-        warnings.push(`beads_import_lock_conflict:${id}`);
-        skipped += 1;
-        continue;
-      }
-      throw error;
+    const commit = await commitImportedItem({
+      pmRoot,
+      id,
+      itemPath,
+      document: afterDocument,
+      author,
+      message,
+      settings,
+      conflictWarningPrefix: "beads_import_lock_conflict",
+    });
+    if (!commit.committed) {
+      warnings.push(commit.conflictWarning);
+      skipped += 1;
+      continue;
     }
+    warnings.push(...commit.writeWarnings);
 
     ids.push(id);
     imported += 1;

package/packages/pm-calendar/README.md

@@ -3,7 +3,9 @@
 `@unbrained/pm-calendar` provides agenda and calendar views as an installable pm package.
 
 ```bash
-pm install calendar
+pm install calendar --project
+# Or bootstrap all bundled package commands in a new project:
+pm init --defaults --with-packages
 pm calendar --view week --full-period
 pm cal --json --view agenda --include reminders,events
 ```

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

@@ -1,5 +1,19 @@
 import { renderCalendarPackageOutput, runCalendarPackage } from "./runtime.js";
 
+const CALENDAR_VIEW_NAMES = ["agenda", "day", "week", "month"];
+
+// Standalone error class so the package stays self-contained when installed
+// outside the pm-cli source tree. The class name "PmCliError" lines up with
+// the Sentry beforeSend filter (isExpectedCliErrorEvent) so usage errors do
+// not leak into Sentry as crashes.
+class PmCliError extends Error {
+  constructor(message, exitCode) {
+    super(message);
+    this.name = "PmCliError";
+    this.exitCode = exitCode;
+  }
+}
+
 export const manifest = {
   name: "builtin-calendar",
   version: "0.1.0",
@@ -23,7 +37,7 @@ const calendarFlags = [
   { long: "--assignee-filter", value_name: "value", value_type: "string", description: "Filter assignee presence." },
   { long: "--sprint", value_name: "value", value_type: "string", description: "Filter by sprint." },
   { long: "--release", value_name: "value", value_type: "string", description: "Filter by release." },
-  { long: "--include", value_name: "value", value_type: "string", description: "Include sources: deadlines|reminders|events|all." },
+  { long: "--include", value_name: "value", value_type: "string", description: "Include sources: deadlines|reminders|events|scheduled|all." },
   { long: "--recurrence-lookahead-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookahead days." },
   { long: "--recurrence-lookback-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookback days." },
   { long: "--occurrence-limit", value_name: "n", value_type: "string", description: "Cap generated occurrences per recurring event." },
@@ -31,13 +45,63 @@ const calendarFlags = [
   { long: "--format", value_name: "value", value_type: "string", description: "Calendar output override: markdown|toon|json." },
 ];
 
+// The runtime lowercases `view` before validating (src/cli/commands/calendar.ts),
+// so the unknown-alias / recovery-hint logic must match views case-insensitively
+// or `pm calendar DAY ...` would wrongly flag DAY as unknown.
+function normalizeCalendarView(arg) {
+  const normalized = arg.toLowerCase();
+  return CALENDAR_VIEW_NAMES.includes(normalized) ? normalized : null;
+}
+
+function buildPositionalViewError(positionalArgs) {
+  const received = positionalArgs.map((arg) => arg.trim()).filter((arg) => arg.length > 0);
+  const receivedList = received.join(", ");
+  // Check every received positional, not just the tail, so an invalid first
+  // positional (e.g. `pm calendar totally-bogus week`) is still surfaced.
+  const extras = received.filter((arg) => normalizeCalendarView(arg) === null);
+  // Fall back to the first valid view from `received` (normalized to canonical
+  // lowercase) for the recovery hint; recommend `agenda` only when none of the
+  // positionals are valid view names.
+  const recoveryView = received.map(normalizeCalendarView).find((view) => view !== null) ?? "agenda";
+  const hintLines = [`Calendar accepts at most one positional view (agenda|day|week|month), but received: ${receivedList}.`];
+  if (extras.length > 0) {
+    hintLines.push(`Unknown view alias(es): ${extras.join(", ")}.`);
+  }
+  hintLines.push("Use a single view, or pass extra arguments via flags:");
+  hintLines.push(`  pm calendar ${recoveryView}`);
+  hintLines.push(`  pm calendar --view ${recoveryView} --date +7d`);
+  return new PmCliError(hintLines.join("\n"), 2);
+}
+
 function calendarCommand(name) {
   return {
     name,
     action: "calendar",
     description: "Show deadline, reminder, and scheduled event calendar views.",
+    arguments: [{ name: "view", required: false, description: "Calendar view: agenda|day|week|month." }],
     flags: [...calendarFlags],
-    run: async (context) => runCalendarPackage(context.options, context.global),
+    run: async (context) => {
+      // Extension flags are parsed loosely, so context.args still contains flag
+      // tokens (e.g. ["day", "--date", "+7d"]). Only the leading non-flag tokens
+      // are true positionals, so a positional view combined with --date/--from/etc.
+      // must not be mistaken for multiple positional views.
+      const firstFlagIndex = context.args.findIndex((arg) => arg.startsWith("-"));
+      const rawPositionalArgs = firstFlagIndex === -1 ? context.args : context.args.slice(0, firstFlagIndex);
+      // Drop empty/whitespace-only positionals (e.g. from `pm calendar agenda ""`
+      // when a shell variable is unset) so the count check stays meaningful.
+      const positionalArgs = rawPositionalArgs.filter((arg) => arg.trim().length > 0);
+      const positionalView = positionalArgs[0]?.trim();
+      if (positionalArgs.length > 1) {
+        throw buildPositionalViewError(positionalArgs);
+      }
+      return runCalendarPackage(
+        {
+          ...context.options,
+          ...(positionalView && context.options.view === undefined ? { view: positionalView } : {}),
+        },
+        context.global,
+      );
+    },
   };
 }
 

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

@@ -6,6 +6,21 @@ import type {
 import type { CalendarOptions } from "../../../../src/sdk/runtime.js";
 import { renderCalendarPackageOutput, runCalendarPackage } from "./runtime.js";
 
+const CALENDAR_VIEW_NAMES = ["agenda", "day", "week", "month"] as const;
+
+// Standalone error class so the package stays self-contained when installed
+// outside the pm-cli source tree. The class name "PmCliError" lines up with
+// the Sentry beforeSend filter (isExpectedCliErrorEvent) so usage errors do
+// not leak into Sentry as crashes.
+class PmCliError extends Error {
+  exitCode: number;
+  constructor(message: string, exitCode: number) {
+    super(message);
+    this.name = "PmCliError";
+    this.exitCode = exitCode;
+  }
+}
+
 export const manifest = {
   name: "builtin-calendar",
   version: "0.1.0",
@@ -29,7 +44,7 @@ const calendarFlags = [
   { long: "--assignee-filter", value_name: "value", value_type: "string", description: "Filter assignee presence." },
   { long: "--sprint", value_name: "value", value_type: "string", description: "Filter by sprint." },
   { long: "--release", value_name: "value", value_type: "string", description: "Filter by release." },
-  { long: "--include", value_name: "value", value_type: "string", description: "Include sources: deadlines|reminders|events|all." },
+  { long: "--include", value_name: "value", value_type: "string", description: "Include sources: deadlines|reminders|events|scheduled|all." },
   { long: "--recurrence-lookahead-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookahead days." },
   { long: "--recurrence-lookback-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookback days." },
   { long: "--occurrence-limit", value_name: "n", value_type: "string", description: "Cap generated occurrences per recurring event." },
@@ -37,13 +52,67 @@ const calendarFlags = [
   { long: "--format", value_name: "value", value_type: "string", description: "Calendar output override: markdown|toon|json." },
 ] as const;
 
+// The runtime lowercases `view` before validating (src/cli/commands/calendar.ts),
+// so the unknown-alias / recovery-hint logic must match views case-insensitively
+// or `pm calendar DAY ...` would wrongly flag DAY as unknown.
+function normalizeCalendarView(arg: string): (typeof CALENDAR_VIEW_NAMES)[number] | null {
+  const normalized = arg.toLowerCase();
+  return (CALENDAR_VIEW_NAMES as readonly string[]).includes(normalized)
+    ? (normalized as (typeof CALENDAR_VIEW_NAMES)[number])
+    : null;
+}
+
+function buildPositionalViewError(positionalArgs: readonly string[]): PmCliError {
+  const received = positionalArgs.map((arg) => arg.trim()).filter((arg) => arg.length > 0);
+  const receivedList = received.join(", ");
+  // Check every received positional, not just the tail, so an invalid first
+  // positional (e.g. `pm calendar totally-bogus week`) is still surfaced.
+  const extras = received.filter((arg) => normalizeCalendarView(arg) === null);
+  // Fall back to the first valid view from `received` (normalized to canonical
+  // lowercase) for the recovery hint; recommend `agenda` only when none of the
+  // positionals are valid view names.
+  const recoveryView =
+    received.map(normalizeCalendarView).find((view): view is (typeof CALENDAR_VIEW_NAMES)[number] => view !== null) ??
+    "agenda";
+  const hintLines = [`Calendar accepts at most one positional view (agenda|day|week|month), but received: ${receivedList}.`];
+  if (extras.length > 0) {
+    hintLines.push(`Unknown view alias(es): ${extras.join(", ")}.`);
+  }
+  hintLines.push("Use a single view, or pass extra arguments via flags:");
+  hintLines.push(`  pm calendar ${recoveryView}`);
+  hintLines.push(`  pm calendar --view ${recoveryView} --date +7d`);
+  return new PmCliError(hintLines.join("\n"), 2);
+}
+
 function calendarCommand(name: "calendar" | "cal"): CommandDefinition {
   return {
     name,
     action: "calendar",
     description: "Show deadline, reminder, and scheduled event calendar views.",
+    arguments: [{ name: "view", required: false, description: "Calendar view: agenda|day|week|month." }],
     flags: [...calendarFlags],
-    run: async (context) => runCalendarPackage(context.options as CalendarOptions, context.global),
+    run: async (context) => {
+      // Extension flags are parsed loosely, so context.args still contains flag
+      // tokens (e.g. ["day", "--date", "+7d"]). Only the leading non-flag tokens
+      // are true positionals, so a positional view combined with --date/--from/etc.
+      // must not be mistaken for multiple positional views.
+      const firstFlagIndex = context.args.findIndex((arg) => arg.startsWith("-"));
+      const rawPositionalArgs = firstFlagIndex === -1 ? context.args : context.args.slice(0, firstFlagIndex);
+      // Drop empty/whitespace-only positionals (e.g. from `pm calendar agenda ""`
+      // when a shell variable is unset) so the count check stays meaningful.
+      const positionalArgs = rawPositionalArgs.filter((arg) => arg.trim().length > 0);
+      const positionalView = positionalArgs[0]?.trim();
+      if (positionalArgs.length > 1) {
+        throw buildPositionalViewError(positionalArgs);
+      }
+      return runCalendarPackage(
+        {
+          ...(context.options as CalendarOptions),
+          ...(positionalView && (context.options as CalendarOptions).view === undefined ? { view: positionalView } : {}),
+        },
+        context.global,
+      );
+    },
   };
 }
 

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

@@ -90,6 +90,7 @@ function readPayloadGlobalOptions(payload) {
 
 export async function runCalendarPackage(options, global) {
   const loaded = await ensureCalendarCoreModule();
+  loaded.resolveCalendarOutputFormat(options, global);
   return loaded.runCalendar(options, global);
 }
 

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

@@ -99,6 +99,7 @@ function readPayloadGlobalOptions(payload: unknown): GlobalOptions {
 
 export async function runCalendarPackage(options: CalendarOptions, global: GlobalOptions): Promise<CalendarResult> {
   const loaded = await ensureCalendarCoreModule();
+  loaded.resolveCalendarOutputFormat(options, global);
   return loaded.runCalendar(options, global);
 }
 

package/packages/pm-governance-audit/extensions/governance-audit/runtime.js

@@ -29,7 +29,9 @@ async function loadGovernanceModule() {
     if (
       typeof loaded.runDedupeAudit === "function" &&
       typeof loaded.runCommentsAudit === "function" &&
-      typeof loaded.runNormalize === "function"
+      typeof loaded.runNormalize === "function" &&
+      typeof loaded.readStringOption === "function" &&
+      typeof loaded.readBooleanOption === "function"
     ) {
       return loaded;
     }
@@ -41,41 +43,8 @@ async function loadGovernanceModule() {
   );
 }
 
-function readStringOption(options, key, aliases = []) {
-  const keys = [key, ...aliases];
-  for (const candidate of keys) {
-    const value = options[candidate];
-    if (typeof value === "string" && value.trim().length > 0) {
-      return value;
-    }
-  }
-  return undefined;
-}
-
-function readBooleanOption(options, key, aliases = []) {
-  const keys = [key, ...aliases];
-  for (const candidate of keys) {
-    const value = options[candidate];
-    if (value === undefined) {
-      continue;
-    }
-    if (typeof value === "boolean") {
-      return value;
-    }
-    if (typeof value === "string") {
-      const normalized = value.trim().toLowerCase();
-      if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on") {
-        return true;
-      }
-      if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "off") {
-        return false;
-      }
-    }
-  }
-  return undefined;
-}
-
-function normalizeDedupeAuditOptions(raw) {
+function normalizeDedupeAuditOptions(sdk, raw) {
+  const readStringOption = sdk.readStringOption;
   return {
     mode: readStringOption(raw, "mode"),
     status: readStringOption(raw, "status"),
@@ -94,7 +63,9 @@ function normalizeDedupeAuditOptions(raw) {
   };
 }
 
-function normalizeCommentsAuditOptions(raw) {
+function normalizeCommentsAuditOptions(sdk, raw) {
+  const readStringOption = sdk.readStringOption;
+  const readBooleanOption = sdk.readBooleanOption;
   return {
     status: readStringOption(raw, "status"),
     type: readStringOption(raw, "type"),
@@ -112,7 +83,9 @@ function normalizeCommentsAuditOptions(raw) {
   };
 }
 
-function normalizeNormalizeOptions(raw) {
+function normalizeNormalizeOptions(sdk, raw) {
+  const readStringOption = sdk.readStringOption;
+  const readBooleanOption = sdk.readBooleanOption;
   return {
     status: readStringOption(raw, "filterStatus", ["filter_status", "status"]),
     list: {
@@ -145,15 +118,15 @@ function normalizeNormalizeOptions(raw) {
 
 export async function runDedupeAuditPackage(options, global) {
   const module = await ensureGovernanceModule();
-  return module.runDedupeAudit(normalizeDedupeAuditOptions(options), global);
+  return module.runDedupeAudit(normalizeDedupeAuditOptions(module, options), global);
 }
 
 export async function runCommentsAuditPackage(options, global) {
   const module = await ensureGovernanceModule();
-  return module.runCommentsAudit(normalizeCommentsAuditOptions(options), global);
+  return module.runCommentsAudit(normalizeCommentsAuditOptions(module, options), global);
 }
 
 export async function runNormalizePackage(options, global) {
   const module = await ensureGovernanceModule();
-  return module.runNormalize(normalizeNormalizeOptions(options), global);
+  return module.runNormalize(normalizeNormalizeOptions(module, options), global);
 }

package/packages/pm-governance-audit/extensions/governance-audit/runtime.ts

@@ -8,6 +8,8 @@ interface GovernanceRuntimeSdkModule {
   runDedupeAudit: (options: Record<string, unknown>, global: GlobalOptions) => Promise<unknown>;
   runCommentsAudit: (options: Record<string, unknown>, global: GlobalOptions) => Promise<unknown>;
   runNormalize: (options: Record<string, unknown>, global: GlobalOptions) => Promise<unknown>;
+  readStringOption: (options: Record<string, unknown>, key: string, aliases?: string[]) => string | undefined;
+  readBooleanOption: (options: Record<string, unknown>, key: string, aliases?: string[]) => boolean | undefined;
 }
 
 let governanceModule: GovernanceRuntimeSdkModule | null = null;
@@ -37,7 +39,9 @@ async function loadGovernanceModule(): Promise<GovernanceRuntimeSdkModule> {
     if (
       typeof loaded.runDedupeAudit === "function" &&
       typeof loaded.runCommentsAudit === "function" &&
-      typeof loaded.runNormalize === "function"
+      typeof loaded.runNormalize === "function" &&
+      typeof loaded.readStringOption === "function" &&
+      typeof loaded.readBooleanOption === "function"
     ) {
       return loaded as GovernanceRuntimeSdkModule;
     }
@@ -49,41 +53,11 @@ async function loadGovernanceModule(): Promise<GovernanceRuntimeSdkModule> {
   );
 }
 
-function readStringOption(options: Record<string, unknown>, key: string, aliases: string[] = []): string | undefined {
-  const keys = [key, ...aliases];
-  for (const candidate of keys) {
-    const value = options[candidate];
-    if (typeof value === "string" && value.trim().length > 0) {
-      return value;
-    }
-  }
-  return undefined;
-}
-
-function readBooleanOption(options: Record<string, unknown>, key: string, aliases: string[] = []): boolean | undefined {
-  const keys = [key, ...aliases];
-  for (const candidate of keys) {
-    const value = options[candidate];
-    if (value === undefined) {
-      continue;
-    }
-    if (typeof value === "boolean") {
-      return value;
-    }
-    if (typeof value === "string") {
-      const normalized = value.trim().toLowerCase();
-      if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on") {
-        return true;
-      }
-      if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "off") {
-        return false;
-      }
-    }
-  }
-  return undefined;
-}
-
-function normalizeDedupeAuditOptions(raw: Record<string, unknown>): Record<string, unknown> {
+function normalizeDedupeAuditOptions(
+  sdk: GovernanceRuntimeSdkModule,
+  raw: Record<string, unknown>,
+): Record<string, unknown> {
+  const readStringOption = sdk.readStringOption;
   return {
     mode: readStringOption(raw, "mode"),
     status: readStringOption(raw, "status"),
@@ -102,7 +76,12 @@ function normalizeDedupeAuditOptions(raw: Record<string, unknown>): Record<strin
   };
 }
 
-function normalizeCommentsAuditOptions(raw: Record<string, unknown>): Record<string, unknown> {
+function normalizeCommentsAuditOptions(
+  sdk: GovernanceRuntimeSdkModule,
+  raw: Record<string, unknown>,
+): Record<string, unknown> {
+  const readStringOption = sdk.readStringOption;
+  const readBooleanOption = sdk.readBooleanOption;
   return {
     status: readStringOption(raw, "status"),
     type: readStringOption(raw, "type"),
@@ -120,7 +99,12 @@ function normalizeCommentsAuditOptions(raw: Record<string, unknown>): Record<str
   };
 }
 
-function normalizeNormalizeOptions(raw: Record<string, unknown>): Record<string, unknown> {
+function normalizeNormalizeOptions(
+  sdk: GovernanceRuntimeSdkModule,
+  raw: Record<string, unknown>,
+): Record<string, unknown> {
+  const readStringOption = sdk.readStringOption;
+  const readBooleanOption = sdk.readBooleanOption;
   return {
     status: readStringOption(raw, "filterStatus", ["filter_status", "status"]),
     list: {
@@ -156,7 +140,7 @@ export async function runDedupeAuditPackage(
   global: GlobalOptions,
 ): Promise<unknown> {
   const module = await ensureGovernanceModule();
-  return module.runDedupeAudit(normalizeDedupeAuditOptions(options), global);
+  return module.runDedupeAudit(normalizeDedupeAuditOptions(module, options), global);
 }
 
 export async function runCommentsAuditPackage(
@@ -164,7 +148,7 @@ export async function runCommentsAuditPackage(
   global: GlobalOptions,
 ): Promise<unknown> {
   const module = await ensureGovernanceModule();
-  return module.runCommentsAudit(normalizeCommentsAuditOptions(options), global);
+  return module.runCommentsAudit(normalizeCommentsAuditOptions(module, options), global);
 }
 
 export async function runNormalizePackage(
@@ -172,5 +156,5 @@ export async function runNormalizePackage(
   global: GlobalOptions,
 ): Promise<unknown> {
   const module = await ensureGovernanceModule();
-  return module.runNormalize(normalizeNormalizeOptions(options), global);
+  return module.runNormalize(normalizeNormalizeOptions(module, options), global);
 }