@unbrained/pm-cli 2026.8.16 → 2026.8.18

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.16"
+    "version": "2026.8.18"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.16",
+      "version": "2026.8.18",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/AGENTS.md

@@ -63,8 +63,8 @@ For real repository tracking, do not override `PM_PATH`. If a script must target
 ```bash
 pm context --limit 10
 pm search "<request keywords>" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 pm create --create-mode progressive --title "..." --description "..." --type Task --status open
 pm claim <id>
 pm update <id> --status in_progress --message "Start implementation"
@@ -82,12 +82,13 @@ Author identity is automatic; use `--author` only for an explicit override.
 
 ## Working Rules
 
-- **Orient:** run `pm context`, `pm search`, `pm list-open`, and `pm list-in-progress` before `pm create`. If net-new work is required, create or reuse the parent lineage first and record duplicate-check evidence in a create-time comment.
+- **Orient:** run `pm context`, `pm search`, `pm list --status open`, and `pm list --status in_progress` before `pm create`. If net-new work is required, create or reuse the parent lineage first and record duplicate-check evidence in a create-time comment.
 - **Verify before you claim:** the verification recipe for the Non-Negotiable above. A `closed` item whose `resolution`/`close_reason` describes the fix represents completed, shipped work — never describe it as outstanding. Confirm release/CI/infra status against the live system, e.g. `pm get pm-9gxi`, `npm view @unbrained/pm-cli version`, `gh release list`, `gh run list --workflow=auto-release.yml`.
 - **Implement:** keep edits scoped to the claimed item. Link changed files with `pm files`, docs with `pm docs`, and runnable verification with `pm test`.
 - **Record:** use `pm comments`, `pm notes`, and `pm learnings` for progress, rationale, and durable lessons. Prefer append-style updates over rewriting item content.
 - **Verify:** use sandbox-safe commands. For documentation-only work, run at least `pnpm build` and a focused link/content check. For broader work, run linked tests, coverage, validation, and release gates as appropriate.
 - **Close:** add evidence first, then `pm close <id> "<reason>" --validate-close warn`, then `pm release <id>`.
+- **Land closeout through review:** tracker evidence, item closure, and the generated changelog are part of the reviewed delivery. Never push post-merge closeout commits directly to `main`; if evidence depends on the merge SHA, carry it in a normal `main`-based follow-up PR so the new head retains analyzer provenance. See [Releasing](docs/RELEASING.md#reviewed-delivery-closeout).
 
 ## Test Safety
 

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 2026.8.18 - 2026-08-18
+
+### Added
+
+- Alias shim layer: config-aware hidden aliases with one-line migration hints (foundation for all consolidations) ([pm-0z7n](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-0z7n.toon))
+
+### Fixed
+
+- A commit pushed directly to the default branch can never be released: both analyzer-evidence fallbacks presuppose a pull request, and nothing declares that precondition ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
+- GH-1052: typed fail-closed whole-list SDK primitive ([pm-y4aaol](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y4aaol.toon))
+- Packed Bun SDK import fails on node:module stripTypeScriptTypes ([pm-ikj8ve](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ikj8ve.toon))
+- GH-1051: package catalog rejects universal output-budget controls ([pm-2firut](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2firut.toon))
+- Bun event streaming falls back to authoritative history without node:sqlite ([pm-b8hwfr](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-b8hwfr.toon))
+- Surface replication gate scopes trigger activation to relevant diff content ([pm-mrhwow](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mrhwow.toon))
+- CodeQL: remove generated-code artifact path interpolation from exporter integration harness ([pm-ozxkm2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ozxkm2.toon))
+- Exporter artifact-channel contract: clean stdout, bounded receipts, and binary-safe streaming ([pm-dilou2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dilou2.toon))
+- GH-1048: Windows Node 24 numeric EDQUOT fixtures construct NaN on platforms that do not declare that errno ([pm-y4kovm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y4kovm.toon))
+- Queued daily releases recognize an already-published same-day release before analyzer provenance ([pm-dm2vfz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dm2vfz.toon))
+
+### Security
+
+- Adopt Dependabot PR \#1046 pinned CodeQL 4.37.7 and TruffleHog 3.97.0 refresh ([pm-pp6al9](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-pp6al9.toon))
+
+### Deprecated
+
+- ADR: noun-verb CLI grammar — accepted consolidation principles and alias-preserving deprecation policy ([pm-pbyu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-pbyu.toon))
+
+### Other
+
+- Command-grammar conformance gate: the noun-verb table and shared verb vocabulary become machine-checked contracts a non-conforming command cannot pass ([pm-wt43zj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-wt43zj.toon))
+- Consolidate the 8 list-\* status variants into pm list --status (list-all/open/draft/in-progress/blocked/closed/canceled become hidden aliases) ([pm-pfqi](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-pfqi.toon))
+- Command-destination census: 14 of 76 canonical commands have no declared home in the target grammar, so the surface can be frozen with its shape still undecided ([pm-yy8rmx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-yy8rmx.toon))
+- Half of the pm events payload is per-row resume cursors an agent never reads: 48 percent of stream bytes buy a capability consumed once per batch ([pm-ez1dfg](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-ez1dfg.toon))
+
+## 2026.8.17 - 2026-08-17
+
+### Added
+
+- History-derived defect recurrence gate: turn resolved incident patterns into targeted local and hosted CI protections ([pm-1qkivy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-1qkivy.toon))
+- Agent skills routed to a workflow loop but named no capability family and no read-cost, so four of twelve command families and the entire output-budget surface were unreachable through progressive disclosure ([pm-f6zjpq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-f6zjpq.toon))
+
+### Fixed
+
+- Linked tests retain high-volume Vitest output without aborting ([pm-giks4s](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-giks4s.toon))
+- A declared context intent returns no context when combined with the narrowing flag, and its refusal receipt reports 122 tokens against a 2400 budget as the reason it does not fit ([pm-3crymx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-3crymx.toon))
+- The relationship lexicon cannot express recurrence, so a defect family fixed thirty times is thirty unrelated nodes to every graph algorithm ([pm-ouyq3n](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ouyq3n.toon))
+- The gate contributors run before merging fails on every Claude Code workstation and passes on the runner for the same tree, because a harness probe writes advisory warnings into the surface the token budget measures ([pm-95h7pg](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-95h7pg.toon))
+- The public-surface gate enumerates its own hand-written entrypoint list, so two published code exports ship ungoverned and ./cli publishes 86 internal functions as typed API ([pm-suhxny](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-suhxny.toon))
+- GH-1033: read fields selectors can erase identity and requested empty collections ([pm-4fwgaz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-4fwgaz.toon))
+- GH-1036/GH-1040: history integrity verdicts and repairs are incompatible across supported CLI versions ([pm-0wfdim](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-0wfdim.toon))
+- GH-1032: extension manifests silently accept unenforced version-floor spellings ([pm-qqoumq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qqoumq.toon))
+- GH-1038: docs linked-resource pair syntax corrupts URLs and splits labeled entries ([pm-fpdk37](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-fpdk37.toon))
+- GH-1039: graph impact discards dependency direction and makes the direction selector inert ([pm-jn1x30](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-jn1x30.toon))
+
+### Other
+
+- Decision: adopt reviewed defect-evidence field constraints into audited workspace history ([pm-4smp5b](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-4smp5b.toon))
+- Defect-escape ratchet: every escaped defect must land a gate that would have caught it, tracked as evidence on the fixing item ([pm-rtn5h6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-rtn5h6.toon))
+- Boundary-fixture gate: every value that must match a system outside this repository is tested against a captured real sample, never against a fixture the production code generated ([pm-0pzgit](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-0pzgit.toon))
+- Disposition the test-only escape hatch published through the ./cli entrypoint: 86 internal functions are consumer-visible API with no support intent ([pm-rf120g](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-rf120g.toon))
+
 ## 2026.8.16 - 2026-08-16
 
 ### Fixed
@@ -10,7 +71,6 @@
 - GH-1028: history-author-acknowledge bulk mutation lacks dry-run and misreports empty selection ([pm-mcxk8v](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mcxk8v.toon))
 - GH-1030: contracts --json --full is wholly omitted by the default output budget ([pm-2qvq7a](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2qvq7a.toon))
 - Auto Release blocker closure ignores successful recovery dispatch and reruns the stale tag-push workflow ([pm-db8onn](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-db8onn.toon))
-- A commit pushed directly to the default branch can never be released: both analyzer-evidence fallbacks presuppose a pull request, and nothing declares that precondition ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
 
 ### Other
 
@@ -25,7 +85,6 @@
 - Provide an audited repair and severity-migration contract for legacy invalid provenance ([pm-76fkpp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-76fkpp.toon))
 - Detect extension-host pm-cli version skew before a workspace reports healthy ([pm-643e0k](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-643e0k.toon))
 - Restore strict unknown-key parity for docs linked-artifact additions ([pm-22rzjp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-22rzjp.toon))
-- Surface replication gate scopes trigger activation to relevant diff content ([pm-mrhwow](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mrhwow.toon))
 - Make every failing health verdict self-indexing and attach gate severity to findings ([pm-larv4r](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-larv4r.toon))
 - GH-1004: history-repair remains writer-version-specific across 2026.8.7 and 2026.8.13 ([pm-igdvfq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-igdvfq.toon))
 - Assurance gates preserve zero-valued counts and report actionable source failures ([pm-xmmafu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xmmafu.toon))
@@ -942,10 +1001,10 @@
 
 ### Fixed
 
+- Sentry no longer captures deliberate Ctrl+C/Ctrl+D interrupts as error-level events (AbortError, PM-CLI-27) ([pm-ksv2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ksv2.toon))
 - pm get --full omits children for Plan parents while pm list --parent returns them ([pm-y4z5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y4z5.toon))
 - Intentional package CommandError outcomes create high-severity Sentry issues (PM-CLI-16) ([pm-7071](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7071.toon))
 - Extension install self-copy guard: reject source-inside-destination layouts before fs.cp EINVAL (PM-CLI-28) ([pm-8myl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-8myl.toon))
-- Sentry captures deliberate Ctrl+C interrupts as error-level events (AbortError, PM-CLI-27) ([pm-ksv2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ksv2.toon))
 - Torn-install bundle transients block scheduled releases: boot-time chunk-integrity self-check + distinct error code for gate classification ([pm-wfvq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wfvq.toon))
 - GH-446: pm get omits schedule facet (events/start_at/end_at/location) for Meeting/Event/Reminder ([pm-x1g5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-x1g5.toon))
 - GH-533: create/update accept empty --title — required-title contract inconsistent between omitted and empty string ([pm-7je0](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7je0.toon))
@@ -1269,12 +1328,12 @@
 
 ### Fixed
 
+- GH-363: Windows nightly (Node 24) red — runtime-loader colon-path + telemetry detached-spawn unhandled error + npm-install regression ([pm-xaib](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xaib.toon))
 - pm validate --check-files mis-handles remote (URL) doc/file references: flagged as deleted and silently destroyed by --prune-missing ([pm-k2n4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-k2n4.toon))
 - pm next hides completed-container closeout rows while leaf work exists ([pm-9g87](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-9g87.toon))
 - MCP action-schema contracts drifted from CLI flag tables (guide.list, health.brief, validate.parentCycleSeverity, contracts.full) ([pm-zx13](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-zx13.toon))
 - describeExtensionBlueprint omits importer/exporter-with-options command definitions (parity gap vs describeExtensionActivation) ([pm-zqes](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-zqes.toon))
 - Contracts command lookup should handle package namespace roots ([pm-y1o4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y1o4.toon))
-- GH-363: Windows nightly (Node 24) red — runtime-loader colon-path + telemetry detached-spawn unhandled error + npm-install regression ([pm-xaib](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xaib.toon))
 - CI: make Codecov badge uploads branch-explicit ([pm-x878](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-x878.toon))
 - deriveExtensionCapabilities omits 'schema' for importer/exporter options.flags (declarative blueprint under-grant) ([pm-v3ty](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-v3ty.toon))
 - pm install does not scaffold extension-contributed item-type folders (transient missing_directory health warning) ([pm-rjab](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-rjab.toon))
@@ -1502,6 +1561,7 @@
 
 ### Fixed
 
+- PR \#266 review feedback: tighten init and dynamic option validation ([pm-at1j](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-at1j.toon))
 - pm templates: unknown subcommand + flags silently fall back to 'list' (exit 0) instead of erroring ([pm-r2kd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-r2kd.toon))
 - linked-test-adapters package install loses ESM module type ([pm-v8fy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-v8fy.toon))
 - GH-215: enforce timestamps in history entries ([pm-u42x](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u42x.toon))
@@ -1511,7 +1571,6 @@
 - GH-262: prevent path-like pm init from corrupting caller tracker settings ([pm-jek2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-jek2.toon))
 - GH-284: align pm init required schema directories with health ([pm-hl9y](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-hl9y.toon))
 - CI contracts snapshot temp cleanup can fail with ENOTEMPTY ([pm-c61g](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-c61g.toon))
-- PR \#266 review feedback: tighten init and dynamic option validation ([pm-at1j](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-at1j.toon))
 - GH-265: schema unknown subcommands must not create custom types ([pm-ablm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ablm.toon))
 - GH-280: pm validate does not detect circular parent references (hierarchy cycles A-\>B-\>A of any length) ([pm-8vul](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-8vul.toon))
 - Auto Release retries branch push after main advances ([pm-5oti](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-5oti.toon))
@@ -2709,6 +2768,7 @@
 
 ### Security
 
+- Ignore local .env files for telemetry/security operations ([pm-qgvj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qgvj.toon))
 - Track GitHub Dependabot alert \#8 for undici (GHSA-wqq4-5wpv-mx2g) ([pm-v6vi](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-v6vi.toon))
 - Track GitHub Dependabot alert \#11 for undici (GHSA-9qxr-qj54-h672) ([pm-tl4d](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-tl4d.toon))
 - Track GitHub Dependabot alert \#12 for undici (GHSA-cxrh-j4jr-qwg3) ([pm-pagj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-pagj.toon))
@@ -2729,7 +2789,6 @@
 - Track GitHub Dependabot alert \#27 for undici (GHSA-4992-7rv2-5pvq) ([pm-02c4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-02c4.toon))
 - Issue: Private IP address in committed pm task files ([pm-xk8b](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xk8b.toon))
 - Track GitHub Dependabot alert \#19 for undici (GHSA-f269-vfmq-vjvj) ([pm-rb9v](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-rb9v.toon))
-- Ignore local .env files for telemetry/security operations ([pm-qgvj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qgvj.toon))
 - Track GitHub Dependabot alert \#22 for undici (GHSA-vrm6-8vpv-qv8q) ([pm-i1rm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-i1rm.toon))
 - Track GitHub Dependabot alert \#21 for undici (GHSA-4992-7rv2-5pvq) ([pm-cg7l](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-cg7l.toon))
 - Track GitHub Dependabot alert \#29 for picomatch (GHSA-3v7f-55p6-f55p) ([pm-5e88](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-5e88.toon))

package/README.md

@@ -21,19 +21,19 @@
 
 ## Start Here
 
-| Need                                                           | Read                                                                                                                                    |
-| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| Install and create the first item                              | [Quickstart](docs/QUICKSTART.md)                                                                                                        |
-| New maintainer onboarding                                      | [Onboarding](docs/ONBOARDING.md)                                                                                                        |
-| Agent workflow and token-minimal loops                         | [Agent Guide](docs/AGENT_GUIDE.md)                                                                                                      |
-| Command families and examples                                  | [Command Reference](docs/COMMANDS.md)                                                                                                   |
-| Shell, CI, and machine-client composition                       | [CLI Scripting Contract](docs/SCRIPTING.md)                                                                                              |
-| Settings, storage, search, and output                          | [Configuration](docs/CONFIGURATION.md)                                                                                                  |
-| Safe test execution and linked tests                           | [Testing](docs/TESTING.md)                                                                                                              |
-| Security reporting and resilience controls                    | [Security Policy](SECURITY.md), [Security Governance](docs/SECURITY_GOVERNANCE.md)                                                      |
-| Package and extension authoring                                | [Packages and Extensions](docs/EXTENSIONS.md), [SDK](docs/SDK.md), [Customization Primitives](docs/SDK_CUSTOMIZATION_PRIMITIVES.md), [Evidence Traceability](docs/SDK_EVIDENCE_TRACEABILITY.md), and [Agent Runtime Primitives](docs/AGENT_RUNTIME_PRIMITIVES.md) |
-| Maintainer release process (daily auto-release + local parity) | [Releasing](docs/RELEASING.md)                                                                                                          |
-| Contributor internals                                          | [Architecture](docs/ARCHITECTURE.md)                                                                                                    |
+| Need                                                           | Read                                                                                                                                                                                                                                                                                                                        |
+| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Install and create the first item                              | [Quickstart](docs/QUICKSTART.md)                                                                                                                                                                                                                                                                                            |
+| New maintainer onboarding                                      | [Onboarding](docs/ONBOARDING.md)                                                                                                                                                                                                                                                                                            |
+| Agent workflow and token-minimal loops                         | [Agent Guide](docs/AGENT_GUIDE.md)                                                                                                                                                                                                                                                                                          |
+| Command families and examples                                  | [Command Reference](docs/COMMANDS.md)                                                                                                                                                                                                                                                                                       |
+| Shell, CI, and machine-client composition                      | [CLI Scripting Contract](docs/SCRIPTING.md)                                                                                                                                                                                                                                                                                 |
+| Settings, storage, search, and output                          | [Configuration](docs/CONFIGURATION.md)                                                                                                                                                                                                                                                                                      |
+| Safe test execution and linked tests                           | [Testing](docs/TESTING.md)                                                                                                                                                                                                                                                                                                  |
+| Security reporting and resilience controls                     | [Security Policy](SECURITY.md), [Security Governance](docs/SECURITY_GOVERNANCE.md)                                                                                                                                                                                                                                          |
+| Package and extension authoring                                | [Packages and Extensions](docs/EXTENSIONS.md), [SDK](docs/SDK.md), [Context Integrity](docs/CONTEXT_INTEGRITY_CONTRACTS.md), [Customization Primitives](docs/SDK_CUSTOMIZATION_PRIMITIVES.md), [Evidence Traceability](docs/SDK_EVIDENCE_TRACEABILITY.md), and [Agent Runtime Primitives](docs/AGENT_RUNTIME_PRIMITIVES.md) |
+| Maintainer release process (daily auto-release + local parity) | [Releasing](docs/RELEASING.md)                                                                                                                                                                                                                                                                                              |
+| Contributor internals                                          | [Architecture](docs/ARCHITECTURE.md)                                                                                                                                                                                                                                                                                        |
 
 Full documentation starts at [docs/README.md](docs/README.md).
 
@@ -84,7 +84,7 @@ pm create \
   --ac "Restore succeeds after stale lock cleanup and has regression coverage." \
   --create-mode progressive
 
-pm list-open --limit 10
+pm list --status open --limit 10
 pm claim <item-id>
 pm update <item-id> --status in_progress --message "Start implementation"
 pm files <item-id> --add path=src/core/lock/lock.ts
@@ -102,8 +102,8 @@ Use `pm next` to get the single highest-priority ready item (and why), or `pm co
 pm next                                          # the next actionable item + rationale, ready/blocked queues
 pm context --limit 10
 pm search "keywords for the requested work" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 ```
 
 If no relevant item exists, create a parent lineage before child work, claim the child item, link changed files/docs/tests, and leave evidence comments before closing. The full workflow is in the [Agent Guide](docs/AGENT_GUIDE.md).

package/dist/cli/error-guidance.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5251395b-715a-5559-a7d5-ca3bc4a1bb16")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="763daf66-1309-50bc-8783-8c232e4d690d")}catch(e){}}();
 import { resolveRecoveryCommandName } from "../sdk/agent/command-recovery.js";
 import { renderPmCommand } from "./argv-utils.js";
 import { discoverNearbyPmRoot } from "../sdk/tracker-root-discovery.js";
@@ -483,7 +483,7 @@ function buildItemNotFoundGuidance(rawMessage, message, context) {
     const nextSteps = isPlaceholder
         ? [
             "Check that the variable holding the item ID is defined before passing it to pm.",
-            'Use "pm list-open --limit 20" to find valid IDs.',
+            'Use "pm list --status open --limit 20" to find valid IDs.',
         ]
         : ["Confirm the active --path/PM_PATH scope, then retry with a valid id."];
     return applyPmCliErrorContext(makeGuidanceMessage({
@@ -492,7 +492,10 @@ function buildItemNotFoundGuidance(rawMessage, message, context) {
         happened,
         required: "Use an existing item ID from current tracker data.",
         why: "Mutation and read commands operate only on known IDs.",
-        examples: ["pm list-open --limit 20", 'pm search "<keyword>" --limit 10'],
+        examples: [
+            "pm list --status open --limit 20",
+            'pm search "<keyword>" --limit 10',
+        ],
         nextSteps,
     }), rawMessage, context);
 }
@@ -1237,4 +1240,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=5251395b-715a-5559-a7d5-ca3bc4a1bb16
+//# debugId=763daf66-1309-50bc-8783-8c232e4d690d

package/dist/cli/public.d.ts

@@ -0,0 +1,2 @@
+/** Run one embedded CLI invocation without leaking its exit status into the host process. */
+export declare function runPmCli(rawArgv?: string[]): Promise<void>;

package/dist/cli/public.js

@@ -0,0 +1,21 @@
+/**
+ * @module cli/public
+ *
+ * Publishes the supported embeddable CLI entrypoint without exposing the
+ * implementation module's repository-only test seams to package consumers.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8e212bdf-7568-54dd-91aa-7de146d65d03")}catch(e){}}();
+import { runPmCli as runInternalPmCli } from "./main.js";
+/** Run one embedded CLI invocation without leaking its exit status into the host process. */
+export async function runPmCli(rawArgv) {
+    const previousExitCode = process.exitCode;
+    try {
+        await runInternalPmCli(rawArgv);
+    }
+    finally {
+        process.exitCode = previousExitCode;
+    }
+}
+//# sourceMappingURL=public.js.map
+//# debugId=8e212bdf-7568-54dd-91aa-7de146d65d03

package/dist/cli/register-list-query.js

@@ -1,10 +1,11 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0bcbdc33-3145-54cc-b4b6-10df50aef57a")}catch(e){}}();
-import { EXIT_CODE, PmCliError, renderRowsAsCsv, renderRowsAsTable, } from "../sdk/runtime-primitives.js";
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7bcf441b-e211-535f-9502-5624add292e5")}catch(e){}}();
+import { EXIT_CODE, PmCliError, readSettings, renderRowsAsCsv, renderRowsAsTable, resolvePmRoot, } from "../sdk/runtime-primitives.js";
+import { renderPmCommandAliasMigrationHint, resolvePmCommandAlias, } from "../sdk/cli-contracts.js";
 import { EVAL_QUERY_SET_SCHEMA_ID } from "../sdk/eval.js";
 import { applyContextIntentProjection } from "../sdk/context-intent-contracts.js";
-import { serializeNdjsonRows } from "../sdk/output.js";
-import { listMutationEvents, subscribeMutationEvents, } from "../sdk/mutation-events.js";
+import { serializeNdjsonRows, serializeNdjsonStream, } from "../sdk/output.js";
+import { listMutationEvents, subscribeMutationEventBatches, subscribeMutationEvents, } from "../sdk/mutation-events.js";
 import { runActivity } from "./commands/activity.js";
 import { runAggregate } from "./commands/aggregate.js";
 import { renderContextMarkdown, runContext, resolveContextOutputFormat, } from "./commands/context.js";
@@ -103,6 +104,14 @@ function registerContentAndGovernanceFilters(command) {
         .option("--filter-sprint-missing", "Show only items missing sprint")
         .option("--filter-release-missing", "Show only items missing release");
 }
+const CANONICAL_LIST_STATUS_VARIANTS = {
+    draft: { name: "list-draft", dependencyBlocked: false },
+    open: { name: "list-open", dependencyBlocked: false },
+    in_progress: { name: "list-in-progress", dependencyBlocked: false },
+    blocked: { name: "list-blocked", dependencyBlocked: true },
+    closed: { name: "list-closed", dependencyBlocked: false },
+    canceled: { name: "list-canceled", dependencyBlocked: false },
+};
 /** Resolve and validate the mutually exclusive list rendering modes. */
 function resolveRegisteredListOutputContext(options, globalOptions) {
     const streamMode = options.stream === true;
@@ -146,39 +155,63 @@ function renderRegisteredListResult(commandName, result, output) {
     }
 }
 async function runRegisteredListCommand(params) {
-    const globalOptions = getGlobalOptions(params.actionCommand);
+    const parsedGlobalOptions = getGlobalOptions(params.actionCommand);
+    const globalOptions = params.aliasContract
+        ? { ...parsedGlobalOptions, command: params.aliasContract.canonical }
+        : parsedGlobalOptions;
     const startedAt = Date.now();
-    if (params.options.all === true) {
-        throw new PmCliError("List --all was ambiguous and is no longer an alias for --no-truncate. Use `pm list --status all --no-truncate` for every status, or `pm list-all --no-truncate` for the dedicated all-status command.", EXIT_CODE.USAGE, {
-            code: "ambiguous_list_all",
-            examples: [
-                "pm list --status all --no-truncate",
-                "pm list-all --no-truncate",
-            ],
-        });
+    if (params.aliasContract?.lifecycle === "deprecated") {
+        const deprecationHints = await readSettings(resolvePmRoot(process.cwd(), globalOptions.path)).then((settings) => settings.ux.deprecation_hints);
+        if (deprecationHints) {
+            printError(renderPmCommandAliasMigrationHint(params.aliasContract));
+        }
     }
     const intentOptions = applyContextIntentProjection("list", params.options);
     const listOptions = normalizeListOptions(intentOptions);
-    applyDefaultListProjection(listOptions, params.name);
-    if (params.excludeTerminal)
-        listOptions.excludeTerminal = true;
-    if (params.name === "list" && listOptions.status === undefined) {
-        listOptions.status = "all";
+    let effectiveName = params.name;
+    let effectiveStatus = params.status;
+    let effectiveDependencyBlocked = params.dependencyBlocked === true;
+    let effectiveExcludeTerminal = params.excludeTerminal === true;
+    const requestedStatus = listOptions.status?.trim().toLowerCase();
+    const requestedVariant = params.name === "list" && requestedStatus !== undefined
+        ? CANONICAL_LIST_STATUS_VARIANTS[requestedStatus]
+        : undefined;
+    if (params.name === "list") {
+        if (params.options.all === true || requestedStatus === "all") {
+            effectiveName = "list-all";
+            effectiveExcludeTerminal = false;
+            listOptions.status = undefined;
+        }
+        else if (requestedStatus !== undefined && requestedVariant !== undefined) {
+            effectiveName = requestedVariant.name;
+            effectiveStatus = requestedStatus;
+            effectiveDependencyBlocked = requestedVariant.dependencyBlocked;
+            effectiveExcludeTerminal = false;
+            listOptions.status = undefined;
+        }
     }
-    listOptions.dependencyBlocked = params.dependencyBlocked;
+    applyDefaultListProjection(listOptions, effectiveName);
+    if (effectiveExcludeTerminal)
+        listOptions.excludeTerminal = true;
+    listOptions.dependencyBlocked = effectiveDependencyBlocked;
     const output = resolveRegisteredListOutputContext(intentOptions, globalOptions);
-    const result = await runList(params.dependencyBlocked ? undefined : params.status, listOptions, globalOptions);
-    renderRegisteredListResult(params.name, result, output);
+    const result = await runList(effectiveDependencyBlocked ? undefined : effectiveStatus, listOptions, globalOptions);
+    renderRegisteredListResult("list", result, output);
     if (globalOptions.profile) {
-        printError(`profile:command=${params.name} took_ms=${Date.now() - startedAt}`);
+        printError(`profile:command=list took_ms=${Date.now() - startedAt}`);
     }
 }
 function registerListCommand(program, descriptor) {
-    const { name, description, status, excludeTerminal, allowStatusFilter, dependencyBlocked, } = descriptor;
-    const command = program.command(name).description(description);
+    const { name, description, status, excludeTerminal, allowStatusFilter, dependencyBlocked, aliasContract, } = descriptor;
+    const command = program
+        .command(name, { hidden: aliasContract?.hidden === true })
+        .description(description);
     if (allowStatusFilter) {
         command.option("--status <value>", "Filter by status (repeatable or comma-separated; matches any; all selects every status)", collect);
     }
+    if (name === "list") {
+        command.option("--all", "Include every lifecycle status");
+    }
     command
         .option("--for <intent>", "Apply a declared context intent projection")
         .option("--token-budget <n>", "Override the selected intent's maximum estimated output tokens")
@@ -228,6 +261,7 @@ function registerListCommand(program, descriptor) {
             dependencyBlocked,
             options,
             actionCommand,
+            aliasContract,
         });
     });
     // Hidden pure snake_case underscore-duplicate alias (kept parse-functional).
@@ -235,7 +269,6 @@ function registerListCommand(program, descriptor) {
     addHiddenOption(command, "--assignee_filter <value>", "Alias for --assignee-filter");
     addHiddenOption(command, "--tree_depth <n>", "Alias for --tree-depth");
     addHiddenOption(command, "--token_budget <n>", "Alias for --token-budget");
-    addHiddenOption(command, "--all", "Removed ambiguous alias; emits migration guidance");
     // Singular alias so `--filter-estimate-missing` works (matches update-many spelling).
     addHiddenOption(command, "--filter-estimate-missing", "Alias for --filter-estimates-missing");
 }
@@ -411,6 +444,13 @@ function buildMutationEventOptions(options, pmRoot) {
     const harness = readRepeatableStringOption(options, "harness");
     const agentInstance = readRepeatableStringOption(options, "agentInstance");
     const provenanceFilter = readRepeatableStringOption(options, "provenanceFilter");
+    const rawCursorMode = typeof options.cursorMode === "string" ? options.cursorMode : undefined;
+    if (rawCursorMode !== undefined &&
+        rawCursorMode !== "batch" &&
+        rawCursorMode !== "row") {
+        throw new PmCliError("Events --cursor-mode must be batch or row.", EXIT_CODE.USAGE, { code: "invalid_event_cursor_mode" });
+    }
+    const cursorMode = rawCursorMode;
     return {
         pmRoot,
         since: typeof options.since === "string" ? options.since : undefined,
@@ -426,42 +466,76 @@ function buildMutationEventOptions(options, pmRoot) {
         ...(harness === undefined ? {} : { harness }),
         ...(agentInstance === undefined ? {} : { agentInstance }),
         ...(provenanceFilter === undefined ? {} : { provenanceFilter }),
+        cursorMode,
     };
 }
-async function runEventsAction(options, command) {
-    const globalOptions = getGlobalOptions(command);
-    const startedAt = Date.now();
-    const eventOptions = buildMutationEventOptions(options, globalOptions.path);
-    if (options.follow === true) {
-        if (options.provenanceSummary === true) {
-            throw new PmCliError("Events --provenance-summary is bounded to one page and cannot be combined with --follow.", EXIT_CODE.USAGE);
-        }
-        const intervalMs = typeof options.intervalMs === "string"
-            ? Number(options.intervalMs)
-            : undefined;
+/** Follows mutation events using either compatibility row cursors or the default batch-boundary trailer contract. */
+async function followMutationEvents(eventOptions, options, quiet) {
+    if (options.provenanceSummary === true) {
+        throw new PmCliError("Events --provenance-summary is bounded to one page and cannot be combined with --follow.", EXIT_CODE.USAGE);
+    }
+    const intervalMs = typeof options.intervalMs === "string"
+        ? Number(options.intervalMs)
+        : undefined;
+    if (eventOptions.cursorMode === "row") {
         for await (const event of subscribeMutationEvents({
             ...eventOptions,
             intervalMs,
         })) {
-            if (!globalOptions.quiet) {
+            if (!quiet) {
                 writeStdout(`${JSON.stringify(event)}\n`);
             }
         }
         return;
     }
+    for await (const page of subscribeMutationEventBatches({
+        ...eventOptions,
+        intervalMs,
+    })) {
+        if (!quiet) {
+            writeStdout(`${serializeNdjsonStream(page.events, {
+                count: page.count,
+                has_more: page.has_more,
+                next_cursor: page.next_cursor ?? null,
+                source: page.source,
+                heartbeat: page.count === 0,
+            })}\n`);
+        }
+    }
+}
+/** Serializes one bounded mutation-event page using its declared row or batch cursor mode. */
+function renderMutationEventPage(page) {
+    if (page.cursor_mode === "row") {
+        return serializeNdjsonRows(page.events);
+    }
+    return serializeNdjsonStream(page.events, {
+        count: page.count,
+        has_more: page.has_more,
+        next_cursor: page.next_cursor ?? null,
+        source: page.source,
+        ...(page.provenance_summary === undefined
+            ? {}
+            : { provenance_summary: page.provenance_summary }),
+    });
+}
+async function runEventsAction(options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const eventOptions = buildMutationEventOptions(options, globalOptions.path);
+    if (options.follow === true) {
+        await followMutationEvents(eventOptions, options, globalOptions.quiet === true);
+        return;
+    }
     const page = await listMutationEvents(eventOptions);
     setActiveCommandResult(page);
-    const rendered = serializeNdjsonRows([
-        ...page.events,
-        ...(page.provenance_summary === undefined
-            ? []
-            : [
-                {
-                    type: "provenance_summary",
-                    provenance_summary: page.provenance_summary,
-                },
-            ]),
-    ]);
+    if (globalOptions.json) {
+        printResult(page, globalOptions);
+        if (globalOptions.profile) {
+            printError(`profile:command=events took_ms=${Date.now() - startedAt}`);
+        }
+        return;
+    }
+    const rendered = renderMutationEventPage(page);
     if (!globalOptions.quiet && rendered.length > 0) {
         writeStdout(`${rendered}\n`);
     }
@@ -530,7 +604,7 @@ export function registerListQueryCommands(program, options) {
     const listCommandDescriptors = [
         {
             name: "list",
-            description: "List items across every lifecycle status with optional filters.",
+            description: "List active items with optional lifecycle-status and project filters.",
             excludeTerminal: true,
             allowStatusFilter: true,
         },
@@ -579,7 +653,13 @@ export function registerListQueryCommands(program, options) {
     ];
     for (const descriptor of listCommandDescriptors) {
         if (shouldRegister(descriptor.name)) {
-            registerListCommand(program, descriptor);
+            const aliasContract = resolvePmCommandAlias(descriptor.name);
+            registerListCommand(program, {
+                ...descriptor,
+                ...(aliasContract?.registration === "commander"
+                    ? { aliasContract }
+                    : {}),
+            });
         }
     }
     if (shouldRegister("aggregate")) {
@@ -775,6 +855,7 @@ export function registerListQueryCommands(program, options) {
             .option("--author <value>", "Filter by mutation author (repeatable or comma-separated)", collect)
             .option("--item <value>", "Filter by item or workspace stream id (repeatable or comma-separated)", collect)
             .option("--limit <n>", "Return at most 1,000 events (default: 100)")
+            .option("--cursor-mode <mode>", "Cursor framing: batch emits one terminal trailer (default); row preserves one cursor per event")
             .option("--full", "Include each complete authoritative history entry")
             .option("--provenance", "Include patch-free author, harness, instance, and extensible provenance")
             .option("--provenance-summary", "Include bounded provenance completeness counts")
@@ -838,4 +919,4 @@ export const _testOnlyRegisterListQuery = {
     parseListFormat,
 };
 //# sourceMappingURL=register-list-query.js.map
-//# debugId=0bcbdc33-3145-54cc-b4b6-10df50aef57a
+//# debugId=7bcf441b-e211-535f-9502-5624add292e5