@unbrained/pm-cli 2026.6.19 → 2026.6.21

package/docs/ARCHITECTURE.md

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

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -18,21 +18,11 @@ pm-cli/ (repo root)
 │   │   ├── pm-release/      # Release gate sequence and evidence linking
 │   │   ├── pm-audit/        # Comprehensive audit suite
 │   │   └── pm-planner/      # Planning: decompose, prioritize, triage
-│   ├── commands/
-│   │   ├── pm-status.md     # /pm-status
-│   │   ├── pm-start-task.md # /pm-start-task [id|keywords]
-│   │   ├── pm-close-task.md # /pm-close-task [id]
-│   │   ├── pm-triage.md     # /pm-triage <request>
-│   │   ├── pm-audit.md      # /pm-audit
-│   │   ├── pm-search.md     # /pm-search <query>
-│   │   ├── pm-new.md        # /pm-new <title>
-│   │   ├── pm-list.md       # /pm-list [filter]
-│   │   └── pm-calendar.md   # /pm-calendar [view]
+│   ├── commands/            # Slash-command definitions (one .md per /pm-* command)
 │   ├── hooks/
 │   │   ├── hooks.json       # SessionStart hook definition
 │   │   └── session-start.mjs # Injects pm context at session start
-│   ├── agents/
-│   │   └── pm-coordinator.md # Subagent for multi-item coordination
+│   ├── agents/              # Subagent definitions (one .md per coordinator/triage/verification subagent)
 │   ├── scripts/
 │   │   └── pm-mcp-server.mjs # MCP server launcher (repo → npx fallback)
 │   └── README.md            # User-facing installation guide
@@ -186,7 +176,9 @@ After installing the plugin:
 
 | pm-cli version | Plugin version | Claude Code version |
 |---------------|----------------|---------------------|
-| 2026.5.x+ | 1.0.0 | Any current |
+| 2026.5.x+ | 1.x | Any current |
+
+The authoritative plugin version is `plugins/pm-claude/.claude-plugin/plugin.json`; this row stays on the `1.x` major line so it does not drift with each plugin release.
 
 The MCP server uses JSON-RPC 2.0 over stdio with protocol version `2025-06-18`.
 

package/docs/COMMANDS.md

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

package/docs/CONFIGURATION.md

@@ -83,6 +83,7 @@ pm config project set id_prefix task                       # (id_prefix) IDs bec
 pm config project set author_default release-bot           # (author_default) default mutation author
 pm config project set output_default_format json           # (output.default_format) toon | json
 pm config project set locks_ttl_seconds 60                 # (locks.ttl_seconds) integer >= 1
+pm config project set checkpoints_retention_days 30        # (checkpoints.retention_days) integer >= 1; pm gc --scope checkpoints prunes checkpoints older than this many days
 pm config project set schema_unknown_field_policy reject   # (schema.unknown_field_policy) allow | warn | reject
 ```
 
@@ -128,6 +129,19 @@ Interaction rules:
 
 `pm telemetry stats` reads the local queue and reports, per command bucket, latency percentiles (`duration_p50_ms`/`duration_p95_ms`/`duration_max_ms`, nearest-rank over `command_finish` `duration_ms`), outcome rates (`ok_count`/`error_count`/`error_rate`; a finish event whose `ok` is missing or not strictly `true` is counted conservatively as an error), and `command_resolution_counts`. These are an always-available, zero-network performance and reliability signal for the most recent queued window.
 
+### Sentry environment variables
+
+Crash and error diagnostics are reported to Sentry only when telemetry is enabled and the process is not opted out. These environment variables tune the Sentry client.
+
+| Variable | Values | Use |
+|----------|--------|-----|
+| `PM_SENTRY_DISABLED` | boolean | Disable Sentry error reporting for this process (the Sentry SDK is not even imported). `PM_TELEMETRY_DISABLED` / `PM_NO_TELEMETRY` also disable it. |
+| `SENTRY_DSN` | URL | Override the destination DSN. Defaults to the bundled pm-cli project DSN. |
+| `SENTRY_ENVIRONMENT` | string | Override the reported environment tag. Defaults to `test` under Vitest, `ci` when `CI` is set, otherwise `production`. |
+| `SENTRY_TRACES_SAMPLE_RATE` | number `0`–`1` | Fraction of command spans sampled for performance tracing. Defaults to `0.2` (20%). Set to `1` for full-trace performance debugging or `0` to disable tracing. Non-numeric or out-of-range values fall back to the default. |
+
+> Sentry is hard-disabled under Vitest (`VITEST` / `VITEST_WORKER_ID`), so these knobs are no-ops inside the test suite.
+
 ## Item Storage Format
 
 TOON is the default:
@@ -231,6 +245,31 @@ pm search "release docs" --mode keyword --limit 10
 
 Semantic and hybrid search can use built-in OpenAI-compatible or Ollama providers plus vector stores such as Qdrant or LanceDB. If local Ollama is available and semantic settings are unset, `pm` can resolve local defaults automatically.
 
+### Offline BM25 provider (pm-75k9)
+
+For air-gapped, CI, or zero-setup environments there is a built-in **BM25** lexical ranker that powers `--semantic`/`--hybrid` search entirely in-process — no embedding service or vector store required. Select it via `search.provider`:
+
+```bash
+pm config project set search_provider bm25      # always use BM25 for semantic/hybrid
+pm config project set search_provider auto       # use BM25 only when no embedding provider is configured
+```
+
+- `bm25` always uses the offline ranker for semantic/hybrid queries, even when an embedding provider is set.
+- `auto` falls back to BM25 only when no embedding provider (and no extension search provider) is available; the search result then carries a `search_<mode>_offline_bm25:no_embedding_provider:using_lexical_bm25` warning.
+- Any other value (e.g. `openai`, `ollama`, or an extension provider name) keeps the existing embedding/vector path.
+
+Tune BM25 ranking with two persisted, validated knobs:
+
+- `search.bm25.k1` (number `>= 0`, default `1.2`) — term-frequency saturation; higher values let repeated terms keep accruing weight, lower values saturate sooner.
+- `search.bm25.b` (number `0..1`, default `0.75`) — document-length normalization; `0` disables it, `1` fully normalizes by length.
+
+```bash
+pm config project set search_bm25_k1 1.5
+pm config project set search_bm25_b 0.5
+```
+
+BM25 quality is lexical — a strong baseline, but below true dense retrieval; configure an embedding provider when semantic similarity matters. Measure either path against a golden-query set with `pm eval` (see COMMANDS.md).
+
 `search.hybrid_semantic_weight` (number `0..1`, default `0.7`) is the persistent default blend used in **hybrid** mode: it weights the semantic (vector) score against the lexical score during score fusion — higher favours semantic retrieval, lower favours keyword matching. A per-query `pm search --semantic-weight <value>` overrides it for a single query; when the flag is omitted the persistent setting applies. Set it once with:
 
 ```bash

package/docs/EXTENSIONS.md

@@ -150,7 +150,7 @@ export function activate(api) {
 }
 ```
 
-Package-backed extensions can use the SDK helper after declaring `@unbrained/pm-cli` in `package.json` and installing dependencies. Use this shape for packages published to npm or installed from a package root:
+Package-backed extensions can use the SDK helper after declaring `@unbrained/pm-cli` in `package.json` and installing dependencies. Registry installs satisfy that SDK import from the running host CLI instead of downloading a nested CLI copy into each project extension directory, so package authors can declare `@unbrained/pm-cli` as a peer dependency without adding the CLI's own telemetry/runtime dependencies to every workspace. Use this shape for packages published to npm or installed from a package root:
 
 ```js
 import { defineExtension } from "@unbrained/pm-cli/sdk";
@@ -427,7 +427,7 @@ requiring private loader imports or a temporary `.agents/pm/extensions` tree.
 Keep `pm package doctor --project --detail deep --trace` and runtime contracts
 for integration tests against installed packages.
 
-`PM_CLI_PACKAGE_ROOT` is first-party only. Bundled packages in this repository use it to find the running CLI's `dist/sdk/runtime.js` before they are published or installed independently. External packages must not read this environment variable or import from `dist/` or `src/core`; use `@unbrained/pm-cli/sdk`, `@unbrained/pm-cli/sdk/runtime`, and `@unbrained/pm-cli/sdk/testing`.
+`PM_CLI_PACKAGE_ROOT` is first-party only. Bundled packages in this repository use it to find the running CLI's `dist/sdk/runtime.js` before they are published or installed independently. External packages must not read this environment variable or import from `dist/` or `src/core`; use `@unbrained/pm-cli/sdk`, `@unbrained/pm-cli/sdk/runtime`, and `@unbrained/pm-cli/sdk/testing`. During `pm install npm:<package>`, pm links the installed package's `@unbrained/pm-cli` dependency back to the running host CLI so SDK imports resolve without a duplicate nested CLI install.
 
 ## Troubleshooting
 

package/docs/MIGRATION_CLI_SIMPLIFICATION.md

@@ -19,12 +19,19 @@ Normalization runs across command families and preserves a normalization trace f
 
 `resolvePmRoot()` precedence is now:
 
-1. explicit `--path`
+1. explicit `--pm-path` (or its compatibility alias `--path`)
 2. `PM_PATH`
 3. upward discovery of initialized `.agents/pm` roots (must contain `settings.json`)
 4. local default (`<cwd>/.agents/pm`)
 
-If you need the old local-only behavior from nested directories, pass an explicit path (`--path .agents/pm`).
+`--pm-path` is the preferred explicit flag; `--path` remains a backward-compatible
+alias for the same tracker-storage directory (not a workspace/cwd flag). An
+explicit path that points at a project root is redirected to its `.agents/pm`
+subdirectory (pm-ryik), so `--pm-path <repo>` and `--pm-path <repo>/.agents/pm`
+resolve to the same tracker. See [Configuration](CONFIGURATION.md) for the
+current contract.
+
+If you need the old local-only behavior from nested directories, pass an explicit path (`--pm-path .agents/pm`).
 
 ### 3) Structured recovery bundles in CLI error output
 

package/docs/QUICKSTART.md

@@ -83,8 +83,10 @@ Useful item types:
 | `Epic` | broad outcome or initiative |
 | `Feature` | user-facing capability or major slice |
 | `Task` | implementation work |
+| `Chore` | maintenance, refactoring, or housekeeping work |
 | `Issue` | bug or defect |
 | `Decision` | recorded choice and rationale |
+| `Plan` | agent-optimized living plan with ordered steps and evidence |
 | `Event`, `Reminder`, `Milestone`, `Meeting` | calendar-aware planning |
 
 ## Find and Claim Work

package/docs/README.md

@@ -38,9 +38,11 @@ pm guide release --json
 - [Testing](TESTING.md) - sandbox-safe local tests and linked-test orchestration.
 - [Architecture](ARCHITECTURE.md) - contributor internals: storage, mutation flow, search, extensions, and command contracts.
 - [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.
+- [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md) - the stability guarantees and contract surface package authors build against.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
 - [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
 - [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) - native Claude Code plugin architecture and install flow.
+- [CLI Simplification Migration](MIGRATION_CLI_SIMPLIFICATION.md) - root discovery (`--pm-path`), recovery bundles, and clear/unset semantics for automation maintainers.
 - [Releasing](RELEASING.md) - maintainer release checklist and failure handling.
 - [starter extension](examples/starter-extension/README.md) - compact extension scaffold reference.
 

package/docs/RELEASING.md

@@ -166,7 +166,7 @@ git push origin v<version>
 - build, typecheck, test, and coverage
 - static quality gate (complexity, duplication, dead/orphan module, file/folder hygiene)
 - temporary-project compatibility gate against latest published tracker data
-- reliability threshold gate (Sentry severity threshold; `--telemetry-mode` gate policy: `off` | `best-effort` | `required`)
+- reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
 - sandboxed `pm` coverage
 - optional Sentry release metadata and sourcemap upload when `SENTRY_AUTH_TOKEN` is configured
 - npm pack dry run and npx tarball smoke test
@@ -201,6 +201,7 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
 ## Failure Handling
 
 - If local gates fail, fix and rerun before tagging.
+- Treat failed scheduled Nightly Validation jobs as release-health blockers until triaged. The nightly workflow opens or updates a GitHub issue for each failing scheduled OS/Node matrix entry, with the run URL and commit SHA, so cross-platform regressions do not rely on someone manually scanning the Actions tab.
 - If the tag workflow fails before npm publish, confirm no package was published before moving or replacing a tag.
 - If npm publish succeeds but GitHub Release creation fails, rerun `.github/workflows/release.yml` with `workflow_dispatch` and `tag=v<version>`; the workflow skips duplicate npm publish, reruns public verification, and creates the GitHub Release for the existing tag.
 - Record failure evidence and remediation in the release `pm` item.

package/docs/SDK.md

@@ -55,6 +55,14 @@ Package manifest exports:
 - `readPmPackageManifest`
 - `collectPackageExtensionDirectories`
 
+Storage format-version exports (under `@unbrained/pm-cli/sdk/runtime`):
+
+- `CURRENT_ITEM_FORMAT_VERSION` / `BASELINE_ITEM_FORMAT_VERSION`
+- `effectiveItemFormatVersion` (resolve an item's stored version; absent means the baseline)
+- `normalizeItemFormatVersion` (persisted form; the baseline is dropped so it is never serialized)
+- `classifyItemFormatVersion` (`current` / `outdated` / `ahead`)
+- `scanItemFormatVersions` (partition items into outdated/ahead reference lists)
+
 Command/action contract exports:
 
 - `PM_CORE_COMMAND_NAMES`
@@ -68,6 +76,7 @@ Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 - `activateExtensionForTest`
 - `assertPackageManifest`
 - `assertRegisteredCommandContract`
+- `assertRegisteredFlags`
 - `assertRegisteredCommandOverride`
 - `assertRegisteredParserOverride`
 - `assertRegisteredPreflightOverride`
@@ -77,6 +86,10 @@ Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 - `assertRegisteredImporter`
 - `assertRegisteredExporter`
 - `assertRegisteredVectorStoreAdapter`
+- `assertRegisteredItemField`
+- `assertRegisteredItemType`
+- `assertRegisteredServiceOverride`
+- `assertRegisteredMigration`
 
 Commander option contract exports:
 
@@ -182,6 +195,29 @@ assertPackageManifest(manifest, {
 });
 ```
 
+Package tests can also assert extension registrations without importing private
+loader internals. Use `activateExtensionForTest` plus the targeted assertion for
+the surface your package owns:
+
+```ts
+import {
+  activateExtensionForTest,
+  assertRegisteredCommandContract,
+  assertRegisteredFlags,
+} from "@unbrained/pm-cli/sdk/testing";
+
+const activation = await activateExtensionForTest(extensionModule);
+
+assertRegisteredCommandContract(activation.registrations, {
+  command: "incident triage",
+  flags: ["--severity"],
+});
+assertRegisteredFlags(activation.registrations, {
+  targetCommand: "list",
+  flags: ["--incident-filter"],
+});
+```
+
 For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat and avoids advanced schema constructs such as root `oneOf`.
 
 ## Capability Requirements
@@ -372,7 +408,7 @@ import { defineExtension } from "@unbrained/pm-cli/sdk";
 import { createPmCliExpectedError } from "@unbrained/pm-cli/sdk/runtime";
 ```
 
-`PM_CLI_PACKAGE_ROOT` is reserved for first-party packages bundled inside this repository. Those packages use it to locate the running CLI's `dist/sdk/runtime.js` before they are installed as independent npm packages. External packages must not depend on `PM_CLI_PACKAGE_ROOT`, `dist/` paths, or `src/core/...`; declare `@unbrained/pm-cli` as a dependency or peer dependency and import the public SDK subpaths instead.
+`PM_CLI_PACKAGE_ROOT` is reserved for first-party packages bundled inside this repository. Those packages use it to locate the running CLI's `dist/sdk/runtime.js` before they are installed as independent npm packages. External packages must not depend on `PM_CLI_PACKAGE_ROOT`, `dist/` paths, or `src/core/...`; declare `@unbrained/pm-cli` as a dependency or peer dependency and import the public SDK subpaths instead. When pm installs a registry package, it links that dependency to the running host CLI so the package gets the active SDK without downloading a second CLI copy into the project.
 
 ## Testing Helpers
 
@@ -514,6 +550,41 @@ assertRegisteredPreflightOverride(activation.preflight); // preflight overrides
 assertRegisteredRendererOverride(activation.renderers, { format: "toon" });
 ```
 
+Service overrides from `registerService(service, override)` live on
+`activation.services` (an `ExtensionServiceRegistry`), so
+`assertRegisteredServiceOverride` takes the service registry and a known service
+name (`output_format` | `error_format` | `help_format` | `lock_acquire` |
+`lock_release` | `history_append` | `item_store_write` | `item_store_delete`):
+
+```ts
+import { assertRegisteredServiceOverride } from "@unbrained/pm-cli/sdk/testing";
+
+const service = assertRegisteredServiceOverride(activation.services, {
+  service: "output_format",
+  extensionName: "my-ext",
+});
+// service.run is the registered ServiceOverride handler
+```
+
+Schema migrations from `registerMigration(definition)` live on
+`activation.registrations.migrations`. `assertRegisteredMigration` matches by the
+migration `id` and can additionally assert the `mandatory` governance flag (an
+unset flag is treated as non-mandatory):
+
+```ts
+import { assertRegisteredMigration } from "@unbrained/pm-cli/sdk/testing";
+
+const migration = assertRegisteredMigration(activation.registrations, {
+  migration: "backfill-severity",
+  mandatory: true,
+});
+// migration.definition is the normalized SchemaMigrationDefinition
+```
+
+Together these complete the SDK assertion surface: every extension `register*`
+method now has a matching `assertRegistered*` helper, so packages can prove any
+registration without importing private registry internals.
+
 The bundled `pm-lifecycle-hooks` package is the first-party hooks exemplar. It
 declares only the `hooks` capability and registers a default-inert `afterCommand`
 hook, so package authors can copy a lifecycle pattern that does not write files,
@@ -630,6 +701,14 @@ Manifest capability: `importers` (and `schema` when supplying `flags`). The two-
 form remains supported; supplying the options object never produces a command-handler
 collision because the definition and handler share the same command path and extension.
 
+Importers and exporters read their source/destination through flags (e.g. `--file`,
+`--folder`) and take **no positional argument** unless one is declared via `arguments`.
+An unexpected positional (such as `pm jsonl import data.jsonl` instead of
+`pm jsonl import --file data.jsonl`) is rejected with a usage error rather than being
+silently ignored, and any `failure_hints` you register are appended to that error so an
+agent is steered to the correct flag. Flags declared via `flags` render once, as
+first-class options in the standard `Options:` section of `--help`.
+
 The bundled `pm-beads` and `pm-todos` packages are first-party importer/exporter
 exemplars that use this registration path and expose runtime contracts for their
 generated commands.