@unbrained/pm-cli 2026.8.23 → 2026.8.24

package/docs/SCRIPTING.md

@@ -1,6 +1,6 @@
 # CLI Scripting Contract
 
-Tracked by [pm-psy1](../.agents/pm/tasks/pm-psy1.toon), [pm-hqa8g1](../.agents/pm/tasks/pm-hqa8g1.toon), [pm-gknu](../.agents/pm/issues/pm-gknu.toon), [pm-999jh7](../.agents/pm/issues/pm-999jh7.toon), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
+Tracked by [pm-psy1](../.agents/pm/tasks/pm-psy1.toon), [pm-hqa8g1](../.agents/pm/tasks/pm-hqa8g1.toon), [pm-gknu](../.agents/pm/issues/pm-gknu.toon), [pm-999jh7](../.agents/pm/issues/pm-999jh7.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), [pm-3oq022](../.agents/pm/issues/pm-3oq022.toon), [pm-iktj](../.agents/pm/tasks/pm-iktj.toon), and [pm-kexu](../.agents/pm/issues/pm-kexu.toon).
 
 Use this contract when composing `pm` with shells, CI runners, `jq`, or another process. Exact flags remain discoverable from `pm <command> --help --json` and `pm contracts --command <command> --flags-only --json`.
 
@@ -14,8 +14,8 @@ Use this contract when composing `pm` with shells, CI runners, `jq`, or another
 | `3`  | Requested tracker or resource was not found.                                     | Correct the path or ID.                              |
 | `4`  | State or concurrency conflict.                                                   | Refresh live state before deciding whether to retry. |
 | `5`  | A required dependency operation failed.                                          | Inspect the dependency evidence before retrying.     |
-| `6`  | The request succeeded but matched nothing to change.                              | Treat as success and inspect the effect receipt.      |
-| `7`  | The request succeeded and changed only part of the selected targets.              | Treat as success and inspect unmatched/skipped rows.  |
+| `6`  | The request succeeded but matched nothing to change.                             | Treat as success and inspect the effect receipt.     |
+| `7`  | The request succeeded and changed only part of the selected targets.             | Treat as success and inspect unmatched/skipped rows. |
 
 Exits `0`, `6`, and `7` are successful outcomes. Bulk mutation envelopes repeat
 the distinction as `outcome: effect`, `outcome: no_effect`, or `outcome:
@@ -134,6 +134,65 @@ else
 fi
 ```
 
+Bulk selectors on `update-many`, `close-many`, and `history-compact` accept the
+same explicit ID grammar through three CLI channels: comma/newline-delimited
+argv text, `-` for stdin, and `@path` for a UTF-8 file. This makes a
+read-selector-write pipeline executable without `xargs` command fan-out:
+
+```bash
+pm list --status open,in_progress --fields id,priority --json |
+  jq -r '.items[] | select(.priority >= 2) | .id' |
+  pm update-many --ids - --priority 1 --dry-run --json
+
+pm close-many --ids @reviewed-ids.txt \
+  --reason "Reviewed batch completed" --dry-run --json
+
+pm list --status closed --fields id --json |
+  jq -r '.items[].id' |
+  pm history-compact --ids - --dry-run --json
+```
+
+An unreadable `@path`, empty stdin, or empty file fails before the tracker is
+read or mutated. `unmatched_ids` means the requested ID does not exist; an
+existing ID excluded by another filter is not misreported as nonexistent.
+Apply-mode exit `6`/`7` and the structured effect receipt remain authoritative.
+
+`update-many --dry-run` may be filter-only. It returns the matched rows with an
+empty `planned_update_options` object and empty per-row `changes`, which is a
+bounded way to validate a selector before choosing a mutation. The same
+filter-only invocation without `--dry-run` is rejected with exit `2`.
+
+Direct SDK and MCP callers may pass `ids` as a string, a finite numeric scalar,
+or an array of string and finite numeric IDs. The SDK normalizes every accepted
+shape through the same stable-deduplicating parser; non-finite numbers and
+unsupported explicit selector values are rejected before target selection:
+
+```ts
+import { PmClient } from "@unbrained/pm-cli/sdk";
+
+const pm = new PmClient({ pmRoot: ".agents/pm" });
+await pm.run("update-many", {
+  options: {
+    ids: ["pm-a1b2", "pm-c3d4"],
+    priority: 1,
+    dryRun: true,
+  },
+});
+```
+
+File-reading text flags use the same stdin sentinel. `--body-file -` reads a
+create/update body, while `comments`, `notes`, and `learnings` accept
+`--file -`. Real file paths remain compatible:
+
+```bash
+generate_body | pm create --title "Generated plan" --body-file -
+render_review | pm comments pm-a1b2 --file -
+```
+
+Each command invocation may consume stdin for only one option. Competing
+stdin-backed inputs such as `--description - --body-file -` are rejected before
+the stream is read.
+
 Use NDJSON for streaming row-by-row tools:
 
 ```bash

package/docs/SDK.md

@@ -2046,6 +2046,8 @@ export default defineExtension({
     api.registerCommand({
       name: "hello",
       action: "hello",
+      tier: "standard",
+      family: "extensions",
       description: "Return a deterministic hello payload.",
       intent: "verify SDK extension activation",
       examples: ["pm hello"],
@@ -2100,6 +2102,12 @@ For a complete commands-capability package that combines `registerCommand`,
 `registerFlags`, and `registerParser`, see the first-party
 [pm-command-kit exemplar](../packages/pm-command-kit/README.md).
 
+Every command definition can declare its agent-surface `tier` (`core`,
+`standard`, `full`, or `internal`) and capability `family`. These are the same
+fields projected into CLI help, completion, MCP profiles, workspace contracts,
+and generated routing documentation. Omitted package values normalize to
+`standard` and `extensions`.
+
 For a generated starter, use `pm package init ./my-package`. Pass
 `--capability hooks` to scaffold a command plus an `afterCommand` lifecycle
 reactor and a runnable `node:test` file that exercises

package/docs/generated/AGENT_CAPABILITY_ROUTING.md

@@ -0,0 +1,17 @@
+# Generated agent capability routing
+
+Tracker: `pm-kxci8x`.
+
+This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it manually.
+
+| Capability family | Commands |
+| --- | --- |
+| workspace | `init`, `config`, `merge`, `schema`, `profile`, `telemetry`, `health`, `gc`, `workspace` |
+| intake | `create`, `copy`, `focus`, `restore` |
+| context | `list`, `aggregate`, `context`, `get`, `search`, `duplicates`, `eval`, `next`, `activity`, `stats`, `help` |
+| lifecycle | `update`, `update-many`, `close`, `close-many`, `delete`, `claim`, `release`, `start-task`, `pause-task`, `close-task` |
+| evidence | `history`, `events`, `history-redact`, `history-repair`, `history-compact`, `history-author-acknowledge`, `append`, `comments`, `notes`, `learnings`, `files`, `docs` |
+| graph | `graph`, `deps`, `plan` |
+| quality | `test`, `test-all`, `validate`, `assurance`, `contracts` |
+| automation | `meet`, `event`, `remind` |
+| extensions | `extension`, `package`, `packages`, `install`, `upgrade` |

package/docs/generated/AGENT_COMMAND_SURFACE.md

@@ -4,7 +4,7 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 
 | Command | Minimum visibility tier | Capability family |
 | --- | --- | --- |
-| `init` | full | workspace |
+| `init` | core | workspace |
 | `config` | standard | workspace |
 | `extension` | full | extensions |
 | `package` | full | extensions |

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -0,0 +1,355 @@
+# Generated refusal closure census
+
+Tracker: `pm-f05lsg`.
+
+Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.
+
+- Catalog error codes: 338
+- Executable error codes: 16
+- Executable-code ratchet floor: 16
+- Required executable canonical codes: `bulk_ids_input_empty`, `bulk_ids_input_missing_path`, `bulk_ids_input_unreadable`, `invalid_argument_value`, `missing_lifecycle_target`, `missing_required_argument`, `projection_options_mutually_exclusive`, `tracker_not_initialized`, `tracker_root_missing`, `tracker_root_not_directory`, `tracker_root_unreadable`, `unknown_context_intent`, `unknown_field_projection`, `unknown_option`, `unknown_subcommand`
+- Uncovered error codes: 322
+- Coverage fraction: 0.047337
+- Closed-domain probes: 18
+- Grammar probes: 95
+
+| Error code | Canonical code | Disposition | Evidence kinds | Probe count |
+| --- | --- | --- | --- | --- |
+| `acceptance_criteria_mutation_conflict` | `acceptance_criteria_mutation_conflict` | uncovered | none | 0 |
+| `acceptance_criteria_remove_unmatched` | `acceptance_criteria_remove_unmatched` | uncovered | none | 0 |
+| `acceptance_criteria_semicolon_forbidden` | `acceptance_criteria_semicolon_forbidden` | uncovered | none | 0 |
+| `accepted_rejected_value` | `accepted_rejected_value` | uncovered | none | 0 |
+| `alias_collision` | `alias_collision` | uncovered | none | 0 |
+| `alias_target_missing` | `alias_target_missing` | uncovered | none | 0 |
+| `already_claimed_by` | `already_claimed_by` | uncovered | none | 0 |
+| `ambiguous_option_combination` | `ambiguous_option_combination` | uncovered | none | 0 |
+| `annotation_alias_conflict` | `annotation_alias_conflict` | uncovered | none | 0 |
+| `annotation_flag_like_value` | `annotation_flag_like_value` | uncovered | none | 0 |
+| `annotation_message_without_text` | `annotation_message_without_text` | uncovered | none | 0 |
+| `annotation_transposed_subcommand` | `annotation_transposed_subcommand` | uncovered | none | 0 |
+| `append_empty_body` | `append_empty_body` | uncovered | none | 0 |
+| `assurance_registry_invalid` | `assurance_registry_invalid` | uncovered | none | 0 |
+| `body_file_conflicts_with_body` | `body_file_conflicts_with_body` | uncovered | none | 0 |
+| `body_file_missing_path` | `body_file_missing_path` | uncovered | none | 0 |
+| `body_file_unreadable` | `body_file_unreadable` | uncovered | none | 0 |
+| `budget_exceeded` | `budget_exceeded` | uncovered | none | 0 |
+| `bulk_ids_input_empty` | `bulk_ids_input_empty` | executable | owned_state | 1 |
+| `bulk_ids_input_missing_path` | `bulk_ids_input_missing_path` | executable | owned_state | 1 |
+| `bulk_ids_input_unreadable` | `bulk_ids_input_unreadable` | executable | owned_state | 1 |
+| `bundle_integrity_torn_install` | `bundle_integrity_torn_install` | uncovered | none | 0 |
+| `capability_undeclared` | `capability_undeclared` | uncovered | none | 0 |
+| `capability_unused` | `capability_unused` | uncovered | none | 0 |
+| `child_projection_item_bound_exceeded` | `child_projection_item_bound_exceeded` | uncovered | none | 0 |
+| `close_reason_required` | `close_reason_required` | uncovered | none | 0 |
+| `close_through_update` | `close_through_update` | uncovered | none | 0 |
+| `close_validation_missing_fields` | `close_validation_missing_fields` | uncovered | none | 0 |
+| `collected_zero_items` | `collected_zero_items` | uncovered | none | 0 |
+| `collection_transposed_subcommand` | `collection_transposed_subcommand` | uncovered | none | 0 |
+| `command_failed` | `command_failed` | uncovered | none | 0 |
+| `command_namespace` | `command_namespace` | uncovered | none | 0 |
+| `command_override_conflict` | `command_override_conflict` | uncovered | none | 0 |
+| `config_duplicate` | `config_duplicate` | uncovered | none | 0 |
+| `config_key_unknown` | `config_key_unknown` | uncovered | none | 0 |
+| `config_value_invalid` | `config_value_invalid` | uncovered | none | 0 |
+| `conflicting_lifecycle_owner` | `conflicting_lifecycle_owner` | uncovered | none | 0 |
+| `context_signal_store_invalid` | `context_signal_store_invalid` | uncovered | none | 0 |
+| `context_signal_store_stale` | `context_signal_store_stale` | uncovered | none | 0 |
+| `context_signal_store_write_failed` | `context_signal_store_write_failed` | uncovered | none | 0 |
+| `context_takes_no_item_argument` | `context_takes_no_item_argument` | uncovered | none | 0 |
+| `core_item_field_requires_dedicated_flag` | `core_item_field_requires_dedicated_flag` | uncovered | none | 0 |
+| `create_positional_type_without_title` | `create_positional_type_without_title` | uncovered | none | 0 |
+| `dependency_edge_not_allowed` | `dependency_edge_not_allowed` | uncovered | none | 0 |
+| `dependency_flag_value_invalid` | `dependency_flag_value_invalid` | uncovered | none | 0 |
+| `dependency_remove_no_match` | `dependency_remove_no_match` | uncovered | none | 0 |
+| `dependency_target_not_found` | `dependency_target_not_found` | uncovered | none | 0 |
+| `dependency_temporal_order_invalid` | `dependency_temporal_order_invalid` | uncovered | none | 0 |
+| `duplicate_canonical_flag` | `duplicate_canonical_flag` | uncovered | none | 0 |
+| `duplicate_command` | `duplicate_command` | uncovered | none | 0 |
+| `duplicate_destination` | `duplicate_destination` | uncovered | none | 0 |
+| `duplicate_edge` | `duplicate_edge` | uncovered | none | 0 |
+| `duplicate_observation` | `duplicate_observation` | uncovered | none | 0 |
+| `duplicate_probe` | `duplicate_probe` | uncovered | none | 0 |
+| `duplicate_sweep_cost_limit` | `duplicate_sweep_cost_limit` | uncovered | none | 0 |
+| `duplicate_target_circular` | `duplicate_target_circular` | uncovered | none | 0 |
+| `duplicate_target_is_duplicate` | `duplicate_target_is_duplicate` | uncovered | none | 0 |
+| `duplicate_target_missing` | `duplicate_target_missing` | uncovered | none | 0 |
+| `duplicate_target_self` | `duplicate_target_self` | uncovered | none | 0 |
+| `empty_corpus` | `empty_corpus` | uncovered | none | 0 |
+| `empty_surface` | `empty_surface` | uncovered | none | 0 |
+| `error_code_mismatch` | `error_code_mismatch` | uncovered | none | 0 |
+| `event_cursor_query_mismatch` | `event_cursor_query_mismatch` | uncovered | none | 0 |
+| `event_index_unavailable` | `event_index_unavailable` | uncovered | none | 0 |
+| `exit_code_mismatch` | `exit_code_mismatch` | uncovered | none | 0 |
+| `extension_command_activation_failed` | `extension_command_activation_failed` | uncovered | none | 0 |
+| `extension_dependency_name_unsafe` | `extension_dependency_name_unsafe` | uncovered | none | 0 |
+| `extension_dependency_spec_invalid` | `extension_dependency_spec_invalid` | uncovered | none | 0 |
+| `extension_dependency_version_unsafe` | `extension_dependency_version_unsafe` | uncovered | none | 0 |
+| `extension_install_soft_failed` | `extension_install_soft_failed` | uncovered | none | 0 |
+| `extension_install_source_contains_destination` | `extension_install_source_contains_destination` | uncovered | none | 0 |
+| `extension_item_field_reserved` | `extension_item_field_reserved` | uncovered | none | 0 |
+| `extension_item_field_type_conflict` | `extension_item_field_type_conflict` | uncovered | none | 0 |
+| `extension_item_field_unknown` | `extension_item_field_unknown` | uncovered | none | 0 |
+| `extension_mutation_guard_failed` | `extension_mutation_guard_failed` | uncovered | none | 0 |
+| `extension_mutation_guard_invalid_decision` | `extension_mutation_guard_invalid_decision` | uncovered | none | 0 |
+| `extension_mutation_guard_invalid_denial` | `extension_mutation_guard_invalid_denial` | uncovered | none | 0 |
+| `extension_mutation_guard_timed_out` | `extension_mutation_guard_timed_out` | uncovered | none | 0 |
+| `extension_update_health_partial_coverage` | `extension_update_health_partial_coverage` | uncovered | none | 0 |
+| `field_duplicate` | `field_duplicate` | uncovered | none | 0 |
+| `field_invalid` | `field_invalid` | uncovered | none | 0 |
+| `field_mcp_input_collision` | `field_mcp_input_collision` | uncovered | none | 0 |
+| `github_source_entry_unbuilt` | `github_source_entry_unbuilt` | uncovered | none | 0 |
+| `hierarchy_cardinality_created` | `hierarchy_cardinality_created` | uncovered | none | 0 |
+| `hierarchy_cycle_created` | `hierarchy_cycle_created` | uncovered | none | 0 |
+| `hierarchy_parent_divergence_created` | `hierarchy_parent_divergence_created` | uncovered | none | 0 |
+| `history_author_acknowledge_plan_conflict` | `history_author_acknowledge_plan_conflict` | uncovered | none | 0 |
+| `history_author_acknowledge_plan_fingerprint_required` | `history_author_acknowledge_plan_fingerprint_required` | uncovered | none | 0 |
+| `history_author_acknowledge_preview_limit_invalid` | `history_author_acknowledge_preview_limit_invalid` | uncovered | none | 0 |
+| `history_author_acknowledge_required_values_missing` | `history_author_acknowledge_required_values_missing` | uncovered | none | 0 |
+| `history_author_acknowledge_selector_conflict` | `history_author_acknowledge_selector_conflict` | uncovered | none | 0 |
+| `history_author_acknowledge_selector_required` | `history_author_acknowledge_selector_required` | uncovered | none | 0 |
+| `history_author_acknowledge_target_not_actionable` | `history_author_acknowledge_target_not_actionable` | uncovered | none | 0 |
+| `history_author_acknowledge_target_unreadable` | `history_author_acknowledge_target_unreadable` | uncovered | none | 0 |
+| `history_drift_chain_mismatch` | `history_drift_chain_mismatch` | uncovered | none | 0 |
+| `history_drift_hash_mismatch` | `history_drift_hash_mismatch` | uncovered | none | 0 |
+| `history_drift_missing_stream` | `history_drift_missing_stream` | uncovered | none | 0 |
+| `history_drift_unreadable_stream` | `history_drift_unreadable_stream` | uncovered | none | 0 |
+| `history_merge_conflict_markers_detected` | `merge_conflict_markers_detected` | uncovered | none | 0 |
+| `history_stream_over_compact_threshold` | `history_stream_over_compact_threshold` | uncovered | none | 0 |
+| `history_target_out_of_range` | `history_target_out_of_range` | uncovered | none | 0 |
+| `history_unknown_author_events` | `history_unknown_author_events` | uncovered | none | 0 |
+| `host_environment_capacity_fault` | `host_environment_capacity_fault` | uncovered | none | 0 |
+| `host_environment_operation_invalid` | `host_environment_operation_invalid` | uncovered | none | 0 |
+| `host_environment_permission_fault` | `host_environment_permission_fault` | uncovered | none | 0 |
+| `host_environment_resource_fault` | `host_environment_resource_fault` | uncovered | none | 0 |
+| `improvement_metric_contract_conflict` | `improvement_metric_contract_conflict` | uncovered | none | 0 |
+| `improvement_observation_conflict` | `improvement_observation_conflict` | uncovered | none | 0 |
+| `incomplete_allowed_values` | `incomplete_allowed_values` | uncovered | none | 0 |
+| `inconsistent_concept_kind` | `inconsistent_concept_kind` | uncovered | none | 0 |
+| `init_existing_settings_requires_force` | `init_existing_settings_requires_force` | uncovered | none | 0 |
+| `init_gitignore_unwritable` | `init_gitignore_unwritable` | uncovered | none | 0 |
+| `init_id_prefix_conflict` | `init_id_prefix_conflict` | uncovered | none | 0 |
+| `init_id_prefix_path_like` | `init_id_prefix_path_like` | uncovered | none | 0 |
+| `integrity_history_conflict_marker` | `integrity_history_conflict_marker` | uncovered | none | 0 |
+| `integrity_history_invalid_json` | `integrity_history_invalid_json` | uncovered | none | 0 |
+| `integrity_history_unreadable` | `integrity_history_unreadable` | uncovered | none | 0 |
+| `integrity_item_ahead_format_version` | `integrity_item_ahead_format_version` | uncovered | none | 0 |
+| `integrity_item_conflict_marker` | `integrity_item_conflict_marker` | uncovered | none | 0 |
+| `integrity_item_outdated_format_version` | `integrity_item_outdated_format_version` | uncovered | none | 0 |
+| `integrity_item_parse_failed` | `integrity_item_parse_failed` | uncovered | none | 0 |
+| `integrity_item_unreadable` | `integrity_item_unreadable` | uncovered | none | 0 |
+| `invalid_argument_value` | `invalid_argument_value` | executable | grammar | 26 |
+| `invalid_command_usage` | `invalid_command_usage` | uncovered | none | 0 |
+| `invalid_event_cursor` | `invalid_event_cursor` | uncovered | none | 0 |
+| `invalid_event_cursor_mode` | `invalid_event_cursor_mode` | uncovered | none | 0 |
+| `invalid_event_follow_interval` | `invalid_event_follow_interval` | uncovered | none | 0 |
+| `invalid_event_limit` | `invalid_event_limit` | uncovered | none | 0 |
+| `invalid_event_since` | `invalid_event_since` | uncovered | none | 0 |
+| `invalid_history_analytics_limit` | `invalid_history_analytics_limit` | uncovered | none | 0 |
+| `invalid_history_analytics_minimum_sample` | `invalid_history_analytics_minimum_sample` | uncovered | none | 0 |
+| `invalid_history_analytics_since` | `invalid_history_analytics_since` | uncovered | none | 0 |
+| `invalid_improvement_ledger` | `invalid_improvement_ledger` | uncovered | none | 0 |
+| `invalid_improvement_metric` | `invalid_improvement_metric` | uncovered | none | 0 |
+| `invalid_improvement_observation` | `invalid_improvement_observation` | uncovered | none | 0 |
+| `invalid_improvement_observation_limit` | `invalid_improvement_observation_limit` | uncovered | none | 0 |
+| `invalid_improvement_observation_timestamp` | `invalid_improvement_observation_timestamp` | uncovered | none | 0 |
+| `invalid_provenance_predicate` | `invalid_provenance_predicate` | uncovered | none | 0 |
+| `invalid_query_cursor` | `invalid_query_cursor` | uncovered | none | 0 |
+| `invalid_read_output_session` | `invalid_read_output_session` | uncovered | none | 0 |
+| `invalid_reproducible_process_environment` | `invalid_reproducible_process_environment` | uncovered | none | 0 |
+| `invalid_workspace_snapshot_target` | `invalid_workspace_snapshot_target` | uncovered | none | 0 |
+| `item_already_active` | `item_already_active` | uncovered | none | 0 |
+| `item_document_invalid` | `item_document_invalid` | uncovered | none | 0 |
+| `item_document_roundtrip_failed` | `item_document_roundtrip_failed` | uncovered | none | 0 |
+| `item_id_collision` | `item_id_collision` | uncovered | none | 0 |
+| `item_not_found` | `item_not_found` | uncovered | none | 0 |
+| `likely_duplicate` | `likely_duplicate` | uncovered | none | 0 |
+| `linked_artifact_mutation_conflict` | `linked_artifact_mutation_conflict` | uncovered | none | 0 |
+| `linked_test_remove_no_match` | `linked_test_remove_no_match` | uncovered | none | 0 |
+| `linked_test_value_not_quoted` | `linked_test_value_not_quoted` | uncovered | none | 0 |
+| `list_source_incomplete` | `list_source_incomplete` | uncovered | none | 0 |
+| `local_package_archive_unsafe` | `local_package_archive_unsafe` | uncovered | none | 0 |
+| `local_source_not_found_bare_name` | `local_source_not_found_bare_name` | uncovered | none | 0 |
+| `lock_conflict` | `lock_conflict` | uncovered | none | 0 |
+| `locks_stale_count` | `locks_stale_count` | uncovered | none | 0 |
+| `locks_unreadable` | `locks_unreadable` | uncovered | none | 0 |
+| `malformed_plan_step_evidence` | `malformed_plan_step_evidence` | uncovered | none | 0 |
+| `manifest_capabilities_absent` | `manifest_capabilities_absent` | uncovered | none | 0 |
+| `manifest_unknown_key` | `manifest_unknown_key` | uncovered | none | 0 |
+| `mcp_annotation_file_unavailable` | `mcp_annotation_file_unavailable` | uncovered | none | 0 |
+| `mcp_stdin_unavailable` | `mcp_stdin_unavailable` | uncovered | none | 0 |
+| `merge_conflict_markers_detected` | `merge_conflict_markers_detected` | uncovered | none | 0 |
+| `merge_decisions_unreviewed` | `merge_decisions_unreviewed` | uncovered | none | 0 |
+| `merge_git_config_unwritable` | `merge_git_config_unwritable` | uncovered | none | 0 |
+| `merge_reconcile_discards_require_acceptance` | `merge_reconcile_discards_require_acceptance` | uncovered | none | 0 |
+| `merge_root_not_found` | `merge_root_not_found` | uncovered | none | 0 |
+| `missing_allowed_values` | `missing_allowed_values` | uncovered | none | 0 |
+| `missing_budget` | `missing_budget` | uncovered | none | 0 |
+| `missing_cli_flag` | `missing_cli_flag` | uncovered | none | 0 |
+| `missing_destination` | `missing_destination` | uncovered | none | 0 |
+| `missing_directory` | `missing_directory` | uncovered | none | 0 |
+| `missing_init_recovery` | `missing_init_recovery` | uncovered | none | 0 |
+| `missing_lifecycle_target` | `missing_lifecycle_target` | executable | grammar | 4 |
+| `missing_observation` | `missing_observation` | uncovered | none | 0 |
+| `missing_observed_signature` | `missing_observed_signature` | uncovered | none | 0 |
+| `missing_parameter_alias` | `missing_parameter_alias` | uncovered | none | 0 |
+| `missing_probe` | `missing_probe` | uncovered | none | 0 |
+| `missing_required_argument` | `missing_required_argument` | executable | grammar | 58 |
+| `missing_required_option` | `missing_required_option` | uncovered | none | 0 |
+| `missing_suggested_retry` | `missing_suggested_retry` | uncovered | none | 0 |
+| `missing_suggested_retry_args` | `missing_suggested_retry_args` | uncovered | none | 0 |
+| `module_import_failed` | `module_import_failed` | uncovered | none | 0 |
+| `multi_target_github_install_ambiguous` | `multi_target_github_install_ambiguous` | uncovered | none | 0 |
+| `mutation_author_required` | `mutation_author_required` | uncovered | none | 0 |
+| `mutation_secret_guard_blocked` | `mutation_secret_guard_blocked` | uncovered | none | 0 |
+| `no_matching_tests` | `no_matching_tests` | uncovered | none | 0 |
+| `no_projects_matched_filters` | `no_projects_matched_filters` | uncovered | none | 0 |
+| `no_test_files_found` | `no_test_files_found` | uncovered | none | 0 |
+| `no_tests_found` | `no_tests_found` | uncovered | none | 0 |
+| `no_update_fields` | `no_update_fields` | uncovered | none | 0 |
+| `no_version_bounds_declared` | `no_version_bounds_declared` | uncovered | none | 0 |
+| `non_refusal_exit` | `non_refusal_exit` | uncovered | none | 0 |
+| `npm_package_not_found` | `npm_package_not_found` | uncovered | none | 0 |
+| `ownership_conflict` | `ownership_conflict` | uncovered | none | 0 |
+| `ownership_dependency_bypass_restricted_options` | `ownership_dependency_bypass_restricted_options` | uncovered | none | 0 |
+| `ownership_metadata_bypass_restricted_options` | `ownership_metadata_bypass_restricted_options` | uncovered | none | 0 |
+| `package_spec_empty` | `package_spec_empty` | uncovered | none | 0 |
+| `positional_shape_budget_exceeded` | `positional_shape_budget_exceeded` | uncovered | none | 0 |
+| `positional_signature_mismatch` | `positional_signature_mismatch` | uncovered | none | 0 |
+| `profile_name_empty` | `profile_name_empty` | uncovered | none | 0 |
+| `profile_name_not_normalized` | `profile_name_not_normalized` | uncovered | none | 0 |
+| `profile_summary_empty` | `profile_summary_empty` | uncovered | none | 0 |
+| `profile_title_empty` | `profile_title_empty` | uncovered | none | 0 |
+| `project_runtime_stale_mutation` | `project_runtime_stale_mutation` | uncovered | none | 0 |
+| `project_runtime_stale_read` | `project_runtime_stale_read` | uncovered | none | 0 |
+| `projection_options_mutually_exclusive` | `projection_options_mutually_exclusive` | executable | closed_domain | 3 |
+| `provenance_value_domain_invalid` | `provenance_value_domain_invalid` | uncovered | none | 0 |
+| `read_output_cursor_command_mismatch` | `read_output_cursor_command_mismatch` | uncovered | none | 0 |
+| `read_output_cursor_invalid` | `read_output_cursor_invalid` | uncovered | none | 0 |
+| `read_output_cursor_stale` | `read_output_cursor_stale` | uncovered | none | 0 |
+| `recovery_kind_mismatch` | `recovery_kind_mismatch` | uncovered | none | 0 |
+| `redundant_edge` | `redundant_edge` | uncovered | none | 0 |
+| `refusal_allowed_values_mismatch` | `refusal_allowed_values_mismatch` | uncovered | none | 0 |
+| `refusal_error_code_mismatch` | `refusal_error_code_mismatch` | uncovered | none | 0 |
+| `refusal_exit_code_mismatch` | `refusal_exit_code_mismatch` | uncovered | none | 0 |
+| `refusal_mutated_state` | `refusal_mutated_state` | uncovered | none | 0 |
+| `refusal_probe_missing` | `refusal_probe_missing` | uncovered | none | 0 |
+| `refusal_recovery_failed` | `refusal_recovery_failed` | uncovered | none | 0 |
+| `reindex_already_running` | `reindex_already_running` | uncovered | none | 0 |
+| `removed_canonical_spelling` | `removed_canonical_spelling` | uncovered | none | 0 |
+| `removed_compatibility_spelling` | `removed_compatibility_spelling` | uncovered | none | 0 |
+| `reopen_reason_required` | `reopen_reason_required` | uncovered | none | 0 |
+| `reopen_receipt_missing` | `reopen_receipt_missing` | uncovered | none | 0 |
+| `reopen_target_status_invalid` | `reopen_target_status_invalid` | uncovered | none | 0 |
+| `reserved_item_field` | `reserved_item_field` | uncovered | none | 0 |
+| `retry_failed` | `retry_failed` | uncovered | none | 0 |
+| `schema_migration_input_required` | `schema_migration_input_required` | uncovered | none | 0 |
+| `semantic_spelling_collision` | `semantic_spelling_collision` | uncovered | none | 0 |
+| `settings_read_fs_error` | `settings_read_fs_error` | uncovered | none | 0 |
+| `settings_read_invalid_json` | `settings_read_invalid_json` | uncovered | none | 0 |
+| `settings_read_invalid_schema` | `settings_read_invalid_schema` | uncovered | none | 0 |
+| `settings_read_merge_failed` | `settings_read_merge_failed` | uncovered | none | 0 |
+| `stale_budget` | `stale_budget` | uncovered | none | 0 |
+| `stale_destination` | `stale_destination` | uncovered | none | 0 |
+| `stale_observed_signature` | `stale_observed_signature` | uncovered | none | 0 |
+| `status_duplicate` | `status_duplicate` | uncovered | none | 0 |
+| `status_invalid` | `status_invalid` | uncovered | none | 0 |
+| `stdin_json_invalid` | `stdin_json_invalid` | uncovered | none | 0 |
+| `stdin_json_unknown_key` | `stdin_json_unknown_key` | uncovered | none | 0 |
+| `structured_event_immutable` | `structured_event_immutable` | uncovered | none | 0 |
+| `structured_event_input_conflict` | `structured_event_input_conflict` | uncovered | none | 0 |
+| `structured_event_json_empty` | `structured_event_json_empty` | uncovered | none | 0 |
+| `structured_event_json_invalid` | `structured_event_json_invalid` | uncovered | none | 0 |
+| `structured_event_since_invalid` | `structured_event_since_invalid` | uncovered | none | 0 |
+| `suggested_retry_args_mismatch` | `suggested_retry_args_mismatch` | uncovered | none | 0 |
+| `telemetry_endpoint_probe_failed` | `telemetry_endpoint_probe_failed` | uncovered | none | 0 |
+| `telemetry_endpoint_probe_http_status` | `telemetry_endpoint_probe_http_status` | uncovered | none | 0 |
+| `telemetry_otel_export_failing` | `telemetry_otel_export_failing` | uncovered | none | 0 |
+| `telemetry_queue_high_retries` | `telemetry_queue_high_retries` | uncovered | none | 0 |
+| `telemetry_queue_invalid_rows` | `telemetry_queue_invalid_rows` | uncovered | none | 0 |
+| `telemetry_queue_pending` | `telemetry_queue_pending` | uncovered | none | 0 |
+| `telemetry_schema_version_behind` | `telemetry_schema_version_behind` | uncovered | none | 0 |
+| `telemetry_state_invalid_json` | `telemetry_state_invalid_json` | uncovered | none | 0 |
+| `template_type_unknown` | `template_type_unknown` | uncovered | none | 0 |
+| `terminal_plan_mutation` | `terminal_plan_mutation` | uncovered | none | 0 |
+| `terminal_state_conflict` | `terminal_state_conflict` | uncovered | none | 0 |
+| `tracked_runtime_cache_files` | `tracked_runtime_cache_files` | uncovered | none | 0 |
+| `tracker_not_initialized` | `tracker_not_initialized` | executable | owned_state | 1 |
+| `tracker_root_missing` | `tracker_root_missing` | executable | owned_state | 1 |
+| `tracker_root_not_directory` | `tracker_root_not_directory` | executable | owned_state | 1 |
+| `tracker_root_unreadable` | `tracker_root_unreadable` | executable | owned_state | 1 |
+| `type_duplicate` | `type_duplicate` | uncovered | none | 0 |
+| `type_invalid` | `type_invalid` | uncovered | none | 0 |
+| `undeclared_observation` | `undeclared_observation` | uncovered | none | 0 |
+| `unexpected_refusal_probe` | `unexpected_refusal_probe` | uncovered | none | 0 |
+| `unknown_command` | `unknown_command` | uncovered | none | 0 |
+| `unknown_context_intent` | `unknown_context_intent` | executable | closed_domain | 5 |
+| `unknown_error` | `unknown_error` | uncovered | none | 0 |
+| `unknown_field` | `unknown_field` | uncovered | none | 0 |
+| `unknown_field_projection` | `unknown_field_projection` | executable | closed_domain | 10 |
+| `unknown_item_type` | `unknown_item_type` | uncovered | none | 0 |
+| `unknown_lifecycle_action` | `unknown_subcommand` | executable | grammar, owned_state | 11 |
+| `unknown_noun` | `unknown_noun` | uncovered | none | 0 |
+| `unknown_option` | `unknown_option` | executable | owned_state | 1 |
+| `unknown_plan_template` | `unknown_plan_template` | uncovered | none | 0 |
+| `unknown_provenance_dimension` | `unknown_provenance_dimension` | uncovered | none | 0 |
+| `unknown_status` | `unknown_status` | uncovered | none | 0 |
+| `unknown_subcommand` | `unknown_subcommand` | executable | grammar, owned_state | 11 |
+| `unsafe_init_recovery` | `unsafe_init_recovery` | uncovered | none | 0 |
+| `unsupported_update_option` | `unsupported_update_option` | uncovered | none | 0 |
+| `validate_command_references_stale_pm_ids` | `validate_command_references_stale_pm_ids` | uncovered | none | 0 |
+| `validate_files_missing_linked_paths` | `validate_files_missing_linked_paths` | uncovered | none | 0 |
+| `validate_files_orphaned_paths` | `validate_files_orphaned_paths` | uncovered | none | 0 |
+| `validate_files_tracked_all_strict_forces_pm_internals` | `validate_files_tracked_all_strict_forces_pm_internals` | uncovered | none | 0 |
+| `validate_format_version_ahead_items` | `integrity_item_ahead_format_version` | uncovered | none | 0 |
+| `validate_format_version_outdated_items` | `integrity_item_outdated_format_version` | uncovered | none | 0 |
+| `validate_hierarchy_parent_cycle` | `validate_hierarchy_parent_cycle` | uncovered | none | 0 |
+| `validate_hierarchy_parent_cycle_error` | `validate_hierarchy_parent_cycle_error` | uncovered | none | 0 |
+| `validate_history_drift_chain_mismatches` | `history_drift_chain_mismatch` | uncovered | none | 0 |
+| `validate_history_drift_hash_mismatches` | `history_drift_hash_mismatch` | uncovered | none | 0 |
+| `validate_history_drift_missing_streams` | `history_drift_missing_stream` | uncovered | none | 0 |
+| `validate_history_drift_unreadable_streams` | `history_drift_unreadable_stream` | uncovered | none | 0 |
+| `validate_history_unknown_author_events` | `history_unknown_author_events` | uncovered | none | 0 |
+| `validate_lifecycle_active_closure_like_metadata` | `validate_lifecycle_active_closure_like_metadata` | uncovered | none | 0 |
+| `validate_lifecycle_active_terminal_parent` | `validate_lifecycle_active_terminal_parent` | uncovered | none | 0 |
+| `validate_lifecycle_dependency_cycles` | `validate_lifecycle_dependency_cycles` | uncovered | none | 0 |
+| `validate_lifecycle_dependency_cycles_error` | `validate_lifecycle_dependency_cycles_error` | uncovered | none | 0 |
+| `validate_lifecycle_stale_blockers` | `validate_lifecycle_stale_blockers` | uncovered | none | 0 |
+| `validate_merge_decisions_unreviewed` | `validate_merge_decisions_unreviewed` | uncovered | none | 0 |
+| `validate_merge_fence_drift` | `validate_merge_fence_drift` | uncovered | none | 0 |
+| `validate_metadata_custom_profile_missing_required_fields` | `validate_metadata_custom_profile_missing_required_fields` | uncovered | none | 0 |
+| `validate_metadata_duplicate_issue_codes` | `validate_metadata_duplicate_issue_codes` | uncovered | none | 0 |
+| `validate_metadata_missing_acceptance_criteria` | `validate_metadata_missing_acceptance_criteria` | uncovered | none | 0 |
+| `validate_metadata_missing_close_reason` | `validate_metadata_missing_close_reason` | uncovered | none | 0 |
+| `validate_metadata_missing_confidence` | `validate_metadata_missing_confidence` | uncovered | none | 0 |
+| `validate_metadata_missing_estimate` | `validate_metadata_missing_estimate` | uncovered | none | 0 |
+| `validate_metadata_missing_release` | `validate_metadata_missing_release` | uncovered | none | 0 |
+| `validate_metadata_missing_reviewer` | `validate_metadata_missing_reviewer` | uncovered | none | 0 |
+| `validate_metadata_missing_risk` | `validate_metadata_missing_risk` | uncovered | none | 0 |
+| `validate_metadata_missing_sprint` | `validate_metadata_missing_sprint` | uncovered | none | 0 |
+| `validate_resolution_missing_fields` | `validate_resolution_missing_fields` | uncovered | none | 0 |
+| `validate_storage_duplicate_item_ids` | `validate_storage_duplicate_item_ids` | uncovered | none | 0 |
+| `validate_storage_history_conflict_markers` | `integrity_history_conflict_marker` | uncovered | none | 0 |
+| `validate_storage_resurrected_items` | `validate_storage_resurrected_items` | uncovered | none | 0 |
+| `validate_storage_tracked_runtime_cache_files` | `tracked_runtime_cache_files` | uncovered | none | 0 |
+| `validate_storage_unparseable_config` | `validate_storage_unparseable_config` | uncovered | none | 0 |
+| `validate_storage_unparseable_history` | `validate_storage_unparseable_history` | uncovered | none | 0 |
+| `validate_storage_unreadable_items` | `validate_storage_unreadable_items` | uncovered | none | 0 |
+| `vectorization_embedding_identity_changed` | `vectorization_embedding_identity_changed` | uncovered | none | 0 |
+| `vectorization_stale_items_remaining` | `vectorization_stale_items_remaining` | uncovered | none | 0 |
+| `visible_surface_ceiling_exceeded` | `visible_surface_ceiling_exceeded` | uncovered | none | 0 |
+| `workflow_duplicate_type` | `workflow_duplicate_type` | uncovered | none | 0 |
+| `workflow_status_unknown` | `workflow_status_unknown` | uncovered | none | 0 |
+| `workflow_transition_malformed` | `workflow_transition_malformed` | uncovered | none | 0 |
+| `workflow_type_empty` | `workflow_type_empty` | uncovered | none | 0 |
+| `workflow_type_unknown` | `workflow_type_unknown` | uncovered | none | 0 |
+| `workspace_history_chain_invalid` | `workspace_history_chain_invalid` | uncovered | none | 0 |
+| `workspace_history_state_conflict` | `workspace_history_state_conflict` | uncovered | none | 0 |
+| `workspace_root_pm_path` | `workspace_root_pm_path` | uncovered | none | 0 |
+| `workspace_snapshot_force_required` | `workspace_snapshot_force_required` | uncovered | none | 0 |
+| `workspace_snapshot_manifest_mismatch` | `workspace_snapshot_manifest_mismatch` | uncovered | none | 0 |
+| `workspace_snapshot_name_reserved_fingerprint` | `workspace_snapshot_name_reserved_fingerprint` | uncovered | none | 0 |
+| `workspace_snapshot_not_found` | `workspace_snapshot_not_found` | uncovered | none | 0 |
+| `workspace_snapshot_permission_denied` | `workspace_snapshot_permission_denied` | uncovered | none | 0 |
+| `workspace_snapshot_resource_exhausted` | `workspace_snapshot_resource_exhausted` | uncovered | none | 0 |
+| `workspace_snapshot_storage_exhausted` | `workspace_snapshot_storage_exhausted` | uncovered | none | 0 |
+| `wrong_item_type` | `wrong_item_type` | uncovered | none | 0 |

package/marketplace.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.23",
+  "version": "2026.8.24",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.8.23",
+  "version": "2026.8.24",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.8.23",
+  "version": "2026.8.24",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/README.md

@@ -6,11 +6,11 @@ command-facing SDK registration APIs in their smallest complete form.
 
 ## What it demonstrates
 
-| API | What the exemplar does |
-| --- | --- |
-| `api.registerCommand(definition)` | Registers `pm command-kit echo` with a FULL `CommandDefinition`: `name`, `action`, `description`, `intent`, `arguments` (required variadic positional), `flags`, `examples`, `failure_hints`, and a pure `run` handler. |
-| `api.registerParser(command, override)` | Preprocesses parsed options before the handler runs: rewrites the deprecated `--shout` alias to `--upper`, coerces `--repeat` to a positive integer, and trims/dedupes `--decorations` values. The override returns a delta (`{ options }`) that is merged over the parsed input. |
-| `api.registerFlags(targetCommand, flags)` | Injects an inert, namespaced `--kit-note <text>` flag into the EXISTING core `pm list` command — the pattern for augmenting commands you do not own. |
+| API                                       | What the exemplar does                                                                                                                                                                                                                                                            |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api.registerCommand(definition)`         | Registers `pm command-kit echo` with a FULL `CommandDefinition`: `name`, `action`, `tier`, `family`, `description`, `intent`, `arguments` (required variadic positional), `flags`, `examples`, `failure_hints`, and a pure `run` handler.                                         |
+| `api.registerParser(command, override)`   | Preprocesses parsed options before the handler runs: rewrites the deprecated `--shout` alias to `--upper`, coerces `--repeat` to a positive integer, and trims/dedupes `--decorations` values. The override returns a delta (`{ options }`) that is merged over the parsed input. |
+| `api.registerFlags(targetCommand, flags)` | Injects an inert, namespaced `--kit-note <text>` flag into the EXISTING core `pm list` command — the pattern for augmenting commands you do not own.                                                                                                                              |
 
 ## Install
 
@@ -49,16 +49,14 @@ packages/pm-command-kit/
 ├── README.md
 └── extensions/command-kit/
     ├── manifest.json                  # capabilities, trusted, sandbox_profile, permissions
-    ├── index.ts                       # TypeScript source (type-only SDK imports)
-    └── index.js                       # hand-maintained runtime module (import-free)
+    └── index.ts                       # authored and loaded directly with type stripping
 ```
 
 Key conventions for authors:
 
-- `index.js` is what actually runs. It is **import-free** so the extension loads in
-  extension-only installs without SDK module resolution. `index.ts` mirrors it with
-  `import type { ... } from` the SDK for editor/typecheck support; type-only imports are
-  erased and keep the shipped `.js` dependency-free.
+- `index.ts` is both the authored source and the runtime entrypoint. pm strips types
+  when loading it, so there is no duplicate compiled module to keep synchronized.
+  Type-only SDK imports retain editor/typecheck support without adding runtime imports.
 - The module's `manifest.capabilities` literal must match `manifest.json` exactly
   (`commands` for `registerCommand`, `schema` for flag definitions/`registerFlags`,
   `parser` for `registerParser`).

package/packages/pm-command-kit/extensions/command-kit/index.ts

@@ -25,7 +25,7 @@ import type {
 export const manifest = {
   name: "builtin-command-kit",
   version: "0.1.0",
-  entry: "./index.js",
+  entry: "./index.ts",
   priority: 0,
   capabilities: ["commands", "schema", "parser"],
   activation: { commands: ["command-kit echo", "list"] },
@@ -145,6 +145,8 @@ export function buildEchoCommandDefinition(): CommandDefinition {
   return {
     name: ECHO_COMMAND,
     action: "command-kit-echo",
+    tier: "standard",
+    family: "extensions",
     description:
       "Echo a message as structured output (commands-capability exemplar).",
     intent:

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.8.23",
+  "version": "2026.8.24",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.8.23",
+  "version": "2026.8.24",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.8.23",
+  "version": "2026.8.24",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",