@unbrained/pm-cli 2026.9.8 → 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                                                                                                                                                                                                   |
@@ -254,6 +254,16 @@ Use only one updated-at window per list call: `--today`, `--recent`, and `--upda
 
 Keyword mode now applies the configured `search.max_results` default (50) when `--limit` is omitted, so a broad query no longer returns every hit. When the limit drops rows the result adds a top-level `total` (pre-limit match count).
 
+### Default search mode (pm-n8a6e7)
+
+A bare `pm search` runs in the mode the SDK resolves from `search.default_mode`, never from a literal in the CLI. `auto` (the default) picks `hybrid` exactly when the stored settings name the active embedding provider (`search.provider`, the same `configured` verdict `pm health` reports) and a vector store or extension adapter resolves, or when an extension search provider is active; every other workspace runs `keyword`. Auto-detected Ollama/LanceDB runtime defaults do not count as configured, so an unconfigured host never pays an embedding round-trip it did not ask for. A concrete `search.default_mode` (`keyword`, `semantic`, `hybrid`) pins the answer, and `--mode` always wins. The result reports `mode` (what ran, after any runtime fallback) beside `mode_source` (`explicit`, `settings`, or `auto`), so a caller can tell a chosen mode from a derived one (compact responses carry `mode_source` only for `settings`, since `explicit` is the caller's own choice and `auto` is the documented default); when the provider is unreachable a hybrid default still degrades to keyword hits with the usual `search_semantic_fallback` warning.
+
+```bash
+pm search "context budget"                       # auto: hybrid here because search.provider is configured and the index resolves
+pm config project set search_default_mode keyword   # pin keyword for a workspace that prefers exact-token results
+pm search "context budget" --mode semantic       # explicit request, mode_source: explicit
+```
+
 ```bash
 pm search "reminder validation queue" --match-mode and          # require all three tokens
 pm search "exact title phrase" --match-mode exact               # contiguous-phrase match
@@ -394,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.
 
@@ -501,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
@@ -512,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"
@@ -545,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"
@@ -692,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
@@ -705,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.
+
+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 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)
+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
 
@@ -898,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.
 
@@ -906,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
@@ -1228,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/CONFIGURATION.md

@@ -388,6 +388,16 @@ Advanced relevance tuning is opt-in:
 When query expansion or rerank providers fail, `pm search` degrades gracefully and keeps the query runnable; warning codes are emitted in the result payload.
 `pm search` filter metadata now reports `query_expansion_*` and `rerank_*` fields so automation can detect when advanced tuning is active.
 
+`search.default_mode` decides the mode a bare `pm search` runs in (`--mode` always wins):
+
+| Value                | Behavior                                                                                                                                                          |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auto`               | default; `hybrid` when `search.provider` names the active embedding provider and a vector store or extension adapter resolves (or an extension search provider is active), `keyword` otherwise |
+| `keyword`            | pin exact-token ranking for every bare search                                                                                                                     |
+| `semantic`, `hybrid` | pin the semantic path; an unreachable provider still degrades to keyword hits with a `search_semantic_fallback` warning                                            |
+
+Every search result reports `mode_source` (`explicit`, `settings`, or `auto`) beside the effective `mode`.
+
 Mutation commands invalidate keyword search caches immediately. Semantic vector refresh is controlled by `search.mutation_refresh_policy`:
 
 | Policy                | Behavior                                                                                                            |
@@ -399,6 +409,7 @@ Mutation commands invalidate keyword search caches immediately. Semantic vector
 Useful commands:
 
 ```bash
+pm config project set search_default_mode keyword
 pm config project set search_mutation_refresh_policy cache_only
 pm config project set search_embedding_corpus_max_characters 12000
 pm config project set search_query_expansion_enabled true
@@ -468,7 +479,7 @@ pm config project set qdrant_api_key '<QDRANT_API_KEY>'   # omit on unauthentica
 
 After changing any of these, run `pm reindex --mode hybrid` so the vector index reflects the new provider/store. `pm search ... --mode semantic|hybrid` emits a `vector_index_stale` warning when items have been modified since the last reindex.
 
-**Refresh contract (important for agents):** by default a mutation (`pm create`/`pm update`) does **not** synchronously re-embed the changed item, so a brand-new item is absent from `--mode semantic|hybrid` results until the next `pm reindex`. This keeps writes fast. Control the tradeoff with `search.mutation_refresh_policy`: `cache_only` (never refresh on write — fastest), `semantic_auto` (refresh when implicit Ollama/LanceDB defaults are active), or `semantic_configured` (refresh only when semantic search is explicitly configured). Keyword mode (`--mode keyword`, the default) always reflects writes immediately because it reads items directly.
+**Refresh contract (important for agents):** by default a mutation (`pm create`/`pm update`) does **not** synchronously re-embed the changed item, so a brand-new item is absent from `--mode semantic|hybrid` results until the next `pm reindex`. This keeps writes fast. Control the tradeoff with `search.mutation_refresh_policy`: `cache_only` (never refresh on write — fastest), `semantic_auto` (refresh when implicit Ollama/LanceDB defaults are active), or `semantic_configured` (refresh only when semantic search is explicitly configured). Keyword mode (`--mode keyword`, or the `auto` default on a workspace without a configured semantic provider) always reflects writes immediately because it reads items directly.
 
 ## Custom Item Types
 

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.
@@ -62,6 +63,7 @@ pm guide release --json
 - [Universal Read Output Contracts](READ_OUTPUT_CONTRACTS.md) - cross-command include, amount, cost, and encoding controls for CLI, SDK, MCP, and packages.
 - [Diagnostic Output Contracts](DIAGNOSTIC_OUTPUT_CONTRACTS.md) - action-first error budgets, deterministic degradation, SDK projection, and executable refusal assurance.
 - [History Maintenance and Recovery](HISTORY_MAINTENANCE.md) - native history commands, permanent aliases, shared SDK transforms, and transactional recovery.
+- [Declarative Workflow Policies](WORKFLOW_POLICIES.md) - portable lifecycle requirements, independent approvals, and completeness reports.
 - [Mutation Integrity](MUTATION_INTEGRITY.md) - shared CLI/SDK/MCP author, secret, append-only disposition, and stale-work guardrails.
 - [Agent Provenance ADR Amendment](AGENT_PROVENANCE_ADR.md) - extensible model, effort, role, and host provenance with privacy and compatibility boundaries.
 - [SDK Agent Session and Episode Context](SDK_AGENT_SESSION_CONTEXT.md) - inherited role/topic context, cross-process episode identity, and deterministic history grouping.
@@ -99,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/READ_OUTPUT_CONTRACTS.md

@@ -167,6 +167,11 @@ Cursor recovery carries the opaque value once in `recovery.cursor` and declares
 the accepting `cli`, `sdk`, and `mcp` binding beside it. This avoids
 serializing the same cursor once per transport while retaining an executable,
 machine-readable binding for each surface.
+When `restore_with` is `"recovery"`, consumers must resolve the adjacent
+`recovery` object: pass its `cursor` value through `cli` (`--output-cursor`)
+or the `sdk`/`mcp` field (`outputCursor`) while repeating the original query.
+The string is a reference, not a shell command. Other `restore_with` values
+provide retry guidance when no declared row collection can continue.
 
 Budget-compacted declared row paths are independently resumable. The
 disclosure's `continuations` entries name the row path, retained/remaining/total

package/docs/TESTING.md

@@ -88,6 +88,16 @@ so PR-local CodeFactor maintainability annotations fail locally before commit or
 push. Existing legacy high-complexity test fixtures are tracked separately and
 must not be used as precedent for new changed production/script code.
 
+`lint:duplicates` runs three zero-clone profiles: the broad repository profile,
+the production cross-format profile, and a supplemental long-table profile at
+28 lines / 80 tokens. The last profile detects the historical GH-508 normalizer
+tables below the other profiles' token floors; it does not replace their shorter
+line thresholds. Its real detector regression rejects the historical table rows
+and accepts a shared declaration. The earlier 12-line / 60-token exploratory
+census informed calibration, but is not the enforced profile. These bounded
+profiles do not claim complete equivalence with hosted analyzers.
+See [pm-xspd](../.agents/pm/chores/pm-xspd.toon) for calibration evidence.
+
 The local parity rules catch analyzer classes before push. The mandatory hosted
 proof runs after the final commit is pushed and both apps have finished:
 

package/docs/WORKFLOW_POLICIES.md

@@ -0,0 +1,129 @@
+# Declarative workflow policies
+
+Tracker: [pm-mj42og](../.agents/pm/features/pm-mj42og.toon) and [pm-htbetn](../.agents/pm/features/pm-htbetn.toon).
+
+Projects can describe their lifecycle requirements as versioned data. The SDK
+uses the same evaluator for item mutations, policy previews, and completeness
+reports. Existing projects have no implicit policies. A declaration can advise,
+warn, or refuse; refusal also requires an explicit workspace opt-in.
+
+## Configure a requirement
+
+```bash
+pm schema policy-put close-evidence --definition '{"id":"close-evidence","effect":"refuse","subject":{"statuses":["closed"]},"rule":{"kind":"require_fields","fields":["resolution","actual_result"]}}'
+pm schema policies
+pm schema policy-check pm-example --definition '{"status":"closed"}'
+pm schema policy-mode refuse
+```
+
+Use canonical status ids and metadata field names. `body` selects the Markdown
+body. Custom fields can use dotted paths with at most eight segments. Empty
+strings, arrays, objects, null, and absent values do not satisfy required fields;
+zero and false are meaningful values.
+
+`policy-put` replaces a declaration with the same id. `policy-remove <id>` removes
+one declaration. `policy-mode advise` disables refusal while retaining diagnostics.
+Registry writes are locked and recorded in workspace history. `--dry-run` previews
+registry changes without writing. Malformed registries fail closed.
+
+## Selectors and rules
+
+All selectors in `subject` must match; values within one selector are alternatives.
+Supported selectors are `types` (case insensitive), `tags`, `statuses`, `operations`,
+`parents`, and `dependency: { "kind": "implements", "id": "pm-example" }` (id optional).
+Parent and dependency selectors inspect direct relationships. Status selectors
+match the destination; other selectors inspect both snapshots so a mutation cannot
+escape a protected scope by removing its tag or changing its type.
+
+| Rule kind | Required properties | Behavior |
+| --- | --- | --- |
+| `require_fields` | `fields` | Checks evidence on lifecycle, scope, or required-field changes |
+| `transition` | `allowed` | Allows listed `[from, to]` status pairs; `$create` and `$delete` represent absent records |
+| `authors` | `authors` | Requires a listed mutation actor |
+| `field_writers` | `fields`, `authors` | Requires a listed actor when protected fields change |
+| `approval` | `fields`, `authors` | Requires independent approval when an existing item changes status or is deleted |
+
+Operation selectors use exact history operation names. Unknown declaration keys
+are errors. Policies contain no executable expressions or regular expressions.
+At most 256 declarations and 64 terms per selector/rule are accepted. Registry
+reads are bounded to 1 MiB, and approval-history reads to 4 MiB.
+
+Actor names are provenance supplied by the caller or local configuration. They
+are not authenticated identities, and these rules are not an access-control
+boundary against a caller who can edit the tracker or choose an author name.
+Authenticated, signed identity ([pm-u14c](../.agents/pm/stories/pm-u14c.toon))
+is a prerequisite for stronger authorization guarantees.
+
+## Approvals
+
+Prepare the declared fields, then have a different workflow actor record approval:
+
+```bash
+pm schema policy-put review --definition '{"id":"review","effect":"refuse","subject":{"statuses":["closed"]},"rule":{"kind":"approval","fields":["body","resolution"],"authors":["reviewer"]}}'
+pm schema policy-approve pm-example --policy review --author reviewer --message 'Reviewed acceptance evidence'
+```
+
+Approval events bind the item id, selected field values, and complete policy
+revision. Changing reviewed content or the declaration invalidates the approval.
+Unrelated metadata changes do not. The actor performing the transition must differ
+from the approval actor. Only sealed approval events from a verified item history
+chain count. `policy-check` previews transitions; `policy-approve` always records
+an event and rejects `--dry-run`.
+
+Approval rules apply to existing items. Creation and initial imports have no
+reviewable history and skip approval requirements; use `transition` rules with
+`["$create", "open"]` to constrain their initial status. Deletion requires approval
+of the current record, using the same content and independent-actor checks.
+
+Refused mutations preserve item state and item history, and append a workspace
+refusal event. Accepted mutations attach bounded policy decisions to their normal
+history event. Diagnostics contain policy ids and missing field paths, without
+copying reviewed content into errors.
+If the mandatory refusal audit cannot be appended, the mutation instead raises
+`workflow_policy_audit_failed` and preserves the original failure in the SDK
+error's `cause`. Item data remains unchanged; resolve the workspace history lock
+or storage failure before retrying. Package imports do not downgrade this error
+to an item-lock warning.
+
+## Completeness reports and SDK
+
+```bash
+pm schema policy-presets
+pm validate --check-completeness --strict-exit
+```
+
+Presets return optional advisory declarations for familiar item types. They do
+not install policies. Author the declarations appropriate to the project's own
+types and lifecycle using `policy-put`. Completeness reports group counts by type,
+return bounded violation examples, and use only `require_fields` declarations
+without `subject.operations`. The report identifies this scope as
+`operation_independent_require_fields`. All item selectors, including status,
+still apply. `policy-check` without a proposed definition uses the same state-only
+scope. Operation-scoped rules remain enforced during matching mutations; a clean
+state report does not imply permission to perform every future operation.
+To check a lifecycle field invariant in both state reports and mutations, select
+its `statuses` without restricting `operations`.
+Default validation includes this check; projects without declarations remain
+unaffected.
+An unreadable or malformed `schema/policies.json` produces an error-level
+`completeness` result with a repair hint. Other requested validation checks still
+run, and `--strict-exit` fails until the policy registry is repaired.
+
+The published `@unbrained/pm-cli/sdk/governance` entrypoint exports
+`runWorkflowPolicyAction`, `evaluateWorkflowPolicies`, policy types, parsers,
+`WORKFLOW_POLICY_SCHEMA`, and `WORKFLOW_POLICY_DOCUMENT_SCHEMA`. `PmClient` exposes
+`workflowPolicy(action, name, options)`. CLI `schema` and MCP `pm_schema` use the
+same action vocabulary and SDK implementation; MCP options accept camelCase
+keys and structured JSON definitions.
+
+For repeated pure evaluation, `createWorkflowPolicyEvaluator(document)` returns
+an evaluator that owns a private normalized policy snapshot and hashes each
+declaration once. Later edits to the supplied document do not change that
+snapshot; create another evaluator to adopt them. Completeness validation uses
+one such snapshot for the whole supplied corpus.
+
+The schema contract version is 4.16. Existing schema operations remain available;
+`SchemaResult` now also includes `WorkflowPolicyActionResult`. Consumers that
+exhaustively narrow schema results should handle the `policy_result: true`
+discriminant. Validation options include `checkCompleteness`, and validation
+results can contain a `completeness` check.

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 |