@unbrained/pm-cli 2026.7.19 → 2026.7.20

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 */\n/** Supported values accepted by the builtin item type contract. */\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;\n/** Supported values accepted by the item type contract. */\nexport const ITEM_TYPE_VALUES = BUILTIN_ITEM_TYPE_VALUES;\n/** Restricts builtin item type values accepted by command, SDK, and storage contracts. */\nexport type BuiltinItemType = (typeof BUILTIN_ITEM_TYPE_VALUES)[number];\n/** Restricts item type values accepted by command, SDK, and storage contracts. */\nexport type ItemType = string;\n\n/** Supported values accepted by the status contract. */\nexport const STATUS_VALUES = [\n  \"draft\",\n  \"open\",\n  \"in_progress\",\n  \"blocked\",\n  \"closed\",\n  \"canceled\",\n] as const;\n/** Restricts item status values accepted by command, SDK, and storage contracts. */\nexport type ItemStatus = string;\n\n/** Supported values accepted by the runtime status role contract. */\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/** Restricts runtime status role values accepted by command, SDK, and storage contracts. */\nexport type RuntimeStatusRole = (typeof RUNTIME_STATUS_ROLE_VALUES)[number];\n\n/** Supported values accepted by the runtime field type contract. */\nexport const RUNTIME_FIELD_TYPE_VALUES = [\n  \"string\",\n  \"number\",\n  \"boolean\",\n  \"string_array\",\n] as const;\n/** Restricts runtime field type values accepted by command, SDK, and storage contracts. */\nexport type RuntimeFieldType = (typeof RUNTIME_FIELD_TYPE_VALUES)[number];\n\n/** Supported values accepted by the runtime field command contract. */\nexport const RUNTIME_FIELD_COMMAND_VALUES = [\n  \"create\",\n  \"update\",\n  \"update_many\",\n  \"list\",\n  \"search\",\n  \"calendar\",\n  \"context\",\n] as const;\n/** Restricts runtime field command values accepted by command, SDK, and storage contracts. */\nexport type RuntimeFieldCommand = (typeof RUNTIME_FIELD_COMMAND_VALUES)[number];\n\n/** Supported values accepted by the runtime unknown field policy contract. */\nexport const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES = [\n  \"allow\",\n  \"warn\",\n  \"reject\",\n] as const;\n/** Restricts runtime unknown field policy values accepted by command, SDK, and storage contracts. */\nexport type RuntimeUnknownFieldPolicy =\n  (typeof RUNTIME_UNKNOWN_FIELD_POLICY_VALUES)[number];\n\n/** Supported values accepted by the dependency kind contract. */\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/** Restricts dependency kind values accepted by command, SDK, and storage contracts. */\nexport type DependencyKind = (typeof DEPENDENCY_KIND_VALUES)[number];\n\n/** Supported values accepted by the scope contract. */\nexport const SCOPE_VALUES = [\"project\", \"global\"] as const;\n/** Restricts link scope values accepted by command, SDK, and storage contracts. */\nexport type LinkScope = (typeof SCOPE_VALUES)[number];\n\n/** Supported values accepted by the risk contract. */\nexport const RISK_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\n/** Restricts risk level values accepted by command, SDK, and storage contracts. */\nexport type RiskLevel = (typeof RISK_VALUES)[number];\n\n/** Supported values accepted by the issue severity contract. */\nexport const ISSUE_SEVERITY_VALUES = [\n  \"low\",\n  \"medium\",\n  \"high\",\n  \"critical\",\n] as const;\n/** Restricts issue severity values accepted by command, SDK, and storage contracts. */\nexport type IssueSeverity = (typeof ISSUE_SEVERITY_VALUES)[number];\n\n/** Supported values accepted by the confidence text contract. */\nexport const CONFIDENCE_TEXT_VALUES = [\"low\", \"medium\", \"high\"] as const;\n/** Restricts confidence text level values accepted by command, SDK, and storage contracts. */\nexport type ConfidenceTextLevel = (typeof CONFIDENCE_TEXT_VALUES)[number];\n/** Restricts confidence value values accepted by command, SDK, and storage contracts. */\nexport type ConfidenceValue = number | ConfidenceTextLevel;\n\n/** Supported values accepted by the item format contract. */\nexport const ITEM_FORMAT_VALUES = [\"toon\", \"json_markdown\"] as const;\n/** Restricts item format values accepted by command, SDK, and storage contracts. */\nexport type ItemFormat = (typeof ITEM_FORMAT_VALUES)[number];\n\n/** Supported values accepted by the sprint release format policy contract. */\nexport const SPRINT_RELEASE_FORMAT_POLICY_VALUES = [\n  \"warn\",\n  \"strict_error\",\n] as const;\n/** Restricts sprint release format policy values accepted by command, SDK, and storage contracts. */\nexport type SprintReleaseFormatPolicy =\n  (typeof SPRINT_RELEASE_FORMAT_POLICY_VALUES)[number];\n/** Supported values accepted by the parent reference policy contract. */\nexport const PARENT_REFERENCE_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\n/** Restricts parent reference policy values accepted by command, SDK, and storage contracts. */\nexport type ParentReferencePolicy =\n  (typeof PARENT_REFERENCE_POLICY_VALUES)[number];\n/** Supported values accepted by the validate metadata profile contract. */\nexport const VALIDATE_METADATA_PROFILE_VALUES = [\n  \"core\",\n  \"strict\",\n  \"custom\",\n] as const;\n/** Restricts validate metadata profile values accepted by command, SDK, and storage contracts. */\nexport type ValidateMetadataProfile =\n  (typeof VALIDATE_METADATA_PROFILE_VALUES)[number];\n/** Supported values accepted by the governance preset contract. */\nexport const GOVERNANCE_PRESET_VALUES = [\n  \"minimal\",\n  \"default\",\n  \"strict\",\n  \"custom\",\n] as const;\n/** Restricts governance preset values accepted by command, SDK, and storage contracts. */\nexport type GovernancePreset = (typeof GOVERNANCE_PRESET_VALUES)[number];\n/** Supported values accepted by the governance ownership enforcement contract. */\nexport const GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES = [\n  \"none\",\n  \"warn\",\n  \"strict\",\n] as const;\n/** Restricts governance ownership enforcement values accepted by command, SDK, and storage contracts. */\nexport type GovernanceOwnershipEnforcement =\n  (typeof GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES)[number];\n/** Supported values accepted by the governance create mode default contract. */\nexport const GOVERNANCE_CREATE_MODE_DEFAULT_VALUES = [\n  \"progressive\",\n  \"strict\",\n] as const;\n/** Restricts governance create mode default values accepted by command, SDK, and storage contracts. */\nexport type GovernanceCreateModeDefault =\n  (typeof GOVERNANCE_CREATE_MODE_DEFAULT_VALUES)[number];\n/** Supported values accepted by the governance close validation default contract. */\nexport const GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES = [\n  \"off\",\n  \"warn\",\n  \"strict\",\n] as const;\n/** Restricts governance close validation default values accepted by command, SDK, and storage contracts. */\nexport type GovernanceCloseValidationDefault =\n  (typeof GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES)[number];\n/** Supported values accepted by the governance workflow enforcement contract. */\nexport const GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES = [\n  \"off\",\n  \"warn\",\n  \"strict\",\n] as const;\n/** Restricts governance workflow enforcement values accepted by command, SDK, and storage contracts. */\nexport type GovernanceWorkflowEnforcement =\n  (typeof GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES)[number];\n/** Supported values accepted by the validate metadata required field contract. */\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/** Restricts validate metadata required field values accepted by command, SDK, and storage contracts. */\nexport type ValidateMetadataRequiredField =\n  (typeof VALIDATE_METADATA_REQUIRED_FIELD_VALUES)[number];\n\n/** Supported values accepted by the recurrence frequency contract. */\nexport const RECURRENCE_FREQUENCY_VALUES = [\n  \"daily\",\n  \"weekly\",\n  \"monthly\",\n  \"yearly\",\n] as const;\n/** Restricts recurrence frequency values accepted by command, SDK, and storage contracts. */\nexport type RecurrenceFrequency = (typeof RECURRENCE_FREQUENCY_VALUES)[number];\n\n/** Supported values accepted by the recurrence weekday contract. */\nexport const RECURRENCE_WEEKDAY_VALUES = [\n  \"mon\",\n  \"tue\",\n  \"wed\",\n  \"thu\",\n  \"fri\",\n  \"sat\",\n  \"sun\",\n] as const;\n/** Restricts recurrence weekday values accepted by command, SDK, and storage contracts. */\nexport type RecurrenceWeekday = (typeof RECURRENCE_WEEKDAY_VALUES)[number];\n\n/** Canonical week-order index for a recurrence weekday (mon=0 .. sun=6). Shared by item serialization, create/update parsing, and calendar expansion so weekday ordering cannot drift between those modules. */\nexport function weekdayOrderIndex(value: RecurrenceWeekday): number {\n  return RECURRENCE_WEEKDAY_VALUES.indexOf(value);\n}\n\n/** Documents the dependency payload exchanged by command, SDK, and package integrations. */\nexport interface Dependency {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports kind for this contract. */\n  kind: DependencyKind;\n  /** ISO 8601 timestamp recording when created occurred. */\n  created_at: string;\n  /** Value that configures or reports author for this contract. */\n  author?: string;\n  /** Value that configures or reports source kind for this contract. */\n  source_kind?: string;\n}\n\n/** Documents the comment payload exchanged by command, SDK, and package integrations. */\nexport interface Comment {\n  /** ISO 8601 timestamp recording when created occurred. */\n  created_at: string;\n  /** Value that configures or reports author for this contract. */\n  author: string;\n  /** Value that configures or reports text for this contract. */\n  text: string;\n}\n\n/** Documents the log note payload exchanged by command, SDK, and package integrations. */\nexport interface LogNote {\n  /** ISO 8601 timestamp recording when created occurred. */\n  created_at: string;\n  /** Value that configures or reports author for this contract. */\n  author: string;\n  /** Value that configures or reports text for this contract. */\n  text: string;\n}\n\n/** Documents the linked file payload exchanged by command, SDK, and package integrations. */\nexport interface LinkedFile {\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports scope for this contract. */\n  scope: LinkScope;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n}\n\n/** Documents the linked test payload exchanged by command, SDK, and package integrations. */\nexport interface LinkedTest {\n  /** Value that configures or reports command for this contract. */\n  command?: string;\n  /** Filesystem path used for path resolution. */\n  path?: string;\n  /** Value that configures or reports scope for this contract. */\n  scope: LinkScope;\n  /** Value that configures or reports timeout seconds for this contract. */\n  timeout_seconds?: number;\n  /** Strategy used to control pm context behavior. */\n  pm_context_mode?: \"schema\" | \"tracker\" | \"auto\";\n  /** Value that configures or reports env set for this contract. */\n  env_set?: Record<string, string>;\n  /** Value that configures or reports env clear for this contract. */\n  env_clear?: string[];\n  /** Value that configures or reports shared host safe for this contract. */\n  shared_host_safe?: boolean;\n  /** Value that configures or reports assert stdout contains for this contract. */\n  assert_stdout_contains?: string[];\n  /** Value that configures or reports assert stdout regex for this contract. */\n  assert_stdout_regex?: string[];\n  /** Value that configures or reports assert stderr contains for this contract. */\n  assert_stderr_contains?: string[];\n  /** Value that configures or reports assert stderr regex for this contract. */\n  assert_stderr_regex?: string[];\n  /** Value that configures or reports assert stdout min lines for this contract. */\n  assert_stdout_min_lines?: number;\n  /** Value that configures or reports assert json field equals for this contract. */\n  assert_json_field_equals?: Record<string, string>;\n  /** Value that configures or reports assert json field gte for this contract. */\n  assert_json_field_gte?: Record<string, number>;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n}\n\n/** Documents the linked doc payload exchanged by command, SDK, and package integrations. */\nexport interface LinkedDoc {\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports scope for this contract. */\n  scope: LinkScope;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n}\n\n/** Documents the reminder payload exchanged by command, SDK, and package integrations. */\nexport interface Reminder {\n  /** Value that configures or reports at for this contract. */\n  at: string;\n  /** Value that configures or reports text for this contract. */\n  text: string;\n}\n\n/** Documents the recurrence rule payload exchanged by command, SDK, and package integrations. */\nexport interface RecurrenceRule {\n  /** Value that configures or reports freq for this contract. */\n  freq: RecurrenceFrequency;\n  /** Value that configures or reports interval for this contract. */\n  interval?: number;\n  /** Value that configures or reports count for this contract. */\n  count?: number;\n  /** Value that configures or reports until for this contract. */\n  until?: string;\n  /** Value that configures or reports by weekday for this contract. */\n  by_weekday?: RecurrenceWeekday[];\n  /** Value that configures or reports by month day for this contract. */\n  by_month_day?: number[];\n  /** Value that configures or reports exdates for this contract. */\n  exdates?: string[];\n}\n\n/** Documents the calendar event payload exchanged by command, SDK, and package integrations. */\nexport interface CalendarEvent {\n  /** ISO 8601 timestamp recording when start occurred. */\n  start_at: string;\n  /** ISO 8601 timestamp recording when end occurred. */\n  end_at?: string;\n  /** Value that configures or reports title for this contract. */\n  title?: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Value that configures or reports location for this contract. */\n  location?: string;\n  /** Value that configures or reports all day for this contract. */\n  all_day?: boolean;\n  /** Value that configures or reports timezone for this contract. */\n  timezone?: string;\n  /** Value that configures or reports recurrence for this contract. */\n  recurrence?: RecurrenceRule;\n}\n\n/** Supported values accepted by the plan mode contract. */\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/** Restricts plan mode values accepted by command, SDK, and storage contracts. */\nexport type PlanMode = (typeof PLAN_MODE_VALUES)[number];\n\n/** Supported values accepted by the plan step status contract. */\nexport const PLAN_STEP_STATUS_VALUES = [\n  \"pending\",\n  \"in_progress\",\n  \"completed\",\n  \"blocked\",\n  \"skipped\",\n  \"superseded\",\n] as const;\n/** Restricts plan step status values accepted by command, SDK, and storage contracts. */\nexport type PlanStepStatus = (typeof PLAN_STEP_STATUS_VALUES)[number];\n\n/** Supported values accepted by the plan harness contract. */\nexport const PLAN_HARNESS_VALUES = [\n  \"codex\",\n  \"claude-code\",\n  \"cursor\",\n  \"generic\",\n] as const;\n/** Restricts plan harness values accepted by command, SDK, and storage contracts. */\nexport type PlanHarness = (typeof PLAN_HARNESS_VALUES)[number];\n\n/** Supported values accepted by the plan step link kind contract. */\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/** Restricts plan step link kind values accepted by command, SDK, and storage contracts. */\nexport type PlanStepLinkKind = (typeof PLAN_STEP_LINK_KIND_VALUES)[number];\n\n/** Documents the plan step link payload exchanged by command, SDK, and package integrations. */\nexport interface PlanStepLink {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports kind for this contract. */\n  kind: PlanStepLinkKind;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n  /** Value that configures or reports required before step for this contract. */\n  required_before_step?: boolean;\n}\n\n/** Documents the plan step file payload exchanged by command, SDK, and package integrations. */\nexport interface PlanStepFile {\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports scope for this contract. */\n  scope?: LinkScope;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n}\n\n/** Documents the plan step test payload exchanged by command, SDK, and package integrations. */\nexport interface PlanStepTest {\n  /** Value that configures or reports command for this contract. */\n  command?: string;\n  /** Filesystem path used for path resolution. */\n  path?: string;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n}\n\n/** Documents the plan step doc payload exchanged by command, SDK, and package integrations. */\nexport interface PlanStepDoc {\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports scope for this contract. */\n  scope?: LinkScope;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n}\n\n/** Documents the plan step payload exchanged by command, SDK, and package integrations. */\nexport interface PlanStep {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports order for this contract. */\n  order: number;\n  /** Value that configures or reports title for this contract. */\n  title: string;\n  /** Value that configures or reports body for this contract. */\n  body?: string;\n  /** Lifecycle state reported for status. */\n  status: PlanStepStatus;\n  /** Value that configures or reports owner for this contract. */\n  owner?: string;\n  /** Value that configures or reports evidence for this contract. */\n  evidence?: string;\n  /** Value that configures or reports blocked reason for this contract. */\n  blocked_reason?: string;\n  /** Value that configures or reports superseded by for this contract. */\n  superseded_by?: string;\n  /** Value that configures or reports linked items for this contract. */\n  linked_items?: PlanStepLink[];\n  /** Value that configures or reports files for this contract. */\n  files?: PlanStepFile[];\n  /** Value that configures or reports tests for this contract. */\n  tests?: PlanStepTest[];\n  /** Value that configures or reports docs for this contract. */\n  docs?: PlanStepDoc[];\n  /** ISO 8601 timestamp recording when created occurred. */\n  created_at: string;\n  /** ISO 8601 timestamp recording when updated occurred. */\n  updated_at: string;\n  /** ISO 8601 timestamp recording when completed occurred. */\n  completed_at?: string;\n}\n\n/** Documents the plan decision payload exchanged by command, SDK, and package integrations. */\nexport interface PlanDecision {\n  /** Value that configures or reports ts for this contract. */\n  ts: string;\n  /** Value that configures or reports author for this contract. */\n  author: string;\n  /** Value that configures or reports decision for this contract. */\n  decision: string;\n  /** Value that configures or reports rationale for this contract. */\n  rationale?: string;\n  /** Value that configures or reports evidence for this contract. */\n  evidence?: string;\n  /** Value that configures or reports step id for this contract. */\n  step_id?: string;\n}\n\n/** Documents the plan discovery payload exchanged by command, SDK, and package integrations. */\nexport interface PlanDiscovery {\n  /** Value that configures or reports ts for this contract. */\n  ts: string;\n  /** Value that configures or reports author for this contract. */\n  author: string;\n  /** Value that configures or reports text for this contract. */\n  text: string;\n  /** Value that configures or reports step id for this contract. */\n  step_id?: string;\n}\n\n/** Documents the plan validation check payload exchanged by command, SDK, and package integrations. */\nexport interface PlanValidationCheck {\n  /** Value that configures or reports text for this contract. */\n  text: string;\n  /** Value that configures or reports command for this contract. */\n  command?: string;\n  /** Value that configures or reports expected for this contract. */\n  expected?: string;\n}\n\n/** Documents the item type option definition payload exchanged by command, SDK, and package integrations. */\nexport interface ItemTypeOptionDefinition {\n  /** Value that configures or reports key for this contract. */\n  key: string;\n  /** Value that configures or reports values for this contract. */\n  values: string[];\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Value that configures or reports aliases for this contract. */\n  aliases?: string[];\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n}\n\n/** Documents the item type command option policy payload exchanged by command, SDK, and package integrations. */\nexport interface ItemTypeCommandOptionPolicy {\n  /** Value that configures or reports command for this contract. */\n  command: \"create\" | \"update\";\n  /** Value that configures or reports option for this contract. */\n  option: string;\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Value that configures or reports visible for this contract. */\n  visible?: boolean;\n  /** Whether enabled applies to this operation. */\n  enabled?: boolean;\n}\n\n/** Documents the item type definition payload exchanged by command, SDK, and package integrations. */\nexport interface ItemTypeDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Status assigned to newly created items of this type when `--status` is not provided. Falls back to the workflow's open status when unset or invalid. */\n  default_status?: string;\n  /** Value that configures or reports folder for this contract. */\n  folder?: string;\n  /** Value that configures or reports aliases for this contract. */\n  aliases?: string[];\n  /** Value that configures or reports required create fields for this contract. */\n  required_create_fields?: string[];\n  /** Value that configures or reports required create repeatables for this contract. */\n  required_create_repeatables?: string[];\n  /** Value that configures or reports options for this contract. */\n  options?: ItemTypeOptionDefinition[];\n  /** Value that configures or reports command option policies for this contract. */\n  command_option_policies?: ItemTypeCommandOptionPolicy[];\n}\n\n/** Documents the runtime status definition payload exchanged by command, SDK, and package integrations. */\nexport interface RuntimeStatusDefinition {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports aliases for this contract. */\n  aliases?: string[];\n  /** Value that configures or reports roles for this contract. */\n  roles?: RuntimeStatusRole[];\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Value that configures or reports order for this contract. */\n  order?: number;\n}\n\n/** Documents the runtime field definition payload exchanged by command, SDK, and package integrations. */\nexport interface RuntimeFieldDefinition {\n  /** Value that configures or reports key for this contract. */\n  key: string;\n  /** Value that configures or reports metadata key for this contract. */\n  metadata_key?: string;\n  /**\n   * @deprecated Use metadata_key.\n   */\n  front_matter_key?: string;\n  /** Value that configures or reports cli flag for this contract. */\n  cli_flag?: string;\n  /** Value that configures or reports cli aliases for this contract. */\n  cli_aliases?: string[];\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Schema type that determines the shape and validation rules for this value. */\n  type?: RuntimeFieldType;\n  /** Value that configures or reports commands for this contract. */\n  commands?: RuntimeFieldCommand[];\n  /** Value that configures or reports repeatable for this contract. */\n  repeatable?: boolean;\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Value that configures or reports required on create for this contract. */\n  required_on_create?: boolean;\n  /** Value that configures or reports required types for this contract. */\n  required_types?: string[];\n  /** Value that configures or reports allow unset for this contract. */\n  allow_unset?: boolean;\n}\n\n/** Documents the runtime workflow definition payload exchanged by command, SDK, and package integrations. */\nexport interface RuntimeWorkflowDefinition {\n  /** Lifecycle state reported for draftthe record. */\n  draft_status?: string;\n  /** Lifecycle state reported for openthe record. */\n  open_status?: string;\n  /** Lifecycle state reported for in progressthe record. */\n  in_progress_status?: string;\n  /** Lifecycle state reported for blockedthe record. */\n  blocked_status?: string;\n  /** Lifecycle state reported for closethe record. */\n  close_status?: string;\n  /** Lifecycle state reported for canceledthe record. */\n  canceled_status?: string;\n}\n\n/** Documents the runtime schema file config payload exchanged by command, SDK, and package integrations. */\nexport interface RuntimeSchemaFileConfig {\n  /** Value that configures or reports types for this contract. */\n  types?: string;\n  /** Value that configures or reports statuses for this contract. */\n  statuses?: string;\n  /** Value that configures or reports fields for this contract. */\n  fields?: string;\n  /** Value that configures or reports workflows for this contract. */\n  workflows?: string;\n}\n\n/** Per-type allowed-transition rule. A type with no matching entry is unrestricted; a type with an entry allows only the listed [from, to] status pairs (status tokens are resolved case-insensitively through the status registry alias map; a same-status no-op is always allowed). */\nexport interface TypeWorkflowDefinition {\n  /** Schema type that determines the shape and validation rules for this value. */\n  type: string;\n  /** Value that configures or reports allowed transitions for this contract. */\n  allowed_transitions: [string, string][];\n}\n\n/** Documents the runtime schema settings payload exchanged by command, SDK, and package integrations. */\nexport interface RuntimeSchemaSettings {\n  /** Value that configures or reports version for this contract. */\n  version: number;\n  /** Value that configures or reports files for this contract. */\n  files: RuntimeSchemaFileConfig;\n  /** Value that configures or reports statuses for this contract. */\n  statuses: RuntimeStatusDefinition[];\n  /** Value that configures or reports fields for this contract. */\n  fields: RuntimeFieldDefinition[];\n  /** Value that configures or reports workflow for this contract. */\n  workflow: RuntimeWorkflowDefinition;\n  /** Value that configures or reports type workflows for this contract. */\n  type_workflows?: TypeWorkflowDefinition[];\n  /** Value that configures or reports unknown field policy for this contract. */\n  unknown_field_policy: RuntimeUnknownFieldPolicy;\n}\n\n/** Documents the item test run summary payload exchanged by command, SDK, and package integrations. */\nexport interface ItemTestRunSummary {\n  /** Executes the id operation through the package runtime. */\n  run_id: string;\n  /** Value that configures or reports kind for this contract. */\n  kind: \"test\" | \"test-all\";\n  /** Lifecycle state reported for status. */\n  status: \"passed\" | \"failed\" | \"stopped\" | \"canceled\";\n  /** ISO 8601 timestamp recording when started occurred. */\n  started_at: string;\n  /** ISO 8601 timestamp recording when finished occurred. */\n  finished_at: string;\n  /** ISO 8601 timestamp recording when recorded occurred. */\n  recorded_at: string;\n  /** Value that configures or reports attempt for this contract. */\n  attempt?: number;\n  /** Value that configures or reports resumed from for this contract. */\n  resumed_from?: string;\n  /** Value that configures or reports passed for this contract. */\n  passed: number;\n  /** Value that configures or reports failed for this contract. */\n  failed: number;\n  /** Value that configures or reports skipped for this contract. */\n  skipped: number;\n  /** Value that configures or reports items for this contract. */\n  items?: number;\n  /** Value that configures or reports linked tests for this contract. */\n  linked_tests?: number;\n  /** Value that configures or reports fail on skipped triggered for this contract. */\n  fail_on_skipped_triggered?: boolean;\n}\n\n/** Documents the item metadata payload exchanged by command, SDK, and package integrations. */\nexport interface ItemMetadata {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports title for this contract. */\n  title: string;\n  /** Value that configures or reports description for this contract. */\n  description: string;\n  /** Schema type that determines the shape and validation rules for this value. */\n  type: ItemType;\n  /** On-disk item-metadata format version. Absent means the implicit baseline (version 1) and is never serialized; populated only once an item advances past the baseline via a future storage migration. See core/item/item-format-version. */\n  pm_format_version?: number;\n  /** Schema type that determines the shape and validation rules for this value. */\n  source_type?: string;\n  /** Inputs that customize the type operation. */\n  type_options?: Record<string, string>;\n  /** Lifecycle state reported for status. */\n  status: ItemStatus;\n  /** Value that configures or reports priority for this contract. */\n  priority: 0 | 1 | 2 | 3 | 4;\n  /** Value that configures or reports tags for this contract. */\n  tags: string[];\n  /** ISO 8601 timestamp recording when created occurred. */\n  created_at: string;\n  /** ISO 8601 timestamp recording when updated occurred. */\n  updated_at: string;\n  /** Value that configures or reports deadline for this contract. */\n  deadline?: string;\n  /** Value that configures or reports reminders for this contract. */\n  reminders?: Reminder[];\n  /** Value that configures or reports events for this contract. */\n  events?: CalendarEvent[];\n  /** ISO 8601 timestamp recording when closed occurred. */\n  closed_at?: string;\n  /** Value that configures or reports assignee for this contract. */\n  assignee?: string;\n  /** Value that configures or reports source owner for this contract. */\n  source_owner?: string;\n  /** Value that configures or reports author for this contract. */\n  author?: string;\n  /** Value that configures or reports estimated minutes for this contract. */\n  estimated_minutes?: number;\n  /** Value that configures or reports acceptance criteria for this contract. */\n  acceptance_criteria?: string;\n  /** Value that configures or reports design for this contract. */\n  design?: string;\n  /** Value that configures or reports external ref for this contract. */\n  external_ref?: string;\n  /** Value that configures or reports definition of ready for this contract. */\n  definition_of_ready?: string;\n  /** Value that configures or reports order for this contract. */\n  order?: number;\n  /** Value that configures or reports goal for this contract. */\n  goal?: string;\n  /** Value that configures or reports objective for this contract. */\n  objective?: string;\n  /** Value that configures or reports value for this contract. */\n  value?: string;\n  /** Value that configures or reports impact for this contract. */\n  impact?: string;\n  /** Value that configures or reports outcome for this contract. */\n  outcome?: string;\n  /** Value that configures or reports why now for this contract. */\n  why_now?: string;\n  /** Value that configures or reports parent for this contract. */\n  parent?: string;\n  /** Value that configures or reports reviewer for this contract. */\n  reviewer?: string;\n  /** Value that configures or reports risk for this contract. */\n  risk?: RiskLevel;\n  /** Value that configures or reports confidence for this contract. */\n  confidence?: ConfidenceValue;\n  /** Value that configures or reports sprint for this contract. */\n  sprint?: string;\n  /** Value that configures or reports release for this contract. */\n  release?: string;\n  /** Value that configures or reports blocked by for this contract. */\n  blocked_by?: string;\n  /** Value that configures or reports blocked reason for this contract. */\n  blocked_reason?: string;\n  /** Value that configures or reports unblock note for this contract. */\n  unblock_note?: string;\n  /** Value that configures or reports reporter for this contract. */\n  reporter?: string;\n  /** Value that configures or reports severity for this contract. */\n  severity?: IssueSeverity;\n  /** Value that configures or reports environment for this contract. */\n  environment?: string;\n  /** Value that configures or reports repro steps for this contract. */\n  repro_steps?: string;\n  /** Value that configures or reports resolution for this contract. */\n  resolution?: string;\n  /** Structured result returned by the expected operation. */\n  expected_result?: string;\n  /** Structured result returned by the actual operation. */\n  actual_result?: string;\n  /** Value that configures or reports affected version for this contract. */\n  affected_version?: string;\n  /** Value that configures or reports fixed version for this contract. */\n  fixed_version?: string;\n  /** Value that configures or reports component for this contract. */\n  component?: string;\n  /** Value that configures or reports regression for this contract. */\n  regression?: boolean;\n  /** Value that configures or reports customer impact for this contract. */\n  customer_impact?: string;\n  /** Value that configures or reports dependencies for this contract. */\n  dependencies?: Dependency[];\n  /** Value that configures or reports comments for this contract. */\n  comments?: Comment[];\n  /** Value that configures or reports notes for this contract. */\n  notes?: LogNote[];\n  /** Value that configures or reports learnings for this contract. */\n  learnings?: LogNote[];\n  /** Value that configures or reports files for this contract. */\n  files?: LinkedFile[];\n  /** Value that configures or reports tests for this contract. */\n  tests?: LinkedTest[];\n  /** Value that configures or reports test runs for this contract. */\n  test_runs?: ItemTestRunSummary[];\n  /** Value that configures or reports docs for this contract. */\n  docs?: LinkedDoc[];\n  /** Value that configures or reports close reason for this contract. */\n  close_reason?: string;\n  /** Value that configures or reports duplicate of for this contract. */\n  duplicate_of?: string;\n  /** Strategy used to control plan behavior. */\n  plan_mode?: PlanMode;\n  /** Value that configures or reports plan scope for this contract. */\n  plan_scope?: string;\n  /** Value that configures or reports plan harness for this contract. */\n  plan_harness?: PlanHarness;\n  /** Value that configures or reports plan steps for this contract. */\n  plan_steps?: PlanStep[];\n  /** Value that configures or reports plan decisions for this contract. */\n  plan_decisions?: PlanDecision[];\n  /** Value that configures or reports plan discoveries for this contract. */\n  plan_discoveries?: PlanDiscovery[];\n  /** Value that configures or reports plan validation for this contract. */\n  plan_validation?: PlanValidationCheck[];\n  /** Value that configures or reports plan resume context for this contract. */\n  plan_resume_context?: string;\n  [key: string]: unknown;\n}\n\n/** Documents the item document payload exchanged by command, SDK, and package integrations. */\nexport interface ItemDocument {\n  /** Value that configures or reports metadata for this contract. */\n  metadata: ItemMetadata;\n  /** Value that configures or reports body for this contract. */\n  body: string;\n}\n\n/** Documents the history patch op payload exchanged by command, SDK, and package integrations. */\nexport interface HistoryPatchOp {\n  /** Value that configures or reports op for this contract. */\n  op: \"add\" | \"remove\" | \"replace\" | \"move\" | \"copy\" | \"test\";\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports from for this contract. */\n  from?: string;\n  /** Value that configures or reports value for this contract. */\n  value?: unknown;\n}\n\n/** Documents the history entry payload exchanged by command, SDK, and package integrations. */\nexport interface HistoryEntry {\n  /** Value that configures or reports ts for this contract. */\n  ts: string;\n  /** Value that configures or reports author for this contract. */\n  author: string;\n  /** Value that configures or reports op for this contract. */\n  op: string;\n  /** Value that configures or reports patch for this contract. */\n  patch: HistoryPatchOp[];\n  /** Value that configures or reports before hash for this contract. */\n  before_hash: string;\n  /** Value that configures or reports after hash for this contract. */\n  after_hash: string;\n  /** Human-readable explanation suitable for logs and agent-facing output. */\n  message?: string;\n}\n\n/** Supported values accepted by the context depth contract. */\nexport const CONTEXT_DEPTH_VALUES = [\n  \"brief\",\n  \"standard\",\n  \"deep\",\n  \"full\",\n] as const;\n/** Restricts context depth values accepted by command, SDK, and storage contracts. */\nexport type ContextDepth = (typeof CONTEXT_DEPTH_VALUES)[number];\n\n/** Supported values accepted by the context section contract. */\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/** Restricts context section name values accepted by command, SDK, and storage contracts. */\nexport type ContextSectionName = (typeof CONTEXT_SECTION_VALUES)[number];\n\n/** Documents the context section settings payload exchanged by command, SDK, and package integrations. */\nexport interface ContextSectionSettings {\n  /** Value that configures or reports hierarchy for this contract. */\n  hierarchy: boolean;\n  /** Value that configures or reports activity for this contract. */\n  activity: boolean;\n  /** Value that configures or reports progress for this contract. */\n  progress: boolean;\n  /** Value that configures or reports recently created for this contract. */\n  recently_created: boolean;\n  /** Value that configures or reports unparented for this contract. */\n  unparented: boolean;\n  /** Value that configures or reports blockers for this contract. */\n  blockers: boolean;\n  /** Value that configures or reports files for this contract. */\n  files: boolean;\n  /** Value that configures or reports workload for this contract. */\n  workload: boolean;\n  /** Value that configures or reports staleness for this contract. */\n  staleness: boolean;\n  /** Value that configures or reports tests for this contract. */\n  tests: boolean;\n}\n\n/** Documents the context settings payload exchanged by command, SDK, and package integrations. */\nexport interface ContextSettings {\n  /** Fallback depth used when callers do not provide an override. */\n  default_depth: ContextDepth;\n  /** Value that configures or reports activity limit for this contract. */\n  activity_limit: number;\n  /** Value that configures or reports stale threshold days for this contract. */\n  stale_threshold_days: number;\n  /** Value that configures or reports sections for this contract. */\n  sections: ContextSectionSettings;\n}\n\n/** Documents the governance settings payload exchanged by command, SDK, and package integrations. */\nexport interface GovernanceSettings {\n  /** Value that configures or reports preset for this contract. */\n  preset: GovernancePreset;\n  /** Value that configures or reports ownership enforcement for this contract. */\n  ownership_enforcement: GovernanceOwnershipEnforcement;\n  /** Creates mode default using the validated operation inputs. */\n  create_mode_default: GovernanceCreateModeDefault;\n  /** Value that configures or reports close validation default for this contract. */\n  close_validation_default: GovernanceCloseValidationDefault;\n  /** Value that configures or reports require close reason for this contract. */\n  require_close_reason: boolean;\n  /** Value that configures or reports parent reference for this contract. */\n  parent_reference: ParentReferencePolicy;\n  /** Value that configures or reports metadata profile for this contract. */\n  metadata_profile: ValidateMetadataProfile;\n  /** Value that configures or reports force required for stale lock for this contract. */\n  force_required_for_stale_lock: boolean;\n  /** Schema type that determines the shape and validation rules for this value. */\n  create_default_type?: string;\n  /** Per-type allowed-transition enforcement mode for `pm update --status`. Read raw from settings (not preset-derived) so existing projects are unaffected when unset; defaults to \"off\". */\n  workflow_enforcement?: GovernanceWorkflowEnforcement;\n}\n\n/** Restricts extension policy mode values accepted by command, SDK, and storage contracts. */\nexport type ExtensionPolicyMode = \"off\" | \"warn\" | \"enforce\";\n/** Restricts extension trust mode values accepted by command, SDK, and storage contracts. */\nexport type ExtensionTrustMode = \"off\" | \"warn\" | \"enforce\";\n/** Restricts extension sandbox profile values accepted by command, SDK, and storage contracts. */\nexport type ExtensionSandboxProfile = \"none\" | \"restricted\" | \"strict\";\n\n/** Documents the extension policy override settings payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionPolicyOverrideSettings {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Whether disabled applies to this operation. */\n  disabled?: boolean;\n  /** Value that configures or reports require trusted for this contract. */\n  require_trusted?: boolean;\n  /** Value that configures or reports require provenance for this contract. */\n  require_provenance?: boolean;\n  /** Value that configures or reports sandbox profile for this contract. */\n  sandbox_profile?: ExtensionSandboxProfile;\n  /** Value that configures or reports allowed capabilities for this contract. */\n  allowed_capabilities?: string[];\n  /** Value that configures or reports blocked capabilities for this contract. */\n  blocked_capabilities?: string[];\n  /** Value that configures or reports allowed surfaces for this contract. */\n  allowed_surfaces?: string[];\n  /** Value that configures or reports blocked surfaces for this contract. */\n  blocked_surfaces?: string[];\n  /** Value that configures or reports allowed commands for this contract. */\n  allowed_commands?: string[];\n  /** Value that configures or reports blocked commands for this contract. */\n  blocked_commands?: string[];\n  /** Value that configures or reports allowed actions for this contract. */\n  allowed_actions?: string[];\n  /** Value that configures or reports blocked actions for this contract. */\n  blocked_actions?: string[];\n  /** Value that configures or reports allowed services for this contract. */\n  allowed_services?: string[];\n  /** Value that configures or reports blocked services for this contract. */\n  blocked_services?: string[];\n}\n\n/** Documents the extension policy settings payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionPolicySettings {\n  /** Value that configures or reports mode for this contract. */\n  mode: ExtensionPolicyMode;\n  /** Strategy used to control trust behavior. */\n  trust_mode: ExtensionTrustMode;\n  /** Value that configures or reports require provenance for this contract. */\n  require_provenance: boolean;\n  /** Value that configures or reports trusted extensions for this contract. */\n  trusted_extensions: string[];\n  /** Fallback sandbox profile used when callers do not provide an override. */\n  default_sandbox_profile: ExtensionSandboxProfile;\n  /** Value that configures or reports allowed extensions for this contract. */\n  allowed_extensions: string[];\n  /** Value that configures or reports blocked extensions for this contract. */\n  blocked_extensions: string[];\n  /** Value that configures or reports allowed capabilities for this contract. */\n  allowed_capabilities: string[];\n  /** Value that configures or reports blocked capabilities for this contract. */\n  blocked_capabilities: string[];\n  /** Value that configures or reports allowed surfaces for this contract. */\n  allowed_surfaces: string[];\n  /** Value that configures or reports blocked surfaces for this contract. */\n  blocked_surfaces: string[];\n  /** Value that configures or reports allowed commands for this contract. */\n  allowed_commands: string[];\n  /** Value that configures or reports blocked commands for this contract. */\n  blocked_commands: string[];\n  /** Value that configures or reports allowed actions for this contract. */\n  allowed_actions: string[];\n  /** Value that configures or reports blocked actions for this contract. */\n  blocked_actions: string[];\n  /** Value that configures or reports allowed services for this contract. */\n  allowed_services: string[];\n  /** Value that configures or reports blocked services for this contract. */\n  blocked_services: string[];\n  /** Value that configures or reports extension overrides for this contract. */\n  extension_overrides: ExtensionPolicyOverrideSettings[];\n}\n\n/** Documents the agent guidance settings payload exchanged by command, SDK, and package integrations. */\nexport interface AgentGuidanceSettings {\n  /** Value that configures or reports prompt completed for this contract. */\n  prompt_completed: boolean;\n  /** Value that configures or reports declined for this contract. */\n  declined: boolean;\n  /** ISO 8601 timestamp recording when declined occurred. */\n  declined_at: string;\n  /** Value that configures or reports template version for this contract. */\n  template_version: number;\n  /** Value that configures or reports last checked files for this contract. */\n  last_checked_files: string[];\n}\n\n/** Restricts search mutation refresh policy values accepted by command, SDK, and storage contracts. */\nexport type SearchMutationRefreshPolicy =\n  | \"cache_only\"\n  | \"semantic_configured\"\n  | \"semantic_auto\";\n\n/** Documents the search query expansion settings payload exchanged by command, SDK, and package integrations. */\nexport interface SearchQueryExpansionSettings {\n  /** Whether enabled applies to this operation. */\n  enabled: boolean;\n  /** Value that configures or reports provider for this contract. */\n  provider: string;\n}\n\n/** Documents the search rerank settings payload exchanged by command, SDK, and package integrations. */\nexport interface SearchRerankSettings {\n  /** Whether enabled applies to this operation. */\n  enabled: boolean;\n  /** Value that configures or reports model for this contract. */\n  model: string;\n  /** Value that configures or reports top k for this contract. */\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  /** Whether enabled applies to this operation. */\n  enabled: boolean;\n  /** Value that configures or reports max entries for this contract. */\n  max_entries: number;\n  /** Value that configures or reports trigger for this contract. */\n  trigger: \"health_warn\" | \"auto\";\n}\n\n/** Documents the pm settings payload exchanged by command, SDK, and package integrations. */\nexport interface PmSettings {\n  /** Value that configures or reports version for this contract. */\n  version: number;\n  /** Value that configures or reports id prefix for this contract. */\n  id_prefix: string;\n  /** Value that configures or reports author default for this contract. */\n  author_default: string;\n  /** Value that configures or reports item format for this contract. */\n  item_format: ItemFormat;\n  /** Value that configures or reports locks for this contract. */\n  locks: {\n    ttl_seconds: number;\n    /** Bounded wait budget (milliseconds) for acquiring a contended item lock before surfacing lock_conflict. 0 disables waiting (fail-fast). Overridable per invocation via PM_LOCK_WAIT_MS. */\n    wait_ms: number;\n  };\n  /** 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). */\n  checkpoints: {\n    retention_days: number;\n  };\n  /** Value that configures or reports output for this contract. */\n  output: {\n    default_format: \"toon\" | \"json\";\n  };\n  /** Value that configures or reports history for this contract. */\n  history: {\n    missing_stream: \"auto_create\" | \"strict_error\";\n    compact_policy: HistoryCompactPolicy;\n  };\n  /** Value that configures or reports validation for this contract. */\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    /** Per-type default estimates (minutes) used by `pm validate --auto-fix --fix-scope estimates` to backfill missing `estimated_minutes` (GH-212). Keys are item type names (case-insensitive); values are positive minutes that override the built-in defaults. Empty by default. */\n    estimate_defaults_by_type: Record<string, number>;\n  };\n  /** Value that configures or reports governance for this contract. */\n  governance: GovernanceSettings;\n  /** Value that configures or reports workflow for this contract. */\n  workflow: {\n    definition_of_done: string[];\n  };\n  /** Value that configures or reports testing for this contract. */\n  testing: {\n    record_results_to_items: boolean;\n  };\n  /** Value that configures or reports telemetry for this contract. */\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  /** Value that configures or reports agent guidance for this contract. */\n  agent_guidance: AgentGuidanceSettings;\n  /** Value that configures or reports item types for this contract. */\n  item_types: {\n    definitions: ItemTypeDefinition[];\n  };\n  /** Value that configures or reports schema for this contract. */\n  schema: RuntimeSchemaSettings;\n  /** Value that configures or reports extensions for this contract. */\n  extensions: {\n    enabled: string[];\n    disabled: string[];\n    policy: ExtensionPolicySettings;\n  };\n  /** Value that configures or reports search for this contract. */\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    /** Optional allow-list of corpus field names embedded for semantic search (see DEFAULT_SEARCH_CORPUS_FIELDS in core/search/corpus.ts). When unset or empty, the full default field set is used (backward compatible). When set, only the named fields are embedded — letting teams opt structured signals (priority, assignee, risk, acceptance_criteria, etc.) in/out for token efficiency. Changing this re-flags items stale on the next refresh. */\n    corpus_fields?: string[];\n    mutation_refresh_policy: SearchMutationRefreshPolicy;\n    query_expansion: SearchQueryExpansionSettings;\n    rerank: SearchRerankSettings;\n    /** 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). */\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  /** Value that configures or reports providers for this contract. */\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  /** Value that configures or reports context for this contract. */\n  context: ContextSettings;\n  /** Value that configures or reports vector store for this contract. */\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":"24e69ccc-1d29-57b3-95a8-73e2501548f0"}
+{"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 */\n/** Supported values accepted by the builtin item type contract. */\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;\n/** Supported values accepted by the item type contract. */\nexport const ITEM_TYPE_VALUES = BUILTIN_ITEM_TYPE_VALUES;\n/** Restricts builtin item type values accepted by command, SDK, and storage contracts. */\nexport type BuiltinItemType = (typeof BUILTIN_ITEM_TYPE_VALUES)[number];\n/** Restricts item type values accepted by command, SDK, and storage contracts. */\nexport type ItemType = string;\n\n/** Supported values accepted by the status contract. */\nexport const STATUS_VALUES = [\n  \"draft\",\n  \"open\",\n  \"in_progress\",\n  \"blocked\",\n  \"closed\",\n  \"canceled\",\n] as const;\n/** Restricts item status values accepted by command, SDK, and storage contracts. */\nexport type ItemStatus = string;\n\n/** Supported values accepted by the runtime status role contract. */\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/** Restricts runtime status role values accepted by command, SDK, and storage contracts. */\nexport type RuntimeStatusRole = (typeof RUNTIME_STATUS_ROLE_VALUES)[number];\n\n/** Supported values accepted by the runtime field type contract. */\nexport const RUNTIME_FIELD_TYPE_VALUES = [\n  \"string\",\n  \"number\",\n  \"boolean\",\n  \"string_array\",\n] as const;\n/** Restricts runtime field type values accepted by command, SDK, and storage contracts. */\nexport type RuntimeFieldType = (typeof RUNTIME_FIELD_TYPE_VALUES)[number];\n\n/** Supported values accepted by the runtime field command contract. */\nexport const RUNTIME_FIELD_COMMAND_VALUES = [\n  \"create\",\n  \"update\",\n  \"update_many\",\n  \"list\",\n  \"search\",\n  \"calendar\",\n  \"context\",\n] as const;\n/** Restricts runtime field command values accepted by command, SDK, and storage contracts. */\nexport type RuntimeFieldCommand = (typeof RUNTIME_FIELD_COMMAND_VALUES)[number];\n\n/** Supported values accepted by the runtime unknown field policy contract. */\nexport const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES = [\n  \"allow\",\n  \"warn\",\n  \"reject\",\n] as const;\n/** Restricts runtime unknown field policy values accepted by command, SDK, and storage contracts. */\nexport type RuntimeUnknownFieldPolicy =\n  (typeof RUNTIME_UNKNOWN_FIELD_POLICY_VALUES)[number];\n\n/** Supported values accepted by the dependency kind contract. */\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/** Restricts dependency kind values accepted by command, SDK, and storage contracts. */\nexport type DependencyKind = (typeof DEPENDENCY_KIND_VALUES)[number];\n\n/** Supported values accepted by the scope contract. */\nexport const SCOPE_VALUES = [\"project\", \"global\"] as const;\n/** Restricts link scope values accepted by command, SDK, and storage contracts. */\nexport type LinkScope = (typeof SCOPE_VALUES)[number];\n\n/** Supported values accepted by the risk contract. */\nexport const RISK_VALUES = [\"low\", \"medium\", \"high\", \"critical\"] as const;\n/** Restricts risk level values accepted by command, SDK, and storage contracts. */\nexport type RiskLevel = (typeof RISK_VALUES)[number];\n\n/** Supported values accepted by the issue severity contract. */\nexport const ISSUE_SEVERITY_VALUES = [\n  \"low\",\n  \"medium\",\n  \"high\",\n  \"critical\",\n] as const;\n/** Restricts issue severity values accepted by command, SDK, and storage contracts. */\nexport type IssueSeverity = (typeof ISSUE_SEVERITY_VALUES)[number];\n\n/** Supported values accepted by the confidence text contract. */\nexport const CONFIDENCE_TEXT_VALUES = [\"low\", \"medium\", \"high\"] as const;\n/** Restricts confidence text level values accepted by command, SDK, and storage contracts. */\nexport type ConfidenceTextLevel = (typeof CONFIDENCE_TEXT_VALUES)[number];\n/** Restricts confidence value values accepted by command, SDK, and storage contracts. */\nexport type ConfidenceValue = number | ConfidenceTextLevel;\n\n/** Supported values accepted by the item format contract. */\nexport const ITEM_FORMAT_VALUES = [\"toon\", \"json_markdown\"] as const;\n/** Restricts item format values accepted by command, SDK, and storage contracts. */\nexport type ItemFormat = (typeof ITEM_FORMAT_VALUES)[number];\n\n/** Supported values accepted by the sprint release format policy contract. */\nexport const SPRINT_RELEASE_FORMAT_POLICY_VALUES = [\n  \"warn\",\n  \"strict_error\",\n] as const;\n/** Restricts sprint release format policy values accepted by command, SDK, and storage contracts. */\nexport type SprintReleaseFormatPolicy =\n  (typeof SPRINT_RELEASE_FORMAT_POLICY_VALUES)[number];\n/** Supported values accepted by the parent reference policy contract. */\nexport const PARENT_REFERENCE_POLICY_VALUES = [\"warn\", \"strict_error\"] as const;\n/** Restricts parent reference policy values accepted by command, SDK, and storage contracts. */\nexport type ParentReferencePolicy =\n  (typeof PARENT_REFERENCE_POLICY_VALUES)[number];\n/** Supported values accepted by the validate metadata profile contract. */\nexport const VALIDATE_METADATA_PROFILE_VALUES = [\n  \"core\",\n  \"strict\",\n  \"custom\",\n] as const;\n/** Restricts validate metadata profile values accepted by command, SDK, and storage contracts. */\nexport type ValidateMetadataProfile =\n  (typeof VALIDATE_METADATA_PROFILE_VALUES)[number];\n/** Supported values accepted by the governance preset contract. */\nexport const GOVERNANCE_PRESET_VALUES = [\n  \"minimal\",\n  \"default\",\n  \"strict\",\n  \"custom\",\n] as const;\n/** Restricts governance preset values accepted by command, SDK, and storage contracts. */\nexport type GovernancePreset = (typeof GOVERNANCE_PRESET_VALUES)[number];\n/** Supported values accepted by the governance ownership enforcement contract. */\nexport const GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES = [\n  \"none\",\n  \"warn\",\n  \"strict\",\n] as const;\n/** Restricts governance ownership enforcement values accepted by command, SDK, and storage contracts. */\nexport type GovernanceOwnershipEnforcement =\n  (typeof GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES)[number];\n/** Supported values accepted by the governance create mode default contract. */\nexport const GOVERNANCE_CREATE_MODE_DEFAULT_VALUES = [\n  \"progressive\",\n  \"strict\",\n] as const;\n/** Restricts governance create mode default values accepted by command, SDK, and storage contracts. */\nexport type GovernanceCreateModeDefault =\n  (typeof GOVERNANCE_CREATE_MODE_DEFAULT_VALUES)[number];\n/** Supported values accepted by the governance close validation default contract. */\nexport const GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES = [\n  \"off\",\n  \"warn\",\n  \"strict\",\n] as const;\n/** Restricts governance close validation default values accepted by command, SDK, and storage contracts. */\nexport type GovernanceCloseValidationDefault =\n  (typeof GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES)[number];\n/** Supported values accepted by the governance workflow enforcement contract. */\nexport const GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES = [\n  \"off\",\n  \"warn\",\n  \"strict\",\n] as const;\n/** Restricts governance workflow enforcement values accepted by command, SDK, and storage contracts. */\nexport type GovernanceWorkflowEnforcement =\n  (typeof GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES)[number];\n/** Supported values accepted by the validate metadata required field contract. */\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/** Restricts validate metadata required field values accepted by command, SDK, and storage contracts. */\nexport type ValidateMetadataRequiredField =\n  (typeof VALIDATE_METADATA_REQUIRED_FIELD_VALUES)[number];\n\n/** Supported values accepted by the recurrence frequency contract. */\nexport const RECURRENCE_FREQUENCY_VALUES = [\n  \"daily\",\n  \"weekly\",\n  \"monthly\",\n  \"yearly\",\n] as const;\n/** Restricts recurrence frequency values accepted by command, SDK, and storage contracts. */\nexport type RecurrenceFrequency = (typeof RECURRENCE_FREQUENCY_VALUES)[number];\n\n/** Supported values accepted by the recurrence weekday contract. */\nexport const RECURRENCE_WEEKDAY_VALUES = [\n  \"mon\",\n  \"tue\",\n  \"wed\",\n  \"thu\",\n  \"fri\",\n  \"sat\",\n  \"sun\",\n] as const;\n/** Restricts recurrence weekday values accepted by command, SDK, and storage contracts. */\nexport type RecurrenceWeekday = (typeof RECURRENCE_WEEKDAY_VALUES)[number];\n\n/** Canonical week-order index for a recurrence weekday (mon=0 .. sun=6). Shared by item serialization, create/update parsing, and calendar expansion so weekday ordering cannot drift between those modules. */\nexport function weekdayOrderIndex(value: RecurrenceWeekday): number {\n  return RECURRENCE_WEEKDAY_VALUES.indexOf(value);\n}\n\n/** Documents the dependency payload exchanged by command, SDK, and package integrations. */\nexport interface Dependency {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports kind for this contract. */\n  kind: DependencyKind;\n  /** ISO 8601 timestamp recording when created occurred. */\n  created_at: string;\n  /** Value that configures or reports author for this contract. */\n  author?: string;\n  /** Value that configures or reports source kind for this contract. */\n  source_kind?: string;\n}\n\n/** Documents the comment payload exchanged by command, SDK, and package integrations. */\nexport interface Comment {\n  /** ISO 8601 timestamp recording when created occurred. */\n  created_at: string;\n  /** Value that configures or reports author for this contract. */\n  author: string;\n  /** Value that configures or reports text for this contract. */\n  text: string;\n}\n\n/** Documents the log note payload exchanged by command, SDK, and package integrations. */\nexport interface LogNote {\n  /** ISO 8601 timestamp recording when created occurred. */\n  created_at: string;\n  /** Value that configures or reports author for this contract. */\n  author: string;\n  /** Value that configures or reports text for this contract. */\n  text: string;\n}\n\n/** Documents the linked file payload exchanged by command, SDK, and package integrations. */\nexport interface LinkedFile {\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports scope for this contract. */\n  scope: LinkScope;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n}\n\n/** Documents the linked test payload exchanged by command, SDK, and package integrations. */\nexport interface LinkedTest {\n  /** Value that configures or reports command for this contract. */\n  command?: string;\n  /** Filesystem path used for path resolution. */\n  path?: string;\n  /** Value that configures or reports scope for this contract. */\n  scope: LinkScope;\n  /** Value that configures or reports timeout seconds for this contract. */\n  timeout_seconds?: number;\n  /** Strategy used to control pm context behavior. */\n  pm_context_mode?: \"schema\" | \"tracker\" | \"auto\";\n  /** Value that configures or reports env set for this contract. */\n  env_set?: Record<string, string>;\n  /** Value that configures or reports env clear for this contract. */\n  env_clear?: string[];\n  /** Value that configures or reports shared host safe for this contract. */\n  shared_host_safe?: boolean;\n  /** Value that configures or reports assert stdout contains for this contract. */\n  assert_stdout_contains?: string[];\n  /** Value that configures or reports assert stdout regex for this contract. */\n  assert_stdout_regex?: string[];\n  /** Value that configures or reports assert stderr contains for this contract. */\n  assert_stderr_contains?: string[];\n  /** Value that configures or reports assert stderr regex for this contract. */\n  assert_stderr_regex?: string[];\n  /** Value that configures or reports assert stdout min lines for this contract. */\n  assert_stdout_min_lines?: number;\n  /** Value that configures or reports assert json field equals for this contract. */\n  assert_json_field_equals?: Record<string, string>;\n  /** Value that configures or reports assert json field gte for this contract. */\n  assert_json_field_gte?: Record<string, number>;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n}\n\n/** Documents the linked doc payload exchanged by command, SDK, and package integrations. */\nexport interface LinkedDoc {\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports scope for this contract. */\n  scope: LinkScope;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n}\n\n/** Documents the reminder payload exchanged by command, SDK, and package integrations. */\nexport interface Reminder {\n  /** Value that configures or reports at for this contract. */\n  at: string;\n  /** Value that configures or reports text for this contract. */\n  text: string;\n}\n\n/** Documents the recurrence rule payload exchanged by command, SDK, and package integrations. */\nexport interface RecurrenceRule {\n  /** Value that configures or reports freq for this contract. */\n  freq: RecurrenceFrequency;\n  /** Value that configures or reports interval for this contract. */\n  interval?: number;\n  /** Value that configures or reports count for this contract. */\n  count?: number;\n  /** Value that configures or reports until for this contract. */\n  until?: string;\n  /** Value that configures or reports by weekday for this contract. */\n  by_weekday?: RecurrenceWeekday[];\n  /** Value that configures or reports by month day for this contract. */\n  by_month_day?: number[];\n  /** Value that configures or reports exdates for this contract. */\n  exdates?: string[];\n}\n\n/** Documents the calendar event payload exchanged by command, SDK, and package integrations. */\nexport interface CalendarEvent {\n  /** ISO 8601 timestamp recording when start occurred. */\n  start_at: string;\n  /** ISO 8601 timestamp recording when end occurred. */\n  end_at?: string;\n  /** Value that configures or reports title for this contract. */\n  title?: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Value that configures or reports location for this contract. */\n  location?: string;\n  /** Value that configures or reports all day for this contract. */\n  all_day?: boolean;\n  /** Value that configures or reports timezone for this contract. */\n  timezone?: string;\n  /** Value that configures or reports recurrence for this contract. */\n  recurrence?: RecurrenceRule;\n}\n\n/** Supported values accepted by the plan mode contract. */\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/** Restricts plan mode values accepted by command, SDK, and storage contracts. */\nexport type PlanMode = (typeof PLAN_MODE_VALUES)[number];\n\n/** Supported values accepted by the plan step status contract. */\nexport const PLAN_STEP_STATUS_VALUES = [\n  \"pending\",\n  \"in_progress\",\n  \"completed\",\n  \"blocked\",\n  \"skipped\",\n  \"superseded\",\n] as const;\n/** Restricts plan step status values accepted by command, SDK, and storage contracts. */\nexport type PlanStepStatus = (typeof PLAN_STEP_STATUS_VALUES)[number];\n\n/** Supported values accepted by the plan harness contract. */\nexport const PLAN_HARNESS_VALUES = [\n  \"codex\",\n  \"claude-code\",\n  \"cursor\",\n  \"generic\",\n] as const;\n/** Restricts plan harness values accepted by command, SDK, and storage contracts. */\nexport type PlanHarness = (typeof PLAN_HARNESS_VALUES)[number];\n\n/** Supported values accepted by the plan step link kind contract. */\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/** Restricts plan step link kind values accepted by command, SDK, and storage contracts. */\nexport type PlanStepLinkKind = (typeof PLAN_STEP_LINK_KIND_VALUES)[number];\n\n/** Documents the plan step link payload exchanged by command, SDK, and package integrations. */\nexport interface PlanStepLink {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports kind for this contract. */\n  kind: PlanStepLinkKind;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n  /** Value that configures or reports required before step for this contract. */\n  required_before_step?: boolean;\n}\n\n/** Documents the plan step file payload exchanged by command, SDK, and package integrations. */\nexport interface PlanStepFile {\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports scope for this contract. */\n  scope?: LinkScope;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n}\n\n/** Documents the plan step test payload exchanged by command, SDK, and package integrations. */\nexport interface PlanStepTest {\n  /** Value that configures or reports command for this contract. */\n  command?: string;\n  /** Filesystem path used for path resolution. */\n  path?: string;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n}\n\n/** Documents the plan step doc payload exchanged by command, SDK, and package integrations. */\nexport interface PlanStepDoc {\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports scope for this contract. */\n  scope?: LinkScope;\n  /** Value that configures or reports note for this contract. */\n  note?: string;\n}\n\n/** Documents the plan step payload exchanged by command, SDK, and package integrations. */\nexport interface PlanStep {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports order for this contract. */\n  order: number;\n  /** Value that configures or reports title for this contract. */\n  title: string;\n  /** Value that configures or reports body for this contract. */\n  body?: string;\n  /** Lifecycle state reported for status. */\n  status: PlanStepStatus;\n  /** Value that configures or reports owner for this contract. */\n  owner?: string;\n  /** Value that configures or reports evidence for this contract. */\n  evidence?: string;\n  /** Value that configures or reports blocked reason for this contract. */\n  blocked_reason?: string;\n  /** Value that configures or reports superseded by for this contract. */\n  superseded_by?: string;\n  /** Value that configures or reports linked items for this contract. */\n  linked_items?: PlanStepLink[];\n  /** Value that configures or reports files for this contract. */\n  files?: PlanStepFile[];\n  /** Value that configures or reports tests for this contract. */\n  tests?: PlanStepTest[];\n  /** Value that configures or reports docs for this contract. */\n  docs?: PlanStepDoc[];\n  /** ISO 8601 timestamp recording when created occurred. */\n  created_at: string;\n  /** ISO 8601 timestamp recording when updated occurred. */\n  updated_at: string;\n  /** ISO 8601 timestamp recording when completed occurred. */\n  completed_at?: string;\n}\n\n/** Documents the plan decision payload exchanged by command, SDK, and package integrations. */\nexport interface PlanDecision {\n  /** Value that configures or reports ts for this contract. */\n  ts: string;\n  /** Value that configures or reports author for this contract. */\n  author: string;\n  /** Value that configures or reports decision for this contract. */\n  decision: string;\n  /** Value that configures or reports rationale for this contract. */\n  rationale?: string;\n  /** Value that configures or reports evidence for this contract. */\n  evidence?: string;\n  /** Value that configures or reports step id for this contract. */\n  step_id?: string;\n}\n\n/** Documents the plan discovery payload exchanged by command, SDK, and package integrations. */\nexport interface PlanDiscovery {\n  /** Value that configures or reports ts for this contract. */\n  ts: string;\n  /** Value that configures or reports author for this contract. */\n  author: string;\n  /** Value that configures or reports text for this contract. */\n  text: string;\n  /** Value that configures or reports step id for this contract. */\n  step_id?: string;\n}\n\n/** Documents the plan validation check payload exchanged by command, SDK, and package integrations. */\nexport interface PlanValidationCheck {\n  /** Value that configures or reports text for this contract. */\n  text: string;\n  /** Value that configures or reports command for this contract. */\n  command?: string;\n  /** Value that configures or reports expected for this contract. */\n  expected?: string;\n}\n\n/** Documents the item type option definition payload exchanged by command, SDK, and package integrations. */\nexport interface ItemTypeOptionDefinition {\n  /** Value that configures or reports key for this contract. */\n  key: string;\n  /** Value that configures or reports values for this contract. */\n  values: string[];\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Value that configures or reports aliases for this contract. */\n  aliases?: string[];\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n}\n\n/** Documents the item type command option policy payload exchanged by command, SDK, and package integrations. */\nexport interface ItemTypeCommandOptionPolicy {\n  /** Value that configures or reports command for this contract. */\n  command: \"create\" | \"update\";\n  /** Value that configures or reports option for this contract. */\n  option: string;\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Value that configures or reports visible for this contract. */\n  visible?: boolean;\n  /** Whether enabled applies to this operation. */\n  enabled?: boolean;\n}\n\n/** Documents the item type definition payload exchanged by command, SDK, and package integrations. */\nexport interface ItemTypeDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Status assigned to newly created items of this type when `--status` is not provided. Falls back to the workflow's open status when unset or invalid. */\n  default_status?: string;\n  /** Value that configures or reports folder for this contract. */\n  folder?: string;\n  /** Value that configures or reports aliases for this contract. */\n  aliases?: string[];\n  /** Value that configures or reports required create fields for this contract. */\n  required_create_fields?: string[];\n  /** Value that configures or reports required create repeatables for this contract. */\n  required_create_repeatables?: string[];\n  /** Value that configures or reports options for this contract. */\n  options?: ItemTypeOptionDefinition[];\n  /** Value that configures or reports command option policies for this contract. */\n  command_option_policies?: ItemTypeCommandOptionPolicy[];\n}\n\n/** Documents the runtime status definition payload exchanged by command, SDK, and package integrations. */\nexport interface RuntimeStatusDefinition {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports aliases for this contract. */\n  aliases?: string[];\n  /** Value that configures or reports roles for this contract. */\n  roles?: RuntimeStatusRole[];\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Value that configures or reports order for this contract. */\n  order?: number;\n}\n\n/** Documents the runtime field definition payload exchanged by command, SDK, and package integrations. */\nexport interface RuntimeFieldDefinition {\n  /** Value that configures or reports key for this contract. */\n  key: string;\n  /** Value that configures or reports metadata key for this contract. */\n  metadata_key?: string;\n  /**\n   * @deprecated Use metadata_key.\n   */\n  front_matter_key?: string;\n  /** Value that configures or reports cli flag for this contract. */\n  cli_flag?: string;\n  /** Value that configures or reports cli aliases for this contract. */\n  cli_aliases?: string[];\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Schema type that determines the shape and validation rules for this value. */\n  type?: RuntimeFieldType;\n  /** Value that configures or reports commands for this contract. */\n  commands?: RuntimeFieldCommand[];\n  /** Value that configures or reports repeatable for this contract. */\n  repeatable?: boolean;\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Value that configures or reports required on create for this contract. */\n  required_on_create?: boolean;\n  /** Value that configures or reports required types for this contract. */\n  required_types?: string[];\n  /** Value that configures or reports allow unset for this contract. */\n  allow_unset?: boolean;\n}\n\n/** Documents the runtime workflow definition payload exchanged by command, SDK, and package integrations. */\nexport interface RuntimeWorkflowDefinition {\n  /** Configured status id representing the draft lifecycle state. */\n  draft_status?: string;\n  /** Configured status id representing the open lifecycle state. */\n  open_status?: string;\n  /** Configured status id representing the in-progress lifecycle state. */\n  in_progress_status?: string;\n  /** Configured status id representing the blocked lifecycle state. */\n  blocked_status?: string;\n  /** Configured status id representing the closed lifecycle state. */\n  close_status?: string;\n  /** Configured status id representing the canceled lifecycle state. */\n  canceled_status?: string;\n}\n\n/** Documents the runtime schema file config payload exchanged by command, SDK, and package integrations. */\nexport interface RuntimeSchemaFileConfig {\n  /** Value that configures or reports types for this contract. */\n  types?: string;\n  /** Value that configures or reports statuses for this contract. */\n  statuses?: string;\n  /** Value that configures or reports fields for this contract. */\n  fields?: string;\n  /** Value that configures or reports workflows for this contract. */\n  workflows?: string;\n}\n\n/** Per-type allowed-transition rule. A type with no matching entry is unrestricted; a type with an entry allows only the listed [from, to] status pairs (status tokens are resolved case-insensitively through the status registry alias map; a same-status no-op is always allowed). */\nexport interface TypeWorkflowDefinition {\n  /** Schema type that determines the shape and validation rules for this value. */\n  type: string;\n  /** Value that configures or reports allowed transitions for this contract. */\n  allowed_transitions: [string, string][];\n}\n\n/** Documents the runtime schema settings payload exchanged by command, SDK, and package integrations. */\nexport interface RuntimeSchemaSettings {\n  /** Value that configures or reports version for this contract. */\n  version: number;\n  /** Value that configures or reports files for this contract. */\n  files: RuntimeSchemaFileConfig;\n  /** Value that configures or reports statuses for this contract. */\n  statuses: RuntimeStatusDefinition[];\n  /** Value that configures or reports fields for this contract. */\n  fields: RuntimeFieldDefinition[];\n  /** Value that configures or reports workflow for this contract. */\n  workflow: RuntimeWorkflowDefinition;\n  /** Value that configures or reports type workflows for this contract. */\n  type_workflows?: TypeWorkflowDefinition[];\n  /** Value that configures or reports unknown field policy for this contract. */\n  unknown_field_policy: RuntimeUnknownFieldPolicy;\n}\n\n/** Documents the item test run summary payload exchanged by command, SDK, and package integrations. */\nexport interface ItemTestRunSummary {\n  /** Executes the id operation through the package runtime. */\n  run_id: string;\n  /** Value that configures or reports kind for this contract. */\n  kind: \"test\" | \"test-all\";\n  /** Lifecycle state reported for status. */\n  status: \"passed\" | \"failed\" | \"stopped\" | \"canceled\";\n  /** ISO 8601 timestamp recording when started occurred. */\n  started_at: string;\n  /** ISO 8601 timestamp recording when finished occurred. */\n  finished_at: string;\n  /** ISO 8601 timestamp recording when recorded occurred. */\n  recorded_at: string;\n  /** Value that configures or reports attempt for this contract. */\n  attempt?: number;\n  /** Value that configures or reports resumed from for this contract. */\n  resumed_from?: string;\n  /** Value that configures or reports passed for this contract. */\n  passed: number;\n  /** Value that configures or reports failed for this contract. */\n  failed: number;\n  /** Value that configures or reports skipped for this contract. */\n  skipped: number;\n  /** Value that configures or reports items for this contract. */\n  items?: number;\n  /** Value that configures or reports linked tests for this contract. */\n  linked_tests?: number;\n  /** Value that configures or reports fail on skipped triggered for this contract. */\n  fail_on_skipped_triggered?: boolean;\n}\n\n/** Documents the item metadata payload exchanged by command, SDK, and package integrations. */\nexport interface ItemMetadata {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports title for this contract. */\n  title: string;\n  /** Value that configures or reports description for this contract. */\n  description: string;\n  /** Schema type that determines the shape and validation rules for this value. */\n  type: ItemType;\n  /** On-disk item-metadata format version. Absent means the implicit baseline (version 1) and is never serialized; populated only once an item advances past the baseline via a future storage migration. See core/item/item-format-version. */\n  pm_format_version?: number;\n  /** Schema type that determines the shape and validation rules for this value. */\n  source_type?: string;\n  /** Inputs that customize the type operation. */\n  type_options?: Record<string, string>;\n  /** Lifecycle state reported for status. */\n  status: ItemStatus;\n  /** Value that configures or reports priority for this contract. */\n  priority: 0 | 1 | 2 | 3 | 4;\n  /** Value that configures or reports tags for this contract. */\n  tags: string[];\n  /** ISO 8601 timestamp recording when created occurred. */\n  created_at: string;\n  /** ISO 8601 timestamp recording when updated occurred. */\n  updated_at: string;\n  /** Value that configures or reports deadline for this contract. */\n  deadline?: string;\n  /** Value that configures or reports reminders for this contract. */\n  reminders?: Reminder[];\n  /** Value that configures or reports events for this contract. */\n  events?: CalendarEvent[];\n  /** ISO 8601 timestamp recording when closed occurred. */\n  closed_at?: string;\n  /** Value that configures or reports assignee for this contract. */\n  assignee?: string;\n  /** Value that configures or reports source owner for this contract. */\n  source_owner?: string;\n  /** Value that configures or reports author for this contract. */\n  author?: string;\n  /** Value that configures or reports estimated minutes for this contract. */\n  estimated_minutes?: number;\n  /** Value that configures or reports acceptance criteria for this contract. */\n  acceptance_criteria?: string;\n  /** Value that configures or reports design for this contract. */\n  design?: string;\n  /** Value that configures or reports external ref for this contract. */\n  external_ref?: string;\n  /** Value that configures or reports definition of ready for this contract. */\n  definition_of_ready?: string;\n  /** Value that configures or reports order for this contract. */\n  order?: number;\n  /** Value that configures or reports goal for this contract. */\n  goal?: string;\n  /** Value that configures or reports objective for this contract. */\n  objective?: string;\n  /** Value that configures or reports value for this contract. */\n  value?: string;\n  /** Value that configures or reports impact for this contract. */\n  impact?: string;\n  /** Value that configures or reports outcome for this contract. */\n  outcome?: string;\n  /** Value that configures or reports why now for this contract. */\n  why_now?: string;\n  /** Value that configures or reports parent for this contract. */\n  parent?: string;\n  /** Value that configures or reports reviewer for this contract. */\n  reviewer?: string;\n  /** Value that configures or reports risk for this contract. */\n  risk?: RiskLevel;\n  /** Value that configures or reports confidence for this contract. */\n  confidence?: ConfidenceValue;\n  /** Value that configures or reports sprint for this contract. */\n  sprint?: string;\n  /** Value that configures or reports release for this contract. */\n  release?: string;\n  /** Value that configures or reports blocked by for this contract. */\n  blocked_by?: string;\n  /** Value that configures or reports blocked reason for this contract. */\n  blocked_reason?: string;\n  /** Value that configures or reports unblock note for this contract. */\n  unblock_note?: string;\n  /** Value that configures or reports reporter for this contract. */\n  reporter?: string;\n  /** Value that configures or reports severity for this contract. */\n  severity?: IssueSeverity;\n  /** Value that configures or reports environment for this contract. */\n  environment?: string;\n  /** Value that configures or reports repro steps for this contract. */\n  repro_steps?: string;\n  /** Value that configures or reports resolution for this contract. */\n  resolution?: string;\n  /** Structured result returned by the expected operation. */\n  expected_result?: string;\n  /** Structured result returned by the actual operation. */\n  actual_result?: string;\n  /** Value that configures or reports affected version for this contract. */\n  affected_version?: string;\n  /** Value that configures or reports fixed version for this contract. */\n  fixed_version?: string;\n  /** Value that configures or reports component for this contract. */\n  component?: string;\n  /** Value that configures or reports regression for this contract. */\n  regression?: boolean;\n  /** Value that configures or reports customer impact for this contract. */\n  customer_impact?: string;\n  /** Value that configures or reports dependencies for this contract. */\n  dependencies?: Dependency[];\n  /** Value that configures or reports comments for this contract. */\n  comments?: Comment[];\n  /** Value that configures or reports notes for this contract. */\n  notes?: LogNote[];\n  /** Value that configures or reports learnings for this contract. */\n  learnings?: LogNote[];\n  /** Value that configures or reports files for this contract. */\n  files?: LinkedFile[];\n  /** Value that configures or reports tests for this contract. */\n  tests?: LinkedTest[];\n  /** Value that configures or reports test runs for this contract. */\n  test_runs?: ItemTestRunSummary[];\n  /** Value that configures or reports docs for this contract. */\n  docs?: LinkedDoc[];\n  /** Value that configures or reports close reason for this contract. */\n  close_reason?: string;\n  /** Value that configures or reports duplicate of for this contract. */\n  duplicate_of?: string;\n  /** Strategy used to control plan behavior. */\n  plan_mode?: PlanMode;\n  /** Value that configures or reports plan scope for this contract. */\n  plan_scope?: string;\n  /** Value that configures or reports plan harness for this contract. */\n  plan_harness?: PlanHarness;\n  /** Value that configures or reports plan steps for this contract. */\n  plan_steps?: PlanStep[];\n  /** Value that configures or reports plan decisions for this contract. */\n  plan_decisions?: PlanDecision[];\n  /** Value that configures or reports plan discoveries for this contract. */\n  plan_discoveries?: PlanDiscovery[];\n  /** Value that configures or reports plan validation for this contract. */\n  plan_validation?: PlanValidationCheck[];\n  /** Value that configures or reports plan resume context for this contract. */\n  plan_resume_context?: string;\n  [key: string]: unknown;\n}\n\n/** Documents the item document payload exchanged by command, SDK, and package integrations. */\nexport interface ItemDocument {\n  /** Value that configures or reports metadata for this contract. */\n  metadata: ItemMetadata;\n  /** Value that configures or reports body for this contract. */\n  body: string;\n}\n\n/** Documents the history patch op payload exchanged by command, SDK, and package integrations. */\nexport interface HistoryPatchOp {\n  /** Value that configures or reports op for this contract. */\n  op: \"add\" | \"remove\" | \"replace\" | \"move\" | \"copy\" | \"test\";\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports from for this contract. */\n  from?: string;\n  /** Value that configures or reports value for this contract. */\n  value?: unknown;\n}\n\n/** Documents the history entry payload exchanged by command, SDK, and package integrations. */\nexport interface HistoryEntry {\n  /** Value that configures or reports ts for this contract. */\n  ts: string;\n  /** Value that configures or reports author for this contract. */\n  author: string;\n  /** Value that configures or reports op for this contract. */\n  op: string;\n  /** Value that configures or reports patch for this contract. */\n  patch: HistoryPatchOp[];\n  /** Value that configures or reports before hash for this contract. */\n  before_hash: string;\n  /** Value that configures or reports after hash for this contract. */\n  after_hash: string;\n  /** Human-readable explanation suitable for logs and agent-facing output. */\n  message?: string;\n}\n\n/** Supported values accepted by the context depth contract. */\nexport const CONTEXT_DEPTH_VALUES = [\n  \"brief\",\n  \"standard\",\n  \"deep\",\n  \"full\",\n] as const;\n/** Restricts context depth values accepted by command, SDK, and storage contracts. */\nexport type ContextDepth = (typeof CONTEXT_DEPTH_VALUES)[number];\n\n/** Supported values accepted by the context section contract. */\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/** Restricts context section name values accepted by command, SDK, and storage contracts. */\nexport type ContextSectionName = (typeof CONTEXT_SECTION_VALUES)[number];\n\n/** Documents the context section settings payload exchanged by command, SDK, and package integrations. */\nexport interface ContextSectionSettings {\n  /** Value that configures or reports hierarchy for this contract. */\n  hierarchy: boolean;\n  /** Value that configures or reports activity for this contract. */\n  activity: boolean;\n  /** Value that configures or reports progress for this contract. */\n  progress: boolean;\n  /** Value that configures or reports recently created for this contract. */\n  recently_created: boolean;\n  /** Value that configures or reports unparented for this contract. */\n  unparented: boolean;\n  /** Value that configures or reports blockers for this contract. */\n  blockers: boolean;\n  /** Value that configures or reports files for this contract. */\n  files: boolean;\n  /** Value that configures or reports workload for this contract. */\n  workload: boolean;\n  /** Value that configures or reports staleness for this contract. */\n  staleness: boolean;\n  /** Value that configures or reports tests for this contract. */\n  tests: boolean;\n}\n\n/** Documents the context settings payload exchanged by command, SDK, and package integrations. */\nexport interface ContextSettings {\n  /** Fallback depth used when callers do not provide an override. */\n  default_depth: ContextDepth;\n  /** Value that configures or reports activity limit for this contract. */\n  activity_limit: number;\n  /** Value that configures or reports stale threshold days for this contract. */\n  stale_threshold_days: number;\n  /** Value that configures or reports sections for this contract. */\n  sections: ContextSectionSettings;\n}\n\n/** Documents the governance settings payload exchanged by command, SDK, and package integrations. */\nexport interface GovernanceSettings {\n  /** Value that configures or reports preset for this contract. */\n  preset: GovernancePreset;\n  /** Value that configures or reports ownership enforcement for this contract. */\n  ownership_enforcement: GovernanceOwnershipEnforcement;\n  /** Creates mode default using the validated operation inputs. */\n  create_mode_default: GovernanceCreateModeDefault;\n  /** Value that configures or reports close validation default for this contract. */\n  close_validation_default: GovernanceCloseValidationDefault;\n  /** Value that configures or reports require close reason for this contract. */\n  require_close_reason: boolean;\n  /** Value that configures or reports parent reference for this contract. */\n  parent_reference: ParentReferencePolicy;\n  /** Value that configures or reports metadata profile for this contract. */\n  metadata_profile: ValidateMetadataProfile;\n  /** Value that configures or reports force required for stale lock for this contract. */\n  force_required_for_stale_lock: boolean;\n  /** Schema type that determines the shape and validation rules for this value. */\n  create_default_type?: string;\n  /** Per-type allowed-transition enforcement mode for `pm update --status`. Read raw from settings (not preset-derived) so existing projects are unaffected when unset; defaults to \"off\". */\n  workflow_enforcement?: GovernanceWorkflowEnforcement;\n}\n\n/** Restricts extension policy mode values accepted by command, SDK, and storage contracts. */\nexport type ExtensionPolicyMode = \"off\" | \"warn\" | \"enforce\";\n/** Restricts extension trust mode values accepted by command, SDK, and storage contracts. */\nexport type ExtensionTrustMode = \"off\" | \"warn\" | \"enforce\";\n/** Restricts extension sandbox profile values accepted by command, SDK, and storage contracts. */\nexport type ExtensionSandboxProfile = \"none\" | \"restricted\" | \"strict\";\n\n/** Documents the extension policy override settings payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionPolicyOverrideSettings {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Whether disabled applies to this operation. */\n  disabled?: boolean;\n  /** Value that configures or reports require trusted for this contract. */\n  require_trusted?: boolean;\n  /** Value that configures or reports require provenance for this contract. */\n  require_provenance?: boolean;\n  /** Value that configures or reports sandbox profile for this contract. */\n  sandbox_profile?: ExtensionSandboxProfile;\n  /** Value that configures or reports allowed capabilities for this contract. */\n  allowed_capabilities?: string[];\n  /** Value that configures or reports blocked capabilities for this contract. */\n  blocked_capabilities?: string[];\n  /** Value that configures or reports allowed surfaces for this contract. */\n  allowed_surfaces?: string[];\n  /** Value that configures or reports blocked surfaces for this contract. */\n  blocked_surfaces?: string[];\n  /** Value that configures or reports allowed commands for this contract. */\n  allowed_commands?: string[];\n  /** Value that configures or reports blocked commands for this contract. */\n  blocked_commands?: string[];\n  /** Value that configures or reports allowed actions for this contract. */\n  allowed_actions?: string[];\n  /** Value that configures or reports blocked actions for this contract. */\n  blocked_actions?: string[];\n  /** Value that configures or reports allowed services for this contract. */\n  allowed_services?: string[];\n  /** Value that configures or reports blocked services for this contract. */\n  blocked_services?: string[];\n}\n\n/** Documents the extension policy settings payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionPolicySettings {\n  /** Value that configures or reports mode for this contract. */\n  mode: ExtensionPolicyMode;\n  /** Strategy used to control trust behavior. */\n  trust_mode: ExtensionTrustMode;\n  /** Value that configures or reports require provenance for this contract. */\n  require_provenance: boolean;\n  /** Value that configures or reports trusted extensions for this contract. */\n  trusted_extensions: string[];\n  /** Fallback sandbox profile used when callers do not provide an override. */\n  default_sandbox_profile: ExtensionSandboxProfile;\n  /** Value that configures or reports allowed extensions for this contract. */\n  allowed_extensions: string[];\n  /** Value that configures or reports blocked extensions for this contract. */\n  blocked_extensions: string[];\n  /** Value that configures or reports allowed capabilities for this contract. */\n  allowed_capabilities: string[];\n  /** Value that configures or reports blocked capabilities for this contract. */\n  blocked_capabilities: string[];\n  /** Value that configures or reports allowed surfaces for this contract. */\n  allowed_surfaces: string[];\n  /** Value that configures or reports blocked surfaces for this contract. */\n  blocked_surfaces: string[];\n  /** Value that configures or reports allowed commands for this contract. */\n  allowed_commands: string[];\n  /** Value that configures or reports blocked commands for this contract. */\n  blocked_commands: string[];\n  /** Value that configures or reports allowed actions for this contract. */\n  allowed_actions: string[];\n  /** Value that configures or reports blocked actions for this contract. */\n  blocked_actions: string[];\n  /** Value that configures or reports allowed services for this contract. */\n  allowed_services: string[];\n  /** Value that configures or reports blocked services for this contract. */\n  blocked_services: string[];\n  /** Value that configures or reports extension overrides for this contract. */\n  extension_overrides: ExtensionPolicyOverrideSettings[];\n}\n\n/** Documents the agent guidance settings payload exchanged by command, SDK, and package integrations. */\nexport interface AgentGuidanceSettings {\n  /** Value that configures or reports prompt completed for this contract. */\n  prompt_completed: boolean;\n  /** Value that configures or reports declined for this contract. */\n  declined: boolean;\n  /** ISO 8601 timestamp recording when declined occurred. */\n  declined_at: string;\n  /** Value that configures or reports template version for this contract. */\n  template_version: number;\n  /** Value that configures or reports last checked files for this contract. */\n  last_checked_files: string[];\n}\n\n/** Restricts search mutation refresh policy values accepted by command, SDK, and storage contracts. */\nexport type SearchMutationRefreshPolicy =\n  | \"cache_only\"\n  | \"semantic_configured\"\n  | \"semantic_auto\";\n\n/** Documents the search query expansion settings payload exchanged by command, SDK, and package integrations. */\nexport interface SearchQueryExpansionSettings {\n  /** Whether enabled applies to this operation. */\n  enabled: boolean;\n  /** Value that configures or reports provider for this contract. */\n  provider: string;\n}\n\n/** Documents the search rerank settings payload exchanged by command, SDK, and package integrations. */\nexport interface SearchRerankSettings {\n  /** Whether enabled applies to this operation. */\n  enabled: boolean;\n  /** Value that configures or reports model for this contract. */\n  model: string;\n  /** Value that configures or reports top k for this contract. */\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  /** Whether enabled applies to this operation. */\n  enabled: boolean;\n  /** Value that configures or reports max entries for this contract. */\n  max_entries: number;\n  /** Value that configures or reports trigger for this contract. */\n  trigger: \"health_warn\" | \"auto\";\n}\n\n/** Documents the pm settings payload exchanged by command, SDK, and package integrations. */\nexport interface PmSettings {\n  /** Value that configures or reports version for this contract. */\n  version: number;\n  /** Value that configures or reports id prefix for this contract. */\n  id_prefix: string;\n  /** Item id allocation policy: `token_length` is the number of random base36 characters appended to `id_prefix` when minting ids (4–12). Longer tokens shrink cross-branch collision odds for concurrent multi-agent workflows: 4 chars ≈ 1.68M ids (~1% birthday-collision at ~184 items), 6 chars ≈ 2.18B (~1% at ~6.6k items), 8 chars ≈ 2.8T (~1% at ~238k items). */\n  ids: {\n    token_length: number;\n  };\n  /** Value that configures or reports author default for this contract. */\n  author_default: string;\n  /** Value that configures or reports item format for this contract. */\n  item_format: ItemFormat;\n  /** Value that configures or reports locks for this contract. */\n  locks: {\n    ttl_seconds: number;\n    /** Bounded wait budget (milliseconds) for acquiring a contended item lock before surfacing lock_conflict. 0 disables waiting (fail-fast). Overridable per invocation via PM_LOCK_WAIT_MS. */\n    wait_ms: number;\n  };\n  /** Retention policy for local crash-recovery receipts: bulk-mutation rollback checkpoints written by `update-many`/`close-many` AND terminal SDK workspace-transaction journals under `transactions/sdk/`. `pm gc --scope checkpoints` prunes checkpoint files older than `retention_days`; `pm gc --scope transactions` prunes committed/compensated journals older than the same window. Unparseable receipts and in-flight journals are always retained (safety-first, mirroring the stale-lock sweep). */\n  checkpoints: {\n    retention_days: number;\n  };\n  /** Value that configures or reports output for this contract. */\n  output: {\n    default_format: \"toon\" | \"json\";\n  };\n  /** Value that configures or reports history for this contract. */\n  history: {\n    missing_stream: \"auto_create\" | \"strict_error\";\n    compact_policy: HistoryCompactPolicy;\n  };\n  /** Value that configures or reports validation for this contract. */\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    /** Per-type default estimates (minutes) used by `pm validate --auto-fix --fix-scope estimates` to backfill missing `estimated_minutes` (GH-212). Keys are item type names (case-insensitive); values are positive minutes that override the built-in defaults. Empty by default. */\n    estimate_defaults_by_type: Record<string, number>;\n  };\n  /** Value that configures or reports governance for this contract. */\n  governance: GovernanceSettings;\n  /** Value that configures or reports workflow for this contract. */\n  workflow: {\n    definition_of_done: string[];\n  };\n  /** Value that configures or reports testing for this contract. */\n  testing: {\n    record_results_to_items: boolean;\n  };\n  /** Value that configures or reports telemetry for this contract. */\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  /** Value that configures or reports agent guidance for this contract. */\n  agent_guidance: AgentGuidanceSettings;\n  /** Value that configures or reports item types for this contract. */\n  item_types: {\n    definitions: ItemTypeDefinition[];\n  };\n  /** Value that configures or reports schema for this contract. */\n  schema: RuntimeSchemaSettings;\n  /** Value that configures or reports extensions for this contract. */\n  extensions: {\n    enabled: string[];\n    disabled: string[];\n    policy: ExtensionPolicySettings;\n  };\n  /** Value that configures or reports search for this contract. */\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    /** Optional allow-list of corpus field names embedded for semantic search (see DEFAULT_SEARCH_CORPUS_FIELDS in core/search/corpus.ts). When unset or empty, the full default field set is used (backward compatible). When set, only the named fields are embedded — letting teams opt structured signals (priority, assignee, risk, acceptance_criteria, etc.) in/out for token efficiency. Changing this re-flags items stale on the next refresh. */\n    corpus_fields?: string[];\n    mutation_refresh_policy: SearchMutationRefreshPolicy;\n    query_expansion: SearchQueryExpansionSettings;\n    rerank: SearchRerankSettings;\n    /** 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). */\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  /** Value that configures or reports providers for this contract. */\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  /** Value that configures or reports context for this contract. */\n  context: ContextSettings;\n  /** Value that configures or reports vector store for this contract. */\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":"0ac15454-83a5-5908-b602-2f84dcec66c0"}

package/docs/AGENT_GUIDE.md

@@ -50,6 +50,8 @@ Repeated singular/plural list flags accumulate, so `--tag a --tag b` is equivale
 
 `--tags` REPLACES the whole tag list. To edit tags without restating the full set, prefer `--add-tags <value>` (adds without replacing) and `--remove-tags <value>` (prunes) on `create`/`update`/`update-many` (both repeatable; CSV or JSON-array). `--remove-tags` is `update`/`update-many` only. Also note `--expected`/`--actual` are short aliases for `--expected-result`/`--actual-result` on these commands, matching `pm close`.
 
+`--acceptance-criteria`/`--ac` likewise REPLACES the whole criteria value. Prefer `--add-ac <text>` (appends one criterion; deduped on exact text) and `--remove-ac <text>` (removes one criterion by exact text; unmatched selectors surface a `remove_ac_unmatched` warning) on `update`/`update-many` so concurrent branch edits with disjoint additions merge instead of clobbering. Acceptance criteria use semicolons as storage boundaries, so one criterion cannot itself contain a semicolon.
+
 ```bash
 pm update <item-id> --add-tags urgent,backend   # keep existing tags, add two
 pm update <item-id> --remove-tags stale          # drop one, keep the rest
@@ -100,53 +102,53 @@ pm release <item-id>
 
 ## Token-Minimal Retrieval
 
-| Need | Command |
-|------|---------|
-| The single next action + why | `pm next` (concrete ready leaves first; completed-container closeout rows surface only when no leaf work is ready; `--ready-only` for the tightest output) |
-| Next ready work in one epic | `pm next --parent <id>` |
-| Next work and agenda | `pm context --limit 10` |
-| Comprehensive whole-tracker snapshot | `pm context --depth full` (every section, no per-section row cap) |
-| Status of one epic/subtree | `pm context --parent <id> --depth deep` |
-| Relevant items | `pm search "<keywords>" --limit 10` (keyword hits are score-ranked; keyword mode defaults to 50 results, `result.total` reports the full pre-limit count) |
-| Require every query token | `pm search "<keywords>" --match-mode and` (hard-filter; `exact` = contiguous phrase; default `or` adds an all-terms ranking bonus) |
-| Just the match count | `pm search "<keywords>" --count` (no hit rows; `count`/`total` carry the matched total) |
-| Per-query score threshold | `pm search "<keywords>" --min-score 5` (overrides settings `search.score_threshold` for this query) |
-| Every matched row (no cap) | `pm list-all --no-truncate --brief` (alias `--all`; `result.total` reports the full count when a `--limit`/`--offset` truncates) |
-| Item bodies in bulk (one call) | `pm list-open --json --include-body` (avoids one `pm get` per item) |
-| Open work only | `pm search "<keywords>" --status open` (drops closed-history noise; did-you-mean on typos) |
-| Scope search like list | `pm search "<keywords>" --type Task --assignee <name> --parent <id>` (full `pm list` filter parity) |
-| Items changed since last window | `pm list-all --updated-after <prev-run-ISO> --brief` (relative `-2h`/`-7d` also work) |
-| Open items changed today | `pm list-open --today --brief` (local-midnight shorthand; mutually exclusive with `--updated-after`) |
-| Items changed recently | `pm list-all --recent --brief` (last seven days; mutually exclusive with `--updated-after`) |
-| Single item | `pm get <id>` |
-| Full machine payload | `pm get <id> --full --json` |
-| Command flags | `pm <command> --help --json` |
-| Command intent map | `pm contracts --summary --json` (one command plus terse intent per row; use before command-scoped contracts) |
-| Low-noise machine contracts | `pm contracts --command <command> --flags-only --json` |
-| Semantic index refresh | `pm reindex --mode semantic --progress` (stale-first by default; add `--full` to force full rebuild; requires the `search-advanced` package) |
-| Timeline | `pm activity --id <id> --limit 20` |
-| Audited history redaction | `pm history-redact <id> --literal "<secret>" --replacement "[redacted]" --dry-run` |
-| Audited history re-anchor | `pm history-repair <id> --dry-run` (clears drift flagged by `pm health`/`pm validate`) |
-| Register custom item type | `pm schema add-type <Name> --description "<text>" --default-status open` (then `pm create <Name> "..."`) |
-| Remove custom item type | `pm schema remove-type <Name>` (warns if items still use it; built-ins refused) |
-| Register custom status | `pm schema add-status <id> --role <active\|terminal\|...> --alias <name> --order <n>` |
-| Remove custom status | `pm schema remove-status <id>` (warns if items use it; built-in statuses refused) |
-| Agent plan create | `pm plan create --title "<scope>" --harness claude-code --scope "<short>" --claim` |
-| Agent plan create with steps | `pm plan create --title "<scope>" --step "<step 1>" --step "<step 2>" --step "<step 3>"` (repeated `--step` seeds ordered steps) |
-| Agent plan step update | `pm plan update-step <plan-id> plan-step-001 --step-status in_progress --step-evidence "<short>"` |
-| Agent plan read | `pm plan show <plan-id> --depth brief` (or `--fields id,title,steps_summary`) |
-| Materialize plan steps | `pm plan materialize <plan-id> --steps plan-step-002 --materialize-type Task` |
-| Dependencies | `pm deps <id> --format tree` |
-| Graph queries | `pm graph successors <id> --limit 20` (also `ancestors`, `paths`, `impact`, `analyze`, `audit`, `communities`, `redundancy`, `dominators`, `plan`) |
-| Bulk update by id allowlist | `pm update-many --ids pm-a,pm-b --priority 1 --dry-run` (preview, then drop `--dry-run`) |
-| Audited bulk close (sprint closeout) | `pm close-many --filter-sprint <s> --reason "<text>" --dry-run` (full `pm close` semantics per item; `--rollback <id>` to undo) |
-| Local docs routing | `pm install guide-shell --project`, then `pm guide <topic>` |
-| Compact mutation echo | `pm --no-changed-fields create "..."` (drops the redundant `changed_fields` array, keeps `changed_field_count`) |
-| Minimal mutation echo | `pm --id-only create "..."` (prints only id and status for single-item mutations) |
-| Duplicate close | `pm close <duplicate> --duplicate-of <canonical>` (or `-d <canonical>`) |
-| Long body from a file | `pm create <Type> "<title>" --body-file ./spec.md` (also on `pm update`; mutually exclusive with `--body`) |
-| Close with short flags | `pm close <id> -r "<reason>"` / `-m "<history msg>"` / `-d <canonical>` |
-| Close via resolution only | `pm close <id> --resolution "<summary>"` (used as the close reason when one is required) |
+| Need                                 | Command                                                                                                                                                    |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The single next action + why         | `pm next` (concrete ready leaves first; completed-container closeout rows surface only when no leaf work is ready; `--ready-only` for the tightest output) |
+| Next ready work in one epic          | `pm next --parent <id>`                                                                                                                                    |
+| Next work and agenda                 | `pm context --limit 10`                                                                                                                                    |
+| Comprehensive whole-tracker snapshot | `pm context --depth full` (every section, no per-section row cap)                                                                                          |
+| Status of one epic/subtree           | `pm context --parent <id> --depth deep`                                                                                                                    |
+| Relevant items                       | `pm search "<keywords>" --limit 10` (keyword hits are score-ranked; keyword mode defaults to 50 results, `result.total` reports the full pre-limit count)  |
+| Require every query token            | `pm search "<keywords>" --match-mode and` (hard-filter; `exact` = contiguous phrase; default `or` adds an all-terms ranking bonus)                         |
+| Just the match count                 | `pm search "<keywords>" --count` (no hit rows; `count`/`total` carry the matched total)                                                                    |
+| Per-query score threshold            | `pm search "<keywords>" --min-score 5` (overrides settings `search.score_threshold` for this query)                                                        |
+| Every matched row (no cap)           | `pm list-all --no-truncate --brief` (alias `--all`; `result.total` reports the full count when a `--limit`/`--offset` truncates)                           |
+| Item bodies in bulk (one call)       | `pm list-open --json --include-body` (avoids one `pm get` per item)                                                                                        |
+| Open work only                       | `pm search "<keywords>" --status open` (drops closed-history noise; did-you-mean on typos)                                                                 |
+| Scope search like list               | `pm search "<keywords>" --type Task --assignee <name> --parent <id>` (full `pm list` filter parity)                                                        |
+| Items changed since last window      | `pm list-all --updated-after <prev-run-ISO> --brief` (relative `-2h`/`-7d` also work)                                                                      |
+| Open items changed today             | `pm list-open --today --brief` (local-midnight shorthand; mutually exclusive with `--updated-after`)                                                       |
+| Items changed recently               | `pm list-all --recent --brief` (last seven days; mutually exclusive with `--updated-after`)                                                                |
+| Single item                          | `pm get <id>`                                                                                                                                              |
+| Full machine payload                 | `pm get <id> --full --json`                                                                                                                                |
+| Command flags                        | `pm <command> --help --json`                                                                                                                               |
+| Command intent map                   | `pm contracts --summary --json` (one command plus terse intent per row; use before command-scoped contracts)                                               |
+| Low-noise machine contracts          | `pm contracts --command <command> --flags-only --json`                                                                                                     |
+| Semantic index refresh               | `pm reindex --mode semantic --progress` (stale-first by default; add `--full` to force full rebuild; requires the `search-advanced` package)               |
+| Timeline                             | `pm activity --id <id> --limit 20`                                                                                                                         |
+| Audited history redaction            | `pm history-redact <id> --literal "<secret>" --replacement "[redacted]" --dry-run`                                                                         |
+| Audited history re-anchor            | `pm history-repair <id> --dry-run` (clears drift flagged by `pm health`/`pm validate`)                                                                     |
+| Register custom item type            | `pm schema add-type <Name> --description "<text>" --default-status open` (then `pm create <Name> "..."`)                                                   |
+| Remove custom item type              | `pm schema remove-type <Name>` (warns if items still use it; built-ins refused)                                                                            |
+| Register custom status               | `pm schema add-status <id> --role <active\|terminal\|...> --alias <name> --order <n>`                                                                      |
+| Remove custom status                 | `pm schema remove-status <id>` (warns if items use it; built-in statuses refused)                                                                          |
+| Agent plan create                    | `pm plan create --title "<scope>" --harness claude-code --scope "<short>" --claim`                                                                         |
+| Agent plan create with steps         | `pm plan create --title "<scope>" --step "<step 1>" --step "<step 2>" --step "<step 3>"` (repeated `--step` seeds ordered steps)                           |
+| Agent plan step update               | `pm plan update-step <plan-id> plan-step-001 --step-status in_progress --step-evidence "<short>"`                                                          |
+| Agent plan read                      | `pm plan show <plan-id> --depth brief` (or `--fields id,title,steps_summary`)                                                                              |
+| Materialize plan steps               | `pm plan materialize <plan-id> --steps plan-step-002 --materialize-type Task`                                                                              |
+| Dependencies                         | `pm deps <id> --format tree`                                                                                                                               |
+| Graph queries                        | `pm graph successors <id> --limit 20` (also `ancestors`, `paths`, `impact`, `analyze`, `audit`, `communities`, `redundancy`, `dominators`, `plan`)         |
+| Bulk update by id allowlist          | `pm update-many --ids pm-a,pm-b --priority 1 --dry-run` (preview, then drop `--dry-run`)                                                                   |
+| Audited bulk close (sprint closeout) | `pm close-many --filter-sprint <s> --reason "<text>" --dry-run` (full `pm close` semantics per item; `--rollback <id>` to undo)                            |
+| Local docs routing                   | `pm install guide-shell --project`, then `pm guide <topic>`                                                                                                |
+| Compact mutation echo                | `pm --no-changed-fields create "..."` (drops the redundant `changed_fields` array, keeps `changed_field_count`)                                            |
+| Minimal mutation echo                | `pm --id-only create "..."` (prints only id and status for single-item mutations)                                                                          |
+| Duplicate close                      | `pm close <duplicate> --duplicate-of <canonical>` (or `-d <canonical>`)                                                                                    |
+| Long body from a file                | `pm create <Type> "<title>" --body-file ./spec.md` (also on `pm update`; mutually exclusive with `--body`)                                                 |
+| Close with short flags               | `pm close <id> -r "<reason>"` / `-m "<history msg>"` / `-d <canonical>`                                                                                    |
+| Close via resolution only            | `pm close <id> --resolution "<summary>"` (used as the close reason when one is required)                                                                   |
 
 Default TOON output is preferred for model-readable loops. Use `--json` only when strict parsing is needed.
 
@@ -196,6 +198,15 @@ Use these defaults unless the task requires otherwise:
 - `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`.
 
+## Multi-Branch and Worktree Workflows
+
+Concurrent agents work on ordinary Git branches/worktrees; tracker artifacts need the semantic merge contract from [Merge Safety](MERGE_SAFETY.md). The short loop:
+
+- After a fresh clone or new worktree, run `pm merge install` once so the field-aware merge drivers back the committed `.gitattributes` fence.
+- After every merge that touches `.agents/pm`, run `pm validate --check-storage-integrity` and `pm history --verify --strict-exit`; follow the remediation output (`pm history-repair` wiring included).
+- Repositories fanning out many branches between merges should raise id entropy: `pm config project set ids_token_length 6`.
+- Use `--add-ac`/`--remove-ac` (not `--ac`) so concurrent acceptance-criteria edits merge instead of clobbering.
+
 ## Self-Repair Remediation
 
 When gating on `pm health` / `pm validate`, read the executable fix command from the output instead of hardcoding a warning-code-to-command mapping:

package/docs/COMMANDS.md

@@ -389,6 +389,13 @@ pm update pm-abc1 --remove-tags stale            # drops "stale", keeps the rest
 pm create "New backend task" --add-tags backend,p1
 ```
 
+Acceptance criteria get the same additive treatment on `update`/`update-many`: `--acceptance-criteria`/`--ac` REPLACES the whole value, while `--add-ac <text>` appends one criterion (repeatable; deduped on exact text) and `--remove-ac <text>` removes one criterion by exact text match (repeatable; a non-matching selector adds a `remove_ac_unmatched:<text>` warning instead of silently no-oping). Criteria are stored joined by `` ;  ``, so one criterion cannot contain a semicolon. Disjoint `--add-ac` edits from concurrent agents/branches merge cleanly instead of clobbering each other.
+
+```bash
+pm update pm-abc1 --add-ac "error path covered by a regression test"
+pm update pm-abc1 --remove-ac "superseded manual QA step"
+```
+
 Update existing work:
 
 ```bash

package/docs/CONFIGURATION.md

@@ -57,6 +57,7 @@ When `settings.json` cannot be loaded, `pm` falls back to built-in defaults and
 | Setting | Purpose |
 |---------|---------|
 | `id_prefix` | generated item ID prefix, default `pm-` |
+| `ids.token_length` | random base36 token length for newly minted item ids (4-12, default `4`); raise it to shrink cross-branch id collision odds in concurrent multi-agent workflows (see [Merge Safety](MERGE_SAFETY.md)) |
 | `author_default` | fallback mutation author |
 | `item_format` | item storage format (`toon` writes; legacy markdown is read/migrate only) |
 | `output.default_format` | default renderer, usually `toon` |
@@ -81,6 +82,7 @@ Each scalar setting above is settable via `pm config set <key> <value>` (no hand
 
 ```bash
 pm config project set id_prefix task                       # (id_prefix) IDs become task-xxxx
+pm config project set ids_token_length 6                   # (ids.token_length) integer 4..12; longer ids for multi-agent collision safety
 pm config project set author_default release-bot           # (author_default) default mutation author
 pm config project set output_default_format json           # (output.default_format) toon | json
 pm config project set locks_ttl_seconds 60                 # (locks.ttl_seconds) integer >= 1

package/docs/MERGE_SAFETY.md

@@ -0,0 +1,99 @@
+# Multi-Branch Tracker Merge Safety
+
+Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fence-coverage completeness and drift detection are tracked by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
+
+pm stores project context as reviewable repository files. Concurrent agents can therefore use ordinary branches and worktrees, but tracker artifacts need semantic merge behavior: raw line merging cannot preserve TOON collection counts, JSON object structure, or append-only history hash chains.
+
+## Install the repository merge contract
+
+Run this once per clone after `pm init`:
+
+```bash
+pm merge install
+git add .gitattributes
+git commit -m "chore(pm): install tracker merge drivers"
+```
+
+`pm merge install` writes an idempotent, fenced `.gitattributes` block and repository-local `git config` entries. The attributes are committed; the driver commands are clone-local, so every collaborator and fresh CI clone that performs merges must run the install command.
+
+### Fence coverage contract
+
+The fenced block is generated by one shared coverage contract (`buildMergeAttributePatterns`) covering every mergeable artifact class: per-type item folders (`*.toon`/`*.md`), all tracker `**/*.jsonl` paths under the relationship-event driver with the more-specific `history/*.jsonl` rule overriding history streams, `settings.json`, and `schema/*.json`. The broad JSONL rule is required because `RelationshipEventStore` supports package-owned custom relative paths anywhere below the tracker root. Two mechanisms keep the committed fence from drifting out of that contract:
+
+- `pm schema add-type` / `pm schema remove-type` refresh the fence automatically when it is installed (warning `merge_fence_refreshed`); repos inside git that never installed it get the actionable `merge_fence_not_installed` hint instead.
+- `pm validate` (the `storage_integrity` check) audits the committed fence against the active schema's type folders and reports `validate_merge_fence_drift` with the exact missing/stale attribute lines when they diverge — for example after editing type folders out-of-band. Rerun `pm merge install` and commit `.gitattributes` to clear it.
+
+Preview without mutation:
+
+```bash
+pm merge install --dry-run --json
+```
+
+## Artifact semantics
+
+| Artifact                         | Driver                              | Merge behavior                                                                                                                                                                                                                               |
+| -------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Item `.toon` / `.md`             | `pm-item-toon` / `pm-item-markdown` | Three-way field merge; format-specific drivers avoid passing the repository path through Git's shell command, append-like collections use set union, `updated_at` uses latest timestamp, and canonical serialization recomputes TOON counts. |
+| `history/*.jsonl`                | `pm-history`                        | Preserves the common prefix and both divergent suffixes, orders deterministically, then re-anchors the resulting hash chain.                                                                                                                 |
+| tracker `**/*.jsonl` except the later `history/*.jsonl` override | `pm-relationship` | Covers default and package-owned custom relationship event paths, unions divergent suffixes by `eventId` (timestamp-ordered, ours-first on ties), and renumbers `sequence` consecutively so the strict-sequence store loader accepts the merged stream. |
+| `settings.json`, `schema/*.json` | `pm-json`                           | Recursively merges objects per key; disjoint settings changes compose without a whole-file conflict.                                                                                                                                         |
+
+When both sides change the same scalar or JSON leaf differently, the driver writes a parseable preferred-side result but exits nonzero. Git keeps the path conflicted so a human or coordinating agent must review the losing value and explicitly `git add` the resolution. Use `--prefer theirs` only when that is the intended resolution policy.
+
+The underlying public SDK exports are `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, `runMergeInstall`, `refreshMergeAttributeFenceIfInstalled`, `buildMergeAttributePatterns`, and `auditMergeAttributeFence` from `@unbrained/pm-cli/sdk`. Hosts can embed the same semantics without shelling out.
+
+## Cross-branch id collision safety
+
+Item ids are `<prefix>` plus random base36 characters, and uniqueness is only probed against the local working tree — two agents branching from the same commit can mint the same id for different items (GH-600 / pm-pibw). Two controls bound that risk:
+
+- **Entropy budget** — `ids.token_length` in `settings.json` (default 4, accepted range 4–12) sets the random token length for newly minted ids. Approximate 1%-birthday-collision workloads per length: 4 chars ≈ 1.68M ids (~184 concurrent unsynced creations), 6 chars ≈ 2.18B (~6.6k), 8 chars ≈ 2.8T (~238k). Multi-agent repositories that fan out many branches between merges should raise it, e.g. `pm config project set ids_token_length 6`.
+- **Post-merge detection** — the `storage_integrity` validate check reports `validate_storage_duplicate_item_ids` whenever one id is claimed by multiple item documents (across type folders or format variants), which is how a same-id/different-item merge materializes. Remediation: keep one document, recreate the other item under a fresh id (`pm copy` then delete the colliding file), and re-point any dependencies.
+
+## Required post-merge gate
+
+After every branch merge that touches `.agents/pm`, run:
+
+```bash
+pm validate --check-history-drift --strict-exit
+pm history <item-id> --verify --strict-exit
+```
+
+The default validation surface includes `storage_integrity`. It fails on unreadable item documents, history conflict markers, malformed history tails, live items whose latest history operation is `delete` (a delete/modify resurrection candidate), and unparseable settings/schema files. This prevents the ordinary tolerant read path from turning corruption into a green gate.
+
+A history union can be structurally valid while replayed history and the chosen item document describe different effective state. In that case inspect both authors' events before reconciliation, then run the audited repair:
+
+```bash
+pm history <item-id> --verify --strict-exit
+pm history-repair <item-id> --dry-run
+pm history-repair <item-id>
+pm validate --check-history-drift --strict-exit
+```
+
+`history-repair` records the reconciliation patch and surfaces discarded event authors/operations when the on-disk document would otherwise revert effective merged history. Re-apply any intended losing mutation as a normal `pm update` so it remains explicit and auditable.
+
+## Delete versus modify policy
+
+A delete on one branch and an edit on another is not safely resolvable by a generic file driver. The merged workspace must not silently resurrect the item. `storage_integrity` reports the live document plus delete-terminated history as a hard finding. The coordinator chooses one policy explicitly:
+
+- Honor deletion: remove the live item document, keep its append-only history, and commit the resolution.
+- Honor modification: restore/recreate through pm so the history contains an explicit post-delete operation and rationale.
+
+Never remove conflict markers manually while leaving the authoritative item and history semantically inconsistent.
+
+## Runtime receipts and retention
+
+`transactions/` and `checkpoints/` are per-branch crash-recovery state, not shared project context. `pm init` places both below the resolved tracker root in the managed `.gitignore` block, including custom `--pm-path` roots.
+
+Terminal SDK transaction journals use the same `checkpoints.retention_days` policy as rollback checkpoints. The default GC sweep includes both receipt classes:
+
+```bash
+pm gc --dry-run
+pm gc --scope transactions --dry-run
+pm gc --scope transactions
+```
+
+Only aged `committed` or `compensated` journals are removed. `applying`, `compensating`, unreadable, and unparseable journals are always retained so cleanup cannot destroy live recovery state.
+
+## Temporary-clone acceptance test
+
+Before releasing merge-contract changes, validate the packed package in a temporary Git repository: initialize pm, install the merge contract, create one base item, branch twice, append disjoint metadata/history on both branches, merge, and run the strict validation commands above. Include a same-key conflict case and prove Git leaves it unresolved while the output remains parseable.

package/docs/README.md

@@ -43,6 +43,7 @@ pm guide release --json
 - [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.
 - [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md) - the stability guarantees and contract surface package authors build against.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
+- [Multi-Branch Merge Safety](MERGE_SAFETY.md) - semantic tracker merge drivers, post-merge integrity gates, delete/modify policy, and recovery-receipt retention.
 - [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
 - [Native ChatGPT and Codex Plugin Implementation Plan](CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md) - official-source
   research, current-state audit, target architectures, security, testing, and phased remediation plan.