@unbrained/pm-cli 2026.8.11 → 2026.8.12

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

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 2026.8.12 - 2026-08-12
+
+### Fixed
+
+- Read-output session receipts can emit an invalid next_state after the served-item set crosses its own 10,000-ID input ceiling ([pm-b0v8fs](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-b0v8fs.toon))
+- Linked pm test children inherit production Sentry environment and turn sandbox failures into release-blocking incidents ([pm-9aaji6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-9aaji6.toon))
+- SDK entrypoint import-cost gate false-fails on cold filesystem cache: single-shot fresh-process sampling exceeds the 30ms noise margin ([pm-cg1sjb](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-cg1sjb.toon))
+- Legacy invalid provenance findings block health without a safe disposition path ([pm-5q8wa0](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-5q8wa0.toon))
+- History drift scan hashes reordered linked-test projections ([pm-eax4y8](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-eax4y8.toon))
+- Linked-test removal must be lossless and observable for commands containing comma or equals delimiters ([pm-m0b7h8](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-m0b7h8.toon))
+- Annotation transposition recovery: detect pm <collection\> add <id\> before the item id is consumed as text ([pm-rncuf7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-rncuf7.toon))
+- Health result contract parity: every checks\[\] row exposes a boolean ok beside its tri-state status ([pm-h97qxd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-h97qxd.toon))
+- The relationship ratchet bounds every edge kind that carries meaning and leaves the one kind that carries none unbounded, so the cheapest way to satisfy every graph guarantee is to add edges no algorithm can traverse ([pm-q6n8sj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-q6n8sj.toon))
+- Assurance registry mutations and gate verdicts record author unknown while carrying the full detected provenance in the same entry, so the audit artifact fails the question it exists to answer ([pm-33mjrw](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-33mjrw.toon))
+- Two assurance measurement sources answer from a projection that omits the fields they read, so a completeness gate reports zero missing evidence on a workspace with 874 items lacking it ([pm-py7qv2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-py7qv2.toon))
+- Assurance mutation refusals cross the CLI as unclassified Sentry faults (PM-CLI-2Y/2Z/30) ([pm-v0a0un](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-v0a0un.toon))
+- GH-976: version history hashes so repeated tests_add streams verify across supported pm versions ([pm-2htk4p](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2htk4p.toon))
+- GH-975: export isAlreadyClaimedError through a supported SDK subpath ([pm-hfqju5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-hfqju5.toon))
+- GH-974: merge receipt preferred contradicts retained side under stable_value_order ([pm-qckpnq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qckpnq.toon))
+- GH-971: health preflight collision diagnostics ignore declared command ownership ([pm-zryb9d](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-zryb9d.toon))
+- GH-969: brief item reads can exceed standard output because omission receipts bill empty fields ([pm-gok2km](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gok2km.toon))
+- GH-970: repeated row contracts consume half of agent read output without a suppression contract ([pm-gjjurs](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gjjurs.toon))
+- The output encoding named toon has no tabular array form, so every row collection pays three to five lines per row while the storage format beside it uses the encoding correctly ([pm-5y05kq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-5y05kq.toon))
+- pm activity answers what happened to one item in the last half hour when the agent asked what changed in the workspace: 20 rows cover 5 of the 272 items touched in 24 hours and none carries a title ([pm-j1r8gl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-j1r8gl.toon))
+- pm stats default output is dominated by rows that carry no information: 7 of 17 type buckets are zero, the status split agents actually need is missing, and the row contract costs more than the data ([pm-7nqo6b](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7nqo6b.toon))
+
+### Other
+
+- Evaluate and refresh @sentry/node 10.70 with packed-consumer proof ([pm-fb0lkg](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-fb0lkg.toon))
+- Refresh compatible tsx 4.23.12 and esbuild 0.28.2 patches ([pm-67b84b](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-67b84b.toon))
+
 ## 2026.8.11 - 2026-08-11
 
 ### Added
@@ -482,7 +513,6 @@
 
 - Immutable-tree DeepScan and CodeFactor zero-new-issues release gate ([pm-39cqqx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-39cqqx.toon))
 - Model-aware agent identity: detection resolves harness, model, and session so an agent never types an identity flag and history still records which model acted ([pm-03pq3o](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-03pq3o.toon))
-- Author-resolution bypass class: create/copy and the context, next, and usage-feedback paths re-implement author precedence without harness detection, stamping author 'unknown' on new items ([pm-42p9nk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-42p9nk.toon))
 
 ### Changed
 
@@ -509,6 +539,7 @@
 - GH-690: plan resume and approve must apply or reject scope changes ([pm-bxdlfa](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bxdlfa.toon))
 - GH-688: seeded Plan creation must be atomic across ownership boundaries ([pm-96tter](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-96tter.toon))
 - GH-679: linked-test output capture must not abort verbose child tools with EAGAIN ([pm-j36ypd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-j36ypd.toon))
+- Author-resolution bypass class: create/copy and the context, next, and usage-feedback paths re-implement author precedence without harness detection, stamping author 'unknown' on new items ([pm-42p9nk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-42p9nk.toon))
 - GH-706: accept bare conventional forms for create/update boolean metadata flags ([pm-ulb3rc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ulb3rc.toon))
 - GH-700/GH-701/GH-702: nightly Node 22 and cross-platform regression bundle ([pm-3x8w4m](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-3x8w4m.toon))
 - GH-704: make extension activation failures actionable at command and lifecycle boundaries ([pm-3ljt19](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-3ljt19.toon))
@@ -688,7 +719,6 @@
 
 ### Added
 
-- Merge-driver fence completeness: relationships/\*.jsonl event stores uncovered and schema-added custom type folders silently drop driver coverage ([pm-i4fx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-i4fx.toon))
 - Tracker merge semantics: field-aware merge guidance, history-chain-safe JSONL merging, and post-merge reconciliation for multi-branch agent workflows ([pm-g5sx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-g5sx.toon))
 - GH-613: public SDK bulk item-mutation helper on commitWorkspaceTransaction — atomic create/update/close batches without hand-rolled step+compensation wiring ([pm-y9hq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-y9hq.toon))
 - GH-612: additive --add-ac/--remove-ac forms for acceptance criteria — replace-only --ac clobbers concurrent branch edits ([pm-xh82](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-xh82.toon))
@@ -696,6 +726,7 @@
 
 ### Fixed
 
+- Merge-driver fence completeness: relationships/\*.jsonl event stores uncovered and schema-added custom type folders silently drop driver coverage ([pm-i4fx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-i4fx.toon))
 - MERGE_SAFETY.md documented an invalid config invocation: 'pm config set project ids.token_length 6' exits 2 (scope must precede the verb) ([pm-46octv](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-46octv.toon))
 - GH-601: SDK mutation option bags and projected list items are Record<string,unknown\> — typos and wrong types compile clean under strict ([pm-x29o](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-x29o.toon))
 - GH-600: item id generation not collision-safe across branches/concurrent agents (4 base36 chars, local-disk-only uniqueness) ([pm-pibw](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-pibw.toon))
@@ -813,7 +844,6 @@
 
 - Promote history-stream maintenance primitives to the public SDK: history-redact, history-repair, history-compact (audited rewrite, re-anchor, checkpoint/prune) ([pm-4a7m](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-4a7m.toon))
 - Context usage feedback signal: served-then-acted-on outcomes strengthen relevance scoring (retrieval-practice effect) ([pm-uwfs](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-uwfs.toon))
-- GH-544: linked-file path anchoring — files/docs add/glob/discover/validate-paths resolve at process.cwd() while validate --check-files anchors at the workspace root ([pm-chyh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-chyh.toon))
 
 ### Changed
 
@@ -834,6 +864,7 @@
 - GH-534: no-op update reports phantom changed_fields in --json while TOON reports empty, and changed_field_count is always null in JSON ([pm-45mb](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-45mb.toon))
 - GH-526: aggregate --sum/--avg accept unknown field names and silently report 0 ([pm-96vo](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-96vo.toon))
 - GH-530: list --status <invalid\> silently returns count 0 — validate against the status domain like --type and search status: ([pm-kj4k](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-kj4k.toon))
+- GH-544: linked-file path anchoring — files/docs add/glob/discover/validate-paths resolve at process.cwd() while validate --check-files anchors at the workspace root ([pm-chyh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-chyh.toon))
 - Separate active dangling dependency warnings from terminal historical reference diagnostics ([pm-2ler](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2ler.toon))
 
 ### Other
@@ -1412,7 +1443,6 @@
 
 ### Added
 
-- Sentry PM-CLI-1R: 'cannot add command init as already have command init' — top-level init double-registration throws raw Commander error ([pm-zyez](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-zyez.toon))
 - GH-216: default lifecycle transition suggestions ([pm-y1z0](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-y1z0.toon))
 - pm schema list-fields / show-field / add-field / remove-field: CLI management of schema/fields.json ([pm-vhbf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-vhbf.toon))
 - GH-245: schema add-type --infer from title prefixes ([pm-tb42](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-tb42.toon))
@@ -1422,6 +1452,10 @@
 - GH-217: scheduling type creation shortcuts ([pm-76r5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-76r5.toon))
 - GH-258: strict unknown-key rejection across all structured CSV/markdown link & metadata parsers (validation parity with test --add) ([pm-0v9k](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-0v9k.toon))
 
+### Fixed
+
+- Sentry PM-CLI-1R: 'cannot add command init as already have command init' — top-level init double-registration throws raw Commander error ([pm-zyez](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-zyez.toon))
+
 ### Other
 
 - Document schema/fields.json runtime custom field authoring in CONFIGURATION.md ([pm-izx5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-izx5.toon))
@@ -1636,7 +1670,6 @@
 ### Added
 
 - MCP pm_health defaults to the compact summary projection for token-efficient agent health checks ([pm-yjub](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-yjub.toon))
-- pm-changelog classifier mis-routes feature titles containing the word 'remove'/'delete' into the Removed section ([pm-ybiz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ybiz.toon))
 - list/search: trim default filters/projection/sorting/now trailer in compact/agent mode ([pm-vhx6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-vhx6.toon))
 - Add schema show-status status inspection ([pm-qpus](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-qpus.toon))
 
@@ -1646,6 +1679,7 @@
 
 ### Fixed
 
+- pm-changelog classifier mis-routes feature titles containing the word 'remove'/'delete' into the Removed section ([pm-ybiz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ybiz.toon))
 - Fix inaccurate PR CI matrix description in CONTRIBUTING.md ([pm-t73k](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-t73k.toon))
 - Fix: --path/PM_PATH did not discover .agents/pm under a project root (never-block dead-end) ([pm-ryik](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ryik.toon))
 - MCP ping method not handled — returns 'Unsupported MCP method' instead of empty response ([pm-lold](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-lold.toon))
@@ -1721,7 +1755,6 @@
 - Add pm stats --storage: aggregate history-stream metrics ([pm-mnee](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-mnee.toon))
 - Add MCP protocol handshake tests (initialize + tools/list + unknown-tool error) ([pm-kl11](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-kl11.toon))
 - Add narrow MCP tools pm_notes, pm_learnings, pm_deps (agent self-documentation + deps) ([pm-hywv](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-hywv.toon))
-- Add pm gc --scope locks: sweep expired lock debris from crashed processes ([pm-d70h](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-d70h.toon))
 - pm telemetry local-analytics subcommand (status/flush/stats/clear) ([pm-6xdl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-6xdl.toon))
 - Add AGENTS.md/README workflow-update checkbox to the PR template ([pm-0sqs](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-0sqs.toon))
 
@@ -1734,6 +1767,7 @@
 
 - MCP TOOL_SCHEMA_BASE additionalProperties:true silently swallows typo'd top-level args ([pm-qxwu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qxwu.toon))
 - File-backed schema sections (types/statuses/fields/type_workflows) leak into settings.json on writeSettings ([pm-haak](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-haak.toon))
+- Add pm gc --scope locks: sweep expired lock debris from crashed processes ([pm-d70h](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-d70h.toon))
 - PRD/contract drift: reminders_weight and events_weight missing from search.tuning docs ([pm-75du](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-75du.toon))
 - MCP stdio server processes JSON-RPC lines concurrently → pipelined mutations on the same item lock-conflict ([pm-3puw](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-3puw.toon))
 
@@ -1906,13 +1940,13 @@
 
 ### Added
 
-- Semantic index not auto-refreshed on mutation: create then pm search --semantic misses the new item (stale index) ([pm-bpaj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bpaj.toon))
 - Reduce ESM module-resolution startup overhead (~85ms) via core bundling ([pm-ss1d](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-ss1d.toon))
 
 ### Fixed
 
 - Calendar positional-date and impossible-deadline UX: pm calendar 2026-06-15 hard-errors; --deadline 2026-02-30 silently rolls to Mar 2 ([pm-wr74](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wr74.toon))
 - Split metadata cache into light + collections tiers to cut list hot-path JSON parse ([pm-jd3v](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-jd3v.toon))
+- Semantic index not auto-refreshed on mutation: create then pm search --semantic misses the new item (stale index) ([pm-bpaj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bpaj.toon))
 - create's schedule-less calendar hint suggests rejected --event pipe form (accepts CSV) — blocks agents ([pm-8c2s](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-8c2s.toon))
 - Suggestion-only command aliases (show/comment/note/view) still hard-fail as nonexistent_command instead of executing ([pm-7by2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7by2.toon))
 - create rejects common type synonyms (Bug/bug, Change/change) instead of mapping to Issue/Chore ([pm-4d1b](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-4d1b.toon))
@@ -2062,11 +2096,6 @@
 
 ## 2026.5.23 - 2026-05-23
 
-### Added
-
-- pm health output stays large even with --brief/--skip flags; add a true one-line summary mode ([pm-nbht](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-nbht.toon))
-- Reduce default verbosity of pm activity/history CLI output and add a compact mode to pm history ([pm-3pbs](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-3pbs.toon))
-
 ### Changed
 
 - Remove dead code: command-aware.ts module, 5 orphaned exported functions, unused undici dependency ([pm-b7do](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-b7do.toon))
@@ -2075,6 +2104,7 @@
 
 - MCP pm_search defaults to full item bodies, blowing past agent token limits ([pm-qrxs](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qrxs.toon))
 - pm create --blocked-by stores free-text metadata, not a dependency edge or blocked status (agent-confusing) ([pm-orrl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-orrl.toon))
+- pm health output stays large even with --brief/--skip flags; add a true one-line summary mode ([pm-nbht](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-nbht.toon))
 - Calendar: pm cal <view\> --date crashes (positional view + any flag) ([pm-l292](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-l292.toon))
 - Agent UX: pm update --status closed, explicit semantic/hybrid search, and pm create <type\> <title\> must never block agents ([pm-j1v7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-j1v7.toon))
 - Sentry PM-CLI-R/PM-CLI-S: undefined-status .trim and undefined-tags .join crashes (fixed in HEAD, mark resolvedInNextRelease) ([pm-d7us](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-d7us.toon))
@@ -2083,6 +2113,7 @@
 - Audited history-repair (re-anchor) command + clear legacy history drift so pm health is ok ([pm-85hm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-85hm.toon))
 - MCP pm_comments returns full comment history (no default limit) — token bloat on long-lived items ([pm-6vfg](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-6vfg.toon))
 - pm plan: materialize creates dependency cycle; decision/discovery/validation flag mismatch; --steps all unsupported ([pm-6blp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-6blp.toon))
+- Reduce default verbosity of pm activity/history CLI output and add a compact mode to pm history ([pm-3pbs](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-3pbs.toon))
 
 ### Security
 
@@ -2381,14 +2412,10 @@
 
 ### Added
 
-- 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))
 - Harden entry and add input resilience ([pm-nhgt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-nhgt.toon))
 - Governance sweep 2026-04-03 net-new remediation ([pm-r7t2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-r7t2.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))
 - List command large-output ergonomics ([pm-a4z3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-a4z3.toon))
 - Activate semantic defaults via local Ollama runtime detection ([pm-zvn2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-zvn2.toon))
-- Add dependency mutation command for existing items ([pm-zdec](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-zdec.toon))
 - Full registration runtime wiring ([pm-zd6y](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-zd6y.toon))
 - Add test-result tracking settings and config policy ([pm-z9k7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-z9k7.toon))
 - Automatic migration and legacy format gate ([pm-z8bl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-z8bl.toon))
@@ -2399,7 +2426,6 @@
 - Add dependency visualization command (pm deps) ([pm-x85o](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-x85o.toon))
 - Configurable item type registry (settings + extensions) ([pm-x2k0](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-x2k0.toon))
 - Strict skipped-test policy and linked-test assertion semantics ([pm-wtq6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-wtq6.toon))
-- Add extension project scaffold command or template ([pm-wsui](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wsui.toon))
 - Feature: claim takeover on non-terminal items ([pm-w9w4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-w9w4.toon))
 - Add governance normalize command with dry-run and apply modes ([pm-vi2v](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-vi2v.toon))
 - List parent filtering and get recovery guidance ([pm-v7o7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-v7o7.toon))
@@ -2416,7 +2442,6 @@
 - Stdin and PTY fail-safe behavior ([pm-olxl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-olxl.toon))
 - SDK publishing and stability contract ([pm-oga6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-oga6.toon))
 - Add AGENTS rule to check existing pm items before creating new ones ([pm-o5uw](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-o5uw.toon))
-- Add compact/full/fields search output controls with compact default ([pm-nrxm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-nrxm.toon))
 - Add files discovery subcommand for referenced paths ([pm-n2ts](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-n2ts.toon))
 - Feature: update close_reason lifecycle integrity ([pm-m4vu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-m4vu.toon))
 - Implement deterministic guard for ambiguous create log seeds ([pm-m3mf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-m3mf.toon))
@@ -2452,7 +2477,6 @@
 - Analyze persisted telemetry and add remote analysis skill ([pm-cakn](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-cakn.toon))
 - Persistent reminder item fields and CLI mutation support ([pm-c877](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-c877.toon))
 - Linked-test sandbox project/global extension parity ([pm-bkvx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-bkvx.toon))
-- Add deterministic linked-test replacement mode for update test mutations ([pm-bjpo](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-bjpo.toon))
 - Background linked-test orchestration and run management ([pm-bi0z](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-bi0z.toon))
 - Expand aggregate group-by to support priority, status, assignee, tags ([pm-bhhe](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-bhhe.toon))
 - Issue3 Feature: Extract PM-id references from linked commands ([pm-bf54](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-bf54.toon))
@@ -2491,7 +2515,6 @@
 - 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 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))
 - Extended schema fields v1.1 - parent, reviewer, risk, sprint, release ([pm-2p6q](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-2p6q.toon))
 - Health optional directory strictness and compatibility ([pm-2i0i](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-2i0i.toon))
@@ -2503,11 +2526,11 @@
 - Phase 2 SDK v2 contracts with backward-compat adapters ([pm-0u1y](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-0u1y.toon))
 - Add activity filtering and stream mode for large program automation ([pm-0g7a](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-0g7a.toon))
 - Event and recurrence schema with mutation contracts ([pm-0ab3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-0ab3.toon))
-- Add --parent filter support for list and list-\* commands ([pm-08zg](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-08zg.toon))
 - Calendar parity integrations and release hardening ([pm-02gd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-02gd.toon))
 
 ### Changed
 
+- 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))
 - Update-many: improve error message when no mutation flags provided ([pm-twtu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-twtu.toon))
 - Update body backfill normalization parity ([pm-ihfm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/epics/pm-ihfm.toon))
 - Parser update: support +m and flexible date strings ([pm-y8a8](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-y8a8.toon))
@@ -2528,6 +2551,7 @@
 - Enforce option policies in create/update and help errors ([pm-co62](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-co62.toon))
 - Improve required option error/help guidance with examples ([pm-bzyr](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-bzyr.toon))
 - C3: Update docs and release notes for comments UX ([pm-bx5r](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-bx5r.toon))
+- Add deterministic linked-test replacement mode for update test mutations ([pm-bjpo](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-bjpo.toon))
 - Update docs and changelog for six audit findings ([pm-9eaz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-9eaz.toon))
 - Update completion and Pi wrapper for event recurrence flags ([pm-5hbj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-5hbj.toon))
 - Phase 2: update extension architecture and migration docs ([pm-4epk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-4epk.toon))
@@ -2538,12 +2562,16 @@
 
 ### Fixed
 
+- 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))
 - 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))
 - 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))
+- 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 dependency mutation command for existing items ([pm-zdec](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-zdec.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))
+- Add extension project scaffold command or template ([pm-wsui](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wsui.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))
@@ -2553,6 +2581,7 @@
 - Regression and release hardening ([pm-qwp7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-qwp7.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))
+- Add compact/full/fields search output controls with compact default ([pm-nrxm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-nrxm.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))
 - SDK starter example leaves extension health warning ([pm-mwiz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mwiz.toon))
 - Align default item types with Decision tracking guidance ([pm-mpmv](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mpmv.toon))
@@ -2577,9 +2606,11 @@
 - Phase 2: parser override regression and docs coverage ([pm-6024](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-6024.toon))
 - Expand recurrence regression and runtime contract tests ([pm-5xih](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-5xih.toon))
 - E1: Expand override and no-extension regression matrix ([pm-5chf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-5chf.toon))
+- Add telemetry runtime diagnostics to pm health ([pm-300m](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-300m.toon))
 - Clarify or harden SDK import resolution for local extension installs ([pm-1etl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-1etl.toon))
 - Context blocked-fallback test uses date-sensitive default deadline ([pm-0xhj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-0xhj.toon))
 - Add status alias regression tests ([pm-0kga](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-0kga.toon))
+- Add --parent filter support for list and list-\* commands ([pm-08zg](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-08zg.toon))
 
 ### Removed
 

package/dist/cli/commander-usage.js

@@ -1,6 +1,6 @@
 
-!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]="78ae2dad-a000-57be-9492-caea26a412ef")}catch(e){}}();
-import { pathExists, resolveItemTypeRegistry, EXIT_CODE, getSettingsPath, resolvePmRoot, readSettings, getActiveExtensionRegistrations, runActiveServiceOverride, levenshteinDistanceWithinLimit, } 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]="05cf369c-7529-57ab-984a-f5505cc9c0c9")}catch(e){}}();
+import { pathExists, resolveItemTypeRegistry, EXIT_CODE, getSettingsPath, resolvePmRoot, readSettings, getActiveExtensionRegistrations, locateItem, runActiveServiceOverride, levenshteinDistanceWithinLimit, } from "../sdk/runtime-primitives.js";
 import { BUILTIN_ITEM_TYPE_VALUES } from "../types/index.js";
 import { PM_CORE_COMMAND_NAMES, resolveSubcommandFlagContractsForCommand, } from "../sdk/cli-contracts.js";
 import { formatCommanderErrorForDisplay, formatCommanderErrorForJson, projectLeanErrorEnvelope, } from "./error-guidance.js";
@@ -536,24 +536,46 @@ export function isKnownHelpCommandPath(root, commandPathTokens) {
     }
     return matchedAny;
 }
-async function resolveAllowedTypesForUsage(bootstrapGlobal) {
+async function resolveWorkspaceUsageContext(bootstrapGlobal, message, invocationArgv, commandName) {
     try {
         const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobal.path);
         if (!(await pathExists(getSettingsPath(pmRoot)))) {
-            return BUILTIN_TYPE_HELP_VALUES;
+            return { allowedTypes: BUILTIN_TYPE_HELP_VALUES };
         }
         const settings = await readSettings(pmRoot);
         const extensionRegistrations = bootstrapGlobal.noExtensions
             ? undefined
             : getActiveExtensionRegistrations();
         const typeRegistry = resolveItemTypeRegistry(settings, extensionRegistrations);
-        return typeRegistry.types.length > 0
-            ? typeRegistry.types.join("|")
-            : BUILTIN_TYPE_HELP_VALUES;
+        let verifiedCollectionItemId;
+        if (/too many arguments/i.test(message) &&
+            ["comments", "docs", "files", "learnings", "notes", "test"].includes(commandName ?? "")) {
+            const commandIndex = invocationArgv.findIndex((token) => token === commandName);
+            const candidate = invocationArgv[commandIndex + 2];
+            if (invocationArgv[commandIndex + 1]?.toLowerCase() === "add" &&
+                candidate !== undefined &&
+                !candidate.startsWith("-")) {
+                try {
+                    verifiedCollectionItemId = (await locateItem(pmRoot, candidate, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder))?.id;
+                }
+                catch {
+                    // Usage rendering remains available when tracker storage is unreadable.
+                }
+            }
+        }
+        return {
+            allowedTypes: typeRegistry.types.length > 0
+                ? typeRegistry.types.join("|")
+                : BUILTIN_TYPE_HELP_VALUES,
+            pmRoot,
+            settings,
+            typeToFolder: typeRegistry.type_to_folder,
+            verifiedCollectionItemId,
+        };
     }
     catch {
         /* v8 ignore start -- defensive fallback for corrupted settings during usage-error rendering; command behavior is covered through normal settings paths */
-        return BUILTIN_TYPE_HELP_VALUES;
+        return { allowedTypes: BUILTIN_TYPE_HELP_VALUES };
         /* v8 ignore stop */
     }
 }
@@ -636,7 +658,8 @@ export async function resolveCommanderUsageContext(error, rootProgram, extension
     const commandName = parseBootstrapCommandName(invocationArgv);
     const attemptedCommand = renderAttemptedCommand(invocationArgv);
     const providedOptionFlags = extractProvidedOptionFlags(invocationArgv);
-    const allowedTypes = await resolveAllowedTypesForUsage(bootstrapGlobal);
+    const workspaceUsage = await resolveWorkspaceUsageContext(bootstrapGlobal, message, invocationArgv, commandName);
+    const allowedTypes = workspaceUsage.allowedTypes;
     const unknownCommandGuidance = buildUnknownCommandGuidanceFromRuntime(message, rootProgram, extensionDescriptors);
     const unknownOption = resolveUnknownOptionSuggestions(message, commandName);
     const splitSchemaSubcommand = resolveSplitSchemaSubcommand(message, invocationArgv);
@@ -659,6 +682,7 @@ export async function resolveCommanderUsageContext(error, rootProgram, extension
             : undefined,
         unknownOptionOtherCommandsTruncated: unknownOption.otherCommands.length > 12 || undefined,
         suggestedRetryCommand,
+        verifiedCollectionItemId: workspaceUsage.verifiedCollectionItemId,
         ...splitSchemaSubcommand,
         ...unknownCommandGuidance,
         ...guidanceOverrides,
@@ -667,7 +691,7 @@ export async function resolveCommanderUsageContext(error, rootProgram, extension
 /** Implements format commander usage message for the public runtime surface of this module. */
 export async function formatCommanderUsageMessage(error, rootProgram, extensionDescriptors, guidanceOverrides = {}) {
     const usageContext = await resolveCommanderUsageContext(error, rootProgram, extensionDescriptors, guidanceOverrides);
-    const { message, commandName, allowedTypes, unknownCommandExamples, unknownCommandNextSteps, attemptedCommand, normalizedInvocationArgs, providedOptionFlags, unknownOptionSuggestions, unknownOptionOtherCommands, unknownOptionOtherCommandsTotal, unknownOptionOtherCommandsTruncated, unknownSubcommandPath, unknownSubcommandToken, unknownSubcommandAllowedValues, suggestedRetryCommand, failedExtensions, } = usageContext;
+    const { message, commandName, allowedTypes, unknownCommandExamples, unknownCommandNextSteps, attemptedCommand, normalizedInvocationArgs, providedOptionFlags, unknownOptionSuggestions, unknownOptionOtherCommands, unknownOptionOtherCommandsTotal, unknownOptionOtherCommandsTruncated, unknownSubcommandPath, unknownSubcommandToken, unknownSubcommandAllowedValues, suggestedRetryCommand, verifiedCollectionItemId, failedExtensions, } = usageContext;
     const formatted = formatCommanderErrorForDisplay(message, commandName, allowedTypes, {
         unknownCommandExamples,
         unknownCommandNextSteps,
@@ -682,6 +706,7 @@ export async function formatCommanderUsageMessage(error, rootProgram, extensionD
         unknownSubcommandToken,
         unknownSubcommandAllowedValues,
         suggestedRetryCommand,
+        verifiedCollectionItemId,
         failedExtensions,
     });
     const serviceOverride = await runActiveServiceOverride("help_format", {
@@ -711,6 +736,7 @@ export async function formatCommanderUsageJson(error, rootProgram, extensionDesc
         unknownSubcommandToken: usageContext.unknownSubcommandToken,
         unknownSubcommandAllowedValues: usageContext.unknownSubcommandAllowedValues,
         suggestedRetryCommand: usageContext.suggestedRetryCommand,
+        verifiedCollectionItemId: usageContext.verifiedCollectionItemId,
         failedExtensions: usageContext.failedExtensions,
     });
     return JSON.stringify(lean ? projectLeanErrorEnvelope(envelope) : envelope, null, 2);
@@ -724,4 +750,4 @@ export const _testOnly = {
     suggestNearestLongFlags,
 };
 //# sourceMappingURL=commander-usage.js.map
-//# debugId=78ae2dad-a000-57be-9492-caea26a412ef
+//# debugId=05cf369c-7529-57ab-984a-f5505cc9c0c9

package/dist/cli/error-guidance.d.ts

@@ -89,6 +89,8 @@ export interface CommanderGuidanceContext {
     unknownSubcommandAllowedValues?: string[];
     /** Value that configures or reports suggested retry command for this contract. */
     suggestedRetryCommand?: string;
+    /** Existing item id verified against the selected tracker for collection recovery. */
+    verifiedCollectionItemId?: string;
     /** Installed extensions whose activation failed for this invocation. */
     failedExtensions?: Array<{
         name: string;

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]="4d6caae5-76d6-5563-acb9-b435f8cdfe9c")}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]="0203943b-16ea-5c3a-a2d3-56a0c4d2848f")}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. */
@@ -125,7 +125,21 @@ function assignRecoveryString(normalized, key, value) {
         normalized[key] = value.trim();
     }
 }
-function assignRecoveryStringArray(normalized, key, value) {
+function assignRecoveryCollection(normalized, key, value) {
+    if (key === "parsed_positionals") {
+        if (!Array.isArray(value))
+            return;
+        const parsedPositionals = value
+            .map((entry) => ({
+            role: typeof entry?.role === "string" ? entry.role.trim() : "",
+            value: typeof entry?.value === "string" ? entry.value.trim() : "",
+        }))
+            .filter((entry) => entry.role.length > 0 && entry.value.length > 0);
+        if (parsedPositionals.length > 0) {
+            normalized.parsed_positionals = parsedPositionals;
+        }
+        return;
+    }
     const values = normalizeStringArray(value);
     if (values) {
         normalized[key] = values;
@@ -140,13 +154,14 @@ function normalizeRecoveryPayload(payload) {
         normalized.recovery_mode = "compact";
     }
     assignRecoveryString(normalized, "attempted_command", payload.attempted_command);
-    assignRecoveryStringArray(normalized, "normalized_args", payload.normalized_args);
-    assignRecoveryStringArray(normalized, "provided_fields", payload.provided_fields);
-    assignRecoveryStringArray(normalized, "missing", payload.missing);
-    assignRecoveryStringArray(normalized, "missing_required_fields", payload.missing_required_fields);
-    assignRecoveryStringArray(normalized, "suggested_flags", payload.suggested_flags);
-    assignRecoveryStringArray(normalized, "allowed_values", payload.allowed_values);
-    assignRecoveryStringArray(normalized, "candidate_commands", payload.candidate_commands);
+    assignRecoveryCollection(normalized, "normalized_args", payload.normalized_args);
+    assignRecoveryCollection(normalized, "parsed_positionals", payload.parsed_positionals);
+    assignRecoveryCollection(normalized, "provided_fields", payload.provided_fields);
+    assignRecoveryCollection(normalized, "missing", payload.missing);
+    assignRecoveryCollection(normalized, "missing_required_fields", payload.missing_required_fields);
+    assignRecoveryCollection(normalized, "suggested_flags", payload.suggested_flags);
+    assignRecoveryCollection(normalized, "allowed_values", payload.allowed_values);
+    assignRecoveryCollection(normalized, "candidate_commands", payload.candidate_commands);
     if (typeof payload.candidate_commands_total === "number" &&
         Number.isSafeInteger(payload.candidate_commands_total) &&
         payload.candidate_commands_total >= 0) {
@@ -186,6 +201,13 @@ function renderRecoveryBundle(recovery) {
     const lines = ["Recovery bundle:"];
     appendRecoveryTextLine(lines, "attempted_command", normalized.attempted_command);
     appendRecoveryListLine(lines, "normalized_args", normalized.normalized_args, " ");
+    if (normalized.parsed_positionals &&
+        normalized.parsed_positionals.length > 0) {
+        lines.push("  parsed_positionals:");
+        for (const positional of normalized.parsed_positionals) {
+            lines.push(`    - ${positional.role}: ${positional.value}`);
+        }
+    }
     appendRecoveryListLine(lines, "provided_fields", normalized.provided_fields, ", ");
     appendRecoveryListLine(lines, "missing", normalized.missing, ", ");
     appendRecoveryListLine(lines, "missing_required_fields", normalized.missing_required_fields, ", ");
@@ -822,8 +844,7 @@ function buildUnknownOptionGuidance(message, commandName, context) {
         return buildUnsupportedUpdateOptionGuidance(optionName, context, suggestions);
     }
     const otherCommands = normalizeContextList(guidanceContext.unknownOptionOtherCommands) ?? [];
-    const candidateTotal = guidanceContext.unknownOptionOtherCommandsTotal ??
-        otherCommands.length;
+    const candidateTotal = guidanceContext.unknownOptionOtherCommandsTotal ?? otherCommands.length;
     const proseCommands = otherCommands.slice(0, 3);
     const proseRemainder = candidateTotal - proseCommands.length;
     let proseRemainderText = "";
@@ -842,7 +863,10 @@ function buildUnknownOptionGuidance(message, commandName, context) {
             ? `Replay with suggested correction: ${retryCommand}`
             : undefined,
     ].filter((entry) => typeof entry === "string");
-    const examples = [retryCommand, `pm ${commandName ?? "<command>"} --help`].filter((entry) => typeof entry === "string");
+    const examples = [
+        retryCommand,
+        `pm ${commandName ?? "<command>"} --help`,
+    ].filter((entry) => typeof entry === "string");
     return makeGuidanceMessage({
         code: "unknown_option",
         title: `Unknown option ${optionName}`,
@@ -966,6 +990,48 @@ function buildLinkedTestValueNotQuotedGuidance(message, commandName, context) {
         recovery: buildCommanderRecoveryPayload(context, retryCommand ? { suggested_retry: retryCommand } : {}),
     });
 }
+const TRANSPOSED_COLLECTION_COMMANDS = new Set([
+    "comments",
+    "docs",
+    "files",
+    "learnings",
+    "notes",
+    "test",
+]);
+function buildTransposedCollectionActionGuidance(message, commandName, context) {
+    if (!/too many arguments/i.test(message) ||
+        !TRANSPOSED_COLLECTION_COMMANDS.has(commandName ?? "")) {
+        return null;
+    }
+    const argv = context?.normalizedInvocationArgs ?? [];
+    const commandIndex = argv.findIndex((token) => token === commandName);
+    const action = argv[commandIndex + 1];
+    const parsedItemId = argv[commandIndex + 2];
+    const itemId = context?.verifiedCollectionItemId?.trim();
+    if (action?.toLowerCase() !== "add" ||
+        !parsedItemId ||
+        parsedItemId.startsWith("-") ||
+        !itemId ||
+        itemId.toLowerCase() !== parsedItemId.toLowerCase()) {
+        return null;
+    }
+    const suggestedRetry = `pm ${commandName} ${itemId} --add <value>`;
+    return makeGuidanceMessage({
+        code: "collection_transposed_subcommand",
+        title: `Transposed ${commandName} add syntax`,
+        happened: `The positional token "add" occupied the item-id role and "${itemId}" occupied the next positional role. pm ${commandName} does not use an add subcommand.`,
+        required: `Place the item id immediately after ${commandName}, then use --add for the value.`,
+        why: "Collection mutations use object-first grammar: pm <collection> <item-id> --add <value>.",
+        examples: [suggestedRetry, `pm ${commandName} --help`],
+        recovery: buildCommanderRecoveryPayload(context, {
+            parsed_positionals: [
+                { role: "transposed_subcommand", value: action },
+                { role: "item_id", value: itemId },
+            ],
+            suggested_retry: suggestedRetry,
+        }),
+    });
+}
 const CONTEXT_GUIDANCE_VALUE_FLAGS = new Set([
     "--activity-limit",
     "--assignee",
@@ -1041,6 +1107,7 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
         buildUnknownOptionGuidance(message, commandName, context) ??
         buildUnknownCommandGuidance(message, context) ??
         buildUnknownSubcommandGuidance(context) ??
+        buildTransposedCollectionActionGuidance(message, commandName, context) ??
         buildLinkedTestValueNotQuotedGuidance(message, commandName, context) ??
         buildContextItemArgumentGuidance(message, commandName, context);
     if (guidance) {
@@ -1134,4 +1201,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=4d6caae5-76d6-5563-acb9-b435f8cdfe9c
+//# debugId=0203943b-16ea-5c3a-a2d3-56a0c4d2848f