@unbrained/pm-cli 2026.5.6 → 2026.5.11

package/dist/sdk/index.d.ts

@@ -8,6 +8,17 @@ export * from "./cli-contracts.js";
  */
 export declare const EXTENSION_CAPABILITIES: readonly ["commands", "renderers", "hooks", "schema", "importers", "search", "parser", "preflight", "services"];
 export type ExtensionCapability = (typeof EXTENSION_CAPABILITIES)[number];
+/**
+ * Canonical extension governance policy modes and registration surfaces.
+ */
+export declare const EXTENSION_POLICY_MODES: readonly ["off", "warn", "enforce"];
+export declare const EXTENSION_POLICY_SURFACES: readonly ["commands.override", "commands.handler", "hooks.beforecommand", "hooks.aftercommand", "hooks.onwrite", "hooks.onread", "hooks.onindex", "schema.flags", "schema.itemfields", "schema.itemtypes", "schema.migrations", "parser.override", "preflight.override", "services.override", "renderers.override", "importers.importer", "importers.exporter", "search.provider", "search.vectorstore"];
+export declare const EXTENSION_TRUST_MODES: readonly ["off", "warn", "enforce"];
+export declare const EXTENSION_SANDBOX_PROFILES: readonly ["none", "restricted", "strict"];
+export type ExtensionPolicyMode = (typeof EXTENSION_POLICY_MODES)[number];
+export type ExtensionPolicySurface = (typeof EXTENSION_POLICY_SURFACES)[number];
+export type ExtensionTrustMode = (typeof EXTENSION_TRUST_MODES)[number];
+export type ExtensionSandboxProfile = (typeof EXTENSION_SANDBOX_PROFILES)[number];
 /**
  * Versioned capability contract metadata emitted by runtime diagnostics.
  */
@@ -29,6 +40,6 @@ export interface ExtensionModule {
  * `export default defineExtension({ activate(api) { ... } })`
  */
 export declare function defineExtension<TModule extends ExtensionModule>(module: TModule): TModule;
-export type { AfterCommandHook, AfterCommandHookContext, BeforeCommandHook, BeforeCommandHookContext, CommandDefinition, ExtensionCommandArgumentDefinition, CommandHandler, CommandHandlerContext, CommandOverride, CommandOverrideContext, ExtensionServiceName, Exporter, ExtensionActivationResult, ExtensionApi, ExtensionCommandRegistry, ExtensionDiagnostic, ExtensionDiscoveryResult, ExtensionLoadResult, ExtensionManifest, ExtensionSearchMode, ExtensionParserRegistry, ExtensionPreflightRegistry, ExtensionRegistrationRegistry, ExtensionRendererRegistry, ExtensionServiceRegistry, FlagValueType, FlagDefinition, ImportExportContext, Importer, OnIndexHook, OnIndexHookContext, OnReadHook, OnReadHookContext, OnWriteHook, OnWriteHookContext, OutputRendererFormat, ParserOverride, ParserOverrideContext, ParserOverrideDelta, PreflightOverride, PreflightOverrideContext, PreflightOverrideDelta, PreflightRuntimeDecision, RendererOverride, RendererOverrideContext, SchemaFieldDefinition, SchemaItemTypeCommandOptionPolicyDefinition, SchemaItemTypeOptionDefinition, SchemaItemTypeDefinition, SchemaMigrationDefinition, SchemaMigrationRunContext, SchemaMigrationRunner, SearchProviderEmbedBatchContext, SearchProviderEmbedContext, SearchProviderDefinition, SearchProviderHit, SearchProviderQueryContext, SearchProviderQueryResult, ServiceOverride, ServiceOverrideContext, VectorStoreAdapterDefinition, VectorStoreDeleteContext, VectorStoreQueryContext, VectorStoreQueryHit, VectorStoreUpsertContext, VectorStoreUpsertPoint, } from "../core/extensions/loader.js";
+export type { AfterCommandHook, AfterCommandHookContext, BeforeCommandHook, BeforeCommandHookContext, CommandDefinition, ExtensionCommandArgumentDefinition, CommandHandler, CommandHandlerContext, CommandOverride, CommandOverrideContext, ExtensionServiceName, Exporter, ExtensionActivationResult, ExtensionApi, ExtensionCommandRegistry, ExtensionDiagnostic, ExtensionDiscoveryResult, ExtensionLoadResult, ExtensionManifest, ExtensionGovernancePolicy, ExtensionPolicyOverride, ExtensionProvenanceMetadata, ExtensionRuntimePermissionDeclaration, ExtensionSearchMode, ExtensionParserRegistry, ExtensionPreflightRegistry, ExtensionRegistrationRegistry, ExtensionRendererRegistry, ExtensionServiceRegistry, FlagValueType, FlagDefinition, ImportExportContext, Importer, OnIndexHook, OnIndexHookContext, OnReadHook, OnReadHookContext, OnWriteHook, OnWriteHookContext, OutputRendererFormat, ParserOverride, ParserOverrideContext, ParserOverrideDelta, PreflightOverride, PreflightOverrideContext, PreflightOverrideDelta, PreflightRuntimeDecision, RendererOverride, RendererOverrideContext, SchemaFieldDefinition, SchemaItemTypeCommandOptionPolicyDefinition, SchemaItemTypeOptionDefinition, SchemaItemTypeDefinition, SchemaMigrationDefinition, SchemaMigrationRunContext, SchemaMigrationRunner, SearchProviderEmbedBatchContext, SearchProviderEmbedContext, SearchProviderDefinition, SearchProviderHit, SearchProviderQueryContext, SearchProviderQueryResult, ServiceOverride, ServiceOverrideContext, VectorStoreAdapterDefinition, VectorStoreDeleteContext, VectorStoreQueryContext, VectorStoreQueryHit, VectorStoreUpsertContext, VectorStoreUpsertPoint, } from "../core/extensions/loader.js";
 export type { GlobalOptions } from "../core/shared/command-types.js";
 export type { ItemDocument, ItemFrontMatter, ItemStatus, ItemType, PmSettings } from "../types/index.js";

package/dist/sdk/index.js

@@ -1,4 +1,4 @@
-import { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES, KNOWN_EXTENSION_CAPABILITIES, } from "../core/extensions/loader.js";
+import { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES, KNOWN_EXTENSION_CAPABILITIES, KNOWN_EXTENSION_POLICY_MODES, KNOWN_EXTENSION_POLICY_SURFACES, KNOWN_EXTENSION_SANDBOX_PROFILES, KNOWN_EXTENSION_TRUST_MODES, } from "../core/extensions/loader.js";
 export * from "./cli-contracts.js";
 /**
  * Canonical extension capability names accepted by pm.
@@ -7,6 +7,13 @@ export * from "./cli-contracts.js";
  * `capabilities`.
  */
 export const EXTENSION_CAPABILITIES = KNOWN_EXTENSION_CAPABILITIES;
+/**
+ * Canonical extension governance policy modes and registration surfaces.
+ */
+export const EXTENSION_POLICY_MODES = KNOWN_EXTENSION_POLICY_MODES;
+export const EXTENSION_POLICY_SURFACES = KNOWN_EXTENSION_POLICY_SURFACES;
+export const EXTENSION_TRUST_MODES = KNOWN_EXTENSION_TRUST_MODES;
+export const EXTENSION_SANDBOX_PROFILES = KNOWN_EXTENSION_SANDBOX_PROFILES;
 /**
  * Versioned capability contract metadata emitted by runtime diagnostics.
  */

package/dist/sdk/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"/","sources":["sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,qCAAqC,EACrC,mCAAmC,EACnC,4BAA4B,GAG7B,MAAM,8BAA8B,CAAC;AACtC,cAAc,oBAAoB,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAGnE;;GAEG;AACH,OAAO,EAAE,6BAA6B,EAAE,qCAAqC,EAAE,mCAAmC,EAAE,CAAC;AAarH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAkC,MAAe;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import {\n  EXTENSION_CAPABILITY_CONTRACT,\n  EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  EXTENSION_CAPABILITY_LEGACY_ALIASES,\n  KNOWN_EXTENSION_CAPABILITIES,\n  type ExtensionApi,\n  type ExtensionManifest,\n} from \"../core/extensions/loader.js\";\nexport * from \"./cli-contracts.js\";\n\n/**\n * Canonical extension capability names accepted by pm.\n *\n * Extension manifests should declare one or more of these values in\n * `capabilities`.\n */\nexport const EXTENSION_CAPABILITIES = KNOWN_EXTENSION_CAPABILITIES;\nexport type ExtensionCapability = (typeof EXTENSION_CAPABILITIES)[number];\n\n/**\n * Versioned capability contract metadata emitted by runtime diagnostics.\n */\nexport { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES };\n\nexport interface ExtensionModule {\n  /**\n   * Optional in-module metadata mirror.\n   *\n   * The authoritative manifest remains on-disk `manifest.json`; this field is\n   * useful when authors want colocated metadata for tooling/tests.\n   */\n  manifest?: ExtensionManifest;\n  activate(api: ExtensionApi): void | Promise<void>;\n}\n\n/**\n * Typed identity helper for extension module exports.\n *\n * Use as:\n * `export default defineExtension({ activate(api) { ... } })`\n */\nexport function defineExtension<TModule extends ExtensionModule>(module: TModule): TModule {\n  return module;\n}\n\nexport type {\n  AfterCommandHook,\n  AfterCommandHookContext,\n  BeforeCommandHook,\n  BeforeCommandHookContext,\n  CommandDefinition,\n  ExtensionCommandArgumentDefinition,\n  CommandHandler,\n  CommandHandlerContext,\n  CommandOverride,\n  CommandOverrideContext,\n  ExtensionServiceName,\n  Exporter,\n  ExtensionActivationResult,\n  ExtensionApi,\n  ExtensionCommandRegistry,\n  ExtensionDiagnostic,\n  ExtensionDiscoveryResult,\n  ExtensionLoadResult,\n  ExtensionManifest,\n  ExtensionSearchMode,\n  ExtensionParserRegistry,\n  ExtensionPreflightRegistry,\n  ExtensionRegistrationRegistry,\n  ExtensionRendererRegistry,\n  ExtensionServiceRegistry,\n  FlagValueType,\n  FlagDefinition,\n  ImportExportContext,\n  Importer,\n  OnIndexHook,\n  OnIndexHookContext,\n  OnReadHook,\n  OnReadHookContext,\n  OnWriteHook,\n  OnWriteHookContext,\n  OutputRendererFormat,\n  ParserOverride,\n  ParserOverrideContext,\n  ParserOverrideDelta,\n  PreflightOverride,\n  PreflightOverrideContext,\n  PreflightOverrideDelta,\n  PreflightRuntimeDecision,\n  RendererOverride,\n  RendererOverrideContext,\n  SchemaFieldDefinition,\n  SchemaItemTypeCommandOptionPolicyDefinition,\n  SchemaItemTypeOptionDefinition,\n  SchemaItemTypeDefinition,\n  SchemaMigrationDefinition,\n  SchemaMigrationRunContext,\n  SchemaMigrationRunner,\n  SearchProviderEmbedBatchContext,\n  SearchProviderEmbedContext,\n  SearchProviderDefinition,\n  SearchProviderHit,\n  SearchProviderQueryContext,\n  SearchProviderQueryResult,\n  ServiceOverride,\n  ServiceOverrideContext,\n  VectorStoreAdapterDefinition,\n  VectorStoreDeleteContext,\n  VectorStoreQueryContext,\n  VectorStoreQueryHit,\n  VectorStoreUpsertContext,\n  VectorStoreUpsertPoint,\n} from \"../core/extensions/loader.js\";\n\nexport type { GlobalOptions } from \"../core/shared/command-types.js\";\nexport type { ItemDocument, ItemFrontMatter, ItemStatus, ItemType, PmSettings } from \"../types/index.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"/","sources":["sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,qCAAqC,EACrC,mCAAmC,EACnC,4BAA4B,EAC5B,4BAA4B,EAC5B,+BAA+B,EAC/B,gCAAgC,EAChC,2BAA2B,GAG5B,MAAM,8BAA8B,CAAC;AACtC,cAAc,oBAAoB,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAGnE;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AACnE,MAAM,CAAC,MAAM,yBAAyB,GAAG,+BAA+B,CAAC;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AACjE,MAAM,CAAC,MAAM,0BAA0B,GAAG,gCAAgC,CAAC;AAM3E;;GAEG;AACH,OAAO,EAAE,6BAA6B,EAAE,qCAAqC,EAAE,mCAAmC,EAAE,CAAC;AAarH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAkC,MAAe;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import {\n  EXTENSION_CAPABILITY_CONTRACT,\n  EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  EXTENSION_CAPABILITY_LEGACY_ALIASES,\n  KNOWN_EXTENSION_CAPABILITIES,\n  KNOWN_EXTENSION_POLICY_MODES,\n  KNOWN_EXTENSION_POLICY_SURFACES,\n  KNOWN_EXTENSION_SANDBOX_PROFILES,\n  KNOWN_EXTENSION_TRUST_MODES,\n  type ExtensionApi,\n  type ExtensionManifest,\n} from \"../core/extensions/loader.js\";\nexport * from \"./cli-contracts.js\";\n\n/**\n * Canonical extension capability names accepted by pm.\n *\n * Extension manifests should declare one or more of these values in\n * `capabilities`.\n */\nexport const EXTENSION_CAPABILITIES = KNOWN_EXTENSION_CAPABILITIES;\nexport type ExtensionCapability = (typeof EXTENSION_CAPABILITIES)[number];\n\n/**\n * Canonical extension governance policy modes and registration surfaces.\n */\nexport const EXTENSION_POLICY_MODES = KNOWN_EXTENSION_POLICY_MODES;\nexport const EXTENSION_POLICY_SURFACES = KNOWN_EXTENSION_POLICY_SURFACES;\nexport const EXTENSION_TRUST_MODES = KNOWN_EXTENSION_TRUST_MODES;\nexport const EXTENSION_SANDBOX_PROFILES = KNOWN_EXTENSION_SANDBOX_PROFILES;\nexport type ExtensionPolicyMode = (typeof EXTENSION_POLICY_MODES)[number];\nexport type ExtensionPolicySurface = (typeof EXTENSION_POLICY_SURFACES)[number];\nexport type ExtensionTrustMode = (typeof EXTENSION_TRUST_MODES)[number];\nexport type ExtensionSandboxProfile = (typeof EXTENSION_SANDBOX_PROFILES)[number];\n\n/**\n * Versioned capability contract metadata emitted by runtime diagnostics.\n */\nexport { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES };\n\nexport interface ExtensionModule {\n  /**\n   * Optional in-module metadata mirror.\n   *\n   * The authoritative manifest remains on-disk `manifest.json`; this field is\n   * useful when authors want colocated metadata for tooling/tests.\n   */\n  manifest?: ExtensionManifest;\n  activate(api: ExtensionApi): void | Promise<void>;\n}\n\n/**\n * Typed identity helper for extension module exports.\n *\n * Use as:\n * `export default defineExtension({ activate(api) { ... } })`\n */\nexport function defineExtension<TModule extends ExtensionModule>(module: TModule): TModule {\n  return module;\n}\n\nexport type {\n  AfterCommandHook,\n  AfterCommandHookContext,\n  BeforeCommandHook,\n  BeforeCommandHookContext,\n  CommandDefinition,\n  ExtensionCommandArgumentDefinition,\n  CommandHandler,\n  CommandHandlerContext,\n  CommandOverride,\n  CommandOverrideContext,\n  ExtensionServiceName,\n  Exporter,\n  ExtensionActivationResult,\n  ExtensionApi,\n  ExtensionCommandRegistry,\n  ExtensionDiagnostic,\n  ExtensionDiscoveryResult,\n  ExtensionLoadResult,\n  ExtensionManifest,\n  ExtensionGovernancePolicy,\n  ExtensionPolicyOverride,\n  ExtensionProvenanceMetadata,\n  ExtensionRuntimePermissionDeclaration,\n  ExtensionSearchMode,\n  ExtensionParserRegistry,\n  ExtensionPreflightRegistry,\n  ExtensionRegistrationRegistry,\n  ExtensionRendererRegistry,\n  ExtensionServiceRegistry,\n  FlagValueType,\n  FlagDefinition,\n  ImportExportContext,\n  Importer,\n  OnIndexHook,\n  OnIndexHookContext,\n  OnReadHook,\n  OnReadHookContext,\n  OnWriteHook,\n  OnWriteHookContext,\n  OutputRendererFormat,\n  ParserOverride,\n  ParserOverrideContext,\n  ParserOverrideDelta,\n  PreflightOverride,\n  PreflightOverrideContext,\n  PreflightOverrideDelta,\n  PreflightRuntimeDecision,\n  RendererOverride,\n  RendererOverrideContext,\n  SchemaFieldDefinition,\n  SchemaItemTypeCommandOptionPolicyDefinition,\n  SchemaItemTypeOptionDefinition,\n  SchemaItemTypeDefinition,\n  SchemaMigrationDefinition,\n  SchemaMigrationRunContext,\n  SchemaMigrationRunner,\n  SearchProviderEmbedBatchContext,\n  SearchProviderEmbedContext,\n  SearchProviderDefinition,\n  SearchProviderHit,\n  SearchProviderQueryContext,\n  SearchProviderQueryResult,\n  ServiceOverride,\n  ServiceOverrideContext,\n  VectorStoreAdapterDefinition,\n  VectorStoreDeleteContext,\n  VectorStoreQueryContext,\n  VectorStoreQueryHit,\n  VectorStoreUpsertContext,\n  VectorStoreUpsertPoint,\n} from \"../core/extensions/loader.js\";\n\nexport type { GlobalOptions } from \"../core/shared/command-types.js\";\nexport type { ItemDocument, ItemFrontMatter, ItemStatus, ItemType, PmSettings } from \"../types/index.js\";\n"]}

package/dist/types.d.ts

@@ -145,6 +145,10 @@ export interface RuntimeStatusDefinition {
 }
 export interface RuntimeFieldDefinition {
     key: string;
+    metadata_key?: string;
+    /**
+     * @deprecated Use metadata_key.
+     */
     front_matter_key?: string;
     cli_flag?: string;
     cli_aliases?: string[];
@@ -195,7 +199,7 @@ export interface ItemTestRunSummary {
     linked_tests?: number;
     fail_on_skipped_triggered?: boolean;
 }
-export interface ItemFrontMatter {
+export interface ItemMetadata {
     id: string;
     title: string;
     description: string;
@@ -258,8 +262,12 @@ export interface ItemFrontMatter {
     close_reason?: string;
     [key: string]: unknown;
 }
+/**
+ * @deprecated Use ItemMetadata.
+ */
+export type ItemFrontMatter = ItemMetadata;
 export interface ItemDocument {
-    front_matter: ItemFrontMatter;
+    metadata: ItemMetadata;
     body: string;
 }
 export interface HistoryPatchOp {
@@ -306,6 +314,46 @@ export interface GovernanceSettings {
     metadata_profile: ValidateMetadataProfile;
     force_required_for_stale_lock: boolean;
 }
+export type ExtensionPolicyMode = "off" | "warn" | "enforce";
+export type ExtensionTrustMode = "off" | "warn" | "enforce";
+export type ExtensionSandboxProfile = "none" | "restricted" | "strict";
+export interface ExtensionPolicyOverrideSettings {
+    name: string;
+    disabled?: boolean;
+    require_trusted?: boolean;
+    require_provenance?: boolean;
+    sandbox_profile?: ExtensionSandboxProfile;
+    allowed_capabilities?: string[];
+    blocked_capabilities?: string[];
+    allowed_surfaces?: string[];
+    blocked_surfaces?: string[];
+    allowed_commands?: string[];
+    blocked_commands?: string[];
+    allowed_actions?: string[];
+    blocked_actions?: string[];
+    allowed_services?: string[];
+    blocked_services?: string[];
+}
+export interface ExtensionPolicySettings {
+    mode: ExtensionPolicyMode;
+    trust_mode: ExtensionTrustMode;
+    require_provenance: boolean;
+    trusted_extensions: string[];
+    default_sandbox_profile: ExtensionSandboxProfile;
+    allowed_extensions: string[];
+    blocked_extensions: string[];
+    allowed_capabilities: string[];
+    blocked_capabilities: string[];
+    allowed_surfaces: string[];
+    blocked_surfaces: string[];
+    allowed_commands: string[];
+    blocked_commands: string[];
+    allowed_actions: string[];
+    blocked_actions: string[];
+    allowed_services: string[];
+    blocked_services: string[];
+    extension_overrides: ExtensionPolicyOverrideSettings[];
+}
 export interface PmSettings {
     version: number;
     id_prefix: string;
@@ -352,6 +400,7 @@ export interface PmSettings {
     extensions: {
         enabled: string[];
         disabled: string[];
+        policy: ExtensionPolicySettings;
     };
     search: {
         score_threshold: number;

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"/","sources":["types.ts"],"names":[],"mappings":"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","sourcesContent":["export const BUILTIN_ITEM_TYPE_VALUES = [\n  \"Epic\",\n  \"Feature\",\n  \"Task\",\n  \"Chore\",\n  \"Issue\",\n  \"Decision\",\n  \"Event\",\n  \"Reminder\",\n  \"Milestone\",\n  \"Meeting\",\n] as const;\nexport const ITEM_TYPE_VALUES = BUILTIN_ITEM_TYPE_VALUES;\nexport type BuiltinItemType = (typeof BUILTIN_ITEM_TYPE_VALUES)[number];\nexport type ItemType = string;\n\nexport const STATUS_VALUES = [\n  \"draft\",\n  \"open\",\n  \"in_progress\",\n  \"blocked\",\n  \"closed\",\n  \"canceled\",\n] as const;\nexport type ItemStatus = string;\n\nexport const RUNTIME_STATUS_ROLE_VALUES = [\n  \"draft\",\n  \"active\",\n  \"blocked\",\n  \"terminal\",\n  \"terminal_done\",\n  \"terminal_canceled\",\n  \"default_open\",\n  \"default_close\",\n  \"default_cancel\",\n] as const;\nexport type RuntimeStatusRole = (typeof RUNTIME_STATUS_ROLE_VALUES)[number];\n\nexport const RUNTIME_FIELD_TYPE_VALUES = [\"string\", \"number\", \"boolean\", \"string_array\"] as const;\nexport type RuntimeFieldType = (typeof RUNTIME_FIELD_TYPE_VALUES)[number];\n\nexport const RUNTIME_FIELD_COMMAND_VALUES = [\"create\", \"update\", \"update_many\", \"list\", \"search\", \"calendar\", \"context\"] as const;\nexport type RuntimeFieldCommand = (typeof RUNTIME_FIELD_COMMAND_VALUES)[number];\n\nexport const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES = [\"allow\", \"warn\", \"reject\"] as const;\nexport type RuntimeUnknownFieldPolicy = (typeof RUNTIME_UNKNOWN_FIELD_POLICY_VALUES)[number];\n\nexport const DEPENDENCY_KIND_VALUES = [\n  \"blocks\",\n  \"parent\",\n  \"child\",\n  \"parent_child\",\n  \"child_of\",\n  \"related\",\n  \"related_to\",\n  \"discovered_from\",\n  \"blocked_by\",\n  \"incident_from\",\n  \"epic\",\n  \"supersedes\",\n  \"task\",\n] as const;\nexport type DependencyKind = (typeof DEPENDENCY_KIND_VALUES)[number];\n\nexport const SCOPE_VALUES = [\"project\", \"global\"] as const;\nexport type LinkScope = (typeof SCOPE_VALUES)[number];\n\nexport const RISK_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\nexport type RiskLevel = (typeof RISK_VALUES)[number];\n\nexport const ISSUE_SEVERITY_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\nexport type IssueSeverity = (typeof ISSUE_SEVERITY_VALUES)[number];\n\nexport const CONFIDENCE_TEXT_VALUES = [\"low\", \"medium\", \"high\"] as const;\nexport type ConfidenceTextLevel = (typeof CONFIDENCE_TEXT_VALUES)[number];\nexport type ConfidenceValue = number | ConfidenceTextLevel;\n\nexport const ITEM_FORMAT_VALUES = [\"toon\", \"json_markdown\"] as const;\nexport type ItemFormat = (typeof ITEM_FORMAT_VALUES)[number];\n\nexport const SPRINT_RELEASE_FORMAT_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\nexport type SprintReleaseFormatPolicy = (typeof SPRINT_RELEASE_FORMAT_POLICY_VALUES)[number];\nexport const PARENT_REFERENCE_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\nexport type ParentReferencePolicy = (typeof PARENT_REFERENCE_POLICY_VALUES)[number];\nexport const VALIDATE_METADATA_PROFILE_VALUES = [\"core\", \"strict\", \"custom\"] as const;\nexport type ValidateMetadataProfile = (typeof VALIDATE_METADATA_PROFILE_VALUES)[number];\nexport const GOVERNANCE_PRESET_VALUES = [\"minimal\", \"default\", \"strict\", \"custom\"] as const;\nexport type GovernancePreset = (typeof GOVERNANCE_PRESET_VALUES)[number];\nexport const GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES = [\"none\", \"warn\", \"strict\"] as const;\nexport type GovernanceOwnershipEnforcement = (typeof GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES)[number];\nexport const GOVERNANCE_CREATE_MODE_DEFAULT_VALUES = [\"progressive\", \"strict\"] as const;\nexport type GovernanceCreateModeDefault = (typeof GOVERNANCE_CREATE_MODE_DEFAULT_VALUES)[number];\nexport const GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES = [\"off\", \"warn\", \"strict\"] as const;\nexport type GovernanceCloseValidationDefault = (typeof GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES)[number];\nexport const VALIDATE_METADATA_REQUIRED_FIELD_VALUES = [\n  \"author\",\n  \"acceptance_criteria\",\n  \"estimated_minutes\",\n  \"close_reason\",\n  \"reviewer\",\n  \"risk\",\n  \"confidence\",\n  \"sprint\",\n  \"release\",\n] as const;\nexport type ValidateMetadataRequiredField = (typeof VALIDATE_METADATA_REQUIRED_FIELD_VALUES)[number];\n\nexport const RECURRENCE_FREQUENCY_VALUES = [\"daily\", \"weekly\", \"monthly\", \"yearly\"] as const;\nexport type RecurrenceFrequency = (typeof RECURRENCE_FREQUENCY_VALUES)[number];\n\nexport const RECURRENCE_WEEKDAY_VALUES = [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\", \"sat\", \"sun\"] as const;\nexport type RecurrenceWeekday = (typeof RECURRENCE_WEEKDAY_VALUES)[number];\n\nexport interface Dependency {\n  id: string;\n  kind: DependencyKind;\n  created_at: string;\n  author?: string;\n  source_kind?: string;\n}\n\nexport interface Comment {\n  created_at: string;\n  author: string;\n  text: string;\n}\n\nexport interface LogNote {\n  created_at: string;\n  author: string;\n  text: string;\n}\n\nexport interface LinkedFile {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n}\n\nexport interface LinkedTest {\n  command?: string;\n  path?: string;\n  scope: LinkScope;\n  timeout_seconds?: number;\n  pm_context_mode?: \"schema\" | \"tracker\" | \"auto\";\n  env_set?: Record<string, string>;\n  env_clear?: string[];\n  shared_host_safe?: boolean;\n  assert_stdout_contains?: string[];\n  assert_stdout_regex?: string[];\n  assert_stderr_contains?: string[];\n  assert_stderr_regex?: string[];\n  assert_stdout_min_lines?: number;\n  assert_json_field_equals?: Record<string, string>;\n  assert_json_field_gte?: Record<string, number>;\n  note?: string;\n}\n\nexport interface LinkedDoc {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n}\n\nexport interface Reminder {\n  at: string;\n  text: string;\n}\n\nexport interface RecurrenceRule {\n  freq: RecurrenceFrequency;\n  interval?: number;\n  count?: number;\n  until?: string;\n  by_weekday?: RecurrenceWeekday[];\n  by_month_day?: number[];\n  exdates?: string[];\n}\n\nexport interface CalendarEvent {\n  start_at: string;\n  end_at?: string;\n  title?: string;\n  description?: string;\n  location?: string;\n  all_day?: boolean;\n  timezone?: string;\n  recurrence?: RecurrenceRule;\n}\n\nexport interface ItemTypeOptionDefinition {\n  key: string;\n  values: string[];\n  required?: boolean;\n  aliases?: string[];\n  description?: string;\n}\n\nexport interface ItemTypeCommandOptionPolicy {\n  command: \"create\" | \"update\";\n  option: string;\n  required?: boolean;\n  visible?: boolean;\n  enabled?: boolean;\n}\n\nexport interface ItemTypeDefinition {\n  name: string;\n  folder?: string;\n  aliases?: string[];\n  required_create_fields?: string[];\n  required_create_repeatables?: string[];\n  options?: ItemTypeOptionDefinition[];\n  command_option_policies?: ItemTypeCommandOptionPolicy[];\n}\n\nexport interface RuntimeStatusDefinition {\n  id: string;\n  aliases?: string[];\n  roles?: RuntimeStatusRole[];\n  description?: string;\n  order?: number;\n}\n\nexport interface RuntimeFieldDefinition {\n  key: string;\n  front_matter_key?: string;\n  cli_flag?: string;\n  cli_aliases?: string[];\n  description?: string;\n  type?: RuntimeFieldType;\n  commands?: RuntimeFieldCommand[];\n  repeatable?: boolean;\n  required?: boolean;\n  required_on_create?: boolean;\n  required_types?: string[];\n  allow_unset?: boolean;\n}\n\nexport interface RuntimeWorkflowDefinition {\n  draft_status?: string;\n  open_status?: string;\n  in_progress_status?: string;\n  blocked_status?: string;\n  close_status?: string;\n  canceled_status?: string;\n}\n\nexport interface RuntimeSchemaFileConfig {\n  types?: string;\n  statuses?: string;\n  fields?: string;\n  workflows?: string;\n}\n\nexport interface RuntimeSchemaSettings {\n  version: number;\n  files: RuntimeSchemaFileConfig;\n  statuses: RuntimeStatusDefinition[];\n  fields: RuntimeFieldDefinition[];\n  workflow: RuntimeWorkflowDefinition;\n  unknown_field_policy: RuntimeUnknownFieldPolicy;\n}\n\nexport interface ItemTestRunSummary {\n  run_id: string;\n  kind: \"test\" | \"test-all\";\n  status: \"passed\" | \"failed\" | \"stopped\" | \"canceled\";\n  started_at: string;\n  finished_at: string;\n  recorded_at: string;\n  attempt?: number;\n  resumed_from?: string;\n  passed: number;\n  failed: number;\n  skipped: number;\n  items?: number;\n  linked_tests?: number;\n  fail_on_skipped_triggered?: boolean;\n}\n\nexport interface ItemFrontMatter {\n  id: string;\n  title: string;\n  description: string;\n  type: ItemType;\n  source_type?: string;\n  type_options?: Record<string, string>;\n  status: ItemStatus;\n  priority: 0 | 1 | 2 | 3 | 4;\n  tags: string[];\n  created_at: string;\n  updated_at: string;\n  deadline?: string;\n  reminders?: Reminder[];\n  events?: CalendarEvent[];\n  closed_at?: string;\n  assignee?: string;\n  source_owner?: string;\n  author?: string;\n  estimated_minutes?: number;\n  acceptance_criteria?: string;\n  design?: string;\n  external_ref?: string;\n  definition_of_ready?: string;\n  order?: number;\n  goal?: string;\n  objective?: string;\n  value?: string;\n  impact?: string;\n  outcome?: string;\n  why_now?: string;\n  parent?: string;\n  reviewer?: string;\n  risk?: \"low\" | \"medium\" | \"high\" | \"critical\";\n  confidence?: ConfidenceValue;\n  sprint?: string;\n  release?: string;\n  blocked_by?: string;\n  blocked_reason?: string;\n  unblock_note?: string;\n  reporter?: string;\n  severity?: IssueSeverity;\n  environment?: string;\n  repro_steps?: string;\n  resolution?: string;\n  expected_result?: string;\n  actual_result?: string;\n  affected_version?: string;\n  fixed_version?: string;\n  component?: string;\n  regression?: boolean;\n  customer_impact?: string;\n  dependencies?: Dependency[];\n  comments?: Comment[];\n  notes?: LogNote[];\n  learnings?: LogNote[];\n  files?: LinkedFile[];\n  tests?: LinkedTest[];\n  test_runs?: ItemTestRunSummary[];\n  docs?: LinkedDoc[];\n  close_reason?: string;\n  [key: string]: unknown;\n}\n\nexport interface ItemDocument {\n  front_matter: ItemFrontMatter;\n  body: string;\n}\n\nexport interface HistoryPatchOp {\n  op: \"add\" | \"remove\" | \"replace\" | \"move\" | \"copy\" | \"test\";\n  path: string;\n  from?: string;\n  value?: unknown;\n}\n\nexport interface HistoryEntry {\n  ts: string;\n  author: string;\n  op: string;\n  patch: HistoryPatchOp[];\n  before_hash: string;\n  after_hash: string;\n  message?: string;\n}\n\nexport const CONTEXT_DEPTH_VALUES = [\"brief\", \"standard\", \"deep\"] as const;\nexport type ContextDepth = (typeof CONTEXT_DEPTH_VALUES)[number];\n\nexport const CONTEXT_SECTION_VALUES = [\n  \"hierarchy\",\n  \"activity\",\n  \"progress\",\n  \"blockers\",\n  \"files\",\n  \"workload\",\n  \"staleness\",\n  \"tests\",\n] as const;\nexport type ContextSectionName = (typeof CONTEXT_SECTION_VALUES)[number];\n\nexport interface ContextSectionSettings {\n  hierarchy: boolean;\n  activity: boolean;\n  progress: boolean;\n  blockers: boolean;\n  files: boolean;\n  workload: boolean;\n  staleness: boolean;\n  tests: boolean;\n}\n\nexport interface ContextSettings {\n  default_depth: ContextDepth;\n  activity_limit: number;\n  stale_threshold_days: number;\n  sections: ContextSectionSettings;\n}\n\nexport interface GovernanceSettings {\n  preset: GovernancePreset;\n  ownership_enforcement: GovernanceOwnershipEnforcement;\n  create_mode_default: GovernanceCreateModeDefault;\n  close_validation_default: GovernanceCloseValidationDefault;\n  parent_reference: ParentReferencePolicy;\n  metadata_profile: ValidateMetadataProfile;\n  force_required_for_stale_lock: boolean;\n}\n\nexport interface PmSettings {\n  version: number;\n  id_prefix: string;\n  author_default: string;\n  item_format: ItemFormat;\n  locks: {\n    ttl_seconds: number;\n  };\n  output: {\n    default_format: \"toon\" | \"json\";\n  };\n  history: {\n    missing_stream: \"auto_create\" | \"strict_error\";\n  };\n  validation: {\n    sprint_release_format: SprintReleaseFormatPolicy;\n    parent_reference: ParentReferencePolicy;\n    metadata_profile: ValidateMetadataProfile;\n    metadata_required_fields: ValidateMetadataRequiredField[];\n    lifecycle_stale_blocker_reason_patterns: string[];\n    lifecycle_closure_like_blocked_reason_patterns: string[];\n    lifecycle_closure_like_resolution_patterns: string[];\n    lifecycle_closure_like_actual_result_patterns: string[];\n  };\n  governance: GovernanceSettings;\n  workflow: {\n    definition_of_done: string[];\n  };\n  testing: {\n    record_results_to_items: boolean;\n  };\n  telemetry: {\n    enabled: boolean;\n    first_run_prompt_completed: boolean;\n    capture_level: \"minimal\" | \"redacted\" | \"max\";\n    endpoint: string;\n    installation_id: string;\n    retention_days: number;\n  };\n  item_types: {\n    definitions: ItemTypeDefinition[];\n  };\n  schema: RuntimeSchemaSettings;\n  extensions: {\n    enabled: string[];\n    disabled: string[];\n  };\n  search: {\n    score_threshold: number;\n    hybrid_semantic_weight: number;\n    max_results: number;\n    embedding_model: string;\n    embedding_batch_size: number;\n    scanner_max_batch_retries: number;\n    provider?: string;\n    tuning?: {\n      title_exact_bonus?: number;\n      title_weight?: number;\n      description_weight?: number;\n      tags_weight?: number;\n      status_weight?: number;\n      body_weight?: number;\n      comments_weight?: number;\n      notes_weight?: number;\n      learnings_weight?: number;\n      dependencies_weight?: number;\n      linked_content_weight?: number;\n    };\n  };\n  providers: {\n    openai: {\n      base_url: string;\n      api_key: string;\n      model: string;\n    };\n    ollama: {\n      base_url: string;\n      model: string;\n    };\n  };\n  context: ContextSettings;\n  vector_store: {\n    adapter?: string;\n    qdrant: {\n      url: string;\n      api_key: string;\n    };\n    lancedb: {\n      path: string;\n    };\n  };\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"/","sources":["types.ts"],"names":[],"mappings":"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","sourcesContent":["export const BUILTIN_ITEM_TYPE_VALUES = [\n  \"Epic\",\n  \"Feature\",\n  \"Task\",\n  \"Chore\",\n  \"Issue\",\n  \"Decision\",\n  \"Event\",\n  \"Reminder\",\n  \"Milestone\",\n  \"Meeting\",\n] as const;\nexport const ITEM_TYPE_VALUES = BUILTIN_ITEM_TYPE_VALUES;\nexport type BuiltinItemType = (typeof BUILTIN_ITEM_TYPE_VALUES)[number];\nexport type ItemType = string;\n\nexport const STATUS_VALUES = [\n  \"draft\",\n  \"open\",\n  \"in_progress\",\n  \"blocked\",\n  \"closed\",\n  \"canceled\",\n] as const;\nexport type ItemStatus = string;\n\nexport const RUNTIME_STATUS_ROLE_VALUES = [\n  \"draft\",\n  \"active\",\n  \"blocked\",\n  \"terminal\",\n  \"terminal_done\",\n  \"terminal_canceled\",\n  \"default_open\",\n  \"default_close\",\n  \"default_cancel\",\n] as const;\nexport type RuntimeStatusRole = (typeof RUNTIME_STATUS_ROLE_VALUES)[number];\n\nexport const RUNTIME_FIELD_TYPE_VALUES = [\"string\", \"number\", \"boolean\", \"string_array\"] as const;\nexport type RuntimeFieldType = (typeof RUNTIME_FIELD_TYPE_VALUES)[number];\n\nexport const RUNTIME_FIELD_COMMAND_VALUES = [\"create\", \"update\", \"update_many\", \"list\", \"search\", \"calendar\", \"context\"] as const;\nexport type RuntimeFieldCommand = (typeof RUNTIME_FIELD_COMMAND_VALUES)[number];\n\nexport const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES = [\"allow\", \"warn\", \"reject\"] as const;\nexport type RuntimeUnknownFieldPolicy = (typeof RUNTIME_UNKNOWN_FIELD_POLICY_VALUES)[number];\n\nexport const DEPENDENCY_KIND_VALUES = [\n  \"blocks\",\n  \"parent\",\n  \"child\",\n  \"parent_child\",\n  \"child_of\",\n  \"related\",\n  \"related_to\",\n  \"discovered_from\",\n  \"blocked_by\",\n  \"incident_from\",\n  \"epic\",\n  \"supersedes\",\n  \"task\",\n] as const;\nexport type DependencyKind = (typeof DEPENDENCY_KIND_VALUES)[number];\n\nexport const SCOPE_VALUES = [\"project\", \"global\"] as const;\nexport type LinkScope = (typeof SCOPE_VALUES)[number];\n\nexport const RISK_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\nexport type RiskLevel = (typeof RISK_VALUES)[number];\n\nexport const ISSUE_SEVERITY_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\nexport type IssueSeverity = (typeof ISSUE_SEVERITY_VALUES)[number];\n\nexport const CONFIDENCE_TEXT_VALUES = [\"low\", \"medium\", \"high\"] as const;\nexport type ConfidenceTextLevel = (typeof CONFIDENCE_TEXT_VALUES)[number];\nexport type ConfidenceValue = number | ConfidenceTextLevel;\n\nexport const ITEM_FORMAT_VALUES = [\"toon\", \"json_markdown\"] as const;\nexport type ItemFormat = (typeof ITEM_FORMAT_VALUES)[number];\n\nexport const SPRINT_RELEASE_FORMAT_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\nexport type SprintReleaseFormatPolicy = (typeof SPRINT_RELEASE_FORMAT_POLICY_VALUES)[number];\nexport const PARENT_REFERENCE_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\nexport type ParentReferencePolicy = (typeof PARENT_REFERENCE_POLICY_VALUES)[number];\nexport const VALIDATE_METADATA_PROFILE_VALUES = [\"core\", \"strict\", \"custom\"] as const;\nexport type ValidateMetadataProfile = (typeof VALIDATE_METADATA_PROFILE_VALUES)[number];\nexport const GOVERNANCE_PRESET_VALUES = [\"minimal\", \"default\", \"strict\", \"custom\"] as const;\nexport type GovernancePreset = (typeof GOVERNANCE_PRESET_VALUES)[number];\nexport const GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES = [\"none\", \"warn\", \"strict\"] as const;\nexport type GovernanceOwnershipEnforcement = (typeof GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES)[number];\nexport const GOVERNANCE_CREATE_MODE_DEFAULT_VALUES = [\"progressive\", \"strict\"] as const;\nexport type GovernanceCreateModeDefault = (typeof GOVERNANCE_CREATE_MODE_DEFAULT_VALUES)[number];\nexport const GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES = [\"off\", \"warn\", \"strict\"] as const;\nexport type GovernanceCloseValidationDefault = (typeof GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES)[number];\nexport const VALIDATE_METADATA_REQUIRED_FIELD_VALUES = [\n  \"author\",\n  \"acceptance_criteria\",\n  \"estimated_minutes\",\n  \"close_reason\",\n  \"reviewer\",\n  \"risk\",\n  \"confidence\",\n  \"sprint\",\n  \"release\",\n] as const;\nexport type ValidateMetadataRequiredField = (typeof VALIDATE_METADATA_REQUIRED_FIELD_VALUES)[number];\n\nexport const RECURRENCE_FREQUENCY_VALUES = [\"daily\", \"weekly\", \"monthly\", \"yearly\"] as const;\nexport type RecurrenceFrequency = (typeof RECURRENCE_FREQUENCY_VALUES)[number];\n\nexport const RECURRENCE_WEEKDAY_VALUES = [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\", \"sat\", \"sun\"] as const;\nexport type RecurrenceWeekday = (typeof RECURRENCE_WEEKDAY_VALUES)[number];\n\nexport interface Dependency {\n  id: string;\n  kind: DependencyKind;\n  created_at: string;\n  author?: string;\n  source_kind?: string;\n}\n\nexport interface Comment {\n  created_at: string;\n  author: string;\n  text: string;\n}\n\nexport interface LogNote {\n  created_at: string;\n  author: string;\n  text: string;\n}\n\nexport interface LinkedFile {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n}\n\nexport interface LinkedTest {\n  command?: string;\n  path?: string;\n  scope: LinkScope;\n  timeout_seconds?: number;\n  pm_context_mode?: \"schema\" | \"tracker\" | \"auto\";\n  env_set?: Record<string, string>;\n  env_clear?: string[];\n  shared_host_safe?: boolean;\n  assert_stdout_contains?: string[];\n  assert_stdout_regex?: string[];\n  assert_stderr_contains?: string[];\n  assert_stderr_regex?: string[];\n  assert_stdout_min_lines?: number;\n  assert_json_field_equals?: Record<string, string>;\n  assert_json_field_gte?: Record<string, number>;\n  note?: string;\n}\n\nexport interface LinkedDoc {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n}\n\nexport interface Reminder {\n  at: string;\n  text: string;\n}\n\nexport interface RecurrenceRule {\n  freq: RecurrenceFrequency;\n  interval?: number;\n  count?: number;\n  until?: string;\n  by_weekday?: RecurrenceWeekday[];\n  by_month_day?: number[];\n  exdates?: string[];\n}\n\nexport interface CalendarEvent {\n  start_at: string;\n  end_at?: string;\n  title?: string;\n  description?: string;\n  location?: string;\n  all_day?: boolean;\n  timezone?: string;\n  recurrence?: RecurrenceRule;\n}\n\nexport interface ItemTypeOptionDefinition {\n  key: string;\n  values: string[];\n  required?: boolean;\n  aliases?: string[];\n  description?: string;\n}\n\nexport interface ItemTypeCommandOptionPolicy {\n  command: \"create\" | \"update\";\n  option: string;\n  required?: boolean;\n  visible?: boolean;\n  enabled?: boolean;\n}\n\nexport interface ItemTypeDefinition {\n  name: string;\n  folder?: string;\n  aliases?: string[];\n  required_create_fields?: string[];\n  required_create_repeatables?: string[];\n  options?: ItemTypeOptionDefinition[];\n  command_option_policies?: ItemTypeCommandOptionPolicy[];\n}\n\nexport interface RuntimeStatusDefinition {\n  id: string;\n  aliases?: string[];\n  roles?: RuntimeStatusRole[];\n  description?: string;\n  order?: number;\n}\n\nexport interface RuntimeFieldDefinition {\n  key: string;\n  metadata_key?: string;\n  /**\n   * @deprecated Use metadata_key.\n   */\n  front_matter_key?: string;\n  cli_flag?: string;\n  cli_aliases?: string[];\n  description?: string;\n  type?: RuntimeFieldType;\n  commands?: RuntimeFieldCommand[];\n  repeatable?: boolean;\n  required?: boolean;\n  required_on_create?: boolean;\n  required_types?: string[];\n  allow_unset?: boolean;\n}\n\nexport interface RuntimeWorkflowDefinition {\n  draft_status?: string;\n  open_status?: string;\n  in_progress_status?: string;\n  blocked_status?: string;\n  close_status?: string;\n  canceled_status?: string;\n}\n\nexport interface RuntimeSchemaFileConfig {\n  types?: string;\n  statuses?: string;\n  fields?: string;\n  workflows?: string;\n}\n\nexport interface RuntimeSchemaSettings {\n  version: number;\n  files: RuntimeSchemaFileConfig;\n  statuses: RuntimeStatusDefinition[];\n  fields: RuntimeFieldDefinition[];\n  workflow: RuntimeWorkflowDefinition;\n  unknown_field_policy: RuntimeUnknownFieldPolicy;\n}\n\nexport interface ItemTestRunSummary {\n  run_id: string;\n  kind: \"test\" | \"test-all\";\n  status: \"passed\" | \"failed\" | \"stopped\" | \"canceled\";\n  started_at: string;\n  finished_at: string;\n  recorded_at: string;\n  attempt?: number;\n  resumed_from?: string;\n  passed: number;\n  failed: number;\n  skipped: number;\n  items?: number;\n  linked_tests?: number;\n  fail_on_skipped_triggered?: boolean;\n}\n\nexport interface ItemMetadata {\n  id: string;\n  title: string;\n  description: string;\n  type: ItemType;\n  source_type?: string;\n  type_options?: Record<string, string>;\n  status: ItemStatus;\n  priority: 0 | 1 | 2 | 3 | 4;\n  tags: string[];\n  created_at: string;\n  updated_at: string;\n  deadline?: string;\n  reminders?: Reminder[];\n  events?: CalendarEvent[];\n  closed_at?: string;\n  assignee?: string;\n  source_owner?: string;\n  author?: string;\n  estimated_minutes?: number;\n  acceptance_criteria?: string;\n  design?: string;\n  external_ref?: string;\n  definition_of_ready?: string;\n  order?: number;\n  goal?: string;\n  objective?: string;\n  value?: string;\n  impact?: string;\n  outcome?: string;\n  why_now?: string;\n  parent?: string;\n  reviewer?: string;\n  risk?: \"low\" | \"medium\" | \"high\" | \"critical\";\n  confidence?: ConfidenceValue;\n  sprint?: string;\n  release?: string;\n  blocked_by?: string;\n  blocked_reason?: string;\n  unblock_note?: string;\n  reporter?: string;\n  severity?: IssueSeverity;\n  environment?: string;\n  repro_steps?: string;\n  resolution?: string;\n  expected_result?: string;\n  actual_result?: string;\n  affected_version?: string;\n  fixed_version?: string;\n  component?: string;\n  regression?: boolean;\n  customer_impact?: string;\n  dependencies?: Dependency[];\n  comments?: Comment[];\n  notes?: LogNote[];\n  learnings?: LogNote[];\n  files?: LinkedFile[];\n  tests?: LinkedTest[];\n  test_runs?: ItemTestRunSummary[];\n  docs?: LinkedDoc[];\n  close_reason?: string;\n  [key: string]: unknown;\n}\n\n/**\n * @deprecated Use ItemMetadata.\n */\nexport type ItemFrontMatter = ItemMetadata;\n\nexport interface ItemDocument {\n  metadata: ItemMetadata;\n  body: string;\n}\n\nexport interface HistoryPatchOp {\n  op: \"add\" | \"remove\" | \"replace\" | \"move\" | \"copy\" | \"test\";\n  path: string;\n  from?: string;\n  value?: unknown;\n}\n\nexport interface HistoryEntry {\n  ts: string;\n  author: string;\n  op: string;\n  patch: HistoryPatchOp[];\n  before_hash: string;\n  after_hash: string;\n  message?: string;\n}\n\nexport const CONTEXT_DEPTH_VALUES = [\"brief\", \"standard\", \"deep\"] as const;\nexport type ContextDepth = (typeof CONTEXT_DEPTH_VALUES)[number];\n\nexport const CONTEXT_SECTION_VALUES = [\n  \"hierarchy\",\n  \"activity\",\n  \"progress\",\n  \"blockers\",\n  \"files\",\n  \"workload\",\n  \"staleness\",\n  \"tests\",\n] as const;\nexport type ContextSectionName = (typeof CONTEXT_SECTION_VALUES)[number];\n\nexport interface ContextSectionSettings {\n  hierarchy: boolean;\n  activity: boolean;\n  progress: boolean;\n  blockers: boolean;\n  files: boolean;\n  workload: boolean;\n  staleness: boolean;\n  tests: boolean;\n}\n\nexport interface ContextSettings {\n  default_depth: ContextDepth;\n  activity_limit: number;\n  stale_threshold_days: number;\n  sections: ContextSectionSettings;\n}\n\nexport interface GovernanceSettings {\n  preset: GovernancePreset;\n  ownership_enforcement: GovernanceOwnershipEnforcement;\n  create_mode_default: GovernanceCreateModeDefault;\n  close_validation_default: GovernanceCloseValidationDefault;\n  parent_reference: ParentReferencePolicy;\n  metadata_profile: ValidateMetadataProfile;\n  force_required_for_stale_lock: boolean;\n}\n\nexport type ExtensionPolicyMode = \"off\" | \"warn\" | \"enforce\";\nexport type ExtensionTrustMode = \"off\" | \"warn\" | \"enforce\";\nexport type ExtensionSandboxProfile = \"none\" | \"restricted\" | \"strict\";\n\nexport interface ExtensionPolicyOverrideSettings {\n  name: string;\n  disabled?: boolean;\n  require_trusted?: boolean;\n  require_provenance?: boolean;\n  sandbox_profile?: ExtensionSandboxProfile;\n  allowed_capabilities?: string[];\n  blocked_capabilities?: string[];\n  allowed_surfaces?: string[];\n  blocked_surfaces?: string[];\n  allowed_commands?: string[];\n  blocked_commands?: string[];\n  allowed_actions?: string[];\n  blocked_actions?: string[];\n  allowed_services?: string[];\n  blocked_services?: string[];\n}\n\nexport interface ExtensionPolicySettings {\n  mode: ExtensionPolicyMode;\n  trust_mode: ExtensionTrustMode;\n  require_provenance: boolean;\n  trusted_extensions: string[];\n  default_sandbox_profile: ExtensionSandboxProfile;\n  allowed_extensions: string[];\n  blocked_extensions: string[];\n  allowed_capabilities: string[];\n  blocked_capabilities: string[];\n  allowed_surfaces: string[];\n  blocked_surfaces: string[];\n  allowed_commands: string[];\n  blocked_commands: string[];\n  allowed_actions: string[];\n  blocked_actions: string[];\n  allowed_services: string[];\n  blocked_services: string[];\n  extension_overrides: ExtensionPolicyOverrideSettings[];\n}\n\nexport interface PmSettings {\n  version: number;\n  id_prefix: string;\n  author_default: string;\n  item_format: ItemFormat;\n  locks: {\n    ttl_seconds: number;\n  };\n  output: {\n    default_format: \"toon\" | \"json\";\n  };\n  history: {\n    missing_stream: \"auto_create\" | \"strict_error\";\n  };\n  validation: {\n    sprint_release_format: SprintReleaseFormatPolicy;\n    parent_reference: ParentReferencePolicy;\n    metadata_profile: ValidateMetadataProfile;\n    metadata_required_fields: ValidateMetadataRequiredField[];\n    lifecycle_stale_blocker_reason_patterns: string[];\n    lifecycle_closure_like_blocked_reason_patterns: string[];\n    lifecycle_closure_like_resolution_patterns: string[];\n    lifecycle_closure_like_actual_result_patterns: string[];\n  };\n  governance: GovernanceSettings;\n  workflow: {\n    definition_of_done: string[];\n  };\n  testing: {\n    record_results_to_items: boolean;\n  };\n  telemetry: {\n    enabled: boolean;\n    first_run_prompt_completed: boolean;\n    capture_level: \"minimal\" | \"redacted\" | \"max\";\n    endpoint: string;\n    installation_id: string;\n    retention_days: number;\n  };\n  item_types: {\n    definitions: ItemTypeDefinition[];\n  };\n  schema: RuntimeSchemaSettings;\n  extensions: {\n    enabled: string[];\n    disabled: string[];\n    policy: ExtensionPolicySettings;\n  };\n  search: {\n    score_threshold: number;\n    hybrid_semantic_weight: number;\n    max_results: number;\n    embedding_model: string;\n    embedding_batch_size: number;\n    scanner_max_batch_retries: number;\n    provider?: string;\n    tuning?: {\n      title_exact_bonus?: number;\n      title_weight?: number;\n      description_weight?: number;\n      tags_weight?: number;\n      status_weight?: number;\n      body_weight?: number;\n      comments_weight?: number;\n      notes_weight?: number;\n      learnings_weight?: number;\n      dependencies_weight?: number;\n      linked_content_weight?: number;\n    };\n  };\n  providers: {\n    openai: {\n      base_url: string;\n      api_key: string;\n      model: string;\n    };\n    ollama: {\n      base_url: string;\n      model: string;\n    };\n  };\n  context: ContextSettings;\n  vector_store: {\n    adapter?: string;\n    qdrant: {\n      url: string;\n      api_key: string;\n    };\n    lancedb: {\n      path: string;\n    };\n  };\n}\n"]}

package/docs/AGENT_GUIDE.md

@@ -11,6 +11,7 @@ pm context --limit 10
 pm search "<request keywords>" --limit 10
 pm list-open --limit 20
 pm list-in-progress --limit 20
+pm guide workflows
 ```
 
 If a relevant item exists, reuse it. If not, create a parent lineage, then create and claim the child implementation item.
@@ -94,9 +95,22 @@ pm release <item-id>
 | Low-noise machine contracts | `pm contracts --command <command> --flags-only --json` |
 | Timeline | `pm activity --id <id> --limit 20` |
 | Dependencies | `pm deps <id> --format tree` |
+| Local docs routing | `pm guide <topic>` |
 
 Default TOON output is preferred for model-readable loops. Use `--json` only when strict parsing is needed.
 
+## Guide Routing for Agents
+
+Use `pm guide` as the local progressive-disclosure router before opening large documents:
+
+```bash
+pm guide
+pm guide quickstart
+pm guide commands --depth standard
+pm guide skills --depth deep --format markdown
+pm guide release --json
+```
+
 ## Ownership Rules
 
 - Claim before heavy edits.
@@ -109,6 +123,7 @@ Default TOON output is preferred for model-readable loops. Use `--json` only whe
 
 - Keep [README](../README.md) short.
 - Put details in focused docs under `docs/`.
+- Keep reusable workflow prompts in `.agents/skills/*` and route via `pm guide skills`.
 - Use relative links such as `[Command Reference](COMMANDS.md)`.
 - Add tracker references near the top of new docs when a task created the change.
 - Link docs back to the active item with `pm docs`.

package/docs/ARCHITECTURE.md

@@ -125,7 +125,7 @@ body: |
   Implementation notes.
 ```
 
-Alternative format is JSON-front-matter markdown. `front_matter` is the internal TypeScript model key; TOON stores the same metadata as top-level fields.
+Legacy JSON-front-matter markdown files are read only for one-way migration into TOON. Runtime internals use `metadata` as the item metadata model key.
 
 Built-in item types:
 
@@ -223,7 +223,7 @@ Search supports:
 - semantic mode, when an embedding provider and vector store are available
 - hybrid mode, combining keyword and semantic results
 
-Keyword scoring uses weighted fields such as title, description, tags, status, body, comments, notes, learnings, and dependencies.
+Keyword scoring uses weighted fields such as title, description, tags, status, body, comments, notes, learnings, reminders, events, and dependencies. Semantic indexing uses the same core corpus so calendar-heavy work remains discoverable through normal search and reindex flows.
 
 Runtime semantic components can come from built-ins or extensions:
 

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -0,0 +1,225 @@
+# pm CLI — Claude Code Plugin
+
+Native pm integration for Claude Code via the Model Context Protocol (MCP). Claude can use all pm operations as native tools — no shell invocation, no context switching.
+
+## Architecture
+
+```
+pm-cli/ (repo root)
+├── .claude-plugin/
+│   └── marketplace.json     # Root marketplace catalog — read by /plugin marketplace add
+├── plugins/pm-cli-claude/
+│   ├── .claude-plugin/
+│   │   └── plugin.json      # Claude Code plugin manifest (name: "pm-cli")
+│   ├── .mcp.json            # MCP server config using ${CLAUDE_PLUGIN_ROOT}
+│   ├── skills/
+│   │   ├── pm-workflow/     # Auto-invoked: orient → claim → implement → close
+│   │   ├── pm-developer/    # Developer execution loop with evidence requirements
+│   │   ├── pm-release/      # Release gate sequence and evidence linking
+│   │   ├── pm-audit/        # Comprehensive audit suite
+│   │   └── pm-planner/      # Planning: decompose, prioritize, triage
+│   ├── commands/
+│   │   ├── pm-status.md     # /pm-status
+│   │   ├── pm-start-task.md # /pm-start-task [id|keywords]
+│   │   ├── pm-close-task.md # /pm-close-task [id]
+│   │   ├── pm-triage.md     # /pm-triage <request>
+│   │   ├── pm-audit.md      # /pm-audit
+│   │   ├── pm-search.md     # /pm-search <query>
+│   │   ├── pm-new.md        # /pm-new <title>
+│   │   ├── pm-list.md       # /pm-list [filter]
+│   │   └── pm-calendar.md   # /pm-calendar [view]
+│   ├── hooks/
+│   │   ├── hooks.json       # SessionStart hook definition
+│   │   └── session-start.mjs # Injects pm context at session start
+│   ├── agents/
+│   │   └── pm-coordinator.md # Subagent for multi-item coordination
+│   ├── scripts/
+│   │   └── pm-mcp-server.mjs # MCP server launcher (repo → npx fallback)
+│   └── README.md            # User-facing installation guide
+└── scripts/
+    └── smoke-claude-plugin.mjs  # Full plugin smoke test (run in CI)
+```
+
+The MCP server itself lives at `src/mcp/server.ts` (compiled to `dist/mcp/server.js`) and is bundled with the npm package as the `pm-mcp` binary.
+
+## MCP Server Tools
+
+The server exposes 18 native tools that call pm library functions directly:
+
+| Tool | pm Operation | Key Args |
+|------|-------------|----------|
+| `pm_context` | `pm context` | `options.limit`, `options.depth` |
+| `pm_search` | `pm search` | `query` (required), `options.limit` |
+| `pm_list` | `pm list` | `options.status`, `options.type`, `options.limit` |
+| `pm_get` | `pm get` | `id` (required) |
+| `pm_create` | `pm create` | `options.title`, `options.description`, `options.type` |
+| `pm_update` | `pm update` | `id` (required), `options.*` |
+| `pm_claim` | `pm claim` | `id` (required), `force` |
+| `pm_release` | `pm release` | `id` (required), `force` |
+| `pm_close` | `pm close` | `id` (required), `reason` (required) |
+| `pm_comments` | `pm comments` | `id` (required), `options.add` |
+| `pm_files` | `pm files` | `id` (required), `options.add`, `options.remove` |
+| `pm_docs` | `pm docs` | `id` (required), `options.add`, `options.remove` |
+| `pm_test` | `pm test` | `id` (required), `options.add`, `options.run` |
+| `pm_validate` | `pm validate` | `options.checkResolution`, `options.checkFiles` |
+| `pm_health` | `pm health` | `options.checkOnly` |
+| `pm_contracts` | `pm contracts` | `options.command`, `options.json` |
+| `pm_guide` | `pm guide` | `options.topic`, `options.depth` |
+| `pm_run` | any pm action | `action` (required), `id`, `query`, `reason`, `options.*` |
+
+All tools accept `cwd` (workspace directory), `path` (pm data root override), and `author` (mutation author).
+
+## Installation Methods
+
+### 1. Plugin marketplace (recommended — full feature set)
+
+Add the pm-cli GitHub repo as a marketplace source, then install:
+
+```
+/plugin marketplace add unbraind/pm-cli
+/plugin install pm-cli@pm-cli
+```
+
+This clones the repo, reads `.claude-plugin/marketplace.json` at the root, installs the plugin from `./plugins/pm-cli-claude/`, and configures the MCP server, 5 skills, 9 slash commands, and the session hook automatically.
+
+### 2. Global MCP via Claude Code CLI (MCP tools only)
+
+```bash
+claude mcp add --transport stdio pm-cli-native -- npx -y @unbrained/pm-cli pm-mcp
+```
+
+Gives you the 18 MCP tools without skills or slash commands.
+
+### 3. Direct project `.mcp.json` (project-scoped MCP only)
+
+Add to the project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "pm-cli-native": {
+      "command": "node",
+      "args": ["./plugins/pm-cli-claude/scripts/pm-mcp-server.mjs"],
+      "env": { "PM_AUTHOR": "claude-code-agent" }
+    }
+  }
+}
+```
+
+The repo root `.mcp.json` uses this approach — activates automatically when Claude Code opens this repository.
+
+## MCP Server Launcher
+
+`plugins/pm-cli-claude/scripts/pm-mcp-server.mjs` resolves the server in order:
+
+1. `PM_CLI_MCP_SERVER` env var (explicit override)
+2. `dist/mcp/server.js` walking up from the launcher (repo checkout)
+3. `npx -y @unbrained/pm-cli@latest pm-mcp` (npm-installed fallback)
+
+This means the plugin works both from a repo checkout and from an npm-cached plugin install.
+
+## Session Start Hook
+
+`hooks/session-start.mjs` runs at the start of each Claude Code session. It:
+
+1. Checks for `.agents/pm/settings.json` in the current workspace.
+2. Exits silently if pm is not initialized.
+3. Runs `pm context --limit 5 --json` with a 5-second timeout.
+4. Injects a compact status line into the session context.
+
+Example injection:
+```
+pm tracker: 3 in_progress, 2 open
+  • [pm-xxxx] Fix authentication bug (in_progress)
+  • [pm-yyyy] Add calendar feature (in_progress)
+  • [pm-zzzz] Update docs (open)
+Use pm_context tool or /pm-status for full details.
+```
+
+## Testing the Plugin
+
+### Full Claude Code plugin smoke test (runs in CI)
+
+```bash
+node scripts/smoke-claude-plugin.mjs
+# or:
+pnpm smoke:claude-plugin
+```
+
+Verifies: file structure (23 files), manifest name consistency, MCP initialize, 18 tools present, full workflow (init → create → claim → update → link files/docs/tests → get → context → search → validate → health), and session-start hook.
+
+### MCP server smoke test
+
+```bash
+node scripts/smoke-codex-plugin-mcp.mjs
+# or:
+pnpm smoke:codex-plugin
+```
+
+### Contract-safe preflight (recommended for CI agents)
+
+```bash
+pm contracts --schema-only --json
+pm contracts --command extension --flags-only --json
+pm extension --doctor --project --detail summary --strict-exit
+pm extension --reload --project
+```
+
+Why this matters:
+
+- `pm contracts` is extension-aware and reflects active runtime action/flag surfaces.
+- `extension --doctor` now includes policy diagnostics and deterministic warning codes.
+- `extension --reload` provides cache-busted module reload for extension dev loops.
+- `--strict-exit` turns warning states into CI-failing exits when governance gates require it.
+
+### CLI simplification compatibility notes
+
+The conservative CLI simplification pass adds invocation normalization and replay metadata that plugin/tooling flows should consume:
+
+- long-option aliases/shape variants and high-confidence typos are normalized before parse
+- setup resolution can auto-discover initialized tracker roots from ancestor directories
+- structured error envelopes may include `recovery` with replay-ready guidance (`attempted_command`, `normalized_args`, `provided_fields`, `missing`, `suggested_retry`)
+
+For migration details and automation expectations, see:
+
+- [CLI Simplification Migration](MIGRATION_CLI_SIMPLIFICATION.md)
+
+### Validate manifests
+
+```bash
+claude plugin validate .claude-plugin/marketplace.json
+claude plugin validate plugins/pm-cli-claude/.claude-plugin/plugin.json
+```
+
+### Manual verification
+
+After installing the plugin:
+
+1. Start Claude Code: `claude` (in a pm-initialized directory)
+2. Ask: "What's the current pm project status?"
+   → Verify Claude uses `pm_context` (not Bash)
+3. Try `/pm-status` — active items + calendar
+4. Try `/pm-search authentication` — search results
+5. Try `/pm-new Fix the login timeout bug` — duplicate-checked create
+6. Try `/pm-start-task pm-xxxx` — claim and start
+7. Try `/pm-calendar week` — upcoming deadlines
+8. Try `/pm-close-task pm-xxxx` — verify, evidence, close
+
+## Compatibility
+
+| pm-cli version | Plugin version | Claude Code version |
+|---------------|----------------|---------------------|
+| 2026.5.x+ | 1.0.0 | Any current |
+
+The MCP server uses JSON-RPC 2.0 over stdio with protocol version `2025-06-18`.
+
+## Extension Policy Diagnostics
+
+When extension governance policy is configured (`settings.extensions.policy`), plugin and MCP automation can surface:
+
+- `extension_policy_violation_*` warnings in warn mode
+- `extension_policy_blocked_*` warnings in enforce mode
+- `extension_policy_*_trust` warnings for trust/provenance gates
+- policy summary counters under `extension doctor` details (`summary.policy` + `triage.policy_*`)
+
+This enables contract-safe and policy-safe automation without falling back to shell heuristics.

package/docs/CODEX_PLUGIN.md

@@ -0,0 +1,33 @@
+# Codex Plugin
+
+pm-cli ships a repo-local Codex plugin at [`plugins/pm-cli-codex`](../plugins/pm-cli-codex/README.md).
+
+## Install From This Repo
+
+```bash
+codex plugin marketplace add .
+```
+
+Restart Codex and install **pm CLI** from the `pm CLI Local` marketplace.
+
+## What It Provides
+
+- `pm-cli-native` MCP server for structured pm operations without invoking the `pm` shell command
+- narrow tools for common loops: context, search, list, get, create, update, claim, release, close, comments, files, docs, tests, validate, health, contracts, and guide
+- `pm_run` for the rest of the pm surface, including calendar, activity, aggregate, dedupe-audit, normalize, reindex, extensions, templates, history, stats, gc, and test-runs controls
+- skills for native tracking, audits, and release workflows
+- command prompts for start, close, and audit flows
+
+## Native MCP Notes
+
+The plugin launcher uses the local repository build when `dist/mcp/server.js` is present. When the plugin is cached outside the repo, it falls back to:
+
+```bash
+npx -y @unbrained/pm-cli@latest pm-mcp
+```
+
+The fallback starts the package MCP server, not the `pm` CLI command. Tool calls import pm command modules and return JSON-compatible structured results.
+
+## Safety
+
+For real repository tracking, leave `path` unset so pm uses the repository `.agents/pm` root. For tests, use a sandbox `cwd` or `path` and isolate `PM_GLOBAL_PATH`.

package/docs/COMMANDS.md

@@ -6,12 +6,14 @@ This is a task-oriented command guide. For exact flags, use runtime help because
 pm <command> --help
 pm <command> --help --json
 pm contracts --command <command> --flags-only --json
+pm guide commands --depth standard
 ```
 
 ## Agent Quick Context
 
 - Prefer `pm context`, `pm search`, and narrow list commands before mutation.
 - Prefer TOON for reading and `--json` for strict parsing.
+- Use `pm guide <topic>` for local docs routing before opening deeper pages.
 - Use `pm contracts` for machine clients.
 - Every mutation writes history.
 
@@ -30,7 +32,7 @@ Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 | History | `history`, `activity`, `restore`, `stats` | inspect and recover item state |
 | Calendar | `calendar`, `cal` | project deadlines, reminders, and events |
 | Extensions | `extension`, extension command groups | install, manage, and run extension commands |
-| Machines | `contracts`, `completion`, `help` | expose stable command contracts and shell helpers |
+| Machines | `guide`, `contracts`, `completion`, `help` | local docs routing plus command contracts and shell helpers |
 
 ## Bootstrap
 
@@ -118,11 +120,13 @@ pm release <id> --allow-audit-release --author <you>
 
 ```bash
 pm comments <id> "Implemented command parsing fix."
+printf '%s\n' '## Verification summary' '- Linux pass' '- macOS pass' | pm comments <id> --stdin
+pm comments <id> --file docs/release-evidence.md
 pm notes <id> --add "Keep renderer changes isolated to TOON output."
 pm learnings <id> --add "Use runtime contracts instead of duplicating flag lists."
 ```
 
-Use comments for progress and evidence, notes for implementation context, and learnings for durable future guidance.
+Use comments for progress and evidence, notes for implementation context, and learnings for durable future guidance. For comments, choose exactly one input source (`[text]`, `--add`, `--stdin`, or `--file`) per invocation.
 
 ## Linked Artifacts
 

package/docs/CONFIGURATION.md

@@ -40,7 +40,7 @@ Precedence:
 |---------|---------|
 | `id_prefix` | generated item ID prefix, default `pm-` |
 | `author_default` | fallback mutation author |
-| `item_format` | `toon` or `json_markdown` item files |
+| `item_format` | item storage format (`toon` writes; legacy markdown is read/migrate only) |
 | `output.default_format` | default renderer, usually `toon` |
 | `locks.ttl_seconds` | stale lock threshold |
 | `history.missing_stream` | `auto_create` or `strict_error` |
@@ -70,13 +70,7 @@ TOON is the default:
 pm config project set item-format --format toon
 ```
 
-JSON-front-matter markdown is also supported:
-
-```bash
-pm config project set item-format --format json_markdown
-```
-
-Changing item format runs migration on item files. History stays JSONL.
+Markdown item files are treated as legacy migration input only. Mutations always write TOON files, and history stays JSONL.
 
 ## Output Format