@unbrained/pm-cli 2026.6.24 → 2026.7.1

package/AGENTS.md

@@ -26,6 +26,7 @@ pm guide <topic>
 ## Non-Negotiables
 
 - `pm` is the system of record. Do not edit `.agents/pm` files directly.
+- **Never claim the state of any tracked work from memory, a prior summary, or a recalled `<system-reminder>` — recalled context is frequently stale. Before stating that ANY `pm` item (or the feature/release/fix/blocker it tracks) is blocked, broken, working, or done, read its full live data — `status`, `resolution`, `close_reason`, `comments`, `history` — with `pm get <id>` / `pm comments <id>`, and cross-check the real system. Live data always wins; when it disagrees with memory, correct the stale memory.** (Verification recipe: see the "Verify before you claim" Working Rule.)
 - Every code, docs, or test change must be linked to a `pm` item with files/docs/tests and evidence comments.
 - Before creating work, search existing items and reuse the canonical lineage when possible.
 - Claim before substantial edits; release when paused, handed off, closed, or canceled.
@@ -82,6 +83,7 @@ Set `PM_AUTHOR=<stable-agent-id>` before mutations.
 ## 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.
+- **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.

package/CHANGELOG.md

@@ -1,5 +1,118 @@
 # Changelog
 
+## 2026.7.1 - 2026-07-01
+
+### Changed
+
+- CodeFactor/Complexity: decompose runCreate (CC 172) and the audit-scope update guard (CC 38) ([pm-g7vl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-g7vl.toon))
+
+### Fixed
+
+- Auto Release blocked: bot cannot push version commit to protected main (GH006, 12 required checks) ([pm-9gxi](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-9gxi.toon))
+
+### Removed
+
+- CodeFactor/Complexity: remove 33 suppressions and split 100+ complexity-point dispatch hot spots ([pm-o34s](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-o34s.toon))
+
+### Other
+
+- CodeFactor/Complexity: zero out the SDK contract-resolution, extension-loader and composition surface ([pm-lzzp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-lzzp.toon))
+- AGENTS.md: mandate reading full live pm item data (status/resolution/comments) before any state claim ([pm-g61e](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-g61e.toon))
+- CodeFactor/Complexity: cut cyclomatic-complexity debt across the extension authoring, management & diagnostics surface ([pm-zro7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-zro7.toon))
+
+## 2026.6.30 - 2026-06-30
+
+### Added
+
+- Project profile author-time validation: lintProjectProfile + assertProjectProfile + pm profile lint ([pm-j1fj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-j1fj.toon))
+- pm package/extension init --capability profile: scaffold a project-profile starter package ([pm-h2hk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-h2hk.toon))
+- Extension-contributed project profiles: api.registerProfile end-to-end ([pm-08sv](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-08sv.toon))
+- SDK test harness summary/render surface ([pm-2qte](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-2qte.toon))
+- Describe --markdown writes reference docs to a file ([pm-u2tm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-u2tm.toon))
+- SDK + CLI: render extension/package surfaces to Markdown reference docs (renderExtensionSurfaceMarkdown + describe --markdown) ([pm-dmum](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-dmum.toon))
+- First-party baseline profile package built on public SDK primitives ([pm-a7o4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-a7o4.toon))
+- Project profile presets: compose types, statuses, fields, workflows, templates, and packages ([pm-v37g](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-v37g.toon))
+- Add pm package / pm packages shell completion (bash/zsh/fish), including the package-only --declarative flag ([pm-mthy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-mthy.toon))
+- pm package init --declarative: scaffold a composeExtension blueprint starter + author-time preflight test ([pm-8mxg](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-8mxg.toon))
+- pm next: recommend the next actionable (unblocked, ready) work item with rationale + blocked companion ([pm-nj90](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-nj90.toon))
+- Complete scaffold capability matrix: --capability renderers/parser/preflight/services starters ([pm-i5p5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-i5p5.toon))
+- pm package/extension init --capability schema: scaffold custom item type/field/migration starter ([pm-d1ig](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-d1ig.toon))
+- Scaffolded & authored command-bearing extensions reliably activate for their own commands ([pm-yxb5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-yxb5.toon))
+- TypeScript-only extension loading: ship .ts entry, load via Node native type stripping (no compiled .js) ([pm-2p7a](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-2p7a.toon))
+
+### Changed
+
+- CodeFactor/Duplication: remove duplicated code blocks (×20: 2 Critical, 3 Major, 15 Minor) ([pm-fmjy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-fmjy.toon))
+- CodeFactor/Complexity: reduce cyclomatic complexity (×152: 3 Critical, 7 High, 142 Moderate) ([pm-arzz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-arzz.toon))
+- ADR: pm extensions are authored AND loaded as TypeScript via Node native type stripping ([pm-m1uz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-m1uz.toon))
+
+### Fixed
+
+- CodeFactor no-regression gate: complexity ceiling + ESLint suppressions baseline + Greptile in local CI/CD ([pm-bkcv](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-bkcv.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))
+- 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))
+- Windows background stop progress assertion ([pm-bnh3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bnh3.toon))
+- GH-348/GH-376: Windows nightly Vitest worker fork exits unexpectedly after passing tests ([pm-2kkl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2kkl.toon))
+- CodeFactor/Maintainability: fix unsafe optional chaining (no-unsafe-optional-chaining ×25) ([pm-m8yl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-m8yl.toon))
+- CI: make Codecov badge uploads branch-explicit ([pm-x878](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-x878.toon))
+- pm next should skip completed open containers when recommending actionable work ([pm-2n6i](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2n6i.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 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))
+- 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))
+- Auto Release blocked-alert step can never create its tracking issue (auto-release.yml missing issues:write) ([pm-qawd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qawd.toon))
+- Sentry PM-CLI-1T: pm stats should tolerate disappearing history streams ([pm-7o0s](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7o0s.toon))
+- Aggregate --status all should match duplicate-safe lifecycle filters ([pm-bhtx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bhtx.toon))
+- Package lifecycle typo recovery should suggest action subcommands ([pm-js02](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-js02.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))
+- 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 package doctor should warn when a schema package registers item types/fields but declares narrow activation.commands (silently non-global) ([pm-ok47](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ok47.toon))
+- Scaffolded search/importers package commands fail to dispatch: lazy-activation probe skips command-bearing extensions that omit activation.commands ([pm-nacb](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-nacb.toon))
+- Harden extensionNeedsActivationForProbe: non-terminal search gate + command-bearing importers ([pm-b5r8](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-b5r8.toon))
+
+### Removed
+
+- CodeFactor/Maintainability: remove useless object-spread fallbacks (unicorn/no-useless-fallback-in-spread ×57) ([pm-xsth](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-xsth.toon))
+
+### Other
+
+- PR \#406 review follow-up: clear partial MCP extension registries before fallback execution ([pm-dyzy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-dyzy.toon))
+- Built-in MCP actions are now extension-aware: pm_profile/pm_list/pm_schema activate workspace extensions like the CLI ([pm-zumn](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-zumn.toon))
+- ADR: profile lint severity model — errors break apply, warnings flag suspicious-but-valid cross-references ([pm-qcdu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-qcdu.toon))
+- Action-scoped MCP parameter descriptions: split shared name/target description per action (schema vs profile) ([pm-fq80](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-fq80.toon))
+- Dogfood: pm-kanban registers kanbanProfile so pm profile apply kanban works ([pm-kj7x](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-kj7x.toon))
+- Docs: SDK.md/EXTENSIONS.md document api.registerProfile + regenerate contracts/full.json ([pm-ol8j](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-ol8j.toon))
+- pm profile list/show/apply merges extension-registered profiles with source labels ([pm-vpwt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-vpwt.toon))
+- registerProfile core registration surface: ExtensionApi + registry + loader gate + capability-usage + policy surface ([pm-6oox](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-6oox.toon))
+- SDK profile parity: assertRegisteredProfile + composeExtension blueprint.profiles + deriveExtensionCapabilities + describe ([pm-l8fl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-l8fl.toon))
+- Decompose cli-contracts.ts monolith into flag-contracts + tool-schema sibling modules ([pm-3wue](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-3wue.toon))
+- First-party package manifests declare current SDK compatibility floor ([pm-6d7q](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-6d7q.toon))
+- Package scaffolds declare current SDK compatibility floor ([pm-sf08](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-sf08.toon))
+- Refresh Sentry release and telemetry dependencies ([pm-4dz7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-4dz7.toon))
+- CodeFactor parity tooling: local ESLint (unicorn) + complexity + duplication lint to reproduce findings and prevent regressions ([pm-6sqo](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-6sqo.toon))
+- CodeFactor/Maintainability: clear remaining unicorn lints (no-thenable ×4, no-useless-spread ×2, no-useless-length-check ×1) ([pm-q0ye](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-q0ye.toon))
+- ADR: offline BM25 lexical provider + relevance eval harness for search quality ([pm-f2al](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-f2al.toon))
+- ADR: explicit pm_format_version front-matter field for storage schema evolution ([pm-eeai](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-eeai.toon))
+- Normalize stale audit containers and intentional-open resolved items ([pm-psc0](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-psc0.toon))
+- Expose project profile application through MCP contracts and drift gates ([pm-bhmk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-bhmk.toon))
+- 2026-06-25 PM ecosystem taxonomy and context backlog normalization ([pm-57vh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/plans/pm-57vh.toon))
+- Sub-agent lane: source, tests, docs, and command-surface coverage map ([pm-xezi](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-xezi.toon))
+- Sub-agent lane: tracker taxonomy, hierarchy, and duplicate hygiene ([pm-klpw](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-klpw.toon))
+- Sub-agent lane: release, GitHub, Sentry, telemetry, and live-ops evidence ([pm-3whx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-3whx.toon))
+- Sub-agent lane: SDK, packages, MCP, and universal customization backlog ([pm-o578](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-o578.toon))
+- Refresh runtime dependencies for audit baseline ([pm-r642](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-r642.toon))
+- Extend pm package init --declarative to the full capability matrix (hooks/search/importers/schema/renderers/parser/preflight/services) ([pm-lfdv](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-lfdv.toon))
+- ADR: dependency-aware actionability for pm next — ready = active leaf with no open blocked_by; reuse compareCriticalItems + shared blocked_by resolver ([pm-9x6k](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-9x6k.toon))
+- Schema-capability scaffolds must omit narrow activation.commands so custom item types/fields register globally ([pm-halx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-halx.toon))
+- Schema scaffold docs: EXTENSIONS.md, SDK.md, shell completion, help-content examples ([pm-pwf1](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-pwf1.toon))
+- Schema scaffold tests: unit coverage (package+extension variants) + materialize/run generated node:test smoke ([pm-x3vi](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-x3vi.toon))
+- Implement schema scaffold capability in scaffold.ts (manifest/entrypoint/README/define\* guidance, omit activation.commands) ([pm-mdw6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-mdw6.toon))
+- Document activation.commands lazy-activation contract in scaffold README, EXTENSIONS.md, SDK.md ([pm-scvz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-scvz.toon))
+- Scaffold emits manifest activation.commands matching registered command paths per capability ([pm-mhih](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-mhih.toon))
+- Scaffolder emits TypeScript source: index.ts + tsconfig.json + type-check/test scripts (./index.ts entry) ([pm-frou](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-frou.toon))
+- Convert docs/examples extensions to TypeScript-first (starter-extension, policy-restricted-extension) ([pm-ax7z](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-ax7z.toon))
+- ADR: pm extensions & SDK packages must be authored fully in TypeScript ([pm-2c28](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-2c28.toon))
+
 ## 2026.6.24 - 2026-06-24
 
 ### Added
@@ -17,7 +130,6 @@
 ### Other
 
 - Reframe SDK docs & docstrings TypeScript-first (SDK.md, EXTENSIONS.md, define\*/compose\*) ([pm-l2ud](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-l2ud.toon))
-- Scaffolder emits TypeScript: index.ts + tsconfig.json + build script, compiled ./index.js entry ([pm-frou](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-frou.toon))
 - defineExtensionBlueprint: typed identity helper for partial blueprint fragments ([pm-nvgy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-nvgy.toon))
 - composeExtensionPackage: author-once capstone returning { module, manifest } ([pm-cn0c](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-cn0c.toon))
 - mergeExtensionBlueprints: pure modular composition of partial ExtensionBlueprints ([pm-high](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-high.toon))

package/CONTRIBUTING.md

@@ -74,6 +74,36 @@ When changing validation behavior, include targeted checks for:
 - `pm validate --check-files --scan-mode tracked-all`
 - `pm validate --check-files --scan-mode tracked-all-strict`
 
+## Code Quality Gates (no regressions)
+
+Every change must *only improve* the codebase — CI blocks any pull request that
+introduces a new quality issue. Run the lint suite before pushing:
+
+```bash
+pnpm lint           # eslint (complexity + maintainability) + jscpd duplication + static-quality gate
+```
+
+**Complex Method no-regression gate.** ESLint enforces a cyclomatic-complexity
+ceiling (`complexity` max 17 — a function at CC ≥ 18 fails), calibrated to
+CodeFactor's "Complex Method" detector. The full set of pre-existing violations is
+grandfathered in `eslint-suppressions.json` (ESLint native bulk suppressions), so:
+
+- A **new** complex method (or making an existing one worse) fails `pnpm lint` in
+  CI — you must simplify it.
+- **Fixing** a complex method makes its suppression unused, which also fails lint
+  until you prune the baseline. Run `pnpm lint:eslint:prune` and commit the smaller
+  `eslint-suppressions.json` — the baseline only ever shrinks.
+
+Do not regenerate the whole baseline (`pnpm lint:complexity:baseline`) to silence a
+new violation; that defeats the gate. Driving the baseline to empty is the path to a
+CodeFactor **A+** (tracked under epic `pm-92if`).
+
+**Greptile review.** `pnpm review:greptile:gate` runs the Greptile CLI reviewer over
+the current branch and fails on findings. It is wired into `pnpm release:gates`
+(skip with `--skip-greptile`) and skips gracefully when the Greptile CLI is
+unavailable or unauthenticated, so token-less CI never blocks on it; the Greptile
+GitHub App still reviews every PR independently.
+
 ## Terminal Compatibility Checks
 
 When changing stdin, output, exit handling, or linked test execution, run targeted terminal-compatibility regressions before full-suite validation:

package/README.md

@@ -1,10 +1,22 @@
 # pm-cli (`pm`)
 
 [![CI](https://github.com/unbraind/pm-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/unbraind/pm-cli/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/unbraind/pm-cli/branch/main/graph/badge.svg)](https://codecov.io/gh/unbraind/pm-cli)
+[![CodeFactor](https://www.codefactor.io/repository/github/unbraind/pm-cli/badge)](https://www.codefactor.io/repository/github/unbraind/pm-cli)
 [![npm version](https://img.shields.io/npm/v/%40unbrained%2Fpm-cli)](https://www.npmjs.com/package/%40unbrained%2Fpm-cli)
-[![Node >=20](https://img.shields.io/node/v/%40unbrained%2Fpm-cli)](https://nodejs.org)
+[![Node >=22.18](https://img.shields.io/node/v/%40unbrained%2Fpm-cli)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
+[![pm total](https://pm-cli.unbrained.dev/badges/svg?repo=unbraind/pm-cli&metric=items&style=flat&rt=2)](https://pm-cli.unbrained.dev/badges)
+[![pm open](https://pm-cli.unbrained.dev/badges/svg?repo=unbraind/pm-cli&metric=status&status=open&style=flat&rt=2)](https://pm-cli.unbrained.dev/badges)
+[![pm in progress](https://pm-cli.unbrained.dev/badges/svg?repo=unbraind/pm-cli&metric=status&status=in_progress&style=flat&rt=2)](https://pm-cli.unbrained.dev/badges)
+[![pm blocked](https://pm-cli.unbrained.dev/badges/svg?repo=unbraind/pm-cli&metric=status&status=blocked&style=flat&rt=2)](https://pm-cli.unbrained.dev/badges)
+[![pm canceled](https://pm-cli.unbrained.dev/badges/svg?repo=unbraind/pm-cli&metric=status&status=canceled&style=flat&rt=2)](https://pm-cli.unbrained.dev/badges)
+[![pm closed](https://pm-cli.unbrained.dev/badges/svg?repo=unbraind/pm-cli&metric=closed&style=flat&rt=2)](https://pm-cli.unbrained.dev/badges)
+[![pm completion](https://pm-cli.unbrained.dev/badges/svg?repo=unbraind/pm-cli&metric=completion&style=flat&rt=2)](https://pm-cli.unbrained.dev/badges)
+[![pm last activity](https://pm-cli.unbrained.dev/badges/svg?repo=unbraind/pm-cli&metric=last-activity&style=flat&rt=2)](https://pm-cli.unbrained.dev/badges)
+[![pm history events](https://pm-cli.unbrained.dev/badges/svg?repo=unbraind/pm-cli&metric=history-events&style=flat&rt=2)](https://pm-cli.unbrained.dev/badges)
+
 `pm` is a git-native project management CLI for humans and coding agents. It stores work items in reviewable repository files, records every mutation in append-only history, and defaults to sparse TOON output so agents can spend fewer tokens while still getting deterministic data.
 
 ## Start Here
@@ -29,7 +41,7 @@ For optional in-terminal docs routing, use the canonical [guide topic map](docs/
 
 ## Install
 
-`pm-cli` requires Node.js 20 or newer.
+`pm-cli` requires Node.js 22.18 or newer (extensions and packages are authored and loaded as TypeScript via Node's native type stripping, so no compiled `.js` is shipped or committed).
 
 ```bash
 npm install -g @unbrained/pm-cli
@@ -92,9 +104,10 @@ pm release <item-id>
 
 ## Agent Loop
 
-Use `pm context` first, then search before creating anything:
+Use `pm next` to get the single highest-priority ready item (and why), or `pm context` for the full snapshot, then search before creating anything:
 
 ```bash
+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

package/dist/cli/bootstrap-args.js

@@ -4,7 +4,7 @@
  * Provides CLI runtime support for Bootstrap Args.
  */
 
-!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]="df81f91f-ed92-5511-b34c-ea7c1b81230b")}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]="ddf0b427-0fb3-5cf1-99ef-177bf6530e4e")}catch(e){}}();
 import { resolveSubcommandFlagContractsForCommand } from "../sdk/cli-contracts.js";
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
 function parseBootstrapPathToken(token, next) {
@@ -504,6 +504,82 @@ function splitCanonicalListToken(token) {
         inlineValue: token.slice(equalsIndex + 1),
     };
 }
+function copyValueConsumingFlag(argv, index, result) {
+    result.push(argv[index]);
+    const next = argv[index + 1];
+    if (typeof next === "string" && next !== "--") {
+        result.push(next);
+        return index + 2;
+    }
+    return index + 1;
+}
+function readListFlagOccurrence(argv, index, parsed, multiValueListFlags) {
+    if (parsed.inlineValue !== undefined) {
+        return {
+            originalTokens: [argv[index]],
+            value: parsed.inlineValue,
+            consumed: 1,
+        };
+    }
+    const values = [];
+    let valueIndex = index + 1;
+    while (valueIndex < argv.length &&
+        argv[valueIndex] !== "--" &&
+        !argv[valueIndex].startsWith("-") &&
+        (values.length === 0 || multiValueListFlags.has(parsed.flag))) {
+        values.push(argv[valueIndex]);
+        valueIndex += 1;
+    }
+    const consumed = values.length === 0 ? 1 : 1 + values.length;
+    return {
+        originalTokens: argv.slice(index, index + consumed),
+        value: values.length === 0 ? undefined : values.join(","),
+        consumed,
+    };
+}
+function recordListFlagOccurrence(slots, result, flag, occurrence) {
+    const existing = slots.get(flag);
+    if (existing) {
+        existing.values.push(occurrence.value);
+        existing.occurrences += 1;
+        return;
+    }
+    slots.set(flag, {
+        outputIndex: result.length,
+        originalTokens: occurrence.originalTokens,
+        values: [occurrence.value],
+        occurrences: 1,
+    });
+    // Reserve the anchor position; finalized after the walk so we know the full
+    // merged value or can restore the original token form for single uses.
+    result.push(null);
+}
+function buildListFlagCoalescingSplices(slots, multiValueListFlags) {
+    const events = [];
+    const splices = [];
+    for (const [flag, slot] of slots) {
+        const shouldMerge = slot.occurrences >= 2 || (multiValueListFlags.has(flag) && slot.originalTokens.length > 2);
+        if (!shouldMerge) {
+            splices.push({ outputIndex: slot.outputIndex, tokens: slot.originalTokens });
+            continue;
+        }
+        const mergedToken = `${flag}=${slot.values.join(",")}`;
+        splices.push({ outputIndex: slot.outputIndex, tokens: [mergedToken] });
+        events.push({
+            from: `${flag} (x${slot.occurrences})`,
+            to: [mergedToken],
+            reason: "list_merge",
+            confidence: "high",
+        });
+    }
+    return { events, splices };
+}
+function applyListFlagSplices(result, splices) {
+    splices.sort((a, b) => b.outputIndex - a.outputIndex);
+    for (const splice of splices) {
+        result.splice(splice.outputIndex, 1, ...splice.tokens);
+    }
+}
 /**
  * Coalesce repeated occurrences of comma-separated list flags into a single
  * `--flag=v1,v2,v3` token anchored at the FIRST occurrence. Without this,
@@ -534,15 +610,7 @@ export function coalesceRepeatedListFlags(argv, listFlags, valueConsumingFlags =
         // even when that value begins with "--". Emit both verbatim so the value is
         // never misread as a list-flag occurrence.
         if (valueConsumingFlags.has(token)) {
-            result.push(token);
-            const next = argv[index + 1];
-            if (typeof next === "string" && next !== "--") {
-                result.push(next);
-                index += 2;
-            }
-            else {
-                index += 1;
-            }
+            index = copyValueConsumingFlag(argv, index, result);
             continue;
         }
         const parsed = splitCanonicalListToken(token);
@@ -551,81 +619,23 @@ export function coalesceRepeatedListFlags(argv, listFlags, valueConsumingFlags =
             index += 1;
             continue;
         }
-        // Determine this occurrence's value (if any) and how many argv tokens it
-        // consumes. Most list flags consume one value per occurrence; selected
-        // agent-facing flags such as create --tags also accept several adjacent
-        // non-flag values in one occurrence.
-        let value;
-        let consumed = 1;
-        if (parsed.inlineValue !== undefined) {
-            value = parsed.inlineValue;
-        }
-        else {
-            const next = argv[index + 1];
-            if (typeof next === "string" && next !== "--" && !next.startsWith("-")) {
-                const values = [next];
-                if (multiValueListFlags.has(parsed.flag)) {
-                    let valueIndex = index + 2;
-                    while (valueIndex < argv.length && argv[valueIndex] !== "--" && !argv[valueIndex].startsWith("-")) {
-                        values.push(argv[valueIndex]);
-                        valueIndex += 1;
-                    }
-                }
-                value = values.join(",");
-                consumed = 1 + values.length;
-            }
-        }
-        if (value === undefined) {
+        const occurrence = readListFlagOccurrence(argv, index, parsed, multiValueListFlags);
+        if (occurrence.value === undefined) {
             // Value-less occurrence: leave untouched, do not coalesce.
             result.push(token);
-            index += consumed;
+            index += occurrence.consumed;
             continue;
         }
-        const originalTokens = argv.slice(index, index + consumed);
-        const existing = slots.get(parsed.flag);
-        if (existing) {
-            existing.values.push(value);
-            existing.occurrences += 1;
-        }
-        else {
-            const slot = {
-                outputIndex: result.length,
-                originalTokens,
-                values: [value],
-                occurrences: 1,
-            };
-            slots.set(parsed.flag, slot);
-            // Reserve the anchor position; finalized after the walk so we know the
-            // full merged value (or restore the original tokens for single uses).
-            result.push(null);
-        }
-        index += consumed;
-    }
-    const events = [];
-    const splices = [];
-    for (const [flag, slot] of slots) {
-        const shouldMerge = slot.occurrences >= 2 || (multiValueListFlags.has(flag) && slot.originalTokens.length > 2);
-        if (shouldMerge) {
-            const mergedToken = `${flag}=${slot.values.join(",")}`;
-            splices.push({ outputIndex: slot.outputIndex, tokens: [mergedToken] });
-            events.push({
-                from: `${flag} (x${slot.occurrences})`,
-                to: [mergedToken],
-                reason: "list_merge",
-                confidence: "high",
-            });
-        }
-        else {
-            // Single occurrence: restore the original token form verbatim.
-            splices.push({ outputIndex: slot.outputIndex, tokens: slot.originalTokens });
-        }
+        recordListFlagOccurrence(slots, result, parsed.flag, {
+            originalTokens: occurrence.originalTokens,
+            value: occurrence.value,
+        });
+        index += occurrence.consumed;
     }
     // Apply anchor splices from the end so earlier indices stay valid when a
     // single-occurrence anchor expands back into two tokens.
-    splices.sort((a, b) => b.outputIndex - a.outputIndex);
-    for (const splice of splices) {
-        result.splice(splice.outputIndex, 1, ...splice.tokens);
-    }
+    const { events, splices } = buildListFlagCoalescingSplices(slots, multiValueListFlags);
+    applyListFlagSplices(result, splices);
     return { argv: result, events };
 }
 /**
@@ -816,4 +826,4 @@ export const _testOnly = {
     resolveCanonicalFlag,
 };
 //# sourceMappingURL=bootstrap-args.js.map
-//# debugId=df81f91f-ed92-5511-b34c-ea7c1b81230b
+//# debugId=ddf0b427-0fb3-5cf1-99ef-177bf6530e4e