@unbrained/pm-cli 2026.8.4 → 2026.8.5

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

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 2026.8.5 - 2026-08-05
+
+### Fixed
+
+- GH-896: heterogeneous atomic specification batches need batch-local references and one discoverable SDK-first CLI path ([pm-o8z748](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-o8z748.toon))
+- Completion is decomposed while creation is composed: create takes nine inline evidence flags, close takes none, so the prescribed finish protocol is seven invocations and seven unrelated history entries ([pm-cyn0y6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-cyn0y6.toon))
+- Reindex coverage test leaks semantic refresh HTTP beyond its mock lifetime ([pm-cflhoj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-cflhoj.toon))
+- Sentry PM-CLI-2V: pm init surfaces raw EACCES when the managed workspace .gitignore cannot be written ([pm-3gh457](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-3gh457.toon))
+- Filed defect populations grow after they are measured and nothing turns a tracker measurement into a ceiling: the maintenance passes that record the count are the writer that widens it ([pm-ips23h](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ips23h.toon))
+- Tracker-only PM governance commits cannot satisfy required CI without changing the generated changelog ([pm-2x5x83](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2x5x83.toon))
+- GH-891: external blockers make graph stale_lifecycle_block impossible to resolve truthfully ([pm-6sc8jq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-6sc8jq.toon))
+- GH-889: merge-conflict recovery guidance hides the durable discarded-value report ([pm-fbrz7p](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-fbrz7p.toon))
+- GH-890: extension collision diagnostics omit the effective winner and cannot distinguish safe scoped overlap ([pm-6mjxgq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-6mjxgq.toon))
+- GH-885: create-time close_reason_required recovery recommends an impossible different-command retry ([pm-5uclvd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-5uclvd.toon))
+- GH-887: terminal create contract is non-atomic and inconsistent across importer-facing closure metadata ([pm-ykdt4m](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ykdt4m.toon))
+
+### Security
+
+- 2026-08-04 holistic pm CLI, SDK, and ecosystem manual review and optimization plan ([pm-gzyt2j](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/plans/pm-gzyt2j.toon))
+
+### Other
+
+- Auto Release fresh clones build the CLI and install merge drivers before tracker gates ([pm-xvccnm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-xvccnm.toon))
+- Tracker data-quality ratchet in CI: pm validate and pm health run against this repository's own workspace with a shrinking-only per-warning baseline ([pm-kpftft](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-kpftft.toon))
+- Eliminate July static-analysis nullability, dead-code, and redundant-allocation findings ([pm-cp5pbo](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-cp5pbo.toon))
+
 ## 2026.8.4 - 2026-08-04
 
 ### Added
@@ -1172,6 +1198,7 @@
 
 ### Added
 
+- Add agent-identity dimension to telemetry events: surface PM_AUTHOR as hashed author_context ([pm-fbyu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-fbyu.toon))
 - Sub-hour duration granularity for scheduling: support minutes in --duration / event duration= ([pm-zoe4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-zoe4.toon))
 - pm context --fields: per-row field projection for focus items (GH-156 follow-up to --depth full) ([pm-hnjf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-hnjf.toon))
 - pm history-compact: expose --scope all-streams (history GC pass) for closed items ([pm-yj9w](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-yj9w.toon))
@@ -1179,7 +1206,6 @@
 - pm search: structured inline query syntax (tag:/status:) + matched-text highlighting (GH-157 remainder) ([pm-ldr1](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-ldr1.toon))
 - Dedupe merge workflow: pm dedupe-merge to consolidate duplicates (GH-163, builds on closed pm-4n1a detection) ([pm-jmld](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-jmld.toon))
 - pm telemetry stats: add error_rate and resolution breakdown per command bucket ([pm-gsoe](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-gsoe.toon))
-- Add agent-identity dimension to telemetry events: surface PM_AUTHOR as hashed author_context ([pm-fbyu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-fbyu.toon))
 - History stream bulk-compaction: pm history-compact --all-over N to batch-compact large streams ([pm-f3pa](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-f3pa.toon))
 - pm plan discoverability: templates and auto-suggest for complex work (GH-158 remainder) ([pm-aer3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-aer3.toon))
 - Validate governance accuracy: suppress false-positive duplicate-code & terminal-item metadata noise + files --remove input clarity ([pm-6bz1](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-6bz1.toon))
@@ -1927,6 +1953,7 @@
 
 ### Fixed
 
+- Investigate validate/health telemetry classification (71-74% failure rate) ([pm-bzx3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bzx3.toon))
 - auto-release.yml workflow_dispatch silently overrides explicit push=false to true ([pm-qa2h](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qa2h.toon))
 - Accept positional title argument in pm create ([pm-7vm9](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7vm9.toon))
 - Sentry extension errors: cannot find module and activate failures ([pm-p7av](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-p7av.toon))
@@ -1953,7 +1980,6 @@
 - CI: skip non-source jobs on docs-only changes ([pm-iv1u](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-iv1u.toon))
 - CI: combine pnpm test + pnpm test:coverage into single coverage run ([pm-hpjd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-hpjd.toon))
 - pm test --add causes immediate history drift via null timeout_seconds ([pm-er4q](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-er4q.toon))
-- Investigate validate/health telemetry classification (71-74% failure rate) ([pm-bzx3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bzx3.toon))
 - Fix: ENOENT lstat in extension path operations ([pm-bh13](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bh13.toon))
 - Fix: localeCompare on undefined in sort comparators ([pm-b9y1](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-b9y1.toon))
 - Suppress benign extension_service_override_collision when calendar+guide-shell both bundled ([pm-5u9z](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-5u9z.toon))
@@ -2154,24 +2180,24 @@
 
 ### Security
 
+- Chore: 2026-05-02 Phase 3 Audit - IP scrub, dogfood, analysis tooling ([pm-2326](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-2326.toon))
 - 2026-05-02 Full PM CLI Audit: Build Fix, Security, Performance, Telemetry ([pm-nnhi](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-nnhi.toon))
 - 2026-05-02 Full PM CLI Audit Phase 2: Dead Code Removal, Security Enhancement, Sentry Optimization ([pm-kkmo](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-kkmo.toon))
 - Documentation overhaul and public docs safety ([pm-3042](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-3042.toon))
 - Pin release dependency ranges for Dependabot hygiene ([pm-q71q](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-q71q.toon))
 - Enhance check-secrets.mjs with private IP detection rule ([pm-daft](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-daft.toon))
-- Chore: 2026-05-02 Phase 3 Audit - IP scrub, dogfood, analysis tooling ([pm-2326](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-2326.toon))
 - Rewrite README and public documentation ([pm-1sb2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-1sb2.toon))
 
 ### Other
 
-- 2026-05-01 Full PM CLI Dogfood Audit v2 ([pm-2eb3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-2eb3.toon))
+- 2026-05-02 Full Audit: All Systems Verified ([pm-ss8d](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-ss8d.toon))
 - Verify remote telemetry stack receives events and data flows to \[redacted_monitoring_ui\] ([pm-g8gj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-g8gj.toon))
+- 2026-05-01 Full PM CLI Dogfood Audit v2 ([pm-2eb3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-2eb3.toon))
 - 2026-05-02 Comprehensive PM CLI Audit ([pm-rrjv](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-rrjv.toon))
 - 2026-04-30 Full PM CLI Dogfood Audit ([pm-23me](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-23me.toon))
 - 2026-05-01 Full PM CLI Audit Implementation ([pm-twpc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-twpc.toon))
 - Lower Sentry tracesSampleRate from 1.0 to 0.2 for free plan quota ([pm-wvhs](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-wvhs.toon))
 - Chore: Prune stuck telemetry queue entries ([pm-wrbo](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-wrbo.toon))
-- 2026-05-02 Full Audit: All Systems Verified ([pm-ss8d](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-ss8d.toon))
 - Decision: Cap telemetry result_summary payload size ([pm-q9yt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-q9yt.toon))
 - Sentry CLI token needs broader scopes for issue analysis ([pm-q4jp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-q4jp.toon))
 - Dead code: root-level facade re-export shims unused ([pm-nr8k](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-nr8k.toon))
@@ -2195,6 +2221,7 @@
 
 ### Added
 
+- Add pm version and source classification to telemetry payloads ([pm-3dd9](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-3dd9.toon))
 - Add scoped audit override mode for pm update metadata mutations ([pm-umhv](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-umhv.toon))
 - Add opt-in runtime probe mode for extension manage parity ([pm-p0ij](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-p0ij.toon))
 - List command large-output ergonomics ([pm-a4z3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-a4z3.toon))
@@ -2303,7 +2330,6 @@
 - Issue4: create strict vs progressive policy mode ([pm-431e](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-431e.toon))
 - Add glob-based linked artifact additions for files/docs ([pm-3eu2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-3eu2.toon))
 - Health vectorization status and targeted refresh ([pm-3ebr](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-3ebr.toon))
-- Add pm version and source classification to telemetry payloads ([pm-3dd9](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-3dd9.toon))
 - Add extension registration support for custom item types/options ([pm-37pj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-37pj.toon))
 - Add telemetry runtime diagnostics to pm health ([pm-300m](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-300m.toon))
 - Implement extension source resolver and installer engine ([pm-2poj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-2poj.toon))
@@ -2352,19 +2378,19 @@
 
 ### Fixed
 
+- Validate UUID fields at telemetry ingestion boundary ([pm-vhdc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-vhdc.toon))
+- Fix Grafana RabbitMQ queue panel metric selector mismatch ([pm-r9ei](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-r9ei.toon))
+- Implement local telemetry queue retention_days TTL cleanup ([pm-pxx0](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-pxx0.toon))
 - Templates command: document correct invocation syntax (positional vs --name) ([pm-6y6i](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-6y6i.toon))
 - Auto-migrate previous-version trackers on first mutation ([pm-yvwt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-yvwt.toon))
 - Cross-command regression verification for date parsing expansion ([pm-x6l7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-x6l7.toon))
-- Validate UUID fields at telemetry ingestion boundary ([pm-vhdc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-vhdc.toon))
 - Allow unquoted multi-word search queries ([pm-v6ob](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-v6ob.toon))
 - Expand regression and release-readiness tests for calendar/reminders ([pm-tyq3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-tyq3.toon))
 - Terminal compatibility regression suite and docs parity ([pm-t6f7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-t6f7.toon))
 - Fix cross-platform CI regressions surfaced by GitHub checks ([pm-skyg](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-skyg.toon))
 - Document resilient input formats and lock regression coverage ([pm-s9hl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-s9hl.toon))
-- Fix Grafana RabbitMQ queue panel metric selector mismatch ([pm-r9ei](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-r9ei.toon))
 - Ship regression tests docs and verification evidence ([pm-r9dy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-r9dy.toon))
 - Regression and release hardening ([pm-qwp7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-qwp7.toon))
-- Implement local telemetry queue retention_days TTL cleanup ([pm-pxx0](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-pxx0.toon))
 - Fix LanceDB vector dimension mismatch blocking default search ([pm-oyt8](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-oyt8.toon))
 - Replace invalid-id echo in get not-found guidance ([pm-opbo](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-opbo.toon))
 - Include active extension commands/actions in contracts output ([pm-nnfc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-nnfc.toon))
@@ -2433,6 +2459,10 @@
 
 ### Other
 
+- Execute telemetry + observability rollout implementation ([pm-ny6y](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-ny6y.toon))
+- 2026-04-26 comprehensive dogfood audit stabilization ([pm-mb4n](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-mb4n.toon))
+- Telemetry and observability rollout ([pm-lnq3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-lnq3.toon))
+- Backfill telemetry documentation files referenced in tracker links ([pm-35wb](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-35wb.toon))
 - Track open Dependabot PR \#14 ([pm-0jpx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-0jpx.toon))
 - Make lifecycle validate patterns configurable ([pm-urxb](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-urxb.toon))
 - Run weekly GitHub findings review ([pm-lou4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-lou4.toon))
@@ -2453,7 +2483,6 @@
 - External audit issue remediation and compatibility hardening ([pm-my6o](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-my6o.toon))
 - Linked-test parity and runnable command enforcement ([pm-mf5z](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-mf5z.toon))
 - Extension lifecycle manager and SDK parity rollout ([pm-m9jc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-m9jc.toon))
-- Telemetry and observability rollout ([pm-lnq3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-lnq3.toon))
 - CLI UX Overhaul: Help, Errors, and Output ([pm-izbd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-izbd.toon))
 - External audit follow-up: unresolved UX and dependency visualization gaps ([pm-iswo](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-iswo.toon))
 - CLI UX and Integrity Hardening ([pm-hp31](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-hp31.toon))
@@ -2521,12 +2550,10 @@
 - Implement dual-format codec and store lookup ([pm-oex4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-oex4.toon))
 - M5: Built-in beads import extension ([pm-odt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-odt.toon))
 - Consolidate 2026-04-25 dogfood audit evidence and tracker links ([pm-odcr](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-odcr.toon))
-- Execute telemetry + observability rollout implementation ([pm-ny6y](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-ny6y.toon))
 - Phase 2: compatibility adapters and migration diagnostics ([pm-ngdf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-ngdf.toon))
 - Phase 2: wire parser override contracts in runtime ([pm-nfii](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-nfii.toon))
 - Track open Dependabot PR \#7 ([pm-n8w4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-n8w4.toon))
 - Wave 8/9: restore replay patch compatibility and diagnostics ([pm-n5cw](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-n5cw.toon))
-- 2026-04-26 comprehensive dogfood audit stabilization ([pm-mb4n](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-mb4n.toon))
 - Release @unbrained/pm-cli 2026.3.12 ([pm-lz4m](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-lz4m.toon))
 - Implement tolerant entry parser and stdin token utility ([pm-luay](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-luay.toon))
 - Phase 2: integrate service overrides into core modules ([pm-leol](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-leol.toon))
@@ -2596,7 +2623,6 @@
 - M1: Item schema model and validation ([pm-3gi](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-3gi.toon))
 - Telemetry pipeline verified: all \[redacted_service_count\] services healthy, E2E event ingestion working ([pm-3akm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-3akm.toon))
 - Integrate command and extension format behavior ([pm-3aga](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-3aga.toon))
-- Backfill telemetry documentation files referenced in tracker links ([pm-35wb](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-35wb.toon))
 - Chore: Telemetry queue steady-state has 100 pending entries ([pm-2gmr](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-2gmr.toon))
 - A1: Unified extension-first command router ([pm-2bxh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-2bxh.toon))
 - Issue3 Task: Default-on validate command reference check ([pm-2ajr](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-2ajr.toon))

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]="2d214367-9872-573e-8380-00667f0820d0")}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]="d9d3d041-587b-5660-a909-d0759998248d")}catch(e){}}();
 import { renderPmCommand } from "./argv-utils.js";
 import { discoverNearbyPmRoot } from "../sdk/tracker-root-discovery.js";
 /** Compact an error envelope to fields that change the caller's next action. */
@@ -884,7 +884,7 @@ function buildUnknownCommandGuidance(message, context) {
         recovery: buildCommanderRecoveryPayload(context),
     });
 }
-function buildLinkedTestValueNotQuotedGuidance(message, commandName, allowedTypes, context) {
+function buildLinkedTestValueNotQuotedGuidance(message, commandName, context) {
     if (!/too many arguments/i.test(message) || commandName !== "test") {
         return null;
     }
@@ -990,7 +990,7 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
         buildMissingRequiredArgumentGuidance(message, commandName, context) ??
         buildUnknownOptionGuidance(message, commandName, context) ??
         buildUnknownCommandGuidance(message, context) ??
-        buildLinkedTestValueNotQuotedGuidance(message, commandName, allowedTypes, context) ??
+        buildLinkedTestValueNotQuotedGuidance(message, commandName, context) ??
         buildContextItemArgumentGuidance(message, commandName, context);
     if (guidance) {
         return guidance;
@@ -1083,4 +1083,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=2d214367-9872-573e-8380-00667f0820d0
+//# debugId=d9d3d041-587b-5660-a909-d0759998248d

package/dist/cli/register-structured-mutation.d.ts

@@ -5,10 +5,12 @@
  */
 import type { Command } from "commander";
 declare function runItemMutateAction(options: Record<string, unknown>, command: Command): Promise<void>;
+declare function runItemCompleteAction(id: string, positionalReason: string | undefined, options: Record<string, unknown>, command: Command): Promise<void>;
 /** Register `pm item mutate`, the stable noun-first atomic batch surface. */
 export declare function registerStructuredMutationCommands(program: Command): void;
 /** Internal action hooks used by exhaustive source-level registration tests. */
 export declare const structuredMutationTestOnly: {
+    runItemCompleteAction: typeof runItemCompleteAction;
     runItemMutateAction: typeof runItemMutateAction;
 };
 export {};

package/dist/cli/register-structured-mutation.js

@@ -1,22 +1,28 @@
 
-!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]="73fa04e4-2dfb-5653-9a39-9a034f80a616")}catch(e){}}();
-import { createStdinTokenResolver, EXIT_CODE, PmCliError, resolveAuthor, resolvePmRoot, } from "../sdk/runtime-primitives.js";
-import { commitItemMutations } from "../sdk/item-transaction.js";
-import { parseAtomicMutationControls, parseItemMutationBatch, } from "../sdk/structured-mutations.js";
-import { getGlobalOptions, printResult } from "./registration-helpers.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]="94fe3b7b-3aeb-5a31-a3a5-d85ae7e1ac83")}catch(e){}}();
+import { createStdinTokenResolver, EXIT_CODE, PmCliError, readSettings, resolveAuthor, resolvePmRoot, } from "../sdk/runtime-primitives.js";
+import { buildItemCompletionMutations, commitItemCompletion, commitItemMutations, } from "../sdk/item-transaction.js";
+import { parseAtomicMutationControls, resolveItemMutationDocument, } from "../sdk/structured-mutations.js";
+import { collect, getGlobalOptions, printResult, } from "./registration-helpers.js";
 async function runItemMutateAction(options, command) {
     const globalOptions = getGlobalOptions(command);
     const input = await createStdinTokenResolver().resolveValue("-", "--stdin-json");
     if (input === undefined || input.trim().length === 0) {
         throw new PmCliError("pm item mutate requires a non-empty JSON batch on stdin.", EXIT_CODE.USAGE);
     }
-    const mutations = parseItemMutationBatch(input);
     const transactionId = typeof options.transactionId === "string"
         ? options.transactionId.trim()
         : "";
     if (transactionId.length === 0) {
         throw new PmCliError("pm item mutate requires --transaction-id <value>.", EXIT_CODE.USAGE);
     }
+    const pmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
+    const settings = await readSettings(pmRoot);
+    const resolved = resolveItemMutationDocument(input, {
+        transactionId,
+        idPrefix: settings.id_prefix,
+    });
+    const { mutations, references } = resolved;
     const controls = parseAtomicMutationControls(options);
     if (options.dryRun === true) {
         printResult({
@@ -24,19 +30,100 @@ async function runItemMutateAction(options, command) {
             dry_run: true,
             mutation_count: mutations.length,
             mutations,
+            references,
         }, globalOptions);
         return;
     }
     const result = await commitItemMutations({
-        pmRoot: resolvePmRoot(process.cwd(), globalOptions.path),
+        pmRoot,
         transactionId,
         author: resolveAuthor(typeof options.author === "string"
             ? options.author
-            : globalOptions.author, "unknown"),
+            : globalOptions.author, settings.author_default),
         mutations,
         ...controls,
     });
-    printResult({ ...result, mutation_count: mutations.length }, globalOptions);
+    printResult({ ...result, mutation_count: mutations.length, references }, globalOptions);
+}
+function resolveCompletionReason(positionalReason, optionReason) {
+    if (typeof positionalReason === "string" &&
+        positionalReason.trim().length > 0) {
+        return positionalReason.trim();
+    }
+    return typeof optionReason === "string" ? optionReason.trim() : "";
+}
+async function runItemCompleteAction(id, positionalReason, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const transactionId = typeof options.transactionId === "string"
+        ? options.transactionId.trim()
+        : "";
+    if (transactionId.length === 0) {
+        throw new PmCliError("pm item complete requires --transaction-id <value>.", EXIT_CODE.USAGE);
+    }
+    const reason = resolveCompletionReason(positionalReason, options.reason);
+    if (reason.length === 0) {
+        throw new PmCliError("pm item complete requires a close reason.", EXIT_CODE.USAGE);
+    }
+    const evidenceKeys = [
+        "file",
+        "doc",
+        "test",
+        "comment",
+        "note",
+        "learning",
+    ];
+    const evidence = Object.fromEntries(evidenceKeys
+        .filter((key) => options[key] !== undefined)
+        .map((key) => [key, options[key]]));
+    const force = options.force === true;
+    const { lockTtlSeconds, lockWaitMs } = parseAtomicMutationControls(options);
+    const closeOptions = {
+        ...(typeof options.resolution === "string"
+            ? { resolution: options.resolution }
+            : {}),
+        ...(typeof options.expectedResult === "string"
+            ? { expectedResult: options.expectedResult }
+            : {}),
+        ...(typeof options.actualResult === "string"
+            ? { actualResult: options.actualResult }
+            : {}),
+        ...(typeof options.completedAt === "string"
+            ? { completedAt: options.completedAt }
+            : {}),
+        ...(typeof options.validateClose === "string"
+            ? { validateClose: options.validateClose }
+            : {}),
+        ...(force ? { force: true } : {}),
+    };
+    const completion = {
+        id,
+        reason,
+        ...(Object.keys(evidence).length === 0 ? {} : { evidence }),
+        ...(Object.keys(closeOptions).length === 0 ? {} : { closeOptions }),
+        ...(force ? { releaseOptions: { force: true } } : {}),
+    };
+    if (options.dryRun === true) {
+        const mutations = buildItemCompletionMutations(completion);
+        printResult({
+            transaction_id: transactionId,
+            dry_run: true,
+            mutation_count: mutations.length,
+            mutations,
+        }, globalOptions);
+        return;
+    }
+    const pmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
+    const result = await commitItemCompletion({
+        pmRoot,
+        transactionId,
+        author: resolveAuthor(typeof options.author === "string"
+            ? options.author
+            : globalOptions.author, (await readSettings(pmRoot)).author_default),
+        ...completion,
+        lockTtlSeconds,
+        lockWaitMs,
+    });
+    printResult({ ...result, mutation_count: Object.keys(result.results).length }, globalOptions);
 }
 /** Register `pm item mutate`, the stable noun-first atomic batch surface. */
 export function registerStructuredMutationCommands(program) {
@@ -53,10 +140,35 @@ export function registerStructuredMutationCommands(program) {
         .option("--lock-ttl-seconds <n>", "Workspace transaction lock lifetime in seconds")
         .option("--lock-wait-ms <n>", "Maximum time to wait for the workspace transaction lock")
         .option("--author <value>", "Mutation author")
-        .description("Apply create/update/close mutations atomically through the public pm SDK.")
+        .description("Apply create/update/close/release mutations atomically through the public pm SDK.")
         .action(runItemMutateAction);
+    itemCommand
+        .command("complete <id> [reason]")
+        .requiredOption("--transaction-id <value>", "Stable idempotency key for the composed completion")
+        .option("--reason <value>", "Close reason when omitted positionally")
+        .option("--file <value>", "Linked file evidence", collect)
+        .option("--doc <value>", "Linked documentation evidence", collect)
+        .option("--test <value>", "Linked test evidence", collect)
+        .option("--comment <value>", "Evidence comment", collect)
+        .option("--note <value>", "Completion note", collect)
+        .option("--learning <value>", "Durable completion learning", collect)
+        .option("--resolution <value>", "Structured resolution evidence")
+        .option("--expected-result <value>", "Expected result evidence")
+        .option("--actual-result <value>", "Actual result evidence")
+        .option("--completed-at <value>", "Actual completion time")
+        .option("--validate-close <mode>", "Close validation: off, warn, or strict")
+        .option("--lock-ttl-seconds <n>", "Workspace transaction lock lifetime in seconds")
+        .option("--lock-wait-ms <n>", "Maximum time to wait for the workspace transaction lock")
+        .option("--dry-run", "Validate and preview completion without writing")
+        .option("--force", "Override lifecycle and ownership conflicts")
+        .option("--author <value>", "Completion author")
+        .description("Record evidence, close the item, and release its claim atomically.")
+        .action(runItemCompleteAction);
 }
 /** Internal action hooks used by exhaustive source-level registration tests. */
-export const structuredMutationTestOnly = { runItemMutateAction };
+export const structuredMutationTestOnly = {
+    runItemCompleteAction,
+    runItemMutateAction,
+};
 //# sourceMappingURL=register-structured-mutation.js.map
-//# debugId=73fa04e4-2dfb-5653-9a39-9a034f80a616
+//# debugId=94fe3b7b-3aeb-5a31-a3a5-d85ae7e1ac83