@unbrained/pm-cli 2026.5.1 → 2026.5.3-5

package/AGENTS.md

@@ -35,7 +35,7 @@ This document defines how coding agents must use `pm` for planning, execution, a
 Before creating any new `pm` item, always check for an existing relevant item first.
 
 - Search and list existing items before `pm create`:
-  - `pm context --limit 10`
+  - `pm context --limit 10` (brief snapshot; use `--depth standard` for hierarchy/progress/workload, `--depth deep` for full sections)
   - `pm search "<keywords>" --limit 10`
   - `pm list-open --limit 20`
   - `pm list-in-progress --limit 20`
@@ -208,6 +208,13 @@ Use release when:
 
 - Prefer default TOON output for list/search/get in agent loops.
 - Prefer `pm context --limit <n>` as the first triage snapshot when selecting next work.
+  - `--depth brief` (default) shows only focus items + agenda -- minimal tokens.
+  - `--depth standard` adds hierarchy, activity, progress, and workload sections -- recommended for medium/large projects.
+  - `--depth deep` adds blockers, hot files, staleness, and test health -- use for full project orientation or debugging.
+  - `--section <name>` (repeatable) overrides `--depth` and includes only named sections (hierarchy, activity, progress, blockers, files, workload, staleness, tests).
+  - `--activity-limit <n>` controls recent activity entries (default 10).
+  - `--stale-threshold <value>` controls staleness cutoff in days (default 7d).
+  - Configure persistent defaults via `pm config project set context --default-depth standard --activity-limit 15`.
 - Use `--json` only when strict machine parsing is required.
 - Request narrow outputs:
   - `--limit`

package/CHANGELOG.md

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2026.5.3-5] - 2026-05-03
+
+### Changed
+- Hardened release workflow reliability gating so Sentry threshold checks are skipped when the runner does not provide the `sentry` CLI binary, preventing false-negative publish blocks on GitHub-hosted runners.
+
+## [2026.5.3-4] - 2026-05-03
+
+### Changed
+- Relaxed tag release version policy guard in `.github/workflows/release.yml` to validate tag/version consistency without blocking same-day retry tags when a previous tag run failed before npm publication.
+- Hardened `scripts/release/run-release-pipeline.mjs` same-day retry version resolution so local retry cuts always advance beyond the currently checked-out package version when npm has not yet observed failed prior tags.
+
+## [2026.5.3-3] - 2026-05-03
+
+### Fixed
+- Relaxed release compatibility health evaluation so compatibility gating only blocks on failing health checks, not warning-only health states, preventing false negatives on GitHub-hosted release runs.
+
+## [2026.5.3-2] - 2026-05-03
+
+### Added
+- Added a scheduled auto-release workflow (`.github/workflows/auto-release.yml`) with one-release-per-UTC-day defaults, manual same-day override controls, and a shared release pipeline driver.
+- Added release automation scripts under `scripts/release/` for changelog promotion, strict static quality checks, temporary-project backward-compatibility validation, Sentry/telemetry threshold gating, unified release gate execution, and full local pipeline orchestration.
+- Added release automation contract coverage in `tests/integration/release-automation-contract.spec.ts`.
+
+### Changed
+- Hardened CI, nightly, and release workflows with explicit static quality and compatibility migration gates.
+- Release workflow now verifies published package availability via npm, npx, and bunx, and verifies GitHub release metadata after publication.
+- Expanded release-readiness runtime checks to cover new release scripts, package commands, and auto-release workflow presence.
+
+## [2026.5.3] - 2026-05-03
+
+### Added
+- Added progressive `pm context` depth, section, activity, staleness, and agenda controls so agents can request brief, standard, deep, or focused project snapshots without broad list scans.
+- Added detailed CLI telemetry error classification for failed command finishes, including normalized `error_code`, `error_category`, and exit-code metadata for telemetry and local OTLP spans.
+- Added regression coverage for bootstrap argument parsing, telemetry classification, Sentry helper filtering, migration gates, context output, and front-matter cache behavior.
+
+### Changed
+- Decomposed `src/cli/main.ts` from ~5800 lines into modular command registration files: `register-setup.ts`, `register-list-query.ts`, `register-mutation.ts`, `register-operations.ts`, and shared `registration-helpers.ts`, reducing main.ts to ~2550 lines while preserving all command behavior and help text.
+- Centralized command argument parsing and command registration helpers to reduce CLI surface drift across help, contracts, completion, and runtime telemetry paths.
+- Centralized shared HTTP request handling for embeddings and vector-store providers, reducing duplicated semantic search transport logic.
+- Changed the built-in telemetry capture default from `max` to `redacted` so new installs preserve agent reliability diagnostics without sending local paths or personal identifiers by default.
+- Hardened CI, nightly, and release workflows around the sandboxed test harness and release readiness contracts while preserving the free GitHub Actions release path.
+
+### Fixed
+- Hardened Sentry filtering so expected handled CLI usage/validation errors are logged as structured usage signals without reopening Sentry exception groups, while unexpected failures still capture normally.
+- Hardened `pm normalize` closed-item backfill so it satisfies resolution metadata requirements without duplicating potentially sensitive `close_reason` text into new tracked fields.
+
+### Performance
+- Added persistent on-disk front-matter cache (`src/core/store/front-matter-cache.ts`) for `listAllFrontMatter` operations, using mtime+size fingerprinting for incremental refresh and context-fingerprint-based invalidation when preferred format or schema changes. Warm `list-open` drops from full-scan to ~60ms for 636-item corpora.
+
+### Security
+- Hardened telemetry and Sentry scrubbing so emails, private IPs, absolute local paths, bearer values, and inline credential assignments are redacted even when higher-detail telemetry capture is explicitly selected.
+- Redacted sensitive infrastructure details from tracked project metadata and kept production telemetry/Sentry release audit notes in the ignored private operations area.
+
+## [2026.5.2] - 2026-05-02
+
+### Changed
+- Reworked the README and public docs into progressive, agent-oriented pages with GitHub-compatible links and `pm` tracker cross-references.
+- Hardened Sentry signal quality by suppressing expected handled `PmCliError` usage/validation failures while retaining unexpected exception capture.
+- Added optional token-gated Sentry release and sourcemap upload to the free GitHub release workflow so published CLI stack traces can resolve source context when Sentry credentials are configured.
+- Updated generated GitHub release notes so closed release-tagged `pm` evidence remains visible after the release item is completed.
+
+### Security
+- Kept private operations material out of public docs and package output; local production operations artifacts remain ignored by git.
+
+## [2026.5.1-2] - 2026-05-01
+
+### Fixed
+- Pinned direct runtime and development dependency ranges instead of publishing `latest` specifiers, including `undici@^8.1.0`, so installs are deterministic and GitHub Dependabot evaluates the manifest against a non-vulnerable patched range.
+
 ## [2026.5.1] - 2026-05-01
 
 ### Fixed
@@ -37,14 +106,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Improved calendar UX ergonomics by accepting `today` for `--date`/`--from`/`--to` boundaries and by adding explicit recurrence delimiter guidance for malformed `--event` CSV payloads.
 - Improved implicit Ollama hybrid search latency by bounding semantic timeout windows and emitting deterministic warning codes when auto-defaulted semantic execution falls back to keyword mode.
 - Improved extension doctor load diagnostics with targeted warning codes and remediation hints for missing `@unbrained/pm-cli` SDK dependency resolution and ESM module-mode mismatches.
-- Improved telemetry event segmentation by adding additive `pm_version`, `source_context`, and `source_context_source` payload fields for `command_start`/`command_finish`, plus explicit override support via `PM_TELEMETRY_SOURCE_CONTEXT`.
+- Improved private diagnostics event segmentation by adding additive package/version and source-context metadata fields.
 - Improved `pm update-many` no-op validation guidance by listing actionable mutation flag examples when users provide filters/`--dry-run` without any mutation flags.
 
 - Added `pm files discover <ID>` to scan item text for existing project/global file paths, report addable vs already linked candidates, and optionally add missing linked files with `--apply`.
 - Added `pm create --comment` plain-text shorthand support so comment seeds can be passed as raw text without mandatory `text=<value>` wrappers.
 - Added ownership-safe dependency-only audit updates via `pm update --allow-audit-dep-update` / `--allow_audit_dep_update` for append-only non-owner `--dep` additions.
 - Added cache cleanup safety controls on `pm gc`: `--dry-run`, repeatable/comma-delimited `--scope index|embeddings|runtime`, and deterministic `guidance` output (including reindex hints after search-artifact cleanup).
-- Added linked-test PM-context ergonomics flags `--check-context` and `--auto-pm-context` for `pm test --run` and `pm test-all`, including preflight summary warnings and run-level execution-context telemetry (`requested_pm_context_mode`, `auto_pm_context_applied`).
+- Added linked-test PM-context ergonomics flags `--check-context` and `--auto-pm-context` for `pm test --run` and `pm test-all`, including preflight summary warnings and run-level execution-context metadata (`requested_pm_context_mode`, `auto_pm_context_applied`).
 - Added hardened background-run attribution fallback for `requested_by` in `pm test-runs` metadata: explicit author -> `PM_AUTHOR` -> settings author default -> `USER`/`LOGNAME`/`USERNAME` -> OS username -> `unknown`.
 - Added contract/completion alias parity improvements: `pm contracts` now publishes canonical flag + alias metadata for command surfaces, and generated completion scripts include accepted alias candidates from the shared contract registry.
 - Added extension lifecycle flag-forwarding parity so subcommand forms (`pm extension manage ...`, `pm extension doctor ...`) honor the same action flags as top-level action forms.
@@ -164,7 +233,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added per-linked-test runtime directives in linked test metadata (`env_set`, `env_clear`, `shared_host_safe`) for deterministic command-level execution control.
 - Added linked-test PM-context and strict-governance controls: `--pm-context schema|tracker|auto`, `--fail-on-context-mismatch`, `--fail-on-skipped`, `--fail-on-empty-test-run`, and `--require-assertions-for-pm` on `pm test --run` and `pm test-all`.
 - Added linked-test PM-context auto-routing (`--pm-context auto`) and per-linked-test context override metadata (`pm_context_mode=schema|tracker|auto`) for mixed-mode linked test execution.
-- Added linked-test assertion metadata support (`assert_stdout_contains`, `assert_stdout_regex`, `assert_stderr_contains`, `assert_stderr_regex`, `assert_stdout_min_lines`, `assert_json_field_equals`, `assert_json_field_gte`) with deterministic assertion-failure classification and per-run `execution_context` telemetry in `run_results`.
+- Added linked-test assertion metadata support (`assert_stdout_contains`, `assert_stdout_regex`, `assert_stderr_contains`, `assert_stderr_regex`, `assert_stdout_min_lines`, `assert_json_field_equals`, `assert_json_field_gte`) with deterministic assertion-failure classification and per-run `execution_context` metadata in `run_results`.
 - Added structured linked-test failure classification in `run_results` (`failure_category`) and aggregated `failure_categories` totals in `pm test`/`pm test-all` results for triage (`infra_collision` vs `assertion_failure` and related categories).
 - Added standalone `pm validate` linked command-reference diagnostics (`command_references`) with default-on stale PM-id detection and dedicated warning token (`validate_command_references_stale_pm_ids:<count>`).
 - Added default-on resolution remediation command hints in `pm validate` details for missing resolution metadata (`resolution`, `expected_result`, `actual_result`).
@@ -202,7 +271,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `pm contracts --command <name>` now scopes action/command/availability output to the selected command for lower-noise machine payloads; use no `--command` filter for full corpus output.
 - Mutation-triggered search cache invalidation now covers linked-test run-tracking paths (`pm test --run`, `pm test-all`) and lifecycle alias mutation flows.
 - Calendar JSON/markdown summaries now expose deterministic aggregate breakdowns (`by_kind`, `by_type`, `by_status`, `recurring_events`) and markdown event lines now include richer metadata tokens (item type, recurrence rule, end-time projection, timezone/location, and description context).
-- Command-aware output summaries now consume the canonical calendar `summary.events` structure (instead of stale `summary.total`) and emit richer calendar highlight telemetry (`events`, `deadlines`, `reminders`, `scheduled`, `view`).
+- Command-aware output summaries now consume the canonical calendar `summary.events` structure (instead of stale `summary.total`) and emit richer calendar highlight metadata (`events`, `deadlines`, `reminders`, `scheduled`, `view`).
 - Mutation parsing errors for entry-style flags now include actionable format guidance and explicit stdin-token usage hints to reduce malformed-input retries.
 - `pm create` log-seed repeatables (`--comment`, `--note`, `--learning`) now reject parsed unsupported keys to prevent silent narrative truncation when unquoted comma segments resemble key/value tokens; guidance now explicitly routes punctuation-heavy text to quoted `text=...`, markdown key/value input, or stdin token usage.
 - Type validation/filtering/completion now resolve from the runtime registry across create/update/list/search/calendar/completion/init/health/storage paths while preserving built-in defaults when no custom type config exists.

package/CONTRIBUTING.md

@@ -95,11 +95,16 @@ Behavior expectations to preserve:
 
 ## Developer Documentation
 
-For deeper context on implementation and extension development:
+Start with the [documentation index](docs/README.md). Focused pages:
 
-- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — source tree, item storage, mutation contract, history/restore, search, and testing internals.
-- [docs/EXTENSIONS.md](docs/EXTENSIONS.md) — full extension development guide: manifest format, ExtensionApi reference, lifecycle hooks, and a working example.
-- [docs/RELEASING.md](docs/RELEASING.md) — maintainer release procedure for calendar versioning, CI gates, npm publish, and GitHub Release automation.
+- [Quickstart](docs/QUICKSTART.md) - first repository setup and item lifecycle.
+- [Agent Guide](docs/AGENT_GUIDE.md) - canonical `pm` workflow for coding agents.
+- [Command Reference](docs/COMMANDS.md) - command families and examples.
+- [Configuration](docs/CONFIGURATION.md) - settings, output, storage, search, and validation.
+- [Testing](docs/TESTING.md) - sandbox-safe local and linked-test workflows.
+- [Architecture](docs/ARCHITECTURE.md) - source tree, storage, mutation contract, history, search, and extension host internals.
+- [Extensions](docs/EXTENSIONS.md) and [SDK](docs/SDK.md) - extension lifecycle and public SDK.
+- [Releasing](docs/RELEASING.md) - maintainer release procedure.
 
 ## Extension Development
 
@@ -139,6 +144,7 @@ When unmanaged extension state is expected to be managed, use `pm extension --do
 
 - Include focused scope and rationale.
 - Confirm all checks pass (`pnpm build && pnpm typecheck && pnpm test:coverage`).
-- Update relevant user-facing docs when behavior changes, but keep enforcement in pm data and runtime tests.
+- Update relevant user-facing docs when behavior changes, but keep enforcement in `pm` data and runtime tests.
+- Keep private operations artifacts out of tracked public docs and package output.
 - Add/maintain tests for any new behavior (100% coverage required).
 - Reference relevant `pm` item IDs in PR description.

package/PRD.md

@@ -2,7 +2,23 @@
 
 Status: Draft v1 (planning reference; pm data and runtime behavior are authoritative)
 Project: `pm` / `pm-cli`  
-Last Updated: 2026-02-19
+Last Updated: 2026-05-01
+
+## Navigation
+
+This PRD is an archival planning reference. For current user and agent documentation, use:
+
+- [README](README.md)
+- [Documentation index](docs/README.md)
+- [Agent Guide](docs/AGENT_GUIDE.md)
+- [Command Reference](docs/COMMANDS.md)
+- [Architecture](docs/ARCHITECTURE.md)
+
+Documentation refresh tracking:
+
+- [pm-3042](.agents/pm/epics/pm-3042.toon)
+- [pm-r9gu](.agents/pm/features/pm-r9gu.toon)
+- [pm-1sb2](.agents/pm/tasks/pm-1sb2.toon)
 
 ## 1) Problem Statement