@unbrained/pm-cli 2026.6.19 → 2026.6.20

package/dist/types.d.ts

@@ -731,6 +731,15 @@ export interface PmSettings {
     locks: {
         ttl_seconds: number;
     };
+    /**
+     * Retention policy for bulk-mutation rollback checkpoints written by
+     * `update-many`/`close-many`. `pm gc --scope checkpoints` prunes checkpoint
+     * files older than `retention_days`; checkpoints with an unparseable
+     * `created_at` are retained (safety-first, mirroring the stale-lock sweep).
+     */
+    checkpoints: {
+        retention_days: number;
+    };
     output: {
         default_format: "toon" | "json";
     };
@@ -802,6 +811,16 @@ export interface PmSettings {
         mutation_refresh_policy: SearchMutationRefreshPolicy;
         query_expansion: SearchQueryExpansionSettings;
         rerank: SearchRerankSettings;
+        /**
+         * Offline BM25 lexical-ranking parameters (pm-75k9), applied when
+         * `search.provider` is `bm25` (or auto-selected as the offline fallback) for
+         * semantic/hybrid queries. `k1` controls term-frequency saturation, `b`
+         * controls document-length normalization. Unset → Lucene defaults (1.2/0.75).
+         */
+        bm25?: {
+            k1?: number;
+            b?: number;
+        };
         tuning?: {
             title_exact_bonus?: number;
             title_weight?: number;

package/dist/types.js

@@ -4,7 +4,7 @@
  * Defines the shared project-management data model used by CLI, SDK, MCP, and packages.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5cc565e8-6fe7-5300-b82a-50262bd9fe80")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3123775a-c8ad-5339-abf2-f3893145f1e7")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -133,4 +133,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=5cc565e8-6fe7-5300-b82a-50262bd9fe80
+//# debugId=3123775a-c8ad-5339-abf2-f3893145f1e7

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["types.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module types\n *\n * Defines the shared project-management data model used by CLI, SDK, MCP, and packages.\n */\nexport 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  \"Plan\",\n] as const;\nexport const ITEM_TYPE_VALUES = BUILTIN_ITEM_TYPE_VALUES;\n/**\n * Restricts builtin item type values accepted by command, SDK, and storage contracts.\n */\nexport type BuiltinItemType = (typeof BUILTIN_ITEM_TYPE_VALUES)[number];\n/**\n * Restricts item type values accepted by command, SDK, and storage contracts.\n */\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;\n/**\n * Restricts item status values accepted by command, SDK, and storage contracts.\n */\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;\n/**\n * Restricts runtime status role values accepted by command, SDK, and storage contracts.\n */\nexport type RuntimeStatusRole = (typeof RUNTIME_STATUS_ROLE_VALUES)[number];\n\nexport const RUNTIME_FIELD_TYPE_VALUES = [\"string\", \"number\", \"boolean\", \"string_array\"] as const;\n/**\n * Restricts runtime field type values accepted by command, SDK, and storage contracts.\n */\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;\n/**\n * Restricts runtime field command values accepted by command, SDK, and storage contracts.\n */\nexport type RuntimeFieldCommand = (typeof RUNTIME_FIELD_COMMAND_VALUES)[number];\n\nexport const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES = [\"allow\", \"warn\", \"reject\"] as const;\n/**\n * Restricts runtime unknown field policy values accepted by command, SDK, and storage contracts.\n */\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;\n/**\n * Restricts dependency kind values accepted by command, SDK, and storage contracts.\n */\nexport type DependencyKind = (typeof DEPENDENCY_KIND_VALUES)[number];\n\nexport const SCOPE_VALUES = [\"project\", \"global\"] as const;\n/**\n * Restricts link scope values accepted by command, SDK, and storage contracts.\n */\nexport type LinkScope = (typeof SCOPE_VALUES)[number];\n\nexport const RISK_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\n/**\n * Restricts risk level values accepted by command, SDK, and storage contracts.\n */\nexport type RiskLevel = (typeof RISK_VALUES)[number];\n\nexport const ISSUE_SEVERITY_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\n/**\n * Restricts issue severity values accepted by command, SDK, and storage contracts.\n */\nexport type IssueSeverity = (typeof ISSUE_SEVERITY_VALUES)[number];\n\nexport const CONFIDENCE_TEXT_VALUES = [\"low\", \"medium\", \"high\"] as const;\n/**\n * Restricts confidence text level values accepted by command, SDK, and storage contracts.\n */\nexport type ConfidenceTextLevel = (typeof CONFIDENCE_TEXT_VALUES)[number];\n/**\n * Restricts confidence value values accepted by command, SDK, and storage contracts.\n */\nexport type ConfidenceValue = number | ConfidenceTextLevel;\n\nexport const ITEM_FORMAT_VALUES = [\"toon\", \"json_markdown\"] as const;\n/**\n * Restricts item format values accepted by command, SDK, and storage contracts.\n */\nexport type ItemFormat = (typeof ITEM_FORMAT_VALUES)[number];\n\nexport const SPRINT_RELEASE_FORMAT_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\n/**\n * Restricts sprint release format policy values accepted by command, SDK, and storage contracts.\n */\nexport type SprintReleaseFormatPolicy = (typeof SPRINT_RELEASE_FORMAT_POLICY_VALUES)[number];\nexport const PARENT_REFERENCE_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\n/**\n * Restricts parent reference policy values accepted by command, SDK, and storage contracts.\n */\nexport type ParentReferencePolicy = (typeof PARENT_REFERENCE_POLICY_VALUES)[number];\nexport const VALIDATE_METADATA_PROFILE_VALUES = [\"core\", \"strict\", \"custom\"] as const;\n/**\n * Restricts validate metadata profile values accepted by command, SDK, and storage contracts.\n */\nexport type ValidateMetadataProfile = (typeof VALIDATE_METADATA_PROFILE_VALUES)[number];\nexport const GOVERNANCE_PRESET_VALUES = [\"minimal\", \"default\", \"strict\", \"custom\"] as const;\n/**\n * Restricts governance preset values accepted by command, SDK, and storage contracts.\n */\nexport type GovernancePreset = (typeof GOVERNANCE_PRESET_VALUES)[number];\nexport const GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES = [\"none\", \"warn\", \"strict\"] as const;\n/**\n * Restricts governance ownership enforcement values accepted by command, SDK, and storage contracts.\n */\nexport type GovernanceOwnershipEnforcement = (typeof GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES)[number];\nexport const GOVERNANCE_CREATE_MODE_DEFAULT_VALUES = [\"progressive\", \"strict\"] as const;\n/**\n * Restricts governance create mode default values accepted by command, SDK, and storage contracts.\n */\nexport type GovernanceCreateModeDefault = (typeof GOVERNANCE_CREATE_MODE_DEFAULT_VALUES)[number];\nexport const GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES = [\"off\", \"warn\", \"strict\"] as const;\n/**\n * Restricts governance close validation default values accepted by command, SDK, and storage contracts.\n */\nexport type GovernanceCloseValidationDefault = (typeof GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES)[number];\nexport const GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES = [\"off\", \"warn\", \"strict\"] as const;\n/**\n * Restricts governance workflow enforcement values accepted by command, SDK, and storage contracts.\n */\nexport type GovernanceWorkflowEnforcement = (typeof GOVERNANCE_WORKFLOW_ENFORCEMENT_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;\n/**\n * Restricts validate metadata required field values accepted by command, SDK, and storage contracts.\n */\nexport type ValidateMetadataRequiredField = (typeof VALIDATE_METADATA_REQUIRED_FIELD_VALUES)[number];\n\nexport const RECURRENCE_FREQUENCY_VALUES = [\"daily\", \"weekly\", \"monthly\", \"yearly\"] as const;\n/**\n * Restricts recurrence frequency values accepted by command, SDK, and storage contracts.\n */\nexport type RecurrenceFrequency = (typeof RECURRENCE_FREQUENCY_VALUES)[number];\n\nexport const RECURRENCE_WEEKDAY_VALUES = [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\", \"sat\", \"sun\"] as const;\n/**\n * Restricts recurrence weekday values accepted by command, SDK, and storage contracts.\n */\nexport type RecurrenceWeekday = (typeof RECURRENCE_WEEKDAY_VALUES)[number];\n\n/**\n * Canonical week-order index for a recurrence weekday (mon=0 .. sun=6).\n * Shared by item serialization, create/update parsing, and calendar expansion\n * so weekday ordering cannot drift between those modules.\n */\nexport function weekdayOrderIndex(value: RecurrenceWeekday): number {\n  return RECURRENCE_WEEKDAY_VALUES.indexOf(value);\n}\n\n/**\n * Documents the dependency payload exchanged by command, SDK, and package integrations.\n */\nexport interface Dependency {\n  id: string;\n  kind: DependencyKind;\n  created_at: string;\n  author?: string;\n  source_kind?: string;\n}\n\n/**\n * Documents the comment payload exchanged by command, SDK, and package integrations.\n */\nexport interface Comment {\n  created_at: string;\n  author: string;\n  text: string;\n}\n\n/**\n * Documents the log note payload exchanged by command, SDK, and package integrations.\n */\nexport interface LogNote {\n  created_at: string;\n  author: string;\n  text: string;\n}\n\n/**\n * Documents the linked file payload exchanged by command, SDK, and package integrations.\n */\nexport interface LinkedFile {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n}\n\n/**\n * Documents the linked test payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the linked doc payload exchanged by command, SDK, and package integrations.\n */\nexport interface LinkedDoc {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n}\n\n/**\n * Documents the reminder payload exchanged by command, SDK, and package integrations.\n */\nexport interface Reminder {\n  at: string;\n  text: string;\n}\n\n/**\n * Documents the recurrence rule payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the calendar event payload exchanged by command, SDK, and package integrations.\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 const PLAN_MODE_VALUES = [\n  \"draft\",\n  \"research\",\n  \"review\",\n  \"approved\",\n  \"executing\",\n  \"paused\",\n  \"completed\",\n  \"superseded\",\n] as const;\n/**\n * Restricts plan mode values accepted by command, SDK, and storage contracts.\n */\nexport type PlanMode = (typeof PLAN_MODE_VALUES)[number];\n\nexport const PLAN_STEP_STATUS_VALUES = [\n  \"pending\",\n  \"in_progress\",\n  \"completed\",\n  \"blocked\",\n  \"skipped\",\n  \"superseded\",\n] as const;\n/**\n * Restricts plan step status values accepted by command, SDK, and storage contracts.\n */\nexport type PlanStepStatus = (typeof PLAN_STEP_STATUS_VALUES)[number];\n\nexport const PLAN_HARNESS_VALUES = [\"codex\", \"claude-code\", \"cursor\", \"generic\"] as const;\n/**\n * Restricts plan harness values accepted by command, SDK, and storage contracts.\n */\nexport type PlanHarness = (typeof PLAN_HARNESS_VALUES)[number];\n\nexport const PLAN_STEP_LINK_KIND_VALUES = [\n  \"related\",\n  \"blocks\",\n  \"blocked_by\",\n  \"depends_on\",\n  \"discovered_from\",\n  \"implements\",\n  \"verifies\",\n  \"supersedes\",\n] as const;\n/**\n * Restricts plan step link kind values accepted by command, SDK, and storage contracts.\n */\nexport type PlanStepLinkKind = (typeof PLAN_STEP_LINK_KIND_VALUES)[number];\n\n/**\n * Documents the plan step link payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanStepLink {\n  id: string;\n  kind: PlanStepLinkKind;\n  note?: string;\n  required_before_step?: boolean;\n}\n\n/**\n * Documents the plan step file payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanStepFile {\n  path: string;\n  scope?: LinkScope;\n  note?: string;\n}\n\n/**\n * Documents the plan step test payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanStepTest {\n  command?: string;\n  path?: string;\n  note?: string;\n}\n\n/**\n * Documents the plan step doc payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanStepDoc {\n  path: string;\n  scope?: LinkScope;\n  note?: string;\n}\n\n/**\n * Documents the plan step payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanStep {\n  id: string;\n  order: number;\n  title: string;\n  body?: string;\n  status: PlanStepStatus;\n  owner?: string;\n  evidence?: string;\n  blocked_reason?: string;\n  superseded_by?: string;\n  linked_items?: PlanStepLink[];\n  files?: PlanStepFile[];\n  tests?: PlanStepTest[];\n  docs?: PlanStepDoc[];\n  created_at: string;\n  updated_at: string;\n  completed_at?: string;\n}\n\n/**\n * Documents the plan decision payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanDecision {\n  ts: string;\n  author: string;\n  decision: string;\n  rationale?: string;\n  evidence?: string;\n  step_id?: string;\n}\n\n/**\n * Documents the plan discovery payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanDiscovery {\n  ts: string;\n  author: string;\n  text: string;\n  step_id?: string;\n}\n\n/**\n * Documents the plan validation check payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanValidationCheck {\n  text: string;\n  command?: string;\n  expected?: string;\n}\n\n/**\n * Documents the item type option definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface ItemTypeOptionDefinition {\n  key: string;\n  values: string[];\n  required?: boolean;\n  aliases?: string[];\n  description?: string;\n}\n\n/**\n * Documents the item type command option policy payload exchanged by command, SDK, and package integrations.\n */\nexport interface ItemTypeCommandOptionPolicy {\n  command: \"create\" | \"update\";\n  option: string;\n  required?: boolean;\n  visible?: boolean;\n  enabled?: boolean;\n}\n\n/**\n * Documents the item type definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface ItemTypeDefinition {\n  name: string;\n  description?: string;\n  /**\n   * Status assigned to newly created items of this type when `--status` is not\n   * provided. Falls back to the workflow's open status when unset or invalid.\n   */\n  default_status?: 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\n/**\n * Documents the runtime status definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface RuntimeStatusDefinition {\n  id: string;\n  aliases?: string[];\n  roles?: RuntimeStatusRole[];\n  description?: string;\n  order?: number;\n}\n\n/**\n * Documents the runtime field definition payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the runtime workflow definition payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the runtime schema file config payload exchanged by command, SDK, and package integrations.\n */\nexport interface RuntimeSchemaFileConfig {\n  types?: string;\n  statuses?: string;\n  fields?: string;\n  workflows?: string;\n}\n\n/**\n * Per-type allowed-transition rule. A type with no matching entry is\n * unrestricted; a type with an entry allows only the listed [from, to]\n * status pairs (status tokens are resolved case-insensitively through the\n * status registry alias map; a same-status no-op is always allowed).\n */\nexport interface TypeWorkflowDefinition {\n  type: string;\n  allowed_transitions: [string, string][];\n}\n\n/**\n * Documents the runtime schema settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface RuntimeSchemaSettings {\n  version: number;\n  files: RuntimeSchemaFileConfig;\n  statuses: RuntimeStatusDefinition[];\n  fields: RuntimeFieldDefinition[];\n  workflow: RuntimeWorkflowDefinition;\n  type_workflows?: TypeWorkflowDefinition[];\n  unknown_field_policy: RuntimeUnknownFieldPolicy;\n}\n\n/**\n * Documents the item test run summary payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the item metadata payload exchanged by command, SDK, and package integrations.\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?: RiskLevel;\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  duplicate_of?: string;\n  plan_mode?: PlanMode;\n  plan_scope?: string;\n  plan_harness?: PlanHarness;\n  plan_steps?: PlanStep[];\n  plan_decisions?: PlanDecision[];\n  plan_discoveries?: PlanDiscovery[];\n  plan_validation?: PlanValidationCheck[];\n  plan_resume_context?: string;\n  [key: string]: unknown;\n}\n\n/**\n * @deprecated Use ItemMetadata.\n */\nexport type ItemFrontMatter = ItemMetadata;\n\n/**\n * Documents the item document payload exchanged by command, SDK, and package integrations.\n */\nexport interface ItemDocument {\n  metadata: ItemMetadata;\n  body: string;\n}\n\n/**\n * Documents the history patch op payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryPatchOp {\n  op: \"add\" | \"remove\" | \"replace\" | \"move\" | \"copy\" | \"test\";\n  path: string;\n  from?: string;\n  value?: unknown;\n}\n\n/**\n * Documents the history entry payload exchanged by command, SDK, and package integrations.\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\", \"full\"] as const;\n/**\n * Restricts context depth values accepted by command, SDK, and storage contracts.\n */\nexport type ContextDepth = (typeof CONTEXT_DEPTH_VALUES)[number];\n\nexport const CONTEXT_SECTION_VALUES = [\n  \"hierarchy\",\n  \"activity\",\n  \"progress\",\n  \"recently_created\",\n  \"unparented\",\n  \"blockers\",\n  \"files\",\n  \"workload\",\n  \"staleness\",\n  \"tests\",\n] as const;\n/**\n * Restricts context section name values accepted by command, SDK, and storage contracts.\n */\nexport type ContextSectionName = (typeof CONTEXT_SECTION_VALUES)[number];\n\n/**\n * Documents the context section settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface ContextSectionSettings {\n  hierarchy: boolean;\n  activity: boolean;\n  progress: boolean;\n  recently_created: boolean;\n  unparented: boolean;\n  blockers: boolean;\n  files: boolean;\n  workload: boolean;\n  staleness: boolean;\n  tests: boolean;\n}\n\n/**\n * Documents the context settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface ContextSettings {\n  default_depth: ContextDepth;\n  activity_limit: number;\n  stale_threshold_days: number;\n  sections: ContextSectionSettings;\n}\n\n/**\n * Documents the governance settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface GovernanceSettings {\n  preset: GovernancePreset;\n  ownership_enforcement: GovernanceOwnershipEnforcement;\n  create_mode_default: GovernanceCreateModeDefault;\n  close_validation_default: GovernanceCloseValidationDefault;\n  require_close_reason: boolean;\n  parent_reference: ParentReferencePolicy;\n  metadata_profile: ValidateMetadataProfile;\n  force_required_for_stale_lock: boolean;\n  create_default_type?: string;\n  /**\n   * Per-type allowed-transition enforcement mode for `pm update --status`.\n   * Read raw from settings (not preset-derived) so existing projects are\n   * unaffected when unset; defaults to \"off\".\n   */\n  workflow_enforcement?: GovernanceWorkflowEnforcement;\n}\n\n/**\n * Restricts extension policy mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionPolicyMode = \"off\" | \"warn\" | \"enforce\";\n/**\n * Restricts extension trust mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionTrustMode = \"off\" | \"warn\" | \"enforce\";\n/**\n * Restricts extension sandbox profile values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionSandboxProfile = \"none\" | \"restricted\" | \"strict\";\n\n/**\n * Documents the extension policy override settings payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the extension policy settings payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the agent guidance settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface AgentGuidanceSettings {\n  prompt_completed: boolean;\n  declined: boolean;\n  declined_at: string;\n  template_version: number;\n  last_checked_files: string[];\n}\n\n/**\n * Restricts search mutation refresh policy values accepted by command, SDK, and storage contracts.\n */\nexport type SearchMutationRefreshPolicy = \"cache_only\" | \"semantic_configured\" | \"semantic_auto\";\n\n/**\n * Documents the search query expansion settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchQueryExpansionSettings {\n  enabled: boolean;\n  provider: string;\n}\n\n/**\n * Documents the search rerank settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchRerankSettings {\n  enabled: boolean;\n  model: string;\n  top_k: number;\n}\n\n/**\n * Config-driven policy for automatic history-stream compaction triage.\n *\n * When `enabled`, `pm health` surfaces an advisory warning for any history\n * stream whose non-empty entry count exceeds `max_entries`, and `pm\n * history-compact` bulk mode uses `max_entries` as its default `--all-over`\n * threshold so the configured policy drives corpus-wide sweeps. `trigger`\n * records operator intent — both values raise the health advisory; `auto`\n * additionally signals that scheduled/automatic sweeps are expected.\n */\nexport interface HistoryCompactPolicy {\n  enabled: boolean;\n  max_entries: number;\n  trigger: \"health_warn\" | \"auto\";\n}\n\n/**\n * Documents the pm settings payload exchanged by command, SDK, and package integrations.\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    compact_policy: HistoryCompactPolicy;\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     * Per-type default estimates (minutes) used by `pm validate --auto-fix\n     * --fix-scope estimates` to backfill missing `estimated_minutes` (GH-212).\n     * Keys are item type names (case-insensitive); values are positive minutes\n     * that override the built-in defaults. Empty by default.\n     */\n    estimate_defaults_by_type: Record<string, number>;\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  agent_guidance: AgentGuidanceSettings;\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_corpus_max_characters?: number;\n    embedding_batch_size: number;\n    embedding_timeout_ms: number;\n    scanner_max_batch_retries: number;\n    provider?: string;\n    /**\n     * Optional allow-list of corpus field names embedded for semantic search\n     * (see DEFAULT_SEARCH_CORPUS_FIELDS in core/search/corpus.ts). When unset or\n     * empty, the full default field set is used (backward compatible). When set,\n     * only the named fields are embedded — letting teams opt structured signals\n     * (priority, assignee, risk, acceptance_criteria, etc.) in/out for token\n     * efficiency. Changing this re-flags items stale on the next refresh.\n     */\n    corpus_fields?: string[];\n    mutation_refresh_policy: SearchMutationRefreshPolicy;\n    query_expansion: SearchQueryExpansionSettings;\n    rerank: SearchRerankSettings;\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    collection_name: string;\n    qdrant: {\n      url: string;\n      api_key: string;\n    };\n    lancedb: {\n      path: string;\n    };\n  };\n}\n"],"names":[],"mappings":"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","debugId":"5cc565e8-6fe7-5300-b82a-50262bd9fe80"}
+{"version":3,"file":"types.js","sources":["types.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module types\n *\n * Defines the shared project-management data model used by CLI, SDK, MCP, and packages.\n */\nexport 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  \"Plan\",\n] as const;\nexport const ITEM_TYPE_VALUES = BUILTIN_ITEM_TYPE_VALUES;\n/**\n * Restricts builtin item type values accepted by command, SDK, and storage contracts.\n */\nexport type BuiltinItemType = (typeof BUILTIN_ITEM_TYPE_VALUES)[number];\n/**\n * Restricts item type values accepted by command, SDK, and storage contracts.\n */\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;\n/**\n * Restricts item status values accepted by command, SDK, and storage contracts.\n */\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;\n/**\n * Restricts runtime status role values accepted by command, SDK, and storage contracts.\n */\nexport type RuntimeStatusRole = (typeof RUNTIME_STATUS_ROLE_VALUES)[number];\n\nexport const RUNTIME_FIELD_TYPE_VALUES = [\"string\", \"number\", \"boolean\", \"string_array\"] as const;\n/**\n * Restricts runtime field type values accepted by command, SDK, and storage contracts.\n */\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;\n/**\n * Restricts runtime field command values accepted by command, SDK, and storage contracts.\n */\nexport type RuntimeFieldCommand = (typeof RUNTIME_FIELD_COMMAND_VALUES)[number];\n\nexport const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES = [\"allow\", \"warn\", \"reject\"] as const;\n/**\n * Restricts runtime unknown field policy values accepted by command, SDK, and storage contracts.\n */\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;\n/**\n * Restricts dependency kind values accepted by command, SDK, and storage contracts.\n */\nexport type DependencyKind = (typeof DEPENDENCY_KIND_VALUES)[number];\n\nexport const SCOPE_VALUES = [\"project\", \"global\"] as const;\n/**\n * Restricts link scope values accepted by command, SDK, and storage contracts.\n */\nexport type LinkScope = (typeof SCOPE_VALUES)[number];\n\nexport const RISK_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\n/**\n * Restricts risk level values accepted by command, SDK, and storage contracts.\n */\nexport type RiskLevel = (typeof RISK_VALUES)[number];\n\nexport const ISSUE_SEVERITY_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\n/**\n * Restricts issue severity values accepted by command, SDK, and storage contracts.\n */\nexport type IssueSeverity = (typeof ISSUE_SEVERITY_VALUES)[number];\n\nexport const CONFIDENCE_TEXT_VALUES = [\"low\", \"medium\", \"high\"] as const;\n/**\n * Restricts confidence text level values accepted by command, SDK, and storage contracts.\n */\nexport type ConfidenceTextLevel = (typeof CONFIDENCE_TEXT_VALUES)[number];\n/**\n * Restricts confidence value values accepted by command, SDK, and storage contracts.\n */\nexport type ConfidenceValue = number | ConfidenceTextLevel;\n\nexport const ITEM_FORMAT_VALUES = [\"toon\", \"json_markdown\"] as const;\n/**\n * Restricts item format values accepted by command, SDK, and storage contracts.\n */\nexport type ItemFormat = (typeof ITEM_FORMAT_VALUES)[number];\n\nexport const SPRINT_RELEASE_FORMAT_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\n/**\n * Restricts sprint release format policy values accepted by command, SDK, and storage contracts.\n */\nexport type SprintReleaseFormatPolicy = (typeof SPRINT_RELEASE_FORMAT_POLICY_VALUES)[number];\nexport const PARENT_REFERENCE_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\n/**\n * Restricts parent reference policy values accepted by command, SDK, and storage contracts.\n */\nexport type ParentReferencePolicy = (typeof PARENT_REFERENCE_POLICY_VALUES)[number];\nexport const VALIDATE_METADATA_PROFILE_VALUES = [\"core\", \"strict\", \"custom\"] as const;\n/**\n * Restricts validate metadata profile values accepted by command, SDK, and storage contracts.\n */\nexport type ValidateMetadataProfile = (typeof VALIDATE_METADATA_PROFILE_VALUES)[number];\nexport const GOVERNANCE_PRESET_VALUES = [\"minimal\", \"default\", \"strict\", \"custom\"] as const;\n/**\n * Restricts governance preset values accepted by command, SDK, and storage contracts.\n */\nexport type GovernancePreset = (typeof GOVERNANCE_PRESET_VALUES)[number];\nexport const GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES = [\"none\", \"warn\", \"strict\"] as const;\n/**\n * Restricts governance ownership enforcement values accepted by command, SDK, and storage contracts.\n */\nexport type GovernanceOwnershipEnforcement = (typeof GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES)[number];\nexport const GOVERNANCE_CREATE_MODE_DEFAULT_VALUES = [\"progressive\", \"strict\"] as const;\n/**\n * Restricts governance create mode default values accepted by command, SDK, and storage contracts.\n */\nexport type GovernanceCreateModeDefault = (typeof GOVERNANCE_CREATE_MODE_DEFAULT_VALUES)[number];\nexport const GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES = [\"off\", \"warn\", \"strict\"] as const;\n/**\n * Restricts governance close validation default values accepted by command, SDK, and storage contracts.\n */\nexport type GovernanceCloseValidationDefault = (typeof GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES)[number];\nexport const GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES = [\"off\", \"warn\", \"strict\"] as const;\n/**\n * Restricts governance workflow enforcement values accepted by command, SDK, and storage contracts.\n */\nexport type GovernanceWorkflowEnforcement = (typeof GOVERNANCE_WORKFLOW_ENFORCEMENT_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;\n/**\n * Restricts validate metadata required field values accepted by command, SDK, and storage contracts.\n */\nexport type ValidateMetadataRequiredField = (typeof VALIDATE_METADATA_REQUIRED_FIELD_VALUES)[number];\n\nexport const RECURRENCE_FREQUENCY_VALUES = [\"daily\", \"weekly\", \"monthly\", \"yearly\"] as const;\n/**\n * Restricts recurrence frequency values accepted by command, SDK, and storage contracts.\n */\nexport type RecurrenceFrequency = (typeof RECURRENCE_FREQUENCY_VALUES)[number];\n\nexport const RECURRENCE_WEEKDAY_VALUES = [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\", \"sat\", \"sun\"] as const;\n/**\n * Restricts recurrence weekday values accepted by command, SDK, and storage contracts.\n */\nexport type RecurrenceWeekday = (typeof RECURRENCE_WEEKDAY_VALUES)[number];\n\n/**\n * Canonical week-order index for a recurrence weekday (mon=0 .. sun=6).\n * Shared by item serialization, create/update parsing, and calendar expansion\n * so weekday ordering cannot drift between those modules.\n */\nexport function weekdayOrderIndex(value: RecurrenceWeekday): number {\n  return RECURRENCE_WEEKDAY_VALUES.indexOf(value);\n}\n\n/**\n * Documents the dependency payload exchanged by command, SDK, and package integrations.\n */\nexport interface Dependency {\n  id: string;\n  kind: DependencyKind;\n  created_at: string;\n  author?: string;\n  source_kind?: string;\n}\n\n/**\n * Documents the comment payload exchanged by command, SDK, and package integrations.\n */\nexport interface Comment {\n  created_at: string;\n  author: string;\n  text: string;\n}\n\n/**\n * Documents the log note payload exchanged by command, SDK, and package integrations.\n */\nexport interface LogNote {\n  created_at: string;\n  author: string;\n  text: string;\n}\n\n/**\n * Documents the linked file payload exchanged by command, SDK, and package integrations.\n */\nexport interface LinkedFile {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n}\n\n/**\n * Documents the linked test payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the linked doc payload exchanged by command, SDK, and package integrations.\n */\nexport interface LinkedDoc {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n}\n\n/**\n * Documents the reminder payload exchanged by command, SDK, and package integrations.\n */\nexport interface Reminder {\n  at: string;\n  text: string;\n}\n\n/**\n * Documents the recurrence rule payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the calendar event payload exchanged by command, SDK, and package integrations.\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 const PLAN_MODE_VALUES = [\n  \"draft\",\n  \"research\",\n  \"review\",\n  \"approved\",\n  \"executing\",\n  \"paused\",\n  \"completed\",\n  \"superseded\",\n] as const;\n/**\n * Restricts plan mode values accepted by command, SDK, and storage contracts.\n */\nexport type PlanMode = (typeof PLAN_MODE_VALUES)[number];\n\nexport const PLAN_STEP_STATUS_VALUES = [\n  \"pending\",\n  \"in_progress\",\n  \"completed\",\n  \"blocked\",\n  \"skipped\",\n  \"superseded\",\n] as const;\n/**\n * Restricts plan step status values accepted by command, SDK, and storage contracts.\n */\nexport type PlanStepStatus = (typeof PLAN_STEP_STATUS_VALUES)[number];\n\nexport const PLAN_HARNESS_VALUES = [\"codex\", \"claude-code\", \"cursor\", \"generic\"] as const;\n/**\n * Restricts plan harness values accepted by command, SDK, and storage contracts.\n */\nexport type PlanHarness = (typeof PLAN_HARNESS_VALUES)[number];\n\nexport const PLAN_STEP_LINK_KIND_VALUES = [\n  \"related\",\n  \"blocks\",\n  \"blocked_by\",\n  \"depends_on\",\n  \"discovered_from\",\n  \"implements\",\n  \"verifies\",\n  \"supersedes\",\n] as const;\n/**\n * Restricts plan step link kind values accepted by command, SDK, and storage contracts.\n */\nexport type PlanStepLinkKind = (typeof PLAN_STEP_LINK_KIND_VALUES)[number];\n\n/**\n * Documents the plan step link payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanStepLink {\n  id: string;\n  kind: PlanStepLinkKind;\n  note?: string;\n  required_before_step?: boolean;\n}\n\n/**\n * Documents the plan step file payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanStepFile {\n  path: string;\n  scope?: LinkScope;\n  note?: string;\n}\n\n/**\n * Documents the plan step test payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanStepTest {\n  command?: string;\n  path?: string;\n  note?: string;\n}\n\n/**\n * Documents the plan step doc payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanStepDoc {\n  path: string;\n  scope?: LinkScope;\n  note?: string;\n}\n\n/**\n * Documents the plan step payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanStep {\n  id: string;\n  order: number;\n  title: string;\n  body?: string;\n  status: PlanStepStatus;\n  owner?: string;\n  evidence?: string;\n  blocked_reason?: string;\n  superseded_by?: string;\n  linked_items?: PlanStepLink[];\n  files?: PlanStepFile[];\n  tests?: PlanStepTest[];\n  docs?: PlanStepDoc[];\n  created_at: string;\n  updated_at: string;\n  completed_at?: string;\n}\n\n/**\n * Documents the plan decision payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanDecision {\n  ts: string;\n  author: string;\n  decision: string;\n  rationale?: string;\n  evidence?: string;\n  step_id?: string;\n}\n\n/**\n * Documents the plan discovery payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanDiscovery {\n  ts: string;\n  author: string;\n  text: string;\n  step_id?: string;\n}\n\n/**\n * Documents the plan validation check payload exchanged by command, SDK, and package integrations.\n */\nexport interface PlanValidationCheck {\n  text: string;\n  command?: string;\n  expected?: string;\n}\n\n/**\n * Documents the item type option definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface ItemTypeOptionDefinition {\n  key: string;\n  values: string[];\n  required?: boolean;\n  aliases?: string[];\n  description?: string;\n}\n\n/**\n * Documents the item type command option policy payload exchanged by command, SDK, and package integrations.\n */\nexport interface ItemTypeCommandOptionPolicy {\n  command: \"create\" | \"update\";\n  option: string;\n  required?: boolean;\n  visible?: boolean;\n  enabled?: boolean;\n}\n\n/**\n * Documents the item type definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface ItemTypeDefinition {\n  name: string;\n  description?: string;\n  /**\n   * Status assigned to newly created items of this type when `--status` is not\n   * provided. Falls back to the workflow's open status when unset or invalid.\n   */\n  default_status?: 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\n/**\n * Documents the runtime status definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface RuntimeStatusDefinition {\n  id: string;\n  aliases?: string[];\n  roles?: RuntimeStatusRole[];\n  description?: string;\n  order?: number;\n}\n\n/**\n * Documents the runtime field definition payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the runtime workflow definition payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the runtime schema file config payload exchanged by command, SDK, and package integrations.\n */\nexport interface RuntimeSchemaFileConfig {\n  types?: string;\n  statuses?: string;\n  fields?: string;\n  workflows?: string;\n}\n\n/**\n * Per-type allowed-transition rule. A type with no matching entry is\n * unrestricted; a type with an entry allows only the listed [from, to]\n * status pairs (status tokens are resolved case-insensitively through the\n * status registry alias map; a same-status no-op is always allowed).\n */\nexport interface TypeWorkflowDefinition {\n  type: string;\n  allowed_transitions: [string, string][];\n}\n\n/**\n * Documents the runtime schema settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface RuntimeSchemaSettings {\n  version: number;\n  files: RuntimeSchemaFileConfig;\n  statuses: RuntimeStatusDefinition[];\n  fields: RuntimeFieldDefinition[];\n  workflow: RuntimeWorkflowDefinition;\n  type_workflows?: TypeWorkflowDefinition[];\n  unknown_field_policy: RuntimeUnknownFieldPolicy;\n}\n\n/**\n * Documents the item test run summary payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the item metadata payload exchanged by command, SDK, and package integrations.\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?: RiskLevel;\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  duplicate_of?: string;\n  plan_mode?: PlanMode;\n  plan_scope?: string;\n  plan_harness?: PlanHarness;\n  plan_steps?: PlanStep[];\n  plan_decisions?: PlanDecision[];\n  plan_discoveries?: PlanDiscovery[];\n  plan_validation?: PlanValidationCheck[];\n  plan_resume_context?: string;\n  [key: string]: unknown;\n}\n\n/**\n * @deprecated Use ItemMetadata.\n */\nexport type ItemFrontMatter = ItemMetadata;\n\n/**\n * Documents the item document payload exchanged by command, SDK, and package integrations.\n */\nexport interface ItemDocument {\n  metadata: ItemMetadata;\n  body: string;\n}\n\n/**\n * Documents the history patch op payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryPatchOp {\n  op: \"add\" | \"remove\" | \"replace\" | \"move\" | \"copy\" | \"test\";\n  path: string;\n  from?: string;\n  value?: unknown;\n}\n\n/**\n * Documents the history entry payload exchanged by command, SDK, and package integrations.\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\", \"full\"] as const;\n/**\n * Restricts context depth values accepted by command, SDK, and storage contracts.\n */\nexport type ContextDepth = (typeof CONTEXT_DEPTH_VALUES)[number];\n\nexport const CONTEXT_SECTION_VALUES = [\n  \"hierarchy\",\n  \"activity\",\n  \"progress\",\n  \"recently_created\",\n  \"unparented\",\n  \"blockers\",\n  \"files\",\n  \"workload\",\n  \"staleness\",\n  \"tests\",\n] as const;\n/**\n * Restricts context section name values accepted by command, SDK, and storage contracts.\n */\nexport type ContextSectionName = (typeof CONTEXT_SECTION_VALUES)[number];\n\n/**\n * Documents the context section settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface ContextSectionSettings {\n  hierarchy: boolean;\n  activity: boolean;\n  progress: boolean;\n  recently_created: boolean;\n  unparented: boolean;\n  blockers: boolean;\n  files: boolean;\n  workload: boolean;\n  staleness: boolean;\n  tests: boolean;\n}\n\n/**\n * Documents the context settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface ContextSettings {\n  default_depth: ContextDepth;\n  activity_limit: number;\n  stale_threshold_days: number;\n  sections: ContextSectionSettings;\n}\n\n/**\n * Documents the governance settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface GovernanceSettings {\n  preset: GovernancePreset;\n  ownership_enforcement: GovernanceOwnershipEnforcement;\n  create_mode_default: GovernanceCreateModeDefault;\n  close_validation_default: GovernanceCloseValidationDefault;\n  require_close_reason: boolean;\n  parent_reference: ParentReferencePolicy;\n  metadata_profile: ValidateMetadataProfile;\n  force_required_for_stale_lock: boolean;\n  create_default_type?: string;\n  /**\n   * Per-type allowed-transition enforcement mode for `pm update --status`.\n   * Read raw from settings (not preset-derived) so existing projects are\n   * unaffected when unset; defaults to \"off\".\n   */\n  workflow_enforcement?: GovernanceWorkflowEnforcement;\n}\n\n/**\n * Restricts extension policy mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionPolicyMode = \"off\" | \"warn\" | \"enforce\";\n/**\n * Restricts extension trust mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionTrustMode = \"off\" | \"warn\" | \"enforce\";\n/**\n * Restricts extension sandbox profile values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionSandboxProfile = \"none\" | \"restricted\" | \"strict\";\n\n/**\n * Documents the extension policy override settings payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the extension policy settings payload exchanged by command, SDK, and package integrations.\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\n/**\n * Documents the agent guidance settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface AgentGuidanceSettings {\n  prompt_completed: boolean;\n  declined: boolean;\n  declined_at: string;\n  template_version: number;\n  last_checked_files: string[];\n}\n\n/**\n * Restricts search mutation refresh policy values accepted by command, SDK, and storage contracts.\n */\nexport type SearchMutationRefreshPolicy = \"cache_only\" | \"semantic_configured\" | \"semantic_auto\";\n\n/**\n * Documents the search query expansion settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchQueryExpansionSettings {\n  enabled: boolean;\n  provider: string;\n}\n\n/**\n * Documents the search rerank settings payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchRerankSettings {\n  enabled: boolean;\n  model: string;\n  top_k: number;\n}\n\n/**\n * Config-driven policy for automatic history-stream compaction triage.\n *\n * When `enabled`, `pm health` surfaces an advisory warning for any history\n * stream whose non-empty entry count exceeds `max_entries`, and `pm\n * history-compact` bulk mode uses `max_entries` as its default `--all-over`\n * threshold so the configured policy drives corpus-wide sweeps. `trigger`\n * records operator intent — both values raise the health advisory; `auto`\n * additionally signals that scheduled/automatic sweeps are expected.\n */\nexport interface HistoryCompactPolicy {\n  enabled: boolean;\n  max_entries: number;\n  trigger: \"health_warn\" | \"auto\";\n}\n\n/**\n * Documents the pm settings payload exchanged by command, SDK, and package integrations.\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  /**\n   * Retention policy for bulk-mutation rollback checkpoints written by\n   * `update-many`/`close-many`. `pm gc --scope checkpoints` prunes checkpoint\n   * files older than `retention_days`; checkpoints with an unparseable\n   * `created_at` are retained (safety-first, mirroring the stale-lock sweep).\n   */\n  checkpoints: {\n    retention_days: number;\n  };\n  output: {\n    default_format: \"toon\" | \"json\";\n  };\n  history: {\n    missing_stream: \"auto_create\" | \"strict_error\";\n    compact_policy: HistoryCompactPolicy;\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     * Per-type default estimates (minutes) used by `pm validate --auto-fix\n     * --fix-scope estimates` to backfill missing `estimated_minutes` (GH-212).\n     * Keys are item type names (case-insensitive); values are positive minutes\n     * that override the built-in defaults. Empty by default.\n     */\n    estimate_defaults_by_type: Record<string, number>;\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  agent_guidance: AgentGuidanceSettings;\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_corpus_max_characters?: number;\n    embedding_batch_size: number;\n    embedding_timeout_ms: number;\n    scanner_max_batch_retries: number;\n    provider?: string;\n    /**\n     * Optional allow-list of corpus field names embedded for semantic search\n     * (see DEFAULT_SEARCH_CORPUS_FIELDS in core/search/corpus.ts). When unset or\n     * empty, the full default field set is used (backward compatible). When set,\n     * only the named fields are embedded — letting teams opt structured signals\n     * (priority, assignee, risk, acceptance_criteria, etc.) in/out for token\n     * efficiency. Changing this re-flags items stale on the next refresh.\n     */\n    corpus_fields?: string[];\n    mutation_refresh_policy: SearchMutationRefreshPolicy;\n    query_expansion: SearchQueryExpansionSettings;\n    rerank: SearchRerankSettings;\n    /**\n     * Offline BM25 lexical-ranking parameters (pm-75k9), applied when\n     * `search.provider` is `bm25` (or auto-selected as the offline fallback) for\n     * semantic/hybrid queries. `k1` controls term-frequency saturation, `b`\n     * controls document-length normalization. Unset → Lucene defaults (1.2/0.75).\n     */\n    bm25?: {\n      k1?: number;\n      b?: number;\n    };\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    collection_name: string;\n    qdrant: {\n      url: string;\n      api_key: string;\n    };\n    lancedb: {\n      path: string;\n    };\n  };\n}\n"],"names":[],"mappings":"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","debugId":"3123775a-c8ad-5339-abf2-f3893145f1e7"}

package/docs/AGENT_GUIDE.md

@@ -189,6 +189,7 @@ Use these defaults unless the task requires otherwise:
 - After switching embedding provider/model, run `pm reindex --mode semantic --full` or `pm reindex --mode hybrid --full` to rebuild vectors completely; `pm reindex --mode keyword` ignores `--full` and now warns when ledger identity drift is detected.
 - `pm normalize --dry-run --json` before lifecycle metadata cleanups.
 - `pm health --check-only` when inspecting repository health without refresh side effects.
+- Mistyped command names get a `Did you mean: <command>?` hint, including typos of the executable shortcut aliases — `pm shwo <id>` suggests `get` (the canonical of `show`/`view`), and `pm comemnt` suggests `comments`.
 
 ## Self-Repair Remediation
 

package/docs/ARCHITECTURE.md

@@ -47,11 +47,15 @@ src/
     item/
     lock/
     output/
+    schema/
     search/
     store/
       front-matter-cache.ts
     test/
+    validate/
     shared/
+  mcp/
+    server.ts
   sdk/
     cli-contracts.ts
     index.ts
@@ -91,13 +95,25 @@ Project tracker root defaults to `.agents/pm/`.
   reminders/
   milestones/
   meetings/
+  plans/
+  stories/
   history/
   locks/
-  index/
+  schema/
+  checkpoints/
+  runtime/
   search/
   extensions/
 ```
 
+Type folders are created on demand: the listing above shows the built-in item
+types plus `stories/`, a representative folder created by a custom or preset
+type. `schema/` holds config-driven customization (`types.json`,
+`statuses.json`, `fields.json`), `checkpoints/` holds bulk-mutation rollback
+snapshots, and `runtime/` holds non-canonical operational state (for example
+background-refresh coordination). The legacy required `index/` directory was
+removed in 2026-05-31 ([pm-yf31](../.agents/pm/issues/pm-yf31.toon)).
+
 Required data:
 
 - item documents under type folders
@@ -106,8 +122,8 @@ Required data:
 
 Optional rebuildable data:
 
-- keyword and vector search cache files
-- generated index metadata
+- keyword and vector search cache files (`search/`)
+- `checkpoints/` and `runtime/` operational state
 
 ## Item Documents
 
@@ -127,7 +143,7 @@ body: |
 
 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:
+Built-in item types (11; confirm at runtime with `pm schema list`):
 
 - `Epic`
 - `Feature`
@@ -139,8 +155,12 @@ Built-in item types:
 - `Reminder`
 - `Milestone`
 - `Meeting`
+- `Plan`
 
-Runtime type resolution merges built-ins, `settings.item_types.definitions`, and extension `registerItemTypes(...)` registrations.
+Runtime type resolution merges built-ins, persisted project schema in
+`.agents/pm/schema/types.json` (`pm schema add-type` / `pm init --type-preset`),
+`settings.item_types.definitions`, and extension `registerItemTypes(...)`
+registrations.
 
 ## Mutation Contract
 
@@ -205,6 +225,43 @@ pm contracts --command create --flags-only --json
 pm help create --json
 ```
 
+### Adding a Command or Flag (Wiring Checklist)
+
+A new command or field-mutating flag touches several registries. Missing one
+produces a silently partial surface (for example a flag that parses on the CLI
+but is absent from `pm contracts`, MCP, or completions). Wire each site that
+applies:
+
+1. **Commander registration** — register the command/flag in the relevant
+   `src/cli/register-*.ts` family module (`register-setup`, `register-list-query`,
+   `register-mutation`, `register-operations`).
+2. **Command module** — implement the handler under `src/cli/commands/` and add
+   it to the `src/cli/commands/index.ts` barrel. The static orphan-modules gate
+   fails on a command module that only the dynamic dispatcher imports, so the
+   barrel export is mandatory.
+3. **Flag contracts** — declare flags in `src/sdk/cli-contracts.ts` (the
+   `*_FLAG_CONTRACTS` registries). Use `list: true` only for comma-list
+   accumulation flags, never for Commander `collect` repeatable flags. Flags that
+   should not appear in the public surface go through the `NO_SURFACE` set.
+4. **MCP exposure** — if the command is agent-callable, add or extend its tool in
+   `src/mcp/tool-definitions.ts` (tool definition plus parameter properties).
+   Shared parameter names (`fields`, `scope`) are owned centrally — prefer a new
+   boolean over overloading a shared enum.
+5. **Option policies** — if the flag participates in `command_option_policies`
+   (provided-set governance), wire it into the command's policy declaration.
+6. **Dependency-audit scope** — field mutations that must be excluded from
+   audit-only update scopes belong in the update command's disallowed list.
+7. **Docs and completions** — document the command in
+   [Command Reference](COMMANDS.md); completion output is generated from the
+   contracts, so confirm `pm completion` reflects the new surface.
+8. **Contract snapshot** — run `pnpm contracts:update` to regenerate
+   `tests/fixtures/contracts/full.json`; the static gate compares against it.
+9. **Coverage** — add focused tests so the new module keeps the corpus at
+   `100/100/100/100` (see [Testing Architecture](#testing-architecture)).
+
+Verify the end-to-end surface with `pm contracts --command <name> --json`,
+`pm help <name> --json`, and the matching MCP tool listing.
+
 ## Telemetry Schema Negotiation
 
 Telemetry preserves wire compatibility through an explicit client/server negotiation split:
@@ -249,6 +306,46 @@ pm reindex --mode hybrid --progress
 pm health --check-only
 ```
 
+## Performance and Startup Latency
+
+`pm-cli` is optimized for the agent loop, where many short commands run back to
+back. The performance model has three layers (the absolute timings below are
+indicative order-of-magnitude figures at the time of writing — treat the relative
+behavior, not the exact milliseconds, as the durable contract):
+
+- **Per-command startup.** After a command-family code split, each handler
+  imports only its own command module rather than the full command barrel, so a
+  read command does not pay for mutation/search modules. On a clean project the
+  dominant remaining cost is Node ESM module resolution (~90ms); this is the last
+  structural startup lever and is tracked under the observability epic.
+- **Reads.** The front-matter cache splits item metadata from body text and skips
+  re-reads of unchanged files, and on-read hooks are skipped when no extension
+  registers one. `pm health` uses a drift-scan verification cache so repeated
+  health checks do not re-hash every history stream.
+- **Mutations.** Mutations are non-blocking: the semantic reindex runs in a
+  detached background worker behind a reindex lock instead of inline embedding,
+  and item-format migration skips already-migrated items rather than re-parsing
+  the whole corpus on every write. This is what keeps `create`/`update` in the
+  hundreds-of-milliseconds range instead of multi-second inline-embed latency.
+
+What dominates latency in a given repository:
+
+- a clean project is fast (~140ms); a large dev repo is slower mainly from many
+  auto-loaded extensions and any inline embedding provider, not from item count.
+- `pm --version` short-circuits before the main entrypoint, so it is **not** a
+  valid probe for command startup cost.
+
+Profiling startup cost:
+
+```bash
+node --cpu-prof --cpu-prof-dir=/tmp/pmprof dist/cli.js list >/dev/null
+pm health --check-only          # drift-scan + telemetry timings
+```
+
+Reindex and embedding remain the heaviest background operations; keep them off
+the synchronous mutation path. See the observability epic
+([pm-5oj5](../.agents/pm/epics/pm-5oj5.toon)) for tracked perf work.
+
 ## Extension Host
 
 Load order:
@@ -292,12 +389,28 @@ node scripts/run-tests.mjs coverage
 
 Linked-test execution also creates sandbox roots and can seed settings/extensions for schema parity. See [Testing](TESTING.md).
 
-Coverage governance is literal all-source under `src/`:
-
-- `vitest.config.ts` coverage include patterns are `src/*.ts` and `src/**/*.ts`.
-- Global thresholds are explicit ratchet baselines for the measured all-source corpus and should only move upward until they reach 100%.
-- Do not maintain a curated include/exclude allowlist for production `src` modules.
-- When a module is hard to test end-to-end (for example CLI orchestration), extract pure logic helpers into small modules and cover those directly instead of weakening thresholds.
+Coverage governance is literal all-source, not a curated allowlist:
+
+- `vitest.config.ts` `coverage.include` is the full ship surface: `src/*.ts`,
+  `src/**/*.ts`, `packages/**/*.ts`, `scripts/*.mjs`, `scripts/**/*.mjs`,
+  `plugins/*.mjs`, `plugins/**/*.mjs`, and the `docs/examples/**/*.{ts,js,mjs}`
+  reference snippets. The only `coverage.exclude` entry is `src/**/*.d.ts`
+  (type-only declarations have no executable lines).
+- Global thresholds are `100/100/100/100` (lines/branches/functions/statements)
+  for the whole measured corpus — there is no per-file ratchet and no per-file
+  `/* c8 ignore */` allowlist for production modules.
+- Adding a new module under any included root automatically pulls it into the
+  gate. There is no include-list to edit; if a new module is genuinely not
+  shippable source (a throwaway script), it belongs outside these roots rather
+  than in a hand-maintained exclude list.
+- When authoring example snippets under `docs/examples/`, import the published
+  SDK by its bare specifier (`@unbrained/pm-cli/sdk`); `vitest.config.ts` aliases
+  that to `src/sdk/index.ts` so the example specs cover without the workspace
+  self-link present in a clean CI install.
+- When a module is hard to test end-to-end (for example CLI orchestration),
+  extract pure logic helpers into small modules and cover those directly instead
+  of weakening thresholds. Run `node scripts/run-tests.mjs coverage` locally to
+  confirm `100/100/100/100` before pushing.
 
 ## Terminal Compatibility
 

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -18,21 +18,11 @@ pm-cli/ (repo root)
 │   │   ├── 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]
+│   ├── commands/            # Slash-command definitions (one .md per /pm-* command)
 │   ├── hooks/
 │   │   ├── hooks.json       # SessionStart hook definition
 │   │   └── session-start.mjs # Injects pm context at session start
-│   ├── agents/
-│   │   └── pm-coordinator.md # Subagent for multi-item coordination
+│   ├── agents/              # Subagent definitions (one .md per coordinator/triage/verification subagent)
 │   ├── scripts/
 │   │   └── pm-mcp-server.mjs # MCP server launcher (repo → npx fallback)
 │   └── README.md            # User-facing installation guide
@@ -186,7 +176,9 @@ After installing the plugin:
 
 | pm-cli version | Plugin version | Claude Code version |
 |---------------|----------------|---------------------|
-| 2026.5.x+ | 1.0.0 | Any current |
+| 2026.5.x+ | 1.x | Any current |
+
+The authoritative plugin version is `plugins/pm-claude/.claude-plugin/plugin.json`; this row stays on the `1.x` major line so it does not drift with each plugin release.
 
 The MCP server uses JSON-RPC 2.0 over stdio with protocol version `2025-06-18`.
 

package/docs/COMMANDS.md

@@ -25,8 +25,9 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 | Family | Commands | Purpose |
 |--------|----------|---------|
 | Bootstrap | `init`, `config`, `health`, `telemetry` | create and inspect tracker setup |
-| Triage | `context`, `search`, `list*`, `aggregate`, `dedupe-audit`*, `dedupe-merge`* | find work and audit decomposition |
+| Triage | `context`, `search`, `eval`, `get`, `list*`, `aggregate`, `dedupe-audit`*, `dedupe-merge`* | find work, read a single item, measure search relevance, and audit decomposition |
 | Lifecycle | `create`, `copy`, `focus`, `claim`, `update`, `append`, `close`, `release`, `delete`, `start-task`, `pause-task`, `close-task` | mutate item state |
+| Bulk | `update-many`, `close-many` | apply one change across a matched, dry-run-previewed set with a rollback checkpoint |
 | Scheduling | `meet`, `event`, `remind` | low-friction Meeting/Event/Reminder creation |
 | Planning | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize` | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization |
 | Logs | `comments`, `notes`, `learnings`, `comments-audit` | record progress and durable context |
@@ -78,6 +79,8 @@ When package-owned commands are unavailable, usage guidance includes an install-
 ```bash
 pm context --limit 10
 pm search "calendar reminder validation" --limit 10
+pm get pm-a1b2                          # read one item; add --fields/--depth for lower-token projections
+pm get pm-a1b2 --tree --tree-depth 2    # item plus its descendant subtree
 pm list-open --type Task --priority 1 --limit 20
 pm list-in-progress --limit 20
 pm aggregate --group-by parent,type --status open
@@ -88,6 +91,7 @@ pm dedupe-merge --keep pm-canonical --close pm-duplicate --dry-run
 ```
 
 Use `context` first for a compact active-work snapshot. Use `search` when the request names a concept, component, or prior issue.
+Use `pm get <id>` to read a single item by ID — the single-item read primitive used throughout the agent loop. It accepts `--fields <list>` and `--depth brief|standard|deep|full` for token-minimal projections, and `--tree`/`--tree-depth <n>` to include descendants. `pm get <id> --json` returns the `body` inside the `item` object (`.item.body`); see [Full results, totals, and bodies](#full-results-totals-and-bodies). To duplicate an existing item as a starting point, `pm copy <id> --title "New title"` clones it into a fresh id with lifecycle fields reset.
 `context` standard/deep views include high-level child completion counters plus `recently_created` and `unparented` sections, so agents can spot new orphan work before creating duplicates.
 Use `pm aggregate --completion` when you need per-group `open`, `in_progress`, `closed`, `other`, and `completion_pct` progress context.
 Each aggregate row carries an explicit `group_label`: a blank/null group value (e.g. unassigned items under `--group-by assignee`) renders as `(unassigned)`/`(untagged)`/`(unparented)` rather than an ambiguous empty key, while the structured `group` value keeps the raw `null` for machine consumers. Multi-field grouping joins each `field=value` pair into the label.
@@ -111,11 +115,14 @@ pm list-all --updated-after 2026-06-04T15:18:32Z --brief
 pm list-open --updated-after=-2h --brief
 pm list-all --created-after=-7d --status open
 
-# Search scoped to open work only (drops closed-history noise); statuses are
-# open/closed/canceled aliases or configured ids, comma-separated, with a
-# did-you-mean hint on typos.
+# Search scoped to open work only (drops closed-history noise); statuses accept
+# all (no lifecycle restriction), open/closed/canceled aliases, or configured
+# ids, comma-separated, with a did-you-mean hint on typos.
 pm search "reminder validation" --status open --limit 10
 
+# Duplicate checks can deliberately scan every lifecycle bucket with one flag.
+pm search "reminder validation" --status all --limit 10
+
 # Full filter parity with list — scope retrieval before ranking.
 pm search "calendar" --type Task --assignee alice --updated-after=-7d --parent pm-abcd
 ```
@@ -159,6 +166,47 @@ pm search "auth" --highlight                       # adds highlights:[{field,sni
 pm search "auth" --full --highlight                # full hit payloads + highlight snippets
 ```
 
+### Offline BM25 provider (pm-75k9)
+
+`semantic`/`hybrid` search normally needs an embedding service (Ollama/OpenAI) plus a vector store. For air-gapped, CI, or zero-setup environments there is a built-in **BM25** lexical ranker that runs entirely in-process over the item corpus — no network, no service. BM25 improves on naive keyword counting with inverse-document-frequency weighting, term-frequency saturation, and document-length normalization.
+
+Activate it by setting the search provider:
+
+```bash
+pm config project set search_provider bm25      # always use offline BM25 for semantic/hybrid
+pm config project set search_provider auto       # use BM25 only when no embedding provider is configured
+pm search "connection pool leak" --semantic       # BM25-ranked; hits carry matched_fields:["bm25"]
+pm search "retry backoff" --hybrid                 # blends BM25 with the keyword scorer
+```
+
+- `bm25` — always use BM25 for `--semantic`/`--hybrid`, even if an embedding provider is configured.
+- `auto` — use BM25 as the **offline fallback** only when no embedding provider (and no extension search provider) is available; the result carries a `search_<mode>_offline_bm25:no_embedding_provider:using_lexical_bm25` warning so the offline path is observable.
+- Plain `keyword` mode is unchanged. BM25 quality is lexical — strong, but below true dense retrieval; configure an embedding provider when you need semantic similarity.
+
+Tune ranking via `search.bm25.k1` (term-frequency saturation, default `1.2`) and `search.bm25.b` (length normalization in `[0,1]`, default `0.75`): `pm config project set search_bm25_k1 1.5`.
+
+### Search relevance evaluation — `pm eval` (pm-u8n5)
+
+`pm eval` measures retrieval quality against a curated golden-query set so relevance regressions (from corpus, weight, or provider changes) are caught instead of guessed. Ground truth lives in a git-tracked `<pmRoot>/search/eval-queries.json` — an array of `{ query, relevant_ids, mode? }` objects:
+
+```json
+[
+  { "query": "offline search ranking", "relevant_ids": ["pm-75k9"], "mode": "keyword" },
+  { "query": "relevance regression gate", "relevant_ids": ["pm-u8n5"] }
+]
+```
+
+It runs each query through the live search path and reports nDCG@k, MRR@k, precision@k, and recall@k per query plus the macro average:
+
+```bash
+pm eval --json                       # full per-query + aggregate metrics
+pm eval --mode hybrid --k 10         # default mode for queries without their own; cutoff @k
+pm eval --queries ./my-eval.json     # evaluate an alternate golden set
+pm eval --fail-under 0.6 --json      # CI gate: exit non-zero when aggregate nDCG@k < 0.6
+```
+
+`--fail-under <0..1>` turns `pm eval` into a CI gate: it still prints the report (stdout) but exits non-zero when the aggregate nDCG@k falls below the threshold, so a relevance drop fails the build.
+
 ### Full results, totals, and bodies
 
 `pm list*` returns every matched row when neither `--limit` nor `--offset` is set. When a `--limit`/`--offset` *does* drop rows, the result adds a top-level `total` (the pre-pagination match count) so an agent knows how many remain. Pass `--no-truncate` (alias `--all`) to force the entire matched set and override any `--limit` in one call — the canonical "give me everything" flag for large-corpus audits:
@@ -547,7 +595,9 @@ pm gc --scope locks --dry-run
 
 Use dry-run modes before broad lifecycle or cleanup changes.
 
-`pm gc` accepts `--scope` values `index`, `embeddings`, `runtime`, and `locks` (comma-separated or repeatable); with no `--scope` it sweeps all of them. The `runtime` scope clears `runtime/test-runs/` and `runtime/history-drift-cache.json`; removing the drift cache forces the next `pm health` run to perform a full history-drift re-scan. The `locks` scope removes only **expired** lock files in `locks/` — those whose own embedded `created_at + ttl_seconds` has elapsed (debris left by crashed processes). Active locks and any lock file that cannot be parsed are always retained (never deleted when staleness cannot be proven), and the result includes a `locks` summary (`scanned`/`removed`/`retained`).
+`pm gc` accepts `--scope` values `index`, `embeddings`, `runtime`, `locks`, and `checkpoints` (comma-separated or repeatable); with no `--scope` it sweeps all of them. The `runtime` scope clears `runtime/test-runs/` and `runtime/history-drift-cache.json`; removing the drift cache forces the next `pm health` run to perform a full history-drift re-scan. The `embeddings` scope removes the keyword/semantic index artifacts (`search/embeddings.jsonl`, `search/vectorization-status.json`, `search/lancedb/`) **and** the background-refresh queue (`search/pending-refresh.json`) and its gate so a worker draining a stale queue cannot rebuild a partial index against an empty ledger; it invalidates the entire semantic index, so run `pm reindex --mode keyword` (and `--mode semantic` when enabled) afterwards. The `locks` scope removes only **expired** lock files in `locks/` — those whose own embedded `created_at + ttl_seconds` has elapsed (debris left by crashed processes). Active locks and any lock file that cannot be parsed are always retained (never deleted when staleness cannot be proven), and the result includes a `locks` summary (`scanned`/`removed`/`retained`).
+
+The `checkpoints` scope prunes bulk-mutation rollback checkpoints under `checkpoints/` (written by `pm update-many`/`pm close-many`) that are older than `checkpoints.retention_days` (default 14; set via `pm config <scope> set checkpoints_retention_days <n>`). Checkpoints whose `created_at` cannot be parsed are retained (safety-first, like the locks sweep), and the result includes a `checkpoints` summary (`scanned`/`removed`/`retained`/`retention_days`). Removing aged checkpoints permanently closes their `--rollback` window.
 
 `--fix-hints` is a read-only flag: each failing check gains `details.fix_hints`, an array of `pm` command templates derived from the warning codes it raised (for example `pm history-repair <id>` for history drift, or `pm update <id> --reviewer "<name>"` for a missing reviewer). Generic hints may contain `<id>`/`<field>`/`<path>` placeholders the agent substitutes from the check's detail rows; the resolution check aliases concrete per-row commands and marks `fix_hints_truncated` when the list is summarized. It never mutates items. The mapping comes from the shared remediation registry that also backs `pm health --json` (see Self-Repair Remediation below), so agents gating on `pm validate` can auto-repair findings without hardcoding warning-code-to-command lookups.