@unbrained/pm-cli 2026.7.7 → 2026.7.9

package/docs/AGENT_GUIDE.md

@@ -116,9 +116,12 @@ pm release <item-id>
 | Open work only | `pm search "<keywords>" --status open` (drops closed-history noise; did-you-mean on typos) |
 | Scope search like list | `pm search "<keywords>" --type Task --assignee <name> --parent <id>` (full `pm list` filter parity) |
 | Items changed since last window | `pm list-all --updated-after <prev-run-ISO> --brief` (relative `-2h`/`-7d` also work) |
+| Open items changed today | `pm list-open --today --brief` (local-midnight shorthand; mutually exclusive with `--updated-after`) |
+| Items changed recently | `pm list-all --recent --brief` (last seven days; mutually exclusive with `--updated-after`) |
 | Single item | `pm get <id>` |
 | Full machine payload | `pm get <id> --full --json` |
 | Command flags | `pm <command> --help --json` |
+| Command intent map | `pm contracts --summary --json` (one command plus terse intent per row; use before command-scoped contracts) |
 | Low-noise machine contracts | `pm contracts --command <command> --flags-only --json` |
 | Semantic index refresh | `pm reindex --mode semantic --progress` (stale-first by default; add `--full` to force full rebuild; requires the `search-advanced` package) |
 | Timeline | `pm activity --id <id> --limit 20` |

package/docs/COMMANDS.md

@@ -7,6 +7,7 @@ Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon),
 ```bash
 pm <command> --help
 pm <command> --help --json
+pm contracts --summary --json
 pm contracts --command <command> --flags-only --json
 ```
 
@@ -15,7 +16,7 @@ pm contracts --command <command> --flags-only --json
 - Prefer `pm context`, `pm search`, and narrow list commands before mutation.
 - Prefer TOON for reading and `--json` for strict parsing.
 - Use the [guide topic map](README.md#guide-topic-map) when optional `pm guide` local docs routing is needed.
-- Use `pm contracts` for machine clients.
+- Use `pm contracts --summary --json` for the cheapest command map, then narrow with command-scoped contracts.
 - Every mutation writes history.
 
 Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
@@ -129,6 +130,10 @@ 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
 
+# Common list windows avoid date math (`list-open` keeps the view open-only).
+pm list-open --today --brief
+pm list-all --recent --brief
+
 # 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.
@@ -141,6 +146,8 @@ pm search "reminder validation" --status all --limit 10
 pm search "calendar" --type Task --assignee alice --updated-after=-7d --parent pm-abcd
 ```
 
+Use only one updated-at window per list call: `--today`, `--recent`, and `--updated-after` are mutually exclusive. `--today` starts at local midnight; `--recent` is the same as `--updated-after=-7d`.
+
 `pm get`, `pm history`, and `pm search` also accept command-local `--format json|toon`. `--format json` is equivalent to the global `--json` flag for that command, while `--format toon` keeps the default agent-readable output. Do not combine global `--json` with `--format toon`.
 
 `list`/`search` full and fields projections echo full filter metadata. Compact mode emits only active filters (plus runtime schema filters when present) and omits the default projection/sorting/now trailer keys for lower token cost.
@@ -858,12 +865,14 @@ Invariants:
 
 ```bash
 pm contracts --json
+pm contracts --summary --json
 pm contracts --command create --flags-only --json
 pm contracts --action create --schema-only --json
 pm help create --json
 ```
 
 Agents should use runtime contracts instead of hard-coding flag lists. Contract output includes extension-provided command surfaces when active.
+Use `pm contracts --summary --json` first when bootstrapping in a tight context window; it emits one command and terse intent per row before the agent requests heavier command-specific flags or schemas.
 
 ## Completion
 

package/docs/EXTENSIONS.md

@@ -179,16 +179,9 @@ useful for agents without inflating context or leaking private item content.
 
 ## Extension Manifest
 
-Runnable manifest examples are the source of truth:
+Runnable manifest examples are the source of truth: [starter extension manifest](examples/starter-extension/manifest.json) and [policy-restricted manifest](examples/policy-restricted-extension/manifest.json).
 
-- [starter extension manifest](examples/starter-extension/manifest.json)
-- [policy-restricted manifest](examples/policy-restricted-extension/manifest.json)
-
-Schema:
-
-- Use [extension-manifest.schema.json](schemas/extension-manifest.schema.json) as the
-  `$schema` value for inline editor validation. The loader ignores `$schema` and
-  tolerates future manifest fields, but the schema documents the fields pm reads.
+Use [extension-manifest.schema.json](schemas/extension-manifest.schema.json) as the `$schema` value for inline editor validation. The loader ignores `$schema` and tolerates future manifest fields, but the schema documents the fields pm reads.
 
 Rules:
 
@@ -347,9 +340,12 @@ Run diagnostics:
 ```bash
 pm package doctor --project --detail summary
 pm package doctor --project --detail deep --trace
+pm package doctor --project --isolated --detail deep --trace
 pm package doctor --project --strict-exit
 ```
 
+Use `--isolated` (alias `--ignore-global`) when a package smoke test must inspect only the project install. Non-isolated project diagnostics include global registrations and emit an isolation remediation hint when global package state can affect the result; subprocess-based test suites can also set `PM_GLOBAL_PATH` to a temporary directory for the whole run.
+
 Manage state and update checks:
 
 ```bash
@@ -359,22 +355,12 @@ pm package adopt my-extension --project
 pm package adopt-all --project
 ```
 
-Activate or deactivate:
+Activate, deactivate, uninstall, and reload:
 
 ```bash
 pm package activate my-extension --project
 pm package deactivate my-extension --project
-```
-
-Uninstall:
-
-```bash
 pm package uninstall my-extension --project
-```
-
-Reload local edits:
-
-```bash
 pm package reload --project
 pm package reload --project --watch
 ```
@@ -432,6 +418,7 @@ Prefer `createExtensionTestHarness(module, { capabilities })` in package unit te
 
 - Manifest or entry failure: run `pm package explore --project`.
 - Activation failure: run `pm package doctor --detail deep --trace`.
+- Machine-dependent package diagnostics: run `pm package doctor --project --isolated --detail deep --trace` or set `PM_GLOBAL_PATH` to a temp directory.
 - Policy block: inspect `settings.extensions.policy` and `details.summary.policy`.
 - Runtime drift: compare with `pm --no-extensions <command>`.
 - Managed-state update-check gap: run `pm package manage --fix-managed-state`.

package/docs/RELEASING.md

@@ -139,6 +139,12 @@ Minimum coverage:
 
 Use maintainer-only local workflows for reliability checks and incident triage. Keep operational details, infrastructure topology, and raw diagnostics out of tracked release documentation and release notes.
 
+Run the public Sentry/telemetry threshold gate through the package script alias:
+
+```bash
+pnpm sentry:telemetry:gate -- --telemetry-mode best-effort
+```
+
 If private reliability checks identify repeated user friction, either confirm the current release already contains the remediation with regression coverage or fix it before continuing.
 
 4. Run the same release pipeline locally.

package/docs/SDK.md

@@ -106,6 +106,14 @@ Command/action contract exports:
 - `PmClient` / `runAction` (high-level in-process action execution for custom tools, bots, CI, and embedded runtimes)
 - Typed read primitives on `PmClient`: `get`, `list`, `search`, `context`, `next`, `aggregate`, and `stats`
 - Read primitive option/result contracts: `GetOptions` / `GetResult`, `ListOptions` / `ListResult`, `SearchOptions` / `SearchResult`, `ContextOptions` / `ContextResult`, `NextOptions` / `NextResult`, `AggregateOptions` / `AggregateResult`, `StatsCommandOptions` / `StatsResult`
+- Typed annotation and relationship primitives on `PmClient`: `comments`, `notes`, `learnings`, `files`, `filesDiscover`, `docs`, `deps`, and `append`
+- Annotation and relationship option/result contracts: `CommentsCommandOptions` / `CommentsResult`, `NotesCommandOptions` / `NotesResult`, `LearningsCommandOptions` / `LearningsResult`, `FilesCommandOptions` / `FilesResult`, `FilesDiscoverOptions` / `FilesDiscoverResult`, `DocsCommandOptions` / `DocsResult`, `DepsCommandOptions` / `DepsResult`, `AppendCommandOptions` / `AppendResult`
+- Typed customization primitives on `PmClient`: `init`, `config`, `schema`, `schemaList`, `schemaShow`, `schemaAddType`, `schemaRemoveType`, `schemaAddStatus`, `schemaRemoveStatus`, `schemaAddField`, `schemaRemoveField`, `schemaListFields`, `schemaShowField`, `schemaApplyPreset`, `schemaInferTypes`, `schemaShowStatus`, `profile`, `profileList`, `profileShow`, `profileApply`, and `profileLint`
+- Customization primitive option/result contracts: `InitCommandOptions` / `InitResult`, `ConfigCommandOptions` / `ConfigResult`, `SchemaSubcommand` / `SchemaResult` / `SchemaInspectResult`, `SchemaListResult`, `SchemaShowResult`, `SchemaAddTypeResult`, `SchemaRemoveTypeResult`, `SchemaAddStatusResult`, `SchemaRemoveStatusResult`, `SchemaAddFieldResult`, `SchemaRemoveFieldResult`, `SchemaListFieldsResult`, `SchemaShowFieldResult`, `SchemaApplyPresetResult`, `SchemaAddTypeInferResult`, `SchemaShowStatusResult`, `ProfileSubcommand` / `ProfileResult`, `ProfileListResult`, `ProfileShowResult`, `ProfileApplyResult`, `ProfileLintResult`
+- Typed governance and maintenance primitives on `PmClient`: `validate`, `health`, and `gc`
+- Governance and maintenance option/result contracts: `ValidateCommandOptions` / `ValidateResult`, `RunHealthOptions` / `HealthResult`, `GcCommandOptions` / `GcResult`
+- Typed package and extension lifecycle primitives on `PmClient`: `extension`, `extensionList`, `extensionActivate`, `extensionDeactivate`, `package`, `packageList`, `packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`, `packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`, `packageDeactivate`, and `upgrade`
+- Lifecycle primitive option/result contracts: `ExtensionCommandOptions` / `ExtensionCommandResult`, `PackageCommandOptions` / `PackageCommandResult`, `UpgradeCommandOptions` / `UpgradeResult`
 - `PM_CORE_COMMAND_NAMES`
 - `PM_TOOL_ACTIONS`
 - `PM_TOOL_PARAMETERS_SCHEMA`
@@ -448,6 +456,17 @@ const open = await pm.list({ status: "open", limit: "20" });
 const recommendation = await pm.next({ readyOnly: true });
 const grouped = await pm.aggregate({ groupBy: "status", count: true });
 const stats = await pm.stats({ metadataCoverage: true });
+await pm.comments(created.item.id, { add: "Investigation context captured." });
+await pm.files(created.item.id, { add: ["src/index.ts"], note: "entrypoint" });
+await pm.docs(created.item.id, { add: ["docs/SDK.md"], note: "authoring reference" });
+const graph = await pm.deps(created.item.id, { format: "graph" });
+const types = await pm.schemaList();
+const profiles = await pm.profileList();
+const validation = await pm.validate({ checkResolution: true });
+const health = await pm.health({ checkOnly: true, summary: true });
+const packages = await pm.packageList({ project: true });
+const doctor = await pm.packageDoctor({ project: true, isolated: true });
+const plannedUpgrade = await pm.upgrade(undefined, { dryRun: true, cliOnly: true });
 
 await runAction({
   action: "context",
@@ -477,6 +496,48 @@ Lifecycle convenience methods and the matching top-level functions (`create`,
 as the CLI and MCP dispatcher. They are the baseline primitives for custom PM
 tools that need to own item state without spawning `pm`.
 
+Package and extension lifecycle convenience methods are the SDK primitive layer
+for custom PM tools that need to manage their own package surface without
+shelling out. Use `pm.packageList`, `pm.packageInstall`,
+`pm.packageUninstall`, `pm.packageDoctor`, `pm.packageManage`,
+`pm.packageDescribe`, `pm.packageReload`, `pm.packageCatalog`,
+`pm.packageActivate`, `pm.packageDeactivate`, and `pm.upgrade` for package-mode
+automation; use `pm.extensionList`, `pm.extensionActivate`, and
+`pm.extensionDeactivate` when the UI vocabulary is explicitly extension-focused.
+The matching top-level helpers (`packageLifecycle`, `packageList`,
+`packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`,
+`packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`,
+`packageDeactivate`, `extension`, `extensionList`, `extensionActivate`,
+`extensionDeactivate`, and `upgrade`) construct a short-lived `PmClient` for
+one-off calls. Package helpers return `PackageCommandResult` and extension
+helpers return `ExtensionCommandResult`; both names describe the same lifecycle
+payload shape with vocabulary-appropriate SDK signatures. `UpgradeResult` is the
+same structured payload rendered by the CLI, so embedded tools can own their
+presentation layer while sharing pm's package/install/doctor semantics.
+
+Annotation and relationship convenience methods turn "project management =
+context management" into a typed SDK surface. Use `pm.comments`, `pm.notes`,
+`pm.learnings`, `pm.files`, `pm.docs`, `pm.deps`, and `pm.append` when an
+embedded agent, package, or custom UI needs to add durable rationale, link
+changed files/docs/tests, or inspect the item graph. `pm.filesDiscover` exposes
+the same file-candidate discovery used by the CLI, so a custom tool can present
+reviewable link suggestions instead of scraping git output itself.
+
+Customization convenience methods are the SDK baseline for project-specific pm
+tools. `pm.init` stages a tracker, `pm.config` reads/writes settings,
+`pm.schema*` methods manage types/statuses/fields/presets, and `pm.profile*`
+methods list, inspect, apply, and lint project archetypes. These helpers let a
+package or app construct an opinionated project-management experience while
+staying on the same schema/profile primitives the CLI and MCP use.
+
+Governance and maintenance convenience methods expose the operational floor a
+custom PM host should run before it trusts or publishes tracker state.
+`pm.validate` checks resolution/history invariants, `pm.health` performs
+read-only diagnostics, and `pm.gc` runs dry-run or explicit cleanup paths through
+the same bounded maintenance engine as the CLI. Prefer these typed calls over
+shelling out when building CI, editor integrations, or long-running agent
+runtimes.
+
 `PmClient` and `runAction` share the same process-wide extension activation
 queue as MCP. Calls from one process are serialized across extension load,
 activation, dispatch, cleanup, and deactivate so active extension registries stay
@@ -579,9 +640,15 @@ Some override surfaces are single-winner: command overrides, parser overrides, p
 
 ```bash
 pm package doctor --project --detail deep --trace
+pm package doctor --project --isolated --detail deep --trace
 pm health --check-only --brief
 ```
 
+Use `--isolated` (alias `--ignore-global`) for hermetic package smoke tests:
+project diagnostics skip global registrations and avoid machine-local
+renderer/service overrides. The same isolation can be applied to a whole
+subprocess suite by setting `PM_GLOBAL_PATH` to a temporary directory.
+
 Collision warnings are deterministic and include package names plus deactivation guidance.
 If extension code calls a `register*` API without declaring the matching
 manifest capability, activation fails with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.7.7",
+  "version": "2026.7.9",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -103,6 +103,7 @@
     "review:greptile:gate": "node scripts/release/greptile-review-gate.mjs",
     "security:scan": "node scripts/check-secrets.mjs",
     "smoke:npx": "node scripts/smoke-npx-from-pack.mjs",
+    "sentry:telemetry:gate": "node scripts/release/sentry-telemetry-gate.mjs",
     "sentry:inject": "sentry-cli sourcemaps inject dist/",
     "sentry:upload": "sentry-cli sourcemaps upload --org unbrained --project pm-cli --release \"pm-cli@$npm_package_version\" --validate dist/",
     "build:sentry": "pnpm build && pnpm sentry:inject && pnpm sentry:upload",

package/dist/cli-bundle/chunks/append-F7WPGIQL.js

@@ -1,11 +0,0 @@
-import {
-  runAppend
-} from "./chunk-DDDWVPID.js";
-import "./chunk-WW4E2DC3.js";
-import "./chunk-2TILG6F2.js";
-import "./chunk-YNCFP5AR.js";
-import "./chunk-LCFJ7XAM.js";
-export {
-  runAppend
-};
-//# sourceMappingURL=append-F7WPGIQL.js.map