@unbrained/pm-cli 2026.8.31 → 2026.9.2

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.31"
+    "version": "2026.9.2"
   },
   "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.31",
+      "version": "2026.9.2",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/AGENTS.md

@@ -4,15 +4,15 @@ This file is the low-context entrypoint for agents working in this repository. R
 
 ## Progressive Disclosure
 
-| Need | Read |
-|------|------|
-| Agent workflow and ownership | [Agent Guide](docs/AGENT_GUIDE.md) |
-| Exact command families and examples | [Command Reference](docs/COMMANDS.md) |
-| Sandbox-safe verification | [Testing](docs/TESTING.md) |
-| Settings, output, and environment | [Configuration](docs/CONFIGURATION.md) |
-| Package or extension work | [Packages and Extensions](docs/EXTENSIONS.md), [SDK](docs/SDK.md) |
-| Release work | [Releasing](docs/RELEASING.md) |
-| Full docs map | [Documentation Index](docs/README.md) |
+| Need                                | Read                                                              |
+| ----------------------------------- | ----------------------------------------------------------------- |
+| Agent workflow and ownership        | [Agent Guide](docs/AGENT_GUIDE.md)                                |
+| Exact command families and examples | [Command Reference](docs/COMMANDS.md)                             |
+| Sandbox-safe verification           | [Testing](docs/TESTING.md)                                        |
+| Settings, output, and environment   | [Configuration](docs/CONFIGURATION.md)                            |
+| Package or extension work           | [Packages and Extensions](docs/EXTENSIONS.md), [SDK](docs/SDK.md) |
+| Release work                        | [Releasing](docs/RELEASING.md)                                    |
+| Full docs map                       | [Documentation Index](docs/README.md)                             |
 
 Use runtime contracts for exact flags because packages and settings can change the active surface:
 
@@ -58,10 +58,11 @@ On a fresh clone or worktree, also run `pm merge install` once: the committed `.
 For real repository tracking, do not override `PM_PATH`. If a script must target a tracker explicitly, prefer `--pm-path <repo>/.agents/pm`; `--path` is only a backward-compatible tracker-root alias, not a workspace/cwd flag. For tests and dogfood runs, use sandboxed `PM_PATH` and `PM_GLOBAL_PATH`; prefer `node scripts/run-tests.mjs ...` because it sets them automatically.
 
 <!-- pm-cli:agent-guidance:start:v1 -->
+
 ## pm Workflow Quickstart
 
 ```bash
-pm context --limit 10
+pm context --limit 10 --for orient
 pm search "<request keywords>" --limit 10
 pm list --status open --limit 20
 pm list --status in_progress --limit 20
@@ -73,21 +74,22 @@ pm docs <id> --add path=<path>,scope=project,note="<why>"
 pm test <id> --add command="node scripts/run-tests.mjs test -- <target>",scope=project,timeout_seconds=240
 pm comments <id> "Evidence: <what changed and what passed>"
 pm test <id> --run --progress
-pm close <id> "<reason with evidence>" --validate-close warn
+pm close <id> "<reason with evidence>" --resolution "<what changed>" --expected "<expected outcome>" --actual "<observed outcome>" --validate-close warn
 pm release <id>
 ```
 
 Author identity is automatic; use `--author` only for an explicit override.
+
 <!-- pm-cli:agent-guidance:end -->
 
 ## Working Rules
 
-- **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.
+- **Orient:** start with the measured canonical cold-start, `pm context --limit 10 --for orient`. Before `pm create`, also run request-specific `pm search`, `pm list --status open`, and `pm list --status in_progress` so duplicate and ownership checks use live state. 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>`.
+- **Close:** add evidence first, then atomically include `--resolution`, `--expected`, and `--actual` on `pm close <id> "<reason>" --validate-close warn`, then `pm release <id>`. Structured evidence belongs in the immutable close event, not in a later backfill.
 - **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,34 @@
 # Changelog
 
+## 2026.9.2 - 2026-09-02
+
+### Fixed
+
+- GH-1174: Windows Node 24 receipt traversal negative control must fail closed portably ([pm-r97901](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-r97901.toon))
+
+### Security
+
+- GH-1173: make merge-receipt evidence diagnostics source-stable and record-addressable ([pm-dn8rwl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dn8rwl.toon))
+
+## 2026.9.1 - 2026-09-01
+
+### Added
+
+- GH-796: duplicate recurrence now reopens the canonical terminal item instead of creating a second item ([pm-83cz0o](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-83cz0o.toon))
+- Progressive MCP discovery and canonical tool results: reveal the minimum relevant catalog and deliver one unambiguous model-facing output contract ([pm-3g3f8z](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-3g3f8z.toon))
+
+### Fixed
+
+- The two-call agent cold start proposed as canonical costs more tokens than the four-call protocol it replaces, and no gate measures either ([pm-jjqyzd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-jjqyzd.toon))
+- GH-1166: root help hides the --all discovery option that reveals the full command surface ([pm-7f9zkh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7f9zkh.toon))
+- GH-1104: health must not certify pending lossless merge receipts as reconciled ([pm-baksix](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-baksix.toon))
+- GH-1135: item_hash_version 2 still masks writer hash divergence as corruption ([pm-2qahia](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2qahia.toon))
+
+### Other
+
+- Document the measured canonical agent cold-start across docs and generated guidance ([pm-ka6d](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-ka6d.toon))
+- Close-time completeness signal for structured resolution fields (resolution/expected/actual) — config-gated warn or require ([pm-wenq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-wenq.toon))
+
 ## 2026.8.31 - 2026-08-31
 
 ### Added
@@ -14,6 +43,10 @@
 - The local preflight token-budget gate is red on a workstation and green in hosted CI for the same commit again, because the earlier remediation closed the one ambient channel that had bitten instead of closing the fixture's environment ([pm-4o7tlx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-4o7tlx.toon))
 - The bounded legacy MCP compatibility set stops one revision short of the spec's own legacy boundary, so every current host is refused at initialize and the dual-era guarantee is unmet ([pm-edywqn](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-edywqn.toon))
 
+### Security
+
+- Refresh compatible GitHub Actions and tsx tooling dependencies ([pm-k47gdd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-k47gdd.toon))
+
 ### Deprecated
 
 - The project's own agent-facing documentation and skills instruct deprecated command spellings, so the alias-usage signal that decides when a spelling can be retired is manufactured by the instructions rather than observed from callers ([pm-q2n4vd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-q2n4vd.toon))
@@ -34,7 +67,6 @@
 - GH-1148: cached drift mismatch can falsely report tracker corruption ([pm-sxg7wl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-sxg7wl.toon))
 - GH-1138: linked test name filters can pass after executing zero tests ([pm-ntnv4k](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ntnv4k.toon))
 - GH-1136: npm 12 object-form npm pack receipts break registry package installs ([pm-xrjy8o](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xrjy8o.toon))
-- GH-1135: item_hash_version 2 still masks writer hash divergence as corruption ([pm-2qahia](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2qahia.toon))
 - The annotation key=value grammar has three divergent comma behaviours, two of which silently corrupt the evidence text before it is made immutable ([pm-hu92i3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-hu92i3.toon))
 - GH-1150: health remediation for pending merge receipts must perform the repair ([pm-r0p3at](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-r0p3at.toon))
 - GH-1134: required collection recovery omits truthful --clear-\* intent ([pm-t7wl00](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-t7wl00.toon))
@@ -132,7 +164,6 @@
 
 ### Fixed
 
-- GH-1104: health must not certify pending lossless merge receipts as reconciled ([pm-baksix](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-baksix.toon))
 - Dynamic-read continuation cursors are born stale: pm health emits a cursor that its next invocation rejects ([pm-oahhyc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-oahhyc.toon))
 - GH-1105: contracts must declare each command projection vocabulary before invocation ([pm-q4isdq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-q4isdq.toon))
 - The outcome-milestone ladder is a sibling set rather than a layer: 1,024 terminal items reach the roadmap apex through 154 typed roots without traversing any outcome milestone ([pm-h6b73t](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-h6b73t.toon))
@@ -223,10 +254,6 @@
 
 ## 2026.8.20 - 2026-08-20
 
-### Added
-
-- GH-796: no reopen transition for terminal items, so recurrence is recorded as a duplicate instead of a reopening ([pm-83cz0o](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-83cz0o.toon))
-
 ### Fixed
 
 - GH-529: init --agent-guidance emits run-tests.mjs linked-test example that may not exist in the target repo ([pm-surv](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-surv.toon))

package/README.md

@@ -99,11 +99,11 @@ pm release <item-id>
 
 ## Agent Loop
 
-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:
+Use the measured one-call context intent for cold-start orientation. Use `pm next` as an alternative when you only need the single highest-priority ready item, then search all statuses before creating anything. Measurement methodology and ratcheted evidence live in the [Agent Guide](docs/AGENT_GUIDE.md#agent-quick-context).
 
 ```bash
-pm next                                          # the next actionable item + rationale, ready/blocked queues
-pm context --limit 10
+pm context --limit 10 --for orient              # canonical cold start: state, ownership, actionable work
+# Alternative: pm next                          # one actionable item + rationale, ready/blocked queues
 pm search "keywords for the requested work" --limit 10
 pm list --status open --limit 20
 pm list --status in_progress --limit 20

package/dist/cli/commands/merge.d.ts

@@ -5,4 +5,4 @@
  * primitives. The SDK owns the three-way merge semantics, the git merge
  * driver runner, and the repository merge-configuration installer.
  */
-export { MERGE_DRIVER_ARTIFACT_VALUES, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, runMergeDriver, runMergeInstall, runMergeReceiptReport, runMergeReconcile, type MergeDriverArtifact, type MergeDriverOptions, type MergeDriverResult, type MergeInstallOptions, type MergeInstallResult, type MergeReceiptReport, type MergeReconcileOptions, type MergeReconcileResult, } from "../../sdk/merge/index.js";
+export { MERGE_DRIVER_ARTIFACT_VALUES, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, runMergeDriver, runMergeInstall, runMergeReceiptEvidenceReport, runMergeReceiptReport, runMergeReconcile, type MergeDriverArtifact, type MergeDriverOptions, type MergeDriverResult, type MergeInstallOptions, type MergeInstallResult, type MergeReceiptEvidenceReport, type MergeReceiptReport, type MergeReconcileOptions, type MergeReconcileResult, } from "../../sdk/merge/index.js";

package/dist/cli/commands/merge.js

@@ -6,7 +6,7 @@
  * driver runner, and the repository merge-configuration installer.
  */
 
-!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]="8bc9436f-c101-583d-ae42-02d51b5eb027")}catch(e){}}();
-export { MERGE_DRIVER_ARTIFACT_VALUES, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, runMergeDriver, runMergeInstall, runMergeReceiptReport, runMergeReconcile, } from "../../sdk/merge/index.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]="0ac2cdcd-45da-5420-ba98-a49ecf54f75c")}catch(e){}}();
+export { MERGE_DRIVER_ARTIFACT_VALUES, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, runMergeDriver, runMergeInstall, runMergeReceiptEvidenceReport, runMergeReceiptReport, runMergeReconcile, } from "../../sdk/merge/index.js";
 //# sourceMappingURL=merge.js.map
-//# debugId=8bc9436f-c101-583d-ae42-02d51b5eb027
+//# debugId=0ac2cdcd-45da-5420-ba98-a49ecf54f75c

package/dist/cli/register-mutation.js

@@ -1,9 +1,9 @@
 
-!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]="28a59fb9-80bc-5e2a-b926-1bb227c103c6")}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]="4e3b2528-5128-5bfd-8234-1e60fe90d9e2")}catch(e){}}();
 import { resolveBodyFileContent, resolveCliBulkIdsInput, EXIT_CODE, splitCommaList, PmCliError, createUnknownSubcommandError, } from "../sdk/runtime-primitives.js";
 import { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, MERGE_SUBCOMMAND_VALUES, PLAN_CREATE_METADATA_PARAMETER_KEYS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, } from "../sdk/cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES, PLAN_STEP_LINK_KIND_VALUES, } from "../types/index.js";
-import { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, runMergeInstall, runMergeReconcile, runMergeReceiptReport, } from "./commands/merge.js";
+import { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, runMergeInstall, runMergeReconcile, runMergeReceiptEvidenceReport, } from "./commands/merge.js";
 import { runAppend } from "./commands/append.js";
 import { runClose } from "./commands/close.js";
 import { runCloseMany } from "./commands/close-many.js";
@@ -847,9 +847,12 @@ async function runMergeAction(subcommand, artifact, base, ours, theirs, options,
             if (artifact !== undefined) {
                 throw new PmCliError("merge report takes no positional arguments.", EXIT_CODE.USAGE);
             }
-            printResult(await runMergeReceiptReport({
+            const result = await runMergeReceiptEvidenceReport({
                 includeReconciled: options.includeReconciled === true,
-            }), globalOptions);
+            });
+            printResult(result, globalOptions);
+            if (!result.ok)
+                process.exitCode = EXIT_CODE.GENERIC_FAILURE;
             break;
         }
         case "driver":
@@ -1886,4 +1889,4 @@ export function registerMutationCommands(program, registrationOptions = {}) {
         .action(runDepsAction);
 }
 //# sourceMappingURL=register-mutation.js.map
-//# debugId=28a59fb9-80bc-5e2a-b926-1bb227c103c6
+//# debugId=4e3b2528-5128-5bfd-8234-1e60fe90d9e2