@unbrained/pm-cli 2026.9.9 → 2026.9.10

package/docs/COMMANDS.md

@@ -54,8 +54,8 @@ JSON ceiling; TOON uses the smaller default agent ceiling.
 | Family       | Commands                                                                                                                                      | Purpose                                                                                                                                                                                                                                                |
 | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Bootstrap    | `init`, `config`, `health`, `telemetry`                                                                                                       | create and inspect tracker setup                                                                                                                                                                                                                       |
-| Lifecycle    | `create`, `copy`, `focus`, `claim`, `update`, `item reopen`, `append`, `close`, `release`, `delete`, `start-task`, `pause-task`, `close-task` | mutate item state, including terminal-work recurrence without duplicate creation                                                                                                                                                                       |
-| Bulk         | `item mutate`, `item complete`, `update-many`, `close-many`                                                                                   | atomically commit heterogeneous SDK mutation batches or evidence-backed completion, or apply one change across a matched, dry-run-previewed set with a rollback checkpoint                                                                             |
+| Lifecycle    | `create`, `copy`, `focus`, `claim`, `update`, `item reopen`, `append`, `close`, `release`, `close delete` | mutate item state, including terminal-work recurrence without duplicate creation                                                                                                                                                                       |
+| Bulk         | `item mutate`, `item complete`, `update many`, `close many`                                                                                   | atomically commit heterogeneous SDK mutation batches or evidence-backed completion, or apply one change across a matched, dry-run-previewed set with a rollback checkpoint                                                                             |
 | Scheduling   | `meet`, `event`, `remind`                                                                                                                     | low-friction Meeting/Event/Reminder creation                                                                                                                                                                                                           |
 | Planning     | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize`                     | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization                                                                                                                                                  |
 | Links        | `files`, `docs`, `test`, `deps`                                                                                                               | connect items to artifacts, tests, and relationships                                                                                                                                                                                                   |
@@ -404,28 +404,28 @@ pm list --status open --has-tests --no-files --json
 
 ## Bulk Operations
 
-`update-many` and `close-many` apply one change across a matched set with a dry-run preview and a rollback checkpoint. Both share the `--filter-*` scoping family (`--filter-status/-type/-tag/-priority/-sprint/-release/-parent/-assignee/-deadline-before|after/-updated-after|before/-created-after|before`) plus `--ids` for an explicit comma-separated allowlist intersected with the other filters. `update-many` additionally accepts the missing-metadata selectors `--filter-ac-missing`/`--filter-estimates-missing`/`--filter-resolution-missing`/`--filter-metadata-missing` for bulk metadata backfill.
+`update many` and `close many` apply one change across a matched set with a dry-run preview and a rollback checkpoint. Both share the `--filter-*` scoping family (`--filter-status/-type/-tag/-priority/-sprint/-release/-parent/-assignee/-deadline-before|after/-updated-after|before/-created-after|before`) plus `--ids` for an explicit comma-separated allowlist intersected with the other filters. `update many` additionally accepts the missing-metadata selectors `--filter-ac-missing`/`--filter-estimates-missing`/`--filter-resolution-missing`/`--filter-metadata-missing` for bulk metadata backfill.
 
-Both `update-many` and `close-many` also accept the governance-field selectors `--filter-reviewer-missing`/`--filter-risk-missing`/`--filter-confidence-missing`/`--filter-sprint-missing`/`--filter-release-missing` and the content-field presence selectors under the `--filter-` prefix: `--filter-has-notes`/`--filter-no-notes`, `--filter-has-learnings`/`--filter-no-learnings`, `--filter-has-files`/`--filter-no-files`, `--filter-has-docs`/`--filter-no-docs`, `--filter-has-tests`/`--filter-no-tests`, `--filter-has-comments`/`--filter-no-comments`, `--filter-has-deps`/`--filter-no-deps`, `--filter-has-body`/`--filter-empty-body`, and `--filter-has-linked-command`/`--filter-no-linked-command`. These mirror the list/search presence filters and intersect with the rest of the scoping family, so you can bulk-select (for example) closed Tasks with no documented learnings before applying a change.
+Both `update many` and `close many` also accept the governance-field selectors `--filter-reviewer-missing`/`--filter-risk-missing`/`--filter-confidence-missing`/`--filter-sprint-missing`/`--filter-release-missing` and the content-field presence selectors under the `--filter-` prefix: `--filter-has-notes`/`--filter-no-notes`, `--filter-has-learnings`/`--filter-no-learnings`, `--filter-has-files`/`--filter-no-files`, `--filter-has-docs`/`--filter-no-docs`, `--filter-has-tests`/`--filter-no-tests`, `--filter-has-comments`/`--filter-no-comments`, `--filter-has-deps`/`--filter-no-deps`, `--filter-has-body`/`--filter-empty-body`, and `--filter-has-linked-command`/`--filter-no-linked-command`. These mirror the list/search presence filters and intersect with the rest of the scoping family, so you can bulk-select (for example) closed Tasks with no documented learnings before applying a change.
 
 ```bash
 # Bulk metadata update by explicit id allowlist (compose with search --json | jq)
-pm update-many --ids pm-a,pm-b,pm-c --priority 1 --dry-run
-pm update-many --filter-tag wave:7 --reviewer maintainer-review
+pm update many --ids pm-a,pm-b,pm-c --priority 1 --dry-run
+pm update many --filter-tag wave:7 --reviewer maintainer-review
 
 # Bulk-backfill a placeholder estimate onto open Tasks that have none
-pm update-many --filter-status open --filter-type Task --filter-estimates-missing --estimate 60 --dry-run
+pm update many --filter-status open --filter-type Task --filter-estimates-missing --estimate 60 --dry-run
 
 # Audited bulk close: routes EACH match through full `pm close` semantics
 # (close validation, active-child orphan checks, blocked-edge cleanup) — unlike
 # `update-many --status closed`, which bypasses them. A shared --reason is required
 # and at least one filter is required so it never matches every item.
-pm close-many --filter-sprint S-12 --reason "Sprint S-12 acceptance criteria met" --dry-run
-pm close-many --filter-sprint S-12 --reason "Sprint S-12 acceptance criteria met"
-pm close-many --rollback close-many-20260604-abc123   # restore the batch
+pm close many --filter-sprint S-12 --reason "Sprint S-12 acceptance criteria met" --dry-run
+pm close many --filter-sprint S-12 --reason "Sprint S-12 acceptance criteria met"
+pm close many --rollback close-many-20260604-abc123   # restore the batch
 ```
 
-`close-many` skips already-terminal matches by default (pass `--force` to re-close), accepts `--completed-at <timestamp>` to preserve one shared actual-completion time across the batch, reports a per-item plan (`close`/`skip`, plus `active_child_ids` for parents that would be orphaned) under `--dry-run`, and writes a checkpoint by default (`--no-checkpoint` to disable). Checkpoints for both commands live under `.agents/pm/checkpoints/<command>/` and are restored with `--rollback <checkpoint-id>`.
+`close many` skips already-terminal matches by default (pass `--force` to re-close), accepts `--completed-at <timestamp>` to preserve one shared actual-completion time across the batch, reports a per-item plan (`close`/`skip`, plus `active_child_ids` for parents that would be orphaned) under `--dry-run`, and writes a checkpoint by default (`--no-checkpoint` to disable). Checkpoints for both commands live under `.agents/pm/checkpoints/<command>/` and are restored with `--rollback <checkpoint-id>`.
 
 When a flag is rejected with `Unknown option`, the error guidance now suggests the nearest supported flag (including abbreviations like `--desc` → `--description`) and notes when the flag is valid on a different command (for example `--type` on `test-all` points to `create`/`list`). Unknown-command guidance ranks agent verb synonyms first, bounded edit distance second, and substring matches last; `pm log` therefore points to `history`, `comments`, and `notes`, never a `catalog` command.
 
@@ -511,10 +511,10 @@ did-you-mean diagnostic instead of becoming an accidental custom field.
 
 Repeated singular/plural list flags now accumulate, so `--tag a --tag b` is equivalent to `--tags a,b` (the same holds for `--status`, `--ids`, and `--fields` on read commands). Earlier versions silently kept only the last value. `list`/`search` also accept `--tags` as a never-block alias for the canonical read filter `--tag`.
 
-`--tags` REPLACES the whole tag list. To edit tags without restating the full set, use the additive/subtractive flags on `create`/`update`/`update-many`:
+`--tags` REPLACES the whole tag list. To edit tags without restating the full set, use the additive/subtractive flags on `create`/`update`/`update many`:
 
 - `--add-tags <value>` adds tags to the existing list without replacing it (repeatable; CSV or JSON-array values accepted).
-- `--remove-tags <value>` prunes the given tags from the existing list (repeatable; CSV or JSON-array). Available on `update`/`update-many` only — `create` has no prior tags to remove.
+- `--remove-tags <value>` prunes the given tags from the existing list (repeatable; CSV or JSON-array). Available on `update`/`update many` only — `create` has no prior tags to remove.
 
 ```bash
 pm update pm-abc1 --add-tags urgent,backend     # keeps existing tags, adds two
@@ -522,7 +522,7 @@ 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` explicitly REPLACES the whole value and returns an `acceptance_criteria_replaced:<before-count>:<after-count>` warning when it changes existing criteria. `--add-ac <text>` appends one criterion (repeatable; deduped on exact text), while `--remove-ac <text>` removes one criterion by exact text match. Every requested removal must match: otherwise the mutation fails atomically with `acceptance_criteria_remove_unmatched` and reports the unmatched selectors, without applying valid removals or additions. Whole-value replacement cannot be combined with additive flags in one mutation. Criteria are stored with semicolon-space separators, so one criterion cannot contain a semicolon. Disjoint `--add-ac` edits from concurrent agents/branches merge cleanly instead of clobbering each other.
+Acceptance criteria get the same additive treatment on `update`/`update many`: `--acceptance-criteria`/`--ac` explicitly REPLACES the whole value and returns an `acceptance_criteria_replaced:<before-count>:<after-count>` warning when it changes existing criteria. `--add-ac <text>` appends one criterion (repeatable; deduped on exact text), while `--remove-ac <text>` removes one criterion by exact text match. Every requested removal must match: otherwise the mutation fails atomically with `acceptance_criteria_remove_unmatched` and reports the unmatched selectors, without applying valid removals or additions. Whole-value replacement cannot be combined with additive flags in one mutation. Criteria are stored with semicolon-space separators, 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"
@@ -555,7 +555,7 @@ pm update <id> \
   --message "Append audit evidence"
 ```
 
-`--expected` and `--actual` are short aliases for `--expected-result` and `--actual-result` on `create`/`update`/`update-many`, matching the aliases `pm close` already accepts:
+`--expected` and `--actual` are short aliases for `--expected-result` and `--actual-result` on `create`/`update`/`update many`, matching the aliases `pm close` already accepts:
 
 ```bash
 pm update <id> --expected "Retry succeeds after backoff" --actual "Retry threw on first attempt"
@@ -702,12 +702,12 @@ Use `pm close <id> "<reason>"` instead of `pm update --status closed`.
 
 ## Lifecycle Aliases
 
-Lifecycle aliases combine claim, status, and close operations into a single command:
+Lifecycle composition flags combine claim, status, and close operations:
 
 ```bash
-pm start-task <id>             # claim + move to in_progress
-pm pause-task <id>             # move to open + release claim
-pm close-task <id> "<reason>"  # close + release assignment
+pm claim <id> --start                       # claim + move to the configured in-progress status
+pm release <id> --pause                     # move to the configured open status + release claim
+pm close <id> "<reason>" --release-assignment # close with evidence + release assignment
 ```
 
 For lifecycle ownership commands, `--assignee <agent>` is accepted as an alias
@@ -715,9 +715,11 @@ for `--author <agent>` on `claim`, `release`, `start-task`, `pause-task`, and
 `close-task`. Use `pm update --assignee <person>` when changing item metadata
 rather than active work ownership.
 
-Tracker references: [pm-qfte](../.agents/pm/tasks/pm-qfte.toon), [pm-98cz](../.agents/pm/features/pm-98cz.toon).
+The old task spellings remain hidden compatibility aliases. See [Lifecycle Commands and Ownership](LIFECYCLE_COMMANDS.md) for migration, typed SDK receipts, MCP controls, and partial-failure semantics.
 
-After `pm create` of a workable item type, the result includes a non-binding `next_transition` hint (`pm start-task <id>` → `in_progress`) when the workflow defines a distinct in-progress status. This nudges agents to move work through `in_progress` instead of jumping straight from `open` to `closed`. Scheduling/reference types (Event, Meeting, Reminder, Milestone, Decision) never receive the hint. (GH-216)
+Tracker references: [pm-eq4x](../.agents/pm/tasks/pm-eq4x.toon), [pm-ik19](../.agents/pm/tasks/pm-ik19.toon), [pm-qfte](../.agents/pm/tasks/pm-qfte.toon), [pm-98cz](../.agents/pm/features/pm-98cz.toon).
+
+After `pm create` of a workable item type, the result includes a non-binding `next_transition` hint (`pm claim <id> --start` → `in_progress`) when the workflow defines a distinct in-progress status. This nudges agents to move work through `in_progress` instead of jumping straight from `open` to `closed`. Scheduling/reference types (Event, Meeting, Reminder, Milestone, Decision) never receive the hint. (GH-216)
 
 ## Scheduling Shortcuts
 
@@ -908,7 +910,7 @@ Use dry-run modes before broad lifecycle or cleanup changes.
 - `embeddings` removes keyword/semantic artifacts (`search/embeddings.jsonl`, `search/vectorization-status.json`, `search/lancedb/`) plus `search/pending-refresh.json` and its gate, preventing a background worker from rebuilding a partial index against an empty ledger. Rebuild with keyword reindex and semantic reindex when enabled.
 - `locks` removes only provably expired locks, using embedded `created_at + ttl_seconds`. Active, unreadable, or unparseable locks remain. The result reports `scanned`, `removed`, and `retained` counts.
 
-The `checkpoints` scope prunes bulk-mutation rollback checkpoints under `checkpoints/` (written by `pm update-many`/`pm close-many`) that are older than `checkpoints.retention_days` (default 14; set via `pm config <scope> set checkpoints_retention_days <n>`). Checkpoints whose `created_at` cannot be parsed are retained (safety-first, like the locks sweep), and the result includes a `checkpoints` summary (`scanned`/`removed`/`retained`/`retention_days`). Removing aged checkpoints permanently closes their `--rollback` window.
+The `checkpoints` scope prunes bulk-mutation rollback checkpoints under `checkpoints/` (written by `pm update many`/`pm close many`) that are older than `checkpoints.retention_days` (default 14; set via `pm config <scope> set checkpoints_retention_days <n>`). Checkpoints whose `created_at` cannot be parsed are retained (safety-first, like the locks sweep), and the result includes a `checkpoints` summary (`scanned`/`removed`/`retained`/`retention_days`). Removing aged checkpoints permanently closes their `--rollback` window.
 
 `--fix-hints` is a read-only flag: each failing check gains `details.fix_hints`, an array of `pm` command templates derived from the warning codes it raised (for example `pm history-repair <id>` for history drift, or `pm update <id> --reviewer "<name>"` for a missing reviewer). Generic hints may contain `<id>`/`<field>`/`<path>` placeholders the agent substitutes from the check's detail rows; the resolution check aliases concrete per-row commands and marks `fix_hints_truncated` when the list is summarized. It never mutates items. The mapping comes from the shared remediation registry that also backs `pm health --json` (see Self-Repair Remediation below), so agents gating on `pm validate` can auto-repair findings without hardcoding warning-code-to-command lookups.
 
@@ -916,7 +918,7 @@ The `checkpoints` scope prunes bulk-mutation rollback checkpoints under `checkpo
 
 `--counts` keeps the validation envelope, check statuses, warning codes, scalar counts/totals, nested count maps, and fix summary totals while recursively omitting diagnostic and fix row arrays. False `*_truncated` markers are omitted; true markers, other false values, and zero counts remain. It is the preferred agent projection when deciding whether drift exists; remove it only when the affected ids or remediation rows are needed. The public SDK `projectValidateCounts` helper applies the identical projection to an already-computed `ValidateResult`.
 
-By default the human view caps each diagnostic `*_item_ids` list at 5 entries and sets the matching `*_truncated` flag. `--json` **never** truncates those lists (machine consumers always receive the complete arrays), and `--all-affected-ids` (equivalent to `--verbose-diagnostics`) emits the full lists in human mode too — so bulk remediation can pipe every affected id straight into `pm update-many`:
+By default the human view caps each diagnostic `*_item_ids` list at 5 entries and sets the matching `*_truncated` flag. `--json` **never** truncates those lists (machine consumers always receive the complete arrays), and `--all-affected-ids` (equivalent to `--verbose-diagnostics`) emits the full lists in human mode too — so bulk remediation can pipe every affected id straight into `pm update many`:
 
 ```bash
 pm validate --check-metadata --all-affected-ids
@@ -1238,7 +1240,7 @@ Invariants:
 - Promoting a step link preserves its semantic kind. `depends_on` normalizes to the canonical top-level `blocked_by`; `implements` and `verifies` remain first-class directed dependency kinds available to SDK relationship registries and graph consumers.
 - Search keyword corpus includes plan_scope, step titles/bodies, decisions, discoveries, validation, and step linked items.
 
-`pm delete <id> --json` reports an explicit `outcome` (`deleted` or `would_delete`), `deleted` boolean, and `previous_status`. Compact and `--id-only` output use the mutation outcome as `status`, so agents never mistake the deleted item's former lifecycle state for the delete result.
+`pm close delete <id> --json` reports an explicit `outcome` (`deleted` or `would_delete`), `deleted` boolean, and `previous_status`. Compact and `--id-only` output use the mutation outcome as `status`, so agents never mistake the deleted item's former lifecycle state for the delete result.
 
 ## Machine Contracts
 

package/docs/COMMAND_NAMESPACES.md

@@ -0,0 +1,65 @@
+# Context and operations command namespaces
+
+Tracked in [pm-kcs4](../.agents/pm/tasks/pm-kcs4.toon),
+[pm-6apl](../.agents/pm/tasks/pm-6apl.toon), and
+[pm-3i9q8g](../.agents/pm/tasks/pm-3i9q8g.toon).
+
+The CLI groups navigation and maintenance under stable nouns. Existing root
+spellings remain executable compatibility aliases with the same arguments,
+results, exit codes, and SDK behavior.
+
+| Native invocation | Compatibility spelling | Purpose |
+| --- | --- | --- |
+| `pm context next` | `pm next` | Select ready work and explain blockers |
+| `pm context focus` | `pm focus` | Read, set, or clear the focused item |
+| `pm ops stats` | `pm stats` | Inspect tracker statistics |
+| `pm ops health` | `pm health` | Diagnose tracker health |
+| `pm ops validate` | `pm validate` | Validate metadata and history |
+| `pm ops gc` | `pm gc` | Clean optional cache artifacts |
+| `pm ops telemetry` | `pm telemetry` | Inspect and manage telemetry |
+| `pm ops eval` | `pm eval` | Evaluate retrieval quality |
+| `pm ops test-all` | `pm test-all` | Run selected linked tests |
+| `pm ops reindex` | `pm reindex` | Refresh indexes through search-advanced |
+| `pm ops normalize` | `pm normalize` | Normalize through an active governance package |
+| `pm history events` | `pm events` | Read or follow committed mutation events |
+
+`pm context --limit 10 --for orient` still produces a context snapshot.
+`pm history <id> --verify` still reads and verifies one item's history.
+Namespace leaves do not change either default operation.
+
+## Discover only what the current task needs
+
+```bash
+pm context next --limit 5 --ready-only
+pm context focus --id pm-example
+pm ops health --check-only --summary
+pm ops validate --check-history-drift
+pm history events --item pm-example --limit 10
+pm ops --help
+pm contracts --command "ops stats" --flags-only
+```
+
+Help, contracts, and shell completion expose native paths. Compatibility aliases
+remain declared in the SDK alias table. Alias guidance uses the existing
+`ux.deprecation_hints` setting. Human-readable calls emit it on stderr; JSON and
+quiet calls suppress it. Compact contract summaries omit duplicate root alias
+rows; full and explicitly selected contracts retain them. Optional commands appear only when their providing package is active;
+namespace placement does not promote package behavior into core.
+
+## SDK and package integration
+
+`PM_NAMESPACED_COMMAND_ALIASES` and `resolvePmCommandOperation` are exported
+from `@unbrained/pm-cli/sdk` and `@unbrained/pm-cli/sdk/contracts`.
+The resolver maps a native path such as `context next` to the existing SDK
+operation identity `next`. Unknown paths are preserved. SDK functions, MCP
+action names, extension activation selectors, and command hooks retain their
+existing operation identities.
+
+Packages that provide `reindex` or `normalize` keep their existing command
+registration. The CLI places the registered handler beneath `ops` after
+activation, preserving flags, argument parsing, and nested commands. A conflicting
+native destination fails explicitly instead of silently replacing a handler.
+
+Generated Bash, Zsh, and Fish scripts recognize namespace command positions and
+skip global option values when selecting a leaf. Re-generate installed completion
+scripts after upgrading with `pm completion <shell>` from guide-shell.

package/docs/LIFECYCLE_COMMANDS.md

@@ -0,0 +1,77 @@
+# Lifecycle Commands and Ownership
+
+Tracked by [pm-ik19](../.agents/pm/tasks/pm-ik19.toon) and
+[pm-eq4x](../.agents/pm/tasks/pm-eq4x.toon).
+
+Bulk mutations and ownership compositions share SDK implementations with their
+compatibility spellings. Runtime help and contracts describe the active surface:
+
+```bash
+pm update many --help
+pm close many --help
+pm close delete --help
+pm contracts --command 'close many' --flags-only --json
+```
+
+## Command migration
+
+| Canonical invocation | Compatibility invocation |
+| --- | --- |
+| `pm update many --ids <ids> --priority 1` | `pm update-many --ids <ids> --priority 1` |
+| `pm close many --ids <ids> --reason "Verified"` | `pm close-many --ids <ids> --reason "Verified"` |
+| `pm close delete <id> --dry-run` | `pm delete <id> --dry-run` |
+| `pm claim <id> --start` | `pm start-task <id>` |
+| `pm release <id> --pause` | `pm pause-task <id>` |
+| `pm close <id> "Verified" --release-assignment` | `pm close-task <id> "Verified"` |
+
+The old spellings remain accepted as hidden aliases. Bulk aliases are permanent;
+the three task aliases are deprecated. Human output for deprecated aliases can
+include migration hints according to `ux.deprecation_hints`; JSON and quiet
+invocations suppress those hints. Bulk commands retain their existing filters,
+stdin selection, dry runs, rollback behavior, and evidence flags. Put bulk flags
+after `many`. Deletion recovery remains `pm history restore <id> <version>`.
+
+Plain `claim`, `release`, `update`, and `close` keep their original semantics.
+`claim --start` requires an explicit item and rejects `--next` and
+`--if-available` before mutation. It claims ownership, then moves the item to the
+configured in-progress status. `release --pause` moves work to the configured
+open status, then releases ownership. `close --release-assignment` records the
+close and its inline evidence, then releases ownership.
+
+Each constituent operation enforces its own policy and writes its own history.
+Compositions do not provide rollback across operations: for example, if the
+status transition fails after a successful claim, the claim remains. Inspect the
+item before retrying after an error.
+
+## SDK and MCP
+
+```ts
+import { PmClient } from "@unbrained/pm-cli/sdk";
+
+const pm = new PmClient({ pmRoot: "/project/.agents/pm" });
+const started = await pm.claim("pm-example", { start: true });
+const paused = await pm.release("pm-example", { pause: true });
+const closed = await pm.close("pm-example", "Acceptance verified", {
+  releaseAssignment: true,
+  resolution: "Implemented the requested behavior",
+  expectedResult: "Acceptance checks pass",
+  actualResult: "Acceptance checks passed",
+  validateClose: "warn",
+});
+```
+
+Literal `true` options return typed `StartTaskResult`, `PauseTaskResult`, or
+`CloseTaskResult` receipts. Their discriminators remain `start_task`,
+`pause_task`, and `close_task`, with the constituent results available under
+`claim`, `update`, `close`, or `release`. Public `runStartTask`, `runPauseTask`, and
+`runCloseTask` primitives expose the same SDK-owned compositions.
+
+MCP actions remain `claim`, `release`, and `close`, using `start`, `pause`, and
+`releaseAssignment`. Action-specific discovery types claim's `start` as boolean;
+scheduling actions retain string timestamps. For the broad provider tool schema,
+pass the claim boolean through `options: { start: true }` because its shared flat
+`start` property retains the scheduling string contract. Bulk action names remain
+`update_many`, `close_many`, and `delete` for transport compatibility.
+
+See [SDK Lifecycle Policy](SDK_LIFECYCLE.md) for transaction and policy ownership
+and [CLI Scripting Contract](SCRIPTING.md) for output projection.

package/docs/README.md

@@ -35,6 +35,7 @@ pm guide release --json
 - [Onboarding](ONBOARDING.md) - first-two-hours maintainer and contributor setup.
 - [Agent Guide](AGENT_GUIDE.md) - canonical agent loop, tracker linking, and token-minimal command choices.
 - [Command Reference](COMMANDS.md) - command families with examples and when to use each family.
+- [Context and Operations Namespaces](COMMAND_NAMESPACES.md) - native navigation, diagnostics, event streams, and compatibility aliases.
 - [CLI Scripting Contract](SCRIPTING.md) - exit codes, flat mutation receipts versus read envelopes, stdout/stderr boundaries, stable JSON fields, uniform OR filters, and shell composition recipes.
 - [Configuration](CONFIGURATION.md) - settings, storage formats, output, search, validation, and environment variables.
 - [Testing](TESTING.md) - sandbox-safe local tests and linked-test orchestration.
@@ -100,6 +101,7 @@ Additional SDK, operations, and generated contracts:
 - [Item Read Projections](ITEM_READ_PROJECTIONS.md) - identity, projections, and read completeness.
 - [MCP Capability Surfaces](MCP_CAPABILITY_SURFACES.md) - negotiated MCP discovery contracts.
 - [PR Review Loop](PR_REVIEW_LOOP.md) - complete review inventories and feedback acknowledgment.
+- [Lifecycle Commands and Ownership](LIFECYCLE_COMMANDS.md) - canonical bulk commands, ownership compositions, and SDK/MCP migration.
 - [SDK Lifecycle](SDK_LIFECYCLE.md) - lifecycle primitives and package integration.
 - [SDK Runtime Boundaries](SDK_RUNTIME_BOUNDARIES.md) - runtime ownership and import boundaries.
 - [Sentry Contract Epochs](SENTRY_CONTRACT_EPOCHS.md) - diagnostic compatibility and release epochs.

package/docs/generated/AGENT_CAPABILITY_ROUTING.md

@@ -6,12 +6,12 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 
 | 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` |
+| workspace | `init`, `config`, `merge`, `schema`, `profile`, `ops telemetry`, `ops health`, `ops gc`, `workspace` |
+| intake | `create`, `copy`, `context focus`, `history restore` |
+| context | `list`, `aggregate`, `context`, `get`, `search`, `duplicates`, `ops eval`, `context next`, `history activity`, `ops stats`, `help` |
+| lifecycle | `update`, `update many`, `close`, `close many`, `close delete`, `claim`, `release` |
+| evidence | `history`, `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` |
+| quality | `test`, `ops test-all`, `ops validate`, `assurance`, `contracts`, `ops` |
 | automation | `meet`, `event`, `remind` |
 | extensions | `package` |

package/docs/generated/AGENT_COMMAND_SURFACE.md

@@ -15,6 +15,7 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `item-reopen` | full | lifecycle |
 | `copy` | full | intake |
 | `focus` | standard | intake |
+| `context focus` | standard | intake |
 | `list` | core | context |
 | `list-all` | standard | context |
 | `list-draft` | full | context |
@@ -31,23 +32,34 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `search` | core | context |
 | `duplicates` | full | context |
 | `eval` | full | context |
+| `ops eval` | full | context |
 | `next` | core | context |
+| `context next` | core | context |
 | `history` | standard | evidence |
 | `events` | standard | evidence |
+| `history events` | standard | evidence |
 | `history-redact` | full | evidence |
+| `history redact` | full | evidence |
 | `history-repair` | full | evidence |
+| `history repair` | full | evidence |
 | `history-compact` | full | evidence |
+| `history compact` | full | evidence |
 | `history-author-acknowledge` | full | evidence |
 | `merge` | full | workspace |
 | `schema` | standard | workspace |
 | `profile` | standard | workspace |
 | `activity` | full | context |
+| `history activity` | full | context |
 | `restore` | full | intake |
+| `history restore` | full | intake |
 | `update` | core | lifecycle |
 | `update-many` | full | lifecycle |
+| `update many` | full | lifecycle |
 | `close` | core | lifecycle |
 | `close-many` | full | lifecycle |
+| `close many` | full | lifecycle |
 | `delete` | full | lifecycle |
+| `close delete` | full | lifecycle |
 | `append` | standard | evidence |
 | `comments` | standard | evidence |
 | `notes` | standard | evidence |
@@ -58,12 +70,18 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `plan` | core | graph |
 | `test` | standard | quality |
 | `test-all` | full | quality |
+| `ops test-all` | full | quality |
 | `telemetry` | full | workspace |
+| `ops telemetry` | full | workspace |
 | `stats` | full | context |
+| `ops stats` | full | context |
 | `health` | standard | workspace |
+| `ops health` | standard | workspace |
 | `validate` | core | quality |
+| `ops validate` | core | quality |
 | `assurance` | full | quality |
 | `gc` | full | workspace |
+| `ops gc` | full | workspace |
 | `workspace` | full | workspace |
 | `contracts` | standard | quality |
 | `claim` | core | lifecycle |
@@ -75,6 +93,7 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `event` | full | automation |
 | `remind` | full | automation |
 | `help` | core | context |
+| `ops` | core | quality |
 | `completion-statuses` | internal | internal |
 | `completion-tags` | internal | internal |
 | `completion-types` | internal | internal |

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -44,7 +44,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `restore` | intake | 23 | 23 |
 | `update` | lifecycle | 105 | 105 |
 | `update-many` | lifecycle | 146 | 146 |
-| `close` | lifecycle | 31 | 31 |
+| `close` | lifecycle | 32 | 32 |
 | `close-many` | lifecycle | 72 | 72 |
 | `delete` | lifecycle | 24 | 24 |
 | `append` | evidence | 25 | 25 |
@@ -65,8 +65,8 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `gc` | workspace | 22 | 22 |
 | `workspace` | workspace | 23 | 23 |
 | `contracts` | quality | 29 | 29 |
-| `claim` | lifecycle | 38 | 38 |
-| `release` | lifecycle | 23 | 23 |
+| `claim` | lifecycle | 39 | 39 |
+| `release` | lifecycle | 24 | 24 |
 | `start-task` | lifecycle | 23 | 23 |
 | `pause-task` | lifecycle | 23 | 23 |
 | `close-task` | lifecycle | 24 | 24 |
@@ -74,3 +74,21 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `event` | automation | 33 | 33 |
 | `remind` | automation | 29 | 29 |
 | `test-runs-worker` | internal | 25 | 25 |
+| `history redact` | evidence | 27 | 27 |
+| `history repair` | evidence | 27 | 27 |
+| `history compact` | evidence | 30 | 30 |
+| `history activity` | context | 35 | 35 |
+| `history restore` | intake | 23 | 23 |
+| `context next` | context | 38 | 38 |
+| `context focus` | intake | 22 | 22 |
+| `ops stats` | context | 29 | 29 |
+| `ops health` | workspace | 36 | 36 |
+| `ops validate` | quality | 46 | 46 |
+| `ops gc` | workspace | 22 | 22 |
+| `ops telemetry` | workspace | 21 | 21 |
+| `ops eval` | context | 25 | 25 |
+| `ops test-all` | quality | 40 | 40 |
+| `history events` | evidence | 33 | 33 |
+| `update many` | lifecycle | 146 | 146 |
+| `close many` | lifecycle | 72 | 72 |
+| `close delete` | lifecycle | 24 | 24 |

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -11,7 +11,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 - Uncovered error codes: 352
 - Coverage fraction: 0.051213
 - Closed-domain probes: 19
-- Grammar probes: 97
+- Grammar probes: 98
 
 | Error code | Canonical code | Disposition | Evidence kinds | Probe count |
 | --- | --- | --- | --- | --- |
@@ -211,7 +211,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `missing_parameter_alias` | `missing_parameter_alias` | uncovered | none | 0 |
 | `missing_positive_execution_receipt` | `missing_positive_execution_receipt` | uncovered | none | 0 |
 | `missing_probe` | `missing_probe` | uncovered | none | 0 |
-| `missing_required_argument` | `missing_required_argument` | executable | grammar | 60 |
+| `missing_required_argument` | `missing_required_argument` | executable | grammar | 61 |
 | `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 |

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.9.9"
+    "version": "2026.9.10"
   },
   "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.9.9",
+      "version": "2026.9.10",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.9",
+  "version": "2026.9.10",
   "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.9.9",
+  "version": "2026.9.10",
   "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.9.9",
+  "version": "2026.9.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

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

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.9.9",
+  "version": "2026.9.10",
   "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.9.9",
+  "version": "2026.9.10",
   "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/README.md

@@ -23,7 +23,7 @@ bodies and full before/after snapshots.
 - `pm dedupe-audit`
 - `pm dedupe-merge`
 - `pm comments-audit`
-- `pm normalize`
+- `pm ops normalize`
 
 The package also augments existing commands with audit-only flags:
 
@@ -63,7 +63,7 @@ pm install audit --project
 pm dedupe-audit --mode parent_scope --status all --limit 20 --json
 pm dedupe-merge --keep pm-canonical --close pm-duplicate --dry-run --json
 pm comments-audit --latest 3 --limit-items 20 --limit-rows 50 --json
-pm normalize --dry-run --json
+pm ops normalize --dry-run --json
 ```
 
 `dedupe-audit --status all` explicitly selects every status and is equivalent
@@ -80,3 +80,5 @@ For `comments-audit`, `--limit-items` caps item
 scanning while `--limit-rows` caps emitted comment rows across the whole
 result. The older `--limit` spelling remains a deprecated alias for
 `--limit-rows`; do not combine the two row-limit spellings.
+
+`pm normalize` remains a compatibility alias for `pm ops normalize`.

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

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

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.9.9",
+  "version": "2026.9.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.9.9",
+  "version": "2026.9.10",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.9.9",
+  "version": "2026.9.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.9.9",
+  "version": "2026.9.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",